Query syntax

This is for:

In this article

Basic queries
Field queries
Advanced field queries
General query extensions

The Coveo query syntax is a set of semantic rules that can be used to compose advanced queries. In other words, it allows you to refine your queries using purpose-built operators.

Although the Coveo query syntax is disabled by default in the atomic-searchbox component, it can be enabled by setting the enable-query-syntax attribute to true.

When performing Search API calls directly, the query syntax is enabled by default.

The following tables list examples of different Coveo query syntax features that can help build more relevant queries. These features often leverage special characters, so be sure to also read on using special characters in queries.

Basic queries

The following table lists examples of basic query syntax:

query syntax example Search results

query syntax example	Search results
`term`	Returns all items containing `term`.
`term1 term2`	Returns all items containing both `term1` and `term2`.
`"term1 term2 term3"`	Returns all items containing the exact phrase between double quotes (see Searching for a phrase).
`'term1 term2 term3'`	Returns all items containing `term1`, `term2`, and `term3`.^[1]
`+term`	Returns all items containing exactly `term`, not other words sharing the same root (see Searching for an exact term).
`term1 AND term2`	Returns all items containing both `term1` and `term2` (see the `AND` operator).
`term1 OR term2`	Returns all items containing either `term1` or `term2` (see the `OR` operator).
`term1 NOT term2` `term1 -term2`	Returns all items containing `term1` but not `term2` (see the `NOT` operator).
`term1 NEAR:5 term2`	Returns all items in which `term1` and `term2` are no more than five terms apart (see the `NEAR` operator).

term

Returns all items containing term.

term1 term2

Returns all items containing both term1 and term2.

"term1 term2 term3"

Returns all items containing the exact phrase between double quotes (see Searching for a phrase).

'term1 term2 term3'

Returns all items containing term1, term2, and term3.^[1]

+term

Returns all items containing exactly term, not other words sharing the same root (see Searching for an exact term).

term1 AND term2

Returns all items containing both term1 and term2 (see the AND operator).

term1 OR term2

Returns all items containing either term1 or term2 (see the OR operator).

term1 NOT term2
term1 -term2

Returns all items containing term1 but not term2 (see the NOT operator).

term1 NEAR:5 term2

Returns all items in which term1 and term2 are no more than five terms apart (see the NEAR operator).

1. Single quotes aren’t handled the same as double quotes. Single quotes are interpreted as any other alphanumeric character except in general query extensions, while double quotes isolate phrases.

Field queries

The following table lists examples of field query syntax:

query syntax example Search results

query syntax example	Search results
`@[fieldname]`	Returns all items with any value in the specified field.
`from:name` `to:"firstname lastname"`	Returns all items with `from` or `to` fields containing the specified name (see Email operators).
`@title=term`	Returns all items whose `title` field value contains `term`.
`@date=yesterday`	Returns all items whose `date` field value is yesterday’s date.
`@date=2015/01/01..2015/03/31`	Returns all items with the `date` field for a range of dates.
`@size<=128`	Returns all items whose file `size` field value is less than 128 bytes (see Value range).
`@author==(bob,robert,rob)` `@author==("bob jones","robert smith","rob johnson")`	Returns all items whose `author` field value is either of the numbered values (see Parentheses and comma with field queries).^[2]

@[fieldname]

Returns all items with any value in the specified field.

from:name
to:"firstname lastname"

Returns all items with from or to fields containing the specified name (see Email operators).

@title=term

Returns all items whose title field value contains term.

@date=yesterday

Returns all items whose date field value is yesterday’s date.

@date=2015/01/01..2015/03/31

Returns all items with the date field for a range of dates.

@size<=128

Returns all items whose file size field value is less than 128 bytes (see Value range).

@author==(bob,robert,rob)
@author==("bob jones","robert smith","rob johnson")

Returns all items whose author field value is either of the numbered values (see Parentheses and comma with field queries).^[2]

2. When a numbered value contains more than one term, you must place the value between double quotes.

Advanced field queries

The Coveo query syntax includes special field operators to perform advanced matches. The following table lists examples of advanced field query syntax:

