Tambahkan kondisi SQL ke pemicu job

Gunakan kondisi SQL untuk memeriksa data Anda sebelum proses job yang dipicu dimulai. Saat trigger dipicu, Azure Databricks menjalankan query SQL yang disimpan pada gudang SQL yang Anda pilih. Run hanya dimulai jika hasil query memenuhi kondisi. Misalnya, jalankan pekerjaan hanya ketika tabel upstream selesai dimuat atau pemeriksaan kualitas data telah lulus, tanpa menambahkan tugas pemeriksa terpisah ke pekerjaan tersebut.

Important

Fitur ini ada di Beta. Untuk menggunakannya, admin workspace harus mengaktifkan kondisi SQL untuk trigger dari halaman Pratinjau . Lihat Kelola Pratinjau Azure Databricks.

Requirements

  • Anda harus memiliki CAN MANAGE pada job tersebut untuk mengonfigurasi trigger-nya.
  • Anda membutuhkan query yang disimpan yang tidak menggunakan parameter query. Anda harus memiliki akses ke query dan dapat menjalankannya di SQL warehouse yang Anda pilih.
  • Run as identity milik pekerjaan harus dapat membuka query yang disimpan, memiliki CAN USE pada SQL warehouse, dan memiliki akses baca ke setiap tabel yang dibaca oleh query. Kueri kondisi dijalankan menggunakan identitas ini.

Cara kerja kondisi SQL

Pemicu menentukan kapan harus memeriksa. Kondisi SQL memutuskan apakah akan memulai sebuah run. Setelah trigger aktif, Azure Databricks menjalankan kueri dalam mode hanya-baca. Run hanya dimulai ketika kedua kondisi trigger dan SQL terpenuhi.

Anda dapat menambahkan satu kondisi SQL ke pemicu terjadwal, pemicu pembaruan tabel, pemicu kedatangan file, pemicu pembaruan model, atau pemicu penyelesaian pekerjaan. Pemicu kontinu tidak mendukung kondisi SQL.

Pilih bagaimana Azure Databricks mengevaluasi hasil query:

Jenis kondisi Nilai API Memulai proses saat Persyaratan kueri
Query mengembalikan baris QUERY_RETURNS_ROWS Hasilnya berisi setidaknya satu baris. None. Baris nol berarti kondisi tidak terpenuhi.
Perubahan nilai hasil RESULT_VALUE_CHANGES Hasilnya berbeda dari nilai pada pemeriksaan sebelumnya. Harus mengembalikan tepat satu baris dan satu kolom. Nilainya harus 1 MiB atau lebih kecil.

Untuk perubahan nilai Result, Azure Databricks menjalankan query di latar belakang tepat setelah Anda menyimpan trigger dan menyimpan hasilnya sebagai baseline. Pemeriksaan ini tidak memulai eksekusi. Pemeriksaan selanjutnya memulai run ketika hasilnya berbeda dari nilai yang disimpan. Mengubah jenis query, gudang SQL, atau jenis kondisi pada trigger akan mereset baseline, dan Azure Databricks menyimpan yang baru dengan cara yang sama. Menjeda trigger atau mengubah pengaturan trigger lainnya juga bisa mereset trigger. Mengedit teks dari kueri yang disimpan tidak mereset teks tersebut.

Setiap pemeriksaan bekerja sebagai berikut:

  • Sebuah pemeriksaan, termasuk startup SQL warehouse, akan mengalami time-out setelah 5 menit. Jika sebuah cek mengalami timeout, tidak ada run yang dimulai, dan trigger akan memeriksa lagi pada evaluasi berikutnya.
  • Trigger menjalankan paling banyak satu pemeriksaan dalam satu waktu. Jika pemicu jatuh tempo saat pemeriksaan masih berjalan, Azure Databricks melewati evaluasi tersebut alih-alih mengantrinya.
  • Jika kueri memiliki lebih dari satu pernyataan, hanya hasil dari pernyataan terakhir yang digunakan.
  • Kondisi SQL hanya berlaku untuk run yang dipicu oleh trigger. Jalankan sekarang dan eksekusi manual lainnya tidak memeriksa kondisi SQL.

Tip

Untuk Kueri mengembalikan baris, pastikan query mengembalikan nol baris ketika data belum siap. Query seperti SELECT count(*) > 100 FROM main.sales.orders mengembalikan satu baris bahkan ketika jumlahnya 100 atau kurang, sehingga kondisi terpenuhi. Filter dengan WHERE atau HAVING sebagai gantinya:

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

Tambahkan kondisi SQL ke trigger

  1. Di sidebar workspace, klik Jobs & Pipelines, lalu buka job tersebut.
  2. Di Jadwal & Pemicu, klik Tambah pemicu, atau edit pemicu yang sudah ada.
  3. Pilih tipe Trigger dan konfigurasikan trigger.
  4. Perluas Lanjutan, lalu klik Tambah kondisi SQL.
  5. Pilih kueri SQL dan SQL warehouse.
  6. Di bawah Trigger when, pilih Kueri mengembalikan baris atau Nilai hasil berubah.
  7. Kliklah Simpan.

Uji pemicu memeriksa bahwa job dapat menggunakan kueri yang disimpan. Ini mengonfirmasi bahwa query ada, tidak berada di trash, dan tidak memiliki parameter, tapi query tidak dijalankan. Untuk melihat hasil kueri, jalankan kueri di editor SQL.

