> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suprsend.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Vector and distance functions

> Vector and distance functions in SuprSend Segment List SQL — cosine, dot product, and L1/L2/Linf norms and distances.

Functions for measuring the length of a vector (norms) and the distance or similarity between two equal-length vectors, useful for embeddings, feature scoring, and nearest-neighbor style comparisons. Vectors are passed as arrays or tuples of numeric values, and paired functions require both inputs to have the same length.

## cosineDistance

Computes the cosine distance between two vectors, defined as one minus their cosine similarity. Values range from `0` (identical direction) to `2` (opposite direction), so smaller values mean more similar orientation regardless of magnitude.

**Syntax**

```sql theme={"system"}
cosineDistance(vector1, vector2)
```

**Arguments**

* `vector1` — first vector, an array or tuple of numeric values.
* `vector2` — second vector, an array or tuple of the same length.

**Returned value**

* The cosine distance as a `Float` (Float32 or Float64 depending on the input types).

**Example**

```sql Cosine distance between two embeddings theme={"system"}
SELECT distinct_id FROM users WHERE cosineDistance([1.0, 2.0, 3.0], [2.0, 4.0, 6.0]) < 0.1
```

## L2Distance / L2Norm

`L2Distance` returns the Euclidean distance between two vectors, the square root of the sum of the squared differences of their elements. `L2Norm` returns the Euclidean length of a single vector, the square root of the sum of the squares of its elements.

**Syntax**

```sql theme={"system"}
L2Distance(vector1, vector2)
L2Norm(vector)
```

**Arguments**

* `vector`, `vector1`, `vector2` — arrays or tuples of numeric values. The two arguments to `L2Distance` must have the same length.

**Returned value**

* `L2Distance`: the Euclidean distance between the two vectors as a `Float`.
* `L2Norm`: the Euclidean length of the vector as a `Float`.

**Example**

```sql Euclidean distance and L2 norm theme={"system"}
SELECT distinct_id FROM users WHERE L2Distance([1.0, 2.0, 3.0], [4.0, 6.0, 3.0]) < 6 AND L2Norm([3.0, 4.0]) > 2
```

## L2SquaredDistance / L2SquaredNorm

`L2SquaredDistance` returns the sum of the squared differences between corresponding elements of two vectors (the squared Euclidean distance). `L2SquaredNorm` returns the sum of the squares of a single vector's elements (the squared L2 norm). Skipping the square root makes these cheaper than their `L2` counterparts and is sufficient when you only need to rank or compare distances.

**Syntax**

```sql theme={"system"}
L2SquaredDistance(vector1, vector2)
L2SquaredNorm(vector)
```

**Arguments**

* `vector`, `vector1`, `vector2` — arrays or tuples of numeric values. The two arguments to `L2SquaredDistance` must have the same length.

**Returned value**

* `L2SquaredDistance`: the sum of squared element-wise differences.
* `L2SquaredNorm`: the sum of the squared element values.

Both return an integer or `Float` value depending on the input types.

**Example**

```sql Squared Euclidean distance and squared L2 norm theme={"system"}
SELECT distinct_id FROM users WHERE L2SquaredDistance([1.0, 2.0, 3.0], [4.0, 6.0, 3.0]) < 30 AND L2SquaredNorm([3.0, 4.0]) > 4
```

## dotProduct

Computes the scalar (dot) product of two vectors: the sum of the products of their corresponding elements.

**Syntax**

```sql theme={"system"}
dotProduct(vector1, vector2)
```

**Arguments**

* `vector1` — first vector, an array or tuple of numeric values.
* `vector2` — second vector, an array or tuple of the same length.

**Returned value**

* The scalar product as a single numeric value whose type follows the input element types.

**Example**

```sql Dot product of two vectors theme={"system"}
SELECT distinct_id FROM users WHERE dotProduct([1.0, 2.0, 3.0], [4.0, 5.0, 6.0]) > 30
```

## L1Distance / L1Norm

`L1Distance` returns the Manhattan (taxicab) distance between two vectors, the sum of the absolute differences of their elements. `L1Norm` returns the L1 length of a single vector, the sum of the absolute values of its elements.

**Syntax**

```sql theme={"system"}
L1Distance(vector1, vector2)
L1Norm(vector)
```

**Arguments**

* `vector`, `vector1`, `vector2` — arrays or tuples of numeric values. The two arguments to `L1Distance` must have the same length.

**Returned value**

* `L1Distance`: the sum of absolute element-wise differences.
* `L1Norm`: the sum of the absolute element values.

Both return an integer or `Float` value depending on the input types.

**Example**

```sql Manhattan distance and L1 norm theme={"system"}
SELECT distinct_id FROM users WHERE L1Distance([1.0, 2.0, 3.0], [4.0, 6.0, 3.0]) < 10 AND L1Norm([-3.0, 4.0, -5.0]) > 2
```

## LinfDistance / LinfNorm

`LinfDistance` returns the Chebyshev (L-infinity) distance between two vectors, the maximum absolute difference across their elements. `LinfNorm` returns the L-infinity length of a single vector, the maximum absolute value among its elements.

**Syntax**

```sql theme={"system"}
LinfDistance(vector1, vector2)
LinfNorm(vector)
```

**Arguments**

* `vector`, `vector1`, `vector2` — arrays or tuples of numeric values. The two arguments to `LinfDistance` must have the same length.

**Returned value**

* `LinfDistance`: the largest absolute element-wise difference, as a `Float`.
* `LinfNorm`: the largest absolute element value, as a `Float`.

**Example**

```sql Chebyshev distance and L-infinity norm theme={"system"}
SELECT distinct_id FROM users WHERE LinfDistance([1.0, 2.0, 3.0], [4.0, 6.0, 3.0]) < 5 AND LinfNorm([-3.0, 4.0, -5.0]) > 2
```