Metadata Basics
Every vector stored with VADD can carry arbitrary metadata as key-value string pairs. Internally, Cachee stores this as a Rust HashMap<String, String> alongside the vector in the HNSW index. There is no enforced maximum size per field, per entry, or per key.
The command format accepts metadata after the METADATA keyword:
Each metadata field is a string key mapped to a string value. You can store serialized JSON, base64-encoded binary, UUIDs, timestamps, or any other string-representable data. The only constraint is system memory.
Metadata lives in the same process memory as the HNSW graph but is structurally separate from the vector data. The graph traversal algorithm never reads metadata during neighbor selection, so metadata size has zero impact on search latency.
Performance Impact by Size
The table below summarizes behavior at common metadata sizes. The critical takeaway: VSEARCH latency is constant regardless of metadata payload.
| Metadata Size | Works? | Memory Impact | VSEARCH Impact | Filter Impact |
|---|---|---|---|---|
| UUID (36 bytes) | Yes | Negligible | Zero | Zero |
| Small JSON (1 KB) | Yes | Negligible | Zero | Zero |
| Medium payload (12 KB) | Yes | Plan for it | Zero | Zero |
| ZK-STARK proof (45-200 KB) | Yes, but use tiered approach | Significant | Zero | Zero |
VSEARCH impact remains at zero across all sizes because the HNSW graph traversal only operates on Vec<f32> vector data. Metadata is never touched during neighbor selection or distance computation.
Why Metadata Doesn't Affect Search Speed
Cachee's HNSW implementation keeps a strict separation between the graph structure (vector coordinates, neighbor lists) and attached metadata. During a VSEARCH query, the engine performs three distinct phases:
- Graph traversal — navigates HNSW layers using only
Vec<f32>vectors. Distance calculations (cosine, L2, dot product) touch raw float arrays only. Metadata is not loaded, not dereferenced, not part of the hot path. - Filter evaluation — if a
FILTERclause is present, the engine does a singleHashMaplookup on the specified field and a string comparison. This is O(1) per candidate vector, regardless of how many other metadata fields exist on that entry. - Result construction — once the top-K results are identified, metadata is cloned into the response. This is a post-search operation that does not affect the search time reported in benchmarks.
The 0.0015ms search latency you see in benchmarks is unaffected whether metadata per vector is 36 bytes or 200 KB. The cost of metadata only manifests as memory consumption and, for very large payloads, response serialization time after the search completes.
Memory Planning
While metadata does not affect search performance, it does consume heap memory. For capacity planning, calculate the total memory footprint as the sum of vector storage and metadata storage.
100K Vectors (768 dimensions)
1M Vectors (768 dimensions)
When total metadata exceeds vector storage, you are likely storing data that belongs in a separate cache key rather than inline metadata. See the two-tier pattern below.
Best Practice: Two-Tier Pattern for Large Payloads
For payloads exceeding 10 KB — ZK-STARK proofs, serialized ML model weights, large JSON documents, binary blobs — the recommended approach is to store lightweight metadata in VADD and the full payload as a separate cache key.
This pattern keeps the HNSW index lean — more vectors fit in memory, neighbor lists stay cache-friendly — while the full payloads still live in-process at sub-microsecond read latency via standard GET. Both operations share the same Cachee process. No network hops, no external storage.
ZK-STARK Specific Guidance
ZK-STARK proofs are a common large-payload use case. A typical STARK proof is 45-200 KB depending on the circuit complexity and number of trace columns. Here is the recommended storage strategy:
- VADD metadata (~500 bytes): Store the proof hash, verification status, circuit ID, prover identity, and timestamp as metadata fields. These are the fields you will filter and search on.
- Cache key (full proof): Store the complete serialized proof as a separate key using
SET. Reference it from metadata via the proof hash. - Search pattern: Use
VSEARCHto find semantically related proofs (same circuit family, similar constraint structure), thenGETthe full proof for verification or aggregation. - Cache hit rates: STARK proofs are immutable once generated. Expect 90%+ cache hit rates for proof lookups, making this pattern extremely efficient for verification pipelines and recursive proof composition.
For deeper coverage of Cachee's ZK integration capabilities, see the ZKP feature page.
Metadata Filtering
The FILTER clause in VSEARCH lets you constrain results by any metadata field. Because metadata is stored as a HashMap, field lookup is O(1) — constant time regardless of how many metadata fields exist on a given vector entry.
Adding more metadata fields to a vector entry does not slow down filtering. Only the field specified in the FILTER clause is evaluated. An entry with 3 metadata fields and an entry with 50 metadata fields have identical filter performance.
Filters are evaluated during HNSW traversal, not as a post-processing step. This means filtered results respect the top-K constraint correctly — you always get K results that match both the vector similarity and the filter condition, not K results filtered down to fewer matches.