Implementation:Langfuse Langfuse Scores Utils

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

Overview

Internal utility functions for retrieving scores by ID from ClickHouse, supporting single-score and batch lookups with optional filtering by source, scope, and data type.

Description

This module provides two internal ClickHouse query functions for score retrieval, marked with @internal to indicate they should not be called directly by consumers. Instead, callers should use the ScoresApiService or higher-level repository functions.

• _handleGetScoreById: Retrieves a single score by its ID and project ID. Supports optional filters for score source (ScoreSourceType), scope (traces_only or all), and data types. Uses ORDER BY event_ts DESC LIMIT 1 BY id, project_id LIMIT 1 to get the latest version of the score (ClickHouse append-only deduplication). Returns undefined if no matching score is found.

• _handleGetScoresByIds: Retrieves multiple scores by an array of IDs. Uses the same filtering options as the single-ID variant but returns all matching scores with LIMIT 1 BY id, project_id deduplication (no overall limit).

Both functions convert ClickHouse records to domain objects using convertClickhouseScoreToDomain.

The scoreScope parameter controls whether only trace-level scores are returned (traces_only, filtering out session and dataset run scores) or all scores (all).

Usage

These are internal building blocks for the scores repository layer. Do not call directly; use ScoresApiService methods or the public repository interface instead. They are separated into this utility module for reuse across different score query patterns.

Code Reference

Source Location

• Repository: Langfuse
• File: packages/shared/src/server/repositories/scores-utils.ts
• Lines: 1-107

Signature

export const _handleGetScoreById = async (params: {
  projectId: string;
  scoreId: string;
  source?: ScoreSourceType;
  scoreScope: "traces_only" | "all";
  scoreDataTypes?: readonly ScoreDataTypeType[];
  preferredClickhouseService?: PreferredClickhouseService;
}): Promise<ScoreDomain | undefined>;

export const _handleGetScoresByIds = async (params: {
  projectId: string;
  scoreId: string[];
  source?: ScoreSourceType;
  scoreScope: "traces_only" | "all";
  dataTypes?: readonly ScoreDataTypeType[];
}): Promise<ScoreDomain[]>;

Import

import {
  _handleGetScoreById,
  _handleGetScoresByIds,
} from "@langfuse/shared/src/server/repositories/scores-utils";

I/O Contract

Inputs

Name	Type	Required	Description
projectId	string	Yes	The project ID to scope the query
scoreId	string or string[]	Yes	The score ID(s) to look up
source	ScoreSourceType	No	Optional filter by score source (e.g., API, ANNOTATION)
scoreScope	"all"	Yes	Whether to return only trace-level scores or all scopes
scoreDataTypes / dataTypes	readonly ScoreDataTypeType[]	No	Optional filter by data types (NUMERIC, BOOLEAN, CATEGORICAL, etc.)
preferredClickhouseService	PreferredClickhouseService	No	Optional preferred ClickHouse service instance

Outputs

Name	Type	Description
_handleGetScoreById return	undefined>	The matching score domain object, or undefined if not found
_handleGetScoresByIds return	Promise<ScoreDomain[]>	Array of matching score domain objects

Usage Examples

// Internal usage within repository layer
import { _handleGetScoreById, _handleGetScoresByIds } from "./scores-utils";

// Get a single score
const score = await _handleGetScoreById({
  projectId: "proj-123",
  scoreId: "score-456",
  scoreScope: "traces_only",
});

// Get multiple scores by IDs
const scores = await _handleGetScoresByIds({
  projectId: "proj-123",
  scoreId: ["score-1", "score-2", "score-3"],
  scoreScope: "all",
  dataTypes: ["NUMERIC", "BOOLEAN"],
});

Related Pages

• Environment:Langfuse_Langfuse_ClickHouse_Analytics