Events Table Query Routing#

Scope: This covers how read queries are routed between the legacy ClickHouse traces/observations tables and the V4 events tables (events_core, events_full), including the useEventsTable flag, environment variable fallback, and implications for V4 events-only deployments.

Overview#

During the V4 data pipeline migration, Langfuse introduced a dual-path query architecture. Legacy queries run against the traces and observations ClickHouse tables; V4 queries aggregate from events_core and events_full via purpose-built repository functions. At runtime, a useEventsTable boolean (derived from a query parameter or environment variable) selects which path to execute.

The write-side counterpart is controlled by LANGFUSE_MIGRATION_V4_WRITE_MODE (legacy | dual | events_only). The default for new deployments is events_only, meaning new installations write only to the events tables and have no legacy table data. 1

Environment Variables#

Three web/src/env.mjs variables gate events-table routing 2:

The useEventsTable Flag#

Schema#

useEventsTableSchema in web/src/features/query/types.ts accepts "true", "false", or a native boolean and transforms to a boolean value. This allows callers to pass the flag as a query string parameter.

Resolution pattern#

Every public API read endpoint resolves useEventsTable with the same pattern — query parameter beats environment variable:

useEventsTable = (query.useEventsTable != null)
  ? query.useEventsTable === true
  : env.LANGFUSE_ENABLE_EVENTS_TABLE_OBSERVATIONS === "true"

This pattern is used in 3, 4, and 5.

Routing by API Layer#

Public REST API — traces list#

web/src/pages/api/public/traces/index.ts 6:

• Events path → getTracesFromEventsTableForPublicApi + getTracesCountFromEventsTableForPublicApi
• Legacy path → generateTracesForPublicApi + getTracesCountForPublicApi

Public REST API — observations list and by-ID#

web/src/pages/api/public/observations/index.ts 7:

• Events path → getObservationsFromEventsTableForPublicApi + getObservationsCountFromEventsTableForPublicApi
• Legacy path → generateObservationsForPublicApi + getObservationsCountForPublicApi

web/src/pages/api/public/observations/[observationId].ts 8:

• Events path → getObservationByIdFromEventsTable
• Legacy path → getObservationById

tRPC observations router (UI)#

web/src/server/api/routers/observations.ts reads LANGFUSE_ENABLE_EVENTS_TABLE_OBSERVATIONS directly — no per-request override 9:

• Events path → getObservationByIdFromEventsTable
• Legacy path → getObservationById

tRPC traces router (UI)#

web/src/server/api/routers/traces.ts does not route trace reads to the events table. getTracesTable and getTracesTableCount always query the legacy traces ClickHouse table. This is in contrast to sessions, which have explicit allFromEvents / countAllFromEvents tRPC endpoints with an isBetaEnabled toggle.

Mutations — dual-write via LANGFUSE_ENABLE_EVENTS_TABLE_FLAGS#

The bookmark and publish tRPC mutations apply changes to the legacy traces table first, then conditionally fan out to the events tables when LANGFUSE_ENABLE_EVENTS_TABLE_FLAGS === "true" 10 11. Both calls are made in parallel via Promise.all.

V4 Events-Only Instances#

In events_only write mode (the default for new deployments), the legacy traces and observations tables contain no data. For such instances:

• Public API reads must have LANGFUSE_ENABLE_EVENTS_TABLE_OBSERVATIONS=true (or the caller must pass useEventsTable=true), otherwise queries return empty results.
• The tRPC traces table UI (.all, .countAll) will return empty results because it always queries the legacy traces table — events-table backing for the traces UI list is not yet implemented.
• Onboarding state detection (hasAnyTrace) uses a three-step fallback: PostgreSQL flag → ClickHouse traces table → ClickHouse events tables, ensuring V4-only projects are not incorrectly shown the onboarding UI.

Key Source Files#