[[breaking_20_aggregation_changes]]
=== 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-syntax,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 <<migration-bool-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.