本页面上的部分或全部信息可能不适用于 Trusted Cloud by S3NS。

此页面由 Cloud Translation API 翻译。

使用 Translation API 转换 SQL 查询

本文档介绍了如何使用 BigQuery 中的转换 API 将用其他 SQL 方言编写的脚本转换为 GoogleSQL 查询。 Translation API 可以简化将工作负载迁移到 BigQuery 的过程。

准备工作

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

确保您拥有所需的所有权限。
启用 BigQuery Migration API。
收集包含待转换的 SQL 脚本和查询的源文件。
将源文件上传到 Cloud Storage。

所需权限

如需获得使用转换 API 创建转换作业所需的权限，请让您的管理员为您授予 parent 资源的 MigrationWorkflow Editor (roles/bigquerymigration.editor) IAM 角色。如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

此预定义角色可提供使用转换 API 创建转换作业所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

使用转换 API 创建转换作业需要以下权限：

bigquerymigration.workflows.create
bigquerymigration.workflows.get

您也可以使用自定义角色或其他预定义角色来获取这些权限。

启用 BigQuery Migration API

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

在 Trusted Cloud 控制台中，前往 BigQuery Migration API 页面。

前往 BigQuery Migration API
点击启用。

将输入文件上传到 Cloud Storage

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

支持的任务类型

转换 API 可以将以下 SQL 方言转换为 GoogleSQL：

Amazon Redshift SQL - Redshift2BigQuery_Translation
Apache HiveQL 和 Beeline CLI - HiveQL2BigQuery_Translation
Apache Spark SQL - SparkSQL2BigQuery_Translation
Azure Synapse T-SQL - AzureSynapse2BigQuery_Translation
Greenplum SQL - Greenplum2BigQuery_Translation
IBM Db2 SQL - Db22BigQuery_Translation
IBM Netezza SQL 和 NZPLSQL - Netezza2BigQuery_Translation
MySQL SQL - MySQL2BigQuery_Translation
Oracle SQL、PL/SQL、Exadata - Oracle2BigQuery_Translation
PostgreSQL SQL - Postgresql2BigQuery_Translation
Presto 或 Trino SQL - Presto2BigQuery_Translation
Snowflake SQL - Snowflake2BigQuery_Translation
SQLite - SQLite2BigQuery_Translation
SQL Server T-SQL - SQLServer2BigQuery_Translation
Teradata 和 Teradata Vantage - Teradata2BigQuery_Translation
Vertica SQL - Vertica2BigQuery_Translation

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

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

这些 UDF 通常位于 bqutil 公共数据集中，这样翻译后的查询便可使用 bqutil.<dataset>.<function>() 格式初始引用它们。例如 bqutil.fn.cw_count()。

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

虽然 bqutil 提供了便捷的方式来访问这些辅助 UDF 以进行初始转换和测试，但出于以下几点原因，不建议在生产工作负载中直接依赖 bqutil：

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

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

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

位置

Translation API 可在以下处理位置使用：

	区域说明	区域名称	详情
