Implementation:Langfuse Langfuse Scores Converters

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

Overview

Converter functions that transform ClickHouse score records into application domain objects, handling type-specific field mapping for NUMERIC, CORRECTION, CATEGORICAL, and BOOLEAN score data types.

Description

This module provides two converter functions and one type definition for transforming score data between ClickHouse storage format and the application domain:

• ScoreAggregation: A TypeScript type representing a raw score aggregation row with fields like id, name, string_value, value, source, data_type, comment, and timestamp.

• convertClickhouseScoreToDomain: The primary converter that transforms a ScoreRecordReadType from ClickHouse into a typed ScoreByDataType<DataType> domain object. It handles:
  • Parsing ClickHouse UTC datetime strings to JavaScript Date objects via parseClickhouseUTCDateTimeFormat
  • Converting metadata from ClickHouse record format to domain format via parseMetadataCHRecordToDomain
  • Type-specific field mapping: NUMERIC and CORRECTION scores have stringValue: null, while other types (CATEGORICAL, BOOLEAN) map string_value to stringValue
  • An optional includeMetadataPayload parameter (defaults to true) to control whether metadata is included
  • Generic type parameters for both metadata exclusion (ExcludeMetadata) and data type (DataType)

• convertScoreAggregation: A simpler converter for aggregated score rows, producing a lightweight object with id, name, stringValue, numeric value, source, dataType, comment, and timestamp.

Usage

Use convertClickhouseScoreToDomain whenever reading individual score records from ClickHouse for API responses, detail views, or further processing. Use convertScoreAggregation when processing pre-aggregated score data from summary queries.

Code Reference

Source Location

• Repository: Langfuse
• File: packages/shared/src/server/repositories/scores_converters.ts
• Lines: 1-96

Signature

export type ScoreAggregation = {
  id: string;
  name: string;
  string_value: string | null;
  value: string;
  source: string;
  data_type: string;
  comment: string | null;
  timestamp: Date;
};

export const convertClickhouseScoreToDomain = <
  ExcludeMetadata extends boolean = false,
  DataType extends ScoreDataTypeType = ScoreDataTypeType,
>(
  record: ScoreRecordReadType,
  includeMetadataPayload?: boolean,
): ScoreByDataType<DataType>;

export const convertScoreAggregation = <DataType extends ScoreDataTypeType>(
  row: ScoreAggregation,
) => {
  id: string; name: string; stringValue: string | null;
  value: number; source: ScoreSourceType; dataType: DataType;
  comment: string | null; timestamp: Date;
};

Import

import {
  convertClickhouseScoreToDomain,
  convertScoreAggregation,
  type ScoreAggregation,
} from "@langfuse/shared/src/server/repositories/scores_converters";

I/O Contract

Inputs

convertClickhouseScoreToDomain

Name	Type	Required	Description
record	ScoreRecordReadType	Yes	Raw ClickHouse score record
includeMetadataPayload	boolean	No	Whether to include parsed metadata; defaults to true

convertScoreAggregation

Name	Type	Required	Description
row	ScoreAggregation	Yes	Raw score aggregation row

Outputs

Name	Type	Description
convertClickhouseScoreToDomain return	ScoreByDataType<DataType>	Fully typed domain score with parsed dates, metadata, and type-specific stringValue
convertScoreAggregation return	Lightweight score object	Object with numeric value, typed source, dataType, and other summary fields

Usage Examples

import { convertClickhouseScoreToDomain } from "./scores_converters";

// Convert a ClickHouse score record to domain
const rows = await queryClickhouse<ScoreRecordReadType>({ query });
const scores = rows.map((row) => convertClickhouseScoreToDomain(row));

// Without metadata for lightweight responses
const scoresLite = rows.map((row) => convertClickhouseScoreToDomain(row, false));

Related Pages

• Environment:Langfuse_Langfuse_ClickHouse_Analytics