--- title: "Configure the Google BigQuery data source | Grafana Plugins documentation" description: "Configure the Google BigQuery data source plugin for Grafana" --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # Configure the Google BigQuery data source This document explains how to configure the Google BigQuery data source in Grafana. ## Before you begin Before configuring the data source, ensure you have: - **Grafana version:** Plugin version 3.x requires Grafana 11.6.11 or later. On Grafana 12.x, the plugin also requires these minimum patch versions: 12.0.10, 12.1.7, or 12.2.5, depending on your minor release. For older Grafana versions, use plugin version 2.x (requires Grafana 10.4.8 or later) or 1.x. - **Grafana permissions:** `Organization administrator` role to add data sources. - **Google Cloud APIs enabled:** The following APIs must be enabled on each GCP project you query: - [BigQuery API](https://console.cloud.google.com/apis/library/bigquery.googleapis.com) - [Cloud Resource Manager API](https://console.cloud.google.com/apis/library/cloudresourcemanager.googleapis.com) - **Google Cloud credentials:** Depending on your authentication method, you need either a service account key file or Grafana running on Google Compute Engine with a default service account. - **Required GCP IAM roles:** The service account (or impersonated service account) must have the following roles on each project it accesses: - **BigQuery Data Viewer** (`roles/bigquery.dataViewer`): read access to BigQuery data - **BigQuery Job User** (`roles/bigquery.jobUser`): permission to run BigQuery jobs - **`resourcemanager.projects.get`** permission: required for the project drop-down to populate in the query editor. This permission is included in the **Browser** role (`roles/browser`) or can be granted through a custom role. Grant **BigQuery Data Viewer** and **BigQuery Job User** at the **project** level when you can. Those project-level roles cover querying and listing datasets in that project. They aren’t sufficient by themselves if you only grant access on individual datasets or tables: - The query editor dataset drop-down uses the BigQuery `datasets.list` API, which returns only datasets the caller can get. If the service account isn’t a dataset [READER](https://cloud.google.com/bigquery/docs/control-access-to-resources-iam#grant_access_to_a_dataset) (or doesn’t have `bigquery.datasets.get` on that dataset), the dataset doesn’t appear in the drop-down. Refer to [datasets.list](https://cloud.google.com/bigquery/docs/reference/rest/v2/datasets/list). - **Save & test** can still succeed. For IAM details beyond these roles, refer to [BigQuery access control](https://cloud.google.com/bigquery/docs/access-control). > Note > > If the service account has project-level access but not dataset or table-level access, **Save & test** may succeed while individual queries return 403 errors. Ensure the service account has read access to the specific datasets and tables you intend to query. > Note > > The data source has a **Default project** where query jobs run. You can query datasets in other GCP projects from the same data source if the service account has the required roles on those projects. Grant `resourcemanager.projects.get` so those projects appear in the query editor drop-down. ## Key concepts If you’re new to Google Cloud or BigQuery, these terms appear throughout the configuration: Expand table | Term | Description | |----------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------| | **Service account** | A Google Cloud identity used by applications. Grafana authenticates to BigQuery as this account (or impersonates another account). | | **Service account impersonation** | Grafana uses a low-privilege key only to mint short-lived tokens for a second service account that has BigQuery access. | | **Workload Identity Federation (WIF)** | Grafana Cloud exchanges the signed-in user’s external identity for a short-lived Google Cloud token. Available on Grafana Cloud only. | | **Processing location** | The geographic location where BigQuery runs the query. Leave empty for automatic selection. | | **Max bytes billed** | A per-query cost cap. Queries that would scan more than this limit fail instead of running. | ## Add the data source To add the Google BigQuery data source: 1. Click **Connections** in the left-side menu. 2. Click **Add new connection**. 3. Type `BigQuery` in the search bar. 4. Select **Google BigQuery**. 5. Click **Add new data source**. ## Configure settings Expand table | Setting | Description | |-------------|------------------------------------------------------------------| | **Name** | The name used to refer to the data source in panels and queries. | | **Default** | Toggle to make this the default data source for new panels. | ## Authentication The Google BigQuery data source supports multiple authentication methods. Choose the method that best fits your deployment environment. Expand table | Method | Best for | Grafana Cloud | Supports alerting | |-----------------------------------|-----------------------------------------------------------------------------------------------------------------|------------------|-------------------| | **Google JWT File** | Any deployment that can store a service account key | Yes | Yes | | **GCE Default Service Account** | Grafana running on a Google Compute Engine VM | No | Yes | | **Service account impersonation** | Delegating BigQuery access without storing a high-privilege key. An option on JWT or GCE, not a standalone type | Yes | Yes | | **Workload Identity Federation** | Grafana Cloud users authenticating through an external OIDC provider | Yes (Cloud only) | No | | **Forward OAuth Identity** | Using Google OAuth login in Grafana for interactive queries | Yes | No | ### Google Service Account key Use this method when running Grafana outside of Google Cloud Platform, or when you need explicit credentials. To configure service account authentication: 1. [Create a Google Cloud Platform (GCP) Service Account](https://cloud.google.com/iam/docs/creating-managing-service-accounts). 2. Assign the following roles to the service account: - **BigQuery Data Viewer** - Provides read access to BigQuery data - **BigQuery Job User** - Allows running BigQuery jobs 3. Create and download a JSON key file for the service account. Google Cloud Console provides a `.json` key. P12 keys aren’t supported. 4. In the data source configuration, select **Google JWT File** as the authentication type. 5. Upload the JSON key file or paste its contents. ### GCE default service account Use this method when running Grafana on a Google Compute Engine (GCE) virtual machine. When Grafana runs on a GCE virtual machine, it can automatically retrieve the default project ID and authentication token from the metadata server. To use this method: 1. Ensure your virtual machine has a service account configured as the default account. 2. Assign the service account the **BigQuery Data Viewer** and **BigQuery Job User** roles. 3. In the data source configuration, select **GCE Default Service Account** as the authentication type. ### Service account impersonation Use [service account impersonation](https://cloud.google.com/iam/docs/service-account-impersonation) when you need to delegate access to BigQuery without distributing service account keys with broad permissions. With impersonation, the key stored in Grafana has minimal permissions. It can only generate short-lived tokens for a separate service account that has BigQuery access. This means the stored credentials cannot directly read data, reducing risk if they are compromised. This is the recommended secure authentication method for connecting Grafana Cloud to BigQuery. Service account impersonation involves two service accounts: - **Authenticating service account:** The service account whose JSON key is uploaded to Grafana. This account’s only permission is to create access tokens for the impersonated account. It requires the [Service Account Token Creator role](https://cloud.google.com/iam/docs/roles-permissions/iam#iam.serviceAccountTokenCreator) (`roles/iam.serviceAccountTokenCreator`). - **Impersonated service account:** The service account that has permissions to read data from BigQuery. Grafana assumes this account’s identity to run queries. It requires the **BigQuery Data Viewer** and **BigQuery Job User** roles. #### Configure GCP permissions Before configuring the data source in Grafana, set up the required permissions in GCP. Replace `AUTH_SA`, `IMPERSONATED_SA`, and `PROJECT_ID` with your values. Grant the authenticating service account permission to create tokens for the impersonated service account: Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash gcloud iam service-accounts add-iam-policy-binding \ IMPERSONATED_SA@PROJECT_ID.iam.gserviceaccount.com \ --member="serviceAccount:AUTH_SA@PROJECT_ID.iam.gserviceaccount.com" \ --role="roles/iam.serviceAccountTokenCreator" ``` Grant the impersonated service account BigQuery access: Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash gcloud projects add-iam-policy-binding PROJECT_ID \ --member="serviceAccount:IMPERSONATED_SA@PROJECT_ID.iam.gserviceaccount.com" \ --role="roles/bigquery.dataViewer" gcloud projects add-iam-policy-binding PROJECT_ID \ --member="serviceAccount:IMPERSONATED_SA@PROJECT_ID.iam.gserviceaccount.com" \ --role="roles/bigquery.jobUser" ``` #### Configure the data source in Grafana To configure service account impersonation in the data source settings: 1. In the **Authentication** section, select **Google JWT File** as the authentication type. 2. Upload the JSON key file for the **authenticating** service account. 3. Under **Service account impersonation**, turn on **Enable**. 4. Enter the full email address of the impersonated service account in **Service account to impersonate**. 5. Click **Save & test** to verify the connection. ### Workload Identity Federation Use [Google Cloud Workload Identity Federation](https://cloud.google.com/iam/docs/workload-identity-federation) (WIF) to let Grafana users authenticate to BigQuery with an external identity provider (such as Okta or another OIDC provider) instead of a service account key. > Note > > This authentication method is available on **Grafana Cloud** only. Grafana Cloud exchanges the signed-in user’s OIDC ID token for a short-lived Google Cloud access token before the request reaches the plugin. > > Workload Identity Federation and [Forward OAuth Identity](/docs/plugins/grafana-bigquery-datasource/latest/configure/#forward-oauth-identity) are different authentication types. WIF exchanges an OIDC ID token from the identity provider Grafana uses for SSO. Forward OAuth Identity forwards a Google OAuth access token and queries BigQuery as that Google user. If Grafana users sign in with [Google OAuth](/docs/grafana/latest/setup-grafana/configure-security/configure-authentication/google/), use Forward OAuth Identity. Configuring Workload Identity Federation involves three systems: Google Cloud, your Grafana Cloud stack, and the data source itself. #### In Google Cloud 1. Create a [Workload Identity Pool and Provider](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers) that trusts your OIDC identity provider. When configuring the provider, set up attribute mappings so that `google.subject` maps to the relevant claim from your identity provider (for example, `assertion.sub`; the exact mapping depends on your provider’s claim format). 2. Grant the BigQuery permissions needed to run queries. How you grant them depends on whether you use service account impersonation: - **Without impersonation:** grant the WIF pool principal directly: - **BigQuery Data Viewer** - **BigQuery Job User** - **With impersonation:** create a service account, grant it those same roles, then grant the WIF pool principal the **Service Account Token Creator** role on that service account. #### In Grafana Cloud 1. Configure your Grafana Cloud stack’s SSO integration against the same OIDC provider, so the signed-in user’s identity is available for Grafana Cloud to exchange for a Google Cloud access token before the request reaches the plugin. Refer to [Configure OAuth2 authentication](/docs/grafana/latest/setup-grafana/configure-security/configure-authentication/generic-oauth/) for setup details. #### In the data source configuration 1. Open the BigQuery data source settings and select **Workload Identity Federation** as the authentication type. 2. In the **Workload Identity Pool Provider** field, enter the full resource path of your provider: `projects//locations/global/workloadIdentityPools//providers/` > Note > > Use the **project number** (a numeric ID such as `123456789`), not the project ID (such as `my-project`). You can find the project number on the Google Cloud Console home page. 3. If you set up service account impersonation, enter the service account email in the **Service account email** field. If you granted permissions directly to the WIF pool, leave this blank. 4. Enter the **Default project** where your BigQuery queries run. > Note > > Credentials from Workload Identity Federation are tied to the signed-in user’s active session. There is no long-lived credential available to the Grafana backend, so features that run without a user present don’t work, including alerting, scheduled reports, and public dashboards. If you rely on these features, use a service account key (JWT) instead. ### Forward OAuth Identity Use Forward OAuth Identity when you want to use Google OAuth authentication in Grafana with BigQuery. To configure Forward OAuth Identity: 1. Configure [Google OAuth authentication](/docs/grafana/latest/setup-grafana/configure-security/configure-authentication/google/) in Grafana. 2. Add the following scopes to the OAuth application: - `https://www.googleapis.com/auth/bigquery` (required) - `https://www.googleapis.com/auth/drive` (optional, for querying Google Sheets data) 3. In the data source configuration, select **Forward OAuth Identity** as the authentication type. 4. Enter the **Default project** where queries run. > Note > > Credentials from Forward OAuth Identity are tied to the signed-in user’s active session. There is no long-lived credential available to the Grafana backend, so features that run without a user present don’t work, including alerting, scheduled reports, and public dashboards. If you rely on these features, use a service account key (JWT) instead. ## Additional settings Expand the **Additional Settings** section to configure optional settings. Expand table | Setting | Description | |-------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Processing location** | Specifies the [geographic location](https://cloud.google.com/bigquery/docs/locations) where BigQuery processes queries. Options include multi-regional locations (US, EU) and specific regions. Leave empty for automatic location selection. | | **Service endpoint** | Custom network address for the BigQuery API. Use this when connecting through a private endpoint or VPC Service Controls. Example: `https://bigquery.googleapis.com/bigquery/v2/` | | **Max bytes billed** | Limits the bytes billed for a query. Queries that would exceed this limit fail instead of running. Use this to prevent unexpectedly expensive queries. Example: `5242880` (5 MB). | | **Restrict to accessible datasets** | Rejects queries that reference tables outside the projects this data source has access to, for example public datasets. Every query is checked with a dry run before it executes, so tables reached through views are covered. Use IAM to control access within your own projects. | | **Additional allowed datasets** | Only shown when the restriction is enabled. Comma-separated list of datasets outside the accessible projects that queries may also reference, entered as `project.dataset` or `dataset` (in the default project). Use this for public or shared datasets you want to allow. These datasets also show up in the query builder’s project and dataset selectors. Example: `bigquery-public-data.samples` | > Note > > When **Restrict to accessible datasets** is enabled, some statements are rejected because their referenced tables cannot be verified: multi-statement scripts, `EXECUTE IMMEDIATE`, and procedure calls. Run each statement as a separate query instead. Queries referencing 50 or more tables are rejected for the same reason. > > With Forward OAuth Identity the plugin cannot list the projects the signed-in user has access to, so only the default project counts as accessible. Any other dataset needs an entry in **Additional allowed datasets**. ## Verify the connection Click **Save & test** to verify the connection. A successful test displays the message “Data source is working”. If you encounter errors, refer to [Troubleshooting](/docs/plugins/grafana-bigquery-datasource/latest/troubleshooting/). ## Provision the data source You can define the data source in YAML files as part of the Grafana provisioning system. For more information, refer to [Provisioning Grafana data sources](/docs/grafana/latest/administration/provisioning/#data-sources). ### Service account key with private key in secure JSON YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml apiVersion: 1 datasources: - name: BigQuery type: grafana-bigquery-datasource editable: true enabled: true jsonData: authenticationType: jwt clientEmail: defaultProject: tokenUri: https://oauth2.googleapis.com/token secureJsonData: privateKey: ``` ### Service account key with private key path YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml apiVersion: 1 datasources: - name: BigQuery type: grafana-bigquery-datasource editable: true enabled: true jsonData: authenticationType: jwt clientEmail: defaultProject: tokenUri: https://oauth2.googleapis.com/token privateKeyPath: '/etc/secrets/bigquery.pem' ``` ### GCE default service account YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml apiVersion: 1 datasources: - name: BigQuery type: grafana-bigquery-datasource editable: true enabled: true jsonData: authenticationType: gce ``` ### GCE default service account with service account impersonation YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml apiVersion: 1 datasources: - name: BigQuery type: grafana-bigquery-datasource editable: true enabled: true jsonData: authenticationType: gce usingImpersonation: true serviceAccountToImpersonate: defaultProject: ``` ### Service account key with service account impersonation YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml apiVersion: 1 datasources: - name: BigQuery type: grafana-bigquery-datasource editable: true enabled: true jsonData: authenticationType: jwt clientEmail: defaultProject: tokenUri: https://oauth2.googleapis.com/token usingImpersonation: true serviceAccountToImpersonate: secureJsonData: privateKey: ``` ### Workload Identity Federation Available on Grafana Cloud only. YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml apiVersion: 1 datasources: - name: BigQuery type: grafana-bigquery-datasource editable: true enabled: true jsonData: authenticationType: workloadIdentityFederation workloadIdentityPoolProvider: projects//locations/global/workloadIdentityPools//providers/ wifServiceAccountEmail: # optional defaultProject: ``` ### Forward OAuth Identity YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml apiVersion: 1 datasources: - name: BigQuery type: grafana-bigquery-datasource editable: true enabled: true jsonData: authenticationType: forwardOAuthIdentity defaultProject: oauthPassThru: true ``` ### With additional settings YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml apiVersion: 1 datasources: - name: BigQuery type: grafana-bigquery-datasource editable: true enabled: true jsonData: authenticationType: jwt clientEmail: defaultProject: tokenUri: https://oauth2.googleapis.com/token processingLocation: US MaxBytesBilled: 5242880 restrictToAccessibleDatasets: true additionalAllowedDatasets: bigquery-public-data.samples serviceEndpoint: https://bigquery.googleapis.com/bigquery/v2/ secureJsonData: privateKey: ``` ### Provisioning configuration reference Expand table | Key | Type | Description | |--------------------------------|---------|----------------------------------------------------------------------------------------------| | `authenticationType` | string | Authentication method: `jwt`, `gce`, `workloadIdentityFederation`, or `forwardOAuthIdentity` | | `clientEmail` | string | Service account email (required for `jwt`) | | `defaultProject` | string | Default GCP project for queries | | `tokenUri` | string | OAuth token endpoint (required for `jwt`): `https://oauth2.googleapis.com/token` | | `privateKeyPath` | string | Path to private key file (alternative to `secureJsonData.privateKey`) | | `usingImpersonation` | boolean | Enable service account impersonation | | `serviceAccountToImpersonate` | string | Email of service account to impersonate | | `workloadIdentityPoolProvider` | string | WIF provider resource path (required for `workloadIdentityFederation`, Grafana Cloud only) | | `wifServiceAccountEmail` | string | Service account to impersonate via WIF (optional, Grafana Cloud only) | | `oauthPassThru` | boolean | Enable OAuth pass-through (required for `forwardOAuthIdentity`) | | `processingLocation` | string | Query processing location (for example, `US`, `EU`, `us-central1`) | | `MaxBytesBilled` | integer | Maximum bytes billed per query | | `restrictToAccessibleDatasets` | boolean | Reject queries referencing tables outside the projects the data source has access to | | `additionalAllowedDatasets` | string | Comma-separated list of extra datasets to allow (`project.dataset` or `dataset`) | | `serviceEndpoint` | string | Custom BigQuery API endpoint URL | | `enableSecureSocksProxy` | boolean | Enable Secure Socks Proxy (requires Grafana configuration) | Expand table | Secure Key | Type | Description | |--------------|--------|------------------------------------------| | `privateKey` | string | Service account private key (PEM format) | ## Provision with Terraform You can provision the data source using the [Grafana Terraform provider](https://registry.terraform.io/providers/grafana/grafana/latest/docs). ### Service account key hcl ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```hcl resource "grafana_data_source" "bigquery" { type = "grafana-bigquery-datasource" name = "BigQuery" json_data_encoded = jsonencode({ authenticationType = "jwt" clientEmail = "" defaultProject = "" tokenUri = "https://oauth2.googleapis.com/token" }) secure_json_data_encoded = jsonencode({ privateKey = file("path/to/service-account-key.pem") }) } ``` ### GCE default service account hcl ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```hcl resource "grafana_data_source" "bigquery" { type = "grafana-bigquery-datasource" name = "BigQuery" json_data_encoded = jsonencode({ authenticationType = "gce" }) } ``` ### With service account impersonation hcl ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```hcl resource "grafana_data_source" "bigquery" { type = "grafana-bigquery-datasource" name = "BigQuery" json_data_encoded = jsonencode({ authenticationType = "gce" usingImpersonation = true serviceAccountToImpersonate = "" defaultProject = "" }) } ``` ### Workload Identity Federation Available on Grafana Cloud only. hcl ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```hcl resource "grafana_data_source" "bigquery" { type = "grafana-bigquery-datasource" name = "BigQuery" json_data_encoded = jsonencode({ authenticationType = "workloadIdentityFederation" workloadIdentityPoolProvider = "projects//locations/global/workloadIdentityPools//providers/" wifServiceAccountEmail = "" # optional defaultProject = "" }) } ``` ### With additional settings hcl ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```hcl resource "grafana_data_source" "bigquery" { type = "grafana-bigquery-datasource" name = "BigQuery" json_data_encoded = jsonencode({ authenticationType = "jwt" clientEmail = "" defaultProject = "" tokenUri = "https://oauth2.googleapis.com/token" processingLocation = "US" MaxBytesBilled = 5242880 restrictToAccessibleDatasets = true additionalAllowedDatasets = "bigquery-public-data.samples" serviceEndpoint = "https://bigquery.googleapis.com/bigquery/v2/" }) secure_json_data_encoded = jsonencode({ privateKey = var.bigquery_private_key }) } ``` For more information, refer to the [Grafana Terraform provider documentation](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/data_source). ## Import queries from DoiT International BigQuery plugin If you previously used the DoiT International BigQuery community plugin, you can import your existing queries into the Grafana BigQuery data source. To import queries: 1. Open the dashboard containing queries from the DoiT International plugin. 2. Edit each panel and change the data source to Grafana BigQuery. 3. Save the dashboard. > Note > > Imported queries are converted to raw SQL queries. ## Related resources - [Google BigQuery documentation](https://cloud.google.com/bigquery/docs) - [Create a service account](https://cloud.google.com/iam/docs/creating-managing-service-accounts) - [BigQuery IAM roles](https://cloud.google.com/bigquery/docs/access-control) - [Grafana provisioning documentation](/docs/grafana/latest/administration/provisioning/)