Snowflake 的結構定義偵測和對應

本指南說明如何定義結構定義，以便將資料從 Snowflake 移轉至 BigQuery。您可以使用 BigQuery 資料移轉服務，自動偵測結構定義和資料類型對應關係，也可以使用翻譯引擎，手動定義結構定義和資料類型。

啟用自動偵測預設結構定義

Snowflake 連接器可自動偵測 Snowflake 資料表結構定義。如要使用自動偵測結構定義功能，請在設定 Snowflake 移轉作業時，將「Translation output GCS path」(翻譯輸出內容 GCS 路徑) 欄位留空。

下表顯示 Snowflake 連接器如何將 Snowflake 資料類型對應至 BigQuery：

  • 下列資料類型在 BigQuery 中會對應為 STRING：
    • TIMESTAMP_TZ
    • TIMESTAMP_LTZ
    • OBJECT
    • VARIANT
    • ARRAY
  • 下列資料類型在 BigQuery 中會對應為 TIMESTAMP：
    • TIMESTAMP_NTZ

所有其他 Snowflake 資料類型都會直接對應至 BigQuery 中的對等類型。

使用翻譯引擎輸出內容手動定義結構定義

將 Snowflake 資料表遷移至 BigQuery 時，Snowflake 專用 BigQuery 資料移轉服務連接器會使用 BigQuery 遷移服務翻譯引擎進行結構定義對應。

如要手動定義結構定義 (例如覆寫特定結構定義屬性)，可以先產生中繼資料，然後執行翻譯引擎。

限制

  • 資料會先以 Parquet 資料格式從 Snowflake 擷取，再載入 BigQuery：

    • 不支援下列 Parquet 資料類型：

    • 不支援下列 Parquet 資料類型，但可以轉換：

      • TIMESTAMP_NTZ
      • OBJECT、VARIANT、ARRAY

      執行翻譯引擎時，請使用全域類型轉換設定 YAML，覆寫這些資料類型的預設行為。

      YAML 設定檔大致如下：

      type: experimental_object_rewriter
global:
  typeConvert:
    datetime: TIMESTAMP
    json: VARCHAR

必要的服務帳戶權限

在 Snowflake 移轉作業中，服務帳戶會用於從指定 Cloud Storage 路徑中的翻譯引擎輸出內容讀取資料。您必須將 storage.objects.get 和 storage.objects.list 權限授予服務帳戶。

建議您將服務帳戶歸入建立移轉設定和目的地資料集的 Google Cloud 專案。如果服務帳戶所在的 Google Cloud 專案與建立 BigQuery 資料移轉作業的專案不同，則必須啟用跨專案服務帳戶授權。

詳情請參閱「BigQuery IAM 角色和權限」。

手動定義結構定義對應

您可以按照下列步驟，手動定義結構定義對應：

  1. 執行 Snowflake 的 dwh-migration-tool。詳情請參閱「產生翻譯和評估的中繼資料」。
  2. 將產生的 metadata.zip 檔案上傳至 Cloud Storage bucket。metadata.zip 檔案會做為翻譯引擎的輸入內容。

  3. 執行批次翻譯服務，並將 target_types 欄位指定為 metadata。詳情請參閱「使用 Translation API 翻譯 SQL 查詢」。

    • 以下是為 Snowflake 執行批次翻譯的指令範例：
      curl -d "{
  \"name\": \"sf_2_bq_translation\",
  \"displayName\": \"Snowflake to BigQuery Translation\",
  \"tasks\": {
      string: {
        \"type\": \"Snowflake2BigQuery_Translation\",
        \"translation_details\": {
            \"target_base_uri\": \"gs://sf_test_translation/output\",
            \"source_target_mapping\": {
              \"source_spec\": {
                  \"base_uri\": \"gs://sf_test_translation/input\"
              }
            },
            \"target_types\": \"metadata\",
        }
      }
  },
  }" \
  -H "Content-Type:application/json" \
  -H "Authorization: Bearer TOKEN" -X POST https://bigquerymigration.googleapis.com/v2alpha/projects/project_id/locations/location/workflows
    • 您可以在 BigQuery 的「SQL Translation」(SQL 翻譯) 頁面查看這項指令的狀態。批次翻譯工作的輸出內容會儲存在 gs://translation_target_base_uri/metadata/config/。

自訂結構定義檔案

如需擷取資料表的重要資訊 (例如主鍵)，建議您指定自訂結構定義，否則這些資訊會在遷移過程中遺失。舉例來說，進行增量移轉時，建議您指定自訂結構定義檔案，以便在後續移轉作業中，將資料載入 BigQuery 時能正確分區。如果沒有結構定義檔案，BigQuery 資料移轉服務會使用要移轉的來源資料，自動套用資料表結構定義，因此所有主鍵和變更追蹤資訊都可能遺失。

如果必須在資料移轉期間變更資料欄名稱或資料類型，自訂結構定義也很有幫助。

自訂結構定義檔案是描述資料庫物件的 JSON 檔案。結構定義包含一組資料庫，每個資料庫包含一組資料表，每個資料表包含一組資料欄。每個物件都有 originalName 欄位，指出 Snowflake 中的物件名稱，以及 name 欄位，指出 BigQuery 中物件的目標名稱。

資料欄包含下列欄位：

  • originalType：表示 Snowflake 中的資料欄資料類型
  • type：表示 BigQuery 中資料欄的目標資料類型。

  • usageType：系統使用資料欄的方式相關資訊。支援的用量類型如下：

    • DEFAULT：您可以使用這種用途類型，在一個目標資料表中為多個資料欄加上註解。DEFAULT 用途類型表示資料欄在來源系統中沒有特殊用途。這是預設值。
    • PRIMARY_KEY：您可以使用這種用途類型，為每個目標資料表中的資料欄加上註解。使用 PRIMARY_KEY 用途類型，將單一資料欄識別為主鍵，或是在複合索引鍵的情況下，在多個資料欄上使用相同的用途類型，識別資料表的不重複實體。這些資料欄會與 COMMIT_TIMESTAMP 搭配運作，擷取上次移轉作業執行後建立或更新的資料列。

以下範例顯示自訂結構定義檔案，用於移轉 my_db 資料庫中名為 orders 的 Snowflake 資料表、將 O_ORDERKEY 資料欄重新命名為 ORDERKEY，以及將 O_ORDERSTATUS 識別為主鍵。

{
  "databases": [
    {
      "name": "my_db",
      "originalName": "my_db",
      "tables": [
        {
          "name": "orders",
          "originalName": "orders",
          "columns": [
            {
              "name": "ORDERKEY",
              "originalName": "O_ORDERKEY",
              "type": "INT64",
              "originalType": "NUMERIC",
              "usageType": [
                "PRIMARY_KEY"
              ],
              "isRequired": true,
              "originalColumnLength": 4
            },
            {
              "name": "O_ORDERSTATUS",
              "originalName": "O_ORDERSTATUS",
              "type": "STRING",
              "originalType": "VARCHAR",
              "usageType": [
                "DEFAULT"
              ],
              "isRequired": true,
              "originalColumnLength": 1
            }
          ]
        }
      ]
    }
  ]
}