このページでは、Google Cloud コンソールを使用して Spanner データベースを Spanner にインポートする方法について説明します。他のソースから Avro ファイルをインポートする方法については、Spanner 以外のデータベースからデータをインポートするをご覧ください。
このプロセスでは Dataflow を使用して、Avro ファイルと JSON マニフェスト ファイルのセットを含む Cloud Storage バケット フォルダからデータをインポートします。このインポート プロセスでは、Spanner からエクスポートされた Avro ファイルのみがサポートされます。
REST API またはgcloud CLIを使用して Spanner データベースをインポートするには、このページの始める前にの手順を行ってから、Cloud Storage Avro から Spanner の詳細手順をご覧ください。
始める前に
Spanner データベースをインポートするには、まず Spanner、Cloud Storage、Compute Engine、Dataflow API を有効にする必要があります。
また、十分な割り当てと必須の IAM 権限も必要です。
割り当て要件
インポート ジョブの割り当て要件は次のとおりです。
- Spanner: インポートするデータの量をサポートできるだけのコンピューティング容量が必要です。データベースをインポートするために追加のコンピューティング容量は必要ありませんが、ジョブが妥当な時間内に終了するようにコンピューティング容量を追加する必要がある場合があります。詳細については、ジョブを最適化するをご覧ください。
- Cloud Storage: インポートするには、以前にエクスポートしたファイルが格納されているバケットが必要です。バケットのサイズを設定する必要はありません。
- Dataflow: インポート ジョブは、他の Dataflow ジョブと同じ CPU、ディスク使用量、IP アドレスの Compute Engine の割り当てに従います。
Compute Engine: インポート ジョブを実行する前に、Dataflow によって使用される Compute Engine の初期割り当てを設定する必要があります。これらの割り当ては、Dataflow でジョブに使用できる最大リソース数を表します。推奨の開始値は次のとおりです。
- CPU: 200
- 使用中の IP アドレス: 200
- 標準永続ディスク: 50 TB
通常、他の調整は必要ありません。 Dataflow では自動スケーリングが提供されているため、インポート中に実際に使用したリソースに対してのみ料金を支払います。ジョブでより多くのリソースが使用される可能性がある場合、Dataflow UI に警告アイコンが表示されます。警告アイコンが表示されてもジョブは完了します。
必要なロール
データベースのエクスポートに必要な権限を取得するには、Dataflow ワーカー サービス アカウントに対する次の IAM ロールを付与するよう管理者に依頼します。
-
Cloud Spanner 閲覧者（
roles/spanner.viewer） - Dataflow ワーカー（
roles/dataflow.worker） -
ストレージ管理者（
roles/storage.admin） -
Spanner データベース リーダー（
roles/spanner.databaseReader） - データベース管理者（
roles/spanner.databaseAdmin）
省略可: Cloud Storage でのデータベース フォルダの検索
Cloud コンソールで、エクスポートしたデータベースを含むフォルダを検索するには、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 番目のファイルです。エクスポートしたデータベースの変更ストリームごとの
ChangeStreamName-manifest.jsonファイル。各変更ストリームの
ChangeStreamName.avro-00000-of-00001ファイル。このファイルには、変更ストリームの Avro スキーマのみを含む空のデータが含まれています。
データベースのインポート
Cloud Storage からインスタンスに Spanner データベースをインポートするには、次の手順を行います。
[Spanner インスタンス] ページに移動
インポートされたデータベースを含むインスタンスの名前をクリックします。
左側のペインで [インポート / エクスポート] メニュー項目をクリックし、[インポート] ボタンをクリックします。
[ソースフォルダを選択] で、[参照] をクリックします。
最初のリストでエクスポートを含むバケットを見つけます。または、[検索]
をクリックしてリストをフィルタリングし、バケットを見つけます。バケットをダブルクリックすると、そのバケットに含まれているフォルダが表示されます。エクスポートしたファイルを含むフォルダをクリックして選択します。
[選択] をクリックします。
インポート プロセス中に Spanner が作成する新しいデータベースの名前を入力します。インスタンスにすでに存在するデータベース名は使用できません。
新しいデータベース（GoogleSQL または PostgreSQL）の言語を選択します。
（省略可）新しいデータベースを顧客管理の暗号鍵で保護するには、[暗号化オプションを表示] をクリックして [顧客管理の暗号鍵（CMEK）を使用する]を選択します。次にプルダウン リストからキーを選択します。
[インポート ジョブのリージョンを選択] プルダウン メニューで、リージョンを選択します。
（省略可）顧客管理の暗号鍵を使用して Dataflow パイプラインの状態を暗号化するには、[暗号化オプションを表示] をクリックして [顧客管理の暗号鍵（CMEK）を使用する] を選択します。次にプルダウン リストから鍵を選択します。
[料金を確認] にあるチェックボックスをオンにして、既存の Spanner ノードによって発生する料金以外に料金が発生することを確認します。
[インポート] をクリックします。
Google Cloud コンソールに [データベースの詳細] ページが表示されます。ここには、インポート ジョブを説明するボックスが表示されています（ジョブの経過時間など）。
ジョブが完了または終了すると、Google Cloud コンソールの [データベースの詳細] ページにメッセージが表示されます。ジョブが成功した場合は、成功メッセージが表示されます。
ジョブが成功しなかった場合は、失敗メッセージが表示されます。
ジョブが失敗した場合は、エラーの詳細についてジョブの Dataflow ログを確認し、失敗したインポート ジョブのトラブルシューティングをご覧ください。
生成された列と変更ストリームのインポートに関する注意事項
Spanner は、Avro スキーマで各々の生成された列の定義を使用して、その列を再作成します。Spanner は、インポート時に生成された列の値を自動的に計算します。
同様に、Spanner は Avro スキーマの各々の変更ストリームの定義を使用して、インポート時に再作成します。変更ストリーム データは Avro を介してエクスポートもインポートもされないため、新しくインポートされたデータベースに関連付けられたすべての変更ストリームに変更データレコードはありません。
シーケンスのインポートに関する注意事項
Spanner がエクスポートする各シーケンス（GoogleSQL、PostgreSQL）が GET_INTERNAL_SEQUENCE_STATE()（GoogleSQL、PostgreSQL）関数を使用して現在の状態をキャプチャします。Spanner は、1,000 のバッファをカウンタに追加し、新しいカウンタ値をレコード フィールドのプロパティに書き込みます。これは、インポート後に発生する可能性のある値の重複エラーを回避するためのみの、ベスト エフォート型アプローチにすぎません。データのエクスポート中にソース データベースへの書き込みが増加した場合は、実際のシーケンス カウンタを調整します。
インポート時に、シーケンスはスキーマで見つかったカウンタではなく、この新しいカウンタから開始されます。必要に応じて、ALTER SEQUENCE（GoogleSQL、PostgreSQL）ステートメントを使用して新しいカウンタに更新できます。
インターリーブされたテーブルと外部キーのインポートに関する注意事項
Dataflow ジョブはインターリーブされたテーブルをインポートできるため、ソースファイルの親子関係を保持できます。ただし、データの読み込み中に外部キー制約は適用されません。Dataflow ジョブは、データの読み込みが完了すると、必要な外部キーをすべて作成します。
インポートの開始前に Spanner データベースに外部キー制約がある場合、参照整合性違反により書き込みエラーが発生することがあります。書き込みエラーを回避するには、インポート プロセスを開始する前に、既存の外部キーを削除することを検討してください。
インポート ジョブのリージョンの選択
Cloud Storage バケットのロケーションに基づいて異なるリージョンを選択する場合があります。送信データ転送料金が発生しないようにするには、Cloud Storage バケットのロケーションと一致するリージョンを選択します。
Cloud Storage バケットのロケーションがリージョンである場合、次の前提で、インポート ジョブに同じリージョンを選択することで、無料のネットワーク使用を利用できます。
Cloud Storage バケットのロケーションがデュアルリージョンである場合、いずれかのリージョンが使用可能であると仮定すると、構成する 2 つのリージョンのいずれかを選択して、無料のネットワーク使用を利用できます。
併置リージョンがインポート ジョブで利用できない場合、または Cloud Storage バケットのロケーションがマルチリージョンである場合は、アウトバウンド データ転送料金が適用されます。データ転送料金が最も低いリージョンを選択するには、Cloud Storage のデータ転送の料金をご覧ください。
Dataflow UI でジョブを表示またはトラブルシューティングする
インポート ジョブの開始後、Google Cloud コンソールの Dataflow セクションで、ジョブの詳細（ログなど）を表示できます。
Dataflow ジョブの詳細を表示する
現在実行中のジョブを含む過去 1 週間以内に実行したインポートまたはエクスポート ジョブの詳細を表示するには、次のコマンドを実行します。
- データベースの [データベースの詳細] ページに移動します。
- 左側のパネルにある [インポート / エクスポート] をクリックします。データベースの [インポート / エクスポート] ページに、最近のジョブのリストが表示されます。
データベースの [インポート / エクスポート] ページで、[Dataflow ジョブ名] 列のジョブ名をクリックします。
Google Cloud コンソールに Dataflow ジョブの詳細が表示されます。
1 週間以上前に実行したジョブを表示するには:
Google Cloud コンソールの Dataflow ジョブページに移動します。
リスト内でジョブを見つけ、その名前をクリックします。
Google Cloud コンソールに Dataflow ジョブの詳細が表示されます。
ジョブの Dataflow ログを表示する
Dataflow ジョブのログを表示するには、ジョブの詳細ページに移動し、ジョブ名の右側にある [ログ] をクリックします。
ジョブが失敗した場合は、ログでエラーを探します。エラーがある場合、エラー数が [ログ] の横に表示されます。
![[ログ] ボタンの横のエラー数の例](https://cloud-dot-devsite-v2-prod.appspot.com/static/spanner/docs/images/dataflow_error_count.png?hl=ja)
ジョブエラーを表示するには:
[ログ] の横のエラー数をクリックします。
Google Cloud コンソールにジョブのログが表示されます。エラーを表示するには、スクロールが必要な場合があります。
エラーアイコン
が表示されているエントリを見つけます。個別のログエントリをクリックして、その内容を展開します。
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.
Google Cloud コンソールで Spanner データベースの [モニタリング] タブで、99% の書き込みレイテンシを確認します。高い値（数秒）が表示されている場合は、インスタンスが過負荷状態になっており、書き込みがタイムアウトになって失敗します。
レイテンシが高くなる原因の 1 つは、多すぎるワーカーを使用して Dataflow ジョブが走行しているため、Spanner インスタンスに負荷がかかりすぎることです。
Dataflow ワーカーの数の上限を指定するには、Google Cloud コンソールの Spanner データベースの [インスタンスの詳細] ページにある [インポート / エクスポート] タブは使用しません。その代わりに、Dataflow の Cloud Storage Avro to Spanner テンプレートを使用してインポートを開始し、以下のようにワーカーの最大数を指定します。コンソール
Dataflow コンソールを使用している場合、[最大ワーカー数] パラメータは、[テンプレートからジョブを作成] ページの [オプションのパラメータ] セクションに配置されます。
gcloud
gcloud dataflow jobs run コマンドを実行し、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 \
--network=network-123
ネットワーク エラーのトラブルシューティング
Spanner データベースをエクスポートすると、次のエラーが発生することがあります。
Workflow failed. Causes: Error: Message: Invalid value for field 'resource.properties.networkInterfaces[0].subnetwork': ''. Network interface must specify a subnet if the network resource is in custom subnet mode. HTTP Code: 400
このエラーは、Dataflow ジョブと同じプロジェクトで default という名前の自動モード VPC ネットワークを使用する予定であると Spanner が想定しているために発生します。プロジェクト内にデフォルトの VPC ネットワークがない場合や、VPC ネットワークがカスタムモードの VPC ネットワークにある場合は、Dataflow ジョブを作成し、代替のネットワークまたはサブネットワークを指定する必要があります。
実行速度が遅いインポート ジョブを最適化する
初期設定の提案に従っている場合は、通常、他の調整は必要ありません。ジョブの実行速度が遅い場合は、その他の最適化を試すことができます。
ジョブとデータのロケーションの最適化: Spanner インスタンスと Cloud Storage バケットが配置されている同じリージョン内で Dataflow ジョブを実行します。
十分な Dataflow リソースの確保: 関連する Compute Engine の割り当てによって Dataflow ジョブのリソースが制限されている場合、Google Cloud Console の、ジョブの Dataflow ページに警告アイコン
とログメッセージが表示されます。
この場合、CPU、使用中の IP アドレス、標準永続ディスクの割り当てを増やすと、ジョブの実行時間が短くなる可能性がありますが、Compute Engine の追加料金が発生する場合があります。
Spanner の CPU 使用率の確認: インスタンスの CPU 使用率が 65% を超えている場合は、そのインスタンスのコンピューティング容量を増やすことができます。容量を追加すると Spanner のリソースが増加し、ジョブの実行速度は速くなりますが、Spanner の追加料金が発生します。
インポート ジョブのパフォーマンスに影響する要素
インポート ジョブを完了するためにかかる時間には、いくつかの要素が影響します。
Spanner データベースのサイズ: 処理するデータ量が増加すると、必要となる時間とリソースも多くなります。
Spanner データベース スキーマ。次のものが含まれます。
- テーブルの数
- 行のサイズ
- セカンダリ インデックスの数
- 外部キーの数
- 変更ストリームの数
Dataflow インポート ジョブが完了した後も、インデックスと外部キーの作成は続行されます。変更ストリームは、インポート ジョブの完了前、ただしすべてのデータがインポートされた後に作成されます。
データのロケーション: データは、Dataflow により Spanner と Cloud Storage の間で転送されます。3 つのコンポーネントがすべて同じリージョン内にあることが理想的です。コンポーネントが同じリージョン内にない場合は、リージョン間のデータの移動によってジョブは遅くなります。
Dataflow ワーカーの数: パフォーマンスの向上には、最適な Dataflow ワーカーが必要です。自動スケーリングを使用することにより、Dataflow では、処理する必要がある作業量に応じてジョブのワーカー数が選択されます。ただし、CPU、使用中の IP アドレス、標準永続ディスクの割り当てにより、ワーカー数には上限があります。割り当ての上限に達すると、Dataflow UI に警告アイコンが表示されます。この状況では、進捗は遅くなりますがジョブは完了します。インポートするデータの量が多い場合は、自動スケーリングによって Spanner が過負荷状態になり、エラーが発生する可能性があります。
Spanner に対する既存の負荷: インポート ジョブを実行すると、Spanner インスタンスに対する CPU 負荷が大幅に上昇します。 インスタンスに既存の負荷がかなりある場合、このジョブの実行速度はさらに遅くなります。
Spanner のコンピューティング容量: インスタンスの CPU 使用率が 65% を超えると、ジョブの実行速度はさらに低下します。
インポート パフォーマンスの向上のためにワーカーを調整する
Spanner のインポート ジョブを開始する際は、良好なパフォーマンスを実現するために、Dataflow ワーカーを最適な値に設定する必要があります。過剰な数のワーカーが存在すると Spanner が過負荷状態になり、ワーカー数が過剰に少ない場合はインポートのパフォーマンスが低下します。
ワーカーの最大数はデータサイズに大きく依存しますが、Spanner の CPU 使用率の合計は 70～90% が理想的です。これにより、Spanner の効率性とエラーのないジョブ完了のバランスが良好になります。
大部分のスキーマ / シナリオでその使用率の目標を達成するには、ワーカー vCPU の最大数を Spanner ノードの数の 4〜6 倍にすることをおすすめします。
たとえば、n1-standard-2 ワーカーを使用する 10 ノードの Spanner インスタンスの場合、最大ワーカー数を 25 に設定し、50 個の vCPU を割り当てます。