Quick answer: A vector database in Python stores data as mathematical embeddings (lists of numbers) and finds similar items by measuring distance between those vectors. You can build a working vector database in Python from scratch in under 200 lines of code β no third-party vector database library required. The core components are a cosine similarity function, an in-memory storage structure, and basic CRUD operations. This guide walks through every line.
Introduction
Every time you use ChatGPT with RAG, or search through a million images with a text query, or ask a document Q&A system a question, a vector database is doing the heavy lifting between your question and the relevant results.
Vector databases are the backbone of semantic search, recommendation systems, and modern AI retrieval. Services like Pinecone, Weaviate, and Chroma charge thousands of dollars a month for managed versions. But the core idea is simple enough that you can build a working version yourself in an afternoon.
This guide builds a production-style vector database from scratch in Python. Not a toy. A database with add, search, delete, persistent storage, and configurable distance metrics. You will understand exactly how embedding search works under the hood by the time you finish.
What a Vector Database Actually Does
A vector database stores pieces of data as points in a high-dimensional space. The key insight is that similar items have similar vectors. A sentence about cats is mathematically closer to another sentence about cats than it is to a sentence about accounting.
This vector database Python tutorial covers every layer: storage format, distance functions, insert and search operations, and optional file persistence.
Every vector database has four core operations. Insert a vector with an ID. Search for the nearest neighbors to a query vector. Delete a vector by ID. Update a vector by ID. That is it. Everything else is optimization.
The search operation is the hard part. A naive search compares the query vector against every stored vector, one by one. This works fine for a thousand vectors but breaks at a million. Real vector databases use approximate nearest neighbor algorithms (HNSW, IVF, PQ) to make search fast at scale. This guide builds the naive version first for correctness, then adds an HNSW index for speed.
Building the Core: Storage and Distance Functions
Start with the foundation. We need a way to store vectors and measure distance between them.
import numpy as np
import pickle
import os
from typing import List, Tuple, Optional, Dict, Any
class VectorStore:
"""A simple vector database with multiple distance metrics."""
def __init__(self, dimension: int, metric: str = "cosine"):
self.dimension = dimension
self.metric = metric
self.vectors: Dict[str, np.ndarray] = {} # id -> embedding
self.metadata: Dict[str, dict] = {} # id -> metadata dict
self.index: Optional[List[str]] = None # ordered list of ids
def _validate_vector(self, vector: List[float]) -> np.ndarray:
vec = np.array(vector, dtype=np.float32)
if vec.shape[0] != self.dimension:
raise ValueError(f"Expected dimension {self.dimension}, got {vec.shape[0]}")
return vec
def _distance(self, a: np.ndarray, b: np.ndarray) -> float:
if self.metric == "cosine":
norm_a = np.linalg.norm(a)
norm_b = np.linalg.norm(b)
if norm_a == 0 or norm_b == 0:
return 1.0
return 1.0 - np.dot(a, b) / (norm_a * norm_b)
elif self.metric == "euclidean":
return float(np.linalg.norm(a - b))
elif self.metric == "dot":
return -float(np.dot(a, b))
raise ValueError(f"Unknown metric: {self.metric}")The distance function is the heart of the system. Cosine similarity measures the angle between two vectors, ignoring their magnitude. Two documents on the same topic might have vectors pointing in similar directions even if one is much longer than the other. Euclidean distance measures straight-line distance, which captures magnitude differences. Dot product is useful when you care about raw similarity scores.
Cosine is the default because it works best for text embeddings from models like OpenAI’s text-embedding-ada-002 or Sentence Transformers.
Insert and Search Operations
With storage and distance ready, we can add the CRUD operations.
def insert(self, vector_id: str, vector: List[float],
metadata: Optional[Dict[str, Any]] = None) -> None:
"""Insert a vector with optional metadata."""
vec = self._validate_vector(vector)
self.vectors[vector_id] = vec
self.metadata[vector_id] = metadata or {}
def search(self, query_vector: List[float], k: int = 10
) -> List[Tuple[str, float, Dict[str, Any]]]:
"""Return top-k nearest neighbors with distances and metadata."""
query = self._validate_vector(query_vector)
distances = []
for vid, vec in self.vectors.items():
d = self._distance(query, vec)
distances.append((d, vid))
distances.sort(key=lambda x: x[0])
results = []
for d, vid in distances[:k]:
results.append((vid, float(d), self.metadata.get(vid, {})))
return results
def delete(self, vector_id: str) -> bool:
if vector_id in self.vectors:
del self.vectors[vector_id]
self.metadata.pop(vector_id, None)
return True
return False
def update(self, vector_id: str, vector: List[float],
metadata: Optional[Dict[str, Any]] = None) -> bool:
if vector_id in self.vectors:
self.vectors[vector_id] = self._validate_vector(vector)
if metadata is not None:
self.metadata[vector_id] = metadata
return True
return False
@property
def count(self) -> int:
return len(self.vectors)That is the entire core of a vector database. Sixty lines. Insert stores a vector. Search loops through everything, computes distances, sorts, and returns the closest ones. Delete and update remove or modify existing entries.
Let us test it with real embeddings.
# Test with Sentence Transformers
# pip install sentence-transformers
from sentence_transformers import SentenceTransformer
model = SentenceTransformer('all-MiniLM-L6-v2')
db = VectorStore(dimension=384, metric="cosine")
documents = [
"Python is a programming language used for web development and data science",
"Machine learning models learn patterns from training data",
"Vector databases store embeddings for semantic search",
"Neural networks are inspired by the human brain",
"Docker containers make deployment reproducible across environments"
]
for i, doc in enumerate(documents):
vec = model.encode(doc).tolist()
db.insert(f"doc_{i}", vec, {"text": doc})
query = "How do databases find similar content?"
query_vec = model.encode(query).tolist()
results = db.search(query_vec, k=3)
for vid, dist, meta in results:
print(f"{vid} (dist={dist:.4f}): {meta['text']}")The output will rank “Vector databases store embeddings for semantic search” as the closest match, followed by the Python and machine learning documents.
Adding Persistence
A database that forgets everything on restart is not useful. Let us add save and load.
def save(self, filepath: str) -> None:
data = {
"dimension": self.dimension,
"metric": self.metric,
"vectors": {k: v.tolist() for k, v in self.vectors.items()},
"metadata": self.metadata
}
with open(filepath, "wb") as f:
pickle.dump(data, f)
@classmethod
def load(cls, filepath: str) -> "VectorStore":
with open(filepath, "rb") as f:
data = pickle.load(f)
db = cls(data["dimension"], data["metric"])
for vid, vec in data["vectors"].items():
db.vectors[vid] = np.array(vec, dtype=np.float32)
db.metadata = data["metadata"]
return dbNow you can persist and reload your data.
db.save("my_vectors.pkl")
loaded = VectorStore.load("my_vectors.pkl")
print(f"Loaded {loaded.count} vectors")Making It Fast: Cosine Similarity with NumPy
Our naive search is O(n * d) where n is the number of vectors and d is the dimension. For 10,000 vectors at 384 dimensions, that is 3.8 million operations per search. Still fast on a laptop. But at 100,000 vectors, it starts to feel slow.
The first optimization is to vectorize the distance computation with NumPy. Instead of looping in Python, we compute all distances in a single matrix operation.
def search_batch(self, query_vector: List[float], k: int = 10
) -> List[Tuple[str, float, Dict[str, Any]]]:
query = self._validate_vector(query_vector)
if not self.vectors:
return []
ids = list(self.vectors.keys())
matrix = np.stack([self.vectors[vid] for vid in ids])
if self.metric == "cosine":
norms = np.linalg.norm(matrix, axis=1)
query_norm = np.linalg.norm(query)
if query_norm == 0:
return []
similarities = np.dot(matrix, query) / (norms * query_norm)
indices = np.argsort(-similarities)[:k]
elif self.metric == "euclidean":
diffs = matrix - query
distances = np.linalg.norm(diffs, axis=1)
indices = np.argsort(distances)[:k]
results = []
for idx in indices:
vid = ids[idx]
d = distances[idx] if self.metric == "euclidean" else float(1 - similarities[idx])
results.append((vid, d, self.metadata.get(vid, {})))
return resultsThis batch version runs 10 to 50 times faster than the loop version because NumPy pushes the computation down to compiled C code.
When Naive Search Is Not Enough
At around 100,000 vectors, even the batch search becomes noticeable. At a million vectors, it takes seconds per query. This is where approximate nearest neighbor (ANN) algorithms come in.
The most popular ANN algorithm for small to medium datasets is HNSW (Hierarchical Navigable Small World). It builds a multi-layer graph where the top layer has a few long-range connections for fast traversal, and lower layers have denser connections for fine-grained search.
Here is a minimal HNSW implementation.
import random
import math
class HNSWIndex:
"""Minimal HNSW index for approximate nearest neighbor search."""
def __init__(self, distance_func, M: int = 16, ef_construction: int = 200):
self.distance = distance_func
self.M = M
self.M_max = M
self.M_max0 = 2 * M
self.ef_construction = ef_construction
self.ef_search = 50
self.graphs: List[Dict[int, List[int]]] = [] # per layer: node -> neighbors
self.entry_point: Optional[int] = None
self.level_mult = 1.0 / math.log(M)
def _random_level(self) -> int:
return int(-math.log(random.random()) * self.level_mult)
def _search_layer(self, query_vec, entry, ef, layer):
visited = {entry}
candidates = [(self.distance(query_vec, entry), entry)]
result = [(self.distance(query_vec, entry), entry)]
while candidates:
current_d, current = candidates.pop(0)
furthest_d = max(result, key=lambda x: x[0])[0]
if current_d > furthest_d:
break
for neighbor in self.graphs[layer].get(current, []):
if neighbor not in visited:
visited.add(neighbor)
d = self.distance(query_vec, neighbor)
candidates.append((d, neighbor))
result.append((d, neighbor))
candidates.sort(key=lambda x: x[0])
result.sort(key=lambda x: x[0])
if len(result) > ef:
result = result[:ef]
return result
def insert(self, vector_id: int, vector):
level = self._random_level()
while len(self.graphs) <= level:
self.graphs.append({})
if self.entry_point is None:
self.entry_point = vector_id
for i in range(len(self.graphs)):
if i not in self.graphs:
self.graphs[i] = {}
self.graphs[i][vector_id] = []
curr_entry = self.entry_point
for layer in range(len(self.graphs) - 1, -1, -1):
result = self._search_layer(vector, curr_entry, 1, layer)
curr_entry = result[0][1]
if layer <= level:
result = self._search_layer(vector, curr_entry,
self.ef_construction, layer)
neighbors = [n for _, n in result[:self.M]]
self.graphs[layer][vector_id] = neighbors
for nid in neighbors:
max_edges = self.M_max if layer > 0 else self.M_max0
self.graphs[layer][nid] = self.graphs[layer].get(nid, [])
self.graphs[layer][nid].append(vector_id)
if len(self.graphs[layer][nid]) > max_edges:
# Prune to closest neighbors
nvec = vectors[nid] # assumed global for brevity
ranked = sorted(
[(self.distance(nvec, vectors[x]), x)
for x in self.graphs[layer][nid]],
key=lambda x: x[0]
)[:max_edges]
self.graphs[layer][nid] = [x for _, x in ranked]
if level > len(self.graphs) - 1:
self.entry_point = vector_idHNSW is complex but delivers search in milliseconds even with hundreds of thousands of vectors, with recall rates above 99 percent compared to brute force. Real vector databases like Qdrant and Weaviate use HNSW internally.
Putting It All Together: A Complete Application
Here is a working script that downloads a public dataset, generates embeddings, indexes them, and runs a search.
# Complete example: search Wikipedia article titles
from sentence_transformers import SentenceTransformer
import requests
# Sample data: 500 Wikipedia article titles
url = "https://raw.githubusercontent.com/brmson/dataset-sts/master/data/wiki-en/train.tsv"
response = requests.get(url)
titles = [line.split("\t")[0] for line in response.text.strip().split("\n")[:500]]
# Create database
model = SentenceTransformer('all-MiniLM-L6-v2')
db = VectorStore(dimension=384, metric="cosine")
for i, title in enumerate(titles):
vec = model.encode(title).tolist()
db.insert(f"wiki_{i}", vec, {"title": title})
print(f"Indexed {db.count} documents")
# Search
query = "artificial intelligence and neural networks"
query_vec = model.encode(query).tolist()
results = db.search(query_vec, k=5)
for vid, dist, meta in results:
print(f"{dist:.4f}: {meta['title']}")What Real Vector Databases Do Differently
Your database works for a few thousand vectors. Production vector databases add these features.
Disk-based storage. Vectors live on disk, not RAM. Only the working set is loaded into memory.
Sharding. Data is split across multiple machines or processes.
Hybrid search. Combining vector similarity with keyword matching (BM25) or metadata filters.
Streaming ingestion. New vectors can be added while searches are running.
Sparse vectors. For text data, sparse vectors with tens of non-zero values can be more efficient than dense vectors with hundreds.
Multi-tenancy. Separate namespaces for different users or applications.
Your implementation covers the core ideas. Everything else is engineering.
Frequently Asked Questions
A: A regular database (PostgreSQL, SQLite) finds exact matches on structured fields. A vector database finds semantically similar items using distance metrics. They solve different problems and are often used together.
A: Not for large datasets. It stores everything in RAM and uses brute force search. For a few thousand vectors it works fine. For production, use Chroma, Qdrant, Pinecone, or Weaviate.
A: Each model architecture produces a different size output. OpenAI’s text-embedding-ada-002 produces 1536-dimensional vectors. Sentence Transformers’ all-MiniLM-L6-v2 produces 384. The dimension is fixed by the model architecture.
A: Rough calculation. 100,000 vectors at 384 dimensions using float32 takes 100000 * 384 * 4 = 153MB for the data alone. Add metadata, Python overhead, and the HNSW graph, and you are at roughly 300MB.
A: Cosine similarity is the standard for text embeddings from most models. L2 normalization followed by dot product gives the same ranking as cosine but can be faster with certain hardware optimizations.
A: No. Vector search is memory-bound, not compute-bound. GPU acceleration helps for building the initial index but not for query time in most cases.
Conclusion
A vector database is surprisingly simple at its core. A distance function, a dictionary, and a loop. The complexity comes from making it fast at scale. But the fundamental insight, that you can find similar items by comparing vectors in a high-dimensional space, is accessible to any Python programmer.
Building one from scratch teaches you exactly what Pinecone and Chroma are doing under the hood. You trade raw performance for complete understanding. And for small projects, your implementation might be all you need.
Schema to implement on this page:
– Article schema (required)
– FAQPage schema (pull from the FAQ section above)
– BreadcrumbList schema (for site navigation)
This vector database Python implementation is intentionally minimal so you can extend it. Add an HTTP interface, connect it to an embedding API, or replace the in-memory store with a file-backed index.
Related: what is a vector database.
