在工作觸發器中加入 SQL 條件

使用 SQL 條件在觸發工作執行開始前檢查資料。 當觸發器觸發時,Azure Databricks 會對你選擇的 SQL 倉庫執行已儲存的 SQL 查詢。 只有當查詢結果符合條件時,執行才會開始。 例如,只有在上游資料表載入完成或資料品質檢查通過時才執行工作,而不在工作中新增獨立的檢查任務。

Important

這項功能位於 測試版 (Beta) 中。 要使用此功能,工作區管理員必須從預覽頁面開啟觸發器的 SQL 條件。 請參閱 管理 Azure Databricks 預覽。

Requirements

  • 你必須在該工作上擁有 CAN MANAGE 權限,才能設定其觸發條件。
  • 你需要一個儲存查詢,且不使用查詢參數。 你必須能存取查詢,並且能在你選擇的 SQL Warehouse 上執行它。
  • 該工作的 Run as identity 必須能夠開啟已儲存的查詢,在 SQL 倉儲上擁有 CAN USE 權限,並且對查詢讀取的每一個資料表都具有讀取權限。 條件查詢以此身份執行。

SQL 條件的運作方式

觸發器決定何時檢查。 SQL 條件決定是否要啟動執行作業。 觸發後,Azure Databricks 會以唯讀模式執行查詢。 只有當觸發條件和 SQL 條件都被滿足時,執行才會開始。

你可以在 排程、 資料表更新、 檔案到達、 模型更新或 工作完成 觸發器中新增一個 SQL 條件。 連續觸發器不支援 SQL 條件。

選擇 Azure Databricks 如何評估查詢結果:

條件類型 API 值 當…時開始執行 查詢需求
查詢回傳資料列 QUERY_RETURNS_ROWS 結果至少包含一列。 None. 列數為零表示條件未被滿足。
結果值變動 RESULT_VALUE_CHANGES 結果與前一次檢查的值不同。 必須回傳恰好一列一欄。 該值必須不超過 1 MiB。

對於結果值變更,Azure Databricks 會在你儲存觸發器後立即在背景執行查詢,並將結果作為基準儲存。 這個檢查不會開始執行。 當結果與儲存值不同時,後續檢查會啟動一次執行。 更改觸發器的查詢、SQL 倉庫或條件類型會重置基準線,Azure Databricks 也會以相同方式儲存新的基準線。 暫停觸發條件或變更其他觸發條件設定也能將其重設。 編輯已儲存查詢的文字內容並不會重設它。

每次檢查的運作方式如下:

  • 檢查(包括 SQL 倉庫啟動)會在 5 分鐘後逾時。 如果檢查逾時,則不會開始任何執行作業,觸發器會在下一次評估時再次檢查。
  • 觸發器一次最多只會執行一項檢查。 如果觸發器到時,而檢查仍在進行中,Azure Databricks 會跳過該評估,而不是將其排入佇列。
  • 若查詢包含多個陳述,則僅使用最後陳述的結果。
  • SQL 條件只適用於由觸發器啟動的執行。 Run Now 和其他手動執行不會檢查 SQL 條件。

提示

對於 查詢回傳列,請確保當資料尚未準備好時,查詢回傳的列為零。 像這樣的 SELECT count(*) > 100 FROM main.sales.orders 查詢即使計數為 100 或更少,仍回傳一列,因此條件已達成。 改用 WHERE 或 HAVING 篩選:

SELECT 1
FROM main.sales.orders
WHERE order_date = current_date()
HAVING count(*) > 100

在觸發器中加入 SQL 條件

  1. 在工作區側邊欄,點選「工作與管線」,然後打開工作。
  2. 在 排程與觸發器中,點選 新增觸發器,或編輯現有觸發器。
  3. 選擇 觸發器類型 並設定觸發器。
  4. 展開 進階,然後按一下 新增 SQL 條件。
  5. 選擇 SQL 查詢 和 SQL 倉儲。
  6. 在 「觸發時」中,選擇 「查詢回傳列 」或 「結果值變更」。
  7. 選取儲存。

測試觸發器會檢查工作是否可以使用已儲存的查詢。 它會確認查詢存在、不在垃圾桶裡,也沒有參數,但不會執行查詢。 要看到查詢結果,請在 SQL 編輯器中執行查詢。

要移除條件,編輯觸發器,展開 進階,然後點擊 移除 SQL 條件。

用 API、CLI 或 bundles 進行配置

將 sql_condition 設定為 sql_query_id、warehouse_id 和 trigger_mode。 對於使用 cron 運算式的排程觸發器,請將其設為 schedule。 其他觸發器類型,請在觸發器類型設定旁的 trigger 上設定。 在 Multiple Triggers Beta 中,請在 triggers 的每個條目中進行設定。

