Skip to main content
Modus connects to your Google BigQuery data warehouse to automatically catalog your datasets, tables, and views — giving your team instant, AI-powered visibility into your data landscape.

​
Prerequisites

Before you begin, make sure you have:
  • A Google Cloud Platform account with access to BigQuery.
  • A GCP Project containing the BigQuery datasets you want Modus to catalog.
  • Sufficient IAM permissions to create service accounts and assign roles in that project.

​
How It Works

​
1. Connect your BigQuery project

You connect Modus to BigQuery using one of two secure authentication methods:
  • Service Account Key — Provide a GCP service account JSON key with access to your BigQuery project.
  • Workload Identity Federation — A keyless, more secure option that federates authentication between AWS and GCP without exchanging long-lived credentials.
Your credentials are encrypted and stored in AWS Secrets Manager.

​
2. Select your datasets

After connecting, Modus lists all available datasets in your BigQuery project. You choose which datasets you want Modus to analyze — nothing is scanned without your explicit selection.

​
GCP Permissions

Before connecting, grant your service account the required roles. The roles depend on your chosen authentication method.
Choose a permission set based on the level of access you want Modus to have:
For workflows that need to create or modify tables (e.g. materializing results):

​
GCP Setup

Choose your authentication method and follow the corresponding guide.
1

Create a service account

  1. Open the Google Cloud Console and select your project.
  2. Go to IAM & Admin > Service Accounts.
  3. Click + Create Service Account.
  4. Enter a descriptive name (e.g. modus-integration) and click Create and Continue.
2

Assign BigQuery roles

In the Grant this service account access to project step:
  1. Click the Select a role dropdown and add each role from the permissions table above.
  2. Click + Add Another Role to add additional roles as needed.
  3. Click Continue, then Done.
3

Generate and download a JSON key

  1. In the Service Accounts list, find the account you just created.
  2. Click the service account name to open its detail page.
  3. Go to the Keys tab.
  4. Click Add Key > Create new key.
  5. Select JSON as the key type and click Create.
  6. A .json file will download automatically — store it securely. You will paste its contents into Modus in a later step.
Treat this key file like a password. Do not commit it to version control or share it in plaintext.

​
Connect in Modus

1

Open the Integrations page

  1. Log into Modus.
  2. Click Integrations in the left sidebar, then select BigQuery.
  3. Click + New Connection.
2

Fill in connection details

Enter a Connection Name and your Project ID (your Google Cloud project identifier). Then choose an Authentication Method.
Select Service Account Key from the Authentication Method dropdown.Open the JSON key file you downloaded from GCP in a text editor, copy its entire contents, and paste it into the Service Account Key field.
BigQuery connection form — Service Account Key
Treat the JSON key file like a password. Do not commit it to version control or share it in plaintext.
3

Test and save

  1. Click Test Connection to verify Modus can reach your BigQuery project.
  2. Click Save Connection.
4

Select datasets

After saving, Modus will list all available datasets in your project. Select the datasets you want Modus to catalog and analyze, then confirm your selection.

​
Connection form field reference

​
Basic information

​
Connection details

​
Authentication

Select your preferred Authentication Method from the dropdown.

​
Verification

Your BigQuery project is now connected. Modus will begin cataloging the selected datasets, tables, and views so that Modus can provide context-aware answers about your data.
All credentials are encrypted and stored in AWS Secrets Manager. Modus only requests the minimum permissions needed to catalog and query your data. Workload Identity Federation is available as a keyless alternative that avoids long-lived credentials entirely.