Referência do conector baseado em consulta

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

Configuração do pipeline

Os parâmetros a seguir têm suporte para conectores baseados em consulta. Defina esses valores no ingestion_definition bloco da configuração do pipeline.

Parâmetro Tipo Obrigatório Descrição
connection_name cadeia Necessário para ingestão de conexão estrangeira O nome da conexão que armazena 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álogos estrangeiros Definido para true ingerir de um catálogo estrangeiro apoiado pela Federação Lakehouse. Se true, não especifique connection_name.
source_catalog cadeia 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 cadeia Sim O esquema no sistema de origem do qual ingerir.
source_table cadeia Necessário para objetos de nível de tabela A tabela no esquema de origem a ser ingerida.
cursor_column cadeia 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 de aumento monotonicamente. Consulte os requisitos de coluna do Cursor.
cursor_columns lista de cadeias de caracteres Necessário para ingestão de catálogos estrangeiros Uma lista que contém o nome da coluna do cursor. Há suporte apenas para uma coluna.
primary_keys lista de cadeias de caracteres Obrigatório, a menos que o modo SCD (controle de histórico) seja APPEND_ONLY (ingestão de catálogo estrangeiro) As colunas de chave primária usadas para identificar linhas para operações de mesclagem. Necessário para e SCD_TYPE_1 modosSCD_TYPE_2.
deletion_condition cadeia No Uma expressão SQL que é true avaliada para linhas que representam exclusões suaves. Configurável apenas usando a API. Consulte a condição de exclusão.
hard_deletion_sync_min_interval_in_seconds inteiro No O intervalo mínimo em segundos entre as verificações de instantâneo de chave primária para detectar exclusões rígidas. Se não estiver definido, o controle de exclusão é desabilitado. Esse parâmetro não tem suporte quando scd_type é SCD_TYPE_2. Ele só é configurável usando a API (Beta). Consulte o acompanhamento de exclusão de disco rígido.
scd_type cadeia No O modo SCD (controle de histórico) da tabela de destino. Valores com suporte: SCD_TYPE_1 (padrão), SCD_TYPE_2, APPEND_ONLY.
destination_catalog cadeia Sim O catálogo para o qual gravar a tabela de destino.
destination_schema cadeia Sim O esquema para o qual gravar a tabela de destino.
destination_table cadeia No O nome da tabela de destino. O padrão será o nome da tabela de origem, se não for especificado. Consulte Nome de uma tabela de destino.

Requisitos de coluna do cursor

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

Requisitos:

  • Você deve especificar uma única coluna de cursor. Você não pode 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. Linhas com valores de cursor em ou abaixo da marca de água alta armazenada não são redimensionadas em execuções subsequentes.
  • Linhas com uma coluna de cursor NULL não são ingeridas.

Tipos de coluna com suporte:

  • Tipos de data/hora ou carimbo de data (recomendado)
  • Tipos numéricos (inteiro, inteiro longo, decimal e duplo)
  • Tipos binários (codificados como números binários)
  • Tipos de cadeia de caracteres

Condição de exclusão

O deletion_condition parâmetro permite que conectores baseados em consulta detectem exclusões temporárias. Esse recurso só é configurável usando a API.

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

Sintaxe:

"deletion_condition": "<sql-expression>"

Exemplos:

"deletion_condition": "deleted_at IS NOT NULL"

"deletion_condition": "is_deleted = 1"

"deletion_condition": "status = 'DELETED'"

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

Acompanhamento de exclusão dura

O hard_deletion_sync_min_interval_in_seconds parâmetro permite que conectores baseados em consulta detectem exclusões difíceis — linhas que foram removidas fisicamente da tabela de origem. Esse recurso está em Beta e só é configurável usando a API.

O acompanhamento de exclusão temporária funciona tirando periodicamente um instantâneo das chaves primárias presentes na tabela de origem e comparando-as com a tabela de destino. As linhas presentes no destino, mas ausentes do instantâneo de origem, são tratadas como excluídas.

O valor define o intervalo mínimo em segundos entre verificações de instantâneo. Esse valor atua como um limite inferior: se o pipeline for executado com menos frequência do que esse intervalo, a sincronização de exclusão rígida se alinhará à frequência real de ingestão em vez de executar com mais frequência. Atualizar esse parâmetro não dispara um instantâneo completo.

Observação

O acompanhamento de exclusão difícil requer primary_keys ser configurado na tabela. Não há suporte quando scd_type é SCD_TYPE_2.

Sintaxe:

"hard_deletion_sync_min_interval_in_seconds": <integer>

Exemplo:

"hard_deletion_sync_min_interval_in_seconds": 86400

Este exemplo dispara uma verificação de exclusão forçada não mais do que 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 colunas de cursor inválidas para obter etapas de solução de problemas.

  • Last updated on