Back to Explore
GuideVibeFix editorialUpdated Nov 20, 2026

Stop making users guess keywords: add semantic search to your vibe project

A user asks for 'a light, appetizing cold dish for summer' and keyword search finds nothing — semantic search finds the cucumber salad. This guide builds a vector-retrieval pipeline with OpenAI's docs and the pgvector README: chunking, model choice, tables, queries, indexes, filtering, and hybrid search, with a cost tally and acceptance checks.

A person reaching for a book on a tall shelf in a library aisle

First, the boundary of this guide. The site already has several guides about search, but none of them is about this one. The Search Box guide is about the input box itself: debouncing, suggestions, and what to do with no results. The Search Ranking guide is about how to order results once you have them. The keyword search guides are about finding things by literal match. This guide is about a different road: finding things by meaning. When a user asks for "a light, appetizing cold dish for summer," you return cucumber salad and spicy kelp — instead of returning nothing because no recipe contains the words "summer." There is also a decision guide on the site, Fine-tune or RAG, about which road to take. This is a hands-on guide: once you have chosen the vector-retrieval road, how to build it step by step. Keyword search and vector search are not either-or; there is a section later on combining the two.

The "What to Eat" site below is a fictional practice project: a recipe website one person built with AI help, holding 800 recipes, searchable by dish name and by ingredient. Every operation, command, number, and query result shown with it is invented to explain the method, not a real record. All the rules, defaults, and SQL for embedding models and pgvector come from OpenAI's official documentation and the pgvector README, listed at the end. Chunk sizes, similarity thresholds, and the test set for acceptance are engineering practices: the text says where they are recommendations rather than rules from any document, so tune them as you go.

Keyword search can't find "something tasty"

Start with one concrete problem. Your recipe site can already search by keyword. A user types "cucumber salad" and finds it; types "cucumber" and finds it too. But what users really ask is rarely a dish name. It is a meaning: "something light and appetizing for summer," "a dish kids will eat that isn't spicy," "I only have eggs and tomatoes in the fridge, what can I make?" Keyword search fails these questions: it returns nothing, or a pile of loosely related results — because words like "light," "appetizing," and "goes with rice" may never appear in the recipe text at all.

Vector search takes a different approach: compare meanings, not letters. Every recipe becomes a list of numbers (a vector); recipes that mean similar things sit closer together. The user's question becomes a vector too, and the database returns the few recipes nearest to it. That way "a light, appetizing cold dish for summer" finds cucumber salad even if that recipe never uses the word "summer." That is semantic search: searching for meaning, not for words.

What a vector is: understand it first, then build

A vector is a list of floating-point numbers. OpenAI's official documentation puts it plainly: an embedding is a numerical representation of text that can be used to measure the relatedness between two pieces of text. Small distances between vectors suggest high relatedness, and large distances suggest low relatedness. The same page lists the common uses of embeddings: search (where results are ranked by relevance to a query string), clustering, recommendations, anomaly detection, diversity measurement, and classification. Our recipe site only needs the first one: search.

You do not need the math to understand this. Picture a huge map where every meaning is a point on it: "cucumber salad" and "spicy kelp" sit close together because both are cold dishes and both whet the appetite; "braised pork" sits far away because it is heavy and spicy. A vector is the coordinates of a point on that map, and searching means finding the points nearest to your question. How many dimensions the coordinates have depends on the model — which is the next section.

Pick a model: default to small, and know when to switch to large

OpenAI currently promotes two third-generation embedding models, plus one legacy model. The comparison table in the official documentation looks like this:

text-embedding-3-small: 1,536 dimensions by default, about 62,500 pages per dollar (at about 800 tokens per page), 62.3% on the MTEB evaluation, maximum input 8,192 tokens. text-embedding-3-large: 3,072 dimensions by default, about 9,615 pages per dollar, 64.6% on MTEB, maximum input also 8,192 tokens. The legacy text-embedding-ada-002: 1,536 dimensions by default, about 12,500 pages per dollar, 61.0% on MTEB, maximum input 8,192 tokens.

