Default filters【免费下载链接】WrenAIGenBI (Generative BI) for AI agents, an open-source, governed text-to-SQL through an open context layer that turns natural-language questions into trusted dashboards, charts, and SQL across 20 data sources, such as BigQuery, Snowflake, PostgreSQL, ClickHouse, Amazon Redshift, Databricks and more.项目地址: https://gitcode.com/GitHub_Trending/wr/WrenAIordersqueries exclude rows wheredeleted_at IS NOT NULLunless the user asks about deletions.usersqueries default tois_active true AND is_internal false.- **为什么重要** 软删除对 schema 完全不可见不写规则Agent 就会产出SQL 正确、行集错误的结果——这是最隐蔽的一类 bug。 **解析** 这是典型的隐性约定。几乎所有 SaaS 数据库都用软删除但没有任何 schema 元数据能表达默认要过滤掉已删除行。写入 ## Default filters 小节后[wren context instructions](https://link.gitcode.com/i/d8ce0e02a8dbbcb2baa5603ad0a4fe11) 命令会在读取业务规则时自动将其注入到 LLM 的上下文。 ### 5. 魔法哨兵值Magic sentinels - **触发条件** 数值列且探测 / raw 显示去重值中包含远离主体的离群值本应全正的列中出现 -1、0或出现 9999、99999999且 description 不含 [magic]。 - **raw 关键词扫描** unknown、all、any、n/a、default、sentinel、-1 means、999 means。 - **Sink** 列 properties.description。 - **Tag** [magic] -1 unknown; 0 system user / [magic] 9999 lifetime / no expiry。 - **为什么重要** 平均值和求和会被当成真实值的哨兵值静默污染。 **解析** 工程上常用特殊数值表达业务状态-1 表示未知、9999 表示终身/无过期。若 Agent 不知道这一点AVG(amount) 会把 -1 当作真实负数参与计算。Step 4.5 的探测正是为此设计了 min/max 补充查询SELECT MIN(col) AS lo, MAX(col) AS hi FROM model一次就能暴露这类离群哨兵。 ### 6. 同义词 / 业务别名Synonyms / business aliases - **触发条件** raw 使用某个业务术语其能映射到某个 model / column / metric但该术语在 MDL 的名称或描述中没有逐字出现。 - 示例customer → customers而非 accounts、customers_v3ARR → mrr * 12DAU → 每日去重活跃用户数。 - **Sink** knowledge/rules/ 下的 ## Naming conventions 小节。 - **写入格式** markdown ## Naming conventions - ARR in business docs subscriptions.mrr * 12. Do not use the revenue table. - customer the customers model (not customers_v3, thats the legacy raw mirror). - active user a user with at least one event in the past 28 days, not users.is_active.为什么重要记忆检索memory retrieval按术语匹配用户说业务语言schema 说技术语言两者之间的鸿沟需要显式桥梁。解析这一类别揭示了 enrich 的核心价值它把业务词典写进规则库。注意第三个示例的微妙之处——active user的业务定义28 天内至少有一次事件与users.is_active列的技术定义不同这种差异若不写明Agent 会默认二者等价。7. 日期 / 时间约定Date / time conventions触发条件column.type ∈ {DATE, TIMESTAMP, TIMESTAMP_TZ, TIMESTAMPTZ}且 description 不含[time]且满足任一时区TZ歧义、事件时间 vs 记录时间歧义、时间粒度歧义。名称提示*_at、*_time、*_date、created_*、updated_*、as_of_*、effective_*。raw 关键词扫描UTC、timezone、event time、as of、snapshot、month-end、fiscal、rolling。Sink列properties.description。Tag[time] UTC; event time (not insert time); month-end snapshot for billing rows。为什么重要跨时区聚合、财年 vs 自然年分桶、as-of 快照会产生干跑dry-run都通过但分桶错误的数字。解析时间列是三类歧义的温床时区歧义存的是 UTC 还是本地时间、事件时间 vs 记录时间歧义created_at是事件发生时刻还是入库时刻、粒度歧义天级、月级还是月末快照。这些歧义在dry-run阶段完全不可见——SQL 能编译、能执行、结果看起来对只有对账时才发现分桶错了。8. 跨系统标识符Cross-system identifiers触发条件列名包含外部系统标签stripe_*、salesforce_*、intercom_*、hubspot_*、*_external_id、*_external_ref或 raw 将内部 ID 映射到外部系统。Sinkknowledge/rules/下的## External identifiers小节。写入格式## External identifiers - users.stripe_customer_id maps to a Stripe Customer object. NULL not yet billed. - orders.external_ref is the source-system order ID; format varies by orders.source (shopify 13-digit numeric, manual free-form string).为什么重要Agent 对外部系统没有 schema它需要显式的映射关系以及格式 / NULL 语义说明。解析外部 ID 列的核心问题有三层映射到哪个外部对象、NULL 的业务含义、值的格式约束。只写这是 Stripe ID不够还要写NULL 表示尚未开票和shopify 来源是 13 位数字、manual 来源是自由文本Agent 才能正确处理 join 和校验。9. 货币 / 区域Currency / locale触发条件任一 model 含有currency、locale、country、region、fx_rate、original_amount列或 raw 提到 FX 汇率、多币种、非美元报表。Sinkknowledge/rules/下的## Currency小节。写入格式## Currency - All amounts in orders.amount are USD-converted at order-time FX (see orders.fx_rate). Use orders.original_amount orders.currency for source-currency analysis. - Display monetary values with 2 decimals and thousand separators.为什么重要没有规则时Agent 会不加换算地直接求和混合币种的行。解析多币种是聚合查询的高危区。这一类别明确了两件事存储口径orders.amount是下单时按汇率折算的 USD和展示口径两位小数、千分位分隔符。两者都属于 schema 无法表达、必须由规则注入 LLM 上下文的语义。10. 规范表偏好Canonical table preferences触发条件schema 中存在相似表users/users_v3、orders/orders_archive/orders_summary或 raw 中出现 use X not Y、deprecated、raw mirror。Sinkknowledge/rules/下的## Canonical tables小节。写入格式## Canonical tables - Use customers for analytics. customers_v3 is the legacy raw mirror — do not query. - For order date ranges 90 days, use orders_summary. orders is row-level only and slow on large windows.为什么重要没有显式规则时Agent 会按词汇接近度选表然后默默选错。解析数据仓库中长得像的表比比皆是生产表、历史归档、预聚合汇总、旧版原始镜像。它们列名相近、含义迥异。若规则库只字不提Agent 依据schema describe的词法相似度选表几乎必然踩坑——而且这种错误同样静默。再富集审计Re-enrichment audit在追加新内容之前先确认此前的 enrich 运行已经覆盖了什么# 列级 tag 检查 grep -rE \[(enum|unit|null|magic|time|pii)\] models/ # knowledge/rules/ 中由 enrich 写入的小节标题检查 grep -rE ^## (Default filters|Naming conventions|External identifiers|Currency|Canonical tables) knowledge/rules/【免费下载链接】WrenAIGenBI (Generative BI) for AI agents, an open-source, governed text-to-SQL through an open context layer that turns natural-language questions into trusted dashboards, charts, and SQL across 20 data sources, such as BigQuery, Snowflake, PostgreSQL, ClickHouse, Amazon Redshift, Databricks and more.项目地址: https://gitcode.com/GitHub_Trending/wr/WrenAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考