subobjects

When indexing a document or updating mappings, Elasticsearch accepts fields that contain dots in their names, which get expanded to their corresponding object structure. For instance, the field metrics.time.max is mapped as a max leaf field with a parent time object, belonging to its parent metrics object.

The described default behaviour is reasonable for most scenarios, but causes problems in certain situations where for instance a field metrics.time holds a value too, which is common when indexing metrics data. A document holding a value for both metrics.time.max and metrics.time gets rejected given that time would need to be a leaf field to hold a value as well as an object to hold the max sub-field.

The subobjects setting, which can be applied only to the top-level mapping definition and to object fields, disables the ability for an object to hold further subobjects and makes it possible to store documents where field names contain dots and share common prefixes. From the example above, if the object container metrics has subobjects set to false, it can hold values for both time and time.max directly without the need for any intermediate object, as dots in field names are preserved.

PUT my-index-000001
{
  "mappings": {
    "properties": {
      "metrics": {
        "type":  "object",
        "subobjects": false, 
        "properties": {
          "time": { "type": "long" },
          "time.min": { "type": "long" },
          "time.max": { "type": "long" }
        }
      }
    }
  }
}

PUT my-index-000001/_doc/metric_1
{
  "metrics.time" : 100, 
  "metrics.time.min" : 10,
  "metrics.time.max" : 900
}

PUT my-index-000001/_doc/metric_2
{
  "metrics" : {
    "time" : 100, 
    "time.min" : 10,
    "time.max" : 900
  }
}

GET my-index-000001/_mapping

{
  "my-index-000001" : {
    "mappings" : {
      "properties" : {
        "metrics" : {
          "subobjects" : false,
          "properties" : {
            "time" : {
              "type" : "long"
            },
            "time.min" : { 
              "type" : "long"
            },
            "time.max" : {
              "type" : "long"
            }
          }
        }
      }
    }
  }
}

The entire mapping may be configured to not support subobjects as well, in which case the document can only ever hold leaf sub-fields:

response = client.indices.create(
  index: 'my-index-000001',
  body: {
    mappings: {
      subobjects: false
    }
  }
)
puts response

response = client.index(
  index: 'my-index-000001',
  id: 'metric_1',
  body: {
    time: '100ms',
    'time.min' => '10ms',
    'time.max' => '900ms'
  }
)
puts response

PUT my-index-000001
{
  "mappings": {
    "subobjects": false 
  }
}

PUT my-index-000001/_doc/metric_1
{
  "time" : "100ms", 
  "time.min" : "10ms",
  "time.max" : "900ms"
}

The subobjects setting for existing fields and the top-level mapping definition cannot be updated.

PUT my-index-000002
{
  "mappings": {
    "properties": {
      "metrics": {
        "subobjects": false,
        "properties": {
          "time": {
            "type": "object", 
            "properties": {
              "min": { "type": "long" }, 
              "max": { "type": "long" }
            }
          }
        }
      }
    }
  }
}
GET my-index-000002/_mapping

{
  "my-index-000002" : {
    "mappings" : {
      "properties" : {
        "metrics" : {
          "subobjects" : false,
          "properties" : {
            "time.min" : { 
              "type" : "long"
            },
            "time.max" : {
              "type" : "long"
            }
          }
        }
      }
    }
  }
}