Common Pitfalls

Working on a search solution based on Coveo 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 in order to 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 use a generic connector (such as Sitemap or Web) only if no specific connector is available for a system from which you want to index content (see Select Appropriate Connectors).


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 (see Add or Edit a Web Source). 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 (see Add or Edit a Sitemap Source).

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 (see Web Scraping Configuration).

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

While the Search API and Usage Analytics Write API are both publicly available and documented, implementing your own search interface on top of those services requires a high level of expertise and understanding of the product (see Implement a Search Interface). As such, you should only consider developing directly against the Search API and Usage Analytics Write API if you can’t use the Coveo JavaScript Search Framework for some legitimate reason (e.g., if you’re integrating a Coveo-based search interface in a desktop or mobile application).

Exposing API Keys in Client-Side Code

Exposing an API key which can only be used to log usage analytics events and execute queries anonymously is acceptable under specific circumstances (see Public API Key Authentication Scenario). 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 (e.g., 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.

Enabling Search-As-You-Type

Enabling the search-as-you-type feature typically consumes a large amount of queries. Moreover, if the delay to display new search results is too long, many end users will likely be typing faster than the refresh rate, therefore defeating the very purpose of the feature. On the other hand, if the refresh delay is too short, the search interface will flicker, causing a poor end-user experience.

Usually, it’s preferable to enable a query suggestions experience in the search box by leveraging Coveo Machine Learning (Coveo ML) Query Suggestions (QS). This light and fast approach directs end users towards successful queries, rather than displaying actual results for partial queries.

Pre-Selecting Filters

You may be tempted to automatically enforce a specific filter expression (e.g., 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. If you find that many end users are using the same filters, there might be a relevance issue in your index; you may then want to consider demoting or removing irrelevant items.

Using Category Facets Unnecessarily

A category facet is a Coveo JavaScript Search Framework component allowing you to display a set of hierarchically organized filter values as such (see Using the Category Facet Component). 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 simple search-driven list in your search interface that displays, for example, relevant and/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 (see Using Wildcards in Queries). In a search interface which provides query suggestions, users are guided towards relevant queries which will return appropriate results. Furthermore, in a Coveo JavaScript Search Framework interface, you should rather use the DidYouMean component to get query suggestions when a query returns no results.

Relevance Tuning Pitfall

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.

What's next for me?