Merge pull request #12357 from rjernst/fix/12317

Update time_zone specification

docs/reference/aggregations/bucket/datehistogram-aggregation.asciidoc

@@ -50,9 +50,10 @@ See <<time-units>> for accepted abbreviations.
 By default, times are stored as UTC milliseconds since the epoch. Thus, all computation and "bucketing" / "rounding" is
 done on UTC. It is possible to provide a time zone value, which will cause all bucket
 computations to take place in the specified zone. The time returned for each bucket/entry is milliseconds since the
-epoch in UTC. The parameters is called `time_zone`. It accepts either a numeric value for the hours offset, for example:
-`"time_zone" : -2`. It also accepts a format of hours and minutes, like `"time_zone" : "-02:30"`.
-Another option is to provide a time zone accepted as one of the values listed here.
+epoch in UTC. The parameters is called `time_zone`. It accepts either a ISO 8601 UTC offset, or a timezone id.
+A UTC offset has the form of a `+` or `-`, followed by two digit hour, followed by `:`, followed by two digit minutes.
+For example, `+01:00` represents 1 hour ahead of UTC. A timezone id is the identifier for a TZ database. For example,
+Pacific time is represented as `America\Los_Angeles`.
 
 Lets take an example. For `2012-04-01T04:15:30Z` (UTC), with a `time_zone` of `"-08:00"`. For day interval, the actual time by
 applying the time zone and rounding falls under `2012-03-31`, so the returned value will be (in millis) of

docs/reference/migration/migrate_2_0.asciidoc

@@ -546,6 +546,12 @@ query to not compute scores and optionally caches the result.
 
 As a consequence the `query` filter serves no purpose anymore and is deprecated.
 
+=== Timezone for date field
+
+Specifying the `time_zone` parameter on queries or aggregations of `date` type fields
+must now be either an ISO 8601 UTC offset, or a timezone id. For example, the value
+`+1:00` must now be `+01:00`.
+
 === Snapshot and Restore
 
 Locations of the shared file system repositories and the URL repositories with `file:` URLs has to be now registered

docs/reference/query-dsl/range-query.asciidoc

@@ -43,7 +43,7 @@ move them to UTC time based date:
         "born" : {
             "gte": "2012-01-01",
             "lte": "now",
-            "time_zone": "+1:00"
+            "time_zone": "+01:00"
         }
     }
 }