Manage Query Parameter Rules
Manage Query Parameter Rules
Users with the required privileges can create query parameter rules to override search parameter values for every query that matches a condition. This can all be done without having to modify your search interface code. Query parameters are specified either through the query string or in the JSON body of a user query.
You want to enable or disable the query syntax based on a user or group.
The list of query parameters in a query pipeline is empty by default. Query parameter rules are defined independently for each pipeline.
|
Note
Query parameter rules have priority over the same parameters set in the search interface code. |
Create query parameter rules
-
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.
-
On the page that opens, select the Advanced tab.
-
In the Advanced tab, on the left-hand side of the page, select Query Parameters.
-
In the upper-right corner of the page, click Add Query Parameters Rule to access the Add a Query Parameter Rule [1] subpage.
-
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).
-
In the Parameter name input, enter the name of the parameter to override (see Parameter Name Section).
-
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.
-
-
On the right-hand side, under Condition, you can optionally select a query pipeline condition in the dropdown menu or create a new one.
-
Under Description, optionally enter information that will help you manage the rule in the future.
-
Click Add Rule.
Edit query parameter rules
-
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.
-
On the page that opens, select the Advanced tab.
-
In the Advanced tab, on the left-hand side of the page, select Query Parameters.
-
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.
-
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).
-
In the Parameter name input, enter the name of the parameter to override (see Parameter Name Section).
-
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.
-
-
On the right-hand side, under Condition, you can optionally select a query pipeline condition in the dropdown menu or create a new one.
-
Under Description, optionally enter information that will help you manage the rule in the future.
-
Click Save.
Duplicate query parameter rules
-
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.
-
On the page that opens, select the Advanced tab.
-
In the Advanced tab, on the left-hand side of the page, select Query parameters.
-
In the Query parameters subtab, click the rule you want to duplicate within the same pipeline (typically to create a slightly different rule).
-
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.
-
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.
-
On the page that opens, select the Advanced tab.
-
In the Advanced tab, on the left side of the page, select Query Parameters.
-
In the Query Parameters subtab, inspect the information of the Details column for the desired rule.
Delete query parameter rules
-
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.
-
On the page that opens, select the Advanced tab.
-
In the Advanced tab, on the left-hand side of the page, select Query parameters.
-
In the Query parameters subtab, click the rule you want to delete.
-
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.
-
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.
-
On the page that opens, select the Advanced tab.
-
In the Advanced tab, on the left-hand side of the page, select Query parameters.
-
In the Query parameters subtab, click the rule whose position you want to change.
-
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 (i.e., requests to the /rest/search/v2
route).
Select Query Suggest if you want the rule to override the parameters in in query suggestion requests (i.e., requests to the /rest/search/v2/querySuggest
route).
You want to only show results in French, so you enter the following expression:

"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:
-
If you selected Query, see Query Parameters.
-
If you selected Query Suggest, see Query Suggest Parameters.
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.
-
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.
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.
|
This parameter overrides the generated disjunction query expression ( |
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.
-
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
, andNOT
, 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.
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))
|
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.
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.
format
(string)
See format
for the complete parameter definition.
index
(string)
See index
for the complete parameter definition.
indexToken
(string)
See indexToken
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.
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.
maximumAge
(integer [int32])
See maximumAge
for the complete parameter definition.
maximumTimeoutMs
(integer [int32])
See maximumTimeoutMs
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.
|
Don’t set this parameter in the query pipeline if your search interface contains a |
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.
|
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.
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
recommendation
(string)
See recommendation
for the complete parameter definition.
referrer
(string)
See referrer
for the complete parameter definition.
retrieveFirstSentences
(boolean)
See retrieveFirstSentences
for the complete parameter 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)
searchById
(boolean)
See searchById
for the complete parameter definition.
searchHub
(string)
See searchHub
for the complete parameter definition.
sortCriteria
(string)
See sortCriteria
for the complete parameter 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)
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.
timezone
(string)
See timezone
for the complete parameter definition.
visitorId
(string)
See visitorId
for the complete parameter definition.
wildcards
(boolean)
See wildcards
for the complete parameter 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
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.
count
(integer [int32])
See count
for the complete parameter definition.
debug
(boolean)
See debug
for the complete parameter definition.
enableWordCompletion
(boolean)
See enableWordCompletion
for the complete parameter definition.
format
(string)
See format
for the complete parameter definition.
indexToken
(string)
See indexToken
for the complete parameter definition.
isGuestUser
(boolean)
See isGuestUser
for the complete parameter definition.
locale
(string)
See locale
for the complete parameter definition.
maximumAge
(integer [int32])
See maximumAge
for the complete parameter definition.
maximumTimeoutMs
(integer [int32])
See maximumTimeoutMs
for the complete parameter definition.
q
(string)
See q
for the complete parameter definition.
|
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. |
recommendation
(string)
See recommendation
for the complete parameter definition.
referrer
(string)
See referrer
for the complete parameter definition.
searchHub
(string)
See searchHub
for the complete parameter definition.
tab
(string)
See tab
for the complete parameter definition.
timezone
(string)
See timezone
for the complete parameter definition.
visitorId
(string)
See visitorId
for the complete parameter definition.
Unsupported parameters
The following parameters are NOT supported:
-
actionsHistory
-
analytics
-
categoryFacets
-
commerce
-
context
-
dictionaryFieldContext
-
disableQuerySyntax
NoteWe 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 (i.e., inGET
orPOST
requests to the/rest/search/v2
route). -
querySuggest
: modifies parameters in query suggestion requests (i.e., inGET
orPOST
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:

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 |
View |
Edit query parameter rules |
Organization - Organization |
View |
Search - Query pipelines |
Edit |
