bucket() Query Function

Extends the groupBy() function for grouping by time.

This function produces a table, if a graph is a desired, please consider using timeChart() instead.

This function divides the search time interval into buckets. Each event is put into a bucket based on its timestamp.

Events are grouped by their bucket, generating the field _bucket. The value of _bucket is the corresponding bucket’s start time in milliseconds (UTC time).

The bucket() function takes all the same parameters as groupBy(). The _bucket is added to the fields grouped by.

Parameters

Name

Type

Required

Default

Description

limit

number

No

Defines

Defines the maximum number of series to produce (defaults to 50). A warning is produced if this limit is exceeded, unless the parameter is specified explicitly.

timezone

string

No

Defines the time zone for bucketing. This value overrides timeZoneOffsetMinutes which may be passed in the HTTP/JSON query API. For example, timezone=UTC or timezone=’+02:00’.

span

string

No

auto

Defines the time span for each bucket. The time span is defined as a relative time modifier like 1hour or 3 weeks. If not provided or set to auto the search time interval, and thus the number of buckets, is determined dynamically

minspan

string

No

New in version 1.33: Defines the time span for each bucket. The time span is defined as a relative time modifier such as ‘1hour’ or ‘3 weeks’. If not provided or set to ‘auto’ the search time interval, and thus the number of buckets, is determined dynamically.

buckets

number

No

Defines the number of buckets. The time span is defined by splitting the query time interval into this many buckets. 0..1500

unit

[string]

No

Each value is a unit conversion for the given column. For instance: bytes/span to Kbytes/day converts a sum of bytes into Kb/day automatically taking the time span into account. If present, this array must be either length 1 (apply to all series) or have the same length as the function parameter. Default is no conversion. The documentation has a section on this conversion.

field

string

No

Specifies which fields to group by. Note it is possible to group by multiple fields.

function

[Aggregate]

No

count(as=_count)

Specifies which aggregate functions to perform on each group. Default is to count the elements in each group.

The implied parameter is span.

Examples

Divides the search time interval into buckets. As time span is not specified, the search interval is divided into 127 buckets. Events in each bucket are counted:

humio
bucket(function=count())

Counts different http status codes over time and buckets them into time intervals of 1 minute. Notice we group by two fields: status code and the implicit field _bucket.

humio
bucket(1min, field=status_code, function=count())

Show response time percentiles over time. Calculate percentiles per minute (bucket time into 1 minute intervals):

humio
bucket(span=60sec, function=percentile(field=responsetime, percentiles=[50, 75, 99, 99.9]))