使用交互式 SQL 转换器来转换查询

本文档介绍如何使用 BigQuery 交互式 SQL 转换器将查询从其他 SQL 方言转换为 GoogleSQL 查询。当您将工作负载迁移到 BigQuery 时，交互式 SQL 转换器可以帮助减少时间和工作量。本文档适用于熟悉 Google Cloud 控制台的用户。

如果您的所在位置受支持，您可以使用转换规则功能（预览）自定义交互式 SQL 转换器转换 SQL 的方式。

限制

您必须登录 Google 账号才能使用交互式 SQL 转换器。交互式 SQL 转换器不支持使用联合身份。

准备工作

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

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

前往 BigQuery Migration API
点击启用。

权限和角色

本部分介绍使用交互式 SQL 转换器所需的 Identity and Access Management (IAM) 权限，包括授予这些权限的预定义 IAM 角色。本部分还介绍了设置其他转换配置所需的权限。

使用交互式 SQL 转换器所需的权限

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

此预定义角色可提供使用交互式转换器所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

如需使用交互式转换器，需要以下权限：

bigquerymigration.workflows.create
bigquerymigration.workflows.get

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

设置其他转换配置的权限

您可以使用转换设置中的转换配置 ID 和转换配置来源位置字段来设置其他转换配置。如需设置这些转换配置，您需要以下权限：

bigquerymigration.workflows.get
bigquerymigration.workflows.list

以下预定义的 IAM 角色提供了设置其他转换配置所需的权限：

roles/bigquerymigration.viewer

如需详细了解 BigQuery IAM，请参阅使用 IAM 进行访问权限控制。

支持的 SQL 语言

BigQuery 交互式 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 Spark SQL
Azure Synapse T-SQL
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

位置

交互式 SQL 转换器在以下处理位置提供：

	区域说明	区域名称	详情
亚太地区
	东京	`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`

转换规则功能可在以下处理位置使用：

us（美国多区域）
eu（欧盟多区域）
us-central1（爱荷华）
europe-west4（荷兰）

将查询转换为 GoogleSQL

请按照以下步骤将查询转换为 GoogleSQL：

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

转到 BigQuery
在编辑器窗格中，点击更多，然后选择转换设置。
在源方言部分，选择要转换的 SQL 方言。
可选。在处理位置部分，选择要运行转换作业的位置。例如，如果您在欧洲，并且不希望您的数据跨越任何位置边界，那么请选择 eu 区域。
点击保存。
在编辑器窗格中，点击更多，然后选择启用 SQL 转换。

编辑器窗格拆分为两个窗格。
在左侧窗格中，输入要转换的查询。
点击翻译。

BigQuery 会将查询转换为 GoogleSQL，并将其显示在右侧窗格中。例如，下面的屏幕截图显示了转换后的 Teradata SQL：
可选：如需运行转换后的 GoogleSQL 查询，请点击运行。
可选：如需返回到 SQL 编辑器，请点击更多，然后选择停用 SQL 转换。

编辑器窗格随即会恢复为单个窗格。

配置交互式 SQL 转换器

您可以配置交互式 SQL 转换器，以调整交互式 SQL 转换器转换源 SQL 的方式。为此，您可以提供自己的规则，以便在 YAML 配置文件中与 Gemini 搭配使用，或者提供包含 SQL 对象元数据或对象映射信息的配置 YAML 文件。

创建转换规则

您可以通过创建转换规则来自定义交互式 SQL 转换器转换 SQL 的方式。交互式 SQL 转换器会根据您为其分配的任何 Gemini 增强型 SQL 转换规则调整其转换结果，让您可以根据迁移需求自定义转换结果。只有某些位置支持此功能。

如需创建 Gemini 增强型 SQL 转换规则，请执行以下任一操作：

控制台

如需创建 Gemini 增强型 SQL 转换规则，请执行以下操作：

运行互动式转换后，点击自定义。
您可以使用以下任一提示或两者兼用来创建转换规则：
- 在将一个 SQL 模式替换为另一个提示中，在替换字段中指定要替换的 SQL 模式，并在替换为字段中指定要用来替换的 SQL 模式。
  
  SQL 模式可以在 SQL 脚本中包含任意数量的语句、子句或函数。当您使用此提示创建规则时，Gemini 增强型 SQL 转换会在转换输出中识别该 SQL 模式的所有实例，并将其动态替换为另一个 SQL 模式。例如，您可以使用此提示创建一个规则，将所有 months_between (X,Y) 都替换为 date_diff(X,Y,MONTH)。
- 在描述转换输出的变更字段中，用自然语言描述 SQL 转换输出的变更。
  
  当您使用此提示创建规则时，Gemini 增强型 SQL 转换会识别请求并对转换输出进行指定的更改。
点击预览。
在预览建议的更改对话框中，查看 Gemini 增强型 SQL 转换根据您的规则对转换输出所做的更改。
可选：如要添加此规则以供日后转换使用，请选中添加规则…复选框。

规则会保存在默认配置 YAML 文件（即 __default.ai_config.yaml）中。此配置 YAML 文件会保存到 Cloud Storage 文件夹中，如转换设置中的转换配置源位置字段中所指定。配置 YAML 文件最多可支持 10 条转换规则，并且会受到配置文件大小限制。
如需将建议的更改应用于转换输出，请点击应用。

YAML

您可以通过创建配置 YAML 文件并将其上传到 Cloud Storage 来创建 Gemini 增强型 SQL 转换规则。

要求

转换规则 YAML 文件的后缀必须为 .ai_config.yaml。例如 rules_1.ai_config.yaml

限制

您只能在交互式 SQL 转换器中应用一个转换规则 YAML 文件。
每个转换规则 YAML 文件最多支持 10 条规则，并且受配置文件大小限制的约束。

