Search Response

Search responses are returned as a JSON map, with several main (or important) keys: hits, facets, and aggregations. There are some other values returned, mostly of minor importance (of course, until you need to use that data).


Hits is, generally, the most important part of the response. This is another JSON map, with 2 very important keys: total and hits. Total is the count of the documents that match the supplied query (the total count, not just the count of items returned). HIts (as in, the value of the key hits -> hits) is a JSON array of mappings.

These mappings are the actual search results, with some metadata and the actual (or only the requested) data of a specific result. The data of this result is contained within the key “_source”. This mapping also contains other keys: highlight, index, type, and id. Index, type, and id are the detailed information about this record at the storage level. Highlight is, itself, another JSON map of fields and the snippets of their values that contain a relevant “hit” for the query.


Facets is a JSON map containing facet names as the key. Each facet name has a corresponding JSON map containing the facet data. This data is highly specific to the facet operation performed.

For example, when dealing with a terms facet (arguably, the most used facet), the values of the facet are a JSON array within the key “terms”. Each element of this array, is also a mapping with the keys of “term” and “count”.


Aggregations are similar to facets, with one important distinction: they may contain sub-aggregations. For example, you may be aggregating a revenue field by country and state. The result aggregation response would contain several maps -- one for country which contains another map for states that itself is a map containing the aggregated statistics.