How to design Elasticsearch index mappings and analyzers

What and why

Elasticsearch stores documents in indices and uses mappings to define how each field is stored and searched. Getting mappings and analyzers right is what makes search fast and relevant: text fields are tokenized for full-text search, while keyword fields support exact matches, sorting, and aggregations. This tutorial defines mappings and runs a search.

Prerequisites

• A running Elasticsearch cluster reachable over HTTP.
• Familiarity with JSON and REST calls (curl or Kibana Dev Tools).
• Sample documents to index.

Steps

1. Start Elasticsearch

docker run -d --name es -p 9200:9200 -e discovery.type=single-node \
  docker.elastic.co/elasticsearch/elasticsearch:8.13.0

2. Plan field types

Decide per field: text for full-text (descriptions), keyword for exact values (status, tags), and numeric/date types for ranges and sorting. Relying on dynamic mapping often makes everything both text and keyword, wasting space.

3. Create an index with mappings

curl -X PUT localhost:9200/products -H 'Content-Type: application/json' -d '{
  "mappings": { "properties": {
    "title": { "type": "text" },
    "status": { "type": "keyword" },
    "price": { "type": "scaled_float", "scaling_factor": 100 },
    "created_at": { "type": "date" }
  } }
}'

4. Configure an analyzer

Analyzers control tokenization for text fields. Define a custom analyzer in index settings to add lowercasing and stop-word handling, then reference it on the field with "analyzer": "my_analyzer". The default standard analyzer suits many cases.

5. Index documents

curl -X POST localhost:9200/products/_doc -H 'Content-Type: application/json' -d '{
  "title": "Wireless headphones", "status": "active", "price": 79.99, "created_at": "2026-06-01"
}'

6. Run a search query

Full-text on title, filtered by status:

curl localhost:9200/products/_search -H 'Content-Type: application/json' -d '{
  "query": { "bool": {
    "must": { "match": { "title": "headphones" } },
    "filter": { "term": { "status": "active" } }
  } }
}'

Verification

The search should return the indexed document ranked by relevance. Use the _analyze API to see how text is tokenized, and confirm a term query on status matches exactly while a match on title matches individual words.

Next Steps

Use index templates for consistent mappings, add multi-fields to index one value as both text and keyword, and tune relevance with custom scoring and synonyms.