Referensi Utilitas Databricks (dbutils
)
Artikel ini berisi referensi untuk Utilitas Databricks (dbutils
). Utilitas menyediakan perintah yang memungkinkan Anda bekerja dengan lingkungan Databricks Anda dari notebook. Misalnya, Anda dapat mengelola file dan penyimpanan objek, dan bekerja dengan rahasia.
dbutils
tersedia di notebook Python, R, dan Scala.
Catatan
dbutils
hanya mendukung lingkungan komputasi yang menggunakan DBFS.
modul Utilitas
Tabel berikut mencantumkan modul Utilitas Databricks, yang dapat Anda ambil menggunakan dbutils.help()
.
Modul | Deskripsi |
---|---|
data | Utilitas untuk memahami dan berinteraksi dengan himpunan data (EKSPERIMENTAL) |
fs | Utilitas untuk mengakses sistem file Databricks (DBFS) |
pekerjaan | Utilitas untuk memanfaatkan fitur pekerjaan |
pustaka | Tidak direkomendasikan. Utilitas untuk mengelola pustaka yang berbasis sesi |
buku catatan | Utilitas untuk mengelola alur kontrol buku catatan (EKSPERIMENTAL) |
rahasia | Utilitas untuk memanfaatkan rahasia dalam notebook |
widget | Utilitas untuk parameterisasi notebook. |
api | Utilitas untuk mengelola build aplikasi |
Bantuan Perintah
Untuk mencantumkan perintah untuk modul utilitas bersama dengan deskripsi singkat dari setiap perintah, tambahkan .help()
setelah nama modul utilitas. Contoh berikut mencantumkan perintah yang tersedia untuk utilitas notebook:
dbutils.notebook.help()
The notebook module.
exit(value: String): void -> This method lets you exit a notebook with a value
run(path: String, timeoutSeconds: int, arguments: Map): String -> This method runs a notebook and returns its exit value
Untuk menampilkan bantuan untuk perintah, jalankan dbutils.<utility-name>.help("<command-name>")
. Contoh berikut menampilkan bantuan untuk perintah salin utilitas sistem file, dbutils.fs.cp
:
dbutils.fs.help("cp")
/**
* Copies a file or directory, possibly across FileSystems.
*
* Example: cp("/mnt/my-folder/a", "dbfs:/a/b")
*
* @param from FileSystem URI of the source file or directory
* @param to FileSystem URI of the destination file or directory
* @param recurse if true, all files and directories will be recursively copied
* @return true if all files were successfully copied
*/
cp(from: java.lang.String, to: java.lang.String, recurse: boolean = false): boolean
Utilitas data (dbutils.data)
Penting
Fitur ini ada di Pratinjau Publik.
Catatan
Tersedia untuk Databricks Runtime 9.0 ke atas.
Utilitas data memungkinkan Anda memahami dan berinteraksi dengan himpunan data.
Tabel berikut mencantumkan perintah yang tersedia untuk utilitas ini, yang dapat Anda ambil menggunakan dbutils.data.help()
.
Perintah | Deskripsi |
---|---|
meringkas | Meringkas Spark DataFrame dan memvisualisasikan statistik untuk mendapatkan wawasan cepat |
perintah meringkas (dbutils.data.summarize)
Catatan
Fitur ini ada di Pratinjau Publik.
summarize(df: Object, precise: boolean): void
Menghitung dan menampilkan statistik ringkasan dari Apache Spark DataFrame atau DataFrame panda. Perintah ini tersedia untuk Python, Scala, dan R.
Penting
Perintah ini menganalisis konten lengkap DataFrame. Menjalankan perintah ini untuk DataFrame yang sangat besar bisa sangat mahal.
Untuk menampilkan bantuan lengkap untuk perintah ini, jalankan:
dbutils.data.help("summarize")
Dalam Databricks Runtime 10.4 LTS ke atas, Anda dapat menggunakan parameter tambahan precise
untuk menyesuaikan presisi statistik komputasi.
- Ketika
precise
diatur ke false (default), beberapa statistik yang dikembalikan menyertakan estimasi untuk mengurangi waktu proses.- Jumlah nilai berbeda pada kolom kategoris mungkin memiliki kesalahan relatif sekitar ~5% untuk kolom dengan kardinalitas tinggi.
- Jumlah nilai frekuen mungkin mengalami kesalahan hingga 0,01% ketika jumlah nilai yang berbeda lebih dari 10.000.
- Histogram dan perkiraan persentil mungkin memiliki kesalahan hingga 0,01% relatif terhadap jumlah total baris.
- Ketika
precise
diatur ke true, statistik dihitung dengan presisi yang lebih tinggi. Semua statistik kecuali histogram dan persentil untuk kolom numerik sekarang tepat.- Histogram dan perkiraan persentil mungkin memiliki kesalahan hingga 0,0001% relatif terhadap jumlah total baris.
Tipsalat di bagian atas output ringkasan data menunjukkan mode eksekusi saat ini.
Contoh
Contoh ini menampilkan statistik ringkasan untuk Apache Spark DataFrame dengan perkiraan diaktifkan secara default. Untuk melihat hasilnya, jalankan perintah ini di notebook. Contoh ini didasarkan pada Himpunan data Sampel.
Python
df = spark.read.format('csv').load(
'/databricks-datasets/Rdatasets/data-001/csv/ggplot2/diamonds.csv',
header=True,
inferSchema=True
)
dbutils.data.summarize(df)
R
df <- read.df("/databricks-datasets/Rdatasets/data-001/csv/ggplot2/diamonds.csv", source = "csv", header="true", inferSchema = "true")
dbutils.data.summarize(df)
Scala
val df = spark.read.format("csv")
.option("inferSchema", "true")
.option("header", "true")
.load("/databricks-datasets/Rdatasets/data-001/csv/ggplot2/diamonds.csv")
dbutils.data.summarize(df)
Visualisasi menggunakan notasi SI untuk merender nilai numerik secara ringkas lebih kecil dari 0,01 atau lebih besar dari 10000. Sebagai contoh, nilai numerik 1.25e-15
akan dirender sebagai 1.25f
. Satu pengecualian: visualisasi menggunakan "B
" untuk 1.0e9
(giga) bukan "G
".
Utilitas sistem file (dbutils.fs)
Utilitas sistem file memungkinkan Anda mengakses Apa itu DBFS?, sehingga lebih mudah menggunakan Azure Databricks sebagai sistem file.
Peringatan
Implementasi Python dari semua dbutils.fs
metode menggunakan snake_case
daripada camelCase
untuk pemformatan kata kunci.
Misalnya, dbutils.fs.help()
menampilkan opsi extraConfigs
untuk dbutils.fs.mount()
. Namun, di Python Anda akan menggunakan kata kunci extra_configs
.
Tabel berikut mencantumkan perintah yang tersedia untuk utilitas ini, yang dapat Anda ambil menggunakan dbutils.fs.help()
.
Perintah | Deskripsi |
---|---|
cp | Menyalin file atau direktori, mungkin di seluruh FileSystems |
kepala | Mengembalikan hingga byte-byte 'maxBytes' pertama dari file yang diberikan sebagai string yang dikodekan dalam UTF-8 |
ls | Mencantumkan isi direktori |
mkdirs | Membuat direktori yang diberikan jika tidak ada, juga membuat direktori induk yang diperlukan |
pemasangan | Memasang direktori sumber yang diberikan ke DBFS pada titik pemasangan yang diberikan |
pemasangan | Menampilkan informasi tentang apa yang dipasang dalam DBFS |
mv | Memindahkan file atau direktori, mungkin di seluruh Sistem Berkas |
taruh | Menulis String yang diberikan ke berkas, dikodekan dalam UTF-8 |
segarkanPemasangan | Memaksa semua komputer dalam kluster ini untuk menyegarkan cache pemasangan mereka, memastikan mereka menerima informasi terbaru |
rm | Menghapus file atau direktori |
melepas | Menghapus titik pemasangan DBFS |
perbaruiMount | Mirip dengan mount(), tetapi memperbarui titik pemasangan yang ada alih-alih membuat yang baru |
Tips
Di notebook, Anda dapat menggunakan %fs
perintah ajaib untuk mengakses DBFS. Misalnya, %fs ls /Volumes/main/default/my-volume/
sama dengan dbutils.fs.ls("/Volumes/main/default/my-volume/")
. Lihat perintah sihir.
perintah cp (dbutils.fs.cp)
cp(from: String, to: String, recurse: boolean = false): boolean
Menyalin file atau direktori, mungkin di seluruh filesystem.
Untuk menampilkan bantuan lengkap untuk perintah ini, jalankan:
dbutils.fs.help("cp")
Contoh
Contoh ini menyalin file bernama data.csv
dari /Volumes/main/default/my-volume/
ke new-data.csv
dalam volume yang sama.
Python
dbutils.fs.cp("/Volumes/main/default/my-volume/data.csv", "/Volumes/main/default/my-volume/new-data.csv")
# Out[4]: True
R
dbutils.fs.cp("/Volumes/main/default/my-volume/data.csv", "/Volumes/main/default/my-volume/new-data.csv")
# [1] TRUE
Scala
dbutils.fs.cp("/Volumes/main/default/my-volume/data.csv", "/Volumes/main/default/my-volume/new-data.csv")
// res3: Boolean = true
perintah head (dbutils.fs.head)
head(file: String, maxBytes: int = 65536): String
Mengembalikan hingga jumlah maksimum byte yang ditentukan dalam file yang diberikan. Byte dikembalikan sebagai string yang dikodekan UTF-8.
Untuk menampilkan bantuan lengkap untuk perintah ini, jalankan:
dbutils.fs.help("head")
Contoh
Contoh ini menampilkan 25 byte pertama dari file data.csv
yang berada di /Volumes/main/default/my-volume/
.
Python
dbutils.fs.head("/Volumes/main/default/my-volume/data.csv", 25)
# [Truncated to first 25 bytes]
# Out[12]: 'Year,First Name,County,Se'
R
dbutils.fs.head("/Volumes/main/default/my-volume/data.csv", 25)
# [1] "Year,First Name,County,Se"
Scala
dbutils.fs.head("/Volumes/main/default/my-volume/data.csv", 25)
// [Truncated to first 25 bytes]
// res4: String =
// "Year,First Name,County,Se"
perintah ls (dbutils.fs.ls)
ls(dir: String): Seq
Mencantumkan konten direktori.
Untuk menampilkan bantuan lengkap untuk perintah ini, jalankan:
dbutils.fs.help("ls")
Contoh
Contoh ini menampilkan informasi tentang konten /Volumes/main/default/my-volume/
. Bidang modificationTime
ini tersedia di Databricks Runtime 10.4 LTS ke atas. Dalam R, modificationTime
dikembalikan sebagai string.
Python
dbutils.fs.ls("/Volumes/main/default/my-volume/")
# Out[13]: [FileInfo(path='dbfs:/Volumes/main/default/my-volume/data.csv', name='data.csv', size=2258987, modificationTime=1711357839000)]
R
dbutils.fs.ls("/Volumes/main/default/my-volume/")
# For prettier results from dbutils.fs.ls(<dir>), please use `%fs ls <dir>`
# [[1]]
# [[1]]$path
# [1] "/Volumes/main/default/my-volume/data.csv"
# [[1]]$name
# [1] "data.csv"
# [[1]]$size
# [1] 2258987
# [[1]]$isDir
# [1] FALSE
# [[1]]$isFile
# [1] TRUE
# [[1]]$modificationTime
# [1] "1711357839000"
Scala
dbutils.fs.ls("/tmp")
// res6: Seq[com.databricks.backend.daemon.dbutils.FileInfo] = WrappedArray(FileInfo(/Volumes/main/default/my-volume/data.csv, 2258987, 1711357839000))
perintah mkdirs (dbutils.fs.mkdirs)
mkdirs(dir: String): boolean
Membuat direktori yang diberikan jika tidak ada. Juga membuat direktori induk yang diperlukan.
Untuk menampilkan bantuan lengkap untuk perintah ini, jalankan:
dbutils.fs.help("mkdirs")
Contoh
Contoh ini membuat direktori my-data
dalam /Volumes/main/default/my-volume/
.
Python
dbutils.fs.mkdirs("/Volumes/main/default/my-volume/my-data")
# Out[15]: True
R
dbutils.fs.mkdirs("/Volumes/main/default/my-volume/my-data")
# [1] TRUE
Scala
dbutils.fs.mkdirs("/Volumes/main/default/my-volume/my-data")
// res7: Boolean = true
perintah mount (dbutils.fs.mount)
mount(source: String, mountPoint: String, encryptionType: String = "",
owner: String = null, extraConfigs: Map = Map.empty[String, String]): boolean
Memasang direktori sumber yang ditentukan ke dalam DBFS pada titik pemasangan yang ditentukan.
Untuk menampilkan bantuan lengkap untuk perintah ini, jalankan:
dbutils.fs.help("mount")
Contoh
Python
dbutils.fs.mount(
source = "wasbs://<container-name>@<storage-account-name>.blob.core.windows.net",
mount_point = "/mnt/<mount-name>",
extra_configs = {"<conf-key>":dbutils.secrets.get(scope = "<scope-name>", key = "<key-name>")})
Scala
dbutils.fs.mount(
source = "wasbs://<container-name>@<storage-account-name>.blob.core.windows.net/<directory-name>",
mountPoint = "/mnt/<mount-name>",
extraConfigs = Map("<conf-key>" -> dbutils.secrets.get(scope = "<scope-name>", key = "<key-name>")))
Untuk contoh kode tambahan, lihat Menyambungkan ke Azure Data Lake Storage Gen2 dan Blob Storage.
perintah mounts (dbutils.fs.mounts)
mounts: Seq
Menampilkan informasi tentang apa yang saat ini dipasang dalam DBFS.
Untuk menampilkan bantuan lengkap untuk perintah ini, jalankan:
dbutils.fs.help("mounts")
Contoh
Peringatan
Panggil dbutils.fs.refreshMounts()
semua kluster lain yang sedang berjalan untuk menyebarluaskan pemasangan baru. Lihat perintah refreshMounts (dbutils.fs.refreshMounts).
Python
dbutils.fs.mounts()
Scala
dbutils.fs.mounts()
Untuk contoh kode tambahan, lihat Menyambungkan ke Azure Data Lake Storage Gen2 dan Blob Storage.
perintah mv (dbutils.fs.mv)
mv(from: String, to: String, recurse: boolean = false): boolean
Memindahkan file atau direktori, mungkin di seluruh filesystem. Memindahkan adalah penyalinan yang diikuti oleh penghapusan, bahkan untuk perpindahan dalam filesystem.
Untuk menampilkan bantuan lengkap untuk perintah ini, jalankan:
dbutils.fs.help("mv")
Contoh
Contoh ini memindahkan file rows.csv
dari /Volumes/main/default/my-volume/
ke /Volumes/main/default/my-volume/my-data/
.
Python
dbutils.fs.mv("/Volumes/main/default/my-volume/rows.csv", "/Volumes/main/default/my-volume/my-data/")
# Out[2]: True
R
dbutils.fs.mv("/Volumes/main/default/my-volume/rows.csv", "/Volumes/main/default/my-volume/my-data/")
# [1] TRUE
Scala
dbutils.fs.mv("/Volumes/main/default/my-volume/rows.csv", "/Volumes/main/default/my-volume/my-data/")
// res1: Boolean = true
perintah put (dbutils.fs.put)
put(file: String, contents: String, overwrite: boolean = false): boolean
Menulis string tertentu ke file. String dikodekan UTF-8.
Untuk menampilkan bantuan lengkap untuk perintah ini, jalankan:
dbutils.fs.help("put")
Contoh
Contoh ini menulis string Hello, Databricks!
ke file bernama hello.txt
di /Volumes/main/default/my-volume/
. Jika file ada, file akan ditimpa.
Python
dbutils.fs.put("/Volumes/main/default/my-volume/hello.txt", "Hello, Databricks!", True)
# Wrote 2258987 bytes.
# Out[6]: True
R
dbutils.fs.put("/Volumes/main/default/my-volume/hello.txt", "Hello, Databricks!", TRUE)
# [1] TRUE
Scala
dbutils.fs.put("/Volumes/main/default/my-volume/hello.txt", "Hello, Databricks!", true)
// Wrote 2258987 bytes.
// res2: Boolean = true
perintah refreshMounts (dbutils.fs.refreshMounts)
refreshMounts: boolean
Memaksa semua komputer dalam kluster untuk me-refresh cache pemasangan mereka, memastikan mereka menerima informasi terbaru.
Untuk menampilkan bantuan lengkap untuk perintah ini, jalankan:
dbutils.fs.help("refreshMounts")
Contoh
Python
dbutils.fs.refreshMounts()
Scala
dbutils.fs.refreshMounts()
Untuk contoh kode aditif, lihat Menyambungkan ke Azure Data Lake Storage Gen2 dan Blob Storage.
perintah rm (dbutils.fs.rm)
rm(dir: String, recurse: boolean = false): boolean
Menghapus file atau direktori dan, secara opsional, semua kontennya. Jika file ditentukan, recurse
parameter diabaikan. Jika direktori ditentukan, kesalahan terjadi ketika recurse
dinonaktifkan dan direktori tidak kosong.
Untuk menampilkan bantuan lengkap untuk perintah ini, jalankan:
dbutils.fs.help("rm")
Contoh
Contoh ini menghapus seluruh direktori /Volumes/main/default/my-volume/my-data/
termasuk kontennya.
Python
dbutils.fs.rm("/Volumes/main/default/my-volume/my-data/", True)
# Out[8]: True
R
dbutils.fs.rm("/Volumes/main/default/my-volume/my-data/", TRUE)
# [1] TRUE
Scala
dbutils.fs.rm("/Volumes/main/default/my-volume/my-data/", true)
// res6: Boolean = true
perintah unmount (dbutils.fs.unmount)
unmount(mountPoint: String): boolean
Menghapus titik pemasangan DBFS.
Peringatan
Untuk menghindari kesalahan, jangan pernah memodifikasi titik pemasangan saat pekerjaan lain sedang membaca atau menulis ke dalamnya. Setelah memodifikasi pemasangan, selalu jalankan dbutils.fs.refreshMounts()
pada semua kluster lain yang sedang berjalan untuk menyebarluaskan pembaruan pemasangan apa pun. Lihat perintah refreshMounts (dbutils.fs.refreshMounts).
Untuk menampilkan bantuan lengkap untuk perintah ini, jalankan:
dbutils.fs.help("unmount")
Contoh
dbutils.fs.unmount("/mnt/<mount-name>")
Untuk contoh kode tambahan, lihat Menyambungkan ke Azure Data Lake Storage Gen2 dan Blob Storage.
perintah updateMount (dbutils.fs.updateMount)
updateMount(source: String, mountPoint: String, encryptionType: String = "",
owner: String = null, extraConfigs: Map = Map.empty[String, String]): boolean
Mirip dengan perintah dbutils.fs.mount
, tetapi memperbarui titik pemasangan yang ada dan bukan membuat yang baru. Mengembalikan kesalahan jika titik pemasangan tidak ada.
Peringatan
Untuk menghindari kesalahan, jangan pernah memodifikasi titik pemasangan saat pekerjaan lain sedang membaca atau menulis ke dalamnya. Setelah memodifikasi pemasangan, selalu jalankan dbutils.fs.refreshMounts()
pada semua kluster lain yang sedang berjalan untuk menyebarluaskan pembaruan pemasangan apa pun. Lihat perintah refreshMounts (dbutils.fs.refreshMounts).
Perintah ini tersedia di Databricks Runtime 10.4 LTS ke atas.
Untuk menampilkan bantuan lengkap untuk perintah ini, jalankan:
dbutils.fs.help("updateMount")
Contoh
Python
dbutils.fs.updateMount(
source = "wasbs://<container-name>@<storage-account-name>.blob.core.windows.net",
mount_point = "/mnt/<mount-name>",
extra_configs = {"<conf-key>":dbutils.secrets.get(scope = "<scope-name>", key = "<key-name>")})
Scala
dbutils.fs.updateMount(
source = "wasbs://<container-name>@<storage-account-name>.blob.core.windows.net/<directory-name>",
mountPoint = "/mnt/<mount-name>",
extraConfigs = Map("<conf-key>" -> dbutils.secrets.get(scope = "<scope-name>", key = "<key-name>")))
Utilitas pekerjaan (dbutils.jobs)
Menyediakan utilitas untuk memanfaatkan fitur pekerjaan.
Catatan
Utilitas ini hanya tersedia bagi Python.
Tabel berikut mencantumkan modul yang tersedia untuk utilitas ini, yang dapat Anda ambil menggunakan dbutils.jobs.help()
.
Submodul | Deskripsi |
---|---|
nilaiTugas | Menyediakan utilitas untuk memanfaatkan nilai tugas pekerjaan |
Subutilitas taskValues (dbutils.jobs.taskValues)
Catatan
Subutilitas ini hanya tersedia bagi Python.
Menyediakan perintah untuk memanfaatkan nilai tugas pekerjaan.
Gunakan sub-utilitas ini untuk mengatur dan mendapatkan nilai arbitrer selama pekerjaan berjalan. Nilai-nilai ini disebut nilai tugas. Tugas apa pun bisa mendapatkan nilai yang diatur oleh tugas upstream dan mengatur nilai untuk tugas downstream yang akan digunakan.
Setiap nilai tugas memiliki kunci unik di dalam tugas yang sama. Kunci unik ini dikenal juga sebagai kunci nilai tugas. Nilai tugas diakses dengan nama tugas serta kunci nilai tugas. Anda dapat menggunakan ini untuk meneruskan informasi hilir dari tugas ke tugas dalam eksekusi pekerjaan yang sama. Misalnya, Anda dapat meneruskan pengidentifikasi atau metrik, seperti informasi tentang evaluasi model pembelajaran mesin, di antara tugas yang berbeda dalam pekerjaan yang dijalankan.
Tabel berikut ini mencantumkan perintah yang tersedia untuk subutilitas ini, yang dapat Anda ambil menggunakan dbutils.jobs.taskValues.help()
.
Perintah | Deskripsi |
---|---|
mendapatkan | Mendapatkan isi dari nilai tugas yang ditentukan untuk tugas yang ditentukan di dalam eksekusi pekerjaan saat ini. |
set | Mengatur ataupun memperbarui nilai tugas. Anda dapat menyiapkan hingga 250 nilai tugas untuk eksekusi pekerjaan. |
mendapatkan perintah (dbutils.jobs.taskValues.get)
Catatan
Utilitas tersebut hanya tersedia bagi Python.
Pada Databricks Runtime 10.4 dan yang lebih lama, jika get
tidak dapat menemukan tugas, Py4JJavaError dinaikkan alih-alih ValueError
.
get(taskKey: String, key: String, default: int, debugValue: int): Seq
Mendapatkan isi dari nilai tugas yang ditentukan untuk tugas yang ditentukan di dalam eksekusi pekerjaan saat ini.
Untuk menampilkan bantuan lengkap untuk perintah ini, jalankan:
dbutils.jobs.taskValues.help("get")
Contoh
Contohnya:
dbutils.jobs.taskValues.get(taskKey = "my-task", \
key = "my-key", \
default = 7, \
debugValue = 42)
Dalam contoh sebelumnya:
-
taskKey
adalah nama tugas yang mengatur nilai tugas. Jika perintah tidak bisa menemukan tugas ini, makaValueError
akan dimunculkan. -
key
adalah nama kunci nilai tugas yang Anda tetapkan dengan perintah set (dbutils.jobs.taskValues.set). Jika perintah tidak dapat menemukan kunci nilai tugas ini,ValueError
akan diajukan (kecualidefault
telah disebutkan). -
default
adalah nilai opsional yang dikembalikan apabilakey
tidak dapat ditemukan.default
tidak bisa menjadiNone
. -
debugValue
adalah nilai opsional yang dikembalikan jika Anda mencoba mendapatkan nilai tugas dari dalam buku catatan yang berjalan di luar pekerjaan. Hal ini mungkin berguna selama penelusuran kesalahan saat Anda ingin menjalankan buku catatan Anda secara manual dan menghasilkan beberapa nilai, alih-alih menaikkanTypeError
secara default.debugValue
tidak bisa menjadiNone
.
Jika Anda mencoba mendapatkan nilai tugas dari dalam buku catatan yang berjalan di luar pekerjaan, perintah ini akan menaikkan TypeError
secara default. Namun, jika argumen debugValue
ditentukan dalam perintah, nilai debugValue
akan ditampilkan alih-alih mengajukanTypeError
.
mengatur perintah (dbutils.jobs.taskValues.set)
Catatan
Utilitas tersebut hanya tersedia bagi Python.
set(key: String, value: String): boolean
Mengatur ataupun memperbarui nilai tugas. Anda dapat menyiapkan hingga 250 nilai tugas untuk eksekusi pekerjaan.
Untuk menampilkan bantuan lengkap untuk perintah ini, jalankan:
dbutils.jobs.taskValues.help("set")
Contoh
Beberapa contohnya termasuk:
dbutils.jobs.taskValues.set(key = "my-key", \
value = 5)
dbutils.jobs.taskValues.set(key = "my-other-key", \
value = "my other value")
Di dalam contoh sebelumnya:
-
key
adalah kunci nilai tugas. Kunci ini harus unik untuk tugas. Artinya, jika dua tugas yang berbeda masing-masing mengatur nilai tugas dengan kunciK
, ini adalah dua nilai tugas berbeda yang memiliki kunci yang samaK
. -
value
adalah nilai kunci untuk nilai tugas ini. Perintah ini harus bisa mewakili nilai secara internal dalam format JSON. Ukuran representasi JSON dari nilai tidak dapat melebihi 48 KiB.
Jika Anda mencoba mengatur nilai tugas dari dalam buku catatan yang berjalan di luar pekerjaan, perintah ini tidak melakukan apa pun.
Utilitas pustaka (dbutils.library)
Sebagian besar metode dalam dbutils.library
submodul tidak digunakan lagi. Lihat Utilitas pustaka (dbutils.library) (warisan).
Anda mungkin perlu memulai ulang proses Python secara terprogram di Azure Databricks untuk memastikan bahwa pustaka yang diinstal atau ditingkatkan secara lokal berfungsi dengan benar di kernel Python untuk SparkSession Anda saat ini. Untuk melakukan hal ini, jalankan perintah dbutils.library.restartPython
. Lihat Memulai ulang proses Python di Azure Databricks.
Utilitas notebook (dbutils.notebook)
Utilitas notebook memungkinkan Anda untuk merantai bersama notebook dan bertindak berdasarkan hasilnya. Lihat Mengatur buku catatan dan memodulasi kode di notebook.
Tabel berikut mencantumkan perintah yang tersedia untuk utilitas ini, yang dapat Anda ambil menggunakan dbutils.notebook.help()
.
Perintah | Deskripsi |
---|---|
keluar | Keluar dari buku catatan dengan nilai |
menjalankan | Menjalankan notebook dan mengembalikan nilai keluarannya |
perintah exit (dbutils.notebook.exit)
exit(value: String): void
Keluar dari notebook dengan nilai.
Untuk menampilkan bantuan lengkap untuk perintah ini, jalankan:
dbutils.notebook.help("exit")
Contoh
Contoh ini keluar dari notebook dengan nilai Exiting from My Other Notebook
.
Python
dbutils.notebook.exit("Exiting from My Other Notebook")
# Notebook exited: Exiting from My Other Notebook
R
dbutils.notebook.exit("Exiting from My Other Notebook")
# Notebook exited: Exiting from My Other Notebook
Scala
dbutils.notebook.exit("Exiting from My Other Notebook")
// Notebook exited: Exiting from My Other Notebook
Catatan
Jika eksekusi memiliki kueri dengan streaming terstruktur yang berjalan di latar belakang, panggilan dbutils.notebook.exit()
tidak menghentikan eksekusi. Eksekusi akan terus dijalankan selama kueri dijalankan di latar belakang. Anda bisa menghentikan kueri yang berjalan di latar belakang dengan mengklik Batal di sel kueri atau dengan menjalankan query.stop()
. Saat kueri berhenti, Anda bisa menghentikan eksekusi dengan dbutils.notebook.exit()
.
perintah run (dbutils.notebook.run)
run(path: String, timeoutSeconds: int, arguments: Map): String
Menjalankan notebook dan mengembalikan nilai keluarnya. Notebook akan berjalan di kluster saat ini secara default.
Catatan
Panjang maksimum nilai string yang dikembalikan dari perintah run
adalah 5 MB. Lihat Dapatkan output untuk satu run (GET /jobs/runs/get-output
).
Untuk menampilkan bantuan lengkap untuk perintah ini, jalankan:
dbutils.notebook.help("run")
Contoh
Contoh ini menjalankan notebook yang bernama My Other Notebook
di lokasi yang sama dengan notebook panggilan. Notebook yang dipanggil berakhir dengan baris kode dbutils.notebook.exit("Exiting from My Other Notebook")
. Jika notebook yang dipanggil tidak selesai berjalan dalam waktu 60 detik, pengecualian dilakukan.
Python
dbutils.notebook.run("My Other Notebook", 60)
# Out[14]: 'Exiting from My Other Notebook'
Scala
dbutils.notebook.run("My Other Notebook", 60)
// res2: String = Exiting from My Other Notebook
Utilitas rahasia (dbutils.secrets)
Utilitas rahasia memungkinkan Anda untuk menyimpan dan mengakses informasi masuk sensitif tanpa membuatnya terlihat di notebook. Lihat Manajemen rahasia dan Langkah 3: Gunakan rahasia dalam buku catatan.
Tabel berikut mencantumkan perintah yang tersedia untuk utilitas ini, yang dapat Anda ambil menggunakan dbutils.secrets.help()
.
Perintah | Deskripsi |
---|---|
mendapatkan | Menghasilkan representasi string dari nilai rahasia yang memiliki cakupan dan kunci |
getBytes | Mendapatkan nilai rahasia dalam bentuk byte berdasarkan cakupan dan kunci |
daftar | Mencantumkan metadata rahasia untuk rahasia dalam suatu cakupan |
|
Mencantumkan cakupan rahasia |
mendapatkan perintah (dbutils.secrets.get)
get(scope: String, key: String): String
Mendapatkan representasi string dari nilai rahasia untuk cakupan dan kunci rahasia yang ditentukan.
Peringatan
Administrator, pembuat rahasia, dan pengguna yang diberikan izin dapat membaca rahasia Azure Databricks. Meskipun Azure Databricks berupaya untuk meredaksi nilai rahasia yang mungkin ditampilkan di notebook, tidak mungkin untuk mencegah pengguna tersebut membaca rahasia. Untuk informasi selengkapnya, lihat Redaksi rahasia.
Untuk menampilkan bantuan lengkap untuk perintah ini, jalankan:
dbutils.secrets.help("get")
Contoh
Contoh ini mendapatkan representasi string dari nilai rahasia untuk cakupan bernama my-scope
dan kunci bernama my-key
.
Python
dbutils.secrets.get(scope="my-scope", key="my-key")
# Out[14]: '[REDACTED]'
R
dbutils.secrets.get(scope="my-scope", key="my-key")
# [1] "[REDACTED]"
Scala
dbutils.secrets.get(scope="my-scope", key="my-key")
// res0: String = [REDACTED]
perintah getBytes (dbutils.secrets.getBytes)
getBytes(scope: String, key: String): byte[]
Mendapatkan representasi byte dari nilai rahasia untuk cakupan dan kunci yang ditentukan.
Untuk menampilkan bantuan lengkap untuk perintah ini, jalankan:
dbutils.secrets.help("getBytes")
Contoh
Contoh ini mendapatkan representasi byte dari nilai rahasia (dalam contoh ini, a1!b2@c3#
) untuk cakupan bernama my-scope
dan kunci bernama my-key
.
Python
dbutils.secrets.getBytes(scope="my-scope", key="my-key")
# Out[1]: b'a1!b2@c3#'
R
dbutils.secrets.getBytes(scope="my-scope", key="my-key")
# [1] 61 31 21 62 32 40 63 33 23
Scala
dbutils.secrets.getBytes(scope="my-scope", key="my-key")
// res1: Array[Byte] = Array(97, 49, 33, 98, 50, 64, 99, 51, 35)
perintah daftar (dbutils.secrets.list)
list(scope: String): Seq
Mencantumkan metadata untuk rahasia dalam cakupan yang ditentukan.
Untuk menampilkan bantuan lengkap untuk perintah ini, jalankan:
dbutils.secrets.help("list")
Contoh
Contoh ini mencantumkan metadata untuk rahasia dalam cakupan bernama my-scope
.
Python
dbutils.secrets.list("my-scope")
# Out[10]: [SecretMetadata(key='my-key')]
R
dbutils.secrets.list("my-scope")
# [[1]]
# [[1]]$key
# [1] "my-key"
Scala
dbutils.secrets.list("my-scope")
// res2: Seq[com.databricks.dbutils_v1.SecretMetadata] = ArrayBuffer(SecretMetadata(my-key))
perintah listScopes (dbutils.secrets.listScopes)
listScopes: Seq
Mencantumkan cakupan yang tersedia.
Untuk menampilkan bantuan lengkap untuk perintah ini, jalankan:
dbutils.secrets.help("listScopes")
Contoh
Contoh ini mencantumkan cakupan yang tersedia.
Python
dbutils.secrets.listScopes()
# Out[14]: [SecretScope(name='my-scope')]
R
dbutils.secrets.listScopes()
# [[1]]
# [[1]]$name
# [1] "my-scope"
Scala
dbutils.secrets.listScopes()
// res3: Seq[com.databricks.dbutils_v1.SecretScope] = ArrayBuffer(SecretScope(my-scope))
Utilitas widget (dbutils.widgets)
Utilitas widget memungkinkan Anda untuk membuat parameter notebook. Lihat Widget Databricks.
Tabel berikut mencantumkan perintah yang tersedia untuk utilitas ini, yang dapat Anda ambil menggunakan dbutils.widgets.help()
.
Perintah | Deskripsi |
---|---|
kotak kombo | Membuat widget input kotak kombo dengan nama tertentu, nilai default, dan pilihan |
dropdown | Membuat widget input dropdown dengan nama tertentu, nilai default, dan pilihan |
mendapatkan | Mengambil nilai widget input saat ini |
dapatkanSemua | Mengambil peta semua nama widget dan nilainya |
getArgument | Tidak direkomendasikan. Setara dengan yang didapatkan |
pilihan ganda | Membuat widget input multipilih dengan nama tertentu, nilai default, dan pilihan |
menghapus | Menghapus widget input dari notebook |
hapusSemua | Menghapus semua widget di buku catatan |
teks | Membuat widget input teks dengan nama tertentu dan nilai default |
perintah combobox (dbutils.widgets.combobox)
combobox(name: String, defaultValue: String, choices: Seq, label: String): void
Membuat dan menampilkan widget combobox dengan nama terprogram yang ditentukan, nilai default, pilihan, dan label opsional.
Untuk menampilkan bantuan lengkap untuk perintah ini, jalankan:
dbutils.widgets.help("combobox")
Contoh
Contoh ini membuat dan menampilkan widget combobox dengan nama terprogram fruits_combobox
. Ini menawarkan pilihan apple
, banana
, coconut
, dan dragon fruit
dan diatur ke nilai awal banana
. Widget combobox ini memiliki label yang menyertai Fruits
. Contoh ini diakhiri dengan mencetak nilai awal widget combobox, banana
.
Python
dbutils.widgets.combobox(
name='fruits_combobox',
defaultValue='banana',
choices=['apple', 'banana', 'coconut', 'dragon fruit'],
label='Fruits'
)
print(dbutils.widgets.get("fruits_combobox"))
# banana
R
dbutils.widgets.combobox(
name='fruits_combobox',
defaultValue='banana',
choices=list('apple', 'banana', 'coconut', 'dragon fruit'),
label='Fruits'
)
print(dbutils.widgets.get("fruits_combobox"))
# [1] "banana"
Scala
dbutils.widgets.combobox(
"fruits_combobox",
"banana",
Array("apple", "banana", "coconut", "dragon fruit"),
"Fruits"
)
print(dbutils.widgets.get("fruits_combobox"))
// banana
SQL
CREATE WIDGET COMBOBOX fruits_combobox DEFAULT "banana" CHOICES SELECT * FROM (VALUES ("apple"), ("banana"), ("coconut"), ("dragon fruit"))
SELECT :fruits_combobox
-- banana
perintah dropdown (dbutils.widgets.dropdown)
dropdown(name: String, defaultValue: String, choices: Seq, label: String): void
Membuat dan menampilkan widget dropdown dengan nama terprogram yang ditentukan, nilai default, pilihan, dan label opsional.
Untuk menampilkan bantuan lengkap untuk perintah ini, jalankan:
dbutils.widgets.help("dropdown")
Contoh
Contoh ini membuat dan menampilkan widget dropdown dengan nama terprogram toys_dropdown
. Ini menawarkan pilihan alphabet blocks
, basketball
, cape
, dan doll
dan diatur ke nilai awal basketball
. Widget dropdown ini memiliki label yang menyertai Toys
. Contoh ini diakhiri dengan mencetak nilai awal widget dropdown, basketball
.
Python
dbutils.widgets.dropdown(
name='toys_dropdown',
defaultValue='basketball',
choices=['alphabet blocks', 'basketball', 'cape', 'doll'],
label='Toys'
)
print(dbutils.widgets.get("toys_dropdown"))
# basketball
R
dbutils.widgets.dropdown(
name='toys_dropdown',
defaultValue='basketball',
choices=list('alphabet blocks', 'basketball', 'cape', 'doll'),
label='Toys'
)
print(dbutils.widgets.get("toys_dropdown"))
# [1] "basketball"
Scala
dbutils.widgets.dropdown(
"toys_dropdown",
"basketball",
Array("alphabet blocks", "basketball", "cape", "doll"),
"Toys"
)
print(dbutils.widgets.get("toys_dropdown"))
// basketball
SQL
CREATE WIDGET DROPDOWN toys_dropdown DEFAULT "basketball" CHOICES SELECT * FROM (VALUES ("alphabet blocks"), ("basketball"), ("cape"), ("doll"))
SELECT :toys_dropdown
-- basketball
mendapatkan perintah (dbutils.widgets.get)
get(name: String): String
Mendapatkan nilai widget saat ini dengan nama terprogram yang ditentukan. Nama terprogram ini dapat berupa:
- Nama widget kustom di notebook, misalnya,
fruits_combobox
atautoys_dropdown
. - Nama parameter kustom diteruskan ke notebook sebagai bagian dari tugas notebook, misalnya
name
atauage
. Untuk informasi selengkapnya, lihat cakupan parameter untuk tugas buku catatan di UI pekerjaan atau bidangnotebook_params
dalam operasi "Trigger a new job run" () (POST /jobs/run-now
) di Jobs API.
Untuk menampilkan bantuan lengkap untuk perintah ini, jalankan:
dbutils.widgets.help("get")
Contoh
Contoh ini mendapat nilai widget yang memiliki nama terprogram fruits_combobox
.
Python
dbutils.widgets.get('fruits_combobox')
# banana
R
dbutils.widgets.get('fruits_combobox')
# [1] "banana"
Scala
dbutils.widgets.get("fruits_combobox")
// res6: String = banana
SQL
SELECT :fruits_combobox
-- banana
Contoh ini mendapat nilai parameter tugas notebook yang memiliki nama terprogram age
. Parameter ini diatur ke 35
ketika tugas buku catatan terkait dijalankan.
Python
dbutils.widgets.get('age')
# 35
R
dbutils.widgets.get('age')
# [1] "35"
Scala
dbutils.widgets.get("age")
// res6: String = 35
SQL
SELECT :age
-- 35
perintah getAll (dbutils.widgets.getAll)
getAll: map
Mendapatkan pemetaan semua nama dan nilai widget saat ini. Ini bisa sangat berguna untuk meneruskan nilai widget dengan cepat ke kueri spark.sql()
.
Perintah ini tersedia di Databricks Runtime 13.3 LTS ke atas. Ini hanya tersedia untuk Python dan Scala.
Untuk menampilkan bantuan lengkap untuk perintah ini, jalankan:
dbutils.widgets.help("getAll")
Contoh
Contoh ini mendapatkan peta nilai widget dan meneruskannya sebagai argumen parameter dalam kueri Spark SQL.
Python
df = spark.sql("SELECT * FROM table where col1 = :param", dbutils.widgets.getAll())
df.show()
# Query output
Scala
val df = spark.sql("SELECT * FROM table where col1 = :param", dbutils.widgets.getAll())
df.show()
// res6: Query output
perintah getArgument (dbutils.widgets.getArgument)
getArgument(name: String, optional: String): String
Mendapatkan nilai widget saat ini dengan nama terprogram yang ditentukan. Jika widget tidak ada, pesan opsional dapat dikembalikan.
Catatan
Perintah ini tidak digunakan lagi. Gunakan dbutils.widgets.get sebagai gantinya.
Untuk menampilkan bantuan lengkap untuk perintah ini, jalankan:
dbutils.widgets.help("getArgument")
Contoh
Contoh ini mendapat nilai widget yang memiliki nama terprogram fruits_combobox
. Jika widget ini tidak ada, pesan Error: Cannot find fruits combobox
akan dikembalikan.
Python
dbutils.widgets.getArgument('fruits_combobox', 'Error: Cannot find fruits combobox')
# Deprecation warning: Use dbutils.widgets.text() or dbutils.widgets.dropdown() to create a widget and dbutils.widgets.get() to get its bound value.
# Out[3]: 'banana'
R
dbutils.widgets.getArgument('fruits_combobox', 'Error: Cannot find fruits combobox')
# Deprecation warning: Use dbutils.widgets.text() or dbutils.widgets.dropdown() to create a widget and dbutils.widgets.get() to get its bound value.
# [1] "banana"
Scala
dbutils.widgets.getArgument("fruits_combobox", "Error: Cannot find fruits combobox")
// command-1234567890123456:1: warning: method getArgument in trait WidgetsUtils is deprecated: Use dbutils.widgets.text() or dbutils.widgets.dropdown() to create a widget and dbutils.widgets.get() to get its bound value.
// dbutils.widgets.getArgument("fruits_combobox", "Error: Cannot find fruits combobox")
// ^
// res7: String = banana
perintah multiselect (dbutils.widgets.multiselect)
multiselect(name: String, defaultValue: String, choices: Seq, label: String): void
Membuat dan menampilkan widget pilihan ganda dengan nama terprogram yang ditentukan, nilai default, pilihan, dan label opsional.
Untuk menampilkan bantuan lengkap untuk perintah ini, jalankan:
dbutils.widgets.help("multiselect")
Contoh
Contoh ini membuat dan menampilkan widget pilihan ganda dengan nama terprogram days_multiselect
. Ini menawarkan pilihan Monday
hingga Sunday
dan disetel ke nilai awal Tuesday
. Widget pilihan ganda ini memiliki label yang menyertainya Days of the Week
. Contoh ini diakhiri dengan mencetak nilai awal widget pilihan ganda, Tuesday
.
Python
dbutils.widgets.multiselect(
name='days_multiselect',
defaultValue='Tuesday',
choices=['Monday', 'Tuesday', 'Wednesday', 'Thursday',
'Friday', 'Saturday', 'Sunday'],
label='Days of the Week'
)
print(dbutils.widgets.get("days_multiselect"))
# Tuesday
R
dbutils.widgets.multiselect(
name='days_multiselect',
defaultValue='Tuesday',
choices=list('Monday', 'Tuesday', 'Wednesday', 'Thursday',
'Friday', 'Saturday', 'Sunday'),
label='Days of the Week'
)
print(dbutils.widgets.get("days_multiselect"))
# [1] "Tuesday"
Scala
dbutils.widgets.multiselect(
"days_multiselect",
"Tuesday",
Array("Monday", "Tuesday", "Wednesday", "Thursday",
"Friday", "Saturday", "Sunday"),
"Days of the Week"
)
print(dbutils.widgets.get("days_multiselect"))
// Tuesday
SQL
CREATE WIDGET MULTISELECT days_multiselect DEFAULT "Tuesday" CHOICES SELECT * FROM (VALUES ("Monday"), ("Tuesday"), ("Wednesday"), ("Thursday"), ("Friday"), ("Saturday"), ("Sunday"))
SELECT :days_multiselect
-- Tuesday
menghapus perintah (dbutils.widgets.remove)
remove(name: String): void
Menghapus widget dengan nama terprogram yang ditentukan.
Untuk menampilkan bantuan lengkap untuk perintah ini, jalankan:
dbutils.widgets.help("remove")
Penting
Jika Anda menambahkan perintah untuk menghapus widget, Anda tidak dapat menambahkan perintah berikutnya untuk membuat widget di sel yang sama. Anda harus membuat widget di sel lain.
Contoh
Contoh ini menghapus widget dengan nama terprogram fruits_combobox
.
Python
dbutils.widgets.remove('fruits_combobox')
R
dbutils.widgets.remove('fruits_combobox')
Scala
dbutils.widgets.remove("fruits_combobox")
SQL
REMOVE WIDGET fruits_combobox
perintah removeAll (dbutils.widgets.removeAll)
removeAll: void
Menghapus semua widget dari notebook.
Untuk menampilkan bantuan lengkap untuk perintah ini, jalankan:
dbutils.widgets.help("removeAll")
Penting
Jika Anda menambahkan perintah untuk menghapus semua widget, Anda tidak dapat menambahkan perintah berikutnya untuk membuat widget apa pun di sel yang sama. Anda harus membuat widget di sel lain.
Contoh
Contoh ini menghapus semua widget dari notebook.
Python
dbutils.widgets.removeAll()
R
dbutils.widgets.removeAll()
Scala
dbutils.widgets.removeAll()
perintah text (dbutils.widgets.text)
text(name: String, defaultValue: String, label: String): void
Membuat dan menampilkan widget teks dengan nama terprogram yang ditentukan, nilai default, dan label opsional.
Untuk menampilkan bantuan lengkap untuk perintah ini, jalankan:
dbutils.widgets.help("text")
Contoh
Contoh ini membuat dan menampilkan widget teks dengan nama terprogram your_name_text
. Ini diatur ke nilai awal Enter your name
. Widget teks ini memiliki label yang menyertai Your name
. Contoh ini diakhiri dengan mencetak nilai awal widget teks, Enter your name
.
Python
dbutils.widgets.text(
name='your_name_text',
defaultValue='Enter your name',
label='Your name'
)
print(dbutils.widgets.get("your_name_text"))
# Enter your name
R
dbutils.widgets.text(
name='your_name_text',
defaultValue='Enter your name',
label='Your name'
)
print(dbutils.widgets.get("your_name_text"))
# [1] "Enter your name"
Scala
dbutils.widgets.text(
"your_name_text",
"Enter your name",
"Your name"
)
print(dbutils.widgets.get("your_name_text"))
// Enter your name
SQL
CREATE WIDGET TEXT your_name_text DEFAULT "Enter your name"
SELECT :your_name_text
-- Enter your name
Pustaka API Utilitas Databricks
Penting
Pustaka Api Utilitas Databricks (dbutils-api
) tidak digunakan lagi. Databricks merekomendasikan agar Anda menggunakan salah satu hal berikut ini sebagai gantinya:
Untuk mempercepat pengembangan aplikasi, akan sangat membantu untuk mengompilasi, membangun, dan menguji aplikasi sebelum Anda menyebarkannya sebagai pekerjaan produksi. Untuk memungkinkan Anda mengompilasi terhadap Utilitas Databricks, Databricks memberikan pustaka dbutils-api
. Anda dapat mengunduh pustaka dbutils-api
dari halaman situs web API DBUtilsdi situs web Maven Repository atau menyertakan pustaka dengan menambahkan dependensi ke file build Anda:
SBT
libraryDependencies += "com.databricks" % "dbutils-api_TARGET" % "VERSION"
Maven
<dependency> <groupId>com.databricks</groupId> <artifactId>dbutils-api_TARGET</artifactId> <version>VERSION</version> </dependency>
Gradle
compile 'com.databricks:dbutils-api_TARGET:VERSION'
Ganti TARGET
dengan target yang diinginkan (misalnya, 2.12
) dan VERSION
dengan versi yang diinginkan (misalnya, 0.0.5
). Untuk daftar target dan versi yang tersedia, lihat halaman web DBUtils API di situs web Repositori Maven.
Setelah Anda membangun aplikasi Anda terhadap pustaka ini, Anda dapat menyebarkan aplikasi.
Penting
dbutils-api
Pustaka hanya memungkinkan Anda untuk mengkompilasi aplikasi secara lokal yang menggunakan dbutils
, bukan untuk menjalankannya. Untuk menjalankan aplikasi, Anda harus menyebarkannya di Azure Databricks.
Batasan
Memanggil dbutils
di dalam eksekutor dapat menghasilkan hasil atau kesalahan yang tidak terduga.
Jika Anda perlu menjalankan operasi sistem file pada pelaksana menggunakan dbutils
, lihat metode daftar paralel dan hapus menggunakan Spark di Cara mencantumkan dan menghapus file lebih cepat di Databricks.
Untuk informasi tentang pelaksana, lihat Gambaran Umum Mode Kluster di situs web Apache Spark.