All chapters
  1. Start hereRetrieval is a query. The model reads only what it returns
  2. Foundations · 1What retrieval means: lookup, keyword search, semantic search
  3. Foundations · 2Traditional SQL first: WHERE, indexes, full-text search and BM25
  4. Foundations · 3Vectors without AI: coordinates, distance and nearest neighbors
  5. Foundations · 4Embeddings: how a model turns text into a vector
  6. Foundations · 5Choosing an embedding model: quality, cost, privacy and fit
  7. Search · 6Schema and storage: where the vectors live
  8. Search · 7Exact vector search: compare the query with every row
  9. Search · 8Approximate nearest neighbors: HNSW, IVF and the recall trade
  10. Search · 9PostgreSQL and pgvector: vectors inside a relational database
  11. Search · 10SQLite vector search: one file on one machine
  12. Pipeline · 11Chunking and ingestion: from a document to retrievable units
  13. Pipeline · 12Retrieval pipelines: from a question to the context the model reads
  14. Pipeline · 13Hybrid search: words and vectors together
  15. Pipeline · 14Reranking: a second, more careful look at the candidates
  16. Pipeline · 15Top-k and scale: ten thousand, a hundred thousand, a million rows
  17. Pipeline · 16Two corpora: similar applicants and underwriter precedents
  18. Pipeline · 17Grounded generation: citations, abstention and conflicts
  19. Pipeline · 18Evaluating retrieval: recall@k, MRR, nDCG and faithfulness
  20. Practice · 19Google Cloud choices: Cloud SQL, AlloyDB, Vector Search, Agent Retrieval, RAG Engine, Agent Search
  21. Practice · 20Other ecosystems: libraries, engines and managed services
  22. Practice · 21Operations: migrations, deletes, permissions and freshness
  23. Practice · 22Advanced retrieval: rewriting, hierarchies, late interaction, graphs, agents
  24. Practice · 23Reference architectures: local-first, dual-corpus, managed, Postgres-native
  25. Practice · 24Framework recipes and the decision guide
  26. ReferenceGlossary
  27. AboutAbout this site and its sources
Pipeline · 16

Two corpora: similar applicants and underwriter precedents

Two retrieval jobs with different questions, contents, metadata, authority and freshness. What each one embeds, what stays an exact filter, and whether they need two databases or two tables.

Two questions, two corpora
Corpus A asks "which past applicants look like this one?". Corpus B asks "how did underwriters decide cases like this, and why?". Different text is embedded, different columns stay exact.
Authority is not similarity
Guidance has the highest authority: current policy outranks any precedent, however similar. A precedent is decision support, never a replacement for current policy or for the human decision.
Tables or databases
Two corpora usually need two tables, not two databases. A split earns its cost through compliance, retention, permissions, latency or ownership, and a decision matrix says which.

The underwriting agent has SUB-1004 in front of it: a masonry office built in 2001, 20,000 sq ft, sprinklered, wind zone C, no losses. The application says the roof is 9 years old; the roof-data provider says 22 (EV-ROOF-0412). Before it writes a recommendation, the agent calls the tool find_similar_decisions(submission_id), because an underwriter reading the recommendation will ask a fair question: what did we do last time?

Picture a first version of that tool built on one table. Every past case, its applicant profile and the underwriter's rationale, is pasted into one text, embedded once, and searched with one query vector. The nearest row comes back: PRE-001, an approval of an almost identical masonry office with a roof of about 26 years. The agent reads "a building like this was approved" and leans toward approve.

Every part of that worked. The vectors were right, the distance was small, the row was real (in this example; the seeded precedents are synthetic). What went wrong is that the tool answered two questions with one ranking and dropped the columns that make the answer usable. PRE-001 was decided under policy 2025.4, when the roof limit was 30 years. Under the current 2026.2, a 26-year roof in zone C is over the 25-year limit. The row also does not say who decided, whether it was an override, or whether it still counts. The similarity was real; the authority was gone. This page separates the two questions.

What this is not. A precedent store is not the agent's memory. It holds decided cases that a person reviewed, with their policy version and provenance, for any run to retrieve. Durable memory of one agent and saved execution state are covered at memory.sammuthu.com.

Two questions that sound like one#

Recall the primitive. An embedding column holds one vector per row; a vector query compares the query vector with the rows' vectors, ranks the rows by distance and returns the nearest k; the model reads only what retrieval returned. Retrieval is a query. The model reads only what it returns. So the question you embed decides what "near" means, and two different questions need two different things embedded.

