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（Migration Workflow 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 のクリーンアップ：Cloud Storage と BigQuery の利用状況について、 Google Cloud の料金を確認してください。バッチ移行が完了したら、Cloud Storage 内の一時的なステージング済み入力フォルダーと出力フォルダーを削除します。

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

6. 変換の追跡：バッチ変換や、複数回の変換が必要なクエリでは、目標、予定している手順、進捗を記録する変換トラッカー（例： translation_tracker.md）を用意します。 変換のたびに、以下のテンプレートを使って 1 行を記録してください。

   イテレーション	ステータス	エラーの合計	正確性エラー	完全性エラー	互換性エラー	主な対応／変換

   1 回目の試行で問題なく変換できた単一のクエリには、トラッカーは不要です。回答には変換 ID とログを記載してください。

ワークフローの選択

移行の範囲に応じてワークフローを選択します。

• インタラクティブ変換（単一クエリ）：アドホックなクエリ、探索的テスト、方言構文の比較、または迅速なエラーデバッグに最適です。
• バッチ変換（複数ファイルと Cloud Storage）：複数のファイルやディレクトリを変換する場合に使用します。アプリケーションコードに埋め込まれた SQL も対象です（最初に .sql ファイルへ抽出してください）。SQL を埋め込んだ複数ファイルの Python コードベースでは、 python_embedded_sql_migrator_template.py を使用してクエリをステージング済みファイルに抽出し、変換後の SQL を再度挿入します。バッチ変換は、ファイルを 1 つずつ変換するより高速かつ低コストで、ファイル間の依存関係も解決するため、通常はより良い結果が得られます。最初にステージング済みファイルに対して translate_batch_queries を実行し、必要な場合に限り、その後 translation_report.csv の特定のステートメントをデバッグするために translate_query を使用します。

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 プロジェクトが利用できる場合は、結果をドライランします（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 に同じ名前の関数があっても、 未変換として扱います。テーブル不足でドライランが停止した場合、その関数はチェックされません。
   • ソース方言に注意点のリファレンスがある場合は（ 方言固有の注意点を参照）、それを読み、記載されているパターンが出力に ないか確認します。意味上の違いによってはログ項目が出ず、ドライランにも合格することがあります。

4. 問題がなくなるまで繰り返す：ログにエラーや警告が含まれている場合、変換後の SQL に ERROR_TYPE または インラインのエラーコメントが含まれている場合、ドライランが失敗した場合、または出力が方言固有の注意点に 該当する場合は、変換の問題を解決するに記載された方法で問題を解決し、 再度変換します。

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）：projectNumber、 location、sourceDialect、targetDialect、sourceBaseUri、および targetBaseUriを指定して、translate_batch_queriesを呼び出します。
   • メタデータ ZIP ファイルの変換（translate_metadata）：抽出した データベースメタデータ ZIP ファイル（Teradata、Oracle などの metadata.zip）から移行先の BigQuery DDL スキーマ定義を生成して バッチ変換を支援するには、sourceBaseUri（metadata.zipの Cloud Storage URI）とtargetBaseUri（出力先の Cloud Storage フォルダー）を指定して translate_metadataを呼び出します。

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 の 再挿入後に残る可能性のあるエラーが記載されています。

翻訳に関する問題の解決

どちらのワークフローでも、問題は同じ方法で解決します。

• 各問題の影響（CORRECTNESS、COMPLETENESS、COMPATIBILITY）を特定し、コンパイラのフェーズ依存関係に従って順番に解決します。まずCORRECTNESS（解析エラー）、次にCOMPLETENESS（オブジェクトの不足）、最後にCOMPATIBILITY（未対応の機能）に対応します。
• 修正を適用する前に、エラーの影響別トラブルシューティングにある各影響のリファレンスガイドを必ず読み、そこに記載された解決ワークフローに従ってください。
• 修正では、入力の前処理（例：DDL の追加）や、BigQuery Migration Service（BQMS）の出力の後処理（例：方言に関する注意点で必要とされる書き換え）を行えます。自分で翻訳するのではなく、前処理した入力に対して BigQuery Migration Service（BQMS）を実行してください。
• 再翻訳する場合は、常にソースシステムの方言を使用してください。同じ SQL を別の方言で受け入れられる場合でも、異なるセマンティクス（例：戻り値の型、数値型、識別子の大文字・小文字）で翻訳される可能性があるため、よりきれいな出力を得る目的で方言を切り替えないでください。
• 最適化など、ユーザーの依頼によるものも含め、BigQuery Migration Service（BQMS）の出力を書き換える場合は、ソースクエリと同じ行を返す必要があります。たとえば、行数制限（TOP、LIMIT）の後に実行されるフィルターを、行数制限の前に実行されるクエリに統合することはできません。
• 再翻訳が完了するまで待ち、その翻訳 ID、エラー件数、前処理または後処理の内容をトラッカーに記録し、前回の反復時の件数と比較してください。エラーがなくなるか、すべての選択肢を使い切るまで繰り返します。
• トラッカーに記録された反復での最終 SQL、適用した前処理と後処理、残っているエラーを報告してください。

リファレンス検索インデックス

エラーのトラブルシューティングや設定ファイルの作成には、以下のリファレンスガイドを使用してください。

エラーの影響別トラブルシューティング

影響	主な原因	リファレンスガイド
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