Langfuse on ClickHouse, without Langfuse

---

Langfuse (open-source LLM observability) keeps its OLTP state in Postgres, but every observation and score lands in ClickHouse. This lab loads a snapshot of that ClickHouse database into a plain ClickHouse server and runs the ClickHouse SQL from the langfuse-hols workshop on it. You need one container. Langfuse, Postgres and Python are not needed.

Verified end to end on 2026-10-06 against ClickHouse 26.8.18.2: tools/hol run passes all four SQL files. The snapshot itself comes from Langfuse 4.52.0, SDK 4.17.0 and ClickHouse 26.8.18.2.

What is in the snapshot

00-data.sql recreates Langfuse's ClickHouse database default:

• every table and view exactly as Langfuse's migrations created them (no DDL changes), and
• the raw rows, read without FINAL.

It is generated by export_snapshot.py from one run of the langfuse-hols v4 track at commit c7901ec:

• OSS mode, no model key, so every model call is simulated;
• langfuse-ee 02 seeded 40 traces;
• langfuse-eval 01 seeded 20 more, and 02–06 added prompts, a dataset, two experiments, a rubric judge and an annotation queue.

Table	Rows	What it holds
events_full	424	One wide row per observation: 240 SPAN, 104 GENERATION, 80 EVALUATOR. 101 of them are trace root rows (is_app_root)
events_core	424	The same rows with input, output and metadata truncated. In Langfuse events_core_mv fills it; the snapshot loads its rows directly and creates the MV last
scores	212	Every quality signal. All of them have source = 'API' (see Limits)
blob_storage_file_log, schema_migrations	212, 100	Langfuse bookkeeping
traces, observations	0	v3 tables: still created by the migrations, but v4 no longer writes to them. 01-explore.sql shows this
dataset_run_items_rmt, observations_batch_staging, observations_pid_tid_sorting	0	Empty in this run

A round trip proves the copy is exact. 00-data.sql was loaded into a fresh clickhouse/clickhouse-server:26.8.18.2, and all 14 objects matched the source on count() and sum(cityHash64(toString(tuple(*)))). As a negative check, a deliberately modified copy showed DIFF, and reloading the file restored the match.

Files

File	What it does
00-data.sql	Generated snapshot: DDL, raw rows, materialized views created last (1.5 MB)
01-explore.sql	Langfuse's tables, engines and sort keys; a trace as its root row (langfuse-ee/03)
02-analytics.sql	Cost, latency, tokens and quality as plain ClickHouse SQL (langfuse-ee/04)
03-scores.sql	Scores joined to their traces' root rows (langfuse-eval/07)
export_snapshot.py	Regenerates 00-data.sql from a running langfuse-hols v4 stack

The three SQL files are copies of the langfuse-hols files at c7901ec. Only their run instructions changed.

Run

tools/hol run usecase/langfuse-on-clickhouse

That starts a throwaway clickhouse/clickhouse-server:26.8.18.2 and runs 00…03 in order. Add --keep to leave it up and query it yourself:

docker exec -it hol-usecase-langfuse-on-clickhouse clickhouse-client

Limits

• The schema is Langfuse's internal detail, not an API. It matches Langfuse 4.52.0. Other versions can rename columns or tables (v3 → v4 moved everything to events_*).
• All 212 scores are source = 'API'. 03-scores.sql is written for three sources: API, EVAL and ANNOTATION. In this offline run every score came in through the SDK/API, including the rubric judge (05) and the annotation-queue demo scores (06). EVAL needs Langfuse's managed LLM judge, which needs a model connection.
• FINAL changes nothing here. Every row has its own sorting key and none is marked deleted. For example, events_full has 424 rows with and without FINAL. The SQL still uses FINAL, as it should on a live Langfuse, but the snapshot has no row versions for it to collapse.
• Simulated data. No model was called, so costs, latencies and outputs come from the generator, not from a real LLM. The users (user_001 …) are synthetic. The only key in the data is the workshop's public placeholder pk-lf-workshop-public, in ingestion_api_key.

Regenerate the snapshot

1. Bring up the langfuse-hols v4 stack. Host ports 8123 and 9000 must be free, so stop a ClickStack or any other local ClickHouse first.
2. Run the seed commands listed in the header of 00-data.sql, with ANTHROPIC_API_KEY empty.
3. Run the regenerate command from the same header, then tools/hol run again.

The generator writes byte-identical output for the same data and --date.

Related

• langfuse-hols: the live versions of these labs, with Langfuse itself: v4 langfuse-ee (OSS 01–04, Enterprise 05–11) and langfuse-eval.

---

tools/hol run usecase/langfuse-on-clickhouse

docker exec -it hol-usecase-langfuse-on-clickhouse clickhouse-client