使用批量 SQL 转换器迁移代码

本文档介绍了如何在 BigQuery 中使用批量 SQL 转换器将用其他 SQL 方言编写的脚本转换为 GoogleSQL 查询。本文档适用于熟悉 Google Cloud 控制台的用户。

准备工作

在提交转换作业之前，请完成以下步骤：

  1. 确保您拥有所需的所有权限。
  2. 启用 BigQuery Migration API。
  3. 收集包含待转换的 SQL 脚本和查询的源文件。
  4. 可选。创建元数据文件以提高转换的准确性。
  5. 可选。确定是否需要将源文件中的 SQL 对象名称映射到 BigQuery 中的新名称。确定必要的名称映射规则。
  6. 确定用于提交转换作业的方法。
  7. 将源文件上传到 Cloud Storage。

所需权限

您必须拥有项目的以下权限才能启用 BigQuery Migration Service：

  • resourcemanager.projects.get
  • serviceusage.services.enable
  • serviceusage.services.get

您需要拥有项目的以下权限才能访问和使用 BigQuery Migration Service：

  • bigquerymigration.workflows.create
  • bigquerymigration.workflows.get
  • bigquerymigration.workflows.list
  • bigquerymigration.workflows.delete
  • bigquerymigration.subtasks.get

  • bigquerymigration.subtasks.list

    或者，您可以使用以下角色获取相同的权限：

    • bigquerymigration.viewer - 只读权限。
    • bigquerymigration.editor - 读写权限。

要访问 Cloud Storage 存储桶的输入和输出文件，您需要拥有以下权限：

  • 针对源 Cloud Storage 存储桶的 storage.objects.get 权限。
  • 针对源 Cloud Storage 存储桶的 storage.objects.list 权限。
  • 针对目标 Cloud Storage 存储桶的 storage.objects.create 权限。

您可以从以下角色获得上述所有必要的 Cloud Storage 权限：

  • roles/storage.objectAdmin
  • roles/storage.admin

启用 BigQuery Migration API

如果您的 Google Cloud CLI 项目是在 2022 年 2 月 15 日之前创建的，请按如下方式启用 BigQuery Migration API：

  1. 在 Google Cloud 控制台中，前往 BigQuery Migration API 页面。

    前往 BigQuery Migration API

  2. 点击启用。

收集源文件

源文件必须是包含源方言有效 SQL 的文本文件。源文件也可以包含注释。尽量使用您可以使用的任何方法确保 SQL 有效。

创建元数据文件

为帮助该服务生成更准确的转换结果，我们建议您提供元数据文件。不过，这并非强制性要求。

您可以使用 dwh-migration-dumper 命令行提取工具生成元数据信息，也可以提供自己的元数据文件。元数据文件准备就绪后，您可以将其与源文件一起添加到转换来源文件夹中。转换程序会自动检测这些文件并利用它们来转换源文件，您无需配置任何额外设置即可实现该转换。

如需使用 dwh-migration-dumper 工具生成元数据信息，请参阅生成转换元数据。

如需提供您自己的元数据，请将源系统中 SQL 对象的数据定义语言 (DDL) 语句收集到单独的文本文件中。

确定如何提交转换作业

您可以通过以下三种方式提交批量转换作业：

  • 批量转换客户端：通过更改配置文件中的设置来配置作业，并使用命令行提交作业。此方法不要求您将源文件手动上传到 Cloud Storage。客户端在转换作业处理期间仍使用 Cloud Storage 存储文件。

    旧版批量转换客户端是一个开源 Python 客户端，可让您转换本地机器上的源文件，并将转换后的文件输出到本地目录。您可以通过更改客户端配置文件中的一些设置来配置客户端的基本用法。如果您愿意，还可以配置客户端来处理更复杂的任务，例如宏替换以及转换输入和输出的预处理和后处理。如需了解详情，请参阅批量转换客户端的readme。

  • Google Cloud 控制台：使用界面配置和提交作业。此方法要求您将源文件上传到 Cloud Storage。

创建配置 YAML 文件

您可以酌情创建和使用配置 YAML 文件，以自定义批量转换。这些文件可用于通过各种方式对转换输出进行转换。例如，您可以创建配置 YAML 文件，以在转换期间更改 SQL 对象的大小写。

如果要使用 Google Cloud 控制台或 BigQuery Migration API 执行批量转换作业，您可以将配置 YAML 文件上传到包含源文件的 Cloud Storage 存储桶。

如果您要使用批量转换客户端，则可以将配置 YAML 文件放在本地转换输入文件夹中。

将输入文件上传到 Cloud Storage

如果您要使用 Google Cloud 控制台或 BigQuery Migration API 执行转换作业，则必须将包含待转换查询和脚本的源文件上传到 Cloud Storage。您还可以将任何元数据文件或配置 YAML 文件上传到包含源文件的同一 Cloud Storage 存储桶和目录。如需详细了解如何创建存储桶并将文件上传到 Cloud Storage，请参阅创建存储桶，以及从文件系统上传对象。

支持的 SQL 语言

批量 SQL 转换器是 BigQuery Migration Service 的一部分。批量 SQL 转换器可以将以下 SQL 方言转换为 GoogleSQL：

  • Amazon Redshift SQL
  • Apache HiveQL 和 Beeline CLI
  • IBM Netezza SQL 和 NZPLSQL
  • Teradata 和 Teradata Vantage：
    • SQL
    • Basic Teradata Query (BTEQ)
    • Teradata 并行传输 (TPT)

此外，预览版还支持转换以下 SQL 方言：

  • Apache Impala SQL
  • Apache Spark SQL
  • Azure Synapse T-SQL
  • GoogleSQL (BigQuery)
  • Greenplum SQL
  • IBM DB2 SQL
  • MySQL SQL
  • Oracle SQL、PL/SQL、Exadata
  • PostgreSQL SQL
  • Trino 或 PrestoSQL
  • Snowflake SQL
  • SQL Server T-SQL
  • SQLite
  • Vertica SQL

使用辅助 UDF 处理不受支持的 SQL 函数

将 SQL 从源方言转换为 BigQuery 时，某些函数可能没有直接对应的函数。为解决此问题，BigQuery Migration Service（以及更广泛的 BigQuery 社区）提供了辅助用户定义的函数 (UDF)，用于复制这些不受支持的来源方言函数的行为。

这些 UDF 通常位于 bqutil 公共数据集中，因此转换后的查询最初可以使用 bqutil.<dataset>.<function>() 格式引用它们。例如 bqutil.fn.cw_count()。

生产环境的重要注意事项：

虽然 bqutil 可为初始转换和测试提供对这些辅助 UDF 的便捷访问，但出于以下几个原因，不建议直接依赖 bqutil 来处理生产工作负载：

  1. 版本控制：bqutil 项目托管这些 UDF 的最新版本，这意味着它们的定义可能会随时间而变化。直接依赖 bqutil 可能会在 UDF 的逻辑更新时，导致生产查询出现意外行为或破坏性更改。
  2. 依赖项隔离：将 UDF 部署到您自己的项目可将生产环境与外部更改隔离开来。
  3. 自定义：您可能需要修改或优化这些 UDF，以更好地满足您的特定业务逻辑或性能要求。只有当它们位于您自己的项目中时，才能实现此目的。
  4. 安全和治理：组织的安全政策可能会限制直接访问公共数据集（例如 bqutil）来进行生产数据处理。将 UDF 复制到受控环境符合此类政策。

将辅助 UDF 部署到您的项目：

为了在生产环境中可靠、稳定地使用，您应将这些辅助 UDF 部署到您自己的项目和数据集中。这样一来，您就可以完全控制其版本、自定义设置和访问权限。如需详细了解如何部署这些 UDF，请参阅 GitHub 上的 UDF 部署指南。本指南提供了将 UDF 复制到您的环境所需的脚本和步骤。