Untuk menghapus suatu kondisi, edit pemicu, perluas Lanjutan, lalu klik Hapus kondisi SQL.

Konfigurasikan dengan API, CLI, atau bundle

Set sql_condition dengan sql_query_id, warehouse_id, dan trigger_mode. Untuk pemicu terjadwal yang menggunakan ekspresi cron, atur pemicu tersebut pada schedule. Untuk tipe trigger lain, atur pada trigger, di samping pengaturan tipe trigger. Dengan Multiple Triggers Beta, atur fitur ini pada setiap entri di triggers.

REST API

Simpan permintaan ini sebagai update-job.json dan kirimkan ke POST /api/2.2/jobs/update di API Jobs. Ganti ID tersebut dengan ID pekerjaan, query tersimpan, dan SQL warehouse milik Anda.

{
  "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

Simpan isi permintaan dari tab REST API sebagai update-job.json, lalu jalankan:

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

Bundles

Untuk Bundel Otomasi Deklaratif, tambahkan pengaturan berikut ke sumber daya pekerjaan yang sudah ada, beserta tugasnya:

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

Bundles tidak dapat membuat kueri yang disimpan. Buat kueri di workspace terlebih dahulu, lalu referensikan ID-nya.

Objek jobs/update yang Anda kirim ke sql_condition menggantikan objek yang saat ini ada secara keseluruhan, jadi sertakan semua bidangnya. Jika Anda menghilangkan sql_condition, kondisi saat ini tetap ada. Untuk memperbarui beberapa trigger, lihat Tambahkan beberapa trigger ke sebuah pekerjaan.

Pantau pemeriksaan kondisi SQL

  • Untuk trigger terjadwal, status trigger di halaman pekerjaan menunjukkan apakah pemeriksaan kondisi SQL terbaru telah terpenuhi. Klik Query execution details untuk membuka pernyataan di riwayat query.
  • Untuk membaca pemeriksaan terbaru yang berjalan tanpa error, panggil API Get job dengan include_trigger_state=true dan baca trigger_state.sql_condition. Bidang latest_condition_evaluation_satisfied menunjukkan apakah pemeriksaan tersebut memenuhi kondisi, dan latest_condition_evaluation_sql_statement_id mengidentifikasi pernyataannya dalam riwayat kueri. Pemeriksaan yang gagal tidak mengubah kolom-kolom ini. Dengan Pemicu Ganda, baca trigger_details[].state.sql_condition.
  • Untuk setiap run yang dimulai oleh kondisi SQL, field Launched di daftar run dan di halaman detail run menampilkan tag SQL . Klik item tersebut, lalu klik Query execution details untuk membuka pemeriksaan run tersebut di riwayat kueri.
  • Jika pemeriksaan gagal karena alasan yang bisa Anda perbaiki, kesalahan akan muncul di status pemicu di halaman pekerjaan. Azure Databricks juga mengirimkan error ke notifikasi kegagalan pekerjaan, termasuk penerima email dan tujuan webhook. Anda hanya mendapat satu notifikasi saat kondisi pemantauan mulai gagal, bukan satu untuk setiap pemeriksaan yang gagal. Kesalahan ini tetap ada hingga pemeriksaan berikutnya berhasil. Lihat Menambahkan pemberitahuan pada pekerjaan.

Setiap pemeriksaan berjalan sebagai pernyataan SQL di SQL warehouse Anda. Untuk meninjau pemeriksaan dari waktu ke waktu, jalankan kueri pada tabel sistem riwayat kueri untuk warehouse.

Troubleshooting

Masalah Action
Pekerjaan berjalan setiap kali trigger terpicu Untuk opsi Query returns rows, ubah kueri sehingga mengembalikan nol baris saat data belum siap.
Perubahan nilai hasil tidak pernah memulai proses Baseline adalah hasil query pada saat Anda menyimpan trigger. Run hanya dimulai setelah hasil query berubah dari nilai tersebut.
Pemeriksaan mengalami habis waktu Buat kueri lebih cepat, atau gunakan serverless SQL warehouse, yang aktif lebih cepat.
Kondisi Add SQL tidak muncul Perluas Advanced. Jika tombol masih hilang, minta admin workspace untuk mengaktifkan kondisi SQL untuk trigger.

Limitations

  • Setiap trigger mendukung satu kondisi SQL.
  • Trigger kontinu tidak mendukung kondisi SQL.
  • Kueri kondisi hanya berjalan pada gudang SQL, dalam mode hanya-baca.
  • Sebuah pemeriksaan, termasuk startup SQL warehouse, akan mengalami batas waktu setelah 5 menit.
  • Trigger hanya menyimpan pemeriksaan terbarunya, bukan riwayat lengkap setiap pemeriksaan. Untuk melihat pemeriksaan sebelumnya, gunakan tag SQL pada run yang dimulai oleh kondisi, atau riwayat query.
  • Pemeriksaan dijalankan pada gudang SQL Anda dan ditagih sebagai penggunaan gudang SQL. Pengecekan dapat memulai gudang yang berhenti.
  • Pemicu dengan kondisi SQL dihitung dalam batas workspace sebanyak 12.000 pemicu aktif.