Databricks 公用程式 (`dbutils`) 參考

發行項
01/07/2025

本文包含 Databricks 工具（dbutils）的相關參考。公用程式提供命令，可讓您從筆記本使用 Databricks 環境。例如，您可以管理檔案和物件記憶體，並使用秘密。 dbutils 可用於 Python、R 和 Scala 筆記本。

注意

dbutils 僅支援使用 DBFS 的計算環境。

公用程式模組

下列 table 列出 Databricks 公用程式模組，您可以使用 dbutils.help()來擷取。

模組	描述
數據	用於瞭解與資料集互動的工具（實驗性質）
fs	存取 Databricks 檔案系統（DBFS）的工具
作業	運用作業功能的公用程式
程式庫	已廢棄。用於管理會話範圍連結庫的公用程式
筆記本	用於管理筆記本控制流程的公用程式（EXPERIMENTAL）
秘密	用於運用筆記本中機密資訊的工具程式
小工具	參數化筆記本的公用程式。
應用程式介面	用於管理應用程式組建的公用程式

命令說明

若要 list 公用程式模組的命令以及每個命令的簡短描述，請在公用程式模組的名稱後面附加 .help()。下列範例會列出筆記本公用程式的可用命令：

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

若要輸出指令的說明，請執行 dbutils.<utility-name>.help("<command-name>")。下列範例會顯示檔案系統公用程式複製命令的說明，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

資料公用程式 (dbutils.data)

重要

這項功能處於公開預覽狀態。

注意

Databricks Runtime 9.0 和更新版本中提供。

數據公用程式可讓您了解數據集並與其互動。

下列 table 列出這個公用程式的可用命令，您可以使用 dbutils.data.help()來擷取。

指令	描述
總結	總結 Spark DataFrame的內容，並將統計數據可視化以獲得快速見解到 get。

summarize 命令 (dbutils.data.summarize)

注意

這項功能處於公開預覽狀態。

summarize(df: Object, precise: boolean): void

計算並顯示 Apache Spark DataFrame 或 pandas DataFrame 的摘要統計資料。此命令適用於 Python、Scala 和 R。

重要

此命令會分析 DataFrame 的完整內容。針對非常大型的 DataFrame 執行此命令可能非常昂貴。

若要顯示此指令的完整說明，請執行：

dbutils.data.help("summarize")

在 Databricks Runtime 10.4 LTS 和更新版本中，您可以使用其他 precise 參數來調整計算統計資料的有效位數。

當 preciseset 為 false 時（預設值），某些傳回的統計數據會包含近似值，以減少運行時間。
- 類別 columns 的相異 values 數目，對於高基數 columns，可能有 ~5% 相對錯誤。
- 當相異 values 數目大於 10000 時，頻繁的值計數可能會有高達 0.01% 的錯誤。
- 長條圖和百分位數估計值可能相對於資料列總數的誤差高達 0.01%。
當 preciseset 為 true 時，統計數據會以較高的精確度計算。除了數值 columns 的直方圖和百分位數之外，所有統計數據現在都是確切的。
- 長條圖和百分位數估計值可能相對於資料列總數的誤差高達 0.0001%。

數據摘要輸出頂端的工具提示表示目前執行的模式。

例

此範例會顯示預設啟用近似值之 Apache Spark DataFrame 的摘要統計資料。若要查看結果，請在筆記本中執行此命令。此範例是以範例資料集為基礎。

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)

視覺效果會使用 SI 表示法，以精簡呈現小於 0.01 或大於 10000 的數值 values。例如，數值 1.25e-15 會轉譯為。1.25f 其中一個例外：視覺效果會針對 B (1.0e9) 使用「」而不是「G」。

檔案系統公用程式 (dbutils.fs)

檔案系統公用程式可讓您存取什麼是 DBFS？，讓您更輕鬆地使用 Azure Databricks 作為檔案系統。

警告

所有 dbutils.fs 方法的 Python 實作都會使用 snake_case，而不是 camelCase 用於關鍵字格式化。

例如，dbutils.fs.help()顯示的選項extraConfigsdbutils.fs.mount()。不過，在 Python 中，您會使用關鍵詞 extra_configs。

