Vector Top-K

SQL function: cuvs_top_k

Official cuVS reference: C++ API

Select the smallest or largest values in every dense vector row.

Quickstart

The call below expects the registered relation input_vectors (the input role), passed as a parenthesized SELECT subquery. Substitute your own relations and column names.

SELECT *
FROM cuvs_top_k(
  input => (SELECT id, d0, d1 FROM input_vectors),
  k => 1,
  select => 'max'
)
ORDER BY row_ordinal, rank;

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
input	yes	table	Dense-vector rows consumed by this operation.

Vector element types

Element type	Valid metrics
Float32	Not applicable

Arguments and options

Scalar SQL arguments

Argument	Type	Required	Description
k	integer	yes	Number of values selected from each row.
select	enum ("min", "max")	yes	Select the minimum or maximum values.

SQL value argument schemas

Argument	Required	Literal shape	Default	Constraints	Description
k	yes	integer	No default	minimum 1; maximum 4294967295	Number of values selected from each row.
select	yes	string	No default	one of "min", "max"	Select the minimum or maximum values.

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) 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
row_ordinal	UInt64	no	Zero-based physical ordinal of the evaluated input row; it disambiguates duplicate input IDs.
id	same_as_input.id	no	Logical ID copied from the input relation.
rank	UInt32	no	One-based value rank within an input row. Order consumers explicitly by row_ordinal, rank.
position	Int64	no	Zero-based dimension index of the selected value within the input vector.
value	Float32	no	Selected Float32 input vector value; rank follows ascending values for min and descending values for max.

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.
• k must not exceed the vector dimension. Empty input returns an empty result with the stable schema.
• Equal selected values are ordered by position; when ties straddle rank k, the selected positions among them are unspecified.

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