Query pipeline routing mechanisms and rules

This is for:

Developer System Administrator

All queries sent to your Coveo organization are routed to a query pipeline before they reach the index (see What’s a query pipeline?). Depending on your needs, you can leverage different query pipeline routing mechanisms.

Usually, you’ll want to use condition-based routing to take advantage of the flexibility offered by query pipeline conditions. However, some situations may require you to enforce a specific routing, ignoring query pipeline conditions altogether (see Search interface-enforced routing and Search token-enforced routing).

The following table summarizes the main criteria to consider when selecting a query pipeline routing mechanism.

Selection criteria

Query pipeline routing mechanisms

Condition-based routing (recommended)

Search interface-enforced routing

Search token-enforced routing

Routing priority

Lowest

Medium

Highest

Implementation by

Coveo administrator

Developer

Developer

Implementation in

Coveo Administration Console
(no code required)

Search interface configuration
(client-side code)

Search token generation logic
(server-side code)
Note

Before the introduction of the Safer conditional pipeline routing critical update, it was possible to bypass all routing mechanisms by setting the pipeline query parameter directly in the search request. However, this option is no longer available.

Review the following leading practices and rules to better understand how queries are routed to a given query pipeline, and determine which routing mechanism best suits your needs.

Routing rules

The following diagram and rules describe the routing rules.

diagram_pipeline_selection | Coveo

  1. When your setup uses search tokens for authentication, a query pipeline can be specified in each generated token (see the pipeline parameter), in which case that query pipeline is used, bypassing its condition (if any).

    The search token can include either a pipeline or a search hub. If a search hub is included, it will use the pipeline condition (Query matches condition) even if a different pipeline is enforced in the interface.

    Search token-enforced routing takes precedence over all other query pipeline routing mechanisms.

    Note

    You can validate whether a search token enforces a query pipeline by decoding this search token with a tool such as JWT.IO.

  2. The search token can include either a pipeline or a search hub. If a search hub is included, it will use the pipeline condition (Query matches condition) even if a different pipeline is enforced in the interface.

    Note

    We recommend using a search hub in the search token instead of a pipeline to ensure the query matches the intended conditions even if the interface enforces a different pipeline.

  3. If a query pipeline is set in the Coveo JavaScript Search Framework interface code (typically on the SearchInterface component), this query pipeline is used, bypassing its condition (if any).

    Search interface-enforced routing takes precedence over condition-based routing.

  4. When the query pipeline isn’t enforced by the search token or by the search interface, for each query:

    1. Starting with the oldest query pipeline with a condition, and then proceeding on chronologically, the Search API evaluates query pipeline conditions against the query. Query pipelines without a condition are ignored.

    2. If the query satisfies a query pipeline condition, that query pipeline is used. Remaining query pipeline conditions aren’t evaluated.

    3. If the query satisfies no single query pipeline condition, the Admin-QPLDefaultTag query pipeline is used, bypassing its condition (if any).

      Notes

      • A query can only be routed to a query pipeline that has no condition when that query pipeline is enforced by the search token or by the search interface.

      • The actual order of evaluation of query pipeline conditions should be considered unpredictable, reinforcing the recommendation that you should set mutually exclusive query pipeline conditions.

Condition-based routing is the most flexible query pipeline routing mechanism. This mechanism doesn’t normally require you to modify a single line of code; you can alter query pipeline routing rules by modifying conditions from the Coveo Administration Console.

Consider the following leading practices when using the condition-based query pipeline routing mechanism:

  • Always use positive operators (for example, is, contains, or matches) when creating a condition that aims at routing the queries originating from a specific search interface to a given query pipeline.

  • Ensure that no query pipeline is enforced by the search interface or search token (see Determining if a query pipeline is hardcoded). Note that the condition on a query pipeline enforced by the search interface or search token is ignored (see Routing rules).

  • Enforce the searchHub in the search token, and base the condition of each query pipeline in your Coveo organization on the searchHub value. The Admin-QPLDefaultTag query pipeline should typically have no condition.

  • Set the Admin-QPLDefaultTag tag on a query pipeline containing rules that are suitable for all kinds of queries sent to your Coveo organization (see Set a query pipeline as the default).

    Notes

    • Only one query pipeline can have the Admin-QPLDefaultTag tag.

    • While setting a condition on the default query pipeline is possible, this condition will be bypassed if a query fails to satisfy all query pipeline conditions.

    • You can’t delete the default query pipeline without first setting another query pipeline as default.

  • Delete unused query pipelines.

Note

In a usage analytics report, you can configure cards with the Query Pipeline, Search Origin 1 (page/hub), and Search Origin 2 (tab/interface) dimensions and the Search Event Count metric to see which page/hub/tab/interface uses which query pipeline.

Search interface-enforced routing

Consider using the search interface-enforced routing mechanism only when you want to:

  1. Control query pipeline routing through client-side logic in your search interfaces.

  2. Bypass the condition-based query pipeline routing mechanism.

Note

The search interface-enforced query pipeline routing mechanism shouldn’t be considered any more "secure" than condition-based routing.

Users could still bypass search interface-enforced query pipelines (for example, by interacting with the search interface programmatically, or by making their own HTTP requests against the Search API).

Search token-enforced routing

Consider using the search token-enforced routing mechanism only when you want to:

  1. Control query pipeline routing through the server-side logic that generates search tokens for your solution.

  2. Bypass all other query pipeline routing mechanisms (that is, condition-based and search interface-enforced). This can be useful in specific cases (for example, if you’re using query pipelines to enforce rules or filters for "security" reasons).

Important

When authenticating a query with a search token, the pipeline argument set on that token (if specified) takes precedence over the possible output of all other query pipeline routing mechanisms.

For example, if you specify a searchHub in a search token that enforces a query pipeline, this searchHub won’t affect the query pipeline routing in any way. The enforced pipeline will be used even if a query pipeline condition is based on the specified searchHub in your Coveo organization (see Search hub condition). However, the searchHub will still be used for usage analytics and Coveo ML purposes.