在 Databricks 笔记本中开发代码

本页介绍如何在 Databricks 笔记本中开发代码，包括自动完成、Python 和 SQL 的自动格式设置、在笔记本中组合使用 Python 和 SQL，以及跟踪笔记本版本历史记录。

有关编辑器提供的高级功能（例如自动完成、变量选择、多光标支持和并列比较）的更多详细信息，请参阅浏览 Databricks 笔记本和文件编辑器。

使用笔记本或文件编辑器时，Databricks 助手可用于帮助生成、解释和调试代码。 有关详细信息，请参阅使用 Databricks 助手。

Databricks 笔记本还包括适用于 Python 笔记本的内置交互式调试程序。 请参阅调试笔记本。

将代码模块化

使用 Databricks Runtime 11.3 LTS 及更高版本，可以在 Azure Databricks 工作区中创建和管理源代码文件，然后根据需要将这些文件导入到笔记本中。

有关使用源代码文件的详细信息，请参阅在 Databricks 笔记本之间共享代码和使用 Python 和 R 模块。

格式化代码单元格

Azure Databricks 提供的工具可用于在笔记本单元格中快速且轻松地设置 Python 和 SQL 代码的格式。 这些工具减少了保持代码格式化的工作量，有助于在笔记本中强制实施一致的编码标准。

Python black 格式化程序库

重要

此功能目前以公共预览版提供。

Azure Databricks 支持在笔记本中使用 black 的 Python 代码格式设置。 笔记本必须附加到安装了 black 和 tokenize-rt Python 包的群集。

在 Databricks Runtime 11.3 LTS 及更高版本上，Azure Databricks 将预安装 black 和 tokenize-rt。 可以直接使用格式化程序，而无需安装这些库。

在 Databricks Runtime 10.4 LTS 及更低版本上，必须在笔记本或群集上通过 PyPI 安装 black==22.3.0 和 tokenize-rt==4.2.1 才能使用 Python 格式化程序。 可以在笔记本中运行以下命令：

%pip install black==22.3.0 tokenize-rt==4.2.1

或在群集上安装库。

有关安装库的更多详细信息，请参阅 Python 环境管理。

对于 Databricks Git 文件夹中的文件和笔记本，可根据 pyproject.toml 文件配置 Python 格式化程序。 若要使用此功能，请在 Git 文件夹根目录中创建一个 pyproject.toml 文件，并根据 Black 配置格式对其进行配置。 编辑文件中的 [tool.black] 部分。 当格式化该 Git 文件夹中的任何文件和笔记本时，将应用该配置。

如何设置 Python 和 SQL 单元格的格式

必须拥有笔记本“可编辑”权限，才能设置代码的格式。

Azure Databricks 使用 Gethue/sql-formatter 库来设置 SQL 格式，并使用适用于 Python 的 black 代码格式化程序。

可通过以下方式触发格式化程序：

• 设置单个单元格的格式

  • 键盘快捷方式：按 Cmd+Shift+F。
  • 命令上下文菜单：
    • 设置 SQL 单元格的格式：在 SQL 单元格的命令上下文下拉菜单中选择“设置 SQL 格式”。 此菜单项仅在 SQL 笔记本单元格和具有 %sql语言 magic 的单元格中可见。
    • 设置 Python 单元格的格式：在 Python 单元格的命令上下文下拉菜单中选择“设置 Python 格式”。 此菜单项仅在 Python 笔记本单元格和具有 %python语言 magic 的单元格中可见。
  • 笔记本编辑菜单：选择一个 Python 或 SQL 单元格，然后选择编辑>设置单元格格式。

• 设置多个单元格的格式

  选择多个单元格，然后选择“编辑”>“设置单元格格式”。 如果选择多个语言的单元格，则仅会设置 SQL 和 Python 单元格的格式。 这包括那些使用 %sql 和 %python 的。

• 设置笔记本中所有 Python 和 SQL 单元格的格式

  选择“编辑”>“设置笔记本格式”。 如果笔记本包含多种语言，则只会设置 SQL 和 Python 单元格的格式。 这包括那些使用 %sql 和 %python 的。

若要自定义 SQL 查询的格式设置方式，请参阅 自定义格式 SQL 语句。

代码格式设置的限制

• Black 对 4 空格缩进强制执行 PEP 8 标准。 缩进不可配置。
• 不支持设置 SQL UDF 中嵌入的 Python 字符串的格式。 同样，不支持设置 Python UDF 中 SQL 字符串的格式。

笔记本中的代码语言

设置默认语言

笔记本的默认语言显示在笔记本名称下方。

要更改默认语言，请单击语言按钮并从下拉菜单中选择新语言。 为确保现有命令可继续正常工作，以前的默认语言的命令会自动带有语言 magic 命令前缀。

混合语言

默认情况下，单元格使用笔记本的默认语言。 通过单击语言按钮并从下拉菜单中选择一种语言，可以替代单元格中的默认语言。

也可在单元格开头使用语言 magic 命令 %<language>。 支持的 magic 命令为：%python、%r、%scala 和 %sql。

注意

调用语言 magic 命令时，该命令会被调度到笔记本的执行上下文中的 REPL。 用一种语言定义（并且因此位于该语言的 REPL 中）的变量在其他语言的 REPL 中不可用。 REPL 只能通过外部资源（例如 DBFS 中的文件或对象存储中的对象）共享状态。

笔记本还支持几个辅助的魔法命令：