下列 table 列出這個公用程式的可用命令，您可以使用 dbutils.fs.help()來擷取。

命令	描述
cp	複製檔案或目錄（可能跨越 FileSystems）
頭部	傳回指定檔案中最多 "maxBytes" 個位元組，並以 UTF-8 編碼為字串。
ls	列出目錄的內容
mkdirs	如果指定的目錄不存在，請建立該目錄，並同時建立任何必要的父目錄。
掛接	將指定的來源目錄掛載至指定掛載點的 DBFS
掛接	顯示有關 DBFS 中掛載內容的資訊
mv	可能跨檔案系統移動檔案或目錄
將放置	將指定的字串寫出至以UTF-8編碼的檔案
refreshMounts	強制此叢集中的所有機器進行refresh其掛載快取，確保它們能收到最新的資訊。
rm	拿掉檔案或目錄
卸除	刪除 DBFS 載入點
updateMount	類似於 mount（），但會更新現有的裝入點，而不是建立新的裝入點

提示

在筆記本中，您可以使用 %fs magic命令來存取 DBFS。例如，%fs ls /Volumes/main/default/my-volume/ 與 dbutils.fs.ls("/Volumes/main/default/my-volume/") 相同。請參閱 magic 命令。

cp 命令 (dbutils.fs.cp)

cp(from: String, to: String, recurse: boolean = false): boolean

跨檔案系統複製檔案或目錄。

若要顯示此指令的完整說明，請執行：

dbutils.fs.help("cp")

例

本範例會將名為 data.csv 的檔案 /Volumes/main/default/my-volume/ 複製到相同磁碟區中的 new-data.csv。

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

head 命令 (dbutils.fs.head)

head(file: String, maxBytes: int = 65536): String

傳回指定檔案中指定的最大位元元組數目。位元組會以 UTF-8 編碼字串的形式傳回。

若要顯示此指令的完整說明，請執行：

dbutils.fs.help("head")

例

這個範例會顯示位於 data.csv 中的檔案 /Volumes/main/default/my-volume/ 前 25 個位元組。

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"

ls 命令 (dbutils.fs.ls)

ls(dir: String): Seq

列出目錄內容。

若要顯示此指令的完整說明，請執行：

dbutils.fs.help("ls")

例

此範例會顯示 /Volumes/main/default/my-volume/ 的內容相關資訊。 modificationTime 欄位在 Databricks Runtime 10.4 LTS 和更新版本中可用。在 R 中，modificationTime 會以字串的形式傳回。

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))

mkdirs 命令 (dbutils.fs.mkdirs)

mkdirs(dir: String): boolean

如果指定目錄不存在，則建立該目錄。也建立任何必要的父系目錄。

若要顯示此指令的完整說明，請執行：

dbutils.fs.help("mkdirs")

例

這個範例會在 my-data 中建立 /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

mount 命令 (dbutils.fs.mount)

mount(source: String, mountPoint: String, encryptionType: String = "", owner: String = null, extraConfigs: Map = Map.empty[String, String]): boolean

將指定的來源目錄掛接至指定的掛接點上的 DBFS。

若要顯示此指令的完整說明，請執行：

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>")))

如需其他程式碼範例，請參閱連線至 Azure Data Lake Storage Gen2 和 Blob 儲存體。

mounts 命令 (dbutils.fs.mounts)

mounts: Seq

顯示 DBFS 中目前掛接之專案的相關資訊。

若要顯示此指令的完整說明，請執行：

dbutils.fs.help("mounts")

例

警告

在所有其他執行中的叢集上呼叫 dbutils.fs.refreshMounts() 以傳播新的裝載。請參閱 refreshMounts 命令 (dbutils.fs.refreshMounts)。

Python

dbutils.fs.mounts()

Scala

dbutils.fs.mounts()

如需其他程式碼範例，請參閱連線至 Azure Data Lake Storage Gen2 和 Blob 儲存體。

mv 命令 (dbutils.fs.mv)

mv(from: String, to: String, recurse: boolean = false): boolean

