WARNING: Version 1.3 of Elasticsearch has passed its EOL date.

This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.

› › ›

Nested Type

edit

Nested Type

edit

The nested type works like the object type except that an array of objects is flattened, while an array of nested objects allows each object to be queried independently. To explain, consider this document:

{
    "group" : "fans",
    "user" : [
        {
            "first" : "John",
            "last" :  "Smith"
        },
        {
            "first" : "Alice",
            "last" :  "White"
        },
    ]
}

If the user field is of type object, this document would be indexed internally something like this:

{
    "group" :        "fans",
    "user.first" : [ "alice", "john" ],
    "user.last" :  [ "smith", "white" ]
}

The first and last fields are flattened, and the association between alice and white is lost. This document would incorrectly match a query for alice AND smith.

If the user field is of type nested, each object is indexed as a separate document, something like this:

{ 
    "user.first" : "alice",
    "user.last" :  "white"
}
{ 
    "user.first" : "john",
    "user.last" :  "smith"
}
{ 
    "group" :       "fans"
}

	Hidden nested documents.
	Visible “parent” document.

By keeping each nested object separate, the association between the user.first and user.last fields is maintained. The query for alice AND smith would not match this document.

Searching on nested docs can be done using either the nested query or nested filter.

Mapping

edit

The mapping for nested fields is the same as object fields, except that it uses type nested:

{
    "type1" : {
        "properties" : {
            "users" : {
                "type" : "nested",
                "properties": {
                    "first" : {"type": "string" },
                    "last"  : {"type": "string" }
                }
            }
        }
    }
}

changing an object type to nested type requires reindexing.

You may want to index inner objects both as nested fields and as flattened object fields, eg for highlighting. This can be achieved by setting include_in_parent to true:

{
    "type1" : {
        "properties" : {
            "users" : {
                "type" : "nested",
                "include_in_parent": true,
                "properties": {
                    "first" : {"type": "string" },
                    "last"  : {"type": "string" }
                }
            }
        }
    }
}

The result of indexing our example document would be something like this:

{ 
    "user.first" : "alice",
    "user.last" :  "white"
}
{ 
    "user.first" : "john",
    "user.last" :  "smith"
}
{ 
    "group" :        "fans",
    "user.first" : [ "alice", "john" ],
    "user.last" :  [ "smith", "white" ]
}

	Hidden nested documents.
	Visible “parent” document.

Nested fields may contain other nested fields. The include_in_parent object refers to the direct parent of the field, while the include_in_root parameter refers only to the topmost “root” object or document.

Nested docs will automatically use the root doc _all field only.

Internal Implementation

Internally, nested objects are indexed as additional documents, but, since they can be guaranteed to be indexed within the same "block", it allows for extremely fast joining with parent docs.

Those internal nested documents are automatically masked away when doing operations against the index (like searching with a match_all query), and they bubble out when using the nested query.

Because nested docs are always masked to the parent doc, the nested docs can never be accessed outside the scope of the nested query. For example stored fields can be enabled on fields inside nested objects, but there is no way of retrieving them, since stored fields are fetched outside of the nested query scope.

The _source field is always associated with the parent document and because of that field values via the source can be fetched for nested object.

« Root Object Type IP Type »