🪢 Langfuse 图解教程Langfuse Visual Guide 第四部分 · 查询链路Part 4 · The Read Path 23 / 55
第四部分 · 查询链路Part 4 · The Read Path

过滤·搜索栏·查询构建Filtering & the search bar

🧭 读前Before you start
先读 第22课 的仓储层,本课讲过滤、搜索栏与查询如何一步步构建。
Read Lesson 22 on the repository layer; this lesson covers filtering, the search bar, and how queries are built.

第 22 课的执行器负责「把查询发出去」,可那些查询的 WHERE 条件是谁拼的?这一课就讲过滤。关键洞察是:用户过滤的方式五花八门——点侧栏面板、敲搜索栏语法、甚至用 AI 自然语言描述—— 但它们最终都汇成同一个 FilterState(一组带类型的条件),再由它编译成参数化 SQL(ClickHouse 或 Postgres)。一个中间契约, 既挡住了 SQL 注入,又让搜索栏、AI filter 这些花样都构造即安全。

🌐 生活类比
把 FilterState 想成联合国的中间语。与会者说着不同的母语——有人点菜单(侧栏面板)、有人写电报(搜索栏 key:value 语法)、有人口述需求(AI 自然语言)—— 但所有发言都先被译成同一种标准中间语(FilterState),再由它译成数据库听得懂的话(ClickHouse SQL 或 Postgres SQL)。这个译员有两条铁律: 一是绝不把原话直接塞进译文(用占位符传值,杜绝注入);二是听不懂的、编不出的,当场打回,绝不胡乱转述(校验 + 往返丢弃幻觉)。所有输入收敛到一种中间表示,再分发到各种后端——这就是过滤系统的骨架。

一个 FilterState,编译到两套 SQL

FilterState 是一组带类型的条件:每条说清「哪一列、什么运算符、什么值」(如 {column:"level", operator:"any of", value:["ERROR"]})。 它要变成 SQL,得过一个工厂 createFilterFromFilterState——这一步既翻译、又把关:

三种输入 → 一个 FilterState → 两套 SQL 侧栏面板 搜索栏语法 AI 自然语言 FilterState一组带类型的条件列·运算符·值 工厂:翻译 + 把关① 校验列是否在 schema② 校验类型是否兼容③ 注入强制 project_idcreateFilterFromFilterState ClickHouse SQL参数化 · 看板/列表 Postgres SQL参数化 · 评估/审计 同一份 FilterState + 列定义,可编译到 ClickHouse 或 Postgres——两套后端共享一个抽象 ClickHouse 栈:clickhouse-filter.ts(StringFilter/DateTimeFilter…)+ factory.tsPostgres 栈:filterToPrisma.ts → Prisma.Sql(评估、审计等 Prisma 表)
一个抽象,两套后端:FilterState + 列定义经工厂 createFilterFromFilterState 校验列/类型、注入强制 project_id,再编译成参数化 SQL。ClickHouse 栈在 clickhouse-sql/,Postgres 栈在 filterToPrisma.ts。源码:queries/clickhouse-sql/factory.ts:37,217。
示例:搜索框输入 → FilterState 数组 name = "answer" AND userId = "u_42" AND total_cost > 0.003🔍 parse FilterState = [ { column:"name", operator:"=", value:"answer", type:"string" }, { column:"userId", operator:"=", value:"u_42", type:"string" }, { column:"total_cost",operator:">", value:0.003, type:"number" } ] → 编译成 SQL:WHERE name = ? AND userId = ? AND total_cost > ? 每个 {column,operator,value,type} 是一条结构化过滤,可校验、可下推
把自由文本变成结构化过滤(结构对齐 packages/shared/src/interfaces/filters.ts;值为示例):搜索框的一行输入被解析成一个 FilterState 数组,每项是 {{column, operator, value, type}}。结构化之后既能校验(类型/算子合法),又能安全地编译成参数化 SQL 下推到 ClickHouse——这也是搜索栏成为「所有可过滤视图的统一入口」的基础。
packages/shared/src/server/queries/clickhouse-sql/{factory,clickhouse-filter}.ts编译 + 把关
// 工厂:逐个把关再翻译
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 课资源保护之外的另一道防线。

FilterState 一条条件 column: level operator: any of value: [ERROR, WARNING] apply() 编译 + 把关 SQL 片段(只留占位符) level IN {pXY9z: Array(String)} params(用户值绑这里) { pXY9z: [ERROR, WARNING] } 用户值只进 params(随机命名占位符),绝不拼进 SQL 字符串 哪怕值写成 '; DROP TABLE…,也只当普通字符串匹配 → 注入无从下手

😖 各输入直连各后端:N×M

