Documentation Plugins Google BigQuery Configure

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: 11.6.0 or later (plugin version 3.x). For older Grafana versions, use plugin version 2.x (requires Grafana 10.4.8+) or 1.x.
• Grafana permissions: Organization administrator role to add data sources.
• Google Cloud APIs enabled: The following APIs must be enabled in your GCP project:
  • BigQuery API
  • Cloud Resource Manager API
• Google Cloud credentials: Depending on your authentication method, you need either a service account key file or access to the Google Metadata Server.

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

Authentication

Google BigQuery data source supports multiple authentication methods. Choose the method that best fits your deployment environment.

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.
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.
4. In the data source configuration, select Google Service Account Key as the authentication type.
5. Upload the JSON key file or paste its contents.

Google Metadata Server

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 Google Metadata Server as the authentication type.

Service account impersonation

Use service account impersonation when you need to delegate access to BigQuery without distributing service account keys.

To configure service account impersonation:

1. Ensure the service account used by the plugin has the iam.serviceAccounts.getAccessToken permission. This permission is included in the Service Account Token Creator role (roles/iam.serviceAccountTokenCreator).
2. Ensure the service account being impersonated has the following roles:
   • BigQuery Data Viewer
   • BigQuery Job User
3. In the data source configuration, enable Service Account Impersonation.
4. Enter the email address of the service account to impersonate.

Forward OAuth Identity

Use Forward OAuth Identity when you want to use Grafana’s Google OAuth authentication with BigQuery.

To configure Forward OAuth Identity:

1. Configure Google OAuth authentication 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.

Additional settings

Expand the Additional Settings section to configure optional settings.

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.

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.

Service account key with private key in secure JSON

YAML Copy

apiVersion: 1
datasources:
  - name: BigQuery
    type: grafana-bigquery-datasource
    editable: true
    enabled: true
    jsonData:
      authenticationType: jwt
      clientEmail: <SERVICE_ACCOUNT_EMAIL>
      defaultProject: <DEFAULT_PROJECT_ID>
      tokenUri: https://oauth2.googleapis.com/token
    secureJsonData:
      privateKey: <PRIVATE_KEY>

Service account key with private key path

YAML Copy

apiVersion: 1
datasources:
  - name: BigQuery
    type: grafana-bigquery-datasource
    editable: true
    enabled: true
    jsonData:
      authenticationType: jwt
      clientEmail: <SERVICE_ACCOUNT_EMAIL>
      defaultProject: <DEFAULT_PROJECT_ID>
      tokenUri: https://oauth2.googleapis.com/token
      privateKeyPath: '/etc/secrets/bigquery.pem'

Google Metadata Server

YAML Copy

apiVersion: 1
datasources:
  - name: BigQuery
    type: grafana-bigquery-datasource
    editable: true
    enabled: true
    jsonData:
      authenticationType: gce

Google Metadata Server with service account impersonation

YAML Copy

apiVersion: 1
datasources:
  - name: BigQuery
    type: grafana-bigquery-datasource
    editable: true
    enabled: true
    jsonData:
      authenticationType: gce
      usingImpersonation: true
      serviceAccountToImpersonate: <SERVICE_ACCOUNT_EMAIL>
      defaultProject: <DEFAULT_PROJECT_ID>

Forward OAuth Identity

YAML Copy

apiVersion: 1
datasources:
  - name: BigQuery
    type: grafana-bigquery-datasource
    editable: true
    enabled: true
    jsonData:
      authenticationType: forwardOAuthIdentity
      defaultProject: <DEFAULT_PROJECT_ID>
      oauthPassThru: true

With additional settings

YAML Copy

apiVersion: 1
datasources:
  - name: BigQuery
    type: grafana-bigquery-datasource
    editable: true
    enabled: true
    jsonData:
      authenticationType: jwt
      clientEmail: <SERVICE_ACCOUNT_EMAIL>
      defaultProject: <DEFAULT_PROJECT_ID>
      tokenUri: https://oauth2.googleapis.com/token
      processingLocation: US
      MaxBytesBilled: 5242880
      serviceEndpoint: https://bigquery.googleapis.com/bigquery/v2/
    secureJsonData:
      privateKey: <PRIVATE_KEY>

Provisioning configuration reference

Provision with Terraform

You can provision the data source using the Grafana Terraform provider.

Service account key

hcl Copy

resource "grafana_data_source" "bigquery" {
  type = "grafana-bigquery-datasource"
  name = "BigQuery"

  json_data_encoded = jsonencode({
    authenticationType = "jwt"
    clientEmail        = "<SERVICE_ACCOUNT_EMAIL>"
    defaultProject     = "<DEFAULT_PROJECT_ID>"
    tokenUri           = "https://oauth2.googleapis.com/token"
  })

  secure_json_data_encoded = jsonencode({
    privateKey = file("path/to/service-account-key.pem")
  })
}

Google Metadata Server

hcl Copy

resource "grafana_data_source" "bigquery" {
  type = "grafana-bigquery-datasource"
  name = "BigQuery"

  json_data_encoded = jsonencode({
    authenticationType = "gce"
  })
}

With service account impersonation

hcl Copy

resource "grafana_data_source" "bigquery" {
  type = "grafana-bigquery-datasource"
  name = "BigQuery"

  json_data_encoded = jsonencode({
    authenticationType          = "gce"
    usingImpersonation          = true
    serviceAccountToImpersonate = "<SERVICE_ACCOUNT_EMAIL>"
    defaultProject              = "<DEFAULT_PROJECT_ID>"
  })
}

With additional settings

hcl Copy

resource "grafana_data_source" "bigquery" {
  type = "grafana-bigquery-datasource"
  name = "BigQuery"

  json_data_encoded = jsonencode({
    authenticationType = "jwt"
    clientEmail        = "<SERVICE_ACCOUNT_EMAIL>"
    defaultProject     = "<DEFAULT_PROJECT_ID>"
    tokenUri           = "https://oauth2.googleapis.com/token"
    processingLocation = "US"
    MaxBytesBilled     = 5242880
    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.

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.

Related resources

• Google BigQuery documentation
• Create a service account
• BigQuery IAM roles
• Grafana provisioning documentation