Skip to main content

Delete Compare-Exchange Items

  • Custom compare-exchange items can be deleted:
    You can delete your own custom compare-exchange items. An item is deleted only if the index you provide in the request matches the current index stored on the server for the specified key.

  • Delete items by expiration:
    Compare-exchange items can also be deleted by adding an expiration date to them.
    Learn more in Compare-exchange expiration.

  • Compare-exchange tombstones:
    Whenever a compare-exchange item is deleted, a compare-exchange tombstone is created for it.
    These tombstones are used to indicate to other RavenDB processes that the compare-exchange item was deleted,
    so they can react accordingly.
    For example, indexes referencing the deleted item will update themselves to remove those references.
    Compare-exchange tombstones that are eligible for deletion are removed periodically by an internal cleanup task.
    See: Cluster.CompareExchangeTombstonesCleanupIntervalInMin.

  • Do NOT attempt to delete atomic guards, which RavenDB uses internally to ensure ACID guarantees in cluster-wide transactions. These compare-exchange items are created automatically and must not be modified or removed.

    If your custom compare-exchange item was set up to protect the consistency of a transaction, deleting it will break the ACID guarantees. Only delete or modify such items if you truly know what you're doing.

Delete compare-exchange item using a cluster-wide session​

  • Delete compare-exchange items using a cluster-wide session when you want the deletion to be part of a transaction committed via SaveChanges(). This is suitable if you want to include compare-exchange deletions alongside other operations, such as putting or deleting documents and compare-exchange items, in a single transaction.
    Learn more about cluster-wide sessions in Cluster transactions - overview.

  • Use DeleteCompareExchangeValue() to register the deletion of an existing compare-exchange item in the session.
    The item will be deleted as part of the cluster-wide transaction when SaveChanges() is called.

  • If the item's index (its version) on the server is different from the index you provide, SaveChanges() will throw a ClusterTransactionConcurrencyException. This means the item was modified by another operation after it was loaded into the session, and the entire transaction will be rejected.

  • Examples:

    Delete by item​

    // The session must be opened in cluster-wide mode.
    // An `InvalidOperationException` is thrown if the session is not opened in cluster-wide mode.  
    using (var session = store.OpenSession(
        new SessionOptions { TransactionMode = TransactionMode.ClusterWide }))
    {
        // Get the latest version of the existing compare-exchange item to be deleted.
        CompareExchangeValue<string> itemToDelete = session.Advanced.ClusterTransaction
            .GetCompareExchangeValue<string>("user1-name@example.com");
        
        if (itemToDelete != null)
        {
            // Call 'DeleteCompareExchangeValue' to register the deletion as part of the cluster-wide
            // transaction. Pass the item to delete.
            session.Advanced.ClusterTransaction.DeleteCompareExchangeValue(itemToDelete);
            
            // Commit the cluster-wide transaction. This will delete the compare-exchange item,
            // or throw a 'ClusterTransactionConcurrencyException' if the item's index (its version)
            // on the server is different than the one provided in the delete request.
            session.SaveChanges();
        }
    }

    Delete by key and index​

    // The session must be opened in cluster-wide mode.
    // An `InvalidOperationException` is thrown if the session is not opened in cluster-wide mode.  
    using (var session = store.OpenSession(
        new SessionOptions { TransactionMode = TransactionMode.ClusterWide }))
    {
        // Get the latest version of the existing compare-exchange item to be deleted.
        CompareExchangeValue<string> itemToDelete = session.Advanced.ClusterTransaction
            .GetCompareExchangeValue<string>("user1-name@example.com");
        
        if (itemToDelete != null)
        {
            // Call 'DeleteCompareExchangeValue' to register the deletion as part of the cluster-wide
            // transaction. Specify the item's KEY and current INDEX (its version).
            session.Advanced.ClusterTransaction.DeleteCompareExchangeValue(
                itemToDelete.Key, itemToDelete.Index);
            
            // Commit the cluster-wide transaction. This will delete the compare-exchange item,
            // or throw a 'ClusterTransactionConcurrencyException' if the item's index (its version)
            // on the server is different than the one provided in the delete request.
            session.SaveChanges();
        }
    }

    Delete multiple items​

    // The session must be opened in cluster-wide mode  
    using (var session = store.OpenSession(
        new SessionOptions { TransactionMode = TransactionMode.ClusterWide }))
    {
        // Get the latest version of the items to be deleted.        
        CompareExchangeValue<string> itemToDelete1 = session.Advanced.ClusterTransaction
            .GetCompareExchangeValue<string>("user1-name@example.com");
        CompareExchangeValue<string> itemToDelete2 = session.Advanced.ClusterTransaction
            .GetCompareExchangeValue<string>("user2-name@example.com");
        CompareExchangeValue<string> itemToDelete3 = session.Advanced.ClusterTransaction
            .GetCompareExchangeValue<string>("user3-name@example.com");
        
        // You can delete multiple compare-exchange items before calling 'SaveChanges'.
        // Call 'DeleteCompareExchangeValue' for each item you want to delete in the transaction.
        session.Advanced.ClusterTransaction.DeleteCompareExchangeValue(itemToDelete1);
        session.Advanced.ClusterTransaction.DeleteCompareExchangeValue(itemToDelete2);
        session.Advanced.ClusterTransaction.DeleteCompareExchangeValue(itemToDelete3);
      
        // All items will be deleted atomically as part of the same transaction. 
        // If any deletion fails, the entire transaction is rolled back
        // and none of the items will be deleted.  
        session.SaveChanges();
    }

