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 A/B test feature to compare the results of the rule with the results of the original pipeline.

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

When creating query parameter rules in a query pipeline, you may want to create a new rule that’s similarly configured to an existing one. An efficient way to do this is to duplicate the existing rule and then modify it as needed.

  1. On the Query Pipelines (platform-ca | platform-eu | platform-au) page, click the query pipeline for which you want to duplicate 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, select each checkbox next to the rules you want to duplicate within the same pipeline.

  5. In the Action bar, click Duplicate.

The duplicated query parameter rules appear at the bottom of the list in the pipeline component tab.

Copy query parameter rules to another pipeline

When you have more than one query pipeline that serve different purposes but require similar rules, you may want to copy query parameter rules from one pipeline to another.

  1. On the Query Pipelines (platform-ca | platform-eu | platform-au) page, click the query pipeline from which you want to copy 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, select each checkbox next to the rules you want to copy to another pipeline.

  5. In the Action bar, click More, and then click Copy to…​.

  6. In the dialog that appears, select the target pipeline to which you want to copy the rules, and then click Copy.

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

You can delete query parameter rules from a query pipeline.

  1. On the Query Pipelines (platform-ca | platform-eu | platform-au) page, click the query pipeline for which you want to delete 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, select each checkbox next to the rules you want to delete.

  5. In the Action bar, click More, and then Delete.

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

The advanced query expression, typically generated by code (for example, when toggling facet values).

Note

When logging a usage analytics event for a query, the advancedQuery field of that event should be set to the aq value of the corresponding query (for reporting purposes).
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)

The @-prefixed name of the field to use to be able to identify an item as a child of another item in a folded query result.

Use a field whose value points to the parentField value of the intended parent. Whenever an item is a child of another item, its childField value must be identical to the parentField value of that other item.

Note

  • In the index, the values of the childField must only contain alphanumeric characters. Using a childField whose values contain non-indexable characters, such as underscores, will make folding fail.

  • The values of the childField must contain 60 characters or less (60 being the default maximum of characters for a word in the index).

commerce.catalogId (string)

The unique identifier of the catalog to use for the query in a Coveo for Commerce solution.

cq (string)

The constant query expression, typically populated with expressions that must apply to all queries sent from a specific search interface (for example, from a specific tab). Once evaluated, the result sets of those expressions are kept in a special cache.

Tip

Avoid including dynamic content in the constant query expression. Otherwise you risk filling up the cache with useless data, which can have a negative impact on performance.
Notes

  • Other parts of the query expression can also benefit from the index cache (see maximumAge). However, using the constant query expression allows you to explicitly cache specific result sets.

  • Temporal keywords (now, today, yesterday) in the constant query expression are only re-evaluated once every three to four minutes. Therefore, you should avoid basing cq expressions on temporal keywords if you require split second accuracy.
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)

Whether to force a successful response to include debug information.

Default: false

Notes

  • Debug information can only appear in responses in the JSON format.

  • Avoid setting this parameter to true in your production environment, as it has a negative impact on query performance.

dq (string)

The disjunction query expression, typically populated by Coveo ML ART models to ensure that relevant items are included in the query results. This expression is merged with the other parts of the query expression using the OR operator. Therefore, the resulting query expression is ((q AND aq) OR dq) AND cq. 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)

Whether to enable the Did You Mean feature of the index, which populates the queryCorrections property of a successful response with keyword correction suggestions.

Default: false

Notes

  • The Did You Mean feature only processes the basic query expression (see the q parameter).

  • The Did You Mean feature won’t return corrections when the query is processed by Coveo ML ART model whose Intelligent Term Detection (ITD) feature is enabled.

  • When both enableDidYouMean and enableMLDidYouMean parameters are set to true, the output of both features will appear in the queryCorrections array.

enableDuplicateFiltering (Boolean)

Whether to filter out duplicates, so that items resembling one another only appear once in the query results.

Default: false

Notes

  • Two items must be at least 85% similar to one another to be considered duplicates.

  • When duplicates are found, only the higher-ranked item of the two is kept in the result set.

  • Enabling this feature can make the total result count less precise, since only results up to those being retrieved (see the firstResult and numberOfResults parameters) are submitted to duplicate filtering.

