Key concepts
This guide covers key Fauna concepts and features.
Fauna
Fauna is a distributed document-relational database service that combines the flexibility of documents with the power of a relational database.
You access Fauna through a client driver or directly through an HTTP API.
See Client drivers, Fauna Core API |
---|
Transactions
Every Fauna query is a transaction, submitted as a request to the Query HTTP API endpoint.
Transactions are isolated and serialized to guarantee consistency across concurrent operations.
See Transactions |
---|
Distributed service
Fauna uses a fully managed, serverless infrastructure designed for high availability and global distribution.
Region groups
You assign each top-level Fauna database a region group. Region groups give you control over where your data resides.
You can use region groups to comply with data locality legislation, such as the General Data Protection Regulation (GDPR).
See Region groups |
---|
Intelligent routing
All Fauna transactions use a single HTTP endpoint, regardless of their region group or database.
Fauna uses intelligent routing to route requests to the right region group and database based on its authentication token. A client application can use multiple region groups or databases without code changes.
See Intelligent routing |
---|
High availability
Fauna replicates your data by default. Your data is unaffected by regional outages and is always recoverable from disasters.
See Replica distribution |
---|
Virtual private Fauna
Virtual Private Fauna lets you use Fauna in a single-tenant environment with no infrastructure management.
You can fully customize Virtual Private Fauna to meet your specific security and compliance needs. Virtual Private Fauna is available across a single region, multiple regions, or multiple clouds of your choice.
See Virtual Private Fauna |
---|
Data model
You add data to Fauna as JSON-like objects called documents. Documents are stored in collections, which group related data.
See Data model |
---|
Indexes
An index stores, or covers, specific document field values for quick retrieval. Using indexes can significantly improve query performance and reduce costs, especially for large datasets.
You create indexes at the collection level. Fauna indexes support non-scalar data types, such as arrays or nested objects, and non-ID scalar fields.
See Indexes |
---|
Multi-tenancy
You can use Fauna to build multi-tenant applications with strong isolation guarantees.
A Fauna database can have multiple child databases. Child databases can have their own child databases.
You can programmatically create databases using queries or the Fauna CLI. Databases are instantly allocated.
Each database is logically isolated from its peers, with separate access controls. Transactions run in the context of a single database and can’t access data outside the database.
See Databases and multi-tenancy |
---|
Connect to Fauna
You can interact with Fauna through a client driver or directly through the HTTP API. Any client that can send and receive HTTP requests can connect to Fauna.
See Fauna Core API |
---|
Fauna drivers
Fauna has official client drivers for popular programming languages, such as JavaScript, Python, and Go.
Each driver is a lightweight, open-source wrapper for the Fauna Core HTTP API. The drivers are small enough for use in serverless functions, edge networks, and other resource-constrained environments.
See Client drivers |
---|
Fauna CLI and Dashboard
You manage Fauna using the Fauna CLI or the Fauna Dashboard UI. Use the CLI or Dashboard to:
-
Create and delete databases
-
Define and manage schemas
-
Run queries in an interactive shell
See Fauna CLI, Fauna Dashboard |
---|
Schema
Schemas determine the structure and behavior of your database.
See Schema |
---|
Fauna Schema Language
In Fauna, you define schemas using Fauna Schema Language (FSL). You use FSL to create and update schemas for collections, security roles, server-side user-defined functions (UDFs), and more.
See FSL reference |
---|
Document type
A collection schema can include a document type definition. The document type controls what fields are accepted in a collection’s documents.
You define a document’s type using:
-
Field definitions that predefine fields for the collection’s documents
-
A wildcard constraint that allows or disallows arbitrary ad hoc fields
-
Computed field definitions that derive their value from a user-defined function that runs on every read
See Document type definitions |
---|
Zero-downtime migrations
A schema migration is an update to a collection schema’s document type. In Fauna, schema migrations require no downtime or locks on your database.
You can use schema migration to progressively define and enforce a document type in a collection. For example, you can:
-
Require that new documents contain specific fields
-
Add and backfill fields in existing documents
-
Move or rename existing fields
-
Add, remove, or update the wildcard constraint
See Zero-downtime migrations (beta) |
---|
User-defined functions (UDFs)
A user-defined function (UDF) is a set of one or more FQL statements stored as a reusable resource in a Fauna database. Like a stored procedure in SQL, a UDF can accept parameters, perform operations, and return results.
You can use UDFs to encapsulate business logic, making it easier to manage complex operations within your database.
See User-defined functions (UDFs) |
---|
Manage schemas as FSL files
You can manage schemas as FSL files and use the Fauna CLI to push changes to Fauna. This lets you version control, review, and automate schema changes.
See Fauna CLI |
---|
Query data with FQL
Fauna Query Language (FQL) is a TypeScript-like language used to read and write data. You typically compose an FQL query by chaining methods to one or more collections. Expressions are evaluated from left to right.
See FQL language reference |
---|
Static typing
FQL is statically typed. Every expression has a data type that’s checked before evaluation.
Type checking helps catch errors early and consistently, saving you time during development. You can turn off type checking for any query.
See Static typing |
---|
Document relationships and references
Fauna supports one-to-one, one-to-many, and many-to-many relationships between documents in different collections.
You create relationships by including a reference to a document in another document. This lets you model complex data structures without duplicating data across collections.
Projection lets you return only the specific fields you want from queries. You can project results to dynamically resolve document relationships. This lets you traverse multiple deeply nested relationships in a single query.
See Model relationships between documents |
---|
Event streaming
Fauna supports event streaming. An event stream sends your application a real-time update when changes occur in a database. You can configure streams to only track specific collections, fields, or documents.
Fauna’s drivers provide methods for creating and connecting to streams.
See Event streams |
---|
Security
Fauna prioritizes security and compliance. All Fauna connections use HTTPS. Fauna is compliant with GDPR and SOC2 Type II. Fauna can be configured to meet HIPAA requirements.
See Security |
---|
Authentication
Fauna uses stateless, token-based authentication. You authenticate with Fauna using secrets that are passed to the Fauna Core HTTP API as bearer tokens. Every transaction is an independently secured API request.
Identity-based authentication
Fauna supports two methods for end-user authentication:
-
Credentials: A credential associates an end-user password with a document representing a user, system, or other identity. This document is called an identity document.
Once created, you use the credential to generate a token you can use as an authentication secret. The token is associated with the identity document and can have multiple roles.
See Credentials -
Access providers: Configure an external identity provider (IdP), such as Auth0, as an access provider in your Fauna database.
When a user logs in, the access provider passes a JSON Web Token (JWT) to your application. You can use the JWT as a secret. The JWT is associated with the user and can have multiple roles.
See Access providers
Anonymous authentication
You can also create keys that can be used as authentication secrets. Unlike tokens and JWTs, keys are not associated with an identity and only have one role.
See Keys |
---|
Authorization
Secrets are also used for authorization. Each secret has one or more roles that control access to a database’s data.
See Authorization |
---|
Roles
Fauna uses secrets for authentication and authorization. Roles determine a secret’s privileges, which control data access.
See Roles |
---|
ABAC
Fauna supports attribute-based access control (ABAC), which extends traditional role-based access control (RBAC).
In Fauna, you define roles and their privileges as FSL schemas. You can conditionally grant roles or privileges using predicates.
See Attribute-based access control (ABAC) |
---|
Privilege predicates
Predicates are anonymous, read-only FQL functions that evaluate to true
or
false
. They have access to FQL methods, collections, and server-side UDFs.
Privilege predicates can also access the current token’s identity document.
Fauna evaluates privilege predicates at query time for each query. This lets you dynamically change privileges based on current state. For example, you can change access based on:
-
The user’s current location, status, or recent activity.
-
The accessed document’s current status or other attributes.
-
Date or time of day
See Attribute-based access control (ABAC) |
---|
Dynamic role assignment
Fauna assigns roles to tokens based on their identity document’s collection
and the role’s membership
property.
You can use membership predicates to dynamically assign roles based on current state. Like privilege predicates, Fauna evaluates membership predicates at query time for each query.
See Attribute-based access control (ABAC) |
---|
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!