Session: Querying: How to customize query?

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

IDocumentQueryCustomization BeforeQueryExecution(Action<IndexQuery> action);

Example

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

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

Please check our dedicated article.

Please check our dedicated article.

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

IDocumentQueryCustomization NoCaching();

Example

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

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

IDocumentQueryCustomization NoTracking();

Example

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

To order results randomly use RandomOrdering method.

IDocumentQueryCustomization RandomOrdering();

IDocumentQueryCustomization RandomOrdering(string seed);

Example

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

Please check our dedicated article.

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

Example

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

Please check our dedicated article.

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

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;

Please check our dedicated article.

Spatial

Please check our dedicated article.

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

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

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

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

Example

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

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

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

Example

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

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

IDocumentQueryCustomization WaitForNonStaleResultsAsOfNow();

IDocumentQueryCustomization WaitForNonStaleResultsAsOfNow(TimeSpan waitTimeout);

Example

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

Please check our dedicated article.