Implementation:Langfuse Langfuse Dataset Run Items Repository

Knowledge Sources	Langfuse
Domains	Datasets, Experiments, ClickHouse
Last Updated	2026-02-14 00:00 GMT

Overview

Repository for querying dataset run items, run metrics, and experiment data from ClickHouse, providing the data layer for dataset run comparison views and experiment analysis.

Description

This module provides ClickHouse-backed data access for dataset run items -- the records that link dataset items to specific experiment runs via traces and observations. It powers the dataset runs table, experiment comparison views, and run metrics aggregation.

Key query patterns:

• Run items table -- getDatasetRunItemsTable queries the dataset_run_items_rmt table with full filtering, ordering, and pagination support using the ClickHouse filter framework.
• Run metrics -- getDatasetRunsTable supports three select modes: "rows" (basic run metadata), "metrics" (aggregated latency, cost, and score data), and "count" (total matching runs). Metrics queries join with score aggregations and compute average/total costs with trace-vs-observation priority logic.
• Enriched run items -- getDatasetRunItemsWithLinkedData returns run items enriched with observation latency/cost, trace duration/cost, and aggregated scores, used for detailed experiment comparison tables.
• Item-run mapping -- getDatasetItemIdsWithRunData and getDatasetItemsWithRunDataCount support paginated views of dataset items crossed with their run results, with per-run filtering.
• Deletion -- deleteDatasetRunItemsByDatasetId and deleteDatasetRunItemsByDatasetRunIds execute lightweight deletes on ClickHouse.
• Analytics -- getDatasetRunItemCountsByProjectInCreationInterval provides usage counts grouped by project for billing and analytics.

The module defines several domain types including DatasetRunsMetrics (with Decimal cost fields, score aggregates) and EnrichedDatasetRunItem (with linked observation and trace data).

Usage

Use this repository from tRPC routes serving the dataset runs UI, experiment comparison views, and the public API dataset endpoints. The metrics queries are particularly important for the runs table which shows aggregated latency, cost, and score metrics per run.

Code Reference

Source Location

• Repository: Langfuse
• File: packages/shared/src/server/repositories/dataset-run-items.ts
• Lines: 1-1232

Signature

export type DatasetRunsMetrics = {
  id: string;
  name: string;
  projectId: string;
  datasetId: string;
  countRunItems: number;
  avgTotalCost: Decimal;
  totalCost: Decimal;
  avgLatency: number;
  aggScoresAvg: Array<[string, number]>;
  aggScoreCategories: string[];
};

export type EnrichedDatasetRunItem = {
  id: string;
  createdAt: Date;
  datasetItemId: string;
  datasetItemVersion: Date | undefined;
  datasetRunId: string;
  datasetRunName: string;
  observation: { id: string; latency: number; calculatedTotalCost: Decimal } | undefined;
  trace: { id: string; duration: number; totalCost: number };
  scores: ScoreAggregate;
};

export const getDatasetRunsTable: (opts: DatasetRunsMetricsTableQuery) => Promise<...>;
export const getDatasetRunItemsTable: (opts: DatasetRunItemsTableQuery) => Promise<...>;
export const getDatasetRunItemsWithLinkedData: (opts: ...) => Promise<EnrichedDatasetRunItem[]>;
export const getDatasetItemIdsWithRunData: (opts: ...) => Promise<...>;
export const getDatasetItemsWithRunDataCount: (opts: ...) => Promise<number>;
export const deleteDatasetRunItemsByDatasetId: (opts: { projectId: string; datasetId: string }) => Promise<void>;
export const deleteDatasetRunItemsByDatasetRunIds: (opts: { projectId: string; datasetRunIds: string[]; datasetId: string }) => Promise<void>;
export const getDatasetRunItemCountsByProjectInCreationInterval: (opts: { start: Date; end: Date }) => Promise<...>;

Import

import {
  getDatasetRunsTable,
  getDatasetRunItemsTable,
  getDatasetRunItemsWithLinkedData,
  deleteDatasetRunItemsByDatasetId,
  deleteDatasetRunItemsByDatasetRunIds,
  getDatasetRunItemCountsByProjectInCreationInterval,
} from "@langfuse/shared/src/server/repositories/dataset-run-items";

I/O Contract

Inputs

Name	Type	Required	Description
projectId	string	Yes	Project scope for all queries
datasetId	string	Yes (for most queries)	Dataset to query run items for
filter	FilterState	Yes	Filter conditions (supports run name, dates, etc.)
runIds	string[]	No	Specific run IDs to include
orderBy	OrderByState	No	Column ordering specification
limit	number	No	Page size for pagination
offset	number	No	Offset for pagination
select	"metrics" | "count"	Yes (for runs table)	What data to return from runs query
start / end	Date	Yes (for interval counts)	Time interval boundaries

Outputs

Name	Type	Description
DatasetRunsMetrics	DatasetRunsMetrics	Aggregated run metrics including cost (Decimal), latency, and scores
DatasetRunsRows	{ id, name, projectId, createdAt, datasetId, description, metadata }	Basic run metadata
EnrichedDatasetRunItem	EnrichedDatasetRunItem	Run item with linked observation/trace data and scores
DatasetRunItemDomain	DatasetRunItemDomain	Core run item domain record
count	number	Result count for pagination

Usage Examples

import {
  getDatasetRunsTable,
  getDatasetRunItemsWithLinkedData,
} from "@langfuse/shared/src/server/repositories/dataset-run-items";

// Get run metrics for a dataset
const metrics = await getDatasetRunsTable({
  select: "metrics",
  projectId: "proj_123",
  datasetId: "ds_456",
  filter: [],
  orderBy: { column: "createdAt", order: "DESC" },
  limit: 20,
  offset: 0,
});

// Get enriched run items for comparison view
const enrichedItems = await getDatasetRunItemsWithLinkedData({
  projectId: "proj_123",
  datasetId: "ds_456",
  runIds: ["run_1", "run_2"],
  datasetItemIds: ["item_1", "item_2"],
});

Related Pages

• Environment:Langfuse_Langfuse_ClickHouse_Analytics