The first question is about the applicant. An underwriter wants comparables, as an appraiser wants "comps": past submissions with the same occupancy, construction, size, age and exposure. Call this applicant similarity: finding past applicants whose risk profile resembles the current one. For SUB-1004, a good answer is another masonry office of 10,000 to 25,000 sq ft, built between 1990 and 2010, roof 20 to 30 years, zone C, sprinklered.

The second question is about decisions. A precedent is a past decided case stored for decision support: what was decided, under which policy version, by whom, and why. For SUB-1004 the useful precedents are cases where the stated roof age and the provider's estimate disagreed, whatever the building's size. Here the rationale carries the meaning, so the rationale is what gets embedded.

Before AI. Legal research has kept these apart for a long time. Statutes say what the law is; case law says how courts applied it, with a date and a court. A lawyer cites the statute first, and an old case decided under a repealed statute is history, not authority. Guidance is the statute here, precedents are case law, and applicant profiles are the comparables an appraiser pulls.

Three more words carry the page. Authority is how much a source may decide: current guidance decides, a precedent informs. Freshness is how current a row is: a precedent decided under 2025.4 is older than the rule that now applies. Provenance is where a row came from and who stands behind it: decided_role says a senior underwriter decided PRE-002; simulated: true says the seeded rows are invented.

The contract of each corpus#

A contract here means four things a corpus promises: the question it answers, the unit stored in one row, the text that is embedded, and the columns that stay exact. Exact columns are compared with = in a WHERE clause, never by distance, because they decide what is allowed, not what is similar.

Diagram: Three corpora, three contracts: what is embedded, what stays exact, how much it may decide

Each lane is one corpus. The first box is the question, the second what is embedded, the third the exact columns, the last its authority. Only guidance decides; profiles are comparables; precedents inform and carry their policy version.

  1. Guidance
    1. What does policy say?: The tool that retrieves passages of the policy fixture for a query.
    2. Embeds the passage: The passage text is the embedded text.
    3. Exact: version, status: Only the current version may be cited as the rule.
    4. Decides: Current policy outranks any precedent, however similar.
  2. Corpus A
    1. Who looks like this?: Past applicants whose risk profile resembles the current one.
    2. Embeds banded profile: A key=value summary of bands such as area and roof age.
    3. Exact: zone, tenant: Hard constraints are filters inside the query, never distances.
    4. A comparable: Shown to the underwriter for context; it decides nothing.
  3. Corpus B
    1. How was it decided?: Past decided cases for the same situation, with why and by whom.
    2. Embeds rationale: The reasoning carries the meaning, so it is embedded here.
    3. Columns: version, role: Chronology and human authority stay columns the writer must see.
    4. Informs: Never replaces current policy or the human decision.
CorpusQuestionOne rowEmbedded textExact columns (filters)Authority
Guidance (guidance_passages)What does the current policy say?one passage of UW-GUIDEthe passage textpolicy_version, rule_id, status, sectiondecides (current version only)
A: applicant profiles (applicant_profiles)Which past applicants look like this one?one past submission's profilea banded profile summaryrisk_region, wind_zone, occupancy, construction, tenantnone: a comparable
B: precedents (precedents)How were similar cases decided, and why?one decided casethe rationale + banded contextdecision, policy_version, decided_role, override, status, decided_at, tenant, simulatedinforms; never replaces policy or the person

Read the last column first. A distance tells you how close two texts are; it cannot tell you that one row is a rule and another an old decision. That lives in columns, which the application must carry into the prompt.

Some columns filter every query: tenant (another book of business must never leak, case UW-R07) and status. Others filter one query and label another: policy_version filters guidance to 2026.2, but on a precedent it is a label the writer must see, because an old approval is useful context when marked as old. Chronology belongs in columns too: "decided before 2026-07-01" is a comparison, not a similarity.

What Corpus A embeds, and when bands beat an embedding#

Corpus A embeds a banded profile summary. A band is a range that replaces a raw number: area_band=10k-25k instead of 20,000, roof_age_band=20-30 instead of 22. For SUB-1004 the summary is the text below, and SUB-1004's roof band uses the provider's 22 years, not the application's 9.

occupancy=office; construction=masonry; area_band=10k-25k; year_built_band=1990-2010; roof_age_band=20-30; wind_zone=C; sprinklered=yes

Bands hide differences that do not matter (20,000 and 21,000 sq ft are the same risk here) and keep raw numbers, which embeddings handle poorly, out of the vector; the embeddings page shows why.

