Implementation:Langfuse Langfuse EventsTable Definition
| Knowledge Sources | |
|---|---|
| Domains | ClickHouse, Table Definitions, Filtering |
| Last Updated | 2026-02-14 00:00 GMT |
Overview
Defines the column definitions for the ClickHouse events table, mapping UI column names and filter types to their corresponding ClickHouse SQL expressions.
Description
The eventsTableCols array is an exported constant that provides a comprehensive list of ColumnDefinition objects describing every column available in the events table. Each definition specifies a human-readable name, a programmatic ID, a filter type (e.g., string, number, datetime, stringOptions, arrayOptions), and an internal field containing the raw ClickHouse SQL expression used in queries. Many columns include complex ClickHouse expressions for computed values such as total cost (using mapExists and cost_details), token counts (using arraySum and mapFilter over usage_details), latency calculations (using date_diff), and tokens-per-second throughput. Several columns are marked nullable: true and some have empty options arrays that are populated at runtime.
The 36 columns defined cover trace identification (ID, Trace ID), timing (Start Time, End Time, Latency, Time To First Token), naming and classification (Name, Type, Level, Environment, Version), user and session tracking (User ID, Session ID), model information (Model ID, Provided Model Name, Prompt Name), cost and usage metrics (Total Cost, Input/Output/Total Tokens, Input/Output Cost), content fields (Input, Output, Metadata), scoring (Scores numeric, Scores categorical), and experimental context (Experiment Dataset ID, Experiment ID, Experiment Name).
Usage
Use this definition array whenever the web application or worker needs to build filter UIs, generate ClickHouse queries with proper column mappings, or validate filter operations against the events table. It is imported by filtering and table rendering components to ensure consistency between the UI and the underlying ClickHouse schema.
Code Reference
Source Location
- Repository: Langfuse
- File: packages/shared/src/eventsTable.ts
- Lines: 1-276
Signature
export const eventsTableCols: ColumnDefinition[];
Import
import { eventsTableCols } from "@langfuse/shared";
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| (none) | N/A | N/A | This is a static constant array; it accepts no inputs. |
Outputs
| Name | Type | Description |
|---|---|---|
| eventsTableCols | ColumnDefinition[] |
Array of 36 column definition objects, each with name, id, type, internal (ClickHouse SQL expression), optional options, and optional nullable flag.
|
Usage Examples
import { eventsTableCols } from "@langfuse/shared";
// Find the internal ClickHouse expression for a filter column
const latencyCol = eventsTableCols.find((col) => col.id === "latency");
console.log(latencyCol?.internal);
// => "date_diff('millisecond', e.start_time, e.end_time) / 1000.0"
// Use in filter-to-SQL conversion
const totalCostCol = eventsTableCols.find((col) => col.id === "totalCost");
// totalCostCol.internal contains the ClickHouse map expression for cost_details['total']