Search #

A search query, or query, is a request for information about documents in Pizza collections.

A search consists of one or more queries that are combined and sent to Pizza. Documents that match a search’s queries are returned in the hits, or search results, of the response.

A search may also contain additional information used to better process its queries. For example, a search may be limited to a specific collection or only return a specific number of results.

The canonical DSL at a glance #

Every search body is one JSON object whose keys fall into three layers — what matches, how it ranks, and what comes back:

{
  "query":           { ... },
  "retrieve":        [ { "bm25": { ... } }, { "vector": { ... } } ],
  "fuse":            { "method": "rrf", "k": 60 },
  "score_functions": { ... },
  "rescore":         { ... },
  "post_filter":     { ... },
  "sort":            [ { "field": "price", "order": "desc" } ],
  "from": 0,
  "size": 10,
  "highlight":       { ... },
  "collapse":        { ... },
  "aggs":            { ... }
}

• Matching — query. A recursively composable tree: leaf queries (match, term, range, vector, …) combined by bool (must / should / filter / must_not, plus minimum_should_match). A body without query is a match_all.
• Ranking — retrieve + fuse, then score_functions / rescore. Either a plain query, or a hybrid retrieve list — BM25 and vector legs side by side, mutually exclusive with a top-level query — merged by fuse (RRF / linear / disjunctive max). See hybrid search.
• Shaping — everything else. sort with from/size or search_after cursors, highlight, collapse, aggs, and _source/fields filtering decide what the response contains — the full list is in request-level options and API conventions.

Leaf form #

A leaf query names one field and one condition with explicit keys — the canonical strict form used by every example in this documentation:

{ "term":  { "field": "status", "value": "published" } }
{ "match": { "field": "message", "query": "this is a test" } }
{ "range": { "field": "age", "gte": 10, "lte": 20 } }

The same three queries in shorthand form ({"term": {"status": "published"}}) are accepted by the gateway as a migration courtesy only; the canonical form is the documented standard, and unknown top-level body keys are rejected with HTTP 400 instead of being silently ignored.

Execution model #

The body maps onto one execution pipeline. Matching produces candidates (scored doc ids); shaping reduces them to the returned page:

