Explicit mapping

You know more about your data than Elasticsearch can guess, so while dynamic mapping can be useful to get started, at some point you will want to specify your own explicit mappings.

You can create field mappings when you create an index and add fields to an existing index.

You can use the create index API to create a new index with an explicit mapping.

response = client.indices.create(
  index: 'my-index-000001',
  body: {
    mappings: {
      properties: {
        age: {
          type: 'integer'
        },
        email: {
          type: 'keyword'
        },
        name: {
          type: 'text'
        }
      }
    }
  }
)
puts response

res, err := es.Indices.Create(
	"my-index-000001",
	es.Indices.Create.WithBody(strings.NewReader(`{
	  "mappings": {
	    "properties": {
	      "age": {
	        "type": "integer"
	      },
	      "email": {
	        "type": "keyword"
	      },
	      "name": {
	        "type": "text"
	      }
	    }
	  }
	}`)),
)
fmt.Println(res, err)

PUT /my-index-000001
{
  "mappings": {
    "properties": {
      "age":    { "type": "integer" },  
      "email":  { "type": "keyword"  }, 
      "name":   { "type": "text"  }     
    }
  }
}

You can use the update mapping API to add one or more new fields to an existing index.

The following example adds employee-id, a keyword field with an index mapping parameter value of false. This means values for the employee-id field are stored but not indexed or available for search.

response = client.indices.put_mapping(
  index: 'my-index-000001',
  body: {
    properties: {
      "employee-id": {
        type: 'keyword',
        index: false
      }
    }
  }
)
puts response

res, err := es.Indices.PutMapping(
	[]string{"my-index-000001"},
	strings.NewReader(`{
	  "properties": {
	    "employee-id": {
	      "type": "keyword",
	      "index": false
	    }
	  }
	}`),
)
fmt.Println(res, err)

PUT /my-index-000001/_mapping
{
  "properties": {
    "employee-id": {
      "type": "keyword",
      "index": false
    }
  }
}

Except for supported mapping parameters, you can’t change the mapping or field type of an existing field. Changing an existing field could invalidate data that’s already indexed.

If you need to change the mapping of a field in a data stream’s backing indices, see Change mappings and settings for a data stream.

If you need to change the mapping of a field in other indices, create a new index with the correct mapping and reindex your data into that index.

Renaming a field would invalidate data already indexed under the old field name. Instead, add an alias field to create an alternate field name.

You can use the get mapping API to view the mapping of an existing index.

response = client.indices.get_mapping(
  index: 'my-index-000001'
)
puts response

res, err := es.Indices.GetMapping(es.Indices.GetMapping.WithIndex("my-index-000001"))
fmt.Println(res, err)

GET /my-index-000001/_mapping

The API returns the following response:

{
  "my-index-000001" : {
    "mappings" : {
      "properties" : {
        "age" : {
          "type" : "integer"
        },
        "email" : {
          "type" : "keyword"
        },
        "employee-id" : {
          "type" : "keyword",
          "index" : false
        },
        "name" : {
          "type" : "text"
        }
      }
    }
  }
}

If you only want to view the mapping of one or more specific fields, you can use the get field mapping API.

This is useful if you don’t need the complete mapping of an index or your index contains a large number of fields.

The following request retrieves the mapping for the employee-id field.

response = client.indices.get_field_mapping(
  index: 'my-index-000001',
  fields: 'employee-id'
)
puts response

res, err := es.Indices.GetMapping(es.Indices.GetMapping.WithIndex("my-index-000001"))
fmt.Println(res, err)

GET /my-index-000001/_mapping/field/employee-id

The API returns the following response:

{
  "my-index-000001" : {
    "mappings" : {
      "employee-id" : {
        "full_name" : "employee-id",
        "mapping" : {
          "employee-id" : {
            "type" : "keyword",
            "index" : false
          }
        }
      }
    }
  }
}