What Elasticsearch is & how to run it

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.

Elasticsearch is a distributed, near-real-time search and analytics engine that stores data as JSON documents and makes every field searchable. It is built on Apache Lucene and is driven entirely through a REST/JSON API. This page explains the model, where Elasticsearch sits in the Elastic Stack, what it is not, how to start a node, and how to make a first round-trip against it.

A distributed JSON document store and search engine

Elasticsearch keeps data as JSON documents grouped into indices. Each index is split into shards, and every shard is a self-contained Apache Lucene index; replica shards give the cluster redundancy and extra read capacity. Writes are near-real-time: a freshly indexed document becomes visible to search after the next refresh (once per second by default), not the instant the write returns. Cluster, nodes & shards covers that topology.

Every operation is an HTTP request with a JSON body — there is no binary wire protocol. The root endpoint reports the running version and the cluster name:

GET /
// https://www.elastic.co/guide/en/elasticsearch/reference/current/elasticsearch-intro.html

For the narrative overview and the mental model, read What is Elasticsearch?. For the full endpoint catalogue see REST APIs.

The Elastic Stack

Elasticsearch is the storage and search core of a set of tools that are usually deployed together:

Component Role

Elasticsearch

Stores documents, indexes them, answers search and aggregation requests

Kibana

Web UI for dashboards, plus the Dev Tools Console used for the [source,console] examples here

Elastic Agent / Beats

Lightweight shippers that collect logs, metrics and traces from hosts and services

Logstash

Server-side pipeline that parses, enriches and routes events before they reach Elasticsearch

The Console lives in Kibana under Management → Dev Tools; a good first request there is the cluster health check:

GET /_cluster/health
// https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-health.html

See Elastic Stack overview for how the pieces fit together, and Run Elasticsearch API requests for the Console itself.

Releases and versions

These pages track the 9.x line. 8.19 is the final 8.x release and continues to receive maintenance fixes; there is no 8.20. No specific patch version is pinned here. Check the running version before relying on a feature:

GET /
// "version": { "number": "9.x.y", ... }
// https://www.elastic.co/guide/en/elasticsearch/reference/current/es-release-notes.html

Per-release changes are listed in the Release notes.

What Elasticsearch is not

Elasticsearch has no multi-document ACID transactions. A single document write (index, update, delete) is atomic and durable once acknowledged, but there is no rollback spanning several documents and no serializable isolation. Concurrent updates are reconciled with optimistic concurrency control using the if_seq_no and if_primary_term parameters returned by every write — a stale write is rejected with a 409, and the client retries:

PUT /orders/_doc/1?if_seq_no=7&if_primary_term=1
{
  "status": "PAID",
  "total": 42.00
}
// 409 version_conflict_engine_exception if another writer moved _seq_no on.
// https://www.elastic.co/guide/en/elasticsearch/reference/current/optimistic-concurrency-control.html

Because of that, Elasticsearch is not a system of record for money movement and not a primary transactional store. Keep the authoritative copy of orders, ledgers and account balances in a store that offers real transactions, and feed Elasticsearch a searchable projection of that data. For an engine that does provide multi-document transactions, see MongoDB transactions; for choosing where each dataset belongs, see Choosing the Right Database.

Running Elasticsearch

Single-node Docker

The fastest local install is one container. Security is on by default, so the first start generates a password for the elastic user and a TLS CA; the flags below disable that for a throwaway dev node:

docker network create elastic

docker run -d --name es01 --net elastic -p 9200:9200 \
  -e "discovery.type=single-node" \
  -e "xpack.security.enabled=false" \
  docker.elastic.co/elasticsearch/elasticsearch:9.1.0

curl http://localhost:9200/
# https://www.elastic.co/guide/en/elasticsearch/reference/current/run-elasticsearch-locally.html

The full walk-through, including the multi-node Compose file, is Run Elasticsearch locally and Install Elasticsearch with Docker.

The archive and OS packages

