Shards, replicas and cluster health

Elasticsearch Course · lesson 4 of 19 · 5 min read

How an index is split across nodes, and what yellow and red are actually telling you.

Open this lesson in the learning hub

Key points

  • An index is divided into primary shards, and each shard is a complete Lucene index of its own.
  • Since 7.0 a new index defaults to number_of_shards: 1 and number_of_replicas: 1.
  • The primary count is fixed at creation - changing it needs a reindex, or the split or shrink API.
  • Replicas are copies that also serve reads, so they buy availability and read throughput, not capacity.
  • Yellow means all primaries are assigned but a replica is not; red means a primary is missing.
  • A one-node cluster with the default replica is permanently yellow - a copy cannot share its own node.

Example

GET _cluster/health
GET _cat/shards/articles?v
GET _cluster/allocation/explain      # why is this shard unassigned

PUT /articles
{
  "settings": {
    "number_of_shards": 1,           # default since 7.0
    "number_of_replicas": 1
  }
}

Green means allocated, not fast - and yellow on a single node is normal, not an incident.

Documents, indices and near real time Analyzers, tokenizers and token filters

This is a reading copy. The full lesson — with the visual explainer, the interactive lab and a Run button for the code — lives in the Elasticsearch Course course, and every lesson in it is listed on the Elasticsearch Course contents page.