TrailSpark

Connecting BigQuery

Overview

Go to Settings > Integrations > BigQuery to connect your data warehouse. All three connection options are read-only — TrailSpark never writes to your warehouse.

Prerequisites

  • A Google Cloud project ID that owns the data you want to sync
  • Access to Settings > Integrations in your TrailSpark workspace
  • If you'll authorize a service account or upload your own key: permission (yours or a Google Cloud admin's) to grant IAM roles or create a service account key

Choosing a connection option

OptionHow it worksWhen to use it
We connect with a Google service account you authorizeYou create a service account in your own project, named exactly as the connection screen shows you, give it read access to your data, and grant TrailSpark's account permission to use it. Three quick grants, no keys to manage.Recommended for production. It isn't tied to any one person's Google login, so nothing breaks if a teammate leaves or loses access.
Sign in with GoogleYou sign in with your own Google account, the same way you would for any "Sign in with Google" button.The fastest way to try the connector. Only appears if Google sign-in has been turned on for your TrailSpark workspace.
Upload a service account keyYou create your own service account key in Google Cloud and paste the key file's contents in. TrailSpark encrypts it at rest and never displays it again.Good if you'd rather not wait on any approval and you're comfortable managing the key yourself.

Step 1: Enter your project details

Click Add connection (or Connect BigQuery if this is your first one). Fill in:

  • Connection name — a label to tell this connection apart from others (e.g., "Production warehouse")
  • Project ID — your Google Cloud project that owns the data (e.g., my-gcp-project)
  • Region — the BigQuery location your dataset lives in (e.g., US, EU, europe-west1)
Every query TrailSpark runs executes in the region you enter. If your data lives in an EU dataset, your queries run in the EU — TrailSpark doesn't need to copy or move your data to run a sync.

Step 2: Choose how to connect

Under How should we connect?, pick one of the options described above.

Authorizing a Google service account

Select We connect with a Google service account you authorize. TrailSpark walks you through three grants, all in your own Google Cloud project:

  1. Create a service account with the exact name shown. TrailSpark shows a name like trailspark-sync-ab12cd34 with a copy button. Create a service account with that name, exactly — that name is what proves the account was created for your workspace, and TrailSpark checks it when you save. (The name is specific to your workspace; you'll only ever see your own.)

  2. Give it read access to your data — grant the new service account exactly two roles and nothing more:

    • BigQuery Job User (roles/bigquery.jobUser) on your project — lets it run query jobs. Queries run under your project, so your existing BigQuery quotas, region, and billing apply, and you can see every query TrailSpark runs in your project's job history.
    • BigQuery Data Viewer (roles/bigquery.dataViewer) on the specific datasets you want synced — read access to just those datasets.

    It never needs write access to anything in your project.

  3. Let TrailSpark use it. TrailSpark also shows a service-account email of its own, with a copy button. On the account you just created, grant that email the Service Account Token Creator role. This is what lets TrailSpark run your syncs as that account — with no long-lived key for anyone to leak.

Then paste the new service account's full email into Paste the service account's email and save. If the name doesn't match what the screen showed, TrailSpark tells you exactly what to rename it to.

If this option shows a "not enabled on this deployment yet" note, it hasn't been turned on for your workspace. Use Sign in with Google or Upload a service account key instead, or ask your TrailSpark contact to enable it.

Signing in with Google

If Sign in with Google appears as an option, select it and click Sign in with Google. You'll be sent to Google's own sign-in flow. Your own Google account almost certainly already has both roles above — the two grants are what you'd give a service account instead.

Uploading a service account key

Select Upload a service account key, then paste the full contents of the JSON key file you downloaded from Google Cloud into Service account key (JSON). TrailSpark stores it encrypted and never displays it again. The service account behind that key needs the same two roles listed above.

When you're ready, click Connect to save the connection (or Sign in with Google, if that's the option you selected — this sends you to Google's sign-in flow instead).

Step 3: Test the connection

Once a connection is saved, click Test connection to confirm TrailSpark can reach your project before creating any syncs. A successful test shows "We reached your BigQuery project." If it fails, the error message tells you what to check — usually a missing IAM role or an incorrect project ID.

If a connection that used Sign in with Google stops working later on — access was revoked, or a Google Workspace admin changed something — you'll see a Reconnect your Google account option on that connection. See Schedules and Run History for what to do.

Next Steps