Document Expiration

• Use the Expiration feature when data is needed to be kept for only a temporary time.

• Examples:

  • Shopping cart data that is kept for only a specific time
  • Email links that need to be expired after a few hours
  • Storing a web application login session details
  • When using RavenDB to hold cache data from a SQL server.
    

• By default, the expiration feature is turned off.

• The delete frequency is configurable, the default value is 60 secs.

• The Expiration feature can be turned on and off using Studio, see Setting Document Expiration in Studio.

• The Expiration feature can also be configured using the Client:

// Enable document expiration and set the frequency to 50 seconds:
// ===============================================================

// Define the expiration configuration object 
const expirationConfiguration = {
    disabled: false,           // Enable expiration
    deleteFrequencyInSec: 50   // Set frequency to 50 seconds
};

// Define the configure expiration operation,
// pass the configuration to set
const configureExpirationOp = new ConfigureExpirationOperation(expirationConfiguration);

// Execute the operation by passing it to maintenance.send
await store.maintenance.send(configureExpirationOp);

• To set the document expiration time just add the @expires property to the document @metadata and set it to contain the appropriate expiration time.

• Once the Expiration feature is enabled, the document will automatically be deleted at the specified time.

• Note: The date must be in UTC format, not local time.

• The document expiration time can be set using the following code from the client:

// Setting a new document to expire after 5 minutes:
// =================================================

// Create a new document
const newEmployee = new Employee();
newEmployee.lastName = "Smith";

const session = documentStore.openSession();
await session.store(newEmployee);

// Get the metadata of the document
const metadata = session.advanced.getMetadataFor(newEmployee);

// Set the '@expires' metadata property with the expiration date in UTC format
const expiresAt = new Date(new Date().getTime() + (5 * 60_000))
metadata[CONSTANTS.Documents.Metadata.EXPIRES] = expiresAt.toISOString();

// Save the new document to the database
await session.saveChanges();

• Once documents are expired, it can take up to the delete frequency interval (60 seconds by default) until these expired documents are actually deleted.

• Expired documents are not filtered on load/query/indexing time, so be aware that an expired document might still be there after it has expired up to the 'delete frequency interval' timeframe.
  

• Internally, each document that has the @expires property in the metadata is tracked by the RavenDB server
  even if the expiration feature is turned off.
  This way, once the expiration feature is turned on we can easily delete all the expired documents.

• Note: Metadata properties starting with @ are internal for RavenDB usage.
  You should not use the @expires property in the metadata for any other purpose other than the built-in expiration feature.