---
title: "Example of alerting on tabular data | Grafana Cloud documentation"
description: "This example shows how to create an alert rule using table data."
---

# Example of alerting on tabular data

Not all data sources return time series data. SQL databases, CSV files, and some APIs often return results as rows or arrays of columns or fields — commonly referred to as tabular data.

This example shows how to create an alert rule using data in table format. Grafana treats each row as a separate alert instance, as long as the data meets the expected format.

## How Grafana Alerting evaluates tabular data

When a query returns data in table format, Grafana transforms each row into a separate alert instance.

To evaluate each row (alert instance), it expects:

1. **Only one numeric column.** This is the value used for evaluating the alert condition.
2. **Non-numeric columns.** These columns defines the label set. The column name becomes a label name; and the cell value becomes the label value.
3. **Unique label sets per row.** Each row must be uniquely identifiable by its labels. This ensures each row represents a distinct alert instance.

> Caution
> 
> These three conditions must be met—otherwise, Grafana can’t evaluate the table data and the rule will fail.

## Example overview

Imagine you store disk usage in a `DiskSpace` table and you want to trigger alerts when the available space drops below 5%.

Expand table

| Time       | Host | Disk | PercentFree |
|------------|------|------|-------------|
| 2021-06-07 | web1 | /etc | 3           |
| 2021-06-07 | web2 | /var | 4           |
| 2021-06-07 | web3 | /var | 8           |

To calculate the free space per Host and Disk in this case, you can use `$__timeFilter` to filter by time but without returning the date to Grafana:

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

```sql
SELECT
  Host,
  Disk,
  AVG(PercentFree) AS PercentFree
FROM DiskSpace
WHERE $__timeFilter(Time)
GROUP BY Host, Disk
```

This query returns the following table response:

Expand table

| Host | Disk | PercentFree |
|------|------|-------------|
| web1 | /etc | 3           |
| web2 | /var | 4           |
| web3 | /var | 8           |

When Alerting evaluates the query response, the data is transformed into three alert instances as previously detailed:

- The numeric column becomes the value for the alert condition.
- Additional columns define the label set for each alert instance.

Expand table

| Alert instance               | Value |
|------------------------------|-------|
| `{Host="web1", Disk="/etc"}` | 3     |
| `{Host="web2", Disk="/var"}` | 4     |
| `{Host="web3", Disk="/var"}` | 8     |

Finally, an alert condition that checks for less than 5% of free space (`$A < 5`) would result in two alert instances firing:

Expand table

| Alert instance               | Value | State  |
|------------------------------|-------|--------|
| `{Host="web1", Disk="/etc"}` | 3     | Firing |
| `{Host="web2", Disk="/var"}` | 4     | Firing |
| `{Host="web3", Disk="/var"}` | 8     | Normal |

## Try it with TestData

To test this quickly, you can simulate the table using the [**TestData** data source](/docs/grafana-cloud/connect-externally-hosted/data-sources/testdata/):

1. Add the **TestData** data source through the **Connections** menu.
2. Go to **Alerting** and create an alert rule
3. Select **TestData** as the data source.
4. From **Scenario**, select **CSV Content** and paste this CSV:
   
   Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```bash
   host, disk, percentFree
   web1, /etc, 3
   web2, /var, 4
   web3, /var, 8
   ```
5. Set a condition like `$A < 5` and **Preview** the alert.
   
   Grafana evaluates the table data and fires the two first alert instances.
   
   [](/media/docs/alerting/example-table-data-preview.png)
   
   > Tip
   > 
   > You can explore this [**alerting example in Grafana Play**](https://play.grafana.org/alerting/grafana/tabular-data/view?tech=docs&pg=alerting-examples&plcmt=callout-tip&cta=alert-tabular-data).
   > 
   > Open the example to view alert evaluation results, generated alert instances, the alert history timeline, and alert rule details.

## CSV data with Infinity

Note that when the [Infinity plugin fetches CSV data](/404/), all the columns are parsed and returned as strings. By default, this causes the query expression to fail in Alerting.

To make it work, you need to format the CSV data as [expected by Grafana Alerting](#how-grafana-alerting-evaluates-tabular-data).

In the query editor, specify the column names and their types to ensure that only one column is treated as a number.

[](/media/docs/alerting/example-table-data-infinity-csv-data.png)

## Differences with time series data

Working with time series is similar—each series is treated as a separate alert instance, based on its label set.

The key difference is the data format:

- **Time series data** contains multiple values over time, each with its own timestamp. To evaluate the alert condition, alert rules **must reduce each series to a single number** using a function like `last()`, `avg()`, or `max()`.
- **Tabular data** doesn’t require reduction, as each row contains only a single numeric value used to evaluate the alert condition.

For comparison, see the [multi-dimensional time series data example](/docs/grafana-cloud/alerting-and-irm/alerting/best-practices/multi-dimensional-alerts/).