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

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"}'
);

Relation inputs

Every execution relation argument is a parenthesized SELECT subquery. The planner retains that relation as a real logical and physical child; a bare table identifier or quoted table-name string is rejected. Metadata validation instead uses a registered named table or view in its relation envelope.

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.

See Vector Inputs for the ID and dense-vector type, null, finite-value, and runtime-dimension contract.

Scalar arguments & JSON 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 schema

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.

Limitations & lifecycle

• Validation resolves named tables or views and reads schemas only; it does not execute relation scans or GPU work.
• Bounded cuVS execution is unavailable until the lower-level peak-memory preflight contract exists.
• 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 before running

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',
  '{"options":{"dataset":{"id":"item_id","vector":{"columns":["d0","d1"]}},"k":8,"metric":"l2_expanded","queries":{"id":"query_id","vector":{"columns":["d0","d1"]}}},"relations":{"dataset":{"table":"dataset_vectors"},"queries":{"table":"queries_vectors"}},"schema_version":1}'
);

See GPU Function Catalog API for the full gpu_validate_call contract.