Documents

reference:

Document

A Document is the basic unit of information in Fauna. Documents belong to Collections, similar to a table in other database systems.

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.

Fauna uses a flexible schema model. While possible, documents in the collection aren’t required to share the same structure. You control a collection’s document structure using field definitions.

Data stored in a document looks similar to a JSON document and can include strings, integers, arrays, and other 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 transaction limits.

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.

  • Documents have an optional time-to-live (ttl) field that indicates when the document should be removed. On removal, the document ceases to exist as if it never existed. Temporal queries can’t recover the document.

CRUD operations on documents

Every document object has the following methods:

Method Description

delete()

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

exists()

Tests if a given document exists.

replace()

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

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.

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!