第 22 课的执行器负责「把查询发出去」,可那些查询的 WHERE 条件是谁拼的?这一课就讲过滤。关键洞察是:用户过滤的方式五花八门——点侧栏面板、敲搜索栏语法、甚至用 AI 自然语言描述——
但它们最终都汇成同一个 FilterState(一组带类型的条件),再由它编译成参数化 SQL(ClickHouse 或 Postgres)。一个中间契约,
既挡住了 SQL 注入,又让搜索栏、AI filter 这些花样都构造即安全。
FilterState 想成联合国的中间语。与会者说着不同的母语——有人点菜单(侧栏面板)、有人写电报(搜索栏 key:value 语法)、有人口述需求(AI 自然语言)——
但所有发言都先被译成同一种标准中间语(FilterState),再由它译成数据库听得懂的话(ClickHouse SQL 或 Postgres SQL)。这个译员有两条铁律:
一是绝不把原话直接塞进译文(用占位符传值,杜绝注入);二是听不懂的、编不出的,当场打回,绝不胡乱转述(校验 + 往返丢弃幻觉)。所有输入收敛到一种中间表示,再分发到各种后端——这就是过滤系统的骨架。
FilterState 是一组带类型的条件:每条说清「哪一列、什么运算符、什么值」(如 {column:"level", operator:"any of", value:["ERROR"]})。
它要变成 SQL,得过一个工厂 createFilterFromFilterState——这一步既翻译、又把关:
FilterState + 列定义经工厂 createFilterFromFilterState 校验列/类型、注入强制 project_id,再编译成参数化 SQL。ClickHouse 栈在 clickhouse-sql/,Postgres 栈在 filterToPrisma.ts。源码:queries/clickhouse-sql/factory.ts:37,217。packages/shared/src/interfaces/filters.ts;值为示例):搜索框的一行输入被解析成一个 FilterState 数组,每项是 {{column, operator, value, type}}。结构化之后既能校验(类型/算子合法),又能安全地编译成参数化 SQL 下推到 ClickHouse——这也是搜索栏成为「所有可过滤视图的统一入口」的基础。// 工厂:逐个把关再翻译 const column = matchAndVerifyTracesUiColumn(filter, columnMapping); // 列必须在 CH schema 里 const compatible = COMPATIBLE_FILTER_TYPES[colDef.type]; // 类型必须兼容 getProjectIdDefaultFilter(projectId, …); // 强制注入 project_id(第 10 课) // 每个过滤器的 apply():用随机参数名传值,绝不拼接字符串 apply(): ClickhouseFilter { const varName = `stringFilter${clickhouseCompliantRandomCharacters()}`; return { query: `col = {${varName}: String}`, params: { [varName]: this.value } }; }
看清这段就抓住了过滤系统的安全底座:用户输入的值,永远不会被拼进 SQL 字符串,而是绑定到一个随机命名的占位符(stringFilter_xY9z),
由数据库驱动安全地代入。哪怕你在过滤值里写 '; DROP TABLE…,它也只会被当成一个普通字符串去匹配,注入无从下手。加上工厂对「列是否存在、类型是否兼容」的前置校验,
脏输入在编译期就被挡下——这正是第 22 课资源保护之外的另一道防线。
3 种输入 × 2 套后端 = 6 套翻译逻辑、6 处要各自防注入。新加一种输入(比如 AI),就得为每个后端重写对接、重写安全校验——组合爆炸,且总有一处会写漏。
每个输入只管「译成 FilterState」,每个后端只管「从 FilterState 译出 SQL」。校验与参数化只在中间做一次。新加输入只需 +1 个译入器,白嫖所有后端与全部安全。
侧栏面板之外,Langfuse 还提供一个键盘党喜欢的搜索栏——一套 key:value 语法(如 level:(ERROR OR WARNING)、latency:>2、metadata.region:eu)。
但要记住一条铁律(写在它的 README 里):侧栏的 FilterState 才是唯一真源,搜索栏只是它的一个「受控编辑器」——它从 FilterState 读、往 FilterState 写,自己不另存一份。
| 搜索栏写法 | 含义 |
|---|---|
level:(ERROR OR WARNING) | 任选其一(any-of) |
-env:dev | 排除(none-of) |
latency:>2 · startTime:>2026-06-01 | 数值/时间比较 |
statusMessage:*chat* | 文本包含(* 通配) |
metadata.region:eu · scores.accuracy:>0.8 | 嵌套/点路径字段 |
这套语法有意只覆盖扁平 FilterState 能表达的范围:跨字段 OR、分组括号这些 FilterState 装不下的形态,搜索栏会给出阻止提交的诊断提示,而不是悄悄丢掉——
宁可当面说「这我编不出来」,也不给你一个似是而非的错误过滤。这正是「真源单一」带来的好处:搜索栏永远不会和侧栏不一致,因为它们本就是同一份 FilterState 的两种皮肤。
最妙的是 AI filter:你用自然语言说「给我看上周延迟超过 2 秒的报错」,generateFilter 调用大模型(Bedrock)把它变成过滤。可大模型会胡编不存在的列怎么办?
Langfuse 的解法堪称精巧——把模型输出往返一遍:
filterStateToQueryText 往返一遍,只有能还原成合法搜索栏语法(即能降解成 FilterState 能表达的过滤)的才保留,幻觉列直接 droppedCount++ 丢弃。源码:web/src/features/search-bar/server/router.ts:45,178-183。用户在搜索栏旁说「上周延迟超 2 秒的报错」;generateFilter(受保护过程,企业版)接住。
用 v4 字段注册表拼出提示词,调 Bedrock 生成候选过滤——此时可能夹带不存在的列。
把候选过滤通过 filterStateToQueryText 转回搜索栏语法,再尝试解析回 FilterState。
能干净往返的保留、应用;还原不了的(幻觉/非法列)丢弃并计入 droppedCount。
最终结果写进侧栏那份 FilterState——和你手点、手敲的过滤完全同源同路。
FilterState 中间契约后,事情变成 N+M:每个输入面只管「译成 FilterState」,每个后端只管「从 FilterState 译出 SQL」,校验与参数化只在中间做一次。
更深的一层是「构造即合法」:因为 AI 的输出必须能还原成 FilterState 能表达的形态才被采纳,幻觉列从结构上就不可能通过——安全不再依赖「记得加一道检查」,而是由表示本身的边界来保证。
这是「单一真源 + 中间表示」最优雅的一面。
FilterState(带类型的条件组),再编译成 SQL。clickhouse-sql/)或 Postgres(filterToPrisma.ts)。apply() 用随机命名的占位符传值,绝不拼接字符串;工厂还校验列存在性、类型兼容,并注入强制 project_id(第 10 课)。filterStateToQueryText,只留能还原成合法语法的——幻觉列构造上进不来。安全靠结构,不靠事后检查。
Lesson 22's executor "sends queries out", but who builds those queries' WHERE clauses? This lesson is about filtering. The key insight: users filter in
many ways — clicking the sidebar facets, typing search-bar grammar, even describing it in natural language to AI — yet they all converge into one
FilterState (a set of typed conditions), which then compiles to parameterized SQL (ClickHouse or Postgres). One intermediate
contract that both blocks SQL injection and makes the search bar and AI filters safe by construction.
FilterState as the UN's interlingua. Attendees speak different mother tongues — some pick from a menu (sidebar
facets), some write a telegram (search-bar key:value grammar), some dictate a request (AI natural language) — but every
utterance is first translated into one standard interlingua (FilterState), then translated again into what the database speaks (ClickHouse SQL or
Postgres SQL). This translator has two iron rules: never splice the original words straight into the translation (pass values via placeholders, no
injection); and refuse on the spot what it can't understand or express, never paraphrasing nonsense (validation + round-trip dropping
hallucinations). All inputs converge to one intermediate representation, then fan out to various backends — that's the filtering system's skeleton.
FilterState is a set of typed conditions: each says "which column, what operator, what value" (e.g.
{column:"level", operator:"any of", value:["ERROR"]}). To become SQL it passes a factory, createFilterFromFilterState — a step that
both translates and gatekeeps:
FilterState + column defs pass the factory createFilterFromFilterState, which verifies columns/types, injects the mandatory project_id, then compiles to parameterized SQL. ClickHouse stack in clickhouse-sql/, Postgres stack in filterToPrisma.ts. Source: queries/clickhouse-sql/factory.ts:37,217.packages/shared/src/interfaces/filters.ts; values illustrative): one line in the search bar parses into a FilterState array, each item a {{column, operator, value, type}}. Once structured it can be validated (legal type/operator) and safely compiled to parameterized SQL pushed down to ClickHouse — the basis for the search bar becoming the unified entry for every filterable view.// factory: gatekeep each, then translate const column = matchAndVerifyTracesUiColumn(filter, columnMapping); // column must be in CH schema const compatible = COMPATIBLE_FILTER_TYPES[colDef.type]; // type must be compatible getProjectIdDefaultFilter(projectId, …); // force-inject project_id (L10) // each filter's apply(): pass values via random param names, never splice strings apply(): ClickhouseFilter { const varName = `stringFilter${clickhouseCompliantRandomCharacters()}`; return { query: `col = {${varName}: String}`, params: { [varName]: this.value } }; }
Grasp this and you've got the filtering system's security bedrock: user-input values are never spliced into the SQL string, but bound
to a randomly-named placeholder (stringFilter_xY9z), safely substituted by the DB driver. Even if you write '; DROP TABLE… in a
filter value, it's matched as a plain string — injection has no foothold. Plus the factory's up-front checks for "does the column exist, is the type
compatible" stop dirty input at compile time — another line of defense beyond Lesson 22's resource protection.
3 inputs × 2 backends = 6 translation logics, 6 places to each guard injection. Add a new input (say AI) and you must rewrite the wiring and security checks for every backend — a combinatorial explosion, and one spot always gets missed.
Each input only "translates to FilterState", each backend only "translates FilterState to SQL". Validation and parameterization happen once in the middle. A new input is just +1 translator-in, freeloading all backends and all the safety.
Beyond the sidebar facets, Langfuse offers a keyboard-lover's search bar — a key:value grammar (e.g. level:(ERROR OR
WARNING), latency:>2, metadata.region:eu). But remember one iron rule (in its README): the sidebar's
FilterState is the single source of truth, and the bar is just a "controlled editor" over it — it reads from and writes to FilterState,
keeping no second copy.
| search-bar syntax | meaning |
|---|---|
level:(ERROR OR WARNING) | any-of |
-env:dev | exclude (none-of) |
latency:>2 · startTime:>2026-06-01 | numeric/time comparison |
statusMessage:*chat* | text contains (* glob) |
metadata.region:eu · scores.accuracy:>0.8 | nested / dot-path fields |
This grammar deliberately covers only what flat FilterState can express: shapes FilterState can't hold (cross-field OR, grouping
parens) get a commit-blocking diagnostic, not a silent drop — better to say to your face "I can't express that" than hand you a
plausible-but-wrong filter. That's the gift of "single source of truth": the bar can never disagree with the sidebar, because they're two skins of the same
FilterState.
Best of all is the AI filter: you say in natural language "show me last week's errors over 2 seconds latency", and generateFilter
calls an LLM (Bedrock) to turn it into filters. But what if the model hallucinates a nonexistent column? Langfuse's fix is elegant — it
round-trips the model output:
filterStateToQueryText; only filters that restore to valid search-bar grammar (i.e. lower to what FilterState can express) are kept, hallucinated columns droppedCount++. Source: web/src/features/search-bar/server/router.ts:45,178-183.The user says, next to the bar, "errors over 2s latency last week"; generateFilter (protected procedure, enterprise) catches it.
Build a prompt from the v4 field registry, call Bedrock to generate candidate filters — possibly smuggling in nonexistent columns.
Turn candidates back to search-bar grammar via filterStateToQueryText, then try to parse back to FilterState.
Cleanly round-tripping ones are kept and applied; un-restorable ones (hallucinated/illegal columns) are dropped and counted in droppedCount.
The result is written into the sidebar's FilterState — exactly the same source and path as your clicked and typed filters.
FilterState contract and it becomes N+M: each input only "translates to FilterState", each backend only "translates FilterState to SQL",
validation and parameterization done once in the middle. The deeper layer is "valid by construction": because the AI output must
restore to what FilterState can express to be accepted, hallucinated columns are structurally impossible to pass — safety no longer
depends on "remembering to add a check" but is guaranteed by the boundaries of the representation itself. This is the most elegant face of "single
source of truth + intermediate representation".
FilterState (a set of typed conditions), then compile to SQL.clickhouse-sql/) or Postgres (filterToPrisma.ts).apply() passes values via randomly-named placeholders, never splicing strings; the factory also verifies column existence, type compatibility, and injects the mandatory project_id (L10).filterStateToQueryText, keeping only what restores to valid grammar — hallucinated columns can't enter by construction. Security by structure, not after-checks.