round ↗

Use the round() function to take a numeric input (either a float or an integer) and return the value rounded to the nearest whole integer.

Syntax

round (<float> | <integer>)

Parameters

Name	Type	Required	Description
value	float, integer	Yes	The numeric value to be rounded.

Returns

The round() function returns an integer representing the input value rounded to the nearest whole number. Standard mathematical rounding rules apply, where values exactly at .5 typically round up.

Usage notes

• The function accepts either a floating-point number or an integer as its input.
• If the input is already an integer, the value remains unchanged.
• For positive numbers, a fractional part of .5 or greater rounds up to the next higher integer.
• For negative numbers, the function rounds to the nearest integer, adhering to standard mathematical rounding for negative values.

Examples

Example 1: Round on a positive floating-point field

Goal: Round a positive floating-point field to the nearest integer, demonstrating rounding up and rounding down.

XQL code:

config timeframe = 1d
| dataset = sample_xql_raw
| alter rounded_duration_up = round(duration_seconds)
| alter example_duration = 1.4
| alter rounded_duration_down = round(example_duration)
| fields event_id, duration_seconds, rounded_duration_up, example_duration, rounded_duration_down
| limit 3

Explanation: This query calculates rounded_duration_up by rounding duration_seconds. For event_id 101 (duration_seconds of 1.5), it rounds to 2. For event_id 102 (duration_seconds of 0.8), it rounds to 1. A literal 1.4 is introduced to show it rounds down to 1.

Output:

EVENT_ID	DURATION_SECONDS	ROUNDED_DURATION_UP	EXAMPLE_DURATION	ROUNDED_DURATION_DOWN
101	1.5	2	1.4	1
102	0.8	1	1.4	1
103	10.2	10	1.4	1

Example 2: Round on a calculated floating-point value (from an integer field)

Goal: Round a calculated floating-point number derived from an integer field after a division operation.

XQL code:

config timeframe = 1d
| dataset = sample_xql_raw
| alter divided_event_id = divide(event_id, 3)
| alter rounded_divided_id = round(divided_event_id)
| fields event_id, divided_event_id, rounded_divided_id
| limit 3

Explanation: Here, event_id (for example, 101) is divided by 3, resulting in approximately 33.666. The round() function then rounds this to 34. For event_id 102, 102/3 = 34, so round() returns 34.

Output:

EVENT_ID	DIVIDED_EVENT_ID	ROUNDED_DIVIDED_ID
101	33.666666666666664	34
102	34	34
103	34	34

Example 3: Round on a negative floating-point value (from an array field)

Goal: Round a negative floating-point number derived from an array element.

XQL code:

config timeframe = 1d
| dataset = sample_xql_raw
| alter second_numeric_code = arrayindex(numeric_codes, 1)
| alter negative_float_example = divide(second_numeric_code, 10.0)
| alter rounded_negative_float = round(negative_float_example)
| fields event_id, numeric_codes, negative_float_example, rounded_negative_float
| limit 3

Explanation: For event_id 101, second_numeric_code is -47. Dividing by 10.0 results in -4.7. round() then converts -4.7 to -5. For event_id 102, the code is 56, resulting in 5.6, which round() converts to 6.

Output:

EVENT_ID	NUMERIC_CODES	NEGATIVE_FLOAT_EXAMPLE	ROUNDED_NEGATIVE_FLOAT
101	[13, -47, 29,...]	-4.7	-5
102	[-21, 56, 13,...]	5.6	6
103	[90, -33, 7,...]	-3.3	-3

Example 4: Round on an integer field (no change)

Goal: Apply the function to an integer field to confirm that whole numbers remain unchanged.

XQL code:

config timeframe = 1d
| dataset = sample_xql_raw
| alter rounded_event_id = round(event_id)
| fields event_id, rounded_event_id
| limit 3

Explanation: The event_id field contains integers (for example, 101, 102). When round() is applied, these values remain 101, 102, etc., demonstrating no change for whole numbers.

Output:

EVENT_ID	ROUNDED_EVENT_ID
101	101
102	102
103	103

Example 5: Round on a numeric value extracted from JSON data

Goal: Round a number extracted from a JSON field after converting it and performing a calculation.

XQL code:

config timeframe = 1d
| dataset = sample_xql_raw
| filter simple_json_data != null
| alter json_code_string = simple_json_data -> code
| alter json_numeric_value = to_number(json_code_string)
| alter calc_json_value = divide(json_numeric_value, 1.5)
| alter rounded_json_value = round(calc_json_value)
| fields event_id, simple_json_data, json_numeric_value, calc_json_value, rounded_json_value
| limit 1

Explanation: This query extracts the code value (for example, "200") from the simple_json_data field as a string, converts it to a number using to_number(), divides it by 1.5 to introduce a decimal, and then applies round() to get the nearest whole integer. Note that only event_id 101 has a "code" field in simple_json_data in the sample_xql_raw dataset, hence only one result is displayed.

Output:

EVENT_ID	SIMPLE_JSON_DATA	JSON_NUMERIC_VALUE	CALC_JSON_VALUE	ROUNDED_JSON_VALUE
101	{"status": "ok", "code": 200}	200	133.33333333333334	133

Related articles

• Stages: alter, fields, limit
• Functions: divide, arrayindex, to_number