Query Extension Language Basics

A query extension is a named encapsulation of a query that can have arguments and become a building block for more complex queries. Execution of a query extension can involve running queries, working with lists of values, generating ranking expressions, joins, correlation, group-by, etc. This article describes and provides examples for the basic syntax and concepts of the Coveo query extension language.

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

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

Invoking a Query Extension

You can invoke a query extension by referencing it in a query. The query extension name starts with a dollar sign ($) prefix and can include comma separated argument and value pairs listed between parenthesis as a suffix.

$myExtension(arg1:value, arg2:value)

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')

Using Arguments

In query extensions, use the following syntax to refer to various types of arguments:

  • Scalar (string, integer, double, Boolean, and date) value between single quotes (e.g., 'Case')
  • Salesforce field value between double quotes and single braces (e.g., "{!Id}" ) (see Using Salesforce Objects Fields)
  • Alias name between double braces (e.g., {{caseNumber}}) (see Using Aliases)

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}"

Arguments Types

A query extension can take arguments and return values of those types:

Result Set

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

Any query expression passed as an argument to a 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. Using a query extension returning this type of argument is currently the only way to define a list of values from the query.

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 that can be used to restrict a list of field values 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 or equal to the specified amounts alias.

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

Using Aliases

When you define query extensions, you can define an alias for a complex expression part, and then reuse the alias later in the same expression. An alias only evaluates and stores the intermediate value once thus eliminating duplicate computations.

Define and an alias using the following syntax:

{{aliasName=aliasValue}}

Reuse the alias using the following syntax:

{{aliasName}}

The emailsMatchingSubject alias is defined in the first line and reused in 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 using the sortOrder attribute with one of the following values:

  • SortByOccurrence
  • SortByScore
  • SortByScoreAlphaAscending
  • SortByScoreAlphaDescending
  • SortByChiSquare
  • SortByNoSort

The result set returned by the follow query extension is ordered by ranking score.

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

Including Comments

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

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

foo  /* This is a comment */ bar

Using Salesforce Objects Fields

With Coveo for Salesforce, when using query extensions, you refer to Salesforce objects using this syntax:

  • {!sfObject} - raw content of the object
  • {!>sfObject} - cleaned up content of the object string where illegal characters as well as leading and trailing spaces are removed

The following Coveo query uses the case number ('{!CaseNumber}') and the subject ('{!>Subject}') of the currently selected case. Because the !> prefix is used, the subject string is cleaned up of illegal characters before being used.

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

Using No Syntax Blocks

When a query extension expression includes a variable, the variable values may sometimes contain special characters that can be interpreted by the Coveo query syntax (see Coveo Query Syntax Reference) and produce undesired behavior or errors.

Prevent these issues by enclosing the variable in a no syntax block using the <@- and -@> delimiters (see No Syntax Block).

You use the $some query extension on the myDescription variable. The content of the myDescription variable is entered by end users so there is a fair probability that it will sometimes contain special characters.

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

When you have query pipeline thesaurus rules (see Adding and Managing Query Pipeline Thesaurus Rules), ensure that your keywords are not enclosed in quotes when you want them to be expanded by the thesaurus.

What’s Next?

The Coveo query language is made of standard query extensions that are generic built-in extensions (see Standard Query Extensions). You can start using or adapting existing Coveo for Salesforce query extension examples (see Query Extensions).