Documents

Every record, of any kind, in a FaunaDB 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 FaunaDB.

Even the definitions of Databases, Collections, Keys, Indexes, and user-defined functions, are all documents. They exist within internal FaunaDB 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 created. FaunaDB documents are versioned, 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.

  • 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; temporal queries cannot recover the document.

    Document removal is handled by a background task, so once the ttl "expires", it could be some time (hours or days) before the document removal occurs. There is no guarantee that removal actually occurs.

  • 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, FaunaDB 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

FaunaDB 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 FaunaDB 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, FaunaDB 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! documentation@fauna.com

Thank you for your feedback!