Implementation:Langfuse Langfuse Sessions UI Table Service

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

Overview

The sessions-ui-table-service provides ClickHouse query functions for retrieving session table data using the direct trace and observation table join approach, supporting session listing, counting, and metrics with full filter and sort capabilities.

Description

This module is the primary implementation of the sessions table query service that uses direct joins between the deduplicated traces and observations tables in ClickHouse. It provides three main exported functions:

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

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

• getSessionsWithMetrics - Returns session rows enriched with full metrics including total observations, duration, usage/cost details broken down by input/output/total, and score aggregations.

All three functions delegate to a shared internal getSessionsTableGeneric function that builds a multi-CTE ClickHouse query:

1. scores_agg CTE (conditional) - Aggregates scores per session, computing average values for numeric/boolean scores and collecting categorical score name:value pairs. Only included when metrics are requested or score-based filters/sorting are active.

1. deduplicated_traces CTE - Deduplicates trace records using LIMIT 1 BY id, project_id with optional session ID, bookmarked, and environment filters applied early for performance.

1. deduplicated_observations CTE - Deduplicates observation records scoped to the trace IDs from the traces CTE, with optional timestamp filtering.

1. observations_agg CTE - Aggregates observations per trace, computing count, min/max times, and summed usage/cost details.

1. session_data CTE - Aggregates trace-level data into session-level data with LEFT JOINs to observations and scores aggregates.

The final SELECT applies session-level filters, ordering, and pagination. The trace table reference uses a __TRACE_TABLE__ placeholder that is replaced with "traces" at query execution time, enabling potential future table substitution.

Compared to the events-based service, this module uses explicit deduplication CTEs and direct table scans with Skip indices, which can be more efficient for certain query patterns.

Usage

Use this module when you need to:

• Query sessions table data using the direct trace/observation join strategy.
• Fetch session counts, listings, or metrics with full filter and sort support from the sessions UI.
• Access session-level cost, usage, duration, and score aggregations.

Code Reference

Source Location

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

Signature

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

export type SessionWithMetricsReturnType = SessionDataReturnType & {
  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 const getSessionsTableCount = async (props: {
  projectId: string;
  filter: FilterState;
  orderBy?: OrderByState;
  limit?: number;
  page?: number;
}) => number;

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

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

Import

import {
  getSessionsTableCount,
  getSessionsTable,
  getSessionsWithMetrics,
  SessionDataReturnType,
  SessionWithMetricsReturnType,
} from "@langfuse/shared/src/server/services/sessions-ui-table-service";

I/O Contract

Inputs

Name	Type	Required	Description
projectId	string	Yes	The project ID scoping all session queries
filter	FilterState	Yes	Dynamic filter conditions from the UI filter bar (supports session, trace, score, and metric filters)
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
number	number	Total session count matching filters (from getSessionsTableCount)
SessionDataReturnType[]	array	Session rows with core data: session ID, timestamps, trace IDs, user IDs, trace count, tags, environment
SessionWithMetricsReturnType[]	array	Session rows with full metrics: total observations, duration, usage/cost details (input/output/total), score aggregations

Usage Examples

import {
  getSessionsTableCount,
  getSessionsTable,
  getSessionsWithMetrics,
} from "@langfuse/shared/src/server/services/sessions-ui-table-service";

// Get total count for pagination
const count = await getSessionsTableCount({
  projectId: "proj-123",
  filter: [
    { column: "min_timestamp", type: "datetime", operator: ">=", value: new Date("2024-01-01") },
  ],
});

// Get paginated session listing
const sessions = await getSessionsTable({
  projectId: "proj-123",
  filter: [],
  orderBy: { column: "createdAt", order: "DESC" },
  limit: 50,
  page: 0,
});

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

// Access metrics from results
metricsRows.forEach((session) => {
  console.log(
    `Session ${session.session_id}: ` +
    `${session.trace_count} traces, ` +
    `${session.total_observations} observations, ` +
    `${session.duration}s duration, ` +
    `$${session.session_total_cost} total cost`
  );
});

Related Pages

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