このページでは、Cloud Spanner 以外のデータベースからエクスポートした Avro ファイルを準備し、それらのファイルを Cloud Spanner にインポートする方法について説明します。以前エクスポートした Cloud Spanner データベースをインポートする場合は、Cloud Spanner に Avro ファイルをインポートするをご覧ください。
このプロセスでは Dataflow を使用して、Avro ファイルのセットと、宛先テーブルを指定する JSON マニフェスト ファイルと各テーブルにデータを入力する Avro ファイルを含む Cloud Storage バケットからデータをインポートします。
準備
Cloud Spanner データベースをインポートするには、まず Cloud Spanner、Cloud Storage、Compute Engine、Dataflow API を有効にする必要があります。
また、十分な割り当てと必須の IAM 権限も必要です。
割り当て要件
インポート ジョブの割り当て要件は次のとおりです。
- 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 Spanner 以外のデータベースから Avro ファイルへのデータのエクスポート
インポート プロセスでは、Cloud Storage バケット内の Avro ファイルからデータを取り込みます。任意のソースからデータを Avro 形式でエクスポートできます。これにはさまざまな方法があります。
データをエクスポートするときは、次の点に留意してください。
- 任意の Avro プリミティブ型と配列複合型を使用してエクスポートできます。
Avro ファイルの各列には、次の列型のいずれかを使用する必要があります。
ARRAYBOOLBYTES*DOUBLEFLOATINTLONG†STRING‡
* 型
BYTESの列が Cloud SpannerNUMERICのインポートに使用されます。詳細については、下記の推奨されるマッピングをご覧ください。†,‡ タイムスタンプを格納する
LONGまたはタイムスタンプを格納するSTRINGを Cloud SpannerTIMESTAMPとしてインポートできます。詳細については、下記の推奨されるマッピングをご覧ください。Avro ファイルをエクスポートする際に、メタデータを含めたり生成したりする必要はありません。
ファイルについて特定の命名規則に従う必要はありません。
ファイルを Cloud Storage に直接エクスポートしない場合は、Avro ファイルを Cloud Storage バケットにアップロードする必要があります。詳細な手順については、オブジェクトのアップロードをご覧ください。
Cloud Spanner データベースのスキーマの作成
インポートを実行する前に、Cloud Spanner でターゲット テーブルを作成し、そのスキーマを定義する必要があります。
Avro ファイルの各列に対し適切な列型を使用するスキーマを作成する必要があります。
推奨されるマッピング
| Avro の列型 | Cloud Spanner の列型 |
|---|---|
ARRAY |
ARRAY |
BOOL |
BOOL |
BYTES |
|
DOUBLE |
FLOAT64 |
FLOAT |
FLOAT64 |
INT |
INT64 |
LONG |
|
STRING |
|
spanner-export.json ファイルの作成
Cloud Storage バケットに spanner-export.json という名前のファイルを作成する必要もあります。このファイルには、各テーブルの名前とデータファイルの場所を示す tables 配列を格納します。
ファイルの内容は次の形式を取ります。
{
"tables": [
{
"name": "TABLE1",
"dataFiles": [
"RELATIVE/PATH/TO/TABLE1_FILE1",
"RELATIVE/PATH/TO/TABLE1_FILE2"
]
},
{
"name": "TABLE2",
"dataFiles": ["RELATIVE/PATH/TO/TABLE2_FILE1"]
}
]
}
gcloud を使用した Dataflow インポート ジョブの実行
インポート ジョブを開始するには、Google Cloud CLI を使用して、Avro to Cloud Spanner テンプレートでジョブを実行する手順を行います。
インポート ジョブを開始したら、Cloud Console でジョブの詳細を確認できます。
インポート ジョブが完了したら、必要なセカンダリ インデックスと外部キーを追加します。
インポート ジョブのリージョンの選択
Cloud Storage バケットでリージョン構成を使用するかマルチリージョン構成を使用するかによって、異なるリージョンの選択が必要になる場合があります。下り（外向き）ネットワーク料金が発生しないようにするには、Cloud Storage バケットのロケーションと重複するリージョンを選択します。
リージョン バケットのロケーション
Cloud Storage バケットのロケーションがリージョンである場合、無料のネットワーク使用を利用できるリージョンであれば、インポート ジョブに対し同じリージョンを選択します。
同じリージョンを利用できない場合は、下り料金が適用されます。下り（外向き）ネットワーク料金が最小限になるリージョンを選択するには、Cloud Storage の下り（外向き）ネットワークの料金をご覧ください。
マルチリージョン バケットのロケーション
Cloud Storage バケットのロケーションがマルチリージョンである場合、無料のネットワーク使用を利用できるマルチリージョン ロケーションを構成するリージョンの 1 つを選択します。
重複するリージョンを利用できない場合は、下り料金が適用されます。下り（外向き）ネットワーク料金が最小限になるリージョンを選択するには、Cloud Storage の下りネットワークの料金をご覧ください。
Dataflow UI でのジョブの表示またはトラブルシューティング
インポート ジョブの開始後、Cloud Console の Dataflow セクションで、ジョブの詳細（ログなど）を表示できます。
Dataflow ジョブの詳細の表示
現在実行中のジョブを含む過去 1 週間以内のインポート / エクスポート ジョブの詳細を表示するには、次のコマンドを実行します。
- データベースの [データベースの詳細] ページに移動します。
- 左側のパネルにある [インポート / エクスポート] をクリックします。データベースの [インポート / エクスポート] ページに、最近のジョブのリストが表示されます。
データベースの [インポート / エクスポート] ページで、[Dataflow ジョブ名] 列のジョブ名をクリックします。
Cloud Console に Dataflow ジョブの詳細が表示されます。
1 週間以上前に実行したジョブを表示するには:
Cloud Console の Dataflow ジョブページに移動します。
リスト内でジョブを見つけ、その名前をクリックします。
Cloud Console に Dataflow ジョブの詳細が表示されます。
ジョブの Dataflow ログの表示
Dataflow ジョブのログを表示するには、上記の説明に従ってジョブの詳細ページに移動し、ジョブ名の右側にある [ログ] をクリックします。
ジョブが失敗した場合は、ログでエラーを探します。エラーがある場合、エラー数が [ログ] の横に表示されます。
![[ログ] ボタンの横のエラー数の例](https://cloud.google.com/static/spanner/docs/images/dataflow_error_count.png?hl=ja)
ジョブエラーを表示するには:
[ログ] の横のエラー数をクリックします。
Cloud Console にジョブのログが表示されます。エラーを表示するには、スクロールが必要な場合があります。
エラーアイコン
が表示されているエントリを見つけます。個別のログエントリをクリックして、その内容を展開します。
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
実行速度が遅いインポート ジョブの最適化
初期設定の提案に従っている場合は、通常、他の調整は必要ありません。ジョブの実行速度が遅い場合は、その他の最適化を試すことができます。
ジョブとデータのロケーションの最適化: 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 により Cloud Spanner と Cloud Storage の間で転送されます。3 つのコンポーネントがすべて同じリージョン内にあることが理想的です。コンポーネントが同じリージョン内にない場合は、リージョン間のデータの移動によってジョブは遅くなります。
Dataflow ワーカーの数: パフォーマンスの向上には、最適な Dataflow ワーカーが必要です。自動スケーリングを使用することにより、Dataflow では、処理する必要がある作業量に応じてジョブのワーカー数が選択されます。ただし、CPU、使用中の IP アドレス、標準永続ディスクの割り当てにより、ワーカー数には上限があります。割り当ての上限に達すると、Dataflow UI に警告アイコンが表示されます。この状況では、進捗は遅くなりますがジョブは完了します。インポートするデータの量が多い場合は、自動スケーリングによって Cloud Spanner が過負荷状態になり、エラーが発生する可能性があります。
Cloud Spanner に対する既存の負荷: インポート ジョブを実行すると、Cloud Spanner インスタンスの CPU 負荷がかなり高くなります。インスタンスに既存の負荷がかなりある場合、このジョブの実行速度はさらに遅くなります。
Cloud Spanner のコンピューティング容量の量: インスタンスの CPU 使用率が 65% を超えると、ジョブの実行はさらに遅くなります。
インポート パフォーマンスの向上のためのワーカーの調整
Cloud Spanner のインポート ジョブを開始する際は、良好なパフォーマンスを実現するために、Dataflow ワーカーを最適な値に設定する必要があります。過剰な数のワーカーが存在すると Cloud Spanner が過負荷状態になり、ワーカー数が過剰に少ない場合はインポートのパフォーマンスが低下します。
ワーカーの最大数はデータサイズに大きく依存しますが、Spanner の CPU 使用率の合計は 70～90% が理想的です。これにより、Spanner の効率性とエラーのないジョブ完了のバランスが良好になります。
大部分のスキーマ / シナリオでその使用率の目標を達成するには、ワーカー vCPU の最大数を Spanner ノードの数の 4〜6 倍にすることをおすすめします。
たとえば、n1-standard-2 ワーカーを使用する 10 ノードの spanner インスタンスの場合、最大ワーカー数を 25 に設定し、50 個の vCPU を割り当てます。