Widget Databricks

Artikel
01/30/2025

Widget input memungkinkan Anda menambahkan parameter ke notebook 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(). Anda juga dapat merujuk ke dokumentasi utilitas widget (dbutils.widgets).

Ada 4 jenis widget:

text: Memasukkan nilai di kotak teks.
dropdown: Pilih nilai dari daftar nilai yang disediakan.
combobox: Kombinasi teks dan dropdown. Pilih nilai dari daftar atau input yang disediakan di kotak teks.
multiselect: Pilih 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 notebook:

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.

Nilai widget akses untuk 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:

Buat widget dropdown dari semua database di katalog saat ini:

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

Buat widget teks untuk menentukan nama tabel secara manual:
```
dbutils.widgets.text("table", "")
```
Jalankan kueri SQL untuk melihat semua tabel dalam database (dipilih dari daftar dropdown):
```
SHOW TABLES IN IDENTIFIER(:database)
```
Catatan

Anda harus menggunakan klausa SQL IDENTIFIER() untuk mengurai string sebagai pengidentifikasi objek seperti nama untuk database, tabel, tampilan, fungsi, kolom, dan bidang.
Masukkan nama tabel secara manual ke widget table.
Buat widget teks untuk menentukan nilai filter:
```
dbutils.widgets.text("filter_value", "")
```

Pratinjau konten tabel tanpa perlu mengedit konten kueri:

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

Bagian ini menjelaskan cara meneruskan nilai widget Databricks ke sel notebook %sql di Databricks Runtime versi 15.1 dan yang lebih rendah.

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"

Teruskan nilai widget menggunakan sintaks ${param}.

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.

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.

Klik ikon di ujung kanan panel Widget.
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, hanya sel yang mengambil nilai untuk widget tertentu 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.
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.
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.
Untuk mengatur ulang tata letak widget ke urutan dan ukuran default, klik ikon gigi untuk membuka dialog Pengaturan Panel Widget lalu klik Reset Tata Letak. Perintah removeAll() tidak mengatur ulang tata letak widget.