> 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/safe_divide.md). # safe\_divide Use the `safe_divide()` function to perform division of two numeric values with error protection. Unlike the standard `divide()` function, `safe_divide()` returns `null` instead of raising an error when dividing by zero. ## Syntax ```sql safe_divide(, ) ``` ## 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). | ## Returns **Type**: float **Description**: The `safe_divide()` function returns the result of dividing the `dividend` by the `divisor`. If the `divisor` is zero, the function returns `null` instead of raising an error. If either 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. * **Division by Zero Protection**: The primary advantage of `safe_divide()` over `divide()` is that it returns `null` instead of raising an error when the divisor is zero. * **Null Handling**: If either input expression is `null`, the function returns `null`. * **Return Type**: The result is always a float, even when both inputs are integers. * **Common Use Cases**: This function is used when the divisor might be zero, such as calculating ratios, percentages, or averages where the denominator could be zero in some records. ## Examples ### Example 1: Safe division with zero divisor **Goal**: Demonstrate that `safe_divide()` returns null instead of an error when dividing by zero. **XQL code**: ```sql dataset = xdr_data | limit 1 | alter result1 = safe_divide(10, 2), result2 = safe_divide(10, 0), result3 = safe_divide(0, 5) | fields result1, result2, result3 ``` **Explanation**: `safe_divide(10, 2)` returns `5.0`. `safe_divide(10, 0)` returns `null` instead of raising a division-by-zero error. `safe_divide(0, 5)` returns `0.0`. **Output**: | RESULT1 | RESULT2 | RESULT3 | | ------- | ------- | ------- | | 5.0 | null | 0.0 | ### Example 2: Calculate safe ratios from field values **Goal**: Calculate a ratio between two fields where the denominator might be zero. **XQL code**: ```sql config timeframe = 1d | dataset = sample_xql_raw | alter ratio = safe_divide(numeric_value, duration_seconds) | fields event_id, numeric_value, duration_seconds, ratio | limit 3 ``` **Explanation**: This query safely divides `numeric_value` by `duration_seconds`. If `duration_seconds` is zero for any record, the result is `null` rather than an error, preventing query failure. **Output**: | EVENT\_ID | NUMERIC\_VALUE | DURATION\_SECONDS | RATIO | | --------- | -------------- | ----------------- | -------- | | 101 | 100.0 | 1.5 | 66.66667 | | 102 | 50.0 | 0.0 | null | | 103 | 200.0 | 10.2 | 19.60784 | ### Example 3: Use safe\_divide with coalesce for fallback **Goal**: Calculate a safe ratio and provide a default value when division by zero occurs. **XQL code**: ```sql config timeframe = 1d | dataset = sample_xql_raw | alter safe_ratio = safe_divide(numeric_value, duration_seconds) | alter final_ratio = coalesce(safe_ratio, 0) | fields event_id, numeric_value, duration_seconds, safe_ratio, final_ratio | limit 3 ``` **Explanation**: This query uses `safe_divide()` to calculate a ratio, then applies `coalesce()` to replace any `null` results (from division by zero or null inputs) with `0` as a fallback value. **Output**: | EVENT\_ID | NUMERIC\_VALUE | DURATION\_SECONDS | SAFE\_RATIO | FINAL\_RATIO | | --------- | -------------- | ----------------- | ----------- | ------------ | | 101 | 100.0 | 1.5 | 66.66667 | 66.66667 | | 102 | 50.0 | 0.0 | null | 0 | | 103 | 200.0 | 10.2 | 19.60784 | 19.60784 | ## 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), [`safe_multiply()`](/xql-command-reference-guide/readme/functions/safe_multiply.md), [`safe_add()`](/xql-command-reference-guide/readme/functions/safe_add.md), [`coalesce()`](/xql-command-reference-guide/readme/functions/coalesce.md) * **Datasets**: [`xdr_data`](https://docs-cortex.paloaltonetworks.com/r/Cortex-XQL-Schema-Reference-Guide/Introduction) --- # 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/safe_divide.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.