Compare Exchange Overview

Compare Exchange items are key/value pairs where the key servers a unique value across your database.

• Each compare-exchange item contains:

  • A key - A unique string identifier in the database scope.
  • A value - Can be any object (a number, string, array, or any valid JSON object).
  • Metadata - Data that is associated with the compare-exchange item. Must be a valid JSON object.
    • For example, the metadata can be used to set expiration time for the compare-exchange item.
      Learn more in compare-exchange expiration.
  • Raft index - The compare-exchange item's version.
    Any change to the value or metadata will increase this number.

• Creating and modifying a compare-exchange item is an atomic, thread-safe compare-and-swap interlocked compare-exchange operation.

Compare exchange items are created and managed with any of the following approaches:

• Document Store Operations
  You can manage a compare-exchange item as an Operation on the document store.
  This can be done within or outside of a session (cluster-wide or single-node session).

  • When inside a session:
    If the session fails, the compare-exchange operation can still succeed because store Operations do not rely on the success of the session.
    You will need to delete the compare-exchange item explicitly upon session failure if you don't want the compare-exchange item to persist.

• Cluster-Wide Sessions
  You can manage a compare-exchange item from inside a Cluster-Wide session.
  If the session fails, the compare-exchange item creation also fails.
  None of the nodes in the group will have the new compare-exchange item.

• Atomic Guards
  When creating documents using a cluster-wide session RavenDB automatically creates Atomic Guards,
  which are compare-exchange items that guarantee ACID transactions.
  See Cluster-wide vs. Single-node for a session comparision overview.

• Studio
  Compare-exchange items can be created from the Studio as well.

• Each cluster defines its policies and configurations, and should ideally have sole responsibility for managing its own documents. Read Consistency in a Globally Distributed System to learn more about why global database modeling is more efficient this way.

• When creating a compare-exchange item a Raft consensus is required from the nodes in the database group. Externally replicating such data is problematic as the target database may reside within a cluster that is in an unstable state where Raft decisions cannot be made. In such a state, the compare-exchange item will not be persisted in the target database.

• Conflicts between documents that occur between two databases are solved with the help of the documents Change-Vector. Compare-exchange conflicts cannot be handled properly as they do not have a similar mechanism to resolve conflicts.

• To ensure unique values between two databases without using compare-exchange items see Example III.

The following example shows how to use compare-exchange to create documents with unique values.
The scope is within the database group on a single cluster.

Compare-exchange items are not externally replicated to other databases.
To establish uniqueness without using compare-exchange see Example III.

string email = "user@example.com";

User user = new User
{
    Email = email
};

using (IDocumentSession session = store.OpenSession())
{
    session.Store(user);
    // At this point, the user document has an Id assigned

    // Try to reserve a new user email 
    // Note: This operation takes place outside of the session transaction, 
    //       It is a cluster-wide reservation
    CompareExchangeResult<string> cmpXchgResult
        = store.Operations.Send(
            new PutCompareExchangeValueOperation<string>("emails/" + email, user.Id, 0));

    if (cmpXchgResult.Successful == false)
        throw new Exception("Email is already in use");

    // At this point we managed to reserve/save the user email -
    // The document can be saved in SaveChanges
    session.SaveChanges();
}

Implications:

• The User object is saved as a document, hence it can be indexed, queried, etc.

• This compare-exchange item was created as an operation rather than with a cluster-wide session.
  Thus, if session.SaveChanges fails, then the email reservation is not rolled back automatically.
  It is your responsibility to do so.

• The compare-exchange value that was saved can be accessed in a query using CmpXchg:
  

  • Query-LINQ
  • Document-Query
  • RQL

  var query = from u in session.Query<User>()
              where u.Id == RavenQuery.CmpXchg<string>("emails/ayende@ayende.com")
              select u;

  var q = session.Advanced
      .DocumentQuery<User>()
      .WhereEquals("Id", CmpXchg.Value("emails/ayende@ayende.com"));

  from Users as s where id() == cmpxchg("emails/ayende@ayende.com")

In the following example, we use compare-exchange to reserve a shared resource.
The scope is within the database group on a single cluster.

