IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Metrics aggregations Query DSL »
Elastic Docs ›Java API [7.0] ›Aggregations

Bucket aggregations

edit

Bucket aggregations

edit

Global Aggregation

edit

Here is how you can use Global Aggregation with Java API.

Prepare aggregation request

edit

Here is an example on how to create the aggregation request:

AggregationBuilders
    .global("agg")
    .subAggregation(AggregationBuilders.terms("genders").field("gender"));

Use aggregation response

edit

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.bucket.global.Global;
// sr is here your SearchResponse object
Global agg = sr.getAggregations().get("agg");
agg.getDocCount(); // Doc count

Filter Aggregation

edit

Here is how you can use Filter Aggregation with Java API.

Prepare aggregation request

edit

Here is an example on how to create the aggregation request:

AggregationBuilders
    .filter("agg", QueryBuilders.termQuery("gender", "male"));

Use aggregation response

edit

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.bucket.filter.Filter;
// sr is here your SearchResponse object
Filter agg = sr.getAggregations().get("agg");
agg.getDocCount(); // Doc count

Filters Aggregation

edit

Here is how you can use Filters Aggregation with Java API.

Prepare aggregation request

edit

Here is an example on how to create the aggregation request:

AggregationBuilder aggregation =
    AggregationBuilders
        .filters("agg",
            new FiltersAggregator.KeyedFilter("men", QueryBuilders.termQuery("gender", "male")),
            new FiltersAggregator.KeyedFilter("women", QueryBuilders.termQuery("gender", "female")));

Use aggregation response

edit

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.bucket.filters.Filters;
// sr is here your SearchResponse object
Filters agg = sr.getAggregations().get("agg");

// For each entry
for (Filters.Bucket entry : agg.getBuckets()) {
    String key = entry.getKeyAsString();            // bucket key
    long docCount = entry.getDocCount();            // Doc count
    logger.info("key [{}], doc_count [{}]", key, docCount);
}

This will basically produce:

key [men], doc_count [4982]
key [women], doc_count [5018]

Missing Aggregation

edit

Here is how you can use Missing Aggregation with Java API.

Prepare aggregation request

edit

Here is an example on how to create the aggregation request:

AggregationBuilders.missing("agg").field("gender");

Use aggregation response

edit

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.bucket.missing.Missing;
// sr is here your SearchResponse object
Missing agg = sr.getAggregations().get("agg");
agg.getDocCount(); // Doc count

Nested Aggregation

edit

Here is how you can use Nested Aggregation with Java API.

Prepare aggregation request

edit

Here is an example on how to create the aggregation request:

AggregationBuilders
    .nested("agg", "resellers");

Use aggregation response

edit

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.bucket.nested.Nested;
// sr is here your SearchResponse object
Nested agg = sr.getAggregations().get("agg");
agg.getDocCount(); // Doc count

Reverse Nested Aggregation

edit

Here is how you can use Reverse Nested Aggregation with Java API.

Prepare aggregation request

edit

Here is an example on how to create the aggregation request:

AggregationBuilder aggregation =
    AggregationBuilders
        .nested("agg", "resellers")
        .subAggregation(
                AggregationBuilders
                        .terms("name").field("resellers.name")
                        .subAggregation(
                                AggregationBuilders
                                        .reverseNested("reseller_to_product")
                        )
        );

Use aggregation response

edit

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.bucket.nested.Nested;
import org.elasticsearch.search.aggregations.bucket.nested.ReverseNested;
import org.elasticsearch.search.aggregations.bucket.terms.Terms;
// sr is here your SearchResponse object
Nested agg = sr.getAggregations().get("agg");
Terms name = agg.getAggregations().get("name");
for (Terms.Bucket bucket : name.getBuckets()) {
    ReverseNested resellerToProduct = bucket.getAggregations().get("reseller_to_product");
    resellerToProduct.getDocCount(); // Doc count
}

Children Aggregation

edit

Here is how you can use Children Aggregation with Java API.

Prepare aggregation request

edit

Here is an example on how to create the aggregation request:

AggregationBuilder aggregation =
    AggregationBuilders
        .children("agg", "reseller");
  1. "agg" is the name of the aggregation and "reseller" is the child type

Use aggregation response

edit

Import Aggregation definition classes:

