このページには、構成パラメーター、カーソル列の要件、削除追跡構文、エラー条件など、Lakeflow Connect のクエリ ベースのコネクタに関するリファレンス ドキュメントが含まれています。
パイプラインの構成
クエリ ベースのコネクタでは、次のパラメーターがサポートされています。 これらの値は、パイプライン構成の ingestion_definition ブロックに設定します。
| パラメーター | タイプ | 必須 | 説明 |
|---|---|---|---|
connection_name |
文字列 | 外部接続インジェストに必要 | ソース データベースの認証資格情報を格納する接続の名前。
ingest_from_uc_foreign_catalogがtrue場合は、connection_nameを指定しないでください。 |
ingest_from_uc_foreign_catalog |
ブーリアン | 外部カタログ インジェストに必要 | Lakehouse Federation によってサポートされている外部カタログから取り込むには、 true に設定します。
true場合は、connection_nameを指定しないでください。 |
source_catalog |
文字列 | はい | ソース システム内のカタログ (または、 ingest_from_uc_foreign_catalog が trueされている場合は外部カタログ名)。 |
source_schema |
文字列 | はい | 取り込み元のソース システム内のスキーマ。 |
source_table |
文字列 | テーブル レベルのオブジェクトに必要 | 取り込むソース スキーマ内のテーブル。 |
cursor_column |
文字列 | 外部接続インジェストに必要 | 増分追跡に使用するカーソル列の名前。 単調に増加する単一の列である必要があります。 カーソル列の要件を参照してください。 |
cursor_columns |
文字列のリスト | 外部カタログ インジェストに必要 | カーソル列名を含むリスト。 サポートされている列は 1 つだけです。 |
primary_keys |
文字列のリスト | 履歴追跡 (SCD) モードが APPEND_ONLY (外部カタログ インジェスト) でない限り必須 |
マージ操作の行を識別するために使用される主キー列。
SCD_TYPE_1モードとSCD_TYPE_2モードに必要です。 |
deletion_condition |
文字列 | いいえ | 論理的な削除を表す行の true に評価される SQL 式。 API を使用してのみ構成できます。
削除条件を参照してください。 |
hard_deletion_sync_min_interval_in_seconds |
整数 | いいえ | ハード削除を検出するための主キー スナップショット スキャン間の最小間隔 (秒)。 設定されていない場合、ハード削除の追跡は無効になります。 このパラメーターは、 scd_type が SCD_TYPE_2されている場合はサポートされません。 API (ベータ) を使用してのみ構成できます。
「ハード削除の追跡」を参照してください。 |
scd_type |
文字列 | いいえ | 宛先テーブルの履歴追跡 (SCD) モード。 サポートされている値: SCD_TYPE_1 (既定値)、 SCD_TYPE_2、 APPEND_ONLY。 |
destination_catalog |
文字列 | はい | コピー先テーブルを書き込むカタログ。 |
destination_schema |
文字列 | はい | 宛先テーブルを書き込むスキーマ。 |
destination_table |
文字列 | いいえ | 対象テーブルの名前です。 指定しない場合は、既定でソース テーブル名が使用されます。 「 宛先テーブルに名前を付けます」を参照してください。 |
カーソル列の要件
カーソル列は、パイプラインの実行間の増分進行状況を追跡します。 コネクタは、正常に実行されるたびに最大カーソル値を格納し、次回の実行時に下限フィルターとして使用します。
必要条件：
- 1 つのカーソル列を指定する必要があります。 複合カーソルとして複数の列を指定することはできません。 複数を指定した場合、パイプラインは
INVALID_CURSOR_COLUMNSで失敗します。 - カーソル列は単調に増加する必要があります。 値を減らしてはなりません。
APPEND_ONLYインジェストの場合、カーソル値が保存されたハイウォーターマーク以下の行は、その後の実行で再インジェストされません。 タイムスタンプカーソルを使ったSCD_TYPE_1およびSCD_TYPE_2の取り込みの場合、コネクターは各ランのハイウォーターマーク直下の短い行ウィンドウを再読み込み、遅れて到着したレコードをキャプチャします。 これらのモードは主キーでマージするため、変更されていない再読み行は冪等的に照合され、重複は生みません。 - NULL カーソル列を持つ行は取り込まれません。
サポートされている列の種類:
- タイムスタンプまたは日付型 (推奨)
- 数値型 (整数、長整数、10 進数、double)
- バイナリ型 (バイナリ番号としてエンコード)
- 文字列型
削除条件
deletion_condition パラメーターを使用すると、クエリ ベースのコネクタが論理的な削除を検出できます。 この機能は、API を使用してのみ構成できます。
この値は、変換先テーブルで削除済みとして扱う必要がある行の true に評価される SQL 式です。 コネクタは、各パイプラインの実行中にこの式を評価します。
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 秒) に 1 回までトリガーします。
エラー条件
最も一般的なエラーは INVALID_CURSOR_COLUMNSです。 これは、カーソル列が正しく構成されていない場合に発生します。 トラブルシューティングの手順については、「 無効なカーソル列 」を参照してください。