Contextflo Blog

How to Set Up BigQuery with Contextflo: A Complete Guide

Learn how to connect Google BigQuery to Contextflo. This step-by-step guide covers creating a service account with proper permissions, downloading credentials, and uploading them to Contextflo.

December 22, 2025•8 min read•Vivek Sah

Google BigQuery is a serverless cloud data warehouse for analyzing large datasets. Connecting it to Contextflo lets you query your data, define metrics, and build dashboards.

This guide covers the full process: creating a service account with the right permissions, downloading its credentials, and connecting it to Contextflo.

Prerequisites

Before you begin, make sure you have:

  • Admin access to a Google Cloud Platform (GCP) project
  • The BigQuery API enabled in your project
  • Permission to create service accounts and assign IAM roles

Step 1: Create a service account

A service account represents an application rather than a person. Contextflo uses it to read your BigQuery data.

1

Open IAM & Admin

In the Google Cloud Console, open the navigation menu and select IAM & Admin → Service Accounts (or search for "Service Accounts" in the top bar).

2

Create the service account

Click Create service account and fill in the details:

  • Name: contextflo-bigquery
  • ID: auto-generated from the name
  • Description: e.g. "Read-only access for Contextflo"
3

Grant read-only roles

Click Continue and add these two roles:

  • BigQuery Data Viewer: read tables and datasets
  • BigQuery Job User: run queries
Both roles are read-only, so Contextflo cannot modify or delete your data.
BigQuery service account permissions screen showing the two required IAM roles
4

Finish

Click Continue, then Done. You can skip the optional "Grant users access" step.

Step 2: Download the JSON key

Generate a JSON key file for the service account. This is what Contextflo uses to authenticate with BigQuery.

1

Find your service account

In the Service Accounts list, open the contextflo-bigquery account you just created.

2

Add a key

Go to the Keys tab and click Add key → Create new key. Choose JSON, then Create. The file downloads automatically.

The key file contains sensitive credentials. Store it securely and never commit it to version control.

The downloaded file looks like this (sensitive values redacted):

{
  "type": "service_account",
  "project_id": "your-project-id",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
  "client_email": "[email protected]"
}

Step 3: Connect BigQuery to Contextflo

1

Open Data Sources

In Contextflo, go to Data Sources and click Add data source → BigQuery.

2

Fill in the form

  • Project ID: the project_id from the JSON key
  • Location: where your datasets live (e.g. US, EU, us-central1)
  • Service account JSON: upload the downloaded file or paste its contents
3

Test and save

Click Test connection to confirm the credentials work, then Connect to save. If the test fails, check the Project ID, the location, and that the service account has both roles.

Troubleshooting

Permission denied

Cause: The service account is missing the required IAM roles.

Fix: In IAM & Admin, confirm both BigQuery Data Viewer and BigQuery Job User are assigned to the service account.

Invalid JSON

Cause: The key file is incomplete or malformed.

Fix: Re-download the JSON key from the Google Cloud Console, and if pasting, copy the entire file contents.

Project not found

Cause: The Project ID is wrong, or the BigQuery API is not enabled.

Fix: Verify the Project ID, and enable the BigQuery API under APIs & Services → Library.

Location mismatch

Cause: The location does not match where your datasets are stored.

Fix: Use the region of your datasets (e.g. US, EU, us-central1, europe-west1).

Security best practices

  • Keep access read-only. The roles above let Contextflo read and query data, nothing more.
  • Rotate keys periodically. Replacing service account keys (for example every 90 days) limits exposure.
  • Never commit credentials. Add JSON key files to .gitignore.
  • Scope access narrowly. Grant dataset-level access if you only need specific datasets.
  • Monitor usage. Use Google Cloud audit logs to review service account activity.

Next steps

With BigQuery connected, you can define metrics from your tables, organize them into metric trees, ask questions in natural language, and build dashboards.

Learn about metrics →Read about metric trees

Need help?

Email [email protected] or see the data source connection docs.