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, etc. This article describes and provides examples of the basic syntax and concepts used in 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 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)

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) values between single quotes (e.g., 'Case').
  • Salesforce field values between double quotes and single braces (e.g., "{!Id}") (see Using Salesforce Objects Fields).
  • Alias names 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}"

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.

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

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

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

The result set returned by the following 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 by 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} 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}' )

Using no syntax blocks

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

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

You use the $some query extension on the myDescription variable. Because the content of the myDescription variable is entered by end users, it’s likely that it will sometimes contain special characters:

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

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 (see Manage Thesaurus Rules).

What’s next?

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