位置

批量 SQL 转换器可在以下处理位置使用：

区域说明 区域名称 详细信息
亚太地区
德里 asia-south2
香港 asia-east2
雅加达 asia-southeast2
墨尔本 australia-southeast2
孟买 asia-south1
大阪 asia-northeast2
首尔 asia-northeast3
新加坡 asia-southeast1
悉尼 australia-southeast1
台湾 asia-east1
东京 asia-northeast1
欧洲
比利时 europe-west1 叶形图标 二氧化碳排放量低
柏林 europe-west10
欧盟多区域 eu
芬兰 europe-north1 叶形图标 二氧化碳排放量低
法兰克福 europe-west3
伦敦 europe-west2 叶形图标 二氧化碳排放量低
马德里 europe-southwest1 叶形图标 二氧化碳排放量低
米兰 europe-west8
荷兰 europe-west4 叶形图标 二氧化碳排放量低
巴黎 europe-west9 叶形图标 二氧化碳排放量低
斯德哥尔摩 europe-north2 叶形图标 二氧化碳排放量低
都灵 europe-west12
华沙 europe-central2
苏黎世 europe-west6 叶形图标 二氧化碳排放量低
美洲
俄亥俄州，哥伦布 us-east5
达拉斯 us-south1 叶形图标 二氧化碳排放量低
艾奥瓦 us-central1 叶形图标 二氧化碳排放量低
拉斯维加斯 us-west4
洛杉矶 us-west2
墨西哥 northamerica-south1
北弗吉尼亚 us-east4
俄勒冈 us-west1 叶形图标 二氧化碳排放量低
魁北克 northamerica-northeast1 叶形图标 二氧化碳排放量低
圣保罗 southamerica-east1 叶形图标 二氧化碳排放量低
盐湖城 us-west3
圣地亚哥 southamerica-west1 叶形图标 二氧化碳排放量低
南卡罗来纳 us-east1
多伦多 northamerica-northeast2 叶形图标 二氧化碳排放量低
美国多区域 us
非洲
约翰内斯堡 africa-south1
MiddleEast
Dammam me-central2
多哈 me-central1
以色列 me-west1

提交转换作业

请按照以下步骤启动转换作业、监控其进度并查看结果。

控制台

