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.

The include_in_parent and include_in_root options do not apply to geo_shape fields, which are only ever indexed inside the nested document.

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