Brute-force kNN

SQL function: cuvs_brute_force_knn

Exact brute-force nearest-neighbor search over dense vectors.

Signature

cuvs_brute_force_knn((dataset relation subquery), (queries relation subquery), options_json)

Quickstart

The call below expects the registered relations dataset_vectors (the dataset role) and queries_vectors (the queries role), each passed as a parenthesized SELECT subquery. Substitute your own relations and column names.

SELECT *
FROM cuvs_brute_force_knn(
  (SELECT item_id, d0, d1 FROM dataset_vectors),
  (SELECT query_id, d0, d1 FROM query_vectors),
  '{"dataset":{"id":"item_id","vector":{"columns":["d0","d1"]}},"queries":{"id":"query_id","vector":{"columns":["d0","d1"]}},"k":8,"metric":"l2_expanded"}'
);

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
dataset	yes	table	Dense-vector rows searched by the exact kNN operation.
queries	yes	table	Dense-vector query rows matched against the evaluated dataset.

Arguments and options

Scalar SQL arguments

Argument	Type	Required	Description
options_json	JSON string literal	yes	cuVS operation options and relation-column bindings

JSON options

Option	Required	JSON shape	Default	Constraints	Description
dataset	yes	object			Names the dataset ID column and one dense-vector binding shape.
k	yes	integer		minimum 1; maximum 4294967295	Number of neighbors returned for each evaluated query row.
metric	yes	string		one of "l2_expanded", "l2_sqrt_expanded", "cosine", "inner_product"	Distance or score metric. Distance metrics rank lower values first; inner product ranks higher values first.
queries	yes	object			Names the query ID column and one dense-vector binding shape.

Vector binding shapes

id: Non-null logical row ID column. IDs may repeat; result ordinals disambiguate physical rows.

Shape	JSON	Contract
Wide Float32 columns	{"vector":{"columns":["d0","d1"]}}	Ordered, unique non-null Float32 feature columns; order defines vector dimensions.
List column	{"vector":{"column":"embedding"}}	One non-null FixedSizeList<Float32, D>, List<Float32>, or LargeList<Float32> column.

Choose exactly one dense-vector binding shape.

Output

Column	Type	Nullable	Description
query_ordinal	UInt64	no	Zero-based ordinal of the evaluated query row; it disambiguates duplicate query IDs.
query_id	same_as_queries.id	no	Logical ID copied from the queries relation.
neighbor_ordinal	UInt64	no	Zero-based ordinal of the matched dataset row; it disambiguates duplicate dataset IDs.
neighbor_id	same_as_dataset.id	no	Logical ID copied from the matched dataset row.
rank	UInt32	no	One-based neighbor rank within a query. Order consumers explicitly by query_ordinal, rank.
distance	Float32	no	Metric value; smaller is better for distance metrics, while 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.
• Builds an exact query-local index over the evaluated dataset relation; it does not persist an ANN index or replace a vector database.
• The evaluated dataset must be non-empty and k must not exceed its row count. An empty query relation may return an empty result with the stable schema.
• Dataset and query vector dimensions must match after both relation children are evaluated.

Validate the call

Validation checks registered relation metadata, bindings, dtypes, and options without scanning rows or touching the GPU:

SELECT * FROM gpu_validate_call(
  'cuvs_brute_force_knn',
  '{"schema_version":1,"relations":{"dataset":{"table":"dataset_vectors"},"queries":{"table":"queries_vectors"}},"options":{"dataset":{"id":"item_id","vector":{"columns":["d0","d1"]}},"queries":{"id":"query_id","vector":{"columns":["d0","d1"]}},"k":8,"metric":"l2_expanded"}}'
);

See GPU Function Catalog API for the full gpu_validate_call contract.