text versus keyword

Elasticsearch Course · lesson 7 of 19 · 5 min read

The single most common Elasticsearch mistake, and the multi-field that avoids it.

Open this lesson in the learning hub

Key points

  • text is analysed into terms for full-text matching; keyword is indexed as one exact term.
  • Sorting or aggregating on a text field fails, and the error suggests enabling fielddata - do not.
  • fielddata: true loads every term of that field onto the heap and is a classic way to kill a node.
  • Dynamic mapping hedges by giving strings both: a text field plus a .keyword sub-field.
  • That sub-field carries ignore_above: 256, so longer values are silently not indexed there.
  • Ids, status values, tags and enums should be keyword only - analysis buys nothing and costs disk.

Example

"title": {
  "type": "text",
  "fields": { "keyword": { "type": "keyword", "ignore_above": 256 } }
}

GET /articles/_search
{
  "query": { "match": { "title": "spring boot" } },
  "aggs":  { "by_title": { "terms": { "field": "title.keyword" } } },
  "sort":  [ { "title.keyword": "asc" } ]
}

Aggregate and sort on the keyword side, match on the text side, and never enable fielddata.

Mapping and the dynamic mapping trap match, term and match_phrase

This is a reading copy. The full lesson — with the visual explainer, the interactive lab and a Run button for the code — lives in the Elasticsearch Course course, and every lesson in it is listed on the Elasticsearch Course contents page.