Query extension language basics

This is for:

Developer

A query extension is a named encapsulation of a query that can contain arguments and become a building block for more complex queries. Executing a query extension can involve running queries, working with lists of values, generating ranking expressions, joins, correlations, Group By operations, and so on. This article describes and provides examples of the basic syntax and concepts used in the Coveo query extension language.

Note

You can use any of the query extensions described in this article in the basic query (q), advanced query (aq), or constant query (cq) parameters (see Query parameters).

For example: /rest/search?q=user%20keywords&aq=$myExtension(arg1:value, arg2:value).

Invoke a query extension

You can invoke a query extension by referencing it in a query. The query extension 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 returned by the foo query with a boosted ranking score for the MyCompany account items:

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

Use arguments

In query extensions, 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 between double quotes and single braces (for example, "{!Id}").

  • Alias names between double braces (for example, {{caseNumber}}).

Example

The following query extension expression includes various types of arguments:

$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:

Result set

The logical definition of a set of results, with an optional sort order and ranking expressions.

Important

Any query expression passed as an argument to another query extension 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. Currently, the only way to define a list of values from a query is to use a query extension that returns this type of argument.

The following query extension returns the list of values in the foo field for the results returned by the some query query:

$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 in the query:

$extensionName(arg: 'value')

Aggregate conditions

An aggregate condition is an advanced feature. It can be used to restrict a list of field values that’s extracted from a result set, based on a computed field operation.

The following aggregateConditions argument filters to items for which the sum of opportunity amounts is greater than or equal to the specified amount alias:

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

Use aliases

When you define a query extension, 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:

{{aliasName=aliasValue}}

Reuse the alias using the following syntax:

{{aliasName}}

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

{{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, 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 is ordered by ranking score:

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

Include comments

You can include comments in a query by using the /* [comment] */ syntax. All of the words between /* and */ are ignored.

The following query returns items containing the keywords foo and bar:

foo  /* This is a comment */ bar

Use Salesforce object fields

With Coveo for Salesforce, when using query extensions, 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 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:

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

Use no syntax blocks

When a variable is included in a query extension expression, its values may contain special characters that can be interpreted by Coveo query syntax and produce undesired behavior or errors.

Tip
Leading practice

Enclose the variable in a no syntax block to prevent Coveo query syntax from interpreting it in error. No syntax blocks use the delimiters <@- and -@>.

For example, you use the $some query extension 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:

$some(keywords: <@- myDescription -@>)
Note

If you have query pipeline thesaurus rules, ensure that your keywords aren’t enclosed in quotes when you want them to be expanded by the thesaurus.

What’s next?

The Coveo query extension language is made up of standard query extensions. You can start using or adapting existing Coveo for Salesforce query extension examples.