Elasticsearch Elasticsearch Mapping API: A Comprehensive Guide

By Opster Team

Updated: Jul 23, 2023

| 3 min read

Introduction

The Elasticsearch Mapping API plays a crucial role in defining how documents and their fields are stored and indexed. It allows you to configure the data types, analyzer settings, and other mapping-specific parameters to optimize search performance and relevancy. In this article, we will delve into the Mapping API, its usage, and best practices for managing mappings in Elasticsearch.

Understanding Mappings

Mappings are the schema definitions for Elasticsearch indices, which determine how the data is indexed and stored. They define the data types for fields, such as text, keyword, date, and numeric types, as well as which index-time and search-time analyzers and tokenizers are used for text fields. Mappings also support dynamic templates, which allow you to define rules for field names and types that are automatically applied when new fields are encountered.

Creating and Updating Mappings

To create a new index with a specific mapping, you can use the Create Index API with the “mappings” parameter. Here’s an example of creating an index with a custom mapping:

PUT /my_index
{
  "mappings": {
    "properties": {
      "title": {
        "type": "text",
        "analyzer": "english"
      },
      "publish_date": {
        "type": "date",
        "format": "strict_date_optional_time||epoch_millis"
      },
      "rating": {
        "type": "float"
      }
    }
  }
}

In this example, we define a “title” field with the “text” data type and the “english” analyzer, a “publish_date” field with the “date” data type and a custom date format, and a “rating” field with the “float” data type.

To update the mapping of an existing index, you can use the Put Mapping API. Note that you can only add new fields or update certain properties of existing fields, such as adding a new analyzer or changing the “ignore_above” parameter for keyword fields. You cannot change the data type of an existing field or remove fields from the mapping.

Here’s an example of updating the mapping of an existing index:

PUT /my_index/_mapping
{
  "properties": {
    "author": {
      "type": "text",
      "analyzer": "english"
    }
  }
}

In this example, we add a new “author” field with the “text” data type and the “english” analyzer to the existing mapping.

Retrieving Mappings

To retrieve the mapping of an index, you can use the Get Mapping API. Here’s an example of retrieving the mapping for the “my_index” index:

GET /my_index/_mapping

This will return the current mapping for the specified index in JSON format.

To retrieve the mapping of a specific field, you can also use the Get Mapping API. Here’s an example of retrieving the mapping for the “author” field:

GET /my_index/_mapping/field/author

This will return the current mapping for the “author” field in JSON format. It is also possible to specify multiple field names separated by commas.

Dynamic Mappings

By default, Elasticsearch automatically creates mappings for new fields that are not defined in the existing mapping. This is called dynamic mapping and can be configured using the “dynamic” parameter in the mapping definition. There are four possible values for the “dynamic” parameter:

1. “true”: Automatically create mappings for new fields (default behavior).
2. “false”: Ignore new fields and do not index them.
3. “runtime”: Add new fields to the mapping as runtime fields.
4. “strict”: Throw an exception if a document contains a new field that is not defined in the mapping.

Here’s an example of disabling dynamic mapping for an index:

PUT /my_index
{
  "mappings": {
    "dynamic": "false",
    "properties": {
      "title": {
        "type": "text",
        "analyzer": "english"
      }
    }
  }
}

In this example, only the “title” field will be indexed, and any new fields in the documents will be ignored, yet they will still be present in the _source document.

Dynamic Templates

Dynamic templates allow you to define rules for field names and types that are automatically applied when new fields are encountered. They can be useful for applying consistent settings to fields with similar names or patterns, such as applying a specific analyzer to all text fields with a “name” prefix.

Here’s an example of using dynamic templates to apply the “english” analyzer to all text fields with a “name” prefix:

PUT /my_index
{
  "mappings": {
    "dynamic_templates": [
      {
        "name_fields": {
          "match_mapping_type": "string",
          "match": "name_*",
          "mapping": {
            "type": "text",
            "analyzer": "english"
          }
        }
      }
    ],
    "properties": {
      "title": {
        "type": "text",
        "analyzer": "english"
      }
    }
  }
}

In this example, any new text field with a “name_” prefix will automatically have the “english” analyzer applied.

Conclusion

The Elasticsearch Mapping API is a powerful tool for defining and managing the schema of your indices. By understanding how to create, update, and retrieve mappings, as well as using dynamic mappings and templates, you can optimize your search performance and relevancy. Always plan your mappings carefully and consider the specific requirements of your use case to ensure the best possible search experience.