移動檔案或目錄，可能跨檔案系統移動。即使是檔案系統內的移動，移動也是複製後刪除。

若要顯示此指令的完整說明，請執行：

dbutils.fs.help("mv")

例

這個範例會將名稱為 rows.csv 的檔案從 /Volumes/main/default/my-volume/ 移至。/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

put 命令 (dbutils.fs.put)

put(file: String, contents: String, overwrite: boolean = false): boolean

將指定的字串寫入檔案。字串為 UTF-8 編碼。

若要顯示此指令的完整說明，請執行：

dbutils.fs.help("put")

例

這個範例會將 Hello, Databricks! 字串寫入 hello.txt 中名為 /Volumes/main/default/my-volume/ 的檔案。若此檔案已存在，系統會覆寫該檔案。

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

refreshMounts 命令 (dbutils.fs.refreshMounts)

refreshMounts: boolean

強制叢集中的所有機器 refresh 其掛接快取，確保它們會收到最新的資訊。

若要顯示此指令的完整說明，請執行：

dbutils.fs.help("refreshMounts")

例

Python

dbutils.fs.refreshMounts()

Scala

dbutils.fs.refreshMounts()

如需額外程式碼範例，請參閱連線至 Azure Data Lake Storage Gen2 和 Blob 儲存體。

rm 命令 (dbutils.fs.rm)

rm(dir: String, recurse: boolean = false): boolean

拿掉檔案或目錄，並選擇性地移除其所有內容。如果指定了檔案， recurse 則會忽略參數。如果指定了目錄，當停用且目錄不是空的時 recurse ，就會發生錯誤。

若要顯示此指令的完整說明，請執行：

dbutils.fs.help("rm")

例

此範例會移除整個目錄 /Volumes/main/default/my-volume/my-data/ ，包括其內容。

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

unmount 命令 (dbutils.fs.unmount)

unmount(mountPoint: String): boolean

刪除 DBFS 掛接點。

警告

為避免錯誤，請勿在其他工作讀取或寫入時修改掛接點。修改掛接之後，請一律在所有其他執行中的叢集上執行 dbutils.fs.refreshMounts()，以傳播任何掛接更新。請參閱 refreshMounts 命令 (dbutils.fs.refreshMounts)。

若要顯示此指令的完整說明，請執行：

dbutils.fs.help("unmount")

例

dbutils.fs.unmount("/mnt/<mount-name>")

如需其他程式碼範例，請參閱連線至 Azure Data Lake Storage Gen2 和 Blob 儲存體。

updateMount 命令 (dbutils.fs.updateMount)

updateMount(source: String, mountPoint: String, encryptionType: String = "", owner: String = null, extraConfigs: Map = Map.empty[String, String]): boolean

類似於 dbutils.fs.mount 命令，但會更新現有的掛接點，而不是建立新的掛接點。若屬性不存在，會傳回錯誤。

警告

此命令在 Databricks Runtime 10.4 LTS 和更新版本中可用。

若要顯示此指令的完整說明，請執行：

dbutils.fs.help("updateMount")

例

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>")))

工作公用程式 (dbutils.jobs)

提供用於利用作業功能的工具。

注意

此公用程式僅適用於 Python。

下列 table 列出此公用程式的可用模組，您可以使用 dbutils.jobs.help()來擷取。

子模組	描述
taskValues	提供可以有效運用作業任務 values 的工具

taskValues 子公用程式 (dbutils.jobs.taskValues)

注意

此子公用程式僅適用於 Python。

提供利用作業工作 values的命令。

使用此子公用程式於作業進行時任意 set 和 getvalues。這些 values 叫作 任務 values。任何工作都可以被上游工作 getvaluesset，並且可以由下游工作 setvalues 使用。

每個工作值在相同的工作中都有唯一索引鍵。這個唯一索引鍵稱為工作值的索引鍵。工作值是使用工作名稱和工作值索引鍵來存取。您可以使用此選項，將工作下游的資訊傳遞至相同作業執行內的工作。例如，您可以在作業執行內的不同工作之間傳遞標識碼或計量，例如機器學習模型評估的相關信息。

