Data warehouse connectors

Connect Swetrix Cloud to BigQuery to keep a daily copy of your pageviews and custom events in your own Google Cloud project. Use these tables in SQL queries, Looker Studio, or another BI tool that supports BigQuery.

For Snowflake, Redshift, and other destinations, use the raw export API in your own pipeline. BigQuery is the built-in destination; Swetrix does not provide a native Snowflake, Redshift, Airbyte, or Fivetran connector.

What is exported?Copy Anchor Link

Each export contains individual events recorded by Swetrix:

Both tables use the same schema and are partitioned by event_date, the UTC date of the event. The default prefix is based on your Swetrix Project ID, so projects can share a dataset without sharing tables.

Exports do not contain imported historical data from Google Analytics, Plausible, or another analytics provider. They also exclude session replay recordings, errors, performance timings, revenue transactions, and Google Search Console data. Historical backfill only includes native events still stored in Swetrix.

The built-in BigQuery connector supports up to 10 GiB of uncompressed export data per project per UTC day, combining both tables. For larger days, use the streaming export API in your own pipeline.

Dashboard totals can differ from a warehouse query if the dashboard includes imported data, uses a different timezone, or applies filters. Visitor IDs are Swetrix's analytics identifiers; they are not Google Analytics client IDs or permanent identities across days. profile_id is populated only where an event was associated with a profile.

Connect BigQueryCopy Anchor Link

1. Prepare Google CloudCopy Anchor Link

1. Choose a Google Cloud project and enable the BigQuery API.
2. Create a dataset for Swetrix, for example swetrix_analytics. Note its Dataset ID and Data location. The location in Swetrix must match the dataset, for example EU, US, or europe-west2. See Google's dataset location guide.
3. Create a dedicated service account for the integration.
4. Grant that service account BigQuery Job User (roles/bigquery.jobUser) on the Google Cloud project and BigQuery Data Editor (roles/bigquery.dataEditor) on the destination dataset. This lets it run load jobs and manage the destination tables. You do not need to grant project-wide BigQuery Admin access. See Google's BigQuery roles reference.
5. Create and download a JSON key for the service account. See Google's service account key instructions. If your organisation prohibits service account keys, use the export API from an approved pipeline instead.

Swetrix uploads directly to BigQuery; a Cloud Storage bucket is not required. Google charges your account for applicable storage and query usage. Review BigQuery pricing when choosing retention and BI queries.

2. Configure the connection in SwetrixCopy Anchor Link

Open Project Settings → Data warehouse and enter:

Test the connection, then save it. Testing checks dataset access, location, and job permissions, and creates missing export tables. It does not export event data. Swetrix creates and manages its own export tables; use a fresh prefix rather than the name of an existing business table. One BigQuery connection can be configured per Swetrix project.

The saved private key is encrypted and is never returned by the settings API. When editing an existing connection, leave the credential field empty to keep its saved key. To rotate credentials, supply a new JSON key, save and verify a successful sync, then revoke the old key in Google Cloud.

3. Follow the first syncCopy Anchor Link

The first sync works through completed UTC days from your start date through yesterday. The settings page shows whether it is queued, syncing, or has failed, together with its progress and last successful sync.

After backfill, Swetrix schedules daily exports from 06:00 UTC and refreshes the three most recent completed days to pick up late-arriving data. Actual completion depends on queue and data volume. Today's events are available after the UTC day has ended; this is not a real-time stream.

Each load replaces one day's partition in one table. Retrying a day therefore does not append another copy of its events. The two tables are loaded separately, so an interrupted sync can temporarily leave them at different dates; a successful retry completes the day.

Use Sync now to request another sync. Pausing or disconnecting stops subsequent work, although a day already being uploaded can finish. Disconnecting removes the connection and its saved credentials from Swetrix; it leaves the exported tables in BigQuery.

Swetrix manages the contents and schema of its export tables. Keep your derived metrics, joins, and manually inserted data in separate tables or views. A refreshed partition replaces its existing rows.

Changing destination settings or the start date restarts backfill from the configured start date. Rotating only the service account key preserves progress. Wait for the current export to finish before making these changes. A change of project ownership disables the saved connection; the new owner must save it with a new service account key to resume delivery and restart backfill.

After a plan downgradeCopy Anchor Link

When the project owner's plan no longer includes warehouse exports, Swetrix disables scheduled delivery. Queued jobs and running syncs recheck plan access before exporting each day; a day already being uploaded can finish. The saved connection, credentials, and backfill progress are retained, and previously exported BigQuery data stays in your account.

