Elasticsearch Index Mapping: What It Is and How to Configure It

An Elasticsearch index mapping defines how documents are structured and how each field is indexed — which fields are searchable, which are filterable, and what data type is used for each.

Dynamic vs explicit mapping

• Without an explicit mapping, Elasticsearch infers types from the first document — a string field gets both text (analyzed, full-text searchable) and keyword (exact match, sortable) sub-fields by default
• Dynamic mapping is convenient for prototyping but risky in production — if a malformed document is indexed first, the wrong type is inferred and subsequent correct documents may fail or store incorrectly
• Define explicit mappings before indexing production data: PUT /products/_mapping { "properties": { "name": { "type": "text" }, "status": { "type": "keyword" } } }

`text` vs `keyword` — the critical distinction

• text fields are analyzed — the analyzer tokenizes the value and indexes each token, which means match queries work for partial matches and the text is not suitable for sorting or aggregation
• keyword fields are stored as-is — used for exact match (term queries), filtering, sorting, and aggregations; status = "active" must be a keyword field, not text
• The common mistake: mapping a field that you'll filter and aggregate on (like status, category, user_id) as text instead of keyword; text fields can't be used for exact filtering or aggregations

Index settings — analysis and performance

• number_of_shards is set at index creation and cannot be changed — choose based on expected document count; a shard that grows beyond 50GB performs poorly; plan for 20-30GB per shard as a target
• number_of_replicas can be changed anytime — 1 replica per primary is the standard for production; replicas serve read requests and provide failover

Changing a field's mapping after indexing requires re-indexing the data — the _reindex API copies documents from one index to another with the new mapping applied.