Key Concepts

Documents

Documents are the basic unit of information in Fauna. All user data is stored in documents, and everything in the Fauna data model — including databases, collections, indexes, and user-defined functions — is defined in a document.

Documents are similar to JSON objects, with keys and values. A typical document looks like this:

{
  ref: Ref(Collection("myCollection"), "302044124774662656"),
  ts: 1624310574250000,
  data: {
           'stringValue': 'abc123',
           'arrayValue': ['abc', 1, 2, 3]
           'integerValue': 358192,
           'objectValue': { 'a': 1, 'b': 2, 'c': 3 }
        }
}

Documents may be nested. The value for any key may itself be a document.

See the limits page for details on document size and transaction limits.

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

Collections are containers for holding documents. They serve the same purpose in Fauna’s data model that tables do in SQL databases. A database may contain one or more collections, and a collection may have any number of documents. To create a collection, use the CreateCollection function.

Once the collection has been created, it is possible to create documents within the collection using the Fauna Query Language or the GraphQL API.

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

References

A Reference is the unique identifier for a document in a particular database.

Each Reference is a compound value, composed of:

  • a reference to the collection containing the document: either a user-defined collection, or a system schema collection, such as Tokens.

  • a document ID: a string-encoded 64-bit integer. Note that References to system schema collections do not have document IDs; the name of the system schema collection is its unique identifier.

Together, the collection reference and the document ID refer to a distinct document: no two documents in a database can share the same reference.

Indexes

Fauna’s query model relies on indexes to support all query patterns which do not involve looking up documents directly by their Reference. An understanding of index creation and usage is crucial for effective Fauna development.

Indexes allow for the organization and retrieval of documents by attributes other than their Reference. They act as a lookup table that improves the performance of finding documents: instead of reading every single document to find the one(s) that you are interested in, you query an index to find those documents.

User-defined functions

The Fauna Query Language provides many built-in functions that can be used to query and modify a database. User-defined functions (or UDFs) provide a mechanism to store and run commonly used Fauna queries.

User-defined functions are used to combine functions, built-in or user-defined, into queries that can be stored and executed repeatedly.

Region groups

Region Groups provide control over where your data resides: each database, its storage, and its compute services exist in a specific geographic region. The capability makes it possible to comply with data locality legislation, such as the General Data Protection Regulation (GDPR) in Europe, while benefiting from Fauna’s distributed service features.

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!