企业官网建设流程全解析

• 数据目录
• AI Agent
• 人工智能
• 知识管理
• 示例工程

本文围绕 Google Analytics 4（GA4）的Purchasers（购买者）受众指标，讲解如何用 BigQuery 的通配符分片查询统计"完成过购买的用户"，并剖析该指标在 knowledge-catalog 仓库中作为 OKF（Open Knowledge Format）Reference 文档的完整形态——从 SQL 查询模式、底层events_*表结构，到文档如何由 reference_agent 生成、经 push/pull 流程在 Knowledge Catalog 与本地 bundle 之间无损往返。读完本文，你将掌握购买受众查询的写法与参数含义，也能复用它构建活跃度、获客等其他同族受众指标。

一、指标定义：什么是 Purchasers 受众

Purchasers 指标的核心定义简洁而明确：统计"已经完成购买的用户"的受众群体，即用户只要记录过in_app_purchase（应用内购买）或purchase（购买）事件，就被归入购买者受众。该定义记录在 purchasers.md 文档的正文开篇：

Computes the audience of purchasers, defined as users who have logged eitherin_app_purchaseorpurchase.

这一双事件判定有实际意义：purchase覆盖 Web 端网页购买，in_app_purchase覆盖移动端 App 内购买，二者共同构成跨平台的完整购买行为集合。对于同时运营 Web 商城与移动 App 的业务（如该仓库所模拟的 Google Merchandise Store），只统计单一事件类型会漏掉另一半转化路径。

在文档的 frontmatter 中，该指标的元数据为：

其中description会被 bundle/index.py 中的_build_index_text自动抽取，拼进 metrics/index.md 的条目列表，成为索引中"Computes the count or list of users who have completed a purchase or in-app purchase"这一行描述的来源。

二、核心查询模式：购买用户计数的标准 SQL

文档的# Common query patterns小节给出了一段可直接运行的参考查询（purchasers.md 中# Common query patterns一节）：

/** * Computes the audience of purchasers. * * Purchasers = users who have logged either in_app_purchase or * purchase. */ SELECT COUNT(DISTINCT user_id) AS purchasers_count FROM `YOUR_TABLE.events_*` WHERE event_name IN ('in_app_purchase', 'purchase') AND _TABLE_SUFFIX BETWEEN '20180501' AND '20240131';

这段 SQL 结构非常典型，是 GA4 受众类指标查询的"骨架模板"，逐句拆解如下：

• SELECT COUNT(DISTINCT user_id)：对购买事件去重计数。由于同一个用户可能多次购买（触发多条purchase事件），必须用DISTINCT才能得到"有多少个用户"而非"有多少次购买"。结果列别名purchasers_count直接表达指标语义。
• **FROM \YOUR_TABLE.events_`**：events_是通配符表名，YOUR_TABLE是占位符，需替换为实际的 BigQuery 数据集路径。GA4 的 BigQuery 导出按天分片（daily sharding），*` 通配符让一次查询横跨全部日期分片。
• WHERE event_name IN ('in_app_purchase', 'purchase')：这是指标定义的直接落点——只保留两种购买事件，其他事件（如page_view、session_start、scroll）全部过滤掉。
• AND _TABLE_SUFFIX BETWEEN '20180501' AND '20240131'：_TABLE_SUFFIX是 BigQuery 通配符查询的伪列，值为各分片表名后缀（即日期YYYYMMDD）。此条件把扫描范围限定在 2018-05-01 至 2024-01-31 之间，避免全量扫描，既控制成本又保证统计窗口正确。

该查询与同目录下其他受众指标文档（如 n_day_active_users.md）是同一套"事件名判定 + 时间窗口过滤"模式的变体，可对照学习。

三、数据基础：GA4 事件级分片表events_*

要正确使用上面的查询，需要理解底层数据表。Purchasers 指标并不映射到独立的数据表，而是作用于 GA4 的事件级导出表——文档中# Schema一节明确说明：

This reference describes a query pattern and does not map to a single database schema.

在本仓库的 OKF catalog 中，与该指标配套的数据资源有：

• 数据集 ga4_obfuscated_sample_ecommerce.md：脱敏的 GA4 电商示例数据集，模拟 Google Merchandise Store 的真实 Web 电商实现，覆盖 2020-11-01 至 2021-01-01 三个月的历史事件。
• 表 events_.md：events_表族是一系列按天分片的导出表（如events_20201101至events_20210131），每一行代表用户与线上店面交互触发的一次事件（page_view、scroll、session_start、view_item、purchase等）。

