This documentation contains work-in-progress information for future Elastic Stack and Cloud releases. Use the version selector to view supported release docs. It also contains some Elastic Cloud serverless information. Check out our serverless docs for more details.
« Numeric field types Pass-through object field type »
Elastic Docs ›Elasticsearch Guide [8.16] ›Mapping ›Field data types

Object field type

edit

Object field type

edit

JSON documents are hierarchical in nature: the document may contain inner objects which, in turn, may contain inner objects themselves:

resp = client.index(
    index="my-index-000001",
    id="1",
    document={
        "region": "US",
        "manager": {
            "age": 30,
            "name": {
                "first": "John",
                "last": "Smith"
            }
        }
    },
)
print(resp)
response = client.index(
  index: 'my-index-000001',
  id: 1,
  body: {
    region: 'US',
    manager: {
      age: 30,
      name: {
        first: 'John',
        last: 'Smith'
      }
    }
  }
)
puts response
const response = await client.index({
  index: "my-index-000001",
  id: 1,
  document: {
    region: "US",
    manager: {
      age: 30,
      name: {
        first: "John",
        last: "Smith",
      },
    },
  },
});
console.log(response);
PUT my-index-000001/_doc/1
{ 
  "region": "US",
  "manager": { 
    "age":     30,
    "name": { 
      "first": "John",
      "last":  "Smith"
    }
  }
}

The outer document is also a JSON object.

It contains an inner object called manager.

Which in turn contains an inner object called name.

Internally, this document is indexed as a simple, flat list of key-value pairs, something like this:

{
  "region":             "US",
  "manager.age":        30,
  "manager.name.first": "John",
  "manager.name.last":  "Smith"
}

An explicit mapping for the above document could look like this:

resp = client.indices.create(
    index="my-index-000001",
    mappings={
        "properties": {
            "region": {
                "type": "keyword"
            },
            "manager": {
                "properties": {
                    "age": {
                        "type": "integer"
                    },
                    "name": {
                        "properties": {
                            "first": {
                                "type": "text"
                            },
                            "last": {
                                "type": "text"
                            }
                        }
                    }
                }
            }
        }
    },
)
print(resp)
response = client.indices.create(
  index: 'my-index-000001',
  body: {
    mappings: {
      properties: {
        region: {
          type: 'keyword'
        },
        manager: {
          properties: {
            age: {
              type: 'integer'
            },
            name: {
              properties: {
                first: {
                  type: 'text'
                },
                last: {
                  type: 'text'
                }
              }
            }
          }
        }
      }
    }
  }
)
puts response
const response = await client.indices.create({
  index: "my-index-000001",
  mappings: {
    properties: {
      region: {
        type: "keyword",
      },
      manager: {
        properties: {
          age: {
            type: "integer",
          },
          name: {
            properties: {
              first: {
                type: "text",
              },
              last: {
                type: "text",
              },
            },
          },
        },
      },
    },
  },
});
console.log(response);
PUT my-index-000001
{
  "mappings": {
    "properties": { 
      "region": {
        "type": "keyword"
      },
      "manager": { 
        "properties": {
          "age":  { "type": "integer" },
          "name": { 
            "properties": {
              "first": { "type": "text" },
              "last":  { "type": "text" }
            }
          }
        }
      }
    }
  }
}

Properties in the top-level mappings definition.

The manager field is an inner object field.

The manager.name field is an inner object field within the manager field.

You are not required to set the field type to object explicitly, as this is the default value.

Parameters for object fields

edit

The following parameters are accepted by object fields:

dynamic

Whether or not new properties should be added dynamically to an existing object. Accepts true (default), runtime, false and strict.

enabled

Whether the JSON value given for the object field should be parsed and indexed (true, default) or completely ignored (false).

subobjects

Whether the object can hold subobjects (true, default) or not (false). If not, sub-fields with dots in their names will be treated as leaves instead, otherwise their field names would be expanded to their corresponding object structure.

properties

The fields within the object, which can be of any data type, including object. New properties may be added to an existing object.

If you need to index arrays of objects instead of single objects, read Nested first.

« Numeric field types Pass-through object field type »