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
) adalahchoices
, daftar nilai yang dapat diambil widget. Argumen ini tidak digunakan untuktext
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:
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 klausul 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
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.
- 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
${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.
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, 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.
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 mereset 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
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
Lihat Buku catatan Databricks batasan yang diketahui untuk informasi selengkapnya.
Saran dan Komentar
https://aka.ms/ContentUserFeedback.
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat:Kirim dan lihat umpan balik untuk