インタラクティブな SQL トランスレータを使用してクエリを変換する

このドキュメントでは、BigQuery のインタラクティブ SQL トランスレータを使用して、別の SQL 言語のクエリを GoogleSQL クエリに変換する方法について説明します。インタラクティブ SQL トランスレータを使用すると、ワークロードを BigQuery に移行する時間と労力を削減できます。このドキュメントは、Google Cloud コンソールに慣れている方を対象としています。

ロケーションがサポートされている場合は、変換ルール機能を使用して、インタラクティブ SQL 変換ツールによる SQL の変換方法をカスタマイズできます。

始める前に

2022 年 2 月 15 日より前に Google Cloud CLI プロジェクトを作成した場合、次のように BigQuery Migration API を有効にします。

Google Cloud コンソールで、BigQuery Migration API のページに移動します。

BigQuery Migration API に移動
[有効にする] をクリックします。

権限とロール

このセクションでは、インタラクティブ SQL トランスレータを使用するために必要な Identity and Access Management（IAM）権限（それらの権限を付与する IAM 事前定義ロールを含む）について説明します。また、追加の変換構成を構成するために必要な権限についても説明します。

インタラクティブ SQL トランスレータを使用するための権限

インタラクティブトランスレータの使用に必要な権限を取得するには、parent リソースに対する MigrationWorkflow 編集者（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
- 基本的な Teradata Query（BTEQ）
- Teradata Parallel Transport（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

ヘルパー UDF を使用してサポートされていない SQL 関数を処理する

ソース言語から BigQuery に SQL を変換する場合、一部の関数には直接対応するものがないことがあります。この問題に対処するために、BigQuery Migration Service（およびより広い BigQuery コミュニティ）では、サポートされていない元のソース言語の関数の動作を再現する補助的なユーザー定義関数（UDF）を提供しています。

これらの UDF は bqutil 一般公開データセットに存在することが多く、変換されたクエリは最初に bqutil.<dataset>.<function>() 形式を使用して参照できます。例: bqutil.fn.cw_count()

本番環境に関する重要な考慮事項:

bqutil は、初期の変換とテストにこれらのヘルパー UDF への便利なアクセスを提供しますが、本番環境のワークロードで bqutil に直接依存することは、いくつかの理由から推奨されません。

バージョン管理: bqutil プロジェクトにはこれらの UDF の最新バージョンがホストされているため、定義は時間の経過とともに変化する可能性があります。bqutil に直接依存すると、UDF のロジックが更新された場合に、本番環境のクエリで予期しない動作や破壊的変更が発生する可能性があります。
依存関係の分離: UDF を独自のプロジェクトにデプロイすると、本番環境が外部の変更から分離されます。
カスタマイズ: 特定のビジネスロジックやパフォーマンス要件に合わせて、これらの UDF を変更または最適化する必要が生じる場合があります。これは、ユーザーが自分のプロジェクト内にいる場合にのみ可能です。
セキュリティとガバナンス: 組織のセキュリティポリシーにより、本番環境のデータ処理で bqutil などの一般公開データセットへの直接アクセスが制限されることがあります。UDF を制御された環境にコピーすることは、このようなポリシーに沿ったものです。

ヘルパー UDF をプロジェクトにデプロイする:

信頼性が高く安定した本番環境で使用するには、これらのヘルパー UDF を独自のプロジェクトとデータセットにデプロイする必要があります。これにより、バージョン、カスタマイズ、アクセスを完全に制御できます。これらの UDF をデプロイする手順については、GitHub の UDF デプロイガイドをご覧ください。このガイドでは、UDF を環境にコピーするために必要なスクリプトと手順について説明します。

ロケーション

インタラクティブ SQL 変換ツールは、次のロケーションで使用できます。

	リージョンの説明	リージョン名	詳細
アジア太平洋
	デリー	`asia-south2`
	香港	`asia-east2`
	ジャカルタ	`asia-southeast2`
	メルボルン	`australia-southeast2`
	ムンバイ	`asia-south1`
	大阪	`asia-northeast2`
	ソウル	`asia-northeast3`
	シンガポール	`asia-southeast1`
	シドニー	`australia-southeast1`
	台湾	`asia-east1`
	東京	`asia-northeast1`
