Customize Query

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

IDocumentQueryCustomization addBeforeQueryExecutedListener(Consumer<IndexQuery> action);
IDocumentQueryCustomization removeBeforeQueryExecutedListener(Consumer<IndexQuery> action);

Example

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

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

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

IDocumentQueryCustomization addAfterQueryExecutedListener(Consumer<QueryResult> action);
IDocumentQueryCustomization removeAfterQueryExecutedListener(Consumer<QueryResult> action);

Example

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

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

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

IDocumentQueryCustomization addAfterStreamExecutedListener(Consumer<ObjectNode> action);
IDocumentQueryCustomization removeAfterStreamExecutedListener(Consumer<ObjectNode> action);

Example

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

session.query(Employee.class)
    .addAfterStreamExecutedListener(result -> {
        totalStreamedResultsSize.value += result.size();
    })
    .toList();

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

IDocumentQueryCustomization noCaching();

Example

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

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

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

IDocumentQueryCustomization noTracking();

Example

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

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

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

To order results randomly, use the randomOrdering method.

IDocumentQueryCustomization randomOrdering();

IDocumentQueryCustomization randomOrdering(String seed);

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

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.

IDocumentQueryCustomization waitForNonStaleResults();

IDocumentQueryCustomization waitForNonStaleResults(Duration waitTimeout);

Example

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

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