Warning:
Fauna is decommissioning FQL v4 on June 30, 2025.

This driver is not compatible with FQL v10, the latest version. Fauna accounts created after August 21, 2024 must use FQL v10.
Ensure you migrate existing projects to the official v10 driver by the v4 EOL date: https://github.com/fauna/fauna-python.

For more information, see the v4 end of life (EOL) announcement and related FAQ.

Module faunadb.objects

Types used in queries and responses. See the docs <https://app.fauna.com/documentation/reference/queryapi#simple-type>__.

Expand source code 
"""
Types used in queries and responses.
See the `docs <https://app.fauna.com/documentation/reference/queryapi#simple-type>`__.
"""
from datetime import datetime
# pylint: disable=redefined-builtin
from iso8601 import parse_date
from faunadb.deprecated import deprecated
from faunadb.query import _Expr

class Ref(_Expr):
  """
  FaunaDB ref. See the `docs <https://app.fauna.com/documentation/reference/queryapi#special-type>`__.

  A simple wrapper around a string which can be extracted using ``ref.value``.
  Queries that require a Ref will not work if you just pass in a string.
  """

  def __init__(self, id, cls=None, db=None):
    if id is None:
      raise ValueError("The Ref must have an id.")

    value = {"id": id}

    if cls != None:
      value["collection"] = cls

    if db != None:
      value["database"] = db

    super(Ref, self).__init__(value)

  def collection(self):
    """
    Gets the collection part out of the Ref.
    """
    return self.value.get("collection")

  @deprecated("use collection instead")
  def class_(self):
    """
    Gets the class part out of the Ref.
    """
    return self.value.get("collection")

  def database(self):
    """
    Gets the database part out of the Ref.
    """
    return self.value.get("database")

  def id(self):
    """
    Gets the id part out of the Ref.
    """
    return self.value["id"]

  def to_fauna_json(self):
    return {"@ref": self.value}

  def __str__(self):
    col = ", collection=%s" % self.value["collection"] if "collection" in self.value else ""
    db = ", database=%s" % self.value["database"] if "database" in self.value else ""
    return "Ref(id=%s%s%s)" % (self.value["id"], col, db)

  def __repr__(self):
    col = ", collection=%s" % self.value["collection"] if "collection" in self.value else ""
    db = ", database=%r" % self.value["database"] if "database" in self.value else ""
    return "Ref(id=%s%s%s)" % (self.value["id"], col, db)

  def __eq__(self, other):
    return isinstance(other, Ref) and self.value == other.value

  def __ne__(self, other):
    # pylint: disable=unneeded-not
    return not self == other

class Native(object):
  COLLECTIONS = Ref('collections')
  INDEXES = Ref('indexes')
  DATABASES = Ref('databases')
  FUNCTIONS = Ref('functions')
  KEYS = Ref('keys')
  TOKENS = Ref('tokens')
  CREDENTIALS = Ref('credentials')
  ROLES = Ref('roles')
  ACCESS_PROVIDERS = Ref('access_providers')

  def __init__(self):
    raise TypeError

  @classmethod
  def from_name(cls, name):
    return getattr(cls, name.upper(), Ref(name))

class SetRef(_Expr):
  """
  FaunaDB Set.
  This represents a set returned as part of a response.
  For query sets see :doc:`query`.
  """

  def __init__(self, set_ref):
    if isinstance(set_ref, _Expr):
      value = set_ref.value
    else:
      value = set_ref

    super(SetRef, self).__init__(value)

  def to_fauna_json(self):
    return {"@set": self.value}

  def __repr__(self):
    return "SetRef(%s)" % repr(self.value)

  def __eq__(self, other):
    return isinstance(other, SetRef) and self.value == other.value

  def __ne__(self, other):
    # pylint: disable=unneeded-not
    return not self == other


