sec ↗

Use the sec() function to calculate the secant of a numeric value specified in radians. The secant is the reciprocal of the cosine function.

Syntax

sec(<numeric_expression>)

Parameters

Name Type Required Description
numeric_expression integer, float Yes The angle in radians for which to calculate the secant. The value must not be an odd multiple of p/2.

Returns

Type: float

Description: The sec() function returns the secant of the input angle, which is equivalent to 1 / cos(x). If the 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.
  • Valid Input Range: The sec() function accepts any real number except values where cos(x) = 0 (i.e., odd multiples of p/2), where the secant is undefined.
  • Undefined Values: At odd multiples of p/2 (for example, p/2, 3p/2), the function returns infinity, NaN, or null since the secant is undefined at these points.
  • Null Handling: If the input expression is null, the function returns null.
  • Relationship: sec(x) = 1 / cos(x).
  • Result Range: The result is always = -1 or = 1 (never between -1 and 1).
  • Common Use Cases: This function is typically used within the alter stage for trigonometric calculations, optics computations, and engineering analysis.

Examples

Example 1: Calculate secant of literal values

Goal: Calculate the secant for specific radian values to verify known mathematical results.

XQL code:

dataset = xdr_data
| limit 1
| alter result1 = sec(0), result2 = sec(pi()), result3 = sec(1)
| fields result1, result2, result3

Explanation: sec(0) returns 1.0 (since cos(0) = 1), sec(p) returns -1.0 (since cos(p) = -1), and sec(1) returns approximately 1.8508.

Output:

RESULT1 RESULT2 RESULT3
1.0 -1.0 1.85082

Example 2: Calculate secant from a field value

Goal: Calculate the secant of values stored in a dataset field.

XQL code:

config timeframe = 1d
| dataset = sample_xql_raw
| alter sec_val = sec(numeric_value)
| fields event_id, numeric_value, sec_val
| limit 3

Explanation: This query computes the secant for each value in the numeric_value field and stores the result in sec_val.

Output:

EVENT_ID NUMERIC_VALUE SEC_VAL
101 0.0 1.0
102 1.0 1.85082
103 3.14159 -1.0

Example 3: Verify secant as reciprocal of cosine

Goal: Demonstrate that sec(x) equals 1 / cos(x) by computing both and comparing.

XQL code:

config timeframe = 1d
| dataset = sample_xql_raw
| alter sec_val = sec(numeric_value)
| alter reciprocal_cos = divide(1, cos(numeric_value))
| fields event_id, numeric_value, sec_val, reciprocal_cos
| limit 3

Explanation: This query computes both sec(numeric_value) and 1 / cos(numeric_value) to verify they produce the same result, confirming the mathematical identity sec(x) = 1 / cos(x).

Output:

EVENT_ID NUMERIC_VALUE SEC_VAL RECIPROCAL_COS
101 0.0 1.0 1.0
102 1.0 1.85082 1.85082
103 3.14159 -1.0 -1.0