Check out v4 of the Fauna CLI

v4 of the Fauna CLI is now in beta.

The new version introduces enhancements to the developer experience, including an improved authentication workflow. To get started, check out the CLI v4 quick start.

Collection

Learn: Collection schema

We recommend you use FSL to create and update user-defined collections. See FSL collection schema.

You add data to Fauna as JSON-like documents, stored in collections.

`Collection` collection

Fauna stores user-defined collections as documents in the Collection system collection. These documents have the CollectionDef type and are an FQL version of the FSL collection schema.

Collection documents have the following FQL structure:

{
  name: "Customer",
  coll: Collection,
  ts: Time("2099-10-03T20:45:53.780Z"),
  history_days: 0,
  fields: {
    name: {
      signature: "String"
    },
    email: {
      signature: "String"
    },
    address: {
      signature: "{ street: String, city: String, state: String, postalCode: String, country: String }"
    }
  },
  wildcard: "Any",
  computed_fields: {
    cart: {
      body: "(customer) => Order.byCustomerAndStatus(customer, \"cart\").first()",
      signature: "Order?"
    },
    orders: {
      body: "(customer) => Order.byCustomer(customer)",
      signature: "Set<Order>"
    }
  },
  indexes: {
    byEmail: {
      terms: [
        {
          field: ".email",
          mva: false
        }
      ],
      values: [
        {
          field: ".email",
          order: "desc",
          mva: false
        },
        {
          field: ".name",
          order: "asc",
          mva: false
        }
      ],
      queryable: true,
      status: "complete"
    },
  },
  ttl_days: 10,
  constraints: [
    {
      unique: [
        {
          field: ".email",
          mva: false
        }
      ],
      status: "active"
    }
  ],
  document_ttls: true,
  migrations: [
    {
      add_wildcard: {}
    }
  ]
}

Field Type Read-only Required Description

Field	Type	Read-only	Required	Description
`name`	String		true	Name of the collection.
`coll`	String	true		The `Collection` collection name.
`ts`	Time	true		Timestamp of the most recent document write.
`computed_fields`	Object			FQL version of the collection schema’s computed fields. See FSL collection schema: Computed field definitions
`constraints`	Object			FQL version of the collection schema’s check and unique constraints. See FSL collection schema: Check constraint definitions and FSL collection schema: Unique constraint definitions.
`data`	Object			Arbitrary user-defined metadata.
`document_ttls`	Boolean \| `null`			If true, you can write to the `ttl` field in the collection’s documents. `document_ttls` does not stop `ttl`-related deletions or affect `ttl` values set by the collection schema’s `ttl_days` field. See Enable or disable ttl writes.
`fields`	Object			FQL version of the collection schema’s field definitions. See FSL collection schema: Field definitions.
`history_days`	Number			Number of days of history to retain for collection documents. When the number of days lapses, document snapshots older than the interval are removed. Does not affect the current version of documents. Defaults to `0` (Retain only current documents). See Document history.
`indexes`	Object			FQL version of the collection schema’s index definitions. See Index definitions. `indexes` objects include fields you can use to monitor the index build. See `indexes` build fields.
`migrations`	Array of Objects			FQL version of the collection schema’s migrations block. See FSL collection schema: Migrations block.
`ttl_days`	Number			Documents are deleted `ttl_days` number of days after their last write. Defaults to `null` (Retained documents indefinitely). See Document time-to-live (TTL).
`wildcard`	String			FQL version of the collection schema’s wildcard constraint. See Wildcard constraints.

name

String

true

Name of the collection.

coll

String

true

The Collection collection name.

ts

Time

true

Timestamp of the most recent document write.

computed_fields

Object

FQL version of the collection schema’s computed fields. See FSL collection schema: Computed field definitions

constraints

Object

FQL version of the collection schema’s check and unique constraints. See FSL collection schema: Check constraint definitions and FSL collection schema: Unique constraint definitions.

data

Object

Arbitrary user-defined metadata.

document_ttls

Boolean | null

If true, you can write to the ttl field in the collection’s documents.

document_ttls does not stop ttl-related deletions or affect ttl values set by the collection schema’s ttl_days field.

