Vector Search

Lux includes native HNSW-based vector search with cosine similarity, metadata filtering, and TTL support. There are no extensions to install, no modules to load, and no external dependencies. Vectors are a first-class data type, stored alongside your keys, hashes, and time series in a single process.

VSET

Store a vector with an optional JSON metadata payload and TTL. The first time you write to a vector key, Lux creates an HNSW index scoped to that key. All vectors under the same key must share the same dimensionality.

VSET key id dims val1 val2 ... valN [META json] [EX seconds | PX milliseconds]

key is the index name, id is a unique identifier within that index, and dims is the vector dimensionality (for example 384, 768, or 1536). The remaining positional arguments are the float values of the vector itself.

The META option attaches arbitrary JSON metadata to the vector. This metadata is stored alongside the vector and can be used for filtering during search. The EX and PX options set a TTL on the individual vector entry. Expired vectors are automatically removed from the index.

127.0.0.1:6379> VSET embeddings doc1 3 0.1 0.2 0.3 META '{"source":"wiki","topic":"physics"}' EX 3600
OK
127.0.0.1:6379> VSET embeddings doc2 3 0.4 0.5 0.6 META '{"source":"arxiv","topic":"math"}'
OK

VGET

Retrieve a stored vector by its ID. Returns the dimensionality, the vector values, and any attached metadata.

VGET key id

127.0.0.1:6379> VGET embeddings doc1
1) (integer) 3
2) 1) "0.1"
   2) "0.2"
   3) "0.3"
3) {"source":"wiki","topic":"physics"}

VSEARCH

Find the K nearest neighbors to a query vector using cosine similarity. Results are returned in order of decreasing similarity, each with its ID and similarity score. Use the FILTER option to restrict results by metadata fields, and the META flag to include each result's full metadata in the response.

VSEARCH key dims val1 val2 ... valN K count [FILTER json] [META]

127.0.0.1:6379> VSEARCH embeddings 3 0.1 0.25 0.35 K 5 META
1) 1) "doc1"
   2) "0.9987"
   3) {"source":"wiki","topic":"physics"}
2) 1) "doc2"
   2) "0.9821"
   3) {"source":"arxiv","topic":"math"}

127.0.0.1:6379> VSEARCH embeddings 3 0.1 0.25 0.35 K 5 FILTER '{"source":"wiki"}'
1) 1) "doc1"
   2) "0.9987"

VCARD

Returns the total number of vectors stored in an index.

127.0.0.1:6379> VCARD embeddings
(integer) 2

Performance

HNSW search is sublinear, so latency scales well as the index grows. Benchmarks on a single core:

SDK Example

The TypeScript SDK provides typed methods for all vector operations.

import Lux from "@luxdb/sdk";

const lux = new Lux("lux://127.0.0.1:6379");

await lux.vset("embeddings", "doc1", [0.1, 0.2, 0.3], {"'{'"}
  meta: {"'{'"} source: "wiki", topic: "physics" {"'}'"},
  ex: 3600,
{"'}'"});

const vector = await lux.vget("embeddings", "doc1");
// {"'{'"} dims: 3, values: [0.1, 0.2, 0.3], meta: {"'{'"} source: "wiki", topic: "physics" {"'}'"}  {"'}'"}

const results = await lux.vsearch("embeddings", [0.1, 0.25, 0.35], {"'{'"}
  k: 5,
  filter: {"'{'"} source: "wiki" {"'}'"},
  meta: true,
{"'}'"});
// [{"'{'"} id: "doc1", score: 0.9987, meta: {"'{'"} source: "wiki", topic: "physics" {"'}'"}  {"'}'"} ]

Use Cases

Vectors in Lux are designed for workloads where embedding storage and search live alongside your operational data. Common patterns include:

• Agent memory - Store conversation embeddings and retrieve relevant context for LLM agents without a separate vector database.
• RAG pipelines - Chunk documents, embed them, and search at query time. Metadata filtering lets you scope results by source, date, or user.
• Semantic search - Power search-as-you-type with vector similarity instead of keyword matching.
• Recommendations - Embed items and users into the same space, then use VSEARCH to find the nearest items for a given user vector.