Document time-to-live (TTL)

Reference: 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 transactions:

// First transaction.
// 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 transactions use the cursor and Set.paginate() to iterate through the remaining pages:

// Subsequent transactions.
// 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
}

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.

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!