If you’ve used ChatGPT, Google, or any modern recommendation system, you’ve used vector search — even if you didn’t know it. It’s the technology that lets machines find “similar” pieces of text, images, or data, not just exact keyword matches.
In this guide, we’ll build a working vector search engine from scratch using pure Python — no sklearn, no faiss, no external embedding APIs. Just re, math, and collections from the standard library. By the end, you'll understand exactly what's happening under the hood before you ever plug in a library.
This post originally appeared on Code Magnet — head there for the full formatted version with the downloadable code.
Vector search works by converting text into a list of numbers (a “vector”) that captures something about its meaning or content. Similar pieces of text end up with similar vectors. To search, you convert your query into a vector too, then find which documents have the closest vectors using a similarity measure.
We’ll use two classic building blocks:
First, we need some text to search through, and a way to break sentences into words (tokens).
python
import reimport mathfrom collections import Counter
documents = [ "Python is a popular programming language for data science", "Machine learning models require large amounts of training data", "Vector search helps find similar documents using embeddings", "Data science uses Python and statistics to analyze data", "Search engines use vectors to rank relevant documents", "Deep learning is a subset of machine learning using neural networks",]
python
def tokenize(text): text = text.lower() return re.findall(r"[a-z]+", text)
Every unique word across all documents becomes part of our vocabulary. Each document will eventually be represented as a vector of numbers — one number per vocabulary word.
python
def build_vocabulary(docs): vocab = set() for doc in docs: vocab.update(tokenize(doc)) return sorted(vocab)
This is the core of our engine. TF-IDF gives more weight to words that are frequent in a specific document but rare across the whole collection — these words are usually the most meaningful ones.
python
class TFIDFVectorizer: def __init__(self): self.vocab = [] self.idf = {}
python
def fit(self, docs): self.vocab = build_vocabulary(docs) n_docs = len(docs) df = Counter() for doc in docs: for word in set(tokenize(doc)): df[word] += 1 for word in self.vocab: self.idf[word] = math.log(n_docs / (1 + df[word])) + 1 return self
python
def transform(self, docs): vectors = [] for doc in docs: tokens = tokenize(doc) tf = Counter(tokens) total = len(tokens) vector = [(tf[w] / total if total else 0) * self.idf.get(w, 0) for w in self.vocab] vectors.append(vector) return vectors
python
def fit_transform(self, docs): self.fit(docs) return self.transform(docs)
What’s happening here:
Once documents are vectors, we need a way to measure how similar two vectors are. Cosine similarity measures the angle between two vectors — it returns 1 for identical direction, 0 for no similarity.
python
def cosine_similarity(vec_a, vec_b): dot = sum(a * b for a, b in zip(vec_a, vec_b)) mag_a = math.sqrt(sum(a * a for a in vec_a)) mag_b = math.sqrt(sum(b * b for b in vec_b)) if mag_a == 0 or mag_b == 0: return 0.0 return dot / (mag_a * mag_b)
Now we wrap everything into a VectorSearchEngine class that can index documents and search them.
python
class VectorSearchEngine: def __init__(self): self.vectorizer = TFIDFVectorizer() self.doc_vectors = [] self.documents = []
python
def index(self, docs): self.documents = docs self.doc_vectors = self.vectorizer.fit_transform(docs) print(f"Indexed {len(docs)} documents.") print(f"Vocabulary size: {len(self.vectorizer.vocab)} unique words\n")
python
def search(self, query, top_k=3): query_vector = self.vectorizer.transform([query])[0] scores = [(i, cosine_similarity(query_vector, dv)) for i, dv in enumerate(self.doc_vectors)] scores.sort(key=lambda x: x[1], reverse=True) results = scores[:top_k]
print(f"Query: '{query}'") print("-" * 60) for rank, (idx, score) in enumerate(results, 1): print(f"Rank {rank} | Score: {score:.4f}") print(f" Document: {self.documents[idx]}") print() return results
Let’s index our sample documents and run a few searches:
python
engine = VectorSearchEngine()engine.index(documents)
engine.search("machine learning and neural networks")engine.search("python for data analysis")engine.search("finding similar documents with vectors")
Indexed 6 documents.Vocabulary size: 39 unique words
Query: 'machine learning and neural networks'------------------------------------------------------------Rank 1 | Score: 0.6070 Document: Deep learning is a subset of machine learning using neural networksRank 2 | Score: 0.2307 Document: Machine learning models require large amounts of training dataRank 3 | Score: 0.1732 Document: Data science uses Python and statistics to analyze data
Query: 'python for data analysis'------------------------------------------------------------Rank 1 | Score: 0.5456 Document: Python is a popular programming language for data scienceRank 2 | Score: 0.3838 Document: Data science uses Python and statistics to analyze dataRank 3 | Score: 0.1138 Document: Machine learning models require large amounts of training data
Query: 'finding similar documents with vectors'------------------------------------------------------------Rank 1 | Score: 0.3845 Document: Vector search helps find similar documents using embeddingsRank 2 | Score: 0.3845 Document: Search engines use vectors to rank relevant documentsRank 3 | Score: 0.0000 Document: Python is a popular programming language for data science
Notice something interesting in the last result: the third-ranked document scores 0.0000. That’s because our third document shares zero vocabulary words with the query — TF-IDF cosine similarity is purely lexical (word-based), not semantic. It has no idea that “vectors” and “programming language” could ever be related in meaning; it only counts shared words.
This from-scratch engine is great for learning, but it has real limits worth knowing before you use it in production:
Originally published at codemagnet.in, where I write about Python, data science, and practical coding tutorials.
How to Build Vector Search from Scratch in Python: Complete Beginner-Friendly Guide was originally published in Dev Genius on Medium, where people are continuing the conversation by highlighting and responding to this story.