Manage query pipeline conditions

This is for:

Developer System Administrator

A query pipeline condition is a set of one or more elements that determine when a particular query pipeline, query pipeline rule, or Coveo Machine Learning (Coveo ML) model is applied to a query. Members with the required privileges can use the Conditions (platform-ca | platform-eu | platform-au) page to manage conditions.

Once you create a condition, you can associate it with a single query pipeline, or any number of query pipeline rules or ML model associations.

Note

Each query pipeline, query pipeline rule, or ML model association can only be associated with a single condition.

How query pipeline conditions are used

In a typical setup, you’ll associate each query pipeline (except the default one) with a distinct condition based on a unique search hub value such as $searchHub is "AgentPanel". Inside a given query pipeline, you can then associate rules to more specific conditions.

Example

While managing the website for Barca Sports, you create a query pipeline named Support that contains a featured results rule. You want the rule to boost pages that contain assembly guides for the company’s best-selling home gym equipment, therefore, you create a condition for queries containing how to and assembly.

Most rules should be associated with a condition, unless you want a rule to apply whenever a query is routed to the pipeline. Associating rules with conditions allows for more targeted results, while not associating them means the rule applies more broadly.

Different ways to create or edit a condition

There are different ways to create a condition in the Coveo Administration Console. We recommend that you use the method that best suits the context in which you want to create the condition.

You can:

  • Create or edit a condition from the Add/edit a condition panel.

    This is a straightforward method as you can access the panel directly from the Conditions (platform-ca | platform-eu | platform-au) page, or also from a given query pipeline. It’s the recommended method when creating a condition that you want to use in multiple query pipelines, rules, or ML model associations.

  • Create or edit a condition with the Edit a Rule With Code panel.

    This method lets you manage the condition using the query pipeline language (QPL) syntax. It’s the recommended method when you want to create a condition that’s specific to a single rule or ML model association.

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).

On the Conditions (platform-ca | platform-eu | platform-au) page, you can perform the following actions:

Create a condition

  1. Access the Add a Condition panel using one of the following methods:

  2. In the Add a Condition panel that appears:

    1. Click the first dropdown menu, and then select on which object the condition is based (see Objects reference).

    2. Click the second dropdown menu, and then select an operator to apply between the selected object and the value (see Operators reference).

    3. If a third dropdown menu is available, click it, and then provide values to filter on by doing one of the following:

      • Select one or more values from the suggestions.

      • Enter new values, and then select Enter or click add.

    4. (Optional) Click add on the right side of the panel to add another condition:

      1. In the dropdown menu, select either the And or the Or operator to specify how this second condition will be linked to the first one.

      2. Repeat the procedure starting with step 2b to define the second condition.

  3. Click Add Condition.

Edit a condition

Important

Modifying a condition immediately affects all pipeline rules or models that use the condition.

  1. Double-click the condition to modify.

  2. In the Edit a Condition panel, add or delete condition elements.

  3. Click Save.

Enter a condition description

  1. Click the condition to which you want to add a description, and then click More > Set description in the Action bar.

  2. In the Set Description panel, enter a text with information that will help you and your colleagues to manage the condition in the future.

    The entered text appears in the Description column.

  3. Click Save.

Delete a condition

Important

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

  1. Click the condition that you want to delete, and then in the Action bar, click Delete.

  2. Next to the Delete <CONDITION_NAME> message that appears in the Action bar, click Delete again.

Create or edit a condition with code

Developers can directly enter a condition that respects the query pipeline language (QPL) syntax (see QPL objects).

  1. In the desired query pipeline component tab, click the rule on which you want to add a condition, and then click More > Edit code in the Action bar.

  2. In the Edit a Rule With Code panel that appears, in the form editor box, add a condition at the end of the rule.

  3. Click Save.

Note

Keep in mind that 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 when creating or editing a condition with code.

Add/Edit a Condition panel:

Add a condition | Coveo

Add/Edit a Rule With Code panel:

Edit a condition with code | Coveo

Access the "Add a Condition" panel from a pipeline component (optional)

You can access the Add a Condition panel from different parts of the Query Pipelines configuration page. This lets you create a condition on-the-fly when you’re adding or editing a query pipeline component.

  1. On the Query Pipelines (platform-ca | platform-eu | platform-au) page, click the pipeline in which you want to add a condition to a rule or model, and then click Edit components in the Action bar.

  2. On the query pipeline configuration page, select the tab under which you want to add the condition. Depending on the selected tab:

    • In the Configuration tab, click Create a new condition.

    • In the Groups & Campaigns tab:

      1. Click the desired rule, and then click Edit in the Action bar.

      2. On the subpage that appears, click Create a new condition.

    • In the Result Ranking tab, double-click the desired rule, and then click Create a new condition.

    • In the Machine Learning tab:

      1. Click the desired model, and then click Edit in the Action bar.

      2. In the Edit a Model Association subpage that appears, click Create a new condition.

    • In the Search Terms and Advanced tabs:

      1. On the left side of the screen, select the desired rule type.

      2. Click the desired rule, and then click Edit in the Action bar.

      3. On the subpage that appears, click Create a new condition.

Reference

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 being processed by a query pipeline.

Note

The Original objects also have a regular counterpart that can be chosen to create a condition on an object after it has been processed by a query pipeline. Both option types can be selected in the object dropdown menu of the Add a Condition panel.

(For Original/non-original object pairs only) Depending on the selected object:

  • When you select the non-original object such as Query, the condition is met whether the value matches the original expression or the expression resulting of the query pipeline processing.

    Example

    You want to apply a specific pipeline or a specific rule if an empty query is performed. Therefore, you add a query pipeline condition that catches empty queries.

    Add a condition where query is empty example | Coveo

  • When you select the original object such as Original Query, the condition is met only if the value matches the original expression.

    Example

    A user searches dashcam on your support page. You have a thesaurus rule that replaces dashcam with dash cam. If you set a condition Original Query is dash cam, the condition won’t be met since the original query of the user was dashcam. However, if your condition was Query is dash cam, the condition would be met.

Advanced Query/Original Advanced Query

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

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.[1]

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.

Click the Context key dropdown menu, and then select a suggestion, or manually enter the desired context key and select Enter or click add.

Important

The keys used in the Context object are case sensitive.
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.[1]

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 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 link 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.[1]

Locale

The value of the locale query parameter passed by the search interface, such as the one configured in the browser 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.[1]

Query Time UTC

The UTC time at which the query was made.

Note

For this object only, your operator options at next step are Is between and Is not between, and you must enter a date range.
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

You should always use positive operators (for example, is, contains, or matches) when creating a condition that aims at routing the 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 does not 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 if you want 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 each have their own purpose.

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).

Object state

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.

Action Service - Domain Required access level

View pipeline conditions

Search - Query pipelines
Organization - Organization

View

Edit pipeline conditions

Analytics - Analytics data
Analytics - Dimensions
Organization - Organization

View

Search - Query pipelines

Edit
1. To understand the difference between the Original and non-original condition objects, see the "Objects" reference documentation.