Query pipeline language (QPL)

This is for:

Developer System Administrator

The query pipeline language, also known as QPL (pronounced qupel) is the language used to define query pipeline statements. These statements are authored in the Coveo Administration Console when configuring query pipelines and are interpreted by the Search API at query time.

QPL describes how a query should be handled by query pipeline features (for example, Thesaurus, Ranking, and Stop) as a search request passes through a query pipeline.

Query pipeline features

Each query pipeline feature is expressed using a specific QPL statement.

The featured result query pipeline feature increases the ranking scores of items that match specific query expressions.

Example

The following QPL statement expressing the featured result feature promotes specific items identified by field expressions when the user query contains the word help.

when $query contains "help"
featured result `@urihash==7Vf6bWsytplARQu3`

filter

The filter query pipeline feature adds hidden query syntax expressions to the query before it’s executed against the index.

Example

The following QPL statement expressing the filter feature adds @source=="Public Content to the advanced (aq) part of the query expression. As a result, items not originating from the Public Content source are excluded from the query results.

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

queryParamOverride

The queryParamOverride query pipeline feature overrides the values of specific query parameters.

Example

In your company intranet, support agents often search for previous cases containing long product codes. To help them find relevant results without having to enter complex queries, you set the enableQuerySyntax and wildcards query parameters to true for all search requests processed by the Search API.

override query enableQuerySyntax: true, wildcards: true

ranking expression

The ranking expression query pipeline feature modifies the ranking scores of query result items based on whether they match specific query expressions.

Example

On your company blog, you want to boost the ranking scores of posts whose title contains the word troubleshoot. Therefore, you create the following QPL statement that boosts the ranking score by 10 for items that match the specified regex.

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

rankingweight

The rankingweight query pipeline feature can modify the weights of various ranking factors used by the index to determine the ranking scores of query result items.

Example

On a medical information portal, you want to prioritize recent articles regardless of their relevance to the user query. Therefore, you create a QPL statement that increases the docDate ranking factor weight while decreasing other ranking factor weights.

rank docDate: 9, termCasing: 1, uri: 0

stop

The stop query pipeline feature removes specified words from the basic (q) part of the query expression before executing a query against the index.

Example

On a customer support intranet for equipment repair, you want agents to find relevant results faster by ignoring common words that don’t add meaning to their queries. Therefore, you create the following QPL statement that removes the words fix and repair, as well as any word that matches the /how to \w+/ regex.

stop "fix", "repair", /how to \w+/

thesaurus

The thesaurus query pipeline feature expands specific words or phrases in the basic (q) part of the query expression with their synonyms before executing a query against the index.

Example

On your health information portal, you want users searching for treatments to also find results related to prevention methods. Therefore, you create the following QPL statement that expands the word treatment with the synonym prevention, as well as any word that matches the (medication) \w+ regex.

expand "treatment", /(medication) \w+/ to "prevention"

trigger

The trigger query pipeline feature executes specific actions in the search interface from which queries originate.

Example

In your e-learning platform, you want to display an animation in the search interface when users search for instructions on how to use a specific feature. Therefore, you create the following QPL statement that triggers the showAnimation action when the user query contains the word instruction.

when $originalQuery contains "instruction"
execute showAnimation("triggerStatement", 100, true)
Note

Since queries are parsed before query pipeline statements are evaluated, the $originalQuery QPL object is preferred over the $query QPL object when defining features that depend on the original user query.

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)`
Tip
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

$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

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 for rightmost 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"

  • $constantQuery 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)).

Tip
Leading practice

When referencing a QPL object in a ranking expression query pipeline statement, 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