Documents

Every record, of any kind, in a Fauna database is stored as an object called a document. Documents are made up of fields and their associated value, just like a JSON object. The value for any key can itself be a document.

Every document belongs to a specific collection, similar to a table in other database systems, which groups similar documents together. Documents within collections are not required to share the same structure. Collections belong to a specific database, which is the contains of all other schemas in Fauna.

Even the definitions of Databases, Collections, Keys, Indexes, and user-defined functions, are all documents. They exist within internal Fauna collections of the same name.

All documents have a set of common characteristics:

  • Documents have an identifier called a ref. A document’s ref encodes its collection along with a unique id. The combination of these attributes forms a unique identifier for the document within the scope of the database in which it is stored.

  • User-specified documents have a timestamp that identifies when the document was most recently updated. Fauna documents are versioned — each time a document is updated, a new version is stored — and the versions are distinguished using the timestamp. When a query does not specify a timestamp, the latest versions of any documents involved are used. The timestamp — returned in the ts field — is of type Integer.

    ts should not be directly manipulated. Instead, you can use the Insert and Remove functions to manipulate the history of a document at specific timestamps.

    To track timestamps independent of Fauna operations, include fields in your documents to record timestamps entirely under your control.

  • Documents can have an optional ttl field (meaning time-to-live), which is a timestamp that indicates when the document should be removed. When a document is removed, the document’s existence ceases (as if it never existed); temporal queries cannot recover the document.

    Removal is handled by a background task, so once a document (including collections, databases, indexes, keys, roles, and tokens) "expires" due to the setting in the ttl field, it could be some time (hours or days) before the removal occurs. There is no guarantee that removal actually occurs.

    As of version 3.0.0, the ttl field is honored on read — a document that should have been removed behaves as if it has been removed. However, until removal actually occurs due to background task processing, you can continue to access the history of the document, provided you have its reference, via the Events function.

  • Documents are manipulated with the same query language functions, such as get, create, update, replace, or delete. Documents returned by queries are represented as JSON objects. Within a query, a document’s fields may be accessed using the Select function.

To separate the ref and timestamp from user-defined fields, Fauna wraps each user-specified document in a metadata document for storage, and user-specified data appears in the data field. For example, when a blog post document is created, it is stored as:

{
  ref: Ref(Collection("posts"), "227576404750893579"),
  ts: 1553292644000000,
  data: {
    title: 'My blog post',
    tags: [ 'post', 'popular', 'blog' ],
    body: "Lorem ipsum..."
  }
}

Limits

Fauna does not impose any architectural limits on the size of a document. Operational concerns do impose limits, such as available system memory, storage, network, and so on.

The most important operational limit is that Fauna requests cannot currently exceed 1 megabyte, including request headers. That means that the maximum size for a document, upon creation, is approximately 1,020 kilobytes, which includes the JSON syntax required to describe the document.

Documents can be modified to become larger than the request limit, or could be generated using functions such as Repeat or Reduce. Documents that exceed 5 megabytes may show evidence of poorer performance than smaller documents.

As a document database, Fauna is not currently a good storage solution for arbitrary binary blob data, such as images, PDFs, etc.

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!