Understanding Persistent Queries

Coveo has recently introduced persistent queries to help customers reduce their QPM (queries per month). In order to understand the pertinence of this new feature, it is important to know what exactly counts as query in a Coveo Cloud implementation.

What is a Query

As a rule of thumb, whenever search results are updated, you can be fairly certain that a query was performed.

Technically, each call to the /rest/search/v2 (or /rest/search) Search API route counts as a query.

However, queries do not all count against the queries per month (QPM) quota. For instance, persistent queries count against the persistent queries per month (PQPM) quota of a Coveo Cloud organization.

What Counts as a Query

Queries can take multiple forms, but some of the most common are:

  • Search - A user types in the search box and hits Enter, or clicks the Submit button.

  • Applying filters - A user filters the search results by selecting a tab, toggling facet values, etc.

  • Sort - A user changes the sort criteria and/or direction of search results.

  • Paging - A user resizes the current page, or navigates to a specific page of the search results.

What Does Not Count as a Query

Here are a few examples of actions that do not count as queries:

  • Clicks - Clicking a search result item does not count as query. However, if you are using Coveo-powered listing pages, requesting the data to render such a listing triggers a search request, and therefore counts as a query.

  • Coveo ML Event Recommendations - These are available in the Enterprise Edition and count against their own quota (i.e., recommendations per month (RPM)).

  • Query suggestions - Getting facet value, field, or Coveo ML Query Suggestions does not count as a query. However, selecting a rendered query suggestion triggers a search request, and therefore counts as a query.

    Search-as-you-type is different from query suggestions, as it requests entirely new results on each keystroke. This means that when the search-as-you-type feature is enabled in a search box, each individual keystroke counts as a distinct query.

You can refer to the queries per month entitlement metric to get more detailed information about what does and does not count as a query (see Queries per Month (QPM)).

What is a Persistent Query

Some Coveo Cloud implementations can generate a lot of queries per month. Coveo has introduced persistent queries to help tackle this problem. Persistent queries allow you to render relatively static, search-based content without significantly impacting your monthly query quota.

A persistent query is just like a normal query, except it returns cached content. The content will be refreshed with the indexed information every two hours using the same search request parameters. Each Coveo Cloud organization is allowed a certain number of persistent queries, which can be used to flag any query performed against its index. A query flagged as persistent can be performed indefinitely as it does not count against the query per month quota. A persistent query only counts once, in the persistent query limit. The persistent query count is reset to zero on the first day of each month (see Persistent Queries).

See Rendering Static Content Using Persistent Queries for more technical information and leading practices.

  • A website uses Coveo to power its listing pages. The results returned by these queries do not change very often and are the same for all users. Using persistent queries to power these pages will allow the underlying Coveo Cloud organization to save on QPM. In this use case, each listing page requires a persistent query; the number of times those pages are reloaded will therefore not affect the QPM. If the content of a listing page changes, the updated results will appear next time the persistent query cache refreshes (by default two hours).

  • An e-commerce website uses Coveo to display some featured products on its home page. Those products are selected on a daily basis by the content manager and are configured directly in Coveo Cloud. Since the website is using personalization, there are three kinds of featured products, based on three personas. To prevent querying the index each time a user is accessing the home page, persistent queries are used. However, since there is a small variation in the queries (the persona), three persistent queries will be required to render the component for every use case.