• %sh：允许你在笔记本中运行 shell 代码。 若要在 shell 命令的退出状态为非零值的情况下使单元格发生失败，请添加 -e 选项。 此命令仅在 Apache Spark 驱动程序上运行，不在工作器上运行。 若要在所有节点上运行 shell 命令，请使用初始化脚本。
• %fs：允许你使用 dbutils 文件系统命令。 例如，如需运行 dbutils.fs.ls 命令以列出文件，可以改为指定 %fs ls。 有关详细信息，请参阅在 Azure Databricks 上处理文件。
• %md：允许你包括各种类型的文档，例如文本、图像以及数学公式和等式。 请参阅下一部分。

Python 命令中的 SQL 语法突出显示和自动完成

当你在 Python 命令（例如在 命令中）中使用 SQL 时，语法突出显示和 SQL 自动补全功能是可用的。

浏览 SQL 单元格结果

在 Databricks 笔记本中，SQL 语言单元格的结果会自动作为分配给变量 _sqldf的隐式 DataFrame 提供。 然后，可以在之后运行的任何 Python 和 SQL 单元格中使用此变量，而不考虑它们在笔记本中的位置。

注意

此功能具有以下限制：

• _sqldf 变量在使用 SQL 仓库进行计算的笔记本中不可用。
• 在 Databricks Runtime 13.3 及更高版本中支持在后续的 Python 单元格中使用 _sqldf。
• _sqldf仅在 Databricks Runtime 14.3 及更高版本上支持在后续 SQL 单元中使用。
• 如果查询使用关键字CACHE TABLE或UNCACHE TABLE_sqldf变量不可用。

以下屏幕截图显示如何在后续的 Python 和 SQL 单元格中使用 _sqldf:

重要

每次运行 SQL 单元格时，都会重新分配变量 _sqldf 。 若要避免丢失对特定 DataFrame 结果的引用，请在运行下一个 SQL 单元格之前将其分配给新的变量名称：

Python

new_dataframe_name = _sqldf

SQL

ALTER VIEW _sqldf RENAME TO new_dataframe_name

并行执行 SQL 单元格

当某个命令正在运行且你的笔记本已附加到交互式群集时，可以将 SQL 单元格与当前命令同时运行。 SQL 单元格在新的并行会话中执行。

若要并行执行某个单元格，请执行以下操作：

1. 运行该单元格。

2. 单击“立即运行”。 此时会立即执行该单元格。

   

由于单元格在新会话中运行，因此并行执行的单元格不支持临时视图、UDF 和隐式 Python 数据帧 (_sqldf)。 此外，在并行执行期间将使用默认目录和数据库名称。 如果代码引用不同目录或数据库中的表，则你必须使用三级命名空间 (catalog.schema.table) 来指定表名。

在 SQL 仓库上执行 SQL 单元格

可以在 SQL 仓库上的 Databricks 笔记本中运行 SQL 命令，这是一种针对 SQL 分析优化的计算类型。 请参阅将笔记本与 SQL 仓库配合使用。

在无服务器计算环境中由助手运行代码

可以在无服务器计算上的 Databricks 助手中运行代码，这是 Databricks 的默认计算。 对于已选择计算的页面（例如笔记本或 SQL 编辑器），Databricks 会默认使用该计算。 有关计算类型的信息，请参阅 “计算”。

如果你无权访问无服务器计算，则必须有一个计算实例可用于在助手面板中运行代码。

使用魔术命令

Databricks 笔记本支持各种 magic 命令，这些命令将功能扩展到标准语法之外，以简化常见任务。 Magic 命令中的行魔法和单元格魔法命令使用 % 作为前缀。

魔法命令	示例	说明
%python	%python print("Hello")	将单元格编程语言切换到 Python。 在单元格中执行 Python 代码。
%r	%r print("Hello")	将单元格语言切换到 R。在单元格中执行 R 代码。
%scala	%scala println("Hello")	将单元格语言切换到 Scala。 在单元格中执行 Scala 代码。
%sql	%sql SELECT * FROM table	将单元格语言切换到 SQL。 在 Python/SQL 单元格中，结果以 _sqldf 形式提供。
%md	%md # Title Content here	将单元格语言切换到 Markdown。 呈现单元格中的 Markdown 内容。 支持文本、图像、公式和 LaTeX。
%pip	%pip install pandas	安装 Python 包（笔记本范围内）。 请参阅笔记本范围的 Python 库。
%run	%run /path/to/notebook	执行另一个笔记本，导入其函数和变量。 请参阅 Notebook 工作流。
%fs	%fs ls /path	执行 dbutils 文件系统命令。 dbutils.fs 命令的速记。 请参阅 “使用文件”。
%sh	%sh ls -la	执行 shell 命令。 仅在驱动程序节点上运行。 使用 -e 在出错时失败。
%tensorboard	%tensorboard --logdir /logs	内联显示 TensorBoard UI。 仅适用于 Databricks Runtime ML。 请参阅 TensorBoard。
%set_cell_max_output_size_in_mb	%set_cell_max_output_size_in_mb 10	设置最大单元格输出大小。 范围：1-20 MB。 适用于笔记本中的所有后续单元格。
%skip	%skip print("This won't run")	跳过单元格执行。 防止单元格在执行笔记本时运行。

注意

IPython Automagic：默认情况下，Databricks 笔记本已启用 IPython automagic，允许某些指令在没有 pip 和 % 前缀的情况下工作。 例如，pip install pandas 的工作方式与 %pip install pandas 相同。

重要

• 变量和状态在不同的语言 REPL 之间隔离。 例如，在 Scala 单元格中无法访问 Python 变量。
• 笔记本单元格只能有一个单元格魔术命令，并且它必须是单元格的第一行。
• %run 必须单独位于单元格中，因为它以内联方式运行整个笔记本。
• 在 Databricks Runtime 12.2 LTS 及更低版本上使用 %pip 时，将所有包安装命令放在笔记本的开头，因为安装后将重置 Python 状态。