Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

perf(scores): allow skipping scores dedup for projects that never update scores (#19157)

Niklas Semmler2ec7d561c100
diff --git a/packages/shared/src/env.ts b/packages/shared/src/env.ts
index d46b537f66..7736a34bb6 100644
--- a/packages/shared/src/env.ts
+++ b/packages/shared/src/env.ts
@@ -740,6 +740,20 @@ const EnvSchema = z.object({
LANGFUSE_SKIP_FINAL_FOR_OTEL_PROJECTS: z
.enum(["true", "false"])
.default("false"),
+ // Comma-separated project ids whose scores are never updated after ingestion.
+ // Reads of the scores table skip deduplication (FINAL / LIMIT 1 BY) for them.
+ LANGFUSE_SKIP_SCORES_DEDUP_PROJECT_IDS: z
+ .string()
+ .default("")
+ .transform(
+ (value) =>
+ new Set(
+ value
+ .split(",")
+ .map((id) => id.trim())
+ .filter(Boolean),
+ ),
+ ),
// Langfuse AI Features
LANGFUSE_AI_FEATURES_PUBLIC_KEY: z.string().optional(),
diff --git a/packages/shared/src/features/query/server/queryBuilder.filterValidation.test.ts b/packages/shared/src/features/query/server/queryBuilder.filterValidation.test.ts
index 5ff42e84bf..b00f2b7331 100644
--- a/packages/shared/src/features/query/server/queryBuilder.filterValidation.test.ts
+++ b/packages/shared/src/features/query/server/queryBuilder.filterValidation.test.ts
@@ -11,6 +11,7 @@ import { QueryBuilder } from "./queryBuilder";
// Mock it so these validation tests stay unit-level and do not need ClickHouse.
vi.mock("../../../server/queries/clickhouse-sql/query-options", () => ({
shouldSkipObservationsFinal: vi.fn().mockResolvedValue(false),
+ shouldSkipScoresDedup: vi.fn().mockReturnValue(false),
}));
const baseQuery = {
diff --git a/packages/shared/src/features/query/server/queryBuilder.intervalBucketing.test.ts b/packages/shared/src/features/query/server/queryBuilder.intervalBucketing.test.ts
index 230069b521..fa5f22cb34 100644
--- a/packages/shared/src/features/query/server/queryBuilder.intervalBucketing.test.ts
+++ b/packages/shared/src/features/query/server/queryBuilder.intervalBucketing.test.ts
@@ -7,6 +7,7 @@ import { QueryBuilder } from "./queryBuilder";
vi.mock("../../../server/queries/clickhouse-sql/query-options", () => ({
shouldSkipObservationsFinal: vi.fn().mockResolvedValue(false),
+ shouldSkipScoresDedup: vi.fn().mockReturnValue(false),
}));
/** windowBucketCases maps each window token to its expected ClickHouse interval. */
diff --git a/packages/shared/src/features/query/server/queryBuilder.pairExpand.test.ts b/packages/shared/src/features/query/server/queryBuilder.pairExpand.test.ts
index fce2dc40e1..506d64bbb7 100644
--- a/packages/shared/src/features/query/server/queryBuilder.pairExpand.test.ts
+++ b/packages/shared/src/features/query/server/queryBuilder.pairExpand.test.ts
@@ -7,6 +7,7 @@ import { QueryBuilder } from "./queryBuilder";
// Mock it so these stay unit-level and do not need ClickHouse.
vi.mock("../../../server/queries/clickhouse-sql/query-options", () => ({
shouldSkipObservationsFinal: vi.fn().mockResolvedValue(false),
+ shouldSkipScoresDedup: vi.fn().mockReturnValue(false),
}));
const usageByTypeTimeseries = {
diff --git a/packages/shared/src/features/query/server/queryBuilder.scoresListableCountView.test.ts b/packages/shared/src/features/query/server/queryBuilder.scoresListableCountView.test.ts
index 333e5a61b1..ece720f632 100644
--- a/packages/shared/src/features/query/server/queryBuilder.scoresListableCountView.test.ts
+++ b/packages/shared/src/features/query/server/queryBuilder.scoresListableCountView.test.ts
@@ -9,11 +9,13 @@ import {
type QueryType,
} from "../types";
import { QueryBuilder } from "./queryBuilder";
+import { shouldSkipScoresDedup } from "../../../server/queries/clickhouse-sql/query-options";
// QueryBuilder.build checks the OTEL FINAL optimization before filter lowering.
// Mock it so this stays unit-level and does not need ClickHouse.
vi.mock("../../../server/queries/clickhouse-sql/query-options", () => ({
shouldSkipObservationsFinal: vi.fn().mockResolvedValue(false),
+ shouldSkipScoresDedup: vi.fn().mockReturnValue(false),
}));
const baseQuery = {
@@ -70,3 +72,28 @@ describe("scores-listable-count view (internal-only, powers ScoresOutlierStrip's
expect(dataTypeParam).not.toContain("CORRECTION");
});
});
+
+describe("scores views for projects that skip scores dedup", () => {
+ it.each([
+ ["v1", "scores-numeric", "scores_numeric"],
+ ["v1", "scores-categorical", "scores_categorical"],
+ ["v1", "scores-boolean", "scores_boolean"],
+ ["v1", SCORES_LISTABLE_COUNT_VIEW, "scores_listable_count"],
+ ["v2", "scores-numeric", "scores_numeric"],
+ ["v2", "scores-categorical", "scores_categorical"],
+ ["v2", "scores-boolean", "scores_boolean"],
+ ] as const)(
+ "%s %s reads the scores table without FINAL",
+ async (version, view, alias) => {
+ vi.mocked(shouldSkipScoresDedup).mockReturnValueOnce(true);
+
+ const { query: compiledQuery } = await new QueryBuilder(
+ undefined,
+ version,
+ ).build({ ...baseQuery, view }, "test-project");
+
+ expect(compiledQuery).toContain(`FROM scores ${alias}`);
+ expect(compiledQuery).not.toMatch(/\bFINAL\b/);
+ },
+ );
+});
diff --git a/packages/shared/src/features/query/server/queryBuilder.ts b/packages/shared/src/features/query/server/queryBuilder.ts
index de679788e6..3e57c4d141 100644
--- a/packages/shared/src/features/query/server/queryBuilder.ts
+++ b/packages/shared/src/features/query/server/queryBuilder.ts
@@ -1,6 +1,9 @@
import { randomUUID } from "crypto";
import { type z } from "zod";
-import { shouldSkipObservationsFinal } from "../../../server/queries/clickhouse-sql/query-options";
+import {
+ shouldSkipObservationsFinal,
+ shouldSkipScoresDedup,
+} from "../../../server/queries/clickhouse-sql/query-options";
import {
bindUtcDateTimeParam,
FilterList,
@@ -796,6 +799,7 @@ export class QueryBuilder {
filterList: FilterList,
query: QueryType,
skipObservationsFinal: boolean,
+ skipScoresFinal: boolean,
) {
const relationJoins = [];
for (const relationTableName of relationTables) {
@@ -809,7 +813,8 @@ export class QueryBuilder {
// Conditionally add FINAL - skip for observations if flag is set, and respect per-relation useFinal
const shouldUseFinal =
(relation.useFinal ?? true) &&
- !(relation.name === "observations" && skipObservationsFinal);
+ !(relation.name === "observations" && skipObservationsFinal) &&
+ !(relation.name === "scores" && skipScoresFinal);
const alias =
relation.name !== relationTableName ? ` AS ${relationTableName}` : "";
let joinStatement = `INNER JOIN ${relation.name}${alias}${shouldUseFinal ? " FINAL" : ""} ${relation.joinConditionSql}`;
@@ -1564,6 +1569,7 @@ export class QueryBuilder {
// Check if we should skip FINAL modifier for observations (OTEL optimization)
const skipObservationsFinal = await shouldSkipObservationsFinal(projectId);
+ const skipScoresFinal = shouldSkipScoresDedup(projectId);
let view = this.getViewDeclaration(query.view);
// Events table never needs FINAL modifier (already deduplicated)
@@ -1577,6 +1583,11 @@ export class QueryBuilder {
...view,
baseCte: "observations", // Remove FINAL (was "observations FINAL")
};
+ } else if (view.baseCte.startsWith("scores ") && skipScoresFinal) {
+ view = {
+ ...view,
+ baseCte: view.baseCte.replace(/\s+FINAL$/, ""),
+ };
}
// Map dimensions and metrics
@@ -1654,6 +1665,7 @@ export class QueryBuilder {
filterList,
query,
skipObservationsFinal,
+ skipScoresFinal,
);
fromClause += ` ${relationJoins.join(" ")}`;
}
diff --git a/packages/shared/src/server/queries/clickhouse-sql/query-fragments.ts b/packages/shared/src/server/queries/clickhouse-sql/query-fragments.ts
index 335ffe7121..5b59fbe30e 100644
--- a/packages/shared/src/server/queries/clickhouse-sql/query-fragments.ts
+++ b/packages/shared/src/server/queries/clickhouse-sql/query-fragments.ts
@@ -2,6 +2,7 @@
* Reusable ClickHouse query fragments and CTEs
*/
+import { shouldSkipScoresDedup } from "./query-options";
import {
EventsAggregationQueryBuilder,
EventsAggQueryBuilder,
@@ -171,7 +172,7 @@ const buildScoresAggregationCTE = (
data_type,
string_value,
avg(value) as avg_value
- FROM scores FINAL
+ FROM scores ${shouldSkipScoresDedup(params.projectId) ? "" : "FINAL"}
WHERE project_id = {projectId: String}
${observationFilter}
${params.scoreRowsFilter ? `AND ${params.scoreRowsFilter.query}` : ""}
@@ -459,7 +460,7 @@ export const eventsSessionScoresAggregation = (params: {
data_type,
string_value,
avg(value) avg_value
- FROM scores s FINAL
+ FROM scores s ${shouldSkipScoresDedup(params.projectId) ? "" : "FINAL"}
WHERE
project_id = {projectId: String}
GROUP BY
@@ -576,7 +577,7 @@ export const buildScoresCTE = (params: ScoresCTEParams): CTEWithSchema => {
data_type,
string_value,
avg(value) avg_value
- FROM scores s FINAL
+ FROM scores s ${shouldSkipScoresDedup(params.projectId) ? "" : "FINAL"}
WHERE
project_id = {projectId: String}
${observationFilter}
diff --git a/packages/shared/src/server/queries/clickhouse-sql/query-options.ts b/packages/shared/src/server/queries/clickhouse-sql/query-options.ts
index 6ff34697ec..e00d5cde3c 100644
--- a/packages/shared/src/server/queries/clickhouse-sql/query-options.ts
+++ b/packages/shared/src/server/queries/clickhouse-sql/query-options.ts
@@ -33,3 +33,11 @@ export async function shouldSkipObservationsFinal(
return false;
}
+
+/**
+ * Whether reads of the scores table may skip deduplication (FINAL / LIMIT 1 BY)
+ * for this project. Only safe for projects that never update scores.
+ */
+export function shouldSkipScoresDedup(projectId: string): boolean {
+ return env.LANGFUSE_SKIP_SCORES_DEDUP_PROJECT_IDS.has(projectId);
+}
diff --git a/packages/shared/src/server/repositories/blobStorageExportWindow.test.ts b/packages/shared/src/server/repositories/blobStorageExportWindow.test.ts
index 4cb29be73b..c0543edc1d 100644
--- a/packages/shared/src/server/repositories/blobStorageExportWindow.test.ts
+++ b/packages/shared/src/server/repositories/blobStorageExportWindow.test.ts
@@ -20,6 +20,7 @@ vi.mock("./clickhouse", () => ({
vi.mock("../queries/clickhouse-sql/query-options", () => ({
shouldSkipObservationsFinal: vi.fn().mockResolvedValue(false),
+ shouldSkipScoresDedup: vi.fn().mockReturnValue(false),
}));
import { getTracesForBlobStorageExport } from "./traces";
diff --git a/packages/shared/src/server/repositories/dashboards.ts b/packages/shared/src/server/repositories/dashboards.ts
index fad9e259ed..e3f84631e4 100644
--- a/packages/shared/src/server/repositories/dashboards.ts
+++ b/packages/shared/src/server/repositories/dashboards.ts
@@ -1,3 +1,4 @@
+import { shouldSkipScoresDedup } from "../queries/clickhouse-sql/query-options";
import {
parseClickhouseUTCDateTimeFormat,
queryClickhouse,
@@ -64,7 +65,7 @@ export const getScoreAggregate = async (
avg(s.value) as avg_value,
s.source,
s.data_type
- FROM scores s FINAL
+ FROM scores s ${shouldSkipScoresDedup(projectId) ? "" : "FINAL"}
${hasTraceFilter ? "JOIN traces t FINAL ON t.id = s.trace_id AND t.project_id = s.project_id" : ""}
WHERE s.project_id = {projectId: String}
AND ${chFilterApplied.query}
diff --git a/packages/shared/src/server/repositories/dataset-run-items.ts b/packages/shared/src/server/repositories/dataset-run-items.ts
index 86fff63efe..6e9164d8cc 100644
--- a/packages/shared/src/server/repositories/dataset-run-items.ts
+++ b/packages/shared/src/server/repositories/dataset-run-items.ts
@@ -1,3 +1,4 @@
+import { shouldSkipScoresDedup } from "../queries/clickhouse-sql/query-options";
import { DatasetRunItemDomain } from "../../domain/dataset-run-items";
import { scoreBooleansAggregation } from "../queries/clickhouse-sql/query-fragments";
import { type OrderByState } from "../../interfaces/orderBy";
@@ -358,7 +359,7 @@ const getDatasetRunsTableInternal = async <T>(
data_type,
string_value,
avg(value) as avg_value
- FROM scores s FINAL
+ FROM scores s ${shouldSkipScoresDedup(projectId) ? "" : "FINAL"}
WHERE ${appliedScoresFilter.query}
AND s.trace_id IN (
SELECT dri.trace_id
@@ -670,7 +671,7 @@ const getQualifyingDatasetItems = async <T>(opts: {
data_type,
string_value,
avg(value) as avg_value
- FROM scores s FINAL
+ FROM scores s ${shouldSkipScoresDedup(projectId) ? "" : "FINAL"}
WHERE ${appliedScoresFilter.query}
AND s.trace_id IN (
SELECT dri.trace_id
@@ -853,7 +854,7 @@ const getDatasetRunItemsTableInternal = async <
data_type,
string_value,
avg(value) as avg_value
- FROM scores s FINAL
+ FROM scores s ${shouldSkipScoresDedup(projectId) ? "" : "FINAL"}
WHERE ${appliedScoresFilter.query}
AND s.trace_id IN (
SELECT dri.trace_id
diff --git a/packages/shared/src/server/repositories/observations.ts b/packages/shared/src/server/repositories/observations.ts
index f02f6bebc1..b0fb3d1d30 100644
--- a/packages/shared/src/server/repositories/observations.ts
+++ b/packages/shared/src/server/repositories/observations.ts
@@ -60,7 +60,10 @@ import {
} from "../../domain/observation-field-groups";
import { recordDistribution } from "../instrumentation";
import { DEFAULT_RENDERING_PROPS, RenderingProps } from "../utils/rendering";
-import { shouldSkipObservationsFinal } from "../queries/clickhouse-sql/query-options";
+import {
+ shouldSkipObservationsFinal,
+ shouldSkipScoresDedup,
+} from "../queries/clickhouse-sql/query-options";
/**
* Checks if observation exists in clickhouse.
@@ -811,7 +814,7 @@ const getObservationsTableInternal = async <T>(
data_type,
comment
FROM
- scores FINAL
+ scores ${shouldSkipScoresDedup(projectId) ? "" : "FINAL"}
WHERE ${appliedScoresFilter.query}
GROUP BY
trace_id,
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..e8a9959bac 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
@@ -18,6 +18,10 @@ const recorder = vi.hoisted(() => {
return { captured, uid };
});
+const mockShouldSkipScoresDedup = vi.hoisted(() =>
+ vi.fn<(projectId: string) => boolean>(() => false),
+);
+
vi.mock("./clickhouse", () => ({
queryClickhouse: vi.fn(async (opts: any) => {
recorder.captured.push({ fn: "queryClickhouse", ...opts });
@@ -39,6 +43,7 @@ vi.mock("./clickhouse", () => ({
// calls it.
vi.mock("../queries/clickhouse-sql/query-options", () => ({
shouldSkipObservationsFinal: vi.fn().mockResolvedValue(false),
+ shouldSkipScoresDedup: mockShouldSkipScoresDedup,
}));
// Import via the server barrel so it initializes in the correct order; entering
@@ -287,13 +292,15 @@ const ROWS: Array<
["f", "n1", "2026-01-10 05:00:00.000", "T2", null, 0.9, 3],
];
-const insertRows = () => {
- const values = ROWS.map(
- ([id, name, ts, traceId, obsId, value, eventTs]) =>
- `('${id}', '${ts}', '${PROJECT_ID}', '${traceId}', ${
- obsId === null ? "NULL" : `'${obsId}'`
- }, '${name}', ${value}, 'API', NULL, NULL, NULL, 'NUMERIC', NULL, NULL, 'default', NULL, NULL, NULL, NULL, NULL, map(), 'pk', 'sdk', '1', '${ts}', '${ts}', toDateTime64(${eventTs}, 3), 0)`,
- ).join(",\n");
+const insertRows = (rows = ROWS) => {
+ const values = rows
+ .map(
+ ([id, name, ts, traceId, obsId, value, eventTs]) =>
+ `('${id}', '${ts}', '${PROJECT_ID}', '${traceId}', ${
+ obsId === null ? "NULL" : `'${obsId}'`
+ }, '${name}', ${value}, 'API', NULL, NULL, NULL, 'NUMERIC', NULL, NULL, 'default', NULL, NULL, NULL, NULL, NULL, map(), 'pk', 'sdk', '1', '${ts}', '${ts}', toDateTime64(${eventTs}, 3), 0)`,
+ )
+ .join(",\n");
return `INSERT INTO scores VALUES ${values};`;
};
@@ -304,8 +311,8 @@ const finalCount = (predicate: string) =>
const finalIds = (predicate: string) =>
`SELECT id FROM scores FINAL WHERE project_id = '${PROJECT_ID}' AND data_type = 'NUMERIC' AND (${predicate}) ORDER BY id;`;
-const runLocal = (sql: string) =>
- executeClickhouseLocal(`${SCORES_DDL}\n${insertRows()}\n${sql}`);
+const runLocal = (sql: string, rows = ROWS) =>
+ executeClickhouseLocal(`${SCORES_DDL}\n${insertRows(rows)}\n${sql}`);
const sortedLines = (out: string) =>
out
@@ -365,4 +372,66 @@ describeWithLocal("scores selective-seek: parity vs FINAL", () => {
}
});
+// Projects listed in LANGFUSE_SKIP_SCORES_DEDUP_PROJECT_IDS never update scores,
+// so a plain scan over single-version rows must match FINAL.
+describe("scores skip-dedup: plain scan", () => {
+ // b, c, d each have one row per dedup key (c spans two day-buckets).
+ const SINGLE_VERSION_ROWS = ROWS.filter(([id]) =>
+ ["b", "c", "d"].includes(id),
+ );
+
+ beforeEach(() => mockShouldSkipScoresDedup.mockReturnValue(true));
+ afterEach(() => mockShouldSkipScoresDedup.mockReturnValue(false));
+
+ it("emits no dedup reconstruction or seek", async () => {
+ const count = await captureCountSql(traceIdEq("T1"));
+ const rows = await captureRowsSql(traceIdEq("T1"));
+ for (const q of [count, rows]) {
+ expect(q.query).not.toContain("argMax");
+ expect(q.query).not.toContain("latest_event_ts");
+ expect(q.query).not.toContain("SELECT DISTINCT");
+ }
+ });
+
+ const scenarios = [
+ { name: "no filter", filter: [] as FilterState, predicate: "1" },
+ {
+ name: "name IN [n1]",
+ filter: nameIn(["n1"]),
+ predicate: "name = 'n1'",
+ },
+ {
+ name: "trace_id = T1",
+ filter: traceIdEq("T1"),
+ predicate: "trace_id = 'T1'",
+ },
+ ];
+
+ for (const { name, filter, predicate } of scenarios) {
+ it.skipIf(!clickhouseLocalAvailable())(
+ `count parity: ${name}`,
+ async () => {
+ const q = await captureCountSql(filter);
+ const appCount = runLocal(
+ substituteNamedParams(q.query, q.params ?? {}),
+ SINGLE_VERSION_ROWS,
+ );
+ const refCount = runLocal(finalCount(predicate), SINGLE_VERSION_ROWS);
+ expect(appCount.trim()).toBe(refCount.trim());
+ },
+ );
+
+ it.skipIf(!clickhouseLocalAvailable())(`rows parity: ${name}`, async () => {
+ const q = await captureRowsSql(filter);
+ const appOut = runLocal(
+ substituteNamedParams(q.query, q.params ?? {}),
+ SINGLE_VERSION_ROWS,
+ );
+ const refOut = runLocal(finalIds(predicate), SINGLE_VERSION_ROWS);
+ const appIds = sortedLines(appOut).map((l) => l.split("\t")[0]);
+ expect(appIds).toEqual(sortedLines(refOut));
+ });
+ }
+});
+
afterEach(() => resetCaptures());
diff --git a/packages/shared/src/server/repositories/scores-utils.ts b/packages/shared/src/server/repositories/scores-utils.ts
index 712768d056..fdc78e5c3f 100644
--- a/packages/shared/src/server/repositories/scores-utils.ts
+++ b/packages/shared/src/server/repositories/scores-utils.ts
@@ -1,3 +1,4 @@
+import { shouldSkipScoresDedup } from "../queries/clickhouse-sql/query-options";
import { ScoreDataTypeType, ScoreDomain, ScoreSourceType } from "../../domain";
import { PreferredClickhouseService } from "../clickhouse/client";
import { queryClickhouse } from "./clickhouse";
@@ -35,7 +36,7 @@ export const _handleGetScoreById = async ({
${source ? `AND s.source = {source: String}` : ""}
${scoreScope === "traces_only" ? "AND s.session_id IS NULL AND s.dataset_run_id IS NULL" : ""}
ORDER BY s.event_ts DESC
- LIMIT 1 BY s.id, s.project_id
+ ${shouldSkipScoresDedup(projectId) ? "" : "LIMIT 1 BY s.id, s.project_id"}
LIMIT 1
`;
@@ -84,7 +85,7 @@ export const _handleGetScoresByIds = async ({
${scoreScope === "traces_only" ? "AND s.session_id IS NULL AND s.dataset_run_id IS NULL" : ""}
${dataTypes ? `AND s.data_type IN ({dataTypes: Array(String)})` : ""}
ORDER BY s.event_ts DESC
- LIMIT 1 BY s.id, s.project_id
+ ${shouldSkipScoresDedup(projectId) ? "" : "LIMIT 1 BY s.id, s.project_id"}
`;
const rows = await queryClickhouse<ScoreRecordReadType>({
diff --git a/packages/shared/src/server/repositories/scores.golden.test.ts b/packages/shared/src/server/repositories/scores.golden.test.ts
index cc4ca5afe9..e77e458a6a 100644
--- a/packages/shared/src/server/repositories/scores.golden.test.ts
+++ b/packages/shared/src/server/repositories/scores.golden.test.ts
@@ -17,6 +17,7 @@ vi.mock("./clickhouse", () => ({
// module initialization when the graph is entered from this repository file.
vi.mock("../queries/clickhouse-sql/query-options", () => ({
shouldSkipObservationsFinal: vi.fn().mockResolvedValue(false),
+ shouldSkipScoresDedup: vi.fn().mockReturnValue(false),
}));
import {
diff --git a/packages/shared/src/server/repositories/scores.test.ts b/packages/shared/src/server/repositories/scores.test.ts
index 50b0c3db38..88df04900f 100644
--- a/packages/shared/src/server/repositories/scores.test.ts
+++ b/packages/shared/src/server/repositories/scores.test.ts
@@ -17,6 +17,7 @@ vi.mock("./clickhouse", () => ({
// module initialization when the graph is entered from this repository file.
vi.mock("../queries/clickhouse-sql/query-options", () => ({
shouldSkipObservationsFinal: vi.fn().mockResolvedValue(false),
+ shouldSkipScoresDedup: vi.fn().mockReturnValue(false),
}));
import {
diff --git a/packages/shared/src/server/repositories/scores.ts b/packages/shared/src/server/repositories/scores.ts
index e51c80d880..3085721cb8 100644
--- a/packages/shared/src/server/repositories/scores.ts
+++ b/packages/shared/src/server/repositories/scores.ts
@@ -81,6 +81,7 @@ import {
eventsExperimentTraceIds,
} from "../queries/clickhouse-sql/query-fragments";
import { compileClickhouseQuery } from "../query-ast/compile";
+import { shouldSkipScoresDedup } from "../queries/clickhouse-sql/query-options";
import { getClickhouseKysely } from "../query-ast/dialect";
import {
limitBy,
@@ -127,7 +128,7 @@ export const searchExistingAnnotationScore = async (
${configId ? `OR s.config_id = {configId: String}` : ""}
)
ORDER BY s.event_ts DESC
- LIMIT 1 BY s.id, s.project_id
+ ${shouldSkipScoresDedup(projectId) ? "" : "LIMIT 1 BY s.id, s.project_id"}
LIMIT 1
`;
@@ -283,7 +284,7 @@ export const getScoresForSessions = async <
AND s.session_id IN ({sessionIds: Array(String)})
AND s.data_type IN ({dataTypes: Array(String)})
ORDER BY s.event_ts DESC
- LIMIT 1 BY s.id, s.project_id
+ ${shouldSkipScoresDedup(projectId) ? "" : "LIMIT 1 BY s.id, s.project_id"}
${limit !== undefined && offset !== undefined ? `limit {limit: Int32} offset {offset: Int32}` : ""}
`;
@@ -333,7 +334,7 @@ export const getScoresForExperiments = async <
AND s.dataset_run_id IN ({runIds: Array(String)})
AND s.data_type IN ({dataTypes: Array(String)})
ORDER BY s.event_ts DESC
- LIMIT 1 BY s.id, s.project_id
+ ${shouldSkipScoresDedup(projectId) ? "" : "LIMIT 1 BY s.id, s.project_id"}
${limit !== undefined && offset !== undefined ? `limit {limit: Int32} offset {offset: Int32}` : ""}
`;
@@ -393,7 +394,7 @@ export const getTraceScoresForDatasetRuns = async (
length(mapKeys(s.metadata)) > 0 AS has_metadata,
dri.dataset_run_id as run_id
FROM dataset_run_items_rmt dri
- JOIN scores s FINAL ON dri.trace_id = s.trace_id
+ JOIN scores s ${shouldSkipScoresDedup(projectId) ? "" : "FINAL"} ON dri.trace_id = s.trace_id
AND dri.project_id = s.project_id
WHERE dri.project_id = {projectId: String}
AND dri.dataset_run_id IN {datasetRunIds: Array(String)}
@@ -437,7 +438,10 @@ const experimentItemEventsQuery = (experimentIds: string[]) =>
.where("e.experiment_id", "in", experimentIds)
.where("e.experiment_id", "!=", literal(""));
-const scoresForExperimentItemsQuery = (experimentIds: string[]) =>
+const scoresForExperimentItemsQuery = (
+ experimentIds: string[],
+ skipDedup: boolean,
+) =>
getClickhouseKysely()
.selectFrom(experimentItemEventsQuery(experimentIds).as("e"))
.innerJoin("scores as s", (join) =>
@@ -445,7 +449,7 @@ const scoresForExperimentItemsQuery = (experimentIds: string[]) =>
.onRef("e.trace_id", "=", "s.trace_id")
.onRef("e.project_id", "=", "s.project_id"),
)
- .$call(useFinal(["scores"]))
+ .$if(!skipDedup, useFinal(["scores"]))
.select((eb) => [
"s.id as id",
"s.timestamp as timestamp",
@@ -503,7 +507,10 @@ export const getScoresForExperimentItems = async (
if (experimentIds.length === 0) return [];
const compiled = compileClickhouseQuery(
- scoresForExperimentItemsQuery(experimentIds),
+ scoresForExperimentItemsQuery(
+ experimentIds,
+ shouldSkipScoresDedup(projectId),
+ ),
projectId,
);
@@ -574,7 +581,7 @@ const getScoresForTracesInternal = async <
${timestamp ? `AND s.timestamp >= {traceTimestamp: DateTime64(3)} - ${SCORE_TO_TRACE_OBSERVATIONS_INTERVAL}` : ""}
${levelFilter}
ORDER BY s.event_ts DESC
- LIMIT 1 BY s.id, s.project_id
+ ${shouldSkipScoresDedup(projectId) ? "" : "LIMIT 1 BY s.id, s.project_id"}
${limit !== undefined && offset !== undefined ? `limit {limit: Int32} offset {offset: Int32}` : ""}
`;
@@ -703,7 +710,7 @@ export const getScoresForObservations = async <
AND s.data_type IN ({dataTypes: Array(String)})
${minTimestamp ? `AND s.timestamp >= {minTimestamp: DateTime64(3)} - ${SCORE_TO_TRACE_OBSERVATIONS_INTERVAL}` : ""}
ORDER BY s.event_ts DESC
- LIMIT 1 BY s.id, s.project_id
+ ${shouldSkipScoresDedup(projectId) ? "" : "LIMIT 1 BY s.id, s.project_id"}
${limit !== undefined && offset !== undefined ? `limit {limit: Int32} offset {offset: Int32}` : ""}
`;
@@ -844,7 +851,7 @@ export async function queryScoreRecordsForExperimentItems({
)
)
ORDER BY s.event_ts DESC
- LIMIT 1 BY s.id
+ ${shouldSkipScoresDedup(projectId) ? "" : "LIMIT 1 BY s.id"}
) s
ORDER BY s.event_ts DESC
LIMIT {scoreLimit: UInt32} BY s.trace_id
@@ -907,7 +914,7 @@ export async function queryScoreRecordsForExperiments({
AND s.observation_id IS NULL
AND s.session_id IS NULL
ORDER BY s.event_ts DESC
- LIMIT 1 BY s.id
+ ${shouldSkipScoresDedup(projectId) ? "" : "LIMIT 1 BY s.id"}
) s
ORDER BY s.dataset_run_id ASC, s.event_ts DESC
LIMIT {scoreLimit: UInt32} BY s.dataset_run_id
@@ -1435,7 +1442,7 @@ const getScoresUiGeneric = async <T>(props: {
const query = `
SELECT
${select}
- FROM scores s final
+ FROM scores s ${shouldSkipScoresDedup(projectId) ? "" : "FINAL"}
${performTracesJoin ? "LEFT JOIN traces t ON s.trace_id = t.id AND t.project_id = s.project_id" : ""}
WHERE s.project_id = {projectId: String}
AND s.data_type IN ({dataTypes: Array(String)})
@@ -1717,7 +1724,10 @@ const getScoresUiGenericFromEvents = async <T>(props: {
// 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 skipDedup = shouldSkipScoresDedup(projectId);
+ // The seek only narrows the dedup reconstruction; a plain scan has none.
+ const seekEligible =
+ !skipDedup && scoreOnlyFiltersAreSeekEligible(scoreOnlyFilters);
const seekSubquery = seekEligible
? `
SELECT DISTINCT s.project_id, toDate(s.timestamp), s.name, s.id
@@ -1769,9 +1779,27 @@ const getScoresUiGenericFromEvents = async <T>(props: {
// 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"
- ? `
+ const orderAndPage = `
+ ${withIdTiebreaker(orderByToClickhouseSql(orderBy ?? null, scoresTableUiColumnDefinitionsFromEvents), orderBy)}
+ ${limit !== undefined && offset !== undefined ? `limit {limit: Int32} offset {offset: Int32}` : ""}`;
+
+ // Projects whose scores are never updated have one row per key, so they
+ // read the table directly instead of reconstructing the latest version.
+ const plainScanQuery = () => `
+ ${tracesCTEClause}
+ SELECT
+ ${props.select === "count" ? "count(*) AS count" : rowSelect}
+ FROM (
+ SELECT s.*
+ FROM scores s
+ ${innerScanWhere}
+ ) s
+ ${eventsJoin}
+ ${outerWhereClause}
+ ${props.select === "count" ? "" : orderAndPage}
+ `;
+
+ const dedupCountQuery = () => `
${tracesCTEClause}
SELECT count(*) AS count
FROM (
@@ -1788,8 +1816,9 @@ const getScoresUiGenericFromEvents = async <T>(props: {
) s
${eventsJoin}
${outerWhereClause}
- `
- : `
+ `;
+
+ const dedupRowsQuery = () => `
${tracesCTEClause}
SELECT
${rowSelect}
@@ -1816,10 +1845,15 @@ const getScoresUiGenericFromEvents = async <T>(props: {
LIMIT 1 BY s.project_id, toDate(s.timestamp), s.name, s.id
) s
${eventsJoin}
- ${withIdTiebreaker(orderByToClickhouseSql(orderBy ?? null, scoresTableUiColumnDefinitionsFromEvents), orderBy)}
- ${limit !== undefined && offset !== undefined ? `limit {limit: Int32} offset {offset: Int32}` : ""}
+ ${orderAndPage}
`;
+ const query = (() => {
+ if (skipDedup) return plainScanQuery();
+ if (props.select === "count") return dedupCountQuery();
+ return dedupRowsQuery();
+ })();
+
const input = {
params: {
projectId,
@@ -2172,7 +2206,7 @@ export const getNumericScoreHistogram = async (
${traceFilter ? `AND t.project_id = {projectId: String}` : ""}
${chFilterRes?.query ? `AND ${chFilterRes.query}` : ""}
ORDER BY s.event_ts DESC
- LIMIT 1 BY s.id, s.project_id
+ ${shouldSkipScoresDedup(projectId) && !traceFilter ? "" : "LIMIT 1 BY s.id, s.project_id"}
${limit !== undefined ? `limit {limit: Int32}` : ""}
`;
@@ -2213,7 +2247,7 @@ export const getAggregatedScoresForPrompts = async (
s.comment,
s.timestamp,
length(mapKeys(s.metadata)) > 0 AS has_metadata
- FROM scores s FINAL LEFT JOIN observations o FINAL
+ FROM scores s ${shouldSkipScoresDedup(projectId) ? "" : "FINAL"} LEFT JOIN observations o FINAL
ON o.trace_id = s.trace_id
AND o.project_id = s.project_id
${fetchScoreRelation === "observation" ? "AND o.id = s.observation_id" : ""}
@@ -2262,6 +2296,7 @@ const aggregatedScoresForPromptsFromEventsQuery = (
promptIds: string[],
fetchScoreRelation: "observation" | "trace",
timeWindow: { fromTimestamp?: Date; toTimestamp?: Date } = {},
+ skipDedup = false,
) =>
getClickhouseKysely()
.with("prompt_events", () =>
@@ -2277,7 +2312,7 @@ const aggregatedScoresForPromptsFromEventsQuery = (
),
)
.selectFrom("scores as s")
- .$call(useFinal(["scores"]))
+ .$if(!skipDedup, useFinal(["scores"]))
.innerJoin("prompt_events as e", (join) => {
const base = join
.onRef("s.project_id", "=", "e.project_id")
@@ -2348,6 +2383,7 @@ export const buildAggregatedScoresForPromptsFromEventsQuery = (
promptIds,
fetchScoreRelation,
timeWindow,
+ shouldSkipScoresDedup(projectId),
),
projectId,
);
@@ -2556,7 +2592,7 @@ const buildScoresForBlobStorageExportQuery = (
const query = `
SELECT
${columns.join(",\n ")}
- FROM scores FINAL
+ FROM scores ${shouldSkipScoresDedup(projectId) ? "" : "FINAL"}
WHERE project_id = {projectId: String}
AND timestamp >= {minTimestamp: DateTime64(3)}
AND timestamp < {maxTimestamp: DateTime64(3)}
@@ -2745,7 +2781,7 @@ export const getScoresForAnalyticsIntegrations = async function* (
s.metadata as metadata,
t.posthog_session_id as posthog_session_id,
t.mixpanel_session_id as mixpanel_session_id
- FROM scores s FINAL
+ FROM scores s ${shouldSkipScoresDedup(projectId) ? "" : "FINAL"}
LEFT JOIN selected_traces t ON s.trace_id = t.id AND s.project_id = t.project_id
WHERE s.project_id = {projectId: String}
AND s.timestamp >= {minTimestamp: DateTime64(3)}
@@ -2863,7 +2899,7 @@ export const getScoreMetadataById = async (
AND s.id = {id: String}
${source ? `AND s.source = {source: String}` : ""}
ORDER BY s.event_ts DESC
- LIMIT 1 BY s.id, s.project_id
+ ${shouldSkipScoresDedup(projectId) ? "" : "LIMIT 1 BY s.id, s.project_id"}
LIMIT 1
`;
@@ -3072,8 +3108,7 @@ export const _handleGenerateScoresForPublicApi = async ({
${scoreScope === "traces_only" ? "AND s.session_id IS NULL AND s.dataset_run_id IS NULL" : ""}
ORDER BY
s.timestamp desc
- LIMIT
- 1 BY s.id, s.project_id
+ ${shouldSkipScoresDedup(projectId) ? "" : "LIMIT 1 BY s.id, s.project_id"}
))
)
${scoreScope === "traces_only" ? "AND s.session_id IS NULL AND s.dataset_run_id IS NULL" : ""}
@@ -3081,8 +3116,13 @@ export const _handleGenerateScoresForPublicApi = async ({
${tracesFilter.length() > 0 ? `AND ${appliedTracesFilter.query}` : ""}
ORDER BY
s.timestamp desc, s.event_ts desc
- LIMIT
- 1 BY s.id, s.project_id
+ ${
+ // The traces join is not deduplicated, so LIMIT 1 BY also collapses
+ // one score row per unmerged trace version.
+ shouldSkipScoresDedup(projectId) && !needsTraceJoin
+ ? ""
+ : "LIMIT 1 BY s.id, s.project_id"
+ }
${pagination !== undefined ? `LIMIT {limit: Int32} OFFSET {offset: Int32}` : ""}
`;
@@ -3171,8 +3211,7 @@ export const _handleGetScoresCountForPublicApi = async ({
${scoreScope === "traces_only" ? "AND s.session_id IS NULL" : ""}
ORDER BY
s.timestamp desc
- LIMIT
- 1 BY s.id, s.project_id
+ ${shouldSkipScoresDedup(projectId) ? "" : "LIMIT 1 BY s.id, s.project_id"}
))
)
${appliedScoresFilter.query ? `AND ${appliedScoresFilter.query}` : ""}
@@ -3423,6 +3462,7 @@ const buildV3ListQuery = (
withCursor: boolean,
fields: ScoreFieldGroupV3[],
filterClause: string,
+ skipDedup: boolean,
) => `
SELECT
${buildSelectColumns(fields)}
@@ -3439,7 +3479,7 @@ const buildV3ListQuery = (
}
${filterClause ? `AND ${filterClause}` : ""}
ORDER BY s.timestamp DESC, s.id DESC, s.event_ts DESC
- LIMIT 1 BY s.id, s.project_id
+ ${skipDedup ? "" : "LIMIT 1 BY s.id, s.project_id"}
LIMIT {limit: Int32}
`;
@@ -3574,6 +3614,7 @@ export async function listScoresV3ForPublicApi(
Boolean(params.cursor),
params.fields,
filterClause,
+ shouldSkipScoresDedup(params.projectId),
),
params: input.params,
tags: input.tags,
diff --git a/packages/shared/src/server/repositories/traces.test.ts b/packages/shared/src/server/repositories/traces.test.ts
index ade8e7577f..0ac9a31193 100644
--- a/packages/shared/src/server/repositories/traces.test.ts
+++ b/packages/shared/src/server/repositories/traces.test.ts
@@ -16,6 +16,7 @@ vi.mock("./clickhouse", () => ({
vi.mock("../queries/clickhouse-sql/query-options", () => ({
shouldSkipObservationsFinal: mockShouldSkipObservationsFinal,
+ shouldSkipScoresDedup: vi.fn().mockReturnValue(false),
}));
import {
diff --git a/packages/shared/src/server/repositories/traces.ts b/packages/shared/src/server/repositories/traces.ts
index 0cfe8fc645..d4193aef99 100644
--- a/packages/shared/src/server/repositories/traces.ts
+++ b/packages/shared/src/server/repositories/traces.ts
@@ -13,7 +13,10 @@ import {
} from "../queries/clickhouse-sql/factory";
import { orderByToClickhouseSql } from "../queries";
import { scoreBooleansAggregation } from "../queries/clickhouse-sql/query-fragments";
-import { shouldSkipObservationsFinal } from "../queries/clickhouse-sql/query-options";
+import {
+ shouldSkipObservationsFinal,
+ shouldSkipScoresDedup,
+} from "../queries/clickhouse-sql/query-options";
import {
planScoreFilterPushdown,
resolveScoreDataRequirement,
@@ -1704,7 +1707,7 @@ async function buildTracesBaseQuery(
data_type,
string_value,
avg(value) as avg_value
- FROM scores FINAL
+ FROM scores ${shouldSkipScoresDedup(projectId) ? "" : "FINAL"}
WHERE project_id = {projectId: String}
AND session_id IS NULL
AND dataset_run_id IS NULL
diff --git a/packages/shared/src/server/services/sessions-ui-table-service.ts b/packages/shared/src/server/services/sessions-ui-table-service.ts
index 90a5cf8757..c616e41ddc 100644
--- a/packages/shared/src/server/services/sessions-ui-table-service.ts
+++ b/packages/shared/src/server/services/sessions-ui-table-service.ts
@@ -1,3 +1,4 @@
+import { shouldSkipScoresDedup } from "../queries/clickhouse-sql/query-options";
import { ClickHouseClientConfigOptions } from "@clickhouse/client";
import { OrderByState } from "../../interfaces/orderBy";
import { sessionCols } from "../tableMappings/mapSessionTable";
@@ -285,7 +286,7 @@ const getSessionsTableGeneric = async <T>(props: FetchSessionsTableProps) => {
data_type,
string_value,
avg(value) avg_value
- FROM scores s FINAL
+ FROM scores s ${shouldSkipScoresDedup(projectId) ? "" : "FINAL"}
WHERE
project_id = {projectId: String}
${scoresFilterRes ? `AND ${scoresFilterRes.query}` : ""}
diff --git a/packages/shared/src/server/services/traces-ui-table-service.test.ts b/packages/shared/src/server/services/traces-ui-table-service.test.ts
index 2a3666133b..3af06d6c60 100644
--- a/packages/shared/src/server/services/traces-ui-table-service.test.ts
+++ b/packages/shared/src/server/services/traces-ui-table-service.test.ts
@@ -15,6 +15,7 @@ vi.mock("../repositories", () => ({
vi.mock("../queries/clickhouse-sql/query-options", () => ({
shouldSkipObservationsFinal: mockShouldSkipObservationsFinal,
+ shouldSkipScoresDedup: vi.fn().mockReturnValue(false),
}));
import {
diff --git a/packages/shared/src/server/services/traces-ui-table-service.ts b/packages/shared/src/server/services/traces-ui-table-service.ts
index e9a975e78f..d55e68e008 100644
--- a/packages/shared/src/server/services/traces-ui-table-service.ts
+++ b/packages/shared/src/server/services/traces-ui-table-service.ts
@@ -28,7 +28,10 @@ import {
import { TracingSearchType } from "../../interfaces/search";
import { ObservationLevelType, TraceDomain } from "../../domain";
import { ClickHouseClientConfigOptions } from "@clickhouse/client";
-import { shouldSkipObservationsFinal } from "../queries/clickhouse-sql/query-options";
+import {
+ shouldSkipObservationsFinal,
+ shouldSkipScoresDedup,
+} from "../queries/clickhouse-sql/query-options";
import { convertDateToClickhouseDateTime } from "../clickhouse/client";
import type { TraceDeleteBatchActionCursor } from "../../features/batchAction/types";
import {
@@ -354,7 +357,7 @@ async function getTracesTableGeneric(props: FetchTracesTableProps) {
data_type,
string_value,
avg(value) as avg_value
- FROM scores s FINAL
+ FROM scores s ${shouldSkipScoresDedup(projectId) ? "" : "FINAL"}
WHERE
project_id = {projectId: String}
${timeStampFilter ? `AND s.timestamp >= {traceTimestamp: DateTime64(3)} - ${SCORE_TO_TRACE_OBSERVATIONS_INTERVAL}` : ""}
diff --git a/web/src/features/score-analytics/server/scoreAnalyticsRouter.ts b/web/src/features/score-analytics/server/scoreAnalyticsRouter.ts
index 60a632fb15..beedaf5844 100644
--- a/web/src/features/score-analytics/server/scoreAnalyticsRouter.ts
+++ b/web/src/features/score-analytics/server/scoreAnalyticsRouter.ts
@@ -8,6 +8,7 @@ import {
getScoresGroupedByNameSourceType,
queryClickhouse,
convertDateToClickhouseDateTime,
+ shouldSkipScoresDedup,
} from "@langfuse/shared/src/server";
import { buildEstimateQuery } from "./buildEstimateQuery";
import { buildScoreComparisonQuery } from "./buildScoreComparisonQuery";
@@ -267,6 +268,7 @@ export const createScoreAnalyticsRouter = ({
// Adaptive FINAL logic: Only use FINAL for small datasets to avoid expensive merge
// For large datasets, skip FINAL to improve performance (scores can be updated, so accuracy matters for recent data)
const shouldUseFinal =
+ !shouldSkipScoresDedup(projectId) &&
estimates.score1Count < adaptiveFinalThreshold &&
estimates.score2Count < adaptiveFinalThreshold;
diff --git a/web/src/features/scores/actions/annotationFormActions.ts b/web/src/features/scores/actions/annotationFormActions.ts
index 738cf3d692..58743c3202 100644
--- a/web/src/features/scores/actions/annotationFormActions.ts
+++ b/web/src/features/scores/actions/annotationFormActions.ts
@@ -44,6 +44,8 @@ type Dependencies = {
createScore: (data: CreateAnnotationScoreData) => Promise<unknown>;
updateScore: (data: UpdateAnnotationScoreData) => Promise<unknown>;
deleteScore: (data: { id: string; projectId: string }) => Promise<unknown>;
+ /** Saved scores are immutable: value and comment changes to them are ignored. */
+ editsDisabled?: boolean;
};
const SAVED_STATUS_VISIBLE_MS = 3_000;
@@ -59,6 +61,7 @@ export function createAnnotationFormActions({
createScore,
updateScore,
deleteScore,
+ editsDisabled = false,
}: Dependencies) {
const fields = (): AnnotationScoreFormData[] =>
form
@@ -234,7 +237,7 @@ export function createAnnotationFormActions({
stringValue: string | null,
) => {
const field = find(key);
- if (!field) return;
+ if (!field || (editsDisabled && field.id)) return;
const config = target.configControl.configs.find(
(config) => config.id === field.configId,
);
@@ -529,7 +532,7 @@ export function createAnnotationFormActions({
comment: string | null,
) {
const field = find(key);
- if (!field?.id) return;
+ if (!field?.id || editsDisabled) return;
const next = { ...field, comment };
const tracked = beginSave(
comment ? "update_comment" : "delete_comment",
diff --git a/web/src/features/scores/components/AnnotationForm.tsx b/web/src/features/scores/components/AnnotationForm.tsx
index 35e8c6dcd6..6ff91b94de 100644
--- a/web/src/features/scores/components/AnnotationForm.tsx
+++ b/web/src/features/scores/components/AnnotationForm.tsx
@@ -26,6 +26,7 @@ import { useMergedAnnotationScores } from "@/src/features/scores/lib/useMergedAn
import { prepareAnnotationFormData } from "@/src/features/scores/lib/prepareAnnotationFormData";
import { transformToAnnotationScores } from "@/src/features/scores/lib/transformScores";
import { useScoreMutations } from "@/src/features/scores/hooks/useScoreMutations";
+import { useScoreEditsDisabled } from "@/src/features/scores/hooks/useScoreEditsDisabled";
import { useAnnotationScoreConfigs } from "@/src/features/scores/hooks/useScoreConfigs";
import { useAnnotationKeyboard } from "@/src/features/scores/hooks/useAnnotationKeyboard";
import { createAnnotationFormActions } from "@/src/features/scores/actions/annotationFormActions";
@@ -157,6 +158,7 @@ export function AnnotationFormContent({
});
const { createMutation, updateMutation, deleteMutation } =
useScoreMutations();
+ const scoreEditsDisabled = useScoreEditsDisabled(scoreMetadata.projectId);
const [actions] = useState(() =>
createAnnotationFormActions({
form,
@@ -167,6 +169,7 @@ export function AnnotationFormContent({
createScore: createMutation.mutateAsync,
updateScore: updateMutation.mutateAsync,
deleteScore: deleteMutation.mutateAsync,
+ editsDisabled: scoreEditsDisabled,
}),
);
const formRootRef = useRef<HTMLDivElement | null>(null);
@@ -407,6 +410,7 @@ export function AnnotationFormContent({
showTarget={showSelectedTargets}
formRootRef={formRootRef}
commentSaving={updateMutation.isPending}
+ editsDisabled={scoreEditsDisabled}
targetOptions={
target.configControl.allowManualSelection
? targets
diff --git a/web/src/features/scores/components/AnnotationScoreRow.tsx b/web/src/features/scores/components/AnnotationScoreRow.tsx
index 2715f88122..8377cdda26 100644
--- a/web/src/features/scores/components/AnnotationScoreRow.tsx
+++ b/web/src/features/scores/components/AnnotationScoreRow.tsx
@@ -148,6 +148,7 @@ export function AnnotationScoreRow({
showTarget,
formRootRef,
commentSaving,
+ editsDisabled = false,
targetOptions,
isActive = true,
onRemove,
@@ -161,6 +162,8 @@ export function AnnotationScoreRow({
showTarget: boolean;
formRootRef: React.RefObject<HTMLDivElement | null>;
commentSaving: boolean;
+ /** Saved scores in this project are immutable; new scores stay editable. */
+ editsDisabled?: boolean;
targetOptions: { target: PreparedAnnotationTarget; hasField: boolean }[];
isActive?: boolean;
onRemove: () => void;
@@ -186,6 +189,7 @@ export function AnnotationScoreRow({
null,
);
const focusFieldKey = useRef(fieldKey);
+ const locked = editsDisabled && !isScoreUnsaved(score.id);
const hasScoreValue = Boolean(
score.id || isPresent(score.value) || score.stringValue || score.comment,
);
@@ -290,7 +294,7 @@ export function AnnotationScoreRow({
savedComment={score.comment ?? null}
localValue={commentDraft ?? score.comment ?? ""}
onValueChange={setCommentDraft}
- disabled={config.isArchived}
+ disabled={config.isArchived || locked}
loading={commentSaving}
onSave={(newComment) => {
const trimmed = newComment?.trim();
@@ -341,7 +345,7 @@ export function AnnotationScoreRow({
value={field.value ?? ""}
maxLength={TEXT_SCORE_MAX_LENGTH}
className="text-xs"
- disabled={config.isArchived}
+ disabled={config.isArchived || locked}
placeholder="Enter free form text..."
onBlur={(event) => {
field.onBlur();
@@ -392,7 +396,7 @@ export function AnnotationScoreRow({
max={config.maxValue ?? undefined}
step="any"
className="aria-invalid:border-destructive text-xs"
- disabled={config.isArchived}
+ disabled={config.isArchived || locked}
onBlur={(event) => {
field.onBlur();
if (!isMovingToScoreActions(event))
@@ -424,7 +428,7 @@ export function AnnotationScoreRow({
categories={categories}
name={field.name}
value={field.value ?? ""}
- disabled={config.isArchived}
+ disabled={config.isArchived || locked}
analyticsData={{
...target.analyticsData,
targetType: getAnnotationTargetType(
@@ -447,6 +451,11 @@ export function AnnotationScoreRow({
/>
) : null}
</div>
+ {locked ? (
+ <p className="text-muted-foreground mt-1 text-xs">
+ Saved scores cannot be edited in this project.
+ </p>
+ ) : null}
{hasScoreValue || invalid || canRemove || targetOptions.length > 0 ? (
<DropdownMenuController
align="end"
diff --git a/web/src/features/scores/components/DualAnnotationContent.clienttest.tsx b/web/src/features/scores/components/DualAnnotationContent.clienttest.tsx
index 87ff953767..36679a9730 100644
--- a/web/src/features/scores/components/DualAnnotationContent.clienttest.tsx
+++ b/web/src/features/scores/components/DualAnnotationContent.clienttest.tsx
@@ -35,6 +35,7 @@ const mocks = vi.hoisted(() => ({
headerRender: vi.fn(),
hasConfigAccess: false,
configsLoading: false,
+ scoreEditsDisabled: false,
}));
const defaultConfig = {
id: "quality",
@@ -67,6 +68,9 @@ vi.mock("@/src/features/rbac", () => ({
useHasProjectAccess: () => mocks.hasConfigAccess,
}));
vi.mock("@/src/features/notifications", () => ({ showErrorToast: vi.fn() }));
+vi.mock("@/src/features/scores/hooks/useScoreEditsDisabled", () => ({
+ useScoreEditsDisabled: () => mocks.scoreEditsDisabled,
+}));
vi.mock("@/src/features/posthog-analytics", () => ({
usePostHogClientCapture: () => mocks.capture,
}));
@@ -192,6 +196,7 @@ describe("unified annotation targets", () => {
vi.clearAllMocks();
mocks.hasConfigAccess = false;
mocks.configsLoading = false;
+ mocks.scoreEditsDisabled = false;
Element.prototype.scrollIntoView = vi.fn();
localStorage.clear();
localStorage.setItem(
@@ -414,6 +419,26 @@ describe("unified annotation targets", () => {
},
);
+ it("locks saved scores when the project disables score edits", async () => {
+ mocks.scoreEditsDisabled = true;
+ renderContent(
+ cloneElement(content, {
+ observationScores: [{ ...serverQualityScore(), metadata: "{}" }],
+ }),
+ );
+ const quality = screen.getByRole("group", { name: "Quality" });
+ expect(
+ within(quality).getByText(
+ "Saved scores cannot be edited in this project.",
+ ),
+ ).toBeInTheDocument();
+ fireEvent.click(within(quality).getByText("True"));
+ act(() => quality.focus());
+ await act(async () => fireEvent.keyDown(quality, { key: "2" }));
+ expect(mocks.update).not.toHaveBeenCalled();
+ expect(mocks.create).not.toHaveBeenCalled();
+ });
+
it("refreshes clean scores on reopening while retaining text and score-comment drafts", async () => {
configs.push({
...defaultConfig,
diff --git a/web/src/features/scores/hooks/useScoreEditsDisabled.ts b/web/src/features/scores/hooks/useScoreEditsDisabled.ts
new file mode 100644
index 0000000000..a92b7bb3d5
--- /dev/null
+++ b/web/src/features/scores/hooks/useScoreEditsDisabled.ts
@@ -0,0 +1,15 @@
+import { useSession } from "next-auth/react";
+
+/**
+ * Whether saved scores in this project are immutable in the UI. Resolved on
+ * the server from the deployment allowlist and carried on the session; the
+ * score mutations enforce the same rule.
+ */
+export function useScoreEditsDisabled(projectId: string): boolean {
+ const session = useSession();
+ return (
+ session.data?.user?.organizations
+ .flatMap((org) => org.projects)
+ .find((project) => project.id === projectId)?.scoreEditsDisabled === true
+ );
+}
diff --git a/web/src/features/traces/components/IOPreview/components/CorrectedOutputField.clienttest.tsx b/web/src/features/traces/components/IOPreview/components/CorrectedOutputField.clienttest.tsx
index a718ad5db0..93945ef4c8 100644
--- a/web/src/features/traces/components/IOPreview/components/CorrectedOutputField.clienttest.tsx
+++ b/web/src/features/traces/components/IOPreview/components/CorrectedOutputField.clienttest.tsx
@@ -20,7 +20,10 @@ const editorHook = vi.hoisted(() => ({
spy: vi.fn(),
handleEdit: vi.fn(),
}));
-const access = vi.hoisted(() => ({ hasAccess: true }));
+const access = vi.hoisted(() => ({
+ hasAccess: true,
+ scoreEditsDisabled: false,
+}));
vi.mock("../hooks/useCorrectionEditor", () => ({
useCorrectionEditor: (params: { correctionValue: string }) => {
@@ -40,6 +43,10 @@ vi.mock("@/src/features/rbac", () => ({
useHasProjectAccess: () => access.hasAccess,
}));
+vi.mock("@/src/features/scores/hooks/useScoreEditsDisabled", () => ({
+ useScoreEditsDisabled: () => access.scoreEditsDisabled,
+}));
+
vi.mock("@/src/features/posthog-analytics", () => ({
usePostHogClientCapture: () => vi.fn(),
}));
@@ -79,6 +86,7 @@ const baseProps = {
describe("CorrectedOutputField visibility", () => {
beforeEach(() => {
access.hasAccess = true;
+ access.scoreEditsDisabled = false;
editorHook.spy.mockClear();
editorHook.handleEdit.mockClear();
});
@@ -114,6 +122,18 @@ describe("CorrectedOutputField visibility", () => {
).toBeDisabled();
});
+ it("does not open the editor when the project disables score edits", () => {
+ access.scoreEditsDisabled = true;
+ render(<CorrectedOutputField {...baseProps} existingCorrection={null} />);
+
+ fireEvent.click(screen.getByRole("button", { name: "Correct output" }));
+
+ expect(editorHook.handleEdit).not.toHaveBeenCalled();
+ expect(
+ screen.getByRole("button", { name: "Click to add corrected output" }),
+ ).toBeDisabled();
+ });
+
it("opens the inline link straight into edit mode with access", () => {
render(<CorrectedOutputField {...baseProps} existingCorrection={null} />);
diff --git a/web/src/features/traces/components/IOPreview/components/CorrectedOutputField.tsx b/web/src/features/traces/components/IOPreview/components/CorrectedOutputField.tsx
index f8e88b637b..40c00a05e4 100644
--- a/web/src/features/traces/components/IOPreview/components/CorrectedOutputField.tsx
+++ b/web/src/features/traces/components/IOPreview/components/CorrectedOutputField.tsx
@@ -14,6 +14,7 @@ import { useCallback, useMemo, useRef, useState } from "react";
import { type ReactCodeMirrorRef } from "@uiw/react-codemirror";
import { CodeMirrorEditor } from "@/src/components/editor/CodeMirrorEditor";
import { useHasProjectAccess } from "@/src/features/rbac";
+import { useScoreEditsDisabled } from "@/src/features/scores/hooks/useScoreEditsDisabled";
import { usePostHogClientCapture } from "@/src/features/posthog-analytics";
import useLocalStorage from "@/src/components/useLocalStorage";
import { CorrectedOutputDiffDialog } from "./CorrectedOutputDiffDialog";
@@ -52,11 +53,11 @@ export function useCorrectOutputAction({
onOpen: () => void;
}): IOSectionAction {
const capture = usePostHogClientCapture();
- const hasAccess = useHasProjectAccess({ projectId, scope: "scores:save" });
+ const canEdit = useCanEditCorrection(projectId);
return {
icon: Pencil,
label: "Correct output",
- disabled: !hasAccess,
+ disabled: !canEdit,
onClick: () => {
capture("trace_detail:io_section_collapse_toggle", {
section: "corrected_output",
@@ -81,6 +82,7 @@ export function CorrectedOutputField({
onClosed,
}: CorrectedOutputFieldProps) {
const hasAccess = useHasProjectAccess({ projectId, scope: "scores:save" });
+ const canEdit = useCanEditCorrection(projectId);
const capture = usePostHogClientCapture();
// JSON validation toggle (persisted in localStorage)
@@ -133,7 +135,7 @@ export function CorrectedOutputField({
onSave: handleSave,
setSaveStatus,
strictJsonMode,
- initialEditing: startEditing && hasAccess,
+ initialEditing: startEditing && canEdit,
});
// When not editing, use correctionValue (source of truth from cache/server)
@@ -217,7 +219,7 @@ export function CorrectedOutputField({
// One click: open the section straight into the editor (readers
// without scores:save get the disabled placeholder).
setIsExpanded(true);
- if (hasAccess) handleEdit();
+ if (canEdit) handleEdit();
}}
className="text-muted-foreground hover:text-foreground inline-flex items-center gap-1 text-xs hover:underline"
>
@@ -249,7 +251,7 @@ export function CorrectedOutputField({
icon: Pencil,
label: "Edit corrected output",
onClick: handleEdit,
- disabled: !hasAccess,
+ disabled: !canEdit,
},
]
: []),
@@ -279,7 +281,7 @@ export function CorrectedOutputField({
<CorrectionBody
hasContent={hasContent}
isEditing={isEditing}
- hasAccess={hasAccess}
+ hasAccess={canEdit}
displayValue={displayValue}
strictJsonMode={strictJsonMode}
editorRef={editorRef}
@@ -416,3 +418,11 @@ function CorrectionBody({
/>
);
}
+
+/** Corrections autosave by rewriting the same score id, which projects that
+ read scores without dedup must not do, so editing is off for them. */
+function useCanEditCorrection(projectId: string) {
+ const hasAccess = useHasProjectAccess({ projectId, scope: "scores:save" });
+ const scoreEditsDisabled = useScoreEditsDisabled(projectId);
+ return hasAccess && !scoreEditsDisabled;
+}
diff --git a/web/src/server/api/routers/scores.ts b/web/src/server/api/routers/scores.ts
index 4c6b3d913c..bbf9f71b74 100644
--- a/web/src/server/api/routers/scores.ts
+++ b/web/src/server/api/routers/scores.ts
@@ -64,6 +64,7 @@ import {
deleteScores,
getTracesIdentifierForSession,
validateConfigAgainstBody,
+ shouldSkipScoresDedup,
} from "@langfuse/shared/src/server";
import { v4 } from "uuid";
import { throwIfNoEntitlement } from "@/src/features/entitlements/server";
@@ -635,6 +636,7 @@ export const scoresRouter = createTRPCRouter({
input.configId,
input.dataType,
);
+ if (clickhouseScore) throwIfScoreEditsDisabled(input.projectId);
const timestamp = input.timestamp ?? new Date();
@@ -713,6 +715,8 @@ export const scoresRouter = createTRPCRouter({
scope: "scores:save",
});
+ throwIfScoreEditsDisabled(input.projectId);
+
let updatedScore: ScoreDomain | null | undefined = null;
// Fetch the current score from Clickhouse
@@ -1050,6 +1054,7 @@ export const scoresRouter = createTRPCRouter({
undefined,
ScoreDataTypeEnum.CORRECTION,
);
+ if (clickhouseScore) throwIfScoreEditsDisabled(input.projectId);
const timestamp = input.timestamp;
@@ -1190,3 +1195,14 @@ export const scoresRouter = createTRPCRouter({
return (await getScoreMetadataById(input.projectId, input.id)) ?? null;
}),
});
+
+// Projects that read scores without dedup must not rewrite an existing score
+// id: every rewrite is a new row and would surface as a duplicate.
+function throwIfScoreEditsDisabled(projectId: string) {
+ if (shouldSkipScoresDedup(projectId)) {
+ throw new TRPCError({
+ code: "PRECONDITION_FAILED",
+ message: "Existing scores cannot be edited in this project.",
+ });
+ }
+}
diff --git a/web/src/server/auth.ts b/web/src/server/auth.ts
index 108bc51af0..7b96234a17 100644
--- a/web/src/server/auth.ts
+++ b/web/src/server/auth.ts
@@ -80,6 +80,7 @@ import {
logger,
resolveProjectRole,
isLangfuseAITracingConfigured,
+ shouldSkipScoresDedup,
} from "@langfuse/shared/src/server";
import {
getOrganizationPlanServerSide,
@@ -991,6 +992,9 @@ export async function getAuthOptions(
topicsEnabled: isTopicsProjectEnabled(
project.id,
),
+ scoreEditsDisabled: shouldSkipScoresDedup(
+ project.id,
+ ),
deletedAt: project.deletedAt,
metadata:
(project.metadata as Record<
diff --git a/web/types/next-auth.d.ts b/web/types/next-auth.d.ts
index a441f2fde3..1dd4c06161 100644
--- a/web/types/next-auth.d.ts
+++ b/web/types/next-auth.d.ts
@@ -51,6 +51,7 @@ declare module "next-auth" {
retentionDays: PrismaProject["retentionDays"];
hasTraces: PrismaProject["hasTraces"];
topicsEnabled?: boolean; // deployment allowlist, resolved server-side; absent = off
+ scoreEditsDisabled?: boolean; // scores are read without dedup, so existing scores stay immutable; absent = off
metadata: Record<string, unknown>;
role: Role; // include only projects where user has a role
createdAt: string; // iso datetime string — JWT does not support Date objects
diff --git a/worker/src/features/database-read-stream/trace-stream.ts b/worker/src/features/database-read-stream/trace-stream.ts
index 83a04c13bd..ae3b4c410b 100644
--- a/worker/src/features/database-read-stream/trace-stream.ts
+++ b/worker/src/features/database-read-stream/trace-stream.ts
@@ -16,6 +16,7 @@ import {
parseClickhouseUTCDateTimeFormat,
scoreBooleansAggregation,
StringFilter,
+ shouldSkipScoresDedup,
} from "@langfuse/shared/src/server";
import { Readable } from "stream";
import { env } from "../../env";
@@ -149,7 +150,7 @@ export const getTraceStream = async (props: {
data_type,
string_value,
avg(value) as avg_value
- FROM scores FINAL
+ FROM scores ${shouldSkipScoresDedup(projectId) ? "" : "FINAL"}
WHERE ${appliedScoresFilter.query}
GROUP BY
project_id,