About the query pipeline routing algorithm

This is for:

Developer System Administrator

When a query is sent to the Search API, a routing algorithm is executed to determine which query pipeline in the target Coveo organization will process this query.

The following diagram illustrates the process of a query being routed to a query pipeline.[1]

Query Pipeline Routing Algorithm

1. The Last pipeline in organization refers to the pipeline whose position attribute is the highest of all the query pipelines in the Coveo organization.

When a query is sent to the Search API:

  1. If the search token enforces a pipeline, go to Step 4 using the search token-enforced pipeline (bypassing its condition, if any).

  2. Otherwise, if the search interface enforces a pipeline, go to Step 4 using the search interface-enforced pipeline (bypassing its condition, if any).

  3. Otherwise, for each pipeline that has a condition in the Coveo organization:

    1. If the query meets the condition, go to Step 4 using the current pipeline.

    2. Otherwise, if the current pipeline is the last pipeline in the organization, go to Step 4 using the default pipeline (bypassing its condition, if any).

    3. Otherwise, repeat Step 3.a using the next pipeline.

  4. Route the query through the pipeline.

Notes

  • Unless a specific query pipeline is enforced (see Step 1 and Step 2), pipelines with conditions are evaluated sequentially until a condition is satisfied (see Step 3). The order of evaluation of pipelines is based on the position attribute, which is automatically populated when a pipeline is created, and can’t be changed thereafter.

    In essence, this means that pipelines with conditions are typically evaluated from oldest to newest. This is slightly counter-intuitive, as pipelines are displayed in alphabetical order in the Coveo Administration Console. You can use the List query pipelines Search API operation to retrieve the actual position value of each pipeline in a Coveo organization.

  • It’s possible for the default query pipeline to have a condition. When this is the case, the default pipeline may be evaluated just like any other pipeline with a condition (see Step 3). However, if the query doesn’t satisfy the condition of any of the evaluated pipelines, it will ultimately be routed through the default pipeline, bypassing its condition.

Specify which pipeline a query uses

You can use the pipeline query parameter to specify which pipeline a query will use:

  • Its value is the name of the pipeline.

  • When no value is specified, a default pipeline is used.

Example

The following query will use the pipeline mypipeline:

GET /rest/search?q=@uri&pipeline=mypipeline HTTP/1.1

Because no value is specified for the pipeline parameter in the following query, the default pipeline is used:

GET /rest/search?q=@uri HTTP/1.1