Documentation Plugins Google BigQuery Query editor

Google BigQuery query editor

This document explains how to use the Google BigQuery query editor to build and run queries in Grafana.

Before you begin

Before using the query editor:

• Configure the Google BigQuery data source.
• Verify your credentials have appropriate permissions to query the datasets you need.

Query editor modes

The BigQuery data source provides two query editor modes, which you can switch between using the Builder / Code toggle in the query editor header:

• Builder (Visual query editor): Build queries without writing SQL using a point-and-click interface.
• Code (SQL query editor): Write raw SQL queries with autocompletion and validation.

Query editor header

The query editor header includes the following options:

SQL query editor

The SQL query editor provides a rich editing experience for writing BigQuery Standard SQL queries.

Autocompletion

The SQL query editor includes autocompletion for:

• BigQuery Standard SQL syntax: Keywords, functions, and operators.
• Schema objects: Datasets, tables, and columns from your BigQuery project.
• Macros: Grafana macros like $__timeFilter and $__timeGroup.
• Template variables: Dashboard variables you’ve defined.

To trigger autocompletion, press Ctrl+Space (Windows/Linux) or Cmd+I (macOS).

Query validation

The SQL query editor validates your query as you type. If the query contains errors, the editor displays information about what’s wrong.

When the query is valid, the editor shows an estimated query size, helping you understand the data volume before running the query.

Extended code editor

For complex queries, use the full-screen code editor. Click the expand button (double arrow icon) in the query toolbar to open the extended editor.

Format query

Click the Format query button (brackets icon) in the query toolbar to automatically format your SQL code for better readability.

Keyboard shortcuts

Visual query editor

The Visual query editor lets you build BigQuery queries without writing SQL. It’s useful for users who aren’t familiar with SQL or for building simple queries quickly.

Resource selectors

In Builder mode, the query editor header displays resource selectors:

Query building

The Visual query editor supports the following sections (toggle visibility using the switches in the header):

Aggregation functions

The following aggregation functions are available:

• AVG - Average value
• COUNT - Count of rows
• MIN - Minimum value
• MAX - Maximum value
• SUM - Sum of values
• STDDEV - Standard deviation
• VARIANCE - Variance

The Visual query editor validates your query as you build it, similar to the SQL query editor.

Query as time series

To visualize data as a time series:

1. Include a TIMESTAMP column in your query.
2. The timestamp column is used as the time axis.
3. All other columns are treated as value columns.

Time series example

SQL Copy

SELECT
  timestamp_column AS time,
  value_column,
  metric_name
FROM `project.dataset.table`
WHERE $__timeFilter(timestamp_column)
ORDER BY timestamp_column

Multi-series time series

To display multiple series (for example, metrics by region), include a label column. Each unique value creates a separate series:

SQL Copy

SELECT
  $__timeGroup(timestamp_column, $__interval) AS time,
  region,
  AVG(metric_value) AS value
FROM `project.dataset.metrics`
WHERE $__timeFilter(timestamp_column)
GROUP BY time, region
ORDER BY time

Query as table

Table visualizations work with any valid BigQuery query. You don’t need to include a timestamp column for table results.

Table example

SQL Copy

SELECT
  user_id,
  user_name,
  email,
  created_at
FROM `project.dataset.users`
LIMIT 100

Macros

Macros simplify queries by providing dynamic values based on the dashboard context. Use macros to filter data by the dashboard time range without hardcoding dates.

Macro examples

The following examples demonstrate common macro usage patterns.

Filter by time range

Use $__timeFilter to filter data to the dashboard’s selected time range:

SQL Copy

SELECT
  timestamp_column AS time,
  value_column
FROM `project.dataset.table`
WHERE $__timeFilter(timestamp_column)

Group by time interval

Use $__timeGroup to aggregate data into time buckets:

SQL Copy

SELECT
  $__timeGroup(timestamp_column, $__interval) AS time,
  AVG(value_column) AS avg_value
FROM `project.dataset.table`
WHERE $__timeFilter(timestamp_column)
GROUP BY time
ORDER BY time

Use time boundaries

Use $__timeFrom() and $__timeTo() when you need explicit time boundaries:

SQL Copy

SELECT
  COUNT(*) AS total_events,
  $__timeFrom() AS period_start,
  $__timeTo() AS period_end
FROM `project.dataset.events`
WHERE timestamp_column BETWEEN $__timeFrom() AND $__timeTo()

Query partitioned tables

BigQuery partitioned tables improve query performance and reduce costs. The query editor provides autocompletion for partition filters.

Ingestion-time partitioned tables

For tables partitioned by ingestion time, filter on _PARTITIONTIME:

SQL Copy

SELECT
  timestamp_column AS time,
  value_column
FROM `project.dataset.partitioned_table`
WHERE _PARTITIONTIME BETWEEN $__timeFrom() AND $__timeTo()
  AND $__timeFilter(timestamp_column)

Storage API

The plugin supports the BigQuery Storage API for reading large result sets more efficiently.

To enable the Storage API:

• Code mode: Toggle Use Storage API in the query header.
• Builder mode: Expand the Options section at the bottom and toggle Use Storage API.

Query options

The query editor provides additional options depending on the mode:

Code mode options

In Code mode, access the Use Storage API toggle directly in the query header.

Builder mode options

In Builder mode, expand the Options section at the bottom of the query editor to access:

Next steps

• Use template variables to create dynamic dashboards
• Add Transformations to manipulate query results
• Set up Alerting rules based on your BigQuery data