Managing Index Mappings

1. Understanding Mapping Types

Type	Description	Usage	Notes
text	Full-text search field	`"message": {"type": "text"}`	Supports full-text search with analyzers
keyword	Exact match field	`"status": {"type": "keyword"}`	Used for filtering, aggregations, sorting
integer	Whole number field	`"count": {"type": "integer"}`	For numeric comparisons and aggregations
date	Date and time field	`"timestamp": {"type": "date"}`	Supports date formats and range queries
boolean	True/false field	`"is_active": {"type": "boolean"}`	Used in filters and queries
float	Decimal number field	`"score": {"type": "float"}`	For precise numeric values
geo_point	Geospatial point field	`"location": {"type": "geo_point"}`	Used for location-based queries
nested	Nested object field	`"tags": {"type": "nested"}`	Allows querying nested arrays

Example: Defining a Mapping with Different Types

{
  "properties": {
    "message": {
      "type": "text"
    },
    "status": {
      "type": "keyword"
    },
    "count": {
      "type": "integer"
    },
    "timestamp": {
      "type": "date"
    },
    "is_active": {
      "type": "boolean"
    },
    "score": {
      "type": "float"
    },
    "location": {
      "type": "geo_point"
    },
    "tags": {
      "type": "nested"
    }
  }
}

2. Defining Field Types

Field Type	Description	Usage Example	Notes
text	Full-text search field, analyzed for full-text search capabilities.	`"message": { "type": "text" }`	Supports fuzzy matching and phrase queries.
keyword	Exact value match field, not analyzed.	`"status": { "type": "keyword" }`	Used for filtering, aggregations, and exact matches.
integer	Whole number field (32-bit integer).	`"count": { "type": "integer" }`	Supports range queries and aggregations.
float	Decimal number field (32-bit float).	`"price": { "type": "float" }`	Supports range queries and aggregations.
date	Date field, supports various date formats.	`"timestamp": { "type": "date" }`	Can use `format` property to define custom date formats.
boolean	True or false value field.	`"is_active": { "type": "boolean" }`	Used for filtering and logical operations.
geo_point	Geographic point data (latitude, longitude).	`"location": { "type": "geo_point" }`	Supports spatial queries like distance and bounding box.
ip	IPv4 or IPv6 address field.	`"ip_address": { "type": "ip" }`	Used for network-related filtering and analysis.
nested	Array of objects, each object treated as a separate document.	`"tags": { "type": "nested" }`	Allows querying and aggregating nested objects independently.
object	Single JSON object field.	`"user": { "type": "object" }`	Used to store structured data within a document.

Example: Defining a Mapping with Various Field Types

{
  "mappings": {
    "properties": {
      "message": {
        "type": "text"
      },
      "status": {
        "type": "keyword"
      },
      "count": {
        "type": "integer"
      },
      "price": {
        "type": "float"
      },
      "timestamp": {
        "type": "date",
        "format": "yyyy-MM-dd HH:mm:ss"
      },
      "is_active": {
        "type": "boolean"
      },
      "location": {
        "type": "geo_point"
      },
      "ip_address": {
        "type": "ip"
      },
      "tags": {
        "type": "nested"
      },
      "user": {
        "type": "object"
      }
    }
  }
}

3. Creating Explicit Mappings

Field	Type	Description	Options
name	`string`	Name of the field	-
type	`string`	Data type of the field	`text`, `keyword`, `integer`, `float`, `date`, `boolean`, `geo_point`
index	`boolean`	Whether the field is searchable	`true`, `false`
analyzer	`string`	Analyzer to use for text fields	`standard`, `english`, `keyword`

Example: Defining a mapping for a log document

{
  "properties": {
    "message": {
      "type": "text",
      "analyzer": "standard"
    },
    "timestamp": {
      "type": "date"
    },
    "level": {
      "type": "keyword"
    }
  }
}

4. Viewing Index Mappings

Field	Type	Description
_id	`string`	Unique identifier for the document
_source	`object`	Original JSON document stored in the index
_index	`string`	Name of the index where the document is stored
_score	`float`	Relevance score of the document in a search query

Example: Retrieve Index Mapping

GET /my-index/_mapping

{
  "my-index" : {
    "mappings" : {
      "properties" : {
        "name" : {
          "type" : "text"
        },
        "age" : {
          "type" : "integer"
        }
      }
    }
  }
}

Example: Get Field Mapping

GET /my-index/_mapping/field/name

{
  "my-index" : {
    "mappings" : {
      "properties" : {
        "name" : {
          "full_name" : "name",
          "mapping" : {
            "type" : "text"
          }
        }
      }
    }
  }
}

5. Using Dynamic Mapping

Field	Type	Description	Default
dynamic	`boolean` or `string`	Controls whether new fields are added dynamically to the mapping. `true` allows automatic field addition, `false` prevents it, and `"strict"` throws an error for unknown fields.	`true`
dynamic_templates	`object`	Defines templates for dynamically added fields. Allows specifying field types and settings based on field names or patterns.	`{}`

Example: Enabling Dynamic Mapping

{
  "mappings": {
    "dynamic": true,
    "properties": {
      "title": {
        "type": "text"
      }
    }
  }
}

Example: Strict Dynamic Mapping

{
  "mappings": {
    "dynamic": "strict",
    "properties": {
      "title": {
        "type": "text"
      }
    }
  }
}

Note: When dynamic is set to false, new fields will be ignored and not indexed. Use "strict" to enforce strict field control.

