Widget Databricks

Widget input memungkinkan Anda menambahkan parameter ke buku catatan dan dasbor Anda. Anda dapat menambahkan widget dari UI Databricks atau menggunakan API widget. Untuk menambahkan atau mengedit widget, Anda harus memiliki izin EDIT BISA di buku catatan.

Jika Anda menjalankan Databricks Runtime 11.3 LTS atau lebih tinggi, Anda juga dapat menggunakan ipywidgets di notebook Databricks.

Widget Databricks adalah pilihan terbaik untuk:

• Membangun buku catatan atau dasbor yang dijalankan ulang dengan parameter yang berbeda.
• Menjelajahi hasil kueri tunggal dengan parameter yang berbeda dengan cepat.

Untuk melihat dokumentasi api widget di Scala, Python, atau R, gunakan perintah berikut: dbutils.widgets.help()

Jenis widget Databricks

Ada 4 jenis widget:

• text: Memasukkan nilai di kotak teks.
• dropdown: Memilih nilai dari daftar nilai yang disediakan.
• combobox: Kombinasi teks dan dropdown. Pilih nilai dari daftar yang disediakan atau masukkan nilai dalam kotak teks.
• multiselect: Memilih satu atau beberapa nilai dari daftar nilai yang disediakan.

Dropdown widget dan kotak teks akan muncul segera setelah toolbar buku catatan. Widget hanya menerima nilai string.

Membuat widget

Bagian ini menunjukkan kepada Anda cara membuat widget menggunakan UI atau secara terprogram menggunakan sihir SQL atau API widget untuk Python, Scala, dan R.

Membuat widget menggunakan UI

Buat widget menggunakan UI notebook. Jika Anda terhubung ke gudang SQL, ini adalah satu-satunya cara Anda dapat membuat widget.

Pilih Edit > Tambahkan widget. Dalam dialog Tambahkan widget, masukkan nama widget, label opsional, jenis, jenis parameter, nilai yang mungkin, dan nilai default opsional. Dalam dialog, Nama Parameter adalah nama yang Anda gunakan untuk mereferensikan widget dalam kode Anda. Label Widget adalah nama opsional yang muncul di atas widget di UI.

Setelah membuat widget, Anda dapat mengarahkan mouse ke atas nama widget untuk menampilkan tipsalat yang menjelaskan cara mereferensikan widget.

Anda dapat menggunakan menu kebab untuk mengedit atau menghapus widget:

Membuat widget dengan SQL, Python, R, dan Scala

Buat widget secara terprogram di notebook yang dilampirkan ke kluster komputasi.

API widget dirancang agar konsisten di Scala, Python, dan R. API widget di SQL sedikit berbeda tetapi setara dengan bahasa lain. Anda mengelola widget melalui antarmuka referensi Utilitas Databricks (dbutils).

• Argumen pertama untuk semua jenis widget adalah name. Ini adalah nama yang Anda gunakan untuk mengakses widget.
• Argumen kedua adalah defaultValue, pengaturan default widget.
• Argumen ketiga untuk semua jenis widget (kecuali text) adalah choices, daftar nilai yang dapat diambil widget. Argumen ini tidak digunakan untuk text widget jenis.
• Argumen terakhir adalah label, nilai opsional untuk label yang ditampilkan di atas kotak teks widget atau dropdown.

Python

dbutils.widgets.dropdown("state", "CA", ["CA", "IL", "MI", "NY", "OR", "VA"])

Scala

dbutils.widgets.dropdown("state", "CA", ["CA", "IL", "MI", "NY", "OR", "VA"])

R

dbutils.widgets.dropdown("state", "CA", ["CA", "IL", "MI", "NY", "OR", "VA"])

SQL

CREATE WIDGET DROPDOWN state DEFAULT "CA" CHOICES SELECT * FROM (VALUES ("CA"), ("IL"), ("MI"), ("NY"), ("OR"), ("VA"))

Lakukan interaksi dengan widget dari panel widget.

Anda dapat mengakses nilai widget saat ini atau mendapatkan pemetaan semua widget:

Python

dbutils.widgets.get("state")

dbutils.widgets.getAll()

Scala

dbutils.widgets.get("state")

dbutils.widgets.getAll()

R

dbutils.widgets.get("state")

SQL

SELECT :state

Terakhir, Anda dapat menghapus widget atau semua widget di buku catatan:

Python

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

Scala

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

R

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

SQL

REMOVE WIDGET state

Jika Anda menghapus widget, Anda tidak dapat membuatnya di sel yang sama. Anda harus membuat widget di sel lain.

Menggunakan nilai widget di Spark SQL dan SQL Warehouse

