Implementation:Langfuse Langfuse Public API Filter Builder

Knowledge Sources	Langfuse
Domains	Public API, Query Building
Last Updated	2026-02-14 00:00 GMT

Overview

Converts public API query parameters into ClickHouse filter lists, providing column mapping definitions for traces and observations tables, and a merge strategy where advanced JSON filters take precedence over simple query parameters.

Description

This module bridges the public REST API layer and the ClickHouse query layer. It provides:

1. Column mapping factories:
   • createPublicApiTracesColumnMapping: Generates column mappings for trace-level API filters (timestamp, userId, name, environment, metadata, sessionId, version, release, tags). Timestamp is split into fromTimestamp (>=) and toTimestamp (<) filters.
   • createPublicApiObservationsColumnMapping: Generates column mappings for observation-level API filters (userId, traceId, name, level, type, parentObservationId, startTime range, version, environment). Supports both the legacy observations table and the new events table with appropriate field name differences.

1. Filter conversion: convertApiProvidedFilterToClickhouseFilter iterates over the column mappings, reads matching values from the API query object, and instantiates the appropriate ClickHouse filter class (DateTimeFilter, ArrayOptionsFilter, StringOptionsFilter, CategoryOptionsFilter, StringFilter, NumberFilter) into a FilterList.

1. Filter merging: deriveFilters combines simple API query parameters with advanced JSON filter arrays (FilterState). Advanced filters are converted first using createFilterFromFilterState, then simple parameter filters are added only for fields not already covered by the advanced filters. This ensures advanced filters always take precedence.

The base column definitions for traces (TRACES_COLUMN_DEFINITIONS) provide a single source of truth that is reused by both the traces and events table column mapping factories.

Usage

Use this module in public API route handlers to convert incoming query parameters and optional JSON filter bodies into ClickHouse-compatible filter lists. Call createPublicApiTracesColumnMapping or createPublicApiObservationsColumnMapping to get the column definitions, then use deriveFilters or convertApiProvidedFilterToClickhouseFilter to produce the FilterList for query execution.

Code Reference

Source Location

• Repository: Langfuse
• File: packages/shared/src/server/queries/public-api-filter-builder.ts
• Lines: 1-378

Signature

export type ApiColumnMapping = {
  id: string;
  clickhouseSelect: string;
  clickhouseTable: string;
  filterType: string;
  operator?: ClickhouseOperator;
  clickhousePrefix?: string;
};

export function createPublicApiTracesColumnMapping(
  tableName: "traces" | "events",
  tablePrefix: "t" | "e",
): ApiColumnMapping[];

export function createPublicApiObservationsColumnMapping(
  tableName: "events" | "observations",
  tablePrefix: "e" | "o",
  parentFieldName: "parent_span_id" | "parent_observation_id",
): ApiColumnMapping[];

export function convertApiProvidedFilterToClickhouseFilter(
  filter: BaseQueryType,
  columnMapping: ApiColumnMapping[],
): FilterList;

export function deriveFilters<T extends BaseQueryType>(
  simpleFilterProps: T,
  filterParamsMapping: ApiColumnMapping[],
  advancedFilters: FilterState | undefined,
  uiColumnDefinitions: UiColumnMappings,
): FilterList;

Import

import {
  createPublicApiTracesColumnMapping,
  createPublicApiObservationsColumnMapping,
  convertApiProvidedFilterToClickhouseFilter,
  deriveFilters,
  type ApiColumnMapping,
} from "@langfuse/shared/src/server/queries/public-api-filter-builder";

I/O Contract

Inputs

Name	Type	Required	Description
tableName	"traces" / "events" / "observations"	Yes	The ClickHouse table to generate column mappings for
tablePrefix	"t" / "e" / "o"	Yes	The SQL alias prefix for the table
filter	BaseQueryType	Yes	API query parameters object containing page, limit, projectId, and optional filter fields
columnMapping	ApiColumnMapping[]	Yes	Column mapping definitions to drive filter creation
simpleFilterProps	T extends BaseQueryType	Yes	Simple API query parameters for deriveFilters
advancedFilters	FilterState / undefined	No	Optional advanced JSON filter array from the API request body
uiColumnDefinitions	UiColumnMappings	Yes	UI column definitions used for converting advanced filters

Outputs

Name	Type	Description
ApiColumnMapping[]	array	Column mapping definitions for the specified table
FilterList	FilterList	Composed ClickHouse filter list ready for query building

Usage Examples

import {
  createPublicApiTracesColumnMapping,
  deriveFilters,
} from "@langfuse/shared/src/server/queries/public-api-filter-builder";

// In a public API route handler for GET /api/public/traces
const columnMapping = createPublicApiTracesColumnMapping("events", "e");

const filters = deriveFilters(
  {
    page: 1,
    limit: 50,
    projectId: "project-123",
    userId: "user-abc",
    fromTimestamp: "2024-01-01T00:00:00Z",
    name: "my-trace",
  },
  columnMapping,
  req.body.filter, // optional advanced filters from request body
  tracesTableUiColumns,
);

const { query: filterQuery, params: filterParams } = filters.apply();
// Use filterQuery and filterParams in ClickHouse query construction