---
title: "Google BigQuery alerting | Grafana Plugins documentation"
description: "Set up alerting with the Google BigQuery data source 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 alerting

You can create Grafana alerts based on BigQuery queries to get notified when your data meets specific conditions. Use alerts to monitor metrics, detect anomalies, or track business KPIs stored in BigQuery.

## Before you begin

Before setting up alerts:

- [Configure the Google BigQuery data source](/docs/plugins/grafana-bigquery-datasource/latest/configure/)
- Understand [Grafana Alerting](/docs/grafana/latest/alerting/)
- Ensure your BigQuery credentials are configured using a method that doesn’t require user interaction (service account key, GCE metadata, or service account impersonation)

> Note
> 
> Alerting doesn’t work with **Forward OAuth Identity** authentication. Grafana alerting runs in the background and requires credentials that are always available, which isn’t the case with OAuth-based authentication.

## Create an alert rule

To create an alert rule using BigQuery data:

1. Navigate to **Alerting** > **Alert rules**.
2. Click **New alert rule**.
3. Enter a name for the alert rule.
4. Select your **Google BigQuery** data source.
5. Write a query that returns numeric data.
6. Configure the alert condition (threshold, range, or no data handling).
7. Set the evaluation interval and pending period.
8. Add labels and annotations.
9. Click **Save rule**.

## Query requirements for alerting

Alert queries have specific requirements:

- **Return numeric values:** The query must return at least one numeric column for threshold evaluation.
- **Single value or time series:** Queries can return a single value or a time series.
- **Time column:** For time series alerts, include a `TIMESTAMP` column aliased as `time`.

## Alert query examples

The following examples demonstrate common alerting patterns.

### Threshold alert on a metric

Alert when a value exceeds a threshold:

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

```sql
SELECT
  CURRENT_TIMESTAMP() AS time,
  COUNT(*) AS error_count
FROM `project.dataset.errors`
WHERE timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 5 MINUTE)
```

Set the condition to alert when `error_count` is above your threshold.

### Alert on aggregated data

Alert when an average value crosses a threshold:

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

```sql
SELECT
  CURRENT_TIMESTAMP() AS time,
  AVG(response_time_ms) AS avg_response_time
FROM `project.dataset.requests`
WHERE $__timeFilter(timestamp)
```

### Alert on rate of change

Alert when a metric changes significantly:

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

```sql
SELECT
  CURRENT_TIMESTAMP() AS time,
  (
    SELECT COUNT(*)
    FROM `project.dataset.events`
    WHERE timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 5 MINUTE)
  ) - (
    SELECT COUNT(*)
    FROM `project.dataset.events`
    WHERE timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 10 MINUTE)
      AND timestamp < TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 5 MINUTE)
  ) AS count_change
```

### Multi-dimensional alerts

Alert on multiple series with labels:

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

```sql
SELECT
  $__timeGroup(timestamp, $__interval) AS time,
  region,
  SUM(error_count) AS errors
FROM `project.dataset.metrics`
WHERE $__timeFilter(timestamp)
GROUP BY time, region
ORDER BY time
```

This creates separate alert instances for each region.

## Configure alert conditions

After writing your query, configure the alert condition:

Expand table

| Condition type       | Use case                                   |
|----------------------|--------------------------------------------|
| **Is above**         | Alert when value exceeds a threshold       |
| **Is below**         | Alert when value drops below a threshold   |
| **Is within range**  | Alert when value is between two thresholds |
| **Is outside range** | Alert when value is outside a range        |
| **Has no value**     | Alert when query returns no data           |

## Handle no data and errors

Configure how alerts behave when queries return no data or encounter errors:

Expand table

| Setting     | Options                                        |
|-------------|------------------------------------------------|
| **No data** | `No Data`, `Alerting`, `OK`, `Keep Last State` |
| **Error**   | `Error`, `Alerting`, `OK`, `Keep Last State`   |

For BigQuery:

- **No data:** Consider using `Keep Last State` if data gaps are expected, or `Alerting` if missing data indicates a problem.
- **Error:** Use `Alerting` to be notified of query failures, which may indicate permission or connectivity issues.

## Performance considerations

BigQuery alerts run on a schedule, and each evaluation executes a query against BigQuery. Consider these factors:

- **Query cost:** Each alert evaluation runs a query. Optimize queries to scan less data using filters and partitioned tables.
- **Evaluation interval:** Don’t set intervals shorter than necessary. A 1-minute interval runs 1,440 queries per day per alert rule.
- **Query timeout:** Complex queries may timeout. Simplify queries or pre-aggregate data for alerting.
- **Partition pruning:** Use `$__timeFilter` on partitioned columns to limit scanned data.

### Cost optimization example

Instead of scanning an entire table:

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

```sql
-- Expensive: scans all data
SELECT COUNT(*) AS errors
FROM `project.dataset.large_table`
WHERE error = true
```

Filter to recent data and use partitioning:

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

```sql
-- Optimized: uses partition pruning
SELECT COUNT(*) AS errors
FROM `project.dataset.large_table`
WHERE $__timeFilter(_PARTITIONTIME)
  AND error = true
```

## Best practices

Follow these recommendations for effective BigQuery alerts:

- **Use meaningful names:** Name alerts descriptively, like “High Error Rate - Production API” instead of “Alert 1”.
- **Add annotations:** Include context in annotations to help responders understand the alert.
- **Set appropriate thresholds:** Avoid noisy alerts by setting thresholds based on historical data.
- **Use labels:** Add labels for routing alerts to the correct teams or channels.
- **Test queries first:** Verify your query returns expected results in the query editor before creating an alert.
- **Consider time zones:** BigQuery uses UTC by default. Account for time zone differences in your queries.

## Troubleshoot alerts

Use these tips to diagnose common alerting issues.

### Alert not firing

If an alert isn’t firing when expected:

1. Verify the query returns data by running it in the query editor.
2. Check that the returned values actually meet the alert condition.
3. Ensure the evaluation interval has passed.
4. Verify the data source connection is working.

### Alert always firing

If an alert fires continuously:

1. Check the threshold value is appropriate.
2. Verify the query is returning expected values.
3. Look for data quality issues in the source data.

### Query errors in alerts

If alert queries fail:

1. Check the data source credentials are valid and not expired.
2. Verify the service account has required permissions.
3. Test the query manually in the query editor.
4. Check for query syntax errors.

## Related resources

- [Grafana Alerting](/docs/grafana/latest/alerting/)
- [Create alert rules](/docs/grafana/latest/alerting/alerting-rules/create-grafana-managed-rule/)
- [Configure notifications](/docs/grafana/latest/alerting/configure-notifications/)