Glossary

113 terms from Embeddings and Vector Search, in plain words, each with the chapter that teaches it.

Search the glossary

#

@cache: A Python decorator from `functools` that remembers a function's result. In `kc.py` it makes the embedding model load only once.

A

all-MiniLM-L6-v2: A small, free embedding model that runs locally with sentence-transformers. It turns any text into a 384-number vector and reads at most 256 tokens, ignoring anything past that.
ANN (approximate nearest neighbor): Search that finds almost the true closest vectors much faster than checking all of them, by using an index. It occasionally misses a neighbor, which you measure as recall against exact search.
Apache 2.0 license: A permissive open-source license that allows commercial use of software and models. A model's license is listed on its Hugging Face page and should be checked before use.
argparse: A Python standard-library module that reads options and arguments typed after a script's name, such as `-k 3` or `--source product`. It checks them and prints a usage message on mistakes.
argsort: A NumPy function that returns the positions that would sort an array from smallest to largest. Sorting the negated scores puts the best matches first.

B

Batch API: OpenAI's option for sending many requests together and getting results within 24 hours, at half the normal price.
bi-encoder: An embedding model that embeds the query and each document separately. Documents can therefore be embedded ahead of time, which makes search fast.
binary plus rescoring: A way to save memory: pick about 100 candidates using tiny 1-bit codes, then re-score only those with the full-precision vectors kept on disk. This can recover the recall of an exact search while storing far less in memory.
blurring: What happens when one vector summarizes a long text about several topics: it becomes a bit about each and matches a focused question poorly. It is a reason to chunk documents.
BM25: The scoring formula behind most keyword search engines. It rewards words that appear often, counts rare words more, and discounts long documents, but knows nothing about meaning.
brute-force search: Search that compares the query with every single item. It is the simplest method and always finds the true best matches, and is usually enough up to about 100,000 vectors.

C

candidates (pool): The short list of results (20 to 100) that fast retrieval hands to a slower step such as a cross-encoder. In the project, `pool` sets how many each retriever returns.
CCPA: A California law that gives people a right to have their personal data deleted. Kettle & Crane promises deletion within 30 days, and it must reach every copy, including vectors and backups.
Chroma: An open-source vector database that can run inside your Python program and save to a folder, with no server needed. It uses HNSW and stores vectors, text and metadata together.
chunking: Cutting a long document into smaller pieces (chunks) and embedding each separately. This avoids truncation and blurring, and lets results point to the passage that answers the question.
collection: In Chroma, a named group of items that share one embedding model and one distance metric, like a table. Kettle & Crane's items live in a collection called `kettle_crane`.
cosine distance: One minus the cosine similarity, so smaller means closer. Chroma and pgvector report it, which is why a distance of 0.549 means a similarity of 0.451.
cosine similarity: A score for how alike two vectors' directions are: the dot product divided by both lengths. It is 1 for the same direction and near 0 for unrelated texts.
cross-encoder: A model that reads the query and one document together and outputs a relevance score. It is more accurate than comparing embeddings but must run once per pair, so it only reranks a short candidate list.
curl: A command-line tool that sends web requests and prints the response. Adding `-s` (silent) hides the progress bar, which makes it handy for calling an API endpoint such as a search route.

D

Deletes (syncing): Removing from the index whatever has left the source data, so search stops returning discontinued products or old emails. Deleting a customer's data must reach every copy.
dimension: The number of values in a vector. all-MiniLM-L6-v2 gives 384, and text-embedding-3-small gives 1,536 by default.
doc_id: The field that names the original document an item came from. Several chunks of one help article share a `doc_id`, so you can keep only the best chunk per document.
dot product: Multiply two vectors position by position and add up the results. For unit vectors it equals cosine similarity, and in NumPy `@` computes it.

E

