---
title: "Google BigQuery query editor | Grafana Plugins documentation"
description: "Use the Google BigQuery query editor to build and run queries in Grafana"
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# 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](/docs/plugins/grafana-bigquery-datasource/latest/configure/).
- Verify your credentials have appropriate permissions to query the datasets you need.

## Key concepts

If you’re new to BigQuery queries in Grafana, these terms appear in the editor:

Expand table

| Term                  | Description                                                                                                 |
|-----------------------|-------------------------------------------------------------------------------------------------------------|
| **Standard SQL**      | BigQuery’s SQL dialect. The query editor doesn’t support Legacy SQL.                                        |
| **Macros**            | Tokens such as `$__timeFilter` that Grafana expands from the dashboard time range before sending the query. |
| **Storage API**       | An optional BigQuery API for reading large result sets more efficiently than the standard query API.        |
| **Partitioned table** | A table split by a time or ingestion column so queries can scan less data.                                  |

## 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:

Expand table

| Option                         | Description                                                                       |
|--------------------------------|-----------------------------------------------------------------------------------|
| **Processing location**        | Override the data source processing location for this query.                      |
| **Format**                     | Select the output format: **Time series** or **Table**. The default is **Table**. |
| **Use Storage API**            | Enable the BigQuery Storage API for this query (Code mode only).                  |
| **Filter/Group/Order/Preview** | Toggle sections in the Visual query editor (Builder mode only).                   |
| **Builder/Code**               | Switch between Visual query builder and SQL code editor.                          |

## Query with Grafana Assistant

When [Grafana Assistant](/docs/grafana-cloud/platform/grafana-assistant/) is available in your Grafana instance, the query editor header displays a **Query with Assistant** button. Use it to build and refine BigQuery queries with AI assistance instead of writing SQL by hand.

The Assistant uses the current query and the data source connection as context. It discovers the projects, datasets, and tables available to your data source to suggest relevant queries against your data. You can then run the generated query or continue editing it in Builder or Code mode.

> Note
> 
> The **Query with Assistant** button only appears when Grafana Assistant is enabled for your Grafana instance. If you don’t see it, Grafana Assistant isn’t available in your environment.

## 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

Expand table

| Shortcut            | Action                 |
|---------------------|------------------------|
| `Cmd/Ctrl + Return` | Run the query          |
| `Ctrl + Space`      | Trigger autocompletion |

## 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:

Expand table

| Selector    | Description                                  |
|-------------|----------------------------------------------|
| **Project** | Select the GCP project containing your data. |
| **Dataset** | Select the dataset within the project.       |
| **Table**   | Select the table to query.                   |

### Query building

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

Expand table

| Section     | Description                                                                                          |
|-------------|------------------------------------------------------------------------------------------------------|
| **Select**  | Choose columns and apply aggregation functions.                                                      |
| **Filter**  | Add `WHERE` conditions to filter data by column values.                                              |
| **Group**   | Group results by one or more columns (required when using aggregations).                             |
| **Order**   | Sort results by column values in ascending or descending order. Optional **Limit** defaults to `50`. |
| **Preview** | View the generated SQL query.                                                                        |

### Aggregation functions

The Visual query builder offers the following aggregation functions:

- `ANY_VALUE`
- `ARRAY_AGG`
- `ARRAY_CONCAT_AGG`
- `AVG`
- `BIT_AND`
- `BIT_OR`
- `BIT_XOR`
- `COUNT`
- `COUNTIF`
- `LOGICAL_AND`
- `LOGICAL_OR`
- `MAX`
- `MIN`
- `STRING_AGG`
- `SUM`

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`](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-types#timestamp_type) column in your query.
2. The timestamp column is used as the time axis.
3. All other columns are treated as value columns.

> Note
> 
> Grafana interprets timestamp rows without an explicit time zone as UTC.

### Time series example

SQL ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```sql
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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```sql
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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```sql
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 putting dates in the query.

The plugin expands macros before sending the query to BigQuery. Macros inside SQL comments (`--`, `#`, and `/* */`) aren’t expanded, and those comments are stripped from the query that BigQuery receives.

Expand table

| Macro                            | Description                                                                                                                                               | Example output                                                          |
|----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------|
| `$__timeFilter(column)`          | Filters results to the dashboard time range                                                                                                               | `column >= '2024-01-01T00:00:00Z' AND column <= '2024-01-02T00:00:00Z'` |
| `$__timeFrom()`                  | Returns the start of the dashboard time range as a timestamp value                                                                                        | `TIMESTAMP('2024-01-01T00:00:00Z')`                                     |
| `$__timeFrom(column)`            | Lower-bound filter on `column`                                                                                                                            | `column >= '2024-01-01T00:00:00Z'`                                      |
| `$__timeTo()`                    | Returns the end of the dashboard time range as a timestamp value                                                                                          | `TIMESTAMP('2024-01-02T00:00:00Z')`                                     |
| `$__timeTo(column)`              | Upper-bound filter on `column`                                                                                                                            | `column <= '2024-01-02T00:00:00Z'`                                      |
| `$__timeGroup(column, interval)` | Groups results by time interval for use in `GROUP BY`. Month intervals such as `3M`, `6M`, and `12M` create N-month buckets aligned to the calendar year. | `TIMESTAMP_MILLIS(DIV(UNIX_MILLIS(column), 300000) * 300000)`           |
| `$__interval`                    | The dashboard interval, formatted for BigQuery (for example, `5m` or `1d`)                                                                                | `5m`                                                                    |
| `$__interval_ms`                 | The dashboard interval in milliseconds                                                                                                                    | `300000`                                                                |

The `$__column` and `$__table` macros aren’t supported. Using them returns an error.

### 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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```sql
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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```sql
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. Pass a column name (`$__timeFrom(column)` / `$__timeTo(column)`) when you want a one-sided filter instead of a timestamp value.

SQL ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```sql
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](https://cloud.google.com/bigquery/docs/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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

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

> Note
> 
> Always include partition filters in your queries to minimize data scanned and reduce costs.

## Storage API

The plugin supports the [BigQuery Storage API](https://cloud.google.com/bigquery/docs/reference/storage) 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**.

> Note
> 
> The Storage API doesn’t work with Forward OAuth Identity authentication.

## 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:

Expand table

| Option              | Description                                                                      |
|---------------------|----------------------------------------------------------------------------------|
| **Use Storage API** | Enable the BigQuery Storage API for improved performance with large result sets. |

## Next steps

- [Use template variables](/docs/plugins/grafana-bigquery-datasource/latest/template-variables/) to create dynamic dashboards
- Add [Transformations](/docs/grafana/latest/panels-visualizations/query-transform-data/transform-data/) to manipulate query results
- Set up [Alerting](/docs/plugins/grafana-bigquery-datasource/latest/alerting/) rules based on your BigQuery data