Bagikan melalui


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, maka ValueError 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 (kecuali default telah disebutkan).
  • default adalah nilai opsional yang dikembalikan apabila key tidak dapat ditemukan. default tidak bisa menjadi None.
  • 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 menaikkan TypeError secara default. debugValue tidak bisa menjadi None.

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 debugValueditentukan 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 kunci K, ini adalah dua nilai tugas berbeda yang memiliki kunci yang sama K.
  • 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
listScopes 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 atau toys_dropdown.
  • Nama parameter kustom diteruskan ke notebook sebagai bagian dari tugas notebook, misalnya name atau age. Untuk informasi selengkapnya, lihat cakupan parameter untuk tugas buku catatan di UI pekerjaan atau bidang notebook_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.