> 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/mod.md).

# mod

Use the `mod()` function to calculate the remainder (modulus) of the division of two numeric values.

## Syntax

```sql
mod(<dividend>, <divisor>)
```

## Parameters

| Name       | Type           | Required | Description                                              |
| ---------- | -------------- | -------- | -------------------------------------------------------- |
| `dividend` | integer, float | Yes      | The number to be divided (numerator).                    |
| `divisor`  | integer, float | Yes      | The number to divide by (denominator). Must not be zero. |

## Returns

**Type**: integer or float (matches input types)

**Description**: The `mod()` function returns the remainder after dividing the `dividend` by the `divisor`. If either input is `null` or the divisor is zero, 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.
* **Division by Zero**: If the `divisor` is zero, the function returns `null` or raises an error.
* **Null Handling**: If either input expression is `null`, the function returns `null`.
* **Sign of Result**: The sign of the result matches the sign of the `dividend`.
* **Common Use Cases**: This function is typically used within the `alter` stage for cyclic calculations, even/odd detection, bucketing, time-based grouping (for example, grouping by hour of day), and hash-based distribution.

## Examples

### Example 1: Calculate modulus of literal values

**Goal**: Calculate the remainder for specific division operations.

**XQL code**:

```sql
dataset = xdr_data
| limit 1
| alter result1 = mod(10, 3), result2 = mod(15, 5), result3 = mod(-7, 3)
| fields result1, result2, result3
```

**Explanation**: `mod(10, 3)` returns `1` (10 = 3�3 + 1), `mod(15, 5)` returns `0` (15 is evenly divisible by 5), and `mod(-7, 3)` returns `-1` (the sign follows the dividend).

**Output**:

| RESULT1 | RESULT2 | RESULT3 |
| ------- | ------- | ------- |
| 1       | 0       | -1      |

### Example 2: Determine even or odd event IDs

**Goal**: Classify events as having even or odd event IDs using the modulus operator.

**XQL code**:

```sql
config timeframe = 1d
| dataset = sample_xql_raw
| alter is_even = if(mod(event_id, 2) = 0, "even", "odd")
| fields event_id, is_even
| limit 4
```

**Explanation**: This query uses `mod(event_id, 2)` to check if the event ID is divisible by 2. If the remainder is 0, the event is classified as "even"; otherwise, it is "odd".

**Output**:

| EVENT\_ID | IS\_EVEN |
| --------- | -------- |
| 101       | odd      |
| 102       | even     |
| 103       | odd      |
| 104       | even     |

### Example 3: Group events into cyclic buckets

**Goal**: Distribute events into 5 cyclic buckets based on their event ID.

**XQL code**:

```sql
config timeframe = 1d
| dataset = sample_xql_raw
| alter bucket = mod(event_id, 5)
| fields event_id, bucket
| limit 5
```

**Explanation**: This query assigns each event to one of 5 buckets (0 through 4) using `mod(event_id, 5)`. This creates a cyclic distribution pattern useful for load balancing or sampling.

**Output**:

| EVENT\_ID | BUCKET |
| --------- | ------ |
| 101       | 1      |
| 102       | 2      |
| 103       | 3      |
| 104       | 4      |
| 105       | 0      |

## Related articles

* **Stages**: [`alter`](/xql-command-reference-guide/readme/stages/alter.md), [`fields`](/xql-command-reference-guide/readme/stages/fields.md), [`limit`](/xql-command-reference-guide/readme/stages/limit.md)
* **Functions**: [`divide()`](/xql-command-reference-guide/readme/functions/divide.md), [`multiply()`](/xql-command-reference-guide/readme/functions/multiply.md), [`if()`](/xql-command-reference-guide/readme/functions/if.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/mod.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.