Translation API を使用して SQL クエリを変換する
このドキュメントでは、BigQuery で Translation API を使用して、他の SQL 言語で作成されたスクリプトを GoogleSQL クエリに変換する方法について説明します。Translation API を使用すると、ワークロードを BigQuery に移行するプロセスを簡素化できます。
始める前に
変換ジョブを送信する前に、次の手順を行います。
- 必要な権限がすべて付与されていることを確認します。
- BigQuery Migration API を有効にします。
- 変換対象の SQL スクリプトとクエリが含まれるソースファイルを収集します。
- ソースファイルを Cloud Storage にアップロードします。
必要な権限
Translation API を使用して変換ジョブを作成するために必要な権限を取得するには、parent リソースに対する MigrationWorkflow 編集者（roles/bigquerymigration.editor）IAM ロールを付与するよう管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。
この事前定義ロールには、Translation API を使用して変換ジョブを作成するために必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。
必要な権限
Translation API を使用して変換ジョブを作成するには、次の権限が必要です。
-
bigquerymigration.workflows.create -
bigquerymigration.workflows.get
カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。
BigQuery Migration API を有効にする
2022 年 2 月 15 日より前に Google Cloud CLI プロジェクトを作成した場合、次のように BigQuery Migration API を有効にします。
Google Cloud コンソールで、[BigQuery Migration API] ページに移動します。
[有効にする] をクリックします。
入力ファイルを Cloud Storage にアップロードする
Google Cloud コンソールまたは BigQuery Migration API を使用して変換ジョブを実行する場合は、変換するクエリとスクリプトを含むソースファイルを Cloud Storage にアップロードする必要があります。任意のメタデータ ファイルまたは構成 YAML ファイルを、ソースファイルが含まれている同じ Cloud Storage バケットにアップロードすることもできます。バケットの作成と Cloud Storage へのファイルのアップロードの詳細については、バケットの作成とファイル システムからオブジェクトのアップロードをご覧ください。
サポートされているタスクの種類
Translation API によって、次の SQL 言語を GoogleSQL に変換できます。
- Amazon Redshift SQL -
Redshift2BigQuery_Translation - Apache HiveQL と Beeline CLI -
HiveQL2BigQuery_Translation - Apache Spark SQL -
SparkSQL2BigQuery_Translation - Azure Synapse T-SQL -
AzureSynapse2BigQuery_Translation - Greenplum SQL -
Greenplum2BigQuery_Translation - IBM Db2 SQL -
Db22BigQuery_Translation - IBM Netezza SQL と NZPLSQL -
Netezza2BigQuery_Translation - MySQL SQL -
MySQL2BigQuery_Translation - Oracle SQL、PL/SQL、Exadata -
Oracle2BigQuery_Translation - PostgreSQL SQL -
Postgresql2BigQuery_Translation - Presto または Trino SQL -
Presto2BigQuery_Translation - Snowflake SQL -
Snowflake2BigQuery_Translation - SQLite -
SQLite2BigQuery_Translation - SQL Server T-SQL -
SQLServer2BigQuery_Translation - Teradata と Teradata Vantage -
Teradata2BigQuery_Translation - Vertica SQL -
Vertica2BigQuery_Translation
ロケーション
Translation API は、次の処理ロケーションで使用できます。
| リージョンの説明 | リージョン名 | 詳細 | |
|---|---|---|---|
| アジア太平洋 | |||
| 東京 | asia-northeast1 |
||
| ムンバイ | asia-south1 |
||
| シンガポール | asia-southeast1 |
||
| シドニー | australia-southeast1 |
||
| ヨーロッパ | |||
| EU（マルチリージョン） | eu |
||
| ワルシャワ | europe-central2 |
||
| フィンランド | europe-north1 |
 低 CO2
