/suggesting-data-imports

name: suggesting-data-imports
description: 'Use when the user asks about revenue, payments, subscriptions, billing, CRM deals, support tickets, ad spend, production database tables, bucket files, or local file uploads. Also use when the user wants to join PostHog events with external data, or when a query fails because an expected table is missing. The data warehouse can import from SaaS tools, ad platforms, databases, object storage, and uploaded files. Covers checking existing sources, identifying the right source type, and guiding setup.'

Suggesting data imports

This skill helps identify when data the user needs lives outside PostHog and guides them toward importing it via the data warehouse. The key insight is recognizing the gap — then connecting it to the right source type.

What PostHog collects natively

PostHog collects product analytics events, persons, sessions, and groups via its SDKs. Additional products are available but must be enabled: session replay, feature flags, experiments, surveys, web analytics, error tracking, AI observability, conversations, logs, revenue analytics, workflows, CDP destinations, and batch exports. PostHog does **not** collect external business data like payments, subscriptions, CRM records, support tickets from other systems, or production database tables — that data must be imported via the data warehouse.

When to use this skill

• A HogQL query fails because a table doesn't exist
• The user asks about data from an external system (Stripe, Hubspot, Salesforce, etc.)
• The user wants to correlate PostHog analytics with business data (revenue, support tickets, CRM records, etc)
• The user asks "how do I get my X data into PostHog?"
• Analysis requires joining PostHog events with external data
• The user asks about exporting PostHog data for comparison elsewhere (in a google sheet, external warehouse, etc)
• The user wants to import files from a bucket or upload a local file

Workflow

1. Understand what data is missing

Listen for signals that the user needs external data:

• They mention a specific tool or system (Stripe, Hubspot, Zendesk, their production database, etc.)
• They mention bucket files or a local CSV, JSON, or Parquet file
• A query references a table that doesn't exist in PostHog
• They want to analyze something PostHog doesn't track natively (revenue, support tickets, CRM deals, etc.)

If a query failed, check the error — if it's "table not found" or similar, the data likely needs to be imported.

2. Check what's already connected

Call `posthog:external-data-sources-list` to see existing sources. The data might already be imported but the user doesn't know the table name or prefix.

If a source exists for the system they're asking about, call `posthog:external-data-schemas-list` to show the available tables. The data might be there but under a different name or prefix.

Also query `system.information_schema.tables` with `posthog:execute-sql` to see all queryable tables — the data might already be available as a view or joined table.

3. Identify the right source type

If the data isn't imported yet, call `posthog:external-data-sources-wizard` to see available source types — when enumerating without `source_type`, pass `fields: ['*.name', '*.caption']` to skip the large per-source config field definitions. Match the user's need to a source:

**Common patterns:**

| User wants | Source type | Key tables | | -------------------------- | ---------------------------------------------- | ------------------------------------------- | | Revenue / payment data | Stripe, Chargebee, Shopify | charges, subscriptions, invoices, customers | | CRM / sales pipeline | Hubspot, Salesforce, Attio | contacts, deals, companies | | Support tickets | Zendesk | tickets, users, organizations | | Product data from their DB | Postgres, MySQL, BigQuery, Snowflake, Redshift | user's own tables | | Marketing / ads | Google Ads, Meta Ads, LinkedIn Ads, TikTok Ads | campaigns, ad_groups, ads | | Email marketing | Mailchimp, Klaviyo | campaigns, lists, subscribers | | Project management | Linear | issues, projects | | Error tracking (external) | Sentry | issues, events |

For bucket files, use `AmazonS3`, `GoogleCloudStorage`, `AzureBlob`, or `CloudflareR2`. For local files, use the PostHog app upload flow. It creates a `FileUpload` source.

4. Suggest the import

Present the recommendation concisely:

• What source type to connect
• What tables would become available
• How this enables the analysis they want

Example: "Your Stripe data isn't in PostHog yet. If you connect a Stripe source, you'll get tables like `charges`, `subscriptions`, and `customers` that you can join with PostHog events to analyze revenue by user behavior."

5. Offer to set up the source

If the user wants to proceed, the fastest path is the one-step `data-warehouse-source-setup` tool (validate creds → discover tables → sync defaults → create, in one call), with `data-warehouse-source-connect-link` to collect credentials securely in the browser rather than in chat. For anything beyond the happy path (hand-picking tables, non-default sync types, webhooks, CDC), hand off to the **`setting-up-a-data-warehouse-source`** skill, which covers the full flow, sync-type selection, webhook registration, and prefix guidance. Do not duplicate that workflow here.

For a local file, direct the user to upload it in the PostHog app. The upload creates a `FileUpload` source. No MCP tool uploads files.

6