[[explicit-mapping]]
== Explicit mapping

You know more about your data than {es} 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-mapping,create an index>> and
<<add-field-mapping,add fields to an existing index>>.

[discrete]
[[create-mapping]]
=== Create an index with an explicit mapping

You can use the <<indices-create-index,create index>> API to create a new index
with an explicit mapping.

[source,console]
----
PUT /my-index-000001
{
  "mappings": {
    "properties": {
      "age":    { "type": "integer" },  <1>
      "email":  { "type": "keyword"  }, <2>
      "name":   { "type": "text"  }     <3>
    }
  }
}
----

<1> Creates `age`, an <<number,`integer`>> field
<2> Creates `email`, a <<keyword,`keyword`>> field
<3> Creates `name`, a <<text,`text`>> field

[discrete]
[[add-field-mapping]]
=== Add a field to an existing mapping

You can use the <<indices-put-mapping, 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
<<mapping-index,`index`>> mapping parameter value of `false`. This means values
for the `employee-id` field are stored but not indexed or available for search.

[source,console]
----
PUT /my-index-000001/_mapping
{
  "properties": {
    "employee-id": {
      "type": "keyword",
      "index": false
    }
  }
}
----
// TEST[continued]

[discrete]
[[update-mapping]]
=== Update the mapping of a field

include::{es-repo-dir}/indices/put-mapping.asciidoc[tag=change-field-mapping]

include::{es-repo-dir}/indices/put-mapping.asciidoc[tag=rename-field]

[discrete]
[[view-mapping]]
=== View the mapping of an index

You can use the <<indices-get-mapping, get mapping>> API to view the mapping of
an existing index.

[source,console]
----
GET /my-index-000001/_mapping
----
// TEST[continued]

The API returns the following response:

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

[discrete]
[[view-field-mapping]]
=== View the mapping of specific fields

If you only want to view the mapping of one or more specific fields, you can use
the <<indices-get-field-mapping, 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.

[source,console]
----
GET /my-index-000001/_mapping/field/employee-id
----
// TEST[continued]

The API returns the following response:

[source,console-result]
----
{
  "my-index-000001" : {
    "mappings" : {
      "employee-id" : {
        "full_name" : "employee-id",
        "mapping" : {
          "employee-id" : {
            "type" : "keyword",
            "index" : false
          }
        }
      }
    }
  }
}

----