---
title: "Compare Exchange in Cluster-Wide Session"
url: "https://docs.ravendb.net/6.2/client-api/session/cluster-transaction/compare-exchange"
version: "6.2"
language: "csharp"
---

# Compare Exchange in Cluster-Wide Session

> Client language: C#. Also available for [Python](https://docs.ravendb.net/6.2/client-api/session/cluster-transaction/compare-exchange.python.md), [PHP](https://docs.ravendb.net/6.2/client-api/session/cluster-transaction/compare-exchange.php.md), [Node.js](https://docs.ravendb.net/6.2/client-api/session/cluster-transaction/compare-exchange.nodejs.md).
>
> RavenDB publishes an official agent skill for coding assistants at https://docs.ravendb.net/skills/ravendb/SKILL.md (also installable with `npx skills add ravendb/skills`). The skill describes itself as: "Read this before writing any RavenDB query, client call or /databases/ request. Covers server setup, document modelling, the Node.js, .NET and Python clients, RQL, indexes, vector search and AI agents. Code written from recall tends to run and return the wrong rows, because RQL resembles SQL and the clients take field names as plain strings."

> **Note**
>
> - Compare-Exchange items can be created and managed on the advanced session (`Session.Advanced`)  
>   Other options are listed in this [compare-exchange overview](https://docs.ravendb.net/6.2/client-api/operations/compare-exchange/overview.md#how-to-create-and-manage-compare-exchange-items).
>
> - When working with compare-exchange items from the session,  
>   the session **must be opened as a [cluster-wide session](https://docs.ravendb.net/6.2/client-api/session/cluster-transaction/overview.md#open-a-cluster-transaction)**.
>
> - In this page:
>   - [Create compare-exchange](#create-compare-exchange)
>   - [Get compare-exchange](#get-compare-exchange)
>   - [Delete compare-exchange](#delete-compare-exchange)

## Create compare-exchange

> **Note**
>
> #### Example
>
> ##### Sync
>
> ```csharp
> // The session must be first opened with cluster-wide mode
> session.Advanced.ClusterTransaction.CreateCompareExchangeValue(
>   key: "Best NoSQL Transactional Database",
>   value: "RavenDB"
> );
>
> session.SaveChanges();
> ```
>
> ##### Async
>
> ```csharp
> // The session must be first opened with cluster-wide mode
> session.Advanced.ClusterTransaction.CreateCompareExchangeValue(
>   key: "Best NoSQL Transactional Database",
>   value: "RavenDB"
> );
>
> await session.SaveChangesAsync();
> ```
>
> - `SaveChanges()` throws a `ConcurrencyException` if the key already exists.
> - An `InvalidOperationException` exception is thrown if the session was Not opened as **cluster-wide**.

> **Note**
>
> #### Syntax
>
> ##### Sync
>
> ```csharp
> session.Advanced.ClusterTransaction.CreateCompareExchangeValue<T>(key, value);
> ```
>
> ##### Async
>
> ```csharp
> session.Advanced.ClusterTransaction.CreateCompareExchangeValue<T>(key, value);
> ```
>
> | Parameters | Type | Description |
> | - | - | - |
> | **key** | `string` | The compare-exchange item key. This string can be up to 512 bytes. |
> | **value** | `T` | The associated value to store for the key |
>
> | Return Value | Description |
> | - | - |
> | `CompareExchangeValue<T>` | The new compare-exchange item is returned |

> **Note**
>
> #### The CompareExchangeValue
>
> | Parameters | Type | Description |
> | - | - | - |
> | **key** | `string` | The compare-exchange item key. This string can be up to 512 bytes. |
> | **value** | `T` | The value associated with the key |
> | **index** | `long` | Index for concurrency control |

## Get compare-exchange

> **Note**
>
> #### Get single value
>
> ##### Sync
>
> ```csharp
> session.Advanced.ClusterTransaction.GetCompareExchangeValue<T>(key);
> ```
>
> ##### Async
>
> ```csharp
> await session.Advanced.ClusterTransaction.GetCompareExchangeValueAsync<T>(key);
> ```
>
> | Parameters | Type | Description |
> | - | - | - |
> | **key** | `string` | The key to retrieve |
>
> | Return Value | Description |
> | - | - |
> | `CompareExchangeValue<T>` | If the key doesn't exist it will return `null` |

> **Note**
>
> #### Get multiple values
>
> ##### Sync
>
> ```csharp
> session.Advanced.ClusterTransaction.GetCompareExchangeValues<T>(keys);
> ```
>
> ##### Async
>
> ```csharp
> await session.Advanced.ClusterTransaction.GetCompareExchangeValuesAsync<T>(keys);
> ```
>
> | Parameters | Type | Description |
> | - | - | - |
> | **keys** | `string[]` | Array of keys to retrieve |
>
> | Return Value | Description |
> | - | - |
> | `Dictionary<string, CompareExchangeValue<T>>` | If a key doesn't exists the associate value will be `null` |

> **Note**
>
> #### Get compare-exchange lazily
>
> ##### Sync
>
> ```csharp
> // Single value
> session.Advanced.ClusterTransaction.Lazily.GetCompareExchangeValue<T>(key);
>
> // Multiple values
> session.Advanced.ClusterTransaction.Lazily.GetCompareExchangeValues<T>(keys);
> ```
>
> ##### Async
>
> ```csharp
> // Single value
> session.Advanced.ClusterTransaction.Lazily.GetCompareExchangeValueAsync<T>(key);
>
> // Multiple values
> session.Advanced.ClusterTransaction.Lazily.GetCompareExchangeValuesAsync<T>(keys);
> ```
>
> | Parameters | Type | Description |
> | - | - | - |
> | **key** | `string` | The key to retrieve |
> | **keys** | `string[]` | Array of keys to retrieve |
>
> | Return Value | Description |
> | - | - |
> | `Lazy<CompareExchangeValue<T>>` | If the key doesn't exist it will return `null` |
> | `Lazy<Dictionary<string, CompareExchangeValue<T>>>` | If a key doesn't exists the associate value will be `null` |

## Delete compare-exchange

> **Note**
>
> ### Sync
>
> ```csharp
> // Delete by key & index
> session.Advanced.ClusterTransaction.DeleteCompareExchangeValue(key, index);
>
> // Delete by compare-exchange item
> session.Advanced.ClusterTransaction.DeleteCompareExchangeValue<T>(item);
> ```
>
> ### Async
>
> ```csharp
> // Delete by key & index
> session.Advanced.ClusterTransaction.DeleteCompareExchangeValue(key, index);
>
> // Delete by compare-exchange item
> session.Advanced.ClusterTransaction.DeleteCompareExchangeValue<T>(item);
> ```
>
> | Parameters | Type | Description |
> | - | - | - |
> | **key** | `string` | The key of the compare-exchange item to delete |
> | **index** | `long` | The index of this compare-exchange item |
> | **item** | `CompareExchangeValue<T>` | The compare-exchange item to delete |

## See also

- [Compare Exchange: Overview](https://docs.ravendb.net/6.2/client-api/operations/compare-exchange/overview.md)
- [Get a Compare-Exchange Value](https://docs.ravendb.net/6.2/client-api/operations/compare-exchange/get-compare-exchange-value.md)
- [Get Compare-Exchange Values](https://docs.ravendb.net/6.2/client-api/operations/compare-exchange/get-compare-exchange-values.md)
- [Put a Compare-Exchange Value](https://docs.ravendb.net/6.2/client-api/operations/compare-exchange/delete-compare-exchange-value.md)
