bin

The bin function works with numbers, dates, and timespans. When combined with the summarize operator, it enables powerful time-series analysis by grouping events into fixed intervals.

Usage#

Syntax#

bin(value, bin_size)

Parameters#

Name	Type	Description
`value`	`real`, `datetime`, or `timespan`	The value to round down to the nearest bin boundary.
`bin_size`	`real`, `datetime`, or `timespan`	The size of each bin. Must be a positive value.

Returns#

The nearest multiple of bin_size that's less than or equal to value. The return type matches the input type.

Use case examples#

Log analysisOpenTelemetry traces

Aggregate HTTP requests into 5-minute intervals to analyze traffic patterns.

Query

['sample-http-logs']
| summarize request_count = count(), avg_duration = avg(req_duration_ms) by bin(_time, 5m)

Run in Playground

Output

request_count	avg_duration
581,330	0.8631ms

This query groups all HTTP requests into 5-minute windows, providing a time-series view of traffic volume and average response times.

Analyze trace durations by grouping them into 1-minute intervals per service.

Query

['otel-demo-traces']
| summarize span_count = count(), p95_duration = percentile(duration, 95) by bin(_time, 1m), ['service.name']
| order by span_count desc

Run in Playground

Output

service.name	span_count	p95_duration
frontend	520	24.2ms
cart	230	12.4ms
checkout	85	10.2ms

This query creates a per-minute breakdown of span counts and 95th percentile durations for each service.

bin_auto: Automatically determines bin size based on the query time range. Use bin when you need explicit control over the bin size.
floor: Rounds down to the largest integer less than or equal to the input. Use bin for rounding to arbitrary multiples.
ceiling: Rounds up to the smallest integer greater than or equal to the input. Use bin when you need to round down to specific intervals.
summarize: The bin function is commonly used within summarize for time-based aggregations.

Other query languages#

Splunk SPL users

In Splunk SPL, you use the bin command (formerly bucket) to group continuous values. APL's bin function works similarly but is used as a scalar function within expressions.

Splunk example

| bin span=5m _time
| stats count by _time

APL equivalent

['sample-http-logs']
| summarize count() by bin(_time, 5m)

ANSI SQL users

In ANSI SQL, you typically use FLOOR with division and multiplication to achieve binning. APL's bin function provides this capability directly.

SQL example

SELECT FLOOR(UNIX_TIMESTAMP(timestamp) / 300) * 300 AS time_bucket, COUNT(*)
FROM logs
GROUP BY time_bucket