Referência do conector baseado em consulta

info

Visualização

Este recurso está em Pré-visualização Pública.

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.