Get Compare-Exchange Item
-
To retrieve an existing compare-exchange item using the Client API,
use either a store operation or a cluster-wide session - as described below.
A cluster-wide session also supports lazy retrieval. -
To view existing compare-exchange items in the Studio, go to Documents > Compare Exchange,
as described in Ways to manage compare-exchange items. -
This article shows how to get a single compare-exchange item by its unique key.
To get multiple items at once, see Get multiple compare-exchange items. -
In this article:
Get item using a cluster-wide session
-
You can retrieve compare-exchange items using a cluster-wide session.
The session must be opened in cluster-wide mode. -
Use the
GetCompareExchangeValue
advanced session method to get a compare-exchange item by its key.
If the specified key does not exist, the method returnsnull
. No exception is thrown. -
Once a compare-exchange item is retrieved using a cluster-wide session, the item is tracked by the session.
Repeating the sameGetCompareExchangeValue
call with the same key does not send another request to the server,
the value is returned from the session's internal state.
To force a re-fetch from the server, callsession.Advanced.Clear()
first. -
Examples:
Get compare-exchange item
- Cluster_wide_session
- Cluster_wide_session_async
// First, let's create a compare-exchange item for the example,
// e.g. store a user's email as the key and the user document id as the value.
using (var session = store.OpenSession(
new SessionOptions { TransactionMode = TransactionMode.ClusterWide }))
{
CompareExchangeValue<string> itemToCreate =
session.Advanced.ClusterTransaction.CreateCompareExchangeValue(
key: "user1-name@example.com",
value: "users/1"
);
// Optionally, add some metadata:
itemToCreate.Metadata["email-type"] = "work email";
session.SaveChanges();
}
using (var session = store.OpenSession(
new SessionOptions { TransactionMode = TransactionMode.ClusterWide }))
{
// Get the compare-exchange item:
// ==============================
CompareExchangeValue<string> retrievedItem = session.Advanced.ClusterTransaction
.GetCompareExchangeValue<string>("user1-name@example.com");
if (retrievedItem != null)
{
// Access the VALUE of the retrieved item
var userDocumentId = retrievedItem.Value; // "users/1"
// Access the METADATA of the retrieved item
var emailType = retrievedItem.Metadata["email-type"]; // "work email"
// Access the VERSION number of the retrieved item
var version = retrievedItem.Index;
}
else
{
Console.WriteLine("Compare-exchange item not found");
}
}// First, let's create a compare-exchange item for the example,
// e.g. store a user's email as the key and the user document id as the value.
using (var asyncSession = store.OpenAsyncSession(
new SessionOptions { TransactionMode = TransactionMode.ClusterWide }))
{
CompareExchangeValue<string> itemToCreate =
asyncSession.Advanced.ClusterTransaction.CreateCompareExchangeValue(
key: "user1-name@example.com",
value: "users/1"
);
// Optionally, add some metadata:
itemToCreate.Metadata["email-type"] = "work email";
await asyncSession.SaveChangesAsync();
}
using (var asyncSession = store.OpenAsyncSession(
new SessionOptions { TransactionMode = TransactionMode.ClusterWide }))
{
// Get the compare-exchange item:
// ==============================
CompareExchangeValue<string> retrievedItem = await asyncSession.Advanced.ClusterTransaction
.GetCompareExchangeValueAsync<string>("user1-name@example.com");
if (retrievedItem != null)
{
// Access the VALUE of the retrieved item
var userDocumentId = retrievedItem.Value; // "users/1"
// Access the METADATA of the retrieved item
var emailType = retrievedItem.Metadata["email-type"]; // "work email"
// Access the VERSION number of the retrieved item
var version = retrievedItem.Index;
}
else
{
Console.WriteLine("Compare-exchange item not found");
}
}Get compare-exchange item lazily
- Cluster_wide_session
- Cluster_wide_session_async
// Create a compare-exchange item for the example:
using (var session = store.OpenSession(
new SessionOptions { TransactionMode = TransactionMode.ClusterWide }))
{
CompareExchangeValue<string> itemToCreate =
session.Advanced.ClusterTransaction.CreateCompareExchangeValue(
key: "user1-name@example.com",
value: "users/1"
);
session.SaveChanges();
}
using (var session = store.OpenSession(
new SessionOptions { TransactionMode = TransactionMode.ClusterWide }))
{
// Get the compare-exchange item lazily:
// =====================================
var lazyItem = session.Advanced.ClusterTransaction.Lazily
.GetCompareExchangeValue<string>("user1-name@example.com");
// Access the item:
CompareExchangeValue<string> retrievedItem = lazyItem.Value;
if (retrievedItem != null) {
// Access the VALUE of the retrieved item
var userDocumentId = retrievedItem.Value; // "users/1"
// Access the VERSION number of the retrieved item
var version = retrievedItem.Index;
}
else
{
Console.WriteLine("Compare-exchange item not found");
}
}// Create a compare-exchange item for the example:
using (var asyncSession = store.OpenAsyncSession(
new SessionOptions { TransactionMode = TransactionMode.ClusterWide }))
{
CompareExchangeValue<string> itemToCreate =
asyncSession.Advanced.ClusterTransaction.CreateCompareExchangeValue(
key: "user1-name@example.com",
value: "users/1"
);
await asyncSession.SaveChangesAsync();
}
using (var asyncSession = store.OpenAsyncSession(
new SessionOptions { TransactionMode = TransactionMode.ClusterWide }))
{
// Get the compare-exchange item lazily:
// =====================================
var lazyItem = asyncSession.Advanced.ClusterTransaction.Lazily
.GetCompareExchangeValueAsync<string>("user1-name@example.com");
// Access the item:
CompareExchangeValue<string> retrievedItem = await lazyItem.Value;
if (retrievedItem != null) {
// Access the VALUE of the retrieved item
var userDocumentId = retrievedItem.Value; // "users/1"
// Access the VERSION number of the retrieved item
var version = retrievedItem.Index;
}
else
{
Console.WriteLine("Compare-exchange item not found");
}
}Retrieved compare-exchange items are tracked by the session
- Cluster_wide_session
- Cluster_wide_session_async
using (var session = store.OpenSession(
new SessionOptions { TransactionMode = TransactionMode.ClusterWide }))
{
// First retrieval — server call will happen
var item1 = session.Advanced.ClusterTransaction
.GetCompareExchangeValue<string>("user1-name@example.com");
// No server call - the item is returned from session
var item2 = session.Advanced.ClusterTransaction
.GetCompareExchangeValue<string>("user1-name@example.com");
// Clear tracked entities and compare-exchange items
session.Advanced.Clear();
// Server call will happen again
var item3 = session.Advanced.ClusterTransaction
.GetCompareExchangeValue<string>("user1-name@example.com");
}using (var asyncSession = store.OpenAsyncSession(
new SessionOptions { TransactionMode = TransactionMode.ClusterWide }))
{
// First retrieval — server call will happen
var item1 = await asyncSession.Advanced.ClusterTransaction
.GetCompareExchangeValueAsync<string>("user1-name@example.com");
// No server call - the item is returned from session
var item2 = await asyncSession.Advanced.ClusterTransaction
.GetCompareExchangeValueAsync<string>("user1-name@example.com");
// Clear tracked entities and compare-exchange items
asyncSession.Advanced.Clear();
// Server call will happen again
var item3 = await asyncSession.Advanced.ClusterTransaction
.GetCompareExchangeValueAsync<string>("user1-name@example.com");
}
Get item using a store operation
-
You can retrieve compare-exchange items using a store operation.
Use theGetCompareExchangeValueOperation
operation to get a compare-exchange item by its key. -
If the specified key does not exist, the operation returns
null
. No exception is thrown. -
Examples:
Get compare-exchange item that has a number value and metadata
- Get_operation
- Get_operation_async
// First, let's create a new compare-exchange item for the example,
// e.g. store the number of sales made by an employee as the value + some metadata info:
var putCmpXchgOp = new PutCompareExchangeValueOperation<long>("employees/1-A", 12345, 0,
new MetadataAsDictionary
{
{ "Department", "Sales" },
{ "Role", "Salesperson" }
});
CompareExchangeResult<long> putResult = store.Operations.Send(putCmpXchgOp);
// Get the compare-exchange item:
// ==============================
// Define the get compare-exchange operation, pass the unique item key
var getCmpXchgOp = new GetCompareExchangeValueOperation<long>("employees/1-A");
// Execute the operation by passing it to Operations.Send
CompareExchangeValue<long> retrievedItem = store.Operations.Send(getCmpXchgOp);
if (retrievedItem != null)
{
// Access the VALUE of the retrieved item
long numberOfSales = retrievedItem.Value; // 12345
// Access the METADATA of the retrieved item
var employeeRole = retrievedItem.Metadata["Role"]; // "Salesperson"
// Access the VERSION number of the retrieved item
long version = retrievedItem.Index;
}
else
{
Console.WriteLine("Compare-exchange item not found");
}// First, let's create a new compare-exchange item for the example,
// e.g. store the number of sales made by an employee as the value + some metadata info:
var putCmpXchgOp = new PutCompareExchangeValueOperation<long>("employees/1-A", 12345, 0,
new MetadataAsDictionary
{
{ "Department", "Sales" },
{ "Role", "Salesperson" }
});
CompareExchangeResult<long> putResult = await store.Operations.SendAsync(putCmpXchgOp);
// Get the compare-exchange item:
// ==============================
// Define the get compare-exchange operation, pass the unique item key
var getCmpXchgOp = new GetCompareExchangeValueOperation<long>("employees/1-A");
// Execute the operation by passing it to Operations.SendAsync
CompareExchangeValue<long> retrievedItem = await store.Operations.SendAsync(getCmpXchgOp);
if (retrievedItem != null)
{
// Access the VALUE of the retrieved item
long numberOfSales = retrievedItem.Value; // 12345
// Access the METADATA of the retrieved item
var employeeRole = retrievedItem.Metadata["Role"]; // "Salesperson"
// Access the VERSION number of the retrieved item
long version = retrievedItem.Index;
}
else
{
Console.WriteLine("Compare-exchange item not found");
}Get compare-exchange item that has a custom object value
- Get_operation
- Get_operation_async
- EmployeeRole_class
// Create a new compare-exchange item for the example:
// Put a new compare-exchange item with an object as the value
var employeeRole = new EmployeeRole
{
Role = "Salesperson",
Department = "Sales",
NumberOfSales = 12345
};
var putCmpXchgOp = new PutCompareExchangeValueOperation<EmployeeRole>(
"employees/1-A", employeeRole, 0);
CompareExchangeResult<EmployeeRole> putResult = store.Operations.Send(putCmpXchgOp);
// Get the compare-exchange item:
// ==============================
// Define the get compare-exchange operation, pass the unique item key
var getCmpXchgOp = new GetCompareExchangeValueOperation<EmployeeRole>("employees/1-A");
// Execute the operation by passing it to Operations.Send
CompareExchangeValue<EmployeeRole> retrievedItem = store.Operations.Send(getCmpXchgOp);
if (retrievedItem != null)
{
// Access the VALUE of the retrieved item
var employeeDetails = retrievedItem.Value;
var objectType = employeeDetails.GetType(); // typeof(EmployeeRole)
var role = employeeDetails.Role; // "Salesperson"
var Dep = employeeDetails.Department; // "Sales"
var Sales = employeeDetails.NumberOfSales; // 12345
// Access the VERSION number of the retrieved item
long version = retrievedItem.Index;
}
else
{
Console.WriteLine("Compare-exchange item not found");
}// Create a new compare-exchange item for the example:
// Put a new compare-exchange item with an object as the value
var employeeRole = new EmployeeRole
{
Role = "Salesperson",
Department = "Sales",
NumberOfSales = 12345
};
var putCmpXchgOp = new PutCompareExchangeValueOperation<EmployeeRole>(
"employees/1-A", employeeRole, 0);
CompareExchangeResult<EmployeeRole> putResult = await store.Operations.SendAsync(putCmpXchgOp);
// Get the compare-exchange item:
// ==============================
// Define the get compare-exchange operation, pass the unique item key
var getCmpXchgOp = new GetCompareExchangeValueOperation<EmployeeRole>("employees/1-A");
// Execute the operation by passing it to Operations.SendAsync
CompareExchangeValue<EmployeeRole> retrievedItem = await store.Operations.SendAsync(getCmpXchgOp);
if (retrievedItem != null)
{
// Access the VALUE of the retrieved item
var employeeDetails = retrievedItem.Value;
var objectType = employeeDetails.GetType(); // typeof(EmployeeRole)
var role = employeeDetails.Role; // "Salesperson"
var Dep = employeeDetails.Department; // "Sales"
var Sales = employeeDetails.NumberOfSales; // 12345
// Access the VERSION number of the retrieved item
long version = retrievedItem.Index;
}
else
{
Console.WriteLine("Compare-exchange item not found");
}public class EmployeeRole
{
public string Id { get; set; }
public string Department { get; set; } = "";
public string Role { get; set; } = "";
public int NumberOfSales { get; set; }
}
Syntax
GetCompareExchangeValueOperation
Get compare-exchange item using a store operation:
public GetCompareExchangeValueOperation(string key);
GetCompareExchangeValue
Get compare-exchange item using cluster-wide session:
CompareExchangeValue<T> GetCompareExchangeValue<T>(string key);
Task<CompareExchangeValue<T>> GetCompareExchangeValueAsync<T>(string key,
CancellationToken token = default);
Lazy<CompareExchangeValue<T>> GetCompareExchangeValue<T>(string key);
Lazy<Task<CompareExchangeValue<T>>> GetCompareExchangeValueAsync<T>(string key,
CancellationToken token = default);
Input parameter | Type | Description |
---|---|---|
key | string | The unique identifier of the compare-exchange item to retrieve. |
The returned object: | Description |
---|---|
CompareExchangeValue<T> | The compare-exchange item is returned. Returns null if key doesn't exist. |
public class CompareExchangeValue<T>
{
// The unique identifier of the compare-exchange item.
public string Key { get; }
// The existing `value` of the returned compare-exchange item.
public T Value { get; set; }
// The compare-exchange item's version.
public long Index { get; internal set; }
// The existing `metadata` of the returned compare-exchange item.
public IMetadataDictionary Metadata;
}