Customize Query

• Use Customize() to set the following customization options on a specific Query.
  Can be set for both dynamic and index queries.

• Each such customization can also be implemented via the DocumentQuery API.

• A query can also be customized on the Store or Session level by subscribing to OnBeforeQuery.
  Learn more in Subscribing to Events.

• Customization methods available:

  • BeforeQueryExecuted
  • AfterQueryExecuted
  • AfterStreamExecuted
  • NoCaching
  • NoTracking
  • Projection
  • RandomOrdering
  • Timings
  • WaitForNonStaleResults

• Methods return value

BeforeQueryExecuted

• Use BeforeQueryExecuted to customize the query just before it is executed.

Example

• Query
• Query_async
• DocumentQuery
• RawQuery

List<Employee> results = session
  .Query<Employee>()
   // Call 'Customize' with 'BeforeQueryExecuted'
  .Customize(x => x.BeforeQueryExecuted(query =>
  {
      // Can modify query parameters
      query.SkipDuplicateChecking = true;
      // Can apply any needed action, e.g. write to log
      _logger.Info($"Query to be executed is: {query.Query}");
  }))
  .Where(x => x.FirstName == "Robert")
  .ToList();

List<Employee> results = await asyncSession
  .Query<Employee>()
   // Call 'Customize' with 'BeforeQueryExecuted'
  .Customize(x => x.BeforeQueryExecuted(query =>
  {
      // Can modify query parameters
      query.SkipDuplicateChecking = true;
      // Can apply any needed action, e.g. write to log
      _logger.Info($"Query to be executed is: {query.Query}");
  }))
  .Where(x => x.FirstName == "Robert")
  .ToListAsync();

List<Employee> results = session.Advanced
  .DocumentQuery<Employee>()
  .WhereEquals(x => x.FirstName, "Robert")
   // Call 'BeforeQueryExecuted'
  .BeforeQueryExecuted(query =>
  {
      // Can modify query parameters
      query.SkipDuplicateChecking = true;
      // Can apply any needed action, e.g. write to log
      _logger.Info($"Query to be executed is: {query.Query}");
  })
  .ToList();

List<Employee> results = session.Advanced
  .RawQuery<Employee>("from 'Employees' where FirstName == 'Robert'")
   // Call 'BeforeQueryExecuted'
  .BeforeQueryExecuted(query =>
  {
      // Can modify query parameters
      query.SkipDuplicateChecking = true;
      // Can apply any needed action, e.g. write to log
      _logger.Info($"Query to be executed is: {query.Query}");
  })
  .ToList();

Syntax

IDocumentQueryCustomization BeforeQueryExecuted(Action<IndexQuery> action);

Parameters	Type	Description
action	Action<IndexQuery>	An Action method that operates on the query. The query is passed in the IndexQuery param.

AfterQueryExecuted

• Use AfterQueryExecuted to access the raw query result after it is executed.

Example

• Query
• Query_async
• DocumentQuery
• RawQuery

List<Employee> results = session
  .Query<Employee>()
   // Call 'Customize' with 'AfterQueryExecuted'
  .Customize(x => x.AfterQueryExecuted(rawResult =>
  {
      // Can access the raw query result
      var queryDuration = rawResult.DurationInMs;
      // Can apply any needed action, e.g. write to log
      _logger.Info($"{rawResult.LastQueryTime}");
  }))
  .ToList();

List<Employee> results = await asyncSession
  .Query<Employee>()
   // Call 'Customize' with 'AfterQueryExecuted'
  .Customize(x => x.AfterQueryExecuted(rawResult =>
  {
      // Can access the raw query result
      var queryDuration = rawResult.DurationInMs;
      // Can apply any needed action, e.g. write to log
      _logger.Info($"{rawResult.LastQueryTime}");
  }))
  .ToListAsync();

List<Employee> results = session.Advanced
  .DocumentQuery<Employee>()
   // Call 'AfterQueryExecuted'
  .AfterQueryExecuted(rawResult =>
  {
      // Can access the raw query result
      var queryDuration = rawResult.DurationInMs;
      // Can apply any needed action, e.g. write to log
      _logger.Info($"{rawResult.LastQueryTime}");
  })
  .ToList();

List<Employee> results = session.Advanced
  .RawQuery<Employee>("from 'Employees'")
   // Call 'AfterQueryExecuted'
  .AfterQueryExecuted(rawResult =>
  {
      // Can access the raw query result
      var queryDuration = rawResult.DurationInMs;
      // Can apply any needed action, e.g. write to log
      _logger.Info($"{rawResult.LastQueryTime}");
  })
  .ToList();

Syntax

IDocumentQueryCustomization AfterQueryExecuted(Action<QueryResult> action);

Parameters	Type	Description
action	Action<QueryResult>	An Action method that receives the raw query result. The query result is passed in the QueryResult param.

AfterStreamExecuted

• Use AfterStreamExecuted to retrieve a raw (blittable) result of the streaming query.

• Learn more in how to stream query results.

Example

• Query
• Query_async
• DocumentQuery
• RawQuery

long totalStreamedResultsSize = 0;

// Define the query
var query = session
  .Query<Employee>()
   // Call 'Customize' with 'AfterStreamExecuted'
  .Customize(x => x.AfterStreamExecuted(streamResult =>
      // Can access the stream result
      totalStreamedResultsSize += streamResult.Size));
  
// Call 'Stream' to execute the query
var streamResults = session.Advanced.Stream(query);

long totalStreamedResultsSize = 0;

// Define the query
var query = asyncSession
  .Query<Employee>()
   // Call 'Customize' with 'AfterStreamExecuted'
  .Customize(x => x.AfterStreamExecuted(streamResult =>
      // Can access the stream result
      totalStreamedResultsSize += streamResult.Size));
  
// Call 'Stream' to execute the query
var streamResults = await asyncSession.Advanced.StreamAsync(query);

long totalStreamedResultsSize = 0;

// Define the document query
var query = session.Advanced
  .DocumentQuery<Employee>()
   // Call 'AfterStreamExecuted'
  .AfterStreamExecuted(streamResult =>
      // Can access the stream result
      totalStreamedResultsSize += streamResult.Size);
  
// Call 'Stream' to execute the document query
var streamResults = session.Advanced.Stream(query);

long totalStreamedResultsSize = 0;

// Define the raw query
var query = session.Advanced
  .RawQuery<Employee>("from 'Employees'")
   // Call 'AfterStreamExecuted'
  .AfterStreamExecuted(streamResult =>
      // Can access the stream result
      totalStreamedResultsSize += streamResult.Size);

// Call 'Stream' to execute the document query
var streamResults = session.Advanced.Stream(query);

Syntax

IDocumentQueryCustomization AfterStreamExecuted(Action<BlittableJsonReaderObject> action);

Parameters	Type	Description
action	Action<BlittableJsonReaderObject>	An Action method that recieves a single stream query result. The stream result is passed in the BlittableJsonReaderObject param.

NoCaching

• By default, query results are cached.

• You can use the NoCaching customization to disable query caching.

• Learn more in disable caching per session.

Example

• Query
• Query_async
• DocumentQuery
• RawQuery

List<Employee> results = session
  .Query<Employee>()
   // Call 'Customize' with 'NoCaching'
  .Customize(x => x.NoCaching())
  .Where(x => x.FirstName == "Robert")
  .ToList();

List<Employee> results = await asyncSession
  .Query<Employee>()
   // Call 'Customize' with 'NoCaching'
  .Customize(x => x.NoCaching())
  .Where(x => x.FirstName == "Robert")
  .ToListAsync();

List<Employee> results = session.Advanced
  .DocumentQuery<Employee>()
  .WhereEquals(x => x.FirstName, "Robert")
   // Call 'NoCaching'
  .NoCaching()
  .ToList();

List<Employee> results = session.Advanced
  .RawQuery<Employee>("from 'Employees' where FirstName == 'Robert'")
   // Call 'NoCaching'
  .NoCaching()
  .ToList();

Syntax

IDocumentQueryCustomization NoCaching();

NoTracking

• By default, the Session tracks all changes made to all entities that it has either loaded, stored, or queried for.

• You can use the NoTracking customization to disable entity tracking.

• See disable entity tracking for all other options.

Example

• Query
• Query_async
• DocumentQuery
• RawQuery

List<Employee> results = session
  .Query<Employee>()
   // Call 'Customize' with 'NoTracking'
  .Customize(x => x.NoTracking())
  .Where(x => x.FirstName == "Robert")
  .ToList();

List<Employee> results = await asyncSession
  .Query<Employee>()
   // Call 'Customize' with 'NoTracking'
  .Customize(x => x.NoTracking())
  .Where(x => x.FirstName == "Robert")
  .ToListAsync();

List<Employee> results = session.Advanced
  .DocumentQuery<Employee>()
  .WhereEquals(x => x.FirstName, "Robert")
   // Call 'NoTracking'
  .NoTracking()
  .ToList();

List<Employee> results = session.Advanced
  .RawQuery<Employee>("from 'Employees' where FirstName == 'Robert'")
   // Call 'NoTracking'
  .NoTracking()
  .ToList();

Syntax

IDocumentQueryCustomization NoTracking();

Projection

• By default, when querying an index and projecting query results,
  the server will try to retrieve field values from the fields stored in the index.

  Projecting means the query returns only specific document fields instead of the full document.

• If the index does Not store these fields, the field values will be retrieved from the documents.

• Use the Projection method to customize and modify this behavior.

• Note:
  Entities resulting from a projecting query are Not tracked by the session.
  Learn more about projections in:

  • Project index query results
  • Project dynamic query results

Example

• Query
• Query_async
• DocumentQuery
• RawQuery
• Index

List<string> results = session
  .Query<Employees_ByFullName.IndexEntry, Employees_ByFullName>()
   // Call 'Customize'
   // Pass the requested projection behavior to the 'Projection' method
  .Customize(x => x.Projection(ProjectionBehavior.FromDocumentOrThrow))
   // Select the fields that will be returned by the projection
  .Select(x => x.FullName)
  .ToList();

List<string> results = await asyncSession
  .Query<Employees_ByFullName.IndexEntry, Employees_ByFullName>()
   // Call 'Customize'
   // Pass the requested projection behavior to the 'Projection' method
  .Customize(x => x.Projection(ProjectionBehavior.FromDocumentOrThrow))
   // Select the fields that will be returned by the projection
  .Select(x => x.FullName)
  .ToListAsync();

List<Employee> results = session.Advanced
  .DocumentQuery<Employee>("Employees/ByFullName")
   // Pass the requested projection behavior to the 'SelectFields' method
   // and specify the field that will be returned by the projection
  .SelectFields<Employee>(ProjectionBehavior.FromDocumentOrThrow, "FullName")
  .ToList();

List<Employee> results = session.Advanced
   // Define an RQL query that returns a projection
  .RawQuery<Employee>(@"from index 'Employees/ByFullName' select FullName")
   // Pass the requested projection behavior to the 'Projection' method
  .Projection(ProjectionBehavior.FromDocumentOrThrow)
  .ToList();

public class Employees_ByFullName : AbstractIndexCreationTask<Employee, Employees_ByFullName.IndexEntry>
{
  // The IndexEntry class defines the index-fields.
  public class IndexEntry
  {
      public string FullName { get; set; }
  }
      
  public Employees_ByFullName()
  {
      // The 'Map' function defines the content of the index-fields
      Map = employees => from employee in employees
          select new IndexEntry
          {
              FullName = $"{employee.FirstName} {employee.LastName}"
          };
      
      // Store field 'FullName' in the index
      Store(x => x.FullName, FieldStorage.Yes);
  }
}

In the above example:

• Field 'FullName' is stored in the index (see index definition in the rightmost tab).
  However, the server will try to fetch the value from the document since the default behavior was modified to FromDocumentOrThrow.
• An exception will be thrown since an 'Employee' document does not contain the property 'FullName'.
  (based on the Northwind sample data).

Syntax

IDocumentQueryCustomization Projection(ProjectionBehavior projectionBehavior);

public enum ProjectionBehavior {
  Default,
  FromIndex,
  FromIndexOrThrow,
  FromDocument,
  FromDocumentOrThrow
}

• Default
  Retrieve values from the stored index fields when available.
  If fields are not stored then get values from the document,
  a field that is not found in the document is skipped.
• FromIndex
  Retrieve values from the stored index fields when available.
  A field that is not stored in the index is skipped.
• FromIndexOrThrow
  Retrieve values from the stored index fields when available.
  An exception is thrown if the index does not store the requested field.
• FromDocument
  Retrieve values directly from the documents store.
  A field that is not found in the document is skipped.
• FromDocumentOrThrow
  Retrieve values directly from the documents store.
  An exception is thrown if the document does not contain the requested field.

RandomOrdering

• Use RandomOrdering to order the query results randomly.

• More ordering options are available in this Sorting article.

Example

• Query
• Query_async
• DocumentQuery
• RawQuery

List<Employee> results = session
  .Query<Employee>()
  // Call 'Customize' with 'RandomOrdering'
  .Customize(x => x.RandomOrdering())
  .ToList();

