Documents, Mapping & Indexing

The Core Model

A distributed search/analytics engine built on Lucene. An index is roughly a "table" (a collection of similar documents); a document is roughly a "row" — a JSON object. Internally it's built on an inverted index: a mapping from each term to the documents containing it, so a search jumps straight to relevant docs instead of scanning everything.

Mapping: text vs. keyword

PUT /articles
{
  "mappings": {
    "properties": {
      "title": {
        "type": "text",
        "fields": { "keyword": { "type": "keyword" } }
      },
      "published_at": { "type": "date" },
      "views": { "type": "integer" }
    }
  }
}
// title -> full-text search; title.keyword -> exact match/sort/aggregation

text fields are analyzed (tokenized, lowercased) for word-level matching. keyword fields are stored as-is, for exact filtering/sorting/aggregations. Mapping structural changes (like changing a field's type) generally require reindexing into a new index — not an in-place edit.

Indexing a Document

POST /articles/_doc/1
{ "title": "Learning Elasticsearch", "views": 42, "published_at": "2026-09-01" }

# newly indexed docs aren't immediately searchable — visible only after
# the next periodic refresh (default ~1s) — near-real-time, not real-time

Shards, Replicas & Reindexing

An index is split into shards, distributed across nodes for parallel processing/horizontal scale. Replicas are copies of primary shards on other nodes, for fault tolerance and extra read throughput. Shard count is much harder to change after index creation — plan for growth upfront. Aliases let you repoint queries from an old index to a newly reindexed one with zero app downtime.