REST API

將此請求儲存為 update-job.json,並在 Jobs API 中將其傳送到 POST /api/2.2/jobs/update。 用你的作業、儲存的查詢和 SQL 倉庫 ID 替換這些 ID。

{
  "job_id": 9001,
  "new_settings": {
    "trigger": {
      "pause_status": "UNPAUSED",
      "table_update": {
        "table_names": ["main.sales.orders"],
        "condition": "ANY_UPDATED"
      },
      "sql_condition": {
        "sql_query_id": "fe25e731-92f2-4838-9fb2-1ca364320a3d",
        "warehouse_id": "5d409943fcd32c6f",
        "trigger_mode": "QUERY_RETURNS_ROWS"
      }
    }
  }
}

CLI

將 REST API 分頁中的請求主體儲存為 update-job.json,然後執行:

databricks api post /api/2.2/jobs/update --json @update-job.json

套裝組合

對於 宣告式自動化套件,請在現有的工作資源中新增以下設定,連同其任務一起:

resources:
  jobs:
    orders_report:
      trigger:
        pause_status: UNPAUSED
        periodic:
          interval: 1
          unit: DAYS
        sql_condition:
          sql_query_id: fe25e731-92f2-4838-9fb2-1ca364320a3d
          warehouse_id: 5d409943fcd32c6f
          trigger_mode: RESULT_VALUE_CHANGES

Bundle 無法建立已儲存的查詢。 先在工作區建立查詢,然後參考它的 ID。

你傳送至 sql_condition 的 A jobs/update 會整體取代目前的項目,所以要包含它所有的欄位。 如果你省略了 sql_condition,目前的狀況就會維持不變。 要更新多個觸發器,請參見 「將多個觸發器新增至作業」。

監視 SQL 條件檢查

  • 對於排程觸發器,工作頁面的觸發狀態會顯示最新的 SQL 條件檢查是否被滿足。 點擊 查詢執行詳細資料,即可在 查詢歷史 中開啟該語句。
  • 要讀取最新且未出錯的檢查,請使用 include_trigger_state=true 呼叫 Get job API,並讀取 trigger_state.sql_condition。 該 latest_condition_evaluation_satisfied 欄位顯示該檢查是否符合條件,而 latest_condition_evaluation_sql_statement_id 會指出其在查詢歷史中的陳述式。 檢查失敗不會改變這些欄位。 關於多重觸發,請閱讀 trigger_details[].state.sql_condition。
  • 對於每個由 SQL 條件啟動的執行,執行清單中的 Launched 欄位和執行詳情頁面都會顯示一個 SQL 標籤。 點選它,然後點選 查詢執行細節,在查詢記錄中開啟該次執行的檢查項目。
  • 如果檢查因可修正的原因失敗,錯誤會顯示在工作頁面的觸發狀態中。 Azure Databricks 也會將錯誤訊息傳送到作業的失敗通知,包括電子郵件收件人和 webhook 目的地。 當工作條件開始失效時,你會收到一次通知,而不是每次檢查失敗都會收到通知。 錯誤會持續到下一次成功檢查。 請參閱 在作業上新增通知。

每個檢查都以 SQL 陳述式執行於你的 SQL 倉庫中。 若要檢視隨時間變化的檢查,請查詢資料倉儲的 查詢歷史系統資料表。

Troubleshooting

Issue Action
每次觸發觸發時,工作都會執行 對於 查詢回傳列,請將查詢改成當資料尚未準備好時,回傳零列。
結果值變更 絕不會啟動執行程序 基準是你儲存觸發器時的查詢結果。 執行只有在查詢結果從該值變更後才會開始。
檢查會逾時 讓查詢速度更快,或使用無伺服器 SQL 倉儲,其啟動速度更快。
新增 SQL 條件未顯示 展開進階。 如果按鈕還是不見,請請工作區管理員啟用 觸發器的 SQL 條件。

Limitations

  • 每個觸發器支援一個 SQL 條件。
  • 連續觸發器不支援 SQL 條件。
  • 條件查詢僅在 SQL 倉庫中以唯讀模式執行。
  • 檢查(包括 SQL 倉庫啟動)會在 5 分鐘後逾時。
  • 觸發器只會保留最新的檢查,而非每次檢查的完整歷史。 要查看先前的檢查,請在條件開始的執行中使用 SQL 標籤,或使用 查詢歷史記錄。
  • 檢查會在您的 SQL Warehouse 上執行,並以 SQL Warehouse 使用量計費。 一次檢查可以啟動一個停擺的倉儲。
  • 帶有 SQL 條件的觸發器會計入工作區 12,000 個有效觸發器的上限。