---
title: Standard query extensions
slug: '1462'
canonical_url: https://docs.coveo.com/en/1462/
collection: build-a-search-ui
source_format: adoc
---
# Standard query extensions

The standard [query extensions](https://docs.coveo.com/en/1397/) are built-in elements of the [query extension language](https://docs.coveo.com/en/1415/) that you can use in [queries](https://docs.coveo.com/en/231/).
This article describes and provides examples for the available standard [query extensions](https://docs.coveo.com/en/1397/).

> **Note**
>
> The [query extensions](https://docs.coveo.com/en/1397/) described in this article are usable in the [basic (`q`)](https://docs.coveo.com/en/178/), [advanced (`aq`)](https://docs.coveo.com/en/175/), [constant (`cq`)](https://docs.coveo.com/en/179/), or [disjunction (`dq`)](https://docs.coveo.com/en/190/) parts of the query expression.
> 
> However, [query extensions](https://docs.coveo.com/en/1397/) returning the _sequence_ type, such as `$valuesOfField`, `$joinValues`, or `$splitValues`, are only meant to be used as arguments of other [query extensions](https://docs.coveo.com/en/1397/).
> 
> For example, you want the results to be ordered by descending date rather than the default, which is relevance.
> You inject a `$sort` [query extension](https://docs.coveo.com/en/1397/) into the [advanced query expression (`aq`)](https://docs.coveo.com/en/175/) so that it's transparent to the user:
> 
> ```text
/rest/search?q=user%20keywords&aq=$sort(criteria:'datedescending')
```

## General extensions

### $q

Injects the [basic query expression (`q`)](https://docs.coveo.com/en/178/) inside another query expression.

This extension is useful when another part of the [query](https://docs.coveo.com/en/231/) expression (either [advanced](https://docs.coveo.com/en/175/) or [disjunction](https://docs.coveo.com/en/190/)) should contain the [keywords](https://docs.coveo.com/en/2738/) entered by the user.
A typical use is inside [nested queries](https://docs.coveo.com/en/220/) to match additional content.

**Examples**

The following [advanced query expression](https://docs.coveo.com/en/175/) will expand to `foo bar baz` if the [basic query expression](https://docs.coveo.com/en/178/) is `bar`: `foo $q() baz`.

### $qf

Evaluates a [query function](https://docs.coveo.com/en/232/) against each [item](https://docs.coveo.com/en/210/) in the result set and stores the resulting values in a dynamic, temporary [field](https://docs.coveo.com/en/200/) that's generated at [query](https://docs.coveo.com/en/231/) time.
These values can then be used for almost any normal numeric [field](https://docs.coveo.com/en/200/) operation, including further [query functions](https://docs.coveo.com/en/232/).

**Examples**

* For each [item](https://docs.coveo.com/en/210/) in the [query](https://docs.coveo.com/en/231/) result set, evaluate the distance between that [item](https://docs.coveo.com/en/210/) and a specific location, and store the resulting value in the `@distance` dynamic [field](https://docs.coveo.com/en/200/).

`$qf(function: 'dist(@latitude, @longitude, 46.8167, -71.2167)', fieldName: 'distance')`

where:

** `@latitude` and `@longitude` are floating point numeric [fields](https://docs.coveo.com/en/200/) available in your [index](https://docs.coveo.com/en/204/).

** `46.8167` and `-71.2167` are the latitude and longitude of the current reference position.

* For each [item](https://docs.coveo.com/en/210/) in the [query](https://docs.coveo.com/en/231/) result set, divide the byte size of that [item](https://docs.coveo.com/en/210/) by 1024, and store the resulting value in the `@sizekb` dynamic [field](https://docs.coveo.com/en/200/).

`$qf(function: '@size/1024', fieldName: 'sizekb')`

> **Note**
>
> You can also use the [`queryFunctions`](https://docs.coveo.com/en/13#operation/searchUsingPost-queryFunctions) parameter to include [query functions](https://docs.coveo.com/en/232/) in a query.

`$qf` parameters:

#### function (scalar [string])

The mathematical expression to evaluate against each [item](https://docs.coveo.com/en/210/) in the [query](https://docs.coveo.com/en/231/) result set.

> **Notes**
>
> * [query function](https://docs.coveo.com/en/232/) expressions support the geolocation distance function (`dist`) and the [C{plus}{plus} Mathematical Expression Toolkit Library (ExprTk)](http://www.partow.net/programming/exprtk/index.html) syntax.
> Although `if` and `switch` statements are supported, the following statements have been disabled:
> 
> ** `for`
> 
> ** `while`
> 
> ** `repeat until`
> 
> * If your [query function](https://docs.coveo.com/en/232/) expression references certain numeric [fields](https://docs.coveo.com/en/200/), you should ensure that the [`useCacheForComputedFacet`](https://docs.coveo.com/en/8#tag/Fields/operation/createField-useCacheForComputedFacet) option is enabled for each of those [fields](https://docs.coveo.com/en/200/) to speed up evaluation.

Sample value: `'dist(@latitude, @longitude, 46.8167, -71.2167)'`

#### fieldName (scalar [string])

The name of the dynamic, temporary [field](https://docs.coveo.com/en/200/) in which to store the values resulting from evaluating the [`function`](#function-scalar-string).

Must start with a lowercase alphabetical character, and may only contain lowercase alphanumeric or underscore characters.

> **Notes**
>
> * You can't use dynamic [field](https://docs.coveo.com/en/200/) values to override existing [field](https://docs.coveo.com/en/200/) values.
> For example, `$qf(function: 'sqrt(@size)', fieldName: '@size')` has no effect.
> 
> * In a [Group By](https://docs.coveo.com/en/203/) operation, you can use a dynamic [field](https://docs.coveo.com/en/200/) as the [`field`](https://docs.coveo.com/en/13#operation/searchUsingPost-groupBy-field) value.
>  
> However, when doing so, setting [`generateAutomaticRanges`](https://docs.coveo.com/en/13#operation/searchUsingPost-groupBy-generateAutomaticRanges) to `true` has no effect (that is, you must explicitly specify [`rangeValues`](https://docs.coveo.com/en/13#operation/searchUsingPost-groupBy-rangeValues)).
> You can also use a dynamic [field](https://docs.coveo.com/en/200/) as the [`field`](https://docs.coveo.com/en/13#operation/searchUsingPost-groupBy-computedFields) value of a computed [field](https://docs.coveo.com/en/200/).

Sample value: `'distance'`

### $qre

Injects a [query ranking expression (QRE)](https://docs.coveo.com/en/1472/) into the [query](https://docs.coveo.com/en/231/).
A [QRE](https://docs.coveo.com/en/1472/) applies a specific ranking score modifier to the [items](https://docs.coveo.com/en/210/) in a specific result set.

Returns a result set.

**Examples**

* Increase the ranking score of all book [items](https://docs.coveo.com/en/210/) by 1000 (cache the [query](https://docs.coveo.com/en/231/) result set):

`$qre(expression: @documenttype==Book, modifier: '100', isConstant: true)`

* Increase the ranking score of all [items](https://docs.coveo.com/en/210/) already ranked high enough by the [index](https://docs.coveo.com/en/204/), and whose concepts contain any of the [basic query expression](https://docs.coveo.com/en/178/) [keywords](https://docs.coveo.com/en/2738/), by 100 (don't cache the [query](https://docs.coveo.com/en/231/) result set):

`$qre(expression: @concepts=$splitValues(text: $query, separator: '\s'), modifier: 10, applyToEveryResults: 'false')`

> **Note**
>
> You can also configure conditional [QREs](https://docs.coveo.com/en/1472/) in your [query pipelines](https://docs.coveo.com/en/180/) (see [Ranking expression - query pipeline feature](https://docs.coveo.com/en/1452/)).

`$qre` parameters:

#### expression (result set)

The [query](https://docs.coveo.com/en/231/) expression whose result set [items](https://docs.coveo.com/en/210/) the [QRE](https://docs.coveo.com/en/1472/) should apply to.

Sample value: `@documenttype==Book`

#### modifier (scalar [integer])

The ranking score modifier to apply to each [item](https://docs.coveo.com/en/210/) in the `expression` [query](https://docs.coveo.com/en/231/) result set.
A positive value increases ranking scores, whereas a negative one reduces them.

Must be in the range `[-1000000, 1000000]`.

> **Important**
>
> The `modifier` value is correlated to the ranking score of a [query](https://docs.coveo.com/en/231/) result set [item](https://docs.coveo.com/en/210/) by a 1 to 10 ratio.
> For example, a `modifier` value of `'100'` adds 1000 to the ranking score of each [item](https://docs.coveo.com/en/210/) in the `expression` [query](https://docs.coveo.com/en/231/) result set.
> 
> Typically, you should use a modifier value between `'-100'` and `'100'`, unless you want to completely override the [index](https://docs.coveo.com/en/204/) ranking scores.

Sample value: `'100'`

#### isConstant (scalar [boolean], _optional_)

Whether to treat the `expression` as a [constant query expression (`cq`)](https://docs.coveo.com/en/179/) (and cache its result set).

> **Note**
>
> You should leave this option set to `'false'` if the `expression` contains a [nested query](https://docs.coveo.com/en/220/) or if it's based on user input:
> 
> `@concepts=$splitValues(text: $query, separator: '\s')`

Default value: `'false'`

#### applyToEveryResults (scalar [boolean], _optional_)

Whether to apply the [QRE](https://docs.coveo.com/en/1472/) to every [item](https://docs.coveo.com/en/210/) in the `expression` [query](https://docs.coveo.com/en/231/) result set, regardless of its current ranking score.
When this option is set to `'false'`, the [QRE](https://docs.coveo.com/en/1472/) only applies to [query](https://docs.coveo.com/en/231/) result set [items](https://docs.coveo.com/en/210/) whose current ranking score is considered high enough by the [index](https://docs.coveo.com/en/204/).

Default value: `'true'`

### $qrf

Injects a [query ranking function (QRF)](https://docs.coveo.com/en/237/) in the [query](https://docs.coveo.com/en/231/), effectively creating a custom ranking algorithm for that [query](https://docs.coveo.com/en/231/).

Returns a result set.

**Examples**

* For each [item](https://docs.coveo.com/en/210/) in the [query](https://docs.coveo.com/en/231/) result set, increase the ranking score of that [item](https://docs.coveo.com/en/210/) by the square root of its current view count:

`$qrf(expression: 'sqrt(@viewcount)')`

* For each [item](https://docs.coveo.com/en/210/) in the [query](https://docs.coveo.com/en/231/) result set, add a normalized boost of 0 to 600 to the ranking score of that [item](https://docs.coveo.com/en/210/) based on whichever is higher between its last update date and a date that corresponds to four weeks ago:

`$qrf(expression: 'max(@date, (NOW - (WEEK * 4)))', normalizeWeight: 'true')`

* For each [item](https://docs.coveo.com/en/210/) in the [query](https://docs.coveo.com/en/231/) result set, add a normalized boost of 0 to 1000 to the ranking score of that [item](https://docs.coveo.com/en/210/) depending on how good its rating or price ratio is:

`$qrf(expression: '@rating / @price', normalizeWeight: 'true', modifier: '1000')`

> **Note**
>
> You can also use the [`rankingFunctions`](https://docs.coveo.com/en/13#operation/searchUsingPost-rankingFunctions) [query](https://docs.coveo.com/en/231/) parameter to include [QRFs](https://docs.coveo.com/en/237/) in a [query](https://docs.coveo.com/en/231/).

> **Important**
>
> Ranking functions operate with floating-point precision rather than integers.
> As a result, calculations may introduce minor inaccuracies due to the inherent limitations of floating-point arithmetic.
> 
> Using ranking functions with dates or other data requiring high precision isn't recommended, unless some imprecision is acceptable for your use case.
> For scenarios in which precision is critical, use [query ranking expressions (QREs)](https://docs.coveo.com/en/1472/) instead.

`$qrf` parameters:

#### expression (scalar [string])

The mathematical expression to evaluate against each [item](https://docs.coveo.com/en/210/) in the [query](https://docs.coveo.com/en/231/) result set.
The result of this expression for a given [item](https://docs.coveo.com/en/210/) generates a boost which is then added to the ranking score of that [item](https://docs.coveo.com/en/210/).

> **Notes**
>
> * [QRF](https://docs.coveo.com/en/237/) expressions support the geolocation distance function (`dist`) and the [C{plus}{plus} Mathematical Expression Toolkit Library (ExprTk)](http://www.partow.net/programming/exprtk/index.html) syntax.
> Although `if` and `switch` statements are supported, the following statements have been disabled:
> 
> ** `for`
> 
> ** `while`
> 
> ** `repeat until`
> 
> * The following time constants are available in [QRF](https://docs.coveo.com/en/237/) expressions:
> 
> ** `NOW`: A value corresponding to the date and time of the precise moment when the [query](https://docs.coveo.com/en/231/) was performed.
> 
> ** `YEAR`: A value corresponding to the duration of a year (that is, 365.25 days).
> 
> ** `WEEK`: A value corresponding to the duration of a week.
> 
> ** `DAY`: A value corresponding to the duration of a day.
> 
> * If your [QRF](https://docs.coveo.com/en/237/) expression references certain numeric [fields](https://docs.coveo.com/en/200/), you should ensure that the [`useCacheForComputedFacet`](https://docs.coveo.com/en/8#tag/Fields/operation/createField-useCacheForComputedFacet) option is enabled for each of those [fields](https://docs.coveo.com/en/200/) to speed up evaluation.

Sample value: `'sqrt(@viewcount)'`

#### normalizeWeight (scalar [boolean], _optional_)

Whether to normalize the ranking score boosts resulting from the evaluation of this [query ranking function (QRF)](https://docs.coveo.com/en/237/) using the standard [index](https://docs.coveo.com/en/204/) scale.

Default value: `'false'`

> **Tip**
>
> Unless you want to completely override the [index](https://docs.coveo.com/en/204/) ranking and use the results of this {query-ranking function} directly to boost the ranking scores of [query](https://docs.coveo.com/en/231/) results, you should set this parameter to `'true'`.

#### modifier (scalar [unsigned integer], _optional_)

The maximum boost that this [query ranking function (QRF)](https://docs.coveo.com/en/237/) can add to the ranking score of any given [query](https://docs.coveo.com/en/231/) result.
This property only has a meaning if `normalizeWeight` is set to `'true'`.

> **Note**
>
> Unlike the [`$qre`](#qre) [`modifier`](#modifier-scalar-integer), this boost **isn't** correlated to the ranking score of a [query](https://docs.coveo.com/en/231/) result set [item](https://docs.coveo.com/en/210/) by a 1 to 10 ratio.

Must be in the range `[0, 1000000]`.

Default value: `'600'`

### $weight

Adjusts the weight of a specific ranking factor for the [query](https://docs.coveo.com/en/231/).

Returns a result set.

**Examples**

* Slightly increase the weight of the `TFIDF` ranking factor for the current [query](https://docs.coveo.com/en/231/):

`$weight(name: 'TFIDF', value: '6')`

* Reduce the weight of the `concept` ranking factor to its minimum value for the current [query](https://docs.coveo.com/en/231/):

`$weight(name: 'Concept', value: '0')`

* Increase the weight of the `docDate` ranking factor to its maximum value for the current [query](https://docs.coveo.com/en/231/):

`$weight(name: 'DocDate', value: '9')`

> **Note**
>
> You can also configure conditional [ranking weight rules](https://docs.coveo.com/en/1470/) in your [query pipelines](https://docs.coveo.com/en/180/).

`$weight` parameters:

#### name (scalar [string])

The name of the ranking factor whose weight should be altered.

Allowed values:

* `Adjacency`: The proximity of [query](https://docs.coveo.com/en/231/) terms to one another in the [item](https://docs.coveo.com/en/210/).


* `Concept`: [query](https://docs.coveo.com/en/231/) terms in the automatically populated `@concepts` [field](https://docs.coveo.com/en/200/) for the [item](https://docs.coveo.com/en/210/).

* `CustomDocumentWeight`: Custom weight assigned through an [indexing pipeline extension (IPE)](https://docs.coveo.com/en/206/) for the [item](https://docs.coveo.com/en/210/).

* `DocDate`: How recently the [item](https://docs.coveo.com/en/210/) was modified.

* `Formatted`: How [query](https://docs.coveo.com/en/231/) terms are formatted in the [item](https://docs.coveo.com/en/210/).
Possible formatting types include heading level, bold, and large.

* `Language`: Whether the [item](https://docs.coveo.com/en/210/) is in the language of the [search interface](https://docs.coveo.com/en/2741/) from which the [query](https://docs.coveo.com/en/231/) originates.

* `Quality`: The proximity of the [item](https://docs.coveo.com/en/210/) to the root of the [indexed](https://docs.coveo.com/en/204/) system.

* `SourceReputation`: The rating of the [source](https://docs.coveo.com/en/246/) in which the [item](https://docs.coveo.com/en/210/) resides.

* `Summary`: [query](https://docs.coveo.com/en/231/) terms in the summary of the [item](https://docs.coveo.com/en/210/).

* `TermCorrelation`: [query](https://docs.coveo.com/en/231/) term correlations within [stemming](https://docs.coveo.com/en/3436/) classes in the [item](https://docs.coveo.com/en/210/).

* `TermCasing`: [query](https://docs.coveo.com/en/231/) term casing in the [item](https://docs.coveo.com/en/210/).

* `TFIDF`: Term frequency-inverse document frequency.

* `Title`: [query](https://docs.coveo.com/en/231/) terms in the title of the [item](https://docs.coveo.com/en/210/).

* `URI`: [query](https://docs.coveo.com/en/231/) terms in the URI of the [item](https://docs.coveo.com/en/210/).

> **Important**
>
> The allowed `name` values are case-sensitive.

#### value (scalar [integer])

How much to alter the target ranking factor weight (as determined by the [`name`](#name-scalar-string) argument), relative to its default weight.

Must be in the range `[0, 9]`.

A value of `5` applies the default ranking weight, as determined by the [index](https://docs.coveo.com/en/204/).
A value of less than `5` reduces the ranking factor weight, whereas a value greater than `5` increases it.

### $sort

Sorts the result set according to the specified criterion.

Returns a result set.

**Examples**

* Sort the result set [items](https://docs.coveo.com/en/210/) in descending order based on the date of their last update:

`$sort(criteria: 'datedescending')`

* Sort the result set [items](https://docs.coveo.com/en/210/) in ascending order based on their respective prices:

`$sort(criteria: 'fieldascending', field: '@price')`

> **Note**
>
> You can also use the [`sortCriteria`](https://docs.coveo.com/en/13#operation/searchUsingPost-sortCriteria) [query](https://docs.coveo.com/en/231/) parameter to specify how to sort the result set of a [query](https://docs.coveo.com/en/231/).

`$sort` parameters:

#### criteria (scalar [string])

The criteria to use to sort the result set.

Allowed values:

* `relevancy`: Use configured ranking weights as well as any specified ranking expressions to sort the result set.

* `dateascending`/`datedescending`: Use the `@date` [field](https://docs.coveo.com/en/200/) to sort the result set.
This [field](https://docs.coveo.com/en/200/) typically contains the last modification date of an [item](https://docs.coveo.com/en/210/) in the [index](https://docs.coveo.com/en/204/).

* `rankingexpressions`: Sort the result set using only the weights applied through [query ranking expressions (QREs)](https://docs.coveo.com/en/1472/).
This is similar to `relevancy`, except that ranking factor weights such as adjacency and TFIDF aren't computed.

* `noranking`: Don't sort the result set.
The [index](https://docs.coveo.com/en/204/) will return the result set [items](https://docs.coveo.com/en/210/) in an essentially random order.

* `fieldascending`/`fielddescending`: Sort the result set using the values of a specified, sortable [`field`](#field-scalar-string-optional).

Sample value: `'fieldascending'`

#### field (scalar [string], _optional_)

The name of the [field](https://docs.coveo.com/en/200/) on which to sort the result set.
Only required when using `fieldascending` or `fielddescending` as a [`criteria`](#criteria-scalar-string).
If specified, must reference an existing, sortable [field](https://docs.coveo.com/en/200/) in the [index](https://docs.coveo.com/en/204/).

> **Note**
>
> If the [field](https://docs.coveo.com/en/200/) being used isn't numeric (that is, string), ensure that its [`sort`](https://docs.coveo.com/en/8#tag/Fields/operation/createField-sort) option is set to `true`.
> Otherwise, sorting will fail.

Sample value: `'@price'`

### $fold

Groups up to a specific number of [items](https://docs.coveo.com/en/210/) matching the [query](https://docs.coveo.com/en/231/) and sharing the same value for a specific [field](https://docs.coveo.com/en/200/).
Grouped items are _folded_ under the [item](https://docs.coveo.com/en/210/) in that same group that would appear first in the sorted [query](https://docs.coveo.com/en/231/) result set.

Returns a result set.

**Example**

Fold up to five [items](https://docs.coveo.com/en/210/) with the same conversation ID under the same result:

`$fold(field: '@conversationid', range: '5')`

> **Note**
>
> You can also use the [`filterField`](https://docs.coveo.com/en/13#operation/searchUsingPost-filterField) and [`filterFieldRange`](https://docs.coveo.com/en/13#operation/searchUsingPost-filterFieldRange) [query](https://docs.coveo.com/en/231/) parameters to request folded [query](https://docs.coveo.com/en/231/) results.

`$fold` parameters:

#### field (scalar [string])

A [field](https://docs.coveo.com/en/200/) that has the same value for all of the [items](https://docs.coveo.com/en/210/) that you want to group or fold.
Must reference an existing [field](https://docs.coveo.com/en/200/) in the [index](https://docs.coveo.com/en/204/).

> **Note**
>
> The values of the [field](https://docs.coveo.com/en/200/) must only contain alphanumeric characters.
> Trying to fold [items](https://docs.coveo.com/en/210/) on a [field](https://docs.coveo.com/en/200/) whose values contain non-[indexable](https://docs.coveo.com/en/204/) characters (such as underscores) will fail.

**Example**

Trying to fold [items](https://docs.coveo.com/en/210/) on a [field](https://docs.coveo.com/en/200/) containing values such as `id_123` will fail.

The [field](https://docs.coveo.com/en/200/) should contain values such as `id123` instead.

Sample value: `'@conversationid'`

#### range (scalar [unsigned integer])

The maximum number of [items](https://docs.coveo.com/en/210/) to fold under the `childResults` array of the group [item](https://docs.coveo.com/en/210/) that would appear first in the sorted [query](https://docs.coveo.com/en/231/) result set.

Sample value: `'5'`.

### $loadParent

Load an [item](https://docs.coveo.com/en/210/) which is the parent of another [item](https://docs.coveo.com/en/210/).
The parent-child relationship is determined by the presence of the parent ID value among the [fields](https://docs.coveo.com/en/200/) of the child [item](https://docs.coveo.com/en/210/).

Returns a result set.

**Example**

Loads the parent result that has the ID specified in the child [item](https://docs.coveo.com/en/210/).

`$loadParent(parent:'@messageid', child:'@parentmessageid')`

> **Note**
>
> You can also use the [`parentField`](https://docs.coveo.com/en/13#operation/searchUsingPost-parentField) and [`childField`](https://docs.coveo.com/en/13#operation/searchUsingPost-childField) [query](https://docs.coveo.com/en/231/) parameters to identify parent-child relationships in the result set of a [query](https://docs.coveo.com/en/231/).

#### parent (scalar [string])

The name of the [field](https://docs.coveo.com/en/200/) to use to identify the parent [item](https://docs.coveo.com/en/210/).
This should correspond to a [field](https://docs.coveo.com/en/200/) whose value can uniquely identify the parent [item](https://docs.coveo.com/en/210/).
Any [item](https://docs.coveo.com/en/210/) whose child [field](https://docs.coveo.com/en/200/) value is the same as the parent [field](https://docs.coveo.com/en/200/) value of another [item](https://docs.coveo.com/en/210/) is considered a child of that [item](https://docs.coveo.com/en/210/).

Sample value: `'@messageid'`

#### child (scalar [string])

The name of the [field](https://docs.coveo.com/en/200/) to use to identify an [item](https://docs.coveo.com/en/210/) as a child of another [item](https://docs.coveo.com/en/210/).
Whenever an [item](https://docs.coveo.com/en/210/) is a child of another [item](https://docs.coveo.com/en/210/), its child [field](https://docs.coveo.com/en/200/) value should be the same as the parent [field](https://docs.coveo.com/en/200/) value of its parent.

Sample value: `'@parentmessageid'`

### $quoteVar

Allows you to put the value between double quotes `("value")`.
This is useful when you want to set a value between double quotes in a [basic](https://docs.coveo.com/en/178/), [advanced](https://docs.coveo.com/en/175/), [constant](https://docs.coveo.com/en/179/), or [disjunction](https://docs.coveo.com/en/190/) [query](https://docs.coveo.com/en/231/).
It's also useful in [query ranking expressions (QREs)](https://docs.coveo.com/en/1472/).

**Examples**

* `$quoteVar(value: myvalue)` returns `"myvalue"`.

* `@title=$quoteVar(value: This is my title)` returns `@title="This is my title"`.

* `$quoteVar` helps when string concatenation is present in a [field](https://docs.coveo.com/en/200/) [query](https://docs.coveo.com/en/231/) expression.
For example, none of the following would produce the expected `@myfield=="some static text $query"` output:

--
** `@myfield==some static text $query`

** `@myfield==(some static text $query)`

** `@myfield=="some static text $query"`
--

However, the following does work with `$quoteVar`:

--
** `@myfield==$quoteVar(value: some static text $query)`
--

### $stripXml

Removes all XML tags from an expression.

**Example**

Consider the following [context](https://docs.coveo.com/en/13#operation/searchUsingPost-context):

```text
{
  "context": {
    "Case_Subject": "<h1>Hello</h1>"
  }
}
```

The [QueryParamOverride](https://docs.coveo.com/en/1491/) `override query q: \"<@+ $stripXml(value: $context.Case_Subject) +@>\"` will result in a [`q`](https://docs.coveo.com/en/178/) containing `"Hello"`.

[%header,cols="1,4"]
|===
|Argument
|Description

|`value`
|The value to filter.
|===

## Keyword extensions

### $anyKeywords

Tokenizes the input and produces an `OR` expression.

**Example**

`$anyKeywords(keywords:$splitValues(text:'first , second', separator:','))` produces `first OR second`.

### $allKeywords

Tokenizes the input and produces an `AND` expression.

**Example**

`$allKeywords(keywords:$splitValues(text:'first , second', separator:','))` produces `first AND second`.

## Extensions for lists of values

### $valuesOfField

Lists all of the distinct values of a [field](https://docs.coveo.com/en/200/) in a result set.

**Example**

The following [query extension](https://docs.coveo.com/en/1397/) returns all of the work emails associated with the result set specified by the `Contacts` alias:

`$valuesOfField(field: '@sysworkemail', resultSet: @firstname==john)`

[%header,cols="~,~"]
|===
|Argument
|Description

|`resultSet`
|The result set for which to compute the list of values.

|`field`
|The name of the [field](https://docs.coveo.com/en/200/) whose values should be retrieved.

|`aggregateConditions`
|Optional.
The [aggregate conditions](https://docs.coveo.com/en/1465#aggregate-conditions) to use to filter the values based on a computed [field](https://docs.coveo.com/en/200/) operation.

|`maximum`
|Optional.
The maximum number of values to retrieve.
If not specified, all of the values are retrieved.

|`sortOrder`
|Optional.
The [sort order](https://docs.coveo.com/en/1465#group-by-sort-orders) to use when retrieving values.
The default value is `donotsort`.
|===

### $keepMatchingValues

Filters a list to select only the values matching a regular expression.

**Example**

The following extension returns only email addresses from the `company.com` domain:

`$keepMatchingValues(regex: '.*@company.com', values: {{addresses}})`

[%header,cols="1,4"]
|===
|Argument
|Description

|`regex`
a|The regular expression to use.

> **Note**
>
> Use the Java [regular expression](https://docs.coveo.com/en/1449#regular-expressions) (REGEX) syntax.

|`values`
|The list of values to filter.
|===

### $removeMatchingValues

Filters a list to remove all values matching a regular expression.

**Example**

The following extension returns all email addresses except those ending with `@company.com`:

`$removeMatchingValues(regex: '.*@company.com', values: {{addresses}})`

[%header,cols="1,4"]
|===
|Argument
|Description

|`regex`
a|The regular expression to use.

> **Note**
>
> Use the Java [regular expression](https://docs.coveo.com/en/1449#regular-expressions) (REGEX) syntax.

|`values`
|The list of values to filter.
|===

### $removeEmptyValues

Filters a list to remove all of the empty values.

**Example**

The following extension eliminates the empty values from the values returned by `{{addresses}}`:

`$removeEmptyValues(values: {{addresses}})`

[%header,cols="1,4"]
|===
|Argument
|Description

|`values`
|The list of values to filter.
|===

### $removeDuplicateValues

Filters a list to remove all of the duplicate values.

**Example**

The following extension eliminates the duplicate values from the values returned by `{{addresses}}`:

`$removeDuplicateValues(values: {{addresses}})`

[%header,cols="1,4"]
|===
|Argument
|Description

|`values`
|The list of values to filter.
|===

### $replaceInValues

Transforms a list using a regular expression.

**Example**

In the list of values returned by `{{addresses}}`, the following extensions replace occurrences of the string `company` with the string `somethingelse`, and `.com` value endings with `.org`.

```javascript
$replaceInValues(values: {{addresses}}, regex: 'company', replacement: 'somethingelse')
$replaceInValues(values: {{addresses}}, regex: '(.*)\.com', replacement: '$1.org')
```

[%header,cols="~,~"]
|===
|Argument
|Description

|`regex`
a|The regular expression to use.

> **Note**
>
> Use the Java [regular expression](https://docs.coveo.com/en/1449#regular-expressions) (REGEX) syntax.

|`replacement`
|The replacement string to use with the regular expression.

|`values`
|The list of values to transform.

|`removeNonMatchingValues`
|Optional.
If `true`, all values that don't match the regular expression are removed.
By default, non-matching values are kept as is.

|`removeEmptyValues`
|Optional.
If `true`, all values that are empty following the replacement are removed.
By default, empty values are kept.

|`removeDuplicateValues`
|Optional.
If `true`, all duplicate values following the replacement are removed.
By default, duplicate values are kept.
|===

### $mergeValues

Merges two lists of values together.
Duplicate values are only included once.

**Example**

The following [query extension](https://docs.coveo.com/en/1397/) merges the `{{addresses}}` and `{{anotherListOfAddresses}}` lists of values:

`$mergeValues(first: {{addresses}}, second: {{anotherListOfAddresses}})`

[%header,cols="1,4"]
|===
|Argument
|Description

|`first`
|The first list of values to merge.

|`second`
|The second list of values to merge.
|===

### $joinValues

Joins a list of values into a string.

**Example**

The following expression joins a list of values into a string:

`$joinValues(values: {{values}}, separator: ',')`

[%header,cols="1,4"]
|===
|Argument
|Description

|`values`
|The list of values to join.

|`separator`
|The separator to put between values.
|===

### $splitValues

Splits a string into a list of values.

**Example**

The following expression splits a string into a list of values:

`$splitValues(text: 'foo, bar, baz', separator: ',')`

[%header,cols="1,4"]
|===
|Argument
|Description

|`text`
|The string value to split.

|`separator`
|The separator that separates each value.
|===

## Join extensions

The join [query extensions](https://docs.coveo.com/en/1397/) produce similar operations as the join [keyword](https://docs.coveo.com/en/2738/) used in an SQL statement.

### $valuesToResultSet

Converts a list of values to a result set matching the [items](https://docs.coveo.com/en/210/) where a given [field](https://docs.coveo.com/en/200/) is equal to a value in the list.
The original order of the values in the result set is preserved using [ranking expressions](https://docs.coveo.com/en/1472/).

**Example**

The following [query extension](https://docs.coveo.com/en/1397/) returns a result set of [items](https://docs.coveo.com/en/210/) for which the `@sysworkemail` [field](https://docs.coveo.com/en/200/) contains a value present in the `{{addresses}}` list of values:

`$valuesToResultSet(values: {{addresses}}, field: '@sysworkemail')`

[%header,cols="1,4"]
|===
|Argument
|Description

|`values`
|The values to filter with.

|`field`
|The name of the [field](https://docs.coveo.com/en/200/) to use.

|`modifier`
|Optional.
The modifier to use for the [ranking expressions](https://docs.coveo.com/en/1472/).

|`minimumModifier`
|Optional.
The minimum modifier to use for the [ranking expressions](https://docs.coveo.com/en/1472/).
|===

### $joinOnValues

Filters a result set to only the [items](https://docs.coveo.com/en/210/) for which a given [field](https://docs.coveo.com/en/200/) is equal to one of the values contained in a list.
The order of the values can optionally be preserved in the resulting result set when the modifier argument is specified.
The extension returns a result set filtered on the [field](https://docs.coveo.com/en/200/) values.
Any [ranking expressions](https://docs.coveo.com/en/1472/) associated with the result set are kept.

**Example**

The following [query extension](https://docs.coveo.com/en/1397/) returns only [items](https://docs.coveo.com/en/210/) for which the email domain name is listed in the specified `domains` alias:

`$joinOnValues(resultSet: @uri, field: '@sfemaildomainnames', values: {[domains](https://docs.coveo.com/en/2819/)})`

[%header,cols="1,4"]
|===
|Argument
|Description

|`resultSet`
|The result set to filter.

|`field`
|The name of the [field](https://docs.coveo.com/en/200/) to use.

|`values`
|The values to filter with.

|`modifier`
|Optional.
The highest modifier to use for the [ranking expressions](https://docs.coveo.com/en/1472/).

|`minimumModifier`
|Optional.
The minimum modifier to use for the [ranking expressions](https://docs.coveo.com/en/1472/).
|===

### $join

Filters a result set to only the [items](https://docs.coveo.com/en/210/) for which a given [field](https://docs.coveo.com/en/200/) is equal to a value of another [field](https://docs.coveo.com/en/200/) in another result set.
If the `toResultSet` contains [ranking expressions](https://docs.coveo.com/en/1472/) or sort orders, they will be included in the resulting result set.
The order of the values can optionally be preserved in the resulting result set when the modifier argument is specified.

**Example**

The following [query extension](https://docs.coveo.com/en/1397/) returns only accounts with won opportunities for which the opportunity amount sum is greater or equal to the specified amount alias:

`$join(fromResultSet:  $type(name: 'Opportunity') @sfopportunitystagename=won, toResultSet: $type(name: 'Account'), fromAggregateConditions: $sum(@sfopportunityamount)>={{amount}}, field: '@sfaccountid')`

[%header,cols="1,4"]
|===
|Argument
|Description

|`fromResultSet`
|The result set from which the list of values is extracted.

|`toResultSet`
|The result set to filter.

|`fromField`
|Required if `field` isn't set.
The name of the [field](https://docs.coveo.com/en/200/) to use in the `fromResultSet`.

|`toField`
|Required if `field` isn't set.
The name of the [field](https://docs.coveo.com/en/200/) to use in the `toResultSet`.

|`field`
|Required if `fromField` and `toField` aren't set.
The name of the [field](https://docs.coveo.com/en/200/) to use in both result sets.
This is equivalent to specifying both `fromField` and `toField` with the same value.

|`fromAggregateConditions`
|Optional.
The [aggregate conditions](https://docs.coveo.com/en/1465#aggregate-conditions) to use to filter the from result set before performing the join.

|`maximumValues`
|Optional.
The maximum number of values to filter on.
By default, all values are used.

|`sortOrder`
|Optional.
The sort criteria to use when retrieving values from the `fromResultSet`.
The default value is `donotsort`.

|`modifier`
|Optional.
The highest modifier to use for the [ranking expressions](https://docs.coveo.com/en/1472/).

|`minimumModifier`
|Optional.
The minimum modifier to use for the [ranking expressions](https://docs.coveo.com/en/1472/).
|===

### $filterJoin

Filters a result set to only the [items](https://docs.coveo.com/en/210/) that can be joined in another result set using the specified [fields](https://docs.coveo.com/en/200/).
If the local result set contains [ranking expressions](https://docs.coveo.com/en/1472/) or sort orders, they're included in the resulting result set.
This [query extension](https://docs.coveo.com/en/1397/) basically performs two joins, one from the local to the external result set, and another back from the external to the local result set.

**Example**

The following [query extension](https://docs.coveo.com/en/1397/) returns accounts with won opportunities for which the total amount is greater than $100,000:

`$filterJoin(localResultSet: $type(name: 'Account'), externalResultSet: (@sfopportunitystagename=won), field: '@sfaccountid', aggregateConditions: $sum(@sfopportunityamount)>100000, maximumValues: 5)`

[%header,cols="1,4"]
|===
|Argument
|Description

|`localResultSet`
|The result set to filter.

|`externalResultSet`
|The result set to perform a join on to filter [items](https://docs.coveo.com/en/210/) in `localResultSet`.

|`localField`
|Required if `field` isn't set.
The name of the [field](https://docs.coveo.com/en/200/) to use in the `localResultSet`.

|`externalField`
|Required if `field` isn't set.
The name of the [field](https://docs.coveo.com/en/200/) to use in the `externalResultSet`.

|`field`
|Required if `localField` and `externalField` aren't set.
The name of the [field](https://docs.coveo.com/en/200/) to use in both result sets.
This is equivalent to specifying both `localField` and `externalField` with the same value.

|`aggregateConditions`
|Optional.
The [aggregate conditions](https://docs.coveo.com/en/1465#aggregate-conditions) to use to filter the result set resulting from joining the local result set to the external one.

|`maximumValues`
|Optional.
The maximum number of values to filter on.
By default, all values are used.
|===

## Correlation extensions

### $correlateListOfValues

Outputs a set of [ranking expressions](https://docs.coveo.com/en/1472/) that boosts results having one of several values in a specified `field.Arguments`.

[%header,cols="1,4"]
|===
|Argument
|Description

|`field`
|The name of the [field](https://docs.coveo.com/en/200/) to use.

|`values`
|The values to use for boosting.

|`modifier`
|The maximum modifier to apply when a result matches.
[items](https://docs.coveo.com/en/210/) that match the first value in the list get the highest modifier, and those that match the last one get the lowest modifier.

|`useContainsOperator`
|Optional.
Whether to match using the containment operator (`=`) rather than the identity operator (`==`), which is used by default.

|`useFullText`
|Optional.
If `true`, [query ranking expressions (QREs)](https://docs.coveo.com/en/1472/) will also be output for [items](https://docs.coveo.com/en/210/) that match the [field](https://docs.coveo.com/en/200/) values in full text.
The default value is `false`.

|`forceOneMatch`
|Optional.
If `true`, a [query](https://docs.coveo.com/en/231/) expression will be added that ensures that all results have a least one matching [field](https://docs.coveo.com/en/200/) value.
The default value is `false`.
|===

### $correlateResultSet

Outputs a set of [ranking expressions](https://docs.coveo.com/en/1472/) that boosts results sharing a [field](https://docs.coveo.com/en/200/) value from another result set.

[%header,cols="1,4"]
|===
|Argument
|Description

|`resultSet`
|The result set from which to grab the list of values.

|`fromField`
|Required if `field` isn't set.
The name of the [field](https://docs.coveo.com/en/200/) to use in `resultSet`.

|`toField`
|Required if `field` isn't set.
The name of the [field](https://docs.coveo.com/en/200/) to use in the resulting result set.

|`field`
|Required if `fromField` and `toField` aren't set.
The name of the [field](https://docs.coveo.com/en/200/) to use in both result sets.
This is equivalent to specifying both `fromField` and `toField` with the same value.

|`maximumValues`
|Optional.
The maximum number of values to retrieve from the source result set.
By default, all values are used.

|`sortOrder`
|Optional.
The sort criteria to use when retrieving values from `resultSet`.
The default value is `chisquare`.

|`modifier`
|The highest modifier to use for the {ranking expressions}.
The maximum modifier to apply when a result matches.
[items](https://docs.coveo.com/en/210/) that match the first value in the list get the highest modifier, and those that match the last one get the lowest modifier.

|`useFullText`
|Optional.
If `true`, [query ranking expressions (QREs)](https://docs.coveo.com/en/1472/) will also be output for [items](https://docs.coveo.com/en/210/) that match the [field](https://docs.coveo.com/en/200/) values in full text.
The default value is `false`.

|`forceOneMatch`
|Optional.
If `true`, a [query](https://docs.coveo.com/en/231/) expression will be added that ensures that all results have a least one matching [field](https://docs.coveo.com/en/200/) value.
The default value is `false`.
|===

### $correlateUsingIdf

Outputs an expression that ranks up [items](https://docs.coveo.com/en/210/) sharing [keywords](https://docs.coveo.com/en/2738/) with those specified.
Uses the inverse document frequency (IDF) method to give a greater weight to [keywords](https://docs.coveo.com/en/2738/) that are less frequent in the [index](https://docs.coveo.com/en/204/).

**Example**

You may want to apply this extension when you need to make accessible [items](https://docs.coveo.com/en/210/) that aren't frequently clicked within your [index](https://docs.coveo.com/en/204/).
For example, articles about less popular products.

[%header,cols="1,4"]
|===
|Argument
|Description

|`keywords`
|The string from which to extract [keywords](https://docs.coveo.com/en/2738/).

|`forceOneMatch`
|Optional.
If `true`, a [query](https://docs.coveo.com/en/231/) expression will be added that ensures that all results have at least one matching [keyword](https://docs.coveo.com/en/2738/).
The default value is `false`.

|`removeStopWords`
a|Optional.
If `true`, any English stop word present in the [keywords](https://docs.coveo.com/en/2738/) will be automatically removed.
The default value is `true`.

> **Important**
>
> This argument is deprecated.
> 
> You should use the [stop words](https://docs.coveo.com/en/3406/) [query pipeline feature](https://docs.coveo.com/en/234/) to filter out stop words from the [query](https://docs.coveo.com/en/231/) expression.

|`noStemming`
|Optional.
If `true`, [keywords](https://docs.coveo.com/en/2738/) won't be expanded using the [index](https://docs.coveo.com/en/204/) [stemming](https://docs.coveo.com/en/3436/) before matching [items](https://docs.coveo.com/en/210/).
The default value is `false`.

|`maximum`
|Optional.
The maximum number of [keywords](https://docs.coveo.com/en/2738/) to use.
If a larger number of [keywords](https://docs.coveo.com/en/2738/) is provided, some [keywords](https://docs.coveo.com/en/2738/) will be completely ignored.
The default value is `100`.
|===

### $some

Extracts up to a specific part of "best" terms from a string, then retrieves [items](https://docs.coveo.com/en/210/) that match at least a specific part of those terms from the [index](https://docs.coveo.com/en/204/).

Returns a result set.

**Examples**

* Retrieve items containing at least the `foo`, `bar`, and `baz` terms:

`$some(keywords: 'foo bar baz')`

* Retrieve items containing at least the one "best" term among `foo`, `bar`, and `baz`:

`$some(keywords: 'foo bar baz', best: '1')`

* Retrieve items containing at least two terms among `foo`, `bar`, and `baz`:

`$some(keywords: 'foo bar baz', match: '50%')`

* Retrieve items containing at least one of the best two terms among `foo`, `bar`, and `baz`:

`$some(keywords: 'foo bar baz', best: '50%', 'match': '1')`

* Retrieve items containing at least the terms `foo` and `bar`:

`$some(keywords: 'foo bar baz', maximum: '2')`

* Retrieve items containing at least one of the best two terms among `foo`, `bar`, and `baz`:

`$some(keywords: 'foo bar baz hello', best: '50%', match: '50%', maximum: '3')`

#### keywords (scalar [string])

The string from which to extract a subset of [`best`](#best-scalar-string-unsigned-integer-optional) terms.

> **Note**
>
> All of the original `keywords` terms (not only the "best" terms) are highlighted in matching [items](https://docs.coveo.com/en/210/).

#### best (scalar [string | unsigned integer], _optional_)

The absolute or percentage (rounded up) maximum number of "best" terms to extract from [`keywords`](#keywords-scalar-string).
Terms that occur less frequently in the [index](https://docs.coveo.com/en/204/) are considered "better" than more common [keywords](https://docs.coveo.com/en/2738/).
Applies after [`maximum`](#maximum-scalar-unsigned-integer-optional), but before [`match`](#match-scalar-string-unsigned-integer-optional).

Sample values:

* `'5'`

* `'75%'`

Default value: `'100%'`

#### match (scalar [string | unsigned integer], _optional_)

The absolute or percentage (rounded up) minimum number of "best" terms an [item](https://docs.coveo.com/en/210/) must contain to be included in the result set.
Applies after [`best`](#best-scalar-string-unsigned-integer-optional).

Sample values:

* `'5'`

* `'75%'`

Default value: `'100%'`

#### removeStopWorlds (scalar [boolean], _optional_)

> **Important**
>
> This parameter is deprecated.
> It's exposed for legacy compatibility reasons.
> 
> Use [query pipeline statements](https://docs.coveo.com/en/236/) expressing the [`stop`](https://docs.coveo.com/en/1446/) [query pipeline feature](https://docs.coveo.com/en/234/) instead.

Whether to ignore standard English stop words (`a`, `the`, etc.) in the [`keywords`](#keywords-scalar-string).

Default value: `'false'`

#### maximum (scalar [unsigned integer], _optional_)

The absolute maximum number of terms in [`keywords`](#keywords-scalar-string) to consider when extracting terms (consider the string as a sequence).
Excess [keywords](https://docs.coveo.com/en/2738/) are ignored.

Default value: `'100'`

### $removeStopWords

Removes the English stop words from a list of [keywords](https://docs.coveo.com/en/2738/).

[%header,cols="1,4"]
|===
|Argument
|Description

|`keywords`
|The string from which to extract [keywords](https://docs.coveo.com/en/2738/).
|===

> **Important**
>
> This extension is deprecated.
> 
> You should use the [stop words](https://docs.coveo.com/en/3406/) [query pipeline feature](https://docs.coveo.com/en/234/) to filter out stop words from the [query](https://docs.coveo.com/en/231/) expression.

### $noStemming

Arranges for a list of [keywords](https://docs.coveo.com/en/2738/) to match without using [stemming](https://docs.coveo.com/en/3436/).

[%header,cols="1,4"]
|===
|Argument
|Description

|`keywords`
|The string from which to extract [keywords](https://docs.coveo.com/en/2738/).
|===