FQL v4 will be decommissioned on June 30, 2025. Ensure that you complete your migration from FQL v4 to FQL v10 by that date.

For more details, see the v4 EOL announcement and migration guide. Contact support@fauna.com with any questions.

Data model, querying, and security

Data model

Fauna’s data model is based on documents, collections, and databases. A database has one or more collections, and a collection contains one or more documents. Most collections use one or more indexes, which are required to support searching, sorting, and other kinds of queries.

Fauna is a document-oriented database. Storing data in documents instead of rows and columns gives you greater flexibility and allows you to shape your data in the way that best fits your applications, rather than writing your applications to fit your data.

Data stored in a document looks similar to a JSON document and can include strings, integers, arrays, and other data types. All documents also include a timestamp and a unique Ref which is a combination of the document’s collection name and a string representation of an integer. Documents are stored in immutable fashion; mutations create new versions, which supports temporal querying.

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

Collections contain documents. In a relational database, a collection would be called a table. Depending on your application requirements, you can organize your documents into one collection or several, and collections can be customized to retain each document’s version history for as long as you need. Region Groups provide a way to satisfy data residency requirements.

Databases can also contain:

  • indexes, for searching and reporting on documents,

  • user-defined functions, for defining business/query logic,

  • keys, tokens, credentials, and access providers, which are all part of a Fauna database’s security configuration,

  • child databases, which are useful for multitenancy applications.

Learn more:


Fauna’s query model is based on indexes and fql-formal (FQL). FQL provides functions for searching and retrieving data, and indexes provide the necessary sorting structure. If you’re coming from the SQL world, Fauna indexes are similar to views on a relational database.

When you’re ready to begin working with a Fauna collection, it’s important to consider your data access needs and create the necessary indexes to satisfy those requirements. To learn more about index creation, see the Index tutorials. For examples of index creation and usage, see Index recipes.

Fauna features ACID compliant transactions, and consistent, global replication. The architecture of Fauna which powers these capabilities is inspired by the Calvin Protocol. Data consistency and isolation are baked in, with no additional application code necessary.

FQL includes built-in functions for CRUD, math and logical operations, as well as security and database administration. For more complex functionality, you can create user-defined functions, which can then be assigned individual roles and privileges.

Learn more:


Security in Fauna gives you control over all aspects of data access and manipulation. You can use either identity-based or anonymous-based access control, with privileges as fine-grained as individual documents or as large as entire databases. You can create custom roles or use built-in roles, and assign them to users, functions, and other database entities. All Fauna databases require authentication and cannot be left accidentally unprotected.

Fauna offers authentication either anonymously with API keys, with identity-based tokens, or through third-party authentication providers by using JSON Web Tokens (JWTs).

Learn more:

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!