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.

EXAMPLE

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.

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

Create Query Parameter Rules

  1. On the Query Pipelines page, click the query pipeline in which you want to add a rule, and then in the Action bar, click Edit Components.

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

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

  4. In the upper-right corner of the page, click Add Query Parameters 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-hand side, under Condition, you can optionally select a query pipeline condition in the drop-down menu or create a new one.

  9. Under User note, 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 page, click the query pipeline in which you want to edit a rule, and then in the Action bar, click Edit Components.

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

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

  4. Click the rule you want to edit, and then in the Action bar, click Edit [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-hand side, under Condition, you can optionally select a query pipeline condition in the drop-down menu or create a new one.

  9. Under User note, 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 page, click the query pipeline for which you want to duplicate query pipeline rules, and then in the Action bar, click Edit components.

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

  3. In the Advanced tab, on the left-hand 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.

Delete Query Parameter Rules

  1. On the Query Pipelines page, click the query pipeline for which you want to delete query pipeline rules, and then in the Action bar, click Edit components.

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

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

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

  5. In the Action bar, click More, and then select 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 page, click the query pipeline for which you want to manage the rules' execution order, and then in the Action bar, click Edit components.

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

  3. In the Advanced tab, on the left-hand 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 (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).

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

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)

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

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

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)

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)

firstResult (integer [int32])

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

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

partialMatch (boolean), partialMatchKeywords (integer [int32]), and partialMatchThreshold (string)

See Taking Advantage of the Partial Match Feature to learn how to leverage this feature.

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.

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

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 are the following (see Get Query Suggestions):

searchHub (string)

See searchHub for the complete parameter definition.

locale (string)

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

enableWordCompletion (boolean)

See enableWordCompletion for the complete parameter definition.

Unsupported Parameters

The following parameters are NOT supported:

  • Nested fields such as groupBy

  • sortField

  • fieldsToInclude

  • pipeline

  • disableQuerySyntax

    We recommend that you use the enableQuerySyntax parameter instead.

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., in GET or POST requests to the /rest/search/v2 route).

  • querySuggest: modifies parameters in query suggestion requests (i.e., 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 highlights in orange the position of query parameter rules in the overall order of execution of query pipeline features.

query parameter rules in the query pipeline order of execution

Required Privileges

By default, members of the Administrators and Relevance Managers built-in groups can view and edit elements of the Query Pipelines page.

The following table indicates the required privileges to view or edit elements of the Query Pipelines page (see Manage Privileges and Privilege Reference).

Action Service - Domain Required access level

View query parameter

Search - Query pipelines

View

Edit query parameter

Search - Query pipelines

Edit


1. (Advanced) You can click Menu, and then select Add query parameters 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.
Recommended Articles