Collections

You add data to Fauna as JSON-like objects called documents. Documents are stored in collections, which group related data.

Collection types

Fauna has two types of collections:

User-defined collections
System collections

User-defined collections

A user-defined collection stores application data you’ve added to a Fauna database. For example, a database for an e-commerce application may have a Product collection to store product-related data.

A database can have zero or more user-defined collections. A user-defined collection can have any number of documents.

System collections

A system collection stores built-in Fauna resources.

For example, Fauna stores credentials as documents in the Credential system collection. You can use Credential methods to access Credential collection documents in FQL.

System collections include:

Named collections

A named collection is a subset of system collections whose documents are uniquely identified using names instead of document IDs.

Named collections include:

Limitations

You can create and manage system collection documents, but you can’t create, change, or delete a system collection itself.

You can’t change the collection schema of a system collection.

Collection schema

You create and manage user-defined collections as FSL collection schema.

Each user-defined collection has a collection schema. The schema defines the structure and behavior of a collection and its documents.

See Collection schema

`Collection` collection

Fauna stores the schema for user-defined collections as documents in the Collection system collection. You can use the Collection collection’s static methods to access collection schema in FQL.

Reference: Static Collection methods

Create and access collection documents

Collections names act as top-level objects in FQL queries. You can use collection name methods to create and access collection documents.

For example, the following query uses collection.create() to create a document in the Customer collection:

// Creates a `Customer` collection document.
Customer.create({
  name: "John Doe",
  email: "jdoe@example.com",
  address: {
    street: "87856 Mendota Court",
    city: "Washington",
    state: "DC",
    postalCode: "20220",
    country: "US"
  }
})

The query returns the document and includes the document ID:

{
  id: "12345",
  coll: Customer,
  ts: Time("2099-07-10T15:41:49.945Z"),
  cart: null,
  orders: "hdW...",
  name: "John Doe",
  email: "jdoe@example.com",
  address: {
    street: "87856 Mendota Court",
    city: "Washington",
    state: "DC",
    postalCode: "20220",
    country: "US"
  }
}

You can use collection.byId() to get a document by its ID:

// Gets a `Customer` collection document by ID.
Customer.byId("12345")

You can chain document instance methods to a document to update, replace, or delete the document.

For example, the following query uses document.update() to update a document:

// Updates the `Customer` collection document.
Customer.byId("12345")?.update({
  // Updates the existing `name` field value.
  name: "Jonathan Doe"
})

Reference: Collection name methods, document instance methods

Security and privileges

A user-defined role can assign privileges to a collection, including system collections.

Collection privileges grant access to a collection’s documents. A collection privilege can allow the create, delete, read, or write actions. read access includes the ability to call the collection’s indexes. An example FSL role schema:

role customer {
  // Grant read access to `Product` documents and indexes.
  privileges Product {
    read
  }
}

You can also grant access to system collections that store Fauna resources:

role manager {
  // Grant `create` and `read` access to the `Token` system collection.
  // Allows the role to create token secrets.
  privileges Token {
    create
    read
  }
}

To allow a role to create, delete, or manage user-defined collections themselves, grant access to the Collection system collection:

role manager {
  // Grant full access to the `Collection` system collection.
  // Allows the role to create, delete, read, and update
  // user-defined collections.
  privileges Collection {
    create
    delete
    read
    write
  }
}

Built-in roles also have collection privileges. See built-in roles.