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`](../stages/alter), [`fields`](../stages/fields), [`limit`](../stages/limit)
* **Functions**: [`divide()`](divide), [`multiply()`](multiply), [`if()`](if)
* **Datasets**: [`xdr_data`](https://docs-cortex.paloaltonetworks.com/r/Cortex-XQL-Schema-Reference-Guide/Introduction)