Include Compare Exchange Values

• Compare Exchange Values can be included in Session.Load calls and in queries.

• The Session tracks Compare Exchange Values, which means that after it has been included, the value can be accessed and modified in that Session without requiring an additional call to the server.

• The Compare Exchange include syntax is based on the include builder.

• In this page:

  • Syntax
  • Examples

Syntax

Include builder

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

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;
Expression<Func<T, string>>;
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 followed by cmpxchg() to include a compare exchange value:

include cmpxchg(key)

In javascript functions within queries, use includes.cmpxchg() (see the RawQuery example below):

includes.cmpxchg(key);

Parameter	Type	Description
key	string;
path to string	The key of the compare exchange value you want to include, or a path to the key.

Examples

• Load
• LoadAsync
• Query
• RawQuery(RQL)

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);
}

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);
}

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));
}

// 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));
}