suggesting-data-imports

建议导入数据

此技能可帮助识别用户需要的数据是否位于 PostHog 之外，并引导他们通过数据仓库导入数据。关键在于识别数据缺口，然后将其与合适的数据源类型对应起来。

PostHog 原生收集的数据

PostHog 通过其 SDK 收集产品分析事件、人员、会话和群组。还提供其他产品，但需要启用：会话回放、功能标志、实验、调查、Web 分析、错误跟踪、AI 可观测性、对话、日志、收入分析、工作流、CDP 目标和批量导出。PostHog 不会收集外部业务数据，例如支付、订阅、CRM 记录、来自其他系统的支持工单或生产数据库表——这些数据必须通过数据仓库导入。

何时使用此技能

• HogQL 查询失败，因为某个表不存在
• 用户询问外部系统中的数据（Stripe、Hubspot、Salesforce 等）
• 用户想将 PostHog 分析数据与业务数据（收入、支持工单、CRM 记录等）关联起来
• 用户询问“如何将我的 X 数据导入 PostHog？”
• 分析需要将 PostHog 事件与外部数据联接
• 用户询问如何导出 PostHog 数据，以便在其他地方进行比较（例如 Google 表格、外部数据仓库等）

工作流

1. 了解缺少哪些数据

留意用户需要外部数据的迹象：

• 他们提到某个具体工具或系统（Stripe、Hubspot、Zendesk、自家的生产数据库等）
• 查询引用了 PostHog 中不存在的表
• 他们想分析 PostHog 不会原生跟踪的数据（收入、支持工单、CRM 交易等）

如果查询失败，请检查错误——如果错误提示“找不到表”或类似信息，则很可能需要导入数据。

2. 检查已连接的数据源

调用 posthog:external-data-sources-list 查看现有数据源。数据可能已经导入，只是用户不知道表名或前缀。

如果用户所询问系统对应的数据源已存在，请调用 posthog:external-data-schemas-list 显示可用表。数据可能已经存在，只是表名或前缀不同。

还可以通过 posthog:execute-sql 查询 system.information_schema.tables，查看所有可查询的表——数据可能已经作为视图或联接表提供。

3. 确定合适的数据源类型

如果数据尚未导入，请调用 posthog:external-data-sources-wizard 查看可用的数据源类型——枚举时若不指定 source_type，请传入 fields: ['*.name', '*.caption']，以跳过庞大的各数据源配置字段定义。根据用户需求匹配数据源：

常见模式：

用户想要的数据	数据源类型	关键表
收入／支付数据	Stripe、Chargebee、Shopify	charges、subscriptions、invoices、customers
CRM／销售管道	Hubspot、Salesforce、Attio	contacts、deals、companies
支持工单	Zendesk	tickets、users、organizations
来自自家数据库的产品数据	Postgres、MySQL、BigQuery、Snowflake、Redshift	用户自己的表
营销／广告	Google Ads、Meta Ads、LinkedIn Ads、TikTok Ads	campaigns、ad_groups、ads
邮件营销	Mailchimp、Klaviyo	campaigns、lists、subscribers
项目管理	Linear	issues、projects
错误跟踪（外部）	Sentry	issues、events

4. 推荐导入

简洁地给出建议：

• 应连接哪种来源类型
• 哪些表将变为可用
• 这如何帮助实现用户想要的分析

示例：“您的 Stripe 数据尚未导入 PostHog。连接 Stripe 来源后，您就能获取 charges、subscriptions 和 customers 等表，并将其与 PostHog 事件联接，按用户行为分析收入。”

5. 提议设置来源

如果用户想继续，最快的方式是使用一步完成的 data-warehouse-source-setup 工具（在一次调用中完成验证凭据 → 发现表 → 同步默认值 → 创建），并使用 data-warehouse-source-connect-link 在浏览器中安全地收集凭据，而不是在聊天中收集。对于超出常规流程的操作（手动挑选表、使用非默认同步类型、配置 Webhook、CDC），请交由 setting-up-a-data-warehouse-source 技能处理，该技能涵盖完整流程、同步类型选择、Webhook 注册和前缀说明。不要在此重复该工作流。

6. 展示导入后可实现的功能

连接后，帮助用户编写第一个将 PostHog 数据与导入数据联接的查询。使用 posthog:execute-sql 进行演示。

常见联接模式：

• 按电子邮件将 Stripe 客户与 PostHog 用户关联：SELECT * FROM stripe_customers sc JOIN persons p ON sc.email = p.properties.$email
• 将 CRM 交易与事件关联：将产品使用情况与销售结果联系起来
• 将支持工单与会话录像关联：查找提交过工单的用户的录像

重要说明

• 不要猜测表名。 在声称数据不存在之前，务必检查 system.information_schema.tables（通过 posthog:execute-sql）和 posthog:external-data-schemas-list。
• 检查前缀。 导入的表通常带有前缀（例如，stripe_charges 而不是 charges）。用户可能不知道这个前缀。
• 安全地收集凭据。 使用 data-warehouse-source-connect-link 向用户提供浏览器链接。该链接会打开一个精简的连接页面，显示来源的完整连接表单（来源支持哪种方式就显示 OAuth 或凭据表单），并临时保存信息，但不会创建来源。之后，将通过 data-warehouse-stored-credentials-list 查到的 {"credential_id": <id>} 传递给 data-warehouse-source-setup。存储的凭据只能使用一次，并会在 24 小时后过期。不要在聊天中收集密码或 OAuth 令牌。
• 并非支持所有系统。 如果用户的系统不在向导列表中，可建议在他们能导出到数据库时使用 Postgres/MySQL 作为桥接，或者说明可以申请支持自定义来源。
• 连接来源也会为数据生成说明。 首次同步后，PostHog 会自动为导入的表和列生成语义说明（优先使用来源数据库中已有的列注释，并结合表之间的关系和团队的业务背景，通过大模型补充说明）。这些说明会显示在 system.information_schema.columns 中（使用 posthog:execute-sql 查询）。因此，连接来源后，Agent 不仅能了解列的名称和类型，还能推理每列的含义以及表之间的联接方式。推荐导入时，请提及这一点：连接来源后，数据才能用于回答问题。

相关工具

• posthog:external-data-sources-list：检查现有来源连接
• posthog:external-data-schemas-list：检查已导入的表
• 对 system.information_schema.* 使用 posthog:execute-sql：查看所有可查询的表，包括视图
• posthog:external-data-sources-wizard：获取可用的来源类型（枚举时传入 fields: ['*.name', '*.caption']）
• posthog:data-warehouse-source-connect-link：获取安全的浏览器/OAuth 链接以收集凭据
• posthog:data-warehouse-source-setup：一步完成创建（验证、发现表、应用同步默认值、创建）
• posthog:execute-sql：运行查询，演示可实现的功能

相关技能

• setting-up-a-data-warehouse-source：完整的数据源创建工作流 — 用户决定连接数据源后，请转交至此