Temporality

Temporality is a Fauna feature that allows you to query your database at a specific point in time.

Document history

Whenever a document is created or updated, Fauna stores a new version of the document along with the current transaction timestamp. Fauna indexes also store the history of fields in the index’s terms or values definitions. The result is a record of the evolution of your database that is automatically updated as changes occur.

You can explore a document’s changes, which are called events, by using the Events function. You can modify a document’s history by using the Insert and Remove functions.

Temporal queries

The At function allows you to execute a query expression at a specific timestamp, and the results include documents or values that existed in your database at that timestamp.

Removal of documents or history

Temporal queries work as expected when document history exists. However, document history increases the amount of storage required for your database, and significant amounts of history can affect the performance of your queries. See Billing for more details.

If temporality is less important than billing and performance, we recommend using one or more of the following features to automatically remove document history, or to remove documents and their history:

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

Document history removal

  • history_days is a collection field that specifies the number of days of document history that should be maintained, for all documents within the collection. Once the specified number of days has elapsed, document history is removed, but the document itself is retained.

    This feature is useful for any documents that change frequently and only the most recent versions are required. For example, any document that stores a rolling overage of some activity over the past month.

    history_days should be set to zero for a collection storing counters, as those are often updated extremely frequently. Counters that update multiple times per second can quickly cause enough history to be retained to notably affect the performance of queries operating on the counter.

Document plus history removal

  • ttl is a document field that specifies the document’s time-to-live, which is when the document and all of its history should be removed. When a document is removed, the document’s existence ceases (as if it never existed); temporal queries cannot recover the document nor its history.

    This is particularly useful for "intermediate" documents involved in gathering report data. These documents need to be retained while a complex report is being prepared, but after the report has been generated the documents can be removed automatically.

    This feature should be used carefully because documents with ttl set can be removed automatically. As such, the default ttl is undefined, which means that document history is retained indefinitely.

    As of API version 3, the ttl field is honored on read — a document that should have been removed behaves as if it has been removed. However, until removal actually occurs due to background task processing, you can continue to access the history of the document, provided you have its reference, via the Events function.
  • ttl_days is a collection field that specifies the number of days that documents in the collection should be retained. Once the specified number of days has elapsed, any documents (and all of their history) whose age in days is greater are removed.

    This feature could be useful for any documents that need to exist for short periods and you wish to avoid executing "maintenance" queries to remove the documents.

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!