AI TL;DR
Too lazy to read? Summarize this post with:
Blog Post Publish Date: 2025/01/05
OpenSearch Concepts: Index and Shards#
This blog post explains two of the most basic concepts in OpenSearch administration: indices and shards. It covers what primary and replica shards are, how their counts affect performance and fault tolerance, and the API calls I use most to inspect indices and shards while troubleshooting.
Understanding Indices and Shards#
An index is a logical namespace for a collection of documents and their characteristics, such as field types, lifecycle policies, and storage tier. OpenSearch stores those documents on disk in partitions called shards.
A shard is one partition of an index, and each shard is a full Lucene index. As the OpenSearch introduction describes, shards come in two kinds:
Primary shards receive every write and can also serve reads.
Replica shards are copies of the primaries. They provide fault tolerance and serve reads, which spreads the query load.
An index can have one or more shards spread across several nodes. That distribution is what lets an OpenSearch cluster scale an index beyond one machine and survive the loss of a node.
Primary shards |
Replica shards |
|
|---|---|---|
Purpose |
Hold the data and receive every write |
Copies of the primaries for fault tolerance and reads |
More of them means |
More parallel indexing, until shards get too small |
More read capacity and more copies to survive node failures |
Can change after creation? |
Only with split, shrink, or reindex |
Yes, at any time |
More primary shards spread writes across more partitions and nodes, which raises indexing throughput. More replicas add fault tolerance and more nodes that can answer queries.
The number of primary shards is set when the index is created. Changing it later means creating a new index with the split or shrink APIs, or reindexing. Choose it carefully, based on your query load and, above all, your write load. Replicas can be changed at any time.
More shards are not always better, though. Every shard costs heap, file handles, and cluster state, so many small shards hurt more than they help. I wrote about one way to avoid that in Avoiding Over-Sharding in OpenSearch with Filtered Aliases.
Note
A primary shard and its replica are never allocated to the same node. If that node fails, the other copy is still available.
Useful API Calls for Indices and Shards#
These calls help with troubleshooting and monitoring indices and shards. You can run them in OpenSearch Dashboards » Dev Tools or with an HTTP client such as cURL or Postman.
List all indices, sorted by name (CAT indices):
GET _cat/indices?v&s=index
List the shards of a specific index:
GET <INDEX-NAME>/_search_shards
Get the index settings, for example the number of shards, replicas, and creation time:
GET <INDEX-NAME>/_settings
Get the field types defined in the index mapping:
GET <INDEX-NAME>/_mapping
Show the ISM policy attached to an index (ISM explain API):
GET _plugins/ism/explain/<INDEX-NAME>?show_policy=true
List shards that are not allocated to any node (status UNASSIGNED) and why (CAT shards):
GET _cat/shards?v&h=index,shard,prirep,state,unassigned.reason&s=state
Check how shards and disk are distributed across nodes (CAT allocation):
GET _cat/allocation?v
Follow shard recovery or relocation progress (CAT recovery):
GET _cat/recovery/<INDEX-NAME>?v&s=stage:desc
List all shards, sorted by index:
GET _cat/shards?v&s=index
List indices, sorted by size:
GET _cat/indices?v&h=index,store.size&s=store.size:desc
These calls answer most of my day-to-day questions about a cluster. When the allocation output shows nodes with very different disk usage, OpenSearch Shard Allocation: Balanced by Count, Rebalanced by Watermarks explains why. When you need to remove nodes, Scaling Down and Resizing OpenSearch Data Nodes shows how to move their shards safely first.
Key Takeaways#
An index is a logical collection of documents. Shards are the partitions that store it, and each shard is a Lucene index.
Primary shards receive every write. Replica shards are copies that add fault tolerance and serve reads.
The number of primary shards is fixed at creation. Changing it requires split, shrink, or reindex. Replicas can change at any time.
More primaries raise write throughput, but too many small shards waste heap and cluster state.
A primary and its replica are never placed on the same node.
_cat/indices,_cat/shards,_cat/allocation, and_cat/recoverycover most troubleshooting questions about indices and shards.
References#
I’m Carlos Neto, and I’ve been running OpenSearch on EKS for over five years. More about me on my home page. If you have questions or a different approach, contact me on LinkedIn.