asin ↗

Use the asin() function to calculate the principal value of the inverse sine (arcsine) of a numerical expression.

Syntax

asin(<numeric_expression>)

Parameters

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

Returns

Type: float

Description: The asin() function returns the principal value of the arcsine of the input in radians. The resulting value is within the range [-π/2, π/2].

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 used within the alter stage for geometric calculations, spatial analysis, or normalizing data vectors.

Examples

Example 1: Calculate arcsine of literal values

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

XQL code:

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

Explanation: You use asin() on three different literal values. asin(0) returns 0.0, asin(1) returns approximately 1.5708 (π/2), and asin(-1) returns approximately -1.5708 (-π/2).

Output:

RESULT1 RESULT2 RESULT3
0.0 1.5708 -1.5708

Example 2: Calculate arcsine from a field value

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

XQL code:

config timeframe = 1d
| dataset = sample_xql_raw
| filter duration_seconds >= -1 and duration_seconds <= 1
| alter arc_sin_val = asin(duration_seconds)
| fields event_id, duration_seconds, arc_sin_val
| limit 3

Explanation: This query first filters the dataset to ensure duration_seconds contains only values between -1 and 1, then computes the arcsine for each and stores it in arc_sin_val.

Output:

EVENT_ID DURATION_SECONDS ARC_SIN_VAL
101 0.5 0.5236
102 -0.3 -0.3047
103 1.0 1.5708