mod ↗

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

Syntax

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:

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:

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:

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