graph TD Q["matching — query
or retrieve + fuse"] --> PF("pre_filter") PF --> SF("score_functions") SF --> PO("post_filter") PO --> RS("rescore") RS --> PA("shaping — collapse, sort,
from/size or search_after") PA --> H["hits — _source + highlight"] Q -.->|"aggs see every match,
independent of pagination"| AGG["aggregations"]

pre_filter cuts candidates before scoring; post_filter narrows the hit list after scoring while aggregations still see the unfiltered matches (faceted navigation). The hybrid path runs retrieve → fuse → pre_filter → score_functions → truncate and rejects the stages it does not run (aggs, collapse, rescore, post_filter) by name — a stage is either executed or refused, never silently skipped.

Examples #

Search all the collections under the default namespace whose names are ended with -logs, fetch the documents whose field year has value 2024:

POST /default.*-logs/_search
{
  "query": {
    "term": {
      "field": "year",
      "value": "2024"
    }
  }
}

Requests #

POST /<targets>/_search
GET /<targets>/_search
POST /_search
GET /_search

A request without a targets path segment searches every collection the caller may access.

Path parameters #

• targets
  (Optional, String) Comma-separated, names of the collection to search (wildcard supported)

Query parameters #

URL parameters override the corresponding body fields and apply to every request shape:

• q
  (Optional, string) “lite” search — only consulted for a request without a body; becomes a query_string query.

• from
  (Optional, integer) How many documents to skip, should be non-negative and defaults to 0.

• size
  (Optional, integer) The maximum number of documents to be returned in hits, defaults to 10.

• track_total_hits
  (Optional, boolean) Whether to track the total hit count.

• key_as_id
  (Optional, boolean, default: false) compatibility hit rendering: keyed documents answer with the user key AS _id in every hit — the default keeps the system _id and reports the key as _key. Also accepted as a body field.

Response #

{
  "took": 5,
  "timed_out": false,
  "hits": {
    "total": { ... },
    "hits": [ { "_id": "0,0", "_key": "...", "_score": 1.0, "source": { ... } } ]
  },
  "aggregations": { ... }
}

aggregations is present only when the request carried aggs. A search that exceeded its deadline returns partial results with "timed_out": true.

Request bodies are accepted in Pizza’s canonical DSL (the documented standard — see API conventions), and the gateway additionally tolerates common Elasticsearch forms; a bodyless GET is a match_all query. Much of this surface also has an SQL spelling — every example widget on the query pages toggles between DSL and SQL where the SQL subset reaches.

Full-text queries #

• match query
  Returns documents that match a provided text, number, date or boolean value. The provided text is analyzed before matching.
• phrase query
  Returns documents that contain the exact sequence of terms of the provided text, in order.
• multi_match query
  Returns documents that match a provided text across several fields with per-field boosts.
• query_string query
  Returns documents that match a compact query-syntax string, e.g. status:active AND title:search.
• bool query
  Matches documents matching boolean combinations of other queries.
• match_all query
  Matches every document — the default when no query is sent. match_none matches none.
• span queries
  Low-level positional queries (span_term, span_near, span_or, span_multi) for phrase-adjacent logic.
• intervals query
  The rule language for term positions: sequences, bounded gaps, unordered combinations, positional filters.

Term-level queries #

• exists query
  Returns documents that contain an indexed value for a field.
• fuzzy query
  Returns documents that contain terms similar to the search term within an edit distance.
• prefix query
  Returns documents that contain a specific prefix in a provided field.
• range query
  Returns documents that contain terms within a provided range.
• regexp query
  Returns documents that contain terms matching a regular expression.
• suffix query
  Returns documents that contain terms ending in the provided value.
• term query
  Returns documents that contain an exact term in a provided field.
• terms query
  Returns documents that contain one or more exact terms in a provided field.
• wildcard query
  Returns documents that contain terms matching a wildcard pattern.
• keys query
  Returns documents whose key is in the provided set (ids spelling also accepted).

Geo queries #

• geo_bounding_box query
  Returns documents with a geo point inside a rectangle.
• geo_distance query
  Returns documents with a geo point within a radius.
• geo_polygon query
  Returns documents with a geo point inside an arbitrary polygon.
• geo_shape query
  Matches indexed shapes against a query geometry by spatial relation.

Vector queries #

• vector query
  kNN similarity search over vector fields; accepts an embedding or text (embedded server-side).
• multi_vector query
  Executes several vector queries and fuses the results (weighted sum or RRF).
• semantic query
  Semantic search with zero field knowledge: the vector field and embedding model resolve from the collection schema, the request is plain text; composes inside bool like any leaf.
• Hybrid search — the native retrieve + fuse DSL (BM25 + vector legs, RRF / linear fusion, strategy optimizer) plus the ES retriever and top-level knn syntaxes translated at the gateway. See the vector reference and API conventions.

Relational queries #

• nested query
  Matches parent documents via queries on nested sub-documents.
• join query
  Semi-join against a query on another index.
• traverse query
  Bounded graph traversal over relation-typed edge fields.
• graph block
  Renders the hit set as a node/edge graph for UIs and GraphRAG.

Specialized queries #

• distance_feature query
  Recalls every document and scores by proximity to an origin (date, numeric or geo point).
• more_like_this query
  Finds documents similar to given text or documents — top terms as a disjunctive query, no embedding model.
• Scripted queries
  script_score scoring, script filter predicates and the _script sort key on the sandboxed script engine.

Other supported query types #

Two variants of the catalog above round out the query surface:

• match_none — matches no documents; useful as a placeholder branch in generated queries. See match all.
• Every leaf also accepts rewrite (constant-score and top-N forms) and case_insensitive where exact matching applies.

Request-level options #

Beyond query, the search body accepts: sort and cursor pagination ( sort and pagination), highlight ( highlighting), hybrid retrieval and scoring stages ( hybrid search), second-pass re-ranking ( rescore), result deduplication ( field collapsing), computed per-hit values ( script fields), streaming delivery ( streaming search), plus from, size, track_total_hits, collect_size, timeout, explain, _source, fields, epoch_range and point-in-time snapshot_id (see API conventions).

Analysis #

• Analyze text
  The analysis workbench: run analyzers and pipelines over sample text.
• Built-in analysis components
  The shipped catalog: 83 analyzers, 50 tokenizers, 15 normalizers and 327 token filters, from language analyzers to CJK segmentation.