Session: Querying: How to customize query?

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

public IDocumentQueryCustomization beforeQueryExecution(Action1<IndexQuery> action);

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

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

Please check our dedicated article.

Please check our dedicated article.

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

public IDocumentQueryCustomization noCaching();

Example

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

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

public IDocumentQueryCustomization noTracking();

Example

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

To order results randomly use randomOrdering method.

public IDocumentQueryCustomization randomOrdering();

public IDocumentQueryCustomization randomOrdering(String seed);

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

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.

public IDocumentQueryCustomization setAllowMultipleIndexEntriesForSameDocumentToResultTransformer(boolean val);

Example

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

public IDocumentQueryCustomization showTimings();

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

Please check our dedicated article.

Please check our dedicated article.

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

Example

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

public IDocumentQueryCustomization waitForNonStaleResultsAsOf(Date cutOff);

public IDocumentQueryCustomization waitForNonStaleResultsAsOf(Date cutOff, long waitTimeout);

public IDocumentQueryCustomization waitForNonStaleResultsAsOf(Etag cutOffEtag);

public IDocumentQueryCustomization waitForNonStaleResultsAsOf(Etag cutOffEtag, long 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.

public IDocumentQueryCustomization waitForNonStaleResultsAsOfLastWrite();

public IDocumentQueryCustomization waitForNonStaleResultsAsOfLastWrite(long waitTimeout);

Example

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

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

public IDocumentQueryCustomization waitForNonStaleResultsAsOfNow();

public IDocumentQueryCustomization waitForNonStaleResultsAsOfNow(long waitTimeout);

Example

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

Please check our dedicated article.