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 is a shared, globally-accessible database service. To optimize query performance and share resources in a fair manner, the following limits are in place:

Constraint Limit

Document size

8MB/document

Query size

16MB/query

Transaction size

16MB/transaction

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

Was this article helpful?

We're sorry to hear that.
Tell us how we can improve!
Visit Fauna's Discourse forums or email docs@fauna.com

Thank you for your feedback!