使用代理代码转换器转换 SQL

重要

此功能在 Beta 版中。 若要使用它，工作区管理员必须从预览页打开代理代码转换器。 请参阅 Manage Azure Databricks 预览版。

代理式代码转换器利用 Genie Code，将现有的 T-SQL、Snowflake、Redshift、Oracle、BigQuery 和 Teradata 等 SQL 方言转换为可在 Azure Databricks 上运行的代码。 你在迁移项目中组织工作，并选择一个目标框架作为输出： SQL 生成Databricks的SQL查询，或用 Notebook 生成使用DataFrame API的Databricks笔记本。 转换器分析每个源脚本，验证转换后的输出，并在将结果写入工作区文件夹前反复修正错误。

代理代码转换器是 Databricks 工具的一部分，用于将工作负载从现有数据仓库和 ETL 工具迁移到Azure Databricks。 它会在你组织和跟踪迁移项目中的工作的同时转换源 SQL。

工作原理

通过在工作区中创建迁移项目来开始转换。 项目跟踪每个文件的状态，并提供一个管理迁移的位置。

转换工作流示意图：将源文件添加到迁移项目中，由 Genie Code 子代理对其进行转换，并将经验证的 ANSI SQL 写入工作区文件夹。

运行转换时，Genie Code 会调用迁移技能，并部署并发转换文件的子代理。 每个子代理分析源方言，生成项目目标框架（Databricks SQL 或 Databricks 笔记本）的等效代码，验证结果，并重试失败的部分。 转换后的文件将直接写入为项目指定的工作区文件夹。

还可以通过在 Genie Code 对话中使用 /migrate 命令转换单个文件或文件夹，而无需项目。

Requirements

  • 支持智能体代码转换器 Beta 版的工作区。 工作区管理员从 “预览 ”页启用该功能。 请参阅 Manage Azure Databricks 预览版。
  • 工作区中必须可访问现有 SQL 文件，要么作为工作区文件上传，要么在编辑器中打开。
  • 工作区必须满足 Genie Code 要求。 请参阅 Genie Code。

支持的源和限制

转换器支持以下源方言：

  • T-SQL
  • Snowflake SQL
  • Redshift SQL
  • Oracle
  • BigQuery
  • Teradata

创建迁移项目时，请选择以下目标框架之一：

  • SQL：符合ANSI标准的Databricks SQL查询。
  • 笔记本：Databricks 笔记本中使用 DataFrame API，对于用 SQL 表达更清晰的逻辑，则使用 spark.sql。

以下限制适用于每个转换：

  • 批最多可以包含 300 个文件。
  • 脚本最多可以包含 1,000 行。
  • 尚不支持 Teradata BTEQ 脚本。

转换现有 SQL 代码

以下步骤介绍如何转换迁移项目中的现有 SQL。

步骤 1：上传源文件

使用.sql上传现有 SQL 文件（），或使用 Databricks CLI 批量上传脚本目录。

步骤 2：创建迁移项目

从工作区创建迁移项目：

  1. 单击新建图标>迁移项目。
  2. 输入项目 的名称 。
  3. 使用下拉列表选择器选择 源方言 和 目标框架。 对于 目标框架，选择 SQL 以生成 Databricks SQL 查询，或选择 Notebooks 以生成 Databricks 笔记本。
  4. 输入目标 目标文件夹的文件路径。 单击“ 浏览 ”，从可用工作区文件夹列表中选择目标。
  5. （可选）输入用于描述项目血缘的血缘文件路径。 单击“ 浏览” ，从工作区中的文件列表中选择文件。
  6. 单击 “创建” 。

“新建迁移项目”对话框，其中显示了项目名称、源方言、目标框架和目标文件夹字段。

步骤 3：将文件添加到项目

在新项目中：

  1. 单击“ 添加文件>+ 添加文件”。
  2. 从工作区中选择源文件夹或文件。

项目列出了每个文件及其文件类型、行计数和转换状态。

迁移项目画布，其中显示了添加的源文件及其文件类型、行计数和转换状态。

步骤 4：查看代码复杂性和世系（可选）

