---
title: Set up a query pipeline
slug: '2757'
canonical_url: https://docs.coveo.com/en/2757/
collection: project-guide
source_format: adoc
---
# Set up a query pipeline
In a [Coveo organization](https://docs.coveo.com/en/185/), a given [query pipeline](https://docs.coveo.com/en/180/) is one of the possible paths by which a [query](https://docs.coveo.com/en/231/) can reach the [index](https://docs.coveo.com/en/204/).
Depending on the context, a query journeying through a certain query pipeline may be [altered in different ways](https://docs.coveo.com/en/1611/).

Each individual query pipeline can be configured with its own set of manually-defined relevance tuning rules, such as custom [query ranking expressions (QREs)](https://docs.coveo.com/en/1472/) or [thesaurus](https://docs.coveo.com/en/2742/) rules.
A given query pipeline can also be associated with one or more [Coveo Machine Learning (Coveo ML)](https://docs.coveo.com/en/188/) [models](https://docs.coveo.com/en/1012/).

Depending on the complexity of your search project, you may need to [configure one or more query pipelines](https://docs.coveo.com/en/1791/).

## Choose your query pipeline setup

There are three distinct query pipeline architectures: basic (only one query pipeline), advanced (several query pipelines), and hybrid (one or more query pipelines).
The following table can help you choose the appropriate architecture based on your specific requirements.

[%header,cols="3,^2"]
|===
^|Requirement
|Query pipeline setup

|Single audience
|[Basic](#basic-query-pipeline-setup)

|Many audiences
|[Advanced](#advanced-query-pipeline-setup) or [Hybrid](#hybrid-query-pipeline-setup)

|Distinct audiences sharing the same set of rules
|[Hybrid](#hybrid-query-pipeline-setup)
|===

### Basic query pipeline setup
> **Multiple language support**
>
> When creating your pipelines, it's best to take a proactive approach and add multilingual support from the beginning.
> 
> Implementing a [pipeline condition](#create-your-query-pipeline-rules-and-conditions) for language selection early on, even when only one language is currently supported, can help avoid potential pipeline issues in the future.

The simplest query pipeline setup is to route all queries to the _default_ query pipeline.
This architecture can work fine if your [Coveo organization](https://docs.coveo.com/en/185/) is only powering a single website or application.

In this basic query pipeline setup scenario, the same [relevance tuning rules](#create-your-query-pipeline-rules-and-conditions) may conditionally apply to all queries.

If you [associate](https://docs.coveo.com/en/3397/) a [Coveo ML](https://docs.coveo.com/en/188/) [Automatic Relevance Tuning (ART)](https://docs.coveo.com/en/1013/) model with the default query pipeline in this scenario, the model also processes all queries.
It will yield output based on contextual information such as the current language and [search hub](https://docs.coveo.com/en/1342/).

Similarly, a [Query Suggestion (QS)](https://docs.coveo.com/en/1015/) model that's [associated](https://docs.coveo.com/en/3398/) with the default query pipeline in this scenario will apply to all partial queries.

> **Important**
>
> A [Content Recommendation (CR)](https://docs.coveo.com/en/1016/) model should always be associated with its own distinct query pipeline, as its output is normally intended for a specific search hub (in this case, a recommendation interface).
> 
> This means that you'll need [more than one query pipeline](#advanced-query-pipeline-setup) to [leverage content recommendations](https://docs.coveo.com/en/3399/) in your search solution.

### Advanced query pipeline setup

If your [Coveo organization](https://docs.coveo.com/en/185/) powers many sites or applications targeting different groups of users, you should consider configuring a distinct query pipeline for each audience.
For example, you could configure one query pipeline for your support agents and one for your customers.
If you plan to leverage content recommendations in your solution, you should also configure a distinct query pipeline for each recommendation interface that you need.

In this advanced query pipeline setup scenario, different relevance tuning rules and [Coveo ML](https://docs.coveo.com/en/188/) models may apply to queries that [originate from different locations](#select-your-query-pipeline-routing-mechanism).

**Example**

You're using the same [Coveo organization](https://docs.coveo.com/en/185/) to power both an intranet site and an ecommerce site.

These sites target two different audiences, so you create two distinct query pipelines.
Each has different ART and QS models, thesaurus rules, and ranking expressions.

You also want to leverage content recommendations on each site, so you create two more query pipelines (one for each recommendation interface).

### Hybrid query pipeline setup

When you want the same subset of relevance tuning rules to apply to two distinct audiences, you may want to consider [routing queries](#select-your-query-pipeline-routing-mechanism) made by those two audiences to the same query pipeline rather than maintaining two almost identical query pipelines.
You would then associate conditions to rules which are specific to either audience.

In this hybrid query pipeline setup scenario, queries originating from different locations may be routed to the same query pipeline, but are then altered by different relevance tuning rules and [Coveo ML](https://docs.coveo.com/en/188/) models.

> **Note**
>
> This architecture can be combined with the [advanced query pipeline setup](#advanced-query-pipeline-setup).

**Example**

You're using the same [Coveo organization](https://docs.coveo.com/en/185/) to power [Insight Panels](https://docs.coveo.com/en/2898/) for your support agents and [case deflection](https://docs.coveo.com/en/2911/) panels for your customers.

You want to apply the same relevance tuning rules (such as thesaurus rules and ranking expressions) to queries made by both audiences.
However, because there's much less traffic on your internal support platform than your customer service portal, you decide to use a different set of [Coveo ML](https://docs.coveo.com/en/188/) models for each audience (for example, the ART and QS models you use for your customer service portal train on a shorter period of data).

Therefore, you route queries originating from your internal support platform and customer service portal to the same query pipeline, but set mutually exclusive conditions on each pair of ART and QS models, so those models only apply to queries made by their intended audience.

## Create your query pipeline rules and conditions

A query pipeline can contain various relevance tuning rules (such as thesaurus rules and ranking expressions).
Each of these rules should [have a condition](https://docs.coveo.com/en/1959/) to ensure that it only applies under specific circumstances.

> **Note**
>
> A [Coveo ML](https://docs.coveo.com/en/188/) model associated with a query pipeline can also have a condition.
> This can be useful when several models of the same kind are [associated with the same query pipeline](#hybrid-query-pipeline-setup), such as when a query pipeline contains two distinct ART or QS models.
> 
> A CR model should normally always be associated to its own, distinct query pipeline, as it's intended to process queries from a specific search hub (recommendation interface).

**Example**

For each query routed to the `Default` query pipeline, you want to slightly increase the relevance score of internal articles when the user performing the query is an employee.

In your [Coveo organization](https://docs.coveo.com/en/185/), internal articles [are indexed](https://docs.coveo.com/en/2679/) by the `Internal Documentation` Confluence [source](https://docs.coveo.com/en/246/).
Each query is authenticated by a search token whose [`userGroups`](https://docs.coveo.com/en/1369#usergroups-array-of-strings) property lists the groups to which the user performing the query belongs (this property corresponds to the `$groups` [query pipeline language (QPL)](https://docs.coveo.com/en/235/) object).

You create the following ranking expression in the `Default` query pipeline:

`boost ``@source=="Internal Documentation"`` by 30`

and associate this rule with the following condition:

`when $groups contains "Employee"`

## Select your query pipeline routing mechanism

The most flexible and recommended query pipeline routing mechanism is known as [condition-based routing](https://docs.coveo.com/en/1666#condition-based-routing-recommended).

Each query pipeline in your [Coveo organization](https://docs.coveo.com/en/185/) can be associated with [a single condition](https://docs.coveo.com/en/1959/), and every condition must be mutually exclusive.

> **Leading practice**
>
> Ideally, you should 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`](https://docs.coveo.com/en/13#operation/searchUsingPost-searchHub) value.
> 
> However, this isn't recommended for search tokens that are used in Coveo for Commerce solutions.
> See [Authenticate commerce requests](https://docs.coveo.com/en/o8ld0051/) for more information.

Assuming that no query pipeline is enforced by the search interface or authentication method ([API key](https://docs.coveo.com/en/105/) or [search token](https://docs.coveo.com/en/56/)), each query is routed to the query pipeline whose condition it satisfies.
Query pipelines without a condition aren't considered.

Queries that don't satisfy any conditions are routed to the **Default** query pipeline.

**Example**

In addition to the **Default** query pipeline, you've created three query pipelines in your [Coveo organization](https://docs.coveo.com/en/185/): **Agents**, **Customers**, and **Partners**.

You don't associate a condition with the **Default** query pipeline, and you associate mutually exclusive conditions with the other three:

[%header,cols="2"]
|===
|Query pipeline
|Condition

|**Agents**
|Search Hub is `InternalSearch`

|**Customers**
|Search Hub is `CommunitySearch`

|**Partners**
|Search Hub is `PartnerSearch`
|===

This means that any query whose `searchHub` isn't `InternalSearch`, `CommunitySearch`, or `PartnerSearch` will be routed to the **Default** query pipeline.

When a user performs a query from your customer service portal, the `searchHub` parameter of that query is automatically set to `CommunitySearch`.
Therefore, the query is routed to the **Customers** query pipeline.


## Leverage A/B testing

You can [configure A/B tests](https://docs.coveo.com/en/3255/) to temporarily allow some of the traffic that would normally be routed to query pipeline **A* to be routed to query pipeline *B** instead.
You can then inspect [Coveo Analytics reports](https://docs.coveo.com/en/266/) to compare certain key [metrics](https://docs.coveo.com/en/263/) (for example, Click Event Count, Visit Click Through, etc.), and determine which query pipeline [is performing the best](https://docs.coveo.com/en/1631#ab-testing-template).

A/B testing is a great way to ensure that a new query pipeline rule or [Coveo ML](https://docs.coveo.com/en/188/) model has a positive effect on your solution's relevance before allowing it to apply to a more significant proportion of queries

For more information, see the documentation on A/B testing [leading practices](https://docs.coveo.com/en/3255#leading-practices).

> **Note**
>
> In the context of an A/B test, the condition on query pipeline **B** is ignored.

**Example**

Many of the [items](https://docs.coveo.com/en/210/) in your `Internal Documentation` source undergo frequent but relatively insignificant updates.

Having reviewed the usage analytics reports, you have good reason to believe that when a query is routed to the **Default** query pipeline, the weight of the **Item last modification** ranking factor should be considerably reduced for these items.

You duplicate the **Default** query pipeline in its current state.
In the resulting **Default Copy** query pipeline, you create the following [ranking weights rule](https://docs.coveo.com/en/3412/):

`rank docDate: 1`

and associate this new rule with the following condition:

`when $source=="Internal Documentation"`

You set up an A/B test using the **Default** query pipeline as **A*, and the *Default Copy** query pipeline as **B**.
You route 30% of the traffic to **B**.

After enough time has passed, you inspect the analytics reports again.
The new rule appears to have solved the relevance issue that you had pinpointed, so you decide to apply it to the production pipeline.
You disable and delete the A/B test, and then delete the now-useless **Default Copy** query pipeline.

## What's next?

The [Use query ranking expressions](https://docs.coveo.com/en/2777/) article explains how you can use [query ranking expressions (QREs)](https://docs.coveo.com/en/1472/) to manually tune relevance in your search solution.