Query Pipeline Routing Mechanisms and Rules

All queries sent to your Coveo Cloud organization are routed to a query pipeline before they reach the index (see What Is a Query Pipeline?). Depending on your needs, you can leverage 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 (see Condition-Based Routing (Recommended)). 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.

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

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

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

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

   Coveo JavaScript Search Framework 1.0.20 (July 2015)

   Coveo JavaScript Search Framework 0.9.1530.5 (June 2015)

   Prior Coveo JavaScript Search Framework versions were by default enforcing the default value on the pipeline option when none was set on the SearchInterface component, thus overwriting any condition set on the administration console Query Pipelines page.

3. When the query pipeline is not 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 are not evaluated.

   3. If the query satisfies no single query pipeline condition, the 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 token or by the search interface.
   • In the Coveo Cloud administration console, query pipelines are sorted alphabetically, and cannot be sorted by creation or last modification date. The actual order of evaluation of query pipeline conditions should thus be considered unpredictable, reinforcing the recommendation that you should set mutually exclusive query pipeline conditions.

Condition-Based Routing (Recommended)

Condition-based routing is the most flexible query pipeline routing mechanism. This mechanism does not normally require you to modify a single line of code; you can alter query pipeline routing rules by modifying conditions from the Coveo Cloud administration console (see Adding and Managing 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 or search token (see Determining if a Query Pipeline Is Hardcoded).

  The condition on a query pipeline enforced by the search interface or search token 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 query pipeline should typically have no condition.

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

  • Only one query pipeline can have the 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 cannot 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.

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 (i.e., condition-based and search interface-enforced). This can be useful in specific cases (e.g., if you are using query pipelines to enforce rules or filters for “security” reasons).