---
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: "nodejs"
---

# Compare Exchange in Cluster-Wide Session

> Client language: Node.js. Also available for [C#](https://docs.ravendb.net/6.2/client-api/session/cluster-transaction/compare-exchange.md), [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).
>
> 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.nodejs.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
>
> ```javascript
> // The session must be first opened with cluster-wide mode
> const session = documentStore.openSession({
>   transactionMode: "ClusterWide"
> });
>
> session.advanced.clusterTransaction.createCompareExchangeValue(
>   "Best NoSQL Transactional Database", "RavenDB"  // key, value
> );
>
> await session.saveChanges();
> ```
>
> - An `InvalidOperationException` exception is thrown when:
>   - The session was Not opened as **cluster-wide**.
>   - The key already exists in the database.

> **Note**
>
> #### Syntax
>
> ```javascript
> session.advanced.clusterTransaction.createCompareExchangeValue(key, item);
> ```
>
> | Parameters | Type | Description |
> | - | - | - |
> | **key** | `string` | The compare-exchange item key. This string can be up to 512 bytes. |
> | **value** | `object` | The associated value to store for the key |
>
> | Return value | Description |
> | - | - |
> | `object` | The new compare-exchange item is returned |

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

## Get compare-exchange

> **Note**
>
> #### Get single value
>
> ```javascript
> await session.advanced.clusterTransaction.getCompareExchangeValue(key);
> ```
>
> | Parameters | Type | Description |
> | - | - | - |
> | **key** | `string` | The key to retrieve |
>
> | Return value | Description |
> | - | - |
> | `object` | The compare-exchange item is returned.<br /> Returns `null` if key doesn't exist. |
>
> [key: string]: https://docs.ravendb.net/6.2/client-api/session/cluster-transaction/CompareExchangeValue%3CT%3E;

> **Note**
>
> #### Get multiple values
>
> ```javascript
> await session.advanced.clusterTransaction.getCompareExchangeValues(keys);
> ```
>
> | Parameters | Type | Description |
> | - | - | - |
> | **keys** | `string[]` | Array of keys to retrieve |
>
> | Return value | Description |
> | - | - |
> | `Record<string, object>` | If a key doesn't exists the associate value will be `null` |

> **Note**
>
> #### Get compare-exchange lazily
>
> ```javascript
> // Single item
> const lazyItem = session.advanced.clusterTransaction.lazily.getCompareExchangeValue(key);
> const item = await lazyItem.getValue();
>
> // Multiple items
> const lazyItems = session.advanced.clusterTransaction.lazily.getCompareExchangeValues(keys);
> const items = await lazyItems.getValue();
> ```
>
> | Parameters | Type | Description |
> | - | - | - |
> | **key** | `string` | The key to retrieve |
> | **keys** | `string[]` | Array of keys to retrieve |
>
> | Return value - after calling `getValue` | Description |
> | - | - |
> | `object` | For single item:<br />If the key doesn't exist it will return `null` |
> | `Record<string, object>` | For multiple items:<br />If a key doesn't exists the associate value will be `null` |

## Delete compare-exchange

> **Note**
>
> ```javascript
> // Delete by key & index
> session.advanced.clusterTransaction.deleteCompareExchangeValue(key, index);
>
> // Delete by compare-exchange item
> session.advanced.clusterTransaction.deleteCompareExchangeValue(item);
> ```
>
> | Parameters | Type | Description |
> | - | - | - |
> | **key** | `string` | The key of the compare-exchange item to delete |
> | **index** | `number` | The index of this compare-exchange item |
> | **item** | `object` | 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.nodejs.md)
- [Get Compare-Exchange Values](https://docs.ravendb.net/6.2/client-api/operations/compare-exchange/get-compare-exchange-values.nodejs.md)
- [Put a Compare-Exchange Value](https://docs.ravendb.net/6.2/client-api/operations/compare-exchange/delete-compare-exchange-value.nodejs.md)