下列 table 列出這個子公用程式的可用命令，您可以使用 dbutils.jobs.taskValues.help()來擷取。

命令	描述
get	取得目前工作執行中指定工作之指定工作值的內容。
set	設定或更新工作值。您可以針對作業執行 set 最多 250 個工作 values。

get 命令（dbutils.jobs.taskValues.get）

注意

此命令僅適用於 Python。

在 Databricks Runtime 10.4 和更早版本上，如果 get 找不到工作，則會引發 Py4JJavaError，而不是 ValueError。

get(taskKey: String, key: String, default: int, debugValue: int): Seq

取得目前工作執行中指定工作之指定工作值的內容。

若要顯示此指令的完整說明，請執行：

dbutils.jobs.taskValues.help("get")

例

例如：

dbutils.jobs.taskValues.get(taskKey    = "my-task", \
                            key        = "my-key", \
                            default    = 7, \
                            debugValue = 42)

在前述範例中:

taskKey 是設定工作值的工作名稱。如果指令找不到此工作，則會引發 ValueError。
key 是您使用 set 命令 set 的工作值索引鍵名稱（dbutils.jobs.taskValues.set）。如果命令找不到此工作值的索引鍵，則會引發 ValueError (除非指定了 default)。
如果找不到 default，則會傳回選用值 key。 default 不可以是 None。
debugValue 是可選值，如果您嘗試從一個在作業之外執行的筆記本中 get 任務值，則會返回 debugValue。當您想要手動執行筆記本並傳回某些值，而不是預設引發 TypeError 時，這在偵錯期間很有用。 debugValue 不可以是 None。

如果您嘗試從在作業外部執行的筆記本內 get 工作值，此命令預設會引發 TypeError。不過，如果在命令中指定 debugValue 引數，則會傳回 debugValue 的值，而不是引發 TypeError。

set 命令（dbutils.jobs.taskValues.set）

注意

此命令僅適用於 Python。

set(key: String, value: String): boolean

設定或更新工作值。您可以針對作業執行 set 最多 250 個工作 values。

若要顯示此指令的完整說明，請執行：

dbutils.jobs.taskValues.help("set")

例

這些範例包含：

dbutils.jobs.taskValues.set(key   = "my-key", \
                            value = 5)

dbutils.jobs.taskValues.set(key   = "my-other-key", \
                            value = "my other value")

在上述範例中：

key 是工作值的索引鍵。此索引鍵對工作而言必須是唯一的。也就是說，如果兩個不同的任務各自擁有任務值 set 且該任務值具有鍵值 K，那麼這兩個不同的任務 values 擁有相同的鍵值 K。
value 是此工作值索引鍵的值。此命令必須能夠以 JSON 格式在內部表示值。值的 JSON 表示大小不能超過 48 KiB。

如果您嘗試在不屬於任何作業的執行環境下的筆記本內提取任務值 set，該命令不會執行任何動作。

程式庫公用程式 (dbutils.library)

dbutils.library 子模組中的大部分方法已被取代。請參閱程式庫公用程式 (dbutils.library) (legacy)。

您可能需要以程序設計方式重新啟動 Azure Databricks 上的 Python 程序，以確保本機安裝或升級的程式庫在 Python 核心中正常運作，以取得目前的 SparkSession。若要這麼做，請執行 dbutils.library.restartPython 命令。請參閱在 Azure Databricks 上重新啟動 Python 程序。

筆記本公用程式 (dbutils.notebook)

Notebook 公用程式可讓您將筆記本鏈結在一起，並對其結果採取行動。請參閱管理筆記本，並將筆記本中的程式代碼模組化。

下列 table 列出這個公用程式的可用命令，您可以使用 dbutils.notebook.help()來擷取。

命令	描述
退出	結束筆記本並帶有一個值
執行	執行筆記本並傳回其結束值

exit 命令 (dbutils.notebook.exit)

exit(value: String): void

以一個值退出筆記本。

若要顯示此指令的完整說明，請執行：

dbutils.notebook.help("exit")

例

此範例會以值 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

注意

