Skip to main content

Update Compare-Exchange Item


Update compare-exchange item using a cluster-wide session

// The session must be opened in cluster-wide mode.
using (var session = store.OpenSession(
new SessionOptions { TransactionMode = TransactionMode.ClusterWide }))
{
// Get the existing item from the server
// =====================================

CompareExchangeValue<string> item = session.Advanced.ClusterTransaction
.GetCompareExchangeValue<string>("user1-name@example.com");

// The item is now tracked in the session's internal state
// Modify the value / metadata as needed
// =====================================

item.Value = "users/99";
item.Metadata["email-type"] = "work email";
item.Metadata["updated-at"] = DateTime.UtcNow.ToString("o");

// Save changes for the update to take effect
// ==========================================

session.SaveChanges();

// A 'ClusterTransactionConcurrencyException' is thrown if the compare-exchange item
// no longer exists on the server at the time of calling saveChanges().
// This can happen if another client deletes or modifies the item before your update is saved.
}

Update compare-exchange item using a store operation

  • Use PutCompareExchangeValueOperation to update the value and/or metadata of an existing compare-exchange item. This operation is also used to create new compare-exchange items, see Create compare-exchange item.

  • To perform an update, provide:

    • The existing key
    • A new value and/or metadata
    • The expected index (version) of the item, which must match the current version stored on the server.
  • The update will succeed only if the index you provide matches the current index stored on the server for that key. This ensures that the item hasn’t been modified by another client since you last read it.

  • If the index does not match, or if the specified key does not exist:

    • The item is not updated.
    • No exception is thrown.
    • The operation result has Successful = false.
  • If the update is successful:

    • The value and/or metadata are updated.
    • The server increments the index number of the item.
    • The operation result has Successful = true and will contain the new value and new index.
// Get the existing item from the server
// =====================================

CompareExchangeValue<string> item = store.Operations.Send(
new GetCompareExchangeValueOperation<string>("user1-name@example.com"));

// Modify the value / metadata as needed
// =====================================

var newValue = "users/99"; // Modify the value to be associated with the unique email key
var newMetadata = new MetadataAsDictionary
{
{ "email-type", "work email" },
{ "updated-at", DateTime.UtcNow.ToString("o") } // Add entries / modify the metadata
};

// Update the item
// ===============

// The put operation will succeed only if the 'index' of the compare-exchange item
// has not changed between the read and write operations.
CompareExchangeResult<string> putResult = store.Operations.Send(
new PutCompareExchangeValueOperation<string>(item.Key, newValue, item.Index, newMetadata));

// Check results
// =============

bool putResultSuccessful = putResult.Successful; // Has operation succeeded
long putResultIndex = putResult.Index; // The new version number assigned if update succeeded

Update compare-exchange item using the Studio

You can update any existing compare-exchange item from the Studio.

The compare-exchange view

  1. Go to Documents > Compare Exchange.
  2. Click to edit a compare-exchange item.

The compare-exchange view

  1. Enter the value.
  2. Enter the metadata (optional).
  3. Click Save to update the item.

Syntax

Method:

public PutCompareExchangeValueOperation(
string key, T value, long index, IMetadataDictionary metadata = null)
ParameterTypeDescription
keystringThe unique identifier in the database scope.
valueTThe value to be saved for the specified key.
Can be any object (number, string, array, or any valid JSON object).
indexlongThe current version of the item when updating an existing item.
Pass 0 to create a new key.
metadataIMetadataDictionaryMetadata to be saved for the specified key.
Must be a valid JSON object.

Returned object:

public class CompareExchangeResult<T>
{
public bool Successful;
public T Value;
public long Index;
}
Return ValueTypeDescription
Successfulbool
  • true if the put operation has completed successfully.
  • false if the put operation failed.
ValueT
  • Upon success - the value of the compare-exchange item that was saved.
  • Upon failure - the existing value on the server.
Indexlong
  • Upon success - the updated version (the incremented index of the modified item).
  • Upon failure (if indexes do not match) - the existing version from the server.