Cloud Spanner への Avro ファイルのインポート

このページでは、Google Cloud Console を使用して Cloud Spanner データベースを Cloud Spanner にインポートする方法について説明します。他のソースから Avro ファイルをインポートする方法については、Cloud Spanner 以外のデータベースからデータをインポートするをご覧ください。

このプロセスでは Dataflow を使用して、Avro ファイルと JSON マニフェスト ファイルのセットを含む Cloud Storage バケット フォルダからデータをインポートします。このインポート プロセスでは、Cloud Spanner からエクスポートされた Avro ファイルのみがサポートされます。

REST API または gcloud コマンドライン ツールを使用して、Cloud Spanner データベースをインポートするには、このページの始める前にのセクションの手順を完了してから、Cloud Storage Avro to Cloud Spannerで詳しい手順をご覧ください。

始める前に

Cloud Spanner データベースをインポートするには、まず Cloud Spanner、Cloud Storage、Compute Engine、Dataflow API を有効にする必要があります。

API を有効にする

また、十分な割り当てと必須の IAM 権限も必要です。

割り当て要件

Google Cloud サービスによるインポート ジョブの割り当て要件は次のとおりです。

  • Cloud Spanner: インポートするデータの量をサポートできるだけのノードが必要です。データベースをインポートするためにノードを追加する必要はありませんが、ジョブが妥当な時間内に終了するようにノードの追加が必要になる場合があります。詳細については、ジョブの最適化をご覧ください。
  • Cloud Storage: インポートするには、以前にエクスポートしたファイルが格納されているバケットが必要です。バケットのサイズを設定する必要はありません。
  • Dataflow: インポート ジョブは、他の Dataflow ジョブと同じ CPU、ディスク使用量、IP アドレスの Compute Engine の割り当てに従います。
  • Compute Engine: インポート ジョブを実行する前に、Dataflow によって使用される Compute Engine の初期割り当てを設定する必要があります。これらの割り当ては、Dataflow でジョブに使用できる最大リソース数を表します。推奨の開始値は次のとおりです。

    • CPU: 200
    • 使用中の IP アドレス: 200
    • 標準永続ディスク: 50 TB

    通常、他の調整は必要ありません。Dataflow では自動スケーリングが提供されているため、インポート中に実際に使用したリソースに対してのみ料金を支払います。ジョブでより多くのリソースが使用される可能性がある場合、Dataflow UI に警告アイコンが表示されます。警告アイコンが表示されてもジョブは完了します。

IAM 要件

データベースをインポートするには、インポート ジョブに関連するすべてのサービスを使用するための十分な権限を持つ IAM のロールも必要です。ロールと権限の付与については、IAM ロールの適用をご覧ください。

データベースをインポートするには、次のロールが必要です。

  • Google Cloud プロジェクト レベル:
    • Cloud Spanner 閲覧者
    • Dataflow 管理者
    • ストレージ管理者
  • Cloud Spanner データベースまたはインスタンス レベル、あるいは Google Cloud プロジェクト レベル:
    • Cloud Spanner 読み取り
    • Cloud Spanner データベース管理者(インポート ジョブの場合のみ必要)

省略可: Cloud Storage でのデータベース フォルダの検索

Cloud Console で、エクスポートしたデータベースを含むフォルダを検索するには、Cloud Storage ブラウザに移動し、エクスポートされたフォルダを含むバケットをクリックします。

Cloud Storage ブラウザに移動

エクスポートされたデータを含むフォルダ名は、インスタンスの ID、データベース名、エクスポート ジョブのタイムスタンプで始まります。フォルダには以下が含まれています。

  • spanner-export.json ファイル
  • エクスポートしたデータベースの各テーブルの TableName-manifest.json ファイル。
  • 1 つ以上の TableName.avro-#####-of-##### ファイル。拡張子 .avro-#####-of-##### の最初の数字は 0 から始まる Avro ファイルのインデックスを表します。2 番目の数字は各テーブルに対して生成された Avro ファイルの数を表します。

    たとえば、Songs.avro-00001-of-00002 は、Songs テーブルのデータを含む 2 つのファイルのうちの 2 番目のファイルです。

データベースのインポート

