You are currently browsing legacy 5.0 version of documentation. Click here to switch to the newest 6.2 version.
    We can help you with migration to the latest RavenDB
    Contact Us Now
    See on GitHub

    Session: Querying: How to Customize a Query

    The following query customization options are available:

    Query is an EventEmitter. It emits few events allowing you to customize its behavior.

    BeforeQueryExecuted

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

    query.on("beforeQueryExecuted", action);
    Parameters
    action function Action on the index query
    Return Value
    query Returns self for easier method chaining.

    Example

    await session
    .query(Employee)
    .on("beforeQueryExecuted", indexQuery => {
        // set 'pageSize' to 10
        indexQuery.pageSize = 10;  
    })
    .all();

    AfterQueryExecuted

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

    query.on("afterQueryExecuted", action);
    Parameters
    action function Action on the query result
    Return Value
    query Returns self for easier method chaining

    Example

    let queryDuration;

await session.query(Employee)
    .on("afterQueryExecuted", result => {
        queryDuration = result.durationInMs;
    })
    .all();

    AfterStreamExecuted

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

    query.on("afterStreamExecuted", action);
    Parameters
    action function Action on a single query result
    Return Value
    query Returns self for easier method chaining.

    Example

    let totalStreamedResultsSize;

await session.query(Employee)
    .on("afterStreamExecuted", result => {
        totalStreamedResultsSize += result.size;
    });

    NoCaching

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

    queryCustomization.noCaching();
    Return Value
    IDocumentQueryCustomization Returns self for easier method chaining.

    Example

    session.advanced.on("beforeQuery",
    event => event.queryCustomization.noCaching());

const results = await session.query({ collection: "Employees" })
    .whereEquals("FirstName", "Robert")
    .all();

    NoTracking

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

    queryCustomization.noTracking();
    Return Value
    IDocumentQueryCustomization Returns self for easier method chaining.

    Example

    session.advanced.on("beforeQuery",
    event => event.queryCustomization.noTracking());

const results = await session.query({ collection: "Employees" })
    .whereEquals("FirstName", "Robert")
    .all();

    RandomOrdering

    To order results randomly, use the randomOrdering() method.

    queryCustomization.randomOrdering([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.on("beforeQuery",
    event => event.queryCustomization.randomOrdering());

// result will be ordered randomly each time
const results = await session.query({ collection: "Employees" })
    .whereEquals("FirstName", "Robert")
    .all();

    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.

    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.

    queryCustomization.waitForNonStaleResults([waitTimeout]);
    Parameters
    waitTimeout number Time to wait for an index to return non-stale results. The default is 15 seconds.
    Return Value
    query Returns self for easier method chaining.

    Example

    session.advanced.on("beforeQuery",
    event => event.queryCustomization.waitForNonStaleResults());

const results = await session.query({ collection: "Employees" })
    .whereEquals("FirstName", "Robert")
    .all();

    related articlesRelated Articles

    Session

    Configuration

    Indexes

    Home / Docs / Client Api / Session / Querying / How To Customize Query