本頁包含 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 Server
datetime2(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。 當游標欄位設定不正確時,會發生這種情況。 請參見 「無效游標欄位」 以了解故障排除步驟。