Check out v4 of the Fauna CLI

v4 of the Fauna CLI is now in beta.

The new version introduces enhancements to the developer experience, including an improved authentication workflow. To get started, check out the CLI v4 quick start.

Document time-to-live (TTL)

Reference: FSL collection schema

A document can include an optional ttl (time-to-live) metadata field that contains the document’s expiration timestamp:

Customer.create({
 name: "John Doe",
 email: "jdoe@example.com",
  address: {
    street: "87856 Mendota Court",
    city: "Washington",
    state: "DC",
    postalCode: "20220",
    country: "US"
  },
  // Sets a `ttl` 60 days after the current time.
  // After the `ttl` passes, Fauna deletes the document.
  ttl: Time.now().add(60, "days")
})

After the ttl timestamp passes, Fauna permanently deletes the document. Use the ttl field to automatically expire documents and control data retention.

Documents without a ttl or a ttl of null persist indefinitely.

Enable or disable TTL writes

A collection schema’s document_ttls field controls whether you can write to the ttl field of collection documents:

collection Customer {
  ...
  // Explicitly set `document_ttls` to `true`
  document_ttls true
  ...
}

If the collection schema contains field definitions, document_ttls defaults to false. Otherwise, document_ttls defaults to true.

document_ttls does not affect:

  • An existing document’s ttl. Fauna deletes documents based on their ttl, even if document_ttls is false.

  • The collection schema’s ttl_days field. If set, ttl_days assigns a ttl based on the document’s last write, even if document_ttls is false.

Set a default TTL

A collection schema’s ttl_days field sets a default ttl for collection documents:

collection Customer {
  ...
  // Set default document `ttl` to 365 days after
  // the last write.
  ttl_days 365
  ...
}

When ttl_days is set, new and updated collection documents are assigned a ttl based on the ttl_days value, in days, since the last document write.

For example, if ttl_days is set to 30, each document is assigned a ttl of 30 days after its most recent update.

You can overwrite the default by assigning an explicit ttl.

Set a default TTL for existing documents

Changing ttl_days on an existing collection does not affect the ttl of existing, unchanged documents.

To explicitly set the ttl of all collection documents, use set.pageSize() and set.paginate() to iterate through the collection over several queries:

// First query.
// Gets `Customer` collection documents with a `ttl`
// of `null` (unset). Use `pageSize()`
// and`paginate()` to paginate results and
// limit each page to 20 documents.
let page = Customer.all()
  .where(.ttl == null)
  .pageSize(20).paginate()

let data = page.data

data.forEach(document => document.update({
  // Set `ttl` as the document timestamp (`ts`) + 365 days.
  ttl: document.ts.add(365, "days")
}))

page {
  after
}
{
  after: "hdW..."
}

Subsequent queries use the cursor and Set.paginate() to iterate through the remaining pages:

// Subsequent queries.
// Uses `Set.paginate()` to iterate through
// subsequent pages.
let page = Set.paginate("hdW...")

let data = page.data

data.forEach(document => document.update({
  ttl: document.ts.add(365, "days")
}))

page {
  after
}

Set a default ttl using field definitions

ttl is a reserved field. You can’t use field definitions to set a default ttl for new documents. To set a default ttl, use ttl_days or use your client application to set the default in document creation queries.

You can check constraint to ensure documents have a ttl and enforce a ttl policy. See Enforce TTL policies with check constraints.

Enforce TTL policies with check constraints

You can use a check constraint to ensure a ttl is set in new and updated documents:

collection Product {
  ...
  // Check constraint.
  // Requires that documents contain a `ttl`.
  check ttlPolicy (.ttl != null)
  ...
}

You can also ensure ttl values meet a pre-defined rule. For example:

collection Product {
  ...
  // Check constraint. Ensures the `ttl` of `Product`
  // documents is no more than 30 days from the current date.
  // Requires that documents contain a `ttl`.
  check ttlPolicy (.ttl?.difference(Time.now(), 'days') <= 30)
  ...
}

To enforce a similar rule but make ttl optional:

collection Product {
  ...
  // Check constraint. Ensures the `ttl` of `Product`
  // documents is no more than 30 days from the current date.
  // Requires that documents contain a `ttl`.
  check ttlPolicy (
    .ttl == null || .ttl?.difference(Time.now(), 'days') <= 30
  )
  ...
}

TTL and document history

When a document’s ttl timestamp passes, Fauna only deletes the latest version of the document. Historical snapshots of the document are still available using the at expression.

You can control the retention of historical snapshots using the collection schema’s history_days field.

TTL and event sources

Event sources don’t emit remove events for documents deleted due to an expired TTL. Such documents are deleted lazily upon expiration.

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!