---
title: Query pipeline routing mechanisms and rules
slug: '1666'
canonical_url: https://docs.coveo.com/en/1666/
collection: tune-relevance
source_format: adoc
---
# Query pipeline routing mechanisms and rules
All [queries](https://docs.coveo.com/en/231/) sent to your [Coveo organization](https://docs.coveo.com/en/185/) are routed to a [query pipeline](https://docs.coveo.com/en/180/) before they reach the [index](https://docs.coveo.com/en/204/) (see [What's a query pipeline?](https://docs.coveo.com/en/1611/)).
Depending on your needs, you can leverage different query pipeline routing mechanisms.

Usually, you'll want to use [condition-based routing](#condition-based-routing-recommended) to take advantage of the flexibility offered by [query pipeline conditions](https://docs.coveo.com/en/2793/).
However, some situations may require you to enforce a specific routing, ignoring query pipeline conditions altogether (see [Search interface-enforced routing](#search-interface-enforced-routing) and [Search token-enforced routing](#search-token-enforced-routing)).

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

[cols="4"]
|===
.2+.^h|Selection criteria
3+^h|Query pipeline routing mechanisms

^h|Condition-based routing (recommended)
^h|Search interface-enforced routing
^h|Search token-enforced routing

|**Routing priority**
^|Lowest
^|Medium
^|Highest

|**Implementation by**
^|Coveo administrator
^|Developer
^|Developer

|**Implementation in**
^|[Coveo Administration Console](https://docs.coveo.com/en/183/)  
(no code required)
^|Search interface configuration  
(client-side code)
^|Search token generation logic  
(server-side code)
|===

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.


![Pipeline Selection Diagram | Coveo](https://docs.coveo.com/en/assets/images/tune-relevance/diagram-pipeline-selection.png)

. When your setup uses [search tokens for authentication](https://docs.coveo.com/en/56/), a query pipeline can be specified in each generated token (see the [`pipeline`](https://docs.coveo.com/en/56#pipeline-string-optional) 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](#search-token-enforced-routing) takes precedence over all other query pipeline routing mechanisms.

> **Note**
>
> You can validate whether a search token enforces a query pipeline by decoding this search token with a tool such as [JWT.IO](http://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](https://docs.coveo.com/en/1959#matchesdoesnt-match)) even if a different pipeline is enforced in the interface.

> **Note**
>
> Use 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`](https://coveo.github.io/search-ui/components/searchinterface.html#options.pipeline) component), this query pipeline is used, bypassing its condition (if any).

[Search interface-enforced routing](#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 ![Default query pipeline tag | Coveo](tune-relevance/query-pipeline-default-tag.png) 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](https://docs.coveo.com/en/1959/) from the Coveo Administration Console.

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

* Always use positive [operators](https://docs.coveo.com/en/1959#operators) (for example, `is`, `contains`, or `matches`) 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](https://docs.coveo.com/en/168/)).
Note that the condition on a query pipeline enforced by the search interface or search token is ignored (see [Routing rules](#routing-rules)).

* Enforce the `searchHub` [in the search token](https://docs.coveo.com/en/56#searchhub-string-optional), and [base the condition](https://docs.coveo.com/en/1666#condition-based-routing-recommended) of each query pipeline in your Coveo organization on the `searchHub` value.
The ![Default query pipeline highlighted tag | Coveo](tune-relevance/query-pipeline-default-tag.png) query pipeline should typically have no condition.

* Set the ![Default query pipeline tag | Coveo](tune-relevance/query-pipeline-default-tag.png) 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](https://docs.coveo.com/en/1791#set-a-query-pipeline-as-the-default)).

> **Notes**
>
> * Only one query pipeline can have the ![Default query pipeline tag | Coveo](tune-relevance/query-pipeline-default-tag.png) 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](https://docs.coveo.com/en/263/) 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).

> **Important**
>
> When authenticating a query with a search token, the [`pipeline`](https://docs.coveo.com/en/56#pipeline-string-optional) 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`](https://docs.coveo.com/en/56#searchhub-string-optional) 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](https://docs.coveo.com/en/1959#search-hub)).
> However, the `searchHub` will still be used for usage analytics and Coveo ML purposes.