3 种输入 × 2 套后端 = 6 套翻译逻辑、6 处要各自防注入。新加一种输入(比如 AI),就得为每个后端重写对接、重写安全校验——组合爆炸,且总有一处会写漏。

😀 收敛到 FilterState:N+M

每个输入只管「译成 FilterState」,每个后端只管「从 FilterState 译出 SQL」。校验与参数化只在中间做一次。新加输入只需 +1 个译入器,白嫖所有后端与全部安全。

搜索栏与 AI filter:同一个真源的两种皮肤

侧栏面板之外,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 的解法堪称精巧——把模型输出往返一遍:

AI filter:往返校验,幻觉列进不来 自然语言「上周超 2s 的报错」 大模型生成候选过滤(可能含幻觉列) 往返:转回搜索栏语法filterStateToQueryText 能还原 → 保留应用到 FilterState 还原不了 → 丢弃droppedCount++ 只有「能还原成合法搜索栏语法」的过滤才被采纳——幻觉/不存在的列天然进不来 「构造即合法」:安全不靠事后检查,而靠「编不出就过不来」的结构
往返即护栏:模型输出被 filterStateToQueryText 往返一遍,只有能还原成合法搜索栏语法(即能降解成 FilterState 能表达的过滤)的才保留,幻觉列直接 droppedCount++ 丢弃。源码:web/src/features/search-bar/server/router.ts:45,178-183。
1

自然语言进来

用户在搜索栏旁说「上周延迟超 2 秒的报错」;generateFilter(受保护过程,企业版)接住。

2

喂给大模型

用 v4 字段注册表拼出提示词,调 Bedrock 生成候选过滤——此时可能夹带不存在的列。

3

往返一遍

把候选过滤通过 filterStateToQueryText 转回搜索栏语法,再尝试解析回 FilterState。

4

留真去假

能干净往返的保留、应用;还原不了的(幻觉/非法列)丢弃并计入 droppedCount。

5

落到同一个真源

最终结果写进侧栏那份 FilterState——和你手点、手敲的过滤完全同源同路。

🎯 设计取舍
为什么不让搜索栏、AI 各自直接生成 SQL,非要都先收敛成 FilterState? 因为「输入面」和「后端」都不止一个。输入有侧栏、搜索栏、AI、未来还会更多; 后端有 ClickHouse、Postgres。如果让每个输入面各自直连每个后端,就是 N×M 套翻译逻辑、N×M 处注入风险——而且新加一种输入,就要把所有后端的对接、所有安全校验重写一遍。 收敛成一个 FilterState 中间契约后,事情变成 N+M:每个输入面只管「译成 FilterState」,每个后端只管「从 FilterState 译出 SQL」,校验与参数化只在中间做一次。 更深的一层是「构造即合法」:因为 AI 的输出必须能还原成 FilterState 能表达的形态才被采纳,幻觉列从结构上就不可能通过——安全不再依赖「记得加一道检查」,而是由表示本身的边界来保证。 这是「单一真源 + 中间表示」最优雅的一面。
🎯 本课要点
  • 用户过滤的多种入口(侧栏 / 搜索栏 / AI)都汇成一个 FilterState(带类型的条件组),再编译成 SQL。
  • 一个抽象、两套后端:同一份 FilterState 经工厂可编译到 ClickHouse(clickhouse-sql/)或 Postgres(filterToPrisma.ts)。
  • 注入安全:每个过滤器 apply() 用随机命名的占位符传值,绝不拼接字符串;工厂还校验列存在性、类型兼容,并注入强制 project_id(第 10 课)。
  • 搜索栏是 FilterState 的「受控编辑器」(README:侧栏 FilterState 是唯一真源);语法只覆盖 FilterState 能表达的范围,编不出的阻止提交、不静默丢弃。
  • AI filter把模型输出往返 filterStateToQueryText,只留能还原成合法语法的——幻觉列构造上进不来。安全靠结构,不靠事后检查。

🧪 自测 · 想一想为什么这么设计

1. 用户的过滤来自侧栏、搜索栏、AI 三种入口,后端又有 ClickHouse 和 Postgres 两套。Langfuse 让它们都先汇成一个 FilterState 再编译成 SQL,最大的好处是?
  1. 可以不用 WHERE 条件
  2. 让前端不用写代码
  3. 让查询变快
  4. 把 N×M 的直连组合降成 N+M:每个输入只管译成 FilterState、每个后端只管从 FilterState 译出 SQL;校验与参数化只在中间做一次,新增输入白嫖所有后端与全部安全
