BigQuery integration
Connect TheyDo to BigQuery to pull warehouse data into your metrics. Once set up, your metrics will update automatically from BigQuery — no manual data entry needed.
Before you start
- You need integration-management permission in TheyDo.
- We recommend working with a data analyst or BigQuery account owner during setup.
- Have a BigQuery table ready to test the connection — you'll need its full table reference in the format
project_id.dataset_id.table_name.
Need help getting started? Reach out to support@theydo.com with the subject line "BigQuery Integration" and the team will walk you through it.
How to set up the BigQuery integration
- Go to Settings > Integrations in TheyDo.
- Find BigQuery under Data integrations and select Enable.
Step 1: Add your service account key
Provide a Service Account JSON Key from your Google Cloud project. The service account needs the BigQuery User and BigQuery Data Viewer roles on the project that holds your data.
Tip: Use a service account dedicated to TheyDo, not one shared with other tools. This makes it easier to rotate the key later without affecting anything else.
Step 2: Name your instance
Enter an Instance Name — this is how this connection will appear in TheyDo. Useful if you plan to connect multiple BigQuery instances.
Step 3: Test your connection
Enter the full reference of a BigQuery table to verify the connection:
project_id.dataset_id.table_name
You can find this under Details > Table ID in BigQuery. TheyDo uses this to confirm it has the right permissions and can access your data.
- Click Test and authorize to complete the setup.
Adding multiple instances: You can connect more than one BigQuery instance by repeating these steps.
Prepare your data in BigQuery
Your tables need to return the correct columns for each metric type:
| Metric type | Required columns |
|---|---|
| CSAT | date, positives, negatives, respondents |
| CES | date, respondents, value |
| NPS | date, detractors, promoters, respondents |
| RATIO | date, numerator, denominator |
| OTHER | date, value |
For the Other metric type, TheyDo pulls a pre-calculated average value — make sure that value is already computed in your BigQuery data.
Supported data types:
- Date columns:
DATE - Metric value columns:
INTEGER,FLOAT, orNUMERIC
Column aliasing: If your table uses different column names, use SQL aliasing in your query. For example:
SELECT det AS detractors, ... FROM project_id.dataset_id.your_table_name
Dimensions
Any extra columns in your query, like country, product, channel, or segment, automatically become dimensions you can filter by in TheyDo.
This means you can write one query and create multiple filtered views of the same metric, instead of writing a separate query for every variation.
Rotate your service account key
Many security teams require service account keys to be replaced on a schedule, or straight away if a key may have been exposed. You can replace the key TheyDo uses at any time, without interrupting your metrics: before switching, TheyDo runs every metric query on the connection with the new key, and only swaps once they all pass. If anything fails, your current key stays in place.
- In Google Cloud, open
IAM & Admin > Service Accounts, select the service account TheyDo uses, and create a new JSON key. Keep the old key for now. - In TheyDo, go to
Settings > Integrationsand open your BigQuery integration. - In the
Service account keysection, clickReplace key.

- Paste the new JSON key, or upload the
.jsonfile, and submit.

- Once you see the success message, delete the old key in Google Cloud.
If verification fails, TheyDo lists each metric that couldn't run with the new key, along with the error from BigQuery. This usually means the service account is missing access to a dataset or table: fix it in Google Cloud and submit again. If the connection has no metrics yet, TheyDo asks for a table reference (project_id.dataset_id.table_name) to test the key against instead.
Note: If the same service account is used by more than one BigQuery connection in TheyDo, replace the key on each of them before deleting the old key in Google Cloud. Every rotation is recorded in your organization's activity log.