Render static content using persistent queries

This is for:

Developer

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 (see About Persistent Queries).

Performing 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 query per month quota as a single, regular query.
  • Any subsequent execution of the exact same persistent query during the same month doesn’t count against your query per month quota (see Determining Persistent Query Uniqueness).
  • Persistent query result sets are cached (and incrementally updated every few hours).

You could use a persistent query such as this one 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
}
  • 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.

Determining persistent query uniqueness

In order for two queries to be considered as the same persistent query, both queries must be flagged as persistent (i.e., have their staticQuery parameter set to true) and have the exact same q, aq, dq, cq, lq, firstResult, numberOfResults, and sortCriteria values (after they have been processed by the query pipeline). Both queries must also be run using the same user identity.

  • The following persistent queries count as two completely distinct queries against your query per month 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 query per month 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 extremely 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 in order 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 when it’s updated (e.g., on a daily, weekly, or monthly basis, depending on its configuration), each time potentially generating a new, unique persistent query (see Determining Persistent Query Uniqueness).

Leading practices

  • Avoid basing persistent queries on dynamic expressions and/or end-user input.
  • Use persistent queries only to retrieve query results that don’t need to be regularly updated.
  • Process persistent queries through dedicated query pipelines.
  • Be aware that processing persistent queries through non-empty query pipelines can add a layer of complexity when determining the uniqueness of persistent queries (see Determining Persistent Query Uniqueness).