bin

The bin command groups numeric values into buckets of equal intervals, which is useful for creating histograms and analyzing data distribution. It accepts a numeric or time-based field and generates a new field containing values that represent the lower bound of each bucket.

Syntax

The bin command has the following syntax:

bin <field> [span=<interval>] [minspan=<interval>] [bins=<count>] [aligntime=(earliest | latest | <time-specifier>)] [start=<value>] [end=<value>]

Parameters

The bin command supports the following parameters.

The bins parameter for timestamp fields

The bins parameter for timestamp fields has the following requirements:

• Pushdown must be enabled: Enable pushdown by setting plugins.calcite.pushdown.enabled to true (enabled by default). If pushdown is disabled, use the span parameter instead (for example, bin @timestamp span=5m).
• The timestamp field must be used as an aggregation bucket: The binned timestamp field must be included in a stats aggregation (for example, source=events | bin @timestamp bins=3 | stats count() by @timestamp). Using bins on timestamp fields outside of aggregation buckets is not supported.

Time units

The following time units are available for the span parameter:

• Microseconds (us)
• Milliseconds (ms)
• Centiseconds (cs)
• Deciseconds (ds)
• Seconds (s, sec, secs, second, or seconds)
• Minutes (m, min, mins, minute, or minutes)
• Hours (h, hr, hrs, hour, or hours)
• Days (d, day, or days)
• Months (M, mon, month, or months)

Align time options

The following options are available for the aligntime parameter:

• earliest – Align bins to the earliest timestamp in the data.
• latest – Align bins to the latest timestamp in the data.
• <time-specifier> – Align bins to a specific epoch time value or time modifier expression.

Parameter behavior

When multiple parameters are specified, the priority order is: span > minspan > bins > start/end > default.

Special parameter types

The bin command has the following special handling for certain parameter types:

• Logarithmic spans (for example, log10 or 2log10) create logarithmic bin boundaries instead of linear ones.
• Daily or monthly spans automatically align to calendar boundaries and return date strings (YYYY-MM-DD) instead of timestamps.
• The aligntime parameter applies only to time spans shorter than a day (excluding daily or monthly spans).
• The start and end parameters expand the range (they never reduce it) and affect bin width calculations.

Example 1: Basic numeric span

source=accounts
| bin age span=10
| fields age, account_number
| head 3

The query returns the following results:

Example 2: Large numeric span

source=accounts
| bin balance span=25000
| fields balance
| head 2

The query returns the following results:

Example 3: Logarithmic span (log10)

source=accounts
| bin balance span=log10
| fields balance
| head 2

The query returns the following results:

Example 4: Logarithmic span with coefficient

source=accounts
| bin balance span=2log10
| fields balance
| head 3

The query returns the following results:

Example 5: Basic bins parameter

source=time_test
| bin value bins=5
| fields value
| head 3

The query returns the following results:

Example 6: Low bin count

source=accounts
| bin age bins=2
| fields age
| head 1

The query returns the following results:

Example 7: High bin count

source=accounts
| bin age bins=21
| fields age, account_number
| head 3

The query returns the following results:

Example 8: Basic minspan

source=accounts
| bin age minspan=5
| fields age, account_number
| head 3

The query returns the following results:

Example 9: Large minspan

source=accounts
| bin age minspan=101
| fields age
| head 1

The query returns the following results:

Example 10: Start and end range

source=accounts
| bin age start=0 end=101
| fields age
| head 1

The query returns the following results:

Example 11: Large end range

source=accounts
| bin balance start=0 end=100001
| fields balance
| head 1

The query returns the following results:

Example 12: Span with start/end

source=accounts
| bin age span=1 start=25 end=35
| fields age
| head 6

The query returns the following results:

Example 13: Hour span

source=time_test
| bin @timestamp span=1h
| fields @timestamp, value
| head 3

The query returns the following results:

Example 14: Minute span

source=time_test
| bin @timestamp span=45minute
| fields @timestamp, value
| head 3

The query returns the following results:

Example 15: Second span

source=time_test
| bin @timestamp span=30seconds
| fields @timestamp, value
| head 3

The query returns the following results:

Example 16: Daily span

source=time_test
| bin @timestamp span=7day
| fields @timestamp, value
| head 3

The query returns the following results:

Example 17: Aligntime with time modifier

source=time_test
| bin @timestamp span=2h aligntime='@d+3h'
| fields @timestamp, value
| head 3

The query returns the following results:

Example 18: Aligntime with epoch timestamp

source=time_test
| bin @timestamp span=2h aligntime=1500000000
| fields @timestamp, value
| head 3

The query returns the following results:

Example 19: Default behavior (no parameters)

source=accounts
| bin age
| fields age, account_number
| head 3

The query returns the following results:

Example 20: Binning with string fields

source=accounts
| eval age_str = CAST(age AS STRING)
| bin age_str bins=3
| stats count() by age_str
| sort age_str

The query returns the following results: