Explicit mapping

edit

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.

Create an index with an explicit mapping

edit

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"  }     
    }
  }
}

Creates age, an integer field

Creates email, a keyword field

Creates name, a text field

Add a field to an existing mapping

edit

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
    }
  }
}

Update the mapping of a field

edit

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.

View the mapping of an index

edit

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"
        }
      }
    }
  }
}

View the mapping of specific fields

edit

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
          }
        }
      }
    }
  }
}