Databricks SQL アラートとは

[アーティクル]
07/11/2024

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

重要

パラメーターを含むクエリを利用するアラートでは、各パラメーターに対して SQL エディターで指定された既定値が使用されます。

アラートの表示と整理

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

サイドバーの [ワークスペース] をクリックすると、既定の保存場所であるホーム フォルダーにアラートが表示されます。ユーザーは、他の Databricks オブジェクトと共に、ワークスペースブラウザー内のフォルダーにアラートを整理できます。
サイドバーの [アラート] をクリックして、アラートの一覧ページを表示します。

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

[名前] には、各アラートの文字列名が表示されます。
[状態] には、アラートの状態が TRIGGERED、OK、UNKNOWN のいずれであるかが表示されます。
[最終更新日時] には、最後に更新された時刻または日付が表示されます。
[作成日時] には、アラートが作成された日時が表示されます。
- TRIGGERED は、最新の実行において、ターゲットクエリの値列が、構成されている条件としきい値を満たしたことを意味します。 "猫" が 1500 より多いかどうかをチェックするアラートの場合、"猫" が 1500 を超えている間はアラートがトリガーされます。
- OK は、最新のクエリの実行において、値列が構成されている条件としきい値を満たさなかったことを意味します。これは、アラートが以前にトリガーされていないことを意味するものではありません。 "猫" の値が現在は 1470 になっている場合は、アラートで OK が示されます。
- UNKNOWN は、アラートの条件を評価するのに十分なデータが Databricks SQL にないことを意味します。アラートを作成した直後から、クエリが実行されるまでは、この状態が表示されます。また、クエリの結果にデータがなかった場合や、最新のクエリの結果に構成した "値列" が含まれていない場合にも、この状態が表示されます。

アラートを作成する

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

以下のいずれかを実行します。
- サイドバーで [新規] をクリックし、[アラート] を選択します。
- サイドバーで [アラート] をクリックし、[+ 新しいアラート] ボタンをクリックします。
- サイドバーで [ワークスペース] をクリックし、[+ アラートの作成] をクリックします。
- 保存したクエリの右上隅にある kebab メニューをクリックし、[+ アラートの作成] をクリックします。
[クエリ] フィールドで、ターゲットクエリを検索します。

複数の列に対してアラートを出すには、クエリを変更する必要があります。「アラートの集計」を参照してください。
[トリガー] フィールドで、アラートを構成します。
- [値列] のドロップダウンは、クエリ結果のどのフィールドを評価するかを制御します。アラート条件は、クエリ結果の列の最初の値に設定することも、SUM や AVERAGE などのように、1 つの列のすべての行の集計を設定することもできます。
- [演算子] ドロップダウンは、適用される論理演算子を制御します。
- しきい値のテキスト入力は、指定した条件を使用して値列と比較されます。
[アラートのプレビュー] をクリックしてアラートをプレビューし、アラートが現在のデータでトリガーされるかどうかをテストします。
[When alert is triggered, send notification] (アラートのトリガー時に通知を送信する) フィールドで、アラートがトリガーされたときに送信される通知の件数を選択します。
- [Just once](1 回だけ): アラートの状態が OK から TRIGGERED に変化したときに通知を送信します。
- [Each time alert is evaluated](アラートが評価されるたび): 前回の評価による状態とは関係なく、アラートの状態が TRIGGERED になるたびに通知を送信します。
- [At most every](最大で次の間隔ごと): アラートの状態が TRIGGERED になるたびに一定の間隔で通知を送信します。これを選択すると、頻繁にトリガーされるアラートのスパム通知を回避できます。
どの通知設定を選択した場合でも、状態が OK から TRIGGERED、または TRIGGERED から OK に変わるたびに通知が送信されます。スケジュール設定は、1 回の実行から次の実行まで TRIGGERED の状態が維持される場合に受け取る通知の件数に影響を与えます。詳細については、「通知頻度」を参照してください。
[テンプレート] ドロップダウンで、テンプレートを選択します。
- [Use default template](既定のテンプレートを使用する): アラートの通知は、アラートの構成画面とクエリ画面へのリンクを含むメッセージになります。
- [Use custom template](カスタムテンプレートを使用する): アラート通知には、アラートに関するより具体的な情報が含まれます。
  1. 件名と本文の入力フィールドで構成されたボックスが表示されます。静的なコンテンツはすべて有効であり、組み込みのテンプレート変数を使用できます。
    - ALERT_STATUS: 評価されたアラートの状態 (文字列)。
    - ALERT_CONDITION: アラートの条件演算子 (文字列)。
    - ALERT_THRESHOLD: アラートのしきい値 (文字列または数値)。
    - ALERT_COLUMN: アラートの列名 (文字列)。
    - ALERT_NAME: アラート名 (文字列)。
    - ALERT_URL: アラートページの URL (文字列)。
    - QUERY_NAME: 関連付けられているクエリ名 (文字列)。
    - QUERY_URL: 関連付けられているクエリページの URL (文字列)。
    - QUERY_RESULT_TABLE: クエリ結果の HTML テーブル (文字列)。
    - 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> 用)、title (<a>、 <abbr>、 <acronym> 用)
  3. [プレビュー] トグルボタンをクリックして、レンダリングされた結果をプレビューします。
    
    重要
    
    プレビューは、テンプレート変数が正しくレンダリングされることを確認するのに役立ちます。通知は送信先ごとに異なる方法で表示できるため、最終的な通知の内容が正確に表現されるわけではありません。
  4. [変更内容を保存] ボタンをクリックします。
