Understanding The Coveo Cloud Query Syntax

Configuring The Coveo Cloud Query Syntax

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.

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:

Operator	Example
AND	fish AND tank - returns results with both "fish" and "tank"
OR	fish OR tank - returns results with "fish" OR "tank"
NOT	fish NOT tank - returns results with "fish" but not "tank"

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

Operator	Example
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?

Operator	Example
"	"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.

Syntax	Example
@[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:

Syntax	Example
@[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:

Operator	Example
*= 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.