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 get a 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: Collection schema

A collection schema's history_days field 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. Temporal queries that attempt to access snapshots older than history_days return an error.

Default history days

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

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 storage, latency, and indexing

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

  • Increased storage: More document snapshots are retained, consuming additional database storage and storage costs.

  • Longer index build times: Indexes cover both live and 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.

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!