euclidean_distance ↗

Use the euclidean_distance() function to calculate the Euclidean distance between two numeric vectors (arrays). The Euclidean distance is the straight-line distance between two points in multi-dimensional space.

Syntax

euclidean_distance(<vector1>, <vector2>)

Parameters

Name Type Required Description
vector1 array of integers or floats Yes The first numeric vector (array). Must have the same length as vector2.
vector2 array of integers or floats Yes The second numeric vector (array). Must have the same length as vector1.

Returns

Type: float

Description: The euclidean_distance() function returns a non-negative float representing the straight-line distance between the two input vectors. A value of 0.0 indicates identical vectors. If either input is null or the vectors have different lengths, 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.
  • Vector Length: Both input vectors must have the same number of elements. If they differ in length, the function returns null.
  • Vector Type: Only float values are supported for the input vectors.
  • Null Handling: If either input expression is null, the function returns null.
  • Non-Negative Result: The result is always ≥ 0. A result of 0.0 means the two vectors are identical.
  • Formula: The Euclidean distance is calculated as sqrt(sum((v1[i] - v2[i])^2)) for all elements i.
  • Common Use Cases: This function is typically used within the alter stage for similarity analysis, anomaly detection, clustering, and comparing feature vectors in machine learning workflows.

Examples

Example 1: Calculate Euclidean distance between literal vectors

Goal: Calculate the Euclidean distance between specific vector pairs to verify known results.

XQL code:

dataset = xdr_data
| limit 1
| alter dist1 = euclidean_distance(arraycreate(0.0, 0.0), arraycreate(3.0, 4.0))
| alter dist2 = euclidean_distance(arraycreate(1.0, 2.0, 3.0), arraycreate(1.0, 2.0, 3.0))
| fields dist1, dist2

Explanation: The distance between (0.0,0.0) and (3.0,4.0) is 5.0 (a classic 3-4-5 right triangle). The distance between two identical vectors (1.0,2.0,3.0) is 0.0.

Output:

DIST1 DIST2
5.0 0.0

Example 2: Calculate Euclidean distance between field vectors

Goal: Compute the Euclidean distance between an array field and a reference vector.

XQL code:

config timeframe = 1d
| dataset = sample_xql_raw
| filter numeric_codes != null and array_length(numeric_codes) = 5
| alter reference_vector = arraycreate(10.0, 20.0, 30.0, 40.0, 50.0)
| alter euc_dist = euclidean_distance(numeric_codes, reference_vector)
| fields event_id, numeric_codes, euc_dist
| limit 3

Explanation: This query creates a reference vector and computes the Euclidean distance between each record's numeric_codes array and the reference vector. Lower values indicate the vectors are closer together in multi-dimensional space.

Output:

EVENT_ID NUMERIC_CODES EUC_DIST
101 [13, -47, 29, 82, -15] 107.35
102 [-21, 56, 13, -88, 42] 148.92
105 [8, 15, 25, 35, 45] 9.95

Example 3: Find most similar records using Euclidean distance

Goal: Sort records by their Euclidean distance to a reference vector to find the most similar ones.

XQL code:

config timeframe = 1d
| dataset = sample_xql_raw
| filter numeric_codes != null and array_length(numeric_codes) = 5
| alter ref = arraycreate(10.0, 20.0, 30.0, 40.0, 50.0)
| alter distance = euclidean_distance(numeric_codes, ref)
| fields event_id, numeric_codes, distance
| sort asc distance
| limit 3

Explanation: This query computes the Euclidean distance between each record's numeric_codes and a reference vector, then sorts by distance ascending to show the most similar records first.

Output:

EVENT_ID NUMERIC_CODES DISTANCE
105 [8, 15, 25, 35, 45] 9.95
101 [13, -47, 29, 82, -15] 107.35
102 [-21, 56, 13, -88, 42] 148.92