Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 43 ยท Mappings and Data Modeling

Mappings and Field Types

Understand Elasticsearch mappings: text vs keyword, numbers, dates, booleans, ip, geo_point, multi-fields, mapping explosion and how to change a type.

A mapping is the schema of an index. It says which fields exist and what type each one has, and the type decides how the field is stored and searched. A text field is analyzed into words for full-text search. A keyword field is kept whole for exact matching, sorting and grouping. A date field can be filtered by range. Picking the right type is one of the most important decisions you make, because you usually cannot change it later.

This lesson covers the common field types, multi-fields, the difference between dynamic and explicit mapping, and what to do when a mapping is wrong. The requests are read-only (the real engine does not run here), and a small JavaScript validator shows how a mapping decides what is accepted.

Creating an index with an explicit mapping

HTTP
PUT /products
{
  "mappings": {
    "properties": {
      "name":       { "type": "text" },
      "brand":      { "type": "keyword" },
      "price":      { "type": "scaled_float", "scaling_factor": 100 },
      "stock":      { "type": "integer" },
      "in_stock":   { "type": "boolean" },
      "released":   { "type": "date" },
      "last_ip":    { "type": "ip" },
      "location":   { "type": "geo_point" }
    }
  }
}

GET /products/_mapping

Fields you do not list are still accepted by default and mapped dynamically (the next lesson, Dynamic Mapping and Index Templates, covers this). For anything important, define the mapping yourself before you load data.

text versus keyword

This is the pair that confuses everyone at first.

text keyword
Analyzed? Yes: split into lowercase tokens No: stored as one exact term
Good for Full-text search on prose IDs, tags, emails, status codes, brands
Query match finds "running shoes" by either word term must match the exact whole value
Sorting and aggregations Not by default Yes (uses doc values)

If the value is a sentence a human would search by words (a title, a description), use text. If it is a label you filter, sort or count by, use keyword. Often you need both for the same value, which is what multi-fields are for.

Multi-fields

A multi-field indexes one source value in several ways:

HTTP
PUT /articles
{
  "mappings": {
    "properties": {
      "title": {
        "type": "text",
        "fields": {
          "raw": { "type": "keyword", "ignore_above": 256 }
        }
      }
    }
  }
}

Now title is searched by words, and title.raw is used to sort or aggregate on the exact title. The JSON source is stored once. ignore_above skips keyword indexing for values longer than that many characters, which protects you from huge terms.

Other common types

  • Numbers: long, integer, short, byte, double, float, half_float, scaled_float. Use the smallest type that fits. A scaled_float stores a decimal as a long multiplied by a factor, which suits prices. Note that a number used only as an identifier (a ZIP code, an order number) is often better as keyword, because you will match it exactly and never use range or math on it.
  • date: accepts ISO 8601 strings and epoch milliseconds by default (strict_date_optional_time||epoch_millis). Elasticsearch stores dates as UTC milliseconds internally. You can set a custom format.
  • boolean: true and false (and the strings "true" and "false").
  • ip: IPv4 and IPv6 addresses, searchable with CIDR notation such as "192.168.0.0/16".
  • geo_point: a latitude and longitude, used for distance filters (see the later lesson on geo queries).
  • object and nested: JSON objects. See Objects, Arrays and Nested Fields.
  • dense_vector, flattened, wildcard, search_as_you_type, completion: specialized types for embeddings, free-form objects, wildcard search and autocomplete.

There is no special "array" type: any field can hold one value or a list of values of its type.

JS A tiny mapping validator

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The second document passes because Elasticsearch coerces numeric strings such as "7" into numbers by default. The third document is rejected in a real cluster with a mapper_parsing_exception, and the document is not indexed. Coercion can be switched off per field with "coerce": false.

Text versus keyword in action

The difference shows up as soon as you query. This stand-in tokenizes like a simple analyzer (lowercase, split on non-letters) for text and keeps keyword values whole:

JS Why term on a text field often fails

Press Run (or Ctrl + Enter) to see the console output here.

No output.

A term query is not analyzed. Searching term: "Running" on an analyzed text field finds nothing, because the index holds the lowercase token running. Use match for text fields and term for keyword fields. The Query DSL basics lesson goes deeper.

Dynamic or strict

The dynamic setting in the mapping decides what happens to unknown fields: add them (true, the default), keep them in _source but do not index them (false), or reject the document (strict). Production indexes with a known shape often use strict so that a typo in a field name is an error instead of a silent new field.

Mapping explosion

Every new field name adds to the cluster state that all nodes keep in memory. If your documents use user-generated keys (for example {"attrs": {"color_red": 1, "size_xl": 2}}), the number of fields can grow without bound. This is a mapping explosion. Elasticsearch protects you with index.mapping.total_fields.limit (1000 by default), after which indexing fails. Fixes: model variable data as a list of key/value objects, use the flattened type for free-form objects, or set dynamic to false or strict.

You cannot change a field's type

An existing field's type cannot be changed in place, because the data on disk was built for the old type. You can add new fields and add some parameters (like a multi-field) to existing ones, but otherwise the way out is a reindex:

  1. Create a new index with the correct mapping.
  2. Copy the documents with the _reindex API.
  3. Switch your application to the new index (aliases make this seamless).
  4. Delete the old index.
HTTP
PUT /products_v2
{ "mappings": { "properties": { "stock": { "type": "integer" } } } }

POST /_reindex
{ "source": { "index": "products" }, "dest": { "index": "products_v2" } }

Plan for this from day one: write to an alias such as products that points to a versioned index, and the swap costs nothing.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which field type fits a product brand that you filter and group by?

    A brand is a label matched exactly and used in sorting and aggregations, which is what keyword is for.
  2. 2. What is a multi-field?

    A multi-field (the fields parameter) lets title be analyzed for search and title.raw be exact for sorting, from one source value.
  3. 3. You mapped a field as integer but it should have been keyword. What is the standard fix?

    Field types cannot be changed in place. You reindex into a new index, ideally behind an alias.
  4. 4. What is a mapping explosion?

    Each field name is kept in the cluster state, so user-generated keys can create thousands of fields. The total_fields limit (1000 by default) stops it.

Summary

  • A mapping defines field types and decides how each field is indexed and searched.
  • Use text for prose (analyzed), keyword for exact values, sorting and aggregations, and a multi-field when you need both.
  • Pick the smallest fitting numeric type; use date, boolean, ip and geo_point for their own kinds of data.
  • Prefer explicit or strict mappings in production, and watch out for mapping explosion.
  • A field's type cannot change in place: reindex into a new index, behind an alias.

Next: Dynamic Mapping and Index Templates.