-
Build Query Pipelines
- What's a Query Pipeline
- Routing Mechanisms and Rules
- Deploy a Query Pipeline
- Order of Execution of Query Pipeline Features
- Troubleshoot Query Pipeline Rules
- Manage Query Pipeline Rules
- Code Query Pipeline Rules
- Test Query Pipeline Changes
- Export and Import Query Pipeline Elements
- Query Pipeline Language (QPL)
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 (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.
Selection criteria | Query pipeline routing mechanisms | ||
---|---|---|---|
Condition-based routing1 | Search interface-enforced routing | Search token-enforced routing | |
Routing priority | Lowest | Medium | Highest |
Implementation by | Coveo Cloud 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 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.
-
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.
-
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 thepipeline
option when none was set on theSearchInterface
component, therefore overwriting any condition set on the Administration Console Query Pipelines page. -
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.
-
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 (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 (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 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 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 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.