dbutils) 参考本文是 Databricks Utilities (dbutils) 的参考。 dbutils 实用工具在 Python、R 和 Scala 笔记本中可用。 可以使用该实用工具来：
备注
dbutils 仅支持使用 DBFS 的计算环境。
实用工具：数据、fs、作业、库、笔记本、机密、小组件、实用工具 API 库
要列出可用的实用工具以及每个实用工具的简短说明，请针对 Python 或 Scala 运行 dbutils.help()。
此示例列出了 Databricks 实用工具的可用命令。
dbutils.help()
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
要列出实用工具的可用命令以及每个命令的简短说明，请在此实用工具的编程名称之后运行 .help()。
此示例列出了 Databricks 文件系统 (DBFS) 实用工具的可用命令。
dbutils.fs.help()
dbutils.fs.help()
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
要显示命令的相关帮助，请在命令名称之后运行 .help("<command-name>")。
此示例显示 DBFS 复制命令的相关帮助。
dbutils.fs.help("cp")
dbutils.fs.help("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
重要
此功能目前以公共预览版提供。
备注
可在 Databricks Runtime 9.0 及更高版本中使用。
命令：summarize
使用数据实用工具可以理解和解释数据集。 要列出可用命令，请运行 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
计算并显示 Apache Spark DataFrame 或 pandas DataFrame 的摘要统计信息。 此命令可用于 Python、Scala 和 R。
此命令会分析数据帧的完整内容。 为非常大的数据帧运行此命令可能非常昂贵。
要显示此命令的相关帮助，请运行 dbutils.data.help("summarize")。
在 Databricks Runtime 10.4 LTS 及更高版本中，可以使用其他 precise 参数来调整计算统计信息的精度。
备注
此功能目前以公共预览版提供。
precise 设置为 false（默认值），则某些返回的统计信息会包含近似值以缩短运行时间。
precise 设置为 true，计算的统计信息具有更高的精度。 对于数值列，除直方图和百分位估计值以外的所有统计信息目前都非常精确。
数据摘要输出顶部的工具提示指示当前运行的模式。
此示例显示默认启用了近似值的 Apache Spark DataFrame 的摘要统计信息。 要查看结果，请在笔记本中运行此命令。 此示例基于示例数据集。
df = spark.read.format('csv').load(
'/databricks-datasets/Rdatasets/data-001/csv/ggplot2/diamonds.csv',
header=True,
inferSchema=True
)
dbutils.data.summarize(df)
df <- read.df("/databricks-datasets/Rdatasets/data-001/csv/ggplot2/diamonds.csv", source = "csv", header="true", inferSchema = "true")
dbutils.data.summarize(df)
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 的数值。 例如，数字值 1.25e-15 将呈现为 1.25f。 一个例外：对于 1.0e9（千兆），可视化效果为使用“B”而不是“G”。
警告
所有 dbutils.fs 方法的 Python 实现都使用 snake_case 而不是 camelCase 进行关键字格式设置。
例如，dbutils.fs.help()显示选项extraConfigs。dbutils.fs.mount() 但是，在 Python 中，将使用关键字 extra_configs。
命令：cp、head、ls、mkdirs、mount、mounts、mv、put、refreshMounts、rm、unmount、updateMount
通过文件系统实用工具可访问 什么是 DBFS？，从而更轻松地将 Azure Databricks 用作文件系统。
在笔记本中，可以使用 %fs magic 命令访问 DBFS。 例如，%fs ls /Volumes/main/default/my-volume/ 和 duties.fs.ls("/Volumes/main/default/my-volume/") 相同。 请参阅 magic 命令。
要列出可用命令，请运行 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
复制文件或目录，可能跨文件系统复制。
要显示此命令的相关帮助，请运行 dbutils.fs.help("cp")。
此示例将名为 data.csv 的文件从 /Volumes/main/default/my-volume/ 复制到同一卷中的 new-data.csv。
dbutils.fs.cp("/Volumes/main/default/my-volume/data.csv", "/Volumes/main/default/my-volume/new-data.csv")
# Out[4]: True
dbutils.fs.cp("/Volumes/main/default/my-volume/data.csv", "/Volumes/main/default/my-volume/new-data.csv")
# [1] TRUE
dbutils.fs.cp("/Volumes/main/default/my-volume/data.csv", "/Volumes/main/default/my-volume/new-data.csv")
// res3: Boolean = true
返回给定文件中指定的最大字节数。 字节以 UTF-8 编码字符串形式返回。
要显示此命令的相关帮助，请运行 dbutils.fs.help("head")。
此示例显示位于 /Volumes/main/default/my-volume/ 中的 data.csv 文件的前 25 个字节。
dbutils.fs.head("/Volumes/main/default/my-volume/data.csv", 25)
# [Truncated to first 25 bytes]
# Out[12]: 'Year,First Name,County,Se'
dbutils.fs.head("/Volumes/main/default/my-volume/data.csv", 25)
# [1] "Year,First Name,County,Se"
dbutils.fs.head("/Volumes/main/default/my-volume/data.csv", 25)
// [Truncated to first 25 bytes]
// res4: String =
// "Year,First Name,County,Se"
列出目录的内容。
要显示此命令的相关帮助，请运行 dbutils.fs.help("ls")。
此示例显示有关 /Volumes/main/default/my-volume/ 的内容的信息。 modificationTime 字段在 Databricks Runtime 10.4 LTS 及更高版本中可用。 在 R 中， modificationTime 作为字符串返回。
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)]
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"
dbutils.fs.ls("/tmp")
// res6: Seq[com.databricks.backend.daemon.dbutils.FileInfo] = WrappedArray(FileInfo(/Volumes/main/default/my-volume/data.csv, 2258987, 1711357839000))
如果给定目录不存在，则创建它。 同时创建任何必要的父目录。
要显示此命令的相关帮助，请运行 dbutils.fs.help("mkdirs")。
此示例会在 /Volumes/main/default/my-volume/ 中创建目录 my-data。
dbutils.fs.mkdirs("/Volumes/main/default/my-volume/my-data")
# Out[15]: True
dbutils.fs.mkdirs("/Volumes/main/default/my-volume/my-data")
# [1] TRUE
dbutils.fs.mkdirs("/Volumes/main/default/my-volume/my-data")
// res7: Boolean = true
将指定的源目录装载到 DBFS 中的指定装入点。
要显示此命令的相关帮助，请运行 dbutils.fs.help("mount")。
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>")})
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 存储。
显示有关 DBFS 中当前装载内容的信息。
要显示此命令的相关帮助，请运行 dbutils.fs.help("mounts")。
警告
在所有其他正在运行的群集上调用 dbutils.fs.refreshMounts() 来传播新装载。 请参阅 refreshMounts 命令 (dbutils.fs.refreshMounts)。
dbutils.fs.mounts()
dbutils.fs.mounts()
有关其他代码示例，请参阅连接到 Azure Data Lake Storage Gen2 和 Blob 存储。
移动文件或目录，可能跨文件系统移动。 移动是复制后再删除，即使在文件系统内移动时也一样。
要显示此命令的相关帮助，请运行 dbutils.fs.help("mv")。
此示例将文件 rows.csv 从 /Volumes/main/default/my-volume/ 移动到 /Volumes/main/default/my-volume/my-data/。
dbutils.fs.mv("/Volumes/main/default/my-volume/rows.csv", "/Volumes/main/default/my-volume/my-data/")
# Out[2]: True
dbutils.fs.mv("/Volumes/main/default/my-volume/rows.csv", "/Volumes/main/default/my-volume/my-data/")
# [1] TRUE
dbutils.fs.mv("/Volumes/main/default/my-volume/rows.csv", "/Volumes/main/default/my-volume/my-data/")
// res1: Boolean = true
将指定的字符串写入文件。 该字符串采用 UTF-8 编码。
要显示此命令的相关帮助，请运行 dbutils.fs.help("put")。
此示例将字符串 Hello, Databricks! 写入 /Volumes/main/default/my-volume/ 中名为 hello.txt 的文件。 如果此文件已存在，则会将其覆盖。
dbutils.fs.put("/Volumes/main/default/my-volume/hello.txt", "Hello, Databricks!", True)
# Wrote 2258987 bytes.
# Out[6]: True
dbutils.fs.put("/Volumes/main/default/my-volume/hello.txt", "Hello, Databricks!", TRUE)
# [1] TRUE
dbutils.fs.put("/Volumes/main/default/my-volume/hello.txt", "Hello, Databricks!", true)
// Wrote 2258987 bytes.
// res2: Boolean = true
强制群集中的所有计算机刷新其装载缓存，确保它们能接收最新的信息。
要显示此命令的相关帮助，请运行 dbutils.fs.help("refreshMounts")。
dbutils.fs.refreshMounts()
dbutils.fs.refreshMounts()
有关其他代码示例，请参阅连接到 Azure Data Lake Storage Gen2 和 Blob 存储。
删除文件或目录，并根据需要删除其所有内容。 如果指定了文件，则 recurse 忽略参数。 如果指定了目录，则禁用目录且该目录不为空时 recurse 发生错误。
要显示此命令的相关帮助，请运行 dbutils.fs.help("rm")。
此示例删除包含其内容的整个目录 /Volumes/main/default/my-volume/my-data/ 。
dbutils.fs.rm("/Volumes/main/default/my-volume/my-data/", True)
# Out[8]: True
dbutils.fs.rm("/Volumes/main/default/my-volume/my-data/", TRUE)
# [1] TRUE
dbutils.fs.rm("/Volumes/main/default/my-volume/my-data/", true)
// res6: Boolean = true
删除 DBFS 装入点。
警告
为了避免错误，切勿在其他作业正在读取或写入装入点时修改装入点。 修改装载后，请始终在所有其他正在运行的群集上运行 dbutils.fs.refreshMounts()，以传播任何装载更新。 请参阅 refreshMounts 命令 (dbutils.fs.refreshMounts)。
要显示此命令的相关帮助，请运行 dbutils.fs.help("unmount")。
dbutils.fs.unmount("/mnt/<mount-name>")
有关其他代码示例，请参阅连接到 Azure Data Lake Storage Gen2 和 Blob 存储。
类似于 dbutils.fs.mount 命令，但更新现有安装点而不是创建新安装点。 如果装入点不存在，则返回错误。
要显示此命令的相关帮助，请运行 dbutils.fs.help("updateMount")。
警告
为了避免错误，切勿在其他作业正在读取或写入装入点时修改装入点。 修改装载后，请始终在所有其他正在运行的群集上运行 dbutils.fs.refreshMounts()，以传播任何装载更新。 请参阅 refreshMounts 命令 (dbutils.fs.refreshMounts)。
此命令在 Databricks Runtime 10.4 LTS 及更高版本中可用。
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>")})
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>")))
子实用工具：taskValues
备注
此实用工具只适用于 Python。
作业实用工具允许利用作业功能。 要显示此实用工具的相关帮助，请运行 dbutils.jobs.help()。
Provides utilities for leveraging jobs features.
taskValues: TaskValuesUtils -> Provides utilities for leveraging job task values
备注
此子实用工具只适用于 Python。
提供用于利用作业任务值的命令。
使用此子实用工具在作业运行期间设置和获取任意值。 这些值称为“任务值”。 任何任务都可以获取上游任务设置的值，并为要使用的下游任务设置值。
每个任务值在同一个任务中都具有一个唯一的键。 此唯一键称为任务值的键。 使用任务名称和任务值的键访问任务值。 可以使用此选项将下游信息从任务传递到同一作业运行中的任务。 例如，可以在作业运行中的不同任务之间传递标识符或指标，例如有关机器学习模型评估的信息。
要显示此子实用工具的相关帮助，请运行 dbutils.jobs.taskValues.help()。
获取当前作业运行中指定任务的指定任务值的内容。
要显示此命令的相关帮助，请运行 dbutils.jobs.taskValues.help("get")。
例如：
dbutils.jobs.taskValues.get(taskKey = "my-task", \
key = "my-key", \
default = 7, \
debugValue = 42)
在上面的示例中：
taskKey 是设置任务值的任务的名称。 如果命令找不到此任务，则会引发 ValueError。key 是使用 set 命令 (dbutils.jobs.taskValues.set) 设置的任务值键的名称。 如果命令找不到此任务值的键，则会引发 ValueError（除非指定了 default）。default 是在找不到 key 时返回的可选值。 default 不能为 None。debugValue 是一个可选值，如果尝试从在作业外部运行的笔记本中获取任务值，则会返回该值。 如果要手动运行笔记本并返回一些值（而不是默认引发 TypeError），则它在调试过程中很有用。 debugValue 不能为 None。如果尝试从在作业外部运行的笔记本中获取任务值，则此命令将默认引发 TypeError。 但如果在命令中指定了 debugValue 参数，则会返回 debugValue 的值而不是引发 TypeError。
备注
此命令仅适用于 Python。
设置或更新任务值。 最多可为作业运行设置 250 个任务值。
要显示此命令的相关帮助，请运行 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 是任务值的键。 此键对于任务必须是独一无二的。 也就是说，如果两个不同的任务分别使用 K 键设置任务值，则这两个不同的任务值具有相同的键 (K)。value 是此任务值键的值。 此命令必须能够在内部以 JSON 格式表示值。 值的 JSON 表示形式的大小不能超过 48 KiB。如果尝试从在作业外部运行的笔记本中设置任务值，则此命令不执行任何操作。
dbutils.library 子模块中的大多数方法已弃用。 请参阅库实用工具 (dbutils.library)（旧版）。
你可以需要在 Azure Databricks 上以编程方式重启 Python 进程，以确保本地安装的或升级的库在当前 SparkSession 的 Python 内核中正常运行。 为此，请运行 dbutils.library.restartPython 命令。 请参阅在 Azure Databricks 上重启 Python 进程。
可以通过笔记本实用工具将笔记本链接在一起，并对其结果进行操作。 请参阅从一个 Databricks 笔记本运行另一个笔记本。
要列出可用命令，请运行 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.
使用值退出笔记本。
要显示此命令的相关帮助，请运行 dbutils.notebook.help("exit")。
此示例使用值 Exiting from My Other Notebook 退出笔记本。
dbutils.notebook.exit("Exiting from My Other Notebook")
# Notebook exited: Exiting from My Other Notebook
dbutils.notebook.exit("Exiting from My Other Notebook")
# Notebook exited: Exiting from My Other Notebook
dbutils.notebook.exit("Exiting from My Other Notebook")
// Notebook exited: Exiting from My Other Notebook
备注
如果运行包含的查询在后台运行结构化流式处理，则调用 dbutils.notebook.exit() 不会终止运行。 只要查询在后台执行，运行就会继续执行。 可单击查询单元格中的“取消”或运行 query.stop() 来停止在后台运行的查询。 查询停止时，可使用 dbutils.notebook.exit() 终止运行。
运行笔记本并返回其退出值。 默认情况下，笔记本将在当前群集中运行。
备注
从 run 命令返回的字符串值的最大长度为 5 MB。 请参阅获取单个运行的输出 (GET /jobs/runs/get-output)。
要显示此命令的相关帮助，请运行 dbutils.notebook.help("run")。
此示例在调用笔记本的位置运行一个名为 My Other Notebook 的笔记本。 被调用的笔记本以代码行 dbutils.notebook.exit("Exiting from My Other Notebook") 结束。 如果被调用的笔记本在 60 秒内未完成运行，则会引发异常。
dbutils.notebook.run("My Other Notebook", 60)
# Out[14]: 'Exiting from My Other Notebook'
dbutils.notebook.run("My Other Notebook", 60)
// res2: String = Exiting from My Other Notebook
命令：get、getBytes、list、listScopes
利用机密实用工具可以存储和访问敏感的凭据信息，而无需使其在笔记本中可见。 请参阅机密管理和步骤 3：在笔记本中使用机密。 要列出可用命令，请运行 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
获取指定机密范围和密钥的机密值的字符串表示形式。
警告
具有权限的管理员、机密创建者和用户可读取 Azure Databricks 机密。 虽然 Azure Databricks 会努力编修笔记本中可能会显示的机密值，但没法阻止此类用户读取机密。 有关详细信息，请查看机密编修。
要显示此命令的相关帮助，请运行 dbutils.secrets.help("get")。
此示例获取名为 my-scope 的范围和名为 my-key 的密钥的机密值的字符串表示形式。
dbutils.secrets.get(scope="my-scope", key="my-key")
# Out[14]: '[REDACTED]'
dbutils.secrets.get(scope="my-scope", key="my-key")
# [1] "[REDACTED]"
dbutils.secrets.get(scope="my-scope", key="my-key")
// res0: String = [REDACTED]
获取指定范围和密钥的机密值的字节表示形式。
要显示此命令的相关帮助，请运行 dbutils.secrets.help("getBytes")。
此示例获取名为 my-scope 的范围和名为 my-key 的密钥的机密值（在示例中为 a1!b2@c3#）的字节表示形式。
dbutils.secrets.getBytes(scope="my-scope", key="my-key")
# Out[1]: b'a1!b2@c3#'
dbutils.secrets.getBytes(scope="my-scope", key="my-key")
# [1] 61 31 21 62 32 40 63 33 23
dbutils.secrets.getBytes(scope="my-scope", key="my-key")
// res1: Array[Byte] = Array(97, 49, 33, 98, 50, 64, 99, 51, 35)
列出指定范围内的机密的元数据。
要显示此命令的相关帮助，请运行 dbutils.secrets.help("list")。
此示例列出了名为 my-scope 的范围内机密的元数据。
dbutils.secrets.list("my-scope")
# Out[10]: [SecretMetadata(key='my-key')]
dbutils.secrets.list("my-scope")
# [[1]]
# [[1]]$key
# [1] "my-key"
dbutils.secrets.list("my-scope")
// res2: Seq[com.databricks.dbutils_v1.SecretMetadata] = ArrayBuffer(SecretMetadata(my-key))
列出可用范围。
要显示此命令的相关帮助，请运行 dbutils.secrets.help("listScopes")。
此示例列出可用的范围。
dbutils.secrets.listScopes()
# Out[14]: [SecretScope(name='my-scope')]
dbutils.secrets.listScopes()
# [[1]]
# [[1]]$name
# [1] "my-scope"
dbutils.secrets.listScopes()
// res3: Seq[com.databricks.dbutils_v1.SecretScope] = ArrayBuffer(SecretScope(my-scope))
命令：combobox、dropdown、get、getArgument、multiselect、remove、removeAll、text
通过小组件实用工具可以将笔记本参数化。 请参阅 Databricks 小组件。
要列出可用命令，请运行 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
使用指定的编程名称、默认值、选项和可选标签创建并显示一个 combobox 小组件。
要显示此命令的相关帮助，请运行 dbutils.widgets.help("combobox")。
此示例创建并显示编程名称为 fruits_combobox 的 combobox 小组件。 它提供了 apple、banana、coconut 和 dragon fruit 选项并设置为初始值 banana。 此 combobox 小组件包含一个随附的标签 Fruits。 此示例以打印 combobox 小组件的初始值 banana 结束。
dbutils.widgets.combobox(
name='fruits_combobox',
defaultValue='banana',
choices=['apple', 'banana', 'coconut', 'dragon fruit'],
label='Fruits'
)
print(dbutils.widgets.get("fruits_combobox"))
# banana
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"
dbutils.widgets.combobox(
"fruits_combobox",
"banana",
Array("apple", "banana", "coconut", "dragon fruit"),
"Fruits"
)
print(dbutils.widgets.get("fruits_combobox"))
// banana
CREATE WIDGET COMBOBOX fruits_combobox DEFAULT "banana" CHOICES SELECT * FROM (VALUES ("apple"), ("banana"), ("coconut"), ("dragon fruit"))
SELECT :fruits_combobox
-- banana
使用指定的编程名称、默认值、选项和可选标签创建并显示一个 dropdown 小组件。
要显示此命令的相关帮助，请运行 dbutils.widgets.help("dropdown")。
此示例创建并显示编程名称为 toys_dropdown 的 dropdown 小组件。 它提供了 alphabet blocks、basketball、cape 和 doll 选项并设置为初始值 basketball。 此 dropdown 小组件包含一个随附的标签 Toys。 此示例以打印 dropdown 小组件的初始值 basketball 结束。
dbutils.widgets.dropdown(
name='toys_dropdown',
defaultValue='basketball',
choices=['alphabet blocks', 'basketball', 'cape', 'doll'],
label='Toys'
)
print(dbutils.widgets.get("toys_dropdown"))
# basketball
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"
dbutils.widgets.dropdown(
"toys_dropdown",
"basketball",
Array("alphabet blocks", "basketball", "cape", "doll"),
"Toys"
)
print(dbutils.widgets.get("toys_dropdown"))
// basketball
CREATE WIDGET DROPDOWN toys_dropdown DEFAULT "basketball" CHOICES SELECT * FROM (VALUES ("alphabet blocks"), ("basketball"), ("cape"), ("doll"))
SELECT :toys_dropdown
-- basketball
通过指定编程名称获取小组件的当前值。 此编程名称可以是：
fruits_combobox toys_dropdown。name 或 age。 有关详细信息，请查看作业 UI 中有关笔记本任务参数的内容或作业 API 中触发新作业运行 (POST /jobs/run-now) 操作中 notebook_params 字段的内容。要显示此命令的相关帮助，请运行 dbutils.widgets.help("get")。
此示例获取具有编程名称 fruits_combobox 的小组件的值。
dbutils.widgets.get('fruits_combobox')
# banana
dbutils.widgets.get('fruits_combobox')
# [1] "banana"
dbutils.widgets.get("fruits_combobox")
// res6: String = banana
SELECT :fruits_combobox
-- banana
此示例获取具有编程名称 age 的笔记本任务参数的值。 当相关笔记本任务运行时，此参数设置为 35。
dbutils.widgets.get('age')
# 35
dbutils.widgets.get('age')
# [1] "35"
dbutils.widgets.get("age")
// res6: String = 35
SELECT :age
-- 35
获取所有当前小组件名称和值的映射。 这对于快速将小组件值传递到 spark.sql() 查询尤其有用。
此命令在 Databricks Runtime 13.3 LTS 及更高版本中可用。 此命令可用于 Python 和 Scala。
要显示此命令的相关帮助，请运行 dbutils.widgets.help("getAll")。
此示例获取小组件值的映射，并将其作为参数的参数传递到 Spark SQL 查询中。
df = spark.sql("SELECT * FROM table where col1 = :param", dbutils.widgets.getAll())
df.show()
# Query output
val df = spark.sql("SELECT * FROM table where col1 = :param", dbutils.widgets.getAll())
df.show()
// res6: Query output
通过指定编程名称获取小组件的当前值。 如果小组件不存在，则可以返回可选消息。
备注
此命令已弃用。 请改用 dbutils.widgets.get。
要显示此命令的相关帮助，请运行 dbutils.widgets.help("getArgument")。
此示例获取具有编程名称 fruits_combobox 的小组件的值。 如果此小组件不存在，则返回消息 Error: Cannot find fruits combobox。
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'
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"
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.help("multiselect")。
此示例创建并显示编程名称为 days_multiselect 的 multiselect 小组件。 它通过 Sunday 提供了 Monday 选项并设置为初始值 Tuesday。 此 multiselect 小组件具有随附的标签 Days of the Week。 此示例以打印 multiselect 小组件的初始值 Tuesday 结束。
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
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"
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
CREATE WIDGET MULTISELECT days_multiselect DEFAULT "Tuesday" CHOICES SELECT * FROM (VALUES ("Monday"), ("Tuesday"), ("Wednesday"), ("Thursday"), ("Friday"), ("Saturday"), ("Sunday"))
SELECT :days_multiselect
-- Tuesday
删除具有指定编程名称的小组件。
要显示此命令的相关帮助，请运行 dbutils.widgets.help("remove")。
重要
如果添加了命令来删除小组件，则之后不能在同一单元格中再添加命令来创建小组件。 必须在另一个单元格中创建小组件。
此示例将删除编程名称为 fruits_combobox 的小组件。
dbutils.widgets.remove('fruits_combobox')
dbutils.widgets.remove('fruits_combobox')
dbutils.widgets.remove("fruits_combobox")
REMOVE WIDGET fruits_combobox
从笔记本中删除所有小组件。
要显示此命令的相关帮助，请运行 dbutils.widgets.help("removeAll")。
重要
如果添加了命令来删除小组件，则之后不能在同一单元格中再添加命令来创建任何小组件。 必须在另一个单元格中创建小组件。
此示例从笔记本中删除所有小组件。
dbutils.widgets.removeAll()
dbutils.widgets.removeAll()
dbutils.widgets.removeAll()
创建并显示具有指定编程名称、默认值和可选标签的 text 小组件。
要显示此命令的相关帮助，请运行 dbutils.widgets.help("text")。
此示例创建并显示编程名称为 your_name_text 的 text 小组件。 此值设置为初始值 Enter your name。 此 text 小组件包含一个随附的标签 Your name。 此示例以打印 text 小组件的初始值 Enter your name 结束。
dbutils.widgets.text(
name='your_name_text',
defaultValue='Enter your name',
label='Your name'
)
print(dbutils.widgets.get("your_name_text"))
# Enter your name
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"
dbutils.widgets.text(
"your_name_text",
"Enter your name",
"Your name"
)
print(dbutils.widgets.get("your_name_text"))
// Enter your name
CREATE WIDGET TEXT your_name_text DEFAULT "Enter your name"
SELECT :your_name_text
-- Enter your name
重要
Databricks 实用工具 API (dbutils-api) 库已弃用。 尽管仍提供此库，但 Databricks 没有计划为 dbutils-api 库提供新功能。
Databricks 建议改用以下库之一：
为了加快应用程序开发，可以在将应用程序部署为生产作业之前对其进行编译、构建和测试。 为了让你能够针对 Databricks 实用工具进行编译，Databricks 提供了 dbutils-api 库。 可以从 Maven Repository 网站上的 DBUtils API 网页下载 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）。 有关可用目标和版本的列表，请参阅 Maven Repository 网站上的 DBUtils API 网页。
针对此库生成应用程序后，即可部署该应用程序。
重要
该 dbutils-api 库仅允许你在本地编译使用 dbutils的应用程序，而不是运行它。 若要运行该应用程序，必须将其部署到 Azure Databricks 中。
在执行程序内调用 dbutils 可能会产生意外的结果或可能导致错误。
如果需要使用dbutils对执行程序运行文件系统操作，请参阅在 Databricks 中使用 Spark 的并行列表和删除方法。
有关执行器的信息，请参阅 Apache Spark 网站上的集群模式概述。
文档
在 Azure Databricks 上处理文件 - Azure Databricks
了解在 Azure Databricks 上使用文件的选项。
了解如何使用 Azure Databricks 机密来存储凭据，以通过 JDBC 对外部数据源进行身份验证。
Databricks 作业的监视和可观测性 - Azure Databricks
了解 Azure Databricks 中的作业和任务监视和可观测性工具。