Setting up Your Query Pipeline

In a Coveo organization, a given query pipeline can be seen as one of the possible paths a query can take to reach the index. Depending on the context, a query journeying through a certain query pipeline may be altered in different ways (see What’s a Query Pipeline?).

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 several Coveo Machine Learning (Coveo ML) models.

Depending on the complexity of your search project, you may need to configure one or more query pipelines (see Adding and Managing 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 several query pipelines). The following table can help you choose the appropriate architecture based on your specific requirements.

Requirement Query pipeline setup
Single audience Basic
Many audiences Advanced or Hybrid
Distinct audiences sharing the same set of rules Hybrid

Basic Query Pipeline Setup

The most simple 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 (see Create your Query Pipeline Rules and Conditions).

If you associate a Coveo ML Automatic Relevance Tuning (ART) model to the default query pipeline in this scenario, the model also processes all queries, yielding output based on contextual information such as the current language, search hub, and tab (see Adding and Managing Coveo Machine Learning Models).

In a similar fashion, a Coveo ML Query Suggestions (QS) model associated to the default query pipeline in this scenario applies to all partial queries (see Create a QS Model).

A Coveo ML Event Recommendations (ER) model should always be associated to its own distinct query pipeline, as its output is normally intended for a specific search hub (i.e., a recommendation interface).

Therefore, if you want to leverage event recommendations in your search solution, you very likely need more than one query pipeline (see Advanced Query Pipeline Setup).

See also Adding and Editing Coveo Machine Learning Event Recommendations Models in a Query Pipeline.

Advanced Query Pipeline Setup

If your Coveo organization is powering many websites and/or applications targeting different groups of end users, you should typically consider configuring a distinct query pipeline for each audience (e.g., one for your support agents, and one for your customers). If you plan to leverage Coveo ML Event Recommendations in your solution, you should also configure a distinct query pipeline for each recommendation interface you need (see Adding and Editing Coveo Machine Learning Event Recommendations Models in a Query Pipeline).

In this advanced query pipeline setup scenario, different relevance tuning rules and Coveo ML models may apply to queries originating from different locations (see Select your Query Pipeline Routing Mechanism Routing).

You’re using the same Coveo organization to power an intranet site and an e-commerce site.

Those two sites obviously target two different audiences. Therefore, you create two distinct query pipelines with different ART and QS models, thesaurus rules, ranking expressions, etc.

You also want to leverage Coveo ML Event Recommendations in each of those two sites. Therefore, you create two more query pipelines (one for each event recommendations 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 (see Select your Query Pipeline Routing Mechanism Routing).

In this hybrid query pipeline setup scenario, queries originating from different locations may be routed to the same query pipeline, but be altered by different relevance tuning rules and Coveo ML models.

This architecture can be combined with the advanced query pipeline setup (see Advanced Query Pipeline Setup).

You’re using the same Coveo organization to power insight panels for your support agents, as well as case-deflection panels for your customers.

You want to apply the same relevance tuning rules (e.g., thesaurus, ranking expressions, etc.) to queries made by both audiences. However, since there’s much less traffic on your internal support platform than on your customer service portal, you decide to use a different set of Coveo ML models for each audience (e.g., 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 from your customer service portal to the same query pipeline, but set mutually exclusive conditions on each pair of ART and QS models, so those models apply only to queries made by their intended audience.

Create Your Query Pipeline Rules and Conditions

A query pipeline can contain various relevance tuning rules (e.g., ranking expressions, thesaurus, etc.). Normally, each of those rules should have a condition to ensure it only applies under specific circumstances (see Adding and Managing Query Pipeline Conditions).

A Coveo ML model associated to a query pipeline can also have a condition. This can be useful when several models of the same kind are associated to the same query pipeline, such as when a query pipeline contains two distinct ART and/or QS models (see Hybrid Query Pipeline Setup).

An Event Recommendations model should normally always be associated to its own, distinct query pipeline, as it’s intended to process queries from a specific search hub (i.e., a recommendation interface).

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

In your Coveo organization, internal articles are all indexed by a Confluence source named Internal Documentation (see Locating and Indexing Content). Each query is authenticated by a search token whose userGroups property lists the groups the end user performing the query belongs to (this property corresponds to the $groups query pipeline language (QPL) object).

Therefore, you create the following ranking expression in the Default query pipeline:

boost @source=="Internal Documentation" by 30

And associate this rule to 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 (see Condition-Based Routing (Recommended)).

Each query pipeline in your Coveo organization can be associated to a single condition (see Adding and Managing Query Pipeline Conditions). A query pipeline condition is often based on the value of the searchHub query parameter, although conditions relying on other query parameters can be equally valid, as long as query pipeline conditions remain mutually exclusive.

Assuming no query pipeline is being enforced by the search interface or search token, each query is routed to the query pipeline whose condition it satisfies (query pipelines lacking a condition aren’t considered). Queries that don’t satisfy the condition of any query pipeline are routed to the Default query pipeline.

In addition to the Default query pipeline, you have created three query pipelines in your Coveo organization: Agents, Customers, and Partners.

You associate mutually exclusive conditions to those query pipelines, as shown in the following table:

Query pipeline Condition
Agents Search Hub is InternalSearch
Customers Search Hub is CommunitySearch
Partners Search Hub is PartnerSearch

You associate no condition to the Default query pipeline. This means that any query whose searchHub isn’t InternalSearch, CommunitySearch, or PartnerSearch will be routed to the Default query pipeline.

When an end 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.

Sometimes, such as when filters need to apply to queries for security reasons, your Coveo Solution Architect may suggest that you enforce query pipelines in search tokens, rather than using the typically recommended condition-based query pipeline routing mechanism (see Search Token Enforced Routing).

While it’s also possible to enforce query pipelines in the code of your search interface, doing so offers no advantage over condition-based or search token-enforced query pipeline routing, and should therefore typically be avoided in a production environment (see Search Interface Enforced Routing).

Leverage A/B Testing

You can configure A/B tests to temporarily allow a portion of traffic that would normally be routed to query pipeline A to be routed to query pipeline B instead (see Adding and Managing A/B Tests). You can then inspect Coveo Usage Analytics (Coveo UA) reports to compare certain key metrics (e.g., Click Event Count, Visit Click Through, etc.), and determine which query pipeline is performing best (see Analyzing the Performance of Pipeline A Vs Pipeline B).

A/B testing is a great way to assert that a new query pipeline rule or Coveo ML model is actually affecting relevance positively in your solution before allowing this rule to apply to a more significant part of queries (see A/B Tests Leading Practices).

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

Having reviewed usage analytics reports, you have good reasons 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 items in the Internal Documentation source, as many of those items undergo frequent, yet relatively insignificant updates.

You duplicate the Default query pipeline in its current state. In the resulting Default Copy query pipeline, you create the following ranking weights rule (see Adding and Managing Query Pipeline Ranking Weight Rules):

rank docDate: 1

and associate this new rule to the following condition:

when $source=="Internal Documentation"

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

After a while (e.g., a week or month later), you inspect analytics reports and realize that your new ranking weights rule appears to have solved the relevance issue you had pinpointed before. You decide to apply this new rule 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 next article in this section explains how you can use query ranking expressions (QREs) to manually tune relevance in your search solution (see Using Query Ranking Expressions).

Recommended Articles