Pairwise Distance

SQL function: cuvs_pairwise_distance

Official cuVS reference: C API

Pairwise distance or similarity for every x and y vector row.

Quickstart

The call below expects the registered relations x_vectors (the x role) and y_vectors (the y role), each passed as a parenthesized SELECT subquery. Substitute your own relations and column names.

SELECT *
FROM cuvs_pairwise_distance(
  x => (SELECT id, d0, d1 FROM x_vectors),
  y => (SELECT id, d0, d1 FROM y_vectors),
  metric => 'l2_expanded'
)
ORDER BY x_ordinal, y_ordinal;

Inputs

Each relation argument is a parenthesized SELECT subquery that the planner keeps as a real child; metadata validation resolves a registered table or view for the same role instead. See Vector Inputs for the relation identity rules and the ID, dense-vector type, null, finite-value, and runtime-dimension contract.

Role	Required	Validation reference	Description
x	yes	table	Dense-vector rows on the first axis of the pairwise distance result.
y	yes	table	Dense-vector rows on the second axis of the pairwise distance result.

Vector element types

Element type	Valid metrics
Float32	l2_expanded, l2_sqrt_expanded, cosine, inner_product
Float64	l2_expanded, l2_sqrt_expanded, cosine, inner_product

Arguments and options

Scalar SQL arguments

Argument	Type	Required	Description
metric	enum ("l2_expanded", "l2_sqrt_expanded", "cosine", "inner_product")	yes	Distance metric; inner_product is a similarity where larger is closer.

SQL value argument schemas

Argument	Required	Literal shape	Default	Constraints	Description
metric	yes	string	No default	one of "l2_expanded", "l2_sqrt_expanded", "cosine", "inner_product"	Distance metric; inner_product is a similarity where larger is closer. Supported element/metric combinations: Float32: l2_expanded, l2_sqrt_expanded, cosine, inner_product; Float64: l2_expanded, l2_sqrt_expanded, cosine, inner_product.

Vector binding shapes

Each relation subquery must project a non-null id field followed by either one or more non-null feature fields of a supported element type (Float32, Float64) or one non-null list vector field named vector.

For wide vectors, the projection order defines the feature dimensions. A list vector relation must contain no feature field beside id and vector.

Output

Column	Type	Nullable	Description
x_ordinal	UInt64	no	Zero-based physical ordinal of the evaluated x row; it disambiguates duplicate x IDs.
x_id	same_as_x.id	no	Logical ID copied from the x relation.
y_ordinal	UInt64	no	Zero-based physical ordinal of the evaluated y row; it disambiguates duplicate y IDs.
y_id	same_as_y.id	no	Logical ID copied from the y relation.
distance	same_as_x.vector_element	no	Float32 for Float32 input, Float64 for Float64 input. Smaller is closer for distance metrics; inner_product prefers larger values.

Concrete schemas are call-specific. Run gpu_validate_call against registered relations to inspect the output schema after the actual ID types and literal options are validated.

Limits

• Validation resolves named tables or views and reads schemas only; it does not execute relation scans or GPU work.
• Execution relation arguments require parenthesized subqueries; dry-run validation accepts registered named relations only.
• Output rows equal x rows multiplied by y rows; the query allocation cap limits the result size.
• Empty x or y returns an empty result with the stable schema.
• x and y must share the same vector dimension and element type. inner_product is a similarity where larger is closer.

To dry-run validate relation metadata, column types, and options without execution, see gpu_validate_call.