Date Histogram Facet

The interval allows to set the interval at which buckets will be created for each hit. It allows for the constant values of year, quarter, month, week, day, hour, minute ,second.

It also support time setting like 1.5h (up to w for weeks).

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 (both pre rounding, and post rounding) value, which will cause all computations to take the relevant zone into account. The time returned for each bucket/entry is milliseconds since the epoch of the provided time zone.

The parameters are pre_zone (pre rounding based on interval) and post_zone (post rounding based on interval). The time_zone parameter simply sets the pre_zone parameter. By default, those are set to UTC.

The zone value 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.

Lets take an example. For 2012-04-01T04:15:30Z, with a pre_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 2012-03-31T00:00:00Z (UTC). For hour interval, applying the time zone results in 2012-03-31T20:15:30, rounding it results in 2012-03-31T20:00:00, but, we want to return it in UTC (post_zone is not set), so we convert it back to UTC: 2012-04-01T04:00:00Z. Note, we are consistent in the results, returning the rounded value in UTC.

post_zone simply takes the result, and adds the relevant offset.

Sometimes, we want to apply the same conversion to UTC we did above for hour also for day (and up) intervals. We can set pre_zone_adjust_large_interval to true, which will apply the same conversion done for hour interval in the example, to day and above intervals (it can be set regardless of the interval, but only kick in when using day and higher intervals).

The date histogram works on numeric values (since time is stored in milliseconds since the epoch in UTC). But, sometimes, systems will store a different resolution (like seconds since UTC) in a numeric field. The factor parameter can be used to change the value in the field to milliseconds to actual do the relevant rounding, and then be applied again to get to the original unit. For example, when storing in a numeric field seconds resolution, the factor can be set to 1000.

Specific offsets can be provided for pre rounding and post rounding. The pre_offset for pre rounding, and post_offset for post rounding. The format is the date time format (1h, 1d, …​).

The date_histogram facet allows to use a different key (of type date) which controls the bucketing, with a different value field which will then return the total and mean for that field values of the hits within the relevant bucket. For example:

{
    "query" : {
        "match_all" : {}
    },
    "facets" : {
        "histo1" : {
            "date_histogram" : {
                "key_field" : "timestamp",
                "value_field" : "price",
                "interval" : "day"
            }
        }
    }
}

A script can be used to compute the value that will then be used to compute the total and mean for a bucket. For example:

{
    "query" : {
        "match_all" : {}
    },
    "facets" : {
        "histo1" : {
            "date_histogram" : {
                "key_field" : "timestamp",
                "value_script" : "doc['price'].value * 2",
                "interval" : "day"
            }
        }
    }
}