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.

querying the index steps

  1. The end user types some text in the search box and submits a new query.

  2. The search interface, typically relying on the JavaScript Search Framework, builds the query by combining the search keywords submitted by the end user with other generated filter expressions and parameters (see Building the Query).

  3. The search interface sends the query to the Search API.

  4. The Search API parses the query and determines the appropriate query pipeline (see About the Query Pipeline Routing Algorithm).

  5. The Search API routes the query to the appropriate query pipeline.

  6. The query pipeline applies various rules to modify the query depending on its context (see Order of Execution of Query Pipeline Features).

  7. The query pipeline forwards the modified query to the index.

  8. The index executes the query.

  9. The index returns the ranked query response to the Search API.

  10. The Search API builds the JSON query response (e.g., populates the results array, evaluates the query duration, etc.).

  11. The Search API sends the query response to the search interface.

  12. The search interface processes the query response and notifies its components (e.g., result list, facet, etc.) that the query was successful.

  13. Affected components update themselves (e.g., the result list renders the query results, facets adjust their values and numbers, etc.).

See Order of Execution of Query Pipeline Features.

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;

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 q and aq, or just dq. Additionally, lq is processed by the Intelligent Term Detection (ITD) feature to inject relevant keywords in q.

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 fridge.

  • The Coveo JavaScript Search Framework builds the basic expression entered in the Coveo Search Box component. It also builds expressions of other types based on components such as facets, sorting, ranking, filtering panels, and others. Hence, in a standard Coveo scenario, a developer could complete a full project without ever having to build an expression.

  • 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 Articles and 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 @objecttype field.

If you’re using the Coveo JavaScript Search Framework to implement your search interface, and more specifically the tab component to implement your tabs, the constant query expression is entirely handled by the framework. If you’re using the Coveo Cloud APIs directly, see Implement Tabs.

  • 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.

What’s Next?

The next article in this section explains how you can use the Coveo JavaScript Search Framework to implement your search interfaces (see Leveraging the Coveo JavaScript Search Framework).

Recommended Articles