open-knowledge-format源码解读②:BigQuerySource如何把数据集变成概念清单,分片表家族归组技巧
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 Datasetresource:底层资产的规范 URIhint:来源相关的附加信息(通配符标记、分片数量等)
定义见 ConceptRef。
二、dataset 怎么拆成「1 + N」个概念
调用 list_concepts() 时,BigQuerySource 做三件事:
- 第 1 个概念固定是数据集本身:id 为
("datasets", <dataset_id>),resource 指向 BigQuery REST API 的数据集端点; - 遍历 dataset 里的全部表,用正则把表名分成「分片表」和「普通表」两类(下一节细说);
- 普通表按字典序每张表一个概念,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.listREST 端点拒绝非基础表,于是退化为一条SELECT * ... LIMIT n查询把行物化出来
两条路径都包了 try/except,采样失败时返回 None 而不是抛错——元数据永远优先,样本只是锦上添花。这个「优雅降级」思路值得在任何数据接入层借鉴。
六、概念清单如何变成 Markdown bundle
概念清单只是中间产物,真正的消费者是 agent 工具层与 runner:
- 工具层:list_concepts / read_concept_raw / sample_rows 把 Source 能力包装成 LLM 可调用的函数;
- 编排层:enrich_all 遍历每个 ConceptRef,为每个概念开一个独立会话,让 LLM 按 工作流指令 先读已有文档、再读原始元数据、最后调
write_concept_doc写出恰好一篇 OKF 文档; - 收尾:跑完所有概念后统一 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 工具链和可视化器都能原样复用。