データのインポートとエクスポート

このドキュメントでは、Avro 形式と CSV 形式を使用して Spanner Omni でデータを移行、バックアップ、転送する方法について説明します。Spanner Omni CLI を使用して、Spanner Omni と Cloud Storage、Amazon Simple Storage Service（Amazon S3）、S3 互換ローカル ストレージ、ローカル ファイル システム（NFS）などのストレージ ソリューション間でデータベース コンテンツを移動します。Spanner Omni のインポートとエクスポートのデータフローでは、モデル、地域グループ、配置はサポートされていません。

インポート オペレーションとエクスポート オペレーションは Spanner Omni サーバーで実行され、使用可能なシステムリソースを共有します。インポートはリソースを大量に消費するため、RAM、CPU、ディスクの使用率が高くなり、アクティブなワークロードに影響する可能性があります。通常、これらのタスクは通常のトラフィックよりも低い優先度で実行されますが、デプロイのパフォーマンスに影響する可能性があるため、モニタリングする必要があります。

ファイル形式の比較

次の表は、Spanner データのインポートとエクスポートにおける Avro ファイル形式と CSV ファイル形式の機能の違いを示しています。

能力 Avro CSV
データベース全体をインポートまたはエクスポートする はい いいえ
以前にエクスポートしたテーブルをインポートする はい はい
過去のタイムスタンプでエクスポートする はい はい
Spanner を使用してインポートまたはエクスポートする はい はい
他のデータベースからデータをインポートする いいえ はい

Avro 形式と CSV 形式の両方で、データベース内のすべてのテーブルがエクスポートされます。Avro 形式ではスキーマもエクスポートされるため、再度インポートできます。CSV 形式ではスキーマはエクスポートされません。

始める前に

インポート オペレーションまたはエクスポート オペレーションを開始する前に、権限を確認し、データ ストレージの場所にアクセスできるように構成します。

権限

開始する前に、次の権限があることを確認してください。

  • spanner.databases.import
  • spanner.databases.export

Spanner Omni の Identity and Access Management（IAM）の詳細については、 IAM の概要をご覧ください。ユーザーのロールを更新する方法については、ユーザーを更新するをご覧ください。

データソースと宛先

データは、Amazon Simple Storage Service（Amazon S3）バケット、Cloud Storage バケット、Amazon S3 互換ローカル ストレージ（MinIO など）、ローカル ファイル システム（NFS）に保存できます。ローカル ファイル システムを使用する場合は、デプロイ内のすべてのサーバーで同じパスでデータを使用できることを確認してください。

データストアへのアクセス権を付与するには、次の 2 つの方法があります。

  • デプロイに外部ストレージを追加する: バケットを再利用する場合は、この方法をおすすめします。

  • ワンタイム認証情報を作成する: これらの認証情報は、インポート オペレーションまたはエクスポート オペレーションの期間（48 時間など）よりも長く保持されるようにしてください。

認証情報には、インポート用のバケット内のオブジェクトを一覧表示して読み取る権限が必要です。Amazon S3 にエクスポートする場合は、次の追加の Amazon S3 権限が必要です。

  • s3:PutObject
  • s3:AbortMultipartUpload
  • s3:ListBucketMultipartUploads

詳細については、 IAM 権限をご覧ください。

Spanner Avro ファイルをインポートする

別の Spanner データベース（Spanner または Spanner Omni）から Avro 形式でエクスポートしたデータをインポートする手順は次のとおりです。

Avro インポートの前提条件

Avro インポートを開始する前に、環境が次の要件を満たしていることを確認してください。

  • 宛先データベースを作成している。

  • インポートするスキーマ オブジェクトがデータベースにまだ存在しない。 Avro インポート プロセスでは、データをインポートする前にこれらのテーブルが作成されます。

Avro インポートの手順

エクスポートされたデータが格納されているフォルダのパスを特定します。フォルダには次のものが含まれています。

  • spanner-export.json ファイル。

  • エクスポートされた エンティティ（テーブル、シーケンス、スキーマなど）ごとに ENTITY_NAME-manifest.json ファイル。

  • マニフェスト ファイルに記載されているすべての Avro ファイル。

データストアを外部ストレージとして追加している場合は、パスに認証情報を含める必要はありません。パスを直接指定できます。ワンタイム認証情報を使用する場合は、次の URL 形式を使用します。

  • Cloud Storage: gs://BUCKET_NAME/BASE_FOLDER[?accesskey=ACCESS_KEY&secret=SECRET_KEY]. HMAC 認証情報を使用します。詳細については、HMAC キーをご覧ください。

  • Amazon S3: s3://S3_BUCKET/BASE_FOLDER[?accesskey=ACCESS_KEY&secret=SECRET_KEY[&sessiontoken=SESSION_TOKEN]]

  • ローカル ファイル フォルダ*: file:///PATH_TO_DIR

インポートを開始するには、次のコマンドを実行します。

spanner databases import DATABASE_ID --url="URL" --format=avro [--avro-skip-wait-for-index-creation]

その他の情報

Avro ファイルをインポートする際は、次の点に留意してください。

インポート オペレーションが正常に開始されると、長時間実行オペレーション ID が返されます。この ID を使用して、オペレーションのステータスを追跡します。

CSV ファイルをインポートする

別のデータベースからエクスポートしたテキスト データをインポートする手順は次のとおりです。