enableMLDidYouMean (Boolean)

Important

This feature is in an experimental state.

Whether to enable the Coveo ML query suggestions Did You Mean feature, which populates the queryCorrections property of a successful response with keyword correction suggestions.

Default: false

Notes

  • The Did You Mean feature only processes the basic query expression (see the q parameter).

  • When both the enableDidYouMean and enableMLDidYouMean parameters are set to true, the output of both features will appear in the queryCorrections array.

enableQuerySyntax (Boolean)

Whether to interpret advanced Coveo query syntax as such in the basic query expression (see the q and lowercaseOperators parameters).

Default: true

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

The maximum length of result excerpts (in number of characters). An excerpt is a segmented text generated at query time by the index from the body of an item. When a query is performed, the excerpt yields relevant item body sections in which the queried terms are highlighted.

An excerpt includes the most relevant sentences in which the queried keywords appear, in the order in which they appear in the item, up to the specified number of characters.

Default: 200

Note

The maximum length you set using this parameter also applies to retrieved first sentences, if those are included in the results (see the retrieveFirstSentences parameter).
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)

The @-prefixed name of the field to use to group items into distinct folded query results. Use a field whose value is identical for all items to group under the same folded query result.

filterFieldRange (integer [int32])

The maximum number of items to include in the childResults array of a folded query result.

Default: 5

firstResult (integer [int32])

The 0-based position of the first result to return in the non-paginated result set. Along with the numberOfResults parameter, this allows you to retrieve a specific page of result items.

Default: 0

forwardLanguageToCoveoIndex (boolean)

Controls whether the language of the user’s interface is used when interpreting the query.

Default: false

When set to true, the language of the user’s interface is included in the search request sent to the Coveo index. This means that the interpretation and processing of the user’s query are influenced by their language setting, potentially enhancing the relevance of the returned search results. It can be particularly useful for stem expansion.

Tip

This parameter should be used in combination with the locale request parameter.
Example

If a user’s interface is in French and forwardLanguageToCoveoIndex is set to true, the language information is included in the search request sent to the Coveo index. French content is therefore prioritized in the search results, making the results more relevant to the user’s language preference.

index (string)

The identifier of the index mirror to forward the request to. If you don’t specify an index (or #indextoken-string[indexToken]) value, any index mirror could be used.

Note

Passing an index (or indexToken) value has no effect when the results of a specific request can be returned from cache (see maximumAge).

indexToken (string)

The identifier of the index mirror to forward the request to.

If you don’t specify an indexToken (or index) value, any index mirror could be used.

Note

Passing an indexToken (or index) value has no effect when the results of a specific request can be returned from the cache (see maximumAge).

isGuestUser (Boolean)

Whether the current user is anonymous. Coveo ML models may use this information to provide contextually relevant output.

Note

When logging a usage analytics event for a query, the anonymous field of that event should be set to the isGuestUser value of the query.

locale (string)

The locale of the current user. Must comply with IETF’s BCP 47 definition.

Coveo ML models use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $locale object.

Note

When logging a usage analytics event, the language field of that event should match the language part of the locale value of the query (for example, en-US in locale becomes en in language).

logicalIndex (string)

The identifier for a logical group of indexes that have been configured to include items from the same sources. If you don’t specify a logicalIndex value, the default grouping will be used, typically including all indexes.

Default: "default"

lowercaseOperators (Boolean)

Whether to treat the AND, NEAR, NOT, and OR keywords in the basic query expression (see the q parameter) as Coveo query syntax operators, even if those keywords are in lowercase.

Note

Setting this parameter to true has no effect unless you also set the enableQuerySyntax parameter to true. For instance, if you set both this parameter and the enableQuerySyntax parameter to true, the index interprets the near keyword in the basic query expression service center near me as the NEAR Coveo query syntax operator.

Default: false

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)

The large query expression, typically populated with a case description, long textual query, or any other form of text that can help refine a query. The Coveo ML Intelligent Term Detection (ITD) feature can extract relevant keywords from the large query expression and inject those keywords in the basic query expression (see the q parameter).

lqPartialMatchKeywords (integer [int32])

