使用 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：

在 Google Cloud 控制台中，转到 BigQuery Migration API 页面。

前往 BigQuery Migration API
点击启用。

将输入文件上传到 Cloud Storage

如果您要使用 Google 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

位置

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

	区域说明	区域名称	详情
亚太地区
	东京	`asia-northeast1`
	孟买	`asia-south1`
	新加坡	`asia-southeast1`
	悉尼	`australia-southeast1`
欧洲
	欧盟多区域	`eu`
	华沙	`europe-central2`
	芬兰	`europe-north1`	二氧化碳排放量低
	马德里	`europe-southwest1`	二氧化碳排放量低
	比利时	`europe-west1`	二氧化碳排放量低
	伦敦	`europe-west2`	二氧化碳排放量低
	法兰克福	`europe-west3`	二氧化碳排放量低
	荷兰	`europe-west4`	二氧化碳排放量低
	苏黎世	`europe-west6`	二氧化碳排放量低
	巴黎	`europe-west9`	二氧化碳排放量低
	都灵	`europe-west12`
美洲
	圣保罗	`southamerica-east1`	二氧化碳排放量低
	美国多区域	`us`
	艾奥瓦	`us-central1`	二氧化碳排放量低
	南卡罗来纳	`us-east1`
	北弗吉尼亚	`us-east4`
	俄亥俄州，哥伦布	`us-east5`
	达拉斯	`us-south1`	二氧化碳排放量低
	俄勒冈	`us-west1`	二氧化碳排放量低
	洛杉矶	`us-west2`
	盐湖城	`us-west3`

提交转换作业

如需使用转换 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\"
              }
            },
        }
      }
  }
  }" \
  -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。
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 查询。当 "state" 更改为 COMPLETED 时，表示作业已完成。如果任务成功完成，则转换后的 SQL 可在 gs://my_data_bucket/teradata/output 中找到。

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

以下 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 格式（例如 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 中所有已完成的文件。您可以轮询此端点以检查工作流的状态。