You're viewing version 3.4 of the OpenSearch documentation. This version is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.

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: