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.

Documents

Reference: Document

You add data to Fauna as JSON-like objects called documents. A document is a single, changeable record in a Fauna database. Each document belongs to a collection.

All user data is stored in documents, and every entity in the Fauna data model, including Database, Collection, and Function, is defined in a document.

Storing data in documents instead of rows and columns gives you greater flexibility. It allows you to shape your data in the way that best fits your applications instead of writing your applications to fit the data. Every record in a Fauna database is grouped and stored as a Document object, consisting of key:value pairs. A key can be a document.

Data stored in a document looks similar to a JSON document and can include Strings, Integers, Arrays, and other FQL data types. Documents include:

  • a timestamp

  • the name of their collection

  • a string-encoded integer used as a document ID.

Documents changes create a new version of the document, which supports temporal querying.

See the Global limits for more information on document size and query limits.

Document type

A document’s data type is taken from its collection’s name. For example, Product for a document in the Product collection. This type is an instance of the Document type, which is a subtype of the Object type.

You define the structure of a collection’s document type using the collection schema’s:

See Document type definitions

Document metadata

All documents have these common metadata fields:

  • Documents have a string-encoded 64-bit integer identifier. A document ID is a compound value of a collection identifier and a unique document ID. The ID is a unique identifier for the document in the scope of the database where it is stored.

  • When a document is updated, a new version is stored. User documents have a timestamp that identifies the most recent document update. Documents are versioned, and the versions are distinguished using a timestamp. When a query doesn’t specify a timestamp, the latest version of the document is used. The timestamp is returned in the document ts field.

  • The ts field shouldn’t be directly manipulated. To track timestamps independent of Fauna operations, include fields that are under your control in your documents to record timestamps.

  • data is 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.

  • Documents have an optional ttl (time-to-live) field that indicates when the document should be removed. See Document time-to-live (TTL).

CRUD operations on documents

Every document object has the following methods:

Method Description

document.delete()

Deletes the document, returning the id and coll in an object.

document.exists()

Tests if a given document exists.

document.replace()

Fully replaces the document data with the provided data. Fields are removed if they aren’t present in the provided data.

document.update()

Updates the document with the provided data and returns the updated document. This does a patch update. Omitted fields are left as-is. To remove fields from a document, set the field value to null.

NullDoc

A NullDoc is a marker used to indicate that a document doesn’t exist or is inaccessible.

A NullDoc’s data type is taken from its collection’s name. For example, a NullDoc for a Product collection document is NullProduct. NullDocs always contains a null value.

Several FQL methods, such as collection.byId(), return a NullDoc for missing or inaccessible documents:

// Attempts to access a `Product` collection document
// with an `id` of `12345`. In this
// example, the document doesn't exist.
Product.byId("12345")
// Returns a `NullProduct` value.
Product("12345") /* not found */

Is this article helpful? 

Tell Fauna how the article can be improved:
 Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!