Cloud Storage からインスタンスに Cloud Spanner データベースをインポートするには、次の手順を行います。

  1. Cloud Spanner インスタンス ページに移動します。

    インスタンス ページに移動

  2. インポートされたデータベースを含むインスタンスの名前をクリックします。

  3. [インポート / エクスポート] タブをクリックし、[インポート] ボタンをクリックします。

  4. [ソースフォルダを選択] で、[参照] をクリックします。

  5. 最初のリストでエクスポートを含むバケットを見つけます。または、[検索] 検索の UI 要素のスクリーンショット をクリックしてリストをフィルタリングし、バケットを見つけます。バケットをダブルクリックすると、そのバケットに含まれているフォルダが表示されます。

  6. エクスポートしたファイルを含むフォルダをクリックして選択します。

  7. [選択] をクリックします。

  8. 新しいデータベースの名前を入力します。インポート プロセスで、Cloud Spanner がこの名前でデータベースを作成します。インスタンスにすでに存在するデータベース名は使用できません。

  9. [インポート ジョブのリージョンを選択] プルダウン メニューで、リージョンを選択します。

  10. [料金を確認] にあるチェックボックスをオンにして、既存の Cloud Spanner ノードによって発生する料金以外に料金が発生することを確認します。

  11. [インポート] をクリックします。

    Cloud Console に [データベースの詳細] ページが表示されます。ここには、インポート ジョブを説明するボックスが表示されています(ジョブの経過時間など)。

    進行中のジョブのスクリーンショット

ジョブが完了または終了すると、Cloud Console の [データベースの詳細] ページにメッセージが表示されます。ジョブが成功した場合は、成功メッセージが表示されます。

インポート ジョブの成功メッセージ

ジョブが成功しなかった場合は、失敗メッセージが表示されます。

インポート ジョブの失敗メッセージ

ジョブが失敗した場合は、エラーの詳細についてジョブの Dataflow ログを確認し、失敗したインポート ジョブのトラブルシューティングをご覧ください。

インポート ジョブのリージョンの選択

Cloud Storage バケットでリージョン構成を使用するかマルチリージョン構成を使用するかによって、異なるリージョンの選択が必要になる場合があります。下り(外向き)ネットワーク料金が発生しないようにするには、Cloud Storage バケットのロケーションと重複するリージョンを選択します。

リージョン バケットのロケーション

Cloud Storage バケットのロケーションがリージョンである場合、無料のネットワーク使用を利用できるリージョンであれば、インポート ジョブに対し同じリージョンを選択します。

同じリージョンを利用できない場合は、下り(外向き)料金が適用されます。下り(外向き)ネットワーク料金が最小限になるリージョンを選択するには、Cloud Storage の下り(外向き)ネットワークの料金をご覧ください。

マルチリージョン バケットのロケーション

Cloud Storage バケットのロケーションがマルチリージョンである場合、無料のネットワーク使用を利用できるマルチリージョン ロケーションを構成するリージョンの 1 つを選択します。

重複するリージョンを利用できない場合は、下り(外向き)料金が適用されます。下り(外向き)ネットワーク料金が最小限になるリージョンを選択するには、Cloud Storage の下りネットワークの料金をご覧ください。

Dataflow UI でのジョブの表示またはトラブルシューティング

インポート ジョブの開始後、Cloud Console の Dataflow セクションで、ジョブの詳細(ログなど)を表示できます。

Dataflow ジョブの詳細の表示

現在実行中のジョブの詳細を表示するには:

  1. データベースの [データベースの詳細] ページに移動します。
  2. 次のようなジョブ ステータス メッセージ内の [Dataflow でジョブの詳細を表示] をクリックします。

    進行中のジョブのステータス メッセージ

    Cloud Console に Dataflow ジョブの詳細が表示されます。

最近実行したジョブを表示するには:

  1. データベースの [データベースの詳細] ページに移動します。
  2. [インポート / エクスポート] タブをクリックします。
  3. リスト内のジョブの名前をクリックします。

    Cloud Console に Dataflow ジョブの詳細が表示されます。

1 週間以上前に実行したジョブを表示するには:

  1. Cloud Console の Dataflow ジョブページに移動します。

    ジョブページに移動

  2. リスト内でジョブを見つけ、その名前をクリックします。

    Cloud Console に Dataflow ジョブの詳細が表示されます。

ジョブの Dataflow ログの表示

Dataflow ジョブのログを表示するには、上記の説明に従ってジョブの詳細ページに移動し、ジョブ名の右側にある [ログ] をクリックします。

ジョブが失敗した場合は、ログでエラーを探します。エラーがある場合、エラー数が [ログ] の横に表示されます。

[ログ] ボタンの横のエラー数の例

ジョブエラーを表示するには:

  1. [ログ] の横のエラー数をクリックします。

    Cloud Console にジョブのログが表示されます。エラーを表示するには、スクロールが必要な場合があります。

  2. エラーアイコン エラーアイコン が表示されているエントリを見つけます。

  3. 個別のログエントリをクリックして、その内容を展開します。

Dataflow ジョブのトラブルシューティングの詳細については、パイプラインをトラブルシューティングするをご覧ください。

失敗したインポート ジョブのトラブルシューティング

ジョブログに次のエラーが表示された場合、

com.google.cloud.spanner.SpannerException: NOT_FOUND: Session not found

--or--

com.google.cloud.spanner.SpannerException: DEADLINE_EXCEEDED: Deadline expired before operation could complete.

