elasticsearch/docs/java-api/aggregations/bucket/datehistogram-aggregation.asciidoc

[[java-aggs-bucket-datehistogram]]
==== Date Histogram Aggregation

Here is how you can use
{ref}/search-aggregations-bucket-datehistogram-aggregation.html[Date Histogram Aggregation]
with Java API.


===== Prepare aggregation request

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

[source,java]
--------------------------------------------------
AggregationBuilder aggregation =
        AggregationBuilders
                .dateHistogram("agg")
                .field("dateOfBirth")
                .dateHistogramInterval(DateHistogramInterval.YEAR);
--------------------------------------------------

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

[source,java]
--------------------------------------------------
AggregationBuilder aggregation =
        AggregationBuilders
                .dateHistogram("agg")
                .field("dateOfBirth")
                .dateHistogramInterval(DateHistogramInterval.days(10));
--------------------------------------------------


===== Use aggregation response

Import Aggregation definition classes:

[source,java]
--------------------------------------------------
import org.elasticsearch.search.aggregations.bucket.histogram.Histogram;
--------------------------------------------------

[source,java]
--------------------------------------------------
// 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:

[source,text]
--------------------------------------------------
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

Supports the same order functionality as the <<java-aggs-bucket-terms,`Terms Aggregation`>>.