The conclusion is direct: default to small for a new project. It is the cheapest, and it performs better than the legacy model. Switch to large in only one situation: you have tried small and the top results keep including a few wrong ones, and you want a better model to lift accuracy. Do not start a new project on ada-002; it is the legacy model being replaced.

There is also a very practical parameter: dimensions. Both third-generation models support shortening it, and the quality loss is smaller than you would expect. The official documentation states it explicitly: a text-embedding-3-large embedding shortened to 256 dimensions still outperforms an unshortened text-embedding-ada-002 embedding at 1,536 dimensions on MTEB. That is because both models were trained so the leading dimensions carry the most information. So if you later find vectors too expensive to store or too slow to search, try shortening the dimensions first instead of rushing to a more expensive storage setup. One detail to note: if you truncate a vector by hand instead of using the dimensions parameter, normalize it afterwards — the official docs include ready-made code for that. Using the parameter lets the model handle it for you.

Before spending anything, work out one small bill. By the official table's units, small costs about 62,500 pages per dollar, at about 800 tokens per page. "What to Eat" has 800 recipes cut into 2,400 text chunks, each about 300 tokens — about 720,000 tokens in total, or about 900 pages. That costs about 900 divided by 62,500, or about 1.4 US cents. Vectorizing everything the first time costs a little over a cent; after that you only embed new or changed recipes, which costs almost nothing. With vector search, generating vectors is never the expensive part — the bill grows only once you make the setup complicated.

Chunking: one chunk, one idea

An embedding model accepts up to 8,192 tokens at once, but that does not mean you should stuff a whole recipe in. What search returns is a chunk, not a whole article: a 2,000-word recipe covers the method, the ingredients, and the plating all at once. A user searching "how to pick a tender cucumber" gains nothing from the whole recipe — they need the passage about picking cucumbers. So split the content into chunks first, with one idea per chunk.

The chunking rule for "What to Eat" is this: split each recipe into about 3 chunks — "title and introduction," "ingredients," "steps," and "tips" — turning 800 recipes into 2,400 chunks. Keep each chunk between 200 and 500 tokens: too short and the meaning is incomplete; too long and several meanings get mixed together and the results go wrong. Leave a little overlap between neighboring chunks, for example by carrying the last sentence of one chunk into the start of the next, so the meaning does not break at the cut. There is no standard answer for how much overlap; 10% to 20% is a common starting point, then tune it against real measurements.

Besides its text, every chunk should carry three things: which recipe it belongs to, which chunk number it is, and which model and dimensions produced it. The first two are for query results: search returns chunks, and the page needs to jump back to the original recipe. The third is an escape route for changing models later: vectors are computed per model, so switching models invalidates the old vectors and everything must be re-embedded. Store the model name and dimensions in the table and you can see at a glance what needs re-embedding when the model changes.

Seen as one pipeline, the whole thing is five numbers, shown in the diagram below: 800 recipes cut into 2,400 chunks, each chunk turned into a 1,536-dimensional vector stored in Postgres; a user asks a question, the question is embedded the same way, the 10 nearest chunks are fetched, and the page shows the top 5. Each step has its own section: chunking is this one, embedding and table setup are the next two, querying and indexing come after. Remember these five numbers; every section that follows explains one step of the pipeline.

The five numbers of semantic search: 800 recipes cut into 2,400 text chunks, each chunk embedded as a 1,536-dimensional vector, the 10 nearest chunks fetched per query, the top 5 shown on the page

Build the table: vectors live in Postgres

Vectors do not need a separate database. pgvector is an open-source extension for Postgres: install it and the Postgres you already run can store vectors and search by distance. The official README says it in one line: store your vectors with the rest of your data, and keep Postgres features like transactions, point-in-time recovery, and JOINs. For a project that already runs Postgres, this is the smoothest road.

