Temporality

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

Document history

When 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 declared in the index terms or values definitions. The result is a record of the evolution of your database that is updated as changes occur.

Changes to a document are called events, You can explore those changes by using the Events function. You can change document history 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. But, document history increases the amount of storage required for your database, and significant amounts of history can affect the performance of your queries.

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

Document history removal

The history_days collection field specifies the number of days of document history that should be maintained, for all documents in the collection. After the number of days elapses, document history is removed, but the document is retained.

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

The default`history_days` value of zero is appropriate for a collection that stores counters because those are updated at a high rate. Counters that update multiple times per second can quickly cause enough history to be retained to noticeably affect the performance of queries operating on the counter.

Setting history_days to null causes a collection to retain version history for each document indefinitely. The more frequently documents are updated in a collection, the more history consumes database storage. When an indexed field is frequently updated, the indexes retain the history of indexed fields also, which can increase the latency for queries on that index over time. Be aware of how your history_days choice affects your storage costs and query latency, and avoid unnecessary history retention.

Setting history_days to zero retains only the current version of each document in a collection, and no history is retained.

Updating history_days has the following behavior. If history_days becomes smaller, such as changing the value from 10 days to zero days, history is truncated as of the time of the collection document update, minus the new history_days value. History before the new history_days setting is inaccessible.

If history_days becomes larger, such as changing the value from zero to 30 days, history begins accumulating as of the time of the collection document update. After history_days expires, history before the time of the update to the collection becomes inaccessible.

Document plus history removal

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

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

This feature should be used carefully because documents with ttl set can be removed without intervention. 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 be removed behaves as if removal has taken place. But, until removal occurs you can continue to access the history of the document, provided you have its reference, using the Events function.

The ttl field has the following behavior:

Queries using temporality, including the use of the At, Events, or Paginate functions, return an error if the effective query timestamp is older than a collection history_days value.
Indexes don’t report document events older than the history_days value in the source collections.
When ttl_days is set on a collection, new documents have the ttl field set according to the ttl_days value.
When the ttl timestamp is passed, the document is removed but its history continues to exist until the collection history_days has elapsed.

ttl_days is a collection field that specifies the number of days that documents in the collection should be retained. After the number of days has elapsed, documents old enough are removed along with their history.

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