See Enable or disable ttl writes.

fields

Object

FQL version of the collection schema’s field definitions. See FSL collection schema: Field definitions.

history_days

Number

Number of days of history to retain for collection documents. When the number of days lapses, document snapshots older than the interval are removed. Does not affect the current version of documents.

Defaults to 0 (Retain only current documents). See Document history.

indexes

Object

FQL version of the collection schema’s index definitions. See Index definitions.

indexes objects include fields you can use to monitor the index build. See indexes build fields.

migrations

Array of Objects

FQL version of the collection schema’s migrations block. See FSL collection schema: Migrations block.

ttl_days

Number

Documents are deleted ttl_days number of days after their last write.

Defaults to null (Retained documents indefinitely).

See Document time-to-live (TTL).

wildcard

String

FQL version of the collection schema’s wildcard constraint. See Wildcard constraints.

`indexes` build fields

indexes objects include fields you can use to monitor the index build:

Field Type Read-only Required Description

Field	Type	Read-only	Required	Description
`queryable`	Boolean	true		If true, the index is queryable. If false, the index is not queryable.
`status`	Union of `pending`, `active`, and `failed`.	true		Status of the index build. Possible values are `pending`, `active`, and `failed`.

queryable

Boolean

true

If true, the index is queryable. If false, the index is not queryable.

status

Union of pending, active, and failed.

true

Status of the index build. Possible values are pending, active, and failed.

Static methods

You can use the following static methods to manage the Collection collection in FQL.

Method Description

Method	Description
`Collection()`	Access a collection by its name.
`Collection.all()`	Get a Set of all collection definitions for the database.
`Collection.byName()`	Get a collection definition by the collection’s name.
`Collection.create()`	Create a collection.
`Collection.firstWhere()`	Get the first collection definition that matches a provided predicate.
`Collection.toString()`	Get `"Collection"` as a String.
`Collection.where()`	Get a Set of collection definitions that match a provided predicate.

Collection()

Access a collection by its name.

Collection.all()

Get a Set of all collection definitions for the database.

Collection.byName()

Get a collection definition by the collection’s name.

Collection.create()

Create a collection.

Collection.firstWhere()

Get the first collection definition that matches a provided predicate.

Collection.toString()

Get "Collection" as a String.

Collection.where()

Get a Set of collection definitions that match a provided predicate.

Instance properties

Collection documents have the following properties. You access the property using an existing collection’s name.

Property Description

Property	Description
`collection.definition`	A collection’s definition, represented as a `Collection` document.

collection.definition

A collection’s definition, represented as a Collection document.

Instance methods

You can use the following instance methods to manage collection definitions, represented as Collection documents, in FQL. You call the methods on a CollectionDef.

Method Description

Method	Description
`collectionDef.delete()`	Delete a collection.
`collectionDef.exists()`	Test if a collection exists.
`collectionDef.replace()`	Replace a collection definition.
`collectionDef.update()`	Update a collection definition.

collectionDef.delete()

Delete a collection.

collectionDef.exists()

Test if a collection exists.

collectionDef.replace()

Replace a collection definition.

collectionDef.update()

Update a collection definition.

Collection name methods

You can use the following collection name methods to create and manage documents within a user-defined collection using FQL. You call the methods directly on an existing collection’s name.

Method Description

Method	Description
`collection.all()`	Get a Set of all documents in a collection.
`collection.byId()`	Get a collection document by its document `id`.
`collection.create()`	Create a collection document.
`collection.createData()`	Create a collection document from an object that may contain metadata fields.
`collection.firstWhere()`	Get the first collection document that matches a provided predicate.
`collection.where()`	Get a Set of collection documents that match a provided predicate.
`collection.indexName()`	Call an index as a method to get a Set of matching collection documents.

collection.all()

Get a Set of all documents in a collection.

collection.byId()

Get a collection document by its document id.

collection.create()

Create a collection document.

collection.createData()

Create a collection document from an object that may contain metadata fields.

collection.firstWhere()

Get the first collection document that matches a provided predicate.

collection.where()

Get a Set of collection documents that match a provided predicate.