Elasticsearch Reference

This section documents the current Elasticsearch 9.x line (with 8.19 as the final 8.x release) as published at the Elasticsearch documentation, which is the reference these pages are written and verified against. No specific patch version is pinned. Some capabilities (Kibana-only UIs, the ML/NLP model-management workflow, cross-cluster replication, and parts of the paid / serverless-only surface) are linked, not documented in depth.

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production, as Elasticsearch iterates quickly.

This section’s bibliography lists the reference material consulted while preparing these pages.

Welcome to the Elasticsearch reference. Elasticsearch is a distributed, near-real-time JSON document store and search / analytics engine built on Apache Lucene: it stores each record as a JSON document in an index, analyzes text into an inverted index of terms for relevance-ranked full-text search, exposes a rich JSON Query DSL (plus ES|QL, EQL and SQL) and an aggregation framework for real-time analytics, and shards every index across a cluster with automatic replication and failover. This section documents the current Elasticsearch line as a database-developer reference — the data model, mapping and analysis, indexing and querying, relevance and aggregations, the distributed model, index lifecycle, tuning, operations and security, and the clients — written and verified against the Elasticsearch documentation.

If you are new to Elasticsearch, read What Elasticsearch is & how to run it first, then Documents, indices & the inverted index and Mapping & field types, followed by The search API, paging & sorting. Everything after that builds on those foundations.

For the relational and document-database baselines this section contrasts with, see the sibling SQL Reference, MongoDB Reference and Couchbase Reference, which the Elasticsearch pages cross-link rather than restate. For where a dedicated search engine fits alongside a primary store, see Choosing the Right Database. For the other mature Lucene-based search server and how the two compare, see Solr vs. Elasticsearch.

What’s covered

Getting started

  • What Elasticsearch is & how to run it — Elasticsearch as a distributed, Lucene-based JSON document and search / analytics engine, its place in the Elastic Stack, the release line, running a node (Docker, the archive, Elastic Cloud / serverless), the Kibana Dev Tools Console and curl conventions used throughout this section, and a first index / search round-trip.

Data model, mapping & analysis

  • Documents, indices & the inverted index — a document as JSON with _source and metadata fields, an index as documents + settings
    mappings, one type per index, the inverted index and Lucene segments, and near-real-time search with the refresh cycle.

  • Mapping & field types — dynamic vs. explicit mapping, the main field data types (text vs. keyword, numeric, date, object vs. nested, flattened, geo_point / geo_shape, dense_vector, join, completion), multi-fields, mapping parameters, metadata fields, dynamic templates, runtime fields, and preventing mapping explosion.

  • Text analysis: analyzers, tokenizers & token filters — the character filters / tokenizer / token filters chain, the built-in analyzers and the _analyze API, custom analyzers and search_analyzer, normalizers, and the tokenizers and token filters behind partial matching, stemming, stop words and synonyms.

Indexing

  • Indexing, CRUD, bulk & concurrency control — the single-document APIs (index / get / update / delete, partial and scripted updates, upsert), the multi-document APIs (_bulk, _mget, _update_by_query / _delete_by_query, _reindex), optimistic concurrency control with _seq_no / _primary_term, and the refresh request parameter.

  • Ingest pipelines & processors — ingest-node pipelines and processors (set, grok, dissect, date, geoip, script, enrich, pipeline), on_failure handling, the _simulate API, and default_pipeline / final_pipeline.

Searching & analytics

  • The search API, paging & sorting — the _search endpoint and response envelope, query vs. filter context, choosing fields (_source filtering, fields, docvalue_fields), sorting, and pagination with from / size, keyset-style search_after + point-in-time, and scroll.

  • Full-text queries — match, match_phrase, match_phrase_prefix, multi_match and its types, combined_fields, query_string / simple_query_string, and intervals.

  • Term-level queries — term, terms (and terms-lookup), terms_set, range with date math, exists, ids, and the expensive prefix / wildcard / regexp / fuzzy queries.

  • Compound queries, relevance & scoring — bool / dis_max / constant_score / boosting, BM25 as the default similarity, the _explain API, query-time boost and named queries, function_score and script_score, and rescore.

  • Aggregations — the metric, bucket and pipeline families, running aggregations on the query result set, sub-aggregations and nesting, and the approximate-count / approximate-percentile trade-offs.

  • Joins & relationships — object vs. nested, the join field for parent-child (has_child / has_parent), terms-lookup joins, and denormalizing vs. application-side joins.

  • Search extras: highlighting, suggesters, collapse, percolation & more like this — highlighting, the term / phrase / completion suggesters and the search_as_you_type field, result collapse and _msearch, search templates, the percolate query, and more_like_this for finding similar documents.

  • Geospatial data & queries — geo_point and geo_shape mappings and coordinate formats, the geo queries (geo_bounding_box, geo_distance, geo_shape, geo_grid), and the geo aggregations (geohash_grid / geotile_grid, geo_bounds, geo_centroid).

  • Vector & semantic search — dense_vector mapping and kNN search (approximate and exact, filtered), sparse_vector / ELSER, the semantic_text field and the semantic query, and retrievers (standard, knn, rrf, text_similarity_reranker) for hybrid search.

  • Query languages & scripting — when to reach for ES|QL (piped), EQL (event sequences), Elasticsearch SQL (_sql, JDBC / ODBC) or KQL / Lucene syntax instead of the Query DSL, and Painless scripting (script contexts, params, stored scripts).

Distributed model & operations

  • Cluster, nodes & shards — the cluster / node / index / shard / segment model, primary and replica shards, node roles and the data tiers, discovery and master election, routing and query-then-fetch search, and cluster health.

  • Index lifecycle & scaling — shard sizing and time-based indices, aliases and the write alias, index and component templates, data streams and rollover, ILM phases and actions, the data-stream lifecycle, downsampling, and searchable snapshots.

  • Performance & the storage/caching model — tuning for indexing speed (_bulk, refresh_interval, the translog, segment merges) and search speed (query vs. filter context, the node query and shard request caches), the fielddata trap and doc_values, and tuning for disk usage.

  • Administration, monitoring & snapshots — the _cat APIs and the cluster / nodes stats APIs, what to watch (heap, thread-pool rejections, disk watermarks, unassigned shards, slow logs), and snapshot & restore with snapshot lifecycle management.

  • Securing a cluster — transport and HTTP TLS and the enrollment flow, the authentication realms and API keys, role-based access control with field- and document-level security, and the audit log.

  • Clients & REST API conventions — the official language clients and what they share, the REST API conventions (multi-target syntax, date math in index names, ?filter_path and the common options), and the REST API compatibility policy.

Cheat sheet

  • Cheat Sheet (PDF) — a single-page, printable summary of everything in this section, with a downloadable PDF.

Bibliography