Referência de conector baseada em consulta

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

Configuração do pipeline

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

Parâmetro Tipo Obrigatório Descrição
connection_name cadeia (de caracteres) Necessário para a ingestão de ligação estrangeira O nome da ligação que armazena as credenciais de autenticação para a base de dados de origem. Se ingest_from_uc_foreign_catalog for true, não especifique connection_name.
ingest_from_uc_foreign_catalog Booleano Necessário para a ingestão de catálogos estrangeiros Configurado para true ingerir de um catálogo estrangeiro apoiado pela Lakehouse Federation. Se true, não especifique connection_name.
source_catalog cadeia (de caracteres) 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 (de caracteres) Sim O esquema no sistema de origem a ingerir.
source_table cadeia (de caracteres) Obrigatório para objetos ao nível da tabela A tabela no esquema de origem a ingerir.
cursor_column cadeia (de caracteres) Necessário para a ingestão de ligação estrangeira O nome da coluna do cursor a usar para rastreamento incremental. Deve ser uma única coluna monotonamente crescente. Ver requisitos da coluna do cursor.
cursor_columns Lista de cadeias de caracteres Necessário para a ingestão de catálogos estrangeiros Uma lista contendo o nome da coluna do cursor. Apenas uma coluna é suportada.
primary_keys Lista de cadeias de caracteres Obrigatório, a menos que o modo de rastreamento de histórico (SCD) seja APPEND_ONLY (ingestão de catálogo estrangeiro) As principais colunas de chave são usadas para identificar linhas para operações de fusão. Obrigatório para SCD_TYPE_1 modos e.SCD_TYPE_2
deletion_condition cadeia (de caracteres) No Uma expressão SQL que avalia para true linhas que representam eliminações suaves. Só configurável usando a API. Ver Condição de deleção.
hard_deletion_sync_min_interval_in_seconds número inteiro No O intervalo mínimo em segundos entre as varreduras de snapshots da chave primária para detetar eliminações duras. Se não estiver ativado, o rastreamento de eliminação rígida fica desativado. Este parâmetro não é suportado quando scd_type é SCD_TYPE_2. Só é configurável usando a API (Beta). Ver Rastreamento por eliminação forçada.
scd_type cadeia (de caracteres) No O modo de rastreamento de histórico (SCD) para a tabela de destinos. Valores suportados: SCD_TYPE_1 (por defeito), SCD_TYPE_2, APPEND_ONLY.
destination_catalog cadeia (de caracteres) Sim O catálogo para escrever a tabela de destinos.
destination_schema cadeia (de caracteres) Sim O esquema para escrever a tabela de destino.
destination_table cadeia (de caracteres) No O nome da tabela de destino. Por defeito, o nome da tabela de origem é indicado se não for especificado. Veja Nomeie uma tabela de destinos.

Requisitos da 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 usa-o como filtro de limite inferior na execução seguinte.

Requisitos:

  • Deve especificar uma única coluna de cursor. Não podes especificar múltiplas colunas como um cursor composto. Se especificar mais do que uma, o pipeline falha com INVALID_CURSOR_COLUMNS.
  • A coluna do cursor deve aumentar de forma monótona. Os valores nunca devem diminuir. Para a APPEND_ONLY ingestão, as linhas com valores de cursor iguais ou abaixo da marca de maré máxima armazenada não são reingeridas nas corridas seguintes. Para SCD_TYPE_1 uma SCD_TYPE_2 ingestão com um cursor de carimbo temporal, o conector relê uma curta janela de linhas logo abaixo da marca máxima em cada execução para capturar registos que chegam tarde. Como estes modos se fundem por chave primária, as linhas de releitura inalteradas são reconciliadas idempotentemente e não criam duplicados.
  • Linhas com uma coluna de cursor NULL não são ingeridas.

Tipos de colunas suportadas:

  • Tipos de carimbo temporal ou 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 deleção

O deletion_condition parâmetro permite que conectores baseados em consulta detetem eliminações suaves. Esta funcionalidade só é configurável através da API.

O valor é uma expressão SQL que avalia para true linhas que devem ser tratadas como eliminadas na tabela de destino. O conector avalia esta expressão durante cada execução do 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 eliminada (para SCD_TYPE_2).

Rastreamento por eliminação rígida

O hard_deletion_sync_min_interval_in_seconds parâmetro permite que conectores baseados em consulta detetem eliminações forçadas — linhas que foram fisicamente removidas da tabela de origem. Esta funcionalidade está em Beta e só pode ser configurada através da API.

O rastreamento por eliminação rígida 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 snapshot de origem são tratadas como eliminadas.

O valor define o intervalo mínimo em segundos entre as varreduras instantâneas. Este valor funciona como um limite inferior: se o pipeline for executado com menos frequência do que este intervalo, a sincronização por eliminação dura alinha-se com a frequência real de ingestão em vez de correr com mais frequência. Atualizar este parâmetro não desencadeia um snapshot completo.

Observação

O rastreamento por eliminação rígida exige primary_keys ser configurado na tabela. Não é suportado 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 desencadeia uma varredura de apagamento rígido no máximo uma vez a cada 24 horas (86400 segundos).

Condições de erro

O erro mais comum é INVALID_CURSOR_COLUMNS. Isto ocorre quando a coluna do cursor não está configurada corretamente. Consulte Colunas de cursor inválidas para os passos de resolução de problemas.

  • Last updated on