Set up a query pipeline
Set up a query pipeline
In a Coveo organization, a given query pipeline is one of the possible paths by which a query can reach the index. Depending on the context, a query journeying through a certain query pipeline may be altered in different ways.
Each individual query pipeline can be configured with its own set of manually-defined relevance tuning rules, such as custom query ranking expressions (QREs) or thesaurus rules. A given query pipeline can also be associated with one or more Coveo Machine Learning (Coveo ML) models.
Depending on the complexity of your search project, you may need to configure one or more query pipelines.
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.
| Requirement | Query pipeline setup |
|---|---|
Single audience |
|
Many audiences |
|
Distinct audiences sharing the same set of rules |
Basic query pipeline setup
The simplest query pipeline setup is to route all queries to the default query pipeline. This architecture can work fine if your Coveo organization is only powering a single website or application.
In this basic query pipeline setup scenario, the same relevance tuning rules may conditionally apply to all queries.
If you associate a Coveo ML Automatic Relevance Tuning (ART) 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.
Similarly, a Query Suggestion (QS) model that’s associated with the default query pipeline in this scenario will apply to all partial queries.
|
A Content Recommendation (CR) 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 to leverage content recommendations in your search solution. |
Advanced query pipeline setup
If your Coveo organization 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 models may apply to queries that originate from different locations.
You’re using the same Coveo organization 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 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 models.
|
Note
This architecture can be combined with the advanced query pipeline setup. |
You’re using the same Coveo organization to power Insight Panels for your support agents and case deflection 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 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 to ensure that it only applies under specific circumstances.
|
|
Note
A Coveo ML 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, 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). |
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, internal articles are indexed by the Internal Documentation Confluence source.
Each query is authenticated by a search token whose userGroups property lists the groups to which the user performing the query belongs (this property corresponds to the $groups query pipeline language (QPL) 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.
Each query pipeline in your Coveo organization can be associated with a single condition, and every condition must be mutually exclusive.
|
Leading practice
Ideally, you should enforce the However, this isn’t required for search tokens that are used in Coveo for Commerce solutions. See Authenticate commerce requests for more information. |
Assuming that no query pipeline is enforced by the search interface or authentication method (API key or search token), 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.
In addition to the Default query pipeline, you’ve created three query pipelines in your Coveo organization: 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:
| Query pipeline | Condition |
|---|---|
Agents |
Search Hub is |
Customers |
Search Hub is |
Partners |
Search Hub is |
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 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 Usage Analytics (Coveo UA) reports to compare certain key metrics (for example, Click Event Count, Visit Click Through, etc.), and determine which query pipeline is performing the best.
A/B testing is a great way to ensure that a new query pipeline rule or Coveo ML 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.
|
|
Note
In the context of an A/B test, the condition on query pipeline B is ignored. |
Many of the items 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:
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 article explains how you can use query ranking expressions (QREs) to manually tune relevance in your search solution.
Very useful
Not really
Very useful
Not really