Databricks SQL アラートとは

Databricks SQL アラートは、クエリーを定期的に実行し、定義された条件を評価し、条件が満たされた場合に通知を送信します。 アラートを設定してビジネスを監視し、報告されたデータが予想される制限を超えた場合に通知を送信できます。 アラートをスケジュールすると、基になるクエリーが実行され、アラート条件がチェックされます。 これは、基になるクエリーに存在する可能性のあるスケジュールとは無関係です。

重要

  • クエリーとパラメーター を使用するアラートでは、SQL エディターでパラメーターごとに指定された既定値が使用されます。

アラートの表示と整理

アラートにアクセスするには、次のオプションのいずれかを使用します。

  • クリックワークスペースアイコンサイドバーのワークスペースでは、ホームフォルダー内のアラートを表示します。アラートはデフォルトで保存されます。 ユーザーは、アラートを他の Databricks オブジェクトとともにワークスペース ブラウザー内のフォルダーに整理できます。

  • クリックアラートアイコンサイドバーのアラートをクリックして、アラート リスト ページを表示します。

デフォルトでは、オブジェクトは新しい順に並べ替えられます。 列見出しをクリックすると、リストを並べ替えることができます。 ワークスペース内のすべてのアラートを表示するには、画面の上部近くにある [すべてのアラート] タブをクリックします。 自分が所有者であるアラートを表示するには、 「マイ アラート」タブをクリックします。

  • [名前 ] には、各アラートの文字列名が表示されます。

  • 状態 は、アラートの状態が TRIGGERED、 OK、または UNKNOWNのいずれであるかを示します。

  • 最終更新日 には、最終更新時刻または最終更新日が表示されます。

  • [作成日時] には、アラートが作成された日時が表示されます。

    • TRIGGERED は、最新の実行で、ターゲットクエリーの [値] 列が、設定した条件としきい値を満たしたことを意味します。 "cats" が 1500 を超えているかどうかをアラートで確認する場合、「cats」が 1500 を超えている限りアラートがトリガーされます。

    • OK は、最新のクエリー実行時に、[値] 列が構成した [条件] と [しきい値] を満たしていなかったことを意味します。 これは、アラートが以前にトリガーされなかったことを意味するものではありません。 「cats」の値が1470の場合、アラートは OKと表示されます。

    • UNKNOWN は、Databricks SQL にアラート条件を評価するのに十分なデータがないことを意味します。 このステータスは、アラートを作成した直後から、クエリーが実行されるまで表示されます。 クエリー結果にデータがない場合、または最新のクエリー結果に構成した 値列 が含まれていない場合にも、この状態が表示されます。

アラートを作成する

