Referência do conector baseado em consulta

Esta página contém documentação de referência para conectores baseados em consultas no LakeFlow Connect, incluindo parâmetros de configuração, requisitos de coluna do cursor, sintaxe de acompanhamento de exclusão e condições de erro.

Configuração do pipeline

Os seguintes parâmetros são suportados para conectores baseados em consultas. Defina esses valores no bloco ingestion_definition da configuração do seu pipeline.

Parâmetro	Tipo	Obrigatório	Descrição
connection_name	string	Necessário para ingestão de conexão estrangeira	O nome da conexão que armazena as credenciais de autenticação para o banco de dados de origem. Se ingest_from_uc_foreign_catalog for true, não especifique connection_name.
ingest_from_uc_foreign_catalog	boolean	Necessário para ingestão de catálogo estrangeiro	Defina como true para ingerir de um catálogo estrangeiro com suporte do Lakehouse Federation. Se true, não especifique connection_name.
source_catalog	string	Sim	O catálogo no sistema de origem (ou o nome do catálogo estrangeiro se ingest_from_uc_foreign_catalog for true).
source_schema	string	Sim	O esquema no sistema de origem do qual os dados serão ingeridos.
source_table	string	Necessário para objetos de nível de tabela.	A tabela no esquema de origem a ser ingerida.
cursor_column	string	Necessário para ingestão de conexão estrangeira	O nome da coluna do cursor a ser usada para acompanhamento incremental. Deve ser uma única coluna monotonicamente crescente. Consulte os requisitos da coluna Cursor.
cursor_columns	lista de strings	Necessário para ingestão de catálogo estrangeiro	Uma lista contendo o nome da coluna do cursor. Apenas uma coluna é suportada.
primary_keys	lista de strings	Obrigatório, a menos que o modo história acompanhamento (SCD) seja APPEND_ONLY (ingestão de catálogo estrangeiro)	As colunas key primária usadas para identificar linhas em operações merge . Necessário para os modos SCD_TYPE_1 e SCD_TYPE_2 .
deletion_condition	string	Não	Uma expressão SQL que resulta em true para linhas que representam exclusões lógicas. Configurável somente através da API. Consulte a condição de exclusão.
hard_deletion_sync_min_interval_in_seconds	inteiro	Não	Intervalo mínimo em segundos entre as verificações de snapshots key primária para detecção de exclusões permanentes. Se não estiver configurado, o acompanhamento por exclusão permanente é desativado. Configurável apenas através da API (Beta). Consulte Acompanhamento de exclusão irreversível.
scd_type	string	Não	O modo história acompanhamento (SCD) para a tabela de destino. Valores suportados: SCD_TYPE_1 (default), SCD_TYPE_2, APPEND_ONLY.
destination_catalog	string	Sim	O catálogo no qual a tabela de destino será gravada.
destination_schema	string	Sim	O esquema para escrever na tabela de destino.
destination_table	string	Não	O nome da tabela de destino. Caso não seja especificado, será utilizado por padrão o nome da tabela de origem. Consulte Nomear uma tabela de destino.

Requisitos da coluna do cursor

A coluna do cursor rastreia o progresso incremental entre a execução pipeline . O conector armazena o valor máximo do cursor após cada execução bem-sucedida e o utiliza como filtro de limite inferior na próxima execução.

Requisitos:

• Você deve especificar uma única coluna de cursor. Não é possível especificar várias colunas como um cursor composto. Se você especificar mais de um, o pipeline falhará com INVALID_CURSOR_COLUMNS.
• A coluna do cursor deve aumentar monotonicamente. Os valores nunca devem diminuir. As linhas com valores de cursor iguais ou inferiores à marca d'água máxima armazenada não são reinseridas em execuções subsequentes.
• Linhas com uma coluna de cursor NULL não são incluídas.

Tipos de coluna suportados:

• Tipos de carimbo de data/hora ou data (recomendado)
• Tipos numéricos (inteiro, inteiro longo, decimal e ponto flutuante de dupla precisão)
• Tipos binários (codificados como números binários)
• tipos de strings

Condição de exclusão

O parâmetro deletion_condition permite que conectores baseados em consultas detectem exclusões lógicas. Este recurso só pode ser configurado através da API.

O valor é uma expressão SQL que resulta em true para linhas que devem ser tratadas como excluídas na tabela de destino. O conector avalia essa expressão durante cada execução do pipeline.

Sintaxe:

"deletion_condition": "<sql-expression>"

Exemplos:

JSON

"deletion_condition": "deleted_at IS NOT NULL"

JSON

"deletion_condition": "is_deleted = 1"

JSON

"deletion_condition": "status = 'DELETED'"

Quando uma linha corresponde a deletion_condition, o conector remove a linha correspondente da tabela de destino (para SCD_TYPE_1) ou a marca como excluída (para SCD_TYPE_2).

exclusão permanente

O parâmetro hard_deletion_sync_min_interval_in_seconds permite que conectores baseados em consultas detectem exclusões permanentes — linhas que foram fisicamente removidas da tabela de origem. Este recurso está em versão Beta e só pode ser configurado através da API.

O acompanhamento de exclusão permanente funciona tirando periodicamente um instantâneo da chave primária presente na tabela de origem e comparando-o com a tabela de destino. As linhas presentes no destino, mas ausentes no snapshot de origem, são tratadas como excluídas.

O valor define o intervalo mínimo em segundos entre as verificações de instantâneo. Esse valor funciona como um limite inferior: se a execução pipeline for menos frequente do que esse intervalo, a sincronização de exclusão permanente se alinha com a frequência real de ingestão, em vez de ser executada com mais frequência. A atualização deste parâmetro não aciona um Snapshot completo.

nota

A exclusão permanente de acompanhamento requer que primary_keys seja configurado na tabela.

Sintaxe:

"hard_deletion_sync_min_interval_in_seconds": <integer>

Exemplo:

JSON

"hard_deletion_sync_min_interval_in_seconds": 86400

Este exemplo aciona uma verificação de exclusão permanente no máximo uma vez a cada 24 horas (86400 segundos).

Condições de erro

O erro mais comum é INVALID_CURSOR_COLUMNS. Isso ocorre quando a coluna do cursor não está configurada corretamente. Consulte a seção "Colunas de cursor inválidas" para solucionar problemas.