Coveo Query Syntax Examples in Coveo for Salesforce

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

With the Coveo for Salesforce Free edition, both the Coveo Query Syntax and the Query Extension Language are translated by the Coveo Search API (see Understanding the Coveo for Salesforce Free Edition Architecture).

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 should not access certain documents from your index, as it is 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:

For the Coveo for Salesforce Free edition, some Query Extensions might not be available (see Standard Query Extension Usage Comparison (Coveo for Salesforce)).

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 should not 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 will not 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 Creating 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, where Your Filter Expression is replaced with the filter that you want to use.

<apex:page standardstylesheets="false" sidebar="false" docType="html-5.0">
  <CoveoV2:SearchInterface mobile="false"
                           name="Your Custom Page"
                           filter="Your Filter Expression"/>
</apex:page>

Client-Side Filtering

Client-side filtering is less secure than server-side filtering, but simpler to use. It is 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 are 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.

    Free edition only

    With the Coveo for Salesforce Free edition, the query should instead read:

      @sfarticletype=(Documentation__kav,Troubleshooting__kav) $qre(expression:'@sfartciletype==Documentation__kav',modifier:'100')
    

    This is simply because the Salesforce index uses a different field name than the Coveo index for its article types.

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 is not 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.

      Free edition only

      For the Coveo for Salesforce Free edition, the nested query should instead be @objecttype="Account" @sfname=[[@sfaccountname] @objecttype="Opportunity" @sfamount>50000 ]

      This is because there is no available id to use in the Salesforce index, and because the field in which the account name is stored is different for accounts and for opportunities.

      Thus, the field @sfname is the Account name for the Account object, while @sfaccountname is the Account name for the Opportunity object.