CSV インポートの前提条件

CSV インポートを開始する前に、次のことを行っていることを確認してください。

  • テーブルが、BOOL、INT64、FLOAT64、NUMERIC、STRING、DATE、TIMESTAMP、BYTES、JSON のいずれかのサポートされているデータ型であることを確認します。

  • 宛先データベースを作成します。

  • データをインポートするすべてのテーブルを作成します。CSV インポート プロセスではテーブルは作成されません。

  • CSV ファイルにヘッダー行が含まれていないことを確認します。

CSV インポートの手順

CSV ファイルをインポートするには、インポートするデータを記述するマニフェスト ファイルを作成します。 マニフェスト ファイルは次の構造を使用します。これは protobuf 形式で定義されています。

message ImportManifest {
  // The per-table import manifest.
  message TableManifest {
    // Required. The name of the destination table.
    string table_name = 1;
    // Required. The CSV files to import. This value can be either a path or a glob pattern.
    repeated string file_patterns = 2;
    // The schema for a table column.
    message Column {
      // Required for each column that you specify. The name of the column in the
      // destination table.
      string column_name = 1;
      // Required for each column that you specify. The type of the column.
      string type_name = 2;
    }
    // Optional. The schema for the table columns.
    repeated Column columns = 3;
  }
  // Required. The TableManifest of the tables to be imported.
  repeated TableManifest tables = 1;

  enum ProtoDialect {
    GOOGLE_STANDARD_SQL = 0;
    POSTGRESQL = 1;
  }
  // Optional. The dialect of the receiving database. Defaults to GOOGLE_STANDARD_SQL.
  ProtoDialect dialect = 2;
}

次にマニフェストの例を示します。

{
  "tables": [
    {
      "table_name": "Albums",
      "file_patterns": [
        "gs://bucket1/Albums_1.csv",
        "gs://bucket1/Albums_2.csv"
      ]
    },
    {
      "table_name": "Singers",
      "file_patterns": [
        "gs://bucket1/Singers*.csv"
      ],
      "columns": [
        {"column_name": "SingerId", "type_name": "INT64"},
        {"column_name": "FirstName", "type_name": "STRING"},
        {"column_name": "LastName", "type_name": "STRING"}
      ]
    }
  ]
}

次の CSV ファイルにヘッダー行が含まれていませんインポート コマンドの URL は、マニフェストの例で説明されているように、JSON 形式のマニフェストファイルを含むフォルダを指している必要があります。 マニフェストの例で説明されているように、JSON 形式のマニフェストファイルを含むフォルダを指している必要があります。このファイルは、Avro インポートの手順で説明されているのと同じ URL 形式の認証情報を使用して、Cloud Storage、Amazon S3、またはローカル ファイル フォルダに配置できます。インポートを開始するには、次のコマンドを実行します。

spanner databases import DATABASE_ID --url="URL" --format=csv

CSV インポートのオプション

次のフラグを使用して、Spanner Omni でテキスト ファイルを処理する方法をカスタマイズします。

  • --csv-date-format: 日付列の形式をオーバーライドします。デフォルトは %Y-%m-%d です。例: %d/%m/%Y。

  • --csv-timestamp-format: タイムスタンプ列の形式をオーバーライドします。これは、Spanner Omni が CSV の形式をサポートしていない場合にのみ使用します。 例: %d/%m/%Y %H:%M:%S%Ez。

  • --csv-delimiter: 区切り文字をオーバーライドします。デフォルトはカンマです。

  • --csv-quote-char: 引用符をオーバーライドします。デフォルトは二重引用符です。

  • --csv-escape-char: エスケープ文字をオーバーライドします。デフォルトは二重引用符です。

  • --csv-null-string: NULL 値を表す文字列をオーバーライドします。デフォルトは \N です。

  • --csv-has-trailing-delimiters: CSV ファイルに末尾の区切り文字があるかどうかを指定します。デフォルトは false です。

Avro ファイルにエクスポートする

データを Avro ファイルにエクスポートするには、 Avro インポートの手順の URL 形式の手順に沿って操作します。

デプロイ内の任意のサーバーで、指定されたデータストアにデータを書き込むことができます。宛先としてローカル ファイル フォルダを使用する場合は、すべてのサーバーが同じパスにアクセスでき、並行して書き込めるようにしてください。

システムは、データベース内のすべてのテーブルとエンティティをエクスポートします。エクスポートされたデータの新しい空のフォルダパスを指定してください。

エクスポートを開始するには、次のコマンドを実行します。

spanner databases export DATABASE_ID --url="URL" --format=avro

CSV エクスポートはテーブルのみをサポートし、データベース スキーマはエクスポートしません。

CSV ファイルにエクスポートする

CSV エクスポートでは、データベース スキーマはエクスポートされず、テーブルのみがサポートされます。データを CSV ファイルにエクスポートするには、次のコマンドを実行します。

spanner databases export DATABASE_ID --url="URL" --format=csv

トラブルシューティング

インポートが失敗した場合、スキーマの更新とインポートされたデータは自動的に元に戻りません。 オペレーションを再試行する前に、データベースを手動でクリーンアップしてください。

インポート オペレーションの速度は、フォルダ内のファイル数、デプロイで使用可能なコンピューティング リソース、ディスク速度など、いくつかの要因によって異なります。十分なリソースが使用可能な場合、システムはファイルを並行してインポートします。