CAGRA

SQL function: cuvs_cagra

Official cuVS reference: C API

Query-local graph approximate nearest-neighbor search.

Quickstart

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

SELECT *
FROM cuvs_cagra(
  dataset => (SELECT id, d0, d1 FROM dataset_vectors),
  queries => (SELECT id, d0, d1 FROM query_vectors),
  k => 8,
  metric => 'l2_expanded',
  graph_degree => 32,
  intermediate_graph_degree => 64
)
ORDER BY query_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
dataset	yes	table	Dense-vector rows indexed for nearest-neighbor search.
queries	yes	table	Dense-vector query rows matched against the evaluated dataset.

Vector element types

Element type	Valid metrics
Float32	l2_expanded, inner_product, cosine
Int8	l2_expanded, inner_product, cosine
UInt8	l2_expanded, inner_product, cosine

Arguments and options

Scalar SQL arguments

Argument	Type	Required	Description
k	integer	yes	Number of neighbors returned for each evaluated query row.
metric	enum ("l2_expanded", "inner_product", "cosine")	no	Distance or score metric; native default l2_expanded. inner_product ranks higher scores first.
graph_degree	integer	no	Output graph degree; native default 64. Must be less than dataset rows.
intermediate_graph_degree	integer	no	Build graph degree; native default 128. Must exceed graph_degree and be less than dataset rows.
build_algo	enum ("ivf_pq", "nn_descent")	no	Graph construction algorithm; native default ivf_pq. nn_descent does not support cosine.
itopk_size	integer	no	Intermediate search results; native default 64. Must be at least k.
search_width	integer	no	Starting graph nodes per iteration; native default 1.
max_iterations	integer	no	Maximum search iterations; native default 0 selects automatically.
search_algo	enum ("auto", "single_cta", "multi_cta", "multi_kernel")	no	Search kernel; auto is set explicitly (the native zero-initialized default is single_cta).

SQL value argument schemas

Argument	Required	Literal shape	Default	Constraints	Description
build_algo	no	string	"ivf_pq"	one of "ivf_pq", "nn_descent"	Graph construction algorithm; native default ivf_pq. nn_descent does not support cosine.
graph_degree	no	integer	64	minimum 1; maximum 4294967295	Output graph degree; native default 64. Must be less than dataset rows.
intermediate_graph_degree	no	integer	128	minimum 1; maximum 4294967295	Build graph degree; native default 128. Must exceed graph_degree and be less than dataset rows.
itopk_size	no	integer	64	minimum 1; maximum 4294967295	Intermediate search results; native default 64. Must be at least k.
k	yes	integer	No default	minimum 1; maximum 4294967295	Number of neighbors returned for each evaluated query row.
max_iterations	no	integer	0	minimum 0; maximum 4294967295	Maximum search iterations; native default 0 selects automatically.
metric	no	string	"l2_expanded"	one of "l2_expanded", "inner_product", "cosine"	Distance or score metric; native default l2_expanded. inner_product ranks higher scores first. Supported element/metric combinations: Float32: l2_expanded, inner_product, cosine; Int8: l2_expanded, inner_product, cosine; UInt8: l2_expanded, inner_product, cosine.
search_algo	no	string	"auto"	one of "auto", "single_cta", "multi_cta", "multi_kernel"	Search kernel; auto is set explicitly (the native zero-initialized default is single_cta).
search_width	no	integer	1	minimum 1; maximum 4294967295	Starting graph nodes per iteration; native default 1.

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, Int8, UInt8) 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
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 and destroys a query-local graph and padded dataset within the statement; no index persists across statements.
• Approximate search may return fewer than k neighbors; missing (query, rank) rows are omitted and valid ranks remain contiguous.
• The dataset must be non-empty, k and intermediate_graph_degree must be less than or equal to its row count, and graph_degree must be less than intermediate_graph_degree.
• k must not exceed itopk_size. single_cta requires itopk_size no greater than 1024. cosine cannot use nn_descent.
• Dataset and query dimensions and element types must match.

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