Document Expiration

Use the Expiration feature when data is needed only for a given time period.

Examples:

• Shopping cart data that is kept only for a certain time period
• Email links that need to be expired after a few hours
• A web application login session details
• Cache data from an SQL server

• By default, the expiration feature is turned off.
• The deletion frequency is configurable.
  The default frequency is 60 seconds.
• The Expiration feature can be turned on or 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 document expiration time add an @expires property to the document @metadata and set the property's value to the designated expiration time.
  

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

  Metadata properties starting with @ are internal for RavenDB usage.
  Do not use metadata @expires property for any other usage but that of the built-in expiration feature.
  

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

  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 RavenDB can delete expired documents right away.
  

• To set the document expiration time from the client, use the following code:

  // 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 expire, it may take up to the delete frequency interval (60 seconds by default) until they are actually deleted.
• Expired documents are not filtered out during load, query, or indexing, so be aware that an expired document may still be included in the results after its expiration, for the period set by delete frequency interval.