The code also checks for clients who never release resources (i.e. due to failure) by using timeout.

private class SharedResource
{
    public DateTime? ReservedUntil { get; set; }
}

public void PrintWork() 
{
    // Try to get hold of the printer resource
    long reservationIndex = LockResource(store, "Printer/First-Floor", TimeSpan.FromMinutes(20));

    try
    {
        // Do some work for the duration that was set.
        // Don't exceed the duration, otherwise resource is available for someone else.
    }
    finally
    {
        ReleaseResource(store, "Printer/First-Floor", reservationIndex);
    }
}

public long LockResource(IDocumentStore store, string resourceName, TimeSpan duration)
{
    while (true)
    {
        DateTime now = DateTime.UtcNow;

        SharedResource resource = new SharedResource
        {
            ReservedUntil = now.Add(duration)
        };

        CompareExchangeResult<SharedResource> saveResult = store.Operations.Send(
                new PutCompareExchangeValueOperation<SharedResource>(resourceName, resource, 0));

        if (saveResult.Successful)
        {
            // resourceName wasn't present - we managed to reserve
            return saveResult.Index;
        }

        // At this point, Put operation failed - someone else owns the lock or lock time expired
        if (saveResult.Value.ReservedUntil < now)
        {
            // Time expired - Update the existing key with the new value
            CompareExchangeResult<SharedResource> takeLockWithTimeoutResult = store.Operations.Send(
                new PutCompareExchangeValueOperation<SharedResource>(resourceName, resource, saveResult.Index));

            if (takeLockWithTimeoutResult.Successful)
            {
                return takeLockWithTimeoutResult.Index;
            }
        }

        // Wait a little bit and retry
        Thread.Sleep(20);
    }
}

public void ReleaseResource(IDocumentStore store, string resourceName, long index)
{
    CompareExchangeResult<SharedResource> deleteResult
        = store.Operations.Send(new DeleteCompareExchangeValueOperation<SharedResource>(resourceName, index));

    // We have 2 options here:
    // deleteResult.Successful is true - we managed to release resource
    // deleteResult.Successful is false - someone else took the lock due to timeout 
}

Unique values can also be ensured without using compare-exchange.

The below example shows how to achieve that by using reference documents.
The reference documents' IDs will contain the unique values instead of the compare-exchange items.

Using reference documents is especially useful when External Replication is defined between two databases that need to be synced with unique values.
The reference documents will replicate to the destination database, as opposed to compare-exchange items, which are not externally replicated.

// When you create documents that must contain a unique value such as a phone or email, etc.,
// you can create reference documents that will have that unique value in their IDs.
// To know if a value already exists, all you need to do is check whether a reference document with such ID exists.

// The reference document class
class UniquePhoneReference
{
    public class PhoneReference
    {
        public string Id;
        public string CompanyId;
    }

    static void Main(string[] args)
    {
        // A company document class that must be created with a unique 'Phone' field
        Company newCompany = new Company
        {
            Name = "companyName",
            Phone = "phoneNumber",
            Contact = new Contact
            {
                Name = "contactName",
                Title = "contactTitle"
            },
        };

        void CreateCompanyWithUniquePhone(Company newCompany)
        {
            // Open a cluster-wide session in your document store
            using var session = DocumentStoreHolder.Store.OpenSession(
                    new SessionOptions { TransactionMode = TransactionMode.ClusterWide }
                );

            // Check whether the new company phone already exists
            // by checking if there is already a reference document that has the new phone in its ID.
            var phoneRefDocument = session.Load<PhoneReference>("phones/" + newCompany.Phone);
            if (phoneRefDocument != null)
            {
                var msg = $"Phone '{newCompany.Phone}' already exists in ID: {phoneRefDocument.CompanyId}";
                throw new ConcurrencyException(msg);
            }

            // If the new phone number doesn't already exist, store the new entity
            session.Store(newCompany);
            // Store a new reference document with the new phone value in its ID for future checks.
            session.Store(new PhoneReference { CompanyId = newCompany.Id }, "phones/" + newCompany.Phone);

            // May fail if called concurrently with the same phone number
            session.SaveChanges();
        }
    }
}