List<Employee> results = await asyncSession
  .Query<Employee>()
   // Call 'Customize' with 'RandomOrdering'
  .Customize(x => x.RandomOrdering())
  .ToListAsync();

List<Employee> results = session.Advanced
  .DocumentQuery<Employee>()
   // Call 'RandomOrdering'
  .RandomOrdering()
  .ToList();

List<Employee> results = session.Advanced
   // Define an RQL query that orders the results randomly
  .RawQuery<Employee>("from 'Employees' order by random()")
  .ToList();

Syntax

IDocumentQueryCustomization RandomOrdering();
IDocumentQueryCustomization RandomOrdering(string seed);

Parameters	Type	Description
seed	string	Order the search results randomly using this seed. Useful when executing repeated random queries.

Timings

• Use Timings to get detailed stats of the time spent by the server on each part of the query.

• The timing statistics will be included in the query results.

• Learn more in how to include query timings.

Example

• Query
• Query_async
• DocumentQuery
• RawQuery

List<Employee> results = session
  .Query<Employee>()
   // Call 'Customize' with 'Timings'
   // Provide an out param for the timings results
  .Customize(x => x.Timings(out QueryTimings timings))
  .Where(x => x.FirstName == "Robert")
  .ToList();

List<Employee> results = await asyncSession
  .Query<Employee>()
   // Call 'Customize' with 'Timings'
   // Provide an out param for the timings results
  .Customize(x => x.Timings(out QueryTimings timings))
  .Where(x => x.FirstName == "Robert")
  .ToListAsync();

List<Employee> results = session.Advanced
  .DocumentQuery<Employee>()
  .WhereEquals(x => x.FirstName, "Robert")
   // Call 'Timings'.
   // Provide an out param for the timings results
  .Timings(out QueryTimings timings)
  .ToList();

List<Employee> results = session.Advanced
  .RawQuery<Employee>("from 'Employees' where FirstName == 'Robert'")
   // Call 'Timings'.
   // Provide an out param for the timings results
  .Timings(out QueryTimings timings)
  .ToList();

Syntax

IDocumentQueryCustomization Timings(out QueryTimings timings);

Parameters	Type	Description
timings	QueryTimings	An out param that will be filled with the timings results

WaitForNonStaleResults

• All queries in RavenDB provide results using an index, even when you don't specify one.
  See detailed explanation in Queries always provide results using an index.

• Use WaitForNonStaleResults to instruct the query to wait for non-stale results from the index.

• A TimeoutException will be thrown if the query is not able to return non-stale results within the specified
  (or default) timeout.

• Note: This feature is Not available when streaming the query results.
  Calling WaitForNonStaleResults with a streaming query will throw an exception.

• Learn more about stale results in stale indexes.

Example

• Query
• Query_async
• DocumentQuery
• RawQuery

List<Employee> results = session
  .Query<Employee>()
   // Call 'Customize' with 'WaitForNonStaleResults'
  .Customize(x => x.WaitForNonStaleResults(TimeSpan.FromSeconds(10)))
  .Where(x => x.FirstName == "Robert")
  .ToList();

List<Employee> results = await asyncSession
  .Query<Employee>()
   // Call 'Customize' with 'WaitForNonStaleResults'
  .Customize(x => x.WaitForNonStaleResults(TimeSpan.FromSeconds(10)))
  .Where(x => x.FirstName == "Robert")
  .ToListAsync();

List<Employee> results = session.Advanced
  .DocumentQuery<Employee>()
  .WhereEquals(x => x.FirstName, "Robert")
   // Call 'WaitForNonStaleResults'
  .WaitForNonStaleResults(TimeSpan.FromSeconds(10))
  .ToList();

List<Employee> results = session.Advanced
  .RawQuery<Employee>("from 'Employees' where FirstName == 'Robert'")
   // Call 'WaitForNonStaleResults'
  .WaitForNonStaleResults(TimeSpan.FromSeconds(10))
  .ToList();

Syntax

IDocumentQueryCustomization WaitForNonStaleResults(TimeSpan? waitTimeout);

Parameters	Type	Description
waitTimeout	TimeSpan?	Time to wait for non-stale results. Default is 15 seconds.

Methods return value

All of the above customization methods return the following:

Query return value
IDocumentQueryCustomization	Returns self for easier method chaining.

DocumentQuery return value
IQueryBase	Returns self for easier method chaining.