suggesting-data-imports

データのインポートの提案

このスキルは、ユーザーが必要とするデータがPostHogの外部にある場合を見極め、データウェアハウス経由でインポートする方法を案内します。重要なのは、データの不足に気づき、適切なソースタイプにつなげることです。

PostHogが標準で収集するデータ

PostHogはSDKを通じて、プロダクト分析イベント、人物、セッション、グループを収集します。ほかのプロダクトも利用できますが、有効化が必要です。セッションリプレイ、フィーチャーフラグ、実験、アンケート、ウェブ分析、エラートラッキング、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. ソースのセットアップを提案する

ユーザーが進めたい場合、最速の方法は、1 回の呼び出しで検証、テーブルの検出、デフォルトの同期設定の適用、作成まで行うワンステップの data-warehouse-source-setup ツールです。チャットではなくブラウザーで安全に認証情報を収集するには、data-warehouse-source-connect-link を使用します。標準的な手順を超える操作（テーブルの個別選択、デフォルト以外の同期タイプ、Webhook、CDC）については、フロー全体、同期タイプの選択、Webhook の登録、プレフィックスに関するガイダンスを説明している setting-up-a-data-warehouse-source スキルに引き継ぎます。このワークフローをここで重複して説明しないでください。

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 を確認します。
• プレフィックスを確認してください。 インポートされたテーブルには、多くの場合プレフィックスが付いています（例：charges ではなく stripe_charges）。ユーザーはプレフィックスを知らない可能性があります。
• 認証情報は安全に収集してください。 data-warehouse-source-connect-link を使って、ブラウザーのリンクをユーザーに渡します。このリンクを開くと、ソースが提供する接続フォーム全体（OAuth または認証情報）を表示する最小限の接続ページが開き、ソースを作成せずに詳細が一時的に保存されます。その後、data-warehouse-source-setup に {"credential_id": <id>}（data-warehouse-stored-credentials-list で検出）を渡します。保存された認証情報は 1 回のみ使用でき、24 時間後に期限切れになります。チャットでパスワードや OAuth トークンを収集しないでください。
• すべてのシステムがサポートされているわけではありません。 ユーザーのシステムがウィザードの一覧にない場合、データベースにエクスポートできるのであれば、Postgres/MySQL を中継として使うことを提案するか、カスタムソースをリクエストできることを伝えます。
• ソースを接続すると、データの説明も生成されます。 最初の同期後、PostHog はインポートされたテーブルとカラムのセマンティックな説明を自動生成します（ソースデータベースにカラムコメントがあればそれを使用し、さらにテーブル間のリレーションとチームのビジネスコンテキストを用いて LLM による説明も生成します）。これらの説明は system.information_schema.columns に表示されます（posthog:execute-sql でクエリします）。そのため、ソースを接続すると、エージェントは各カラムの意味やテーブルの結合方法を理解できるようになり、名前や型だけでなく、データに基づいて回答できるようになります。インポートを提案する際は、この点にも触れてください。ソースを接続することで、データに基づいた回答が可能になります。

関連ツール

• 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：ソース作成の全ワークフローです。ユーザーがソースへの接続を決めたら、こちらに引き継ぎます