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

Fauna accounts created after August 21, 2024 must use FQL v10. These accounts will not be able to run FQL v4 queries or access the v4 Dashboard.

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

Collections

A database’s schema is defined by its collections, which are similar to tables in other databases. Collections are containers for holding 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 FQL API.

A collection cannot be created and used in the same transaction.

It is possible to rename a collection by updating its name field. Renaming a collection changes its Reference, but preserves inbound references to the collection. Documents within the collection remain associated with the collection.

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

Reading or writing collection’s metadata document (not the documents within the collection) requires a key with the server role or better, or equivalent Attribute-based access control (ABAC) permissions.

To learn more about common operations and functions related to collections, see Collection recipes.

Structure

Field Type Definition and Requirements

Field	Type	Definition and Requirements
`name`	String	The name of the collection. Cannot be `events`, `sets`, `self`, `documents`, or `_`. Cannot have the `%` character.
`data`	Object	Optional - A JSON object, for storing additional metadata about the collection.
`history_days`	Number	Optional - Document history is retained for at least this many days. When the number of days has elapsed, events older than the specified time window are removed. The current version of a document is retained. The default value is to zero days. See Temporality. See Temporality.
`ttl_days`	Number	Optional - Documents are deleted this many days after their last write. Defaults to `null`, which means that documents are always retained.
`permissions`	Object	Optional.

name

String

The name of the collection.

Cannot be events, sets, self, documents, or _. Cannot have the % character.

data

Object

Optional - A JSON object, for storing additional metadata about the collection.

history_days

Number

Optional - Document history is retained for at least this many days. When the number of days has elapsed, events older than the specified time window are removed. The current version of a document is retained. The default value is to zero days.

See Temporality.

ttl_days

Number

Optional - Documents are deleted this many days after their last write. Defaults to null, which means that documents are always retained.

permissions

Object

Optional.

Each collection has two configuration fields that control the retention of documents. By default, document history is stored for zero days. Set history_days to another value to keep more, or less, history. Setting history_days to null retains history indefinitely. Increasing retention increases storage utilization. See Billing for storage implications.

By setting a collection’s ttl_days, documents within the collection are removed as if they never existed if they have not been updated within the configured number of days.

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!