Databricks 实用工具

• 03/17/2021
• • m
  • D

使用 Databricks 实用工具 (DBUtils) 可以轻松地执行各种强大的任务组合。 可以使用这些实用工具来有效地处理对象存储，对笔记本进行链接和参数化，以及处理机密。 对 DBUtils 的支持仅限于笔记本内。

所有 dbutils 实用工具均在 Python、R 和 Scala 笔记本中提供。

文件系统实用工具

文件系统实用工具会访问 Databricks 文件系统 (DBFS)，让你可以更轻松地将 Azure Databricks 用作文件系统。 有关详细信息，请运行：

dbutils.fs.help()

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

dbutils.fs.ls 命令

ls 命令返回的序列包含以下属性：

例如： 。

Python

dbutils.fs.ls("/databricks-datasets/adult")
dbutils.fs.head("/databricks-datasets/adult/adult.data")

R

dbutils.fs.ls("/databricks-datasets/")
dbutils.fs.head("/databricks-datasets/Rdatasets/data-001/datasets.csv")

Scala

dbutils.fs.ls("/databricks-datasets/adult")
dbutils.fs.head("/databricks-datasets/adult/adult.data")

笔记本工作流实用工具

可以通过笔记本工作流将笔记本链接在一起，并对其结果进行操作。 请参阅笔记本工作流。 有关详细信息，请运行：

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

机密实用工具

可以利用机密存储和访问敏感的凭据信息，而无需使其在笔记本中可见。 请参阅机密管理和在笔记本中使用机密。 有关详细信息，请运行：

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

库实用工具

可以通过库实用工具安装 Python 库并创建作用域为笔记本会话的环境。 这些库在驱动程序和执行程序上均可用，因此你可以在 UDF 中引用它们。 这样做可以实现以下操作：

• 在笔记本自身中组织笔记本的库依赖项。
• 具有不同库依赖项的笔记本用户共享群集而不受干扰。

分离笔记本会破坏此环境。 但是，你可以重新创建它，只需在笔记本中重新运行库 install API 命令即可。 请参阅 restartPython API，了解如何才能重置笔记本状态而不失去环境。

默认情况下，库实用工具处于启用状态。 因此，默认情况下会通过使用单独的 Python 可执行文件隔离每个笔记本的 Python 环境，该可执行文件在笔记本附加到群集并继承群集上的默认 Python 环境时创建。 通过 init script 安装到 Azure Databricks Python 环境中的库仍可用。 可以通过将 spark.databricks.libraryIsolation.enabled 设置为 false 来禁用此功能。

此 API 与通过 UI 和 REST API 进行的群集范围的现有库安装兼容。 通过此 API 安装的库的优先级高于群集范围的库。

dbutils.library.help()

install(path: String): boolean -> Install the library within the current notebook session
installPyPI(pypiPackage: String, version: String = "", repo: String = "", extras: String = ""): boolean -> Install the PyPI library within the current notebook session
list: List -> List the isolated libraries added for the current notebook session via dbutils
restartPython: void -> Restart python process for the current notebook session

示例

• 在笔记本中安装 PyPI 库。 version、repo 和 extras 是可选的。 使用 extras 参数可指定额外功能（额外要求）。

  dbutils.library.installPyPI("pypipackage", version="version", repo="repo", extras="extras")
  dbutils.library.restartPython()  # Removes Python state, but some libraries might not work without calling this function
  

  重要

  version 和 extras 键不能是 PyPI 包字符串的一部分。 例如，dbutils.library.installPyPI("azureml-sdk[databricks]==1.19.0") 无效。 请使用 version 和 extras 参数指定版本和额外信息，如下所示：

  dbutils.library.installPyPI("azureml-sdk", version="1.19.0", extras="databricks")
  dbutils.library.restartPython()  # Removes Python state, but some libraries might not work without calling this function
  

  备注

  将 dbutils.library.installPyPI 命令替换为 %pip 命令时，Python 解释器将自动重启。 可以按以下方式运行安装命令：

  %pip install azureml-sdk[databricks]==1.19.0
  

• 在一个笔记本中指定库要求，然后通过 %run 在另一个笔记本中安装它们。

  • 定义要在名为 InstallDependencies 的笔记本中安装的库。

    dbutils.library.installPyPI("torch")
    dbutils.library.installPyPI("scikit-learn", version="1.19.1")
    dbutils.library.installPyPI("azureml-sdk", extras="databricks")
    dbutils.library.restartPython()  # Removes Python state, but some libraries might not work without calling this function
    

  • 将它们安装在需要这些依赖项的笔记本中。

    %run /path/to/InstallDependencies    # Install the dependencies in first cell
    

    import torch
    from sklearn.linear_model import LinearRegression
    import azureml
    # do the actual work
    

• 列出笔记本中已安装的库。

  dbutils.library.list()
  

  备注

  使用 %pip 的此命令的等效项是：

  %pip freeze
  

