Implementation:Langfuse Langfuse Dashboards Repository

Knowledge Sources	Langfuse
Domains	Dashboard, Analytics, ClickHouse
Last Updated	2026-02-14 00:00 GMT

Overview

Repository providing ClickHouse-backed dashboard analytics queries for score aggregation, observation cost, and usage time-series data with dynamic time bucketing.

Description

This module contains the data access functions that power the Langfuse dashboard analytics views. It queries ClickHouse to produce aggregated metrics over configurable time windows, with support for dynamic filter states and environment-scoped queries.

Key functions:

• getScoreAggregate -- Aggregates scores by name, source, and data type, returning counts and average values. Optionally joins with the traces table when trace-level filters are present.
• getObservationCostByTypeByTime -- Produces time-series cost breakdowns by cost detail key (e.g., input, output, total). Uses ClickHouse ARRAY JOIN on the cost_details map column to pivot cost types into rows, then groups by time bucket.
• getObservationUsageByTypeByTime -- Similar to cost, but aggregates token usage by usage detail key over time.

Supporting utilities:

• orderByTimeSeries -- Computes optimal time bucket size from predefined intervals (5s to 30 days) targeting approximately 50 buckets, and generates ClickHouse ORDER BY ... WITH FILL clauses for gap-free time series.
• selectTimeseriesColumn -- Generates toStartOfInterval expressions for bucketing timestamps.
• extractFromAndToTimestampsFromFilter -- Extracts the from/to datetime boundaries from a filter state array.

All queries use parameterized ClickHouse SQL with the filter framework (FilterList, createFilterFromFilterState) to safely apply user-defined filters. Environment filters are extracted and applied separately to support cross-table filtering.

Usage

Use these functions from tRPC dashboard routes to fetch analytics data for the dashboard charts. Each function requires a project ID and a filter state that must include datetime range filters for time-series queries.

Code Reference

Source Location

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

Signature

export type DateTrunc = "month" | "week" | "day" | "hour" | "minute";

export const getScoreAggregate = async (
  projectId: string,
  filter: FilterState,
) => Promise<Array<{ name: string; count: string; avg_value: string; source: string; data_type: string }>>;

export const getObservationCostByTypeByTime = async (
  projectId: string,
  filter: FilterState,
) => Promise<Array<{ intervalStart: Date; key: string; sum: number }>>;

export const getObservationUsageByTypeByTime = async (
  projectId: string,
  filter: FilterState,
) => Promise<Array<{ intervalStart: Date; key: string; sum: number }>>;

export const orderByTimeSeries = (
  filter: FilterState,
  col: string,
): [string, { fromTime: number; toTime: number }, number];

export const selectTimeseriesColumn = (
  bucketSizeInSeconds: number,
  col: string,
  as: String,
) => string;

export const extractFromAndToTimestampsFromFilter = (
  filter?: FilterState,
) => [FilterState[0] | undefined, FilterState[0] | undefined];

Import

import {
  getScoreAggregate,
  getObservationCostByTypeByTime,
  getObservationUsageByTypeByTime,
  orderByTimeSeries,
  selectTimeseriesColumn,
  extractFromAndToTimestampsFromFilter,
} from "@langfuse/shared/src/server/repositories/dashboards";

I/O Contract

Inputs

Name	Type	Required	Description
projectId	string	Yes	Scopes all queries to a specific project
filter	FilterState	Yes	Array of filter conditions including required datetime range for time-series
col	string	Yes (for orderByTimeSeries)	Column name for time-series ordering (e.g., "start_time")
bucketSizeInSeconds	number	Yes (for selectTimeseriesColumn)	Interval size for time bucketing

Outputs

Name	Type	Description
Score aggregate	Array<{name, count, avg_value, source, data_type}>	Aggregated score metrics grouped by name/source/data_type
Cost by type	Array<{intervalStart, key, sum}>	Time-bucketed cost sums per cost detail key
Usage by type	Array<{intervalStart, key, sum}>	Time-bucketed usage sums per usage detail key
orderByTimeSeries return	[query, params, bucketSize]	ClickHouse ORDER BY WITH FILL clause, parameters, and computed bucket size

Usage Examples

import { getScoreAggregate, getObservationCostByTypeByTime } from "@langfuse/shared/src/server/repositories/dashboards";

// Get score aggregates for a project with date filter
const scores = await getScoreAggregate("proj_123", [
  { column: "Timestamp", type: "datetime", operator: ">=", value: new Date("2024-01-01") },
  { column: "Timestamp", type: "datetime", operator: "<=", value: new Date("2024-01-31") },
]);

// Get cost time series
const costTimeSeries = await getObservationCostByTypeByTime("proj_123", [
  { column: "Start Time", type: "datetime", operator: ">=", value: new Date("2024-01-01") },
  { column: "Start Time", type: "datetime", operator: "<=", value: new Date("2024-01-31") },
]);

Related Pages

• Environment:Langfuse_Langfuse_ClickHouse_Analytics