---
title: Query pipeline language (QPL)
slug: '1449'
canonical_url: https://docs.coveo.com/en/1449/
collection: tune-relevance
source_format: adoc
---
# Query pipeline language (QPL)
The _query pipeline language_, also known as QPL (pronounced _qupel_) is the language used to define [query pipeline statements](https://docs.coveo.com/en/236/).
These statements are authored in the [Coveo Administration Console](https://docs.coveo.com/en/183/) when configuring [query pipelines](https://docs.coveo.com/en/180/) and are interpreted by the Search API at [query](https://docs.coveo.com/en/231/) time.

QPL describes how a query should be handled by [query pipeline features](https://docs.coveo.com/en/234/) (for example, [Thesaurus](https://docs.coveo.com/en/1442/), [Ranking](https://docs.coveo.com/en/1452/), and [Stop](https://docs.coveo.com/en/1446/)) as a search request passes through a [query pipeline](https://docs.coveo.com/en/180/).

## Query pipeline features

Each [query pipeline feature](https://docs.coveo.com/en/234/) is expressed using a specific QPL statement.

### `featured result`

The `featured result` [query pipeline feature](https://docs.coveo.com/en/234/) 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](https://docs.coveo.com/en/200/) expressions when the user query contains the word `help`.

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

### `filter`

The [`filter`](https://docs.coveo.com/en/1440/) [query pipeline feature](https://docs.coveo.com/en/234/) 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`)](https://docs.coveo.com/en/175/) part of the [query expression](https://docs.coveo.com/en/2830/).
As a result, items not originating from the `Public Content` source are excluded from the query results.

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

### `queryParamOverride`

The [`queryParamOverride`](https://docs.coveo.com/en/1491/) [query pipeline feature](https://docs.coveo.com/en/234/) 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.

```text
override query enableQuerySyntax: true, wildcards: true
```

### `ranking expression`

The [`ranking expression`](https://docs.coveo.com/en/1452/) [query pipeline feature](https://docs.coveo.com/en/234/) 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](https://docs.coveo.com/en/2777/) 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.

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

### `rankingweight`

The [`rankingweight`](https://docs.coveo.com/en/1470/) [query pipeline feature](https://docs.coveo.com/en/234/) can modify the weights of various ranking factors used by the [index](https://docs.coveo.com/en/204/) 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.

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

### `stop`

The `stop` [query pipeline feature](https://docs.coveo.com/en/234/) removes specified words from the [basic (`q`)](https://docs.coveo.com/en/178/) 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.

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

### `thesaurus`

The [`thesaurus`](https://docs.coveo.com/en/1442/) [query pipeline feature](https://docs.coveo.com/en/234/) expands specific words or phrases in the [basic (`q`)](https://docs.coveo.com/en/178/) 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.

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

### `trigger`

The [`trigger`](https://docs.coveo.com/en/1458/) [query pipeline feature](https://docs.coveo.com/en/234/) 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`.

```text
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](https://docs.oracle.com/javase/tutorial/essential/regex/index.html)).

**Example**

[,text]
```
# 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](https://docs.coveo.com/en/1552/)).

**Example**

[,text]
```
# 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**

[,text]
```
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**

[,text]
```
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.

[options="header", cols="1,2,1"]
|===
| 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](https://docs.coveo.com/en/1552/)).

The following table lists the supported QPL operators.

[options="header", cols="1,2,1"]
|===
| Operator | Best suited for rightmost operand types | Examples

| [`is`/`is not` operators](https://docs.coveo.com/en/1959#isis-not)
a|
* Boolean
* Integer
* Quoted string
* Query expression
a|
* `$context[isAdmin] is true`
* `$context[level] is not 3`
* `$language is "fr"`
* `$advancedQuery is not @source=="Community Site"`

| [`contains`/`doesn't contain` operators](https://docs.coveo.com/en/1959#containsdoesnt-contain)
a|
* Quoted string
* Query expression
a|
* `$device contains "Mobi"`
* `$constantQuery doesn't contain @filetype=="PDF"`

| [`matches`/`doesn't match` operators](https://docs.coveo.com/en/1959#matchesdoesnt-match)
| Regular expression
a|
* `$query matches ^(?i)how do i.*$`
* `$device doesn't match ^.**Mac.**$`

| `starts with` / `doesn't start with`
a|
* Quoted string
* Query expression
a|
* `$identity starts with "john"`
* `$originalQuery doesn't start with the`

| `ends with` / `doesn't end with`
a|
* Quoted string
* Query expression
a|
* `$context[partner] ends with "@partner.com"`
* `$query doesn't end with product`
| [`isPopulated`](https://docs.coveo.com/en/1959#is-populatedis-not-populated)[.footnote]^[[1](#is-populated-operator)]^ / [`isEmpty`](https://docs.coveo.com/en/1959#is-emptyis-not-empty)[.footnote]^[[2](#is-empty-operator)]^ / `isNull`[.footnote]^[[3](#is-null-operator)]^ / `isUndefined`[.footnote]^[[4](#is-undefined-operator)]^
| None
a|
* `$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 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
> 
> ```text
when $context.userRole isPopulated
```
> 
> Statement
> 
> ```text
boost `@audience==$context.userRole` by 100
```

### Comments

QPL comments:

* Must be preceded by the `#` symbol.

* Take an entire line.

**Example**

Valid:

```text
# This is a valid comment.
```

Invalid:

```text
expand foo to bar # This is an invalid comment.
```

### Empty lines

The QPL parser ignores empty lines.

**Example**

```text
expand foo to bar
# The five previous lines are ignored
```