Use the bin function to round values down to the nearest multiple of a specified bin size. This function is essential for grouping continuous data into discrete intervals, making it invaluable for time-based aggregations, histogram creation, and data bucketing.

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.

For users of other query languages

If you come from other query languages, this section explains how to adjust your existing queries to achieve the same results in APL.

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.

```sql Splunk example | bin span=5m _time | stats count by _time ``` 
['sample-http-logs']
| summarize count() by bin(_time, 5m)

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

```sql SQL example SELECT FLOOR(UNIX_TIMESTAMP(timestamp) / 300) * 300 AS time_bucket, COUNT(*) FROM logs GROUP BY time_bucket ``` 
['sample-http-logs']
| summarize count() by bin(_time, 5m)

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 is less than or equal to value. The return type matches the input type.

Use case examples

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.

Good evening

I'm here to help you with the docs.

⌘I
AIBased on your contextⓘ