Manage query parameter rules

This is for:

Developer System Administrator

A query parameter is a component of a query that can be specified either through the query string or in the JSON body of a user query. The Query Parameters section of the Query Pipelines (platform-ca | platform-eu | platform-au) page lets members with the required privileges create query parameter rules to override search parameter values for every query that matches a condition.

These rules can be added without having to modify the search interface code. By default, the list of query parameters in a query pipeline is empty. Therefore, the query parameters in the search interface code are used.

Query parameter rules are defined independently for each pipeline. These parameters are useful in customizing the search experience, allowing for the override of default values for every query that matches a defined condition.

Example

You want to enable or disable the query syntax based on a user or group. For administrators, you set a rule that enables advanced query syntax whenever they’re performing a search. This includes allowing specific query operators or search fields that are typically not available to general users. On the other hand, for general users, the default search parameters would apply, with the advanced syntax options remaining disabled.

Note

Query parameter rules have priority over the same parameters set in the search interface code.

Prerequisites

Before creating a rule, first make sure that you have the following:

Once you meet these requirements, you can create a rule on the Query Pipelines (platform-ca | platform-eu | platform-au) page. To test the rule, use the search page that uses the pipeline to which you added the rule. Alternatively, you can use the Content Browser (platform-ca | platform-eu | platform-au) page to ensure that the rule works as expected. To do so, on the Content Browser, select the pipeline to which you added the rule, and then perform queries to see the rule in action.

Create query parameter rules

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

  2. On the page that opens, select the Advanced tab.

  3. In the Advanced tab, on the left side of the page, select Query Parameters.

  4. In the upper-right corner of the page, click Add Query Parameter Rule to access the Add a Query Parameter Rule [1] subpage.

  5. Under Parameter type to override, select whether the rule will override a Query or a Query Suggest type parameter (see Parameter type to override section).

  6. In the Parameter name input, enter the name of the parameter to override (see Parameter name section).

  7. Under Parameter type, select one of the supported parameter value types: String, Number, or Boolean.

    • If you selected String, in the Parameter value input that appears, enter the value of the parameter with which you want to replace the actual parameter value.

    • If you selected Integer, in the Parameter value input that appears, enter the number with which you want to replace the actual parameter value.

    • If you selected Boolean, select True or False.

  8. On the right side, under Condition, you can optionally select a query pipeline condition in the dropdown menu or create a new one.

  9. Under Description, optionally enter information that will help you manage the rule in the future.

  10. Click Add rule.

Edit query parameter rules

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

  2. On the page that opens, select the Advanced tab.

  3. In the Advanced tab, on the left side of the page, select Query Parameters.

  4. Click the rule you want to edit, and then click Edit in the Action bar [2] to access the Edit a Query Parameter Rule subpage.

  5. Under Parameter type to override, select whether the rule will override a Query or a Query Suggest type parameter (see Parameter type to override section).

  6. In the Parameter name input, enter the name of the parameter to override (see Parameter name section).

  7. Under Parameter type, select one of the supported parameter value types: String, Number, or Boolean.

    • If you selected String, in the Parameter value input that appears, enter the value of the parameter with which you want to replace the actual parameter value.

    • If you selected Integer, in the Parameter value input that appears, enter the number with which you want to replace the actual parameter value.

    • If you selected Boolean, select True or False.

  8. On the right side, under Condition, you can optionally select a query pipeline condition in the dropdown menu or create a new one.

  9. Under Description, optionally enter information that will help you manage the rule in the future.

  10. Click Save.

Duplicate query parameter rules

  1. On the Query Pipelines (platform-ca | platform-eu | platform-au) page, click the query pipeline for which you want to duplicate query pipeline rules, and then click Edit components in the Action bar.

  2. On the page that opens, select the Advanced tab.

  3. In the Advanced tab, on the left side of the page, select Query parameters.

  4. In the Query parameters subtab, click the rule you want to duplicate within the same pipeline (typically to create a slightly different rule).

  5. In the Action bar, click Duplicate.

The duplicated rule appears at the bottom of the list in the pipeline component tab.

Review information about the rule’s creation or last modification

You can verify who created or last modified a given query parameter rule by inspecting the Details column of the Query Parameters subtab. The Details column also indicates the hour and date the rule was created or last modified.

  1. On the Query Pipelines (platform-ca | platform-eu | platform-au) page, click the query pipeline containing the rule for which you want to inspect the information of the Details column, and then click Edit components in the Action bar.

  2. On the page that opens, select the Advanced tab.

  3. In the Advanced tab, on the left side of the page, select Query Parameters.

  4. In the Query Parameters subtab, inspect the information of the Details column for the desired rule.

