Databricks SQL Alerts: Thresholds and Notification Destinations

1.What an alert is made of

An alert answers one question on a timer: is a number from this query outside the range I expect? To create one, click Alerts in the sidebar, then Create Alert. The editor has a fixed set of parts, and each one handles a separate job:

- Query editor: where you write and test the SQL the alert checks. - Compute: the SQL warehouse that runs the alert query. - Schedule: how often the alert runs. - Share: permissions for other people in the workspace. - Condition: the threshold that triggers a notification. - Notifications: which users or notification destinations hear about it, and optionally how often to repeat. - Advanced: special cases such as empty results and custom message templates.

This lesson focuses on Condition (the threshold) and Notifications (the destination), because that is what the objective asks for. The other parts set the context they run in.

The alert query also has a limit: alerts do not support queries with parameters. If you are used to parameterized dashboard queries, hard-code the values into the alert's SQL.

Each evaluation ends in one of three statuses: OK, TRIGGERED or ERROR. The UNKNOWN status from legacy alerts no longer exists. TRIGGERED means that on the most recent run, the value met the condition and threshold you set. OK means the most recent run did *not* meet it. The docs' example is an alert that checks whether "cats" is above 1500. It stays TRIGGERED as long as cats is above 1500 and shows OK once cats drops to 1470. OK describes the latest run only. It does not mean the alert never fired. ERROR means something went wrong while the alert was being evaluated.

Sources123

2.Setting the threshold: value, operator, comparison

The Condition section is where you define what "out of range" means. It has three settings:

1. The value to check. This is either the *first value* of a column in the query result, or an *aggregation across all rows* of one column, such as SUM or AVERAGE. You also choose which column. 2. The logical operator, for example > (greater than). 3. The threshold. Static value is the default, and you type a number into the value field. The threshold can also be another column instead of a literal.

In the docs' tutorial, the query returns one row per day of NYC taxi fares with a column amount. The condition is set to Sum of amount > static value 4000. Then you click Test condition to see whether the alert would trigger on the current data. You can change the threshold and test again before saving.

      evaluation:
        comparison_operator: EQUAL
        source:
          name: '1'
        threshold:
          value:
            double_value: 2
      query_text: select 2
      schedule:
        quartz_cron_schedule: '44 19 */1 * * ?'
        timezone_id: Europe/Amsterdam
      warehouse_id: 799f096837fzzzz4

Here is why. An aggregation on an alert doesn't summarize the rows after the fact. The alert rewrites the SQL: it wraps your original query text in a common table expression (CTE) and runs an aggregation query over it. So the result the alert evaluates, and passes to templates, is a single aggregated value. The pre-aggregation rows are gone.

WITH q AS (SELECT 1 AS column_name) SELECT  ? (column_name) FROM q

A condition checks one column. When the real rule depends on several columns, for example *drafts above 10,000 and archived above 5,000*, put that logic in the query and return a flag. Then set the alert to trigger when the value is 1.

SELECT CASE WHEN drafts_count > 10000 AND archived_count > 5000 THEN 1 ELSE 0 END
FROM (
SELECT sum(CASE WHEN is_archived THEN 1 ELSE 0 END) AS archived_count,
sum(CASE WHEN is_draft THEN 1 ELSE 0 END) AS drafts_count
FROM queries) data

Sources245

3.Choosing where the notification goes

The threshold decides *when* an alert fires. The Notifications section decides *who hears about it*. There you search for and add either users or notification destinations. In the tutorial, you search for your own username, and the notification arrives by email.

Email to users is the default. To send anywhere else, an admin has to configure a notification destination first. Only a workspace admin can manage destinations, and once one is configured, every user can select it. The admin path is: username in the top bar → Settings → under *Workspace admin*, the Notifications tab → Manage → +Add destination. Then choose a type, configure it and click Create.

Databricks stores destination configurations encrypted. It recommends separate credentials for each destination, so you can revoke one without affecting the others. Webhook-based endpoints must use HTTPS with SSL certificates signed by a trusted certificate authority. They must also allowlist the workspace's control plane and data plane outbound IP addresses. Slack and Microsoft Teams can also be reached through the Databricks Genie app, which supports SQL alerts on both platforms. That option is in Beta and an admin has to turn it on.

How often notifications go out. You can optionally set a notification frequency in the Notifications section, so notifications repeat until the alert returns to OK. The bundle definition shows what this means: retrigger_seconds is how long the alert waits after triggering before it may notify again. If it is 0 or omitted, there is only one notification after the first trigger. A value of 1 notifies on every evaluation where the condition holds. A separate flag, notify_on_ok, sends a message when the alert returns to normal.

Sources26

4.Advanced settings: OK messages, empty results, templates

Advanced settings controls what the notification says and handles edge cases:

- Notify on OK: also notify when the alert goes back to OK, so recipients learn the problem has cleared. - Empty result state: the status to report when the query returns no rows. - Template: the default message, or a customized subject and body.

With Customize template you get two editors. The standard editor uses {{VARIABLE_NAME}} placeholders and accepts a limited set of HTML tags. The Markdown editor uses @VARIABLE_NAME, and typing @ opens a variable picker.

Sources2

5.Scheduling, testing and checking the alert

The threshold and the destination only matter if the alert runs. Use Compute to choose the SQL warehouse that runs the alert query. Then click the calendar icon to open Edit schedule. In the tutorial the alert runs every 5 minutes, starting at 0 minutes past the hour. You can also tick Show cron syntax to write the schedule in Quartz cron syntax. Click View alert to save it.

Once saved, the alert runs on its schedule. If the condition is met, recipients are notified. If the evaluation is OK, no notification goes out. The alert's page shows a history of evaluation details, and Run now runs the query immediately.

One operational limit can stop an alert from firing even when everything is set up correctly. Each workspace allows 250 simultaneous active alert runs by default. If all slots are busy when a scheduled alert is due, that run is skipped and the alert does not evaluate. The usual sign is a gap in the evaluation history at the scheduled time, while a manual Run now works. The fix is to stagger schedules, for example 01:30, 01:32, 01:34, instead of running everything at 01:30.

Sources2

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.An alert query can use parameters, and the alert evaluates them with their default values.Why is that wrong?

   In the current alert editor, the query cannot have parameters. Hard-code the values in the alert's own SQL.

   Covered in What an alert is made of

2. 2.With a SUM aggregation on the alert, QUERY_RESULT_ROWS in the email still lists the original rows.Why is that wrong?

   The alert wraps your query in a CTE and aggregates it, so the template variables only hold the post-aggregation result.

   Covered in Setting the threshold: value, operator, comparison

3. 3.Any alert author can add a new Slack webhook or PagerDuty destination from inside the alert editor.Why is that wrong?

   Only a workspace admin can create notification destinations. Once created, they are available to all users, who pick them in the Notifications section.

   Covered in Choosing where the notification goes

4. 4.An HTML-formatted template with QUERY_RESULT_TABLE renders the same way in Slack, Teams and email.Why is that wrong?

   Only email destinations can render HTML. Other destinations display the notification in their own way.

   Covered in Advanced settings: OK messages, empty results, templates