Session: Querying: How to Customize a Query

The following query customization options are available in the IDocumentQueryCustomization interface:

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

BeforeQueryExecuted

Allows you to modify the index query just before it's executed.

IDocumentQueryCustomization BeforeQueryExecuted(Action<IndexQuery> action);

Parameters
action	Action<IndexQuery>	Action that will modify IndexQuery.

Return Value
IDocumentQueryCustomization	Returns self for easier method chaining.

Example

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

AfterQueryExecuted

Allows you to retrieve a raw query result after it's executed.

IDocumentQueryCustomization AfterQueryExecuted(Action<QueryResult> action);

Parameters
action	Action<QueryResult>	Action that has the query result.

Return Value
IDocumentQueryCustomization	Returns self for easier method chaining.

Example

TimeSpan queryDuration;

List<Employee> results = session.Query<Employee>()
  .Customize(x => x.AfterQueryExecuted(
      result => queryDuration = TimeSpan.FromMilliseconds(result.DurationInMs)))
  .ToList();

AfterStreamExecuted

Allows you to retrieve a raw (blittable) result of the streaming query.

IDocumentQueryCustomization AfterStreamExecuted(Action<BlittableJsonReaderObject> action);

Parameters
action	Action<BlittableJsonReaderObject>	Action that has the single query result.

Return Value
IDocumentQueryCustomization	Returns self for easier method chaining.

Example

long totalStreamedResultsSize = 0;

List<Employee> results = session.Query<Employee>()
  .Customize(x => x.AfterStreamExecuted(
      result => totalStreamedResultsSize += result.Size))
  .ToList();

NoCaching

By default, queries are cached. To disable query caching use the NoCaching customization.

IDocumentQueryCustomization NoCaching();

Return Value
IDocumentQueryCustomization	Returns self for easier method chaining.

Example

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

NoTracking

To disable entity tracking by Session use NoTracking. Usage of this option will prevent holding the query results in memory.

IDocumentQueryCustomization NoTracking();

Return Value
IDocumentQueryCustomization	Returns self for easier method chaining.

Example

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

RandomOrdering

To order results randomly, use the RandomOrdering method.

IDocumentQueryCustomization RandomOrdering();

IDocumentQueryCustomization RandomOrdering(string seed);

Parameters
seed	string	Seed used for ordering. Useful when repeatable random queries are needed.

Return Value
IDocumentQueryCustomization	Returns self for easier method chaining.

Example

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

WaitForNonStaleResults

Queries can be 'instructed' to wait for non-stale results for a specified amount of time using the WaitForNonStaleResults method. If the query won't be able to return non-stale results within the specified (or default) timeout, then a TimeoutException is thrown.

Cutoff Point

If a query sent to the server specifies that it needs to wait for non-stale results, then RavenDB sets the cutoff Etag for the staleness check. It is the Etag of the last document (or document tombstone), from the collection(s) processed by the index, as of the query arrived to the server. This way the server won't be waiting forever for the non-stale results even though documents are constantly updated meanwhile.

If the last Etag processed by the index is greater than the cutoff then the results are considered as non-stale.

IDocumentQueryCustomization WaitForNonStaleResults(TimeSpan? waitTimeout);

Parameters
waitTimeout	TimeSpan?	Time to wait for an index to return non-stale results. The default is 15 seconds.

Return Value
IDocumentQueryCustomization	Returns self for easier method chaining.

Example

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