Delete query parameter rules

  1. On the Query Pipelines (platform-ca | platform-eu | platform-au) page, click the query pipeline for which you want to delete query pipeline rules, and then click Edit components in the Action bar.

  2. On the page that opens, select the Advanced tab.

  3. In the Advanced tab, on the left side of the page, select Query parameters.

  4. In the Query parameters subtab, click the rule you want to delete.

  5. Click Delete to confirm.

Change the rule order

Query pipeline rules are executed in the order in which they appear on the page until a condition is satisfied.

  1. On the Query Pipelines (platform-ca | platform-eu | platform-au) page, click the query pipeline for which you want to manage the rules' execution order, and then click Edit components in the Action bar.

  2. On the page that opens, select the Advanced tab.

  3. In the Advanced tab, on the left side of the page, select Query parameters.

  4. In the Query parameters subtab, click the rule whose position you want to change.

  5. In the Action bar, click Move up or Move down to change the position of the rule.

Reference

"Parameter type to override" section

In this section, you can either select Query or Query Suggest.

Select Query if you want the rule to override the parameters in search requests (that is, requests to the /rest/search/v2 route).

Select Query Suggest if you want the rule to override the parameters in query suggestion requests (that is, requests to the /rest/search/v2/querySuggest route).

Example

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

query-parameters-example

"Parameter name" section

When you input a query parameter name in the Parameter name section, note that the parameter names are case-sensitive.

Depending on the selection you made in the Parameter type to override section, the available parameters differ:

Query parameters

The query parameters listed in this section are those that can be defined in the Parameter name input when creating query parameter rules.

Some other query parameters are available when sending requests to the Search API. For the list of query parameters that can be used when sending requests to the Search API, see Query parameters.

aq (string)

See aq for the complete parameter definition.

For further information on query expressions, see Understanding the query expression.

Examples

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

childField (string)

See childField for the complete parameter definition.

cq (string)

See cq for the complete parameter definition.

For further information on query expressions, see Understanding the query expression.

Example

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

debug (Boolean)

See debug for the complete parameter definition.

dq (string)

See dq for the complete parameter definition.

For further information on query expressions, see Understanding the query expression.

Important

This parameter overrides the generated disjunction query expression (dq). Therefore, it’s strongly recommended to add a condition for your rule to be applied.

enableDidYouMean (Boolean)

See enableDidYouMean for the complete parameter definition.

enableDuplicateFiltering (Boolean)

See enableDuplicateFiltering for the complete parameter definition.

enableMLDidYouMean (Boolean)

See enableMLDidYouMean for the complete parameter definition.

enableQuerySyntax (Boolean)

See enableQuerySyntax for the complete parameter definition.

Examples

  • After analyzing usage analytics data, you noticed that special characters such as (, [, ], {, }, -, and & created content gaps. Therefore, you set enableQuerySyntax to false 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 AND, OR, and 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)

enableTermPermutations (Boolean)

Whether to enable the term permutations feature in the query pipeline.

Default: false

When set to true, the term permutations feature expands the keywords used in the user query to search for different variations of the same query by using casing variations and character transitions.

Example

In your Coveo index, you have support articles and user manuals that relate to the TP 213 v4 product.

You realize that your clients and support agents are often querying TP213v4 to find related information. This results in some of your users not finding the information they’re looking for.

By setting the enableTermPermutations parameter to true, you ensure that all usage variations of TP213v4 are taken into account when queried.

Therefore, when searching for TP213v4, a user will obtain a query similar to the following:

TP213v4 OR ((TP 213 v4) OR (TP213 V4) OR (tp2 13 V4))
Important

The term permutations feature expands every keyword used in a query. Since each queried keyword is affected by the feature, this may lead to query performance issues. Therefore, this feature should only be used when necessary and under certain conditions.

excerptLength (integer [int32])

See excerptLength for the complete parameter definition.

Example

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)

filterField (string)

See filterField for the complete parameter definition.

filterFieldRange (integer [int32])

See filterFieldRange for the complete parameter definition.

firstResult (integer [int32])

See firstResult for the complete parameter definition.

index (string)

See index for the complete parameter definition.

isGuestUser (Boolean)

See isGuestUser for the complete parameter definition.

locale (string)

See locale for the complete parameter definition.

logicalIndex (string)

See logicalIndex for the complete parameter definition.

lowercaseOperators (Boolean)

See lowercaseOperators for the complete parameter definition.

Example

You want to allow customer to 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 won’t be considered.

  • Parameter type to override: Query

  • Parameter name: lowercaseOperators

  • Parameter value type: Boolean

  • Parameter value: true

lq (string)

See lq for the complete parameter definition.

For further information on query expressions, see Understanding the query expression.

lqPartialMatchKeywords (integer [int32])

See lqPartialMatchKeywords for the complete parameter definition.

lqPartialMatchMaxKeywords (integer [int32])

