在管道中启用默认发布模式

本文介绍如何将使用虚拟架构（旧发布模式）的 LIVE 管道迁移到默认发布模式。

默认发布模式允许单个管道写入多个目录和架构，并包括用于处理管道中的表和视图的简化语法。 旧版发布模式被视为已弃用，Databricks 建议将所有管道迁移到默认发布模式。

迁移会影响管道的元数据，但不会读取、移动或写入任何数据集。

如何判断管道是否使用旧版发布模式

旧版发布模式管道在 Lakeflow 声明性管道设置 UI 的《摘要》字段中显示。 您还可以确认管道使用旧版发布模式，如果在管道的 JSON 规范中设置了 target 字段。

迁移到默认发布模式的注意事项

在迁移过程中，请注意以下说明：

• 将管道迁移到默认发布模式后，无法将其迁移回使用 LIVE 虚拟架构。
• 在准备迁移你的工作流时，可能需要解决旧发布模式与默认发布模式之间的语法变更。 大多数管道不需要更改。 有关详细信息，请参阅 准备用于迁移的管道。
• 迁移仅影响元数据。 它不会读取、移动或写入任何数据集。
• 在默认发布模式下，物化视图和流式表在创建后无法跨架构移动。
• 默认发布模式需要 Databricks CLI 版本 v0.230.0 或更高版本。 请参阅安装或更新 Databricks CLI。

迁移到默认发布模式

使用以下步骤迁移到默认发布模式。

1. 在 Databricks UI 中打开要迁移的管道。

2. 暂停更新并要求所有当前正在运行的管道停止。

   在完成迁移之前，必须至少运行一个更新。 如果管道被触发或者已经暂停，请手动运行单个更新。 如果管道是连续的，请确保它进入（或已处于） RUNNING 状态，然后暂停。

3. （可选）准备可能需要迁移的任何代码。

   默认发布模式通常与旧版发布模式向后兼容，但请务必正确 准备管道进行迁移 ，以便在升级时管道代码正常运行。 大多数管道不需要更改。

4. 在管道 设置中添加配置： pipelines.enableDPMForExistingPipeline，设置为 true。

5. 启动手动更新，让更新完成。

6. 转到管道设置 JSON 页。 找到字段 target ，并将其替换为 schema （保留相同的值）。 配置应包括 JSON，如下所示：

   ...
   "catalog": "main",
   "configuration": {
     "pipelines.setMigrationHints": "true",
     "pipelines.enableDPMForExistingPipeline": "true"
   },
   "schema": "default",
   "data_sampling": "false",
   ...
   

7. 保存 JSON。

8. 在管道 设置中，删除管道配置 pipelines.setMigrationHints 和 pipelines.enableDPMForExistingPipeline。

9. 启用管道更新，使其恢复到迁移之前的状态。

现在，在管道上启用了默认发布模式。 如果看到问题，请使用下一部分来帮助进行故障排除。 如果问题仍然存在，请联系 Databricks 客户经理。

准备用于迁移的管道

默认发布模式通常与旧版发布模式向后兼容，但可能需要修改某些管道才能运行。 以下注意事项可帮助你准备管道以便迁移。

LIVE 关键字

在旧版发布模式中，LIVE 关键字使用管道默认值限定对象的目录和架构。 默认发布模式不再使用 LIVE 关键字来限定表或视图。 忽略 LIVE 关键字，并替换为管道的默认目录和架构。 通常，这将使用与旧发布模式下LIVE关键字相同的默认目录和架构，除非稍后您在管道中添加USE CATALOG或USE SCHEMA命令。

在旧版发布模式下，部分限定的表和视图引用（未使用 LIVE 关键字，如 table1）采用 Spark 默认值。 在默认发布模式下，部分限定引用使用管道默认值。 如果 Spark 默认值和管道不同，则应在迁移之前完全限定任何部分限定表或视图的名称。

使用 LIVE 关键字的列引用

不能使用 LIVE 关键字在默认发布模式下定义列。 例如，此代码：

CREATE OR REPLACE MATERIALIZED VIEW target AS SELECT LIVE.source.id FROM LIVE.source;

需要在迁移之前被替换为以下内容：

CREATE OR REPLACE MATERIALIZED VIEW target AS SELECT source.id FROM LIVE.source;

此版本适用于任一发布模式。

警告与错误

旧版发布模式下的某些警告已替换为默认发布模式下的错误。

自我引用 在默认发布模式下不允许使用自我引用（或循环引用），并且旧版发布模式中没有定义的结果。 例如：

CREATE OR REPLACE MATERIALIZED VIEW table1 AS SELECT * FROM target_catalog.target_schema.table1;

将在旧版发布模式下生成警告（且结果未定义）。 在默认发布模式下，它会生成错误。

多部分名称 不能在默认发布模式（多部分名称）中使用名称中的句点。 例如，以下 Python 代码在旧模式下有效，但在默认模式下无效：

@dlt.view(name="a.b.c")
def transform():
  return …

在迁移之前，请将视图重命名为不包含句点字符的名称。

故障排除

下表描述了从旧发布模式迁移时可能发生的错误。