bin
Description
Splits continuous numeric values into discrete sets (bins) based on the specified field <field>.
Syntax
| bin [<bin-options>...] <field> [AS <newfield>]
Required Arguments
| Parameter | Syntax | Description |
|---|---|---|
field | <field> | The name of the field by which data is binned. |
Optional Arguments
Defines limits and parameters for splitting data during analysis:
| Parameter | Syntax | Default | Description |
|---|---|---|---|
bins | bins=<int> | 100 | Maximum number of bins for calculation. |
span | span = (+|-)<int>(s|m|h|d|w|month) | See predefined spans | The interval for binning. |
newfield | as <field> | A new name for the field. |
The following format is accepted for time-based parameters: (+|-)<int>(s|m|h|d|w|month):
- s/sec/secs/second/seconds - seconds
- m/min/mins/minute/minutes - minutes
- h/hr/hrs/hour/hours - hours
- d/day/days - days
- w/week/weeks - weeks
- mon/month/months - months
If the span parameter for a time field is not specified, predefined span parameters will be applied.
List of predefined span parameters:
| Time Interval | span |
|---|---|
| Last 15 minutes | 10 seconds |
| Last 60 minutes | 1 minute |
| Last 4 hours | 5 minutes |
| Last 24 hours | 30 minutes |
| Last 7 days | 1 day |
| Last 30 days | 1 day |
| Last year | 1 month |
If the span parameter for a numeric field is not specified, it is calculated as (maximum field value) / (maximum number of bins).
A time-based span (<int>(s|m|h|d|w|month)) cannot be specified for a numeric field, and a numeric span (<int>) cannot be specified for a time-based field.
Query Examples
The following examples use the auth_sessions index:
| @timestamp | user | host | action | bytes |
|---|---|---|---|---|
| 2026-06-24T08:00:00Z | admin | dc-01 | logged-in | 1500 |
| 2026-06-24T08:15:00Z | admin | dc-01 | file-access | 3200 |
| 2026-06-24T08:30:00Z | admin | srv-01 | logged-in | 800 |
| 2026-06-24T09:00:00Z | john.doe | workstation-01 | logged-in | 1200 |
| 2026-06-24T09:10:00Z | john.doe | workstation-01 | file-access | 4500 |
| 2026-06-24T09:20:00Z | john.doe | workstation-02 | logged-in | 950 |
| 2026-06-24T10:00:00Z | guest | kiosk-01 | logged-in | 300 |
Example 1
In this example, bin rounds the time field @timestamp down to the nearest 30 minutes. stats counts the number of events in each interval.
source auth_sessions
| bin span=30m @timestamp
| stats count by @timestamp
Events at 08:00 and 08:15 fall into one interval 08:00, events at 09:00, 09:10, and 09:20 fall into the 09:00 interval:
| @timestamp | count |
|---|---|
| 2026-06-24T08:00:00.000Z | 2 |
| 2026-06-24T08:30:00.000Z | 1 |
| 2026-06-24T09:00:00.000Z | 3 |
| 2026-06-24T10:00:00.000Z | 1 |
Example 2
In this example, bin divides the numeric field bytes into intervals of width 1000. stats counts the number of events in each range.
source auth_sessions
| bin span=1000 bytes
| stats count by bytes
| bytes | count |
|---|---|
| 0 - 1000 | 3 |
| 1000 - 2000 | 2 |
| 3000 - 4000 | 1 |
| 4000 - 5000 | 1 |
Example 3
In this example, the rounding result is saved to a new field bytes_bucket via as, the original field bytes remains unchanged.
source auth_sessions
| bin span=1000 bytes as bytes_bucket
| table @timestamp, user, bytes, bytes_bucket
| @timestamp | user | bytes | bytes_bucket |
|---|---|---|---|
| 2026-06-24T08:00:00Z | admin | 1500 | 1000 - 2000 |
| 2026-06-24T08:15:00Z | admin | 3200 | 3000 - 4000 |
| 2026-06-24T08:30:00Z | admin | 800 | 0 - 1000 |
| 2026-06-24T09:00:00Z | john.doe | 1200 | 1000 - 2000 |
| 2026-06-24T09:10:00Z | john.doe | 4500 | 4000 - 5000 |
| 2026-06-24T09:20:00Z | john.doe | 950 | 0 - 1000 |
| 2026-06-24T10:00:00Z | guest | 300 | 0 - 1000 |
Example 4
In this example, the parameter bins=3 sets the maximum number of intervals. The interval width is calculated automatically as max_value / bins - for the bytes field this is 4500 / 3 = 1500.
source auth_sessions
| bin bins=3 bytes
| stats count by bytes
| bytes | count |
|---|---|
| 0 - 1500 | 4 |
| 1500 - 3000 | 1 |
| 3000 - 4500 | 1 |