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

Nested objects/documents allow to map certain sections in the document
indexed as nested allowing to query them as if they are separate docs
joining with the parent owning doc.

One of the problems when indexing inner objects that occur several times
in a doc is that "cross object" search match will occur, for example:

[source,js]
--------------------------------------------------
{
    "obj1" : [
        {
            "name" : "blue",
            "count" : 4
        },
        {
            "name" : "green",
            "count" : 6
        }
    ]
}
--------------------------------------------------

Searching for name set to blue and count higher than 5 will match the
doc, because in the first element the name matches blue, and in the
second element, count matches "higher than 5".

Nested mapping allows mapping certain inner objects (usually multi
instance ones), for example:

[source,js]
--------------------------------------------------
{
    "type1" : {
        "properties" : {
            "obj1" : {
                "type" : "nested"
            }
        }
    }
}
--------------------------------------------------

The above will cause all `obj1` to be indexed as a nested doc. The
mapping is similar in nature to setting `type` to `object`, except that
it's `nested`.

Note: changing an object type to nested type requires reindexing.

The `nested` object fields can also be automatically added to the
immediate parent by setting `include_in_parent` to true, and also
included in the root object by setting `include_in_root` to true.

Nested docs will also automatically use the root doc `_all` field.

Searching on nested docs can be done using either the
<<query-dsl-nested-query,nested query>> or
<<query-dsl-nested-filter,nested filter>>.

[float]
==== 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.
