---
title: 'Thesaurus: Query pipeline feature'
slug: '1442'
canonical_url: https://docs.coveo.com/en/1442/
collection: tune-relevance
source_format: adoc
---
# Thesaurus: Query pipeline feature
A query pipeline statement expressing the `thesaurus` query pipeline feature defines how certain terms or phrases appearing in the basic part (`q`) of the query expression should be _expanded_ or _replaced_ before executing the query against the index.

In general:

* Expanding `A` to `B` means: substitute `A` with `(A OR B)`.
* Expanding `A` to `B`, `C` means: substitute `A` with `(A OR B OR C)`.
* Replacing `A` with `B` means: substitute `A` with `B`.
* Replacing `A` with `B`, `C` means: substitute `A` with `(B OR C)`.

The `thesaurus` feature comprises four distinct sub-features:

* `alias`: expand each expression (keywords or phrases) in a list to all other expressions in that same list.
* `expand`: expand each expression (keywords or phrases) in a list to all expressions in another list.
* `replace`: replace each expression (keywords or phrases)  in a list with all expressions in another list.
* `quote`: replace each expression (keywords or phrases) in a list with its corresponding exact phrase match expression.

**Example**

The following table summarizes how statements using each of the different `thesaurus` sub-features would process the basic part (`q`) of the combined query expression, assuming its current value is `kitty cat`:

[%header, cols="1,1"]
|===
|Statement definition |Processed `q` expression

|`alias /kitt(y on en)/, "cat", "mouse hunter", "feline"`
|`(kitty OR cat OR (mouse hunter) OR feline) (cat OR (mouse hunter) OR feline)`

|`expand /kitt(y or en)/, "cat" to "mouse hunter", "feline"`
|`(kitty OR (mouse hunter) OR feline) (cat OR (mouse hunter) OR feline)`

|`replace /kitt(y or en)/, "cat" to "mouse hunter", "feline"`
|`((mouse hunter) OR feline) ((mouse hunter) OR feline)`

|`quote "kitty cat"`
|`"kitty cat"`

|`quote /kitt(y or en)/, "cat" to "mouse hunter"`
|`"mouse hunter" "mouse hunter"`
|===

