Manage query pipeline conditions

This is for:

Developer System Administrator

A query pipeline condition determines when an associated query pipeline, rule, or model applies to a query and is essential for ensuring optimal search relevance. Conditions are built from three parts: an object, an operator, and usually one or more values.

  • The object identifies what you want to evaluate (for example, Search Hub, Device, or a specific Context key).

  • The operator defines how to compare it (for example, is, contains, or matches). Some operators, such as Is empty and Is populated, don’t require a value.

  • The value is what you compare against.

On the Conditions (platform-ca | platform-eu | platform-au) page, you can view, create, and manage conditions.

Conditions page | Coveo Platform

When and why to use conditions

Think of conditions as safety rails that keep query pipelines and their components efficient and predictable. They ensure focused behavior and avoid changes that apply globally to all queries. With conditions, you control when to apply a pipeline or a component, and to which queries, based on specific criteria. Without conditions, they would apply to all targeted queries.

Example

Your company, Barca Sports, has a self-service support portal for equipment assembly and troubleshooting. You previously added a thesaurus rule to handle common misspellings of product names. You notice in your Coveo Analytics report that a recurring theme is for users to query googles instead of goggles when searching for ski goggles on their mobile devices. To make sure that this particular thesaurus rule is applied to queries from mobile devices, you create a condition based on the Device object with the value mobile.

Condition example on rule list page | Coveo Platform

Conditions are also important for pipeline routing. When condition-based routing is used, pipelines are evaluated in their configured order, and the first pipeline whose condition matches handles the query. If no pipeline condition matches, the default pipeline is used as a fallback.

Note

A condition can be used by multiple pipelines and components. However, each query pipeline, rule, and ML model association can only be associated with a single condition.

Prerequisites

To get started with conditions, make sure you have:

Create a condition

Conditions can be created in different areas of the Coveo Administration Console, such as the Conditions (platform-ca | platform-eu | platform-au) page, the Configuration tab of a query pipeline, or the Add/Edit panel of a query pipeline rule.

Tip
Tip

Use clear, specific conditions to target behavior precisely and to prevent unintended interactions between pipelines. Avoid leaving multiple query pipelines without conditions, since a pipeline with no condition can apply to all queries and override pipelines that appear after it.

  1. Access the Add a condition panel by doing one of the following:

  2. In the Description field, enter a description to help you identify the condition later.

  3. Click the first dropdown menu, and then select the object on which the condition is based.

    1. (Optional) For a context object, click Context.

    2. Under the Context type dropdown menu, select String or Boolean.

    3. In the Context key field, enter a value.

      Important

      The keys used in the Context object are case sensitive.

  4. Click the second dropdown menu, and then select an operator to apply between the selected object and the value.

  5. Click the third dropdown menu (if available), and then provide values by either selecting a suggested value or manually entering a value and selecting Enter.

  6. (Optional) Click +Add to add another condition:

    1. In the dropdown menu that appears after the first condition, select the AND or the OR operator to specify how this second configuration will be linked to the first one.

    2. Repeat the steps to define the second condition configuration.

  7. Click Add condition.

View a condition

  1. On the Conditions (platform-ca | platform-eu | platform-au) page, select the checkbox next to the condition that you want to view, and then in the Action bar, click View.

  2. In the Configuration tab of the View a condition panel that appears, review the condition description and configuration.

  3. In the Associations tab, review which pipelines, rules, and ML models use this condition.

  4. (Optional) Click Manage condition on the upper-right corner of the panel, and then select Edit to access the Edit a condition panel.

    Note

    If you don’t see this option, you may not have the required privileges to edit conditions.

Associations

Conditions can be associated with query pipelines, rules, and ML models. You can review this information in the Associations tab of the View a condition panel.

  1. Access the Associations tab of a condition by doing one of the following:

    • On the Conditions (platform-ca | platform-eu | platform-au) page, click See associations on the line of the condition you want to view.

    • In the View/Edit a condition panel of a condition, click the Associations tab.

  2. Review the list of associated pipelines, rules, and ML models.

Edit a condition

Important

Editing a condition affects all associated pipelines, rules, or models immediately after saving the changes.

  1. On the Conditions (platform-ca | platform-eu | platform-au) page, select the checkbox next to the condition that you want to edit, and then in the Action bar, click Edit.

  2. In the Description field of the Edit a condition panel that appears, edit the description.

  3. Under Condition, do any of the following:

    1. Edit the current condition configuration by changing the object, operator, and/or values.

    2. Click dots on the right side of the condition configuration, and then select Delete or Duplicate to remove or duplicate the condition configuration.

    3. Click +Add to add another condition configuration.

      1. In the dropdown menu that appears after the previous condition, select the AND or the OR operator to specify how this second configuration will be linked to the first one.

      2. Follow the steps to define the condition.

  4. (Optional) Click Manage condition on the upper-right corner of the panel.

    1. Select View to review the condition details in read-only mode.

    2. Select Edit code to edit the condition with code.

    3. Select Delete to delete the condition, and then click Delete again on the confirmation message that appears.

  5. Click Save.

