Axiom
Overview

histogramif

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.

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#

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.

Use histogramif to analyze span duration distributions for specific services in your OpenTelemetry traces.

Query

['otel-demo-traces']
| summarize histogramif(duration, 50, ['service.name'] == 'frontend') by bin_auto(_time)

Run in Playground

This query groups span durations into 50ms intervals, focusing only on the frontend service. This helps you identify performance patterns specific to that service.

Use histogramif to examine the distribution of request durations for specific geographic regions, helping you identify regional performance issues or anomalies.

Query

['sample-http-logs']
| summarize histogramif(req_duration_ms, 50, ['geo.country'] == 'United States') by bin_auto(_time)

Run in Playground

This query analyzes request duration patterns for traffic originating from the US, helping you identify geographic performance variations or security patterns.

  • 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.

Other query languages#

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

APL equivalent

['sample-http-logs']
| summarize histogramif(req_duration_ms, 10, status == '200')
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

APL equivalent

['sample-http-logs']
| summarize histogramif(req_duration_ms, 10, status == '200')

Updated

Was this page helpful?