如果已运行 Lakebridge 分析器，请将其 JSON 输出上传到项目，以查看代码复杂性和世系。 单击源文件以打开复杂性评估，然后单击“世系”以打开依赖关系图，该图显示相互依赖且必须一起迁移的文件和表。 有关运行分析器的说明，请参阅 Lakebridge 分析器指南。

步骤 5：运行转换

选择要转换的文件，然后单击“ 运行”。 Genie Code 将打开一个对话，调用迁移技能，并部署子代理以同时转换文件。 每个已转换的文件都显示为项目中的链接文件。 转换器将每个文件标记状态为：

  • 绿色：已成功转换
  • 黄色：需要评审
  • 红色：转换失败
  • 灰色：正在进行中

步骤 6：查看转换结果

对于 SQL 项目，点击已转换的文件，即可在 SQL 编辑器中打开并排差异视图，其中源代码显示在建议的 Databricks SQL 旁边。 接受所有建议，或分别查看并接受单项修改。 对于 笔记本 项目，点击已转换的文件以打开生成的Databricks笔记本。 对于无法转换的脚本，请在编辑器中编辑代码，或要求 Genie Code 重新验证或重试特定部分。 确认后，运行转换后的SQL或笔记本，确认它能在Azure Databricks上运行。

创建自定义技能（可选）

使用自定义技能可以编码 Genie Code 在每个转换过程中自动应用的业务规则。 使用它们来处理专有数据类型、强制实施首选目标模式或捕获重复执行的更正。 迁移技能是一种 Genie Code 技能，因此可以像任何其他技能一样创建和管理它。 有关更多详细信息，请参阅 使用代理技能扩展 Genie Code。

您可以在 Genie Code 设置中或通过 Genie Code 对话创建技能。 使用复杂技能的设置路径，其中包括详细说明、示例或支持文件。 针对简单的单规则技能，请使用聊天路径。

Genie Code 设置

以文件的形式创建技能，以便可以在 Git 文件夹中创作详细说明和对其进行版本控制：

  1. 在“Genie 代码”面板中，单击“ 齿轮”图标。设置，然后单击 图标中的箭头。打开 skills 文件夹。

  2. 在工作区技能路径 Workspace/.assistant/skills/下为技能创建文件夹。 例如，Workspace/.assistant/skills/sql-migration/。

  3. 在技能文件夹中，创建一个 SKILL.md 文件，须包含必需的前页和转换规则。 例如：

    ---
name: sql-migration
description: Conversion rules to apply when migrating legacy SQL to ANSI SQL.
---

Always convert the custom type MYDATE to TIMESTAMP_NTZ.

Genie Code 会在您下次运行转换时识别该技能。

Genie Code 聊天

描述要编码的转换规则，然后要求 Genie Code 保存它：

Tip

Always convert our custom type MYDATE to TIMESTAMP_NTZ. Save this as a custom migration skill.

Genie Code 会创建并注册该技能，并将其应用于工作区中的后续转换。

查看活动技能：

Tip

Show me my migration skills

移除技能：

Tip

Delete the migration skill for [description]

工作区技能存储在工作区级别，并在工作区中的所有用户之间共享。

测试提示

作为代理循环的一部分，转换器会分析每个源脚本，验证转换后的输出在语法上是否有效且语义上等效于源，并迭代修复了在编写结果之前失败的部分。 以下提示可帮助你查看和获得对输出的信心：

  • 批量转换：在一个会话中将一小批 2 到 5 个文件转换为 5 个文件，以验证多文件转换是否以端到端方式工作。
  • 语法验证：转换后，在 Databricks SQL 编辑器或笔记本中运行输出，以确认其运行没有错误。
  • 边缘情况：包括具有特定于方言构造的脚本，例如 T-SQL 窗口函数、Snowflake QUALIFY或 Redshift LISTAGG，以了解转换器如何处理非普通模式。
  • 语义正确性：针对等效的测试数据运行原始查询和转换后的查询，并比较结果。 确认输出在语义上是正确的，而不仅仅是在语法上有效。

其他资源

  • Last updated on