Suggesting Data Imports

1---
2name: suggesting-data-imports
3description: 'Use when the user asks about revenue, payments, subscriptions, billing, CRM deals, support tickets, production database tables, or other data that PostHog does not collect natively. Also use when a query fails because a table does not exist or returns no results for expected external data. The data warehouse can import from SaaS tools (Stripe, Hubspot, etc.), production databases (Postgres, MySQL, BigQuery, Snowflake), and other arbitrary data sources. Covers checking existing sources, identifying the right source type, and guiding the setup.'
4---
5 
6# Suggesting data imports
7 
8This 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.
9 
10## What PostHog collects natively
11 
12PostHog 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.
13 
14## When to use this skill
15 
16- A HogQL query fails because a table doesn't exist
17- The user asks about data from an external system (Stripe, Hubspot, Salesforce, etc.)
18- The user wants to correlate PostHog analytics with business data (revenue, support tickets, CRM records, etc)
19- The user asks "how do I get my X data into PostHog?"
20- Analysis requires joining PostHog events with external data
21- The user asks about exporting PostHog data for comparison elsewhere (in a google sheet, external warehouse, etc)
22 
23## Workflow
24 
25### 1. Understand what data is missing
26 
27Listen for signals that the user needs external data:
28 
29- They mention a specific tool or system (Stripe, Hubspot, Zendesk, their production database, etc.)
30- A query references a table that doesn't exist in PostHog
31- They want to analyze something PostHog doesn't track natively (revenue, support tickets, CRM deals, etc.)
32 
33If a query failed, check the error — if it's "table not found" or similar, the data likely needs to be imported.
34 
35### 2. Check what's already connected
36 
37Call `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.
38 
39If 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.
40 
41Also call `posthog:read-data-warehouse-schema` to see all queryable tables — the data might already be available as a view or joined table.
42 
43### 3. Identify the right source type
44 
45If the data isn't imported yet, call `posthog:external-data-sources-wizard` to see available source types. Match the user's need to a source:
46 
47**Common patterns:**
48 
49| User wants                 | Source type                                    | Key tables                                  |
50| -------------------------- | ---------------------------------------------- | ------------------------------------------- |
51| Revenue / payment data     | Stripe, Chargebee, Shopify                     | charges, subscriptions, invoices, customers |
52| CRM / sales pipeline       | Hubspot, Salesforce, Attio                     | contacts, deals, companies                  |
53| Support tickets            | Zendesk                                        | tickets, users, organizations               |
54| Product data from their DB | Postgres, MySQL, BigQuery, Snowflake, Redshift | user's own tables                           |
55| Marketing / ads            | Google Ads, Meta Ads, LinkedIn Ads, TikTok Ads | campaigns, ad_groups, ads                   |
56| Email marketing            | Mailchimp, Klaviyo                             | campaigns, lists, subscribers               |
57| Project management         | Linear                                         | issues, projects                            |
58| Error tracking (external)  | Sentry                                         | issues, events                              |
59 
60### 4. Suggest the import
61 
62Present the recommendation concisely:
63 
64- What source type to connect
65- What tables would become available
66- How this enables the analysis they want
67 
68Example: "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."
69 
70### 5. Offer to set up the source
71 
72If the user wants to proceed, the fastest path is the one-step `data-warehouse-source-setup` tool (validate creds →
73discover tables → sync defaults → create, in one call), with `data-warehouse-source-connect-link` to collect
74credentials securely in the browser rather than in chat. For anything beyond the happy path (hand-picking tables,
75non-default sync types, webhooks, CDC), hand off to the **`setting-up-a-data-warehouse-source`** skill, which covers
76the full flow, sync-type selection, webhook registration, and prefix guidance. Do not duplicate that workflow here.
77 
78### 6. Show what's possible after import
79 
80Once connected, help the user write their first query joining PostHog data with the imported data. Use `posthog:execute-sql` to demonstrate.
81 
82Common join patterns:
83 
84- Join Stripe customers with PostHog persons on email: `SELECT * FROM stripe_customers sc JOIN persons p ON sc.email = p.properties.$email`
85- Join CRM deals with events: correlate product usage with sales outcomes
86- Join support tickets with session recordings: find recordings for users who filed tickets
87 
88## Important notes
89 
90- **Don't guess table names.** Always check `posthog:read-data-warehouse-schema` and `posthog:external-data-schemas-list` before saying data doesn't exist.
91- **Check prefixes.** Imported tables are often prefixed (e.g. `stripe_charges` not `charges`). The user might not know the prefix.
92- **Collect credentials securely.** Use `data-warehouse-source-connect-link` to hand the user a browser link — it opens a minimal connect page rendering the source's full connection form (OAuth or credentials, whichever the source offers) that stashes the details temporarily without creating the source. Afterwards pass `{"credential_id": <id>}` (discovered via `data-warehouse-stored-credentials-list`) to `data-warehouse-source-setup` — stored credentials are single-use and expire after 24 hours. Don't collect passwords or OAuth tokens in chat.
93- **Not all systems are supported.** If the user's system isn't in the wizard list, suggest using Postgres/MySQL as a bridge if they can export to a database, or mention that custom sources can be requested.
94 
95## Related tools
96 
97- `posthog:external-data-sources-list`: Check existing source connections
98- `posthog:external-data-schemas-list`: Check what tables are already imported
99- `posthog:read-data-warehouse-schema`: See all queryable tables including views
100- `posthog:external-data-sources-wizard`: Get available source types
101- `posthog:data-warehouse-source-connect-link`: Get a secure browser/OAuth link to collect credentials
102- `posthog:data-warehouse-source-setup`: One-step create (validate, discover tables, apply sync defaults, create)
103- `posthog:execute-sql`: Run queries to demonstrate what's possible
104 
105## Related skills
106 
107- **`setting-up-a-data-warehouse-source`**: Full source creation workflow — hand off here once the user decides to connect a source
108