See lqPartialMatchMaxKeywords for the complete parameter definition.

lqPartialMatchThreshold (string)

See lqPartialMatchThreshold for the complete parameter definition.

mlDidYouMeanMaxCandidates (integer [int32])

See mlDidYouMeanMaxCandidates for the complete parameter definition.

mlDidYouMeanMinScore (number [double])

See mlDidYouMeanMinScore for the complete parameter definition.

mlDidYouMeanUseFacetCount (Boolean)

See mlDidYouMeanUseFacetCount for the complete parameter definition.

numberOfResults (integer [int32])

See numberOfResults for the complete parameter definition.

Important

Don’t set this parameter in the query pipeline if your search interface contains a Pager component. Otherwise, pagination won’t work correctly in your search interface.
Example

When your clients search for “find a store”, you’ll want the results returned to only be the articles that help them find stores. You also need a featured result rule on that specific article for the same query (see Manage featured result rules).

  • Parameter type to override: Query

  • Parameter name: numberOfResults

  • Parameter value type: String

  • Parameter value: 1

parentField (string)

See parentField for the complete parameter definition.

partialMatch (Boolean)

See Taking advantage of the partial match feature to learn how to leverage this feature.

partialMatchKeywords (integer [int32])

See partialMatchKeywords for the complete parameter definition.

partialMatchThreshold (string)

See partialMatchThreshold for the complete parameter definition.

q (string)

See q for the complete parameter definition.

For further information on query expressions, see Understanding the query expression.

Important

This parameter overrides the query expression that the user enters in the search box. Therefore, it’s strongly recommended to add a condition for your rule to be applied.

questionMark (Boolean)

See questionMark for the complete parameter definition.

Example

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 (Boolean)

See retrieveFirstSentences for the complete parameter definition.

Example

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 (for example, 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)

searchHub (string)

See searchHub for the complete parameter definition.

sortCriteria (string)

See sortCriteria for the complete parameter definition.

Example

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)

staticQuery (Boolean)

See staticQuery for the complete parameter definition.

summaryLength (integer [int32])

See summaryLength for the complete parameter definition.

syntax (string)

See syntax for the complete parameter definition.

tab (string)

See tab for the complete parameter definition.

wildcards (Boolean)

See wildcards for the complete parameter definition.

Example

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

Query Suggest parameters

The query suggest parameters listed in this section are those that can be defined in the Parameter name input when creating query parameter rules. For the complete list of available query parameters, see QS parameters.

debug (Boolean)

See debug for the complete parameter definition.

enableWordCompletion (Boolean)

See enableWordCompletion for the complete parameter definition.

locale (string)

See locale for the complete parameter definition.

q (string)

See q for the complete parameter definition.

Important

This parameter overrides the query expression that the user enters in the search box. Therefore, it’s strongly recommended to add a condition for your rule to be applied.

searchHub (string)

See searchHub for the complete parameter definition.

tab (string)

See tab for the complete parameter definition.

Unsupported parameters

The following parameters are NOT supported:

  • actionsHistory

  • analytics

  • categoryFacets

  • commerce

  • context

  • dictionaryFieldContext

  • disableQuerySyntax

    Note

    We recommend that you use the enableQuerySyntax parameter instead.

  • facets

  • facetOptions

  • fieldsToExclude

  • fieldsToInclude

  • groupBy

  • mlParameters

  • pipeline

  • queryFunctions

  • sortField

  • userActions

QPL syntax

Use the following query pipeline language (QPL) syntax to define a statement expressing the queryParamOverride feature:

override <query | querySuggest> <queryParameterOverrides>

<query | querySuggest>

This is one of the two options:

  • query: modifies parameters in search requests (that is, in GET or POST requests to the /rest/search/v2 route).

  • querySuggest: modifies parameters in query suggestion requests (that is, in GET or POST requests to the /rest/search/v2/querySuggest route).

<queryParameterOverrides>

A comma-separated list of parameter-value pairs, where each parameter is a valid query/query suggestion parameter and each value must be a valid value for the specified query/query suggestion parameter (see Query parameters).

Order of execution

The following diagram illustrates the overall order of execution of query pipeline features:

diagram showing order of execution

Required privileges

By default, members with the required privileges can view and edit elements of the Query Pipelines (platform-ca | platform-eu | platform-au) page.

The following table indicates the required privileges for members to view or edit query parameter rules (see Manage privileges and Privilege reference).

Action Service - Domain Required access level

View query parameter rules

Organization - Organization
Search - Query pipelines

View

Edit query parameter rules

Organization - Organization

View

Search - Query pipelines

Edit
1. (Advanced) You can click Menu, and then select Add rule with code to define the rule using the appropriate QPL syntax.
2. (Advanced) You can click More, and then select Edit code to edit the rule using the appropriate QPL syntax.