看答案与解析 点击展开
答案:D。若每个输入直连每个后端,是 N×M 套翻译 + N×M 处注入风险,新增输入要为每个后端重写。收敛到一个 FilterState 中间契约后变 N+M:输入只译入、后端只译出,校验/参数化集中一次。这是「单一中间表示」的核心收益。
2. FilterState 编译成 ClickHouse SQL 时,每个过滤器的 apply() 用随机命名的占位符(如 stringFilter_xY9z)传值,而不是把值拼进 SQL 字符串。这防住了什么?
  1. 防止用户看到数据
  2. 防止查询太慢
  3. SQL 注入:用户输入的值永远是被绑定的参数、不进 SQL 文本,哪怕写 '; DROP TABLE… 也只当普通字符串匹配;加上工厂校验列存在/类型兼容,脏输入编译期就被挡下
  4. 防止结果太多
看答案与解析 点击展开
答案:C。参数化查询是防注入的根本:值绑定到占位符、由驱动安全代入,绝不与 SQL 文本拼接。随机参数名进一步避免命名冲突。工厂还前置校验列是否在 schema、类型是否兼容,并注入强制 project_id(第 10 课)——多道防线叠加。
3. AI filter 用大模型从自然语言生成过滤,可大模型可能编造不存在的列。Langfuse 怎么保证幻觉列绝不被应用?
  1. 把模型输出往返一遍:用 filterStateToQueryText 转回搜索栏语法、再解析回 FilterState,只保留能干净往返的;还原不了的(幻觉/非法列)直接丢弃。能表达才能进——构造即合法
  2. 人工逐条审核模型输出
  3. 信任模型,直接应用
  4. 让模型自己检查
看答案与解析 点击展开
答案:A。generateFilter 调 Bedrock 生成候选,再通过 filterStateToQueryText 往返:只有能还原成合法搜索栏语法(即能降解成 FilterState 能表达的过滤)的才被采纳,其余 droppedCount++ 丢弃。因为输出必须能被 FilterState 表达,幻觉列从结构上就进不来——安全靠表示边界而非事后检查。
💭 发散思考(没有标准答案,动手或动脑想想)
  • 「让 AI 的输出必须能还原成一个受限中间表示,不能表达的就进不来」——这种『构造即合法』的护栏,比『生成后再用规则检查』强在哪?你能想到把它用到自己系统里哪个『让 LLM 生成结构化指令』的场景吗?

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.

🌐 Analogy
Think of 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.

One FilterState, compiled to two SQL backends

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:

Three inputs → one FilterState → two SQL backends sidebar facets search-bar grammar AI natural language FilterStatea set of typed conditionscolumn·operator·value factory: translate + gatekeep① verify column in schema② verify type compatible③ inject mandatory project_idcreateFilterFromFilterState ClickHouse SQLparameterized · dashboards/lists Postgres SQLparameterized · evals/audit One FilterState + column defs compiles to ClickHouse or Postgres — two backends, one abstraction ClickHouse stack: clickhouse-filter.ts (StringFilter/DateTimeFilter…) + factory.tsPostgres stack: filterToPrisma.ts → Prisma.Sql (Prisma tables: evals, audit…)
One abstraction, two backends: 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.
Example: search-bar input → FilterState array name = "answer" AND userId = "u_42" AND total_cost > 0.003🔍 parse FilterState = [ { column:"name", operator:"=", value:"answer", type:"string" }, { column:"userId", operator:"=", value:"u_42", type:"string" }, { column:"total_cost",operator:">", value:0.003, type:"number" } ] → compiled to SQL: WHERE name = ? AND userId = ? AND total_cost > ? each {column,operator,value,type} is a structured filter — validatable and pushdown-able
Turning free text into structured filters (shape per 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.
packages/shared/src/server/queries/clickhouse-sql/{factory,clickhouse-filter}.tscompile + gatekeep
// 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.

one FilterState condition column: level operator: any of value: [ERROR, WARNING] apply() compile + guard SQL fragment (placeholder only) level IN {pXY9z: Array(String)} params (user value bound here) { pXY9z: [ERROR, WARNING] } the user value goes only into params (a random placeholder), never into the SQL string even a value like '; DROP TABLE… is matched as plain text → injection has no foothold

😖 each input to each backend: N×M

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.

😀 converge to FilterState: N+M

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.

The search bar & AI filter: two skins of one source of truth

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 syntaxmeaning
level:(ERROR OR WARNING)any-of
-env:devexclude (none-of)
latency:>2 · startTime:>2026-06-01numeric/time comparison
statusMessage:*chat*text contains (* glob)
metadata.region:eu · scores.accuracy:>0.8nested / 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:

AI filter: round-trip validation, hallucinated columns can't enter natural language"errors over 2s last week" LLM generatescandidates (maybe hallucinated) round-trip: back to grammarfilterStateToQueryText restores → keepapply to FilterState can't → dropdroppedCount++ only filters that "restore to valid grammar" are accepted — hallucinated/unknown columns can't get in "valid by construction": safety not from after-checks but from "can't express → can't pass"
The round-trip is the guardrail: the model output is round-tripped through 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.
1

natural language in

The user says, next to the bar, "errors over 2s latency last week"; generateFilter (protected procedure, enterprise) catches it.

2

feed the LLM

Build a prompt from the v4 field registry, call Bedrock to generate candidate filters — possibly smuggling in nonexistent columns.

3

round-trip

Turn candidates back to search-bar grammar via filterStateToQueryText, then try to parse back to FilterState.

4

keep real, drop fake

Cleanly round-tripping ones are kept and applied; un-restorable ones (hallucinated/illegal columns) are dropped and counted in droppedCount.

5

land in the same source

The result is written into the sidebar's FilterState — exactly the same source and path as your clicked and typed filters.

🎯 Design trade-off
Why not let the search bar and AI each generate SQL directly, instead of all converging to FilterState first? Because there are multiple "input surfaces" AND multiple "backends". Inputs: sidebar, search bar, AI, more to come; backends: ClickHouse, Postgres. Wire each input straight to each backend and it's N×M translation logics, N×M injection risks — and adding one input means rewriting every backend's wiring and every safety check. Converge to one 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".
🎯 Key points
  • The many filtering entries (sidebar / search bar / AI) all converge to one FilterState (a set of typed conditions), then compile to SQL.
  • One abstraction, two backends: the same FilterState compiles via the factory to ClickHouse (clickhouse-sql/) or Postgres (filterToPrisma.ts).
  • Injection safety: each filter's 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).
  • The search bar is FilterState's "controlled editor" (README: the sidebar FilterState is the single source of truth); its grammar covers only what FilterState can express, the rest blocking commit, not silently dropped.
  • AI filter round-trips the model output through filterStateToQueryText, keeping only what restores to valid grammar — hallucinated columns can't enter by construction. Security by structure, not after-checks.

🧪 Self-test - think about the design

1. Filters come from three entries (sidebar, search bar, AI), and there are two backends (ClickHouse, Postgres). Langfuse converges them into one FilterState before compiling to SQL. The biggest benefit?
  1. it removes the need for WHERE clauses
  2. the frontend needs no code
  3. it makes queries faster
  4. it cuts the N×M direct-wiring combinatorics to N+M: each input only translates to FilterState, each backend only translates FilterState to SQL; validation and parameterization happen once in the middle, and a new input freeloads all backends and all the safety
Show answer & explanation click to expand
Answer: D. Wiring each input to each backend is N×M translations + N×M injection risks, and a new input means rewriting for every backend. Converging to one FilterState contract makes it N+M: inputs only translate in, backends only translate out, validation/parameterization centralized once. The core gain of a single intermediate representation.
2. When FilterState compiles to ClickHouse SQL, each filter's apply() passes values via randomly-named placeholders (e.g. stringFilter_xY9z) rather than splicing values into the SQL string. What does this prevent?
  1. prevents users from seeing data
  2. prevents slow queries
  3. SQL injection: user values are always bound parameters, never in the SQL text, so even '; DROP TABLE… is matched as a plain string; plus the factory's column-existence/type checks stop dirty input at compile time
  4. prevents too many results
Show answer & explanation click to expand
Answer: C. Parameterized queries are the root of injection defense: values bind to placeholders and are safely substituted by the driver, never spliced into SQL text. Random param names avoid collisions. The factory also pre-checks column existence, type compatibility, and injects the mandatory project_id (L10) — layered defenses.
3. The AI filter uses an LLM to generate filters from natural language, but the model may hallucinate nonexistent columns. How does Langfuse ensure hallucinated columns are never applied?
  1. it round-trips the model output: convert back to search-bar grammar via filterStateToQueryText and re-parse to FilterState, keeping only what cleanly round-trips; un-restorable ones (hallucinated/illegal columns) are dropped. Only the expressible passes — valid by construction
  2. a human reviews each model output
  3. trusts the model and applies directly
  4. asks the model to check itself
Show answer & explanation click to expand
Answer: A. generateFilter calls Bedrock for candidates, then round-trips via filterStateToQueryText: only filters that restore to valid search-bar grammar (i.e. lower to what FilterState expresses) are accepted, the rest droppedCount++. Because the output must be expressible by FilterState, hallucinated columns can't enter structurally — safety from the representation's boundaries, not after-checks.
💭 Open questions (no single right answer - just think or try)
  • 'Make the AI output have to restore to a constrained intermediate representation, and the inexpressible can't enter' — how is this 'valid by construction' guardrail stronger than 'generate then check with rules'? Can you think of a 'let an LLM generate structured commands' scenario in your own systems where you'd apply it?