Render static content using persistent queries

This is for:

Developer
Important

Persistent queries are no longer part of product entitlements and have been deprecated.

When you need to render a search-based section in a web page or application by querying content that doesn’t change very often, it’s best to do so without impacting the queries per month (QPM) quota of the underlying Coveo organization (see Query Types). This is possible through the use of persistent queries.

Perform a persistent query

When executing a query through the Search API, set the staticQuery parameter to true to flag that query as persistent (see Manage query parameter rules).

A persistent query differs from a regular query as follows:

  • If the persistent query is being executed for the first time in a given month, this persistent query counts against your QPM quota as a single, regular query.

  • Any later execution of the same persistent query during the same month doesn’t count against your QPM quota.

  • persistent query result sets are cached and incrementally updated every few hours.

Persistent query example

You could use a persistent query like the following to populate a search-based section with content related to release notes about a specific product:

POST https://platform.cloud.coveo.com/rest/search/v2/ HTTP/1.1
​
Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************

Payload

{
  "aq": "@documenttype==\"ReleaseNote\" AND @productname==\"MyProduct\"",
  "staticQuery": true
}
Notes

  • Setting the staticQuery parameter to true overrides the maximumAge parameter with a high value.

  • The persistent query count is reset to zero on the first of each month (see Entitlements).

  • If you need to change the rate at which persistent query result sets are refreshed in your Coveo organization, contact Coveo Support.

Determine persistent query uniqueness

Two queries are considered to be the same persistent query if both are flagged as persistent (that is, they both have their staticQuery parameter set to true) and if the following values are the same for both queries after they have been processed by the query pipeline:

Both queries must also be run using the same user identity.

Query uniqueness examples

  • The following persistent queries count as two distinct queries against your QPM quota because they have different firstResult values:

      {
  "aq": "@documenttype==\"ReleaseNote\"",
  "firstResult": 0,
  "numberOfResults": 10,
  "sortCriteria": "Relevancy",
  "staticQuery": true
  }
      {
  "aq": "@documenttype==\"ReleaseNote\"",
  "firstResult": 9,
  "numberOfResults": 10,
  "sortCriteria": "Relevancy",
  "staticQuery": true
  }

  • The following persistent queries count as a single query against your QPM quota, even though some of their parameters differ:

      {
  "aq": "@documenttype==\"ReleaseNote\"",
  "excerptLength": 500,
  "firstResult": 0,
  "locale": "en-US",
  "numberOfResults": 10,
  "sortCriteria": "Relevancy",
  "staticQuery": true,
  "timezone": "America/New_York"
  }
      {
  "aq": "@documenttype==\"ReleaseNote\"",
  "firstResult": 0,
  "locale": "fr-FR",
  "numberOfResults": 10,
  "sortCriteria": "Relevancy",
  "staticQuery": true,
  "timezone": "Europe/Paris"
  }

Persistent queries and Coveo Machine Learning

Due to their static nature, persistent queries have limited compatibility with Coveo Machine Learning (Coveo ML). It’s nevertheless possible to configure an Automatic Relevance Tuning (ART) model in the query pipeline that processes a persistent query to achieve a specific goal, such as getting trending items in the result set of a search request with an empty query expression.

If you want to use an ART model along with a persistent query, keep in mind that the model may generate different output whenever it’s updated (for example, on a daily, weekly, or monthly basis, depending on its configuration). It may generate a new unique persistent query each time.

Leading practices

  • Avoid basing persistent queries on dynamic expressions or user input.

  • Only use {persistent queries} to retrieve query results that don’t need to be regularly updated.

  • Process persistent queries through dedicated query pipelines.

  • Processing persistent queries through non-empty query pipelines can add a layer of complexity when determining their uniqueness.