ヨーロッパ
	ベルギー	`europe-west1`	低 CO₂
	ベルリン	`europe-west10`	低 CO₂
	EU（マルチリージョン）	`eu`
	フィンランド	`europe-north1`	低 CO₂
	フランクフルト	`europe-west3`
	ロンドン	`europe-west2`	低 CO₂
	マドリード	`europe-southwest1`	低 CO₂
	ミラノ	`europe-west8`
	オランダ	`europe-west4`	低 CO₂
	パリ	`europe-west9`	低 CO₂
	ストックホルム	`europe-north2`	低 CO₂
	トリノ	`europe-west12`
	ワルシャワ	`europe-central2`
	チューリッヒ	`europe-west6`	低 CO₂
南北アメリカ
	コロンバス（オハイオ州）	`us-east5`
	ダラス	`us-south1`	低 CO₂
	アイオワ	`us-central1`	低 CO₂
	ラスベガス	`us-west4`
	ロサンゼルス	`us-west2`
	メキシコ	`northamerica-south1`
	バージニア州北部	`us-east4`
	オレゴン	`us-west1`	低 CO₂
	ケベック	`northamerica-northeast1`	低 CO₂
	サンパウロ	`southamerica-east1`	低 CO₂
	ソルトレイクシティ	`us-west3`
	サンティアゴ	`southamerica-west1`	低 CO₂
	サウスカロライナ州	`us-east1`
	トロント	`northamerica-northeast2`	低 CO₂
	米国（マルチリージョン）	`us`
アフリカ
	ヨハネスブルグ	`africa-south1`
中東
	ダンマーム	`me-central2`
	ドーハ	`me-central1`
	イスラエル	`me-west1`

デフォルトでは、変換ルール機能は次の処理を行うロケーションで使用できます。

us（米国マルチリージョン）
eu（EU マルチリージョン）
us-central1（アイオワ）
europe-west4（オランダ）

Gemini ベースの変換構成は、処理を行う特定のロケーションでのみ使用できます。詳細については、Google モデルエンドポイントのロケーションをご覧ください。

クエリを GoogleSQL に変換する

クエリを GoogleSQL に変換する手順は、次のとおりです。

Google Cloud コンソールで、[BigQuery] ページに移動します。

[BigQuery] に移動
[エディタ] ペインで [その他] をクリックし、[変換設定] を選択します。
[ソース言語] で、変換する SQL 言語を選択します。
省略可。[処理を行うロケーション] で、変換ジョブを実行するロケーションを選択します。たとえば、ヨーロッパにあり、データがロケーションの境界を越えることを望まない場合は、eu リージョンを選択します。
[保存] をクリックします。
[エディタ] ペインで [その他] をクリックし、[SQL 変換を有効にする] を選択します。

[エディタ] ペインが 2 つのペインに分割されます。
左側のペインに、変換するクエリを入力します。
[変換] をクリックします。

BigQuery でクエリが GoogleSQL に変換され、右側のペインに表示されます。たとえば、次のスクリーンショットは、変換された Teradata SQL を示しています。
（省略可）変換された GoogleSQL クエリを実行するには、[実行] をクリックします。
（省略可）SQL エディタに戻るには、[その他] をクリックして、[SQL 変換を無効にする] を選択します。

[エディタ] ペインが単一のペインに戻ります。

インタラクティブ SQL トランスレータで Gemini を使用する

インタラクティブ SQL トランスレータがソース SQL の変換方法を調整するように、インタラクティブ SQL トランスレータを構成できます。これを行うには、YAML 構成ファイルで Gemini で使用する独自のルールを指定するか、SQL オブジェクトのメタデータまたはオブジェクトマッピング情報を含む構成 YAML ファイルを指定します。

Gemini 拡張変換ルールを作成して適用する