import org.elasticsearch.join.aggregations.Children;
// sr is here your SearchResponse object
Children agg = sr.getAggregations().get("agg");
agg.getDocCount(); // Doc count

Terms Aggregation

edit

Here is how you can use Terms Aggregation with Java API.

Prepare aggregation request

edit

Here is an example on how to create the aggregation request:

AggregationBuilders
    .terms("genders")
    .field("gender");

Use aggregation response

edit

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.bucket.terms.Terms;
// sr is here your SearchResponse object
Terms genders = sr.getAggregations().get("genders");

// For each entry
for (Terms.Bucket entry : genders.getBuckets()) {
    entry.getKey();      // Term
    entry.getDocCount(); // Doc count
}

Order

edit

Import bucket ordering strategy classes:

import org.elasticsearch.search.aggregations.BucketOrder;

Ordering the buckets by their doc_count in an ascending manner:

AggregationBuilders
    .terms("genders")
    .field("gender")
    .order(BucketOrder.count(true))

Ordering the buckets alphabetically by their terms in an ascending manner:

AggregationBuilders
    .terms("genders")
    .field("gender")
    .order(BucketOrder.key(true))

Ordering the buckets by single value metrics sub-aggregation (identified by the aggregation name):

AggregationBuilders
    .terms("genders")
    .field("gender")
    .order(BucketOrder.aggregation("avg_height", false))
    .subAggregation(
        AggregationBuilders.avg("avg_height").field("height")
    )

Ordering the buckets by multiple criteria:

AggregationBuilders
    .terms("genders")
    .field("gender")
    .order(BucketOrder.compound( // in order of priority:
        BucketOrder.aggregation("avg_height", false), // sort by sub-aggregation first
        BucketOrder.count(true))) // then bucket count as a tie-breaker
    .subAggregation(
        AggregationBuilders.avg("avg_height").field("height")
    )

Significant Terms Aggregation

edit

Here is how you can use Significant Terms Aggregation with Java API.

Prepare aggregation request

edit

Here is an example on how to create the aggregation request:

AggregationBuilder aggregation =
        AggregationBuilders
                .significantTerms("significant_countries")
                .field("address.country");

// Let say you search for men only
SearchResponse sr = client.prepareSearch()
        .setQuery(QueryBuilders.termQuery("gender", "male"))
        .addAggregation(aggregation)
        .get();

Use aggregation response

edit

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.bucket.significant.SignificantTerms;
// sr is here your SearchResponse object
SignificantTerms agg = sr.getAggregations().get("significant_countries");

// For each entry
for (SignificantTerms.Bucket entry : agg.getBuckets()) {
    entry.getKey();      // Term
    entry.getDocCount(); // Doc count
}

Range Aggregation

edit

Here is how you can use Range Aggregation with Java API.

Prepare aggregation request

edit

Here is an example on how to create the aggregation request:

AggregationBuilder aggregation =
        AggregationBuilders
                .range("agg")
                .field("height")
                .addUnboundedTo(1.0f)               // from -infinity to 1.0 (excluded)
                .addRange(1.0f, 1.5f)               // from 1.0 to 1.5 (excluded)
                .addUnboundedFrom(1.5f);            // from 1.5 to +infinity

Use aggregation response

edit

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.bucket.range.Range;
// sr is here your SearchResponse object
Range agg = sr.getAggregations().get("agg");

// For each entry
for (Range.Bucket entry : agg.getBuckets()) {
    String key = entry.getKeyAsString();             // Range as key
    Number from = (Number) entry.getFrom();          // Bucket from
    Number to = (Number) entry.getTo();              // Bucket to
    long docCount = entry.getDocCount();    // Doc count

    logger.info("key [{}], from [{}], to [{}], doc_count [{}]", key, from, to, docCount);
}

This will basically produce for the first example:

key [*-1.0], from [-Infinity], to [1.0], doc_count [9]
key [1.0-1.5], from [1.0], to [1.5], doc_count [21]
key [1.5-*], from [1.5], to [Infinity], doc_count [20]

Date Range Aggregation

edit

Here is how you can use Date Range Aggregation with Java API.

Prepare aggregation request

edit

Here is an example on how to create the aggregation request:

AggregationBuilder aggregation =
        AggregationBuilders
                .dateRange("agg")
                .field("dateOfBirth")
                .format("yyyy")
                .addUnboundedTo("1950")    // from -infinity to 1950 (excluded)
                .addRange("1950", "1960")  // from 1950 to 1960 (excluded)
                .addUnboundedFrom("1960"); // from 1960 to +infinity

Use aggregation response

edit

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.bucket.range.Range;
// sr is here your SearchResponse object
Range agg = sr.getAggregations().get("agg");

// For each entry
for (Range.Bucket entry : agg.getBuckets()) {
    String key = entry.getKeyAsString();                // Date range as key
    DateTime fromAsDate = (DateTime) entry.getFrom();   // Date bucket from as a Date
    DateTime toAsDate = (DateTime) entry.getTo();       // Date bucket to as a Date
    long docCount = entry.getDocCount();                // Doc count

    logger.info("key [{}], from [{}], to [{}], doc_count [{}]", key, fromAsDate, toAsDate, docCount);
}

This will basically produce:

key [*-1950], from [null], to [1950-01-01T00:00:00.000Z], doc_count [8]
key [1950-1960], from [1950-01-01T00:00:00.000Z], to [1960-01-01T00:00:00.000Z], doc_count [5]
key [1960-*], from [1960-01-01T00:00:00.000Z], to [null], doc_count [37]

Ip Range Aggregation

edit

Here is how you can use Ip Range Aggregation with Java API.

Prepare aggregation request

edit

Here is an example on how to create the aggregation request:

AggregationBuilder<?> aggregation =
        AggregationBuilders
                .ipRange("agg")
                .field("ip")
                .addUnboundedTo("192.168.1.0")             // from -infinity to 192.168.1.0 (excluded)
                .addRange("192.168.1.0", "192.168.2.0")    // from 192.168.1.0 to 192.168.2.0 (excluded)
                .addUnboundedFrom("192.168.2.0");          // from 192.168.2.0 to +infinity

Note that you could also use ip masks as ranges:

AggregationBuilder<?> aggregation =
        AggregationBuilders
                .ipRange("agg")
                .field("ip")
                .addMaskRange("192.168.0.0/32")
                .addMaskRange("192.168.0.0/24")
                .addMaskRange("192.168.0.0/16");

Use aggregation response

edit

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.bucket.range.Range;
// sr is here your SearchResponse object
Range agg = sr.getAggregations().get("agg");

// For each entry
for (Range.Bucket entry : agg.getBuckets()) {
    String key = entry.getKeyAsString();            // Ip range as key
    String fromAsString = entry.getFromAsString();  // Ip bucket from as a String
    String toAsString = entry.getToAsString();      // Ip bucket to as a String
    long docCount = entry.getDocCount();            // Doc count

    logger.info("key [{}], from [{}], to [{}], doc_count [{}]", key, fromAsString, toAsString, docCount);
}

This will basically produce for the first example:

key [*-192.168.1.0], from [null], to [192.168.1.0], doc_count [13]
key [192.168.1.0-192.168.2.0], from [192.168.1.0], to [192.168.2.0], doc_count [14]
key [192.168.2.0-*], from [192.168.2.0], to [null], doc_count [23]

And for the second one (using Ip masks):

key [192.168.0.0/32], from [192.168.0.0], to [192.168.0.1], doc_count [0]
key [192.168.0.0/24], from [192.168.0.0], to [192.168.1.0], doc_count [13]
key [192.168.0.0/16], from [192.168.0.0], to [192.169.0.0], doc_count [50]

Histogram Aggregation

edit

Here is how you can use Histogram Aggregation with Java API.

Prepare aggregation request

edit

Here is an example on how to create the aggregation request:

AggregationBuilder aggregation =
        AggregationBuilders
                .histogram("agg")
                .field("height")
                .interval(1);

Use aggregation response

edit

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.bucket.histogram.Histogram;
// sr is here your SearchResponse object
Histogram agg = sr.getAggregations().get("agg");

// For each entry
for (Histogram.Bucket entry : agg.getBuckets()) {
    Number key = (Number) entry.getKey();   // Key
    long docCount = entry.getDocCount();    // Doc count

    logger.info("key [{}], doc_count [{}]", key, docCount);
}

Order

edit

Supports the same order functionality as the Terms Aggregation.

Date Histogram Aggregation

edit

