Common pitfalls

Working on a search solution based on the Coveo Platform requires you to make many decisions. As such, there are many occasions to make small (and big) mistakes which can negatively affect the search experience for your end users.

This article outlines some of the most common pitfalls to avoid so you can implement a successful and long-lasting search solution.

Indexing pitfalls

Using the wrong connector

You should always take time to select the most appropriate connector when creating a source to index content from a given repository. You should only use a generic connector (such as Sitemap or Web) if no specific connector is available for a system from which you want to index content.


Rather than using a Web source to index content from a Confluence site, you should configure a Confluence source, which offers better indexing performance and flexibility for this type of content.

Indexing web content improperly

Web sources offer no incremental refresh mechanism, and are limited to crawling up to one page per second by default. If you must use a generic source type to index web-accessible content, consider using a Sitemap source instead, as it offers better indexing and updating performance for this type of content.

In any case, you should typically leverage the web scraping feature of your Sitemap and Web sources to avoid indexing irrelevant item content, such as page headers and footers.

Making many small Push API calls

When using the Push API, it’s possible to push one item at a time. This is inefficient, as individual Push API calls require more processing time and resources than batch calls. Moreover, each Push API call you make counts against the monthly quota allowed for your license. Unless you merely want to update a single item or security identity, use batch calls (see Manage batches of items in a Push source and Manage batches of security identities).

Search experience design pitfalls

Developing directly against Coveo APIs

The Search API and usage analytics Write API are both publicly available and documented, but we don’t recommend that you implement your own search interface on top of these services. In most cases, you should use the Coveo Headless library instead of developing directly against the APIs. If you don’t need the full complexity of Headless, you should use the Atomic library instead.

You should only consider developing directly against the APIs if you can’t use the Headless library for some legitimate reason, such as when you want to integrate Coveo-powered search features into a non-web-based application.

Exposing API keys in client-side code

Exposing an API key which can only be used to log UA events and execute queries anonymously is acceptable under specific circumstances. However, you must never expose an API key with the impersonate privilege in client-side code; otherwise, anyone could use that key to generate search tokens impersonating other users, therefore gaining illegitimate access to all content from sources that index permissions across your index.

Using many search boxes

A search interface may allow end users to query various types of content originating from many sources. One common design mistake is to render many search boxes (for example, one for each type of content). More often than not, this results in an extremely confusing end-user experience. Therefore, a search interface should only have a single search box from which end users can input all of their queries.

Pre-selecting filters

You may be tempted to automatically enforce a specific filter expression (for example, by pre-selecting a certain tab, or certain facet values) whenever an end user navigates to your search interface. However, doing so is typically ill-advised. You should regularly inspect usage analytics reports to monitor how end users are interacting with your search experience. Many end users all using the same filters might indicate a relevance issue in your index. In this case, you may want to consider demoting or removing irrelevant items.

Using category facets unnecessarily

A category facet is an Atomic component that lets you display a set of hierarchically organized filter values. While category facets can fulfill specific use-cases, they can also reduce information visibility and make the search experience confusing for end users when used inadequately. Similar results can often be achieved at lower risks by using an AND operation on a standard facet instead.

Requesting search-driven lists inadequately

You may want a search-driven list in your search interface that displays, for example, relevant or popular items in your index. While this could be done using a query that’s triggered every time the page is loaded, doing so is a bad practice as your queries per month (QPM) would suffer.

Using wildcards improperly

Using wildcards inside of keywords to expand the basic query expression (q) will often yield a larger result count. However, these results will likely be out of context. In a search interface which provides query suggestions, users are guided towards relevant queries which will return appropriate results. Furthermore, in a search interface that uses the Atomic library, you should use the atomic-did-you-mean component to get query suggestions when a query returns no results.

Relevance tuning pitfalls

Defining and applying arbitrary relevance tuning rules

Using manual relevance tuning rules carelessly can have disastrous effects on the overall relevance of your search solution. Manual relevance tuning rules are intended to help you address specific issues identified by inspecting and interpreting usage analytics reports.

A well-designed relevance tuning rule applied in the proper context can eventually help Coveo ML models yield increasingly relevant output. Furthermore, when you create a new manual relevance tuning rule, you should use A/B testing to ensure that this rule actually improves the relevance of your search solution as expected.