Implementation:Langfuse Langfuse Dataset Run Items Converters

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

Overview

Converter functions that transform dataset run item records between ClickHouse storage format and the application domain model, plus a helper for converting raw dataset run metric rows.

Description

This module provides bidirectional conversion between the ClickHouse storage representation of dataset run items and the application-level DatasetRunItemDomain type. It contains three exported functions:

• convertToDatasetRunMetrics: Converts a raw row (from a metrics aggregation query) into a dataset run metrics object with properties like id, name, countRunItems, and date fields. Cost and latency fields are set to undefined as they are computed separately.

• convertDatasetRunItemDomainToClickhouse: Transforms a DatasetRunItemDomain object into the DatasetRunItemRecordReadType format for ClickHouse insertion. Converts all Date fields to ClickHouse DateTime format using convertDateToClickhouseDateTime and sets event timestamp and deletion flag for the append-only ClickHouse schema.

• convertDatasetRunItemClickhouseToDomain: Transforms a ClickHouse record back into a DatasetRunItemDomain object. Uses function overloads to provide clean type discrimination based on a WithIO boolean generic parameter. When IO fields (dataset_item_input, dataset_item_expected_output, dataset_item_metadata) are present in the record, they are included in the domain object; otherwise, a base conversion without IO fields is returned. Metadata is parsed from ClickHouse's record format to domain format via parseMetadataCHRecordToDomain.

Usage

Use these converters in the dataset run items repository layer when reading from or writing to ClickHouse. The WithIO generic parameter allows callers to control whether large input/output payloads are included in the returned domain objects, enabling optimized queries that omit these fields for list views.

Code Reference

Source Location

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

Signature

export const convertToDatasetRunMetrics = (row: any) => {
  id: string; projectId: string; createdAt: Date; updatedAt: Date;
  name: string; description: string; metadata: unknown;
  countRunItems: number; datasetId: string;
  avgTotalCost: undefined; totalCost: undefined; avgLatency: undefined; scores: undefined;
};

export const convertDatasetRunItemDomainToClickhouse = (
  datasetRunItem: DatasetRunItemDomain,
): DatasetRunItemRecordReadType;

// Overloaded
export function convertDatasetRunItemClickhouseToDomain(
  row: DatasetRunItemRecord<true>,
): DatasetRunItemDomain<true>;
export function convertDatasetRunItemClickhouseToDomain(
  row: DatasetRunItemRecord<false>,
): DatasetRunItemDomain<false>;

Import

import {
  convertToDatasetRunMetrics,
  convertDatasetRunItemDomainToClickhouse,
  convertDatasetRunItemClickhouseToDomain,
} from "@langfuse/shared/src/server/repositories/dataset-run-items-converters";

I/O Contract

Inputs

Name	Type	Required	Description
row	any (metrics) or DatasetRunItemRecord<WithIO>	Yes	Raw row from ClickHouse query or typed record
datasetRunItem	DatasetRunItemDomain	Yes	Domain object to convert to ClickHouse format

Outputs

Name	Type	Description
convertToDatasetRunMetrics return	metrics object	Dataset run metrics with count, dates, and metadata
convertDatasetRunItemDomainToClickhouse return	DatasetRunItemRecordReadType	ClickHouse-compatible record with DateTime strings and deletion flag
convertDatasetRunItemClickhouseToDomain return	DatasetRunItemDomain<WithIO>	Application domain object with parsed dates and optional IO fields

Usage Examples

import {
  convertDatasetRunItemClickhouseToDomain,
  convertDatasetRunItemDomainToClickhouse,
} from "./dataset-run-items-converters";

// Convert ClickHouse record to domain (with IO)
const chRecord = await queryClickhouse<DatasetRunItemRecord<true>>({ query });
const domainItem = convertDatasetRunItemClickhouseToDomain(chRecord[0]);
console.log(domainItem.datasetItemInput); // available when WithIO=true

// Convert domain object to ClickHouse for insertion
const chInsert = convertDatasetRunItemDomainToClickhouse(domainItem);
await insertClickhouse("dataset_run_items", [chInsert]);

Related Pages

• Environment:Langfuse_Langfuse_ClickHouse_Analytics