変換ルールを作成することで、インタラクティブ SQL 変換ツールによる SQL 変換方法をカスタマイズできます。インタラクティブ SQL 変換ツールは、割り当てられた Gemini 拡張 SQL 変換ルールに基づいて変換を調整します。これにより、移行のニーズに応じて変換結果をカスタマイズできます。この機能は特定のロケーションでのみサポートされています。

Gemini 拡張 SQL 変換ルールを作成するには、コンソールで作成するか、構成 YAML ファイルを作成して Cloud Storage にアップロードします。

コンソール

入力 SQL の Gemini 拡張 SQL 変換ルールを作成するには、クエリエディタに入力 SQL クエリを記述し、[アシスト] > [カスタマイズ] をクリックします。（プレビュー）

変換入力をカスタマイズする

同様に、出力 SQL の Gemini 拡張 SQL 変換ルールを作成するには、インタラクティブ変換を実行し、[アシスト] > [この変換をカスタマイズ] をクリックします。

変換出力をカスタマイズする

[カスタマイズ] メニューが表示されたら、次の手順に進みます。

変換ルールを作成するには、次のいずれかまたは両方のプロンプトを使用します。
- 「パターンを検索して置換する」プロンプトで、置換する SQL パターンを [置換] フィールドに指定します。[置換先] フィールドには、置換する SQL パターンを指定します。
  
  SQL パターンには、SQL スクリプトの任意の数のステートメント、句、関数を含めることができます。このプロンプトを使用してルールを作成すると、Gemini 拡張 SQL 変換は、SQL クエリでその SQL パターンのインスタンスを特定し、動的に別の SQL パターンに置き換えます。たとえば、このプロンプトを使用して、months_between (X,Y) が含まれるすべての箇所を date_diff(X,Y,MONTH) に置き換えるルールを作成できます。
- [出力の変更を記述する] フィールドで、SQL 変換出力の変更を自然言語で記述します。
  
  このプロンプトを使用してルールを作成すると、Gemini 拡張 SQL 変換がリクエストを識別し、SQL クエリに指定された変更を行います。
[プレビュー] をクリックします。
[Gemini によって生成された提案] ダイアログで、Gemini 拡張 SQL 変換によってルールに基づいて SQL クエリに加えられた変更を確認します。
省略可: 今後の変換で使用するためにこのルールを追加するには、[このプロンプトを保存] チェックボックスをオンにします。

ルールは、デフォルトの構成 YAML ファイル（__default.ai_config.yaml）に保存されます。この構成 YAML ファイルは、変換設定の [変換構成ソースのロケーション] フィールドで指定されている Cloud Storage フォルダに保存されます。[変換構成ソースのロケーション] がまだ設定されていない場合は、フォルダブラウザが表示され、フォルダを選択できます。構成 YAML ファイルには、構成ファイルのサイズ制限が適用されます。
提案された変更を SQL クエリに適用するには、[適用] をクリックします。

YAML

Gemini 拡張 SQL 変換ルールを作成するには、Gemini ベースの YAML 構成ファイルを作成して Cloud Storage にアップロードします。詳細については、Gemini ベースの構成 YAML ファイルを作成するをご覧ください。

Gemini 拡張 SQL 変換ルールをアップロードして Cloud Storage にアップロードしたら、次の操作を行ってルールを適用できます。

Google Cloud コンソールで、[BigQuery] ページに移動します。

[BigQuery] に移動
クエリエディタで、[その他] > [変換設定] をクリックします。
[変換構成ソースのロケーション] フィールドに、Cloud Storage フォルダに保存されている変換ルール YAML ファイルのパスを指定します。
[保存] をクリックします。

保存したら、インタラクティブ変換を実行します。インタラクティブトランスレータは、構成 YAML ファイル（存在する場合）のルールに基づいて、変換の変更を提案します。

ルールに基づいて入力に対して Gemini の提案が利用可能な場合は、[変更の提案のプレビュー] ダイアログが表示され、変換入力に加えられる可能性のある変更が表示されます。（プレビュー）

ルールに基づいて出力に Gemini の提案が利用可能な場合は、コードエディタに通知バナーが表示されます。これらの提案を確認して適用する手順は次のとおりです。