For a non-container install, download the platform archive (tar.gz / zip) or the deb / rpm package. The archive runs from any directory with no root:

curl -O https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-9.1.0-linux-x86_64.tar.gz
tar -xzf elasticsearch-9.1.0-linux-x86_64.tar.gz
cd elasticsearch-9.1.0/
./bin/elasticsearch
# https://www.elastic.co/guide/en/elasticsearch/reference/current/targz.html

All install methods are indexed at Installing Elasticsearch.

Elastic Cloud and serverless

Elastic Cloud runs managed deployments on AWS, GCP or Azure with provisioning, upgrades, backups and monitoring handled for you. Elastic Cloud Serverless removes cluster sizing entirely — you create a project and get an endpoint, and storage and compute scale automatically. Both speak the same REST API, so every [source,console] example here works unchanged against them; only the base URL and credentials differ.

Security on by default

On a self-managed cluster, the very first start of the first node bootstraps security automatically. It prints a one-time elastic password and an enrollment token, and it generates the HTTPS CA certificate. Additional nodes and Kibana join by passing that token:

# Printed once on first start; regenerate if missed:
bin/elasticsearch-reset-password -u elastic
bin/elasticsearch-create-enrollment-token -s kibana

# Reach the secured node (self-signed CA in dev):
curl -u elastic:$PASSWORD --cacert config/certs/http_ca.crt https://localhost:9200/
# https://www.elastic.co/guide/en/elasticsearch/reference/current/configuring-stack-security.html

The enrollment flow, TLS layout and how to disable it for local dev are covered on Security; the reference is Start the Elastic Stack with security enabled.

Verify the node is up

GET / returns 200 with the version and cluster name once the node is ready; GET /_cluster/health reports green, yellow or red:

GET /
GET /_cluster/health
// status "yellow" on a single node just means replica shards are unassigned -- expected.
// https://www.elastic.co/guide/en/elasticsearch/reference/current/getting-started.html

Talking to Elasticsearch: Console syntax and curl

Examples in this section use the Kibana Dev Tools Console shorthand: an HTTP method, a path, and an optional JSON body, with no host, headers or quoting:

GET /_cluster/health?pretty

The equivalent curl adds the base URL, credentials and the JSON content-type header. ?pretty asks Elasticsearch to indent the JSON response (drop it in application code):

curl -u elastic:$PASSWORD --cacert http_ca.crt \
  -H 'Content-Type: application/json' \
  'https://localhost:9200/_cluster/health?pretty'
# https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html

Common request/response conventions — date math in index names, multi-target syntax, ?pretty, ?filter_path, error shapes — are documented in API conventions; Clients & REST conventions maps them onto the language clients. For querying with SQL-like syntax instead of the JSON DSL, see Query languages & scripting.

A first round-trip

Create an index, index a document into it, read it back by id, then search it. There is one document type per index; the write endpoint is the fixed literal _doc (the pre-7.x /<index>/<type>/<id> form is gone).

// 1. Create an index with an explicit mapping.
PUT /books
{
  "mappings": {
    "properties": {
      "title":  { "type": "text" },
      "author": { "type": "keyword" },
      "year":   { "type": "integer" }
    }
  }
}
// https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-create-index.html

// 2. Index one document under id 1.
PUT /books/_doc/1
{
  "title": "The Left Hand of Darkness",
  "author": "Ursula K. Le Guin",
  "year": 1969
}
// https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-index_.html

// 3. Fetch it back by id.
GET /books/_doc/1
// https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-get.html

// 4. Make it searchable now instead of waiting for the 1s refresh (test-only).
POST /books/_refresh

// 5. Full-text search: the match query analyses "darkness" and scores hits with BM25.
GET /books/_search
{
  "query": {
    "match": { "title": "darkness" }
  }
}
// https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-match-query.html

The response wraps hits in hits.hits[], each with its _source, _id and a relevance _score (BM25 is the default similarity). From here:

The reference walk-through for this sequence is Quick start and Getting started with Elasticsearch.

Continue with Documents & indices.