Edit a condition with code

You can edit a condition that respects the query pipeline language (QPL) syntax.

  1. On the Conditions (platform-ca | platform-eu | platform-au) page, select the checkbox next to the condition that you want to edit, and then in the Action bar, click Edit code.

  2. In the Edit a condition with code panel that appears, enter the condition using QPL syntax.

  3. Click Save.

Note

The object on which the condition is based appears differently in the Add/Edit a condition panel dropdown menu than it does as a QPL object on the code editor.

For example, in the Add/Edit a condition panel:

Add a condition | Coveo

In the Edit a condition with code panel:

Edit a condition with code | Coveo

Delete a condition

Important

Deleting a condition removes the condition from all query pipelines, rules, and models using that condition.

  1. On the Conditions (platform-ca | platform-eu | platform-au) page, select the checkbox next to the condition that you want to delete, and then in the Action bar, click Delete.

  2. On the Delete this condition? message that appears, click Delete again.

Reference

The following sections describe the available condition objects and operators that you can use when creating query pipeline conditions.

Objects

The Original objects (that is, Original Advanced Query, Original Constant Query, Original Disjunction Query, Original Large Query, and Original Query) use the expression as it was sent prior to being processed by a query pipeline. The Original objects also have regular counterparts, and both option types can be selected in the object dropdown menu of the Add a condition panel.

Example

A user searches dashcam on your support page. You have a thesaurus rule that replaces dashcam with dash cam.

  • If the condition to your rule is Original Query is dash cam, it won’t be met since the original user query was dashcam.

  • If the condition to your rule is Query is dash cam, the condition will be met since the query is processed by the thesaurus rule before being evaluated against the condition.

Advanced Query/Original Advanced Query

Hidden expression used to narrow the search results made by the user.

Example

When the user selects Word Document in a Type facet, the advanced query can be @filetype==doc.

The Advanced Query/Original Advanced Query object is used to create conditions based on a Facet.

To create a condition based on a DynamicFacet, you must use the Filter query from facets object.

Browser

The type of browser on which the search interface runs, such as chrome, firefox, ie, or safari.

Constant Query/Original Constant Query

Hidden expression used to narrow the search results selected by the user.

Example

When the user selects the Support Cases search interface tab, the constant query is (@objecttype==('CaseComment','Case')).

Context

One or more parameters passed by the search interface in a JSON key/value pair format.

Your search interface must pass custom context information with the query.

Example

Your custom context is used to differentiate users by their role relative to your products. Therefore, you defined your key as userRole and the possible values as end-user, administrator, or developer.

You can define a condition using this key, and one or more of these values.

Device

The type of device on which the search interface runs, such as desktop, mobile, phone, or tablet.

Disjunction Query/Original Disjunction Query

Hidden expression applied with a logical OR operator with other expressions and used to expand the search results, such as, in rare cases, where some search results that don’t match the other expressions must be injected.

Filter Query From Facets

Hidden expression used to narrow the search results made by the user.

Examples

  • You want to apply a rule when the @sourcename facet field has the value Barca selected; therefore, you create a condition with the following expression:

    $facetsFilter is "@sourcename==(Barca)"

  • You want to apply a rule when the @sourcename facet field has the value Jira and the @filetype facet field has the value Jiraissue selected; therefore, you combine the two conditions with the following expression:

    $facetsFilter is "@sourcename==(Jira) @filetype==(Jiraissue)"

The Filter query from facets object is used to create conditions based on a DynamicFacet.

To create a condition based on a Facet, you must use the Advanced Query/Original Advanced Query object.

Groups

When the user performing the query is authenticated through the REST Search API, the name of the user groups, such as the domain\group form for a Windows user.

Identity

When the user performing the query is authenticated through the REST Search API, the name of the user, such as in the domain\name form for a Windows user.

Language

The language part of the locale query parameter (see Locale).

Example

When the locale query parameter is en-US, the language is en.

Large Query/Original Large Query

Contextual text part of the query which typically contains a case description, a long textual query, or any other form of text that can help refine a query.

Locale

The value of the locale query parameter passed by the search interface, for example the browser’s configured value (such as en-US or fr-CA).

Operating System

The operating system of the device on which the search interface runs, such as android, blackberry, ios, osx, or windows.

Query/Original Query

What the end user searches for such as the keywords entered in the search box.

Query Time UTC

The UTC time at which the query was made.

Example

On your ecommerce website, you want to show certain products at the top of the search results page during your Boxing Day sale. So, you create a pipeline or pipeline rule with the following condition: Query Time UTC is between Dec 25, 2019 12:00 AM and Dec 27, 2019 11:59 PM.

Recommendation

The identifier of the recommendation interface from which the query originates.

Note

You can create a condition to ensure that queries originating from a specific recommendation interface are routed to a query pipeline that contains the Content Recommendation (CR) model you want to use to output recommendations for that interface.
Example

On your ecommerce website, you have a side-panel that lists your top selling products that’s identified as RecommendedProducts.

Referrer

