---
title: Query extension language basics
slug: '1465'
canonical_url: https://docs.coveo.com/en/1465/
collection: build-a-search-ui
source_format: adoc
---
# Query extension language basics

A [query extension](https://docs.coveo.com/en/1397/) is a named encapsulation of a [query](https://docs.coveo.com/en/231/) that can contain arguments and become a building block for more complex [queries](https://docs.coveo.com/en/231/).
Executing a [query extension](https://docs.coveo.com/en/1397/) can involve running [queries](https://docs.coveo.com/en/231/), working with lists of values, generating [ranking expressions](https://docs.coveo.com/en/1472/), joins, correlations, [Group By](https://docs.coveo.com/en/203/) operations, and so on.
This article describes and provides examples of the basic syntax and concepts used in the Coveo [query extension language](https://docs.coveo.com/en/1415/).

> **Note**
>
> You can use any of the [query extensions](https://docs.coveo.com/en/1397/) described in this article in the [basic query (`q`)](https://docs.coveo.com/en/178/), [advanced query (`aq`)](https://docs.coveo.com/en/175/), or [constant query (`cq`)](https://docs.coveo.com/en/179/) parameters (see [Query parameters](https://docs.coveo.com/en/13#tag/Search-V2/operation/searchUsingPost)).
> 
> For example: `/rest/search?q=user%20keywords&aq=$myExtension(arg1:value, arg2:value)`.

## Invoke a query extension

You can invoke a [query extension](https://docs.coveo.com/en/1397/) by referencing it in a [query](https://docs.coveo.com/en/231/).
The [query extension](https://docs.coveo.com/en/1397/) name begins with a dollar sign (`$`) prefix, and it can include comma-separated argument and value pairs listed between parenthesis as a suffix: `$myExtension(arg1:value, arg2:value)`.

**Example**

The results of the following expression are the [items](https://docs.coveo.com/en/210/) returned by the foo [query](https://docs.coveo.com/en/231/) with a boosted ranking score for the MyCompany account [items](https://docs.coveo.com/en/210/):

```javascript
foo $qre(expression:@sfaccountname=='MyCompany', modifier:'1000')
```

## Use arguments

In [query extensions](https://docs.coveo.com/en/1397/), use the following syntax to refer to various types of arguments:

* Scalar (string, integer, double, Boolean, and date) values between single quotes (for example, `'Case'`).

* [Salesforce field values](#use-salesforce-object-fields) between double quotes and single braces (for example, `"{!Id}"`).

* [Alias](#use-aliases) names between double braces (for example, `{{caseNumber}}`).

**Example**

The following [query extension](https://docs.coveo.com/en/1397/) expression includes various types of arguments:

```javascript
$type(name: 'Case')
$correlateResultSet(resultSet: @syssfcasenumber=={{caseNumber}}, field: '@sysconcepts', maximumValues: '25', modifier: '10000')
$correlateUsingIdf(keywords: {{subject}})
NOT @sfid=="{!Id}"
```

## Argument types

The following are the possible types of values that can be accepted or returned by [query extensions](https://docs.coveo.com/en/1397/):

### Result set

The logical definition of a set of results, with an optional sort order and [ranking expressions](https://docs.coveo.com/en/1472/).

> **Important**
>
> Any [query](https://docs.coveo.com/en/231/) expression passed as an argument to another [query extension](https://docs.coveo.com/en/1397/) is automatically converted to a result set.

### List of string values

A list of values from a result set, typically extracted using a [Group By operation](https://docs.coveo.com/en/1453/).
Currently, the only way to define a list of values from a [query](https://docs.coveo.com/en/231/) is to use a [query extension](https://docs.coveo.com/en/1397/) that returns this type of argument.

The following [query extension](https://docs.coveo.com/en/1397/) returns the list of values in the foo [field](https://docs.coveo.com/en/200/) for the results returned by the `some query` [query](https://docs.coveo.com/en/231/):

```javascript
$valuesOfField(resultSet: some query, field: '@foo')
```

### Scalar

Scalar types such as string, integer, double, Boolean, and date.
You can pass scalar values enclosed in single quotes when invoking a [query extension](https://docs.coveo.com/en/1397/) in the [query](https://docs.coveo.com/en/231/):

```javascript
$extensionName(arg: 'value')
```

### Aggregate conditions

An aggregate condition is an advanced feature.
It can be used to restrict a list of [field](https://docs.coveo.com/en/200/) values that's extracted from a result set, based on a computed [field](https://docs.coveo.com/en/200/) operation.

The following `aggregateConditions` argument filters to [items](https://docs.coveo.com/en/210/) for which the sum of opportunity amounts is greater than or equal to the specified `amount` alias:

```javascript
aggregateConditions: $sum(@sfopportunityamount)>={{amount}}
```

## Use aliases

When you define a [query extension](https://docs.coveo.com/en/1397/), you can define an _alias_ for a complex part of the expression, and then reuse the alias later in the same expression.
An alias only evaluates and stores the intermediate value once, which eliminates duplicate computations.

Define an alias using the following syntax:

```liquid
{{aliasName=aliasValue}}
```

Reuse the alias using the following syntax:

```liquid
{{aliasName}}
```

In the following example, the `emailsMatchingSubject` alias is defined in the first line and reused in the last one:

```javascript
{{emailsMatchingSubject=@sysfrom $correlateUsingIdf(keywords: {{subject}}, forceOneMatch: 'true')}}
$type(name: 'People')
$valuesToResultSet(values: $onlyAddressesFromCoveo(addresses: $participantsForThoseEmails(emails: {{emailsMatchingSubject}}, sortOrder: 'SortByScore', maximum: '25')), field: '@sysworkemail')
```

## Group By sort orders

In a [Group By operation](https://docs.coveo.com/en/1453/), you can specify a sort order by using the `sortOrder` attribute with one of the following values:

* `SortByOccurrence`

* `SortByScore`

* `SortByScoreAlphaAscending`

* `SortByScoreAlphaDescending`

* `SortByChiSquare`

* `SortByNoSort`

In the following example, the result set returned by the following [query extension](https://docs.coveo.com/en/1397/) is ordered by ranking score:

```javascript
$participantsForThoseEmails (emails: {{emailsMatchingSubject}}, sortOrder:  'SortByScore' , maximum:  '25' )), field:  '@sysworkemail' )
```

## Include comments

You can include comments in a [query](https://docs.coveo.com/en/231/) by using the `+/* [comment] */+` syntax.
All of the words between `+/**+` and `+**/+` are ignored.

The following [query](https://docs.coveo.com/en/231/) returns [items](https://docs.coveo.com/en/210/) containing the [keywords](https://docs.coveo.com/en/2738/) `foo` and `bar`:

```javascript
foo  /* This is a comment */ bar
```

## Use Salesforce object fields

With [Coveo for Salesforce](https://docs.coveo.com/en/1404/), when using [query extensions](https://docs.coveo.com/en/1397/), you refer to Salesforce objects using this syntax:

* `{!sfObject}` is the raw content of the object.

* `{!>sfObject}` is the cleaned-up content of the object string, in which illegal characters and both leading and trailing spaces are removed.

The following Coveo [query](https://docs.coveo.com/en/231/) uses the case number (`'{!CaseNumber}'`) and the subject (`'{!>Subject}'`) of the currently selected case.
The `!>` prefix ensures that the subject string is cleaned up before being used:

```javascript
$SalesforceCase_SimilarCases (caseNumber:  '{!CaseNumber}' , subject:  '{!>Subject}' )
```

## Use no syntax blocks

When a variable is included in a [query extension](https://docs.coveo.com/en/1397/) expression, its values may contain special characters that can be interpreted by Coveo [query syntax](https://docs.coveo.com/en/1552/) and produce undesired behavior or errors.

> **Leading practice**
>
> Enclose the variable in a [no syntax block](https://docs.coveo.com/en/1454/) to prevent Coveo [query syntax](https://docs.coveo.com/en/181/) from interpreting it in error.
> No syntax blocks use the delimiters `<@-` and `-@>`.

For example, you use the `$some` [query extension](https://docs.coveo.com/en/1397/) on the `myDescription` variable.
Because the content of the `myDescription` variable is entered by users, it's likely that it will sometimes contain special characters:

```javascript
$some(keywords: <@- myDescription -@>)
```

> **Note**
>
> If you have [query pipeline](https://docs.coveo.com/en/180/) [thesaurus rules](https://docs.coveo.com/en/3405/), ensure that your [keywords](https://docs.coveo.com/en/2738/) aren't enclosed in quotes when you want them to be expanded by the [thesaurus](https://docs.coveo.com/en/2742/).

## What's next?

The Coveo [query extension language](https://docs.coveo.com/en/1415/) is made up of [standard query extensions](https://docs.coveo.com/en/1462/).
You can start using or adapting existing [Coveo for Salesforce](https://docs.coveo.com/en/1404/) [query extension](https://docs.coveo.com/en/1182/) examples.