Collections and documents

A Collection groups documents in a database. In a relational database, a collection is called a table. Depending on your application requirements, you can organize your documents into one collection or several, and collections can be customized to retain document version history for as long as you want.

A Document is the basic unit of information in Fauna. All user data is stored in documents, and every entity in the Fauna data model, including Databases, Collections, and User-defined functions, is defined in a document.

Collections

reference:

Collection

Collections exist as global values in the Fauna environment.

Each collection includes a definition document that defines the collection name and can optionally define indexes and other metadata. Top-level objects with the names of each Collection exist so that operations on the collections and their documents can be performed. The top-level Collection object has methods that can manage collections.

A database may have zero or more user-defined collections, and a collection can have any number of documents.

Fauna provides a set of internal collections that can be used to manage database resources.

Collection persistence

A collection has two configuration fields that control document retention. Adjust the history_days field to retain more or less history. Setting history_days to null retains history indefinitely. By default, document history is stored for zero days. Increasing retention increases storage utilization.

Set the collection time-to-live (ttl) field to define a time for removal of documents in a collection. After the interval lapses, the document is removed and ceases to exist as if it never existed. After removal, temporal queries can’t recover the document. In the default case, the document persists indefinitely.

Collection definition document

See the Collection document definition reference documentation for a description of the collection definition data structure.

Documents

reference:

Document

A document belongs to a collection, similar to a table in other database systems, which groups similar documents. Documents in collections aren’t required to share the same structure. Documents can be nested.

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, rather than writing your applications to fit your 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 data types. Documents include:

  • a timestamp

  • the name of their collection

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

Documents changes create new versions, which supports temporal querying.

{
  "id": "349229195461657088",
  "coll": "Product",
  "ts": "2022-11-24T17:09:24.460Z",
  "name": "cups",
  "description": "Translucent 9 Oz, 100 ct",
  "price": 6.98,
  "quantity": 100,
  "store": {
    "id": "349229195457462784",
    "coll": "Store"
  },
  "backorderLimit": 5,
  "backordered": false
}

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

Common document characteristics

All documents have a set of common characteristics:

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

References

A Reference uniquely identifies a database document.

Each Reference is a compound value that is composed of:

  • The name of the collection the document belongs to, which can be a user-defined collection, or a native collection, such as Token.

  • A document ID is a string-encoded 64-bit integer. References to native collections don’t have document IDs. The name of the native collection is its unique identifier.

The collection Reference and the document ID refer to a distinct document, and no two documents in a database can share the same Reference.

One and only one of the document id or name fields is present, depending on if the reference points to a named value or not. For example, role documents have a name, so they have the name field only and an associated byName() method to get the document by reference. Documents with an id field have a byId() method to get the document by reference.

When there is an exists field you can use it to find if the reference points to a document that can be read. If exists is set to false, there is a corresponding cause field that indicates the reason that the document can’t be read. Possible reasons are:

  • Not found.

  • Permission denied.

If the exists field isn’t present, the document may or may not exist.

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!