safe_negate ↗

Use the safe_negate() function to negate a numeric value with overflow protection. Unlike standard negation, safe_negate() returns null instead of raising an error when the result overflows.

Syntax

safe_negate(<number>)

Parameters

Name Type Required Description
number integer, float Yes The numeric value to negate.

Returns

Type: integer or float (matches input type)

Description: The safe_negate() function returns the negated value of the input (i.e., -number). If the result would overflow the numeric type, the function returns null instead of raising an error. 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.
  • Overflow Protection: The primary advantage of safe_negate() is that it returns null instead of raising an error when negating the minimum integer value (for example, negating -9223372036854775808 would overflow since the maximum positive 64-bit integer is 9223372036854775807).
  • Null Handling: If the input expression is null, the function returns null.
  • Double Negation: safe_negate(safe_negate(x)) returns x for all non-overflow cases.
  • Common Use Cases: This function is used when working with values that might be at the boundary of the integer range, such as system-generated counters or imported data with extreme values.

Examples

Example 1: Negate literal values safely

Goal: Negate specific numeric literals, including edge cases.

XQL code:

dataset = xdr_data
| limit 1
| alter result1 = safe_negate(42), result2 = safe_negate(-100), result3 = safe_negate(0)
| fields result1, result2, result3

Explanation: safe_negate(42) returns -42, safe_negate(-100) returns 100, and safe_negate(0) returns 0. These are straightforward negations with no overflow risk.

Output:

RESULT1 RESULT2 RESULT3
-42 100 0

Example 2: Safely negate field values

Goal: Negate values stored in a dataset field with overflow protection.

XQL code:

config timeframe = 1d
| dataset = sample_xql_raw
| alter negated_value = safe_negate(numeric_value)
| fields event_id, numeric_value, negated_value
| limit 3

Explanation: This query negates each value in the numeric_value field. If any value is at the minimum integer boundary, the result is null rather than an error.

Output:

EVENT_ID NUMERIC_VALUE NEGATED_VALUE
101 5.0 -5.0
102 -200.0 200.0
103 50.0 -50.0

Example 3: Use safe_negate to compute absolute difference

Goal: Calculate the absolute difference between two fields using safe negation.

XQL code:

config timeframe = 1d
| dataset = sample_xql_raw
| alter diff = subtract(numeric_value, duration_seconds)
| alter abs_diff = if(diff < 0, safe_negate(diff), diff)
| fields event_id, numeric_value, duration_seconds, diff, abs_diff
| limit 3

Explanation: This query calculates the difference between two fields, then uses safe_negate() to compute the absolute value when the difference is negative. This approach safely handles potential overflow at integer boundaries.

Output:

EVENT_ID NUMERIC_VALUE DURATION_SECONDS DIFF ABS_DIFF
101 5.0 1.5 3.5 3.5
102 0.8 200.0 -199.2 199.2
103 50.0 10.2 39.8 39.8