Spanner 變更串流到 BigQuery 範本

使用 Spanner 變更串流至 BigQuery 範本,即可透過 Dataflow 可攜式執行工具,從 Spanner 串流資料變更記錄,並寫入 BigQuery 資料表。這項操作會將 Spanner 資料與 BigQuery 整合,用於即時分析和資料倉儲。

範本總覽

未監控的資料欄不會納入 BigQuery 資料列。任何小於 Dataflow 水位標記的 Spanner 變更,都會成功套用至 BigQuery 資料表,或儲存在無效信件佇列中等待重試。與原始 Spanner 提交時間戳記排序相比,BigQuery 資料列的插入順序不一致。

如果必要的 BigQuery 資料表不存在,管道會建立這些資料表。否則會使用現有的 BigQuery 資料表。現有 BigQuery 資料表的結構定義,必須包含 Spanner 資料表的對應追蹤資料欄,以及 ignoreFields 選項未明確忽略的任何其他中繼資料欄。請參閱下列清單中的中繼資料欄位說明。每個新的 BigQuery 資料列都包含變更串流監控的所有資料欄,這些資料欄來自 Spanner 資料表中對應的資料列,時間戳記為變更記錄的時間戳記。

下列中繼資料欄位會新增至 BigQuery 資料表。如要進一步瞭解這些欄位,請參閱「變更串流分區、記錄和查詢」中的「資料變更記錄」。

  • _metadata_spanner_mod_type:Spanner 交易的修改類型 (插入、更新或刪除)。從變更串流資料變更記錄中擷取。
  • _metadata_spanner_table_name::Spanner 資料表名稱。這個欄位並非連接器的中繼資料表名稱。
  • _metadata_spanner_commit_timestamp:Spanner 修訂版本時間戳記,也就是修訂變更的時間。這個值是從變更串流資料變更記錄中擷取。
  • _metadata_spanner_server_transaction_id:全域不重複字串,代表提交變更的 Spanner 交易。請只在處理變更串流記錄時使用這個值。與 Spanner API 中的交易 ID 無關。這個值是從變更串流資料變更記錄中擷取。
  • _metadata_spanner_record_sequence:Spanner 交易中記錄的序號。序號一律不重複,且在交易中會單調遞增,但不一定連續。這個值是從變更串流資料變更記錄中擷取。
  • _metadata_spanner_is_last_record_in_transaction_in_partition:指出記錄是否為目前分區中 Spanner 交易的最後一筆記錄。這個值是從變更串流資料變更記錄中擷取。
  • _metadata_spanner_number_of_records_in_transaction:所有變更串流分區中,屬於 Spanner 交易的資料變更記錄數量。這個值是從變更串流資料變更記錄中擷取。
  • _metadata_spanner_number_of_partitions_in_transaction:傳回 Spanner 交易資料變更記錄的分區數量。這個值是從變更串流資料變更記錄中擷取。
  • _metadata_big_query_commit_timestamp:資料列插入 BigQuery 的修訂版本時間戳記。如果 useStorageWriteApi 為 true,管道就不會在異動記錄資料表中自動建立這個資料欄。在這種情況下,您必須在異動記錄資料表中手動新增這個資料欄,並視需要將 CURRENT_TIMESTAMP 設為預設值。

使用這個範本時,請注意下列事項:

  • 您可以使用這個範本,將現有資料表的新資料欄或新資料表從 Spanner 傳播至 BigQuery。詳情請參閱「處理新增追蹤資料表或資料欄」。
  • 如果是 OLD_AND_NEW_VALUES 和 NEW_VALUES 值擷取類型,當資料變更記錄包含 UPDATE 變更時,範本必須在資料變更記錄的修訂版本時間戳記,對 Spanner 執行過時讀取,擷取未變更但受監控的資料欄。請務必正確設定資料庫的「version_retention_period」,以便進行過時讀取。如果是 NEW_ROW 值擷取類型,範本會更有效率,因為資料變更記錄會擷取完整的新資料列,包括 UPDATE 要求中未更新的資料欄,且範本不需要執行過時讀取。
  • 為了縮短網路延遲時間並降低網路傳輸成本,請在 Spanner 執行個體或 BigQuery 資料表所在的區域執行 Dataflow 工作。如果您使用的來源、接收器、暫存檔案位置或臨時檔案位置位於工作區域「外部」,則可能會跨區域傳送資料。詳情請參閱「Dataflow 區域」。
  • 這個範本支援所有有效的 Spanner 資料類型。如果 Spanner 類型比 BigQuery 類型更精確,轉換期間可能會遺失精確度。具體問題包括:
    • 如果是 Spanner JSON 類型,物件成員會依字母順序排列,但 BigQuery JSON 類型不保證會依字母順序排列。
    • Spanner 支援 TIMESTAMP 類型的奈秒精確度,但這個範本會以微秒精確度寫入 BigQuery TIMESTAMP 資料欄,因此會截斷微秒以下的時間戳記。如要在 BigQuery 中保留奈秒精確度,請在 Spanner 中將時間戳記值儲存為 INT64 (自 Unix 紀元以來的奈秒數) 或 STRING。

