Aggregation changes

Min doc count defaults to zero

Both the histogram and date_histogram aggregations now have a default min_doc_count of 0 instead of 1.

Timezone for date field

Specifying the time_zone parameter in queries or aggregations on fields of type date must now be either an ISO 8601 UTC offset, or a timezone id. For example, the value +1:00 must now be written as +01:00.

Time zones and offsets

The histogram and the date_histogram aggregation now support a simplified offset option that replaces the previous pre_offset and post_offset rounding options. Instead of having to specify two separate offset shifts of the underlying buckets, the offset option moves the bucket boundaries in positive or negative direction depending on its argument.

The date_histogram options for pre_zone and post_zone are replaced by the time_zone option. The behavior of time_zone is equivalent to the former pre_zone option. Setting time_zone to a value like "+01:00" now will lead to the bucket calculations being applied in the specified time zone. The key is returned as the timestamp in UTC, but the key_as_string is returned in the time zone specified.

In addition to this, the pre_zone_adjust_large_interval is removed because we now always return dates and bucket keys in UTC.

Including/excluding terms

include/exclude filtering on the terms aggregation now uses the same syntax as regexp queries instead of the Java regular expression syntax. While simple regexps should still work, more complex ones might need some rewriting. Also, the flags parameter is no longer supported.

Boolean fields

Aggregations on boolean fields will now return 0 and 1 as keys, and "true" and "false" as string keys. See Boolean fields for more information.

Java aggregation classes

The date_histogram aggregation now returns a Histogram object in the response, and the DateHistogram class has been removed. Similarly the date_range, ipv4_range, and geo_distance aggregations all return a Range object in the response, and the IPV4Range, DateRange, and GeoDistance classes have been removed.

The motivation for this is to have a single response API for the Range and Histogram aggregations regardless of the type of data being queried. To support this some changes were made in the MultiBucketAggregation interface which applies to all bucket aggregations:

  • The getKey() method now returns Object instead of String. The actual object type returned depends on the type of aggregation requested (e.g. the date_histogram will return a DateTime object for this method whereas a histogram will return a Number).
  • A getKeyAsString() method has been added to return the String representation of the key.
  • All other getKeyAsX() methods have been removed.
  • The getBucketAsKey(String) methods have been removed on all aggregations except the filters and terms aggregations.