But look at what is left. Every field in that summary is a short category with a known set of values. Nothing in it is a paraphrase, a synonym or a free sentence. That is the situation in which a semantic embedding has the least to offer, and an exact, weighted comparison of fields has the most. A weighted structured feature distance adds a weight for each field that differs: occupancy might weigh 3, construction 2, roof band 2, the others 1. The weights state, in code someone can review, what makes two risks alike.

The script below ranks the same 82 allowed rows of Corpus A three ways for SUB-1004 (case UW-R04, wind zone C, tenant book-east): by the cosine distance of the embedded summary, by the count of matching bands, and by the weighted band distance. It also counts false matches. A false match is a neighbor that ranks high but should not: here, by a rule written for this page, a neighbor whose occupancy is not office. It is a short file added to a scratch copy of examples/rag-uw that calls only the example's modules. A successful run proves that the three rankings differ on the same rows and that the false-match count depends on the ranking; it does not say which weights are right for a real book.

# band_vs_vector.py, run from a scratch copy of examples/rag-uw
# Corpus A for SUB-1004 (UW-R04): rank the same allowed rows three ways and count false matches
# (a neighbor whose occupancy differs from the query's "office"). Weights are illustrative.
import data
from encoders import TOY_A1
from pipeline import profile_table
from rerank import band_matches
from search import exact_topk

WEIGHTS = {"occupancy": 3, "construction": 2, "roof_age_band": 2,
           "area_band": 1, "year_built_band": 1, "wind_zone": 1, "sprinklered": 1}

qp = data.QUERY_PROFILES["SUB-1004"]
table = profile_table()
allowed = [r for r in table.rows if r["wind_zone"] == "C" and r["tenant"] == "book-east"]
hits = exact_topk(table, TOY_A1.encode_query(qp["summary"]), 5,
                  {"wind_zone": "C", "tenant": "book-east"}, TOY_A1.name).hits


def weighted_distance(row):
    """Sum of the weights of the bands that differ: 0 = identical profile."""
    return sum(w for k, w in WEIGHTS.items() if row["bands"][k] != qp["bands"][k])


def show(label, rows, extra):
    print(label)
    for r in rows:
        m, c = band_matches(qp["bands"], r["bands"])
        print(f"  {r['profile_id']} {extra(r):<12} bands {m}/{c}  {r['occupancy']}/{r['construction']}")
    print(f"  false matches (occupancy is not office): {sum(r['occupancy'] != 'office' for r in rows)} of 5")


dist = {h["id"]: h["distance"] for h in hits}
show("1. cosine distance of the embedded banded summary", [table.row(h["id"]) for h in hits],
     lambda r: f"dist={dist[r['profile_id']]:.4f}")
eq = sorted(allowed, key=lambda r: (-band_matches(qp["bands"], r["bands"])[0], r["profile_id"]))[:5]
show("2. count of matching bands (every band weight 1)", eq, lambda r: "")
wt = sorted(allowed, key=lambda r: (weighted_distance(r), r["profile_id"]))[:5]
show("3. weighted band distance (occupancy 3, construction 2, roof 2, others 1)", wt,
     lambda r: f"wdist={weighted_distance(r)}")
print(f"rows compared in each ranking: {len(allowed)} of {len(table.rows)}")
1. cosine distance of the embedded banded summary
  PRF-0218 dist=0.0018  bands 6/7  office/masonry
  PRF-0206 dist=0.0045  bands 3/7  retail/frame
  PRF-0091 dist=0.0048  bands 4/7  office/concrete
  PRF-0172 dist=0.0066  bands 5/7  restaurant/frame
  PRF-0197 dist=0.0070  bands 4/7  restaurant/frame
  false matches (occupancy is not office): 3 of 5
2. count of matching bands (every band weight 1)
  PRF-0218              bands 6/7  office/masonry
  PRF-0050              bands 5/7  warehouse/masonry
  PRF-0114              bands 5/7  office/steel
  PRF-0138              bands 5/7  light_manufacturing/masonry
  PRF-0172              bands 5/7  restaurant/frame
  false matches (occupancy is not office): 3 of 5
3. weighted band distance (occupancy 3, construction 2, roof 2, others 1)
  PRF-0218 wdist=1      bands 6/7  office/masonry
  PRF-0225 wdist=3      bands 4/7  office/masonry
  PRF-0021 wdist=4      bands 4/7  office/masonry
  PRF-0050 wdist=4      bands 5/7  warehouse/masonry
  PRF-0091 wdist=4      bands 4/7  office/concrete
  false matches (occupancy is not office): 1 of 5

