> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/xql-command-reference-guide/readme/functions/range_bucket.md).

# 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

```sql
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**:

```sql
dataset = xdr_data
| limit 1
| alter bucket1 = range_bucket(5, arraycreate(0, 10, 50, 100))
| alter bucket2 = range_bucket(25, arraycreate(0, 10, 50, 100))
| alter bucket3 = range_bucket(75, arraycreate(0, 10, 50, 100))
| fields bucket1, bucket2, bucket3
```

**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**:

```sql
config timeframe = 1d
| dataset = sample_xql_raw
| alter risk_bucket = range_bucket(numeric_value, arraycreate(0, 25, 50, 75, 100))
| alter risk_level = if(risk_bucket = 0, "none", risk_bucket = 1, "low", risk_bucket = 2, "medium", risk_bucket = 3, "high", "critical")
| fields event_id, numeric_value, risk_bucket, risk_level
| limit 3
```

**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**:

```sql
config timeframe = 1d
| dataset = sample_xql_raw
| alter duration_bucket = range_bucket(duration_seconds, arraycreate(1, 5, 10, 30, 60))
| comp count(event_id) as event_count by duration_bucket
| fields duration_bucket, event_count
| sort asc duration_bucket
```

**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            |

## Related articles

* **Stages**: [`alter`](/xql-command-reference-guide/readme/stages/alter.md), [`comp`](/xql-command-reference-guide/readme/stages/comp.md), [`fields`](/xql-command-reference-guide/readme/stages/fields.md), [`sort`](/xql-command-reference-guide/readme/stages/sort.md)
* **Functions**: [`arraycreate()`](/xql-command-reference-guide/readme/functions/arraycreate.md), [`if()`](/xql-command-reference-guide/readme/functions/if.md), [`floor()`](/xql-command-reference-guide/readme/functions/floor.md)
* **Datasets**: [`xdr_data`](https://docs-cortex.paloaltonetworks.com/r/Cortex-XQL-Schema-Reference-Guide/Introduction)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://cortex-docs.paloaltonetworks.com/xql-command-reference-guide/readme/functions/range_bucket.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.