histogramif

This page explains how to use the histogramif aggregation function in APL.

The histogramif aggregation in APL creates a histogram that groups numeric values into intervals (bins) for rows where a specified condition evaluates to true. This is useful when you want to visualize the distribution of data conditionally—for example, analyzing response times only for successful requests or examining span durations only for specific services.

You use histogramif when you need to combine filtering and distribution analysis in a single operation, making your queries more efficient and expressive.

Like the histogram aggregation, histogramif returns estimated results. The estimation provides speed benefits at the expense of precision, making it fast and resource-efficient even on large or high-cardinality datasets.

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.

Splunk SPL users

In Splunk SPL, you typically combine filtering with histogram operations using separate commands. APL’s histogramif consolidates this into a single aggregation, simplifying your query logic.

Splunk example

| where status='200'
| timechart span=10 count by duration

ANSI SQL users

In ANSI SQL, you combine WHERE clauses with CASE statements and GROUP BY to achieve conditional histograms. APL’s histogramif provides a more concise syntax for this pattern.

SQL example

SELECT FLOOR(req_duration_ms/10)*10 as duration_bin, COUNT(*)
FROM sample_http_logs
WHERE status = '200'
GROUP BY duration_bin

Usage

Syntax

histogramif(numeric_field, number_of_bins, condition)

Parameters

Name	Type	Description
numeric_field	real	The numeric field to create a histogram for, such as request duration or response size.
number_of_bins	long	The number of intervals (bins) to use for grouping the numeric values.
condition	bool	A boolean expression that determines which rows to include in the histogram.

Returns

A table where each row represents a bin, along with the number of occurrences (counts) that fall within each bin for rows where the condition evaluates to true.

Use case examples

Log analysis

Use histogramif to analyze the distribution of request durations only for successful HTTP requests.

Query

['sample-http-logs']
| summarize histogramif(req_duration_ms, 100, status == '200') by bin_auto(_time)

Run in Playground

This query creates a histogram of request durations grouped into 100ms bins, but only includes requests with a 200 HTTP status code. This helps you understand the performance characteristics of successful requests.

List of related aggregations

• histogram: Use histogram when you want to create a distribution without a condition. Use histogramif when you need to filter rows first.
• countif: Use countif for simple conditional counting. Use histogramif when you need distribution analysis with a condition.
• avgif: Use avgif when you need the average of values matching a condition. Use histogramif for full distribution analysis.
• percentileif: Use percentileif to find specific percentile values conditionally. Use histogramif for a complete distribution overview.
• sumif: Use sumif for conditional sums. Use histogramif when you need to understand the distribution of conditional values.