# cuVS CAGRA reference card

_This page covers the KDB-X cuVS CAGRA module APIs, including inputs, outputs, and examples for each function._

## Overview

The cuVS module exposes a `cagra` namespace with the following functions:

| **Function** | **Description** |
|---|---|
| [`.cuvs.cagra.init`](#cuvscagrainit) | Create a new CAGRA index |
| [`cagra.insert`](#cagrainsert) | Build or extend the index with vectors |
| [`cagra.count`](#cagracount) | Count vectors in the index |
| [`cagra.search`](#cagrasearch) | Nearest-neighbor search |
| [`cagra.filter`](#cagrafilter) | Nearest-neighbor search with a boolean mask |
| [`cagra.write`](#cagrawrite) | Serialize the index to disk |
| [`cagra.read`](#cagraread) | Deserialize an index from disk |
| [`cagra.normalize`](#cagranormalize) | L2-normalize a list of vectors |

### Load the module
```q
.cuvs:use`kx.cuvs
```

> **Note**
>
> The cuVS CAGRA module operates on GPU-resident indexes represented as foreign objects returned by `.cuvs.cagra.init` or `cagra.read`.
>
---

## .cuvs.cagra.init

_Create a new CAGRA index_
```syntax
.cuvs.cagra.init params
```

Where `params` is a dictionary of index parameters (or `::` for all defaults), returns a CAGRA index foreign object.

The index is empty after creation – use [`cagra.insert`](#cagrainsert) to build it with vectors.

> **Note**
>
> Indexes created with `.cuvs.cagra.init` are in-memory and are not persisted automatically. They are lost when the process exits unless explicitly saved using [`cagra.write`](#cagrawrite).
>
### Index parameters

| **Parameter** | **Type** | **Default** | **Description** |
|---|---|---|---|
| `gpuid` | long | `0` | GPU device ID to use |
| `metric` | symbol | `` `L2 `` | Distance metric. One of `` `L2 ``, `` `CS ``, `` `IP ``. |
| `graph_degree` | long | `64` | Edges per node in the final graph. Core recall/memory trade-off. |
| `intermediate_graph_degree` | long | `128` | Graph degree before pruning. Must be ≥ `graph_degree`. |
| `build_algo` | symbol | `` `AUTO_SELECT `` | Graph build algorithm. One of `` `AUTO_SELECT ``, `` `IVF_PQ ``, `` `nn_descent ``. |
| `nn_descent_niter` | long | `20` | Number of iterations for `nn_descent` build. Ignored for other algorithms. |

> **Warning**
>
> `compression` and `graph_build_params` are not currently available – passing either will return a `'nyi` error.
>
```q
.cuvs:use`kx.cuvs

/ Create with all defaults
idx:.cuvs.cagra.init[::]

/ Create with explicit params
idx:.cuvs.cagra.init[`gpuid`metric`graph_degree`intermediate_graph_degree`build_algo`nn_descent_niter!(0;`L2;64;128;`IVF_PQ;20)]

/ Cosine similarity – vectors are L2-normalized internally at insert and search time
idx:.cuvs.cagra.init[`gpuid`metric!(0;`CS)]
```

---

## cagra.insert

_Build or extend the index with vectors_
```syntax
cagra.insert[index;vectors]
```

Where:

- `index` is a CAGRA index foreign object returned by `.cuvs.cagra.init` or `cagra.read`
- `vectors` is a list of float (`8h`) vectors of equal length

Returns the count of vectors inserted as a long.

On the **first call**, builds the full CAGRA graph. On **subsequent calls**, extends the existing graph incrementally.

> **Warning — Minimum dataset size**
>
> CAGRA requires at least `intermediate_graph_degree + 1` vectors before the index can be built (default minimum: 129). Inserting fewer vectors on the first call will cause a GPU memory fault and corrupt the CUDA context – all subsequent GPU operations will fail until the process is restarted. Accumulate a sufficient batch before the first insert, or use a lower `intermediate_graph_degree`.
>
> **Note**
>
> A minimum of 2 vectors is required on the first insert. The q wrapper enforces this with a `'Cagra index requires at least 2 vectors` error.
>
```q
dims:128
idx:.cuvs.cagra.init[`gpuid`metric`build_algo!(0;`L2;`IVF_PQ)]

/ Generate random float vectors
N:10000
vecs:{(x;y)#(x*y)?1e};
data:vecs[N;dims];
testVecs:data[answer:neg[nTest]?nTrain];

/ Build the index
cagra.insert[idx;data]
10000

/ Extend with additional vectors
data2:vecs[1000;dims];
cagra.insert[idx;data2]
1000
```

---

## cagra.count

_Count vectors in the index_
```syntax
cagra.count index
```

Where `index` is a CAGRA index foreign object, returns the number of vectors currently in the index as a long. Returns `0` for an empty (unbuilt) index.
```q
idx:.cuvs.cagra.init[enlist[`gpuid]!enlist 0]
.cuvs.cagra.count idx
0

vecs:{(x;y)#(x*y)?1e};
data:vecs[10000;128];
.cuvs.cagra.insert[idx;data]
10000
.cuvs.cagra.count idx
10000
```

---

## cagra.search

_Nearest-neighbor search_
```syntax
cagra.search[index;query;k;params]
```

Where:

- `index` is a CAGRA index foreign object
- `query` is a single float vector or a list of float vectors of length `dims`
- `k` is a long – the number of nearest neighbors to return
- `params` is a dictionary of search parameters (or `::` for all defaults)

Returns a table with columns `distances` and `neighbors` (0-based row indices into the index). For a single query vector, returns a single flattened result. For a batch, returns a list of results.

> **Note**
>
> `k` must not exceed `itopk_size` (default 64). Passing `k > itopk_size` returns a `'value` error. To retrieve more than 64 neighbors, set `itopk_size` accordingly in `params`.
>
> **Warning**
>
> Searching an empty (unbuilt) index returns a `'empty` error.
>
### Search parameters

| **Parameter** | **Type** | **Default** | **Description** |
|---|---|---|---|
| `max_queries` | long | `0` | Max concurrent queries (batch size). `0` = auto-select. |
| `itopk_size` | long | `64` | Internal candidate list size. Primary recall/speed trade-off. Max 512 for `SINGLE_CTA`. |
| `max_iterations` | long | `0` | Upper limit on search iterations. `0` = auto. |
| `algo` | symbol | `` `SINGLE_CTA `` | Search parallelism strategy. One of `` `SINGLE_CTA ``, `` `MULTI_CTA ``, `` `MULTI_KERNEL ``, `` `AUTO ``. |
| `team_size` | long | `0` | CUDA threads per distance calculation. `0` = auto. Valid values: 4, 8, 16, 32. |
| `search_width` | long | `1` | Graph nodes explored in parallel per iteration. |
| `min_iterations` | long | `0` | Minimum search iterations to perform. |
| `thread_block_size` | long | `0` | CUDA thread block size. `0` = auto. |
| `hashmap_mode` | symbol | `` `HASH `` | Hashmap allocation strategy. One of `` `HASH ``, `` `SMALL ``, `` `AUTO_HASH ``. |
| `hashmap_min_bitlen` | long | `0` | Minimum bit length for hashmap. |
| `hashmap_max_fill_rate` | float | `0.5` | Maximum fill rate before hashmap rehash. |
| `num_random_samplings` | long | `1` | Number of random seed samples for graph traversal start points. |
| `rand_xor_mask` | long | `0x128394` | XOR mask for random seed generation. |
| `persistent` | boolean | `0b` | Enable persistent kernel mode. |
| `persistent_lifetime` | float | `2.0` | Lifetime (seconds) for persistent kernel. |
| `persistent_device_usage` | float | `1.0` | Fraction of GPU to dedicate to persistent kernel. |


> **Note**
>
> `SINGLE_CTA` is the default for small workloads, but `AUTO` is recommended for general use and larger batch sizes.
>
```q
dims:128;
vecs:{(x;y)#(x*y)?1e};
data:vecs[10000;dims];
idx:.cuvs.cagra.init[`gpuid`metric`build_algo!(0;`L2;`IVF_PQ)]
.cuvs.cagra.insert[idx;data]
10000

/ Single query – returns a flat table
q:dims?1e
.cuvs.cagra.search[idx;q;10;::]
distances  neighbors
--------------------
0.1234     42
0.2341     817
...

/ Batch query – returns a list of tables
qs:vecs[5;dims];
.cuvs.cagra.search[idx;qs;10;::]

/ Custom search params – higher recall
params:`itopk_size`algo!(128;`MULTI_CTA);
.cuvs.cagra.search[idx;q;10;params]

/ Full search params
params:`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);
.cuvs.cagra.search[idx;q;10;params]
```

---

## cagra.filter

_Nearest-neighbor search with a boolean mask_
```syntax
cagra.filter[index;query;k;params;ids]
```

Where:

- `index` is a CAGRA index foreign object
- `query` is a single float vector or a list of float vectors of length `dims`
- `k` is a long – the number of nearest neighbors to return
- `params` is a dictionary of search parameters (or `::` for all defaults) – same parameters as [`cagra.search`](#cagrasearch)
- `ids` is a list of IDs to include of type `long`.

Returns the same structure as `cagra.search`, restricted to vectors that match the `ids`. Results with negative distances are filtered out automatically.

> **Note**
>
> `ids` must be a subset of the input vectors. 
>
```q
dims:10;
N:10000;
vecs:{(x;y)#(x*y)?1e};
data:vecs[N;dims];
idx:.cuvs.cagra.init[`gpuid`metric`build_algo!(0;`L2;`IVF_PQ)];
.cuvs.cagra.insert[idx;data];
10000

/ Allow only the first 5000 vectors
ids:til 5000;
q:dims?1e
.cuvs.cagra.filter[idx;q;10;::;ids]
distances  neighbors
--------------------
0.1891     312
0.2104     1204
...

/ All results will have neighbors < 5000
```

---

## cagra.write

_Serialize the index to disk_
```syntax
cagra.write[index;path]
```

Where:

- `index` is a CAGRA index foreign object
- `path` is a symbol or string file path (without extension)

Writes two files to disk: `<path>.cagra` (the binary index) and `<path>.kdb` (index metadata including build parameters and GPU ID).

> **Note**
>
> Both files are required to reload the index with `cagra.read`. Do not delete or rename one without the other.
>
```q
.cuvs.cagra.write[idx;`:myindex]
/ Writes: myindex.cagra and myindex.kdb

.cuvs.cagra.write[idx;"myindex"]
/ Equivalent using a string path
```

---

## cagra.read

_Deserialize an index from disk_
```syntax
cagra.read[path;gpuid]
```

Where:

- `path` is a symbol or string file path used when saving (without extension)
- `gpuid` is a long specifying the GPU device to load onto, or `::` to use the GPU ID stored in the index metadata

Returns a CAGRA index foreign object ready for search.

> **Note**
>
> Both `<path>.cagra` and `<path>.kdb` must exist. If either is missing, a `'os` error is returned.
>
> **Warning**
>
> Specifying a `gpuid` that does not exist on the current system returns an error. If the stored GPU ID is no longer valid (e.g. loading on a different machine), pass an explicit `gpuid` override.
>
```q
/ Load onto the GPU stored in metadata
idx:.cuvs.cagra.read[`:myindex;::]

/ Load onto a specific GPU
idx:.cuvs.cagra.read[`:myindex;0]

/ Use immediately after loading
.cuvs.cagra.count idx
10000
.cuvs.cagra.search[idx;dims?1e;10;::]
```

---

## cagra.normalize

_L2-normalize a list of vectors_
```syntax
cagra.normalize x
```

Where `x` is a list of numeric vectors (types `5h`–`9h`), returns a list of real (`8h`) vectors each L2-normalized to unit length.

> **Note**
>
> When `metric:``CS`` (Cosine Similarity) is passed to `.cuvs.cagra.init`, vectors are normalized automatically at insert and search time. Use `cagra.normalize` explicitly only when you need to pre-normalize vectors for other purposes or when using `metric:``IP``.
>
```q
vecs:(1 0 0e; 0 1 0e; 1 1 0e)
.cuvs.cagra.normalize vecs
1          0          0e
0          1          0e
0.7071068  0.7071068  0e

/ Each result vector has unit length
sqrt sum each {x*x} each .cuvs.cagra.normalize vecs
1 1 1e
```

---

## Next steps

- Explore the [cuVS Examples](./examples.md) page for end-to-end usage including index tuning, VRAM planning, and search performance.
- Visit [Troubleshooting Errors](./troubleshooting-errors.md) if you encounter issues.
- Check the [cuVS Release Notes](./release-notes/changelog.md) for version history and fixes.
