---
title: "Include Compare Exchange Values"
url: "https://docs.ravendb.net/6.2/client-api/operations/compare-exchange/include-compare-exchange"
version: "6.2"
language: "csharp"
---

# Include Compare Exchange Values

> Client language: C#. Also available for [Node.js](https://docs.ravendb.net/6.2/client-api/operations/compare-exchange/include-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 included when [loading entities](https://docs.ravendb.net/6.2/client-api/session/loading-entities.md)
>   and when making [queries](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-query.md).
>
> - The Session [tracks](https://docs.ravendb.net/6.2/client-api/session/what-is-a-session-and-how-does-it-work.md#tracking-changes)
>   the included Compare Exchange items which means their value can be accessed  
>   in that Session without making an additional call to the server.
>
> - The Compare Exchange include syntax is based on the [include method](https://docs.ravendb.net/6.2/client-api/how-to/handle-document-relationships.md#includes).
>
> - In this page:
>   - [Syntax](#syntax)
>   - [Examples](#examples)

## Syntax

#### Include method

Chain the method `IncludeCompareExchangeValue()` to include compare exchange values
along with `Session.Load()` or LINQ queries.

```csharp
public interface ICompareExchangeValueIncludeBuilder<T, out TBuilder>
{
  TBuilder IncludeCompareExchangeValue(string path);

  TBuilder IncludeCompareExchangeValue(Expression<Func<T, string>> path);

  TBuilder IncludeCompareExchangeValue(Expression<Func<T, IEnumerable<string>>> path);
}
```

| Parameter | Type | Description |
| - | - | - |
| **path** | `string`; <br /> `Expression<Func<T, string>>`; <br /> `Expression<Func<T, IEnumerable<string>>>` | The key of the compare exchange value you want to include, a path to the key, or a path to a `string[]` of keys. |

#### RQL

In an RQL query, you can use the [`include` keyword](https://docs.ravendb.net/6.2/client-api/session/querying/what-is-rql.md#include)
followed by `cmpxchg()` to include a compare exchange value:

```sql
include cmpxchg(key)
```

In [javascript functions](https://docs.ravendb.net/6.2/client-api/session/querying/what-is-rql.md#declare) within queries,
use `includes.cmpxchg()` (see the RawQuery example
[below](#examples)):

```javascript
includes.cmpxchg(key);
```

| Parameter | Type | Description |
| - | - | - |
| **key** | `string`; <br /> path to `string` | The key of the compare exchange value you want to include, or a path to the key. |

## Examples

### Load

```csharp
using (IDocumentSession session = documentStore.OpenSession())
{
  // Load a user document, include the compare exchange value
  // with the key equal to the user's Name field
  var user = session.Load<User>("users/1-A", 
                                includes => includes.IncludeCompareExchangeValue(
                                    x => x.Name));

  // Getting the compare exchange value does not require
  // another call to the server
  var value = session.Advanced.ClusterTransaction
                              .GetCompareExchangeValue<string>(user.Name);
}
```

### LoadAsync

```csharp
using (IAsyncDocumentSession session = documentStore.OpenAsyncSession())
{
  // Load a user document, include the compare exchange value
  // with the key equal to the user's Name field
  var user = await session.LoadAsync<User>("users/1-A", 
                                           includes => includes.IncludeCompareExchangeValue(
                                               x => x.Name));

  // Getting the compare exchange value does not require
  // another call to the server
  var value = await session.Advanced.ClusterTransaction
                                    .GetCompareExchangeValueAsync<string>(user.Name);
}
```

### Query

```csharp
var users = session.Query<User>()
  .Include(builder => builder.IncludeCompareExchangeValue(x => x.Name))
  .ToList();

List<CompareExchangeValue<string>> compareExchangeValues = null;

// Getting the compare exchange values does not require
// additional calls to the server
foreach (User u in users){
  compareExchangeValues.Add(session.Advanced.ClusterTransaction
                                .GetCompareExchangeValue<string>(u.Name));
}
```

### RawQuery(RQL)

```csharp
// First method: from body of query
var users1 = session.Advanced
  .RawQuery<User>(@"
      from Users as u
      select u
      include cmpxchg(u.Name)"
  )
  .ToList();

List<CompareExchangeValue<string>> compareExchangeValues1 = null;

// Getting the compare exchange values does not require
// additional calls to the server
foreach (User u in users1){
  compareExchangeValues1.Add(session.Advanced.ClusterTransaction
                             .GetCompareExchangeValue<string>(u.Name));
}


// Second method: from a JavaScript function
var users2 = session.Advanced
  .RawQuery<User>(@"
      declare function includeCEV(user) {
          includes.cmpxchg(user.Name);
          return user;
      }

      from Users as u
      select includeCEV(u)"
  )
  .ToList();
// Note that includeCEV() returns the same User 
// entity it received, without modifying it

List<CompareExchangeValue<string>> compareExchangeValues2 = null;

// Does not require calls to the server
foreach (User u in users2){
  compareExchangeValues2.Add(session.Advanced.ClusterTransaction
                             .GetCompareExchangeValue<string>(u.Name));
}
```

## See also

- [Session Change Tracking](https://docs.ravendb.net/6.2/client-api/session/what-is-a-session-and-how-does-it-work.md#tracking-changes)
- [How to: Handle Document Relationships](https://docs.ravendb.net/6.2/client-api/how-to/handle-document-relationships.md)
- [Compare Exchange Overview](https://docs.ravendb.net/6.2/client-api/operations/compare-exchange/overview.md)
- [Indexing Compare Exchange Values](https://docs.ravendb.net/6.2/indexes/indexing-compare-exchange-values.md)
