---
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.md) sent to your [Coveo organization](https://docs.coveo.com/en/185.md) are routed to a [query pipeline](https://docs.coveo.com/en/180.md) before they reach the [index](https://docs.coveo.com/en/204.md) (see [What's a query pipeline?](https://docs.coveo.com/en/1611.md)).
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.md).
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.

| Selection criteria | Query pipeline routing mechanisms | Query pipeline routing mechanisms | Query pipeline routing mechanisms |
|---|---|---|---|
| Selection criteria | 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](https://docs.coveo.com/en/183.md) (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)

1. When your setup uses [search tokens for authentication](https://docs.coveo.com/en/56.md), a query pipeline can be specified in each generated token (see the [`pipeline`](https://docs.coveo.com/en/56.md#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/).

1. 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.md#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.

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

1. When the query pipeline isn't 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.

   1. If the query satisfies a query pipeline condition, that query pipeline is used.
Remaining query pipeline conditions aren't evaluated.

   1. 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.md) 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.md#operators) (for example, `is`, `contains`, or `matches`) when you create a condition that routes 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.md)).
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.md#searchhub-string-optional), and [base the condition](https://docs.coveo.com/en/1666.md#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.md#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.md) 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.

1. 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:

1. Control query pipeline routing through the server-side logic that generates search tokens for your solution.

1. 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.md#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.md#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.md#search-hub)).
> However, the `searchHub` will still be used for usage analytics and Coveo ML purposes.