All five cosine distances are tiny, and the second-nearest row is a retail frame building that shares only 3 of 7 bands. Through this toy encoder, a short key=value text produces a coarse signal: many profiles land close together, and the order among them says little. The second block treats every band as equal, so a warehouse and a light-manufacturing plant rank as high as an office. The third block encodes a judgment, occupancy matters most, and the false matches drop from 3 to 1. The judgment is now visible and testable. Change a weight, rerun, and the false-match count says whether it helped.

These numbers come from synthetic profiles, a toy encoder and a rule written for this page. They do not show that a real model would do as badly, or that these weights suit a real book. They show the method: when the embedded text is a list of categories, compare a semantic ranking with a weighted structured distance on labeled neighbors before choosing. When profiles carry free text, such as an inspector's description, the embedding earns its place, and a hybrid is common: exact filters, a weighted band score and a cosine term, the shape of the feature reranker on reranking.

In the insurance build. In that build, Corpus A is a table customer_profiles, one row per in-force insured property, 1,140 seeded rows with 737 distinct texts, each distinct text embedded once by all-MiniLM-L6-v2 (384 dimensions). The text is a fixed banded template (for example sqft_band=2500-4000; year_built_band=1990-2010; ...; zip3=...), never raw numbers and never personal data, versioned by embedding_version. The query applies a structured filter first, then ORDER BY embedding <=> :q LIMIT 8, and widens the filter step by step when fewer than 3 rows come back, reporting each step.

What Corpus B embeds, and what must stay a column#

Corpus B in this example embeds the rationale plus the banded context, so a query phrased as a situation ("stated roof age on the application and the provider estimate disagree") finds decisions written in other words ("sources disagree on when the roof was replaced; referred upward"). Here is PRE-002, the override from case UW-R05, with the column names of sql/schema.sql (fields rearranged and wrapped for reading):

embedded_text:   Broker said the roofing was renewed a few years ago, but the aerial survey put it near twenty years
                 old; an inspection then showed storm damage, so cover was refused. Context: occupancy=office;
                 construction=masonry; area_band=10k-25k; year_built_band=1990-2010; roof_age_band=20-30;
                 wind_zone=C; sprinklered=yes
decision:        decline            policy_version: 2026.2       decided_at: 2026-08-14
decided_role:    senior underwriter override: true
override_reason: The agent recommended escalate; after an inspection found hail damage the senior underwriter declined.
status: active   tenant: book-east  simulated: true

Everything below embedded_text is a column that answers a question a distance cannot. The decision is a value to group by, not a word to match. policy_version and decided_at give chronology: which rule applied when. decided_role and override record human authority: a senior underwriter departed from the agent's recommendation, which makes the case more instructive, not less. status carries the lifecycle (a quarantined row such as PRE-006 is never returned). simulated is provenance: the seeded precedents are synthetic, and nothing here presents them as history.

On PostgreSQL the first stage of the precedent search is the first statement of Q5 in examples/rag-uw/sql/queries.sql. It ran on the throwaway database on 2026-11-18 (PostgreSQL 16.14, pgvector 0.8.3, one run, toy data, not a benchmark); $1 is the precedent query vector for SUB-1004, bound as a parameter.

-- first statement of Q5 from examples/rag-uw/sql/queries.sql (ran on the throwaway database, 2026-11-18)
PREPARE precedent_candidates(vector, text, int) AS
  SELECT pr.precedent_id, pr.decision, pr.policy_version, pr.override, pr.decided_role, pr.decided_at,
         (pr.policy_version <> '2026.2') AS decided_under_old_version,
         round((pr.embedding <=> $1)::numeric, 4) AS cosine_distance
  FROM precedents AS pr
  WHERE pr.status = 'active' AND pr.tenant = $2
  ORDER BY pr.embedding <=> $1, pr.precedent_id
  LIMIT $3;
EXECUTE precedent_candidates(:'q_prec', 'book-east', 10);
 precedent_id |   decision   | policy_version | override |    decided_role    | decided_at | decided_under_old_version | cosine_distance 