Warning: Enabling dynamic mapping can lead to performance degradation and unexpected behavior if not managed carefully. It's recommended to define mappings explicitly in production environments.

6. Updating Mappings

Mapping Field	Description	Update Method	Notes
field.type	Changes the data type of a field	`PUT /{index}/_mapping`	Cannot change type of existing field. Must reindex.
field.analyzer	Modifies text analysis settings	`PUT /{index}/_mapping`	Can be updated without reindexing
field.index	Enables or disables field indexing	`PUT /{index}/_mapping`	Can be updated without reindexing

Example: Updating Field Analyzer

{
  "mappings": {
    "properties": {
      "description": {
        "type": "text",
        "analyzer": "standard"
      }
    }
  }
}

Note: Field type changes require reindexing the index.

Warning: Updating mappings can cause data loss if not handled carefully.

7. Setting Multi-Fields

Field Name Type Multi-Field Configuration Notes

text_field

Field Name	Type	Multi-Field Configuration	Notes
text_field	`text`	`{ "text_field": { "type": "text", "fields": { "keyword": { "type": "keyword" }, "raw": { "type": "text", "analyzer": "keyword" } } } }`	Enables both full-text search and exact match queries
title	`text`	`{ "title": { "type": "text", "fields": { "raw": { "type": "keyword" }, "edge_ngram": { "type": "text", "analyzer": "edge_ngram_analyzer" } } } }`	Supports both phrase and prefix matching

text

{
  "text_field": {
    "type": "text",
    "fields": {
      "keyword": {
        "type": "keyword"
      },
      "raw": {
        "type": "text",
        "analyzer": "keyword"
      }
    }
  }
}

Enables both full-text search and exact match queries

title

text

{
  "title": {
    "type": "text",
    "fields": {
      "raw": {
        "type": "keyword"
      },
      "edge_ngram": {
        "type": "text",
        "analyzer": "edge_ngram_analyzer"
      }
    }
  }
}

Supports both phrase and prefix matching

Example: Multi-field Mapping Configuration

{
  "mappings": {
    "properties": {
      "description": {
        "type": "text",
        "fields": {
          "keyword": {
            "type": "keyword"
          },
          "english": {
            "type": "text",
            "analyzer": "english"
          }
        }
      }
    }
  }
}

Note: Multi-fields allow you to index the same field in multiple ways, optimizing for different search requirements.

8. Using Nested Objects

Property	Description	Example
nested	Defines a field as nested, allowing arrays of objects to be indexed separately	`{ "mappings": { "properties": { "addresses": { "type": "nested" } } } }`

Example: Indexing Nested Objects

{
  "mappings": {
    "properties": {
      "user": {
        "type": "object",
        "properties": {
          "name": { "type": "text" },
          "addresses": {
            "type": "nested"
          }
        }
      }
    }
  }
}

Example: Querying Nested Objects

{
  "query": {
    "nested": {
      "path": "user.addresses",
      "query": {
        "term": {
          "user.addresses.city": "New York"
        }
      }
    }
  }
}

Note: Nested objects are stored separately in Elasticsearch and require special query handling to retrieve matching parent documents.

9. Configuring Parent-Child Relationships

Property	Description	Values	Notes
_parent	Defines the parent document's ID	`string`	Required for child documents
_routing	Ensures child documents are stored on the same shard as their parent	`string`	Improves query performance

Example: Indexing Parent-Child Documents

{
  "index": "my_index",
  "type": "parent",
  "id": "1",
  "body": {
    "title": "Parent Document"
  }
}

Example: Indexing Child Documents

{
  "index": "my_index",
  "type": "child",
  "id": "2",
  "parent": "1",
  "routing": "1",
  "body": {
    "content": "Child Document Content"
  }
}

Note: The _routing field is crucial for performance when querying parent-child relationships.

Warning: Parent documents must exist before child documents can be indexed.

10. Setting Field Properties

Property	Description	Values	Notes
type	Defines the data type of the field	`text`, `keyword`, `integer`, `date`, `boolean`, `float`, `geo_point`, `ip`, `object`, `array`	Required for all fields
analyzer	Defines the analyzer to use for text fields	`standard`, `english`, `keyword`, custom analyzer name	Applies to `text` fields only
index	Controls whether the field is indexed for searching	`true`, `false`	Defaults to `true`
doc_values	Controls whether to store field data for aggregations	`true`, `false`	Defaults to `true` for `keyword` fields
store	Controls whether the field value is stored in the document	`true`, `false`	Defaults to `false`

Example: Defining a field with properties

{
  "mappings": {
    "properties": {
      "title": {
        "type": "text",
        "analyzer": "standard",
        "index": true
      },
      "published_date": {
        "type": "date",
        "format": "yyyy-MM-dd"
      },
      "is_published": {
        "type": "boolean",
        "store": true
      }
    }
  }
}

11. Disabling Dynamic Mapping

Setting	Description	Default	Notes
dynamic	Controls whether new fields are added dynamically to the mapping	`true`	Set to `false` to disable dynamic field addition
dynamic_templates	Defines templates for dynamically added fields	`null`	Can be used to control how new fields are mapped

Example: Disabling Dynamic Mapping

{
  "settings": {
    "dynamic": false
  },
  "mappings": {
    "properties": {
      "name": {
        "type": "text"
      },
      "age": {
        "type": "integer"
      }
    }
  }
}

Note: When dynamic is set to false, new fields in documents will be ignored and not added to the index mapping.