使用笔记本

笔记本是可运行的单元格(命令)的集合。 使用笔记本时,你主要是在开发和运行单元格。

UI 操作支持所有笔记本任务,但你也可以使用键盘快捷方式执行许多任务。 通过单击键盘图标图标来 切换快捷方式 显示。

开发笔记本

本部分介绍如何开发笔记本单元格并在笔记本中导航。

本节内容:

关于笔记本

笔记本包含一个工具栏,用于在笔记本中管理笔记本和执行操作:

笔记本工具栏

此外还有一个或多个单元格(或命令),可以用来运行:

笔记本单元格

在单元格最右侧,单元格操作 单元格操作包含三个菜单:"运行"、"仪表板"和"编辑":

运行图标 - 仪表板 - 编辑

和两个操作:隐藏 单元格最小化和 删除 删除图标

添加单元格

若要添加单元格,将鼠标悬停在顶部或底部的单元格上,然后单击"添加单元格"图标,或访问最右边的笔记本单元格菜单,单击"向下移植",然后选择"添加上方的单元格"或"在 下方添加单元格"。

删除单元格

转到最右侧单元格 操作菜单单元格 操作,然后单击"删除图标 ) 。

删除单元格时,默认情况下会显示一个用于确认删除操作的对话框。 若要禁用未来的确认对话框,请选中“不再显示此对话框”复选框,然后单击“确认”。 还可以在"用户"图标"用户"和"笔记本"设置"中,使用"打开命令删除"确认选项 设置 User Settings Icon 确认设置。

若要还原已删除的单元格,请选择" 编辑 撤消 删除单元格",或使用 () Z 快捷方式。

剪切单元格

转到最右侧单元格操作菜单单元格操作",单击"向下移植",然后选择"剪切单元格"。

还可以使用 (X) 键盘快捷方式。

若要还原已删除的单元格,请选择" 编辑 撤消 剪切单元格",或使用键盘 () Z 单元格。

选择多个单元格或所有单元格

可以分别对上一个单元格和下一个单元格使用"上移"或"下移"来 选择相邻的笔记本单元格。 可以复制、剪切、删除和粘贴多选的单元格。

若要选择所有单元格,请选择"编辑 ""选择所有单元格 "或使用命令模式快捷方式 Cmd+A

默认语言

笔记本的默认语言由笔记本名称旁边的按钮指示。 在以下笔记本中,默认语言为 SQL。

笔记本默认语言

若要更改默认语言,请执行以下操作:

  1. 单击语言按钮。 此时会显示“更改默认语言”对话框。

    更改默认语言

  2. 从“默认语言”下拉列表中选择新语言。

  3. 单击“更改”

  4. 为确保现有命令可继续正常工作,以前的默认语言的命令会自动带有语言 magic 命令前缀。

混合语言

默认情况下,单元格使用笔记本的默认语言。 可以通过单击语言按钮,然后从下拉列表中选择一种语言来替代单元格中的默认语言。

单元格语言下拉列表

或者,可以在单元格的开头使用语言 magic %<language> 命令。 支持的 magic 命令包括 %python%r%scala :、、 和 %sql

注意

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

笔记本还支持几个辅助 magic 命令:

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

包括文档

若要在笔记本中包括文档,可以通过从单元格的语言按钮或 magic 命令中选择 Markdown 来创建 Markdown 单元格。 单元格的内容将呈现为 HTML。 例如,此代码片段包含一级标题的标记:

%md # Hello This is a Title

它会呈现为 HTML 标题:

笔记本 HTML 标题

可折叠的标题

在包含 Markdown 标题的单元格后显示的单元格可以折叠到标题单元格中。 下图显示了名为“标题 1”的一级标题,后面的两个单元格已折叠到其中。

折叠的单元格

若要展开和折叠标题,请单击 +-

另请参阅隐藏和显示单元格内容

要在整个笔记本中扩展或折叠包含 Markdown 标题的单元格,请从“视图”菜单选择“展开所有标题”或“折叠所有标题” 。

在视图菜单中展开-折叠所有内容

可以使用相对路径链接到 Markdown 单元格中的其他笔记本或文件夹。 将定位点标记的 href 属性指定为相对路径(以 $ 开头),然后遵循与 Unix 文件系统中的模式相同的模式:

