コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

バッチ SQL トランスレータでコードを移行する

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

バッチ SQL トランスレータは、BigQuery Migration Service の一部です。バッチ SQL トランスレータは、次の SQL 言語を Google 標準 SQL に変換できます。

  • Amazon Redshift SQL
  • Teradata SQL(SPL を除く)

また、次の SQL 言語の変換は、プレビューでサポートされています。

  • Apache HiveQL
  • Apache Spark SQL
  • Azure Synapse T-SQL
  • 基本的な Teradata Query(BTEQ)
  • IBM Netezza SQL/NZPLSQL
  • MySQL SQL
  • Oracle SQL、PL/SQL、Exadata
  • Presto SQL
  • PostgreSQL SQL
  • Snowflake SQL
  • SQL Server T-SQL
  • Teradata SPL
  • Vertica SQL

必要な権限

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

準備

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

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

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 にアップロードする必要があります。

  • BigQuery Migration API: プログラムでジョブを構成して送信します。この方法を使用する場合は、ソースファイルを Cloud Storage にアップロードする必要があります。

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

Google Cloud コンソールまたは BigQuery Migration API を使用して変換ジョブを実行する場合は、変換するクエリとスクリプトを含むソースファイルを Cloud Storage にアップロードする必要があります。メタデータ ファイルを作成してアップロードする必要もあります。バケットを作成してファイルを Cloud Storage にアップロードする方法については、ストレージ バケットの作成オブジェクトのアップロードをご覧ください。

変換ジョブを送信する

変換ジョブを開始して進行状況を表示し、結果を確認するには、次の手順に沿って操作します。

バッチ変換クライアント

  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 バケットでジョブによって作成されたファイルを削除します。

Console

以下の手順は、ソースファイルが 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. [Next] をクリックします。

  8. [Target location] には、変換されたファイルの宛先 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. [] で、マッピングするオブジェクトを表すオブジェクト タイプを選択します。
      5. 必要な名前マッピングペアをすべて指定するまで、ステップ 1~4 を繰り返します。Google Cloud コンソールを使用する場合、最大 25 個の名前マッピングのペアのみを指定できます。
  11. [作成] をクリックして変換ジョブを開始します。

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

API

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

  1. 定義済みのワークフローを使用して create メソッドを呼び出します。
  2. start メソッドを呼び出して、変換ワークフローを開始します。

Go、Java、Python 用の BigQuery Migration API クライアント ライブラリを使用すると、プログラムでバッチ変換ジョブの構成と送信を簡単に行うことができます。

変換出力を確認する

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

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

Google Cloud コンソールの出力

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

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

    BigQuery に移動

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

  3. 変換ジョブのリストで、目的のジョブを見つけて、変換ジョブ名をクリックします。

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

  5. [操作] タブを選択して、変換に関する問題とその発生頻度を確認します。表示された各操作には、問題カテゴリ、特定の問題メッセージ、問題が発生したファイルへのリンクを示す子行があります。

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

概要レポート

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

Google Cloud コンソールで概要ファイルを表示するには、次の手順を行います。

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

    BigQuery に移動

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

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

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

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

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

説明
Timestamp 問題が発生したタイムスタンプ。
FilePath 問題が関連付けられているソースファイルへのパス。
FileName 問題が関連付けられているソースファイルの名前。
ScriptLine 問題が発生した行番号。
ScriptColumn 問題が発生した列番号。
TranspilerComponent 警告またはエラーが発生した変換エンジンの内部コンポーネント。この列は空になる可能性があります。
環境 警告またはエラーに関連する変換言語環境。この列は空になる可能性があります。
ObjectName 警告またはエラーに関連付けられているソースファイル内の SQL オブジェクト。この列は空になる可能性があります。
Severity 問題の重大度(警告またはエラー)。
Category 変換に関する問題のカテゴリ。
Message 変換に関する問題の警告またはエラー メッセージ。
ScriptContext 問題に関連付けられているソースファイルの SQL スニペット。
Action この問題を解決するために推奨されるアクション。

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

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

変換されたファイル

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

制限事項

トランスレータは 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 未満に抑えておくことをおすすめします。

次のステップ

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