数据目录AI Agent人工智能知识管理示例工程【免费下载链接】knowledge-catalogGoogle Cloud Knowledge Catalog Tools and Samples项目地址https://gitcode.com/gh_mirrors/kn/knowledge-catalog点击查看免费下载本文围绕 Google Analytics 4GA4的Purchasers购买者受众指标讲解如何用 BigQuery 的通配符分片查询统计完成过购买的用户并剖析该指标在 knowledge-catalog 仓库中作为 OKFOpen Knowledge FormatReference 文档的完整形态——从 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 中该指标的元数据为字段值说明typeReferenceOKF 概念类型标识这是一个引用/参考型文档resourceAnalytics Help 的 sample queries 页面 URI底层事实来源的 URItitlePurchasers Audience Metric人类可读的显示名称descriptionComputes the count or list of users who have completed a purchase or in-app purchase一句话摘要会被自动生成索引直接引用tagsmetric、audience、ga4、purchasers便于检索与编目的标签generatedby: reference_agent/gemini-3.5-flash文档由 reference_agent 工具生成sourcesid: sample_queries出处与脚注标识其中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_.mdevents_表族是一系列按天分片的导出表如events_20201101至events_20210131每一行代表用户与线上店面交互触发的一次事件page_view、scroll、session_start、view_item、purchase等。该表对 Purchasers 查询最关键的字段包括字段类型用途user_idSTRING登录用户的唯一标识Purchasers 查询的计数主体user_pseudo_idSTRING匿名设备标识GA client ID未登录用户也可用event_nameSTRING事件名用于IN (in_app_purchase, purchase)过滤event_timestampINTEGER事件发生的 POSIX 时间戳微秒用于时间窗口过滤event_value_in_usdFLOAT事件的货币价值USD可扩展出收入口径ecommerce.transaction_idSTRING交易标识可用于防重复统计itemsRECORD (REPEATED)商品级重复记录需UNNEST才能展开需要注意的是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_*表、以事件判定 时间窗口为骨架指标文档受众定义purchasers.md记录过in_app_purchase或purchase的用户n_day_active_users.md最近 N 天内有engagement_time_msec 0事件的用户n_day_inactive_users.md最近 M 天活跃但最近 N 天未活跃的用户M Nfrequently_active_users.md最近 M 天中至少 N 天活跃的用户highly_active_users.md最近 M 天内活跃时长超过 N 分钟的用户acquired_users.md通过指定 Source/Medium/Campaign 获取的用户google_acquired_cohorts.md特定时间窗获客、且来自 Google 广告来源的同期群用户这些文档采用完全一致的 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.mdFrontmatter信号层type必需、title、description、resource、tags、generated、sources。其中sources记录出处id用于正文脚注锚定、resource是来源 URI、title是人类可读标题出处信息统一放在 frontmatter 而非正文的# Citations节——这是 OKF v0.2 的明确约定§5.1。正文结构固定顺序一段简明的概念散文描述定义 典型用法# Schema小节——由于该指标是查询模式而非实体表此处明确声明不映射到单一数据库 schema# Common query patterns小节——13 段sql围栏包裹的可运行示例 SQL正文末尾用[^sample_queries]脚注锚定出处与 frontmatter 的sources[].id对应。解析与校验该结构的底层实现位于 bundle/document.pyOKFDocument.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 demotoolbox/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_typeresource映射为条目资源名sources等信号字段作为可检索的类型化字段存入。3. 拉取pullpull.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_iduser_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_infoanalytics_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人工智能知识管理示例工程【免费下载链接】knowledge-catalogGoogle Cloud Knowledge Catalog Tools and Samples项目地址https://gitcode.com/gh_mirrors/kn/knowledge-catalog点击查看免费下载相关推荐QuickBot 前端工程实战基于 Imagen3 文生图应用的 Angular 开发、构建与代码规范QuickBot 前端工程实战基于 Imagen3 文生图应用的 Angular 开发、构建与代码规范 本文以 QuickBot 系列模板中的 text to数据目录AI Agent人工智能知识管理示例工程OpenProject 前端开发风格指南实践声明式、不可变与单向数据流、组件架构OpenProject 前端开发风格指南实践声明式、不可变与单向数据流、组件架构 本篇技术文章基于 OpenProject 仓库中的前端开发风格指南 doc数据目录AI Agent人工智能知识管理示例工程3个必知技巧掌握Rescuezilla的终极系统恢复指南3个必知技巧掌握Rescuezilla的终极系统恢复指南 你是否曾经因为系统崩溃而丢失了所有重要文件或者因为硬盘故障而面临数据灾难想象一下你正在准备一个数据目录AI Agent人工智能知识管理示例工程上一篇brpc 错误码与错误处理全解析Controller::SetFailed、berror 与自定义错误码实战指南下一篇KernelSU App Profile 完全指南基于最小特权原则精细化管控 root 权限创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
