Query Pipeline Routing Mechanisms and Rules

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 two different query pipeline routing mechanisms.

Usually, you will 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 search interface-enforced routing, ignoring query pipeline conditions altogether.

The search token-enforced routing mechanism has been made unavailable in the October 21, 2020 Coveo Platform update following this critical update.

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

Selection criteria   Query pipeline routing mechanisms
Condition-based routing1 Search interface-enforced routing
Routing priority Lowest Highest
Implementation by Coveo Cloud administrator Developer
Implementation in Coveo Administration Console
(no code required)
Search interface configuration
(client-side code)

1: Recommended.

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.


  1. 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.

  2. When the query pipeline isn’t enforced 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).

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

    • In the Coveo Administration Console, query pipelines are sorted alphabetically, and can’t be sorted by creation or last modification date. Therefore, 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 (see Manage Query Pipeline Conditions).

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

  • Ensure that no query pipeline is enforced by the search interface (see Determining if a Query Pipeline Is Hardcoded).

    The condition on a query pipeline enforced by the search interface is ignored (see Routing Rules).

  • Set mutually exclusive conditions on each query pipeline. A good practice is to base the condition of each query pipeline on a unique search hub 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 one).

    • 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.

    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.

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 (e.g., by interacting with the search interface programmatically, or by making their own HTTP requests against the Search API).

Recommended Articles