バッチ SQL トランスレータを使用してコードを移行する

このドキュメントでは、BigQuery のバッチ SQL トランスレータを使用して、他の SQL 言語で作成されたスクリプトを GoogleSQL のクエリに変換する方法について説明します。このドキュメントは、Google Cloud コンソールについての知識があるユーザーを対象としています。

始める前に

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

  1. 必要な権限がすべて付与されていることを確認します。
  2. BigQuery Migration API を有効にします。
  3. 変換対象の SQL スクリプトとクエリが含まれるソースファイルを収集します。
  4. 省略可。変換の精度を改善するために、メタデータ ファイルを作成します。
  5. 省略可。ソースファイル内の SQL オブジェクト名を BigQuery の新しい名前にマッピングする必要があるかどうかを判断します。必要に応じて、使用する名前マッピング ルールを決定します。
  6. 変換ジョブの送信方法を決定します。
  7. ソースファイルを Cloud Storage にアップロードします。

必要な権限

BigQuery Migration Service を有効にするには、プロジェクトに対する次の権限が必要です。

  • resourcemanager.projects.get
  • serviceusage.services.enable
  • serviceusage.services.get

BigQuery Migration Service にアクセスして使用するには、プロジェクトに関する次の権限が必要です。

  • bigquerymigration.workflows.create
  • bigquerymigration.workflows.get
  • bigquerymigration.workflows.list
  • bigquerymigration.workflows.delete
  • bigquerymigration.subtasks.get

  • bigquerymigration.subtasks.list

    または、次のロールを使用して同じ権限を取得することもできます。

    • bigquerymigration.viewer - 読み取り専用アクセス。
    • bigquerymigration.editor - 読み取り / 書き込みアクセス。

入出力ファイル用の Cloud Storage バケットにアクセスするには:

  • ソース Cloud Storage バケットに対する storage.objects.get。
  • ソース Cloud Storage バケットに対する storage.objects.list。
  • 転送先の Cloud Storage バケットに対する storage.objects.create。

次のロールには、上記の必要な Cloud Storage の権限がすべて含まれています。

  • roles/storage.objectAdmin
  • roles/storage.admin

BigQuery Migration API を有効にする

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

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

    BigQuery Migration API に移動

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

ソースファイルを収集する

ソースファイルは、ソース言語の有効な SQL を含むテキスト ファイルである必要があります。ソースファイルにはコメントを含めることもできます。利用可能な方法で、SQL が有効であることを確認してください。

メタデータ ファイルを作成する

サービスでより正確な変換結果を生成できるように、メタデータ ファイルを指定することをおすすめします。ただし、これは必須ではありません。

dwh-migration-dumper コマンドライン抽出ツールを使用して、メタデータ情報を生成できます。または、独自のメタデータ ファイルを指定できます。メタデータ ファイルが準備できたら、ソースファイルとともに変換ソースフォルダに追加できます。トランスレータはメタデータ ファイルを自動的に検出し、それを利用してソースファイルを変換します。このために特別な設定は必要ありません。

dwh-migration-dumper ツールを使用してメタデータ情報を生成するには、変換用のメタデータを生成するをご覧ください。

独自のメタデータを提供するには、移行元システムの SQL オブジェクトのデータ定義言語（DDL）ステートメントを、個別のテキスト ファイルに収集します。

SQL オブジェクト名のマッピング

必要に応じて、一括変換中に出力名のマッピングを実行できます。出力名マッピングを使用する場合は、ソースシステムの SQL オブジェクトの名前を BigQuery の新しい名前に変更する名前マッピング ルールを指定します。たとえば、ソースシステムに schema1.table1 というオブジェクトがあり、BigQuery ではそのオブジェクトに project1.dataset1.table1 という名前を付ける場合などです。出力名マッピングを使用する場合は、一括変換ジョブを開始する前に名前マッピング ルールを定義する必要があります。名前マッピング ルールをジョブの構成時に手動で入力することも、名前マッピング ルールを含む JSON ファイルを作成してアップロードすることもできます。

変換ジョブの送信方法を決定する

