see on GitHub

Session : Querying : How to customize query?

Following query customization options are available in IDocumentQueryCustomization interface:

BeforeQueryExecution

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

IDocumentQueryCustomization BeforeQueryExecution(Action<IndexQuery> action);

Parameters
action Action<IndexQuery> Action that will modify IndexQuery.
Return Value
IDocumentQueryCustomization Returns self for easier method chaining.

Example

// set 'PageSize' to 10
List<Employee> results = session.Query<Employee>()
	.Customize(x => x.BeforeQueryExecution(query => query.PageSize = 10))
	.ToList();

CustomSortUsing

Allows you to use custom sorter on the server. Dedicated article can be found here.

IDocumentQueryCustomization CustomSortUsing(string typeName);

IDocumentQueryCustomization CustomSortUsing(string typeName, bool descending);

Parameters
typeName string AssemblyQualifiedName of a custom sorter available on server-side.
descending bool indicates if results should be ordered descending or ascending
Return Value
IDocumentQueryCustomization Returns self for easier method chaining.

Highlight

Please check our dedicated article.

Include

Please check our dedicated article.

NoCaching

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

IDocumentQueryCustomization NoCaching();

Return Value
IDocumentQueryCustomization Returns self for easier method chaining.

Example

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

NoTracking

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

IDocumentQueryCustomization NoTracking();

Return Value
IDocumentQueryCustomization Returns self for easier method chaining.

Example

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

RandomOrdering

To order results randomly use 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

// results will be ordered randomly each time
List<Employee> results = session.Query<Employee>()
	.Customize(x => x.RandomOrdering())
	.Where(x => x.FirstName == "Robert")
	.ToList();

RelatesToShape

Please check our dedicated article.

SetAllowMultipleIndexEntriesForSameDocumentToResultTransformer

If set to true, multiple index entries will be send from the same document (assuming the index project them) to the result transformer function. Otherwise, those entries will be consolidate an the transformer will be called just once for each document in the result set.

IDocumentQueryCustomization
	SetAllowMultipleIndexEntriesForSameDocumentToResultTransformer(bool val);

Parameters
val bool Indicates if multiple index entries can be send from the same document to result transformer.
Return Value
IDocumentQueryCustomization Returns self for easier method chaining.

Example

List<Employee> results = session.Query<Employee>()
	.Customize(x => x.SetAllowMultipleIndexEntriesForSameDocumentToResultTransformer(true))
	.TransformWith<Employees_NoLastName, Employee>()
	.Where(x => x.FirstName == "Robert")
	.ToList();

SetHighlighterTags

Please check our dedicated article.

ShowTimings

By default, detailed timings (duration of Lucene search, loading documents, transforming results) in queries are turned off, this is due to small overhead that calculation of such timings produces.

IDocumentQueryCustomization ShowTimings();

Return Value
IDocumentQueryCustomization Returns self for easier method chaining.

Returned timings:

  • Query parsing
  • Lucene search
  • Loading documents
  • Transforming results

Example

RavenQueryStatistics stats;
List<Employee> results = session.Query<Employee>()
	.Customize(x => x.ShowTimings())
	.Statistics(out stats)
	.Where(x => x.FirstName == "Robert")
	.ToList();

Dictionary<string, double> timings = stats.TimingsInMilliseconds;

SortByDistance

Please check our dedicated article.

Spatial

Please check our dedicated article.

TransformResults

TransformResults is a client-side function that allows any transformations on query results.

IDocumentQueryCustomization TransformResults(
	Func<IndexQuery, IEnumerable<object>, IEnumerable<object>> resultsTransformer);

Parameters
resultsTransformer Func<IndexQuery, IEnumerable<object>, IEnumerable<object>> Transformation function.
Return Value
IDocumentQueryCustomization Returns self for easier method chaining.

Example

