QueryParamOverride: Query pipeline feature

This is for:

Developer System Administrator
In this article

A query pipeline statement expressing the queryParamOverride query pipeline feature modifies query parameter values before the search (or Coveo Machine Learning (Coveo ML) Query Suggestion (QS)) request is processed any further by the Search API.

Tip
Leading practice

Typically, a statement expressing the queryParamOverride feature should only apply when a certain condition is fulfilled.

In general, you should ensure that this is the case by associating such a statement, and/or the query pipeline it’s defined in, to a global condition.
Note

In the Coveo Administration Console, you can manage statements expressing the queryParamOverride feature from the Query Parameters tab (see Manage query parameter rules).

The following diagram shows the process of a query being sent to the Search API and the order of execution of query pipeline features.

Apply queryParamOverride statements

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

Example

You create a global condition with the following QPL definition:

Global condition:

when $context[userRole] is "powerUser"

In an empty query pipeline named Testing Override, you create two distinct statements, each expressing the queryParamOverride feature, with the following QPL definitions:

Statement 1

override querySuggest enableWordCompletion: true, count: 3

Statement 2

override query enableQuerySyntax: true, wildcards: true

You associate these statements to the global condition statement you created before.

In a graphical search interface, an end user types in a search box which has been configured to provide Coveo Machine Learning (Coveo ML) query completion suggestions, causing a querySuggest request to be sent with a partial basic query expression (q) to the Search API on each new keystroke:

querySuggest payload

{
  "q": "query pip",
  "context": {
    "userRole": "powerUser"
  }
}

Since the query suggestion operation goes through the Testing Override query pipeline and satisfies the global condition, the querySuggest override statement is applied. As a result the following things happen:

  • The query suggestions are ordered by which suggestion best completes the last word being typed by the end user in the search box (because of enableWordCompletion: true).

  • A maximum of three query completion suggestions is returned (because of count: 3).

Tip

Successful response - 200 OK


  completions: [
    {
      "executableConfidence": 1,
      "expression": "query pipeline",
      "highlighted": "{query} {pip}[line]",
      "score": 12.98498638195693
    },
    {
      "executableConfidence": 1,
      "expression": "query pipeline statement",
      "highlighted": "{query} {pip}[line] [statement]",
      "score": 13.960273930588135
    },
    {
      "executableConfidence": 1,
      "expression": "query pipeline language",
      "highlighted": "{query} {pip}[line] [language]",
      "score": 11.744597776008531
    }
  ]
}

The end user ignores the query completion suggestions, and finally inputs an expression which includes a wildcard character (*) and advanced query syntax (@source==docs.coveo.com) before submitting the query:

Query payload

{
  "context": {
    "userRole": "powerUser"
  },
  "q": "query pip* @source==docs.coveo.com"
}

Since the query goes through the Testing Override query pipeline and satisfies the global condition, the query override statement is applied. As a result the following things happen:

  • The index only return items whose @source field value is equal to docs.coveo.com (because of enableQuerySyntax: true).

  • The index only return items whose content includes both the query keyword and a keyword that starts with pip (because of wildcards: true).