Skip to content

πŸͺ’ Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

perf(scores): revert FINAL rows path for the scores table (#18715)

Niklas Semmler086dbced746b
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.ts
index 6bf46dc2dd..0cef3e201f 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,7 +10,6 @@ import {
import {
isSeekEligibleFilter,
scoreOnlyFiltersAreSeekEligible,
- scoreOnlyFiltersHaveIndexedLookup,
} from "./score-seek-eligibility";
const projectIdFilter = () =>
@@ -231,31 +230,3 @@ 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.ts
index 99708654b4..f151112f81 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,14 +66,3 @@ 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.ts
index 5c305069c5..cd8ee8c16f 100644
--- a/packages/shared/src/server/queries/index.ts
+++ b/packages/shared/src/server/queries/index.ts
@@ -112,5 +112,4 @@ 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.snap
index 622f2b8e52..588ad5e1a1 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
@@ -201,14 +201,15 @@ exports[`scores selective-seek: emitted SQL > full SQL text (one representative
{
"fn": "queryClickhouse",
"params": {
- "param1": [
+ "param1": "seek-project",
+ "param2": [
"NUMERIC",
"BOOLEAN",
"CATEGORICAL",
"TEXT",
],
- "param2": "seek-project",
- "param3": "0.5",
+ "param3": "seek-project",
+ "param4": "0.5",
},
"route": "unknown",
"sql": "SELECT
@@ -243,13 +244,34 @@ FROM
(
SELECT s.*
FROM scores AS s
- FINAL
- WHERE (s.data_type IN ({param1:Array(String)})) AND (project_id = {param2:String}) AND (s.value > {param3:Decimal64(12)})
+ 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
) AS s
ORDER BY
s.timestamp DESC,
- s.id DESC
-SETTINGS do_not_merge_across_partitions_select_final = 1",
+ s.id DESC",
},
]
`;
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.ts
index affac87e83..210c4c7eeb 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,15 +145,12 @@ 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 () => {
@@ -161,20 +158,12 @@ 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", () => {
@@ -186,7 +175,6 @@ 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);
});
@@ -280,10 +268,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) β€” 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 asserted
+// 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
const 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.ts
index ff05f6e01f..9587d31e12 100644
--- a/packages/shared/src/server/repositories/scores.ts
+++ b/packages/shared/src/server/repositories/scores.ts
@@ -37,7 +37,6 @@ import {
DateTimeFilter,
NumberFilter,
scoreOnlyFiltersAreSeekEligible,
- scoreOnlyFiltersHaveIndexedLookup,
} from "../queries";
import { FilterCondition, FilterState, TimeFilter } from "../../types";
import {
@@ -1673,17 +1672,27 @@ const getScoresUiGenericFromEvents = async <T>(props: {
`;
// ── Selective seek ────────────────────────────────────────────────────────
- // 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);
+ // 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);
const seekSubquery = seekEligible
? `
SELECT DISTINCT s.project_id, toDate(s.timestamp), s.name, s.id
@@ -1693,44 +1702,48 @@ const getScoresUiGenericFromEvents = async <T>(props: {
${scoreOnlyFilterRes?.query ? `AND ${scoreOnlyFilterRes.query}` : ""}`
: "";
- // Pre-dedup scan of the GROUP BY paths. Every condition is on dedup-key
- // columns, so it keeps or drops whole keys.
+ // 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.
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 all paths.
- const outerConditions = `s.data_type IN ({dataTypes: Array(String)})
+ // Post-dedup outer filters, shared by the count and rows paths.
+ const outerWhereClause = `
+ WHERE s.data_type IN ({dataTypes: Array(String)})
${scoreOnlyFilterRes?.query ? `AND ${scoreOnlyFilterRes.query}` : ""}`;
- // 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.
+ // ── 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.
//
- // count: one argMax GROUP BY pass, then filter.
+ // 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.
//
- // 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.
+ // 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 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}
- ${withIdTiebreaker(orderByToClickhouseSql(orderBy ?? null, scoresTableUiColumnDefinitionsFromEvents), orderBy)}
- ${limit !== undefined && offset !== undefined ? `limit {limit: Int32} offset {offset: Int32}` : ""}`;
+ // 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`).
const query =
props.select === "count"
? `
@@ -1749,22 +1762,9 @@ const getScoresUiGenericFromEvents = async <T>(props: {
GROUP BY s.project_id, toDate(s.timestamp), s.name, s.id
) s
${eventsJoin}
- WHERE ${outerConditions}
+ ${outerWhereClause}
`
- : 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}
@@ -1787,10 +1787,12 @@ const getScoresUiGenericFromEvents = async <T>(props: {
AND s.name = latest.latest_name
AND s.id = latest.latest_id
AND s.event_ts = latest.latest_event_ts
- WHERE ${outerConditions}
+ ${outerWhereClause}
LIMIT 1 BY s.project_id, toDate(s.timestamp), s.name, s.id
) s
- ${pageClause}
+ ${eventsJoin}
+ ${withIdTiebreaker(orderByToClickhouseSql(orderBy ?? null, scoresTableUiColumnDefinitionsFromEvents), orderBy)}
+ ${limit !== undefined && offset !== undefined ? `limit {limit: Int32} offset {offset: Int32}` : ""}
`;
const input = {
diff --git a/web/src/__tests__/server/scores-trpc.servertest.ts b/web/src/__tests__/server/scores-trpc.servertest.ts
index c324ee9504..01a7f70742 100644
--- a/web/src/__tests__/server/scores-trpc.servertest.ts
+++ b/web/src/__tests__/server/scores-trpc.servertest.ts
@@ -47,7 +47,6 @@ 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";
@@ -114,25 +113,6 @@ 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({