open-knowledge-format源码解读②:BigQuerySource如何把数据集变成概念清单,分片表家族归组技巧

原创2026-10-19 19:28:381,609 阅读

open-knowledge-format源码解读②:BigQuerySource如何把数据集变成概念清单,分片表家族归组技巧

open-knowledge-format 是一个用「纯 Markdown + YAML frontmatter」表示数据目录知识的开放格式(OKF),其 reference_agent 能把 BigQuery 数据集自动变成一份份可读的概念文档。本文带你源码级解读 BigQuerySource:它如何把一整个数据集变成「概念清单」(concept list),又靠一条正则表达式,把成百上千张分片表(sharded tables)神奇地归组成一个「表家族」概念。

一、先认识主角:BigQuerySource 在架构中的位置

reference agent 采用「生产者-消费者」双端设计:reference agent 是 OKF 的生产者,可视化器(viz.html)是消费者。生产环节里,Source 抽象层负责「从数据源拉取概念」,目前唯一的具体实现就是 BigQuery:

角色 位置 职责
接口 Source 定义 list_concepts / read_concept / sample_rows 三个能力
实现 BigQuerySource 把 BigQuery dataset 翻译成概念清单
消费 enrich_all 遍历概念清单,逐个交给 LLM 生成 OKF 文档

ConceptRef 是整条流水线里流转的「概念身份证」,一个 frozen dataclass 只有 4 个字段:

  • id:路径元组,如 ("tables", "events_"),将来直接决定文档落盘路径
  • type:OKF 类型,如 BigQuery Table、BigQuery Dataset
  • resource:底层资产的规范 URI
  • hint:来源相关的附加信息(通配符标记、分片数量等)

定义见 ConceptRef。

二、dataset 怎么拆成「1 + N」个概念

调用 list_concepts() 时,BigQuerySource 做三件事:

  1. 第 1 个概念固定是数据集本身:id 为 ("datasets", <dataset_id>),resource 指向 BigQuery REST API 的数据集端点;
  2. 遍历 dataset 里的全部表,用正则把表名分成「分片表」和「普通表」两类(下一节细说);
  3. 普通表按字典序每张表一个概念,id 形如 ("tables", "users")。

关键代码就在 list_concepts 里,它带缓存:首次遍历后写入 _concepts_cache,后续调用零开销——这对后面 agent 反复调 list_concepts 织交叉链接很重要。

概念 id 到文件路径的映射规则极其简单,见 concept_id_to_path:元组 ("tables", "events_") 落盘就是 tables/events_.md。这就是「概念清单」最终变成 bundle 目录树的桥梁。

三、分片表家族归组技巧:一条正则的功劳

真实世界里,很多公共数据集用「表名后缀 = 日期」做水平分片。比如 GA4 样本集里有 events_20201101 到 events_20210131 共 92 张表——如果每张表一篇文档,bundle 会被撑爆,LLM 调用成本也会爆炸。

BigQuerySource 的解法是一条正则:

_SHARD_SUFFIX_RE = re.compile(r"^(?P<prefix>.+?_)(?P<shard>\d{6,8})$")

位于 bigquery.py 第 24 行。它的语义是:表名末尾是下划线 + 6~8 位数字,就认定是分片表,并捕获前面的 prefix 作为家族名。

归组结果一目了然:

表名 判定 归属概念 id
events_20210101 ~ events_20210131 分片表 ("tables", "events_") 一个家族
users 普通表 ("tables", "users") 独立概念
transactions_20240001 分片表(6~8 位数字都算) ("tables", "transactions_")

家族概念会携带一份信息量很大的 hint,见 L98-L115:

  • wildcard: True 与 family_prefix:告诉下游「这是个通配家族」
  • shard_count、first_shard、last_shard:分片数量与首尾边界

这些 hint 后来会被 LLM 直接写进文档正文——你在 bundles/ga4/tables/events_.md 里看到的「from events_20201101 through events_20210131」以及 events_* 的 resource,全都源自这里。

测试用例 test_wildcard_sharded_tables_collapse_to_one_concept 精确断言了这套行为:3 张 events_2021xxxx 表折叠成 1 个概念,shard_count == 3,且不会出现 events_20210101 这种独立概念。

四、read_concept:用「代表表」读全家族元数据

家族归组带来一个新问题:家族里有几十张表,read_concept 读哪张?答案是 代表表策略——

通配家族取最后一个分片(last_shard),普通表就是自己。

原因很朴素:分片表按日期排列,最后一张表的 schema 就是「当前最新结构」,描述最新最准。

拿到表之后,read_concept 会收集一整套结构化元数据:

  • 基础信息:friendly_name、description、labels、行数/字节数、创建与修改时间
  • schema:由 _schema_to_dict 递归展平,嵌套 RECORD 字段会带着 fields 子列表一路钻到底
  • 分区:time_partitioning(类型/字段/过期时间)与 range_partitioning
  • 聚簇字段 clustering_fields

对家族概念,返回值还会额外附上 family_prefix、shard_count、first_shard、last_shard 四件套,让 LLM 写文档时无需再查一次 API。

五、sample_rows:为什么视图要「绕道 SELECT」

采样数据是元数据稀疏时的兜底。这里藏着一个容易踩的坑(sample_rows):

  • TABLE:直接走 client.list_rows,便宜又快
  • VIEW / MATERIALIZED_VIEW / EXTERNAL / SNAPSHOT:BigQuery 的 tabledata.list REST 端点拒绝非基础表,于是退化为一条 SELECT * ... LIMIT n 查询把行物化出来

两条路径都包了 try/except,采样失败时返回 None 而不是抛错——元数据永远优先,样本只是锦上添花。这个「优雅降级」思路值得在任何数据接入层借鉴。

六、概念清单如何变成 Markdown bundle

概念清单只是中间产物,真正的消费者是 agent 工具层与 runner:

  1. 工具层:list_concepts / read_concept_raw / sample_rows 把 Source 能力包装成 LLM 可调用的函数;
  2. 编排层:enrich_all 遍历每个 ConceptRef,为每个概念开一个独立会话,让 LLM 按 工作流指令 先读已有文档、再读原始元数据、最后调 write_concept_doc 写出恰好一篇 OKF 文档;
  3. 收尾:跑完所有概念后统一 regenerate_indexes,给每层目录生成带描述的 index.md,实现 OKF 的「渐进式披露」。

想复现完整流程,可直接跑 GA4 样本配方:samples/ga4_merch_store/README.md,它指向 bigquery-public-data.ga4_obfuscated_sample_ecommerce 数据集,产物就是仓库里的 bundles/ga4/。

七、小结:这个设计的三个可借鉴点

技巧 一句话总结
概念即路径 id 元组天然映射为目录结构,概念清单与文件树一一对应,零转换成本
正则归组分片家族 一条正则 + hint 元数据,把 O(N) 张表压成 O(1) 个概念,LLM 成本立省
元数据分层读取 list 只做轻量枚举,read 才拉 schema,sample 尽力而为,失败静默降级

BigQuerySource 用不到 230 行代码,搭好了「数据源 → 概念清单 → OKF 文档」这条生产管线。理解了它,你就可以照着 Source 接口 为自己的数据源(Unity Catalog、Dataplex 等)写一个新的 Source 实现——只需继承抽象基类、实现 list_concepts 和 read_concept,整个 agent、bundle 工具链和可视化器都能原样复用。

登录后查看全文
open-knowledge-format