About the Query Expression

Build a Search UI Coveo Relevance Cloud Developer System Administrator Product Documentation

Every time a query is sent to a Coveo organization index, the various parts of the query expression are merged into a single combined query expression which can be read as follows:

((q AND lq AND aq) OR dq) AND cq

In other words, in order for an item to be returned as a query result, that item must satisfy the constant query expression (cq), along with either of:

This article explains the typical purpose of each part of the query expression.

Basic Query Expression (q)

The basic query expression (q) typically comes directly from end-user input, such as when an end user is typing keywords in a search box. As such, this part of the query expression can be altered by query pipeline Stop words and Thesaurus rules, and also serves as the main input for several index features such as:

Examples

  • A customer triggers a query from a customer service search interface. The query consists of the keywords speedbit tracking heart rate. Therefore, the q part of the combined query expression has the value speedbit tracking heart rate.

  • A customer browsing products on the Books4Fun commerce site triggers a query from a search box. The query consists of the keywords mark twain. Therefore, the q part of the combined query expression has the value mark twain.

Note

In a Coveo JavaScript Search Framework interface, the Searchbox component disables query syntax on the basic query expression by default.

Advanced Query Expression (aq)

The advanced query expression (aq) is typically created by client-side logic, such as when the end user interacts with facet values or similar search interface elements intended to be used as query result filters. This part of the query expression is assumed to be code-generated, and can take full advantage of the Coveo query syntax.

Examples

  • A support agent selects the Documentation and KB Article values on the File Type facet and the Accessory value on the Product Type facet on a customer service search interface, which triggers a new query. The aq value changes to @filetype==("Documentation", "KB Article") @producttype=="Accessory".

  • A customer selects the Audio Books value from the Exclude File Type facet on the Books4Fun commerce search page, which triggers a new query. As the selected facet was a Exclude File Type facet value, the aq value is NOT @filetype==AudioBooks.

Disjunction Query Expression (dq)

The disjunction query expression (dq) is typically generated by an Automatic Relevance Tuning (ART) Coveo Machine Learning (Coveo ML) model to ensure relevant items are included in the query results, regardless of matching keywords.

Examples

  • A customer triggers a query from a customer service search interface. The ART model on the assigned query pipeline has learned a pattern based on the current context that agents often found the solution to their problem on the result item with a permanentid value of aadd742687c62910d6dc8347304ec2cedfd0b06d5b4d2794a925ce5688bd. Therefore, the dq is assigned the value @permanentid=aadd742687c62910d6dc8347304ec2cedfd0b06d5b4d2794a925ce5688bd.

  • A customer triggers a query from the Books4Fun commerce search page. The ART model on the assigned query pipeline has learned a pattern based on the current context that customers often were interested in purchasing a book (e.g., result item) with a permanentid value of h0f0rcprlia27wg8ov6q4347304ec55nzu6nl8rnzn1p5ncou65fvhrg446c. Therefore, the dq is assigned the value @permanentid=h0f0rcprlia27wg8ov6q4347304ec55nzu6nl8rnzn1p5ncou65fvhrg446c.

Note

An ART model won’t attempt to populate the dq at all if both Match the query and Match the advanced query options are enabled.
Important

The constant and disjunction query expressions should never be used for any query pipeline feature that affects the ranking of results. Instead, you should use either the basic or advanced query expressions.

Constant Query Expression (cq)

The constant query expression (cq) is very similar to the advanced query expression but must hold expressions that are constant for all users of a specific search interface or search tab (e.g., search scope). The results of evaluating these expressions are kept in a special index cache to avoid re-evaluating them on each query.

Examples

  • A support agent authenticates on a customer service search interface. Their generated search token enforces the filter NOT @source=="Marketing" to ensure that marketing items don’t appear in their query results, so the cq value is NOT (@source=="Marketing").

  • A customer selects the Shop tab on the Books4Fun commerce search interface. The selected tab has the value @source==("Products"), so the cq value is @source=="Products" until a different tab is selected.

Important

  • The constant query expression should never be used in conjunction with the $context QPL object variables.

  • Nested queries should never be in the constant query expression, as they prevent caching and will slow down all queries.

  • The constant and disjunction query expressions should never be used for any query pipeline feature that affects the ranking of results. Instead, you should use either the basic or advanced query expressions.

Large Query Expression (lq)

The large query expression (lq) is typically leveraged by case deflection and insight panel search interfaces to send lengthy textual data (e.g., a case description) along with a query. A Coveo ML ART model with Intelligent Term Detection (ITD) enabled can extract contextually relevant keywords from the large query expression and use those keywords to refine the basic query expression (q).

Example

A support agent triggers a query from an insight panel search interface. The lq contains the case description of a customer requesting help. The ART model on the assigned query pipeline uses Intelligent Term Detection (ITD) to extract relevant terms from the case description, based on the current context (see How Does Intelligent Term Detection (ITD) Work?).

Combined Query Expression Examples

  • A customer is on the Pro-Sports Athletics commerce search page. The customer interacts with the search page as follows:

    • The customer triggers a query containing the keywords Blorton snowboard.

      The assigned query pipeline applies a Thesaurus rule that replaces snowboard with snowboard OR board (see Thesaurus - Query Pipeline Feature).

    • The customer interacts with the Price Range Facet value, changing the advanced query expression to @price<=300.

    • The ART model on the assigned query pipeline has learned a pattern based on the current context that customers often were interested in purchasing a snowboard (e.g., result item) with a permanentid value of z0f0rcprlia27wg8ov6q4347f4hjnc55nzu6nl8rnzn1p56ugf1235fvhrg8. Therefore, the dq is assigned the value @permanentid=z0f0rcprlia27wg8ov6q4347f4hjnc55nzu6nl8rnzn1p56ugf1235fvhrg8

      This results in the following combined query expression:

    ((Blorton (snowboard OR board)) AND @price<=300) OR @permanentid=z0f0rcprlia27wg8ov6q4347f4hjnc55nzu6nl8rnzn1p56ugf1235fvhrg8)

  • A support agent is interacting with a customer service search interface to assist a customer with their Orange Technologies product. The support agent interacts with the search interface as follows:

    • The support agent triggers a query containing the keywords piPhone crashing.

    • The support agent selects the V6 value from the piPhone Version facet, changing the advanced query expression to @piphoneversion="V6".

    • The support agent is authenticated on the customer service search interface, so their generated search token enforces the filter @source=="Help" to ensure that only support items appear in the query results, so the cq value is @source=="Help".

    • The ART model on the assigned query pipeline uses intelligent term detection to extract the terms battery and settings from the case description.

      This results in the following combined query expression:

    ((%~ Or([Required:60%],"piPhone crashing settings battery") ~%) AND @piphoneversion="V6")) AND @source=="Help")