PostHog 数据仓库系统表查询指南：querying-posthog-data 技能中的 Data Warehouse 参考

PostHog 数据仓库系统表查询指南querying-posthog-data 技能中的 Data Warehouse 参考【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthog本文基于 PostHog 仓库中querying-posthog-data技能下的 Data Warehouse 参考文档系统讲解用于 AI Agent 通过 HogQL 查询 PostHog 数据仓库元数据的四张system.*表外部数据源system.data_warehouse_sources、数据仓库表system.data_warehouse_tables、同步配置system.source_schemas与同步任务system.source_sync_jobs。读完本文你将掌握各表的字段含义、表间关联关系、同步状态与同步类型的取值并能直接复用七条现成的 HogQL 查询模式来定位 Stripe、Postgres 等外部源同步进来的表、排查同步失败并统计同步量。背景这份参考在 PostHog 中的位置Data Warehouse 参考文档位于 PostHog 为编码 Agent 编写的技能目录中技能入口SKILL.md本文对应文档models-data-warehouse.md.j2Jinja2 模板构建时渲染为models-data-warehouse.md该技能明确要求 Agent 在写任何 HogQL/SQL 或调用posthog:execute-sql之前先阅读相应参考。SKILL.md 指出system.*表只暴露每个 Django 模型的精选子集因此 REST 工具返回的字段不一定可查询应以参考文档中的列清单为准。从源码结构看文档中每个Columns小节的内容由模板变量{{ schema_columns(system.xxx) }}动态生成渲染函数定义在 build_skills.py 中SkillRenderer把schema_columns作为全局函数注入 Jinja2 环境见 schema_columns 模块从而保证列清单与线上 HogQL 目录严格一致。这也是 SKILL.md 所说列清单由实时 HogQL 目录生成的实现机制。外部数据源表system.data_warehouse_sources外部数据源External Data Source代表与第三方数据提供方Stripe、Hubspot、Postgres 等建立的连接连接的数据会被同步进 PostHog。文档列出的常见source_type包括Stripe— 支付与订阅数据Hubspot— CRM 与营销数据Postgres— PostgreSQL 数据库MySQL— MySQL 数据库Snowflake— Snowflake 数据仓库BigQuery— Google BigQueryS3— Amazon S3 文件Zendesk— 客服数据Salesforce— CRM 数据关键关系一个 source 可以对应多条system.data_warehouse_tables记录一个源同步出多张表。该表的 HogQL 定义位于 posthog/hogql/database/schema/system.pypostgres_table_nameposthog_externaldatasource其中几个值得注意的字段语义id源的 UUID。源码描述中说明对于 direct直连型连接可以把该 id 作为查询的 connection id 进行实时查询access_methoddirect表示实时查询连接不同步数据表只有在通过连接查询时才存在warehouse表示数据已同步进 PostHogis_live_queryable表达式字段当source_type映射到受支持的查询引擎、且源要么是纯直连、要么是开启实时查询的同步源时为 1。源码给出了典型用法WHERE is_live_queryable 1列出所有可用于实时查询的连接prefix该源同步的所有表所加的表名前缀status源码中标注为遗留的源级状态已废弃以source_schemas.status中每表的状态为准可能过期——因此排查同步问题时应优先看后文system.source_schemas与system.source_sync_jobsdeleted软删除标记查询时应过滤NOT deleted。数据仓库表system.data_warehouse_tables每张从外部源同步而来或手动上传的表对应一条记录包含列定义、类型与元数据。文档中columns字段的 JSON 结构示例{ id: { hogql: IntegerDatabaseField, clickhouse: Int64, valid: true }, email: { hogql: StringDatabaseField, clickhouse: Nullable(String), valid: true }, created_at: { hogql: DateTimeDatabaseField, clickhouse: DateTime64(3), valid: true } }关键关系external_data_source_id-system.data_warehouse_sources.id。文档给出的重要注意事项表名可能带源前缀例如 Stripe 源、未配置自定义前缀时的stripe_customerscolumns字段从实际数据 schema 同步而来valid: false的列可能存在类型不匹配或其他问题带external_data_source_id的表由同步系统管理不带源的表是用户上传或手动创建的。对应 HogQL 定义见 system.py 中的 data_warehouse_tablesrow_count被描述为表中行数的近似值这解释了查询模式中直接使用row_count做统计而不需要count()的原因。同步配置表system.source_schemas每个外部数据源内部的逐表同步配置存于此表每条 schema 记录代表从外部源同步的一张表或实体HogQL 定义见 system.py底层表posthog_externaldataschema。状态取值statusRunning— 同步正在进行Paused— 被用户暂停Completed— 最近一次同步成功完成Failed— 最近一次同步出错BillingLimitReached— 因账单限额停止BillingLimitTooLow— 账单限额过低无法同步同步类型sync_typefull_refresh— 每次同步全量重载incremental— 只同步新增/变更数据append— 追加新数据而不更新已有行关键关系Sourcesource_id-system.data_warehouse_sources.idTabletable_id-system.data_warehouse_tables.id此外该表还带有should_sync该表是否启用同步、last_synced_at最近一次同步完成时间、latest_error最近一次同步错误信息等字段是定位某张表最近为什么没更新的首选入口。同步任务表system.source_sync_jobs外部数据源的每次同步运行sync job run对应一条记录跟踪单次同步操作的状态、行数与时间定义见 system.py底层表posthog_externaldatajob。状态取值statusRunning— 同步正在进行Completed— 同步成功完成Failed— 同步出错BillingLimitReached— 因账单限额停止BillingLimitTooLow— 账单限额过低无法同步关键关系pipeline_id-system.data_warehouse_sources.id源码中还补充了schema_id-system.source_schemas.id可精确定位到具体表。常用字段rows_synced本次同步行数、latest_error失败时的错误信息、created_at/finished_at起止时间运行中时finished_at为 NULL。常用查询模式可直接复用的 HogQL以下查询模式完整继承自原文档均可通过posthog:execute-sql执行。列出所有数据仓库表SELECT name, row_count, created_at FROM system.data_warehouse_tables WHERE NOT deleted ORDER BY created_at DESC按源类型查找表SELECT t.name, t.row_count, s.source_type FROM system.data_warehouse_tables AS t INNER JOIN system.data_warehouse_sources AS s ON t.external_data_source_id s.id WHERE NOT t.deleted AND s.source_type Stripe查看指定表的列SELECT name, columns FROM system.data_warehouse_tables WHERE name stripe_customers AND NOT deleted查找包含特定列的表SELECT name, JSONExtractString(columns, email, clickhouse) AS email_type FROM system.data_warehouse_tables WHERE NOT deleted AND JSONHas(columns, email)列出带表计数的活跃数据源SELECT s.source_type, s.prefix, count(t.id) AS table_count, sum(t.row_count) AS total_rows FROM system.data_warehouse_sources AS s LEFT JOIN system.data_warehouse_tables AS t ON t.external_data_source_id s.id AND NOT t.deleted WHERE NOT s.deleted GROUP BY s.source_type, s.prefix ORDER BY table_count DESC查看最近的同步任务及其源类型SELECT j.status, j.rows_synced, j.created_at, j.finished_at, j.latest_error, s.source_type FROM system.source_sync_jobs AS j INNER JOIN system.data_warehouse_sources AS s ON j.pipeline_id s.id ORDER BY j.created_at DESC LIMIT 50查找最近 7 天内失败的同步任务SELECT j.pipeline_id, j.latest_error, j.created_at, s.source_type, s.prefix FROM system.source_sync_jobs AS j INNER JOIN system.data_warehouse_sources AS s ON j.pipeline_id s.id WHERE j.status Failed AND j.created_at now() - INTERVAL 7 DAY ORDER BY j.created_at DESC按源统计同步情况SELECT s.source_type, s.prefix, count(j.id) AS total_jobs, countIf(j.status Completed) AS completed, countIf(j.status Failed) AS failed, sum(j.rows_synced) AS total_rows_synced FROM system.source_sync_jobs AS j INNER JOIN system.data_warehouse_sources AS s ON j.pipeline_id s.id GROUP BY s.source_type, s.prefix ORDER BY total_jobs DESC源码级佐证表定义、测试与构建链路以上文档内容并非孤立的散文说明仓库中有多处可验证的实现与测试表结构定义四张system.*表在 posthog/hogql/database/schema/system.py 中以PostgresTable显式声明字段名、类型与描述并在文件末尾注册进目录如data_warehouse_sources: TableNode(...)。文档中{{ schema_columns(...) }}渲染出的列清单即来源于此定义。系统表测试test_system_tables.py 覆盖了这四张表的数据插入与字段读取如data_warehouse_sources、data_warehouse_tables、source_schemas、source_sync_jobs均在该测试的参数化列表中并验证is_live_queryable会编译为对direct_query_enabled字段的表达式——与文档所述direct 连接可实时查询一致。文档构建链路build_skills.py 通过hogli build:skills命令把SKILL.md(.j2)与references/下的模板渲染输出到dist/skills/并打包为dist/skills.zip分发.j2后缀在渲染后会被剥离因此技能目录里链接写的是models-data-warehouse.md而源码文件是models-data-warehouse.md.j2。使用边界与注意事项这套参考服务于发现与聚合场景execute-sql用于定位实体通常拿到 ID读取完整实体仍应使用对应的专用读取工具如posthog:insight-get文档明确反对用 SQL 重构完整实体查询data_warehouse_tables与data_warehouse_sources时应始终带上NOT deleted过滤避免命中软删除记录system.data_warehouse_sources.status已在源码中标记为遗留字段判断某张表的同步健康度应结合system.source_schemas.status与system.source_sync_jobs.status若需要针对业务指标做受治理的度量如 MRR、激活率SKILL.md 建议先检查语义层system.information_schema.metrics再决定是否从原始事件或这些表推导。【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthog创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考