> **Leading practice**
>
> Typically, a statement expressing the `thesaurus` 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](https://docs.coveo.com/en/183/), you can manage statements expressing the `thesaurus` feature [from the **Thesaurus** subtab](https://docs.coveo.com/en/3405/).

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](https://docs.coveo.com/en/assets/images/coveo-platform/trigger-statements-diagram.svg)

## Syntax

Use the following [query pipeline language (QPL)](https://docs.coveo.com/en/235/) syntax to define a statement expressing the `thesaurus` feature:

```text
alias <terms> | expand <terms> to <otherTerms> | replace <terms> to <otherTerms> | quote <terms> [to <otherTerms>]
```

### `<terms>`

A comma-separated list of quoted strings and/or regular expressions, where each quoted string must contain one or more basic query terms (for example, `+"foo bar", "baz", /^meo+w$/+`).

> **Important**
>
> When using the `alias` feature, `<terms>` must contain at least one quoted string (that is,  it can't contain only regular expressions).

### `<otherTerms>`

A comma-separated list of quoted strings, where each quoted string must contain one or more basic query terms (for example, `"hello world", "biz"`).

> **Note**
>
> If you define a named group in a regular expression in the `<terms>` list, you can reference the corresponding match group in the `<otherTerms>` list with the syntax `_<name>_`, where `<name>` is the name of the group.
> 
> For example, in an empty query pipeline named `Testing Match Groups`, you create a statement expressing the `thesaurus` feature with the following definition:
> 
> ```text
expand /(?<username>[^@]+)@example\.com/ to "_username_"
```
> 
> The following table summarizes how the current `q` expression of different queries going through the `Testing Match Groups` query pipeline is processed when this statement is applied:
> 
> [%header, cols="1,1"]
> |===
> |Current `q` expression |Processed `q` expression
> 
> |`asmith@example.com`
> |`asmith@example.com OR asmith`
> 
> |`bjones@example.com`
> |`bjones@example.com OR bjones`
> |===

## Using the `alias` sub-feature

The `alias` sub-feature lets you define statements that essentially make all expressions (keywords or phrases) in a set synonymous to one another.
This means that whenever any of these expressions appears in the basic part (`q`) of the query expression, this expression expands to all other expressions in the `alias` set.

`alias` statements are evaluated in the order they're defined.
This means that when a query is sent, the `alias` sub-feature evaluates the terms defined in the statement in order until it finds a match with the queried keywords.
Therefore, when defining `alias` statements that are meant to expand terms that share a single prefix, you should define more meaningful terms in the first position of the statement to avoid relevance issues.

In the [Coveo Administration Console](https://docs.coveo.com/en/183/), `alias` statements can be defined by using the [**Synonym**](https://docs.coveo.com/en/3405#synonym) thesaurus rule type.

**Example**

When considering the following statement:

```text
alias "vacation", "vacation leave", "vacation policy"
```

When a user queries `vacation policy`, their query is parsed as follows:

```text
(vacation OR (vacation leave) OR (vacation policy)) policy
```

However, when defining the same statement using `vacation policy` in first position as follows:

```text
alias "vacation policy", "vacation leave", "vacation"
```

The same `vacation policy` query is parsed as follows:

```text
(vacation policy) OR (vacation leave) OR vacation
```

> **Important**
>
> An `alias` set of expressions must contain at least one quoted string (that is,  it can't contain only regular expressions).

This sub-feature is an optimized use of the `expand` sub-feature, as many statements would otherwise be required to define a set of bi-directional expansions (that is,  synonyms).

**Examples**

* The following statement:

```text
  alias "foo", "bar", "qux"
```

Is equivalent to:

```text
  expand "foo" to "bar", "qux"
  expand "bar" to "foo", "qux"
  expand "qux" to "foo", "bar"
```

* In an empty query pipeline named `Testing Thesaurus Alias`, you create a statement expressing the `thesaurus` feature with the following QPL definition:

```text
  alias "car", /(dodge) \w+/, "automobile", "motor vehicle"
```

The following table summarizes how current `q` expression of different queries going through the `Testing Thesaurus Alias` query pipeline is processed when this statement is applied:

[%header, cols="~,~"]
|===
|Current `q` expression |Processed `q` expression

|`car`
|`car OR automobile OR (motor vehicle)`

|`automobile`
|`car OR automobile OR (motor vehicle)`

|`motor vehicle`
|`car OR automobile OR (motor vehicle)`

|`dodge stratus`
|`car OR (dodge stratus) OR automobile OR (motor vehicle)`

|`dodge caravan car`
|`(car OR (dodge caravan) OR automobile OR (motor vehicle)) (car OR automobile OR (motor vehicle))`
|===

## Using the `expand` sub-feature

The `expand` sub-feature allows you to define statements that expand each expression (keyword or phrase) in an originating set to all expressions in a destination set.
Those expansions are uni-directional.

In the [Coveo Administration Console](https://docs.coveo.com/en/183/), `expand` statements can be defined by using the [**One-way synonym**](https://docs.coveo.com/en/3405#one-way-synonym) thesaurus rule type.

**Example**

In an empty query pipeline named Testing Thesaurus Expand, you create a statement expressing the `thesaurus` feature with the following QPL definition:

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

The following table summarizes how the current `q` expression of different queries going through the `Testing Thesaurus Expand` query pipeline is processed when this statement is applied:

[%header, cols="~,~"]
|===
|Current `q` expression |Processed `q` expression

|`car`
|`car OR automobile OR (motor vehicle)`

|`dodge stratus`
|`(dodge stratus) OR automobile OR (motor vehicle)`

|`dodge caravan car`
|`((dodge caravan) OR automobile OR (motor vehicle)) (car OR automobile OR (motor vehicle))`
|===

## Using the `replace` sub-feature

The `replace` sub-feature allows you to define statements that replace each expression (keyword or phrase) in an originating set with all expressions in a destination set.

In the [Coveo Administration Console](https://docs.coveo.com/en/183/), `replace` statements can be defined by using the [**Replace**](https://docs.coveo.com/en/3405#replace) thesaurus rule type.

**Example**

In an empty query pipeline named `Testing Thesaurus Replace`, you create a statement expressing the `thesaurus` feature with the following QPL definition:

```text
replace "car", /(dodge) \w+/ to "automobile", "motor vehicle"
```

The following table summarizes how the current `q` expression of different queries going through the `Testing Thesaurus Replace` query pipeline is processed when this statement is applied:

[%header, cols="~,~"]
|===
|Current `q` expression |Processed `q` expression

|`car` |`automobile OR (motor vehicle)`

|`dodge stratus` |`automobile OR (motor vehicle)`

|`dodge caravan car` |`(automobile OR (motor vehicle)) (automobile OR (motor vehicle))`
|===

> **Note**
>
> You can use the `replace` sub-feature along with the no-stemming operator (`+`) to systematically prevent the index from [stemming](https://docs.coveo.com/en/3436/) certain keywords or phrases (that is,  expanding those expressions to other terms that share the same root).
> 
> ```text
replace "dodge" to "+dodge"
```
> 
> This can be useful when a product name has the same root as a frequently used keyword.

## Using the `quote` sub-feature

The `quote` sub-feature allows you to define statements that automatically turn all expressions (keywords or phrases) in an originating set into their corresponding exact phrase match expression, or into the corresponding exact phrase match expression of each expression in a destination set.

You could obtain the same results using the `replace` sub-feature, but the required syntax would be heavier.

In the [Coveo Administration Console](https://docs.coveo.com/en/183/), `quote` statements can be defined by using the [**Match terms exactly**](https://docs.coveo.com/en/3405#match-terms-exactly) thesaurus rule type.

**Examples**

* The following statements:

```text
quote "foo bar"
quote /foo.*/
```

Are respectively equivalent to:

```text
replace "foo bar" to "\"foo bar\""
replace /(?<fooGroup>foo.*)/ to "\"_fooGroup_\""
```

* In an empty query pipeline named `Testing Thesaurus Quote`, you create two distinct statements, each expressing the `thesaurus` feature, with the following QPL definitions:

[example.code]
**Statement 1**

```text
quote /(dodge) \w+/
```
#####  
[example.code]
##### **Statement 2**

```text
quote "car", "automobile" to "motor vehicle"
```
#####  
The following table summarizes how the current `q` expression of different queries going through the `Testing Thesaurus Quote` query pipeline is processed when these statements are applied:

[%header, cols="1,1"]
|===
|Current `q` expression |Processed `q` expression

|`dodge stratus` |`"dodge stratus"`

|`dodge stratus dodge caravan` |`"dodge stratus" "dodge caravan"`

|`car` |`"motor vehicle"`

|`automobile` |`"motor vehicle"`

|`dodge stratus automobile` |`"dodge stratus" "motor vehicle"`
|===

====