You're viewing version 2.7 of the OpenSearch documentation. This version is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.

Mappings and field types

You can define how documents and their fields are stored and indexed by creating a mapping. The mapping specifies the list of fields for a document. Every field in the document has a field type, which corresponds to the type of data the field contains. For example, you may want to specify that the year field should be of type date. To learn more, see Supported field types.

If you’re just starting to build out your cluster and data, you may not know exactly how your data should be stored. In those cases, you can use dynamic mappings, which tell OpenSearch to dynamically add data and its fields. However, if you know exactly what types your data falls under and want to enforce that standard, then you can use explicit mappings.

For example, if you want to indicate that year should be of type text instead of an integer, and age should be an integer, you can do so with explicit mappings. By using dynamic mapping, OpenSearch might interpret both year and age as integers.

This section provides an example for how to create an index mapping and how to add a document to it that will get ip_range validated.

Table of contents

1. Dynamic mapping
2. Explicit mapping
   1. Response
3. Mapping example usage
   1. Create an index with an ip mapping
4. Get a mapping

Dynamic mapping

When you index a document, OpenSearch adds fields automatically with dynamic mapping. You can also explicitly add fields to an index mapping.

Dynamic mapping types

Explicit mapping

If you know exactly what your field data types need to be, you can specify them in your request body when creating your index.

PUT sample-index1
{
  "mappings": {
    "properties": {
      "year":    { "type" : "text" },
      "age":     { "type" : "integer" },
      "director":{ "type" : "text" }
    }
  }
}

Response

{
    "acknowledged": true,
    "shards_acknowledged": true,
    "index": "sample-index1"
}

To add mappings to an existing index or data stream, you can send a request to the _mapping endpoint using the PUT or POST HTTP method:

POST sample-index1/_mapping
{
  "properties": {
    "year":    { "type" : "text" },
    "age":     { "type" : "integer" },
    "director":{ "type" : "text" }
  }
}

You cannot change the mapping of an existing field, you can only modify the field’s mapping parameters.

Mapping example usage

The following example shows how to create a mapping to specify that OpenSearch should ignore any documents with malformed IP addresses that do not conform to the ip data type. You accomplish this by setting the ignore_malformed parameter to true.

Create an index with an ip mapping

To create an index, use a PUT request:

PUT /test-index 
{
  "mappings" : {
    "properties" :  {
      "ip_address" : {
        "type" : "ip",
        "ignore_malformed": true
      }
    }
  }
}

You can add a document that has a malformed IP address to your index:

PUT /test-index/_doc/1 
{
  "ip_address" : "malformed ip address"
}

This indexed IP address does not throw an error because ignore_malformed is set to true.

You can query the index using the following request:

GET /test-index/_search

The response shows that the ip_address field is ignored in the indexed document:

{
  "took": 14,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 1,
    "hits": [
      {
        "_index": "test-index",
        "_id": "1",
        "_score": 1,
        "_ignored": [
          "ip_address"
        ],
        "_source": {
          "ip_address": "malformed ip address"
        }
      }
    ]
  }
}

Get a mapping

To get all mappings for one or more indexes, use the following request:

GET <index>/_mapping

In the above request, <index> may be an index name or a comma-separated list of index names.

To get all mappings for all indexes, use the following request:

GET _mapping

To get a mapping for a specific field, provide the index name and the field name:

GET _mapping/field/<fields>
GET /<index>/_mapping/field/<fields>

Both <index> and <fields> can be specified as one value or a comma-separated list.

For example, the following request retrieves the mapping for the year and age fields in sample-index1:

GET sample-index1/_mapping/field/year,age

The response contains the specified fields:

{
  "sample-index1" : {
    "mappings" : {
      "year" : {
        "full_name" : "year",
        "mapping" : {
          "year" : {
            "type" : "text"
          }
        }
      },
      "age" : {
        "full_name" : "age",
        "mapping" : {
          "age" : {
            "type" : "integer"
          }
        }
      }
    }
  }
}