使用 Lakeflow 声明性管道中的多文件编辑器开发和调试 ETL 管道

本文介绍如何使用 Lakeflow 声明性管道中的多文件编辑器来开发和调试 ETL（提取、转换和加载）管道。 多文件编辑器在管道资产浏览器中将管道显示为一组文件。 您可以在一个地方编辑文件，并控制管道的配置以及要包含的文件。

有关在 Lakeflow 声明性管道中使用单个笔记本的默认开发体验，请参阅 在 Lakeflow 声明性管道中使用笔记本开发和调试 ETL 管道。

多文件编辑器概述

ETL 管道多文件编辑器具有以下功能：

1. 管道资产浏览器：创建、删除、重命名和组织管道资产。
2. 包含选项卡的多文件代码编辑器：跨与管道关联的多个代码文件工作。
3. 特定于管道的工具栏：启用 管道配置 并具有 管道级运行作。
4. 交互式定向无环图（DAG）：获取表的概览，打开数据预览底部栏，并执行其他与表相关的操作。
5. 数据预览：检查流式处理表和具体化视图的数据。
6. 表级执行见解：获取管道中所有表或单个表的执行见解。 见解源自最新的管道运行，
7. 问题面板：此功能汇总了管道中所有文件中的错误，你可以导航到特定文件中发生错误的位置。 可对代码级错误指示形成补充。
8. 选择性执行：代码编辑器具有分步开发的功能，例如，可以使用“运行文件”操作仅刷新当前文件中的表或单个表。
9. 默认管道文件夹结构：新管道包括预定义的文件夹结构和示例代码，可用于管道的起点。
10. 简化的管道创建：提供默认创建表的名称、目录和架构，并使用默认设置创建管道。 稍后可以从管道编辑器工具栏调整“设置”。

启用多文件编辑器

可以通过多种方式启用 ETL 管道多文件编辑器：

• 在创建新的 ETL 管道时，可通过 ETL 管道编辑器 切换，在 Lakeflow 声明性管道中启用多文件编辑器。

  

  首次启用多文件编辑器时，将为管道使用高级设置页。 下次创建新管道时，将使用简化的管道创建窗口。

• 对于现有管道，请打开管道中使用的笔记本，并在标头中启用“ETL 管道编辑器”开关。 还可以转到管道监视页，然后单击 “设置” 以启用多文件编辑器。

启用 ETL 管道编辑器 切换后，默认情况下，所有 ETL 管道都将使用多文件编辑器。 可以从编辑器打开和关闭 ETL 管道多文件编辑器。

或者，可以从用户设置启用多文件编辑器：

1. 单击工作区右上角的用户 徽章，然后单击 设置 和 开发人员。
2. 为笔记本和文件启用选项卡。
3. 启用 ETL 管道多文件编辑器。

创建新的 ETL 管道

若要使用多文件编辑器创建新的 ETL 管道，请执行以下步骤：

1. 在边栏顶部，单击，然后单击“新”，然后选择ETL 管道。

2. 在顶部，您可以为您的管道提供一个独特的名称。

3. 就在名称下，可以看到已为你选择的默认目录和架构。 更改这些选项，为管道提供不同的默认值。

   默认 目录 和默认 架构 是在未在代码中使用目录或架构限定数据集时从中读取或写入数据集的位置。 有关详细信息，请参阅 Azure Databricks 中的数据库对象 。

4. 选择以下选项之一来创建管道：

   • 从 SQL 中的示例代码开始 ，以创建新的管道和文件夹结构，包括 SQL 中的示例代码。
   • 从 Python 中的示例代码开始 ，以创建新的管道和文件夹结构，包括 Python 中的示例代码。
   • 首先，使用单个转换 创建新的管道和文件夹结构，并创建一个新的空白代码文件。
   • 添加现有资产 以便创建可与工作区中的现有代码文件关联的管道。

   可以在 ETL 管道中同时包含 SQL 和 Python 源代码文件。 创建新管道并选择示例代码的语言时，该语言仅适用于默认情况下包含在管道中的示例代码。

5. 选择后，会重定向到新创建的管道。

ETL 管道是使用以下默认设置创建的：

• Unity Catalog
• 预览通道
• 无服务器计算
• 开发模式

可以从管道工具栏调整这些设置，或选择“ 创建高级管道 ”以提供首选设置。 有关详细信息，请参阅 配置 Lakeflow 声明性管道 。

或者，可以从工作区浏览器创建 ETL 管道：

1. 在左侧面板中单击 “工作区 ”。
2. 选择任何文件夹，包括 Git 文件夹。
3. 单击右上角的“ 创建 ”，然后单击 “ETL 管道”。