该表对 Purchasers 查询最关键的字段包括：

需要注意的是event_params是 REPEATED RECORD（数组）结构，提取具体参数必须UNNEST或用子查询（详见 events_.md 的# Common query patterns一节）。这与 n_day_active_users.md 中通过CROSS JOIN T.event_params读取engagement_time_msec参数的写法是同一类处理模式。

四、实战变体：从计数到用户列表与维度细分

文档给出的基础查询解决"有多少购买用户"，实际业务往往还需要以下变体，均可在该查询骨架上扩展：

1. 输出购买用户明细列表

把COUNT(DISTINCT user_id)换成DISTINCT user_id（或按用户聚合），即可得到受众成员名单，供再营销或用户分层使用：

SELECT DISTINCT user_id FROM `YOUR_TABLE.events_*` WHERE event_name IN ('in_app_purchase', 'purchase') AND _TABLE_SUFFIX BETWEEN '20180501' AND '20240131';

2. 用user_pseudo_id覆盖未登录用户

user_id仅在用户登录后才有值，未登录访客的购买会被漏掉。若想统计"设备级"购买受众，可改用user_pseudo_id（并常配合COUNT(DISTINCT ...)得到近似独立用户数）：

SELECT COUNT(DISTINCT user_pseudo_id) AS purchasers_count FROM `YOUR_TABLE.events_*` WHERE event_name IN ('in_app_purchase', 'purchase') AND _TABLE_SUFFIX BETWEEN '20180501' AND '20240131';

3. 加入相对时间窗口

原查询使用固定日期分片（_TABLE_SUFFIX BETWEEN ...），若要"近 N 天购买用户"，可叠加event_timestamp条件，模式与 n_day_active_users.md 相同：

AND event_timestamp > UNIX_MICROS(TIMESTAMP_SUB(CURRENT_TIMESTAMP, INTERVAL 30 DAY))

4. 扩展收入与细分维度

结合event_value_in_usd、ecommerce.transaction_id可计算购买金额；结合traffic_source、geo等嵌套字段可做渠道/地域维度的购买受众细分——这些字段的完整说明见 events_.md 的 Schema 表格。

五、同族受众指标：一套可复用的指标库

Purchasers 并非孤立的单条 SQL，它属于同一套 GA4 受众指标体系。目录 references/metrics/index.md 收录了 7 个同构指标，全部基于events_*表、以"事件判定 + 时间窗口"为骨架：

这些文档采用完全一致的 OKF 结构（frontmatter + 定义段 +# Schema+# Common query patterns），相互之间通过相对路径互链，构成了一个可由人类浏览、也可被 Agent 检索消费的指标知识库。注意，示例数据集的时间范围是 2020-11-01 至 2021-01-01（见 ga4_obfuscated_sample_ecommerce.md），在该数据集上实测时需将_TABLE_SUFFIX范围调整为'20201101'到'20210131'。

六、OKF Reference 文档结构：机器可读的指标契约

Purchasers 指标文档本身就是一个标准 OKF v0.2 文档，其结构完全遵循 reference_agent 的写作规范（见 reference_instruction.md）：

Frontmatter（信号层）：type（必需）、title、description、resource、tags、generated、sources。其中sources记录出处（id用于正文脚注锚定、resource是来源 URI、title是人类可读标题），出处信息统一放在 frontmatter 而非正文的# Citations节——这是 OKF v0.2 的明确约定（§5.1）。

正文结构（固定顺序）：

1. 一段简明的概念散文描述（定义 + 典型用法）；
2. # Schema小节——由于该指标是查询模式而非实体表，此处明确声明"不映射到单一数据库 schema"；
3. # Common query patterns小节——1～3 段```sql围栏包裹的可运行示例 SQL；
4. 正文末尾用[^sample_queries]脚注锚定出处，与 frontmatter 的sources[].id对应。

解析与校验该结构的底层实现位于 bundle/document.py：OKFDocument.parse负责解析---分隔的 YAML frontmatter 与正文，validate强制校验必需键type，其_Loader还特意移除了 YAML 1.1 的时间戳隐式解析器，避免generated.at这类时间戳在解析/序列化往返中被改写。可见"机器可读、可往返、可校验"是这套格式的核心设计目标。