[アラートの作成] をクリックします。
[スケジュールの追加]をクリックします。
- ドロップダウンピッカーを使用して、頻度、期間、開始時刻、タイムゾーンを指定します。必要に応じて、[Cron 構文の表示] チェックボックスをオンにして、[Quartz Cron 構文] でスケジュールを編集します。
- オプションの設定を表示するには、[その他のオプション] を選択します。次を選択することもできます。
  - スケジュールの名前。
  - クエリを実行するための SQL ウェアハウス。既定では、アドホッククエリの実行に使用される SQL ウェアハウスは、スケジュールされたジョブにも使用されます。スケジュールされたクエリを実行するために別のウェアハウスを選択するには、このオプションの設定を使用します。
[スケジュールの追加] ダイアログボックスの [宛先] タブをクリックします。
- ドロップダウンを使用して、使用可能な通知先を選択します。または、ユーザー名の入力を開始して、個人を追加します。
重要

この手順をスキップすると、アラートがトリガーされたときに通知 "されません"。
Create をクリックしてください。保存したアラートと通知の詳細が画面に表示されます。
スケジュールを共有します。
- 一覧表示されているスケジュールの右側にある kebab メニューを選択し、[Edit schedule permissions] (スケジュールのアクセスの許可) を選択します。
- ダイアログのドロップダウンメニューからユーザーまたはグループを選びます。
- 次のスケジュールアクセス許可から選択します。
  - アクセス許可なし: アクセス許可は付与されていません。アクセス許可を持たないユーザーは、スケジュールがサブスクライバーであったり一覧表示されている通知先に含まれていたりする場合でも、存在することを確認できません。
  - 表示可能: スケジュールされた実行結果を表示するためのアクセス許可を付与します。
  - 実行管理可能: スケジュールされた実行結果を表示するためのアクセス許可を付与します。
  - 管理可能: スケジュールを表示、変更、削除するためのアクセス許可を付与します。このアクセス許可は、実行間隔の変更、サブスクライバーリストの更新、スケジュールの一時停止または一時停止解除を行うために必要です。
  - 所有者: 管理可能のすべてのアクセス許可を付与します。さらに、スケジュール所有者の資格情報は、ダッシュボードクエリの実行に使用されます。ワークスペース管理者のみが所有者を変更できます。
重要

アラートとスケジュールのアクセス許可は別です。スケジュールされた実行の結果を表示できるように、通知先の一覧でユーザーとグループにアクセスを許可します。
アラートを共有します。
- ページの右上付近にあるをクリックします。
- アラートへのアクセスを許可するユーザーまたはグループを追加します。
- 適切なアクセス許可レベルを選択し、[追加] をクリックします。

重要

[管理可能] では、スケジュールを表示、変更、削除するためのアクセス許可が付与されます。このアクセス許可は、実行間隔の変更、通知先リストの更新、スケジュールの一時停止または一時停止解除を行うために必要です。

アラートのアクセス許可レベルの詳細については、「アラート 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 などのパラメーターを使用して) アラートカスタム本体に表示することはできません。代わりに、これらの変数は、集計後の最終的なクエリ結果のみを表示します。

Note

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

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

クエリの複数の列に基づいてアラートを設定するには、クエリでアラートロジックを実装し、アラートをトリガーするブール値を返すことができます。次に例を示します。

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 日 1 回実行するようにスケジュールされているクエリに対してアラートが構成されています。次の表に、アラートの状態を日単位で示します。月曜日より前のアラートの状態は OK でした。

日	アラートの状態
月曜日	OK
Tuesday	OK
水曜日	TRIGGERED
Thursday	TRIGGERED
金曜日	TRIGGERED
土曜日	TRIGGERED
土曜日	OK

通知頻度が Just Once に設定されている場合、Databricks SQL は、水曜日に状態が OK から TRIGGERED に変わったときに通知を送信し、日曜日に状態が戻ったときにもう一度通知を送信します。木曜日、金曜日、または土曜日の実行ではアラートの状態が変わらないため、特に構成しない限り、これらの曜日にアラートは送信されません。

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

クエリを共有するには、少なくともクエリに対する管理可能アクセス許可が必要です。アラートのアクセス許可レベルについては、「アラート ACL」を参照してください。

サイドバーの [アラート] をクリックします。
アラートをクリックします。
右上にあるボタンをクリックして、[共有] ダイアログを開きます。
グループおよびユーザーを検索して選び、アクセス許可レベルを割り当てます。
追加をクリックします。

アラートの所有権を譲渡する

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

ワークスペース管理者として、Azure Databricks ワークスペースにログインします。
サイドバーの [アラート] をクリックします。
アラートをクリックします。
右上にある [共有] ボタンをクリックして、[共有] ダイアログを開きます。
右上にある歯車アイコンをクリックし、[新しい所有者の割り当て] をクリックします。
所有権の割り当て先のユーザーを選択してください。
[Confirm](確認) をクリックします。

次の方法で共有