Skip to main content

cuVS SQL API (WIP)

DataFusion Nexus 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.

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 availability​

gpu_validate_call validates schemas and options; it is not a GPU-memory preflight. Until cuVS provides a bounded peak-memory preflight, the server rejects cuvs_* calls before relation children run with structured unsupported_operator; there is no CPU fallback or unadmitted GPU mode.

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 — use the bounded server contract and inspect availability through the GPU function catalog.
  • Configure the server — review per-device capacity and cache admission settings.