七、文档生命周期：从生成到 Knowledge Catalog 的 push/pull 往返

这类 Reference 文档并非手写孤本，而是完整工具链的一环，其生命周期可以归纳为：

1. 生成：reference_agent 按 reference_instruction.md 的工作流执行——先read_existing_doc读取已有文档、再read_concept_raw获取元数据、list_concepts()枚举同 bundle 概念以织入互链、最后write_concept_doc一次性落盘。文档 frontmatter 中的generated: by: reference_agent/gemini-3.5-flash即此过程的署名。目录索引（如 metrics/index.md）由 bundle/index.py 的regenerate_indexes按概念类型分组自动重建，并从各文档的description生成条目摘要。

2. 发布（push）：在 OKF wiki demo（toolbox/mdcode/demo/README.md 的 OKF Wiki 一节）中，bun push.ts将 bundle 内的 markdown 文件推送到 Dataplex EntryGroup。由于通用 Documents Layout 只映射title/description/tags+ 正文，OKF 的信号层会被 okf.ts 的toStaging平移进自定义okfDataplex aspect（类型模板见 okf-aspect.json），文档的type记录为okf_type，resource映射为条目资源名，sources等信号字段作为可检索的类型化字段存入。

3. 拉取（pull）：pull.ts 先把kcmd pull的结果放进.staging/临时目录，再通过fromStaging把okfaspect 中的信号层还原回干净的 OKF frontmatter，写入./pulled/目录。GA4 示例 bundle 已处于规范形式，bun push.ts --bundle catalog后接bun pull.ts --bundle catalog可做到逐字节一致（diff -r无差异），验证了文档往返的无损性。默认 bundle 之外的第二个 bundle 就是本指标所在的okf/catalog/（GA4 示例），可通过--bundle catalog指定。

对于本文的 Purchasers 指标文档，你可以实际运行验证：cd toolbox/mdcode/demo/okf后执行bun push.ts --bundle catalog与bun pull.ts --bundle catalog，然后对比catalog/与pulled/目录，即可看到 purchasers.md 的完整往返过程。

八、实践要点与注意事项

结合源码与数据表结构，使用 Purchasers 指标时有几个关键点值得注意：

• user_idvsuser_pseudo_id：user_id仅在用户登录时填充（events_.md Schema 中标注 "when signed in"），跨设备归因需要登录态；匿名访客的购买只能用user_pseudo_id近似统计。实际口径应根据业务对"用户"的定义选择。
• 去重语义：COUNT(DISTINCT ...)统计的是独立用户而非购买次数；若要统计购买次数或 GMV，需改用COUNT(1)并对ecommerce.transaction_id去重，防止同一笔交易的多条事件重复计数。
• 日期边界与时间戳：_TABLE_SUFFIX基于分片日期（YYYYMMDD），与事件实际发生时间（event_timestamp，微秒级 POSIX 时间戳）存在时区差异，跨时区业务需注意口径一致。
• 分片范围与成本：通配符查询默认扫描全部匹配分片，务必用_TABLE_SUFFIX收紧范围；在示例数据集（2020-11-01 至 2021-01-01）上请相应调整日期边界。
• 隐私与同意：表结构含privacy_info（analytics_storage、ads_storage等同意状态字段），面向广告再营销的受众统计应结合同意状态过滤，符合隐私合规要求。
• 事件类型语义：purchase与in_app_purchase分别对应 Web 与 App 端，若业务只关心单一平台，可将IN (...)收窄为单个事件名。

结语

Purchasers 受众指标是 GA4 分析体系中最直接的"变现信号"之一，其文档化形态在 knowledge-catalog 仓库中示范了如何把一个简单的 SQL 查询模式，沉淀为带类型、带出处、带可校验结构的 OKF Reference 文档，并借助 reference_agent 生成与 push/pull 工具链在本地与 Knowledge Catalog 之间无损流转。无论你是想复用这段查询统计购买用户，还是参考它的文档结构建设自己的指标知识库，purchasers.md 连同同目录的 7 个受众指标文档，都是一套可直接上手、可对照源码验证的完整范本。

• 数据目录
• AI Agent
• 人工智能
• 知识管理
• 示例工程