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

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

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

制限事項

インタラクティブ SQL 変換ツールを使用するには、Google アカウントでログインする必要があります。インタラクティブ SQL 変換ツールは、フェデレーション ID の使用をサポートしていません。

始める前に

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

ロケーション

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

	リージョンの説明	リージョン名	詳細
アジア太平洋
	東京	`asia-northeast1`
	ムンバイ	`asia-south1`
	シンガポール	`asia-southeast1`
	シドニー	`australia-southeast1`
ヨーロッパ
	EU（マルチリージョン）	`eu`
	ワルシャワ	`europe-central2`
	フィンランド	`europe-north1`	低 CO₂
	マドリッド	`europe-southwest1`	低 CO₂
	ベルギー	`europe-west1`	低 CO₂
	ロンドン	`europe-west2`	低 CO₂
	フランクフルト	`europe-west3`	低 CO₂
	オランダ	`europe-west4`	低 CO₂
	チューリッヒ	`europe-west6`	低 CO₂
	パリ	`europe-west9`	低 CO₂
	トリノ	`europe-west12`
南北アメリカ
	サンパウロ	`southamerica-east1`	低 CO₂
	米国（マルチリージョン）	`us`
	アイオワ	`us-central1`	低 CO₂
	サウスカロライナ	`us-east1`
	北バージニア	`us-east4`
	コロンバス（オハイオ州）	`us-east5`
	ダラス	`us-south1`	低 CO₂
	オレゴン	`us-west1`	低 CO₂
	ロサンゼルス	`us-west2`
	ソルトレイクシティ	`us-west3`

変換ルール機能は次のロケーションで使用できます。

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

クエリを GoogleSQL に変換する

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

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

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

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

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

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

要件

変換ルールの YAML ファイルには、接尾辞 .ai_config.yaml が必要です。例: rules_1.ai_config.yaml

制限事項

インタラクティブ SQL トランスレータで適用できる変換ルール YAML ファイルは 1 つだけです。
各変換ルール 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）と、1 つの SQL パターン（input）を別のパターン（output）に置き換える 1 つ以上の例で構成できます。変換ルールでは、instruction フィールド、1 つ以上の 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: 1 つの 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 オブジェクトメタデータやオブジェクトマッピング情報が含まれる場合があります。たとえば、インタラクティブ SQL 変換の品質を向上させるために、ソースデータベースの DDL 情報やスキーマを含めます。

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

クエリエディタで、[その他] > [変換設定] をクリックします。
[変換構成ソースのロケーション] フィールドに、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).

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

次のステップ

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

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

制限事項

始める前に

権限とロール

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

必要な権限

追加の変換構成を構成するための権限

サポートされている SQL 言語

ロケーション

クエリを GoogleSQL に変換する

インタラクティブ SQL トランスレータを構成する

変換ルールを作成する

コンソール

YAML

要件

制限事項

サポートされるフィールド

変換ルールの YAML ファイルを次の変換に適用する

変換ルールの YAML ファイルの例

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

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

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

変換エラーのトラブルシューティング

変換の問題: RelationNotFound または AttributeNotFound

料金

次のステップ

変換の問題: `RelationNotFound` または `AttributeNotFound`