Here is how you can use Date Histogram Aggregation with Java API.

Prepare aggregation request

edit

Here is an example on how to create the aggregation request:

AggregationBuilder aggregation =
        AggregationBuilders
                .dateHistogram("agg")
                .field("dateOfBirth")
                .dateHistogramInterval(DateHistogramInterval.YEAR);

Or if you want to set an interval of 10 days:

AggregationBuilder aggregation =
        AggregationBuilders
                .dateHistogram("agg")
                .field("dateOfBirth")
                .dateHistogramInterval(DateHistogramInterval.days(10));

Use aggregation response

edit

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.bucket.histogram.Histogram;
// sr is here your SearchResponse object
Histogram agg = sr.getAggregations().get("agg");

// For each entry
for (Histogram.Bucket entry : agg.getBuckets()) {
    DateTime key = (DateTime) entry.getKey();    // Key
    String keyAsString = entry.getKeyAsString(); // Key as String
    long docCount = entry.getDocCount();         // Doc count

    logger.info("key [{}], date [{}], doc_count [{}]", keyAsString, key.getYear(), docCount);
}

This will basically produce for the first example:

key [1942-01-01T00:00:00.000Z], date [1942], doc_count [1]
key [1945-01-01T00:00:00.000Z], date [1945], doc_count [1]
key [1946-01-01T00:00:00.000Z], date [1946], doc_count [1]
...
key [2005-01-01T00:00:00.000Z], date [2005], doc_count [1]
key [2007-01-01T00:00:00.000Z], date [2007], doc_count [2]
key [2008-01-01T00:00:00.000Z], date [2008], doc_count [3]

Order

edit

Supports the same order functionality as the Terms Aggregation.

Geo Distance Aggregation

edit

Here is how you can use Geo Distance Aggregation with Java API.

Prepare aggregation request

edit

Here is an example on how to create the aggregation request:

AggregationBuilder aggregation =
        AggregationBuilders
                .geoDistance("agg", new GeoPoint(48.84237171118314,2.33320027692004))
                .field("address.location")
                .unit(DistanceUnit.KILOMETERS)
                .addUnboundedTo(3.0)
                .addRange(3.0, 10.0)
                .addRange(10.0, 500.0);

Use aggregation response

edit

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.bucket.range.Range;
// sr is here your SearchResponse object
Range agg = sr.getAggregations().get("agg");

// For each entry
for (Range.Bucket entry : agg.getBuckets()) {
    String key = entry.getKeyAsString();    // key as String
    Number from = (Number) entry.getFrom(); // bucket from value
    Number to = (Number) entry.getTo();     // bucket to value
    long docCount = entry.getDocCount();    // Doc count

    logger.info("key [{}], from [{}], to [{}], doc_count [{}]", key, from, to, docCount);
}

This will basically produce:

key [*-3.0], from [0.0], to [3.0], doc_count [161]
key [3.0-10.0], from [3.0], to [10.0], doc_count [460]
key [10.0-500.0], from [10.0], to [500.0], doc_count [4925]

Geo Hash Grid Aggregation

edit

Here is how you can use Geo Hash Grid Aggregation with Java API.

Prepare aggregation request

edit

Here is an example on how to create the aggregation request:

AggregationBuilder aggregation =
        AggregationBuilders
                .geohashGrid("agg")
                .field("address.location")
                .precision(4);

Use aggregation response

edit

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.bucket.geogrid.GeoHashGrid;
// sr is here your SearchResponse object
GeoHashGrid agg = sr.getAggregations().get("agg");

// For each entry
for (GeoHashGrid.Bucket entry : agg.getBuckets()) {
    String keyAsString = entry.getKeyAsString(); // key as String
    GeoPoint key = (GeoPoint) entry.getKey();    // key as geo point
    long docCount = entry.getDocCount();         // Doc count

    logger.info("key [{}], point {}, doc_count [{}]", keyAsString, key, docCount);
}

This will basically produce:

key [gbqu], point [47.197265625, -1.58203125], doc_count [1282]
key [gbvn], point [50.361328125, -4.04296875], doc_count [1248]
key [u1j0], point [50.712890625, 7.20703125], doc_count [1156]
key [u0j2], point [45.087890625, 7.55859375], doc_count [1138]
...
« Metrics aggregations Query DSL »