Returning the type of the aggregation

Sometimes you need to know the exact type of an aggregation in order to parse its results. The typed_keys parameter can be used to change the aggregation’s name in the response so that it will be prefixed by its internal type.

Considering the following date_histogram aggregation named requests_over_time which has a sub top_hits aggregation named top_users:

  1. GET /my-index-000001/_search?typed_keys
  2. {
  3.   "aggregations": {
  4.     "requests_over_time": {
  5.       "date_histogram": {
  6.         "field": "@timestamp",
  7.         "calendar_interval": "year"
  8.       },
  9.       "aggregations": {
  10.         "top_users": {
  11.             "top_hits": {
  12.                 "size": 1,
  13.                 "_source": ["user.id", "http.response.bytes", "message"]
  14.             }
  15.         }
  16.       }
  17.     }
  18.   }
  19. }

In the response, the aggregations names will be changed to respectively date_histogram#requests_over_time and top_hits#top_users, reflecting the internal types of each aggregation:

  1. {
  2.   "aggregations": {
  3.     "date_histogram#requests_over_time": {                    
  4.       "buckets": [
  5.         {
  6.           "key_as_string": "2099-01-01T00:00:00.000Z",
  7.           "key": 4070908800000,
  8.           "doc_count": 5,
  9.           "top_hits#top_users": {                             
  10.                       "hits": {
  11.               "total": {
  12.                 "value": 5,
  13.                 "relation": "eq"
  14.               },
  15.               "max_score": 1.0,
  16.               "hits": [
  17.                 {
  18.                   "_index": "my-index-000001",
  19.                   "_type": "_doc",
  20.                   "_id": "0",
  21.                   "_score": 1.0,
  22.                   "_source": {
  23.                     "user": { "id": "kimchy"},
  24.                     "message": "GET /search HTTP/1.1 200 1070000",
  25.                     "http": { "response": { "bytes": 1070000 } }
  26.                   }
  27.                 }
  28.               ]
  29.             }
  30.           }
  31.         }
  32.       ]
  33.     }
  34.   },
  35.   ...
  36. }

The name requests_over_time now contains the date_histogram prefix.

The name top_users now contains the top_hits prefix.

For some aggregations, it is possible that the returned type is not the same as the one provided with the request. This is the case for Terms, Significant Terms and Percentiles aggregations, where the returned type also contains information about the type of the targeted field: lterms (for a terms aggregation on a Long field), sigsterms (for a significant terms aggregation on a String field), tdigest_percentiles (for a percentile aggregation based on the TDigest algorithm).