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