Document Expiration

Use the Expiration feature when data is needed only for a given time period.
E.g., for -

• 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

Documents expiration settings can be changed via Studio or the API.
It is possible to:

• Enable or Disable the deletion of expired documents.
  Default value: Disable the deletion of expired documents.
• Determine how often RavenDB would look for expired documents and delete them.
  Default value: 60 seconds
• Set the maximal number of documents that RavenDB is allowed to delete per interval.
  Default value: All expired documents

Configure expiration settings using the client API

Modify the expiration settings using the client API by setting an ExpirationConfiguration object and sending it to RavenDB using a ConfigureExpirationOperation operation.

Example:

await store.Maintenance.SendAsync(new ConfigureExpirationOperation(new ExpirationConfiguration
{
    Disabled = false,
    DeleteFrequencyInSec = 60,
    MaxItemsToProcess = 1000
}));

ExpirationConfiguration

public class ExpirationConfiguration
{
    // Set 'Disabled' to false to enable the deletion of expired items                    
    public bool Disabled { get; set; }

    // How frequently to delete expired items
    public long? DeleteFrequencyInSec { get; set; }

    // How many items to delete (per batch)
    public long? MaxItemsToProcess { get; set; }
}

• To set a document expiration time, add the document's @metadata an @expires property with the designated expiration time as a value.
  Set the time in UTC format, not local time. E.g. -
  "@expires": "2025-04-22T08:00:00.0000000Z"
  

  Metadata properties starting with @ are for internal RavenDB usage only.
  Do not use the metadata @expires property for any other purpose than scheduling a document's expiration time for the built-in expiration feature.
  

• If and when the expiration feature is enabled, it will process all documents carrying the @expires flag and automatically delete each document by its expiration time.
• To set the document expiration time from the client, use the following code:

  DateTime expiry = DateTime.UtcNow.AddMinutes(5);
  using (IAsyncDocumentSession session = store.OpenAsyncSession())
  {
      await session.StoreAsync(user);
      session.Advanced.GetMetadataFor(user)[Constants.Documents.Metadata.Expires] = expiry;
      await session.SaveChangesAsync();
  }

• Internally, RavenDB tracks all documents carrying the @expires flag even if the expiration feature is disabled. This way, once the expiration feature is enabled expired documents can be processed without delay.
• Once a document expires, it may take up to the delete frequency interval (60 seconds by default) until is it actually deleted.
• Deletion may be further delayed if MaxItemsToProcess is set, limiting the number of documents that RavenDB is allowed to delete each time the expiration feature is invoked.
• Expired documents are not filtered out during load, query, or indexing, so be aware that as long as an expired document hasn't been actually deleted it may still be included in the results.