Search (the feature)

A pointer page. The bulk of the search documentation lives at Search system. This page covers what users see — the query DSL surface, the most common entry points, and where to extend the language.

The _search endpoint

POST /<index>/_search
{
  "query": {...},
  "aggs":  {...},
  "sort":  [...],
  "size":  10,
  "from":  0,
  "_source": ["title", "body"],
  "highlight": {...},
  "rescore": {...},
  "knn": {...},
  "retriever": {...}
}

REST handler: RestSearchAction (server/src/main/java/org/elasticsearch/rest/action/search/RestSearchAction.java). Transport action: TransportSearchAction.

Query DSL

Each query in the JSON body deserializes into a QueryBuilder. Built-in queries live in server/src/main/java/org/elasticsearch/index/query/:

• Term-level: term, terms, range, exists, prefix, wildcard, regexp, fuzzy.
• Compound: bool, dis_max, function_score, boosting, constant_score.
• Full-text: match, multi_match, match_phrase, match_phrase_prefix, simple_query_string, query_string.
• Geo: geo_distance, geo_bounding_box, geo_polygon, geo_shape.
• Joining: nested, has_child, has_parent, parent_id (parent-join lives in modules/parent-join).
• Specialized: more_like_this, script, script_score, pinned, rank_feature, distance_feature, intervals, combined_fields.
• Vector: knn (top-level) and script_score with vector functions.

Queries rewrite through MappedFieldType against the index mapping; the result is a Lucene Query.

Aggregations

See Aggregations. The aggregation tree is parsed alongside the query and runs on the same shards.

Retrievers

Newer style: a retriever is a higher-level "what to retrieve" abstraction that compiles down to one or more standard searches and an optional rerank. Built-in retrievers:

• standard — wraps a query.
• knn — wraps a vector search.
• rrf — Reciprocal Rank Fusion across child retrievers (X-Pack, in rank-rrf).
• rule — applies business overrides (X-Pack, in search-business-rules).
• text_similarity_reranker — reranks with an inference model (X-Pack).

Async search

x-pack/plugin/async-search/ lets the client submit a search and poll for results. Useful for long-running aggregations or cross-cluster searches against many remotes. See RestSubmitAsyncSearchAction, RestGetAsyncSearchAction.

SQL and EQL

Two domain-specific query languages sit on top of search:

• SQL (x-pack/plugin/sql/) — the legacy SQL-on-Elasticsearch frontend. Largely superseded by ES|QL but still supported.
• EQL (Event Query Language, x-pack/plugin/eql/) — sequence and time-window queries used heavily by the Elastic Security solution.

Both compile their AST to standard _search execution under the hood.

Profile API

?profile=true returns a per-shard breakdown of where the query phase spent its time. Implemented in server/src/main/java/org/elasticsearch/search/profile/.

Where to extend

• Add a query: QueryBuilder + parser + Tests; register via SearchPlugin#getQueries.
• Add a retriever: extend Retriever; register via SearchPlugin#getRetrievers.
• Add a rescorer: RescorerBuilder + Rescorer; register via SearchPlugin#getRescorers.
• Add a highlighter: implement Highlighter; register via SearchPlugin#getHighlighters.

For internal mechanics (two-phase execution, cancellation, cross-cluster), see Search system.