Referensi Utilitas Databricks (dbutils)
Artikel ini adalah referensi untuk Utilitas Databricks (dbutils). dbutils utilitas tersedia di notebook Python, R, dan Scala. Anda dapat menggunakan utilitas untuk:
- Bekerja dengan file dan penyimpanan objek secara efisien.
- Bekerja dengan rahasia.
Cara: Mendaftar utilitas, mendaftar perintah, menampilkan bantuan perintah
Utilitas: data, fs, pekerjaan, pustaka, notebook, rahasia, widget, Pustaka API utilitas
Mencantumkan utilitas yang tersedia
Untuk mencantumkan utilitas yang tersedia bersama dengan deskripsi singkat untuk setiap utilitas, jalankan dbutils.help() untuk Python atau Scala.
Contoh ini mencantumkan perintah yang tersedia untuk Utilitas Databricks.
Python
dbutils.help()
Scala
dbutils.help()
This module provides various utilities for users to interact with the rest of Databricks.
credentials: DatabricksCredentialUtils -> Utilities for interacting with credentials within notebooks
data: DataUtils -> Utilities for understanding and interacting with datasets (EXPERIMENTAL)
fs: DbfsUtils -> Manipulates the Databricks filesystem (DBFS) from the console
jobs: JobsUtils -> Utilities for leveraging jobs features
library: LibraryUtils -> Utilities for session isolated libraries
meta: MetaUtils -> Methods to hook into the compiler (EXPERIMENTAL)
notebook: NotebookUtils -> Utilities for the control flow of a notebook (EXPERIMENTAL)
preview: Preview -> Utilities under preview category
secrets: SecretUtils -> Provides utilities for leveraging secrets within notebooks
widgets: WidgetsUtils -> Methods to create and get bound value of input widgets inside notebooks
Cantumkan perintah yang tersedia untuk utilitas
Untuk mencantumkan perintah yang tersedia untuk utilitas bersama dengan deskripsi singkat dari setiap perintah, jalankan .help() setelah nama terprogram untuk utilitas.
Contoh ini mencantumkan perintah yang tersedia untuk utilitas Databricks File System (DBFS).
Python
dbutils.fs.help()
R
dbutils.fs.help()
Scala
dbutils.fs.help()
dbutils.fs provides utilities for working with FileSystems. Most methods in this package can take either a DBFS path (e.g., "/foo" or "dbfs:/foo"), or another FileSystem URI. For more info about a method, use dbutils.fs.help("methodName"). In notebooks, you can also use the %fs shorthand to access DBFS. The %fs shorthand maps straightforwardly onto dbutils calls. For example, "%fs head --maxBytes=10000 /file/path" translates into "dbutils.fs.head("/file/path", maxBytes = 10000)".
fsutils
cp(from: String, to: String, recurse: boolean = false): boolean -> Copies a file or directory, possibly across FileSystems
head(file: String, maxBytes: int = 65536): String -> Returns up to the first 'maxBytes' bytes of the given file as a String encoded in UTF-8
ls(dir: String): Seq -> Lists the contents of a directory
mkdirs(dir: String): boolean -> Creates the given directory if it does not exist, also creating any necessary parent directories
mv(from: String, to: String, recurse: boolean = false): boolean -> Moves a file or directory, possibly across FileSystems
put(file: String, contents: String, overwrite: boolean = false): boolean -> Writes the given String out to a file, encoded in UTF-8
rm(dir: String, recurse: boolean = false): boolean -> Removes a file or directory
mount
mount(source: String, mountPoint: String, encryptionType: String = "", owner: String = null, extraConfigs: Map = Map.empty[String, String]): boolean -> Mounts the given source directory into DBFS at the given mount point
mounts: Seq -> Displays information about what is mounted within DBFS
refreshMounts: boolean -> Forces all machines in this cluster to refresh their mount cache, ensuring they receive the most recent information
unmount(mountPoint: String): boolean -> Deletes a DBFS mount point
updateMount(source: String, mountPoint: String, encryptionType: String = "", owner: String = null, extraConfigs: Map = Map.empty[String, String]): boolean -> Similar to mount(), but updates an existing mount point instead of creating a new one
Menampilkan bantuan untuk perintah
Untuk menampilkan bantuan untuk perintah, jalankan .help("<command-name>") setelah nama perintah.
Contoh ini menampilkan bantuan untuk perintah salin DBFS.
Python
dbutils.fs.help("cp")
R
dbutils.fs.help("cp")
Scala
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.
Perintah: meringkas
Utilitas data memungkinkan Anda untuk memahami dan menafsirkan himpunan data. Untuk mencantumkan perintah yang tersedia, jalankan dbutils.data.help().
dbutils.data provides utilities for understanding and interpreting datasets. This module is currently in preview and may be unstable. For more info about a method, use dbutils.data.help("methodName").
summarize(df: Object, precise: boolean): void -> Summarize a Spark DataFrame and visualize the statistics to get quick insights
perintah meringkas (dbutils.data.summarize)
Menghitung dan menampilkan statistik ringkasan dari Apache Spark DataFrame atau DataFrame panda. Perintah ini tersedia untuk Python, Scala, dan R.
Perintah ini menganalisis konten lengkap DataFrame. Menjalankan perintah ini untuk DataFrame yang sangat besar bisa sangat mahal.
Untuk menampilkan bantuan 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.
Catatan
Fitur ini ada di Pratinjau Publik.
- Ketika
precisediatur ke false (default), beberapa statistik yang dikembalikan menyertakan perkiraan untuk mengurangi durasi.- Jumlah nilai yang berbeda untuk kolom kategoris mungkin memiliki ~ 5% kesalahan relatif untuk kolom kardinalitas tinggi.
- Jumlah nilai yang sering terjadi mungkin memiliki kesalahan hingga 0,01% ketika jumlah nilai yang berbeda lebih besar dari 10000.
- Histogram dan perkiraan persentil mungkin memiliki kesalahan hingga 0,01% relatif terhadap jumlah total baris.
- Ketika
precisediatur 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 berjalan saat ini.
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)
Perlu diketahui bahwa visualisasi menggunakan notasi SI untuk secara ringkas merender nilai numerik yang 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)
Peringatan
Implementasi Python dari semua dbutils.fs metode menggunakan snake_case daripada camelCase untuk pemformatan kata kunci.
Misalnya: saat dbutils.fs.help() menampilkan opsi extraConfigs untuk dbutils.fs.mount(), di Python Anda akan menggunakan kata kunci extra_configs.
Perintah: cp, head, ls, mkdirs, mount, mounts, mv, put, refreshMounts, rm, unmount, updateMount
Utilitas sistem file memungkinkan Anda mengakses Apa itu DBFS?, sehingga lebih mudah menggunakan Azure Databricks sebagai sistem file. Untuk mencantumkan perintah yang tersedia, jalankan dbutils.fs.help().
dbutils.fs provides utilities for working with FileSystems. Most methods in this package can take either a DBFS path (e.g., "/foo" or "dbfs:/foo"), or another FileSystem URI. For more info about a method, use dbutils.fs.help("methodName"). In notebooks, you can also use the %fs shorthand to access DBFS. The %fs shorthand maps straightforwardly onto dbutils calls. For example, "%fs head --maxBytes=10000 /file/path" translates into "dbutils.fs.head("/file/path", maxBytes = 10000)".
fsutils
cp(from: String, to: String, recurse: boolean = false): boolean -> Copies a file or directory, possibly across FileSystems
head(file: String, maxBytes: int = 65536): String -> Returns up to the first 'maxBytes' bytes of the given file as a String encoded in UTF-8
ls(dir: String): Seq -> Lists the contents of a directory
mkdirs(dir: String): boolean -> Creates the given directory if it does not exist, also creating any necessary parent directories
mv(from: String, to: String, recurse: boolean = false): boolean -> Moves a file or directory, possibly across FileSystems
put(file: String, contents: String, overwrite: boolean = false): boolean -> Writes the given String out to a file, encoded in UTF-8
rm(dir: String, recurse: boolean = false): boolean -> Removes a file or directory
mount
mount(source: String, mountPoint: String, encryptionType: String = "", owner: String = null, extraConfigs: Map = Map.empty[String, String]): boolean -> Mounts the given source directory into DBFS at the given mount point
mounts: Seq -> Displays information about what is mounted within DBFS
refreshMounts: boolean -> Forces all machines in this cluster to refresh their mount cache, ensuring they receive the most recent information
unmount(mountPoint: String): boolean -> Deletes a DBFS mount point
updateMount(source: String, mountPoint: String, encryptionType: String = "", owner: String = null, extraConfigs: Map = Map.empty[String, String]): boolean -> Similar to mount(), but updates an existing mount point instead of creating a new one
perintah cp (dbutils.fs.cp)
Menyalin file atau direktori, mungkin di seluruh filesystem.
Untuk menampilkan bantuan untuk perintah ini, jalankan dbutils.fs.help("cp").
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)
Mengembalikan hingga jumlah byte maksimum dari file yang diberikan. Byte dikembalikan sebagai string yang dikodekan UTF-8.
Untuk menampilkan bantuan untuk perintah ini, jalankan dbutils.fs.help("head").
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)
Mencantumkan konten direktori.
Untuk menampilkan bantuan untuk perintah ini, jalankan dbutils.fs.help("ls").
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)
Membuat direktori yang diberikan jika tidak ada. Juga membuat direktori induk yang diperlukan.
Untuk menampilkan bantuan untuk perintah ini, jalankan dbutils.fs.help("mkdirs").
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)
Memasang direktori sumber yang ditentukan ke dalam DBFS pada titik pemasangan yang ditentukan.
Untuk menampilkan bantuan untuk perintah ini, jalankan dbutils.fs.help("mount").
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 Koneksi ke Azure Data Lake Storage Gen2 dan Blob Storage.
perintah mounts (dbutils.fs.mounts)
Menampilkan informasi tentang apa yang saat ini dipasang dalam DBFS.
Untuk menampilkan bantuan untuk perintah ini, jalankan dbutils.fs.help("mounts").
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 Koneksi ke Azure Data Lake Storage Gen2 dan Blob Storage.
perintah mv (dbutils.fs.mv)
Memindahkan file atau direktori, mungkin di seluruh filesystem. Memindahkan adalah penyalinan yang diikuti oleh penghapusan, bahkan untuk perpindahan dalam filesystem.
Untuk menampilkan bantuan untuk perintah ini, jalankan dbutils.fs.help("mv").
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)
Menulis string tertentu ke file. String dikodekan UTF-8.
Untuk menampilkan bantuan untuk perintah ini, jalankan dbutils.fs.help("put").
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)
Memaksa semua mesin dalam kluster untuk menyegarkan pemasangan cache mereka, memastikan mereka menerima informasi terbaru.
Untuk menampilkan bantuan untuk perintah ini, jalankan dbutils.fs.help("refreshMounts").
Python
dbutils.fs.refreshMounts()
Scala
dbutils.fs.refreshMounts()
Untuk contoh kode aditif, lihat Koneksi ke Azure Data Lake Storage Gen2 dan Blob Storage.
perintah rm (dbutils.fs.rm)
Menghapus file atau direktori dan secara opsional semua isinya. Jika file ditentukan, parameter berulang diabaikan. Jika direktori ditentukan, kesalahan terjadi jika pengulangan dinonaktifkan dan direktori tidak kosong.
Untuk menampilkan bantuan untuk perintah ini, jalankan dbutils.fs.help("rm").
Contoh ini menghapus direktori /Volumes/main/default/my-volume/my-data/ termasuk konten direktori.
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)
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 untuk perintah ini, jalankan dbutils.fs.help("unmount").
dbutils.fs.unmount("/mnt/<mount-name>")
Untuk contoh kode tambahan, lihat Koneksi ke Azure Data Lake Storage Gen2 dan Blob Storage.
perintah updateMount (dbutils.fs.updateMount)
Mirip dengan perintah dbutils.fs.mount, tetapi memperbarui titik pemasangan yang ada dan bukan membuat yang baru. Mengembalikan kesalahan jika titik pemasangan tidak ada.
Untuk menampilkan bantuan untuk perintah ini, jalankan dbutils.fs.help("updateMount").
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.
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)
Subutilitas: taskValues
Catatan
Utilitas ini hanya tersedia bagi Python.
Utilitas pekerjaan memungkinkan Anda untuk memanfaatkan fitur pekerjaan. Untuk menampilkan bantuan bagi perintah ini, jalankan dbutils.jobs.help().
Provides utilities for leveraging jobs features.
taskValues: TaskValuesUtils -> Provides utilities for leveraging job task values
Subutilitas taskValues (dbutils.jobs.taskValues)
Catatan
Subutilitas ini hanya tersedia bagi Python.
Menyediakan perintah guna memanfaatkan nilai tugas pekerjaan.
Gunakan subutilitas ini untuk mengatur serta mendapatkan nilai arbitrer selama eksekusi pekerjaan. Nilai ini disebut nilai tugas. Anda bisa mengakses nilai tugas dalam tugas hilir dalam eksekusi pekerjaan yang sama. Misalnya, Anda dapat mengkomunikasikan pengidentifikasi atau metrik, seperti informasi tentang evaluasi model pembelajaran mesin, di antara tugas yang berbeda dalam pekerjaan yang dijalankan. Setiap tugas dapat mengatur beberapa nilai tugas, mendapatkannya, atau juga keduanya. 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.
Untuk menampilkan bantuan bagi perintah ini, harap jalankan dbutils.jobs.taskValues.help().
dapatkan 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.
Mendapatkan isi dari nilai tugas yang ditentukan untuk tugas yang ditentukan di dalam eksekusi pekerjaan saat ini.
Untuk menampilkan bantuan untuk perintah ini, jalankan dbutils.jobs.taskValues.help("get").
Contohnya:
dbutils.jobs.taskValues.get(taskKey = "my-task", \
key = "my-key", \
default = 7, \
debugValue = 42)
Dalam contoh sebelumnya:
taskKeyadalah nama tugas yang mengatur nilai tugas. Jika perintah tidak bisa menemukan tugas ini, makaValueErrorakan dimunculkan.keyadalah nama kunci nilai tugas yang ditetapkan dengan perintah set (dbutils.jobs.taskValues.set). Jika perintah tidak dapat menemukan kunci nilai tugas ini,ValueErrorakan diajukan (kecualidefaulttelah disebutkan).defaultadalah nilai opsional yang dikembalikan apabilakeytidak dapat ditemukan.defaulttidak bisa menjadiNone.debugValueadalah nilai opsional yang akan 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 menaikkanTypeErrorsecara default.debugValuetidak bisa menjadiNone.
Jika Anda mencoba untuk mendapatkan nilai tugas dari dalam buku catatan yang berjalan di luar pekerjaan, perintah ini akan mengajukan TypeError secara default. Namun, jika argumen debugValueditentukan dalam perintah, nilai debugValue akan ditampilkan alih-alih mengajukanTypeError.
set perintah (dbutils.jobs.taskValues.set)
Catatan
Utilitas tersebut hanya tersedia bagi Python.
Mengatur ataupun memperbarui nilai tugas. Anda dapat menyiapkan hingga 250 nilai tugas bagi eksekusi pekerjaan.
Untuk menampilkan bantuan untuk perintah ini, jalankan dbutils.jobs.taskValues.help("set").
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:
keyadalah 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 kunciKyang sama .valueadalah 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 untuk mengatur nilai tugas dari dalam buku catatan yang berjalan di luar pekerjaan, perintah ini tidak akan 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 Menjalankan buku catatan Databricks dari buku catatan lain.
Untuk mencantumkan perintah yang tersedia, jalankan dbutils.notebook.help().
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.
perintah exit (dbutils.notebook.exit)
Keluar dari notebook dengan nilai.
Untuk menampilkan bantuan untuk perintah ini, jalankan dbutils.notebook.help("exit").
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)
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 kali menjalankan (GET /jobs/runs/get-output).
Untuk menampilkan bantuan untuk perintah ini, jalankan dbutils.notebook.help("run").
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)
Perintah: get, getBytes, list, listScopes
Utilitas rahasia memungkinkan Anda untuk menyimpan dan mengakses informasi masuk sensitif tanpa membuatnya terlihat di notebook. Lihat Manajemen rahasia dan Gunakan rahasia di notebook. Untuk mencantumkan perintah yang tersedia, jalankan dbutils.secrets.help().
get(scope: String, key: String): String -> Gets the string representation of a secret value with scope and key
getBytes(scope: String, key: String): byte[] -> Gets the bytes representation of a secret value with scope and key
list(scope: String): Seq -> Lists secret metadata for secrets within a scope
listScopes: Seq -> Lists secret scopes
perintah get (dbutils.secrets.get)
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. Sementara Azure Databricks berusaha untuk mengedit nilai rahasia yang mungkin ditampilkan di notebook, tidak mungkin untuk mencegah pengguna tersebut membaca rahasia. Untuk informasi selengkapnya, lihat Redaksi rahasia.
Untuk menampilkan bantuan untuk perintah ini, jalankan dbutils.secrets.help("get").
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)
Mendapatkan representasi byte dari nilai rahasia untuk cakupan dan kunci yang ditentukan.
Untuk menampilkan bantuan untuk perintah ini, jalankan dbutils.secrets.help("getBytes").
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 list (dbutils.secrets.list)
Mencantumkan metadata untuk rahasia dalam cakupan yang ditentukan.
Untuk menampilkan bantuan untuk perintah ini, jalankan dbutils.secrets.help("list").
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)
Mencantumkan cakupan yang tersedia.
Untuk menampilkan bantuan untuk perintah ini, jalankan dbutils.secrets.help("listScopes").
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)
Perintah: combobox, dropdown, get, getArgument, multiselect, remove, removeAll, text
Utilitas widget memungkinkan Anda untuk membuat parameter notebook. Lihat Widget Databricks.
Catatan
Sihir Notebook SQL seperti CREATE WIDGET dan REMOVE WIDGET menyediakan cara mudah untuk bekerja dengan widget di sel notebook SQL.
Untuk mencantumkan perintah yang tersedia, jalankan dbutils.widgets.help().
combobox(name: String, defaultValue: String, choices: Seq, label: String): void -> Creates a combobox input widget with a given name, default value and choices
dropdown(name: String, defaultValue: String, choices: Seq, label: String): void -> Creates a dropdown input widget a with given name, default value and choices
get(name: String): String -> Retrieves current value of an input widget
getAll: map -> Retrieves a map of all widget names and their values
getArgument(name: String, optional: String): String -> (DEPRECATED) Equivalent to get
multiselect(name: String, defaultValue: String, choices: Seq, label: String): void -> Creates a multiselect input widget with a given name, default value and choices
remove(name: String): void -> Removes an input widget from the notebook
removeAll: void -> Removes all widgets in the notebook
text(name: String, defaultValue: String, label: String): void -> Creates a text input widget with a given name and default value
perintah combobox (dbutils.widgets.combobox)
Membuat dan menampilkan widget combobox dengan nama terprogram yang ditentukan, nilai default, pilihan, dan label opsional.
Untuk menampilkan bantuan untuk perintah ini, jalankan dbutils.widgets.help("combobox").
Contoh ini membuat dan menampilkan widget combobox dengan nama terprogram fruits_combobox. Widget tersebut memberikan pilihan apple, banana, coconut, dan dragon fruit serta 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)
Membuat dan menampilkan widget dropdown dengan nama terprogram yang ditentukan, nilai default, pilihan, dan label opsional.
Untuk menampilkan bantuan untuk perintah ini, jalankan dbutils.widgets.help("dropdown").
Contoh ini membuat dan menampilkan widget dropdown dengan nama terprogram toys_dropdown. Widget tersebut memberikan pilihan alphabet blocks, basketball, cape, dan doll serta 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
perintah get (dbutils.widgets.get)
Mendapatkan nilai widget saat ini dengan nama terprogram yang ditentukan. Nama terprogram ini dapat berupa:
- Nama widget kustom di notebook, misalnya
fruits_comboboxatautoys_dropdown. - Nama parameter kustom diteruskan ke notebook sebagai bagian dari tugas notebook, misalnya
nameatauage. Untuk informasi selengkapnya, lihat cakupan parameter untuk tugas notebook di UI Buat pekerjaan atau bidangnotebook_paramsdi operasi Picu pekerjaan baru (POST /jobs/run-now) di API Pekerjaan.
Untuk menampilkan bantuan untuk perintah ini, jalankan dbutils.widgets.help("get").
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 saat tugas notebook 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)
Mendapatkan pemetaan semua nama dan nilai widget saat ini. Ini bisa sangat berguna untuk meneruskan nilai widget dengan cepat ke spark.sql() kueri.
Perintah ini tersedia di Databricks Runtime 13.3 LTS ke atas. Ini hanya tersedia untuk Python dan Scala.
Untuk menampilkan bantuan untuk perintah ini, jalankan dbutils.widgets.help("getAll").
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)
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 untuk perintah ini, jalankan dbutils.widgets.help("getArgument").
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)
Membuat dan menampilkan widget pilihan ganda dengan nama terprogram yang ditentukan, nilai default, pilihan, dan label opsional.
Untuk menampilkan bantuan untuk perintah ini, jalankan dbutils.widgets.help("multiselect").
Contoh ini membuat dan menampilkan widget pilihan ganda dengan nama terprogram days_multiselect. Widget tersebut memberikan pilihan Monday, Sunday dan serta diatur 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
perintah remove (dbutils.widgets.remove)
Menghapus widget dengan nama terprogram yang ditentukan.
Untuk menampilkan bantuan untuk perintah ini, jalankan dbutils.widgets.help("remove").
Penting
Jika Anda menambahkan perintah untuk menghapus widget, artinya Anda tidak dapat menambahkan perintah berikutnya untuk membuat widget di sel yang sama. Anda harus membuat widget di sel lain.
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)
Menghapus semua widget dari notebook.
Untuk menampilkan bantuan untuk perintah ini, jalankan dbutils.widgets.help("removeAll").
Penting
Jika Anda menambahkan perintah untuk menghapus semua widget, artinya Anda tidak dapat menambahkan perintah berikutnya untuk membuat widget di sel yang sama. Anda harus membuat widget di sel lain.
Contoh ini menghapus semua widget dari notebook.
Python
dbutils.widgets.removeAll()
R
dbutils.widgets.removeAll()
Scala
dbutils.widgets.removeAll()
perintah text (dbutils.widgets.text)
Membuat dan menampilkan widget teks dengan nama terprogram yang ditentukan, nilai default, dan label opsional.
Untuk menampilkan bantuan untuk perintah ini, jalankan dbutils.widgets.help("text").
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. Meskipun pustaka ini masih tersedia, Databricks merencanakan tidak ada fitur baru yang dbutils-api berfungsi untuk pustaka.
Databricks merekomendasikan agar Anda menggunakan salah satu pustaka berikut:
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 API DBUtils di situs web Maven Repository.
Setelah Anda membangun aplikasi Anda terhadap pustaka ini, Anda dapat menyebarkan aplikasi.
Penting
Pustaka dbutils-api memungkinkan Anda untuk mengompilasi aplikasi yang menggunakan dbutils secara lokal, tetapi tidak untuk menjalankannya. Untuk menjalankan aplikasi, Anda harus menyebarkannya di Azure Databricks.
Batasan
Memanggil dbutils di dalam eksekutor dapat menghasilkan hasil yang tidak terduga atau berpotensi mengakibatkan kesalahan.
Jika Anda perlu menjalankan operasi sistem file pada eksekutor menggunakan dbutils, ada beberapa alternatif yang lebih cepat dan lebih terukur yang tersedia:
- Untuk operasi salin atau pindahkan file, Anda dapat memeriksa opsi yang lebih cepat untuk menjalankan operasi sistem file yang dijelaskan dalam Memparalelkan operasi sistem file.
- Untuk daftar sistem file dan operasi hapus, Anda dapat merujuk ke daftar paralel dan menghapus metode 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.
Saran dan Komentar
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: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk