From 0a73fdff419412d87cb4b944b73bae3c457bf38b Mon Sep 17 00:00:00 2001 From: Larissa Wandzura Date: Thu, 4 Sep 2025 08:42:28 -0500 Subject: [PATCH] added requested update to alert/recording rules --- .../query-transform-data/sql-expressions/index.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/sources/panels-visualizations/query-transform-data/sql-expressions/index.md b/docs/sources/panels-visualizations/query-transform-data/sql-expressions/index.md index 4329d85133a..251d4b5d2e2 100644 --- a/docs/sources/panels-visualizations/query-transform-data/sql-expressions/index.md +++ b/docs/sources/panels-visualizations/query-transform-data/sql-expressions/index.md @@ -162,7 +162,8 @@ SQL expressions integrates alerting and recording rules, allowing you to define For SQL Expressions to work properly with alerting and recording rules, your query must return: - One numeric column - **_required_**. This contains the value that triggers alerts or gets recorded. -- One or more string columns - _optional_. These become **labels** for the alert instances or metrics. Column names and their row values become labels. +- Unique string column combinations - **_required_**. Each row must have a unique combination of string column values. +- One or more string columns - _optional_. These become **labels** for the alert instances or metrics. Example: `service`, `region`. Consider the following query results: @@ -190,6 +191,15 @@ For recording rules, creates one metric with three series: - Second series: error_count_total{service=payment-service, region=us-west} 0 - Third series: error_count_total{service=user-service, region=eu-west} 15 +Following are some best practices for alerting and recording rules: + +- Keep numeric values meaningful (for example: error counts, request duration). +- Use clear, descriptive column names - these become your labels. +- Keep string values short and consistent. +- Avoid too many unique label combinations, as this can result in high cardinality. +- Always use GROUP BY to avoid duplicate label errors. +- Aggregate numeric values logically (for example, `SUM(error_count)`). + ## Supported data source formats Grafana supports three types of data source response formats: