bigquery-migration-sql-translator

BigQuery Migration Service（BQMS）SQL 转换器

BigQuery Migration Service（BQMS）可将旧版数据库 SQL 脚本、查询和架构转换为 GoogleSQL。此技能用于协调转换工作流、Cloud Storage 暂存、编译器错误排查和 YAML 配置。

开始之前

在转换查询或架构之前，请确认以下前提条件：

1. Google Cloud SDK 和项目设置：确保已安装 Google Cloud SDK， 确认 Google Cloud 项目已关联有效的 Cloud Billing 账号，并选择目标项目：

   gcloud config set project {project_id}
   

2. 启用 API：在 Google Cloud 项目中启用 BigQuery Migration API （bigquerymigration.googleapis.com）：

   gcloud services enable bigquerymigration.googleapis.com
   

3. 所需 IAM 角色：确认你的身份或服务账号拥有以下角色：

   • roles/mcp.toolUser（MCP 工具用户）
   • roles/bigquerymigration.editor（迁移工作流编辑者）
   • 对于批量转换，需对存放输入和输出文件的 Cloud Storage 存储桶拥有 roles/storage.objectViewer 和 roles/storage.objectCreator（或 roles/storage.objectAdmin）。

4. MCP 服务连接：如果当前工具列表中没有 BigQuery Migration Service（BQMS）工具（例如 translate_query、translate_batch_queries），请配置远程 BigQuery Migration Service（BQMS）MCP 服务。有关各客户端（Claude、Cursor、Gemini CLI、VS Code）的设置说明，请参阅 mcp_config.md。

5. 费用和 Cloud Storage 清理：查看 Google Cloud 定价，了解 Cloud Storage 和 BigQuery 的使用费用详情。完成批量迁移后，请清理 Cloud Storage 中暂存的临时输入和输出文件夹：

   gcloud storage rm -r gs://{bucket}/{folder}
   

6. 转换跟踪：对于批量转换，以及需要多轮转换的查询，请维护转换跟踪文件（例如 translation_tracker.md），记录目标、计划步骤和进度。 每次转换后，使用以下模板记录一行：

   迭代	状态	错误总数	正确性错误	完整性错误	兼容性错误	关键操作 / 转换

   首次尝试即可顺利转换的单个查询无需跟踪文件：在回复中报告其转换 ID 和日志。

工作流选择

根据迁移范围选择工作流：

• 交互式转换（单个查询）：适用于临时查询、探索性测试、方言语法比较或快速调试错误。
• 批量转换（多个文件和 Cloud Storage）：适用于多个文件或一个目录，包括嵌入应用代码中的 SQL（请先将其提取到 .sql 文件中）。对于包含嵌入式 SQL 的多文件 Python 代码库，请使用 python_embedded_sql_migrator_template.py 将查询提取到暂存文件中，并重新注入已转换的 SQL。批量转换比逐个转换文件更快、成本更低，还能解析跨文件依赖，因此通常可获得更好的结果。先对暂存文件运行 translate_batch_queries；之后如有需要，再使用 translate_query 调试 translation_report.csv 中的特定语句。

1. 交互式转换工作流

使用交互式工作流转换单个查询字符串、检查编译器日志并逐步解决问题。

步骤

1. 提交查询（translate_query）：使用 projectNumber、location、inputQuery、sourceDialect 和 targetDialect（BigQuery）调用 translate_query。可选参数包括：

   • metadataFilePath：用于解析架构的元数据 ZIP 文件的 Cloud Storage URI（gs://.../metadata.zip）。
   • translationConfigs：内联 YAML 配置（例如对象重命名、架构重定向、优化器规则）。在回复中展示所用的 YAML，以便用户重用（例如用于批量转换）。

2. 轮询状态（get_translation）：如果返回的 translation_state 为 RUNNING 或 PENDING，则使用 translation ID、projectNumber 和 location 轮询 get_translation，直到 translation.state 为 SUCCEEDED 或 FAILED，轮询间隔遵循 BigQuery Migration Service（BQMS）MCP 工具说明。任务运行期间，可处理不依赖结果的工作（例如阅读方言注意事项参考）。

3. 检查输出和日志：

   • 检查 translated_query 中转换后的 GoogleSQL。
   • 检查 translation_logs 中的每个条目：查看 severity（ERROR、WARNING）、category（例如 RelationNotFound）和 effect（CORRECTNESS、COMPLETENESS、COMPATIBILITY）。
   • 检查 SQL 本身，不要只看日志：BigQuery Migration Service（BQMS）会为无法映射的类型输出 ERROR_TYPE(...)，有时不会生成日志条目。将任何 ERROR_TYPE 或内联错误注释视为错误；如果有 BigQuery 项目，则对结果进行 dry run（bq query --dry_run --use_legacy_sql=false）。Not found 或 must be qualified with a dataset 错误仍表示 SQL 语法有效，只是 BigQuery 中尚不存在所引用的对象。请说明这一点并继续，即使错误提示了修复方法也不要创建占位表，也不要更改 SQL 或 bq 标志来绕过错误。
   • NoSuchFunction 错误表示 BigQuery Migration Service（BQMS）原样复制了该调用，有时函数名会用反引号括起。即使 BigQuery 中存在同名函数，也要将其视为未转换：如果 dry run 因缺少表而停止，就不会检查该函数。
   • 如果源方言有注意事项参考（参见方言特定注意事项），请阅读该参考，并检查输出中是否存在其中列出的模式。某些语义差异不会生成日志条目，dry run 也仍可能通过。

4. 反复处理直至无问题：如果日志中包含错误或警告、转换后的 SQL 包含 ERROR_TYPE 或内联错误注释、dry run 失败，或输出符合某项方言注意事项，请按照解决转换问题中所述解决问题，然后重新转换。

5. 说明并比较差异（explain_translation）：如果用户要求解释转换、比较语法差异，或了解特定查询逻辑的转换方式，请使用 translation（转换 ID）、projectNumber 和 location 调用 explain_translation。此工具会返回查询用途的结构化说明，并详细列出源查询与转换后的 GoogleSQL 在语法、函数和行为方面的差异。该说明不会验证输出，因此请按照步骤 3 检查转换结果，不要仅依赖该说明。

2. 批量转换工作流

批量转换用于处理暂存于 Cloud Storage 中的多个文件。它会解析跨文件依赖项，并生成整合的转换摘要报告（translation_report.csv）。

步骤

1. 将输入文件暂存到云存储：将原始 SQL 文件、配置文件（*.config.yaml）以及任何元数据文件，从本地工作区上传到 Cloud Storage 输入文件夹：

   gcloud storage cp input/*.sql gs://my-bucket/migration/input/
   gcloud storage cp *.config.yaml gs://my-bucket/migration/input/
   

   注意：如果配置文件已位于 sourceBaseUri 中，请勿在工具参数中传入配置文件路径。

   每次运行都使用新的空 Cloud Storage 输入和输出文件夹（例如，添加时间戳后缀）。仅暂存来自本地工作区或在本次运行中生成的文件。切勿重用或复制存储桶中先前运行留下的输入、DDL 或输出：它们可能来自不同的输入或设置。

2. 启动批量转换：

   • 转换 SQL 查询（translate_batch_queries）：调用 translate_batch_queries，并传入 projectNumber、location、sourceDialect、targetDialect、sourceBaseUri 和 targetBaseUri。
   • 转换元数据 Zip 文件（translate_metadata）：为辅助批量转换，可从提取的数据库元数据 Zip 文件（例如 Teradata、Oracle 等提供的 metadata.zip）生成目标 BigQuery DDL 架构定义。调用 translate_metadata，并指定 sourceBaseUri（指向 metadata.zip 的 Cloud Storage URI）和 targetBaseUri（目标 Cloud Storage 文件夹）。

3. 轮询完成状态（fetch_batch_translation）：使用返回的工作流 ID 进行轮询，直到 translation.state 为 SUCCEEDED 或 FAILED。轮询间隔请遵循 BigQuery Migration Service（BQMS）MCP 工具说明中的要求。

4. 获取并检查输出：从 translation.target_base_uri 下载生成的文件：

   gcloud storage cp -r gs://my-bucket/migration/output/ ./local_output/
   

   找到并检查 report/translation_report.csv，以查看所有警告、错误和行级诊断。随后检查生成的 .sql 文件中的 ERROR_TYPE(...) 和内联错误注释，因为报告可能会遗漏这些内容；如果有可用的 BigQuery 项目，还应对生成的 SQL 执行试运行（按交互式工作流中的方式处理 Not found 错误）。检查输出中是否存在源方言注意事项参考文档中列出的模式（如果有）。解决或明确报告所有剩余问题；完成此检查前，不要将输出描述为无问题。

5. 迭代直至无问题：按照解决转换问题中所述解决第 4 步发现的问题，并使用修改后的输入从第 1 步重新运行。

6. 后处理（仅限最后一步）：只有在解决所有可通过重新转换修复的编译器错误后，才能执行任何应用级后处理（例如，重新注入 AST），以恢复宿主源文件。effect_correctness.md 列出了重新注入嵌入式 SQL 时可能残留的错误。

解决翻译问题

两种工作流都以相同的方式解决问题：

• 确定每个问题的 Effect（CORRECTNESS、COMPLETENESS、COMPATIBILITY），并按照编译器阶段的依赖关系依次解决：先处理 CORRECTNESS（解析错误），再处理 COMPLETENESS（缺失对象），最后处理 COMPATIBILITY（不受支持的功能）。
• 必须先阅读 按错误影响排查 中对应 Effect 的参考指南，再应用修复，并遵循其中的解决流程。
• 修复可以预处理输入（例如，添加 DDL），也可以后处理 BigQuery Migration Service (BQMS) 的输出（例如，按方言注意事项的要求进行重写）。应对预处理后的输入运行 BigQuery Migration Service (BQMS)，而不是自行翻译。
• 每次重新翻译都要保留源系统的方言。其他方言可能也接受相同的 SQL，但翻译后的语义可能不同（例如，返回类型、数值类型或标识符大小写），因此不要为了得到更整洁的输出而切换方言。
• 重写 BigQuery Migration Service (BQMS) 的输出（包括用户要求的优化）必须返回与源查询相同的行。例如，在行数限制（TOP、LIMIT）之后执行的筛选，不能合并到限制之前的查询中。
• 等待每次重新翻译完成，在跟踪记录中记录其翻译 ID、错误数量以及任何预处理或后处理，并与上一次迭代的数量进行比较。重复此过程，直至没有错误或所有选项均已用尽。
• 报告跟踪记录中最新迭代的最终 SQL、所应用的预处理和后处理，以及仍然存在的错误。

参考资料索引

排查错误或编写配置文件时，请使用以下参考指南：

按错误影响排查

Effect	常见原因	参考指南
CORRECTNESS	语法错误、未转义的字面量、应用脚本包装器、NoSuchFunction。	effect_correctness.md
COMPLETENESS	缺失的表、视图、列（RelationNotFound、AttributeNotFound）、DDL 建议。	effect_completeness.md
COMPATIBILITY	没有直接 GoogleSQL 映射的函数或功能。	effect_compatibility.md

配置与设置指南

任务	描述	参考指南
YAML 配置	数据库／架构重定向、名称映射、表分区和聚簇注入、优化器转换、语句重写器以及环境设置。架构位于 assets/translation_config_schemas/，示例位于 assets/translation_config_examples/。	translation_yaml_config.md
MCP 服务设置	配置远程 BigQuery Migration Service (BQMS) MCP 服务、OAuth 作用域和 IAM 角色。	mcp_config.md

特定方言的注意事项

方言	主要注意事项	参考指南
Teradata	SET／MULTISET 表、SAMPLE 子句、主索引映射。	teradata_gotchas.md
Oracle	PL/SQL 过程、ROWNUM 仿真、外连接 (+)、序列。	oracle_gotchas.md
Snowflake	动态模板、USE 语句、元数据合并、横向连接。	snowflake_gotchas.md