次の手順に従って、クエリーの 1 つの列にアラートを作成します。

  1. 次のいずれかの操作を行います。

    • サイドバーで [新しいアイコン 新規 ] をクリックし 、[アラート] を選択します。

    • サイドバーの アラートアイコン [アラート ] をクリックし 、[+ 新しいアラート] ボタンをクリックします。

    • ワークスペースアイコン サイドバーの [ワークスペース ] をクリックし 、[ + アラートの作成] をクリックします。

    • ケバブメニュー保存したクエリーの右上隅にあるケバブメニューをクリックし、[+ アラートの作成]をクリックします。

  2. [ クエリー ] フィールドで、ターゲットのクエリーを検索します。

    Target クエリー

    複数の列でアラートを出すには、クエリーを変更する必要があります。 アラートの集計を参照してください。

  3. [ トリガー条件 ] フィールドで、アラートを構成します。

    • [ 値] 列の ドロップダウンは、クエリー結果のどのフィールドを評価するかを制御します。 アラート条件は、クエリー結果の列の最初の値に設定することも、SUM や AVERAGE など、1 つの列のすべての行に集計を設定することもできます。

      アラートの集計

    • [演算子] ドロップダウンは、適用する論理演算を制御します。

    • [しきい値] テキスト入力は、指定した条件を使用して [値] 列と比較されます。

    トリガー条件

  4. [ アラートのプレビュー ] をクリックしてアラートをプレビューし、アラートが現在のデータでトリガーされるかどうかをテストします。

  5. [ アラートがトリガーされたときに通知を送信する] フィールドで、 アラートがトリガーされたときに送信する通知の数を選択します。

    • 一度だけ: アラートの状態 が OK から TRIGGEREDに変わったときに通知を送信します。

    • アラートが評価されるたびに: 前回の評価時の状態に関係なく、アラートの状態が TRIGGERED たびに通知を送信します。

    • 最大間隔: アラートの状態が特定の間隔で TRIGGERED されるたびに通知を送信します。 この選択により、頻繁にトリガーされるアラートの通知スパムを回避できます。

    選択した通知設定に関係なく、ステータスが [ OK ] から [ TRIGGERED ] または [ TRIGGERED ] から [ OK] に変わるたびに通知が届きます。 スケジュール設定は、ある実行から次の実行までステータスが TRIGGERED ままである場合に受信する通知の数に影響します。 詳しくは、 通知頻度をご覧ください。

  6. [ テンプレート] ドロップダウンで、テンプレートを選択します。

    • デフォルトテンプレートを使用:アラート通知は、アラート設定画面とクエリー画面へのリンクを含むメッセージです。

    • カスタム テンプレートを使用する: アラート通知には、アラートに関するより具体的な情報が含まれます。

      1. 件名と本文の入力フィールドで構成されるボックスが表示されます。 静的コンテンツはすべて有効であり、組み込みのテンプレート変数を組み込むことができます。

        • ALERT_STATUS: 評価されたアラートの状態 (文字列)。

        • ALERT_CONDITION: アラート条件演算子 (文字列)。

        • ALERT_THRESHOLD: アラートのしきい値 (文字列または数値)。

        • ALERT_COLUMN: アラート列名 (文字列)。

        • ALERT_NAME: アラート名 (文字列)。

        • ALERT_URL: アラート ページの URL (文字列)。

        • QUERY_NAME: 関連付けられたクエリー名 (文字列)。

        • QUERY_URL: 関連付けられたクエリー ページの URL (文字列)。

        • QUERY_RESULT_TABLE: クエリ結果の HTML テーブル (文字列)。 結果は最初の 100 行に制限されます。

        • QUERY_RESULT_VALUE: クエリーの結果値 (文字列または数値)。

        • QUERY_RESULT_ROWS: クエリーの結果行 (値配列)。

        • QUERY_RESULT_COLS: クエリーの結果列 (文字列配列)。

        たとえば、主題の例は次のとおりです。 Alert "{{ALERT_NAME}}" changed status to {{ALERT_STATUS}}。

      2. HTML を使用して、カスタム テンプレート内のメッセージの書式を設定できます。 テンプレートでは、次のタグと属性を使用できます。

        • タグ: <a>、 <abbr>、 <acronym>、 <b>、 <blockquote>、 <body>、 <br>、 <code>、 <div>、 <em>、 <h1>、 <h2>、 <h3>、 <h4>、 <h5> 、 <h6> 、 <head> 、 <hr>、 <html>, <i>, <li>, <ol>, <p>, <span>, <strong>, <table>, <tbody>, <td>, <th>, <tr>, <ul>

        • 属性: href ( <a>の場合 )、タイトル ( <a>、 <abbr>、 <acronym>)

      3. [プレビュー]切り替えボタンをクリックして、レンダリング結果を プレビュー します。

        重要

        プレビューは、テンプレート変数が正しくレンダリングされていることを確認するのに役立ちます。 通知先ごとに異なる方法で通知が表示される可能性があるため、最終的な通知内容を正確に表すものではありません。

      4. [ 変更を保存 ]ボタンをクリックします。

  7. [ アラートの作成] をクリックします。

  8. 「 スケジュールの追加」をクリックします。

    • ドロップダウンピッカーを使用して、頻度、期間、開始時刻、タイムゾーンを指定します。 オプションで、「 cron 構文を表示 」チェックボックスを選択して、「 Quartz cron 構文」でスケジュールを編集します。

    • [ その他のオプション ] を選択して、オプション設定を表示します。 以下を選択することもできます。

      • スケジュールの名前。

      • クエリーを強化するSQLウェアハウス。 デフォルトでは、アドホッククエリーの実行に使用されるSQLウェアハウスは、スケジュールされたジョブにも使用されます。 このオプション設定を使用して、スケジュールされたクエリーを実行する別のウェアハウスを選択します。

  9. 「スケジュールの追加」ダイアログの「宛先」タブをクリックします。

    設定ダイアログの「宛先」タブ

    • ドロップダウンを使用して、使用可能な 通知先を選択します。 または、ユーザー名の入力を開始して個人を追加します。

    重要

    このステップ をスキップ すると、アラート がトリガーされたときに通知されません。

  10. 「作成」をクリックします。保存したアラートと通知の詳細が画面に表示されます。

    保存済みアラート

  11. スケジュールを共有します。

    • 一覧表示されたスケジュールの右側で、ケバブ メニューを選択し ケバブメニュー 、[ スケジュールのアクセス許可の編集] を選択します。

    • ダイアログのドロップダウンメニューからユーザーまたはグループを選択します。

    • 次のスケジュール権限から選択します。

      • NO PERMISSIONS : 権限は付与されていません。 権限のないユーザーは、サブスクライバーであったり、リストされた通知先に含まれていたりしても、スケジュールが存在することを確認できません。

      • CAN VIEW: スケジュールされた実行結果を表示する権限を付与します。

      • CAN MANAGE RUN: スケジュールされた実行結果を表示する権限を付与します。

      • CAN MANAGE : スケジュールを表示、変更、削除する権限を付与します。 この権限は、実行間隔の変更、サブスクライバー リストの更新、スケジュールの停止または一時停止解除を行うために必要です。

      • IS OWNER: CAN MANAGE のすべての権限を付与します。 さらに、スケジュール所有者の資格情報は、ダッシュボード クエリの実行に使用されます。 ワークスペース管理者のみが所有者を変更できます。

    重要

    アラートとスケジュールの権限は別々です。 通知の宛先リスト内のユーザーおよびグループにアクセス権を付与して、スケジュールされた実行結果を表示できるようにします。

  12. アラートを共有します。

    • ページの右上付近にある をクリックします 共有ボタン 。

    • アラートへのアクセス権を付与するユーザーまたはグループを追加します。

    • 適切な権限レベルを選択し、「 追加」をクリックします。

重要

CAN MANAGE は、スケジュールを表示、変更、および削除する権限を付与します。 この権限は、実行間隔の変更、通知先リストの更新、スケジュールの停止または一時停止解除を行うために必要です。

アラートの権限レベルの詳細については、 「アラート ACL」を参照してください。

アラートの集計

アラートの集計は、アラートにアタッチされている Databricks SQL クエリーの元の SQL を変更することによって機能します。 このアラートは、元のクエリー テキストを共通テーブル式 (CTE) でラップし、そのクエリに対してラップ集計クエリーを実行してクエリー結果を集計します。

たとえば、テキスト SELECT 1 AS column_name を含むクエリに添付されたアラートの SUM 集計は、アラートが更新されるたびに、実行される変更された SQL が WITH q AS (SELECT 1 AS column_name) SELECT SUM(column_name) FROM q.

つまり、アラートに集計がある場合は、元のクエリ結果 (事前に集計された) をアラート カスタム本文 ( QUERY_RESULT_ROWS や QUERY_RESULT_COLSなどのパラメーターと共に) に表示することはできません。 代わりに、これらの変数には、集計後の最終的なクエリー結果のみが表示されます。

注

集計に関連するすべてのトリガー条件は、API ではサポートされていません。

複数の列に関するアラート

クエリーの複数の列に基づいてアラートを設定するには、クエリーでアラート ロジックを実装し、アラートをトリガーする Boolean 値を返します。 例えば：

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

このクエリーは、 drafts_count > 10000 and archived_count > 5000の場合に 1 を返します。次に、値が 1されたときにトリガーするようにアラートを構成できます。

通知の頻度

Databricks SQL は、アラートの状態が OK から TRIGGERED に、またはその逆に変更されたことを検出するたびに、選択した通知先に通知を送信します。 この例では、毎日 1 回実行するようにスケジュールされているクエリーにアラートが構成されています。 アラートの日次ステータスを次の表に示します。 月曜日以前は、アラートステータスは OKでした。

日

アラートの状態

月曜日

OK

火曜日

OK

水曜日

TRIGGERED

木曜日

TRIGGERED

金曜日

TRIGGERED

土曜日

TRIGGERED

日曜日

OK

通知頻度が Just Onceに設定されている場合、Databricks SQL は、状態が OK から TRIGGERED に変わった水曜日と、切り替えた日曜日に通知を送信します。 木曜日、金曜日、または土曜日には、アラートのステータスが実行間で変更されなかったため、特に設定しない限り、アラートは送信されません。

アラートのアクセス許可を構成し、アラートの所有権を譲渡する

クエリを共有するには、クエリに対する CAN MANAGE 権限以上が必要です。 アラートの権限レベルについては、 「アラート ACL」を参照してください。

  1. サイドバーで、 「アラート」をクリックします。

  2. アラートをクリックします。

  3. 共有ボタン右上のボタンをクリックして、[共有]ダイアログを開きます。

    アラート権限の管理

  4. グループとユーザーを検索して選択し、権限レベルを割り当てます。

  5. 「追加」をクリックします。

アラートのオーナー権限を譲渡する

アラートを保存すると、アラートの所有者になります。 アラートの所有者がワークスペースから削除されると、アラートには所有者がなくなります。 ワークスペース管理者ユーザーは、アラートの所有権を別のユーザーに譲渡できます。 サービスシプリンパルとグループにアラートの所有権を割り当てることはできません。 Permissions APIを使用して所有権を譲渡することもできます。

  1. ワークスペース管理者として、Databricks ワークスペースにログインします。

  2. サイドバーで、 「アラート」をクリックします。

  3. アラートをクリックします。

  4. 右上の「 共有 」ボタンをクリックして、「 共有 」ダイアログを開きます。

  5. 右上の歯車アイコンをクリックし、[ 新しい所有者を割り当てる] をクリックします。

    新規所有者を割り当て

  6. 所有権を割り当てるユーザーを選択します。

  7. 「確認」をクリックします。