バッチ変換ジョブを送信するには、次の 3 つの方法があります。

  • バッチ変換クライアント: 構成ファイル内の設定を変更してジョブを構成し、コマンドラインを使用してジョブを送信します。この方法を使用する場合は、ソースファイルを Cloud Storage に手動でアップロードする必要はありません。クライアントは、変換ジョブの処理中は引き続き Cloud Storage を使用してファイルを保存します。

    バッチ変換クライアントはオープンソースの Python クライアントであり、ローカルマシンにあるソースファイルを変換し、変換されたファイルをローカル ディレクトリに出力できます。このクライアントを基本的な用途のために構成するには、構成ファイルのいくつかの設定を変更します。必要であれば、マクロの置換や、変換入出力の前処理や後処理などの複雑なタスクに対応するようにクライアントを構成することもできます。詳細については、バッチ変換クライアントの readme をご覧ください。

  • Google Cloud コンソール: ユーザー インターフェースを使用してジョブの構成と送信を行います。この方法を使用する場合は、ソースファイルを Cloud Storage にアップロードする必要があります。

YAML 構成ファイルを作成する

必要に応じて、構成 YAML ファイルを作成して使用し、一括変換をカスタマイズできます。これらのファイルは、変換出力をさまざまな方法で変換するために使用できます。たとえば、変換中に SQL オブジェクトの大文字 / 小文字を変更する構成 YAML ファイルを作成できます。

バッチ変換ジョブに Google Cloud コンソールまたは BigQuery Migration API を使用する場合は、ソースファイルを含む Cloud Storage バケットに構成 YAML ファイルをアップロードできます。

一括変換クライアントを使用する場合は、構成 YAML ファイルをローカル変換入力フォルダに配置します。

入力ファイルを Cloud Storage にアップロードする

Google Cloud コンソールまたは BigQuery Migration API を使用して変換ジョブを実行する場合は、変換するクエリとスクリプトを含むソースファイルを Cloud Storage にアップロードする必要があります。任意のメタデータ ファイルまたは構成 YAML ファイルを、ソースファイルが含まれている Cloud Storage バケットにアップロードすることもできます。バケットの作成と Cloud Storage へのファイルのアップロードの詳細については、バケットの作成とファイル システムからオブジェクトのアップロードをご覧ください。

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

バッチ SQL トランスレータは、BigQuery Migration Service の一部です。バッチ 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 リーフアイコン 低 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

変換ジョブを送信する

変換ジョブを開始して進行状況を表示し、結果を確認する手順は次のとおりです。

コンソール