您还可以从作业和管道页面创建 ETL 管道：

1. 单击左侧面板中的 “工作流 ”。
2. 单击“作业和管道”选项卡。
3. 单击 ETL 管道。

打开现有的 ETL 管道

若要在多文件编辑器中打开现有的 ETL 管道，请执行以下步骤：

1. 在侧面板中单击 “工作区 ”。
2. 导航到包含管道源代码文件的文件夹。
3. 单击源代码文件以在编辑器中打开管道。

还可以通过以下方式打开现有的 ETL 管道：

• 在左侧边栏的“最近”页面上，打开管道或配置为管道源代码的文件。
• 在管道监视页中，单击“ 编辑管道”。
• 在左侧栏中的“ 作业运行 ”页上，单击“ 作业和管道 ”选项卡，然后单击“ 并 编辑管道。
• 创建新作业并添加管道任务时，可以在“新建”选项卡中单击“ 。在 “管道”下选择管道时，
• 编辑管道时，可以单击资产浏览器顶部的管道名称，从最近查看的管道列表中进行选择。
• 如果从资产浏览器中打开一个配置为用于不同管道的源代码文件，则该文件编辑器顶部会显示一个横幅，提示您打开关联的管道。 若要打开不属于管道的源代码文件，请选择资产浏览器顶部 的所有文件 。

管道资产浏览器

多文件管道编辑器为工作区浏览器侧边栏提供了一种特殊模式（称为“管道资产浏览器”），且默认会将面板焦点锁定在管道上。

单击浏览器顶部的管道名称，在最近查看的管道之间切换。

资产浏览器有两个选项卡：

• 管道：可在其中找到与管道关联的所有文件。 可以创建、删除、重命名并将其组织到文件夹中。
• 所有文件：此处提供了所有其他工作区资产。

管道中可以包含以下类型的文件：

• 源代码文件：这些文件是管道源代码定义的一部分，可在 “设置”中看到。 Databricks 建议始终将源代码文件存储在 管道根文件夹中;否则，它们将显示在浏览器底部 的外部文件 部分中，并具有不太丰富的功能集。
• 非源代码文件：这些文件存储在管道根文件夹中，但不是管道源代码定义的一部分。

根文件夹

管道资产浏览器定位在管道根文件夹中。 创建新管道时，管道根文件夹在用户主文件夹中创建，并命名为与管道名称相同。

可以在管道资产浏览器中更改根文件夹。 如果在文件夹中创建了管道，并且以后想要将所有内容移动到其他文件夹，则这非常有用。 例如，你在普通文件夹中创建了管道，并且想要将源代码移动到 Git 文件夹进行版本控制。

1. 单击 根文件夹的溢出菜单。
2. 单击“ 配置新根文件夹”。
3. 在 “管道根文件夹 ”下，单击 并选择另一个文件夹作为管道根文件夹。
4. 单击“ 保存”。

在 中，对于根文件夹，还可以单击“ 重命名根文件夹 ”以重命名文件夹名称。 在这里，还可以单击“ 移动根文件夹 ”，将根文件夹（例如）移动到 Git 文件夹中。

还可以在设置中更改管道根文件夹：

1. 点击设置。
2. 在 “代码资产 ”下，单击“ 配置路径”。
3. 单击 可更改 管道根文件夹下的文件夹。
4. 单击“ 保存”。

没有根文件夹的现有管道

在默认开发体验中，使用 Lakeflow 声明性管道的单个笔记本创建的现有管道不会配置根文件夹。 按照以下步骤为现有管道配置根文件夹：

1. 在管道资产浏览器中，单击“ 配置”。
2. 单击 以选择 管道根文件夹下的根文件夹。
3. 单击“ 保存”。

默认文件夹结构

创建新管道时，会创建默认文件夹结构。 这是用于组织管道源和非源代码文件的建议结构，如下所示。

在此文件夹结构中创建少量示例代码文件。

可以重命名文件夹名称或更改结构以适应工作流。 若要添加新的源代码文件夹，请执行以下步骤：

1. 在管道资产浏览器中单击“ 添加 ”。
2. 单击“ 创建管道源代码”文件夹。
3. 输入文件夹名称，然后单击“ 创建”。

源代码文件

源代码文件是管道源代码定义的一部分。 运行管道时，将评估这些文件。 源代码定义的文件和文件夹部分有一个特殊图标，上面叠加了一个迷你管道图标。

若要添加新的源代码文件，请执行以下步骤：

1. 在管道资产浏览器中单击“ 添加 ”。
2. 单击“转换”。
3. 输入文件 的名称 ，然后选择 Python 或 SQL 作为 语言。
4. 单击 “创建” 。

