About this guide

This guide covers ElasticSearch aggregation feature, explains how Elastisch presents them in the API and how some of the key features are commonly used. This guide covers:

  • An overview of ElasticSearch aggregation
  • How to perform aggregation queries with Elastisch
  • How to work with responses
  • Different kinds of aggregations

This work is licensed under a Creative Commons Attribution 3.0 Unported License (including images & stylesheets). The source is available on Github.

What version of Elastisch does this guide cover?

This guide covers Elastisch 2.2.x releases, including preview releases.


Aggregate functions compute a single result from a set of documents. Naturally in ElasticSearch the input documents are retrieved using search queries. Aggregation queries (also known as "aggregations") can be used to do the following (some examples):

  • Calculate maximum/minimum/average value of a field (e.g. product price) from a set of documents
  • Calculate range and percentiles value of a field
  • Retrieve a set of terms in a field
  • Produce a histogram of numerical values

and so on.

In the API, aggregations piggyback on search queries. The documents returned by the query are aggregation inputs.

On HTTP or Native ElasticSeach Clients

Aggregations are currently only supported in the REST client.

Performing queries

Using HTTP Client

To perform a query with Elastisch, use the clojurewerkz.elastisch.rest.document/search function and pass it an aggregation map. For convenience, aggregation maps can be created using functions from clojurewerkz.elastisch.aggregation (similar to clojurewerkz.elastisch.query):

(ns clojurewerkz.elastisch.docs.examples
  (:require [clojurewerkz.elastisch.rest          :as esr]
            [clojurewerkz.elastisch.rest.document :as esd]
            [clojurewerkz.elastisch.query         :as q]
            [clojurewerkz.elastisch.aggregation   :as a]
            [clojurewerkz.elastisch.rest.response :as esrsp]
            [clojure.pprint :as pp]))

(defn -main
  [& args]
  ;; performs a term query using a convenience function
  (let [conn (esr/connect "")
        res  (esd/search conn "myapp_development" "person" {:query (q/term :biography "New York")
                                                       :aggregations {:avg_age (a/avg "age")})]
    (println (esrsp/aggregation-from res))))

Checking results

Using HTTP Client

Results returned by search functions have the same structure as ElasticSearch JSON responses.

clojurewerkz.elastisch.rest.response/aggregations-from is a convenience functions for accessing aggregation response:

(require '[clojurewerkz.elastisch.rest.document :as esd])
(require '[clojurewerkz.elastisch.query         :as q])
(require '[clojurewerkz.elastisch.aggregation   :as a])
(require '[clojurewerkz.elastisch.rest.response :as esrsp])

(let [res (esd/search conn "myapp_development" "person" {:query (q/term :biography "New York")
                                                    :aggregations {:avg_age (a/avg "age")})]
  (esrsp/aggregation-from res))

Wrapping Up

ElasticSearch supports multiple aggregation functions that piggyback on top of search queries.

Elastisch follows ElasticSearch REST API structure (for example, the query DSL) and is strives to be as feature complete as possible when it comes to querying.

The documentation is organized as a number of guides, covering different topics in depth:

Tell Us What You Think!

Please take a moment to tell us what you think about this guide on Twitter or the Elastisch mailing list

Let us know what was unclear or what has not been covered. Maybe you do not like the guide style or grammar or discover spelling mistakes. Reader feedback is key to making the documentation better.