Setting Up BigQuery with Contextflo

Step-by-step guide to create a GCP service account and connect BigQuery to Contextflo

Last updated: 2/7/2026

Connect Google BigQuery to Contextflo to analyze your data warehouse tables with natural language queries. This guide walks you through the complete setup process.

Prerequisites

Before you begin, make sure you have:

  • A Google Cloud Platform (GCP) account with access to BigQuery
  • Admin permissions to create service accounts in your GCP project
  • The project ID and dataset location where your tables are stored

Step 1: Note Your Dataset Location and Project

This is critical: BigQuery datasets are region-specific. You need to know the exact location where your data is stored.

Finding Your Dataset Location

  1. Go to the BigQuery Console
  2. In the Explorer panel on the left, expand your project
  3. Click on the dataset you want to connect to Contextflo
  4. In the details panel, look for Data location
  5. Write down the exact location - this could be:
    • Multi-region: US, EU
    • Specific region: us-central1, europe-west1, asia-southeast1, etc.

Note Your Project ID

While viewing your dataset:

  1. Your Project ID appears at the top of the BigQuery Console
  2. It's typically in the format: my-project-name or my-company-prod-123
  3. Write this down - you'll need it in Contextflo

Important: Using the wrong location is the #1 cause of connection issues. If you enter US but your data is in us-central1, Contextflo won't be able to list your tables.

Step 2: Create a Service Account

Contextflo uses a service account to securely access your BigQuery data. Here's how to create one with the right permissions:

Create the Service Account

  1. Go to the Service Accounts page in GCP Console
  2. Make sure you're in the correct project (check the project selector at the top)
  3. Click "Create Service Account"
  4. Fill in the details:
    • Service account name: contextflo-reader (or any descriptive name)
    • Service account ID: Will auto-populate based on the name
    • Description: "Service account for Contextflo to read BigQuery tables"
  5. Click "Create and Continue"

Grant Required Permissions

The service account needs two specific roles to work with Contextflo:

Required Roles:

  1. BigQuery Job User (roles/bigquery.jobUser)

    • Allows Contextflo to run queries against your datasets
    • Required for listing and exploring table schemas

  2. BigQuery Data Viewer (roles/bigquery.dataViewer)

    • Allows read-only access to your tables and metadata
    • Ensures Contextflo can see table structures

How to Assign the Roles

In the service account creation wizard (Step 2):

  1. Click "Select a role" dropdown
  2. Search for "BigQuery Job User" and select it
  3. Click "Add Another Role"
  4. Search for "BigQuery Data Viewer" and select it
  5. Click "Continue"
  6. Skip the optional "Grant users access" step - click "Done"

Note: These are the minimum permissions needed. If you want to grant access to specific datasets only (not all datasets in the project), see the "Advanced: Dataset-Level Permissions" section below.

Step 3: Download the Service Account Credentials

Now you need to download the JSON key file that Contextflo will use to authenticate:

  1. On the Service Accounts page, find your newly created service account
  2. Click on the service account email to open its details
  3. Go to the "Keys" tab
  4. Click "Add Key" → "Create new key"
  5. Select "JSON" as the key type
  6. Click "Create"
  7. The JSON key file will automatically download to your computer
  8. Store this file securely - it contains credentials to access your BigQuery data

Security Best Practice: Never commit this JSON file to version control (git). Store it securely and only upload it directly to Contextflo.

Step 4: Connect BigQuery in Contextflo

Now you're ready to connect BigQuery to Contextflo:

  1. Log in to Contextflo

  2. During onboarding (or from the Data Sources page's Data Warehouses & Databases section), click "+ Add a new connection"

  3. Select "Google BigQuery"

  4. Fill in the connection details:

    • Connection Name: A friendly name (e.g., "Production BigQuery")
    • Description (optional): Add context about this connection
    • Project ID: The project ID you noted in Step 1
    • Location: The exact location you noted in Step 1 (e.g., US, us-central1)
    • Service Account JSON: Click "Choose File" and upload the JSON key you downloaded

  5. Click "Test Connection" to verify everything works

  6. If successful, click "Connect"

What Happens Next

After connecting:

  1. Contextflo will fetch the list of available datasets in your project
  2. You'll be able to select which tables to sync
  3. Contextflo will analyze the table schemas and make them queryable with natural language

Troubleshooting

"Unable to load tables from this data source"

Cause: This usually means the Location field doesn't match where your data is actually stored.

Solution:

  1. Double-check your dataset location in the BigQuery Console
  2. Click "Edit Connection" in Contextflo
  3. Update the Location field with the exact value from BigQuery
  4. Try again

Common mismatches:

  • Entered US but data is in us-central1
  • Entered us-central1 but data is multi-region US
  • Typo in the region name

"Permission denied" errors

Cause: The service account doesn't have the required permissions.

Solution:

  1. Go to IAM & Admin in GCP Console
  2. Find your service account in the principals list
  3. Verify it has both BigQuery Job User and BigQuery Data Viewer roles
  4. If not, click the pencil icon to edit and add the missing roles

"Project not found"

Cause: The Project ID is incorrect or the service account doesn't have access.

Solution:

  1. Verify the exact Project ID from the BigQuery Console
  2. Make sure you're using the Project ID (not the project name or number)
  3. Ensure the service account was created in the same project

Advanced: Dataset-Level Permissions

If you want to restrict Contextflo's access to specific datasets only (not the entire project):

  1. Don't assign project-level roles to the service account
  2. Instead, go to the specific dataset in BigQuery Console
  3. Click "Sharing" → "Permissions"
  4. Click "Add Principal"
  5. Enter your service account email (e.g., [email protected])
  6. Assign these dataset-level roles:
    • BigQuery Data Viewer
  7. Also assign BigQuery Job User at the project level (this can't be dataset-scoped)

Security Notes

  • Read-only access: This setup only grants SELECT permissions. Contextflo cannot modify or delete your data.
  • Rotate keys regularly: Consider rotating service account keys every 90 days.
  • Never commit credentials: Add JSON key files to .gitignore.
  • Limit dataset access: Grant dataset-level permissions instead of project-level for tighter security.

Next Steps