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 Setting |
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 documentsttl
field is set according to thettl_days
value. -
When the
ttl
timestamp is passed, the document is removed, but its history continues to exist until the collectionhistory_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!