Google Analytics (GA4)¶

Connect Google Analytics 4 as a data source using OAuth 2.0.

Overview¶

Google Analytics loads GA4 reporting data into DuckDB. By default, Dango creates 6 tables covering traffic, pages, landing pages, geography, events, and conversions. You can add custom queries for additional reports.

Prerequisites¶

Before adding Google Analytics as a source, you need:

1. GA4 property (not Universal Analytics)
2. Property ID — a numeric ID found in GA4 Admin > Property Settings
3. Viewer role (or higher) on the GA4 property
4. Google Cloud project with the Analytics Data API enabled
5. OAuth 2.0 credentials (Client ID + Client Secret) — can be shared with other Google sources

Create OAuth Credentials¶

If you already have Google OAuth credentials from another source (e.g., Google Sheets), you can reuse them — just enable the Google Analytics Data API in your Google Cloud project.

Otherwise, follow the same steps as Google Sheets > Create OAuth Credentials, but enable the Google Analytics Data API instead of (or in addition to) the Sheets API.

Redirect URIs¶

http://localhost:8080/callback

http://localhost:8800/api/oauth/callback

Setup¶

Step 1: Add Source¶

dango source add
# Select "Google Analytics 4" from the list

Step 2: Authenticate¶

The wizard will:

1. Prompt for your Client ID and Client Secret (if not already saved from another Google source)
2. Open your browser to the Google consent page
3. Return to the terminal after authentication

Step 3: Configure¶

? GA4 Property ID: 123456789
? Start date (YYYY-MM-DD or relative like '90daysAgo') [90daysAgo]:

• Property ID: The numeric ID from GA4 Admin > Property Settings (not the Measurement ID starting with G-)
• Start date: How far back to load on first sync. Accepts absolute dates (2024-01-01) or relative dates (90daysAgo, 30daysAgo)

Step 4: Sync¶

dango sync website_analytics

Configuration¶

sources.yml¶

version: '1.0'
sources:
  - name: website_analytics
    type: google_analytics
    enabled: true
    description: Website traffic from GA4
    google_analytics:
      property_id: "123456789"
      start_date: "90daysAgo"

.dlt/secrets.toml¶

[sources.google_analytics.credentials]
client_id = "123456789-abc.apps.googleusercontent.com"
client_secret = "GOCSPX-..."
refresh_token = "1//0eF..."
project_id = "dango-oauth"

Tables Loaded¶

Dango creates 6 tables by default in the raw_{source_name} schema:

-- Example: query traffic data
SELECT * FROM raw_website_analytics.traffic
WHERE date >= '2024-01-01'
ORDER BY sessions DESC
LIMIT 10;

Custom Queries¶

dango sync website_analytics --full-refresh

Step-by-Step: Editing Queries¶

1. Find your config file: Open .dlt/config.toml in your project root. The default queries are written here when you add the source.

2. Understand the structure: Each query has a resource_name (becomes the table name), dimensions (up to 9), and metrics (up to 10).

   [[sources.google_analytics.queries]]
   resource_name = "my_custom_table"
   dimensions = ["date", "eventName", "sessionSource"]
   metrics = ["eventCount", "totalUsers"]
   

3. Check compatibility: Not all dimensions and metrics can be combined. Use the GA4 Dimensions & Metrics Explorer to verify.

4. GA4 API limits:

   • Maximum 9 dimensions per query (Dango validates this before sending)
   • Maximum 10 metrics per query
   • Some dimensions are incompatible with certain metrics

5. Add a new query: Append a new [[sources.google_analytics.queries]] block to your config:

   [[sources.google_analytics.queries]]
   resource_name = "demographics"
   dimensions = ["date", "userAgeBracket", "userGender", "deviceCategory"]
   metrics = ["totalUsers", "sessions", "engagedSessions"]
   

6. Sync: New queries create new tables automatically. No full refresh needed for new tables (only for dimension changes to existing tables).

   dango sync website_analytics
   

See the GA4 Dimensions & Metrics Explorer for all available fields.

Sync Behavior¶

• Incremental with lookback_days: 7 — each sync deletes and re-fetches the last 7 days to capture GA4 data corrections, then loads new days since the last sync
• First sync loads data from start_date to yesterday
• start_date only affects the first sync — subsequent syncs use dlt's incremental state. To reload history, use dango sync --full-refresh
• Data is aggregated (not event-level) — each row is a dimension combination with summed metrics

Troubleshooting¶

Property Not Found¶

Problem: Property not found or PERMISSION_DENIED

Solutions:

1. Verify you're using a GA4 Property ID (numeric), not a UA property (starts with UA-)
2. The Property ID is NOT the Measurement ID (starts with G-) — find it in GA4 Admin > Property Settings
3. Ensure your Google account has at least Viewer role on the property

7-Day Token Expiry¶

Problem: Token stops working after 7 days

Solution: Your Google Cloud OAuth app is in "Testing" mode. Set it to "In production" in the OAuth consent screen.

Quota Limits¶

Problem: 429 Resource Exhausted or quota errors

Solution: GA4 Data API allows 10 concurrent requests per property. If you have many queries or sync frequently, space out syncs or reduce the number of custom queries.

No Data Returned¶

Problem: Tables are empty after sync

Solutions:

1. Check that the start_date is within the range of your GA4 data
2. Verify your property is receiving data (check GA4 Realtime report)
3. GA4 data may take 24-48 hours to appear in the API

Next Steps¶

• OAuth Sources - OAuth overview and token management
• Sync Modes - Understand incremental loading
• Deduplication - Handle lookback-day overlaps
• Google Sheets - Share OAuth credentials with Sheets
• Google Ads - Share OAuth credentials with Ads