WARNING: Version 2.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.
Inner hits
editInner hits
editThe parent/child and nested features allow the return of documents that have matches in a different scope. In the parent/child case, parent documents are returned based on matches in child documents or child documents are returned based on matches in parent documents. In the nested case, documents are returned based on matches in nested inner objects.
In both cases, the actual matches in the different scopes that caused a document to be returned is hidden. In many cases, it’s very useful to know which inner nested objects (in the case of nested) or children/parent documents (in the case of parent/child) caused certain information to be returned. The inner hits feature can be used for this. This feature returns per search hit in the search response additional nested hits that caused a search hit to match in a different scope.
Inner hits can be used by defining an inner_hits definition on a nested, has_child or has_parent query and filter.
The structure looks like this:
"<query>" : {
"inner_hits" : {
<inner_hits_options>
}
}
If inner_hits is defined on a query that supports it then each search hit will contain an inner_hits json object with the following structure:
"hits": [
{
"_index": ...,
"_type": ...,
"_id": ...,
"inner_hits": {
"<inner_hits_name>": {
"hits": {
"total": ...,
"hits": [
{
"_type": ...,
"_id": ...,
...
},
...
]
}
}
},
...
},
...
]
Options
editInner hits support the following options:
|
|
The offset from where the first hit to fetch for each |
|
|
The maximum number of hits to return per |
|
|
How the inner hits should be sorted per |
|
|
The name to be used for the particular inner hit definition in the response. Useful when multiple inner hits
have been defined in a single search request. The default depends in which query the inner hit is defined.
For |
Inner hits also supports the following per document features:
Nested inner hits
editThe nested inner_hits can be used to include nested inner objects as inner hits to a search hit.
The example below assumes that there is a nested object field defined with the name comments:
{
"query" : {
"nested" : {
"path" : "comments",
"query" : {
"match" : {"comments.message" : "[actual query]"}
},
"inner_hits" : {}
}
}
}
An example of a response snippet that could be generated from the above search request:
...
"hits": {
...
"hits": [
{
"_index": "my-index",
"_type": "question",
"_id": "1",
"_source": ...,
"inner_hits": {
"comments": {
"hits": {
"total": ...,
"hits": [
{
"_type": "question",
"_id": "1",
"_nested": {
"field": "comments",
"offset": 2
},
"_source": ...
},
...
]
}
}
}
},
...
|
The name used in the inner hit definition in the search request. A custom key can be used via the |
The _nested metadata is crucial in the above example, because it defines from what inner nested object this inner hit
came from. The field defines the object array field the nested hit is from and the offset relative to its location
in the _source. Due to sorting and scoring the actual location of the hit objects in the inner_hits is usually
different than the location a nested inner object was defined.
By default the _source is returned also for the hit objects in inner_hits, but this can be changed. Either via
_source filtering feature part of the source can be returned or be disabled. If stored fields are defined on the
nested level these can also be returned via the fields feature.
An important default is that the _source returned in hits inside inner_hits is relative to the _nested metadata.
So in the above example only the comment part is returned per nested hit and not the entire source of the top level
document that contained the comment.
A bug in Elasticsearch 2.x means that if you explicitly specify fields to be returned as part of the _source for inner_hits, you need to define them using the relative path, so in the example above you must write:
"inner_hits" : {
"_source":["message"]
}
If you return field data using fielddata_fields, you need to specify the full path instead.
Hierarchical levels of nested object fields and inner hits.
editIf a mapping has multiple levels of hierarchical nested object fields each level can be accessed using Top level inner hits (see below).
Parent/child inner hits
editThe parent/child inner_hits can be used to include parent or child
The examples below assumes that there is a _parent field mapping in the comment type:
{
"query" : {
"has_child" : {
"type" : "comment",
"query" : {
"match" : {"message" : "[actual query]"}
},
"inner_hits" : {}
}
}
}
An example of a response snippet that could be generated from the above search request:
...
"hits": {
...
"hits": [
{
"_index": "my-index",
"_type": "question",
"_id": "1",
"_source": ...,
"inner_hits": {
"comment": {
"hits": {
"total": ...,
"hits": [
{
"_type": "comment",
"_id": "5",
"_source": ...
},
...
]
}
}
}
},
...
Top level inner hits
editBesides defining inner hits on query and filters, inner hits can also be defined as a top level construct alongside the
query and aggregations definition. The main reason for using the top level inner hits definition is to let the
inner hits return documents that don’t match with the main query. Also inner hits definitions can be nested via the
top level notation. Other than that, the inner hit definition inside the query should be used because that is the most
compact way for defining inner hits.
The following snippet explains the basic structure of inner hits defined at the top level of the search request body:
"inner_hits" : {
"<inner_hits_name>" : {
"<path|type>" : {
"<path-to-nested-object-field|child-or-parent-type>" : {
<inner_hits_body>
[,"inner_hits" : { [<sub_inner_hits>]+ } ]?
}
}
}
[,"<inner_hits_name_2>" : { ... } ]*
}
Inside the inner_hits definition, first the name of the inner hit is defined then whether the inner_hit
is a nested by defining path or a parent/child based definition by defining type. The next object layer contains
the name of the nested object field if the inner_hits is nested or the parent or child type if the inner_hit definition
is parent/child based.
Multiple inner hit definitions can be defined in a single request. In the <inner_hits_body> any option for features
that inner_hits support can be defined. Optionally another inner_hits definition can be defined in the <inner_hits_body>.
An example that shows the use of nested inner hits via the top level notation:
{
"query" : {
"nested" : {
"path" : "comments",
"query" : {
"match" : {"comments.message" : "[actual query]"}
}
}
},
"inner_hits" : {
"comment" : {
"path" : {
"comments" : {
"query" : {
"match" : {"comments.message" : "[different query]"}
}
}
}
}
}
}
|
The inner hit definition is nested and requires the |
|
|
The path option refers to the nested object field |
|
|
A query that runs to collect the nested inner documents for each search hit returned. If no query is defined all nested inner documents will be included belonging to a search hit. This shows that it only make sense to the top level inner hit definition if no query or a different query is specified. |
Additional options that are only available when using the top level inner hits notation:
|
|
Defines the nested scope where hits will be collected from. |
|
|
Defines the parent or child type score where hits will be collected from. |
|
|
Defines the query that will run in the defined nested, parent or child scope to collect and score hits. By default all document in the scope will be matched. |
Either path or type must be defined. The path or type defines the scope from where hits are fetched and
used as inner hits.