// filter-out all results where 'LastName' equals 'Doe' on client-side
List<Employee> results = session.Query<Employee>()
	.Customize(x => x.TransformResults((indexQuery, queryResults) => queryResults.Cast<Employee>().Where(q => q.LastName != "Doe")))
	.Where(x => x.FirstName == "Robert")
	.ToList();

WaitForNonStaleResults

Note

This methods should be used only for testing purposes and are considered EXPERT ONLY

Queries can be 'instructed' to wait for non-stale results for specified amount of time using WaitForNonStaleResults method. It is not advised to use this method, because on live databases indexes might never become unstale.

IDocumentQueryCustomization WaitForNonStaleResults();

IDocumentQueryCustomization WaitForNonStaleResults(TimeSpan waitTimeout);

Parameters
waitTimeout TimeSpan Time to wait for index to return non-stale results. Default: 15 seconds.
Return Value
IDocumentQueryCustomization Returns self for easier method chaining.

Example

List<Employee> results = session.Query<Employee>()
	.Customize(x => x.WaitForNonStaleResults())
	.Where(x => x.FirstName == "Robert")
	.ToList();

WaitForNonStaleResultsAsOf

Queries can be 'instructed' to wait for non-stale results as of cutoff DateTime or Etag for specified amount of time using WaitForNonStaleResultsAsOf method.

IDocumentQueryCustomization WaitForNonStaleResultsAsOf(DateTime cutOff);

IDocumentQueryCustomization WaitForNonStaleResultsAsOf(
	DateTime cutOff,
	TimeSpan waitTimeout);

IDocumentQueryCustomization WaitForNonStaleResultsAsOf(Etag cutOffEtag);

IDocumentQueryCustomization WaitForNonStaleResultsAsOf(
	Etag cutOffEtag,
	TimeSpan waitTimeout);

Parameters
cutOff DateTime Minimum modified date of last indexed document. If last indexed document modified date is greater than this value the results are considered non-stale.
cutOffEtag Etag Minimum Etag of last indexed document. If last indexed document etag is greater than this value the results are considered non-stale.
waitTimeout TimeSpan Time to wait for index to return non-stale results. Default: 15 seconds.
Return Value
IDocumentQueryCustomization Returns self for easier method chaining.

WaitForNonStaleResultsAsOfLastWrite

Queries can be 'instructed' to wait for non-stale results as of last write made by any session belonging to the current DocumentStore using WaitForNonStaleResultsAsOfLastWrite method.

This method internally uses WaitForNonStaleResultsAsOf and passes last written Etag, which DocumentStore tracks, to cutOffEtag parameter.

IDocumentQueryCustomization WaitForNonStaleResultsAsOfLastWrite();

IDocumentQueryCustomization WaitForNonStaleResultsAsOfLastWrite(TimeSpan waitTimeout);

Parameters
waitTimeout TimeSpan Time to wait for index to return non-stale results. Default: 15 seconds.
Return Value
IDocumentQueryCustomization Returns self for easier method chaining.

Example

List<Employee> results = session.Query<Employee>()
	.Customize(x => x.WaitForNonStaleResultsAsOfLastWrite())
	.Where(x => x.FirstName == "Robert")
	.ToList();

WaitForNonStaleResultsAsOfNow

WaitForNonStaleResultsAsOfNow internally uses WaitForNonStaleResultsAsOf and passes DateTime.Now to cutOff parameter.

IDocumentQueryCustomization WaitForNonStaleResultsAsOfNow();

IDocumentQueryCustomization WaitForNonStaleResultsAsOfNow(TimeSpan waitTimeout);

Parameters
waitTimeout TimeSpan Time to wait for index to return non-stale results. Default: 15 seconds.
Return Value
IDocumentQueryCustomization Returns self for easier method chaining.

Example

List<Employee> results = session.Query<Employee>()
	.Customize(x => x.WaitForNonStaleResultsAsOfNow())
	.Where(x => x.FirstName == "Robert")
	.ToList();

WithinRadiusOf

Please check our dedicated article.