Skip to content

skillData and AI

Vector Database Design

Chooses the index type, embedding dimensions, chunking and metadata filters for a vector store, with recall checked against a test set.

npx workspacetemplates add vector-database-design --tool claude-code

Writes 1 file to .claude/skills/vector-database-design/

.claude/skills/vector-database-design/SKILL.md27 lines · 1.6 KBFile
---
name: vector-database-design
description: Chooses the index type, embedding dimensions, chunking and metadata filters for a vector store, with recall checked against a test set.
---

# Vector database design

Decide from data size, query shape and filters, not from what a tutorial used.

## Steps

1. Ask or measure: number of vectors now and in a year, update rate, query rate, latency target, and which filters every query needs (tenant, language, date, access level).
2. Pick the embedding model first. Note its dimensions and max input length. Higher dimensions cost memory and speed; test whether a truncated or smaller variant keeps recall.
3. Chunk by meaning: split on headings and paragraphs, 200 to 500 tokens, with small overlap. Store the source ID, position and title with each chunk.
4. Choose the index. Under about 100k vectors, exact search is often fast enough and has perfect recall. Beyond that use HNSW for low latency, or IVF with quantization when memory is the limit. Write down the tuning parameters (for HNSW: M, efConstruction, efSearch).
5. Design metadata: only fields you filter on, indexed, with fixed types. Enforce tenant and permission filters inside the query, never after retrieval.
6. Build a test set of 30 to 100 real questions with known correct chunks. Measure recall at 5 and 10 against exact search.
7. Add hybrid search (keyword plus vector) when queries contain names, codes or rare terms.

## Rules

- Never mix embeddings from two models in one index.
- Store the model name and version with every vector so you can re-embed later.

## Report

The chosen design with reasons, the parameters, and the measured recall and latency.

What it does

Most vector search problems come from decisions made early and never measured: chunk size, which embedding model, which index. This skill walks the agent through each choice and ends with a recall number rather than a hunch.

It treats metadata filtering as a first-class design question, since filters decide both correctness and speed in production.

Example

you › Design the vector store for our help-center search, 40k articles, multi-tenant

agent › Recommended 300-token chunks, about 220k vectors, HNSW with efSearch 80, tenant_id and locale as indexed filters applied in-query. Recall@5 was 0.93 against exact search on 60 test questions; added keyword hybrid to lift product-code queries from 0.61 to 0.88.

Questions

Do I need a dedicated vector database?
Not always. A Postgres extension or a search engine with vector support handles many apps. Move to a dedicated store when scale or filtering needs outgrow it.
Why measure recall against exact search?
Approximate indexes trade accuracy for speed. Exact search gives the ceiling, so the gap shows what your index settings cost.
  • Data Pipeline Design

    SkillData and AI

    Free
  • dbt Modeling

    SkillData and AI

    Free