Nilai widget akses Spark SQL dan SQL Warehouse menggunakan penanda parameter. Penanda parameter melindungi kode Anda dari serangan injeksi SQL dengan memisahkan nilai yang disediakan dengan jelas dari pernyataan SQL.

Penanda parameter untuk widget tersedia di Databricks Runtime 15.2 ke atas. Versi Databricks Runtime sebelumnya harus menggunakan sintaks lama untuk DBR 15.1 ke bawah.

Anda dapat mengakses widget yang ditentukan dalam bahasa apa pun dari SQL Spark saat mengeksekusi notebook secara interaktif. Pertimbangkan alur kerja berikut:

1. Buat widget dropdown dari semua database di katalog saat ini:

   dbutils.widgets.dropdown("database", "default", [database[0] for database in spark.catalog.listDatabases()])
   

2. Buat widget teks untuk menentukan nama tabel secara manual:

   dbutils.widgets.text("table", "")
   

3. Jalankan kueri SQL untuk melihat semua tabel dalam database (dipilih dari daftar dropdown):

   SHOW TABLES IN IDENTIFIER(:database)
   

   Catatan

   Anda harus menggunakan klausul SQL IDENTIFIER() untuk mengurai string sebagai pengidentifikasi objek seperti nama untuk database, tabel, tampilan, fungsi, kolom, dan bidang.

4. Masukkan nama tabel secara manual ke widget table.

5. Buat widget teks untuk menentukan nilai filter:

   dbutils.widgets.text("filter_value", "")
   

6. Pratinjau konten tabel tanpa perlu mengedit konten kueri:

   SELECT *
   FROM IDENTIFIER(:database || '.' || :table)
   WHERE col == :filter_value
   LIMIT 100
   

Gunakan nilai widget di Databricks Runtime 15.1 ke bawah

Bagian ini menjelaskan cara meneruskan nilai widget Databricks ke %sql sel buku catatan di Databricks Runtime 15.1 ke bawah.

1. Buat widget untuk menentukan nilai teks.

Python

 dbutils.widgets.text("database", "")
 dbutils.widgets.text("table", "")
 dbutils.widgets.text("filter_value", "100")

Scala

 dbutils.widgets.text("database", "")
 dbutils.widgets.text("table", "")
 dbutils.widgets.text("filter_value", "100")

R

 dbutils.widgets.text("database", "")
 dbutils.widgets.text("table", "")
 dbutils.widgets.text("filter_value", "100")

SQL

 CREATE WIDGET TEXT database DEFAULT ""
 CREATE WIDGET TEXT table DEFAULT ""
 CREATE WIDGET TEXT filter_value DEFAULT "100"

1. Teruskan nilai widget menggunakan ${param} sintaks.

   SELECT *
   FROM ${database}.${table}
   WHERE col == ${filter_value}
   LIMIT 100
   

Catatan

Untuk melakukan escape karakter $ dalam untai (karakter) harfiah SQL, gunakan \$. Misalnya, untuk mengekspresikan string $1,000, gunakan "\$1,000". Karakter $ tidak dapat di-escape untuk pengidentifikasi SQL.

Mengonfigurasi pengaturan widget

Anda dapat mengonfigurasi perilaku widget saat nilai baru dipilih, apakah panel widget selalu disematkan ke bagian atas buku catatan, dan mengubah tata letak widget di buku catatan.

1. Klik ikon di ujung kanan panel Widget.

2. Dalam kotak dialog pop-up Pengaturan Panel Widget, pilih perilaku eksekusi widget.

   

   • Jalankan Buku Catatan: Setiap kali nilai baru dipilih, seluruh buku catatan dijalankan ulang.
   • Jalankan Perintah Yang Diakses: Setiap kali nilai baru dipilih, artinya hanya sel yang mengambil nilai untuk widget tersebut saja yang dijalankan ulang. Pengaturan ini adalah pengaturan default saat Anda membuat widget. Sel SQL tidak dijalankan ulang dalam konfigurasi ini.
   • Jangan Lakukan Apa-apa: Setiap kali nilai baru dipilih, tidak ada yang dijalankan ulang.

3. Untuk menyematkan widget ke bagian atas notebook atau untuk menempatkan widget di atas sel pertama, klik . Pengaturan disimpan untuk setiap pengguna. Klik lagi ikon thumbtack untuk mengatur ulang ke perilaku default.

4. Jika Anda memiliki izin KELOLA BISA untuk buku catatan, Anda bisa mengonfigurasi tata letak widget dengan mengklik . Urutan dan ukuran setiap widget dapat disesuaikan. Untuk menyimpan atau menutup perubahan Anda, klik .

   Tata letak widget disimpan dengan buku catatan. Jika Anda mengubah tata letak widget dari konfigurasi default, widget baru tidak ditambahkan menurut abjad.

