Alerts

Preview

This feature is in Public Preview.

Alerts notify you when a field returned by a scheduled query meets a threshold. Use alerts to monitor your business or integrate them with tools to start workflows such as user onboarding or support tickets. Alerts complement scheduled queries, but their criteria are checked after every execution.

Important

  • A query schedule is not required but is highly recommended for alerts. If you add an alert to a non-scheduled query you will be notified only if a user executes the query manually and the alert criteria are met.
  • Alerts don’t work for queries with parameters.

View alerts

To see a list of alerts, click Alerts Icon Alerts in the sidebar. By default, alerts are sorted in reverse chronological order by the Created By column. You can reorder the list by clicking the column headings.

  • Name shows the string name of each alert.
  • Created By shows the user that created the alert.
  • State shows whether the alert status is TRIGGERED, OK, or UNKNOWN.
    • TRIGGERED means that on the most recent execution, the Value column in your target query met the Condition and Threshold you configured. If your alert checks whether “cats” is above 1500, your alert will be triggered as long as “cats” is above 1500.
    • OK means that on the most recent query execution, the Value column did not meet the Condition and Threshold you configured. This doesn’t mean that the Alert was not triggered previously. If your “cats” value is now 1470 your alert will show as OK.
    • UNKNOWN means Databricks SQL does not have enough data to evaluate the alert criteria. You will see this status immediately after creating your Alert until the query has executed. You will also see this status if there was no data in the query result or if the most recent query result doesn’t include the Value Column you configured.
Alert list

Create an alert

Follow these steps to create an alert on a single column of a query.

  1. Do one of the following:

    • Click Create Icon Create in the sidebar and select Alert.
    • Click Alerts Icon Alerts in the sidebar and click the + New Alert button.
  2. Search for a target query. If you don’t see it the one you want, make sure it is published and does not use parameters.

    Target query

    To alert on multiple columns, you need to modify your query. See Alert on multiple columns.

  3. In the Trigger when field, configure the alert.

    • The Value column drop-down controls which field of your query result is evaluated.
    • The Condition drop-down controls the logical operation to be applied.
    • The Threshold text input is compared against the Value column using the Condition you specify.
    Alert settings

    Note

    If a target query returns multiple records, Databricks SQL alerts act on the first one. As you change the Value column setting, the current value of that field in the top row is shown beneath it.

  4. In the When triggered, send notification field, select how many notifications are sent when your alert is triggered:

    • Just once: Send a notification when the alert status changes from OK to TRIGGERED.
    • Each time alert is evaluated: Send a notification whenever the alert status is TRIGGERED regardless of its status at the previous evaluation.
    • At most every: Send a notification whenever the alert status is TRIGGERED at a specific interval. This choice lets you avoid notification spam for alerts that trigger often.

    Regardless of which notification setting you choose, you receive a notification whenever the status goes from OK to TRIGGERED or from TRIGGERED to OK. The schedule settings affect how many notifications you will receive if the status remains TRIGGERED from one execution to the next. For details, see Notification frequency.

  5. In the Template drop-down, choose a template:

    • Use default template: Alert notification is a message with links to the Alert configuration screen and the Query screen.

    • Use custom template: Alert notification includes more specific information about the alert.

      1. A box displays, consisting of input fields for subject and body. Any static content is valid, and you can incorporate built-in template variables:

        • ALERT_STATUS: The evaluated alert status (string).
        • ALERT_CONDITION: The alert condition operator (string).
        • ALERT_THRESHOLD: The alert threshold (string or number).
        • ALERT_NAME: The alert name (string).
        • ALERT_URL: The alert page URL (string).
        • QUERY_NAME: The associated query name (string).
        • QUERY_URL: The associated query page URL (string).
        • QUERY_RESULT_VALUE: The query result value (string or number).
        • QUERY_RESULT_ROWS: The query result rows (value array).
        • QUERY_RESULT_COLS: The query result columns (string array).

        An example subject, for instance, could be: Alert "{{ALERT_NAME}}" changed status to {{ALERT_STATUS}}.

      2. Click the Preview toggle button to preview the rendered result.

        Important

        The preview is useful for verifying that template variables are rendered correctly. It is not an accurate representation of the eventual notification content, as each alert destination can display notifications differently.

      3. Click the Save Changes button.

  6. Click Create Alert.

  7. Choose an alert destination.

    Important

    If you skip this step you will not be notified when the alert is triggered.

    Alert destination

Alert on multiple columns

To set an alert based on multiple columns of a query, your query can implement the alert logic and return a boolean value for the alert to trigger on. For example:

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

This query returns 1 when drafts_count > 10000 and archived_count > 5000. Then you can configure the alert to trigger when the value is 1.

Notification frequency

Databricks SQL sends notifications to your chosen alert destinations whenever it detects that the Alert status has changed from OK to TRIGGERED or vice versa. Consider this example where an Alert is configured on a query that is scheduled to run once daily. The daily status of the Alert appears in the following table. Prior to Monday the alert status was OK.

Day Alert Status
Monday OK
Tuesday OK
Wednesday TRIGGERED
Thursday TRIGGERED
Friday TRIGGERED
Saturday TRIGGERED
Sunday OK

If the notification frequency is set to Just Once, Databricks SQL sends a notification on Wednesday when the status changed from OK to TRIGGERED and again on Sunday when it switches back. It does not send alerts on Thursday, Friday, or Saturday unless you specifically configure it to do so because the Alert status did not change between executions on those days.

Configure alert permissions

To configure who can manage and run alerts, see Alert access control.

Transfer ownership of an alert

An administrator can transfer ownership of an alert. See Transfer ownership of an alert.