[[caching-heavy-aggregations]]
== Caching heavy aggregations

Frequently used aggregations (e.g. for display on the home page of a website)
can be cached for faster responses. These cached results are the same results
that would be returned by an uncached aggregation -- you will never get stale
results.

See <<shard-request-cache>> for more details.

[[returning-only-agg-results]]
== Returning only aggregation results

There are many occasions when aggregations are required but search hits are not.  For these cases the hits can be ignored by
setting `size=0`. For example:

[source,js]
--------------------------------------------------
GET /twitter/_search
{
  "size": 0,
  "aggregations": {
    "my_agg": {
      "terms": {
        "field": "text"
      }
    }
  }
}
--------------------------------------------------
// CONSOLE
// TEST[setup:twitter]

Setting `size` to `0` avoids executing the fetch phase of the search making the request more efficient.

[[agg-metadata]]
== Aggregation Metadata

You can associate a piece of metadata with individual aggregations at request time that will be returned in place
at response time.

Consider this example where we want to associate the color blue with our `terms` aggregation.

[source,js]
--------------------------------------------------
GET /twitter/_search
{
  "size": 0,
  "aggs": {
    "titles": {
      "terms": {
        "field": "title"
      },
      "meta": {
        "color": "blue"
      }
    }
  }
}
--------------------------------------------------
// CONSOLE
// TEST[setup:twitter]

Then that piece of metadata will be returned in place for our `titles` terms aggregation

[source,js]
--------------------------------------------------
{
    "aggregations": {
        "titles": {
            "meta": {
                "color" : "blue"
            },
            "doc_count_error_upper_bound" : 0,
            "sum_other_doc_count" : 0,
            "buckets": [
            ]
        }
    },
    ...
}
--------------------------------------------------
// TESTRESPONSE[s/\.\.\./"took": "$body.took", "timed_out": false, "_shards": "$body._shards", "hits": "$body.hits"/]


[[returning-aggregation-type]]
== 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 <<search-aggregations-bucket-datehistogram-aggregation,`date_histogram` aggregation>> named
`tweets_over_time` which has a sub <<search-aggregations-metrics-top-hits-aggregation, 'top_hits` aggregation>> named
 `top_users`:

[source,js]
--------------------------------------------------
GET /twitter/_search?typed_keys
{
  "aggregations": {
    "tweets_over_time": {
      "date_histogram": {
        "field": "date",
        "calendar_interval": "year"
      },
      "aggregations": {
        "top_users": {
            "top_hits": {
                "size": 1
            }
        }
      }
    }
  }
}
--------------------------------------------------
// CONSOLE
// TEST[setup:twitter]

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

[source,js]
--------------------------------------------------
{
    "aggregations": {
        "date_histogram#tweets_over_time": { <1>
            "buckets" : [
                {
                    "key_as_string" : "2009-01-01T00:00:00.000Z",
                    "key" : 1230768000000,
                    "doc_count" : 5,
                    "top_hits#top_users" : {  <2>
                        "hits" : {
                            "total" : {
                                "value": 5,
                                "relation": "eq"
                            },
                            "max_score" : 1.0,
                            "hits" : [
                                {
                                  "_index": "twitter",
                                  "_type": "_doc",
                                  "_id": "0",
                                  "_score": 1.0,
                                  "_source": {
                                    "date": "2009-11-15T14:12:12",
                                    "message": "trying out Elasticsearch",
                                    "user": "kimchy",
                                    "likes": 0
                                  }
                                }
                            ]
                        }
                    }
                }
            ]
        }
    },
    ...
}
--------------------------------------------------
// TESTRESPONSE[s/\.\.\./"took": "$body.took", "timed_out": false, "_shards": "$body._shards", "hits": "$body.hits"/]

<1> The name `tweets_over_time` now contains the `date_histogram` prefix.
<2> The name `top_users` now contains the `top_hits` prefix.

NOTE: 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).