コードエディタのいずれかの側にある [アシスト] > [提案を表示] をクリックして、対応するクエリに対する提案された変更を再確認します。
[Gemini によって生成された候補] ダイアログで、変換ルールに基づいて Gemini によって SQL クエリに加えられた変更を確認します。
提案された変更を変換出力に適用するには、[適用] をクリックします。

Gemini ベースの構成 YAML ファイルを更新する

既存の構成 YAML ファイルを更新する手順は次のとおりです。

[Gemini で生成された提案] ダイアログで、[Gemini ルール構成ファイルを表示] をクリックします。
構成エディタが表示されたら、編集する構成 YAML ファイルを選択します。
変更を加えて、[保存] をクリックします。
[完了] をクリックして、YAML エディタを閉じます。
インタラクティブ変換を実行して、更新されたルールを適用します。

変換を説明する

インタラクティブ変換を実行した後、Gemini が生成したテキストによる説明をリクエストできます。生成されたテキストには、変換された SQL クエリの概要が含まれます。Gemini は、ソース SQL クエリと変換された GoogleSQL クエリ間の変換の違いと不整合も特定します。

Gemini が生成した SQL 変換の説明を取得するには、次の操作を行います。

Gemini によって生成された SQL 変換の説明を作成するには、[アシスト]、[この変換を説明する] の順にクリックします。

バッチ変換構成 ID を使用して変換する

バッチ変換構成 ID を指定して、バッチ変換ジョブと同じ変換構成でインタラクティブクエリを実行できます。

クエリエディタで、[その他] > [変換設定] をクリックします。
[変換構成 ID] フィールドにバッチ変換構成 ID を入力して、完了した BigQuery バッチ移行ジョブから同じ変換構成を適用します。

ジョブのバッチ変換構成 ID を確認するには、[SQL 変換] ページからバッチ変換ジョブを選択し、[変換構成] タブをクリックします。バッチ変換構成 ID がリソース名として表示されます。
[保存] をクリックします。

追加の構成を使用して変換する

Cloud Storage フォルダに保存されている構成 YAML ファイルを指定すると、追加の変換構成でインタラクティブクエリを実行できます。変換構成には、変換の品質を向上させるために、ソースデータベースの SQL オブジェクトメタデータやオブジェクトマッピング情報が含まれる場合があります。たとえば、インタラクティブ SQL 変換の品質を向上させるために、ソースデータベースの DDL 情報やスキーマを含めます。

変換構成のソースファイルの場所を指定して変換構成を指定するには、次の操作を行います。

クエリエディタで、[その他] > [変換設定] をクリックします。
[変換構成ソースのロケーション] フィールドに、Cloud Storage フォルダに保存されている変換構成ファイルへのパスを指定します。

BigQuery のインタラクティブ SQL トランスレータでは、変換メタデータとオブジェクト名マッピングを含むメタデータ ZIP ファイルがサポートされています。Cloud Storage にファイルをアップロードする方法については、ファイルシステムからオブジェクトをアップロードするをご覧ください。
[保存] をクリックします。

BigQuery のバックエンドで dwh-migration-dumper ツールによって生成されたメタデータファイルからの情報を保存するには、次のようにします。

クエリエディタで、[その他] > [変換設定] をクリックします。
[メタデータのキャッシュ保存を有効にする] チェックボックスをオンにします。大きなメタデータファイルがあるジョブでは、このプロセスにより、後続のリクエストの変換レイテンシが大幅に短縮されます。キャッシュに保存されたメタデータは、最長で 7 日間有効です。この機能はプレビュー版です。この機能に関するサポートのリクエストやフィードバックを行う場合は、bq-edw-migration-support@google.com にお問い合わせください。
[保存] をクリックします。

構成ファイルのサイズに関する制限

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).

メタデータのファイルサイズを減らす方法の 1 つは、--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 トランスレータは無料で使用できます。ただし、入出力ファイルの保存に使用されるストレージには料金が発生します。詳細については、ストレージの料金をご覧ください。

次のステップ

データウェアハウス移行の次のステップの詳細を確認する。