Temporality

Fauna documents are temporal, meaning that create, change, and delete events are assigned a transaction timestamp and inserted in the document history.

Temporality is a Fauna feature that allows you to query your database at a point in time. Working with documents temporally allows event sourcing, reactive programming, and various audit and stream-oriented data architectures.

Document history

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

Document or history removal

Temporal queries work as expected when document history exists. Note that 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, you should use one or more of the following features to remove document history or to remove documents and their history:

Document history removal

The history_days field defines the number of days of document history to maintain 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, a document that stores 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 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 that documents are updated in a collection, the more that 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 and history removal

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

This is particularly useful for intermediate documents involved in gathering report data. These documents must be retained during complex report preparation. After the report is generated, the documents are removed.

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

The ttl field behavior:

  • Queries using temporality 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, a new documents ttl field is 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.

The ttl_days field is a collection field, which is the number of days that documents in the collection should be retained. After the number of days elapses, documents whose age in days is greater are removed with their history.

This feature can be useful for documents that must exist for short intervals, and you want to avoid executing maintenance queries to remove the documents.

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!