> ## Documentation Index
> Fetch the complete documentation index at: https://cache-pot.thatdevguy.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Cache-Pot vector commands: VSET, VSEARCH, VDEL, VCARD, VDIM

> Store and search float32 vectors in Cache-Pot collections using cosine similarity. Full reference for VSET, VSEARCH, VDEL, VCARD, and VDIM commands.

Cache-Pot provides a built-in vector store. Use `VSET` to store float32 vectors in a named collection and `VSEARCH` to find the nearest neighbors by cosine similarity — no separate vector database, sidecar process, or plugin required. Vector collections are first-class Cache-Pot keys: they support TTL, appear in `KEYS` and `SCAN` output with type `vector`, and are included in snapshots and AOF replays.

***

### VSET

Stores a vector in a collection, inserting it if the `id` is new or replacing it if the `id` already exists.

**Syntax:** `VSET key id f1 f2 ... fn [META text]`

<ParamField query="key" type="string" required>
  The collection name. This is a standard Cache-Pot key of type `vector`. It is created automatically on the first `VSET`.
</ParamField>

<ParamField query="id" type="string" required>
  A unique identifier for this vector within the collection.
</ParamField>

<ParamField query="f1 f2 ... fn" type="float32..." required>
  The components of the vector. All values are parsed as float32. Every vector in a collection must have the same number of components; the dimension is fixed by the first `VSET` call on that collection.
</ParamField>

<ParamField query="META text" type="string">
  Optional metadata string stored alongside the vector. Retrieve it with `VSEARCH`. Use it for human-readable labels, JSON payloads, or any context you want returned with search results.
</ParamField>

```redis theme={null}
VSET docs intro 0.1 0.9 0.2 0.5 META "Introduction to ML"
VSET docs adv   0.8 0.1 0.7 0.3 META "Advanced neural nets"
# OK
```

**Returns:** `OK`. Returns an error if the vector dimension does not match the collection's fixed dimension, or if any component cannot be parsed as a float.

***

### VSEARCH

Searches a vector collection for the nearest neighbors to a query vector using cosine similarity.

**Syntax:** `VSEARCH key f1 f2 ... fn [TOPK k] [WITHSCORES]`

<ParamField query="key" type="string" required>
  The collection to search.
</ParamField>

<ParamField query="f1 f2 ... fn" type="float32..." required>
  The query vector. Must have the same dimension as the collection.
</ParamField>

<ParamField query="TOPK k" type="integer">
  Return at most `k` results, sorted by descending similarity. Defaults to `10`. Must be a positive integer.
</ParamField>

<ParamField query="WITHSCORES" type="flag">
  When present, include the cosine similarity score (as a decimal string) for each result.
</ParamField>

```redis theme={null}
VSEARCH docs 0.15 0.85 0.18 0.55 TOPK 5 WITHSCORES
# Returns a flat array:
# 1) "intro"
# 2) "Introduction to ML"
# 3) "0.9981"
# 4) "adv"
# 5) "Advanced neural nets"
# 6) "0.6210"
```

**Returns:** A flat array. Without `WITHSCORES`, every two elements form an `[id, meta]` pair. With `WITHSCORES`, every three elements form an `[id, meta, score]` triple. Results are ordered from most similar to least similar.

<Note>
  Cosine similarity ranges from `0.0` (orthogonal) to `1.0` (identical direction). A score above `0.95` generally indicates a very strong semantic match.
</Note>

***

### VDEL

Removes a single vector from a collection by its identifier.

**Syntax:** `VDEL key id`

<ParamField query="key" type="string" required>
  The collection name.
</ParamField>

<ParamField query="id" type="string" required>
  The identifier of the vector to remove.
</ParamField>

```redis theme={null}
VDEL docs intro   # (integer) 1
VDEL docs intro   # (integer) 0  — already deleted
```

**Returns:** `1` if the vector was found and deleted; `0` if no vector with that `id` exists in the collection.

***

### VCARD

Returns the number of vectors currently stored in a collection.

**Syntax:** `VCARD key`

<ParamField query="key" type="string" required>
  The collection name.
</ParamField>

```redis theme={null}
VCARD docs   # (integer) 2
```

**Returns:** An integer count of vectors. Returns `0` if the key does not exist.

***

### VDIM

Returns the dimensionality of the vectors in a collection. The dimension is fixed when the first `VSET` is called on the collection.

**Syntax:** `VDIM key`

<ParamField query="key" type="string" required>
  The collection name.
</ParamField>

```redis theme={null}
VDIM docs   # (integer) 4
```

**Returns:** An integer representing the number of float32 components per vector.

***

## TTL on vector collections

Vector collections are standard Cache-Pot keys and support all key-expiry commands. Use this to automatically clean up time-bounded embeddings.

```redis theme={null}
VSET session:abc turn-1 0.3 0.7 0.1 META "User asked about billing"
EXPIRE session:abc 3600    # expire the whole collection after 1 hour
TTL session:abc            # check remaining time-to-live
```

<Tip>
  Apply `EXPIRE` immediately after creating a collection to prevent unbounded growth. This is especially useful for per-session or per-request embedding caches.
</Tip>