Skip to main content

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.

RoleRequiredValidation referenceDescription
xyestableDense-vector rows on the first axis of the pairwise distance result.
yyestableDense-vector rows on the second axis of the pairwise distance result.

Vector element types​

Element typeValid metrics
Float32l2_expanded, l2_sqrt_expanded, cosine, inner_product
Float64l2_expanded, l2_sqrt_expanded, cosine, inner_product

Arguments and options​

Scalar SQL arguments​

ArgumentTypeRequiredDefaultConstraintsDescription
metricstringyesNo defaultone of "l2_expanded", "l2_sqrt_expanded", "cosine", "inner_product"Distance metric; inner_product is a similarity where larger is closer.

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​

ColumnTypeNullableDescription
x_ordinalUInt64noZero-based physical ordinal of the evaluated x row; it disambiguates duplicate x IDs.
x_idsame_as_x.idnoLogical ID copied from the x relation.
y_ordinalUInt64noZero-based physical ordinal of the evaluated y row; it disambiguates duplicate y IDs.
y_idsame_as_y.idnoLogical ID copied from the y relation.
distancesame_as_x.vector_elementnoFloat32 for Float32 input, Float64 for Float64 input. Smaller is closer for distance metrics; inner_product prefers larger values.

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.