The third level of origin of the query, typically the URL of the page that linked to the search interface from which the query originates (see Origin 3 (Referrer)).

Search Hub

The search interface from which the query was made.

Tab

The search interface tab from which the query was made.

Operators

Important

Always use positive operators (for example, is, contains, or matches) when you create a condition that routes queries originating from a specific search interface to a given query pipeline.

Is/Is not

Whether the condition object on which the condition is based is exactly the value to filter.

The Is/Is not operators are:

  • Case insensitive

  • Interpreting the value to filter on as a string.

Examples

  • Search hub is Customer Service Portal

  • Device is not iPhone

Contains/Doesn’t contain

Whether the condition object on which the condition is based contains the value to filter.

The Contains/Doesn’t contain operators are:

  • Case insensitive

  • Interpreting the value to filter on as a string.

Examples

  • Search hub contains Service

  • Device doesn’t contain iPhone

Matches/Doesn’t match

Whether the condition object on which the condition is based matches the regular expression (regex) to filter.

The Matches/Doesn’t match operators:

  • Are case sensitive.

  • Interpret the value to filter on as a regex.

  • Evaluate to true only if the entire value of the condition object matches the regex.

Examples

  • Query matches ^(?i)how do i.*$: Checks if the query starts with how do i, case-insensitive.

  • Device doesn’t match ^.*Mac.*$: Checks if the device string doesn’t contain the substring Mac.

Notes

  • If you’re trying to match a specific word or pattern within a larger string, the regex needs to account for the entire string, not just the part you’re interested in.

  • Use the contains operator instead of matches to check whether the pattern appears anywhere within the string, rather than requiring the entire string to match the pattern.

Is empty/Is not empty

Whether the condition object on which the condition is based is empty.

  • The Is empty operator is evaluated to true when the object (for example, Context) is:

    • An empty string (for example, "")

    • An empty array (for example, [])

  • The Is not empty operator is evaluated to true when the object (for example, Context) is:

    • null

    • undefined

    • A non-empty string (for example, " ", "foo", 123)

    • A non-empty array (for example, ["foo"], [" ", "foo"])

Examples

  • Context [UserRole] is empty

  • Context [UserRole] is not empty

See Is empty/Is not empty VS Is populated/Is not populated for further information about the differences between the operators.

Is populated/Is not populated

Whether the condition object on which the condition is based is populated.

  • The Is populated operator is evaluated to true when the object (for example, Context) is:

    • A populated string (for example,"foo", 123 )

    • A populated array (for example, ["123", “foo"])

  • The Is not populated operator is evaluated to true when the object (for example, Context) is:

    • null

    • undefined

    • A non-populated string (for example, "“,” ")

    • A non-populated array (for example, [],["", " "] )

Examples

  • Context [UserRole] is populated

  • Context [UserRole] is not populated

See Is empty/Is not empty VS Is populated/Is not populated for further information about the differences between the operators.

Is between/Is not between

The Query Time UTC object time frame.

The Is between / Is not between operators are available only when selecting the Query Time UTC object.

Example

Query Time UTC Is between Oct 30, 2019, 0:00 to Oct 31, 2019, 0:00

Is empty/Is not empty VS Is populated/Is not populated

The Is empty/Is not empty and Is populated/Is not populated operators may look similar, but they answer different questions:

  • Is empty/Is not empty checks whether a value is actually empty (for example, query is empty would mean that a user triggered a query without typing anything).

  • Is populated/Is not populated checks whether a value is meaningfully set (for example, query is not populated would mean that no search has been performed).

This table highlights how common values are evaluated.

Value Is populated Is empty

undefined / null (missing value)

false

false

"" (empty string)

false

true

" " (spaces only)

false

false

[] (empty array)

false

true

{} (empty object)

false

true

"foo" (non-empty string)

true

false
Note

Is not empty evaluates to true when the value is null or undefined. To check that a value is present and usable, use Is populated instead.
Exact evaluation rules

The following table indicates how a condition object is evaluated according to the chosen operator (Is populated, Is not populated, Is empty, and Is not empty).

Value

Operators

Is populated

Is not populated

Is empty

Is not empty

undefined

false

true

false

true

null

false

true

false

true

true

true

false

false

true

false

true

false

false

true

0

true

false

false

true

1

true

false

false

true

[]

false

true

true

false

["", ""]

false

true

false

true

[" ", " "]

false

true

false

true

{}

false

true

true

false

""

false

true

true

false

" "

false

true

false

true

"foo"

true

false

false

true

Required privileges

The following table indicates the required privileges for members to view or edit elements of the Conditions (platform-ca | platform-eu | platform-au) page and associated panels (see Manage privileges and Privilege reference). This includes the ability to manage query pipeline conditions.

Note

Members with the privilege to view query pipelines (that is, the View all or the Custom access level on the Query Pipelines domain) can review the conditions in read-only mode (see Manage privileges and Query pipelines domain).
Action Service - Domain Required access level

View pipeline conditions

Search - Query pipelines
Organization - Organization

View

Edit pipeline conditions

Organization - Organization

View

Search - Query pipelines

Edit