这些步骤假定您已将源文件上传到 Cloud Storage 存储桶中。

  1. 在 Google Cloud 控制台中，前往 BigQuery 页面。

    转到 BigQuery

  2. 在导航菜单中，点击工具和指南。

  3. 在转换 SQL面板中，依次点击转换 > 批量转换。

  4. 系统会打开转换配置页面。输入以下详细信息：

    1. 在显示名称部分，输入转换作业的名称。名称可以包含字母、数字或下划线。
    2. 在处理位置部分，选择要运行转换作业的位置。例如，如果您在欧洲，并且不希望您的数据跨越任何位置边界，那么请选择 eu 区域。当您选择与源文件存储桶相同的位置时，转换作业效果最佳。
    3. 在源方言部分，选择要转换的 SQL 方言。
    4. 在目标方言部分，选择 BigQuery。

  5. 点击下一步。

  6. 在源位置部分，指定包含待转换文件的 Cloud Storage 文件夹的路径。您可以按 bucket_name/folder_name/ 格式输入路径，也可以使用浏览选项。

  7. 点击下一步。

  8. 在目标位置部分，指定用于存储转换后文件的目标 Cloud Storage 文件夹的路径。您可以按 bucket_name/folder_name/ 格式输入路径，也可以使用浏览选项。

  9. 如果您执行的转换不需要指定默认对象名称或从来源到目标的名称映射，请跳到第 11 步。否则，请点击下一步。

  10. 填写所需的可选设置。

    1. 可选。在默认数据库部分，输入要用于源文件的默认数据库名称。转换程序会使用此默认数据库名称来解析缺少数据库名称的 SQL 对象的完全限定名称。

    2. 可选。在架构搜索路径部分，指定当转换程序需要解析源文件中缺少架构名称的 SQL 对象的完全限定名称时要搜索的架构。如果源文件使用多个不同的架构名称，请点击添加架构名称，以便为可能引用的每个架构名称添加一个值。

      转换程序会搜索您提供的元数据文件，以通过架构名称对表进行验证。如果无法从元数据确定确切的架构，则您输入的第一个架构名称将用作默认值。如需详细了解如何使用默认架构名称，请参阅默认架构。

    3. 可选。如果要指定名称映射规则以在转换期间重命名源系统和 BigQuery 之间的 SQL 对象，您可以提供包含名称映射对的 JSON 文件，也可以使用Google Cloud 控制台指定要映射的值。

      如需使用 JSON 文件，请执行以下操作：

      1. 点击上传用于名称映射的 JSON 文件。

      2. 浏览到采用适当格式的名称映射文件的位置，选择该文件，然后点击打开。

        请注意，该文件必须小于 5 MB。

      如需使用 Google Cloud 控制台，请执行以下操作：

      1. 点击添加名称映射对。
      2. 在来源列的数据库、架构、关系和特性字段中，添加源对象名称的相应部分。
      3. 在目标列的相应字段中，添加 BigQuery 中的目标对象名称的各个部分。
      4. 在类型部分，选择描述您要映射的对象的对象类型。
      5. 重复第 1 - 4 步，直到指定完所需的所有名称映射对。请注意，使用 Google Cloud 控制台时，最多只能指定 25 个名称映射对。

    4. 可选。如需使用 Gemini 模型生成转换 AI 建议，请选中 Gemini AI 建议复选框。建议基于位于 Cloud Storage 目录中且以 .ai_config.yaml 结尾的配置 YAML 文件。每种类型的建议输出都保存在输出文件夹中自己的子目录中，命名格式为 REWRITETARGETSUGGESTION_TYPE_suggestion。例如，由 Gemini 增强的目标 SQL 自定义建议存储在 target_sql_query_customization_suggestion 中，而 Gemini 生成的转换说明存储在 translation_explanation_suggestion 中。如需了解如何为 AI 建议编写配置 YAML 文件，请参阅创建基于 Gemini 的配置 YAML 文件。

  11. 点击创建以启动转换作业。

创建转换作业后，您可以在转换作业列表中查看其状态。

批量转换客户端

  1. 安装批量转换客户端和 Google Cloud CLI。

  2. 生成 gcloud CLI 凭据文件。

  3. 在批量转换客户端安装目录中，使用您选择的文本编辑器打开 config.yaml 文件并修改以下设置：

    • project_number：输入要用于批量转换作业的项目的编号。您可以在项目的Google Cloud 控制台欢迎页面的项目信息窗格中找到此编号。
    • gcs_bucket：输入批量转换客户端在转换作业处理期间用来存储文件的 Cloud Storage 存储桶的名称。
    • input_directory：输入包含源文件和任何元数据文件的目录的绝对或相对路径。
    • output_directory：输入转换后文件的目标目录的绝对或相对路径。

  4. 保存更改并关闭 config.yaml 文件。

  5. 将源文件和元数据文件放在输入目录中。

  6. 使用以下命令运行批量转换客户端：

    bin/dwh-migration-client

    创建转换作业后，您可以在 Google Cloud 控制台的转换作业列表中查看其状态。

  7. 可选。转换作业完成后，便可以删除该作业在您指定的 Cloud Storage 存储桶中创建的文件，以避免产生存储费用。

浏览转换输出

运行转换作业后，您可以在 Google Cloud 控制台中查看有关该作业的信息。如果您使用 Google Cloud 控制台运行作业，则可以在您指定的目标 Cloud Storage 存储桶中查看作业结果。如果您使用批量转换客户端运行作业，则可以在您指定的输出目录中查看作业结果。批量 SQL 转换器会将以下文件输出到指定目标位置：