The modern link attribution platform. Loved by world-class engineering teams at Twilio, Zillow, Jobber, Vercel, Raycast, and more.
TypeScript clickhousemysqlnextjsopen-sourceplanetscaleprismatailwindcsstinybirdtypescriptupstashvercel
Use reciprocal rank fusion for Turbopuffer search branches
Rafic1d835f9a088
diff --git a/apps/web/lib/api/partners/search/providers/turbopuffer.ts b/apps/web/lib/api/partners/search/providers/turbopuffer.tsindex 0d54f51529..70ef727ad8 100644--- a/apps/web/lib/api/partners/search/providers/turbopuffer.ts+++ b/apps/web/lib/api/partners/search/providers/turbopuffer.ts@@ -109,7 +109,7 @@ function serializeTurbopufferRow(}/**- * Two ranked branches, unioned by the caller.+ * Two ranked branches, rank-fused by the caller (see mergeBranchRows).** The text branch treats the last token as a prefix so "john" reaches* "johnson", matching how the Redis provider's $smart behaves. The n-gram@@ -140,25 +140,34 @@ function buildQueryBranches(programId: string, query: string) {return branches;}+// The standard reciprocal-rank-fusion constant: dampens the gap between+// neighboring ranks so one branch's top result cannot drown out the other's.+const RRF_RANK_CONSTANT = 60;++/**+ * Fuses the branches by rank (RRF) rather than by score. BM25 scores from+ * different clauses are not comparable — the n-gram branch sums over many+ * trigram terms and runs numerically hotter than the text branch — but rank+ * positions are. Each document scores Σ 1/(60 + rank) across the branches it+ * appears in, so a document found by both branches receives a contribution+ * from each, and the raw `$dist` values are deliberately unused. Relies on+ * each branch's rows arriving in the server's relevance order.+ */function mergeBranchRows(branches: { rows?: { id: string | number; $dist?: number }[] }[],limit: number,) {- const bestById = new Map<string, number>();+ const scoreById = new Map<string, number>();for (const branch of branches) {- for (const row of branch.rows ?? []) {+ (branch.rows ?? []).forEach((row, index) => {const id = String(row.id);- const score = row.$dist ?? 0;- // Scores come from different BM25 clauses and are not directly- // comparable; the higher one only decides ordering within the union.- if (!bestById.has(id) || score > bestById.get(id)!) {- bestById.set(id, score);- }- }+ const contribution = 1 / (RRF_RANK_CONSTANT + index + 1);+ scoreById.set(id, (scoreById.get(id) ?? 0) + contribution);+ });}- return Array.from(bestById, ([id, score]) => ({ id, score }))+ return Array.from(scoreById, ([id, score]) => ({ id, score })).sort((left, right) =>right.score - left.score || left.id.localeCompare(right.id),diff --git a/apps/web/tests/partners/turbopuffer-partner-search-provider.test.ts b/apps/web/tests/partners/turbopuffer-partner-search-provider.test.tsindex 2f7e13cafd..a94d038185 100644--- a/apps/web/tests/partners/turbopuffer-partner-search-provider.test.ts+++ b/apps/web/tests/partners/turbopuffer-partner-search-provider.test.ts@@ -163,14 +163,17 @@ describe("Turbopuffer partner search provider", () => {expect(queries).toHaveLength(1);});- it("unions branches, keeping the better score for a shared document", async () => {+ it("fuses branches by rank, boosting documents found by both", async () => {+ // Raw $dist values are incomparable across branches, so they must not+ // decide the order: pge_2 carries the highest raw score but only one+ // branch found it, while both branches found pge_1.mocks.multiQuery.mockResolvedValue({results: [{ rows: [{ id: "pge_1", $dist: 0.4 }] },{rows: [+ { id: "pge_2", $dist: 7.6 },{ id: "pge_1", $dist: 0.9 },- { id: "pge_2", $dist: 0.6 },],},],@@ -182,10 +185,27 @@ describe("Turbopuffer partner search provider", () => {limit: 10,});- expect(hits).toEqual([- { id: "pge_1", score: 0.9 },- { id: "pge_2", score: 0.6 },- ]);+ expect(hits.map(({ id }) => id)).toEqual(["pge_1", "pge_2"]);+ // RRF: rank 1 + rank 2 across branches vs rank 1 in one branch.+ expect(hits[0].score).toBeCloseTo(1 / 61 + 1 / 62, 10);+ expect(hits[1].score).toBeCloseTo(1 / 61, 10);+ });++ it("breaks cross-branch rank ties deterministically by ID", async () => {+ mocks.multiQuery.mockResolvedValue({+ results: [+ { rows: [{ id: "pge_b", $dist: 9.5 }] },+ { rows: [{ id: "pge_a", $dist: 0.2 }] },+ ],+ });++ const { hits } = await createProvider().searchCandidates({+ programId: "prog_test",+ query: "examp",+ limit: 10,+ });++ expect(hits.map(({ id }) => id)).toEqual(["pge_a", "pge_b"]);});it("never returns more than the requested limit", async () => {