在 Databricks 笔记本中开发代码

本页介绍如何在 Databricks 笔记本中开发代码，包括代码格式设置、自动完成、混合语言和 magic 命令。

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

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

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

重要

笔记本必须附加到活动计算会话，以获取代码帮助功能，包括自动完成、Python代码格式设置和调试器。

将代码模块化

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

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

格式化代码单元格

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

Python黑色格式化程序库

重要

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

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

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

在 Databricks Runtime 10.4 LTS 及更低版本上，必须在笔记本或群集上安装 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 使用自定义 SQL 格式化程序对 SQL 和 black 代码格式化程序格式化 Python 代码。

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

  • 设置单个单元格的格式

    • 键盘快捷方式：按 Cmd+Shift+F。
    • 命令上下文菜单：
      • 设置 SQL 单元格的格式：在 SQL 单元格的命令上下文下拉菜单中选择“设置 SQL 格式”。 此菜单项仅在 SQL 笔记本单元格和具有 %sql语言 magic 的单元格中可见。
      • 设置Python单元格的格式：在Python单元格的命令上下文下拉菜单中选择Format Python。 此菜单项仅在 Python 笔记本单元或包含 %pythonlanguage magic 的单元格中可见。
    • Notebook Edit 菜单：选择Python或 SQL 单元格，然后选择 Edit > Format Cell（s）。

  • 设置多个单元格的格式

    选择多个单元格，然后选择“编辑”>“设置单元格格式”。 如果选择包含多种语言的单元格，则只有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 autocomplete，例如在 spark.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 结果数据帧

重要

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

Python

new_dataframe_name = _sqldf

SQL

ALTER VIEW _sqldf RENAME TO new_dataframe_name

并行运行 SQL 单元格

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

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

  1. 运行该单元格。

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

    以与当前运行的单元格并行的方式运行 SQL 单元格。

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

在 SQL 仓库上运行 SQL 单元格

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

使用魔术命令

Databricks 笔记本支持各种 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包（在笔记本范围内）。 请参阅 Notebook 范围内的 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")		 跳过单元格执行。 防止单元格在执行笔记本时运行。
%%profile %%profile
my_function()		 分析Python代码执行。 显示具有计时信息的分层调用树。 需要 Databricks Runtime 17.2 及更高版本。
%%oprofile %%oprofile
my_function()		 在单元格执行期间创建配置文件对象。 显示创建、按类型分组的净新对象的表。 需要 Databricks Runtime 17.2 及更高版本。

注意

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

重要

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