Query pipeline language (QPL)

This is for:

In this article

Examples
Reference

The query pipeline language, also known as QPL (pronounced qupel) is a simple language used to define query pipeline statements.

Example

To express the following rule in a given query pipeline:

"Replace the foo keyword in the basic query expression (q) with the (foo OR bar) expression."

you would create a query pipeline statement with the following QPL expression as a definition:

expand "foo" to "bar"

This QPL definition is an expression of the thesaurus query pipeline feature (see Thesaurus - query pipeline feature).

Examples

What follows is a list of query pipeline features that can be expressed with QPL, along with an example of each.

`filter`

The following QPL statement expressing the Filter feature adds @source=="Public Content to the advanced (aq) part of the query expression (see About the query expression).

filter aq `@source=="Public Content"`

`queryParamOverride`

The following QPL statement expressing the QueryParamOverride feature overrides the enableQuerySyntax and wildcards query parameter values to true before the search request is processed any further by the Search API.

Note

queryParamOverride works only for the number, string, and Boolean types of query parameters.

override query enableQuerySyntax: true, wildcards: true

`ranking` (deprecated)

The QPL rule has been replaced by ranking expression query pipeline feature, grouped as Result rankings API.

The following QPL statement expressing the Ranking feature generates a query ranking expression (QRE) that boosts the ranking score by 10 for items that match the specified regex (see Use query ranking expressions).

boost `@title/="^.*Coveo.*$"` by 10

`rankingweight`

The following QPL statement expressing the Rankingweight feature modifies weights of various ranking factors used by the index to determine the ranking scores of query result items.

rank adjacency: 9, concept: 6, title: 5, termCasing: 1, uri: 0

`stop`

The following QPL statement expressing the Stop feature removes the specified list of words from the basic (q) part of the query expression before executing a query against the index (see About the query expression).

stop "be", "do", "how", "i", "in", "my", "not", "or", "the", "to"

`thesaurus`

The following QPL statement expressing the Thesaurus feature appends OR automobile OR (motor vehicle) to phrases in the basic (q) part of the expression matching either the "car" or /(dodge) \w+/ expressions.

expand "car", /(dodge) \w+/ to "automobile", "motor vehicle"

`top` (deprecated)

The QPL rule has been replaced by featured result query pipeline feature, grouped as Result rankings API.

The following QPL statement expressing the Top feature greatly increases the ranking scores of an item matching either of the specified query expressions.

top `@urihash==7Vf6bWsytplARQu3`, `@title=="Top: Query pipeline feature"`

`trigger`

The following QPL statement expressing the Trigger feature executes the showAnimation action in the search interface from which any queries originate.

execute showAnimation("triggerStatement", 100, true)

Reference

Primitive types

QPL supports four primitive types:

Boolean (that is, true, false)
integer (e.g, 123)
quoted string (for example, "foo")
string (for example, foo)

Regular expressions

Regular expressions must be enclosed within forward slashes (/).

Note

QPL uses the java.util.regex package to parse regular expressions (see Lesson: Regular Expressions).

Example

# Using a quantifier
/foo*/

# Using a named capturing group; the `<` and `>` symbols must be escaped
/(?\<myGroup\>foo)/

# Using an embedded flag expression (that is,  modifier)
/(?i)foo/

# Using a predefined character class
/\d/

Query expressions

