Customize Query


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


BeforeQueryExecuted

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

IDocumentQueryCustomization addBeforeQueryExecutedListener(Consumer<IndexQuery> action);
IDocumentQueryCustomization removeBeforeQueryExecutedListener(Consumer<IndexQuery> action);
Parameters
action Consumer Action that will modify IndexQuery.
Return Value
IDocumentQueryCustomization Returns self for easier method chaining.

Example

session.advanced().addBeforeQueryListener(
    (sender, event) -> event.getQueryCustomization().addBeforeQueryExecutedListener(
        // set 'pageSize' to 10
        q -> q.setPageSize(10)));

session.query(Employee.class).toList();

AfterQueryExecuted

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

IDocumentQueryCustomization addAfterQueryExecutedListener(Consumer<QueryResult> action);
IDocumentQueryCustomization removeAfterQueryExecutedListener(Consumer<QueryResult> action);
Parameters
action Consumer Action that has the query result.
Return Value
IDocumentQueryCustomization Returns self for easier method chaining.

Example

AtomicReference<Duration> queryDuration = new AtomicReference<>();

session.query(Employee.class)
    .addAfterQueryExecutedListener(result -> {
        queryDuration.set(Duration.ofMillis(result.getDurationInMs()));
    })
    .toList();

AfterStreamExecuted

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

IDocumentQueryCustomization addAfterStreamExecutedListener(Consumer<ObjectNode> action);
IDocumentQueryCustomization removeAfterStreamExecutedListener(Consumer<ObjectNode> action);
Parameters
action Consumer Action that has the single query result.
Return Value
IDocumentQueryCustomization Returns self for easier method chaining.

Example

Reference<Long> totalStreamedResultsSize = new Reference<Long>(0L);

session.query(Employee.class)
    .addAfterStreamExecutedListener(result -> {
        totalStreamedResultsSize.value += 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

session.advanced().addBeforeQueryListener(
    ((sender, event) -> event.getQueryCustomization().noCaching()));

List<Employee> results = session.query(Employee.class)
    .whereEquals("FirstName", "Robert")
    .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

session.advanced().addBeforeQueryListener(
    ((sender, event) -> event.getQueryCustomization().noTracking()));

List<Employee> results = session.query(Employee.class)
    .whereEquals("FirstName", "Robert")
    .toList();

ProjectionBehavior

By default, queries are satisfied with the values stored in the index. If the index doesn't contain the requested values, they are retrieved from the documents themselves.

This behavior can be configured using the projection option, which takes a ProjectionBehavior:

IDocumentQueryCustomization projection(ProjectionBehavior projectionBehavior);

public enum ProjectionBehavior {
    DEFAULT,
    FROM_INDEX,
    FROM_INDEX_OR_THROW,
    FROM_DOCUMENT,
    FROM_DOCUMENT_OR_THROW
}
  • Default - query will be satisfied with indexed data when possible, and directly from the document when it is not.
  • FromIndex - query will be satisfied with indexed data when possible, and when it is not, the field is skipped.
  • FromIndexOrThrow - query will be satisfied with indexed data. If the index does not contain the requested data, an exception is thrown.
  • FromDocument - query will be satisfied with document data when possible, and when it is not, the field is skipped.
  • FromDocumentOrThrow - query will be satisfied with document data. If the document does not contain the requested data, an exception is thrown.

Example

session.advanced().addBeforeQueryListener((sender, event)
    -> event.getQueryCustomization().projection(ProjectionBehavior.DEFAULT));

List<Employee> results = session.query(Employee.class)
    .selectFields(Employee.class,"name")
    .toList();

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

session.advanced().addBeforeQueryListener(
    (sender, event) -> event.getQueryCustomization().randomOrdering());

//result will be ordered randomly each time
List<Employee> results = session.query(Employee.class)
    .whereEquals("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.

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

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

IDocumentQueryCustomization waitForNonStaleResults(Duration waitTimeout);
Parameters
waitTimeout Duration 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

session.advanced().addBeforeQueryListener(
    (sender, event) -> event.getQueryCustomization().waitForNonStaleResults());

List<Employee> results = session.query(Employee.class)
    .whereEquals("FirstName", "Robert")
    .toList();