Skip to main content
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]
​
string
required
The collection name. This is a standard Cache-Pot key of type vector. It is created automatically on the first VSET.
​
string
required
A unique identifier for this vector within the collection.
​
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.
​
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.
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]
​
string
required
The collection to search.
​
float32...
required
The query vector. Must have the same dimension as the collection.
​
integer
Return at most k results, sorted by descending similarity. Defaults to 10. Must be a positive integer.
​
flag
When present, include the cosine similarity score (as a decimal string) for each result.
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.
Cosine similarity ranges from 0.0 (orthogonal) to 1.0 (identical direction). A score above 0.95 generally indicates a very strong semantic match.

​
VDEL

Removes a single vector from a collection by its identifier. Syntax: VDEL key id
​
string
required
The collection name.
​
string
required
The identifier of the vector to remove.
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
​
string
required
The collection name.
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
​
string
required
The collection name.
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.
Apply EXPIRE immediately after creating a collection to prevent unbounded growth. This is especially useful for per-session or per-request embedding caches.