Implementation:Langfuse Langfuse Sessions UI Table Events Service

Knowledge Sources	Langfuse
Domains	Sessions, ClickHouse, Events
Last Updated	2026-02-14 00:00 GMT

Overview

The sessions-ui-table-events-service provides ClickHouse query functions for retrieving session table data using the events-based aggregation approach, supporting session listing, counting, metrics, and trace retrieval.

Description

This module is an alternative implementation of the sessions table query service that uses an events-based aggregation strategy (via the eventsTracesAggregation CTE) rather than direct trace/observation table joins. It provides four main exported functions:

• getSessionTracesFromEvents - Retrieves individual traces for a specific session, ordered by timestamp ascending. Uses the events traces aggregation builder to construct a CTE that resolves trace data from events.

• getSessionsTableCountFromEvents - Returns the total count of sessions matching the given filter criteria.

• getSessionsTableFromEvents - Returns paginated session rows with core data: session ID, timestamps, trace IDs, user IDs, trace count, tags, and environment.

• getSessionsWithMetricsFromEvents - Returns session rows enriched with metrics: total observations, duration, usage details, cost details (input/output/total for both cost and usage), and score aggregations.

All three table functions delegate to a shared getSessionsTableFromEventsGeneric internal function that:

1. Constructs the appropriate SQL SELECT based on the select parameter ("count", "rows", or "metrics").
2. Builds filter conditions from the FilterState using session column definitions.
3. Conditionally includes a scores CTE (scores_agg) when metrics are requested or when score-based filters/sorting are active.
4. Uses the eventsTracesAggregation builder to create a traces CTE from events data.
5. Aggregates trace-level data into session-level data in a session_data CTE.
6. Applies session-level filters, ordering, and pagination.

The metrics computation aggregates cost and usage details using ClickHouse map functions (sumMap, mapFilter, mapValues) to separate input/output/total values. Score aggregations support both numeric/boolean (average values) and categorical (name:value pairs) scores.

Usage

Use this module when you need to:

• Query sessions table data using the events-based aggregation strategy.
• Retrieve session traces ordered by timestamp for a session detail view.
• Fetch session counts, listings, or metrics with full filter and sort support.
• Access session-level cost, usage, and score aggregations computed from the events model.

Code Reference

Source Location

• Repository: Langfuse
• File: packages/shared/src/server/services/sessions-ui-table-events-service.ts
• Lines: 1-415

Signature

export type SessionEventsDataReturnType = {
  session_id: string;
  max_timestamp: string;
  min_timestamp: string;
  trace_ids: string[];
  user_ids: string[];
  trace_count: number;
  trace_tags: string[];
  environment?: string;
  scores_avg?: Array<Array<[string, number]>>;
  score_categories?: Array<Array<string>>;
};

export type SessionEventsWithMetricsReturnType = SessionEventsDataReturnType & {
  total_observations: number;
  duration: number;
  session_usage_details: Record<string, number>;
  session_cost_details: Record<string, number>;
  session_input_cost: string;
  session_output_cost: string;
  session_total_cost: string;
  session_input_usage: string;
  session_output_usage: string;
  session_total_usage: string;
};

export type SessionTraceFromEvents = {
  id: string;
  name: string | null;
  timestamp: Date;
  environment: string | null;
  userId: string | null;
};

export const getSessionTracesFromEvents = async (props: {
  projectId: string;
  sessionId: string;
}) => SessionTraceFromEvents[];

export const getSessionsTableCountFromEvents = async (props: {
  projectId: string;
  filter: FilterState;
  orderBy?: OrderByState;
  limit?: number;
  page?: number;
}) => number;

export const getSessionsTableFromEvents = async (props: {
  projectId: string;
  filter: FilterState;
  orderBy?: OrderByState;
  limit?: number;
  page?: number;
}) => SessionEventsDataReturnType[];

export const getSessionsWithMetricsFromEvents = async (props: {
  projectId: string;
  filter: FilterState;
  orderBy?: OrderByState;
  limit?: number;
  page?: number;
  clickhouseConfigs?: ClickHouseClientConfigOptions;
}) => SessionEventsWithMetricsReturnType[];

Import

import {
  getSessionTracesFromEvents,
  getSessionsTableCountFromEvents,
  getSessionsTableFromEvents,
  getSessionsWithMetricsFromEvents,
} from "@langfuse/shared/src/server/services/sessions-ui-table-events-service";

I/O Contract

Inputs

Name	Type	Required	Description
projectId	string	Yes	The project ID scoping all session queries
sessionId	string	Yes (for traces)	The specific session ID to retrieve traces for
filter	FilterState	Yes (for table queries)	Dynamic filter conditions from the UI filter bar
orderBy	OrderByState	No	Column and direction for sorting session results
limit	number	No	Maximum number of rows to return per page
page	number	No	Page number for offset calculation (offset = limit * page)
clickhouseConfigs	ClickHouseClientConfigOptions	No	Custom ClickHouse client configuration overrides

Outputs

Name	Type	Description
SessionTraceFromEvents[]	array	Traces within a session with id, name, timestamp, environment, userId
number	number	Total session count matching filters
SessionEventsDataReturnType[]	array	Session rows with core data (IDs, timestamps, counts, tags)
SessionEventsWithMetricsReturnType[]	array	Session rows with full metrics (cost, usage, duration, scores)

Usage Examples

import {
  getSessionTracesFromEvents,
  getSessionsTableFromEvents,
  getSessionsWithMetricsFromEvents,
  getSessionsTableCountFromEvents,
} from "@langfuse/shared/src/server/services/sessions-ui-table-events-service";

// Get traces for a specific session
const traces = await getSessionTracesFromEvents({
  projectId: "proj-123",
  sessionId: "session-abc",
});

// Get paginated session listing
const sessions = await getSessionsTableFromEvents({
  projectId: "proj-123",
  filter: [
    { column: "min_timestamp", type: "datetime", operator: ">=", value: new Date("2024-01-01") },
  ],
  orderBy: { column: "createdAt", order: "DESC" },
  limit: 50,
  page: 0,
});

// Get total count for pagination
const count = await getSessionsTableCountFromEvents({
  projectId: "proj-123",
  filter: [],
});

// Get sessions with full metrics
const metricsRows = await getSessionsWithMetricsFromEvents({
  projectId: "proj-123",
  filter: [],
  limit: 10,
  page: 0,
});

Related Pages

• Environment:Langfuse_Langfuse_ClickHouse_Analytics
• Environment:Langfuse_Langfuse_PostgreSQL_17
• Environment:Langfuse_Langfuse_Redis_7_Queue_Cache