Keys query #

Returns documents whose key is in the provided set. There is no field argument — the match is against the document identity itself, and values that do not exist in the collection are skipped.

The query’s native name is keys: it speaks Pizza’s _key vocabulary, the same word the REST API uses for by-key addressing. The ids spelling deserializes to the same query — an accepted alias, not a different feature.

On Pizza server the same mixed-id convention as GET/DELETE/UPDATE applies to every value: a value containing a comma ("0,17") addresses a document by its system id (rolling,seq — the same id hits echo as _id); any other value is a user key. Query and response therefore speak the same ids both ways.

The convention is unambiguous because user keys are not allowed to contain commas — , is reserved as the system-id separator and is rejected at ingest (keys must not contain ',' (reserved for system IDs)).

In the playground / engine (single rolling context) values are document keys; a numeric value that matches no key addresses its system doc id.

How it works #

keys is a Pizza-native query, not an inverted-index lookup. At the search entry point the key set is rewritten into a store-level document-set query: each value is resolved through the store’s document-key index — a point lookup per key, not a term scan — and the resulting document ids become the match set. Consequences:

• It runs identically on every layer (live, built and frozen segments) — the key index exists before and after segment builds, so results never shift at build boundaries.
• Unknown values are skipped, not errors — only existing documents can match; an empty (or fully unknown) values array rewrites to match_none.
• Numbers are accepted and stringified (1 → "1"); on the engine a numeric value that resolves to no key addresses its system doc id, so keyless documents stay reachable.
• Scoring is constant: every hit scores 1.0, scaled by boost. There is no term frequency to rank by — identity is binary.

Unlike a term query, nothing about the document’s content is consulted: term matches a field’s indexed value (dictionary or BKD, BM25-scored on text), keys matches the document’s name in the store.

Examples #

No SQL twin: the SQL subset can project _key (SELECT _key …) but cannot filter on it yet — WHERE _key … matches nothing. Use the DSL form above.

POST /my-collection/_search
{
  "query": {
    "keys": { "values": ["L001", "L002", "NOPE"] }
  }
}

Unknown values (NOPE above) are skipped; an empty values array matches nothing. Numbers are accepted and stringified:

POST /my-collection/_search
{
  "query": {
    "keys": { "values": [1, 4] }
  }
}

The ids spelling in a full request:

POST /my-collection/_search
{
  "query": {
    "ids": { "values": ["L001", "L002"] }
  }
}

Use cases #

• Two-phase retrieval. Collect keys from a first pass (an aggregation, a collapse, a join) and re-fetch exactly those documents — a stable anchor when scores would otherwise reorder results.
• ids bodies carried over. Migrated requests using {"ids": {...}} run unchanged; the response speaks _key back.
• Spot-checking ingestion. “Did L001, L002 and the retried L150 land?” — unknown keys drop out silently, so the hit list is the answer.
• Addressing keyless documents. On the engine, numeric values that match no key fall back to system doc ids — the way to select documents indexed without a key at all.

Parameters for keys #

• values
  (Required, array of strings or numbers) Document keys to match. A document matches if its key is any of these values. Unknown keys are ignored; an empty array matches nothing.
• Server mixed-id values ("rolling,seq") route to the owning shard and resolve by system id; keys resolve on every shard holding them.
• boost
  (Optional, float, default: 1.0) Decrease or increase the relevance scores of the query.

Notes #

The query is executed natively: keys are resolved through the store’s document-key index on every layer (live, built and frozen segments), so it works the same before and after segment builds, and inside bool filter clauses. An explicit type parameter is rejected.

Related #

• term — the content-side counterpart: match a field’s indexed value instead of the document’s identity.
• join — key-based correlation between collections; join rewrites produce exactly the key/doc sets this query consumes.
• bool — combine a keys selection with content filters (e.g. keys of a batch AND an error-level term).