Pairwise Distance
UDTF: 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.
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 an operator child. Metadata validation resolves a registered table or view for the same role. See Vector Inputs for the relation identity rules and the ID, dense-vector type, null, finite-value, and runtime-dimension contract.
Vector element types
Arguments and options
Scalar SQL arguments
Vector binding shapes
Each relation subquery must project an id field followed by either one or more feature fields of a supported element type (Float32, Float64) or one list field of a supported element type, under any name.
For wide vectors, the projection order defines the feature dimensions. A list vector relation must contain no feature field beside id and its list field. Nullable field types are accepted. A null ID, feature value, list row, or list element fails the query.
Output
The output schema depends on the call. Run gpu_validate_call against registered relations to inspect the schema that the validated ID types and literal options produce.
Limits
- 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.