Indices, Documents, and Mappings
An Elasticsearch index is a named collection of documents that share a similar structure, roughly comparable to a table in a relational database, though the comparison is imperfect since Elasticsearch is schema-flexible rather than schema-rigid. A document is a single JSON object representing one record — one product, one log entry, one user profile — and is uniquely identified within its index by an _id. Every document is indexed according to a mapping, which defines each field's data type and how it should be analyzed and stored, and that mapping directly determines what kinds of queries will work correctly against each field.
Cricket analogy: An index called 'matches' holding one document per ODI, each with fields like teams, venue, and score, is like a physical scorebook where every page is one match record, structured the same way page after page.
Field Types and Dynamic Mapping
Elasticsearch supports many field types, including text (analyzed, tokenized, full-text searchable), keyword (stored as-is, used for exact matching, aggregations, and sorting), numeric types like long and float, date, boolean, and object/nested for structured sub-documents. If you don't explicitly define a mapping, Elasticsearch uses dynamic mapping to guess field types from the first document it sees — a string typically becomes both a text field and a keyword sub-field (via a multi-field mapping) so it's searchable both as full text and as an exact value. This convenience is useful for prototyping but risky in production, because a field guessed as 'date' from one document's format can reject later documents with a different, incompatible date format.
Cricket analogy: Letting Elasticsearch auto-detect that 'venue' is text but 'match_date' is a date field is like a new scorer guessing field formats from the first scorecard they see, which works until a differently formatted card breaks the pattern.
The distinction between text and keyword fields is one of the most important mapping decisions you'll make. A text field is passed through an analyzer at index time — typically lowercased and split into individual tokens — so 'Wireless Keyboard' becomes searchable by 'wireless' or 'keyboard' independently, but it cannot be used for exact-match filtering, sorting, or aggregations like terms buckets, because the original string isn't stored as a single unit. A keyword field is stored exactly as-is, unanalyzed, which makes it ideal for filters, sorting, and aggregations such as 'count products by category', but it can't match partial words the way a text field can.
Cricket analogy: Storing a player's 'team' as keyword ('Mumbai Indians') lets you aggregate wins by exact team name, while storing match 'commentary' as text lets fans search for 'six' anywhere in the description.
PUT /articles
{
"mappings": {
"properties": {
"title": { "type": "text" },
"category": { "type": "keyword" },
"published": { "type": "date" },
"views": { "type": "long" },
"tags": {
"type": "text",
"fields": {
"raw": { "type": "keyword" }
}
}
}
}
}You cannot change an existing field's type in a mapping once documents have been indexed — Elasticsearch will reject a conflicting mapping update. To fix a mapping mistake, create a new index with the corrected mapping and use the Reindex API to copy documents across, then repoint your alias or application to the new index.
Multi-Fields and Nested Objects
Multi-fields let a single JSON field be indexed multiple ways at once, most commonly as both text and keyword using the fields parameter (e.g., tags with a tags.raw sub-field), so you can full-text search on tags while aggregating exact counts on tags.raw. For structured sub-documents, Elasticsearch offers object mapping, which flattens nested fields into the parent document's namespace (losing the relationship between array elements), and nested mapping, which indexes each array element as a hidden separate Lucene document internally, preserving the exact association between fields within each array element for accurate querying.
Cricket analogy: Mapping a player's 'strokes' array as nested keeps each shot's type and runs correctly paired, avoiding false matches like 'four scored on a defensive shot' that a flattened object mapping could accidentally produce.
Use nested mapping whenever you need to query on combinations of fields within array elements (e.g., 'find orders with a line item where product=X AND quantity>10'). If you only ever query fields independently, the simpler and more performant object mapping is usually sufficient.
- An index is a named collection of similar documents; a document is a single JSON record identified by an _id.
- A mapping defines each field's type and controls how it is indexed, searched, and aggregated.
- Dynamic mapping auto-detects field types from the first document but can cause conflicts on inconsistent data.
- text fields are analyzed/tokenized for full-text search; keyword fields are stored exactly for filtering, sorting, and aggregations.
- Field types cannot be changed after documents are indexed; use Reindex API with a new mapping to fix mistakes.
- Multi-fields let one field be indexed multiple ways, commonly as both text and keyword.
- Nested mapping preserves correct field associations within array elements, unlike flattened object mapping.
Practice what you learned
1. What uniquely identifies a document within an Elasticsearch index?
2. Which field type should you use for exact-match filtering, sorting, and terms aggregations?
3. What happens if you try to change an existing field's type in a mapping after documents are indexed?
4. Why would you choose a nested mapping over a plain object mapping for an array of sub-objects?
5. What does dynamic mapping do when Elasticsearch encounters a new field for the first time?
Was this page helpful?
You May Also Like
What Is Elasticsearch?
An introduction to Elasticsearch as a distributed search and analytics engine, why it exists, and the core concepts that make full-text search fast at scale.
The Elasticsearch REST API
How to interact with Elasticsearch over HTTP: indexing, retrieving, searching, and managing documents and indices via the REST API.
Installing and Running Elasticsearch
How to install, configure, and start a local Elasticsearch node or cluster, including key settings and common startup issues.