• 在维护环境时重置 Python 笔记本状态。 此 API 仅在 Python 笔记本中可用。 这可用于：

  • 重新加载 Azure Databricks 预安装的其他版本的库。 例如：

    dbutils.library.installPyPI("numpy", version="1.15.4")
    dbutils.library.restartPython()
    

    # Make sure you start using the library in another cell.
    import numpy
    

  • 安装需要在进程启动时加载的库，例如 tensorflow。 例如：

    dbutils.library.installPyPI("tensorflow")
    dbutils.library.restartPython()
    

    # Use the library in another cell.
    import tensorflow
    

• 在笔记本中安装 .egg 或 .whl 库。

  重要

  Databricks 建议将所有库安装命令放入笔记本的第一个单元，在该单元的末尾调用 restartPython。 在运行 restartPython 后会重置 Python 笔记本状态；笔记本会丢失所有状态，包括但不限于本地变量、导入的库和其他临时状态。 因此，建议在第一个笔记本单元中安装库并重置笔记本状态。

  接受的库源是 dbfs、abfss、adl 和 wasbs。

  dbutils.library.install("abfss:/path/to/your/library.egg")
  dbutils.library.restartPython()  # Removes Python state, but some libraries might not work without calling this function
  

  dbutils.library.install("abfss:/path/to/your/library.whl")
  dbutils.library.restartPython()  # Removes Python state, but some libraries might not work without calling this function
  

  备注

  可以使用 %pip 直接安装自定义 wheel 文件。 在以下示例中，我们假设你已将库 wheel 文件上传到 DBFS：

  %pip install /dbfs/path/to/your/library.whl
  

  pip 不支持 Egg 文件，而 wheel 被认为是 Python 构建和二进制打包的标准。 有关更多详细信息，请参阅 Wheel 和 Egg。 但是，如果想要以与 %pip 兼容的方式使用 egg 文件，则可以使用以下解决方法：

  # This step is only needed if no %pip commands have been executed yet.
  # It will trigger setting up the isolated notebook environment
  %pip install <any-lib>  # This doesn't need to be a real lib, eg - "%pip install foo" would work
  

  import sys
  # Assuming the preceding step was completed, the following command
  # adds the egg file to the current notebook environment
  sys.path.append("/local/path/to/library.egg")
  

DBUtils 笔记本

获取笔记本

Databricks 实用工具 API 库

为了加快应用程序开发，可以在将应用程序部署为生产作业之前对其进行编译、构建和测试。 为了让你能够针对 Databricks 实用工具进行编译，Databricks 提供了 dbutils-api 库。 可以下载 dbutils-api 库，也可以通过将依赖项添加到生成文件来包含库：

• SBT

  libraryDependencies += "com.databricks" % "dbutils-api_2.11" % "0.0.4"
  

• Maven

  <dependency>
      <groupId>com.databricks</groupId>
      <artifactId>dbutils-api_2.11</artifactId>
      <version>0.0.4</version>
  </dependency>
  

• Gradle

  compile 'com.databricks:dbutils-api_2.11:0.0.4'
  

针对此库生成应用程序后，即可部署该应用程序。

使用 %% 表示生成工件的 Scala 版本

如果将生成工件版本表示为 groupID %% artifactID % revision 而不是 groupID % artifactID % revision（区别在于 groupID 后面的双 %%），则 SBT 会将项目的 Scala 版本添加到生成工件名称中。

示例

假设你的生成的 scalaVersion 为 2.9.1。 可以使用 % 编写生成工件版本，如下所示：

val appDependencies = Seq(
  "org.scala-tools" % "scala-stm_2.9.1" % "0.3"
)

下面这个使用 %% 的语句是等效的：

val appDependencies = Seq(
  "org.scala-tools" %% "scala-stm" % "0.3"
)

示例项目

下面是一个示例存档，其中包含最小的示例项目，用于演示如何使用适用于 3 个常用生成工具的 dbutils-api 库进行编译：

• sbt：sbt package
• Maven：mvn install
• Gradle：gradle build

这些命令在以下位置创建输出 JAR：

• sbt：target/scala-2.11/dbutils-api-example_2.11-0.0.1-SNAPSHOT.jar
• Maven：target/dbutils-api-example-0.0.1-SNAPSHOT.jar
• Gradle：build/examples/dbutils-api-example-0.0.1-SNAPSHOT.jar

可以将此 JAR 作为库附加到群集，重启群集，然后运行以下语句：

example.Test()

此语句创建一个文本输入小组件，其标签为 Hello:，初始值为 World。

可以通过相同的方式使用所有其他 dbutils API。

若要测试某个在 Databricks 外部使用 dbutils 对象的应用程序，可以通过调用以下语句来模拟 dbutils 对象：

com.databricks.dbutils_v1.DBUtilsHolder.dbutils0.set(
  new com.databricks.dbutils_v1.DBUtilsV1{
    ...
  }
)

请使用你自己的 DBUtilsV1 实例进行替换。在该实例中，你可以随意实现接口方法，例如，为 dbutils.fs 提供本地文件系统原型。