least ↗

Use the least() function to return the smallest value from a list of expressions.

Syntax

least(<expression1>, <expression2> [, ...])

Parameters

Name Type Required Description
expression1 integer, float, string, timestamp Yes The first value to compare.
expression2 integer, float, string, timestamp Yes The second value to compare.
... integer, float, string, timestamp No Additional values to compare. Any number of additional expressions can be provided.

Returns

Type: Same as input type

Description: The least() function returns the smallest value among all the provided expressions. If any input is null, the function may skip null values or return null depending on the implementation.

Usage notes

  • Input type: XQL doesn't support NaN or infinite values as input and these value types also can not be returned.
  • Multiple Arguments: The function accepts two or more arguments and returns the minimum value among them.
  • Type Consistency: All arguments should be of compatible types for meaningful comparison.
  • Null Handling: If all inputs are null, the function returns null. If some inputs are null, the function typically returns the least non-null value.
  • String Comparison: When comparing strings, the function uses lexicographic (alphabetical) ordering.
  • Relationship to greatest(): The least() function is the counterpart of greatest(), which returns the largest value.
  • Common Use Cases: This function is typically used within the alter stage for selecting the minimum value across multiple fields, implementing upper bounds (capping values), and data normalization.

Examples

Example 1: Find least among literal values

Goal: Find the smallest value from a set of numeric literals.

XQL code:

dataset = xdr_data
| limit 1
| alter min_val = least(10, 25, 5, 42, 18)
| fields min_val

Explanation: The least() function compares all five literal values and returns 5, the smallest among them.

Output:

MIN_VAL
5

Example 2: Find least value across multiple fields

Goal: Find the smallest value among multiple numeric fields for each record.

XQL code:

config timeframe = 1d
| dataset = sample_xql_raw
| alter min_field = least(event_id, numeric_value, duration_seconds)
| fields event_id, numeric_value, duration_seconds, min_field
| limit 3

Explanation: This query compares the values of event_id, numeric_value, and duration_seconds for each record and returns the smallest value in min_field.

Output:

EVENT_ID NUMERIC_VALUE DURATION_SECONDS MIN_FIELD
101 5.0 1.5 1.5
102 200.0 0.8 0.8
103 50.0 10.2 10.2

Example 3: Implement an upper cap using least

Goal: Cap a value at a maximum threshold by using least() as an upper clamp.

XQL code:

config timeframe = 1d
| dataset = sample_xql_raw
| alter capped_duration = least(duration_seconds, 5.0)
| fields event_id, duration_seconds, capped_duration
| limit 3

Explanation: This query ensures that capped_duration does not exceed 5.0 by returning the lesser of duration_seconds and 5.0. Values above 5.0 are capped, while values below remain unchanged.

Output:

EVENT_ID DURATION_SECONDS CAPPED_DURATION
101 1.5 1.5
102 0.8 0.8
103 10.2 5.0