class FaunaTime(_Expr):
  """
  FaunaDB time. See the `docs <https://app.fauna.com/documentation/reference/queryapi#special-type>`__.

  For dates, regular :class:`datetime.date` objects are used.
  """

  def __init__(self, value):
    """
    :param value:
      If a :class:`datetime.datetime` is passed, it is converted to a string.
      Must include an offset.
    """
    if isinstance(value, datetime):
      if value.utcoffset() is None:
        raise ValueError("FaunaTime requires offset-aware datetimes")
      value = value.isoformat()

    # Convert +00:00 offset to zulu for comparison equality
    # We don't check for +0000 or +00 as they are not valid in FaunaDB
    super(FaunaTime, self).__init__(value.replace("+00:00", "Z"))

  def to_datetime(self):
    """
    Convert to an offset-aware datetime object.
    This is lossy as datetimes have microsecond rather than nanosecond precision.
    """
    return parse_date(self.value)

  def to_fauna_json(self):
    return {"@ts": self.value}

  def __repr__(self):
    return "FaunaTime(%s)" % repr(self.value)

  def __eq__(self, other):
    return isinstance(other, FaunaTime) and self.value == other.value

  def __ne__(self, other):
    # pylint: disable=unneeded-not
    return not self == other


class Query(_Expr):
  """
  Represents a `@query` type in FaunaDB.
  See the `docs <https://app.fauna.com/documentation/reference/queryapi#special-type>`__.
  """

  def to_fauna_json(self):
    return {"@query": self.value}

  def __repr__(self):
    return "Query(%s)" % repr(self.value)

  def __eq__(self, other):
    return isinstance(other, Query) and self.value == other.value

  def __ne__(self, other):
    # pylint: disable=unneeded-not
    return not self == other

Classes

class FaunaTime (value)

FaunaDB time. See the docs <https://app.fauna.com/documentation/reference/queryapi#special-type>__.

For dates, regular :class:datetime.date objects are used.

:param value: If a :class:datetime.datetime is passed, it is converted to a string. Must include an offset.

Expand source code 
class FaunaTime(_Expr):
  """
  FaunaDB time. See the `docs <https://app.fauna.com/documentation/reference/queryapi#special-type>`__.

  For dates, regular :class:`datetime.date` objects are used.
  """

  def __init__(self, value):
    """
    :param value:
      If a :class:`datetime.datetime` is passed, it is converted to a string.
      Must include an offset.
    """
    if isinstance(value, datetime):
      if value.utcoffset() is None:
        raise ValueError("FaunaTime requires offset-aware datetimes")
      value = value.isoformat()

    # Convert +00:00 offset to zulu for comparison equality
    # We don't check for +0000 or +00 as they are not valid in FaunaDB
    super(FaunaTime, self).__init__(value.replace("+00:00", "Z"))

  def to_datetime(self):
    """
    Convert to an offset-aware datetime object.
    This is lossy as datetimes have microsecond rather than nanosecond precision.
    """
    return parse_date(self.value)

  def to_fauna_json(self):
    return {"@ts": self.value}

  def __repr__(self):
    return "FaunaTime(%s)" % repr(self.value)

  def __eq__(self, other):
    return isinstance(other, FaunaTime) and self.value == other.value

  def __ne__(self, other):
    # pylint: disable=unneeded-not
    return not self == other

Ancestors

  • faunadb.query._Expr

Methods

def to_datetime(self)

Convert to an offset-aware datetime object. This is lossy as datetimes have microsecond rather than nanosecond precision.

Expand source code 
def to_datetime(self):
  """
  Convert to an offset-aware datetime object.
  This is lossy as datetimes have microsecond rather than nanosecond precision.
  """
  return parse_date(self.value)
def to_fauna_json(self)
Expand source code 
def to_fauna_json(self):
  return {"@ts": self.value}
class Native
Expand source code 
class Native(object):
  COLLECTIONS = Ref('collections')
  INDEXES = Ref('indexes')
  DATABASES = Ref('databases')
  FUNCTIONS = Ref('functions')
  KEYS = Ref('keys')
  TOKENS = Ref('tokens')
  CREDENTIALS = Ref('credentials')
  ROLES = Ref('roles')
  ACCESS_PROVIDERS = Ref('access_providers')

  def __init__(self):
    raise TypeError

  @classmethod
  def from_name(cls, name):
    return getattr(cls, name.upper(), Ref(name))

Class variables

var ACCESS_PROVIDERS
var COLLECTIONS
var CREDENTIALS
var DATABASES
var FUNCTIONS
var INDEXES
var KEYS
var ROLES
var TOKENS

Static methods

def from_name(name)
Expand source code 
@classmethod
def from_name(cls, name):
  return getattr(cls, name.upper(), Ref(name))
class Query (value)

Represents a @query type in FaunaDB. See the docs <https://app.fauna.com/documentation/reference/queryapi#special-type>__.