Cloud Console の Cloud Spanner データベースの [Monitoring] タブで 99% の書き込みレイテンシを確認します。高い値(数秒)が表示されている場合は、インスタンスが過負荷状態になっており、書き込みがタイムアウトになって失敗します。

レイテンシが高くなる原因の 1 つは、多すぎるワーカーを使用して Dataflow ジョブが走行しているため、Cloud Spanner インスタンスに負荷がかかりすぎることです。

Dataflow ワーカーの数の上限を指定するには、Cloud Console の Cloud Spanner データベースの [インスタンスの詳細] ページにある [インポート / エクスポート] タブは使用しません。その代わりに、Dataflow の Cloud Storage Avro to Cloud Spanner テンプレートを使用してインポートを開始し、以下のようにワーカーの最大数を指定します。
  • Dataflow コンソールを使用している場合、[最大ワーカー数] パラメータは、[テンプレートからジョブを作成] ページの [オプションのパラメータ] セクションに配置されます。

  • gcloud を使用している場合は、max-workers 引数を指定します。例:

    gcloud dataflow jobs run my-import-job \
    --gcs-location='gs://dataflow-templates/latest/GCS_Avro_to_Cloud_Spanner' \
    --region=us-central1 \
    --parameters='instanceId=test-instance,databaseId=example-db,inputDir=gs://my-gcs-bucket' \
    --max-workers=10
    

ワーカーの最大数はデータサイズに大きく依存しますが、Spanner の CPU 使用率の合計は 70~90% が理想的です。これにより、Spanner の効率性とエラーのないジョブ完了のバランスが良好になります。

大部分のスキーマ / シナリオでその使用率の目標を達成するには、ワーカー vCPU の最大数を Spanner ノードの数の 4〜6 倍にすることをおすすめします。

たとえば、n1-standard-2 ワーカーを使用する 10 ノードの spanner インスタンスの場合、最大ワーカー数を 25 に設定し、50 個の vCPU を割り当てます。

実行速度が遅いインポート ジョブの最適化

初期設定の提案に従っている場合は、通常、他の調整は必要ありません。ジョブの実行速度が遅い場合は、その他の最適化を試すことができます。

  • ジョブとデータのロケーションの最適化: Cloud Spanner インスタンスと Cloud Storage バケットが配置されている同じリージョン内で Dataflow ジョブを実行します。

  • 十分な Dataflow リソースの確保: 関連する Compute Engine の割り当てによって Dataflow ジョブのリソースが制限されている場合、Google Cloud Console の、ジョブの Dataflow ページに警告アイコン 警告アイコン とログメッセージが表示されます。

    割り当て上限の警告のスクリーンショット

    この場合、CPU、使用中の IP アドレス、標準永続ディスクの割り当てを増やすと、ジョブの実行時間が短くなる可能性がありますが、Compute Engine の追加料金が発生する場合があります。

  • Cloud Spanner の CPU 使用率の確認: インスタンスの CPU 使用率が 65% を超えている場合は、そのインスタンスのノード数を増やすことができます。追加のノードによって Cloud Spanner のリソースが増加し、ジョブの実行速度は速くなりますが、Cloud Spanner の追加料金が発生します。

インポート ジョブのパフォーマンスに影響する要素

インポート ジョブを完了するためにかかる時間には、いくつかの要素が影響します。

  • Cloud Spanner データベースのサイズ: 処理するデータ量が増加すると、必要となる時間とリソースも多くなります。

  • Cloud Spanner データベースのスキーマ: テーブルの数、行のサイズ、セカンダリ インデックスの数、外部キーの数が、インポート ジョブの実行にかかる時間に影響します。Dataflow インポート ジョブが完了した後も、インデックスと外部キーの作成は続行されます。

  • データのロケーション: データは、Dataflow により Cloud Spanner と Cloud Storage の間で転送されます。3 つのコンポーネントがすべて同じリージョン内にあることが理想的です。コンポーネントが同じリージョン内にない場合は、リージョン間のデータの移動によってジョブは遅くなります。

  • Dataflow ワーカーの数: 自動スケーリングを使用することにより、Dataflow では、処理する必要がある作業量に応じてジョブのワーカー数が選択されます。ただし、CPU、使用中の IP アドレス、標準永続ディスクの割り当てにより、ワーカー数には上限があります。割り当ての上限に達すると、Dataflow UI に警告アイコンが表示されます。この状況では、進捗は遅くなりますがジョブは完了します。

  • Cloud Spanner に対する既存の負荷: インポート ジョブを実行すると、Cloud Spanner インスタンスの CPU 負荷がかなり高くなります。インスタンスに既存の負荷がかなりある場合、このジョブの実行速度はさらに遅くなります。

  • Cloud Spanner ノードの数: インスタンスの CPU 使用率が 65% を超えると、ジョブの実行速度はさらに遅くなります。