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 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 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) |
|
Before the introduction of the Safer Conditional Pipeline Routing critical update, it was possible to bypass all routing mechanisms by setting the |
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.
-
When your setup uses search tokens for authentication, a query pipeline can be specified in each generated token (see the
pipelineparameter), 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.
-
If a query pipeline is set in the Coveo JavaScript Search Framework interface code (typically on the
SearchInterfacecomponent), this query pipeline is used, bypassing its condition (if any).Search interface-enforced routing takes precedence over condition-based routing.
-
When the query pipeline isn’t enforced by the search token or by the search interface, for each query:
-
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.
-
If the query satisfies a query pipeline condition, that query pipeline is used. Remaining query pipeline conditions aren’t evaluated.
-
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.
-
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 (Recommended)
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:
-
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
searchHubin the search token, and base the condition of each query pipeline in your Coveo organization on thesearchHubvalue. 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 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 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:
-
Control query pipeline routing through client-side logic in your search interfaces.
-
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). |
Search Token-Enforced Routing
Consider using the search token-enforced routing mechanism only when you want to:
-
Control query pipeline routing through the server-side logic that generates search tokens for your solution.
-
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’re using query pipelines to enforce rules or filters for "security" reasons).
|
When authenticating a query with a search token, the For example, if you specify a |