亚太地区
	德里	`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
	达曼	`me-central2`
	多哈	`me-central1`
	以色列	`me-west1`

提交转换作业

如需使用转换 API 提交转换作业，请使用 projects.locations.workflows.create 方法，并为 MigrationWorkflow 资源实例提供受支持的任务类型。

提交作业后，您可以发出查询以获取结果。

创建批量转换

以下 curl 命令会创建一个批量转换作业，其中的输入和输出文件存储在 Cloud Storage 中。source_target_mapping 字段包含一个列表，用于将源 literal 条目映射到目标输出的可选相对路径。

curl -d "{
  \"tasks\": {
      string: {
        \"type\": \"TYPE\",
        \"translation_details\": {
            \"target_base_uri\": \"TARGET_BASE\",
            \"source_target_mapping\": {
              \"source_spec\": {
                  \"base_uri\": \"BASE\"
              }
            },
            \"target_types\": \"TARGET_TYPES\",
        }
      }
  }
  }" \
  -H "Content-Type:application/json" \
  -H "Authorization: Bearer TOKEN" -X POST https://bigquerymigration.googleapis.com/v2alpha/projects/PROJECT_ID/locations/LOCATION/workflows

替换以下内容：

TYPE：转换的任务类型，用于确定源和目标方言。
TARGET_BASE：所有转换输出的基本 URI。
BASE：作为转换来源读取的所有文件的基本 URI。
TARGET_TYPES（可选）：生成的输出类型。如果未指定，则系统会生成 SQL。
- sql（默认）：转换后的 SQL 查询文件。
- suggestion：AI 生成的建议。
输出结果存储在输出目录的子文件夹中。子文件夹的命名方式取决于 TARGET_TYPES 中的值。
TOKEN：用于身份验证的令牌。如需生成令牌，请使用 gcloud auth print-access-token 命令或 OAuth 2.0 Playground（使用范围 https://www.googleapis.com/auth/cloud-platform）。
PROJECT_ID：处理转换的项目。
LOCATION：处理作业的位置。

上述命令会返回一个响应，其中包含以 projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID 格式编写的工作流 ID。

批量翻译示例

如需转换 Cloud Storage 目录 gs://my_data_bucket/teradata/input/ 中的 Teradata SQL 脚本，并将结果存储在 Cloud Storage 目录 gs://my_data_bucket/teradata/output/ 中，您可以使用以下查询：

{
  "tasks": {
     "task_name": {
       "type": "Teradata2BigQuery_Translation",
       "translation_details": {
         "target_base_uri": "gs://my_data_bucket/teradata/output/",
           "source_target_mapping": {
             "source_spec": {
               "base_uri": "gs://my_data_bucket/teradata/input/"
             }
          },
       }
    }
  }
}

此调用会在 "name" 字段中返回包含所创建工作流 ID 的消息：

{
  "name": "projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00",
  "tasks": {
    "task_name": { /*...*/ }
  },
  "state": "RUNNING"
}

如需获取工作流更新后的状态，请运行 GET 查询。作业会在运行过程中将输出发送到 Cloud Storage。生成所有请求的 target_types 后，作业 state 会更改为 COMPLETED。如果任务成功，您可以在 gs://my_data_bucket/teradata/output 中找到经过转换的 SQL 查询。

包含 AI 建议的批量翻译示例

以下示例会翻译位于 gs://my_data_bucket/teradata/input/ Cloud Storage 目录中的 Teradata SQL 脚本，并将结果存储在 Cloud Storage 目录 gs://my_data_bucket/teradata/output/ 中，同时提供额外的 AI 建议：

{
  "tasks": {
     "task_name": {
       "type": "Teradata2BigQuery_Translation",
       "translation_details": {
         "target_base_uri": "gs://my_data_bucket/teradata/output/",
           "source_target_mapping": {
             "source_spec": {
               "base_uri": "gs://my_data_bucket/teradata/input/"
             }
          },
          "target_types": "suggestion",
       }
    }
  }
}

任务成功运行后，您可以在 gs://my_data_bucket/teradata/output/suggestion Cloud Storage 目录中找到 AI 建议。

使用字符串字面量输入和输出创建交互式转换作业

以下 curl 命令会使用字符串字面量输入和输出创建转换作业。source_target_mapping 字段包含一个列表，用于将源目录映射到目标输出的可选相对路径。

curl -d "{
  \"tasks\": {
      string: {
        \"type\": \"TYPE\",
        \"translation_details\": {
        \"source_target_mapping\": {
            \"source_spec\": {
              \"literal\": {
              \"relative_path\": \"PATH\",
              \"literal_string\": \"STRING\"
              }
            }
        },
        \"target_return_literals\": \"TARGETS\",
        }
      }
  }
  }" \
  -H "Content-Type:application/json" \
  -H "Authorization: Bearer TOKEN" -X POST https://bigquerymigration.googleapis.com/v2alpha/projects/PROJECT_ID/locations/LOCATION/workflows

替换以下内容：

TYPE：转换的任务类型，用于确定源和目标方言。
PATH：字面量条目的标识符，类似于文件名或路径。
STRING：要转换的字面量输入数据（例如 SQL）字符串。
TARGETS：用户希望在响应中直接返回的预期目标，格式为 literal。这些 URI 应采用目标 URI 格式（例如 GENERATED_DIR + target_spec.relative_path + source_spec.literal.relative_path）。此列表中未包含的任何内容都不会在响应中返回。为常规 SQL 转换生成的目录 GENERATED_DIR 是 sql/。
TOKEN：用于身份验证的令牌。如需生成令牌，请使用 gcloud auth print-access-token 命令或 OAuth 2.0 Playground（使用范围 https://www.googleapis.com/auth/cloud-platform）。
PROJECT_ID：处理转换的项目。
LOCATION：处理作业的位置。

上述命令会返回一个响应，其中包含以 projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID 格式编写的工作流 ID。

作业完成后，您可以通过查询作业并检查工作流完成后响应中的内嵌 translation_literals 字段来查看结果。

交互式转换示例

如需以交互方式转换 Hive SQL 字符串 select 1，您可以使用以下查询：

"tasks": {
  string: {
    "type": "HiveQL2BigQuery_Translation",
    "translation_details": {
      "source_target_mapping": {
        "source_spec": {
          "literal": {
            "relative_path": "input_file",
            "literal_string": "select 1"
          }
        }
      },
      "target_return_literals": "sql/input_file",
    }
  }
}

您可以为字面量使用所需的任何 relative_path，但只有在 target_return_literals 中包含 sql/$relative_path 时，转换后的字面量才会显示在结果中。您还可以在单个查询中包含多个字面量，在这种情况下，必须在 target_return_literals 中包含它们的每个相对路径。

此调用会在 "name" 字段中返回包含所创建工作流 ID 的消息：

{
  "name": "projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00",
  "tasks": {
    "task_name": { /*...*/ }
  },
  "state": "RUNNING"
}

如需获取工作流更新后的状态，请运行 GET 查询。当 "state" 更改为 COMPLETED 时，表示作业已完成。如果任务成功，您会在响应消息中找到经过翻译的 SQL：

{
  "name": "projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00",
  "tasks": {
    "string": {
      "id": "0fedba98-7654-3210-1234-56789abcdef",
      "type": "HiveQL2BigQuery_Translation",
      /* ... */
      "taskResult": {
        "translationTaskResult": {
          "translatedLiterals": [
            {
              "relativePath": "sql/input_file",
              "literalString": "-- Translation time: 2023-10-05T21:50:49.885839Z\n-- Translation job ID: projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00\n-- Source: input_file\n-- Translated from: Hive\n-- Translated to: BigQuery\n\nSELECT\n    1\n;\n"
            }
          ],
          "reportLogMessages": [
            ...
          ]
        }
      },
      /* ... */
    }
  },
  "state": "COMPLETED",
  "createTime": "2023-10-05T21:50:49.543221Z",
  "lastUpdateTime": "2023-10-05T21:50:50.462758Z"
}

浏览转换输出

运行转换作业后，通过使用以下命令指定转换作业工作流 ID 来检索结果：

curl \
-H "Content-Type:application/json" \
-H "Authorization:Bearer TOKEN" -X GET https://bigquerymigration.googleapis.com/v2alpha/projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID

替换以下内容：

TOKEN：用于身份验证的令牌。如需生成令牌，请使用 gcloud auth print-access-token 命令或 OAuth 2.0 Playground（使用范围 https://www.googleapis.com/auth/cloud-platform）。
PROJECT_ID：处理转换的项目。
LOCATION：处理作业的位置。
WORKFLOW_ID：创建转换工作流时生成的 ID。

响应包含迁移工作流的状态以及 target_return_literals 中所有已完成的文件。

响应将包含迁移工作流的状态以及 target_return_literals 中所有已完成的文件。您可以轮询此端点以检查工作流的状态。