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 Fauna Query Language or the GraphQL 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 ref, 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.

Field Type Definition and Requirements

name

String

The name of the collection.

Cannot be events, sets, self, documents, or _. Cannot contain 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. Defaults to 30 days.

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 30 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.

Removal is handled by a background task, so once a document (including collections, databases, indexes, keys, roles, and tokens) "expires" due to the setting in the ttl_days field, it could be some time (hours or days) before the removal occurs. There is no guarantee that removal actually occurs.

For more immediate removal, use the ttl field on documents that should have limited lifespans. See Documents for details.

Was this article helpful?

We're sorry to hear that.
Tell us how we can improve!
 Visit Fauna's Discourse forums or email docs@fauna.com

Thank you for your feedback!