You can still view the connection's status, pause it, or disconnect it. Creating or editing a connection, testing it, resuming delivery, syncing manually, and using the raw export API require Plus or Enterprise. After upgrading, choose Resume to continue from the saved progress.

Query the exported dataCopy Anchor Link

Replace the example project, dataset, and prefix with your settings. Include an event_date filter to limit the partitions scanned.

SELECT
  event_date,
  COUNT(*) AS pageviews,
  COUNT(DISTINCT visitor_id) AS visitors
FROM `company-analytics.swetrix_analytics.swetrix_example_pageviews`
WHERE event_date BETWEEN DATE '2026-10-01' AND DATE '2026-10-07'
GROUP BY event_date
ORDER BY event_date;

SELECT
  event_name,
  COUNT(*) AS events
FROM `company-analytics.swetrix_analytics.swetrix_example_custom_events`
WHERE event_date = DATE '2026-10-01'
GROUP BY event_name
ORDER BY events DESC;

SELECT
  timestamp,
  event_name,
  (SELECT value FROM UNNEST(metadata) WHERE key = 'plan' LIMIT 1) AS plan
FROM `company-analytics.swetrix_analytics.swetrix_example_custom_events`
WHERE event_date = DATE '2026-10-01'
  AND event_name = 'signup';

To build a BI dashboard, connect your tool to the dataset using its own Google credentials. Swetrix's service account is for delivering data; dashboard viewers should use the access permissions you configure in Google Cloud.

Export schemaCopy Anchor Link

The BigQuery tables and export API use these fields. Strings can be null when no value was recorded. IDs are strings to preserve their full precision in tools that cannot safely represent large integers.

The export does not add raw IP addresses. Page paths, profile identifiers, and custom metadata retain the values you send to Swetrix, so apply your own access and retention rules to the warehouse copy.

Deleting data in Swetrix does not automatically delete every previously exported copy. Recent partitions can change when refreshed; older partitions, downstream tables, backups, and exports must be removed in your warehouse when required.

Export API for other warehousesCopy Anchor Link

Use the raw export API to load Snowflake, Redshift, object storage, or another destination from your own scheduled job. A BigQuery connection is not required, but the project owner must have Plus or Enterprise.

From the project owner's account, create a scoped API key with Analytics: Read only, Events: Read only, and access to the selected project. Scoped keys currently select projects owned by that account. Public dashboard access, a dashboard password, or read-only sharing does not grant raw export access.

GET https://api.swetrix.com/v1/data-export/PROJECT_ID/events?date=YYYY-MM-DD&type=pageviews

The response is application/x-ndjson: one JSON object per line, using the schema above. An empty day produces an empty response body. The request streams the selected day's events; it is not a dashboard breakdown limited to a fixed number of rows.

curl --fail --show-error \
  'https://api.swetrix.com/v1/data-export/YOUR_PROJECT_ID/events?date=2026-10-01&type=pageviews' \
  -H "X-Api-Key: $SWETRIX_API_KEY" \
  --output pageviews-2026-10-01.ndjson.part || exit 1
mv pageviews-2026-10-01.ndjson.part pageviews-2026-10-01.ndjson || exit 1

curl --fail --show-error \
  'https://api.swetrix.com/v1/data-export/YOUR_PROJECT_ID/events?date=2026-10-01&type=custom_events' \
  -H "X-Api-Key: $SWETRIX_API_KEY" \
  --output custom-events-2026-10-01.ndjson.part || exit 1
mv custom-events-2026-10-01.ndjson.part custom-events-2026-10-01.ndjson || exit 1

For a reliable pipeline:

1. Fetch both event types for each completed UTC day, keeping the API key in your scheduler's secret store.
2. Download into a temporary file and only publish or load it after the request completes successfully. Discard partial downloads on failure.
3. Load into staging tables, then replace that project's destination partition for the selected day. Do not append a retry: the source does not provide a unique event ID for deduplication.
4. Advance your checkpoint only after both loads succeed. Re-fetch the three most recent completed days to pick up late arrivals.
5. Retry transient errors and 429 responses with backoff. API requests share the account's API rate limit.

Invalid dates or event types return a client error. Missing or invalid credentials return 401; insufficient permissions return 403. A project owner's plan without warehouse access returns 402. If the connection closes during a streamed response, treat the entire download as incomplete even if some valid JSON lines were received.

For aggregated reports rather than individual events, use the Statistics API v2. Its existing availability on Standard is unchanged; the Plus requirement applies to the warehouse connector and raw export API.

TroubleshootingCopy Anchor Link

Help us improve Swetrix

Was this page helpful to you?

YesNo

Learn how to contribute•Report a problem with this content