Query Pipeline Routing Mechanisms and Rules

All queries sent to your Coveo Cloud organization go through a query pipeline (see What Is a Query Pipeline?). You can use different mechanisms to determine into which query pipeline queries are routed.

The choice of the mechanism depends essentially on how easily you can get a developer to change code in your Coveo setup and if you want to take advantage of the routing flexibility that query pipeline conditions offer. The following table summarizes the main routing mechanism selection criteria.

Selection criteria   Query pipeline routing mechanisms
Query pipeline conditions Search token1 Hard-coded in search interface1
Routing priority 3 1 2
Implementation by Coveo Cloud administrator Developer Developer
Implementation in Coveo Cloud administration console Search token Search interface code
Applies to all queries Matching a condition With the token From the search interface
Dynamic routing Yes No No
Client-side modification No No Yes

Note 1: You cannot perform A/B tests with hardcoded pipelines or pipelines included in search tokens.

When using a search token, the pipeline query parameter value (if specified) takes precedence over the possible output of all other query pipeline routing mechanisms (see pipeline).

For instance, the pipeline searchHub value you specified in the same search token would be bypassed even if you linked the hub to the query pipeline with a condition (see Search Hub Condition).

Review the following leading practices and rules to better understand how queries are routed to a given query pipeline and which mechanism is the best for your needs.

Routing Rules

The following diagram and rules describe the routing rules.

diagram_pipeline_selection

  1. When your setup uses a search token generated by the REST Search API (see Search Token Authentication), a query pipeline can be specified in the search token (see Using a mandatory query pipeline) in which case this query pipeline is used.

    The search token pipeline routing mechanism has precedence on any JavaScript hard coded pipeline and any condition set in the Coveo Cloud administration console Query Pipelines page (see Coded in Search Token).

    You can check if the search token of your search interface includes a query pipeline by decoding the search token with an online site such as JWT.IO.

  2. If a query pipeline is set in the Coveo JavaScript search interface code on the SearchInterface component (see SearchInterface Component), this pipeline is used, overwriting any condition set in the Coveo Cloud administration console Query Pipelines page (see Hard Coded in the Search Interface).

    Coveo JavaScript Search Framework 1.0.20 - July 2015 

    Coveo JavaScript Search Framework 0.9.1530.5 - June 2015 

    Prior Coveo JavaScript Search Framework versions were by default forcing a default pipeline value when none is set on the SearchInterface component, thus overwriting any condition set in the administration console Query Pipelines page.

  3. When the query pipeline is not hard coded, for each query, the condition associated with the query pipelines defined in the administration console Query Pipelines page (see Coded in Search Token).

    The Coveo Cloud search API evaluates each query as follows:

    1. Pipelines with conditions are evaluated following the pipeline name alphanumerical order until a condition matches.

    2. The first pipeline with a matching condition is used. The other pipelines are not evaluated.

    3. When none of the above situations apply, the query is routed to the Admin-QPLDefaultTag pipeline.

      Pipelines with no condition are not evaluated. They are used only when hard coded in a search token or in a search interface.

Consider this method when you want to take advantage of dynamic query pipeline routing and easily change the query pipeline routing simply by adapting query pipeline conditions from the Coveo Cloud administration console (see Managing Query Pipeline Conditions). Query pipeline condition based routing is the most flexible mechanism and does not require modifying a single line of code.

Consider the following leading practices when using this method:

  • Ensure a pipeline is not hard coded in the search interface (see Determining if a Query Pipeline is Hardcoded).

    A hard coded pipeline has priority, so query pipeline conditions are never applied (see Routing Rules).

  • Set mutually exclusive conditions on the pipelines.

  • Attribute the Admin-QPLDefaultTag tag to a pipeline containing rules that are suitable for all kinds of queries sent to your Coveo Cloud Organization (see Set a query pipeline as the default one).

    • Only one pipeline can have the Admin-QPLDefaultTag tag.

    • Conditions on the default pipeline are ignored. Avoid setting conditions on the default pipeline to minimize risks someone would assume they would be taken into account.

    • You cannot remove the default pipeline without first setting another pipeline as the default pipeline.

  • Delete unused query pipelines.

    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 Query Count metric to see which page/hub/tab/interface uses which pipeline.

Hard Coded in the Search Interface

Consider this method when a developer can easily add or change the search interface code and you want to use the same query pipeline for all queries made from this search interface (see Query Pipeline Deployment Overview and SearchInterface Component).

Use this method when:

  • You want all queries from a search interface to use the same query pipeline.

  • You can easily edit the search interface HTML or JavaScript code.

Coded in Search Token

Consider this method when your setup already uses search tokens and you want to use the same query pipeline for all queries (see Creating a Search Token). Switching to use search token just to specify a fixed query pipeline is probably excessive (see Search Token Authentication). This method is very secure, as the search API would not respond to queries sent with a search token that would have been tampered with.

Use this method when:

  • You already use search tokens in your configuration.

  • A developer can add the pipeline to the token.

  • You want all queries sent with this token to go through the same pipeline.