Skip to content

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

feat(experiments): filter datasets by name instead of id (#16762)

Nikita Kabardincc6af4a037c9
diff --git a/web/src/features/experiments/components/table/ExperimentsTable.tsx b/web/src/features/experiments/components/table/ExperimentsTable.tsx
index 461b85fd2a..51379fff23 100644
--- a/web/src/features/experiments/components/table/ExperimentsTable.tsx
+++ b/web/src/features/experiments/components/table/ExperimentsTable.tsx
@@ -11,6 +11,7 @@ import { useQueryFilterState } from "@/src/features/filters/hooks/useFilterState
import { usePaginationState } from "@/src/hooks/usePaginationState";
import { useSidebarFilterState } from "@/src/features/filters/hooks/useSidebarFilterState";
import { EXPERIMENTS_FIELD_REGISTRY } from "@/src/features/experiments/constants/experimentsSearchRegistry";
+import { withDatasetNamesResolved } from "@/src/features/experiments/fns/datasetNameFilter";
import { toObservedOptions } from "@/src/features/search-bar/lib/observed-options";
import { DEFAULT_SEARCH_TYPE } from "@/src/features/search-bar/lib/commit";
import { useEventsSearchBar } from "@/src/features/search-bar/hooks/useEventsSearchBar";
@@ -279,15 +280,6 @@ export default function ExperimentsTable({
showControlsInPageHeader = false,
}: ExperimentsTableProps) {
const router = useRouter();
- const filterConfig = useMemo(
- () =>
- getExperimentsFilterConfig(
- fixedFilter
- .map((filter) => filter.column)
- .filter(isExperimentsOmittableFilterColumn),
- ),
- [fixedFilter],
- );
const { setDetailPageList } = useDetailPageLists();
// Selection lives in a per-mount vanilla zustand store (not useState) so a
@@ -342,11 +334,29 @@ export default function ExperimentsTable({
const oldFilterState = inputFilterState.concat(dateRangeFilter, fixedFilter);
// Fetch filter options for datasets and scores
- const { filterOptions, isFilterOptionsPending } = useExperimentFilterOptions({
+ const {
+ filterOptions,
+ datasetIdByName,
+ datasetNameById,
+ isFilterOptionsPending,
+ } = useExperimentFilterOptions({
projectId,
oldFilterState,
});
+ // Built after the dataset map, which its filter-state migration needs to
+ // translate a legacy dataset id into the name the facet is keyed by.
+ const filterConfig = useMemo(
+ () =>
+ getExperimentsFilterConfig(
+ fixedFilter
+ .map((filter) => filter.column)
+ .filter(isExperimentsOmittableFilterColumn),
+ datasetNameById,
+ ),
+ [fixedFilter, datasetNameById],
+ );
+
const queryFilter = useSidebarFilterState(filterConfig, filterOptions, {
loading: isFilterOptionsPending,
stateLocation: "urlAndSessionStorage",
@@ -409,7 +419,12 @@ export default function ExperimentsTable({
fixedFilter,
);
- const filterState = combinedFilterState;
+ // The one boundary where a dataset NAME becomes its id — see
+ // fns/datasetNameFilter.
+ const filterState = useMemo(
+ () => withDatasetNamesResolved(combinedFilterState, datasetIdByName),
+ [combinedFilterState, datasetIdByName],
+ );
// Use the custom hook for experiments data fetching
const { experiments, totalCount, dataUpdatedAt } = useExperimentsTableData({
@@ -557,13 +572,13 @@ export default function ExperimentsTable({
{
accessorKey: "datasetId",
id: "datasetId",
- header: getExperimentsColumnName("experimentDatasetId"),
+ header: getExperimentsColumnName("experimentDatasetName"),
size: 150,
cell: ({ row }) => {
const datasetId: string | undefined = row.getValue("datasetId");
- const datasetName = filterOptions.experimentDatasetId?.find(
- (d) => d.value === datasetId,
- )?.displayValue;
+ const datasetName = datasetId
+ ? datasetNameById.get(datasetId)
+ : undefined;
if (!datasetId || !datasetName) {
return undefined;
diff --git a/web/src/features/experiments/components/table/filter-config.ts b/web/src/features/experiments/components/table/filter-config.ts
index bb005a05b1..4521c4c720 100644
--- a/web/src/features/experiments/components/table/filter-config.ts
+++ b/web/src/features/experiments/components/table/filter-config.ts
@@ -1,6 +1,7 @@
import {
omitFilterFacets,
type FilterConfig,
+ type FilterStateMigration,
} from "@/src/features/filters/lib/filter-config";
import type { ColumnDefinition } from "@langfuse/shared";
@@ -42,8 +43,22 @@ export const experimentsTableCols: ColumnDefinition[] = [
internal: "prompts",
nullable: true,
},
+ // Dataset names are unique per project, so the NAME is the canonical filter
+ // value: it survives in a URL or saved view as something readable, and the
+ // sidebar picker and the search bar can both show the same string. It is
+ // translated to `experimentDatasetId` on the way to the query (the dataset
+ // name is not a ClickHouse column) — see fns/datasetNameFilter.
{
name: "Dataset",
+ id: "experimentDatasetName",
+ type: "stringOptions",
+ internal: "experiment_dataset_id",
+ options: [],
+ },
+ // Still filterable so URLs and saved views written before the switch keep
+ // resolving; no longer offered as a facet.
+ {
+ name: "Dataset ID",
id: "experimentDatasetId",
type: "stringOptions",
internal: "experiment_dataset_id",
@@ -136,12 +151,72 @@ export const getExperimentsColumnName = (id: string): string => {
return column.name;
};
+/**
+ * Folds a legacy `experimentDatasetId` filter onto the canonical column.
+ *
+ * Both ids compile to the same ClickHouse column, and the name resolver passes
+ * a value it cannot translate straight through — so an id keeps matching. What
+ * matters is that only ONE dataset column can be present: the sidebar's facet
+ * actions replace entries by exact column name, so a leftover
+ * `experimentDatasetId` from an old link survived every interaction with the
+ * Dataset facet and was ANDed with the user's new choice, silently showing zero
+ * rows with one dataset apparently selected.
+ */
+/**
+ * Folds a legacy `experimentDatasetId` filter onto the canonical column,
+ * translating its value from the id to the dataset's NAME.
+ *
+ * Only ONE dataset column may be present: the sidebar's facet actions replace
+ * entries by exact column name, so a leftover `experimentDatasetId` from an old
+ * link survived every interaction with the Dataset facet and was ANDed with the
+ * user's new choice - one dataset apparently selected, zero rows.
+ *
+ * The value has to travel with the column. The facet's options and its display
+ * labels are keyed by name, so a folded id would render as an opaque id with no
+ * checkbox matching it. Until the id -> name map arrives the legacy filter is
+ * left exactly as it is: it names a real column, so it keeps querying correctly
+ * in the meantime, and an id with no name (a deleted dataset) stays put rather
+ * than becoming a name that resolves to nothing.
+ */
+const foldLegacyDatasetColumn =
+ (datasetNameById: ReadonlyMap<string, string>): FilterStateMigration =>
+ (filters) => {
+ if (
+ datasetNameById.size === 0 ||
+ !filters.some((filter) => filter.column === "experimentDatasetId")
+ ) {
+ return filters;
+ }
+
+ let folded = false;
+ return filters.flatMap((filter) => {
+ if (filter.column !== "experimentDatasetId") return [filter];
+ if (filter.type !== "stringOptions") return [filter];
+
+ const names = filter.value.map((id) => datasetNameById.get(id));
+ // Partial knowledge would drop a constraint, so fold all or nothing.
+ if (names.some((name) => name === undefined)) return [filter];
+ // A second legacy entry would fold onto the same column and re-create
+ // the AND this exists to remove.
+ if (folded) return [];
+ folded = true;
+
+ return [
+ {
+ ...filter,
+ column: "experimentDatasetName",
+ value: names as string[],
+ },
+ ];
+ });
+ };
+
export const experimentsFilterConfig: FilterConfig = {
tableName: "experiments",
columnDefinitions: experimentsTableCols,
- defaultExpanded: ["experimentDatasetId"],
+ defaultExpanded: ["experimentDatasetName"],
facets: [
{
@@ -151,8 +226,8 @@ export const experimentsFilterConfig: FilterConfig = {
},
{
type: "categorical" as const,
- column: "experimentDatasetId",
- label: getExperimentsColumnName("experimentDatasetId"),
+ column: "experimentDatasetName",
+ label: getExperimentsColumnName("experimentDatasetName"),
},
{
type: "stringKeyValue" as const,
@@ -194,7 +269,9 @@ export const experimentsFilterConfig: FilterConfig = {
],
};
-export type ExperimentsOmittableFilterColumn = "experimentDatasetId";
+export type ExperimentsOmittableFilterColumn =
+ | "experimentDatasetId"
+ | "experimentDatasetName";
export function isExperimentsOmittableFilterColumn(
column: string,
@@ -204,6 +281,19 @@ export function isExperimentsOmittableFilterColumn(
export function getExperimentsFilterConfig(
omittedFilter: ExperimentsOmittableFilterColumn[] = [],
+ datasetNameById: ReadonlyMap<string, string> = new Map(),
): FilterConfig {
- return omitFilterFacets(experimentsFilterConfig, omittedFilter);
+ // A dataset-scoped page pins `experimentDatasetId`, but the facet it should
+ // hide is the name one that replaced it.
+ const config = omitFilterFacets(
+ experimentsFilterConfig,
+ omittedFilter.map((column) =>
+ column === "experimentDatasetId" ? "experimentDatasetName" : column,
+ ) as ExperimentsOmittableFilterColumn[],
+ );
+
+ return {
+ ...config,
+ migrateFilterState: foldLegacyDatasetColumn(datasetNameById),
+ };
}
diff --git a/web/src/features/experiments/constants/experimentsSearchRegistry.ts b/web/src/features/experiments/constants/experimentsSearchRegistry.ts
index a6c556873c..18438e167b 100644
--- a/web/src/features/experiments/constants/experimentsSearchRegistry.ts
+++ b/web/src/features/experiments/constants/experimentsSearchRegistry.ts
@@ -21,6 +21,10 @@ function facetColumns(config: FilterConfig) {
const AI_CONTEXT_FIELDS = [
{ observedOptionsKey: "name", promptLabel: "name" },
+ {
+ observedOptionsKey: "experimentDatasetName",
+ promptLabel: "experimentDatasetName (dataset)",
+ },
] as const;
/**
@@ -38,14 +42,6 @@ const AI_CONTEXT_FIELDS = [
* surface as a bogus keyless field.
*/
const EXCLUDED_COLUMN_IDS: ReadonlySet<string> = new Set([
- // `experimentDatasetId` holds the dataset ID while the sidebar's picker shows
- // the dataset NAME (`displayValue`). A text query bar can only show what the
- // query text contains, so offering it here would put `dataset:cmtc1z…` in a
- // pill next to a sidebar that says `legal-answer-quality`. Making the bar
- // speak names would require the derived committed text to depend on
- // async-loaded options, which breaks the one invariant every bar surface
- // relies on. Dataset filtering stays in the sidebar.
- "experimentDatasetId",
"obs_scores_avg",
"obs_score_categories",
"obs_score_booleans",
@@ -65,6 +61,11 @@ const EXPERIMENT_FIELD_OVERLAY = {
label: "Experiment name",
description: "Experiment name",
},
+ experimentDatasetName: {
+ aliases: ["dataset", "datasetname", "dataset_name"],
+ label: "Dataset",
+ description: "Dataset the experiment ran against",
+ },
};
export const EXPERIMENTS_FIELD_REGISTRY: FieldRegistry =
@@ -81,7 +82,11 @@ export const EXPERIMENTS_FIELD_REGISTRY: FieldRegistry =
recentSearches: true,
// `dataset:` takes the dataset ID, not its name — the observed-value picker
// offers the ids, so the examples must not imply a name works.
- searchExamples: ["name:sonnet", "-name:baseline", 'metadata."model":opus'],
+ searchExamples: [
+ "dataset:legal-answer-quality",
+ "name:sonnet",
+ 'metadata."model":opus',
+ ],
aiContextFields: AI_CONTEXT_FIELDS,
fields: EXPERIMENT_FIELD_OVERLAY,
});
diff --git a/web/src/features/experiments/fns/datasetNameFilter.clienttest.ts b/web/src/features/experiments/fns/datasetNameFilter.clienttest.ts
new file mode 100644
index 0000000000..0d164bf534
--- /dev/null
+++ b/web/src/features/experiments/fns/datasetNameFilter.clienttest.ts
@@ -0,0 +1,146 @@
+import { getExperimentsFilterConfig } from "@/src/features/experiments/components/table/filter-config";
+import { describe, expect, it } from "vitest";
+import type { FilterState } from "@langfuse/shared";
+
+import { withDatasetNamesResolved } from "./datasetNameFilter";
+
+const idByName = new Map([
+ ["legal-answer-quality", "ds-legal"],
+ ["groundedness-judge-calibration", "ds-ground"],
+]);
+
+const nameFilter = (values: string[]): FilterState => [
+ {
+ column: "experimentDatasetName",
+ type: "stringOptions",
+ operator: "any of",
+ value: values,
+ },
+];
+
+describe("withDatasetNamesResolved", () => {
+ it("swaps names for ids and keeps the operator", () => {
+ expect(
+ withDatasetNamesResolved(nameFilter(["legal-answer-quality"]), idByName),
+ ).toEqual([
+ {
+ column: "experimentDatasetId",
+ type: "stringOptions",
+ operator: "any of",
+ value: ["ds-legal"],
+ },
+ ]);
+ });
+
+ it("leaves other filters and pre-existing id filters untouched", () => {
+ const others: FilterState = [
+ {
+ column: "name",
+ type: "string",
+ operator: "contains",
+ value: "sonnet",
+ },
+ // A saved view written before the switch already carries the id column.
+ {
+ column: "experimentDatasetId",
+ type: "stringOptions",
+ operator: "any of",
+ value: ["ds-legal"],
+ },
+ ];
+ expect(withDatasetNamesResolved(others, idByName)).toBe(others);
+ });
+
+ it("maps an unknown name to no id rather than dropping the filter", () => {
+ // Dropping it would widen the query to every dataset; an unknown dataset
+ // must return nothing.
+ const [resolved] = withDatasetNamesResolved(
+ nameFilter(["deleted-dataset"]),
+ idByName,
+ );
+ expect(resolved).toMatchObject({
+ column: "experimentDatasetId",
+ value: ["deleted-dataset"],
+ });
+ });
+
+ it("resolves each name in a multi-value selection", () => {
+ expect(
+ withDatasetNamesResolved(
+ nameFilter(["legal-answer-quality", "groundedness-judge-calibration"]),
+ idByName,
+ )[0],
+ ).toMatchObject({ value: ["ds-legal", "ds-ground"] });
+ });
+});
+
+describe("folding the legacy dataset column", () => {
+ const nameById = new Map([
+ ["ds-legal", "legal-answer-quality"],
+ ["ds-judge", "groundedness-judge-calibration"],
+ ]);
+ const migrate = (filters: FilterState, map = nameById) =>
+ getExperimentsFilterConfig([], map).migrateFilterState!(filters);
+
+ const legacy = (...ids: string[]): FilterState => [
+ {
+ type: "stringOptions",
+ column: "experimentDatasetId",
+ operator: "any of",
+ value: ids,
+ },
+ ];
+
+ it("moves the filter onto the canonical column as the dataset NAME", () => {
+ // The facet's options and labels are keyed by name, so folding the id
+ // through unchanged would show an opaque id with nothing checked.
+ expect(migrate(legacy("ds-legal"))).toEqual([
+ {
+ type: "stringOptions",
+ column: "experimentDatasetName",
+ operator: "any of",
+ value: ["legal-answer-quality"],
+ },
+ ]);
+ });
+
+ it("waits rather than folding while the id -> name map is empty", () => {
+ // The legacy column is real, so leaving it alone keeps querying correctly.
+ const filters = legacy("ds-legal");
+ expect(migrate(filters, new Map())).toBe(filters);
+ });
+
+ it("leaves an id it cannot name alone", () => {
+ // A deleted dataset must not become a name that matches nothing.
+ const filters = legacy("ds-deleted");
+ expect(migrate(filters)).toEqual(filters);
+ });
+
+ it("folds all values of an entry or none of them", () => {
+ const filters = legacy("ds-legal", "ds-deleted");
+ expect(migrate(filters)).toEqual(filters);
+ });
+
+ it("cannot leave two dataset filters behind", () => {
+ const migrated = migrate([...legacy("ds-legal"), ...legacy("ds-judge")]);
+
+ expect(migrated).toHaveLength(1);
+ expect(migrated[0]).toMatchObject({
+ column: "experimentDatasetName",
+ value: ["legal-answer-quality"],
+ });
+ });
+
+ it("leaves a filter state without the legacy column untouched", () => {
+ const filters: FilterState = [
+ {
+ type: "stringOptions",
+ column: "experimentDatasetName",
+ operator: "any of",
+ value: ["legal-answer-quality"],
+ },
+ ];
+
+ expect(migrate(filters)).toBe(filters);
+ });
+});
diff --git a/web/src/features/experiments/fns/datasetNameFilter.ts b/web/src/features/experiments/fns/datasetNameFilter.ts
new file mode 100644
index 0000000000..d3e865ba13
--- /dev/null
+++ b/web/src/features/experiments/fns/datasetNameFilter.ts
@@ -0,0 +1,35 @@
+import type { FilterState } from "@langfuse/shared";
+
+const DATASET_NAME_COLUMN = "experimentDatasetName";
+const DATASET_ID_COLUMN = "experimentDatasetId";
+
+/**
+ * Swaps `experimentDatasetName` filters for the equivalent
+ * `experimentDatasetId` filters on the way to the query.
+ *
+ * The dataset name is not a ClickHouse column — it lives in Postgres and
+ * reaches the client with the filter options. Keeping the NAME as the filter
+ * value is what makes a URL or saved view readable and lets the sidebar and the
+ * search bar show the same string; this is the one boundary where it becomes an
+ * id again. Names are unique per project, so the mapping is lossless.
+ *
+ * A name with no known id maps to no id rather than being dropped: an unknown
+ * dataset must return nothing, not everything.
+ */
+export function withDatasetNamesResolved(
+ filters: FilterState,
+ datasetIdByName: ReadonlyMap<string, string>,
+): FilterState {
+ if (!filters.some((filter) => filter.column === DATASET_NAME_COLUMN)) {
+ return filters;
+ }
+ return filters.map((filter) => {
+ if (filter.column !== DATASET_NAME_COLUMN) return filter;
+ if (filter.type !== "stringOptions") return filter;
+ return {
+ ...filter,
+ column: DATASET_ID_COLUMN,
+ value: filter.value.map((name) => datasetIdByName.get(name) ?? name),
+ };
+ });
+}
diff --git a/web/src/features/experiments/hooks/useExperimentFilterOptions.ts b/web/src/features/experiments/hooks/useExperimentFilterOptions.ts
index 12e07d8012..b0b029a999 100644
--- a/web/src/features/experiments/hooks/useExperimentFilterOptions.ts
+++ b/web/src/features/experiments/hooks/useExperimentFilterOptions.ts
@@ -41,16 +41,42 @@ export function useExperimentFilterOptions({
startTimeFilter: startTimeFilters.length > 0 ? startTimeFilters : undefined,
});
- const experimentFilterOptions = useMemo(() => {
- const experimentDatasetFilterOptions = datasets.data
- ?.filter((d) => filterOptions.data?.experimentDatasetIds?.includes(d.id))
- .map((d) => ({
- value: d.id,
- displayValue: d.name,
- }));
+ const usedDatasets = useMemo(
+ () =>
+ datasets.data?.filter((d) =>
+ filterOptions.data?.experimentDatasetIds?.includes(d.id),
+ ),
+ [datasets.data, filterOptions.data],
+ );
+
+ // Dataset names are unique per project, so the name IS the filter value —
+ // no displayValue indirection, which is what let the sidebar show a name
+ // while the search bar and the URL showed an opaque id.
+ //
+ // Both maps are built from EVERY dataset in the project, not from the
+ // datasets the facet offers. The facet list comes from a bounded options
+ // query, so a name missing from it would fail to translate and reach the
+ // query as an id that matches nothing — a filter that silently returns no
+ // rows. Offering fewer options than we can translate is fine; the reverse is
+ // not.
+ const datasetIdByName = useMemo(() => {
+ const map = new Map<string, string>();
+ for (const dataset of datasets.data ?? [])
+ map.set(dataset.name, dataset.id);
+ return map;
+ }, [datasets.data]);
+ /** Rows carry the dataset id; the table renders its name. */
+ const datasetNameById = useMemo(() => {
+ const map = new Map<string, string>();
+ for (const dataset of datasets.data ?? [])
+ map.set(dataset.id, dataset.name);
+ return map;
+ }, [datasets.data]);
+
+ const experimentFilterOptions = useMemo(() => {
return {
- experimentDatasetId: experimentDatasetFilterOptions,
+ experimentDatasetName: usedDatasets?.map((d) => ({ value: d.name })),
// Observation-level score options
obs_scores_avg: filterOptions.data?.obs_scores_avg ?? undefined,
obs_score_categories: processScoreCategories(
@@ -65,10 +91,12 @@ export function useExperimentFilterOptions({
trace_score_booleans:
filterOptions.data?.trace_score_booleans ?? undefined,
};
- }, [datasets.data, filterOptions.data]);
+ }, [usedDatasets, filterOptions.data]);
return {
filterOptions: experimentFilterOptions,
+ datasetIdByName,
+ datasetNameById,
isFilterOptionsPending: datasets.isLoading || filterOptions.isLoading,
};
}
diff --git a/web/src/features/search-bar/lib/searchBarInvariants.clienttest.ts b/web/src/features/search-bar/lib/searchBarInvariants.clienttest.ts
index b01b3c4b87..bf444a76ed 100644
--- a/web/src/features/search-bar/lib/searchBarInvariants.clienttest.ts
+++ b/web/src/features/search-bar/lib/searchBarInvariants.clienttest.ts
@@ -688,11 +688,18 @@ describe("search bar invariants — experiments registry", () => {
it("exposes only the sidebar facets whose columns are actually filterable", () => {
expect(EXPERIMENTS_FIELD_REGISTRY.fields.map((f) => f.id).sort()).toEqual([
+ "experimentDatasetName",
"name",
]);
- // The dataset column holds an ID while the sidebar shows the name, so the
- // bar would contradict it — see the registry's EXCLUDED_COLUMN_IDS note.
- expect(EXPERIMENTS_FIELD_REGISTRY.resolveField("dataset")).toBeNull();
+ // `dataset:` filters by the readable, unique name; the id column stays
+ // filterable for old saved views but is not offered here.
+ expect(EXPERIMENTS_FIELD_REGISTRY.resolveField("dataset")).toMatchObject({
+ type: "field",
+ field: { id: "experimentDatasetName" },
+ });
+ expect(
+ EXPERIMENTS_FIELD_REGISTRY.resolveField("experimentDatasetId"),
+ ).toBeNull();
});
it("keeps score dot-paths closed until the columns are unified", () => {