如果執行有結構化串流的查詢在背景執行，呼叫 dbutils.notebook.exit() 並不會終止執行。只要查詢在背景中執行，執行就會繼續執行。您可以按下查詢儲存格中的 [取消]，或執行 query.stop() 來停止在背景執行的查詢。當查詢停止時，您可以使用終止執行。dbutils.notebook.exit()

run 命令 (dbutils.notebook.run)

run(path: String, timeoutSeconds: int, arguments: Map): String

執行筆記本並傳回其結束值。筆記本預設會在目前的叢集中執行。

注意

從 run 命令傳回的字串值長度上限為 5 MB。請參閱 Get 一次運行的輸出（GET /jobs/runs/get-output）。

若要顯示此指令的完整說明，請執行：

dbutils.notebook.help("run")

例

此範例會在與呼叫筆記本相同的位置執行名為 My Other Notebook 的筆記本。呼叫的 Notebook 結尾是程式碼行 dbutils.notebook.exit("Exiting from My Other Notebook")。如果呼叫的筆記本未在 60 秒內完成執行，則會擲回例外。

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

祕密公用程式 (dbutils.secrets)

祕密公用程式可讓您儲存和存取敏感性認證資訊，而不會在筆記本中顯示它們。請參閱秘密管理和步驟 3：在筆記本中使用秘密。

下列 table 列出這個公用程式的可用命令，您可以使用 dbutils.secrets.help()來擷取。

命令	描述
get	取得具有範圍和鍵值的秘密值字串表現形式
getBytes	取得具有範圍和索引鍵之秘密值的位元組表示法
list	列出範圍內秘密的秘密元數據
listScopes	列出秘密範圍

get 命令（dbutils.secrets.get）

get(scope: String, key: String): String

取得指定祕密範圍和索引鍵之祕密值的字串表示。

警告

系統管理員、祕密建立者和獲授與權限的使用者可以讀取 Azure Databricks 祕密。雖然 Azure Databricks 會努力編輯可能顯示在筆記本中的秘密 values，但無法防止這類使用者讀取秘密。如需詳細資訊，請參閱祕密修訂。

若要顯示此指令的完整說明，請執行：

dbutils.secrets.help("get")

例

這個範例會取得名為 my-scope 範圍之祕密值的字串表示，以及名為 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]

getBytes 命令 (dbutils.secrets.getBytes)

getBytes(scope: String, key: String): byte[]

取得指定範圍和索引鍵之祕密值的位元組表示。

若要顯示此指令的完整說明，請執行：

dbutils.secrets.help("getBytes")

例

這個範例會取得名為 a1!b2@c3# 的範圍和名為 my-scope 之索引鍵的位元組表示法(在此範例中為 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)

list 命令（dbutils.secrets.list）

list(scope: String): Seq

列出指定範圍內祕密的中繼資料。

若要顯示此指令的完整說明，請執行：

dbutils.secrets.help("list")

例

此範例會列出名為 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))

listScopes 命令 (dbutils.secrets.listScopes)

listScopes: Seq

列出可用的範圍。

若要顯示此指令的完整說明，請執行：

dbutils.secrets.help("listScopes")

例

此範例會列出可用的範圍。

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))

Widgets 公用程式 (dbutils.widgets)

Widgets 公用程式可讓您將筆記本參數化。請參閱 Databricks 小工具。

下列 table 列出這個公用程式的可用命令，您可以使用 dbutils.widgets.help()來擷取。

命令	描述
下拉式方塊	建立具有指定名稱、預設值和選項的下拉式方塊輸入小工具
下拉式清單	使用指定的名稱、預設值和選項，建立下拉選單輸入元件
get	擷取輸入元件的當前值
getAll	擷取所有小工具名稱及其 values 的對應
getArgument	已棄用。相當於 get
多重選取	建立具有指定名稱、預設值和選項的多重選取輸入小工具
remove	從筆記本移除輸入小工具
removeAll	移除筆記本中的所有小工具
文字	建立具有指定名稱和預設值的文字輸入小工具

combobox 命令 (dbutils.widgets.combobox)

combobox(name: String, defaultValue: String, choices: Seq, label: String): void

使用指定的程式設計名稱、預設值、選項和選用標籤，建立並顯示下拉式方塊小工具。

