Update Compare-Exchange Item
-
An existing compare-exchange item can be updated in the following ways:
- Using a cluster-wide session
- Using a store operation
- Using the Studio
-
In this article:
Update compare-exchange item using a cluster-wide session
- Update_using_session
- Update_using_session_async
// 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.
}
// The session must be opened in cluster-wide mode.
using (var asyncSession = store.OpenAsyncSession(
new SessionOptions { TransactionMode = TransactionMode.ClusterWide }))
{
// Get the existing item from the server
// =====================================
CompareExchangeValue<string> item = await asyncSession.Advanced.ClusterTransaction
.GetCompareExchangeValueAsync<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
// ==========================================
await asyncSession.SaveChangesAsync();
}
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.
- Update_operation
- Update_operation_async
// 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
// Get the existing item from the server
// =====================================
CompareExchangeValue<string> item = await store.Operations.SendAsync(
new GetCompareExchangeValueOperation<string>("user1-name@example.com"));
// Modify the value / metadata as needed
// =====================================
var newValue = "users/99"; // Modify the value 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 = await store.Operations.SendAsync(
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.
- Go to Documents > Compare Exchange.
- Click to edit a compare-exchange item.
- Enter the value.
- Enter the metadata (optional).
- Click Save to update the item.
Syntax
Method:
public PutCompareExchangeValueOperation(
string key, T value, long index, IMetadataDictionary metadata = null)
Parameter | Type | Description |
---|---|---|
key | string | The unique identifier in the database scope. |
value | T | The value to be saved for the specified key. Can be any object (number, string, array, or any valid JSON object). |
index | long | The current version of the item when updating an existing item. Pass 0 to create a new key. |
metadata | IMetadataDictionary | Metadata 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 Value | Type | Description |
---|---|---|
Successful | bool |
|
Value | T |
|
Index | long |
|