Setting it up takes four steps. First, enable the extension — once per database:

CREATE EXTENSION vector;

Second, create a table. The vector column has type vector(1536), and that 1536 must match the model you use: small defaults to 1,536 dimensions, large to 3,072. If the dimensions do not match, inserting data fails. Besides the vector column, the table needs the recipe id, chunk number, chunk text, and model name:

CREATE TABLE recipe_chunks (
  id bigserial PRIMARY KEY,
  recipe_id bigint NOT NULL,
  chunk_no int NOT NULL,
  content text NOT NULL,
  model text NOT NULL,
  embedding vector(1536) NOT NULL
);

Third, write the vectors in. Call OpenAI's API to embed each chunk — send several chunks per request instead of one at a time — and store the returned vectors by chunk. For large volumes, load with COPY, which is much faster than inserting row by row. Fourth, do not build the index yet: wait until the initial data is loaded, because the official README explicitly recommends building indexes after loading for faster builds. In production, build indexes with CREATE INDEX CONCURRENTLY so writes are not blocked.

Querying: turn the question into a vector too

Querying has two steps: embed the user's question with the same model, then find the nearest rows in the table. The model must be the same one — vectors stored with small can only be queried with vectors computed by small; mixing models returns wrong results. pgvector offers a set of distance operators: <-> is L2 distance (Euclidean), <#> is the negative inner product, <=> is cosine distance, and <+> is L1 distance. Text embeddings usually use cosine distance, and cosine similarity equals 1 minus cosine distance — the closer to 1, the more similar:

SELECT recipe_id, chunk_no, content,
       1 - (embedding <=> '[0.12,-0.03,...]'::vector) AS similarity
FROM recipe_chunks
ORDER BY embedding <=> '[0.12,-0.03,...]'::vector
LIMIT 10;

One detail in this SQL: the query vector is written as '[0.12,-0.03,...]'::vector. In real code, the program computes the vector and passes it in as a parameter; nobody writes it by hand. Fetch 10 rows and show the top 5 on the page, keeping 5 in reserve. Another detail comes from the performance section of the official README: OpenAI's vectors are already normalized to length 1, so inner product is fastest for them — and the inner product operator returns a negative number, so multiply by -1 to get the real value.

Should you set a similarity threshold? Yes, but do not guess the number. Run it first and watch a week of real queries: what similarity does the top result usually have, and what similarity do the obviously wrong answers usually have? The number between those two is your threshold. Below the threshold, do not show a forced result — answer with "nothing quite matched, would you like to rephrase?" That is far better than pushing a wrong answer.

Indexing: skip it while data is small, add it when data grows

By default pgvector runs exact nearest neighbor search: no index, compare every row, perfect recall. While the data is small this is completely enough — 800 recipes and 2,400 chunks finish in the blink of an eye with exact search. When the data grows and row-by-row comparison gets slow, add an approximate index: trade a little recall for speed.

There are two index types; pick HNSW. It builds a multilayer graph, with a better speed-recall tradeoff than IVFFlat; it builds more slowly and uses more memory, but unlike IVFFlat it needs no training step — you can create it on an empty table and add data gradually. To build an HNSW index for cosine distance:

CREATE INDEX ON recipe_chunks USING hnsw (embedding vector_cosine_ops);

Note that the operator class must match the distance in your queries: vector_cosine_ops for cosine distance, vector_l2_ops for L2 distance, vector_ip_ops for inner product. Build one index per distance function you query with — mixing them does not use the index well. HNSW has three tunable numbers, all with defaults in the official README: at most 16 connections per layer when building the graph (m, default 16), a candidate list of 64 when building (ef_construction), and a candidate list of 40 when searching (hnsw.ef_search). For better recall, raise hnsw.ef_search, for example to 100, at the cost of slower queries:

SET hnsw.ef_search = 100;