Delete compare-exchange item using a store operation​

  • Use the DeleteCompareExchangeValueOperation store operation to delete a compare-exchange item by its key and index, without opening a session. This is ideal for stand-alone tasks that don't require batching multiple commands into a single transactional session.

  • The delete operation will only succeed if the item's current index on the server is the same as the one you provide.
    If the indexes do not match, the item is not deleted and no exception is thrown.

  • Examples:

    // Get the latest version of the existing compare-exchange item to be deleted
    var getCmpXchgOp = new GetCompareExchangeValueOperation<string>("user1-name@example.com");
    CompareExchangeValue<string> itemToDelete = store.Operations.Send(getCmpXchgOp);

    if (itemToDelete != null)
    {
        // Define the delete compare-exchange operation 
        // Pass the item's KEY and INDEX (its version)
        var deleteCmpXchgOp = new DeleteCompareExchangeValueOperation<string>(
            itemToDelete.Key, itemToDelete.Index);
        
        // Execute the delete operation by passing it to Operations.Send
        CompareExchangeResult<string> resultOfDelete = store.Operations.Send(deleteCmpXchgOp);
        
        // Check results
        bool successful = resultOfDelete.Successful; // Has operation succeeded
        long indexOfItem = resultOfDelete.Index;     // The version of the deleted item
        
        // If 'successful' is true - the compare-exchange item was deleted.
        // If 'successful' is false - the item was not deleted (index mismatch).
    }

Delete compare-exchange items using the Studio​

You can delete one or multiple compare-exchange items from the Studio.

The compare-exchange view

  1. Go to Documents > Compare Exchange.
  2. Select the compare-exchange items you want to delete.
  3. Click Delete.

Syntax​

DeleteCompareExchangeValueOperation​

Delete compare-exchange item using a store operation:

public DeleteCompareExchangeValueOperation(string key, long index)
ParameterTypeDescription
keystringThe unique key of the compare-exchange item.
indexlongThe current version of the item.
Deletion will only succeed if this matches the version stored on the server.

Returned object:

public class CompareExchangeResult<T>
{
    public bool Successful;
    public T Value;
    public long Index;
}
Return ValueTypeDescription
Successfulbool
  • true if the delete operation completed successfully.
  • true if key doesn't exist
  • false if the delete operation has failed, e.g. when the index version doesn't match.
ValueT
  • The value that was deleted upon a successful delete.
  • null if key doesn't exist
  • The currently existing value on the server if the delete operation has failed.
Indexlong
  • The next available version number upon success.
  • The next available version number if key doesn't exist.
  • The currently existing index on the server if the delete operation has failed.

DeleteCompareExchangeValue​

Delete compare-exchange item using cluster-wide session:

// Available overloads:
void DeleteCompareExchangeValue<T>(CompareExchangeValue<T> item);
void DeleteCompareExchangeValue(string key, long index);
ParameterTypeDescription
itemCompareExchangeValue<T>The compare-exchange item to delete.
keystringThe unique key of the compare-exchange item.
indexlongThe current version of the item.
Deletion will only succeed if this matches the version stored on the server.