Using special characters in queries

This is for:

Developer System Administrator

In a query, special characters which are non-alphanumeric either perform a particular action in specific contexts or are interpreted as a blank space character and are therefore ignored.

Coveo doesn’t index special characters. Therefore, you can’t search for a special character or for a term containing a special character, such as an email address containing the @ character. You can, however, search for special characters in field values using advanced field queries.

Although these characters aren’t free-text-searchable, they’re still displayed in item Quick views, excerpts, and summaries to ensure consistency with original documents. When an item that contains special characters reaches the processing stage of the indexing pipeline, Coveo converters ignore the special characters. Even though they’re not indexed, special characters are still stored so that item Quick views, excerpts, and summaries are displayed correctly.

This information is especially important to keep in mind when working with languages that use accents, as Coveo removes all diacritics and only considers the base letter while indexing. Thus, when working with a language like French, Spanish, or Swedish, it may be helpful to search for an exact term.

Special characters

Use the following special characters in a Coveo search box to perform a special action in specific query contexts.

@ (at sign)

Indicates a field.

The term immediately following the at sign is interpreted as a field name. When the term isn’t a field name, either no results are returned or a syntax error message is displayed (see About fields).

Example

@filetype=doc finds all .doc files.

= (equal character)

Acts as an equal field operator.

When the equal character appears between a field name and its argument, the equal character acts as an equal sign.

Note

When several terms follow =, they don’t need to be contiguous or in the exact order.
Examples

  • @title=(annual roadmap review) returns items containing annual or roadmap or review in their title since they’re between parentheses.

  • @title=annual roadmap review returns items containing annual in their title or roadmap or review anywhere in the item.

== (two equal characters)

Act as an exact match field operator.

When two equal characters appear between a field name and its argument, these equal signs act as an exact, contiguous, and same order match operator for the argument terms appearing between quotation marks.

Example

@title=="annual roadmap review" returns only items with the title annual roadmap review.

<> (smaller than and greater than characters)

Act as an exclusion field operator.

When contiguous smaller than and greater than characters (<>) appear between a field name and its argument, they act as an exclusion operator for the argument term or terms appearing between quotation marks.

Example

@title<>"roadmap review" in a query returns items that don’t contain 'roadmap review' in their title. However, it only applies to items that actually have a title field. This is different from NOT @title="roadmap review", which excludes 'roadmap review' from all items, regardless of whether they have a title field.

< (smaller than character)

Acts as an inferior mathematical field operator.

When the smaller than character appears between a field name and its date or numerical argument, the character acts as an inferior operator.

Examples

  • @size<50 returns items of 49 bytes or fewer.

  • @date<today returns items created or modified before today.

<= (smaller than and equal characters)

Act as an inferior or equal mathematical field operator.

When contiguous smaller than and equal characters appear between a field name and its date or numerical argument, they act as an inferior or equal operator.

Examples

  • @size<=50 returns items of 50 bytes or fewer.

  • @date<=yesterday returns items created or modified before today.

> (greater than character)

Acts as a superior mathematical field operator.

When the greater than character appears between a field name and its date or numerical argument, it acts as a superior operator.

Examples

  • @size>50 returns items of 51 bytes or more.

  • @date>yesterday returns items created or modified today.

>= (greater than and equal characters)

Act as a superior or equal mathematical field operator.

When contiguous greater than and equal characters appear between a field name and its date or numerical argument, they act as a superior or equal operator.

Examples

  • @size>=50 returns items of 50 bytes or more.

  • @date>=yesterday returns items created or modified since the beginning of yesterday.

+ (plus sign)

  • Matches the exact term.

    Note

    You can’t use wildcard characters with an exact match prefix.

    When the plus sign immediately precedes a term, only items containing the exact term are returned. In other words, the plus character disables stemming for the term it precedes.

    Example

    +search finds items containing search and not those containing terms of the same family, such as searched, searches, or searching.

  • Acts as the plus mathematical operator.

    In a @date field argument, when the plus sign appears between a date operator and a duration value, the duration value is added to the date operator.

    Example

    @date<yesterday+1d finds items created or modified yesterday or today, since 1 day is added to the date operator and also because the date operator follows the smaller than character.

# (number sign)

Matches an exact term.

Note

While the # sign still works, it’s deprecated and has been replaced with the plus sign.

Like the plus sign, when the number sign[1] immediately precedes a term, only items containing the exact term are returned (the term isn’t expanded by the stemming algorithm).

1. Also called hash or pound sign.

- (minus sign)

  • Excludes a term.

    Note

    Using the minus sign is equivalent to using the NOT operator before a term.

    When the minus sign[1] is preceded with a space and immediately precedes a term, items containing the term (and same-root terms) are excluded from the search results.

    Example

    roadmap -2010 finds items containing roadmap but not containing 2010.

  • Acts as the minus mathematical operator.

    In a @date field argument, when the minus sign appears between a date operator and a duration value, the duration value is subtracted from the date operator.

    Example

    @date=now-1mo finds items that were created or modified within the day exactly a month prior, since 1 month is deducted from the date operator and also because the date operator follows an equal character.

  • Acts as a contiguity character.

    When the minus sign appears between terms, the returned items contain the term sequence in the specified order.

    Example

    annual-roadmap-review returns items that contain the term sequence and is equivalent to "annual roadmap review".

1. Also called hyphen or dash.

Contiguity characters

When the underscore (_), slash (/), backslash (\), dash (-), dot (.), or single quotation mark (') character appears between terms, the returned items contain the term sequence in the order specified.[1].

Notes

  • Coveo removes non-alphanumeric characters and replaces them with white spaces in the index. When you use a special character (for example, a dash) between terms in your queries, you may therefore have unexpected results if the indexed content contains other special characters (for example, a slash) between the same queried terms.

  • Using the contiguity characters is equivalent to using quotation mark delimited term sequences. For example, annual_roadmap_review or a mix of contiguity characters (for example, annual/roadmap\review) returns items that contain the term sequence ("annual roadmap review").

1. A dot may also be called point or period.

: (colon character)

  • Acts as a contiguity character.

    When the colon character appears between terms, the returned items contain the exact term sequence.

    Example

    annual:roadmap:review returns items containing the exact term sequence.

  • Acts as an equal field operator.

    When the colon character appears between a field name and its argument, the colon is equivalent to an equal sign. With the colon character, you don’t need to enter the at sign (@) before the field name.

    Example

    filetype:doc returns all .doc items.

.. (two dots)

Act as an inclusive value range.

When two dots[1] separate two field values, the dots act as an inclusive range operator.

Example

@size=1024..2048 finds items of which the size is greater or equal to 1024 bytes and smaller or equal to 2048 bytes.

1. Also called two points or periods.

Straight or curly quotation marks

Match term sequence or phrases.

When straight quotation marks (" ") or curly quotation marks (“ ” or « ») enclose terms, they act as a contiguous term sequence or phrase match.

Example

"annual roadmap review" returns items containing the exact term sequence.

Notes

  • On a search page, you can use either straight or curly quotation marks, as they will both be interpreted as a phrase match. However, as an administrator, we recommend using straight quotation marks in the Coveo Administration Console, since curly quotation marks may yield individual terms instead of a phrase match.

  • You can use wildcard characters in a phrase enclosed in quotation marks.

* (asterisk character)

Acts as a wildcard operator.

Important

By default, your query must include at least two characters before the * (see Using wildcards in queries).

When the asterisk character appears at the end of a term or in a term, it acts as a wildcard operator to specify a term completed by any number of any characters at the place of the asterisk character.

Example

micro* returns items containing terms starting with micro such as Microsoft, microphone, or microprocessor.

? (question mark character)

Can optionally act as a wildcard operator.

Note

Your Coveo administrator can enable the question mark wildcard behavior (see Coveo Querybox Component).

The question mark character wildcard behavior is disabled by default, therefore it’s ignored when included in queries. When enabled, the question mark character appearing at the end of a term or within a term acts as a wildcard operator to specify a term completed by any character at the place of the question mark.

Example

When the wildcard behavior is enabled, gr?y returns items containing terms such as grey or gray.

() (parentheses)

Group enclosed terms for Boolean operators.

When parentheses group terms with adjacent and included Boolean operators, they create a filter.

Example

Liz OR (project AND presentation) returns items that contain either Liz or both project and presentation.

(,) (comma between parentheses)

Act as a OR field operator.

When parentheses group space or comma-separated terms in the argument of a field, using the whole expression becomes the equivalent of using the OR operator between terms.

Example

@language=(english, french, spanish) is the same as @language=english OR @language=french OR @language=spanish.

[] (square brackets)

  • Act as nested query delimiters.

    Square brackets are used as delimiters in a nested query. The nested query is a powerful yet complex Coveo query language feature that’s typically used by developers. In a search box, usage of brackets must respect the nested query syntax, with at least one level.[1] A single pair of brackets will return an Invalid syntax error.

    Examples

    • With filetype:artist [[@artistid] [[@albumid] songtitle:love] genre:rock], the last nested query returns a list of artist from @artistid whose rock albums @albumid have at least one song with love in its title.

    • "[query]" returns items that contain the term query despite a single pair of brackets because of the quotation marks encompassing [query].

    • [query] returns an Invalid syntax error.

  • Act as delimiters in regular expressions.

    These brackets can be used in regular expressions when performing advanced field queries.

    Example

    @username /= "@[A-Z0-9.-]\.[A-Z]{2,4}" matches username field values that are in an email form.

1. Two pairs of brackets.

$ (dollar sign)

  • Invokes a query extension.

    The term immediately following the dollar sign character is interpreted as a query extension name. The invoked query extension is applied to the search results.

    Example

    $sort(criteria: 'datedescending') returns the input result set reordered following the specified criterion delineated with the colon character.

  • Indicates a Query pipeline language (QPL) object.

    The term immediately following the dollar sign character is interpreted as a QPL object. For some QPL objects, the search API replaces the $ expression with the corresponding query parameter value, and then sends it to the index. This returns results that contain the query parameter value.

    However, QPL objects such as device, os, and browser don’t have a matching query parameter and may be associated to many user-agent values for a single Coveo user. Using a $joinValues expression makes one string out of the many values returned by such QPL objects.

    Examples

    • $language returns results for en when language query parameter value is en.

    • $joinValues(values: $device) returns results for desktop, pc, and windows to a Windows user.

Notes

  • Query extensions and QPL objects are typically used by advanced administrators and developers.

  • If the character string following the dollar sign isn’t a valid query extension name or a valid QPL object name, the query returns the following error message: "Something went wrong. If the problem persists, contact the administrator."

TM (trademark symbol)

Represents the trademark symbol.

Note

The ™ symbol is a ligature that’s expanded to tm in the index.

When the two letters (TM) appear at the end of a product name, they can represent the expanded form of the trademark symbol (™).

Example

productnametm returns documents that contain either productnametm or productname™.

Ignored characters

All other special characters or previously specified characters appearing in other contexts in a query are treated as a blank space and ignored, or trigger an error message.

Examples of ignored special characters are: percent (%), question mark (?), exclamation point (!), semi-colon (;), ampersand (&), copyright (©), registered trademark (®), euro (€), pound (£), yen (¥), circumflex (^), left and right braces ({}), and tilde (~).

Example

annual&roadmap!review is equivalent to annual roadmap review.