IVFFlat is the other choice: it divides vectors into lists and searches only the lists nearest to the query vector. It builds faster and uses less memory, but its speed-recall tradeoff is worse than HNSW, and the table must already hold data before you build it. Its three rules of thumb are also in the official README: start the number of lists at rows divided by 1,000 (up to 1M rows) and at the square root of rows above 1M; start the number of probes at the square root of the number of lists. When you are just starting with semantic search, HNSW is the lower-maintenance default. Once you have real measurements for recall and latency, consider switching.

Filtering: filter first, then compare distances

Real queries are rarely "compare distances across the whole table." They usually carry conditions: only Sichuan dishes, only dishes ready in 30 minutes, no peanuts. Filtering with pgvector has one easy trap: with an approximate index, filtering is applied after the index is scanned. The official README gives a very concrete example: if a condition matches 10% of rows and HNSW runs with the default hnsw.ef_search of 40, only 4 rows will match on average — you asked for 10 and got 4. The fix is to enable iterative index scans (available since version 0.8.0), which automatically scan more of the index until enough results are found:

SET hnsw.iterative_scan = strict_order;

strict_order guarantees results in exact distance order; relaxed_order allows the order to be slightly off but gives better recall. Two more moves exist: build a separate index on the filter column (for example, a plain index on cuisine), since exact indexes work best for conditions matching a low percentage of rows; and if one filter value is especially common, such as "vegetarian only," build a partial index containing only those rows. At larger scale with many tenants, consider partitioning or separate tables — the multitenancy section of the official README states plainly that tenants sharing one approximate index affect each other's recall and speed, and isolation needs partitioning or separate tables.

Hybrid search: keywords and vectors each do their job

Vector search is good at "the meaning is right"; keyword search is good at "the name is exact." A user searching "Kung Pao chicken" gets a fast, exact hit from keywords; a user searching "a spicy chicken dish that goes with rice" is better served by vectors. So do not choose between them — combine them. The pgvector README has a dedicated section on hybrid search: use it together with Postgres full-text search and combine the two result lists, with reciprocal rank fusion (RRF) or a cross-encoder to merge them.

Keep the merge simple at first. Query each side separately, deduplicate, and merge with a simple rule — for example, exact dish-name matches go first, followed by high-similarity vector results. Once it is running, look at the data: if vector results keep crowding out keyword results, adjust the weights; if users searching dish names still cannot find them, raise the keyword weight. The point of hybrid search is not the formula. It is tuning after you have real query data.

Updates and model changes: vectors expire

Vectors are not forever. When a recipe changes, its chunks must be re-embedded, and the old vectors must be replaced. The method is simple: the content table and the vector table share the same keys. When content changes, delete the affected chunks, re-chunk, re-embed, and re-insert them. Do not fix the text and leave the vector alone, or search will keep returning the meaning of the old content.

Changing models is the bigger event. Vectors are computed per model, so switching models invalidates the old vectors and the whole table must be re-embedded. That is why the table-setup section asked you to store the model name and dimensions in the table: before switching models, look at what the table holds and decide the scope of the re-embedding. When re-embedding, do not overwrite the live table directly: compute everything into a new table first, verify it, and then switch over. If the new model turns out worse than the old one, you can still roll back.

One more easily missed point: the vector column's dimensions are fixed when the table is created. Small is 1,536 dimensions and large is 3,072, so moving from small to large means not just re-embedding but also changing the table structure. Think about this step in advance and the model switch will not catch you off guard.

Acceptance: 20 real questions beat any metric

How do you know the search is accurate? Not by feeling. Prepare 20 questions real users would ask — pull them from your own search-box logs, or ask a few friends to ask on the spot. Run them, check whether the top 5 contain a fitting answer, and write the result down. Every time you change the chunking, switch models, or tune a parameter, run the same 20 questions again. If the numbers improve, the change was right; if they get worse, roll it back.

There is another acceptance method from the monitoring section of the official README: compare approximate search results against exact search results. Turn off index scans (SET LOCAL enable_indexscan = off), run one exact search, then run the approximate search with the index on — how much the two result sets overlap is your recall. If recall is low, tune hnsw.ef_search first, and only then consider a different index type.