以下の手順は、ソースファイルが Cloud Storage バケットにすでにアップロードされていることを前提としています。

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

    [BigQuery] に移動

  2. ナビゲーション パネルの [移行] セクションで、[SQL 変換] をクリックします。

  3. [変換を開始] をクリックします。

  4. 変換構成ダイアログに入力します。

    1. [表示名] に、変換ジョブの名前を入力します。名前には文字、数字、アンダースコアを使用できます。
    2. [処理を行うロケーション] で、変換ジョブを実行するロケーションを選択します。たとえば、ヨーロッパにあり、データがロケーションの境界を越えることを望まない場合は、eu リージョンを選択します。変換ジョブは、ソースファイル バケットと同じロケーションを選択すると最も効率的に処理されます。
    3. [ソース言語] で、変換する SQL 言語を選択します。
    4. [ターゲット言語] で、[BigQuery] を選択します。

  5. [次へ] をクリックします。

  6. [ソースのロケーション] には、変換するファイルを含む Cloud Storage フォルダへのパスを指定します。パスを bucket_name/folder_name/ の形式で入力するか、[参照] オプションを使用します。

  7. [次へ] をクリックします。

  8. [ターゲット ロケーション] には、変換されたファイルの宛先 Cloud Storage フォルダへのパスを指定します。パスを bucket_name/folder_name/ の形式で入力するか、[参照] オプションを使用します。

  9. デフォルトのオブジェクト名や、ソースからターゲットへの名前マッピングを指定する必要がない変換を行う場合は、ステップ 11 に進みます。それ以外の場合は、[次へ] をクリックします。

  10. 必要なオプション設定を入力します。

    1. 省略可。[デフォルトのデータベース] に、ソースファイルで使用するデフォルトのデータベース名を入力します。トランスレータはデータベース名がない SQL オブジェクトの完全修飾名を解決するときに、このデフォルトのデータベース名を使用します。

    2. 省略可。[スキーマの検索パス] には、スキーマ名がないソースファイルの SQL オブジェクトの完全修飾名をトランスレータが解決する必要がある場合に、検索するスキーマを指定します。ソースファイルで複数の異なるスキーマ名が使用されている場合は、[スキーマ名を追加] をクリックして、参照される各スキーマ名の値を追加します。

      トランスレータは指定されたメタデータ ファイル内を検索し、そのスキーマ名でテーブルを検証します。メタデータから明確なオプションを特定できない場合は、最初に入力したスキーマ名がデフォルトとして使用されます。デフォルトのスキーマ名の使用方法について詳しくは、デフォルトのスキーマをご覧ください。

    3. 省略可。名前マッピング ルールを指定して、変換中にソースシステムと BigQuery 間で SQL オブジェクトの名前を変更する場合は、名前マッピングのペアが設定された JSON ファイルを指定するか、Google Cloud コンソールを使用してマッピングする値を指定します。

      JSON ファイルを使用するには:

      1. [名前マッピング用の JSON ファイルのアップロード] をクリックします。

      2. 適切な形式の名前マッピング ファイルの場所を参照して選択し、[開く] をクリックします。

        ファイルサイズは 5 MB 未満である必要があります。

      Google Cloud コンソールを使用するには:

      1. [名前のマッピングペアを追加] をクリックします。
      2. ソース オブジェクト名の適切な部分を、[ソース] 列の [データベース]、[スキーマ]、[リレーション]、[属性] フィールドに追加します。
      3. BigQuery のターゲット オブジェクト名の部分を [ターゲット] 列のフィールドに追加します。
      4. [Type] で、マッピングするオブジェクトを表すオブジェクト タイプを選択します。
      5. 必要な名前マッピングペアをすべて指定するまで、ステップ 1～4 を繰り返します。Google Cloud コンソールを使用する場合、指定できる名前マッピングペアは最大 25 個までです。

  11. [作成] をクリックして変換ジョブを開始します。

変換ジョブが作成されると、ジョブのステータスを変換ジョブのリストで確認できます。

バッチ変換クライアント

  1. バッチ変換クライアントと Google Cloud CLI をインストールします。

  2. gcloud CLI 認証情報ファイルを生成します。

  3. バッチ変換クライアントのインストール ディレクトリで、任意のテキスト エディタを使用して config.yaml ファイルを開き、次の設定を変更します。

    • project_number: 一括変換ジョブに使用するプロジェクトのプロジェクト番号を入力します。これは、プロジェクトの Google Cloud コンソールの [ようこそ] ページの [プロジェクト情報] ペインで確認できます。
    • gcs_bucket: 変換ジョブの処理中にファイルを保存するためにバッチ変換クライアントが使用する Cloud Storage バケットの名前を入力します。
    • input_directory: ソースファイルとメタデータ ファイルを含むディレクトリの絶対パスまたは相対パスを入力します。
    • output_directory: 変換されたファイルのターゲット ディレクトリの絶対パスまたは相対パスを入力します。

  4. 変更を保存し、config.yaml ファイルを閉じます。

  5. ソースファイルとメタデータ ファイルを入力ディレクトリに配置します。

  6. 次のコマンドを使用して、バッチ変換クライアントを実行します。

    bin/dwh-migration-client

    変換ジョブが作成されたら、ジョブのステータスを Google Cloud コンソールの変換ジョブリストで確認できます。

  7. 省略可。ストレージ費用の発生を回避するには、変換ジョブが完了したら、指定した Cloud Storage バケットでジョブによって作成されたファイルを削除します。

変換出力を確認する

