range_bucket
Use the range_bucket() function to determine which bucket a numeric value falls into, given an array of bucket boundaries. The function returns the index of the bucket (0-based) that contains the value.
Syntax
range_bucket(<value>, <boundaries>)Parameters
value
integer, float
Yes
The numeric value to classify into a bucket.
boundaries
array of integers or floats
Yes
A sorted array of boundary values that define the bucket edges. Must be in ascending order.
Returns
Type: integer
Description: The range_bucket() function returns a 0-based integer index indicating which bucket the value falls into. If the value is less than the first boundary, it returns 0. If the value is greater than or equal to the last boundary, it returns the number of boundaries. If the input is null, the function returns null.
Usage notes
Input type: XQL doesn't support NaN or infinite values as input and these value types also can not be returned.
Sorted Boundaries: The
boundariesarray must be sorted in ascending order. Unsorted boundaries produce undefined results.Bucket Ranges: For boundaries
[b1, b2, b3], the buckets are: bucket 0 =(-∞, b1), bucket 1 =[b1, b2), bucket 2 =[b2, b3), bucket 3 =[b3, +∞).Null Handling: If the
valueisnull, the function returnsnull.Common Use Cases: This function is typically used within the
alterstage for data binning, histogram creation, severity classification, and score grading.
Examples
Example 1: Classify values into predefined buckets
Goal: Classify numeric values into severity levels using predefined boundaries.
XQL code:
Explanation: With boundaries [0, 10, 50, 100], the value 5 falls in bucket 1 (between 0 and 10), 25 falls in bucket 2 (between 10 and 50), and 75 falls in bucket 3 (between 50 and 100).
Output:
1
2
3
Example 2: Classify field values into risk levels
Goal: Assign risk levels to events based on their numeric value using bucket boundaries.
XQL code:
Explanation: This query classifies each numeric_value into a risk bucket using boundaries [0, 25, 50, 75, 100], then maps each bucket to a human-readable risk level label.
Output:
101
5.0
1
low
102
60.0
3
high
103
30.0
2
medium
Example 3: Create histogram buckets for duration values
Goal: Distribute duration values into histogram buckets for analysis.
XQL code:
Explanation: This query assigns each event to a duration bucket based on duration_seconds, then counts the number of events in each bucket. This creates a histogram-like distribution of event durations.
Output:
0
3
1
5
2
4
3
2
4
1
Related articles
Functions:
arraycreate(),if(),floor()Datasets:
xdr_data
Last updated
Was this helpful?
