acos ↗

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

Syntax

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:

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:

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.