acos

Use the `acos()` function to calculate the principal value of the inverse cosine (arccosine) of a numerical expression.

## Syntax

```sql
acos(<numeric_expression>)
```

## Parameters

| Name | Type | Required | Description |
| -------------------- | -------------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
| `numeric_expression` | integer, float | Yes | The numerical value for which to calculate the arccosine. The value must be within the range of -1 to 1 (inclusive). |

## Returns

**Type**: float

**Description**: The `acos()` function returns the principal value of the arccosine of the input in radians. The resulting value is within the range \[0, π].

## Usage notes

* **Input type**: XQL doesn't support NaN or infinite values as input and these value types also can not be returned.
* **Valid Input Range**: The input `numeric_expression` must fall within the closed interval \[-1, 1].
* **Out of Range Behavior**: If the input is outside the range of -1 to 1, the function returns `NaN` (Not a Number) or `null`.
* **Null Handling**: If the input expression is `null`, the function returns `null`.
* **Radians to Degrees**: The result is provided in radians. To convert the result to degrees, multiply the return value by `180 / PI()`.
* **Common Use Cases**: This function is typically utilized in the `alter` stage for geometric calculations, spatial analysis, or normalizing data vectors.

## Examples

### Example 1: Calculate arccosine of a literal value

**Goal**: Calculate the inverse cosine for specific numerical literals to see the radian results.

**XQL Code**:

```sql
dataset = xdr_data
| limit 1
| alter result1 = acos(1), result2 = acos(-1), result3 = acos(0)
| fields result1, result2, result3
```

**Explanation**: You use acos() on three different literal values. The function calculates the principal value of the inverse cosine for each. The results are in radians.

**Output**:

| RESULT1 | RESULT2 | RESULT3 |
| ------- | ---------- | --------- |
| 0.0 | 3.14159... | 1.5708... |
| | | |

### Example 2: Calculate arccosine from a field value

**Goal**: Calculate the arccosine of values stored in a specific field, ensuring they are within the valid mathematical range.

**XQL Code**:

```sql
dataset = sample_xql_raw
| filter duration_seconds >= -1 and duration_seconds <= 1
| alter arc_cos_val = acos(duration_seconds)
| fields event_id, duration_seconds, arc_cos_val
| limit 3
```

**Explanation**: This query first filters the dataset to ensure duration\_seconds contains only values between -1 and 1, then computes the arccosine for each and stores it in arc\_cos\_val.

## Related Articles

* **Stages**: [alter](../stages/alter), [fields](../stages/fields), [limit](../stages/limit)
* **Functions**: [cos](cos), [asin](asin), atan
* **Datasets**: [xdr\_data](https://www.google.com/search?q=%5Bhttps://docs-cortex.paloaltonetworks.com/r/Cortex-XQL-Schema-Reference-Guide/Introduction%5D\(https://docs-cortex.paloaltonetworks.com/r/Cortex-XQL-Schema-Reference-Guide/Introduction\))