Include Compare Exchange Values

• Compare-Exchange items can be included when loading entities and when making queries.

• The Session tracks 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.

• In this page:

  • Syntax
  • Examples

Syntax

Include method

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