--------------+--------------+----------------+----------+--------------------+------------+---------------------------+-----------------
 PRE-002      | decline      | 2026.2         | t        | senior underwriter | 2026-08-14 | f                         |          0.0326
 PRE-014      | approve      | 2025.4         | f        | underwriter        | 2024-11-23 | t                         |          0.1262
 PRE-040      | approve      | 2025.4         | f        | underwriter        | 2025-02-09 | t                         |          0.1275
 PRE-039      | approve      | 2026.2         | f        | underwriter        | 2026-10-02 | f                         |          0.1312
 PRE-019      | request_info | 2025.4         | f        | senior underwriter | 2026-04-16 | t                         |          0.1332
 PRE-028      | approve      | 2025.4         | f        | underwriter        | 2025-03-22 | t                         |          0.1414
 PRE-023      | approve      | 2025.4         | f        | underwriter        | 2025-06-06 | t                         |          0.1671
 PRE-015      | request_info | 2025.4         | f        | senior underwriter | 2025-06-11 | t                         |          0.1671
 PRE-012      | decline      | 2025.4         | f        | senior underwriter | 2026-03-15 | t                         |          0.1718
 PRE-022      | escalate     | 2025.4         | f        | senior underwriter | 2025-03-11 | t                         |          0.1721

Eight of the ten nearest decisions were made under 2025.4. That is not a bug in the query. It is what a precedent corpus looks like a few months after a policy change: most of the history predates the current rule. The query does not hide those rows; it computes decided_under_old_version as a column so that every later stage, and the underwriter, sees it. The second statement of Q5 joins each precedent to the current text of the rule it cites, and the exact search page shows that join and its output.

In the insurance build. In that build, Corpus B is a table precedents, one row per decided provision, 41 seeded rows marked simulated ("never presented as real history") plus rows learned from human decisions. Its embedded text is the provision plus 8 permissible risk bands, with no geography in the bands. The underwriter's reason text is stored, redacted of personal data, but NOT embedded. The first stage filters provision, status = 'active' and a 36-month lookback, then ORDER BY embedding <=> :q, decided_at DESC LIMIT 50, with no ANN index (a btree on (provision_key, status, decided_at DESC) and an exact distance sort), followed by the 0.6 / 0.3 / 0.1 feature reranker and 3 approve-side plus 3 decline-side. Precedents move from pending to active after a review window, and can be quarantined or revoked.

The two designs differ on purpose. This example embeds the rationale, so a query in plain words finds decisions written in other words. The insurance build keeps the reason text out of the vector, which is defensible on two grounds. Permissible factors: similarity is limited to fields the business approved as risk factors, while a reason sentence could carry a word that should never influence a match. Determinism: a fixed template from structured fields gives the same text for the same case every time, so a vector changes only when its fields or the model change. What it gives up is what this example shows: two decisions with the same bands and different reasoning look identical to the vector, and the reranker and the underwriter must read the stored reason. Each is a contract someone chose, and each can be measured with labeled queries.

find_similar_decisions, end to end#

Now the whole tool, as examples/rag-uw/pipeline.py implements it. Corpus A finds similar applicants with an exact filter on wind zone and tenant. Corpus B returns precedents for the same situation, filtered on status and tenant, ranked by cosine distance, then reranked by bands, cosine similarity and recency into 3 approve-side and 3 decline-side rows, each with its policy_version. Guidance is searched separately by search_guidance, and it is the only corpus a recommendation cites as its rule.

Diagram: find_similar_decisions for SUB-1004: comparables, then both sides of past decisions

Corpus A filters exactly and returns five comparables. Corpus B filters status and tenant, ranks by cosine distance, then a feature reranker keeps three approve-side and three decline-side precedents. Guidance is searched separately and is the only corpus the recommendation cites as its rule.

  1. Corpus A
    1. Filter zone and tenant: Only rows in wind zone C of tenant book-east are compared.
    2. Top 5 by distance: Five comparables, each joined to its source profile.
  2. Corpus B
    1. Filter active, tenant: Quarantined rows and other tenants never enter the ranking.
    2. Feature rerank: Bands are compared exactly; rows under 4 of 7 bands are dropped.
    3. 3 approve + 3 decline: Both sides are shown; old-version approvals carry a flag.
  3. Guidance
    1. Current passages: search_guidance returns the current rules, the only citable source.
    2. Escalate, cites R-ROOF-03: The writer cites the rule; precedents are listed as decision support.

The command runs both tools for SUB-1004 in a scratch copy of the example. A successful run proves the two corpora return different kinds of rows for the same submission, and that every approval decided under the old version carries a flag; it says nothing about the quality of a model, because the encoder is a toy.

