Query pipeline routing mechanisms and rules
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’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 |
Search interface configuration |
Search token generation logic |
Note
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
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.
NoteYou can validate whether a search token enforces a query pipeline by decoding this search token with a tool such as JWT.IO.
-
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.
NoteWe 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.
-
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.
-
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).
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 (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:
-
Always use positive operators (for example,
is
,contains
, ormatches
) 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 thesearchHub
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 organization (see Set a query pipeline as the default one).
Notes-
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.
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:
-
Control query pipeline routing through client-side logic in your search interfaces.
-
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:
-
Control query pipeline routing through the server-side logic that generates search tokens for your solution.
-
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).
When authenticating a query with a search token, the For example, if you specify a |