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.

« position_increment_gap search_analyzer »

› › ›

properties

edit

`properties`

edit

Type mappings, object fields and nested fields contain sub-fields, called properties. These properties may be of any data type, including object and nested. Properties can be added:

explicitly by defining them when creating an index.
explicitly by defining them when adding or updating a mapping type with the update mapping API.
dynamically just by indexing documents containing new fields.

Below is an example of adding properties to a mapping type, an object field, and a nested field:

resp = client.indices.create(
    index="my-index-000001",
    mappings={
        "properties": {
            "manager": {
                "properties": {
                    "age": {
                        "type": "integer"
                    },
                    "name": {
                        "type": "text"
                    }
                }
            },
            "employees": {
                "type": "nested",
                "properties": {
                    "age": {
                        "type": "integer"
                    },
                    "name": {
                        "type": "text"
                    }
                }
            }
        }
    },
)
print(resp)

resp1 = client.index(
    index="my-index-000001",
    id="1",
    document={
        "region": "US",
        "manager": {
            "name": "Alice White",
            "age": 30
        },
        "employees": [
            {
                "name": "John Smith",
                "age": 34
            },
            {
                "name": "Peter Brown",
                "age": 26
            }
        ]
    },
)
print(resp1)

response = client.indices.create(
  index: 'my-index-000001',
  body: {
    mappings: {
      properties: {
        manager: {
          properties: {
            age: {
              type: 'integer'
            },
            name: {
              type: 'text'
            }
          }
        },
        employees: {
          type: 'nested',
          properties: {
            age: {
              type: 'integer'
            },
            name: {
              type: 'text'
            }
          }
        }
      }
    }
  }
)
puts response

response = client.index(
  index: 'my-index-000001',
  id: 1,
  body: {
    region: 'US',
    manager: {
      name: 'Alice White',
      age: 30
    },
    employees: [
      {
        name: 'John Smith',
        age: 34
      },
      {
        name: 'Peter Brown',
        age: 26
      }
    ]
  }
)
puts response

const response = await client.indices.create({
  index: "my-index-000001",
  mappings: {
    properties: {
      manager: {
        properties: {
          age: {
            type: "integer",
          },
          name: {
            type: "text",
          },
        },
      },
      employees: {
        type: "nested",
        properties: {
          age: {
            type: "integer",
          },
          name: {
            type: "text",
          },
        },
      },
    },
  },
});
console.log(response);

const response1 = await client.index({
  index: "my-index-000001",
  id: 1,
  document: {
    region: "US",
    manager: {
      name: "Alice White",
      age: 30,
    },
    employees: [
      {
        name: "John Smith",
        age: 34,
      },
      {
        name: "Peter Brown",
        age: 26,
      },
    ],
  },
});
console.log(response1);

PUT my-index-000001
{
  "mappings": {
    "properties": { 
      "manager": {
        "properties": { 
          "age":  { "type": "integer" },
          "name": { "type": "text"  }
        }
      },
      "employees": {
        "type": "nested",
        "properties": { 
          "age":  { "type": "integer" },
          "name": { "type": "text"  }
        }
      }
    }
  }
}

PUT my-index-000001/_doc/1 
{
  "region": "US",
  "manager": {
    "name": "Alice White",
    "age": 30
  },
  "employees": [
    {
      "name": "John Smith",
      "age": 34
    },
    {
      "name": "Peter Brown",
      "age": 26
    }
  ]
}

	Properties in the top-level mappings definition.
	Properties under the `manager` object field.
	Properties under the `employees` nested field.
	An example document which corresponds to the above mapping.

The properties setting is allowed to have different settings for fields of the same name in the same index. New properties can be added to existing fields using the update mapping API.

Dot notation

edit

Inner fields can be referred to in queries, aggregations, etc., using dot notation:

resp = client.search(
    index="my-index-000001",
    query={
        "match": {
            "manager.name": "Alice White"
        }
    },
    aggs={
        "Employees": {
            "nested": {
                "path": "employees"
            },
            "aggs": {
                "Employee Ages": {
                    "histogram": {
                        "field": "employees.age",
                        "interval": 5
                    }
                }
            }
        }
    },
)
print(resp)

response = client.search(
  index: 'my-index-000001',
  body: {
    query: {
      match: {
        'manager.name' => 'Alice White'
      }
    },
    aggregations: {
      "Employees": {
        nested: {
          path: 'employees'
        },
        aggregations: {
          "Employee Ages": {
            histogram: {
              field: 'employees.age',
              interval: 5
            }
          }
        }
      }
    }
  }
)
puts response

const response = await client.search({
  index: "my-index-000001",
  query: {
    match: {
      "manager.name": "Alice White",
    },
  },
  aggs: {
    Employees: {
      nested: {
        path: "employees",
      },
      aggs: {
        "Employee Ages": {
          histogram: {
            field: "employees.age",
            interval: 5,
          },
        },
      },
    },
  },
});
console.log(response);

GET my-index-000001/_search
{
  "query": {
    "match": {
      "manager.name": "Alice White"
    }
  },
  "aggs": {
    "Employees": {
      "nested": {
        "path": "employees"
      },
      "aggs": {
        "Employee Ages": {
          "histogram": {
            "field": "employees.age",
            "interval": 5
          }
        }
      }
    }
  }
}

The full path to the inner field must be specified.

« position_increment_gap search_analyzer »