cuVS SQL API

Algeon exposes NVIDIA RAPIDS cuVS as GPU UDTFs (user-defined table functions) in DataFusion SQL sessions. Each cuvs_* UDTF reads a relation of vectors, runs one GPU vector operation and returns rows the same query can join and filter. Exact and approximate nearest neighbors, pairwise distances, per-row top-k, KMeans and PCA are available, and each query execution builds its own index. The cuVS UDTFs index lists every function; Discover & Validate GPU UDTFs and the GPU UDTF Catalog API cover discovery and validation.

Questions to explore

Each question opens a captured example on its UDTF page. The examples read the demo investigations, which connect results to source records.

MerRec

The MerRec investigation builds 64-dimensional taste vectors for 2.08 million shoppers from their browsing, inside SQL.

• Which 5,000 shoppers should a Pokemon campaign reach? (cuvs_brute_force_knn between cugraph_personalized_pagerank and cuml_forest_predict)
• Does a Pokemon lookalike audience find new interest? (cuvs_brute_force_knn)
• Which neighbor matches survive approximate search? (cuvs_cagra, cuvs_ivf_flat, cuvs_ivf_pq against exact search, with recall measured in SQL)

Amazon Reviews

Electronics products and low-rating reviews from Amazon Reviews 2023, with 1,024-dimension BGE-M3 text embeddings computed before any SQL.

• Which travel headphones deserve a catalog review? (cuvs_brute_force_knn)
• Which products have a changed mix of low-rating reviews? (cuvs_kmeans)
• Which review themes describe each group of products? (cuvs_kmeans, cuvs_top_k)

EMBER2024

Extracted file features from EMBER2024. Classifier comparisons use 1.56M Win32 training files and 359,994 later test files. The separate challenge cohort contains 6,315 malicious files.

• Which earlier Win32 files make useful references for a new quarter? (cuvs_brute_force_knn, cuvs_cagra, cuvs_ivf_flat)
• How much histogram variation remains visible in two PCA dimensions? (cuvs_pca)
• Which high-scoring challenge files should an analyst review first? (cuml_forest_predict, cuvs_top_k)

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, or a preceding SQL result. Bare table identifiers and quoted table-name strings are not execution inputs. Vector Inputs documents relation identity, dense-vector binding shapes, and the validation-versus-runtime boundary.

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.

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 keeps nothing between query executions. Every index, KMeans model, PCA transform and result relation is local to one execution, and the server's source and graph caches do not cache cuVS artifacts. See Configuration for server cache configuration and bounded memory limits.

The GPU table functions design explains matrix packing, borrowed tensor lifetimes and output-buffer adoption when vector results feed further SQL operators.