# 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](./gpu-env.md).
2. KDB-X with the cuVS module installed. Refer to [Install KDB-X and the cuVS Module](./kdb-env.md).

## Verify GPU requirements

The cuVS module requires an NVIDIA GPU with CUDA support. Verify that your system meets the requirements:
```bash
nvidia-smi
```

Check the output:

1. **`nvidia-smi` not found?** NVIDIA drivers are not installed. [Install](https://www.nvidia.com/en-us/drivers/) 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](https://www.nvidia.com/en-us/drivers/).

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. Before proceeding, ensure you have completed the [Install KDB-X and the cuVS Module](./kdb-env.md) guide.

### Load the module
```q
.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:
```q
.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](../troubleshooting-errors.md).

## Next steps

- Explore the [cuVS Examples](../examples.md) page for more detailed usage including index tuning, VRAM planning, and search performance.
- Visit the [Troubleshooting Errors](../troubleshooting-errors.md) page if you encounter issues.