%md
<a href="$./myNotebook">Link to notebook in same folder as current notebook</a>
<a href="$../myFolder">Link to folder in parent folder of current notebook</a>
<a href="$./myFolder2/myNotebook2">Link to nested notebook</a>

显示图像

若要显示在 FileStore 中存储的图像,请使用以下语法:

%md
![test](files/image.png)

例如,假设你在 FileStore 中有 Databricks 徽标图像文件:

dbfs ls dbfs:/FileStore/
databricks-logo-mobile.png

在 Markdown 单元格中包括以下代码时:

Markdown 单元中的图像

图像会呈现在单元格中:

呈现的图像

显示数学等式

笔记本支持 KaTeX,用于显示数学公式和等式。 例如,

%md
\\(c = \\pm\\sqrt{a^2 + b^2} \\)

\\(A{_i}{_j}=B{_i}{_j}\\)

$$c = \\pm\\sqrt{a^2 + b^2}$$

\\[A{_i}{_j}=B{_i}{_j}\\]

呈现为:

呈现的公式1

and

%md
\\( f(\beta)= -Y_t^T X_t \beta + \sum log( 1+{e}^{X_t\bullet\beta}) + \frac{1}{2}\delta^t S_t^{-1}\delta\\)

where \\(\delta=(\beta - \mu_{t-1})\\)

呈现为:

呈现的公式2

包括 HTML

可以使用函数 displayHTML 在笔记本中包括 HTML。 请参阅笔记本中的 HTML、D3 和 SVG,通过示例来了解如何执行此操作。

注意

displayHTML iframe 是从域 databricksusercontent.com 提供的,iframe 沙盒包含 allow-same-origin 属性。 必须可在浏览器中访问 databricksusercontent.com。 如果它当前被企业网络阻止,则必须将其添加到允许列表。

命令注释

你可以使用命令注释与协作者进行讨论。

若要切换“注释”边栏,请单击笔记本右上方的“注释”按钮。

切换笔记本评论

若要向命令添加注释,请执行以下操作:

  1. 突出显示命令文本,然后单击注释气泡:

    打开注释

  2. 添加你的注释,然后单击“注释”。

    添加 commenty

若要编辑、删除或回复某项注释,请单击该注释并选择一项操作。

编辑注释

更改单元格显示

笔记本有三个显示选项:

  • 标准视图:结果紧跟在代码单元格之后显示
  • 仅显示结果:只显示结果
  • 并排显示:代码和结果单元格并排显示,结果显示在右侧

请在 "视图" 菜单的 " 视图 中选择 "显示" 选项。

并行视图

显示行号和命令号

若要显示行号或命令编号,请在 "视图" 菜单的 " 视图 中选择 " 显示行号 " 或 " 显示命令号"。 在它们显示后,你可以在同一菜单中再次隐藏它们。 你还可以使用键盘快捷方式 Control+L 来启用行号。

通过

笔记本中启用的行和命令号

如果启用行号或命令号,Databricks 会保存你的首选项,并在该浏览器的所有其他笔记本中显示它们。

单元格上方的命令号会链接到该特定命令。 如果单击某个单元格的命令号,则会更新 URL,使之定位到该命令。 如果要链接到笔记本中的特定命令,请右键单击命令号,然后选择“复制链接地址”。

查找和替换文本

若要查找和替换笔记本中的文本,请选择 " 编辑 查找和替换"。 当前的匹配项以橙色突出显示,所有其他的匹配项以黄色突出显示。

匹配文本

若要替换当前匹配项,请单击“替换”。 若要替换笔记本中的所有匹配项,请单击“全部替换”。

若要在匹配项之间移动,请单击“上一个”和“下一个”按钮 。 还可以按“Shift+Enter”和“Enter”,分别转到上一个和下一个匹配项 。

若要关闭 "查找和替换" 工具,请单击 " 删除 或按 esc键。

自动完成

可以使用 Azure Databricks 自动完成功能,在单元格中键入代码段时自动完成这些代码段。 Azure Databricks 支持两种类型的自动完成:本地自动完成和服务器自动完成。

本地自动完成会完成笔记本中定义的单词。 服务器自动完成会针对定义的类型、类和对象以及 SQL 数据库和表名称访问群集。 若要激活服务器自动完成功能,请将笔记本附加到群集运行所有单元格,以便定义可完成的对象。

重要

在执行命令的过程中,会阻止 R 笔记本中的服务器自动完成功能。

