Skip to main content

Include Compare-Exchange Items

Sample data​

The examples in this article are based on the following sample data:
To learn about ALL the available methods for creating a compare-exchange item, see Create compare-exchange item.

using (var session = store.OpenSession())
{
    // Create some company documents:
    // ==============================

    var company1 = new Company
    {
        Id = "companies/1",
        Name = "Apple",
        Supplier = "suppliers/1",
        Workers = new[] { "employees/1", "employees/2" }
    };

    var company2 = new Company
    {
        Id = "companies/2",
        Name = "Google",
        Supplier = "suppliers/2",
        Workers = new[] { "employees/3", "employees/4" }
    };

    var company3 = new Company
    {
        Id = "companies/3",
        Name = "Microsoft",
        Supplier = "suppliers/3",
        Workers = new[] { "employees/6", "employees/5" }
    };

    session.Store(company1);
    session.Store(company2);
    session.Store(company3);

    session.SaveChanges();
}

Include compare-exchange items when loading​

Include single item:

// Open a session with cluster-wide mode to enable calling 'IncludeCompareExchangeValue'
using (var session = store.OpenSession(new SessionOptions
{
    TransactionMode = TransactionMode.ClusterWide
}))
{
    // Load a company document + include a CmpXchg item:
    // =================================================

    var company1 = session.Load<Company>("companies/1", includes =>
        // Call 'IncludeCompareExchangeValue'
        // "Supplier" is the document property that holds the CmpXchg key to include
        includes.IncludeCompareExchangeValue(c => c.Supplier));

    // Calling 'Load' has triggered a server call
    var numberOfRequests = session.Advanced.NumberOfRequests;
    Console.WriteLine($"Number of requests made: {numberOfRequests}"); // Should be 1

    // Access the included CmpXchg item:
    // =================================

    // Call 'GetCompareExchangeValue' to access the content of the included CmpXchg item.
    // Pass the CmpXchg item KEY. This will NOT trigger another server call.
    var item = session.Advanced.ClusterTransaction
        .GetCompareExchangeValue<string>(company1.Supplier);

    // You can check that no further server calls were made
    Console.WriteLine(session.Advanced.NumberOfRequests == numberOfRequests); // Should be true

    // The CmpXchg item value is available
    var value = item.Value;
}

Include multiple items:

// Open a session with cluster-wide mode
using (var session = store.OpenSession(new SessionOptions
{
    TransactionMode = TransactionMode.ClusterWide
}))
{
    // Load a company document + include multiple CmpXchg items:
    // =========================================================
        
    var company1 = session.Load<Company>("companies/1", includes =>
        // Call 'IncludeCompareExchangeValue'
        // "Workers" is the document property that holds the list of keys to include
        includes.IncludeCompareExchangeValue<Company>(c => c.Workers));

    var numberOfRequests = session.Advanced.NumberOfRequests; 
    Console.WriteLine($"Number of requests made: {numberOfRequests}"); // Should be 1

    // Access the included CmpXchg items:
    // ==================================

    // Call 'GetCompareExchangeValues' to access the content of the included CmpXchg items.
    // Pass the list of KEYS. This will NOT trigger another server call.
    var items = session.Advanced.ClusterTransaction
        .GetCompareExchangeValues<string>(company1.Workers);

    // You can check that no further server calls were made
    Console.WriteLine(session.Advanced.NumberOfRequests == numberOfRequests); // Should be true

    // The value of each item is available
    var value1 = items["employees/1"].Value;
    var value2 = items["employees/2"].Value;
}

Include compare-exchange items when querying​

Dynamic query:

// Open a session with cluster-wide mode to enable calling 'IncludeCompareExchangeValue'
using (var session = store.OpenSession(new SessionOptions
{
    TransactionMode = TransactionMode.ClusterWide
}))
{
    // Make a dynamic query + include CmpXchg items:
    // =============================================

    var companies = session.Query<Company>()
         // Call 'Include' with 'IncludeCompareExchangeValue'
         // pass the PATH of the document property that contains the key of the CmpXchg item to include 
        .Include(x => x.IncludeCompareExchangeValue(c => c.Supplier))
        .ToList();

    // Making the query has triggered a server call
    var numberOfRequests = session.Advanced.NumberOfRequests;
    Console.WriteLine($"Number of requests made: {numberOfRequests}"); // Should be 1

    // Access the included CmpXchg items:
    // ==================================
    
    var cmpXchgItems = new List<CompareExchangeValue<string>>();

    foreach (var company in companies)
    {
        // Call 'GetCompareExchangeValue' to access the included CmpXchg item.
        // Pass the KEY. This will NOT trigger another server call.
        var item = session.Advanced.ClusterTransaction
            .GetCompareExchangeValue<string>(company.Supplier);

        cmpXchgItems.Add(item);
    }

    // You can check that no further server calls were made
    Console.WriteLine(session.Advanced.NumberOfRequests == numberOfRequests); // Should be true
}

Index query:

// Open a session with cluster-wide mode
using (var session = store.OpenSession(new SessionOptions
{
    TransactionMode = TransactionMode.ClusterWide
}))
{
    // Make an index query + include CmpXchg items:
    // ============================================

    var companies = session.Query<Companies_ByNameAndSupplier.IndexEntry, Companies_ByNameAndSupplier>()
         // Call 'Include' with 'IncludeCompareExchangeValue'
         // pass the PATH of the property that contains the key of the CmpXchg item to include
        .Include(x => x.IncludeCompareExchangeValue(c => c.Supplier))
        .OfType<Company>()
        .ToList();

    var numberOfRequests = session.Advanced.NumberOfRequests;
    Console.WriteLine($"Number of requests made: {numberOfRequests}"); // Should be 1

    // Access the included CmpXchg items:
    // ==================================
    
    var cmpXchgItems = new List<CompareExchangeValue<string>>();

    foreach (var company in companies)
    {
        var item = session.Advanced.ClusterTransaction
            .GetCompareExchangeValue<string>(company.Supplier);

        cmpXchgItems.Add(item);
    }

    Console.WriteLine(session.Advanced.NumberOfRequests == numberOfRequests); // Should be true
}
  • Note:
    Similar to the above dynamic query example, you can query the index with a raw query using the provided RQL.

Syntax​

When loading entities or making queries:

  • Use method IncludeCompareExchangeValue() to include compare-exchange items with session.Load() or with queries.
// Available overloads:
IncludeCompareExchangeValue(string path);
IncludeCompareExchangeValue(Expression<Func<T, string>> path);
IncludeCompareExchangeValue(Expression<Func<T, IEnumerable<string>>> path);

ParameterTypeDescription
pathstringThe key of the compare-exchange item to include.
pathExpression<Func<T, string>>An expression indicating the property path that resolves to the key of the compare-exchange item to include.
pathExpression<Func<T, IEnumerable<string>>>An expression indicating the property path that resolves to an array of keys of the items to include.

When querying with RQL:

  • Use the include keyword followed by cmpxchg() to include a compare-exchange item.
include cmpxchg(key)

When using JavaScript functions within RQL:

includes.cmpxchg(key);
ParameterTypeDescription
keystringThe key of the compare exchange value you want to include, or a path to the key.