若要顯示此指令的完整說明，請執行：

dbutils.widgets.help("combobox")

例

此範例會建立並顯示具有程式設計名稱 fruits_combobox 的下拉式方塊小工具。它提供選項 apple、banana、coconut和 dragon fruit，並將初始值設定為 setbanana。此下拉式方塊小工具具有隨附的標籤。Fruits 此範例會以列印下拉式方塊小工具 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

dropdown(name: String, defaultValue: String, choices: Seq, label: String): void

使用指定的程式設計名稱、預設值、選項和選用標籤，建立並顯示下拉式清單小工具。

若要顯示此指令的完整說明，請執行：

dbutils.widgets.help("dropdown")

例

此範例會建立並顯示具有程式設計名稱 toys_dropdown 的下拉式小工具。它提供選項 alphabet blocks、basketball、cape和 doll，並將初始值設為 basketball的 set。這個下拉式清單小工具具有隨附的標籤。Toys 此範例的結尾是列印下拉式小工具 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

get 命令（dbutils.widgets.get）

get(name: String): String

取得具有指定程式設計名稱之小工具的目前值。這個程式設計名稱可以是：

筆記本中自定義小工具的名稱，例如 fruits_combobox 或 toys_dropdown。
做為筆記本工作的一部分傳遞至筆記本的自訂參數名稱，例如 name 或。age 如需詳細資訊，請參閱作業 UI 中筆記本工作的涵蓋範圍，或觸發作業 API 中新作業執行（）作業的字段。

若要顯示此指令的完整說明，請執行：

dbutils.widgets.help("get")

例

此範例會取得具有程式設計名稱 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

這個範例會取得具有程式設計名稱 age 的筆記本工作參數值。當相關筆記本工作執行時，此參數從 set 到 35。

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

getAll 命令 (dbutils.widgets.getAll)

getAll: map

獲取所有目前控件名稱和 values的映射。這對於快速將小工具 values 傳遞至 spark.sql() 查詢特別有用。

此命令在 Databricks Runtime 13.3 LTS 和更新版本中可用。它僅適用於 Python 和 Scala。

若要顯示此指令的完整說明，請執行：

dbutils.widgets.help("getAll")

例

此範例會取得 widget values 的映射，並作為 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

getArgument 命令 (dbutils.widgets.getArgument)

getArgument(name: String, optional: String): String

取得具有指定程式設計名稱之小工具的目前值。如果小工具不存在，則可以傳回選用訊息。

注意

此命令已被取代。使用 dbutils.widgets。改用get。

若要顯示此指令的完整說明，請執行：

dbutils.widgets.help("getArgument")

例

此範例會取得具有程式設計名稱 fruits_combobox 的小工具值。如果這個小工具不存在，則會傳回訊息 Error: Cannot find fruits combobox。

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

multiselect 命令 (dbutils.widgets.multiselect)

multiselect(name: String, defaultValue: String, choices: Seq, label: String): void

使用指定的程式設計名稱、預設值、選項和選用標籤，建立並顯示多重選取小工具。

若要顯示此指令的完整說明，請執行：

dbutils.widgets.help("multiselect")

例

此範例會建立並顯示具有程序設計名稱 days_multiselect 的多選小工具。它提供從 Monday 到 Sunday 的選項，並與 Tuesday的初始值 set。這個多重選取小工具具有隨附的標籤。Days of the Week 此範例的結尾是列印多重選取小工具 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

remove 命令（dbutils.widgets.remove）

remove(name: String): void

移除具有指定程式設計名稱的小工具。

若要顯示此指令的完整說明，請執行：

dbutils.widgets.help("remove")

重要

如果您將命令新增至小工具 remove，就無法再進一步新增命令以在同一個儲存格中建立小工具。您必須在另一個儲存格中建立小工具。

例

此範例會移除具有程式設計名稱 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

removeAll 命令 (dbutils.widgets.removeAll)

removeAll: void

從筆記本中移除所有小工具。

若要顯示此指令的完整說明，請執行：

dbutils.widgets.help("removeAll")

重要