5. Untuk mengatur ulang tata letak widget ke urutan dan ukuran default, klik untuk membuka dialog Pengaturan Panel Widget lalu klik Reset Tata Letak. Perintah removeAll() tidak mengatur ulang tata letak widget.

Contoh notebook

Buku catatan berikut ini memperlihatkan cara kerja pengaturan Jalankan Perintah yang Diakses. year Widget dibuat dengan pengaturan 2014 dan digunakan dalam perintah DataFrame API dan SQL.

Saat Anda mengubah pengaturan widget year menjadi 2007, perintah DataFrame akan dijalankan ulang, tetapi perintah SQL tidak akan dijalankan ulang.

Notebook ini mengilustrasikan penggunaan widget dalam notebook yang dilampirkan ke kluster, bukan gudang SQL.

Buku catatan demo widget

Dapatkan buku catatan

Widget Databricks di dasbor

Saat Anda membuat dasbor dari notebook dengan widget input, semua widget ditampilkan di bagian atas. Dalam mode presentasi, setiap kali Memperbarui nilai widget, Anda bisa mengklik tombol Perbarui untuk menjalankan kembali buku catatan dan memperbarui dasbor Anda dengan nilai baru.

Gunakan widget Databricks dengan %run

Jika Anda menjalankan buku catatan yang berisi widget, buku catatan yang ditentukan akan dijalankan dengan nilai default widget.

Jika notebook dilampirkan ke kluster (bukan gudang SQL), Anda juga dapat meneruskan nilai ke widget. Contohnya:

%run /path/to/notebook $X="10" $Y="1"

Contoh ini menjalankan buku catatan yang ditentukan dan meneruskan 10 ke widget X dan 1 ke widget Y.

Batasan

• Batas berikut berlaku untuk widget:

  • Maksimal 512 widget dapat dibuat di notebook.
  • Nama widget dibatasi hingga 1024 karakter.
  • Label widget dibatasi hingga 2048 karakter.
  • Maksimal 2048 karakter dapat dimasukkan ke widget teks.
  • Mungkin ada maksimal 1024 pilihan untuk widget multi-pilih, kotak kombo, atau dropdown.

• Ada masalah yang diketahui di mana status widget mungkin tidak jelas dengan benar setelah menekan Jalankan Semua, bahkan setelah menghapus atau menghapus widget dalam kode. Jika ini terjadi, Anda akan melihat perbedaan antara visual widget dan status cetak. Menjalankan kembali sel satu per satu dapat melewati masalah ini. Untuk menghindari masalah ini sepenuhnya, Databricks merekomendasikan penggunaan ipywidgets.

• Anda tidak boleh mengakses status widget secara langsung dalam konteks asinkron seperti utas, subproses, atau Streaming Terstruktur (foreachBatch), karena status widget dapat berubah saat kode asinkron sedang berjalan. Jika Anda perlu mengakses status widget dalam konteks asinkron, teruskan sebagai argumen. Misalnya, jika Anda memiliki kode berikut yang menggunakan utas:

  import threading
  
  def thread_func():
    # Unsafe access in a thread
    value = dbutils.widgets.get('my_widget')
    print(value)
  
  thread = threading.Thread(target=thread_func)
  thread.start()
  thread.join()
  

  Maka Anda harus menulisnya dengan cara ini sebagai gantinya:

  # Access widget values outside the asynchronous context and pass them to the function
  value = dbutils.widgets.get('my_widget')
  
  def thread_func(val):
    # Use the passed value safely inside the thread
    print(val)
  
  thread = threading.Thread(target=thread_func, args=(value,))
  thread.start()
  thread.join()
  

• Secara umum, widget tidak dapat meneruskan argumen antara bahasa yang berbeda dalam buku catatan. Anda dapat membuat widget arg1 di sel Python dan menggunakannya di sel SQL atau Scala jika Anda menjalankan satu sel sekaligus. Namun, ini tidak berfungsi jika Anda menggunakan Jalankan Semua atau jalankan buku catatan sebagai pekerjaan. Beberapa pekerjaan di sekitar adalah:

  • Untuk buku catatan yang tidak mencampur bahasa, Anda bisa membuat buku catatan untuk setiap bahasa dan meneruskan argumen saat Menjalankan buku catatan.
  • Anda dapat mengakses widget menggunakan spark.sql() panggilan. Misalnya, di Python: spark.sql("select getArgument('arg1')").take(1)[0][0].