cd rag-uw && /opt/homebrew/bin/python3 pipeline.py --submission SUB-1004
search_guidance('roof age limit for wind zone C; roof age on the application and from the provider differ')
  1. GD-2026.2-R-ROOF-01      rerank=0.700 dense_rank=1 lexical_rank=1
  2. GD-2026.2-R-ROOF-03      rerank=0.700 dense_rank=3 lexical_rank=2
  3. GD-2026.2-R-ROOF-02      rerank=0.500 dense_rank=4 lexical_rank=6
  4. GD-NOTE-01               rerank=0.500 dense_rank=2 lexical_rank=4
  5. GD-NOTE-02               rerank=0.300 dense_rank=5 lexical_rank=3
find_similar_decisions: profiles ['PRF-0218', 'PRF-0206', 'PRF-0091', 'PRF-0172', 'PRF-0197']
  approve_side PRE-001 approve      2025.4 score=0.886 bands=7/7 override=False decided under 2025.4; current policy 2026.2 outranks it
  approve_side PRE-023 approve      2025.4 score=0.816 bands=6/7 override=False decided under 2025.4; current policy 2026.2 outranks it
  approve_side PRE-030 approve      2025.4 score=0.734 bands=5/7 override=False decided under 2025.4; current policy 2026.2 outranks it
  decline_side PRE-002 decline      2026.2 score=0.979 bands=7/7 override=True 
  decline_side PRE-005 escalate     2026.2 score=0.843 bands=6/7 override=False 
  decline_side PRE-007 decline      2026.2 score=0.672 bands=4/7 override=False

Three kinds of rows came back, each treated differently downstream. The guidance passages are the rules; R-ROOF-03 is the one that applies. The profiles are comparables, never cited as a reason. The precedents show both sides: three approvals flagged as decided under 2025.4, and three non-approvals under 2026.2, including the override PRE-002. The opening's one-table design returned PRE-001 alone; this one returns it with the flag that says current policy outranks it.

The lab: two corpora, one submission#

Pick a submission to see Corpus A and Corpus B side by side, with each query's filters, each row's metadata, the flags on old-version approvals, and the guidance answer with its ids. Toy encoders and synthetic data show how the mechanism works, not how good any model or product is.

The same result without JavaScript, in this example:

SubmissionCorpus A top 5 (82 of 240 pass the filter)Corpus B approve-sideCorpus B decline-sideRecommendation
SUB-1004PRF-0218, PRF-0206, PRF-0091, PRF-0172, PRF-0197PRE-001, PRE-023, PRE-030 (all 2025.4, flagged)PRE-002 (override), PRE-005, PRE-007escalate, cites R-ROOF-03, EV-ROOF-0412
SUB-1005PRF-0050, PRF-0007, PRF-0138, PRF-0047, PRF-0056PRE-004, PRE-030, PRE-023 (2025.4, flagged)PRE-007, PRE-012, PRE-002decline, cites R-ROOF-01, EV-ROOF-0515; attachment flagged as untrusted
SUB-1007PRF-0050, PRF-0138, PRF-0007, PRF-0212, PRF-0047PRE-004, PRE-030, PRE-023 (2025.4, flagged)PRE-007, PRE-002, PRE-012decline, cites R-ROOF-01

Every recommendation has requires_human: true. The model recommends; a person decides.

When history disagrees with the current rule#

A policy changes; the decisions made under the old policy stay in the table. This gap between what precedents say and what current policy says is policy drift, and it grows with every revision. Two of this site's cases show its two forms.

In case UW-R05, both retrievals above are correct: PRE-001 (roof about 26 years, inside the 30-year limit of 2025.4) and the override PRE-002. Both must arrive with policy_version, override and decided_role, and the approval must be flagged, because under 2026.2 the same roof is over the limit.

In series case UW-007 the conflict is sharper. SUB-1007 is a masonry warehouse with a 28-year roof in zone C; Corpus B returns PRE-004, an approval of exactly that, decided in March 2025 under 2025.4. Current R-ROOF-01 says a roof older than 25 years in zone C is not eligible. The nearly identical precedent still loses: the recommendation is decline, citing R-ROOF-01, with the old approval listed as an outranked conflict.

Common confusion. "The most similar precedent is the strongest evidence." Similarity measures how alike two cases are; it says nothing about whether the rule that decided the old case still applies. A precedent is decision support, never a replacement for current policy or for the human decision. Rank precedents by similarity, then label them by version and let precedence decide, as the grounding page does.

Drift has a retrieval answer and a governance answer. The retrieval answer is the column: policy_version on every precedent, compared with the current version (decided_under_old_version in Q5) and printed next to the row. The governance answer is the lifecycle: when a policy changes, someone decides whether old precedents stay active with a flag, move to quarantined, or fall outside a lookback window such as the insurance build's 36 months. That is a policy about evidence, owned by the people who own the policy, not a retrieval parameter.