The minimum number of keywords that need to be present in the large query expression (see the lq parameter) to convert it to a partial match expression in case the Coveo ML Intelligent Term Detection (ITD) feature can’t extract relevant keywords from the large query expression. For further information on query expressions, see Understanding the query expression.

Default: 5

Note

This parameter applies as a fallback setting when no Coveo ML ART model is available in the query pipeline to process a query that contains a non-null large query expression (lq).

lqPartialMatchMaxKeywords (integer [int32])

The maximum number of keywords from the large query expression (see the lq parameter) that will be included in the partial match expression in case the Coveo ML Intelligent Term Detection (ITD) feature can’t extract relevant keywords from the large query expression.

Default: 100

Notes

  • This parameter applies as a fallback setting when no Coveo ML ART model is available in the query pipeline to process a query that contains a non-null large query expression (lq).

  • Setting this parameter to a high value can negatively impact the performance of queries, while setting it too low can produce less relevant results.

lqPartialMatchThreshold (string)

An absolute or relative value indicating the minimum number of partial match expression keywords an item must contain to match the large query expression in case the Coveo ML Intelligent Term Detection (ITD) feature can’t extract relevant keywords from the large query expression.

Default: 50%

If specified, the lqPartialMatchThreshold value must be one of the following:

  • a 32-bit unsigned integer (for example, 3)

  • a percentage value between 0% and 100% (for example, 75%)

  • an empty string ("")

  • the all string

Notes

  • This parameter applies when no Coveo ML ART model is available in the query pipeline to process a query that contains a non-null large query expression (lq).

  • The "" and all values are both equivalent to 100%.

maximumAge (integer [int32])

The maximum age (in milliseconds) of the cached query results. If the results of a specific request are available in the cache, and if those results are no older than the maximumAge value, the service returns those results rather than forwarding a new query to the index.

Such cache hits improve responsiveness but still count as queries in your queries per month (QPM) count.

Default: -1

Note

This parameter is automatically overridden when staticQuery is set to true.

mlDidYouMeanMaxCandidates (integer [int32])

The maximum number of Coveo ML Did You Mean candidates to request from the QS model.

Default: 3

mlDidYouMeanMinScore (number [double])

The minimum score a query suggestion may have to be allowed as a candidate for the Coveo ML query suggestions Did You Mean feature. For best results, value should typically be in range [0.8, 2].

Default: 1.0

mlDidYouMeanUseFacetCount (Boolean)

Whether to use facet counts for the Coveo ML Did You Mean feature.

Default: false

numberOfResults (integer [int32])

The number of results to return. Along with the firstResult parameter, this allows you to retrieve a specific page of result items.

This parameter also defines the maximum number of results which can be returned by the Coveo ML Content Recommendations (CR) and Product Recommendations (PR) features.

Default: 10

Note

The maximum numberOfResults value depends on the index settings of your Coveo organization. By default, a Coveo index can return a maximum of 2,000 items per query.
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)

The @-prefixed name of the field to use to be able to identify an item as a parent in a folded query result.

