> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/xql-command-reference-guide/readme/functions/round.md). # 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 ```sql round ( | ) ``` ## 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**: ```sql 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**: ```sql 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**: ```sql 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**: ```sql 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**: ```sql 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`](/xql-command-reference-guide/readme/stages/alter.md), [`fields`](/xql-command-reference-guide/readme/stages/fields.md), [`limit`](/xql-command-reference-guide/readme/stages/limit.md) * **Functions**: [`divide`](/xql-command-reference-guide/readme/functions/divide.md), [`arrayindex`](/xql-command-reference-guide/readme/functions/arrayindex.md), [`to_number`](/xql-command-reference-guide/readme/functions/to_number.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://cortex-docs.paloaltonetworks.com/xql-command-reference-guide/readme/functions/round.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.