Skip to content

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

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.ts
index 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.ts
index 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.ts
index 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.snap
index 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.ts
index 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 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 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_name
AND s.id = latest.latest_id
AND 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.ts
index 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({