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.

Document

Learn: Documents

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

Document fields

All documents contain the id, coll, ts, and optional ttl metadata fields. Documents in user-defined collections also typically contain user-defined fields. For example:

{
  id: "392886847463751746",
  coll: Product,
  ts: Time("2099-04-10T16:50:12.850Z"),
  ttl: Time("2099-04-15T16:50:12.850Z"),
  name: "key limes",
  description: "Conventional, 16 oz bag",
  price: 299,
  stock: 100,
  category: Category("401610017107607625")
}

Field Type Read-only Required Description

Field	Type	Read-only	Required	Description
`id`	ID	true		ID for the document. The ID is a string-encoded, 64-bit unsigned integer in the 2^53-1 range. The ID is unique within the collection. IDs are assigned at document creation. To create a document with a user-provided `id` using `collection.create()`, you must use a secret with the `create_with_id` privilege. If not provided, Fauna generates the `id`.
`coll`	Collection	true		Name of the document’s collection. he `coll` field can’t be indexed.
`ts`	Time	true		Last time the document was created or updated.
`ttl`	Time or `null`			Time-to-live (TTL) for the document. Only present if set. If not present or set to `null`, the document persists indefinitely.
`<USER_DEFINED_FIELD>`	Any supported data type			User-defined document field. Schema method names and schema metadata field names are reserved and can’t be used as a field name but can be used in nested objects. You can enforce typing and constraints for user-defined fields in a collection using collection schema.
`data`	Object		true	A reserved field that contains all user-defined fields and their values. By default, the `data` field isn’t returned in query results. However, if typechecking is disabled, you can project the field to return it. The `data` field does not contain computed fields or metadata fields, such as `id`, `coll`, `ts`, or `ttl`. You can use the `data` field to safely nest user-defined fields that have reserved field names, such as `id` or `ttl`, in a document. See Data field and Avoid conflicts with reserved fields in the v10 migration docs.

id

true

ID for the document. The ID is a string-encoded, 64-bit unsigned integer in the 2^53-1 range. The ID is unique within the collection.

IDs are assigned at document creation. To create a document with a user-provided id using collection.create(), you must use a secret with the create_with_id privilege. If not provided, Fauna generates the id.

coll

Collection

true

Name of the document’s collection. he coll field can’t be indexed.

ts

Time

true

Last time the document was created or updated.

ttl

Time or null

Time-to-live (TTL) for the document. Only present if set. If not present or set to null, the document persists indefinitely.

<USER_DEFINED_FIELD>

Any supported data type

User-defined document field.

Schema method names and schema metadata field names are reserved and can’t be used as a field name but can be used in nested objects.

You can enforce typing and constraints for user-defined fields in a collection using collection schema.

data

Object

true

A reserved field that contains all user-defined fields and their values.

By default, the data field isn’t returned in query results. However, if typechecking is disabled, you can project the field to return it.

The data field does not contain computed fields or metadata fields, such as id, coll, ts, or ttl.

You can use the data field to safely nest user-defined fields that have reserved field names, such as id or ttl, in a document. See Data field and Avoid conflicts with reserved fields in the v10 migration docs.

Instance methods

You can use the following instance methods to manage a document in FQL.

Method Description

Method	Description
`document.delete()`	Delete a collection document.
`document.exists()`	Test if a collection document exists.
`document.replace()`	Replace all fields in a collection document.
`document.replaceData()`	Replace a collection document using an object that may contain metadata fields.
`document.update()`	Update a collection document's fields.
`document.updateData()`	Update a collection document using an object that may contain metadata fields.

document.delete()

Delete a collection document.

document.exists()

Test if a collection document exists.

document.replace()

Replace all fields in a collection document.

document.replaceData()

Replace a collection document using an object that may contain metadata fields.

document.update()

Update a collection document's fields.

document.updateData()

Update a collection document using an object that may contain metadata fields.