[[mapping-nested-type]]
=== Nested Type

The `nested` type works like the <<mapping-object-type,`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:

[source,js]
--------------------------------------------------
{
    "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:

[source,js]
--------------------------------------------------
{
    "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:

[source,js]
--------------------------------------------------
{ <1>
    "user.first" : "alice",
    "user.last" :  "white"
}
{ <1>
    "user.first" : "john",
    "user.last" :  "smith"
}
{ <2>
    "group" :       "fans"
}
--------------------------------------------------
<1> Hidden nested documents.
<2> 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
<<query-dsl-nested-query,nested query>> or
<<query-dsl-nested-filter,nested filter>>.

==== Mapping

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

[source,js]
--------------------------------------------------
{
    "type1" : {
        "properties" : {
            "users" : {
                "type" : "nested",
                "properties": {
                    "first" : {"type": "string" },
                    "last"  : {"type": "string" }
                }
            }
        }
    }
}
--------------------------------------------------

NOTE: 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`:

[source,js]
--------------------------------------------------
{
    "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:

[source,js]
--------------------------------------------------
{ <1>
    "user.first" : "alice",
    "user.last" :  "white"
}
{ <1>
    "user.first" : "john",
    "user.last" :  "smith"
}
{ <2>
    "group" :        "fans",
    "user.first" : [ "alice", "john" ],
    "user.last" :  [ "smith", "white" ]
}
--------------------------------------------------
<1> Hidden nested documents.
<2> 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.

NOTE: The `include_in_parent` and `include_in_root` options do not apply
to <<mapping-geo-shape-type,`geo_shape` fields>>, which are only ever
indexed inside the nested 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.
*********************************************
