# Aggregations

In some cases, you aren't interested in searching documents as you are in retrieving specific information stored within each document. It is for such a purpose that Elasticsearch provides the ability to aggregate, or summarize, index data.

## Creating an Aggregation

cbElasticsearch's `SearchBuilder` provides an `aggregation()` method for simple aggregation definitions:

```js
searchBuilder.aggregation( string name, struct options )
```

## Max Aggregation

Here's an example of a [max aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-max-aggregation.html) using SearchBuilder:

```js
searchBuilder.aggregation( "last_updated", { "max": { "field": "meta.timestamp" } } )
```

This aggregation will retrieve the most recent date value stored in `meta.timestamp`.

## Terms Aggregation

Use a terms aggregation to return an array of term "buckets", one per value:

```js
searchBuilder.aggregation( "movie_genres", { "terms": { "field": "genre" } } )
```

## Working with Aggregations

To run the query and retrieve aggregations, call `searchBuilder.execute()` followed by `getAggregations()`. `getAggregations()` will return a key/value struct where the key is your provided aggregation name:

```js
var data = mySearch.aggregation( "last_updated", { "max": { "field": "meta.timestamp" } } )
                    .execute()
                    .getAggregations()[ "last_updated" ];
```

For a simple metrics aggregation, you should be able to use the `value` or `value_as_string` keys of the returned aggregation:

```js
function getLastUpdateTime(){
    var aggregation = getSearchBuilder()
                        .new( "exams" )
                        .aggregation( "last_updated", { "max": { "field": "meta.timestamp" } } )
                        .execute()
                        .getAggregations();
                
    return aggregation[ "last_updated" ][ "value_as_string" ];
}
```

In contrast, bucket aggregations return a `buckets` array which can be used as-is or mapped into a separate result entirely:

```js
function getMovieGenres(){
    var aggregations = getSearchBuilder()
                        .new( "exams" )
                        .aggregation( "genres", { "terms": { "field": "genre" } })
                        .execute()
                        .getAggregations();
                
    return aggregations[ "genres" ].buckets.map( ( term ) => term.key );
}
```

{% hint style="info" %}
For a full break down on aggregations, check out the [ElasticSearch aggregation reference](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations.html).
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://cbelasticsearch.ortusbooks.com/searching/aggregations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.