cuVS Quickstart

This guide shows how to load the cuVS module, verify your GPU environment, and run a CAGRA-indexed vector search.

Setup

To use the cuVS module, you need:

1. A host with an NVIDIA GPU and driver version ≥ 580. Refer to GPU Environment Setup.
2. KDB-X with the cuVS module installed. Refer to Install KDB-X and the cuVS Module.

Verify GPU requirements

The cuVS module requires an NVIDIA GPU with CUDA support. Verify that your system meets the requirements:

nvidia-smi

Check the output:

1. nvidia-smi not found? NVIDIA drivers are not installed. Install them.
2. No GPU detected? If nvidia-smi runs but shows no GPU, the cuVS module will not work. CUDA cannot run on CPU-only systems.
3. Driver version: Ensure driver version ≥ 580. If less than 580, update your NVIDIA driver.

When all checks pass, proceed.

Basic usage

This example loads the cuVS module, creates a CAGRA-indexed table, inserts vectors, and runs a similarity search.

Set the library path

Before starting your KDB-X session, set the dependency path:

INSTALL_PATH="$HOME/miniforge3"
export LD_LIBRARY_PATH="${INSTALL_PATH}/lib:${LD_LIBRARY_PATH}"

$HOME/miniforge3 is the default installation path. If you chose a different directory when running install_deps.sh, update INSTALL_PATH accordingly. For more details, refer to Install dependencies.

Load the module

.cuvs:use`kx.cuvs

Note

The cuVS CAGRA module provides a GPU-resident, in-memory vector index. Indexes created with .cuvs.cagra.init are not persisted automatically and must be saved with cagra.write if you want to reuse them across sessions.

Typical workflow:

1. Create an index with .cuvs.cagra.init
2. Insert vectors using cagra.insert
3. Query with cagra.search or cagra.filter
4. Persist with cagra.write and reload with cagra.read if needed

Minimum example to test the module

Run this example to validate that cuVS is working correctly:

.cuvs:use`kx.cuvs;

scale:100;
nTrain:10000;
nTest:50;
dims:1024;
k:64; / i.e. the max of k is 64
GPUID:0;

/ train the data
vecs:{(x;y)#(x*y)?1e};
data:vecs[nTrain;dims];
testVecs:data[answer:neg[nTest]?nTrain];

/ define metric and build algorithm
metric:`CS;
build_algo:`nn_descent;

/ set cagra index parameters
cagraParams:(`metric`intermediate_graph_degree`graph_degree`build_algo`nn_descent_niter`gpuid)!(metric; 32; 32; build_algo; 20; GPUID);

/ define search parameters
paramsSearch:`max_queries`itopk_size`max_iterations`algo`team_size`search_width`min_iterations`thread_block_size`hashmap_mode`hashmap_min_bitlen`hashmap_max_fill_rate`num_random_samplings!(0; 64; 0; `SINGLE_CTA; 0; 1; 0; 0; `HASH; 0; 0.5; 1);

/ initialize the index
cagraIndex:.cuvs.cagra.init[cagraParams];

/ insert the data
resInsert:.cuvs.cagra.insert[cagraIndex;data];
resCount:.cuvs.cagra.count[cagraIndex];

/ perform a search
resSearch:.cuvs.cagra.search[cagraIndex;testVecs;k;paramsSearch];

show "count         check 1A - "        ,-3!c1A:resCount~nTrain;
show "accuracy      check 1B - "        ,-3!c1B:0.8<(sum resSearch[;1;0]=answer) % nTest;
show "distance      check 1C - "        ,-3!c1C:all all 0>={1_deltas x}each resSearch[;0];

/ Summary
result:(c1A; c1B; c1C);
testNames:("1A"; "1B"; "1C");
$[all result;
  [show "All tests passed with 1b.";
   exit 0];
  [show "These test(s) are failed: ",", " sv testNames[where not result];
   exit 1]];

All checks should pass if the environment is configured correctly.

If the tests above fail, refer to the Troubleshooting Guide.

Next steps

• Explore the cuVS Examples page for more detailed usage including index tuning, VRAM planning, and search performance.
• Visit the Troubleshooting Errors page if you encounter issues.