Note

Advanced field queries work only with facet fields.

query syntax example Search results

query syntax example	Search results
`@title='term1 term2 term3'`	Returns all items whose `title` field contains `'term1`, `term2`, or `term3'`.^[3]
`@author ~= "name"`	Returns all items whose `author` field contains a value with a fuzzy match for `name`.
`@author %= "name"`	Returns all items whose `author` field value phonetically matches `name`.
`@syssite /= "^(?:[0-9]{1,3}\.){3}[0-9]{1,3}$"`	Returns all items whose `syssite` field contains a string matching an IP address regular expression (regex).
`filetype:artist [[@artistid] [[@albumid] songtitle:love ] genre:rock ]`	Returns all items corresponding to an `artist` whose rock albums have at least one song with the word love in its title.
`@title <> "Enterprise Search"`	Returns all items whose `title` field defines, but doesn’t contain, `"Enterprise Search"` (see Excludes).

@title='term1 term2 term3'

Returns all items whose title field contains 'term1, term2, or term3'.^[3]

@author ~= "name"

Returns all items whose author field contains a value with a fuzzy match for name.

@author %= "name"

Returns all items whose author field value phonetically matches name.

@syssite /= "^(?:[0-9]{1,3}\.){3}[0-9]{1,3}$"

Returns all items whose syssite field contains a string matching an IP address regular expression (regex).

filetype:artist [[@artistid] [[@albumid] songtitle:love ] genre:rock ]

Returns all items corresponding to an artist whose rock albums have at least one song with the word love in its title.

@title <> "Enterprise Search"

Returns all items whose title field defines, but doesn’t contain, "Enterprise Search" (see Excludes).

3. Single quotes aren’t handled the same as double quotes. Single quotes are interpreted as any other alphanumeric character except in general query extensions, while double quotes isolate phrases.

General query extensions

The Coveo query syntax uses query extensions, which are built-in elements of the query extension language.

Note

There are some query extensions that return values instead of results. These must be used in conjunction with other queries to return results.

`$q`

When using the following syntax:

term1 $q() term2

All items containing term1, term2, and the basic query expression (q) are returned.

Note

This syntax is almost never used in the q.

For more information, see $q.

`$qf`

When using the following syntax:

$qf(function:'dist(@latitude, @longitude, 46.8167, -71.2167)', fieldName: 'distance')

The query returns all items and the query extension adds a dynamic field called distance that calculates the distance between each item and the entered coordinates (in meters).

For more information, see $qf.

`$qre`

When using the following syntax:

$qre(expression:@sfaccountname=='MyCompany', modifier:'100')

The query returns all items and the query extension boosts items with the sfaccountname field with the MyCompany value by a value of 100.

For more information, see $qre.

`$qrf`

When using the following syntax:

$qrf(expression:'sqrt(@sfarticleviewcount)', normalizeWeight: true)

The query returns all items and the query extension boosts items by the square root of the value of their sfarticleviewcount field. This boost is normalized to avoid completely overriding the index ranking.

For more information, see $qrf.

`$weight`

When using the following syntax:

$weight(name:'Adjacency', value:'7')

The query returns all items and the query extension changes the ranking so that term proximity (adjacency) is more important when ordering results.

For more information, see $weight.

`$sort`

When using the following syntax:

$sort(criteria: 'datedescending')

The query returns all items and the query extension sorts the results by date, in descending order.

For more information, see $sort.

`$fold`

When using the following syntax:

$fold(field:'@sysconversationsubjectid', range:'5')

The query returns all items and the query extension additionally loads up to 5 child items that share the same value as other results for the sysconversationsubjectid field.

For more information, see $fold.

`$loadParent`

When using the following syntax:

$loadParent(parent:'@permanentid', child:'@parentid')

The query returns all items and the query extension additionally loads the item parents. An item is considered to be the parent of another item when its permanentid field value is the same as the other item's parentid field value.

For more information, see $loadParent.

`$quoteVar`

When using the following syntax:

$quoteVar(value: myValue)

The query returns myValue between double quotes.

For more information, see $quoteVar.