Five anti-patterns

Anti-pattern one: one vector per whole recipe. A single article covers four or five things, and one vector can only represent an average meaning — nothing matches well. Chunk by meaning, one idea per chunk.

Anti-pattern two: different models for storing and querying. Vectors stored with small and queried with vectors from large return wrong results. Storing and querying must use the same model.

Anti-pattern three: forcing in vectors with the wrong dimensions. The table is vector(1536) and large produces 3,072 dimensions — the insert fails. Match the model to the dimensions before creating the table.

Anti-pattern four: building an index while the data is still tiny. With a few thousand chunks, exact search is fast and perfectly accurate; an index only adds maintenance. Get it running first; build the index once it gets slow.

Anti-pattern five: looking only at similarity scores, not at answers. A chunk at 0.9 similarity can still answer the wrong question, and a chunk at 0.7 can be exactly right. Judge with real questions, not with numbers alone.

Checklist: a minimal version you can run in a day

Step one: enable the extension and create the table, with dimensions set to small's 1,536. Do not agonize over which model — start with small.

Step two: chunk 100 recipes, embed them, and load them in. Do not do the full load yet; 100 recipes is enough to verify the whole pipeline.

Step three: write the query endpoint — embed the question, fetch the top 10 by cosine distance, show the top 5. Run your 20 real questions and record how often the top 5 hit.

Step four: once the data grows and queries slow down, add the HNSW index; once you have filter conditions, enable iterative scans; once you want both keywords and vectors, build hybrid search.

Semantic search sounds like a big project, but it breaks down into four steps: chunk, embed, store, and search by distance. Get 100 recipes working first, then talk about 800, then about 80,000. Many projects die on the first step by thinking too much: a month choosing the model, a week tuning the index, and not one query written. Get it running first, then tune. Once your own search box has real queries, go back and tune the chunking, the dimensions, and the index — by then every adjustment is backed by data instead of gut feeling.

Views 4Comments 0

Comments (0)

ME
0/1000
Loading comments...

Sources

Browse projectsPublish your project

Related articles

A modern data center corridor lined with black server racks, cable trays and ventilation ducts overhead, blue indicator lights blinking on the racks
News
Two Months Late, PostgreSQL 19 Is Finally Here: Repack Tables While They Run, and Make Standbys Wait for Your Writes

On 19 November 2026, PostgreSQL 19 shipped — two months late, after a flood of AI-reported vulnerabilities rewrote the schedule. It brings REPACK (CONCURRENTLY), pg_plan_advice, and WAIT FOR LSN: tables can be reorganized while they run, query plans can be pinned, and standbys wait for your writes.

Product LaunchData WorkflowsBackend Engineering
Real photo: a bank of light gray metal filing cabinets with one drawer pulled open, revealing rows of hanging file folders inside
Guide
A real database inside the browser: IndexedDB local storage, explained plainly

localStorage only stores strings and has no indexes. IndexedDB is a real database in the browser: structured data, far larger capacity, indexes, and transactions. Following MDN's Using IndexedDB, IDBDatabase, and IDBObjectStore: the five-step routine, opening, upgrades, keys, indexes, transactions, add versus put, get, cursors, ranges, and multi-tab upgrades.

Tool TipsData WorkflowsFrontend Engineering
Real photo: hands typing on a MacBook Pro showing JavaScript code that changes HTML content, with a white mouse, papers, and binders on a white desk
Guide
Functions without the confusion: JavaScript functions, parameters, and arrow functions, explained plainly

You already call functions every day; this guide names what you have been doing. Following MDN's Functions, Arrow function expressions, and Rest parameters: declarations versus expressions, parameters and arguments, default values, rest parameters, spread syntax, return values, arrow function shorthand, the this trap, callbacks, and scope.

Tool TipsFrontend EngineeringAI Coding