embedding: A list of numbers that represents the meaning of a piece of text. Texts with similar meaning, like "my cup showed up smashed" and "the mug arrived broken", get similar lists.
embedding function: In Chroma, an object that turns texts into vectors so you can add and query plain text. You must pass the same one every time you open the collection.
embedding inversion: Recovering the original text from its embedding. A 2023 paper recovered 92 percent of 32-token inputs exactly, so embeddings are not anonymous and need the same protection as the text.
embedding model: A neural network trained so that texts with similar meanings get similar vectors and unrelated texts get different ones. Documents and queries must use the same one.
encode: The sentence-transformers method that turns a text, or a list of texts, into embeddings as a NumPy array with one row per text. Options include `batch_size` and `normalize_embeddings`.
Euclidean distance (L2): The straight-line distance between two points. For unit vectors, its square equals 2 − 2 × cosine, so ranking by it gives the same order as cosine.
EXPLAIN: A PostgreSQL command that prints the plan the database will use for a query without running it. It is used to confirm that an index, such as an HNSW vector index, is actually being used.
extension: An add-on that gives PostgreSQL new types and functions. pgvector is an extension that adds the `vector` column type.

F

FAISS: Meta's open-source library of exact and approximate vector indexes, installed as `faiss-cpu`. It stores only vectors and numeric ids, so you keep text and metadata yourself.
FastAPI: A Python web framework for exposing code, such as a search engine, as an HTTP endpoint like `/search`. It validates request parameters before your function runs and answers bad requests with a 422 error.
fine-tuning: Further training an embedding model on a few thousand pairs of your own queries and the right documents, so it learns your vocabulary. It is usually a last resort, after trying hybrid search and richer text and measuring the results.
fingerprint: A short string computed from text that changes completely if one character changes. Kettle & Crane's sync stores each item's fingerprint and re-embeds only items whose fingerprint differs.
float32, float16, int8: Number formats for each vector value: float32 uses 4 bytes, float16 2 bytes and int8 1 byte. Smaller formats save memory with little recall loss.

G

graded relevance: Test labels with levels instead of yes/no: in Kettle & Crane's queries, 2 means the document answers the question and 1 means it is related and useful.

H

halfvec: A pgvector column type that stores each number in 2 bytes, allowing indexes on up to 4,000 dimensions.
Hamming distance: The number of bits that differ between two binary codes. `IndexBinaryFlat` uses it to compare 1-bit-per-dimension vectors.
HNSW: An approximate index that links each vector to near neighbors and answers queries by walking the links from sparse upper layers down to the full bottom layer. It has excellent recall and accepts new vectors, but uses memory and build time.
HNSW settings (M, efConstruction, efSearch): The HNSW tuning settings: `M` is links per vector, `efConstruction` is candidates considered while building, and `efSearch` is candidates kept while searching. Raising them improves recall but costs time or memory.
HTTP status codes: Numbers a web server returns to say how a request went, such as 200 for success or 404 for not found. For example, FastAPI answers invalid parameters with 422 Unprocessable, along with a message naming the problem.
Hugging Face: A website that hosts thousands of free models. sentence-transformers downloads all-MiniLM-L6-v2 from it the first time you run it.
hybrid search: Running keyword search and vector search and merging their results. At Kettle & Crane it finds product codes like KC-MUG-GRN and paraphrases like "cup smashed" in one search.

I

index: A structure built in advance that lets a query look only in promising places instead of every vector. HNSW and IVF are indexes.
IndexIDMap: A FAISS wrapper that lets you choose the numeric id of each vector, so ids point back to your items, and allows removal on indexes that support it. Flat and IVF indexes can delete; HNSW cannot.
input_type: A Voyage AI client option set to "query" or "document", because questions and passages are embedded slightly differently.
items: The units you search. Each Kettle & Crane item is a dict with an id, doc_id, source, category, title and the text to embed; there are 251 of them.
iterative index scans: A pgvector 0.8+ feature that keeps scanning the HNSW index until enough rows pass the WHERE filter. It fixes strict filters returning fewer rows than the LIMIT; `relaxed_order` may return rows slightly out of distance order.
IVF: An approximate index that groups vectors into clusters learned in advance (training), then searches only the nearest clusters. It is light on memory but needs training data.

J

JSON Lines: A file format with one JSON object per line. Kettle & Crane's help articles, products, emails and test queries are stored this way.

K

k-means: A method that finds a chosen number of center points (centroids) and assigns each vector to the nearest one. IVF uses it to build its clusters.
keyword search: Search that finds documents containing the words you typed. It fails on synonyms and paraphrases but excels at codes and exact phrases.

