Understanding The Coveo Cloud Query Syntax

October 12, 2021

By David Austin

If you've played around in a Google search field you'll know that there are a lot of options available that aren't immediately obvious. Well, the same goes for Coveo and if you have certain additional functionality enabled, those options are even more extensive.

In Coveo many of these features are disabled by default and need to be enabled or order to be used.

Enabling Query Syntax

If you're using Coveo JavaScript this is disabled by default, however it's enabled by default when using the Search API.

Simply setting the enableQuerySyntax in the QueryBox component will allow these features to be used. There are a lot of other options that can be enabled or disabled independently in the QueryBox so if you want to read up on those, I refer you to the official documentation.

You can also enable query syntax and query debug to take advantage through the debug option.

Understanding the Debug mode in Coveo Cloud Query Syntax

Get to that menu by pressing and holding the Alt key (Option for Mac) and then double-click the component or result.

Simple Queries

What's a simple query? Well it's one that doesn't access any debug capabilities. It's also one you're probably most familiar with if you've been usinga search engine.

In a simple query you're able to take advantage of certain syntax. Majority of people will simply enter in a term into a search box, e.g. fish and get results containing that word. Maybe they enter in fish tank and get results containing both of those terms. But is that what they're really after? The most common operators being:

OperatorExample
ANDfish AND tank - returns results with both "fish" and "tank"
ORfish OR tank - returns results with "fish" OR "tank"
NOTfish NOT tank - returns results with "fish" but not "tank"

There are others though that you might not be aware of. These include:

OperatorExample
NEAR:#NEAR:3 where 3 is limiter of number of terms apart.
++fish will return all items containing the exact phrase.
*fish* returns any result that contains "fish" or any phrase starting with it, e.g. "fishing". The use of a wildcard "*" must be enabled using the enableWildcards option.

Did you know there are two different kinds of quotes in Coveo? i.e. " and ' and they do very different things?

OperatorExample
""fish tank" will return all the results containg the exact phrase, "fish tank".
''fish tank' will return all items "fish" and "tank".

Field Queries

So while using operators like those found above are what typical users might use, those found below are often queries that content authors, developers and administrators typiacally would use if they're looking to debug a query.

As you'll see below, utilizng field based queries, you're searching against fields within Coveo directly.

SyntaxExample
@[field]@title will return any results that have a value in the field specified
@[field]=[value]@title=fishtank will return any result that have the term "fishtank" in it's @title field
Using , >, < />,>=For fields that are integer based, you can use comparative operators to evaluate the values within the field to return you results that match that result. e.g. @year< />

Those are the typical field queries, but there are certainly more complex options available, such as evaluating dates, comparing fields based upon an enumerated set of terms, Regex, or advanced operators. Have a look below:

SyntaxExample
@[field]=[yyyy/mm/dd]@date=2021/10/31 will return all results that have the same date found in the @date field.
@[field]=[yyyy/mm/dd]...[yyyy/mm/dd]@date=2021/10/01...2021/10/31 will return all results with value in the @date field that is between the date range specified.
@[field]==([value 1],[value 2],[value 3])@tags==(fish, tank, water) will return all results where the @tags field has any of those values.

You can also format it with quotations, e.g.
@tags==("red fish", "blue fish", "yellow fish")
@[field]/="^(?:[0-9]{1,3}\.){3}[0-9]{1,3}$"@location="^(?:[0-9]{1,3}\.){3}[0-9]{1,3}$" will return all results that contain an IPV4 address somewhere in the field.

As I mentioned, there are a few advanced operators you can use when doing field queries. I've listed them here:

OperatorExample
*= in combination with ?@body*="fishtank te?m" will return results with both "fishtank term" and "fishtank team".
< />@author< />"David Austin" would return all blogs that don't have me listed as the author
%=@author%="Dan Cruickshank" would return results that match the result phonetically.
~=@author~="David Austin" will fuzzy match based on the value

At this point you're realizing there is a TON of options that one can do when either searching using the search box itself or programmatically building search queries. Most people will never take advantage of these capabilities, to be honest. Largely because they themselves do know the options exist, or they're not enabled.

Most importantly, know your audience. If you think this capability would be useful, be sure to provide them with a legend or toolbox for how to build queries.

Image of Fishtank employee David Austin

David Austin

Development Team Lead | Sitecore Technology MVP x 3

David is a decorated Development Team Lead with Sitecore Technology MVP and Coveo MVP awards, as well as Sitecore CDP & Personalize Certified. He's worked in IT for 25 years; everything ranging from Developer to Business Analyst to Group Lead helping manage everything from Intranet and Internet sites to facility management and application support. David is a dedicated family man who loves to spend time with his girls. He's also an avid photographer and loves to explore new places.