还可以单击 对于管道资产浏览器中的任何文件夹，可以添加源代码文件。

transformations创建新管道时，默认情况下会创建源代码的文件夹。 此文件夹是管道源代码的建议位置，例如包含管道表定义的 Python 或 SQL 代码文件。

非源代码文件

非源代码文件存储在管道根文件夹中，但不是管道源代码定义的一部分。 当您运行管道时，这些文件不会被检查。 非源代码文件不能是 外部文件。

可以将此项用于与你想要与源代码一起存储的管道工作相关的文件。 例如：

• 在非 Lakeflow 声明性管道中执行的临时探索笔记本，其计算发生在管道生命周期之外。
• 除非在源代码文件中明确导入这些模块，否则不会使用你的源代码来评估这些 Python 模块。

若要添加新的非源代码文件，请执行以下步骤：

1. 在管道资产浏览器中单击“ 添加 ”。
2. 单击“ 浏览 ”或 “实用工具”。
3. 输入文件 的名称 。
4. 单击 “创建” 。

还可以单击 对于管道根文件夹或非源代码文件，可将非源代码文件添加到该文件夹中。

创建新管道时，默认情况下会创建以下非源代码文件的文件夹：

还可以导入根文件夹外部的 Python 模块，但在这种情况下，必须将文件夹路径追加到 sys.path Python 代码中：

import sys, os
sys.path.append(os.path.abspath('<alternate_path_for_utilities>/utilities'))
from utils import \*

外部文件

管道浏览器的外部 文件 部分显示根文件夹外的源代码文件。

要将外部文件移动到根文件夹（如 transformations 文件夹），请执行以下步骤：

1. 单击 ，在资产浏览器中选择文件，然后单击移动。
2. 选择要将文件移动到的文件夹，然后单击“ 移动”。

与多个管道关联的文件

如果文件与多个管道关联，则文件标题中会显示一个徽章。 它具有关联管道的数量，并允许切换到其他管道。

所有文件部分

除了 “管道 ”部分，还有一个 “所有文件 ”部分，可在其中打开工作区中的任何文件。 在这里，你可以：

• 在选项卡中打开根文件夹外部的文件，而无需离开多文件编辑器。
• 导航到其他管道的源代码文件并打开它们。 这会在编辑器中打开文件，并提供一个横幅，其中包含将编辑器中的焦点切换到第二个管道的选项。
• 将文件移动到管道的根文件夹。
• 在管道源代码定义中包含根文件夹外部的文件。

运行管道代码

有三个选项可用于运行管道代码：

1. 运行管道中的所有源代码文件：单击运行 管道 或 运行包含完整表刷新的管道 ，以运行所有定义为管道源代码的文件中的所有表定义。

   

   还可以单击 “干运行 ”来验证管道，而无需更新任何数据。

2. 在单个文件中运行代码：单击“运行文件”或“运行文件并刷新整个表”以运行当前文件中的所有表定义。

   

3. 为单个表运行代码：单击源代码文件中表定义的 “运行表 ，然后单击“ 刷新表 ”或“ 完全刷新表”。

   

定向无周期图 （DAG）

运行或验证管道中的所有源代码文件后，会看到有向无环图（DAG）。 该图显示表依赖项关系图。 每个节点在管道生命周期中具有不同的状态，例如已验证、正在运行或错误。

可以通过单击右侧面板中的图形图标来打开和关闭图形。 还可以最大化图形。 右下角还有其他选项，包括缩放选项和用于在垂直或水平布局中显示图形的更多选项。

将鼠标悬停在节点上会显示包含选项的工具栏，包括刷新查询。 右键单击节点可在上下文菜单中提供相同的选项。

单击节点会显示 数据预览 和表定义。 编辑文件时，图形中突出显示了该文件中定义的表。

数据预览

数据预览部分显示所选表的示例数据。

单击有向无环图（DAG）中的节点时，你将看到表数据的预览。

如果未选择表，请转到“ 表 ”部分，然后单击“ 查看数据预览。 如果选择了表，请单击“ 所有表 ”以返回到所有表。

执行见解

可以在编辑器底部的面板中查看有关最新管道更新的表执行见解。

管道设置

若要访问管道设置面板，请单击工具栏中的设置或在管道资产浏览器的迷你卡中单击。

事件日志

您需要在“设置”中进行管道设置，之后管道的事件日志才会可用。

1. 打开设置。
2. 单击 “高级设置”旁边的箭头。
3. 单击“ 编辑高级设置”。
4. 选择“ 将事件日志发布到元存储”。
5. 提供事件日志的名称、目录和架构。
6. 单击“ 保存”。

