Adding and Managing Query Pipeline Conditions

Administrators and relevance managers can use the Conditions page to manage query pipeline conditions that can be applied to query pipelines, query pipeline rules, and Coveo Machine Learning (Coveo ML) models).

Conditions are reusable. Once you create a condition, you can associate it with a single query pipeline and/or any number of query pipeline rules/Coveo ML model associations.

Each query pipeline and query pipeline rule/ML model associations can only be associated with a single condition.

How Query Pipeline Conditions Are Used

In a typical setup, you will associate each query pipeline (except the default one) to a distinct condition based on a unique search hub value, for instance when $searchHub is "AgentPanel".

Inside a given query pipeline, you can then associate rules to more specific conditions. Most rules should be associated with a condition, unless you want a rule to apply whenever a query is routed to the pipeline in which the rule is defined.

Access the “Conditions” Page

  1. If not already done, log in to the Coveo Cloud platform as a member of a group with the required privileges to manage conditions in the target Coveo Cloud organization.

  2. In the main menu on the left, under Search, select Conditions.

Access the “Add a Condition” Dialog From a Pipeline Component

  1. If not already done, log in to the Coveo Cloud platform as a member of a group with the required privileges to manage conditions in the target Coveo Cloud organization.

  2. In the main menu on the left, under Search, select Query Pipelines.

  3. On the Query Pipelines page, access the query pipeline for which you want to add a condition to a rule or model:

    • Double-click the pipeline.

      OR

    • Click the pipeline, and then in the Action bar, click Edit components.

  4. On the query pipeline page, select the tab under which the rule or associated Coveo ML model you want to link to a condition is located.

  5. Depending on the selected pipeline component tab:

    • In the Machine Learning tab, depending on your Coveo Cloud organization:
      Organization version Access instructions
      Organizations created before
      April 23, 2019, and did not go through the migration process
      1. Double-click the desired model.
      2. Expand the Condition to be applied section.
      3. Click Add condition.
      Organizations created after
      April 23, 2019, or went
      through the migration process
      1. Double-click the desired model.
      2. In the Edit a Machine Learning Model Association dialog that appears, click Create a new condition.
    • In the Featured Results tab, depending on your Coveo Cloud organization:

      Organization version Access instructions
      Organizations created before June 10, 2019 1. Click the desired rule.
      2. In the Action bar, click More, and then select Select condition or Change condition.
      3. In the Select a Condition dialog that appears, click Add condition.
      Organizations created after June 10, 2019 1. Click the desired rule.
      2. In the Action bar, click Edit.
      3.In the Edit a Featured Result Rule dialog that appears, click Create a new condition.
    • In the Thesaurus, Ranking Expressions, Ranking Weights, Triggers, Filters, and Query Parameters tabs:
      1. Click the desired rule.
      2. In the Action bar, click More, and then select Select condition or Change condition.
      3. In the Select a Condition dialog that appears, click Add condition.
    • In the Stop Words tab:
      1. In the row of the desired rule, click Apply condition.
      2. In the Select a Condition dialog that appears, click Add condition.

Manage Query Pipeline Conditions

Members with the privilege to view query pipelines (i.e., the View all or the Custom access level on the Query Pipelines domain) can review the conditions in read-only mode (see Privilege Management and Query Pipelines Domain).

On the Conditions page, you can perform the following condition actions:

Create a Condition

  1. Access the Add a Condition dialog:

    • On the Conditions page, click Add Condition.

      If the Add Condition button is grayed and unresponsive, you do not have all required privileges to perform this action.

    OR

    OR

  2. In the Add a Condition dialog that appears:

    1. Click the first drop-down menu, and then select on which object the condition is based.

      • The Original objects (i.e., 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.

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

        • When you select the non-original object (e.g., Query), the condition is met whether the value matches the original expression or the expression after being processed by a query pipeline (in regards with the condition operator).

          You want to apply a specific pipeline or a specific rule (e.g., featured results) if an empty query is performed (e.g., on an interface load), so you add a query pipeline condition that catches empty queries.

          ConditionEx

        • When you select the original object (e.g., Original Query), the condition is met only if the value matches the original expression (in regards with the condition operator).

          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 will not 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 such as facet selections made by the user.

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

      • 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 such as the filter associated with the search interface tab selected by the user.

        When the user selects the Support Cases search interface tab, the constant query can be (@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 (see Sending Custom Context Information).

        Click the Context key drop-down menu, and then select one of the suggestions, or manually enter the desired context key and press Enter or click the plus sign button (Plus Sign Button).

        Your custom context is to discriminate users by their role relative to your products, 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 with other expressions and used to expand the search results such as in rare cases where some search results that do not match the other expressions must be injected.

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

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

      • Query Time UTC: The UTC time at which the query was made.

        For this object only, your operator options at next step are Is between and Is not between, and you must enter a date range.

        On your e-commerce 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.

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

        On your e-commerce website, you have a side-panel that lists your top selling products that is 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.
    2. Click the second drop-down menu, and then select an operator to apply between the selected object and the value. Your options are: Is, Is not, Contains, Doesn’t contain, Matches, Doesn’t match, Is empty, Is not empty, Is populated, and Is not populated, or Is between and Is not between if you selected the Query Time UTC object.

    3. If a third drop-down menu is available, click it, and then provide values to filter on:
      • Select one or more values from the suggestions.

      AND/OR

      • Enter new values, and then press Enter or click the plus sign button (Plus Sign Button).

      The Is/Is not operators:

      • are case insensitive.

      • interpret the value as a string, meaning that if you want to filter on a regular expression (regex), you must add the condition in the QPL syntax (see Adding a Condition With Code).

      The Matches/Doesn’t match operators:

      • are case sensitive.

      • interpret the value to filter on as a regular expression (regex).

    4. (Optional) Click Add Rule to add one or more elements to the condition:

      1. In the drop-down menu, select either the And or the Or operator.

      2. Repeat the procedure starting with step 2b.

  3. Click Add Condition.

For developers, you can also directly enter a condition that respects the Query Pipeline Language (QPL) syntax (see Conditions):

  1. In the query pipeline component tab, click the rule on which you want to add a condition.

  2. In the Action bar, click More, and then select Edit code.

  3. In the Edit a Rule With Code panel that appears:

    1. In the form editor box, add a condition at the end of the rule.

      You can match exact words in a sentence by adding the following condition:

      when $query contains /\btechno\b/

      where the \b stands for word boundaries, including beginning and end (/) of string (^$).

    2. Click Save.

Modify a Condition

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

  1. Double-click the condition to modify.

    OR

    Click the condition you want to modify, and then select Edit condition.

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

  3. Click Save.

Enter a Condition Note

  1. Click the condition to which you want to add a note.

  2. In the Action bar, click More, and then select Set user note.

  3. In the Set a User Note dialog, 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 User note column.

  4. Click Set note.

Delete a Condition

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.

  2. In the Action bar, click More, and then select Delete.

  3. In the Are you Sure? dialog, ensure the selected condition is the one you want to delete, and then click Confirm.

On the Conditions page, at the bottom-right of the table, click the left and right arrow icons, or a page number to navigate through pages.

Set the Number of Conditions per Page

On the Conditions page, at the bottom-left of the page, select 10 or 100.

By default, the table shows 10 conditions per page.

Required Privileges

The following table indicates the required privileges to view or edit elements of the Conditions page and associated panels (see Privilege Management and Privilege Reference).

Action Service - Privilege Required access level
View pipeline conditions

Organization - Organization

Search - Query pipelines

View
Edit pipeline conditions

Organization - Organization

View

Search - Query pipelines

Edit