For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

Name
Type
Required
Description

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 boundaries array 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 value is null, the function returns null.

  • Common Use Cases: This function is typically used within the alter stage 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:

BUCKET1
BUCKET2
BUCKET3

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:

EVENT_ID
NUMERIC_VALUE
RISK_BUCKET
RISK_LEVEL

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:

DURATION_BUCKET
EVENT_COUNT

0

3

1

5

2

4

3

2

4

1

Last updated

Was this helpful?