若要触发自动完成,请在输入一个可完成的对象后按 Tab 键。 例如,在定义和运行包含和定义的单元格后, MyClassinstance 方法 instance 将 completable,并且当你按 MyClass键时,将显示一个有效的完成列表。

触发器自动完成

类型完成采用的方式与 SQL 数据库和表名称的完成采用的方式相同。

类型完成- SQL 完成

在 Databricks Runtime 7.4 及更高版本中,可以通过在输入可完成 Python 对象后按 Shift+Tab 显示 Python docstring 提示。 docstrings 包含与对象的 help() 函数相同的信息。

Python docstring

设置 SQL 格式

Azure Databricks 提供的工具可用于在笔记本单元格中快速且轻松地设置 SQL 代码的格式。 这些工具减少了使代码带有格式的工作量,有助于在笔记本中强制实施相同的编码标准。

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

  • 单个单元格

    • 键盘快捷方式:按 Cmd+Shift+F

    • 命令上下文菜单:在 SQL 单元格的命令上下文下拉菜单中选择“设置 SQL 格式”。 此项仅在 SQL 笔记本单元和具有 %sql%sql的单元格可见。

      从命令上下文 SQL 设置格式

  • 多个单元格

    选择 "多个 SQL 单元格,然后选择"编辑 SQL 单元格格式"。 如果选择多个语言的单元格,则仅会设置 SQL 单元格的格式。 这包括那些使用 %sql 的单元格。

    从编辑菜单 SQL 设置格式

下面是前面示例中进行格式设置后的第一个单元格:

设置格式后 SQL

查看目录

若要显示自动生成的目录,请单击笔记本左上角的箭头(边栏和最顶部的单元格之间)。 目录是通过笔记本中使用的 Markdown 标题生成的。

打开 TOC

若要关闭目录,请单击左箭头。

关闭 TOC

在深色模式下查看笔记本

你可以选择在深色模式下显示笔记本。 若要打开或关闭暗色模式,请选择 " 查看 笔记本主题 " 并选择 " 浅色主题 " 或 " 深色主题"。

笔记本 light 或暗色模式

运行笔记本

此部分介绍如何运行一个或多个笔记本单元格。

本节内容:

要求

必须将笔记本附加到群集。 如果群集未运行,则会在运行一个或多个单元格时启动该群集。

运行单元格

在最右侧的 "单元格操作 ,单击 "运行" 图标 并选择 " 运行单元",或按 shift + enter

重要

笔记本单元格(内容和输出)的最大大小为 16MB。

例如,尝试运行引用预定义变量的此 Python 代码段 sparkspark

spark

然后,运行一些真实的代码:

1+1 # => 2

注意

笔记本有多个默认设置:

  • 运行某个单元格时,笔记本会自动附加到正在运行的群集,而不会进行提示。
  • Shift+Enter 时,如果该单元格不可见,笔记本会自动滚动到下一个单元格。

若要更改这些设置,请选择 "用户设置图标User Settings Icon 用户设置 笔记本" 设置并配置相应的复选框。

运行上方或下方的所有单元格

若要在单元格之前或之后运行所有单元格,请前往最右侧的单元格操作菜单 单元操作 ,单击 " 运行菜单",然后选择 " 全部运行 " 或 " 全部运行"。

“运行下方的所有单元格”包括你所在的单元格。 “运行上方的所有单元格”不包括你所在的单元格。

运行所有单元格

若要运行笔记本中的所有单元格,请在笔记本工具栏中选择“全部运行”。

重要

如果在同一笔记本中执行装载和卸载步骤,请不要执行“全部运行”。 这可能导致出现争用情况并可能损坏装入点。

查看每个单元格的多个输出

Python 笔记本以及非 Python 笔记本中的 %python 单元格支持每个单元格多个输出。

一个单元格中有多个输出

此功能需要 Databricks Runtime 7.1 或更高版本,并且可以通过设置在 Databricks Runtime 7.1-Databricks Runtime 7.3 中启用 spark.databricks.workspace.multipleResults.enabled true 。 默认情况下,该功能在 Databricks Runtime 7.4 及更高版本中处于启用状态。

Python 和 Scala 错误突出显示

Python 和 Scala 笔记本支持错误突出显示。 也就是说,系统会在单元格中突出显示引发错误的代码行。 此外,如果错误输出为堆栈跟踪,则引发错误的单元格会在堆栈跟踪中显示为指向该单元格的链接。 单击该链接可跳转到有问题的代码。

Python 错误突出显示

Scala 错误突出显示

通知

通知会提醒你某些事件,例如,哪个命令当前正在运行所有单元格阶段运行,哪些命令处于错误状态。 当笔记本显示多个错误通知时,第一个错误通知会有一个用于清除所有通知的链接。

笔记本通知

默认情况下,笔记本通知处于启用状态。 你可以在 "用户设置User Settings Icon 用户设置 笔记本 "设置下禁用它们。

Databricks 顾问

Databricks 顾问会在每次运行命令时自动分析命令,并在笔记本中显示相应的建议。 建议通知所提供的信息可帮助你提高工作负载的性能、降低成本以及避免常见错误。

查看建议

带有灯泡图标的蓝色框表示命令已有建议。 该框会显示不同建议的数目。

Databricks 建议

单击灯泡可展开框并查看建议。 一个或多个建议将变得可见。

查看建议

单击“了解更多”链接可查看相关文档,了解与该建议相关的详细信息。

单击“不再显示此对话框”链接可隐藏该建议。 此类型的建议将不再显示。 此操作可在“笔记本设置”中逆转

再次单击灯泡可折叠建议框。

建议设置

若要访问笔记本设置页面,请选择 "用户设置图标User Settings Icon 用户设置 笔记本" 设置或单击 "展开的建议" 框中的齿轮图标。

笔记本设置

切换“启用 Databricks 顾问”选项可启用或禁用通知。

如果当前隐藏了一个或多个类型的建议,则会显示“重置隐藏的建议”链接。 单击链接可使该建议类型再次可见。

从一个笔记本中运行另一个笔记本

可以通过使用 %run <notebook> magic 命令从一个笔记本中运行另一个笔记本。 这大致相当于本地计算机上的 Scala REPL 中的 :load 命令或 Python 中的 import 语句。 <notebook> 中定义的所有变量都会变得可在当前笔记本中使用。

%run 必须位于单元格内,因为它 %run整个笔记本。

注意

不能 使用 运行 Python 文件和 import 该文件中定义的实体。 若要从 Python 文件导入,必须将文件打包到 Python 库,从该 Python 库创建 Azure Databricks ,然后将库安装到用于运行笔记本的群集

示例

假设你有 notebookAnotebookBnotebookA 包含一个具有以下 Python 代码的单元格:

x = 5

即使你未 x 在中定义 notebookB ,你也可以 x 在运行后在中访问 notebookB%run notebookA

%run /Users/path/to/notebookA

print(x) # => 5

若要指定相对路径,请在其前面加上 ./../。 例如,如果 notebookAnotebookB 在同一目录中,则也可从相对路径运行它们。

%run ./notebookA

print(x) # => 5
%run ../someDirectory/notebookA # up a directory and into another

print(x) # => 5

有关笔记本之间的更复杂的交互,请参阅笔记本工作流

管理笔记本状态和结果

将笔记本附加到群集运行一个或多个单元格后,笔记本就会有状态并会显示结果。 此部分介绍如何管理笔记本状态和结果。

本节内容:

清除笔记本状态和结果

若要清除笔记本状态和结果,请单击笔记本工具栏中的“清除”,然后选择操作:

清除状态和结果

下载结果

默认情况下已启用“下载结果”。 若要切换此设置,请参阅管理从笔记本下载结果的功能。 如果已禁用下载结果,则 按钮不可见。

下载单元格结果

可以将包含表格输出的单元格结果下载到本地计算机。 单击 单元格底部的 "下载结果"按钮。

下载单元格结果

名为 export.csv 的 CSV 文件将下载到默认的下载目录。

下载完整结果

默认情况下,Azure Databricks 返回一个数据帧的 1000 行。 如果超过 1000 行,将显示一个选项以重新运行查询并显示最多 10,000 行。

用于重新运行的选项

当查询返回超过 1000 行时,向下箭头 按钮将添加到 "下载 结果 按钮。 若要下载某个查询的所有结果,请执行以下操作:

  1. 单击"下载结果"旁边的向下箭头,然后选择"下载完整结果"。

    下载完整结果

  2. 选择“重新执行并下载”。

    重新运行并下载结果

    下载完整结果后,名为 export.csv 的 CSV 文件就会下载到本地计算机,此时会在 /databricks-results 文件夹中出现一个生成的文件夹,其中包含完整的查询结果。

    下载的结果