L

labeled query set: A fixed list of realistic test queries, each with the documents that should be found. It lets you score any search method with numbers instead of eyeballing.
lambda: A Python way to write a small anonymous function in one line. It is often used for short filter functions like `lambda it: it["price"] <= 15`.
latency: How long one search takes. Reranking raises quality but also latency, so you keep candidate lists short.

M

mask: An array of True/False values, one per item, used to select or exclude items. A pre-filter is a mask that gives failing items a score of minus infinity.
Matryoshka training: Training an embedding model so the first numbers of a vector carry the most meaning. That lets you cut OpenAI vectors short with `dimensions` without wrecking them.
metadata: Plain facts stored beside each vector, such as source, category, price and date. Hard conditions like "under $20" belong in metadata, checked exactly, because models don't do arithmetic.
metric: The measure a vector store ranks by: cosine, inner product or L2. With unit vectors all three give the same order.
MRR: A score based on where the first relevant result appears: 1 if first, 1/2 if second, 0 if not in the top 10, averaged over queries. It answers how far down someone must look.
MS MARCO: A large dataset of real English web search queries and relevant passages, widely used to train rerankers and cross-encoders. Models trained on it work best on English text.
MTEB leaderboard: A public leaderboard that benchmarks embedding models. Use it to shortlist models, then test the best few on your own queries.
multilingual model: An embedding model trained so a sentence and its translation get similar vectors. It lets Spanish questions find English answers, but a small one loses some English accuracy.

N

named entity recognition (NER): Models that find names, places and organizations in text. Unlike regular expressions, they can spot customer names that need redacting.
nDCG: A 0-to-1 ranking score that uses grades and positions, rewarding the best answers for appearing near the top. Each result earns its grade divided by log₂(position + 1), compared with a perfect ranking.
nlist and nprobe: IVF settings: `nlist` is how many clusters are made and `nprobe` is how many of the nearest clusters a search checks. Raising `nprobe` improves recall but is slower.
normalize: Dividing a vector by its length so it has length 1, making it a unit vector. For unit vectors, cosine similarity is just the dot product, which is cheaper.
NumPy array: A grid of numbers of one type with a shape, such as `(3, 384)` for three embeddings. It is what `encode` returns and what search math runs on.

O

operator class: In pgvector, the setting that tells an index which distance it serves. It must match the operator in your query, or the index is silently ignored.
overlap: Words repeated between neighboring fixed-size chunks so nothing loses its context at a boundary. 10 to 20 percent is typical.

P

pathlib: A Python standard-library module whose `Path` object represents a file path. The project uses it to find `kc.py` and the `index` folder from any location.
per-language indexes: Keeping a separate index, or a language filter, for each language when documents are in several languages.
pgvector: An open-source PostgreSQL extension that adds a `vector` column type, distance operators (`<=>`, `<#>`, `<->`) and ANN indexes. It lets vector search sit next to ordinary SQL filters and joins.
PII: Personal details such as email addresses, phone numbers and street addresses. The project redacts them with regular expressions before text is embedded or saved.
Pinecone: A fully managed hosted vector database: you send vectors with metadata and query them with filters without running servers. Others like it include Qdrant, Weaviate, Milvus and MongoDB Atlas.
pooling: A way to label test queries fairly: judge the combined top results of several search methods by hand, so the labels don't favor one method.
post-filter / pre-filter: A pre-filter searches only items that pass a condition, so you get `k` results if enough qualify. A post-filter finds the best `k` first and then drops failures, which can leave few or none; over-fetching (asking for more, then cutting) softens this.
PostgreSQL: A widely used open-source relational database. Kettle & Crane keeps orders and customers in it, and pgvector adds vector search.
precision@k: The fraction of the top `k` results that are relevant. It is like recall@k but divides by `k` instead of the number of relevant documents.
Product code (SKU): A product's stock code, such as KC-MUG-GRN. Codes have no meaning for an embedding model to learn, so keyword search finds them better, and the quality test checks that a code returns its product first.
product quantization (PQ): A compression method that squeezes each vector to a few bytes. It is combined with IVF for billions of vectors.
psycopg: The standard Python driver for PostgreSQL. With the `pgvector` package and `register_vector`, it can send NumPy arrays as vector columns.
PyTorch: A library for building and running neural networks, which sentence-transformers needs in order to run embedding models. A small CPU-only build is enough when no GPU is used.

Q

quantization: Storing each number in fewer bits (float16, int8, or 1-bit binary codes) to shrink storage. Each step trades a little recall for much less memory.
query and passage prefixes: Short labels such as "query: " and "passage: " that open models like e5 and nomic-embed expect before the text. Check each model card.
query expansion: Adding known synonyms or related words (such as cup → mug) to a query before searching, to help match your own vocabulary.

R

RAG: Retrieval-augmented generation: pasting search results into an LLM's prompt so it answers from your own documents. The same vectors that power search make this possible.
re-embedding: Embedding everything again, which is required whenever you switch embedding models. It is a hidden cost of changing models.
recall@k: The fraction of a query's relevant documents found in the top `k` results. For approximate search, it is also how many of the true top 10 an index returns.
reciprocal rank fusion (RRF): A way to merge ranked lists by position instead of score: each item gets 1 / (k + rank) from every list it appears in, summed, with k usually 60. Items found by both searches rise to the top.
redaction: Removing or masking contact details (emails, phones, addresses) before text is embedded or stored, so they never reach the index. Regular expressions catch these patterns but not names.
regular expression: A pattern that matches text, used in Python through the `re` module. It is useful for splitting text at headings, tokenizing codes, and finding or redacting things like emails and phone numbers.
reranking: Reordering a short list of candidates with a slower, more accurate model such as a cross-encoder. It improves the ranking of the top results after a fast first-stage search has picked the candidates.

S

semantic search: Search that compares embeddings so meaning beats exact words. "My cup showed up smashed" can find "arrives broken" with no shared words.
sentence-transformers: A Python library that loads embedding models and runs them locally with `encode`. It also provides `CrossEncoder` for reranking.
SHA-256: A standard hash function that turns any input into a fixed-length fingerprint that changes completely if the input changes. In Python it is available as `hashlib.sha256`, and a shortened hex form can serve as an item's fingerprint to detect changes.
similarity scores are relative: A cosine score only means something compared with other scores: unrelated texts often score 0.1 to 0.3 and paraphrases 0.6 to 0.9, and vector search always returns its nearest guess. A score is not a percentage.
stable ids: Item ids derived from the source, like `email-0042` or `help-returns#2`, so upserting replaces an item instead of duplicating it.
sync: Keeping an index in step with its source data: compare fingerprints, embed only new or changed items, and delete what has gone. Run it on a schedule.

T

t-SNE: A method that squashes high-dimensional vectors onto a flat map so close neighbors stay close. Distances between far-apart groups on the map mean little.
token: A token is a piece of a word, and a model's tokenizer splits text into them. In keyword search, tokenizing means splitting text into words, which must keep codes like KC-MUG-GRN whole.
top-k: The best `k` results by score, such as the top 5. Search returns the top few rather than every item, because the order matters more than the score.
truncation: Silently ignoring text past a model's token limit. all-MiniLM-L6-v2 stops at 256 tokens, so two texts that differ only at the end can get the same vector.

U

upsert: "Update or insert": add an item, or replace it if its id already exists. Running an upsert twice still leaves 251 items.
uvicorn: The server program that runs a FastAPI app, started with `uvicorn api:app --port 8000`.

V

VACUUM: PostgreSQL's housekeeping command that reclaims space from deleted rows. In pgvector it also cleans the vector index.
vector: An ordered list of numbers. Its dimension is how many numbers it holds; meaning lives in the pattern across them, not in any single one.
vector database: A store that keeps vectors, texts and metadata together, builds an ANN index, filters during search, and updates or deletes by id. Chroma and pgvector are examples.
Voyage AI: A company that offers hosted embedding and reranking models, which Anthropic's documentation points to because Anthropic has no embedding model of its own. Its client takes an `input_type` of `"query"` or `"document"`.

Z

zero data retention: An arrangement in which a provider does not keep your API data. OpenAI's embeddings endpoint is eligible for it by arrangement.