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

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

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

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

检查管道是否使用旧版发布模式

以以下方式指示旧版发布模式管道：

• Lakeflow Spark 声明性管道设置 UI 的摘要字段。
• Lakeflow Spark 声明性管道事件日志最新 create_update 包含 effective_publishing_mode。
• 管道 API GET /api/2.0/pipelines/{pipeline_id} 响应包含 effectivePublishingMode

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

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

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

迁移到默认发布模式

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

1. 在工作区的左侧边栏中单击“ 作业和管道 ”。

2. 单击列表中要迁移的管道的名称。

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

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

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

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

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

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

7. （可选）在管道 设置中，删除其 pipelines.enableDPMForExistingPipeline管道配置。 此设置用于迁移，在迁移完成后不需要此设置。

8. 如有需要，请更新时间表，并启用管道更新。

现在，在管道上启用了默认发布模式。 如果看到问题，请使用下一部分来帮助进行故障排除。 如果问题仍然存在，请联系 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;

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

事件 flow_progress 更改

迁移管道会更改事件日志中 flow_progress 事件所属的数据集名称。 如果对此管道的事件日志有查询，则可能需要更新查询。

在旧版发布模式下，数据集名称是 table 名称。 在默认发布模式下，数据集名称是完全限定 catalog.schema.table 的名称。

有关使用事件日志的详细信息，请参阅 管道事件日志。

警告与错误

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

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

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

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

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

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

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

Troubleshooting

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