About the Search Process
Each time an end user triggers a query in a search interface, that query must go through a whole process before the results can be displayed back to the end user. Having a high-level understanding of the search process will help you design your search experience.
Search Process Overview
The following diagram and accompanying explanations provide a fairly high-level overview of a typical search scenario.
The end user types some text in the search box and submits a new query.
The search interface sends the query to the Search API.
The Search API routes the query to the appropriate query pipeline.
The query pipeline applies various rules to modify the query depending on its context (see Order of Execution of Query Pipeline Features).
The query pipeline forwards the modified query to the index.
The index executes the query.
The index returns the ranked query response to the Search API.
The Search API builds the JSON query response (e.g., populates the results array, evaluates the query duration, etc.).
The Search API sends the query response to the search interface.
The search interface processes the query response and notifies its components (e.g., result list, facet, etc.) that the query was successful.
Affected components update themselves (e.g., the result list renders the query results, facets adjust their values and numbers, etc.).
Building the Query
As you may have inferred from the second step of the above diagram/explanations (see Search Process Overview), a query typically contains far more than the keywords entered by the end-user (i.e, the basic query expression (
q)). This means you can build queries differently depending on the context, to yield more personalized and relevant results to different end users, even when they enter the same basic query expression.
About Query Expressions
Administrators sometimes think of a query merely as a basic query expression, i.e., what the end user types. However, there often are other expressions that are as important as user input, namely;
advanced query expression (
aq): essentially generated when toggling facet values
Nested queries should never be in the constant query expression, as they prevent caching and will slow down all queries.
large query expression (
lq): typically added when using a case deflection-like search interface
The end query that’s evaluated against the index is essentially
((q && aq) || dq) && cq). In plain words, the index returns results which match
cq, and either both of
aq, or just
lq is processed by the Intelligent Term Detection (ITD) feature to inject relevant keywords in
A commerce solution has two tabs in its search interface. One tab is only for products, and the other is only for support (e.g., product manuals, support cases, etc.).
An end user visiting the
Products tab selects the
Appliance value in the
Product Type facet, and uses the search box to search for a
fridge. The constant query expression is
@contentType==products, the advanced expression is
@productType=='appliance', and the basic query expression is
All query expressions rely on the Coveo Cloud Query Syntax. It’s highly recommended you understand this syntax before building your set of expressions.
If you require more customization, there are also several non-expression parameters that can be applied when creating a query:
Using Query Expressions to Filter at Query Time
A common use of expressions is filtering a query time. This is a recommended strategy to reduce the scope of certain search pages, search driven listing pages, or search tabs.
In a search interface with
Cases tabs, the constant query expression is
@objecttype=='article' when the
Articles tab is selected, and
@objecttype=='article' when the
Cases tabs is selected. This filters the query so the Search API only returns results which have the right
- The index must be clean of unwanted items before filtering at query time. See the Locating and Indexing Content section of this guide for more information about filtering at indexing time.
- While you can define filter expressions directly in the code of your search interface, a more flexible approach is to create query pipeline filter rules (see Manage Filter Rules). You will learn more about query pipelines in the Tuning Relevance section of this guide (see Setting up Your Query Pipeline).
An index can contain publicly accessible items as well as items that only specific users can see, in accordance with the original repository permission system. When querying the index, the Search API only returns the result items the end user is allowed to access. It’s therefore important that you generate the proper access token for your end users (see Basic Secured Search).
In a search interface displaying public content only, the access token can simply consist of a public API key. On the other hand, in a search interface that displays items according to a permission model, a search token must be generated server-side. This is done using an API key with the privilege to impersonate users (i.e., the Allowed access level on the Impersonate domain), which should never be exposed publicly (see Manage Privileges). Use the appropriate method to add authentication to your search page (see Choosing and Implementing a Search Authentication Method).
Even in a non-secured search page, you may want to consider using the search token authentication, as search tokens can enforce a filter expression, search hub, and query pipeline.