Documents, Collections, and Databases

Documents are single, changeable records within a FaunaDB database. A database is a container for data. A collection is a group of documents within a database.

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 databases. Documents within collections are not required to share the same structure.

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 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..."
  }
}

Databases

Databases are defined as documents of type database. Databases exist within the system-global root database context.

Aside from keys, all other documents exist within the context of a specific database. All queries are limited to a single database as well, and cannot span across databases.

It is possible to rename a database by updating its name field. Renaming a database changes its ref, but preserves inbound references to the database. The data within a database remains accessible via existing keys.

When a database is deleted, its associated data becomes inaccessible and is deleted asynchronously.

Field Type Definition and Requirements

name

String

Cannot be events, sets, self, documents, or _.

api_version

String

The default API version for requests made to this database. Defaults to "2.0".

priority

Number

A priority between 1 and 500, inclusive. Defaults to 1.

data

Object

A JSON object. Optional.

Collections

A database’s schema is defined by its collections, which are similar to tables in other databases. To create a collection, create a document of type collection.

Once the collection is defined, it is possible to create documents within the collection using the query API.

A collection cannot be created and used in the same transaction.

It is possible to rename a collection by updating its name field. Renaming a collection changes its ref, but preserves inbound references to the collection. Documents within the collection remain associated with the collection.

When a collection is deleted, associated documents become inaccessible and are deleted asynchronously.

Field Type Definition and Requirements

name

String

Cannot be events, sets, self, documents, or _.

data

Object

A JSON object. Optional.

history_days

Number

Document history is retained for at least this many days. Defaults to 30 days.

ttl_days

Number

Documents are deleted this many days after their last write. Optional.

permissions

Object

Optional.

Each collection has two configuration fields that control the retention of documents. By default, document history is stored for 30 days. Set history_days to another value to keep more or less history. Setting history_days to null retain history indefinitely. Increasing retention increases storage utilization.

By setting a collection’s ttl_days, documents within the collection are removed if they have not been updated within the configured TTL.

Was this article helpful?

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

Thank you for your feedback!