変換ジョブの実行後、Google Cloud コンソールでジョブに関する情報を確認できます。Google Cloud コンソールを使用してジョブを実行すると、指定した宛先 Cloud Storage バケットでジョブの結果を確認できます。一括変換クライアントを使用してジョブを実行すると、指定した出力ディレクトリでジョブの結果を確認できます。バッチ SQL トランスレータは、指定された宛先に次のファイルを出力します。

  • 変換されたファイル。
  • CSV 形式の変換概要レポート。
  • 使用された出力名マッピング（JSON 形式）。

Google Cloud コンソールの出力

変換ジョブの詳細を表示する手順は次のとおりです。

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

    [BigQuery] に移動

  2. ナビゲーション パネルの [移行] セクションで、[SQL 変換] をクリックします。

  3. 変換ジョブのリストで、変換の詳細を表示するジョブを見つけ、変換ジョブ名をクリックします。

  4. [結果] セクションで、全体的な変換の成功率、処理されたステートメントの数、ジョブの所要時間を確認できます。

  5. [ログのサマリー] タブを選択すると、問題のカテゴリ、推奨されるアクション、各問題の発生頻度など、変換に関する問題のサマリーが表示されます。問題のカテゴリを選択して、その問題のカテゴリに関連付けられたログメッセージを表示することもできます（プレビュー）。

  6. [ログメッセージ] タブを選択すると、問題のカテゴリ、具体的な問題のメッセージ、問題が発生したファイルへのリンクなど、変換に関する各問題の詳細が表示されます。[ログメッセージ] タブで問題を選択すると、該当する場合に入力および出力ファイルを表示する [コードタブ] が開きます（プレビュー）。

  7. [変換の構成] タブを選択して、変換ジョブの構成の詳細を表示します。

概要レポート

概要レポートは、変換ジョブで発生したすべての警告メッセージとエラー メッセージのテーブルが含まれる CSV ファイルです。

Google Cloud コンソールで概要ファイルを表示する手順は、次のとおりです。

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

    [BigQuery] に移動

  2. ナビゲーション パネルの [移行] セクションで、[SQL 変換] をクリックします。

  3. 変換ジョブのリストで目的のジョブを見つけ、[Status] 列の [Show details] をクリックします。

  4. [変換レポート] セクションで [batch_translation_report.csv] をクリックします。

  5. [オブジェクトの詳細] ページで、[認証済み URL] 行の値をクリックして、ブラウザにファイルを表示します。

次の表に、概要ファイルの列を示します。

列 説明
Timestamp 問題が発生した時点のタイムスタンプ。
FilePath 問題が関連付けられているソースファイルへのパス。
FileName 問題が関連付けられているソースファイルの名前。
ScriptLine 問題が発生した行番号。
ScriptColumn 問題が発生した列番号。
TranspilerComponent 警告またはエラーが発生した変換エンジンの内部コンポーネント。この列は空の場合があります。
Environment 警告またはエラーに関連する変換言語環境。この列は空の場合があります。
ObjectName 警告またはエラーに関連付けられているソースファイル内の SQL オブジェクト。この列は空の場合があります。
Severity 問題の重大度（警告またはエラー）。
Category 変換に関する問題のカテゴリ。
SourceType この問題の原因。この列の値は、入力 SQL ファイルの問題を示す SQL か、メタデータ パッケージの問題を示す METADATA のいずれかです。
Message 変換に関する問題の警告またはエラー メッセージ。
ScriptContext 問題に関連付けられているソースファイルの SQL スニペット。
Action この問題を解決するために推奨されるアクション。

コードタブ

コードタブでは、特定の変換ジョブの入力ファイルと出力ファイルに関する詳細情報を確認できます。コードタブでは、変換ジョブで使用されているファイルを調べ、入力ファイルとその変換を並べて比較して誤りがないか確認し、ジョブ内の特定のファイルのログサマリーとメッセージを表示できます。

コードタブにアクセスする手順は次のとおりです。

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

    [BigQuery] に移動

  2. ナビゲーション パネルの [移行] セクションで、[SQL 変換] をクリックします。

  3. 変換ジョブのリストで目的のジョブを見つけ、[ステータス] 列の [詳細を表示] をクリックします。

  4. [コードタブ] を選択します。

使用された出力名マッピング ファイル

