Missed London? Beyond the Map goes live online on Dec 8.

Save your spot →

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

  1. Go to Settings > Integrations in TheyDo.
  2. 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.

  1. 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, or NUMERIC

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.

  1. 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.
  2. In TheyDo, go to Settings > Integrations and open your BigQuery integration.
  3. In the Service account key section, click Replace key.

image.png

  1. Paste the new JSON key, or upload the .json file, and submit.

image.png

  1. 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.

Further reading