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(Class("posts"), "227576404750893579"),
  ts: 1553292644000000,
  data: {
    title: 'My blog post',
    tags: [ 'post', 'popular', 'blog' ],
    body: "Lorem ipsum..."
  }
}

Was this article helpful?

We're sorry to hear that.
Tell us how we can improve! documentation@fauna.com

Thank you for your feedback!