進一步瞭解變更串流、如何建構變更串流 Dataflow 管道和最佳做法。

管道相關規定

  • 執行管道前,Spanner 執行個體必須已存在。
  • 執行管道之前,Spanner 資料庫必須已經存在。
  • 執行管道之前,Spanner 中繼資料執行個體必須已經存在。
  • 執行管道之前,Spanner 中繼資料資料庫必須已經存在。
  • 執行管道之前,Spanner 變更串流必須已經存在。
    • 僅支援監控預設結構定義下資料表的變更串流。
    • 如果變更串流監控其他結構定義下的資料表,會擲回 [找不到資料表錯誤](https://github.com/GoogleCloudPlatform/DataflowTemplates/issues/2622)。
  • 執行管道之前,BigQuery 資料集必須已經存在。

處理新增追蹤表格或資料欄

本節說明在管道執行期間,新增追蹤 Spanner 資料表和資料欄的最佳做法。這項功能支援的最舊範本版本為 2024-09-19-00_RC00。

  • 將新資料欄新增至 Spanner 變更串流範圍之前,請先將資料欄新增至 BigQuery 變更記錄資料表。新增的資料欄必須具有相符的資料類型,且為 NULLABLE。請至少等待 10 分鐘,再繼續在 Spanner 中建立新的資料欄或資料表。如果未等待就寫入新資料欄,可能會導致無效信件佇列中出現未處理的記錄,並顯示無效錯誤代碼。

    如果是 NEW_ROW 或 NEW_ROW_AND_OLD_VALUES 值擷取類型,在執行中的管道中新增具有預設值的新資料欄,方法是先將資料欄新增至 BigQuery 資料表,然後再新增至 Spanner 資料表。

    如果是 NEW_VALUES 或 OLD_AND_NEW_VALUES,在執行中的管道新增具有預設值的資料欄,可能會導致資料遺失。為避免資料遺失,請務必按照下列程序手動匯出及匯入資料:

    1. 停止 Dataflow 管道。
    2. 將資料欄新增至 BigQuery 資料表。
    3. 在 Spanner 中新增含有預設值的資料欄。
    4. 等待 Spanner 結構定義變更和回填作業完成。
    5. 在補充作業完成後,匯出 Spanner 資料表資料。
    6. 將資料匯入 BigQuery 資料表,確保正確處理新資料欄。
    7. 從用於匯出的相同時間戳記啟動 Dataflow 管道。
  • 如要新增資料表,請先在 Spanner 資料庫中新增資料表。 當管道收到新資料表的記錄時,系統會在 BigQuery 中自動建立資料表。
  • 在 Spanner 資料庫中新增資料欄或資料表後,請務必修改變更串流,追蹤您要的新資料欄或資料表 (如果尚未隱含追蹤)。
  • 範本不會從 BigQuery 捨棄資料表或資料欄。如果從 Spanner 資料表捨棄資料欄,則從 Spanner 資料表捨棄資料欄後產生的記錄,系統會為 BigQuery 異動記錄資料欄填入空值,除非您手動從 BigQuery 捨棄資料欄。
  • 範本不支援資料欄類型更新。雖然 Spanner 支援將 STRING 資料欄變更為 BYTES 資料欄,或將 BYTES 資料欄變更為 STRING 資料欄,但您無法在 BigQuery 修改現有資料欄的資料類型,或使用相同資料欄名稱搭配不同資料類型。如果您在 Spanner 中捨棄並重新建立名稱相同但類型不同的資料欄,資料可能會寫入現有的 BigQuery 資料欄,但類型不會變更。
  • 這個範本不支援資料欄模式更新。複製到 BigQuery 的中繼資料欄會設為 REQUIRED 模式。無論是否在 Spanner 資料表中定義為 NOT NULL,複製到 BigQuery 的所有其他資料欄都會設為 NULLABLE。您無法在 BigQuery 中將 NULLABLE 資料欄更新為 REQUIRED 模式。
  • 執行中的管道不支援變更異動串流的值擷取類型。

範本參數

必要參數

  • spannerInstanceId:要讀取變更串流的 Spanner 執行個體。
  • spannerDatabase:要讀取變更串流的 Spanner 資料庫。
  • spannerMetadataInstanceId:用於變更串流連接器中繼資料表的 Spanner 執行個體。
  • spannerMetadataDatabase:用於變更串流連接器中繼資料資料表的 Spanner 資料庫。
  • spannerChangeStreamName:要讀取的 Spanner 變更串流名稱。
  • bigQueryDataset:用於輸出變更串流的 BigQuery 資料集。

選用參數

  • spannerProjectId:要讀取變更串流的專案。這個值也是建立變更串流連接器中繼資料資料表的專案。這個參數的預設值是 Dataflow 管道執行的專案。
  • spannerDatabaseRole:執行範本時要使用的 Spanner 資料庫角色。只有在執行範本的 IAM 主體是精細的存取控管使用者時,才需要這個參數。資料庫角色必須具備變更串流的 SELECT 權限,以及變更串流讀取函式的 EXECUTE 權限。詳情請參閱「變更串流的精細存取控管」(https://cloud.google.com/spanner/docs/fgac-change-streams)。
  • spannerMetadataTableName:要使用的 Spanner 變更串流連接器中繼資料資料表名稱。如未提供,系統會在管道流程中自動建立 Spanner 變更串流連接器中繼資料表。更新現有管道時,必須提供這項參數。否則,請勿提供這個參數。
  • rpcPriority:Spanner 呼叫的要求優先順序。值必須是下列其中一個值:HIGH、MEDIUM 或 LOW。預設值為 HIGH。
  • spannerHost:要在範本中呼叫的 Cloud Spanner 端點。僅供測試。例如:https://batch-spanner.googleapis.com。
  • startTimestamp:用於讀取變更串流的起始 DateTime (https://datatracker.ietf.org/doc/html/rfc3339) (含)。Ex-2021-10-12T07:20:50.52Z. 預設為管道啟動時的時間戳記,也就是目前時間。
  • endTimestamp:讀取變更串流時使用的結束日期時間 (https://datatracker.ietf.org/doc/html/rfc3339),包含該時間。例如 2021-10-12T07:20:50.52Z。預設為無限期。
  • bigQueryProjectId:BigQuery 專案。預設值為 Dataflow 工作的專案。
  • bigQueryChangelogTableNameTemplate:包含異動記錄的 BigQuery 資料表名稱範本。預設值為:{_metadata_spanner_table_name}_changelog。
  • deadLetterQueueDirectory:儲存未處理記錄的路徑。預設路徑是 Dataflow 工作暫存位置下的目錄。通常使用預設值即可。
  • dlqRetryMinutes:無效信件佇列重試間隔時間 (以分鐘為單位)。預設值為 10。
  • ignoreFields:以半形逗號分隔的清單,列出要忽略的欄位 (區分大小寫)。這些欄位可能是受監控資料表的欄位,也可能是管道新增的中繼資料欄位。系統不會將忽略的欄位插入 BigQuery。如果忽略 _metadata_spanner_table_name 欄位,系統也會忽略 bigQueryChangelogTableNameTemplate 參數。預設為空白。
  • disableDlqRetries:是否要停用 DLQ 重試。預設值為:false。
  • spannerChangeStreamTvfNameList:Spanner 變更串流 TVF 名稱清單,以分號分隔,用於查詢和聯集。預設為空白。
  • spannerDirectedReadOptions:Cloud Spanner 變更串流讀取的導向讀取選項。值必須是 DirectedReadOptions 的 JSON 字串格式 (例如 {"includeReplicas":{"replicaSelections":[{"location":"us-central1","type":"READ_ONLY"}]}})。詳情請參閱「導向讀取」(https://docs.cloud.google.com/spanner/docs/directed-reads)。預設為空白。
  • useStorageWriteApi:如果為 true,管道會使用 BigQuery Storage Write API (https://cloud.google.com/bigquery/docs/write-api)。預設值為 false。詳情請參閱「使用 Storage Write API」(https://beam.apache.org/documentation/io/built-in/google-bigquery/#storage-write-api)。
  • useStorageWriteApiAtLeastOnce:使用 Storage Write API 時,指定寫入語意。如要使用至少一次語意 (https://beam.apache.org/documentation/io/built-in/google-bigquery/#at-least-once-semantics),請將這個參數設為 true。如要使用僅一次語意,請將參數設為 false。只有在 useStorageWriteApi 為 true 時,這項參數才會生效。預設值為 false。
  • numStorageWriteApiStreams:使用 Storage Write API 時,指定寫入串流的數量。如果 useStorageWriteApi 為 true 且 useStorageWriteApiAtLeastOnce 為 false,則必須設定這個參數。預設為:0。
  • storageWriteApiTriggeringFrequencySec:使用 Storage Write API 時,指定觸發頻率 (以秒為單位)。如果 useStorageWriteApi 為 true 且 useStorageWriteApiAtLeastOnce 為 false,則必須設定這個參數。

執行範本

控制台

  1. 前往 Dataflow 的「Create job from template」(依據範本建立工作) 頁面。
  2. 前往「依範本建立工作」
  3. 在「Job name」(工作名稱) 欄位中,輸入專屬工作名稱。
  4. 選用:如要使用區域端點,請從下拉式選單中選取值。預設區域為 us-central1。

    如需可執行 Dataflow 工作的區域清單,請參閱「Dataflow 位置」。

  5. 從「Dataflow template」(Dataflow 範本) 下拉式選單中,選取「Cloud Spanner change streams to BigQuery」(Cloud Spanner 變更串流至 BigQuery) 範本。
  6. 在提供的參數欄位中輸入參數值。
  7. 按一下「Run Job」(執行工作)。

gcloud

在殼層或終端機中執行範本:

gcloud dataflow flex-template run JOB_NAME \
    --template-file-gcs-location=gs://dataflow-templates/VERSION/flex/Spanner_Change_Streams_to_BigQuery \
    --region REGION_NAME \
    --parameters \
spannerInstanceId=SPANNER_INSTANCE_ID,\
spannerDatabase=SPANNER_DATABASE,\
spannerMetadataInstanceId=SPANNER_METADATA_INSTANCE_ID,\
spannerMetadataDatabase=SPANNER_METADATA_DATABASE,\
spannerChangeStreamName=SPANNER_CHANGE_STREAM,\
bigQueryDataset=BIGQUERY_DATASET

更改下列內容:

  • JOB_NAME:您選擇的不重複工作名稱
  • VERSION:您要使用的範本版本

    您可以使用下列值:

    • latest,使用範本的最新版本,該版本位於 bucket 中非依日期命名的上層資料夾:gs://dataflow-templates/latest/
    • 版本名稱,例如 2023-09-12-00_RC00,可使用特定版本的範本,該範本會以巢狀結構存放在 bucket 中相應的依日期命名的上層資料夾中:gs://dataflow-templates/
  • REGION_NAME:您要部署 Dataflow 工作的區域,例如 us-central1
  • SPANNER_INSTANCE_ID:Spanner 執行個體 ID
  • SPANNER_DATABASE:Spanner 資料庫
  • SPANNER_METADATA_INSTANCE_ID:Spanner 中繼資料執行個體 ID
  • SPANNER_METADATA_DATABASE:Spanner 中繼資料資料庫
  • SPANNER_CHANGE_STREAM:Spanner 變更串流
  • BIGQUERY_DATASET:用於輸出變更串流的 BigQuery 資料集

API

如要使用 REST API 執行範本,請傳送 HTTP POST 要求。如要進一步瞭解 API 和授權範圍,請參閱 projects.templates.launch。

POST https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/LOCATION/flexTemplates:launch
{
   "launch_parameter": {
      "jobName": "JOB_NAME",
      "parameters": {
          "spannerInstanceId": "SPANNER_INSTANCE_ID",
          "spannerDatabase": "SPANNER_DATABASE",
          "spannerMetadataInstanceId": "SPANNER_METADATA_INSTANCE_ID",
          "spannerMetadataDatabase": "SPANNER_METADATA_DATABASE",
          "spannerChangeStreamName": "SPANNER_CHANGE_STREAM",
          "bigQueryDataset": "BIGQUERY_DATASET"
      },
      "containerSpecGcsPath": "gs://dataflow-templates/VERSION/flex/Spanner_Change_Streams_to_BigQuery",
   }
}

更改下列內容:

  • PROJECT_ID:您要執行 Dataflow 工作的 Google Cloud 專案 ID
  • JOB_NAME:您選擇的不重複工作名稱
  • VERSION:您要使用的範本版本

    您可以使用下列值:

    • latest,使用範本的最新版本,該版本位於 bucket 中非依日期命名的上層資料夾:gs://dataflow-templates/latest/
    • 版本名稱,例如 2023-09-12-00_RC00,可使用特定版本的範本,該範本會以巢狀結構存放在 bucket 中相應的依日期命名的上層資料夾中:gs://dataflow-templates/
  • LOCATION:您要部署 Dataflow 工作的區域,例如 us-central1
  • SPANNER_INSTANCE_ID:Spanner 執行個體 ID
  • SPANNER_DATABASE:Spanner 資料庫
  • SPANNER_METADATA_INSTANCE_ID:Spanner 中繼資料執行個體 ID
  • SPANNER_METADATA_DATABASE:Spanner 中繼資料資料庫
  • SPANNER_CHANGE_STREAM:Spanner 變更串流
  • BIGQUERY_DATASET:用於輸出變更串流的 BigQuery 資料集

實際運作環境注意事項

在正式環境中執行 Spanner 變更串流至 BigQuery 範本時,請考量下列最佳做法,確保可靠性並防止資料遺失:

佈建及調度 worker 資源

  • 適當設定 maxNumWorkers:如果 Dataflow worker 數量不足,管道處理變更串流資料的速度可能會落後。這可能會導致延遲時間增加,在某些情況下,還可能因內部連接器逾時和競爭狀況而遺失資料。worker 數量上限必須足以處理 Spanner 寫入處理量的尖峰。
  • 大小調整指南:雖然最佳數量會因工作負載而異,但請參閱 Spanner 變更串流指南,瞭解如何調整 Dataflow 叢集大小。監控管道成效,並視需要調整。舉例來說,某些高處理量工作負載可能需要大幅增加 maxNumWorkers (例如從 20 增加到 100 以上)。
  • 自動調度資源調整:Dataflow 預設的水平自動調度資源功能主要由 CPU 驅動。如果管道延遲,但 CPU 使用率不高,請考慮調整自動調度資源設定。調低 worker_utilization_hint 參數,可讓自動調度資源功能更靈敏地因應其他瓶頸。詳情請參閱「調整自動水平調度資源」。

監控與快訊

  • 輸出資料更新間隔 (系統延遲):這是監控這個範本時最重要的指標。如果「輸出資料更新間隔」(dataflow.googleapis.com/job/system_lag) 持續增加,表示管道無法跟上 Spanner 傳入的變更。
  • 設定警告:在「輸出資料更新間隔」指標上設定 Cloud Monitoring 警告。為管道建立基準,並根據業務對資料延遲時間的需求設定門檻。如果收到這項指標持續上升的快訊,請立即調查。詳情請參閱「Dataflow 工作指標」。

解讀記錄

  • SpannerException: DEADLINE_EXCEEDED:雖然連接器會重試,但如果 Dataflow worker 記錄中頻繁出現 com.google.cloud.spanner.SpannerException: DEADLINE_EXCEEDED 訊息,就表示 worker 無法及時從 Spanner 變更串流讀取資料。這通常表示管道的 worker 資源佈建不足。

Spanner 變更串流設定

  • 保留期限:請務必將 Spanner 變更串流的 retention_period 設為足夠的時間長度,以便處理 Dataflow 管道可能發生的速度變慢或服務中斷問題。預設值為 7 天。建議將這個值設為 3 到 7 天,為管道提供較大的緩衝區,以便復原及處理任何待處理項目,避免因串流中的變更過期而遺失資料。

只要實作這些做法,就能提升 Spanner 變更串流至 BigQuery Dataflow 管道的韌性和效能。

後續步驟