支持的字段

以下示例展示了如何使用自然语言提示创建 Gemini 增强型转换规则 YAML 文件。

rewrite_target: TARGET
instruction: NL_PROMPT

替换以下内容：

TARGET：指定要将转换规则应用于输入 SQL（SOURCE_SQL）还是输出 SQL（TARGET_SQL，默认值）。
NL_PROMPT：用自然语言描述对目标 SQL 所做的更改。Gemini 增强型 SQL 转换会识别请求并进行指定的更改

您还可以创建包含多条转换规则（最多 10 条）的转换规则 YAML 文件。每条规则可以包含一个描述规则的自然语言提示 (instruction)，以及一个或多个示例，以将一个 SQL 模式 (input) 替换为另一个 SQL 模式 (output)。转换规则可以使用 instruction 字段、一个或多个 examples 字段，也可以使用这两种类型的字段来描述您的规则。

rewrite_target: TARGET
instruction: NL_PROMPT
translation_rules:
- instruction: NL_RULE_1
  examples:
  - input: RULE_1_INPUT_1
    output: RULE_1_OUTPUT_1
  - input: RULE_1_INPUT_2
    output: RULE_1_OUTPUT_2
- instruction: NL_RULE_2
  examples:
  - input: RULE_2_INPUT_1
    output: RULE_2_OUTPUT_1
…
…

替换以下内容：

NL_RULE_1（可选）：用自然语言描述转换规则。
RULE_1_INPUT_1（可选）：您要替换的 SQL 模式。
RULE_1_OUTPUT_1（可选）：替换 input 后预期的 SQL 模式。

您可以根据需要添加更多 translation_rules（最多 10 个）和更多 examples。

如需查看 Gemini 增强型 SQL 转换规则 YAML 文件示例，请参阅转换规则 YAML 文件示例。

将转换规则 YAML 文件应用于下一次转换

如需应用转换规则 YAML 文件，请执行以下操作：

在查询编辑器中，点击更多 > 转换设置。
在转换配置源位置字段中，指定存储在 Cloud Storage 文件夹中的转换规则 YAML 文件的路径。
点击保存。

转换规则 YAML 文件示例

以下示例是 Gemini 增强型 SQL 转换规则 YAML 文件的示例。

示例 1：指定要替换的函数。

translation_rules:
- instruction:  "Remove upper() function"
  examples:
  - input: "upper(X)"
    output: "X"

示例 2：在单个 YAML 文件中指定多个转换规则。

translation_rules:
- instruction:  "Remove upper() function"
  examples:
  - input: "upper(X)"
    output: "X"
- instruction: "Insert a comment at the head that explains each statement in detail."

使用批量转换配置 ID 进行转换

您可以通过提供批量转换配置 ID，以与批量转换作业相同的转换配置运行交互式查询。

在查询编辑器中，点击更多 > 转换设置。
在转换配置 ID 字段中，提供批量转换配置 ID，以应用已完成的 BigQuery 批量迁移作业中的相同转换配置。

如需查找作业的批量转换配置 ID，请从 SQL 转换页面中选择一个批量转换作业，然后点击转换配置标签页。批量转换配置 ID 列为资源名称。
点击保存。

使用额外的配置进行转换

您可以通过指定存储在 Cloud Storage 文件夹中的配置 YAML 文件，运行包含其他转换配置的交互式查询。转换配置可能包含源数据库中的 SQL 对象元数据或对象映射信息，这些信息可以提高转换质量。例如，添加源数据库中的 DDL 信息或架构可以提高交互式 SQL 转换质量。

如需通过提供转换配置源文件的位置来指定转换配置，请执行以下操作：

在查询编辑器中，点击更多 > 转换设置。
在转换配置来源位置字段中，指定存储在 Cloud Storage 文件夹中的转换配置文件的路径。

BigQuery 交互式 SQL 转换器支持包含转换元数据和对象名称映射的配置文件。如需了解如何将文件上传到 Cloud Storage，请参阅从文件系统上传对象。
点击保存。

配置文件大小限制

将转换配置文件与 BigQuery 交互式 SQL 转换器搭配使用时，压缩后的元数据文件或 YAML 配置文件的大小必须小于 50 MB。如果文件大小超过 50 MB，交互式转换器会在转换期间跳过该配置文件，并生成类似于以下内容的错误消息：

CONFIG ERROR: Skip reading file "gs://metadata-file.zip". File size (150,000,000 bytes) exceeds limit (50 MB).

减小元数据文件大小的一种方法是使用 --database 或 --schema 标志，以便仅提取与转换输入查询相关的数据库或架构的元数据。如需详细了解如何在生成元数据文件时使用这些标志，请参阅全局标志。

排查转换错误

以下是使用交互式 SQL 转换器时常见的错误。

`RelationNotFound` 或 `AttributeNotFound` 转换问题

为了确保最准确的转换，您可以在查询之前输入查询中使用的任何表的数据定义语言 (DDL) 语句。例如，如果要转换 Amazon Redshift 查询 select table1.field1, table2.field1 from table1, table2 where table1.id = table2.id;，您需要将以下 SQL 语句输入到交互式 SQL 转换器中：

create table schema1.table1 (id int, field1 int, field2 varchar(16));
create table schema1.table2 (id int, field1 varchar(30), field2 date);

select table1.field1, table2.field1
from table1, table2
where table1.id = table2.id;

价格

使用交互式 SQL 转换器无需付费。但是，用于存储输入和输出文件的存储空间会产生正常费用。如需了解详情，请参阅存储价格。

后续步骤

详细了解迁移数据仓库的以下步骤：