Document Expiration



Expiration feature usages

  • 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.

Configuring the expiration feature

  • 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:

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

Setting the document expiration time

  • 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:

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();
}

Eventual consistency considerations

  • 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.

More details

  • 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.