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 more. 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), constant query (cq), dq, and lq 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').

  • With Coveo for Salesforce, Salesforce field values using Apex merge field syntax, between double quotes and single braces (for example, "{!Id}").

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

Example

The following query extension expression finds Salesforce cases similar to the currently selected case. It mixes scalar values ('Case'), alias references ({{caseNumber}}, {{subject}}), and a Salesforce field token ("{!Id}"):

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

The expression does the following:

  • Limits results to items of type Case.

  • Boosts items whose concepts correlate with the current case number.

  • Further boosts items that share keywords with the case subject.

  • Excludes the current case from the results.

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 aggregateConditions argument is passed to extensions such as $filterJoin and $join.

Example

The aggregateConditions argument filters the join so that only accounts with won opportunities for which the total opportunity amount exceeds $100,000 are returned:

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

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

In the following example, the expression finds the top Coveo participants for emails that match the current message subject. Because computing the set of matching emails is expensive, it’s stored in the emailsMatchingSubject alias on the first line and reused on the last line instead of being recalculated:

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

In this example, $onlyAddressesFromCoveo is a query extension specific to the Coveo for Salesforce connector. It’s not a built-in Search API extension.

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

  • SortByAlphaAscending

  • SortByAlphaDescending

  • SortByComputedFieldAscending

  • SortByComputedFieldDescending

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

Include 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 keywords report and dashboard:

report  /* exclude archived content */ dashboard

Use Salesforce object fields

With Coveo for Salesforce, you can embed Salesforce object field values in query extension expressions using Salesforce merge field syntax. These tokens are resolved by the Coveo for Salesforce component before the expression is sent to the Search API, meaning that the Search API receives only the already-interpolated string, never the raw tokens.

  • {!sfObject} resolves to the raw content of the Salesforce object field.

  • {!>sfObject} resolves to the cleaned-up content of the field, in which illegal characters and both leading and trailing spaces are removed.

The following expression uses the case number ('{!CaseNumber}') and subject ('{!>Subject}') of the currently selected Salesforce case. The !> prefix ensures that the subject string is sanitized before the expression is sent to the Search API:

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