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 instance 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 instance methods, document instance methods

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!