Skip to main content

cuVS SQL API (WIP)

Algeon exposes NVIDIA RAPIDS cuVS as SQL table functions over DataFusion SQL sessions — the same pattern already used by the cuGraph SQL API. Each cuvs_* function reads a relation of vectors, runs a GPU vector operation, and returns rows you can join and filter alongside the rest of your query, over the data already in your session — no separate vector store and no copy to keep in sync.

Three functions are available today: exact brute-force kNN (cuvs_brute_force_knn), KMeans clustering (cuvs_kmeans), and PCA (cuvs_pca). They execute on the GPU when the prerequisites in Execution are met. The surface is still work in progress: approximate indexes, persistent indexes, and other cuVS algorithms are not exposed yet, and the function list will grow.

The function registry, JSON schemas, and generated pages below come from the same live metadata API exposed to embedded and Flight SQL clients.

Vector input and call shape​

Every cuvs_* execution relation is a parenthesized SELECT subquery. The relation remains an explicit planner child, so it can use ordinary session tables, views, CTEs, Parquet scans, Iceberg tables, or a preceding SQL result. Bare table identifiers and quoted table-name strings are not execution inputs.

For metadata-only validation, gpu_validate_call instead resolves a named registered table or view and checks its schema without scanning rows or invoking the GPU. Vector Inputs documents relation identity, dense-vector binding shapes, and the validation-versus-runtime boundary.

Functions​

Start with Functions to choose vector search, clustering, or dimensionality reduction by its one-statement lifecycle. Every function page links back to Vector Inputs for the shared input contract.

Discovery and validation​

Use Discover & Validate GPU Functions for the shared list, describe, validate, and execute workflow. The detailed column and request schemas are in the GPU Function Catalog API.

Execution​

Use functions-only execution to keep input subqueries and surrounding SQL on DataFusion CPU while vector operations run on GPU. That mode retains the prerequisites below and uses bounded, non-spilling host staging for CPU inputs.

A cuvs_* call runs on the GPU when all of the following hold:

  1. the binary was built with the cuvs feature (otherwise every call returns a structured required_feature_disabled error, and gpu_list_functions reports the family as unavailable);
  2. the session installed cuVS SQL: embedded sessions chain try_with_cuvs_sql() as shown in DataFusion Session, and the Flight SQL server installs it on every session it builds;
  3. a AlgeonGpuBackend is installed, because execution needs an admitted query memory domain.

gpu_validate_call validates schemas and options without scanning relations or executing GPU work. At runtime, cuvs_* calls use the admitted query memory domain, and its allocator enforces the configured cap; an input that does not fit that cap fails with a typed allocation error rather than spilling.

cuVS SQL also has no persistent cross-statement cache for brute-force indexes, KMeans models, PCA transforms, or result relations. Each call creates the vector artifacts needed by that evaluated statement only: exact kNN builds its index, KMeans fits its model, and PCA fits and transforms its input.

The server's source and graph caches do not cache cuVS artifacts. See Cache Design and Configuration for their separate bounded server requirements.

Next steps​

  • Integrate cuVS — pick an embedded session or the Flight SQL server, then confirm availability with gpu_list_functions.
  • Configure the server — set the per-device memory cap that each call runs inside.