现在，管道事件将发布到您指定的表。

环境

可以通过在 “设置”中添加依赖项为源代码创建环境。

1. 打开设置。
2. 在 “环境”下，单击“ 编辑环境”。
3. 选择 以添加依赖项，就像将它添加到一个文件中 requirements.txt 一样。 有关依赖项的详细信息，请参阅 向笔记本添加依赖项。

Databricks 建议将版本固定为 ==. 请参阅 PyPI 包。

环境适用于管道中的所有源代码文件。

通知

可以通过使用 旧版管道设置来添加通知。

1. 打开设置。
2. 在“管道设置”面板底部，单击“旧管道设置”。
3. 在 “通知”下，单击“ 添加通知”。
4. 添加一个或多个电子邮件地址以及要发送的事件。
5. 单击“添加通知”。

限制和已知问题

请参阅 Lakeflow 声明性管道中 ETL 管道多行编辑器的以下限制和已知问题：

1. 如果先从 explorations 文件夹中打开一个文件或笔记本，工作区浏览器侧边栏将不会聚焦于管道，因为这些文件或笔记本不属于管道源代码定义的一部分。

   1. 若要在工作区浏览器中输入管道焦点模式，请打开与管道关联的文件。

2. 常规视图不支持数据预览。

3. 只能从管道监视页执行多表刷新。 使用管道浏览器中的迷你卡导航到该页面。

4. 由于代码中的换行，可能会出现在不正确的位置。

5. 不支持在文件（新编辑器的默认资产类型）中执行 %pip install。 可以在设置中添加依赖项。 请参阅 环境。

   或者，您可以继续在与管道相关的笔记本的源代码定义中使用 %pip install。

常见问题

1. 为什么选择使用文件而不是笔记本来处理源代码？

   笔记本的基于单元格的执行与 Lakeflow 声明性管道不兼容。 因此，我们必须关闭功能或更改其行为，从而导致混淆。

   在 ETL 管道的多文件编辑器中，文件编辑器用作 Lakeflow 声明性管道的顶级编辑器基础。 功能是明确针对 Lakeflow 声明式管道设计的，例如 运行表，而不是用来赋予熟悉的功能不同的行为。

2. 是否仍可将笔记本用作源代码？

   是的，可以。 但是，某些功能（如 运行表 或 运行文件）将不存在。

   如有使用笔记本的现有管道，它仍然可以在新编辑器中运行。 但是，Databricks 建议切换到新管道的文件。

3. 如何将现有代码添加到新创建的管道？

   可以将现有源代码文件添加到新管道。 若要添加包含现有文件的文件夹，请执行以下步骤：

   1. 点击设置。
   2. 在 源代码 下，单击“ 配置路径”。
   3. 单击 “添加路径 ”，然后选择现有文件的文件夹。
   4. 单击“ 保存”。

   还可以添加单个文件：

   1. 在管道资产浏览器中单击所有文件。
   2. 导航到文件，单击 然后单击“ 包括在管道中”。

   请考虑将这些文件移动到管道根文件夹。 如果离开管道根文件夹外部，它们将显示在 “外部文件 ”部分。

4. 是否可以在 Git 中管理管道源代码？

   在最初创建管道时，可以通过选择 Git 文件夹来管理 Git 中的管道源。在没有版本控制的情况下创建管道后，可以将源移动到 Git 文件夹。 Databricks 建议使用编辑器的操作将整个根文件夹移动到 Git 文件夹。 这将相应地更新所有设置。 请参阅 根文件夹。

   若要将根文件夹移动到管道资产浏览器中的 Git 文件夹，请执行以下作：

   1. 单击 对于根文件夹。
   2. 单击“ 移动根文件夹”。
   3. 选择根文件夹的新位置，然后单击“ 移动”。

   有关详细信息，请参阅 “根文件夹 ”部分。

   移动后，将看到根文件夹名称旁边的熟悉的 Git 图标。

   重要

   若要移动管道根文件夹，请使用管道资产浏览器和上述步骤。 如果以其他方式移动，将导致管道配置中断，您必须在设置中手动配置正确的文件夹路径。

5. 是否可以在同一根文件夹中有多个管道？

   可以，但 Databricks 建议每个根文件夹只有一个管道。

6. 我什么时候应该运行试运行？

   单击“试运行”以检查代码而不更新表。

7. 何时应使用临时视图，何时应在代码中使用具体化视图？

   如果不想具体化数据，请使用临时视图。 例如，在数据准备就绪（可通过目录中注册的流式处理表或物化视图进行物化）前，此为数据预处理步骤序列中的一步。