基於查詢的連接器參考

本頁包含 Lakeflow Connect 中基於查詢的連接器參考文件,包括設定參數、游標欄位需求、刪除追蹤語法及錯誤條件。

管線設定

以下參數支援基於查詢的連接器。 在你的管線配置區塊中設定這些值 ingestion_definition 。

參數 類型 Required 說明
connection_name 字串 外來連線擷取所需 儲存來源資料庫認證憑證的連線名稱。 若 ingest_from_uc_foreign_catalog , true則不指定 connection_name。
ingest_from_uc_foreign_catalog 布爾值 外國目錄擷取的必要條件 設定 true 為從 Lakehouse Federation 支持的外國目錄中擷取資料。 若 true,則不指定 connection_name。
source_catalog 字串 是的 來源系統中的目錄(或如果 ingest_from_uc_foreign_catalog 是 true,則使用外部目錄名稱)。
source_schema 字串 是的 來源系統中要從中擷取的結構。
source_table 字串 對於資料表層級物件所必需 原始碼結構中的資料表來匯入。
cursor_column 字串 外來連線擷取所需 用於增量追蹤的游標欄位名稱。 必須是單一單調遞增的柱。 請參閱 游標欄位需求。
cursor_columns 字串清單 外國目錄擷取的必要條件 一個包含游標欄位名稱的清單。 僅支援一欄。
primary_keys 字串清單 除非歷史追蹤(SCD)模式是 APPEND_ONLY (外國目錄擷取)否則必須的 主要鍵欄位用於識別合併操作的列。 必須的 SCD_TYPE_1 模式 SCD_TYPE_2 。
deletion_condition 字串 No 一個 SQL 運算式,能對代表軟刪除的列值值 。true 只能用 API 來設定。 參見 刪除條件。
hard_deletion_sync_min_interval_in_seconds 整數 No 主鍵快照掃描間的最小間隔(秒數),用於偵測硬刪除。 若未設定,則強制刪除追蹤將被禁用。 當 scd_type 為 SCD_TYPE_2時,此參數不被支援。 它只能透過 API(測試版)來設定。 詳見 硬刪除追蹤。
scd_type 字串 No 目的資料表的歷史追蹤(SCD)模式。 支援值: SCD_TYPE_1 (預設值)、 SCD_TYPE_2, APPEND_ONLY。
destination_catalog 字串 是的 目錄用來寫入目的表。
destination_schema 字串 是的 寫入目的表的結構。
destination_table 字串 No 目的地資料表的名稱。 若未指定,則預設為來源資料表名稱。 參見 「命名目的地表」。

游標欄位需求

游標欄位追蹤管線運行間的增量進度。 連接器會在每次成功執行後儲存最大游標值,並在下一次執行時將其作為下界濾波器。

要求:

  • 你必須指定單一游標欄位。 你不能指定多個欄位作為複合游標。 若指定多個,管線將失敗。INVALID_CURSOR_COLUMNS
  • 游標欄必須單調增加。 價值絕不能減少。 對於 APPEND_ONLY 擷取,游標值在儲存的高水位線或以下的列,在後續執行時不會被重新輸入。 對於SCD_TYPE_1SCD_TYPE_2使用時間戳記游標的擷取,連接器會在每次執行中重讀剛好低於高水位線的一小段行,以捕捉遲到的紀錄。 由於這些模式會依主鍵合併,未更改的重讀列會被冪分,不會產生重複。
  • 游標欄位為 NULL 的列不會被擷取。
  • 時間戳游標欄位的精度最多應為微秒級(六位分秒)。 更精細的精確度,如 SQL Serverdatetime2(7),可能會延遲在游標值最大值處的資料列擷取。 參見 一般限制。

支援的柱型:

  • 時間戳記或日期類型(建議)
  • 數值類型(整數、長整數、十進位及雙數)
  • 二進位類型(以二進位數字編碼)
  • 字串類型

刪除條件

這個 deletion_condition 參數讓基於查詢的連接器能偵測軟性刪除。 此功能僅能透過 API 進行設定。

這個值是一個 SQL 運算式,對於應該在目的資料表中視為已刪除的資料列,會評估為 。true 連接器在每次管線運行時會評估此表達式。

Syntax:

"deletion_condition": "<sql-expression>"

範例:

"deletion_condition": "deleted_at IS NOT NULL"
"deletion_condition": "is_deleted = 1"
"deletion_condition": "status = 'DELETED'"

當某列與 相符 deletion_condition時,連接器會從目標表中移除該列(對 SCD_TYPE_1),或標記為已刪除(對 SCD_TYPE_2)。

硬刪除追蹤

這個 hard_deletion_sync_min_interval_in_seconds 參數讓基於查詢的連接器能夠偵測硬刪除——也就是那些從來源資料表中物理移除的列。 此功能目前仍處於 測試階段 ,且只能透過 API 進行配置。

硬刪除追蹤的運作方式是定期擷取來源資料表中的主要鍵數,並將其與目標資料表進行比較。 目的地中存在但來源快照中缺失的資料列會被視為已刪除。

該值設定快照掃描間的最小間隔(秒數)。 此值作為下界:若管線執行頻率低於此區間,硬刪除同步會與實際擷取頻率對齊,而非更頻繁。 更新此參數不會觸發完整的快照。

備註

硬刪除追蹤需要 primary_keys 在桌面上設定。 當 scd_type 是 SCD_TYPE_2時,不支援。

Syntax:

"hard_deletion_sync_min_interval_in_seconds": <integer>

範例:

"hard_deletion_sync_min_interval_in_seconds": 86400

此範例每 24 小時(86400 秒)最多觸發一次硬刪除掃描。

錯誤條件

最常見的錯誤是 INVALID_CURSOR_COLUMNS。 當游標欄位設定不正確時,會發生這種情況。 請參見 「無效游標欄位」 以了解故障排除步驟。