Translation API を使用して SQL クエリを変換する

このドキュメントでは、BigQuery で Translation API を使用して、他の SQL 言語で作成されたスクリプトを GoogleSQL クエリに変換する方法について説明します。Translation API を使用すると、ワークロードを BigQuery に移行するプロセスを簡素化できます。

始める前に

変換ジョブを送信する前に、次の手順を行います。

  1. 必要な権限がすべて付与されていることを確認します。
  2. BigQuery Migration API を有効にします。
  3. 変換対象の SQL スクリプトとクエリが含まれるソースファイルを収集します。
  4. ソースファイルを 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 を有効にします。

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

    BigQuery Migration API に移動

  2. [有効にする] をクリックします。

入力ファイルを 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
南北アメリカ
サンパウロ 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\"
              }
            },
        }
      }
  }
  }" \
  -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。
  • 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 クエリを実行します。ジョブが完了すると、"state" が COMPLETED に変わります。タスクが正常に完了すると、変換された SQL が gs://my_data_bucket/teradata/output に表示されます。

文字列リテラルの入力と出力を使用してインタラクティブな変換ジョブを作成する

次の 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 内の完了したファイルが含まれます。このエンドポイントをポーリングして、ワークフローのステータスを確認できます。