Adding and Managing Query Pipeline Query Parameters

Administrators and relevance managers can use the Query Parameters tab to override search parameter values for every query that matches a condition without modifying your search interface code (see Built-In Groups). Query parameters are specified either through the query string or in the JSON body of a user query.

QueryParameter

The query parameters rules have priority over the same parameters set in the search interface code.

You want to enable or disable the query syntax based on a user or group.

</div>

The list of query parameters in a query pipeline is empty by default. Query parameter rules are defined independently for each pipeline.

The following diagram highlights the position of query parameter rules in the overall order of execution of query pipeline features (see Order of Execution of Query Pipeline Features).

Access the “Query Parameters” Tab of a Pipeline

  1. If not already done, log in to your Coveo Cloud organization as a member of a group with the required privileges to manage query pipeline components 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 in which you find the query parameter rules you want to manage:

    • Double-click the pipeline.

      OR

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

  4. On the selected pipeline page, select the Query Parameters tab.

Manage the Query Parameters of a Query Pipeline

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 query parameter rules in read-only mode (see Privilege Management and Query Pipelines Domain).

  1. Access the “Query Parameters” tab of a pipeline.

  2. In the Query Parameters tab, you can add a new query parameter rule:

    1. Access the Add a Query Parameter Rule dialog by clicking Add Rule, and then selecting Query parameters rule.

    2. In the Add a Query Parameter Rule dialog, under Parameter type to override, select whether the rule will override a Query or a Query suggestion type parameter.

      You want to only show results in French, so you enter the following expression:

      QPL-QueryParameterEx

    3. In the first input, enter the Parameter name to override (see Query Parameters).

      • The parameter names are case-sensitive.

      • The query parameters are the following:

        • aq (see aq definition)

          • You want to ignore existing advanced queries containing a query ranking expression (QRE).

            • Parameter type to override: Query

            • Parameter name: aq

            • Parameter value type: String

            • Parameter value:

            • Condition: Advanced query contains QRE (see Create a condition)

          • You want to avoid content from being filtered by a certain facet selection. The Source facet of your search interface contains the Tutorial video and Tutorial web facet values, which both lead to complementary content.

            • Parameter type to override: Query

            • Parameter name: aq

            • Parameter value type: String

            • Parameter value: (@source=="Tutorial video" OR @source=="Tutorial web")

            • Condition: Query contains Tutorial (see Create a condition)

        • cq (see cq definition)

          When your employees perform queries, you want to show results that are internal.

          • Parameter type to override: Query

          • Parameter name: cq

          • Parameter value type: String

          • Parameter value: @targetAudience==internal

          • Condition (see Create a condition):

            • Context

            • Key: userGroup

            • Value: employee

        • enableDidYouMean (see enableDidYouMean definition)

        • enableQuerySyntax (see enableQuerySyntax definition)

          • After analyzing usage analytics data, you noticed that special characters such as (, [, ], {, }, -, and & created content gaps. Therefore, you set enableQuerySyntax to true so the index interprets those special characters as spaces.

            • Parameter type to override: Query

            • Parameter name: enableQuerySyntax

            • Parameter value type: Boolean

            • Parameter value: false

          • You want to ignore operators for your clients, but not for your internal users, so you set a condition on the identity.

            • Parameter type to override: Query

            • Parameter name: enableQuerySyntax

            • Parameter value type: Boolean

            • Parameter value: false

            • Condition: Identity is anonymous (see Create a condition)

          • You want to ignore all operators but still want to use the AND, OR, NOT, so you can add a condition that ignores the rule if the operator is in the query.

            • Parameter type to override: Query

            • Parameter name: enableQuerySyntax

            • Parameter value type: Boolean

            • Parameter value: false

            • Condition: Query doesn't contain "and" or Query doesn't contain "or" or Query doesn't contain "not" (see Create a condition)

        • excerptLength (see excerptLength definition)

          When your clients are on a specific tab, you want to show longer descriptions than in the other tabs.

          • Parameter type to override: Query

          • Parameter name: excerptLength

          • Parameter value type: Number

          • Parameter value: 500

          • Condition: Tab is Books (see Create a condition)

        • firstResult (see firstResult definition)

        • lowercaseOperators (see lowercaseOperators definition)

          You want to allow customer use the AND and OR operators even if they write them in lowercase. When you ignore the operators (enableQuerySyntax set to false), you must add a condition to exclude AND and OR. Otherwise, operators will not be considered.

          • Parameter type to override: Query

          • Parameter name: lowercaseOperators

          • Parameter value type: Boolean

          • Parameter value: true

        • lq (see lq definition)

        • numberOfResults (see numberOfResults definition)

          When your clients search “find a store”, you want them to see the only article that helps them find stores. You also need a featured result rule on that specific article for the same query (see Adding and Managing Query Pipeline Featured Results).

          • Parameter type to override: Query

          • Parameter name: numberOfResults

          • Parameter value type: String

          • Parameter value: 1

        • partialMatch, partialMatchKeywords, and partialMatchThreshold (see Taking Advantage of the Partial Match Feature).

        • q (see q definition)

          This parameter overrides the query expression that the user enters in the search box. It is thus strongly recommended to add a condition for your rule to be applied.

        • questionMark (see questionMark definition)

          You want to allow clients to use the ? wildcard, especially since you set operators to be ignored (enableQuerySyntax set to false). You also set the wildcards parameter to true which is required for the questionMark parameter to be effective.

          • Parameter type to override: Query

          • Parameter name: questionMark

          • Parameter value type: Boolean

          • Parameter value: true

        • retrieveFirstSentences (see retrieveFirstSentences definition)

          You want to always show the first sentence of items. This sentence will be truncated if longer than the excerpt. If the sentence is short (e.g., title of an email), the rest of the normal excerpt will be shown until the excerptLength is reached (see excerptLength).

          • Parameter type to override: Query

          • Parameter name: retrieveFirstSentences

          • Parameter value type: Boolean

          • Parameter value: true

          • Condition: Query is Bulletin (see Create a condition)

        • sortCriteria (see sortCriteria definition)

          When a query contains “training”, you want to sort results by descending publication dates so the latest published trainings appear at the top of the results list.

          • Parameter type to override: Query

          • Parameter name: sortCriteria

          • Parameter value type: String

          • Parameter value: @itemsdate descending

          • Condition: Query contains Training (see Create a condition)

        • wildcards (see wildcards definition)

          You want to allow your clients to use wildcards (*, ?), especially since you set operators to be ignored (enableQuerySyntax set to false).

          • Parameter type to override: Query

          • Parameter name: wildcards

          • Parameter value type: Boolean

          • Parameter value: true

      • The query suggest parameters are the following (see Getting Query Suggestions):

        • searchHub

        • language

        • q

          This parameter overrides the query expression that the user enters in the search box. It is thus strongly recommended to add a condition for your rule to be applied.

        • enableWordCompletion

          (Boolean) Whether to return the best match to complete the currently typed keyword.

      • The following parameters are NOT supported:

        • Nested fields such as groupBy

        • sortField

        • fieldsToInclude

        • pipeline

        • disableQuerySyntax

          Use enableQuerySyntax instead.

    4. Click the drop-down menu, and then select one of the supported Parameter value type: String, Number, or Boolean.

    5. In the last input, enter the Parameter value with which you want to replace the actual parameter value.

    6. Click Add Rule.

      • All changes are immediately effective.

      • For developers, you can also directly enter a rule that respects the Query Pipeline Language (QPL) syntax for query parameters:

        1. In the Query Parameters tab, click Add Rule, and then select Query parameters with code.

        2. In the Add a Rule in QPL dialog, in the form editor box, enter a query parameter rule in the following form:

          override [type] [param1:value1,param2:value2…paramN:valueN]

          where you replace [type] with either query or querySuggest, and paramn and valuen with one of the supported parameters and values (see Supported Query Parameters, Supported Query Suggest Parameters, Unsupported Parameters, Query Parameters definition, and Getting Query Suggestions).

          • If you do not use escaped double quotes (\”) to enclose field or parameter containing values with multiple terms, you will get the following error: "The definition of the statement is syntactically invalid".

            • Invalid syntax: override query cq:"@source==(Web - Besttech, Sitemap - External)"

            • Valid syntax: override query cq:"@source==(\\"Web - Besttech\\", \\"Sitemap - External\\")"

          • You can only define overrides for one parameter type per rule. If you want to change the language (for example) on both query and querySuggest, you need two rules.

            You want to only show results in French so you enter the following rule:

            override query locale:"fr_CA"

        3. Click Save.

  3. You can perform other actions on rules (see Adding and Managing Query Pipeline Rules and Rule Conditions From Tabs).

  4. Add a condition to your query parameter rule (see Adding and Managing Query Pipeline Conditions).

  5. On the search interface(s) for your Coveo Cloud organization, test your query parameter rule to ensure that it provides the desired outcome. Make adjustments when needed.

Required Privileges

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

Action Service - Privilege Required access level
View query parameters

Organization - Organization

Search - Query pipelines

View
Edit query parameters

Organization - Organization

View
Search - Query pipelines Edit