匯入及匯出資料

本文說明如何使用 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 和磁碟使用率偏高，進而影響現有工作負載。雖然這些工作通常會以低於一般流量的優先順序執行，但您仍應監控部署作業，以免對效能造成影響。

檔案格式比較

下表比較 Avro 和 CSV 檔案格式在匯入及匯出 Spanner 資料方面的功能。

功能	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)。如果使用本機檔案系統，請確保部署作業中所有伺服器上的資料路徑相同。

您可以透過下列兩種方式提供資料存放區的存取權：

在部署作業中新增外部儲存空間：如果您打算重複使用 bucket，建議採用這個方法。
建立一次性憑證：請確保這些憑證的有效時間長於匯入或匯出作業的持續時間 (例如 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 檔案。

如果已將資料存放區新增為外部儲存空間，則不必在路徑中加入憑證。您可以直接提供路徑。如果您使用一次性憑證，請使用下列網址格式：

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 檔案時，請注意下列資訊：

Spanner 說明文件：匯入產生的資料欄和變更串流。
Spanner 說明文件中的序列匯入注意事項。
Spanner 說明文件：匯入交錯資料表和外鍵的注意事項。
如要略過匯入特定實體，請從 spanner-export.json 檔案中移除這些實體。
如果資料集很大，建立索引可能需要相當長的時間。如要略過等待索引建立的程序，請使用選用的 --avro-skip-wait-for-index-creation 標記。

匯入作業順利啟動後，系統會傳回長期執行作業 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"}
      ]
    }
  ]
}

下列匯入指令中的網址必須指向包含 JSON 格式資訊清單檔案的資料夾，如資訊清單範例所述。這個檔案可以位於 Cloud Storage、Amazon S3 或本機檔案資料夾中，憑證的網址格式與Avro 匯入說明所述相同。如要開始匯入，請執行下列指令：

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 檔案的操作說明中的網址格式指示操作。

部署作業中的任何伺服器都可以將資料寫入提供的資料儲存庫。如果使用本機檔案資料夾做為目的地，請確保所有伺服器都能存取相同路徑，並可平行寫入。

系統會匯出資料庫中的所有資料表和實體。請務必提供匯出資料的新路徑，且該路徑不得包含任何資料夾。

如要開始匯出，請執行下列指令：

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

CSV 匯出功能僅支援資料表，不會匯出資料庫結構定義。

匯出為 CSV 檔案

CSV 匯出作業不會匯出資料庫結構定義，只會匯出支援資料表。如要將資料匯出為 CSV 檔案，請執行下列指令：

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

疑難排解

如果匯入失敗，結構定義更新和匯入的資料不會自動還原。請先手動清理資料庫，再重試作業。

匯入作業的速度取決於多項因素，包括資料夾中的檔案數量、部署作業中可用的運算資源，以及磁碟速度。如果可用資源充足，系統會平行匯入檔案。