Common pitfalls

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.

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.

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

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

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.

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.

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.

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

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.