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 交易等）

如果查询失败，检查错误——如果是“table not found”或类似错误，数据很可能需要导入。

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 customers 与 PostHog persons 连接：SELECT * FROM stripe_customers sc JOIN persons p ON sc.email = p.properties.$email
将 CRM deals 与事件连接：将产品使用与销售结果关联
将支持工单与会话录制连接：查找提交工单用户的录制

重要说明

不要猜测表名。在说数据不存在之前，始终通过 posthog:execute-sql 检查 system.information_schema.tables 和 posthog:external-data-schemas-list。
检查前缀。导入的表通常有前缀（例如 stripe_charges 而非 charges）。用户可能不知道前缀。
安全收集凭据。使用 data-warehouse-source-connect-link 向用户提供浏览器链接——它会打开一个最小连接页面，渲染数据源的完整连接表单（OAuth 或凭据，取决于数据源提供的方式），临时存储详细信息而不创建数据源。之后将 {"credential_id": <id>}（通过 data-warehouse-stored-credentials-list 发现）传递给 data-warehouse-source-setup——存储的凭据是一次性的，24 小时后过期。不要在聊天中收集密码或 OAuth 令牌。
并非所有系统都受支持。如果用户的系统不在向导列表中，建议如果他们能导出到数据库，则使用 Postgres/MySQL 作为桥梁，或提及可以请求自定义数据源。
连接数据源也会为其生成文档。首次同步后，PostHog 会自动为导入的表和列生成语义描述（来自源数据库自身的列注释（如有），加上使用表关系和团队业务上下文的 LLM 处理）。这些描述会出现在 system.information_schema.columns 中（使用 posthog:execute-sql 查询），因此一旦连接数据源，代理就能推理每列的含义以及表如何连接——而不仅仅是它们的名称和类型。在推荐导入时提及这一点：连接数据源才是让数据可回答的关键。

技能介绍

用途