隐藏和显示单元格内容

单元格内容包含单元格代码和运行单元格后的结果。 可以使用单元格右上方的单元格操作菜单"单元格操作"隐藏和显示单元格代码和结果。

若要隐藏单元格代码,请执行以下操作:

  • 单击 然后选择" 隐藏代码"

若要隐藏和显示单元格结果,请执行下列任一操作:

  • 单击 然后选择" 隐藏结果"
  • 选择
  • 键入 Esc Shift + o

若要显示隐藏的单元格代码或结果,请单击“显示”链接:

显示隐藏的代码和结果

另请参阅可折叠的标题

笔记本隔离

笔记本隔离是指变量和类在笔记本之间的可见性。 Azure Databricks 支持两种类型的隔离:

  • 变量和类隔离
  • Spark 会话隔离

注意

由于附加到同一群集的所有笔记本都在同一群集 VM 上执行,因此即使启用了 Spark 会话隔离,也不能保证群集内的用户隔离。

变量和类隔离

变量和类仅在当前笔记本中可用。 例如,附加到同一群集的两个笔记本可以定义具有同一名称的变量和类,但这些对象是不同的。

若要定义一个对附加到同一群集的所有笔记本均可见的类,请在包单元格中定义该类。 然后,可以使用完全限定的名称来访问该类,这与访问附加的 Scala 或 Java 库中的类是相同的。

Spark 会话隔离

附加到运行 2.0.0 及Apache Spark的群集上的每个笔记本都有一个称为 的预定义变量, 该变量表示 SparkSessionSparkSession 是使用 Spark API 以及设置运行时配置的入口点。

默认情况下已启用 Spark 会话隔离。 你还可以使用全局临时视图跨笔记本共享临时视图。 请参阅创建视图CREATE VIEW。 若要禁用 Spark 会话隔离,在 spark.databricks.session.share Spark 配置中将 truespark.databricks.session.share

重要

spark.databricks.session.share 设置为 true 会中断流式处理笔记本单元格和流式处理作业所使用的监视。 具体而言:

  • 不会显示流式处理单元格中的
  • 只要流在运行,就不会阻止作业(它们在“成功地”完成后就会停止流)。
  • 系统不会监视作业中的流是否已终止, 而必须由你来手动调用 awaitTermination()
  • 对流式处理数据帧调用显示函数将不起作用。

使用其他语言来触发命令的单元格(即,使用 %scala%python%r%sql 的单元格)以及包含其他笔记本的单元格(即使用 %run 的单元格)都是当前笔记本的一部分。 因此,这些单元格与其他笔记本单元格位于相同的会话中。 相比之下, 笔记本 工作流运行具有独立 的笔记本,这意味着此类笔记本中定义的临时视图 在其他 笔记本中不可见。

版本控制

Azure Databricks 为笔记本提供了基本版本控制功能。 你可以执行以下有关修订的操作:添加注释、还原和删除修订,以及清除修订历史记录。

若要访问笔记本修订版本,请单击笔记本工具栏右上方的“修订历史记录”。

修订历史记录

本节内容:

添加注释

若要将注释添加到最新修订版本,请执行以下操作:

  1. 单击修订版本。

  2. 单击“立即保存”链接。

    保存注释

  3. 在“保存笔记本修订版本”对话框中,输入注释。

  4. 单击“保存” 。 笔记本修订版本将连同输入的注释一起保存。

还原修订版本

若要还原某个修订版本,请执行以下操作:

  1. 单击修订版本。

  2. 单击“还原此修订版本”。

    还原修订版本

  3. 单击“确认” 。 所选修订版本将成为笔记本的最新版本。

删除修订版本

若要删除笔记本的修订条目,请执行以下操作:

  1. 单击修订版本。

  2. 单击垃圾桶图标"回收站

    删除修订版本

  3. 单击“是,擦除”。 将从笔记本的修订历史记录中删除所选的修订版本。

清除修订历史记录

若要清除笔记本的修订历史记录,请执行以下操作:

  1. 选择"文件 清除修订历史记录"。

  2. 单击“是,清除”。 此时会清除笔记本修订历史记录。

    警告

    清除后,修订历史记录将无法恢复。

Git 版本控制

注意

若要将 Azure Databricks 中的工作与远程 Git 存储库同步,Databricks 建议使用用于 Git 集成的存储库

Azure Databricks 还集成了以下基于 Git 的版本控制工具: