Coveo query syntax examples

This is for:

Developer System Administrator

Coveo for Salesforce uses the standard Coveo query syntax to build simple to complex queries (see Coveo Query Syntax Reference).

While this syntax can be used by end users in the search box itself - as long as you have not disabled the query syntax on your search page (see Querybox - enableQuerySyntax) - it’s most useful when developing search pages, to easily inject complex queries.

On top of the usual Coveo query syntax, Coveo for Salesforce also allows you to use the Query extension language (see Query extension language), which works with the Coveo Search API instead of the Coveo index.

There are two main ways where you can use this syntax to modify a query: server-side and client-side.

  • Server-side filtering is preferred when users shouldn’t access certain documents from your index, as it’s more secure and prevents users from removing the filtering.

  • Client-side filtering is preferred when you want to filter documents for relevance purposes, but when all documents should normally be available to them.

Reference

The following articles can help you build complex and powerful queries for your search page:

Where to use it

There are two main ways where you can enter such queries: through the token or client-side.

  • Token filtering is preferred when users shouldn’t directly access certain documents from your index.

  • Client-side filtering is preferred when you want to filter documents for relevance purposes.

Server-side filtering

Server-side filtering is more secure, as your users won’t be able to remove the filter in any way.

This method works by adding a filter in the encrypted token used by your user to query the index.

To add filtering through the token, you need to create a custom Visualforce page for your component (see Create a custom Visualforce search page), and use the filter option in it (see JsSearch Visualforce component - filter).

The resulting Visualforce page would look like this:

<apex:page standardstylesheets="false" sidebar="false" docType="html-5.0">
  <CoveoV2:SearchInterface mobile="false"
                           name="<YOUR_CUSTOM_PAGE>"
                           filter="<YOUR_FILTER_EXPRESSION>"/>
</apex:page>

Where you replace:

  • <YOUR_CUSTOM_PAGE> by the name of the custom Visualforce page.

  • <YOUR_FILTER_EXPRESSION> by the filter that you want to use.

Client-side filtering

Client-side filtering is less secure than server-side filtering, but simpler to use. It’s the preferred method when your users have access to all documents, but you want to use filtering to present more relevant results.

There are many ways to add client-side filtering. You can use it as part of a hidden query for your whole component (see SearchInterface - expression), as the query for your tab (see Tab - expression), or as part of a custom component that programmatically adds a custom query using the QueryBuilder (see QueryBuilder).

Examples

The following examples can help you understand how to use the Coveo query syntax and the Query extension language.

Boosting items in a search interface

You’re building a search interface for your knowledge articles, where you have your official documentation created by your documentation team and your troubleshooting guide created by your support team.

You want to promote articles from your official documentation without hiding the articles from your troubleshooting guide.

Using the SearchInterface expression option (see SearchInterface - expression), you use a $qre to be applied to your whole search interface:

@objecttype=(Documentation,Troubleshooting) $qre(expression:'@objecttype==Documentation',modifier:'100')

This query can be explained as such:

  • @objecttype=(Documentation,Troubleshooting) means that only items belonging to Documentation or Troubleshooting, the name of your Knowledge article types, will be returned in your search interface.

  • $qre(expression:'@objecttype==Documentation',modifier:'100') means that items belonging to Documentation should be boosted by a score of 100 in your search interface. This way, articles from your official documentation are going to be favored over articles from your troubleshooting guide. The value of 100 can be adapted to fit your needs, if you find that items are boosted too much or not enough.

Filter items based on a field from another linked item

In your Search Interface, you want to add a button that users can click so that the search interface only returns accounts that are linked to at least one opportunity with an amount over $50,000. Since the opportunity amount isn’t a field of your accounts, you decide to use a nested query (see Nested queries).

For the function that your button calls, you use this code:

function showAccountsWithOpportunitiesOver50000() {
    $('.CoveoSearchInterface').on('buildingQuery', function (e, args) {
        args.queryBuilder.expression.add('@objecttype="Account" [[@syssfaccountid] @objecttype="Opportunity" @syssfamount>50000 ]');
    });
}

This code can be explained as such:

  • $('.CoveoSearchInterface').on('buildingQuery', function (e, args) {...} uses the buildingQuery event to trigger the code (see Events).

  • args.queryBuilder.expression.add(...) uses the queryBuilder class to add your nested query to the basic query (see QueryBuilder).

  • @objecttype="Account" [[@sfaccountid] @objecttype="Opportunity" @sfamount>50000 ] is the nested query itself.

    • @objecttype=opportunity @sfamount>50000 means that a query is performed to find only opportunities with amounts over $50,000.

    • @sfaccountid means that this field - which has the same value for accounts and their associated opportunities - should be used to connect the opportunities found to their associated accounts.

    • @objecttype=Account means you only want to have accounts returned in your results.

    • Together, the nested query only returns accounts that are connected, through the @sfaccountid field, to at least one opportunity with an amount over $50,000.