Query limits and caching

The managed registry limits how many queries each caller translates at once, and caches translations. Neither changes a query's result.

Concurrent queries

CallerQueries translating at once
Each user and each service account3
Callers without an API key (web playground, pip guests)5, shared by all of them

A query over the limit is refused with HTTP 429, code OE/QUERY-CONCURRENCY-LIMIT, and a Retry-After header (in seconds). It was not run, billed or recorded in the query history, so sending it again is safe.

The Python client and the documentation playground do this for you: they wait Retry-After (at most 10 seconds) and send the query again, up to 3 times, before returning the error. Your own HTTP client should do the same. If you run many queries in parallel, keep at most 3 in flight per API key.

A 429 without Retry-After is the monthly usage limit (OE/USAGE-LIMIT-REACHED, see Billing ). Waiting does not help: an owner or admin of the organization raises the limit, or it resets next month. Clients do not retry it.

Translation cache

When the same query was translated before, against the same features, the registry returns the stored translation instead of translating again. Nothing to configure:

  • Same text, same catalog. Any change to the project's features or data caches makes the stored translation unusable.
  • Same query, written differently. Spacing and keyword case do not matter. Comments do, since they can carry tags.
  • Same answer. A stored translation is used only if nothing it read has changed since: the features it reads (directly or through other features) and the data caches registered for them. The result is that of a fresh translation.
  • Per caller. Entries are kept per project, user, role, backend and options, so permissions apply as usual.
  • Not cached: statements that change the catalog (CREATE, DROP, ALTER, transactions), SHOW, DESCRIBE, EXPLAIN, FORMAT, and queries that failed.

A query served from the cache is billed and kept in the query history like any other.

Each FeatureQL response tells whether the cache was used, in its X-FeatureMesh-Query-Cache header. The Python client copies it to result.query_cache:

ValueMeaning
MISSTranslated now, and stored for next time
L1Served from the cache: same text already translated
L2Served from the cache: same query once parsed (spacing and keyword case aside), after checking that nothing it read changed
BYPASSThe cache does not apply: statement not cached, NO-QUERY-CACHE, or cache turned off

To translate a query afresh, add /* NO-QUERY-CACHE */ (or a -- NO-QUERY-CACHE line):

/* NO-QUERY-CACHE */
RETURN FM.SALES.TOTAL_AMOUNT;

NO-QUERY-CACHE is not NO-CACHE. /* NO-CACHE */ tells the compiler not to read data caches , so values are computed from the sources. Each tag does only its own thing, and they can be combined.

Related