Expand source code 
class Query(_Expr):
  """
  Represents a `@query` type in FaunaDB.
  See the `docs <https://app.fauna.com/documentation/reference/queryapi#special-type>`__.
  """

  def to_fauna_json(self):
    return {"@query": self.value}

  def __repr__(self):
    return "Query(%s)" % repr(self.value)

  def __eq__(self, other):
    return isinstance(other, Query) and self.value == other.value

  def __ne__(self, other):
    # pylint: disable=unneeded-not
    return not self == other

Ancestors

  • faunadb.query._Expr

Methods

def to_fauna_json(self)
Expand source code 
def to_fauna_json(self):
  return {"@query": self.value}
class Ref (id, cls=None, db=None)

FaunaDB ref. See the docs <https://app.fauna.com/documentation/reference/queryapi#special-type>__.

A simple wrapper around a string which can be extracted using ref.value. Queries that require a Ref will not work if you just pass in a string.

Expand source code 
class Ref(_Expr):
  """
  FaunaDB ref. See the `docs <https://app.fauna.com/documentation/reference/queryapi#special-type>`__.

  A simple wrapper around a string which can be extracted using ``ref.value``.
  Queries that require a Ref will not work if you just pass in a string.
  """

  def __init__(self, id, cls=None, db=None):
    if id is None:
      raise ValueError("The Ref must have an id.")

    value = {"id": id}

    if cls != None:
      value["collection"] = cls

    if db != None:
      value["database"] = db

    super(Ref, self).__init__(value)

  def collection(self):
    """
    Gets the collection part out of the Ref.
    """
    return self.value.get("collection")

  @deprecated("use collection instead")
  def class_(self):
    """
    Gets the class part out of the Ref.
    """
    return self.value.get("collection")

  def database(self):
    """
    Gets the database part out of the Ref.
    """
    return self.value.get("database")

  def id(self):
    """
    Gets the id part out of the Ref.
    """
    return self.value["id"]

  def to_fauna_json(self):
    return {"@ref": self.value}

  def __str__(self):
    col = ", collection=%s" % self.value["collection"] if "collection" in self.value else ""
    db = ", database=%s" % self.value["database"] if "database" in self.value else ""
    return "Ref(id=%s%s%s)" % (self.value["id"], col, db)

  def __repr__(self):
    col = ", collection=%s" % self.value["collection"] if "collection" in self.value else ""
    db = ", database=%r" % self.value["database"] if "database" in self.value else ""
    return "Ref(id=%s%s%s)" % (self.value["id"], col, db)

  def __eq__(self, other):
    return isinstance(other, Ref) and self.value == other.value

  def __ne__(self, other):
    # pylint: disable=unneeded-not
    return not self == other

Ancestors

  • faunadb.query._Expr

Methods

def class_(self)

Gets the class part out of the Ref.

Expand source code 
@deprecated("use collection instead")
def class_(self):
  """
  Gets the class part out of the Ref.
  """
  return self.value.get("collection")
def collection(self)

Gets the collection part out of the Ref.

Expand source code 
def collection(self):
  """
  Gets the collection part out of the Ref.
  """
  return self.value.get("collection")
def database(self)

Gets the database part out of the Ref.

Expand source code 
def database(self):
  """
  Gets the database part out of the Ref.
  """
  return self.value.get("database")
def id(self)

Gets the id part out of the Ref.

Expand source code 
def id(self):
  """
  Gets the id part out of the Ref.
  """
  return self.value["id"]
def to_fauna_json(self)
Expand source code 
def to_fauna_json(self):
  return {"@ref": self.value}
class SetRef (set_ref)

FaunaDB Set. This represents a set returned as part of a response. For query sets see :doc:query.

Expand source code 
class SetRef(_Expr):
  """
  FaunaDB Set.
  This represents a set returned as part of a response.
  For query sets see :doc:`query`.
  """

  def __init__(self, set_ref):
    if isinstance(set_ref, _Expr):
      value = set_ref.value
    else:
      value = set_ref

    super(SetRef, self).__init__(value)

  def to_fauna_json(self):
    return {"@set": self.value}

  def __repr__(self):
    return "SetRef(%s)" % repr(self.value)

  def __eq__(self, other):
    return isinstance(other, SetRef) and self.value == other.value

  def __ne__(self, other):
    # pylint: disable=unneeded-not
    return not self == other

Ancestors

  • faunadb.query._Expr

Methods

def to_fauna_json(self)
Expand source code 
def to_fauna_json(self):
  return {"@set": self.value}