この JSON ファイルには、変換ジョブで使用された出力名マッピング ルールが含まれています。このファイルのルールは、変換ジョブに指定した出力名マッピング ルールとは異なる場合があります。これは、名前マッピング ルールで競合しているか、変換中に識別された SQL オブジェクトの名前マッピング ルールが欠落しているためです。このファイルを確認して、名前マッピング ルールを修正する必要があるかどうかを判断します。修正する必要がある場合は、特定した問題に対処する新しい出力名マッピング ルールを作成し、新しい変換ジョブを実行します。

変換されたファイル

入力ファイルごとに、対応する出力ファイルが宛先パスに生成されます。出力ファイルには、変換されたクエリが含まれます。

インタラクティブ SQL トランスレータを使用してバッチ変換された一括 SQL クエリをデバッグする

BigQuery のインタラクティブ SQL トランスレータを使用すると、ソース データベースと同じメタデータまたはオブジェクト マッピング情報を使用して SQL クエリを確認またはデバッグできます。バッチ変換ジョブが完了すると、BigQuery は、クエリに該当するジョブのメタデータ、オブジェクト マッピング、スキーマの検索パスに関する情報を含む変換構成 ID を生成します。バッチ変換の構成 ID とインタラクティブ SQL トランスレータを使用して、指定した構成で SQL クエリを実行します。

一括変換構成 ID を使用してインタラクティブ SQL 変換を開始する手順は、次のとおりです。

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

    [BigQuery] に移動

  2. ナビゲーション メニューの [移行] セクションで、[SQL 変換] をクリックします。

  3. 変換ジョブのリストで目的のジョブを見つけて、（その他のオプション）> [インタラクティブ変換を開きます] をクリックします。

BigQuery のインタラクティブ SQL トランスレータが開き、対応する一括変換の構成 ID が表示されます。インタラクティブ変換の変換構成 ID を表示するには、インタラクティブ トランスレータの [その他] > [変換設定] をクリックします。

制限事項

トランスレータは SQL 以外の言語のユーザー定義関数（UDF）を変換できません。これは、SQL 以外の言語を解析して入力データ型と出力データ型を判断することができないためです。このため、このような UDF を参照する SQL ステートメントの変換は不正確になります。変換時に SQL 以外の UDF が適切に参照されるようにするには、有効な SQL を使用して同じ署名を持つプレースホルダ UDF を作成します。

たとえば、2 つの整数の合計を計算する C で記述された UDF があるとします。この UDF を参照する SQL ステートメントが正しく変換されるようにするには、次の例に示すように、C UDF と同じシグネチャを共有するプレースホルダ SQL UDF を作成します。

CREATE FUNCTION Test.MySum (a INT, b INT)
  RETURNS INT
  LANGUAGE SQL
  RETURN a + b;

このプレースホルダ UDF をテキスト ファイルに保存し、そのファイルを変換ジョブのソースファイルの 1 つとして含めます。これにより、トランスレータは UDF 定義を学習し、想定される入力と出力のデータ型を特定できます。

割り当てと上限

  • BigQuery Migration API の割り当てが適用されます。
  • 各プロジェクトには、最大 10 個のアクティブな変換タスクを含めることができます。
  • ソースファイルとメタデータ ファイルの合計数にハードリミットはありませんが、パフォーマンス向上のためにファイル数を 1,000 未満に抑えておくことをおすすめします。

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

変換の問題: RelationNotFound または AttributeNotFound

変換はメタデータ DDL で最適に動作します。SQL オブジェクト定義が見つからない場合は、変換エンジンで RelationNotFound または AttributeNotFound の問題が発生します。メタデータ抽出を使用してメタデータ パッケージを生成し、すべてのオブジェクト定義が存在するようにすることをおすすめします。メタデータの不足によって間接的に発生する他のエラーの多くはたいてい修正可能であるため、ほとんどの変換エラーを解決するための最初の手順として、メタデータの追加をおすすめします。

詳細については、変換と評価のためのメタデータを生成するをご覧ください。

料金

バッチ SQL トランスレータは無料で使用できます。ただし、入出力ファイルの保存に使用されるストレージには料金が発生します。詳細については、ストレージの料金をご覧ください。

次のステップ

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