Two tables in one cluster, or two databases?#

A logical collection is a named set of rows with its own schema, embedding column and indexes, inside a shared engine: a table in PostgreSQL, a collection in a vector database. The example's three corpora are three logical collections in one PostgreSQL database (guidance_passages, applicant_profiles, precedents in examples/rag-uw/sql/schema.sql), each with its own HNSW index and its own btree on the filter columns. The question is when that stops being enough.

Start with what one cluster gives you. A join from a precedent to the current rule text is one SQL statement (Q5). A policy revision that changes a passage and its vector is one transaction; Q14 on the throwaway database shows an update and its rollback. Backups, access control and monitoring exist once. Two contracts imply two tables with different columns, filters and indexes, not two engines (the storage page covers where the vector lives). PostgreSQL can also enforce row access per role inside one table: with row-level security enabled, a policy's expression is evaluated for each row before the conditions of the user's query, and with no policy at all the default is deny (as documented on 2026-11-18).

A split into two physically independent databases has real reasons. Each reason is a requirement of the business, not of the vectors.

RequirementTwo tables in one clusterTwo independent databases
Split by domainEnough when both corpora serve one workflow and one teamWorth it when the corpora serve different products with different release cycles
ComplianceOne boundary; every control applies to bothNeeded when one corpus must sit in another region, account or certification scope
RetentionSeparate deletion jobs per table are possible but share one backup historyCleaner when one corpus must be erased on a different schedule, including its backups
PermissionsGrants per table, row-level security per tenant; one engine to auditStronger isolation when a leak between corpora would be a reportable incident
LatencyShared memory and CPU; a heavy precedent rebuild can slow profile queriesIndependent capacity per corpus; network hop and two connection pools
Organizational ownershipOne owning team, or teams that already share a databaseDifferent owners, on-call rotations and budgets
Joins back to sourceOne SQL join (Q5), one transactionDone in application code; consistency across two stores is your problem

Read the table from the bottom. The last row is what a split costs: every join becomes application code, and a policy revision that should change guidance and flag precedents at once becomes two writes that can disagree. So split when a row above it is a hard requirement (a regulator, a retention law, a separate owner), not because the corpora have different names. Precedents learned from human decisions in a regulated book are the most common candidate, because their retention and access rules often differ from those of the policy text.

In a coding agent. A coding agent has the same two questions. "Which files look like this one?" is applicant similarity: compare structure, language and imports, often better with exact features than with an embedding. "How did we fix problems like this before?" is a precedent search over merged pull requests and their review comments, with the merge date, the reviewer and the commit as columns. An old fix written against a since-removed API is policy drift: the code base, like the guidance, outranks history.

Joining back to the source#

The underwriter acts on the record, not on the summary that was embedded, so every returned row must lead back to its source by id: profile_id and submission_ref in Corpus A, precedent_id and rule_ids in Corpus B. Q4 on the throwaway database returned the same five profiles as the Python run, with raw year_built, area_sq_ft and roof_age_years read from the row; the exact search page walks through it. A row without a source id should never reach the prompt: nobody could cite or check it.

How products and frameworks express two corpora#

In pgvector, each corpus is a table with its own vector column and optional index. Its README documents exact search by default, and that with an approximate index a filter is applied after the index is scanned, so a selective filter can return fewer rows (as documented on 2026-11-18; details on pgvector). Dedicated vector databases call the unit a collection or an index; ecosystems compares them. A framework usually wraps one collection in one retriever object, so two corpora are two retrievers, and the code that labels and orders their results is yours. Documented shapes; not run here.

A checklist for Monday#

The honest boundary of this site applies to every number on this page: the series example is an illustrative reconstruction for teaching. Cases, rules, fields, vectors and every number are invented. Nothing here reports the quality of a real system or model. Example roof thresholds are synthetic, not insurance practice.

Embed the reason, or embed the bands?Two defensible precedent contracts and how to choose between them

Embedding the rationale makes a precedent searchable by situation. "Sources disagree on the roof" finds "the broker's stated roof age and the provider estimate were far apart". That is semantic search doing what it is good at. The cost is that the free text of a reason enters the vector. Any word in it, including one that refers to a factor the business has not approved, can pull a case closer to a query. Reasons are also written by people in different styles, so two decisions with the same basis can land apart because one underwriter wrote three words and another wrote three sentences.

