Documentation Index

Fetch the complete documentation index at: https://docs.supermetrics.com/llms.txt

Use this file to discover all available pages before exploring further.

Google BigQuery connection guide

  • Updated on Jul 8, 2026
  • Published on Jun 25, 2025
Prev Next

This guide contains all permissions and requirements for connecting your Google BigQuery data to Supermetrics.

You can connect to data sources from the Data sources page on the Supermetrics Hub. On the Hub, you can also share an authentication link to connect to a data source you don't have direct access to.

After you connect to the data source on the Hub, you can use the data source connection in all available destinations.

Required permissions

There are 2 ways to authenticate Google BigQuery: with OAuth 2.0, or with a service account.

Permissions when connecting with OAuth 2.0

You need a Google account with access to view and manage tables in BigQuery in Google Cloud in order to connect.

Required Google Account permissions:

  • View and manage your tables, datasets, and jobs in Google BigQuery.

  • See the email address for your Google Account.

Permissions when connecting with a service account

  1. Create a service account:

    1. Create a service account and assign sufficient permissions for it, for example:

      1. roles/bigquery.user (project-level)

      2. roles/bigquery.dataViewer (dataset-level)

      Detailed instructions are available in Google’s documentation.

  2. Create and obtain a private JSON key for the service account:

    1. In the Google Cloud console, go to the Service accounts page.

    2. Go to Service accounts and select a project.

    3. Click the email address of the service account you want to create a key for.

    4. Click the Keys tab.

    5. Click the Add key drop-down menu, then select Create new key.

    6. Select JSON as the Key type and click Create.

    7. To authenticate the connector, use the following values from the JSON file:

      1. Private key: The complete string from - - - - - BEGIN PRIVATE KEY - - - - - to - - - - - END PRIVATE KEY - - - - -\n

      2. Key ID

      3. Client email

      For more details on creating keys, refer to Google’s documentation.

Before you start the authentication process

Obtain your table ID

  1. Identify the BigQuery table you wish to connect to in the Google Cloud console.

  2. In the left-hand Explorer section, click the three dots next to the table.

  3. Select Copy ID and save this for later.

Note

The Table ID must be in the format project.dataset.table with exactly three dot-separated parts, such asmy-project.my_dataset.my_table. A common mistake is copying only the project and dataset (such as my-project.my_dataset) without the table name. This will cause a "Not Found" error.

Sharded tables

Sharded tables are used, for example, for Google Analytics 4 events.

If your BigQuery dataset uses date-sharded tables (such as events_20240101, events_20240102, …), use a wildcard suffix _* to query all shards: my-project.my_dataset.events_*.

Entering a single shard like events_20240101 queries only one day's data. Use it only if desired.

Don’t enter just the prefix without _* (such as events). This will fail with a "Table not found" error.

Example table IDs

Valid table IDs:

  • my-project.analytics_123456.events_* (sharded/wildcard

  • my-project.my_dataset.orders (single table)

  • my-project.my_dataset.daily_report_* (sharded/wildcard)

Invalid table IDs:

  • my-project.my_dataset (missing table name)

  • my-project.my_dataset.events_20240101 (single shard — use events_* instead)

Troubleshooting

Error

Cause

Fix

The table ID you inserted is incorrect

Table doesn't exist or the Table ID is missing the _* suffix for sharded tables.

Verify the table exists in BigQuery console. For sharded tables, add _* suffix.

Invalid Table ID

Table ID has fewer than 3 parts (missing table name).

Use format project.dataset.table.

Data Source Error: Not Found

DSU properties couldn't be resolved.

Re-connect with a valid 3-part Table ID.

Identify your date column

  1. Select your table in the Google Cloud console and open the Schema tab.

  2. Copy the field name of the column you want to use for date range filtering.

    Please note that your BigQuery table must have a DATE or DATETIME column to fetch data for specific date ranges.

Query types

If prompted, you need to select a query type to pull data.

  • Table: Fetch data from your table in BigQuery.

Connection instructions

When connecting to Google BigQuery using OAuth 2.0

  1. You need to be logged in with your Google Account.

  2. Select the Google BigQuery data source on the Supermetrics Hub or in the data destination.

  3. Insert the table ID.

  4. If prompted, choose to make this connection shared or private.

  5. Click Start.

  6. In your data destination, fill in the value for the Date column setting.

When connecting to Google BigQuery using a service account

  1. Select the Google BigQuery data source on the Supermetrics Hub or in the data destination.

  2. Insert the table ID, Private key, Key ID, and Client email.

  3. If prompted, choose to make this connection shared or private.

  4. Click Start.

  5. In your data destination, fill in the value for the Date column setting.

You can also connect to Google BigQuery from these destinations:

More resources

© Supermetrics 2026