Query expressions must be enclosed within backticks (`).

Note

The main difference between a query expression and a quoted string is that the QPL parser will reject a query pipeline statement whose definition contains a syntactically wrong backticks-enclosed query expression, whereas it won’t try to parse that same expression if it’s enclosed within double quotes (see Query syntax).

Example

# A simple query expression
`foo bar`

# A query expression using a Boolean query syntax operator
`foo OR bar`

# A field query expression
`@title==foo`

# A complex query expression using the `$qre` standard query extension
`$qre(expression: $context.key=="foo", modifier: 100)`

# A complex query expression using the `$qre` and `$splitValues` standard query extensions
`$qre(expression: @coveodptaxonomyleaves=$splitValues(text: $query, separator: '\s'), modifier: 15)`

Leading practice

Boolean query syntax operators (AND, NEAR, NOT, and OR) should always be in uppercase in a QPL query expression.

While using lowercase Boolean operators may work, doing so is ill-advised as it can yield unexpected results.

Lists

Some features and constructs accept a list of values rather than a single value.

When this is the case, distinct values are separated by commas (,).

Example

expand /foo.*/, "bar baz" to "\"hello world\""

Hashes

Some features and constructs accept a list of key-value pairs rather than a single value.

When this is the case:

Each key must be a non-quoted string.
Each key must be separated from its value by a colon (:)
Each value must be a Boolean, integer, quoted string, or regular expression.
Distinct key-value pairs are separated by commas (,)

Example

key1: true, key2: 123, key3: "bar", key4: /foo.*/, key5: `hello world`

QPL objects

QPL objects are domain-specific constructs which allow you to define conditions using the supported operators.

The following table lists all available QPL objects.

Object Contains the value of the… Returns many values

Object	Contains the value of the…	Returns many values
`$advancedQuery`	…`aq` query parameter (unprocessed value and current processed value).	No
`$browser`	…browser in the user agent.	Yes
`$constantQuery`	…`cq` query parameter (unprocessed value and current processed value).	No
`$context[key]`	…`key` entry in the `context` query parameter.	Possibly
`$device`	…device in the user agent.	Yes
`$disjunctionQuery`	…`dq` query parameter (unprocessed value and current processed value).	No
`$facetsFilter`	…query expression that represents the filters introduced by the selection of dynamic facets.	No
`$groups`	…`userGroups` part of the identity performing the query.	Yes
`$identity`	…`name` part of the identity performing the query.	Yes
`$language`	…`language` part of the `locale` query parameter.	No
`$largeQuery`	…`lq` query parameter (unprocessed value and current processed value).	No
`$locale`	…`locale` query parameter	No
`$originalQuery`	…`q` query parameter (unprocessed value only).	No
`$originalAdvancedQuery`	…`aq` query parameter (unprocessed value only).	No
`$originalConstantQuery`	…`cq` query parameter (unprocessed value only).	No
`$originalDisjunctionQuery`	…`dq` query parameter (unprocessed value only).	No
`$originalLargeQuery`	…`lq` query parameter (unprocessed value only).	No
`$os`	…operating system in the user agent.	Yes
`$query`	…`q` query parameter (unprocessed value and current processed value).	No
`$recommendation`	…`recommendation` query parameter	No
`$referrer`	…`referrer` query parameter	No
`$searchHub`	…`searchHub` query parameter	No
`$tab`	…`tab` query parameter	No

$advancedQuery

…aq query parameter (unprocessed value and current processed value).

$browser

…browser in the user agent.

Yes

$constantQuery

…cq query parameter (unprocessed value and current processed value).

$context[key]

…key entry in the context query parameter.

Possibly

$device

…device in the user agent.

Yes

$disjunctionQuery

…dq query parameter (unprocessed value and current processed value).

$facetsFilter

…query expression that represents the filters introduced by the selection of dynamic facets.

$groups

…userGroups part of the identity performing the query.

Yes

$identity

…name part of the identity performing the query.

Yes

$language

…language part of the locale query parameter.

$largeQuery

…lq query parameter (unprocessed value and current processed value).

$locale

…locale query parameter

$originalQuery

…q query parameter (unprocessed value only).

$originalAdvancedQuery

…aq query parameter (unprocessed value only).

$originalConstantQuery

…cq query parameter (unprocessed value only).

$originalDisjunctionQuery

…dq query parameter (unprocessed value only).

$originalLargeQuery

…lq query parameter (unprocessed value only).

$os

…operating system in the user agent.

Yes

$query

…q query parameter (unprocessed value and current processed value).

$recommendation

…recommendation query parameter

$referrer

…referrer query parameter

$searchHub

…searchHub query parameter

$tab

…tab query parameter

Supported operators

When using a QPL operator:

The left operand must be a QPL object.
The right operand, if required, must be a Boolean, integer, quoted string, regular expression, or query expression.

Note

Using a query expression as a right operand is typically only legitimate when:

The left operand is one of:
- $advancedQuery/$originalAdvancedQuery
- $constantQuery/$originalConstantQuery
- $disjunctionQuery/$originalDisjunctionQuery
- $largeQuery/$originalLargeQuery
- $query/$originalQuery
You want to ensure that the query pipeline statement will be rejected if the right operand contains a syntactically incorrect query expression (see Query syntax).

The following table lists the supported QPL operators.

Operator Best suited right-hand operand types Examples

Operator	Best suited right-hand operand types	Examples
`is`/`is not` operators	Boolean Integer Quoted string Query expression	`$context[isAdmin] is true` `$context[level] is not 3` `$language is "fr"` `$advancedQuery is not @source=="Community Site"`
`contains`/`doesn’t contain` operators	Quoted string Query expression	`$device contains "Mobi"` `$contantQuery doesn’t contain @filetype=="PDF"`
`matches`/`doesn’t match` operators	Regular expression	$query matches ^(?i)how do i.*$ $device doesn’t match ^.Mac.$
`starts with` / `doesn’t start with`	Quoted string Query expression	`$identity starts with "john"` `$originalQuery doesn’t start with the`
`ends with` / `doesn’t end with`	Quoted string Query expression	`$context[partner] ends with "@partner.com"` `$query doesn’t end with product`
`isPopulated`^[1] / `isEmpty`^[2] / `isNull`^[3] / `isUndefined`^[4]	None	`$identity isPopulated` `not $originalQuery isEmpty` `not ($context[partner] isNull or $context[partner] isUndefined)`

is/is not operators

Boolean
Integer
Quoted string
Query expression

$context[isAdmin] is true
$context[level] is not 3
$language is "fr"
$advancedQuery is not @source=="Community Site"

contains/doesn’t contain operators

Quoted string
Query expression

$device contains "Mobi"
$contantQuery doesn’t contain @filetype=="PDF"

matches/doesn’t match operators

Regular expression

$query matches ^(?i)how do i.*$
$device doesn’t match ^.Mac.$

starts with / doesn’t start with

Quoted string
Query expression

$identity starts with "john"
$originalQuery doesn’t start with the

ends with / doesn’t end with

Quoted string
Query expression

$context[partner] ends with "@partner.com"
$query doesn’t end with product

isPopulated^[1] / isEmpty^[2] / isNull^[3] / isUndefined^[4]

None

$identity isPopulated
not $originalQuery isEmpty
not ($context[partner] isNull or $context[partner] isUndefined)

1. Returns false if the left operand is null, undefined, an empty string, a blank string (that is, a string containing only white spaces), an empty array, or an array of empty/blank strings. Returns true otherwise.

2: Returns false if the left operand is null, undefined, a non-empty string, or a non-empty array. Returns true otherwise.

3: Returns true if the left operand matches the null value. Returns false otherwise.

4: Returns true if the left operand is an undefined object property. Returns false otherwise.

Using QPL objects in query expressions

You can inject the value of any QPL object (except for $query/$originalQuery) inside a query expression.

When a QPL object such as $os returns many values, use the $joinValues query extension (for example, $joinValues(values: $os)).

When you want to inject the value of a specific $context object key inside an expression:

If the expression is a string in a QPL statement definition (that is, not a query expression enclosed within back-ticks), use square brackets notation (for example, boost @audience==$context[userRole] by 100).
If the expression is a query expression enclosed within back-ticks in a QPL statement definition, or if it’s a query expression that isn’t part of a QPL statement, use dot notation (for example, boost `@audience==$context.userRole by 100` / $qre(expression: @audience==$context.userRole, modifier: 100)).

Leading practice

When referencing a QPL object in a ranking query pipeline statement (that is, in a ranking expression rule), always associate the statement with a condition that tests whether the QPL object is nonempty. Otherwise, you risk inadvertently boosting undesired results.

For example:

Condition

when $context.userRole isPopulated

Statement

boost `@audience==$context.userRole` by 100

Comments

QPL comments:

Must be preceded by the # symbol.
Take an entire line.

Example

Valid:

# This is a valid comment.

Invalid:

expand foo to bar # This is an invalid comment.

Empty lines

The QPL parser ignores empty lines.

Example

expand foo to bar





# The five previous lines are ignored.