Embedding only the provision and permissible bands, as the insurance build does, removes both problems. Similarity is limited to approved risk factors; the template is deterministic, so the same case always produces the same text, and re-embedding is needed only when fields or the model change. The cost is the opposite: two cases with the same bands and different reasoning are indistinguishable to the vector, and a query in natural language has nothing to match except the template words.

A middle design embeds a short, controlled situation label (for example a code for "roof age sources disagree") chosen from a reviewed list, plus the bands. It keeps determinism and permissible factors while adding the situation. Whatever the choice, test it the same way: a labeled set of precedent queries, recall@k per slice, and a review of the false matches, as the evaluation page computes.

Structured distance at scaleWeights as configuration, learned weights, and where an embedding still helps

A weighted band distance is cheap and explainable: each point of distance names a field that differs. At scale it has two problems. Exact computation over many rows is a full scan unless the most selective fields become btree filters first, which is what both this example (wind_zone, tenant) and the insurance build (state, zip3, dwelling_type) do. And hand-set weights encode one person's view; they drift as the book changes.

Weights can be learned from labels. Pairs of profiles that underwriters marked as comparable or not comparable give a training set, and a simple model fits a weight per field. The learned weights remain configuration with a version, reviewed like any other change, and evaluated on held-out labels before use. An embedding still helps where profiles carry text that categories cannot express: an inspector's note, a description of a roof repair. Then a common design keeps exact filters for the hard constraints, a weighted structured term for the categories, and a cosine term for the text, combined in a reranker over a candidate set. That is the shape of the 0.6 / 0.3 / 0.1 reranker, applied to profiles instead of precedents.

Isolation inside one clusterTenant filters, row-level security and the post-filter leak

Case UW-R07 is a precedent from another tenant, book-west, that is very similar to SUB-1004. In the example, a search without a tenant filter returns it; a post-filter applied after the top 5 removes it but leaves 2 rows instead of 5; only a filter inside the query is both safe and complete. That is a property of the query, and it holds whether the corpora share a cluster or not.

Inside PostgreSQL, a second line is row-level security. As documented on 2026-11-18, when it is enabled on a table, normal access must be allowed by a policy; without a policy the default is deny; a policy's USING expression is evaluated for each row before the conditions of the user's query. Superusers and roles with BYPASSRLS always bypass it, and table owners normally bypass it unless the table uses FORCE ROW LEVEL SECURITY. So the application's database role must not own the table, or must be forced. With approximate indexes, a selective row filter has the same starvation risk as any other filter (case UW-R09), so test the row count as well as the rows. Defense in depth for permission leaks is the subject of guardrails; the operational side of tenancy is on operations.

Precedents learned from human decisionsA feedback loop that needs a review window, provenance and a way back

A precedent corpus that grows from the underwriters' own decisions is a feedback loop: today's decision becomes tomorrow's evidence. Three controls keep the loop honest. A review window: in the insurance build, new precedents start pending and become active only after a review window, so a hasty decision does not immediately shape the next recommendation. Provenance: who decided, in which role, under which policy version, and whether it was an override, stored as columns and never inferred from text. A way back: quarantined and revoked states, and a filter on status = 'active' in every query, so a decision later found to be wrong stops influencing retrieval without deleting the record.

There is also a selection effect to watch. If the agent shows mostly approvals and underwriters mostly accept, the corpus fills with approvals that confirm the agent. Returning both sides (3 approve-side and 3 decline-side) and tracking the share of overrides over time are cheap ways to notice. Seeded rows must stay marked simulated and be removed or excluded before real decisions are used as evidence.

In one breath#

The insurance agent asks two different retrieval questions: which past applicants look like this one (Corpus A, a banded profile embedded, region, zone, occupancy and tenant as exact filters) and how similar cases were decided and why (Corpus B, rationale and context embedded, decision, policy version, chronology, override and human authority as columns). Guidance answers a third question with the highest authority, so current policy outranks any precedent, as UW-007 shows, and a precedent stays decision support, never a replacement for current policy or for the human decision. When the embedded text is only categories, a weighted structured distance can beat an embedding, and false matches measure it. Two corpora usually need two tables in one cluster; a split into two databases is earned by compliance, retention, permissions, latency or ownership.

find_similar_decisions now returns comparables and both sides of past decisions, each precedent labeled with its version and its decider. What remains is the moment those rows, the guidance passages and an untrusted broker attachment all land in one prompt, and the writer must cite the right one, abstain when nothing applies, and let current policy win. The next page, grounding, builds that prompt and shows each of those behaviors run.