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.

public IDocumentQueryCustomization beforeQueryExecution(Action1<IndexQuery> action);

Parameters
action Action1<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.class)
  .customize(new DocumentQueryCustomizationFactory().beforeQueryExecution(new Action1<IndexQuery>() {
    @Override
    public void apply(IndexQuery query) {
      query.setPageSize(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, boolean descending);

Parameters
typeName String AssemblyQualifiedName of a custom sorter available on server-side.
descending boolean 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.

public IDocumentQueryCustomization noCaching();

Return Value
IDocumentQueryCustomization Returns self for easier method chaining.

Example

QEmployee e = QEmployee.employee;
List<Employee> results = session
  .query(Employee.class)
  .customize(new DocumentQueryCustomizationFactory().noCaching())
  .where(e.firstName.eq("Robert"))
  .toList();

NoTracking

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

public IDocumentQueryCustomization noTracking();

Return Value
IDocumentQueryCustomization Returns self for easier method chaining.

Example

QEmployee e = QEmployee.employee;
List<Employee> results = session
  .query(Employee.class)
  .customize(new DocumentQueryCustomizationFactory().noTracking())
  .where(e.firstName.eq("Robert"))
  .toList();

RandomOrdering

To order results randomly use randomOrdering method.

public IDocumentQueryCustomization randomOrdering();

public 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
QEmployee e = QEmployee.employee;
List<Employee> results = session
  .query(Employee.class)
  .customize(new DocumentQueryCustomizationFactory().randomOrdering())
  .where(e.firstName.eq("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.

public IDocumentQueryCustomization setAllowMultipleIndexEntriesForSameDocumentToResultTransformer(boolean val);

Parameters
val boolean 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

QEmployee e = QEmployee.employee;
List<Employee> results = session
  .query(Employee.class)
  .customize(
    new DocumentQueryCustomizationFactory()
      .setAllowMultipleIndexEntriesForSameDocumentToResultTransformer(true)
    )
  .where(e.firstName.eq("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.

public IDocumentQueryCustomization showTimings();

Return Value
IDocumentQueryCustomization Returns self for easier method chaining.

Returned timings:

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

Example

QEmployee e = QEmployee.employee;
Reference<RavenQueryStatistics> statsRef = new Reference<>();
List<Employee> results = session
  .query(Employee.class)
  .customize(new DocumentQueryCustomizationFactory().showTimings())
  .statistics(statsRef)
  .where(e.firstName.eq("Robert"))
  .toList();

Map<String, Double> timings = statsRef.value.getTimingsInMilliseconds();

SortByDistance

Please check our dedicated article.

Spatial

Please check our dedicated article.

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.

public IDocumentQueryCustomization waitForNonStaleResults();

public IDocumentQueryCustomization waitForNonStaleResults(long waitTimeout);

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

Example

QEmployee e = QEmployee.employee;
List<Employee> results = session
  .query(Employee.class)
  .customize(new DocumentQueryCustomizationFactory().waitForNonStaleResults())
  .where(e.firstName.eq("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.

public IDocumentQueryCustomization waitForNonStaleResultsAsOf(Date cutOff);

public IDocumentQueryCustomization waitForNonStaleResultsAsOf(Date cutOff, long waitTimeout);

public IDocumentQueryCustomization waitForNonStaleResultsAsOf(Etag cutOffEtag);

public IDocumentQueryCustomization waitForNonStaleResultsAsOf(Etag cutOffEtag, long 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 long Time to wait (in miliseconds) 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.

public IDocumentQueryCustomization waitForNonStaleResultsAsOfLastWrite();

public IDocumentQueryCustomization waitForNonStaleResultsAsOfLastWrite(long waitTimeout);

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

Example

QEmployee e = QEmployee.employee;
List<Employee> results = session
  .query(Employee.class)
  .customize(new DocumentQueryCustomizationFactory().waitForNonStaleResultsAsOfLastWrite())
  .where(e.firstName.eq("Robert"))
  .toList();

WaitForNonStaleResultsAsOfNow

waitForNonStaleResultsAsOfNow internally uses waitForNonStaleResultsAsOf and passes new Date() to cutOff parameter.

public IDocumentQueryCustomization waitForNonStaleResultsAsOfNow();

public IDocumentQueryCustomization waitForNonStaleResultsAsOfNow(long waitTimeout);

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

Example

QEmployee e = QEmployee.employee;
List<Employee> results = session
  .query(Employee.class)
  .customize(new DocumentQueryCustomizationFactory().waitForNonStaleResultsAsOfNow())
  .where(e.firstName.eq("Robert"))
  .toList();

WithinRadiusOf

Please check our dedicated article.