Knowledge Catalog 高活跃用户（Highly Active Users）受众指标：GA4 事件数据上的 BigQuery 查询指南

数据目录AI Agent人工智能知识管理示例工程【免费下载链接】knowledge-catalogGoogle Cloud Knowledge Catalog Tools and Samples项目地址https://gitcode.com/gh_mirrors/kn/knowledge-catalog点击查看免费下载本文是 Google Cloud Knowledge Catalog 中 OKF 格式的 Reference 文档《Highly Active Users Metric》的深度解析与实战指南。该指标基于 Google Analytics 4GA4事件级 BigQuery 导出数据构建最近 M 天累计活跃时长超过 N 分钟的高活跃用户受众用于高价值用户分层、留存分析与再营销定向。读完本文你将理解engagement_time_msec事件参数的聚合语义掌握完整的可运行 SQL 模板并了解该 Reference 在仓库 OKF bundle 中的定位与验证方式。指标定义与业务场景在 metrics 索引 中Highly Active Users 被定义为Builds an audience of users active for more than N minutes in the last M days.即构建一个高活跃用户受众其成员是在最近 M 天内累计活跃/参与时长超过 N 分钟的用户且满足M N例如最近 10 天内累计活跃超过 0.1 分钟。它与同目录下其他活跃类指标形成互补指标定义判定维度N-Day Active Users最近 N 天至少记录一条engagement_time_msec 0事件天数 × 存在性Frequently Active Users最近 M 天中至少 N 天有engagement_time_msec 0事件天数 × 频次Highly Active Users本文最近 M 天内累计活跃时长超过 N 分钟天数 × 时长三者都依赖同一事件参数engagement_time_msec但 Highly Active Users 强调的是累计参与时长而非活跃天数或是否活跃过因此能更精细地区分每天登录但停留极短与深度使用两类用户适合用于高价值用户分层、流失预警与再营销受众圈选。数据基础GA4 events 导出表结构该指标查询针对 GA4 的 BigQuery 事件级导出表家族events_*执行。仓库中 GA4 Events Export 表文档 说明了其结构events_是一系列**按天分片daily sharded**的表起始于events_20201101至events_20210131每行代表一个事件如page_view、scroll、session_start、view_item、purchase。与本次查询密切相关的字段event_timestampINTEGER事件注册时的 POSIX 时间戳单位为微秒用于筛选最近 M 天的时间窗口event_paramsRECORD, REPEATED与事件关联的键值参数数组其中的engagement_time_msec记录用户在该事件上的参与时长毫秒user_idSTRING登录用户的唯一标识本查询的受众去重维度_TABLE_SUFFIXBigQuery 分片表通配符伪列用于限定物理表日期范围。其中event_params是重复记录ARRAY结构查询时必须通过CROSS JOIN T.event_params展开event_params.value又是一个按数据类型嵌套的记录整数参与时长存放在event_params.value.int_value中。这些结构特点决定了下面的查询模式。对应地仓库中的 GA4 演示数据集文档 也指出该类数据可直接在bigquery-public-data.ga4_obfuscated_sample_ecommerce公共数据集中实验。Schema 说明Query Pattern 型 Reference原文档明确声明This reference describes a query pattern and does not map to a single database schema.这是 OKF bundle 中Reference 类型文档的典型特征它描述的是一个可复用的查询模式query pattern而不是映射到某一张具体的数据表。因此该指标文档没有独立的 Schema 小节其模式语义全部体现在 SQL 模板中。从源码结构看这类文档由 reference_agent 生成与维护其 frontmatter 携带type: Reference、resource来源 URL、generated生成器与时间与sources引用来源字段文档的 解析与校验逻辑 要求type是唯一必填的 frontmatter 键而 Reference 类型文档在写入时不会触发仅针对type: BigQuery Table的字段一致性守卫参见 test_bundle_tools.py 中的用例。核心查询模式按累计参与时长圈选用户原文档给出了完整 SQL 模板以下为仓库原文未做删减/** * Builds an audience of Highly Active Users. * * Highly Active Users users who have been active for more than N minutes * in the last M days where M N. */ SELECT COUNT(DISTINCT user_id) AS high_active_users_count FROM ( SELECT user_id, event_params.key, SUM(event_params.value.int_value) FROM YOUR_TABLE.events_* AS T CROSS JOIN T.event_params WHERE -- User engagement in the last M 10 days. event_timestamp UNIX_MICROS(TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 10 DAY)) AND event_params.key engagement_time_msec AND _TABLE_SUFFIX BETWEEN 20180521 AND 20240131 GROUP BY 1, 2 HAVING -- Having engaged for more than N 0.1 minutes. SUM(event_params.value.int_value) 0.1 * 60 * 1000000 );逐步拆解执行逻辑数据源与参数展开FROM \YOUR_TABLE.events_ AS T CROSS JOIN T.event_params以分片表通配符读取全部事件表并把每行的event_params数组展开为一行一个参数。YOUR_TABLE需替换为实际项目 ID例如公共演示数据可写作bigquery-public-data.ga4_obfuscated_sample_ecommerce.events_该公共数据集的用法可参考 events 表文档 中的查询示例。时间窗口M 天event_timestamp UNIX_MICROS(TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 10 DAY))将当前时刻往前推 10 天的时间戳换算为微秒UNIX_MICROS与event_timestamp直接比较圈定最近 M 10 天的参与行为。注意event_timestamp单位为微秒必须用UNIX_MICROS而非UNIX_SECONDS对齐。参数过滤AND event_params.key engagement_time_msec只保留参与时长参数避免其他事件参数干扰聚合。物理表范围AND _TABLE_SUFFIX BETWEEN 20180521 AND 20240131限定扫描的分片表日期范围格式YYYYMMDD既控制成本也保证与 M 天窗口一致。示例中的 20180521 与 20240131 是 GA4 公共导出数据支持的历史区间实战中应根据自身导出表实际覆盖范围调整。按用户聚合时长累计GROUP BY 1, 2按user_id与参数 key 分组SUM(event_params.value.int_value)将该用户在窗口内所有事件的engagement_time_msec毫秒累加。阈值判定N 分钟HAVING SUM(...) 0.1 * 60 * 1000000把 N 0.1 分钟换算为微秒单位0.1 × 60 秒 × 1,000,000 微秒/秒只有累计时长超过该阈值的用户才进入结果。外层COUNT(DISTINCT user_id)最终输出高活跃用户数。参数化建议模板中的N与M均为可调参数替换示例值即可适配不同业务口径参数含义示例值修改位置M回溯天数10天INTERVAL 10 DAYN累计活跃时长阈值分钟0.1分钟HAVING中的0.1 * 60 * 1000000表范围分片表起止日期20180521~20240131_TABLE_SUFFIX BETWEEN ...换算公式为N 分钟 N × 60 × 1,000,000 微秒。若想圈选最近 30 天累计活跃超过 60 分钟的用户将INTERVAL改为30 DAY、阈值改为60 * 60 * 1000000即可。与同类指标的对比解读相比 N-Day Active Users只要求窗口内出现过engagement_time_msec 0本指标对参与强度有下限要求相比 Frequently Active Users要求 N 天中至少 M 天活跃按COUNT(DISTINCT event_date)统计活跃天数本指标以时长总和为口径能捕捉单次深度使用但天数少的用户。业务上可组合使用高频但不深度的用户用 Frequently Active深度但低频的用户用 Highly Active。数据口径与注意事项微秒单位一致性event_timestamp、UNIX_MICROS()与int_value的换算都围绕微秒展开混用秒/毫秒/微秒会导致时间窗口或阈值错误user_idvsuser_pseudo_id模板使用user_id登录用户。若目标场景包含未登录用户可改用user_pseudo_idGA 客户端 ID以覆盖更全的用户群但需注意跨设备去重能力会下降窗口与分片范围需同时收窄_TABLE_SUFFIX是物理表级裁剪event_timestamp是逻辑行级过滤两者配合既能保证语义正确也能减少扫描量、控制 BigQuery 费用参数缺失与空值未携带engagement_time_msec的事件如纯浏览型事件在展开后不满足key条件自然被过滤不会计入时长结果语义查询返回的是受众规模的计数若要输出用户明细列表用于再营销或导出可将外层改为SELECT DISTINCT user_id去掉聚合计数。在 Knowledge Catalog 仓库中的定位与验证该文档位于 GA4 bundle 的 references/metrics 目录与其他 6 个受众指标Acquired Users、Frequently Active Users、Google Acquired Cohorts、N-Day Active Users、N-Day Inactive Users、Purchasers共同构成基于获取来源、活跃程度与购买行为的受众度量集合。该集合的入口说明见 references 索引其数据底座是 events_ 导出表 中列出的 Metrics 引用清单。从仓库源码可以确认该文档的生成与管理机制文档 frontmatter 记录generated.by: reference_agent/gemini-3.5-flash表明其由 reference_agent 的文档生成管线产出type: Reference与resource、sources等字段遵循 OKF v0.2 规范OKFDocument 负责 frontmatter 的解析、序列化与必填键校验Reference 类型的写入不会触发仅针对BigQuery Table的反引号标识符与 sources 一致性守卫test_bundle_tools.py 的对应用例 直接印证了该行为。因此本文所述的 SQL 模板既可直接复制到 BigQuery 控制台或 API 中运行也可作为后续 Agent 检索、引用与再加工该受众指标的权威语料来源。赞分享数据目录AI Agent人工智能知识管理示例工程【免费下载链接】knowledge-catalogGoogle Cloud Knowledge Catalog Tools and Samples项目地址https://gitcode.com/gh_mirrors/kn/knowledge-catalog点击查看免费下载相关推荐TigerBeetle Java 两阶段转账Two-Phase Transfer示例解析从资金预留到确认入账的完整实战TigerBeetle Java 两阶段转账Two Phase Transfer示例解析从资金预留到确认入账的完整实战 导读 本文围绕 TigerBeet数据目录AI Agent人工智能知识管理示例工程knowledge-catalog 实战用 GA4 BigQuery 数据构建 Acquired Users 获客受众指标knowledge catalog 实战用 GA4 BigQuery 数据构建 Acquired Users 获客受众指标 导读 本文围绕知识目录仓库 too数据目录AI Agent人工智能知识管理示例工程ESP32 OpenThread CoAP Greenhouse 实战同一 Mesh 网络上 Plain CoAP 遥测与 CoAPS 安全控制的双传输设计ESP32 OpenThread CoAP Greenhouse 实战同一 Mesh 网络上 Plain CoAP 遥测与 CoAPS 安全控制的双传输设计数据目录AI Agent人工智能知识管理示例工程上一篇Boogu-Image-0.1-Edit社区生态与未来展望开源多模态模型的机遇与挑战下一篇告别手柄不兼容RetroPie游戏手柄映射核心技术全解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考