如果您將命令新增至 remove 所有小工具，則無法新增後續命令，以在同一個儲存格中建立任何小工具。您必須在另一個儲存格中建立小工具。

例

此範例會從筆記本中移除所有小工具。

Python

dbutils.widgets.removeAll()

R

dbutils.widgets.removeAll()

Scala

dbutils.widgets.removeAll()

text 命令 (dbutils.widgets.text)

text(name: String, defaultValue: String, label: String): void

使用指定的程式設計名稱、預設值和選用標籤，建立並顯示文字小工具。

若要顯示此指令的完整說明，請執行：

dbutils.widgets.help("text")

例

此範例會建立並顯示具有程序設計名稱 your_name_text 的文字小工具。它是 Enter your name的初始值 set。這個文字小工具具有隨附的標籤 Your name。此範例的結尾是列印文字小工具 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

Databricks 公用程式 API 程式庫

重要

Databricks 實用程式 API（dbutils-api）庫已被廢棄。 Databricks 建議您改用下列其中一項：

若要加速應用程式開發，在將應用程式部署為生產工作之前，先編譯、建置及測試應用程式會很有用。為了讓您能夠針對 Databricks 公用程式進行編譯，Databricks 會提供 dbutils-api 程式庫。您可以從 Maven 存放庫網站上的 dbutils-api 網頁下載程式庫，或藉由將相依性新增至組建檔案來包含程式庫：

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'

TARGET取代為所需的目標（例如 2.12），並以VERSION所需的版本取代（例如，。 0.0.5 如需了解可用目標和版本的 list，請參閱 Maven 存放庫網站上的 DBUtils API 網頁。

一旦您針對此程式庫建置應用程式，您就可以部署應用程式。

重要

連結 dbutils-api 庫只允許您在本機編譯使用 dbutils的應用程式，而不是執行它。若要執行應用程式，您必須在 Azure Databricks 中部署它。

限制

在執行程式內呼叫 dbutils 可能會產生非預期的結果或錯誤。

如果您需要使用 dbutils在執行程式上執行文件系統作業，請參閱 list 如何在 Databricks中，使用 Spark 平行列出和刪除方法。

如需執行程式的相關資訊，請參閱 Apache Spark 網站上的叢集模式概觀。

共用方式為

Databricks 公用程式 (dbutils) 參考

公用程式模組

命令說明

資料公用程式 (dbutils.data)

summarize 命令 (dbutils.data.summarize)

例

Python

R

Scala

檔案系統公用程式 (dbutils.fs)

cp 命令 (dbutils.fs.cp)

例

Python

R

Scala

head 命令 (dbutils.fs.head)

例

Python

R

Scala

ls 命令 (dbutils.fs.ls)

例

Python

R

Scala

mkdirs 命令 (dbutils.fs.mkdirs)

例

Python

R

Scala

mount 命令 (dbutils.fs.mount)

例

Python

Scala

mounts 命令 (dbutils.fs.mounts)

例

Python

Scala

mv 命令 (dbutils.fs.mv)

例

Python

R

Scala

put 命令 (dbutils.fs.put)

例

Python

R

Scala

refreshMounts 命令 (dbutils.fs.refreshMounts)

例

Python

Scala

rm 命令 (dbutils.fs.rm)

例

Python

R

Scala

unmount 命令 (dbutils.fs.unmount)

例

updateMount 命令 (dbutils.fs.updateMount)

例

Python

Scala

工作公用程式 (dbutils.jobs)

taskValues 子公用程式 (dbutils.jobs.taskValues)

get 命令 （dbutils.jobs.taskValues.get）

例

set 命令（dbutils.jobs.taskValues.set）

例

程式庫公用程式 (dbutils.library)

筆記本公用程式 (dbutils.notebook)

exit 命令 (dbutils.notebook.exit)

例

Python

R

Scala

run 命令 (dbutils.notebook.run)

例

Python

Databricks 公用程式 (`dbutils`) 參考

get 命令（dbutils.jobs.taskValues.get）

list 命令（dbutils.secrets.list）

get 命令（dbutils.widgets.get）

remove 命令（dbutils.widgets.remove）