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.

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

Coveo | diagram showing order of execution

Syntax

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

override <query | querySuggest> <queryParameterOverrides>
Note

An override statement can modify only one query parameter at a time. Adding multiple parameters in a single statement will result in an error, such as: Only one parameter can be overridden at a time.

<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 parameter-value pair where the parameter is a valid query or query suggestion parameter, and the value is a valid input for that parameter (see Query parameters). Only one parameter-value combination is supported per override statement.

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 four distinct statements, each expressing the queryParamOverride feature, with the following QPL definitions:

Statement 1

override querySuggest enableWordCompletion: true

Statement 2

override querySuggest count: 3

Statement 3

override query enableQuerySyntax: true

Statement 4

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