|
|
| マドリッド | europe-southwest1 |
低 CO2
|
|
| ベルギー | europe-west1 |
低 CO2
|
|
| ロンドン | europe-west2 |
低 CO2
|
|
| フランクフルト | europe-west3 |
低 CO2
|
|
| オランダ | europe-west4 |
低 CO2
|
|
| チューリッヒ | europe-west6 |
低 CO2
|
|
| パリ | europe-west9 |
低 CO2
|
|
| トリノ | europe-west12 |
||
| 南北アメリカ | |||
| ケベック | northamerica-northeast1 |
低 CO2 |
|
| サンパウロ | southamerica-east1 |
低 CO2
|
|
| 米国（マルチリージョン） | us |
||
| アイオワ | us-central1 |
低 CO2 |
|
| サウスカロライナ | us-east1 |
||
| 北バージニア | us-east4 |
||
| コロンバス（オハイオ州） | us-east5 |
||
| ダラス | us-south1 |
低 CO2 |
|
| オレゴン | us-west1 |
低 CO2 |
|
| ロサンゼルス | us-west2 |
||
| ソルトレイクシティ | us-west3 |
||
変換ジョブを送信する
Translation API を使用して変換ジョブを送信するには、projects.locations.workflows.create メソッドを使用して、サポートされているタスクの種類の MigrationWorkflow リソースのインスタンスを指定します。
ジョブが送信されたら、クエリを実行して結果を取得できます。
バッチ変換を作成する
次の curl コマンドは、入力ファイルと出力ファイルが Cloud Storage に保存されるバッチ変換ジョブを作成します。source_target_mapping フィールドには、ソースの literal エントリをターゲット出力の任意の相対パスにマッピングするリストが含まれています。
curl -d "{
\"tasks\": {
string: {
\"type\": \"TYPE\",
\"translation_details\": {
\"target_base_uri\": \"TARGET_BASE\",
\"source_target_mapping\": {
\"source_spec\": {
\"base_uri\": \"BASE\"
}
},
\"target_types\": \"TARGET_TYPES\",
}
}
}
}" \
-H "Content-Type:application/json" \
-H "Authorization: Bearer TOKEN" -X POST https://bigquerymigration.googleapis.com/v2alpha/projects/PROJECT_ID/locations/LOCATION/workflows
次のように置き換えます。
TYPE: 変換のタスクの種類。これにより、ソースとターゲットの言語が決まります。TARGET_BASE: すべての変換出力のベース URI。BASE: 変換元として読み取られるすべてのファイルのベース URI。TARGET_TYPES（省略可）: 生成された出力タイプ。指定しない場合、SQL が生成されます。sql（デフォルト）: 変換された SQL クエリ ファイル。suggestion: AI 生成の候補。
出力は、出力ディレクトリのサブフォルダに保存されます。サブフォルダの名前は、
TARGET_TYPESの値に基づいて付けられます。TOKEN: 認証用のトークン。トークンを生成するには、gcloud auth print-access-tokenコマンドまたは OAuth 2.0 プレイグラウンド（スコープはhttps://www.googleapis.com/auth/cloud-platform）を使用します。PROJECT_ID: 変換を処理するプロジェクト。LOCATION: ジョブが処理されるロケーション。
前述のコマンドは、projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID 形式で記述されたワークフロー ID を含むレスポンスを返します。
バッチ変換の例
Cloud Storage ディレクトリ gs://my_data_bucket/teradata/input/ にある Teradata SQL スクリプトを変換し、結果を Cloud Storage ディレクトリ gs://my_data_bucket/teradata/output/ に保存するには、次のクエリを使用します。
{
"tasks": {
"task_name": {
"type": "Teradata2BigQuery_Translation",
"translation_details": {
"target_base_uri": "gs://my_data_bucket/teradata/output/",
"source_target_mapping": {
"source_spec": {
"base_uri": "gs://my_data_bucket/teradata/input/"
}
},
}
}
}
}
この呼び出しは、作成されたワークフロー ID を含むメッセージを "name" フィールドに返します。
{
"name": "projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00",
"tasks": {
"task_name": { /*...*/ }
},
"state": "RUNNING"
}
ワークフローの更新ステータスを取得するには、GET クエリを実行します。ジョブは進行に応じて出力を Cloud Storage に送信します。リクエストされたすべての target_types が生成されると、ジョブ state は COMPLETED に変わります。タスクが成功すると、変換された SQL クエリが gs://my_data_bucket/teradata/output に表示されます。
AI の候補を使用したバッチ変換の例
次の例では、gs://my_data_bucket/teradata/input/ Cloud Storage ディレクトリにある Teradata SQL スクリプトを変換し、結果を Cloud Storage ディレクトリ gs://my_data_bucket/teradata/output/ に保存します。また、AI の候補も追加します。
{
"tasks": {
"task_name": {
"type": "Teradata2BigQuery_Translation",
"translation_details": {
"target_base_uri": "gs://my_data_bucket/teradata/output/",
"source_target_mapping": {
"source_spec": {
"base_uri": "gs://my_data_bucket/teradata/input/"
}
},
"target_types": "suggestion",
}
}
}
}
タスクが正常に実行されると、AI の候補は gs://my_data_bucket/teradata/output/suggestion Cloud Storage ディレクトリに保存されます。
文字列リテラルの入力と出力を使用してインタラクティブな変換ジョブを作成する
次の curl コマンドは、文字列リテラルの入出力を持つ変換ジョブを作成します。source_target_mapping フィールドには、ソース ディレクトリをターゲット出力の相対パス（省略可）にマッピングするリストが含まれます。
curl -d "{
\"tasks\": {
string: {
\"type\": \"TYPE\",
\"translation_details\": {
\"source_target_mapping\": {
\"source_spec\": {
\"literal\": {
\"relative_path\": \"PATH\",
\"literal_string\": \"STRING\"
}
}
},
\"target_return_literals\": \"TARGETS\",
}
}
}
}" \
-H "Content-Type:application/json" \
-H "Authorization: Bearer TOKEN" -X POST https://bigquerymigration.googleapis.com/v2alpha/projects/PROJECT_ID/locations/LOCATION/workflows
次のように置き換えます。
TYPE: 変換のタスクの種類。これにより、ソースとターゲットの言語が決まります。PATH: ファイル名またはパスに類似したリテラル エントリの識別子。STRING: 変換するリテラル入力データの文字列（SQL など）。TARGETS: ユーザーがレスポンスで直接返すことを期待しているターゲット（literal形式）。これらはターゲット URI 形式（例: GENERATED_DIR +target_spec.relative_path+source_spec.literal.relative_path）にする必要があります。このリストにないものはレスポンスで返されません。一般的な SQL 変換用に生成されるディレクトリ GENERATED_DIR はsql/です。TOKEN: 認証用のトークン。トークンを生成するには、gcloud auth print-access-tokenコマンドまたは OAuth 2.0 プレイグラウンド（スコープはhttps://www.googleapis.com/auth/cloud-platform）を使用します。PROJECT_ID: 変換を処理するプロジェクト。LOCATION: ジョブが処理されるロケーション。
前述のコマンドは、projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID 形式で記述されたワークフロー ID を含むレスポンスを返します。
ジョブが完了したら、ジョブをクエリして、ワークフロー完了後のレスポンスのインライン translation_literals フィールドを調べることで、結果を確認できます。
インタラクティブ変換の例
Hive SQL 文字列 select 1 をインタラクティブに変換するには、次のクエリを使用します。
"tasks": {
string: {
"type": "HiveQL2BigQuery_Translation",
"translation_details": {
"source_target_mapping": {
"source_spec": {
"literal": {
"relative_path": "input_file",
"literal_string": "select 1"
}
}
},
"target_return_literals": "sql/input_file",
}
}
}
リテラルには任意の relative_path を使用できますが、変換後のリテラルが結果に表示されるのは、target_return_literals に sql/$relative_path が含まれている場合のみです。1 つのクエリに複数のリテラルを含めることもできます。この場合、それぞれの相対パスを target_return_literals に含める必要があります。
この呼び出しは、作成されたワークフロー ID を含むメッセージを "name" フィールドに返します。
{
"name": "projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00",
"tasks": {
"task_name": { /*...*/ }
},
"state": "RUNNING"
}
ワークフローの更新ステータスを取得するには、GET クエリを実行します。ジョブが完了すると、"state" が COMPLETED に変わります。タスクが成功すると、変換された SQL がレスポンス メッセージに表示されます。
{
"name": "projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00",
"tasks": {
"string": {
"id": "0fedba98-7654-3210-1234-56789abcdef",
"type": "HiveQL2BigQuery_Translation",
/* ... */
"taskResult": {
"translationTaskResult": {
"translatedLiterals": [
{
"relativePath": "sql/input_file",
"literalString": "-- Translation time: 2023-10-05T21:50:49.885839Z\n-- Translation job ID: projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00\n-- Source: input_file\n-- Translated from: Hive\n-- Translated to: BigQuery\n\nSELECT\n 1\n;\n"
}
],
"reportLogMessages": [
...
]
}
},
/* ... */
}
},
"state": "COMPLETED",
"createTime": "2023-10-05T21:50:49.543221Z",
"lastUpdateTime": "2023-10-05T21:50:50.462758Z"
}
変換出力を確認する
変換ジョブの実行後、次のコマンドを使用して変換ジョブ ワークフロー ID を指定して結果を取得します。
curl \ -H "Content-Type:application/json" \ -H "Authorization:Bearer TOKEN" -X GET https://bigquerymigration.googleapis.com/v2alpha/projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID
次のように置き換えます。
TOKEN: 認証用のトークン。トークンを生成するには、gcloud auth print-access-tokenコマンドまたは OAuth 2.0 プレイグラウンド（スコープはhttps://www.googleapis.com/auth/cloud-platform）を使用します。PROJECT_ID: 変換を処理するプロジェクト。LOCATION: ジョブが処理されるロケーション。WORKFLOW_ID: 変換ワークフローの作成時に生成された ID。
レスポンスには、移行ワークフローのステータスと、target_return_literals 内の完了したファイルが含まれます。
レスポンスには、移行ワークフローのステータスと、target_return_literals 内の完了したファイルが含まれます。このエンドポイントをポーリングして、ワークフローのステータスを確認できます。