πͺ’ Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.
TypeScript analyticsautogenevaluationlangchainlarge-language-modelsllama-indexllmllm-evaluationllm-observabilityllmopsmonitoringobservabilityopen-sourceopenaiplaygroundprompt-engineeringprompt-managementself-hostedycombinator
perf(scores): dedup events rows path via FINAL (#18028)
Niklas Semmler0b2092af00e2
diff --git a/packages/shared/src/server/queries/clickhouse-sql/score-seek-eligibility.test.ts b/packages/shared/src/server/queries/clickhouse-sql/score-seek-eligibility.test.tsindex 0cef3e201f..6bf46dc2dd 100644--- a/packages/shared/src/server/queries/clickhouse-sql/score-seek-eligibility.test.ts+++ b/packages/shared/src/server/queries/clickhouse-sql/score-seek-eligibility.test.ts@@ -10,6 +10,7 @@ import {import {isSeekEligibleFilter,scoreOnlyFiltersAreSeekEligible,+ scoreOnlyFiltersHaveIndexedLookup,} from "./score-seek-eligibility";const projectIdFilter = () =>@@ -230,3 +231,31 @@ describe("scoreOnlyFiltersAreSeekEligible", () => {).toBe(false);});});++describe("scoreOnlyFiltersHaveIndexedLookup", () => {+ it("is true for a skip-index lookup, also next to a name filter", () => {+ expect(+ scoreOnlyFiltersHaveIndexedLookup(+ new FilterList([projectIdFilter(), traceIdEq()]),+ ),+ ).toBe(true);+ expect(+ scoreOnlyFiltersHaveIndexedLookup(+ new FilterList([projectIdFilter(), nameEq(), sessionIdEq()]),+ ),+ ).toBe(true);+ });++ it("is false for name-only and non-indexed filters", () => {+ expect(+ scoreOnlyFiltersHaveIndexedLookup(+ new FilterList([projectIdFilter(), nameIn(["accuracy"])]),+ ),+ ).toBe(false);+ expect(+ scoreOnlyFiltersHaveIndexedLookup(+ new FilterList([projectIdFilter(), valueRange()]),+ ),+ ).toBe(false);+ });+});diff --git a/packages/shared/src/server/queries/clickhouse-sql/score-seek-eligibility.ts b/packages/shared/src/server/queries/clickhouse-sql/score-seek-eligibility.tsindex f151112f81..99708654b4 100644--- a/packages/shared/src/server/queries/clickhouse-sql/score-seek-eligibility.ts+++ b/packages/shared/src/server/queries/clickhouse-sql/score-seek-eligibility.ts@@ -66,3 +66,14 @@ export const isSeekEligibleFilter = (filter: Filter): boolean => {*/export const scoreOnlyFiltersAreSeekEligible = (filters: FilterList): boolean =>filters.some(isSeekEligibleFilter);++/**+ * Does a score-only conjunct look up scores through a bloom-filter skip index+ * (any seek-eligible field except `name`, which is in the sorting key)? Such+ * matches are scattered across the sorting key, which makes FINAL read far+ * more than the matches themselves.+ */+export const scoreOnlyFiltersHaveIndexedLookup = (+ filters: FilterList,+): boolean =>+ filters.some((f) => isSeekEligibleFilter(f) && f.field !== "name");diff --git a/packages/shared/src/server/queries/index.ts b/packages/shared/src/server/queries/index.tsindex cd8ee8c16f..5c305069c5 100644--- a/packages/shared/src/server/queries/index.ts+++ b/packages/shared/src/server/queries/index.ts@@ -112,4 +112,5 @@ export { extractTimeFilter } from "./clickhouse-sql/filter-utils";export {isSeekEligibleFilter,scoreOnlyFiltersAreSeekEligible,+ scoreOnlyFiltersHaveIndexedLookup,} from "./clickhouse-sql/score-seek-eligibility";diff --git a/packages/shared/src/server/repositories/__snapshots__/scores-selective-seek.golden.test.ts.snap b/packages/shared/src/server/repositories/__snapshots__/scores-selective-seek.golden.test.ts.snapindex 4697e11a93..73aed6603e 100644--- a/packages/shared/src/server/repositories/__snapshots__/scores-selective-seek.golden.test.ts.snap+++ b/packages/shared/src/server/repositories/__snapshots__/scores-selective-seek.golden.test.ts.snap@@ -199,15 +199,14 @@ exports[`scores selective-seek: emitted SQL > full SQL text (one representative{"fn": "queryClickhouse","params": {- "param1": "seek-project",- "param2": [+ "param1": ["NUMERIC","BOOLEAN","CATEGORICAL","TEXT",],- "param3": "seek-project",- "param4": "0.5",+ "param2": "seek-project",+ "param3": "0.5",},"route": "unknown","sql": "SELECT@@ -242,32 +241,11 @@ FROM(SELECT s.*FROM scores AS s- INNER JOIN- (- SELECT- s.project_id AS latest_project_id,- toDate(s.timestamp) AS latest_date,- s.name AS latest_name,- s.id AS latest_id,- max(s.event_ts) AS latest_event_ts- FROM scores AS s- WHERE s.project_id = {param1:String}- GROUP BY- s.project_id,- toDate(s.timestamp),- s.name,- s.id- ) AS latest ON (- s.project_id = latest.latest_project_id- ) AND (toDate(s.timestamp) = latest.latest_date) AND (s.name = latest.latest_name) AND (s.id = latest.latest_id) AND (s.event_ts = latest.latest_event_ts)- WHERE (s.data_type IN ({param2:Array(String)})) AND (project_id = {param3:String}) AND (s.value > {param4:Decimal64(12)})- LIMIT 1 BY- s.project_id,- toDate(s.timestamp),- s.name,- s.id+ FINAL+ WHERE (s.data_type IN ({param1:Array(String)})) AND (project_id = {param2:String}) AND (s.value > {param3:Decimal64(12)})) AS s-ORDER BY s.timestamp DESC",+ORDER BY s.timestamp DESC+SETTINGS do_not_merge_across_partitions_select_final = 1",},]`;diff --git a/packages/shared/src/server/repositories/scores-selective-seek.golden.test.ts b/packages/shared/src/server/repositories/scores-selective-seek.golden.test.tsindex 210c4c7eeb..affac87e83 100644--- a/packages/shared/src/server/repositories/scores-selective-seek.golden.test.ts+++ b/packages/shared/src/server/repositories/scores-selective-seek.golden.test.ts@@ -145,12 +145,15 @@ describeWithFormat("scores selective-seek: emitted SQL", () => {{ name: "observation_id =", filter: observationIdEq("O1") },{ name: "name IN", filter: nameIn(["n1"]) },];+ const indexedLookups = eligible.filter(({ name }) => name !== "name IN");const ineligible = [{ name: "value range", filter: valueGt(0.5) },{ name: "environment none of", filter: environmentNoneOf(["dev"]) },{ name: "no filter", filter: [] as FilterState },];+ // Skip-index lookups keep the manual dedup + seek on the rows path; a name+ // filter is in the sorting key, so its rows path reads FINAL.describe("eligible β seek phase present", () => {for (const { name, filter } of eligible) {it(`count: ${name}`, async () => {@@ -158,12 +161,20 @@ describeWithFormat("scores selective-seek: emitted SQL", () => {expect(q.query).toContain("SELECT DISTINCT");expect(q.query).toMatch(SEEK_TUPLE_IN);});+ }+ for (const { name, filter } of indexedLookups) {it(`rows: ${name}`, async () => {const q = await captureRowsSql(filter);+ expect(q.query).not.toContain("FINAL");expect(q.query).toContain("SELECT DISTINCT");expect(q.query).toMatch(SEEK_TUPLE_IN);});}+ it("rows: name IN reads FINAL without the seek", async () => {+ const q = await captureRowsSql(nameIn(["n1"]));+ expect(q.query).toContain("FINAL");+ expect(q.query).not.toContain("SELECT DISTINCT");+ });});describe("ineligible β fallback unchanged, no seek", () => {@@ -175,6 +186,7 @@ describeWithFormat("scores selective-seek: emitted SQL", () => {});it(`rows: ${name}`, async () => {const q = await captureRowsSql(filter);+ expect(q.query).toContain("FINAL");expect(q.query).not.toContain("SELECT DISTINCT");expect(q.query).not.toMatch(SEEK_TUPLE_IN);});@@ -268,10 +280,10 @@ const SCORES_DDL = `// c: two day-buckets (distinct dedup groups), trace_id T3// d: has observation_id O1// e: value mutates 0.9 -> 0.1 (latest) β exercises dedup-then-filter-// f: two identical rows sharing the SAME max event_ts (a tie) β the equality-// join emits both, so LIMIT 1 BY must collapse them to one row. Divergent-// ties (tied versions differing in a filtered column) are FINAL-arbitrary by-// design β FINAL's own pick flips with insert order β so they are not asserted+// f: two identical rows sharing the SAME max event_ts (a tie) β must collapse+// to one row. Divergent ties (tied versions differing in a filtered column)+// are FINAL-arbitrary by design β FINAL's own pick flips with insert order β+// so they are not assertedconst ROWS: Array<[string, string, string, string, string | null, number, number]> = [diff --git a/packages/shared/src/server/repositories/scores.ts b/packages/shared/src/server/repositories/scores.tsindex d1d17ebe51..7da2779c36 100644--- a/packages/shared/src/server/repositories/scores.ts+++ b/packages/shared/src/server/repositories/scores.ts@@ -37,6 +37,7 @@ import {DateTimeFilter,NumberFilter,scoreOnlyFiltersAreSeekEligible,+ scoreOnlyFiltersHaveIndexedLookup,} from "../queries";import { FilterCondition, FilterState, TimeFilter } from "../../types";import {@@ -1655,27 +1656,17 @@ const getScoresUiGenericFromEvents = async <T>(props: {`;// ββ Selective seek ββββββββββββββββββββββββββββββββββββββββββββββββββββββββ- // A highly selective score-only filter (single trace/observation/id, or a- // name) otherwise reconstructs the whole project before the outer WHERE- // discards almost everything. When at least one score-only conjunct is- // index-prunable (see scoreOnlyFiltersAreSeekEligible), first collect the- // matching dedup keys via the bloom / primary indexes, then reconstruct only- // those keys.- //- // The seek carries the *entire* score-only predicate, not just the prunable- // conjuncts: it stays a superset collection (proof below), the index prunes- // granules via the eligible conjuncts, and the remaining conjuncts shrink the- // key set within surviving granules.- //- // Correctness: if a key's deduped-latest satisfies predicate P, its latest raw- // row satisfies P (the latest *is* a raw row), so `SELECT DISTINCT β¦ WHERE P`- // over raw rows collects it β `{latest matches P} β {some raw row matches P}`- // for any P (negation, null, range included). False positives (a key seeked- // via an older matching version whose latest no longer matches) are removed by- // re-applying P in the outer WHERE post-dedup. The seek's projection is the- // dedup key only, all immutable within a group, so the resulting tuple IN- // touches only dedup-key columns and is safe pre-dedup.- const seekEligible = scoreOnlyFiltersAreSeekEligible(scoreOnlyFilters);+ // When a score-only conjunct is index-prunable, collect the matching dedup+ // keys first and reconstruct only those. The seek applies the whole+ // score-only predicate P to raw rows. A key whose latest version matches P+ // has a raw row matching P, so the key set is a superset; the outer WHERE+ // re-applies P after dedup to drop keys seeked via a stale version. The FINAL+ // rows path does not seek.+ const rowsUseFinal =+ props.select === "rows" &&+ !scoreOnlyFiltersHaveIndexedLookup(scoreOnlyFilters);+ const seekEligible =+ !rowsUseFinal && scoreOnlyFiltersAreSeekEligible(scoreOnlyFilters);const seekSubquery = seekEligible? `SELECT DISTINCT s.project_id, toDate(s.timestamp), s.name, s.id@@ -1685,48 +1676,44 @@ const getScoresUiGenericFromEvents = async <T>(props: {${scoreOnlyFilterRes?.query ? `AND ${scoreOnlyFilterRes.query}` : ""}`: "";- // Pre-dedup inner scan: project scope + coarse date prune only. Mutable-column- // filters run post-dedup in the outer WHERE (see the dedup rule below). When- // the seek fired, the tuple IN restricts the reconstruct scan to seeked keys;- // it references only dedup-key columns, so it is safe pre-dedup.+ // Pre-dedup scan of the GROUP BY paths. Every condition is on dedup-key+ // columns, so it keeps or drops whole keys.const innerScanWhere = `WHERE s.project_id = {projectId: String}${innerDatePruneQuery ? `AND ${innerDatePruneQuery}` : ""}${seekSubquery ? `AND (s.project_id, toDate(s.timestamp), s.name, s.id) IN (${seekSubquery}\n )` : ""}`;- // Post-dedup outer filters, shared by the count and rows paths.- const outerWhereClause = `- WHERE s.data_type IN ({dataTypes: Array(String)})+ // Post-dedup outer filters, shared by all paths.+ const outerConditions = `s.data_type IN ({dataTypes: Array(String)})${scoreOnlyFilterRes?.query ? `AND ${scoreOnlyFilterRes.query}` : ""}`;- // ββ Dedup without FINAL βββββββββββββββββββββββββββββββββββββββββββββββββββ- // Reads dedup the ReplacingMergeTree by reconstructing each score's latest- // version instead of FINAL. The count path collapses columns with one argMax- // GROUP BY pass. The rows path needs every (incl. wide Map/String) column, so- // it INNER JOINs scores back to a GROUP BY subquery holding each key's- // max(event_ts), matching on the full sorting key + that event_ts. Only the- // latest version has event_ts = max, so the join *is* the dedup: every joined- // row is a latest version.+ // No explicit project_id condition: outerConditions already carries it.+ const rowsScanWhere = `+ WHERE ${outerConditions}+ ${innerDatePruneQuery ? `AND ${innerDatePruneQuery}` : ""}`;++ // ββ Dedup βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ+ // Filter after dedup, never before: value / comment / timestamp / trace_id+ // are mutable, so filtering raw rows can surface a stale version.//- // Rule: filter AFTER dedup, never before. value / comment / timestamp /- // trace_id are mutable across versions, so filtering raw rows can surface a- // stale version (filter value>0.5 on v1=0.9βv2=0.1 keeps v1; FINAL keeps none).- // Filtering the join output honours this β filters only ever see latest- // versions. The GROUP BY that finds max(event_ts) carries only project scope +- // a coarse toDate prune (innerDatePruneQuery) + the seek (when eligible), so- // whole buckets are kept/dropped, the latest is never lost pre-dedup, and the- // seek scans once.+ // count: one argMax GROUP BY pass, then filter.//- // Filters run INSIDE the dedup subquery (with the join) so ClickHouse prunes- // the wide scan by the real predicates before assembling the full join. The- // LIMIT 1 BY there collapses the only remaining duplicates: two raw rows- // sharing a key's max event_ts. That tie is two versions with equal version- // timestamps, where FINAL itself keeps an arbitrary row (its answer flips with- // insert order), so an arbitrary tie pick is FINAL-consistent.+ // rows: `scores FINAL`. ClickHouse applies filters on non-sorting-key columns+ // after the merge. do_not_merge_across_partitions_select_final keeps+ // partition pruning (ClickHouse >= 26.3 drops it under FINAL otherwise); it is+ // correct because toDate(timestamp) is in the sorting key, so all versions of+ // a key share a monthly partition.//- // The trace join, ORDER BY, and LIMIT/OFFSET run OUTSIDE the subquery, at one- // level, so pagination follows the requested sort (and a traces-column sort can- // reference the joined `e`).+ // rows with a skip-index lookup (trace_id, observation_id, id, ...): the+ // matches are scattered, and FINAL would read every granule around them with+ // all columns. Instead, INNER JOIN the seeked keys to their max(event_ts).+ // LIMIT 1 BY breaks event_ts ties arbitrarily, as FINAL does.+ //+ // The trace join, ORDER BY and pagination run outside the dedup subquery.+ const pageClause = `+ ${eventsJoin}+ ${orderByToClickhouseSql(orderBy ?? null, scoresTableUiColumnDefinitionsFromEvents)}+ ${limit !== undefined && offset !== undefined ? `limit {limit: Int32} offset {offset: Int32}` : ""}`;const query =props.select === "count"? `@@ -1745,9 +1732,22 @@ const getScoresUiGenericFromEvents = async <T>(props: {GROUP BY s.project_id, toDate(s.timestamp), s.name, s.id) s${eventsJoin}- ${outerWhereClause}+ WHERE ${outerConditions}`- : `+ : rowsUseFinal+ ? `+ ${tracesCTEClause}+ SELECT+ ${rowSelect}+ FROM (+ SELECT s.*+ FROM scores s FINAL+ ${rowsScanWhere}+ ) s+ ${pageClause}+ SETTINGS do_not_merge_across_partitions_select_final = 1+ `+ : `${tracesCTEClause}SELECT${rowSelect}@@ -1770,12 +1770,10 @@ const getScoresUiGenericFromEvents = async <T>(props: {AND s.name = latest.latest_nameAND s.id = latest.latest_idAND s.event_ts = latest.latest_event_ts- ${outerWhereClause}+ WHERE ${outerConditions}LIMIT 1 BY s.project_id, toDate(s.timestamp), s.name, s.id) s- ${eventsJoin}- ${orderByToClickhouseSql(orderBy ?? null, scoresTableUiColumnDefinitionsFromEvents)}- ${limit !== undefined && offset !== undefined ? `limit {limit: Int32} offset {offset: Int32}` : ""}+ ${pageClause}`;const input = {diff --git a/web/src/__tests__/server/scores-trpc.servertest.ts b/web/src/__tests__/server/scores-trpc.servertest.tsindex 2217744e9a..23787b0d42 100644--- a/web/src/__tests__/server/scores-trpc.servertest.ts+++ b/web/src/__tests__/server/scores-trpc.servertest.ts@@ -47,6 +47,7 @@ import {QueueJobs,createOrgProjectAndApiKey,getScoreById,+ queryClickhouse,} from "@langfuse/shared/src/server";import { env } from "@/src/env.mjs";import { observationScopeFilter } from "@/src/features/filters/config/scores-config";@@ -113,6 +114,25 @@ describe("scores trpc", () => {});describe("scores.all", () => {+ // allFromEvents reads scores FINAL with+ // do_not_merge_across_partitions_select_final = 1, which is only correct+ // while every version of a sorting key lands in one partition.+ it("keeps each scores sorting key within one partition", async () => {+ const [table] = await queryClickhouse<{+ partition_key: string;+ sorting_key: string;+ }>({+ query: `+ SELECT partition_key, sorting_key+ FROM system.tables+ WHERE database = currentDatabase() AND name = 'scores'+ `,+ });++ expect(table.partition_key).toBe("toYYYYMM(timestamp)");+ expect(table.sorting_key).toBe("project_id, toDate(timestamp), name, id");+ });+it("preserves evaluator-test filters for score rows and counts on both read paths", async () => {const scores = [createTraceScore({