Use a field whose value can uniquely identify each item. All items whose childField` value is identical to the parentField value of another item are considered children of that other item.

Notes

  • In the index, the values of the parentField must only contain alphanumeric characters. Using a childField whose values contain non-indexable characters, such as underscores, will make folding fail.

  • The values of the parentField must contain 60 characters or less (60 being the default maximum of characters for a word in the index).

partialMatch (Boolean)

Whether to convert a basic expression containing at least partialMatchKeywords to a partial match expression, so that any item containing at least partialMatchThreshold of those keywords will match the expression.

If you don’t set this parameter to true, an item must contain all the basic expression keywords to match the expression. See Taking advantage of the partial match feature to learn how to leverage this feature.

Default: false

Notes

  • This feature only applies to the basic expression (q) of a query, and to the basic queryOverride of its Group By operations.

  • When the enableQuerySyntax parameter is set to true, this feature has no effect on a basic expression containing advanced Coveo query syntax (field expressions, operators, etc.).

partialMatchKeywords (integer [int32])

The minimum number of keywords that needs to be present in a basic expression to convert it to a partial match expression.

Default: 5

Notes

  • This parameter has no effect unless the partialMatch parameter is set to true.

  • Repeated keywords in a basic expression count as a single keyword.

  • Thesaurus expansions in a basic expression count towards the partialMatchKeywords count.

  • Stemming expansions don’t count towards the partialMatchKeywords count.

partialMatchThreshold (string)

An absolute or relative value indicating the minimum number (rounded up) of partial match expression keywords an item must contain to match the expression.

If specified, the partialMatchThreshold value must be either of the following:

  • a 32-bits unsigned integer (for example, 3)

  • a percentage value between 0% and 100% (for example, 75%)

  • the empty string ("")

  • the all string

Default: 50%

Notes

  • This parameter has no effect unless the partialMatch parameter is set to true.

  • A keyword and its stemming expansions count as a single keyword when evaluating whether an item meets the partialMatchThreshold.

  • The "" and the all value are both equivalent to 100%.

q (string)

The basic query expression, typically the keywords entered by the end user in a query box. For further information on query expressions, see Understanding the query expression.

Note

When logging a usage analytics event for a query, the queryText field of that event should be set to the q value of the corresponding query.
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)

Whether to enable question mark character (?) in the wildcard feature of the index in order to expand basic expression keywords (see the q parameter) containing question mark character (?) to the possible matching keywords. See Using wildcards in queries for the complete parameter definition.

Default: false

Note

Setting this parameter to true has no effect unless you also set the wildcards parameter to true.
Example

You want to allow clients to use the ? wildcard, especially since you set operators to be ignored (enableQuerySyntax is 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)

Whether to include the first sentences of textual items in the query results.

First sentences are typically useful when rendering result items such as emails, since the first few sentences of these kinds of items are often more relevant than a contextually generated excerpt (see the excerptLength parameter).

Default: false

Note

The maximum length of the retrieved sentences (in number of characters) is determined by the value of the excerptLength parameter.
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.

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

The first level of origin of the request, typically the identifier of the graphical search interface from which the request originates. Coveo ML models use this information to provide contextually relevant output.

Notes

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.

  • When logging a usage analytics event for a query, the originLevel1 field of that event should be set to the value of the searchHub search request parameter.

sortCriteria (string)

The criteria to use for sorting the query results. Allowed values:

  • relevancy: Uses standard index ranking factors (adjacency, TDIDF, etc.) and custom ranking expressions (QREs and QRFs) to compute a ranking score for each query result item, and sorts the query results by descending score value.

  • date ascending/date descending: Uses the @date field to sort the query results. This field typically contains the last modification date of each item.

  • qre: Uses only custom ranking expressions (QREs and QRFs) to compute a ranking score for each query result item, and sorts the query results by descending score value.

  • nosort: Doesn’t sort the query results; the index will return result items in an essentially random order.

  • @[field] ascending/@[field] descending: Sort using the value of a specific sortable field (replace [field] by the target field name).

Default: relevancy

Note

You can specify a list of comma-separated sort criteria. However, this only works when combining:

  • Two or more field criteria (for example, @views descending,@likes descending).

  • A single date criteria with one or more field criteria (for example, date ascending,@views descending).
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)

Whether to execute this query in a way that doesn’t count against the allowed number of queries per month (QPM) of a Coveo organization, but may produce cached or outdated query results (see Rendering static content using persistent queries).

Default: false

Note

Setting this parameter to true overwrites the maximumAge parameter value for this query.

summaryLength (integer [int32])

The length of the automatically generated item summary. The Coveo Platform uses a linguistic algorithm that relies on term frequency and proximity to generate an item summary made of sentences identified to be the most important ones in the item. This summary is generated independently from the query, as opposed to a result item excerpt, which is generated based on query keywords.

Default: 0

tab (string)

The second level of origin of the request, typically the identifier of the selected tab in the graphical search interface from which the request originates. Coveo ML models use this information to provide contextually relevant output.

Note

When logging a usage analytics event for a query, the originLevel2 field of that event should be set to the tab value of the query (or to the default string, if no tab value was specified in the query).

wildcards (Boolean)

Whether to enable the wildcards feature of the index in order to expand basic expression keywords (see the q parameter) containing wildcard characters (*) to the possible matching keywords (see Using wildcards in queries).

Default: false

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)

Important

This parameter override has been moved from Query suggest parameters and can now be leveraged in the Query Suggestion model association.

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.