Document history

Fauna stores snapshots of each document’s history. Fauna creates these snapshots each time the document receives a write. Fauna indexes also store the history of index terms or values field values.

The historical snapshots act as versions of a document. You can use the snapshots to get a point-in-time view of documents and audit changes.

Run a temporal query

Reference: at expression

You can use an at expression to run a query on the snapshot of one or more documents. This is called a temporal query.

For example, the following query retrieves a snapshot of a document from yesterday:

let yesterday = Time.now().subtract(1, "day")
at (yesterday) { Product.byName("avocados").first() }

If available, Fauna returns the document at the time of the at expression.

History retention

Reference: FSL collection schema

A collection schema's history_days setting defines the number of days of history to retain as document snapshots:

collection Customer {
  ...
  // Number of days of document history to retain.
  history_days 3
}

After history_days passes, snapshots before the related time are deleted and become inaccessible.

history_days also affects events available for event feeds and event streams. See event feeds and event streams.

Minimum viable timestamp (MVT)

The minimum viable timestamp (MVT) is the earliest point in time that you can query a collection’s document history. The MVT is calculated as the query timestamp minus the collection’s history_days setting:

MVT = query timestamp - collection's `history_days`

Temporal queries using an at expression can’t access document snapshots that are older than the MVT. Any query that attempts to access a document snapshot before the MVT returns an error with the invalid_request error code and a 400 HTTP status code:

{
  "code": "invalid_request",
  "message": "Requested timestamp 2099-01-09T00:36:53.334372Z less than minimum allowed timestamp 2099-01-10T00:21:53.334372Z."
}

For example, if a collection has history_days set to 3 and you run a query that attempts to access a document in the collection from 4 days ago, the query returns an error.

Default history days

If omitted or unset, history_days defaults to 0, which only retains the current version of each document. No history is retained.

If history_days is 0 or unset, the replay period for events in event feeds and event streams is limited to 15 minutes.

Decreasing history days

If you decrease history_days, any snapshots created before the new history_days setting are deleted and become inaccessible.

Increasing history days

Increasing history_days does not recreate or recover previously inaccessible snapshots.

For example, increasing history_days from 0 to 7 does not recreate historical snapshots for the last 7 days. Instead, Fauna begins storing snapshots beginning at the time of the schema update.

Impacts on read ops, storage, latency, and indexing

Avoid storing unnecessary history. A high history_days setting has several impacts:

Increased read ops:

To support temporal queries, indexes cover field values from both current documents and their historical document snapshots.

To enable quicker sorting and range searches, current and historical index entries are stored together, sorted by index values. All indexes implicitly include an ascending document id as the index’s last value.

When you read data from an index, including the collection.all() index, Fauna must read from both current and historical index entries to determine if they apply to the query. Fauna then filters out any data not returned by the query.

You are charged for any Transactional Read Operations (TROs) used to read current or historical index data, including data not returned by the query.

You are not charged for any historical data older than the retention period set by the history_days setting.
Longer index build times: Because indexes include historical data, a high history_days setting can increase the index build times.
Increased query latency on indexes: If an indexed field value changes frequently, the index must retain more historical data. A high history_days setting can increase query latency on the index.
Increased storage: More document snapshots and historical index data is retained, consuming additional database storage and increasing storage costs.