Compare-Exchange Expiration

• Compare-exchange items can be set to be deleted automatically in a future time.

• To schedule expiration for a compare-exchange item, set the @expires field in the item's metadata.
  This can be done when creating a new item or updating an existing one.

• RavenDB scans the database periodically to remove expired items. Any compare-exchange item whose @expires timestamp has passed at the time of the scan will be automatically removed.

• The scan frequency is configurable -
  see the Cluster.CompareExchangeExpiredDeleteFrequencyInSec configuration key. The default is 60 seconds.

• To manually remove a compare-exchange item, see Delete compare-exchange items.

• Note: The compare-exchange expiration feature is not related to document expiration.
  You do NOT need to enable document expiration in order to use compare-exchange expiration.

---

• In this article:
  • Add expiration date using the Client API
  • Add expiration date using the Studio
  • Syntax

---

Add expiration date using the Client API

• Cluster_wide_session
• Cluster_wide_session_async
• Store_operation
• Store_operation_async

// The session must be opened in cluster-wide mode
using (var session = store.OpenSession(
    new SessionOptions { TransactionMode = TransactionMode.ClusterWide }))
{
     // Call 'CreateCompareExchangeValue', specify the item's KEY and VALUE  
     CompareExchangeValue<string> item = 
         session.Advanced.ClusterTransaction.CreateCompareExchangeValue(
             key: "user1-name@example.com",
             value: "users/1" 
     );
     
     // Add METADATA fields to the item
     // Set a future UTC DateTime in the `@expires` field to schedule expiration
     // "Constants.Documents.Metadata.Expires" = "@expires"  
     item.Metadata[Constants.Documents.Metadata.Expires] = DateTime.UtcNow.AddDays(7); 

     // The item will be created on the server once 'SaveChanges' is called
     session.SaveChanges();
}

// The session must be opened in cluster-wide mode
using (var asyncSession = store.OpenAsyncSession(
    new SessionOptions { TransactionMode = TransactionMode.ClusterWide }))
{
     // Call 'CreateCompareExchangeValue', specify the item's KEY and VALUE  
     CompareExchangeValue<string> item = 
         asyncSession.Advanced.ClusterTransaction.CreateCompareExchangeValue(
             key: "user1-name@example.com",
             value: "users/1" 
     );
     
     // Add METADATA fields to the item
     // Set a future UTC DateTime in the `@expires` field to schedule expiration
     // "Constants.Documents.Metadata.Expires" = "@expires"  
     item.Metadata[Constants.Documents.Metadata.Expires] = DateTime.UtcNow.AddDays(7); 

     // The item will be created on the server once 'SaveChangesAsync' is called
     await asyncSession.SaveChangesAsync();
}

// Define the metadata with the future expiration date
var metadata = new MetadataAsDictionary
{
     // Constants.Documents.Metadata.Expires = "@expires"
     // Specify the expiration time (UTC) in ISO 8601 format  
     { Constants.Documents.Metadata.Expires, DateTime.UtcNow.AddDays(7).ToString("o") }
};

// Pass the metadata when creating the item
var putCmpXchgOp = new PutCompareExchangeValueOperation<string>(
    "user1-name@example.com", "users/1", 0, metadata);

// Execute the operation
CompareExchangeResult<string> putResult = store.Operations.Send(putCmpXchgOp);

// Define the metadata with the future expiration date
var metadata = new MetadataAsDictionary
{
     // Constants.Documents.Metadata.Expires = "@expires"
     // Specify the expiration time (UTC) in ISO 8601 format
     { Constants.Documents.Metadata.Expires, DateTime.UtcNow.AddDays(7).ToString("o") }
};

// Pass the metadata when creating the item
var putCmpXchgOp = new PutCompareExchangeValueOperation<string>(
    "user1-name@example.com", "users/1", 0, metadata);

// Execute the operation
CompareExchangeResult<string> putResult = await store.Operations.SendAsync(putCmpXchgOp);

---

Add expiration date using the Studio

• You can set or update the expiration date of a compare-exchange item directly from the Studio.

• Go to Documents > Compare Exchange.
  Edit an existing item or create a new one.
  In the item's metadata, set the @expires field to a future UTC date/time (ISO 8601 format).

---

Syntax

• The syntax for creating a compare-exchange item is available in Create compare-exchange item - Syntax
• The syntax for updating a compare-exchange item is available in Update compare-exchange item - Syntax