Todos os produtos
Search
Central de documentação

Realtime Compute for Apache Flink:Opções do conector Hologres (VVR 8 ou anterior)

Última atualização: Jun 27, 2026

Opções do conector para a cláusula WITH ao usar o Realtime Compute for Apache Flink com Hologres no Ververica Runtime (VVR) 8.0.x ou versões anteriores.

Referência rápida de versões

A tabela a seguir resume as opções introduzidas em versões menores específicas do VVR. As opções não listadas aqui estão disponíveis em todas as versões VVR 8.0.x.

Opção

Versão mínima

connection.ssl.mode

VVR 8.0.5

connection.ssl.root-cert.location

VVR 8.0.5

bulkload (sink)

VVR 8.0.5 + Hologres V2.1

deduplication.enabled (sink)

VVR 8.0.5

jdbcReadRetryCount padrão alterado para 10

VVR 8.0.5

type-mapping.timestamp-converting.legacy

VVR 8.0.6

property-version

VVR 8.0.6

sink.delete-strategy

VVR 8.0.8

remove-u0000-in-text.enabled para jdbc_copy

VVR 8.0.8

check-and-put.column

VVR 8.0.11

check-and-put.operator

VVR 8.0.11

check-and-put.null-as

VVR 8.0.11

aggressive.enabled

VVR 8.0.11

Opções do conector na cláusula WITH

Geral

As opções abaixo se aplicam a tabelas de source, tabelas de destino e tabelas de dimensão.

Opção

Tipo de dados

Obrigatório

Padrão

Descrição

connector

String

Sim

Defina como hologres.

dbname

String

Sim

Nome do banco de dados. Para conectar-se a um virtual warehouse, adicione @<warehouse_name> ao nome do banco de dados — por exemplo, 'db_test@read_warehouse'. Virtual warehouses são suportados apenas em modos relacionados a JDBC.

tablename

String

Sim

Nome da tabela. Se o schema não for public, use schema.tableName.

username

String

Sim

AccessKey ID da sua conta Alibaba Cloud ou usuário RAM, ou nome de usuário de conta personalizada no formato BASIC$<user_name>. Armazene as credenciais como variáveis — não as codifique diretamente. Consulte Gerenciar chaves.

password

String

Sim

AccessKey secret da sua conta Alibaba Cloud ou usuário RAM, ou senha da sua conta personalizada.

endpoint

String

Sim

Endpoint do Hologres. Consulte Endpoints.

connection.ssl.mode

String

Não

disable

Modo SSL. Valores válidos: disable, require, verify-ca, verify-full. Os modos verify-ca e verify-full exigem Hologres V2.1 ou posterior e também requerem connection.ssl.root-cert.location. Consulte Criptografia em trânsito. Requer VVR 8.0.5 ou posterior.

connection.ssl.root-cert.location

String

Não

Caminho do arquivo de certificado CA. Obrigatório quando connection.ssl.mode é verify-ca ou verify-full. Faça upload do certificado usando o recurso de artefatos — ele será armazenado no diretório /flink/usrlib. Exemplo: '/flink/usrlib/certificate.crt'. Requer VVR 8.0.5 ou posterior.

jdbcRetryCount

Integer

Não

10

Número máximo de tentativas após falha de conexão durante leitura ou gravação de dados.

jdbcRetrySleepInitMs

Long

Não

1000

Componente fixo do tempo de espera por tentativa, em milissegundos. O tempo real de espera é jdbcRetrySleepInitMs + retry × jdbcRetrySleepStepMs.

jdbcRetrySleepStepMs

Long

Não

5000

Componente incremental do tempo de espera por tentativa, em milissegundos. O tempo real de espera é jdbcRetrySleepInitMs + retry × jdbcRetrySleepStepMs.

jdbcConnectionMaxIdleMs

Long

Não

60000

Duração máxima de ociosidade para uma conexão JDBC, em milissegundos. Conexões ociosas que excederem esse valor serão fechadas e liberadas.

jdbcMetaCacheTTL

Long

Não

60000

Tempo máximo para manter informações de TableSchema no cache, em milissegundos.

jdbcMetaAutoRefreshFactor

Integer

Não

4

Controla quando uma atualização de cache é acionada. O limiar de atualização automática é jdbcMetaCacheTTL / jdbcMetaAutoRefreshFactor. Quando o tempo restante do cache ficar abaixo desse limiar, a atualização ocorre automaticamente.

type-mapping.timestamp-converting.legacy

Boolean

Não

Ver descrição

Base de fuso horário para conversões entre tipos de tempo do Flink e do Hologres. true usa o fuso horário da JVM; false (recomendado) usa o fuso horário do Flink. O padrão é true quando property-version=0, e false quando property-version=1. Consulte Fusos horários. Requer VVR 8.0.6 ou posterior.

property-version

Integer

Não

0

Versão das opções do conector. Defina como 1 (recomendado) para obter os padrões mais recentes. As opções disponíveis e seus valores padrão podem variar entre as principais versões do VVR. Requer VVR 8.0.6 ou posterior.

Específicas de source

Opção

Tipo de dados

Obrigatório

Padrão

Descrição

field_delimiter

String

Não

"\u0002"

Delimitador entre linhas durante a exportação de dados.

binlog

Boolean

Não

Ver descrição

Indica se deve consumir dados de log binário. O padrão é false quando property-version=0, e true quando property-version=1.

sdkMode

String

Não

holohub

Modo SDK para consumo de log binário. holohub: modo HoloHub. jdbc: modo JDBC. jdbc_fixed: modo JDBC fixo, não sujeito a limites de conexão, mas sem suporte a bancos de dados com mascaramento de dados ativado. Para valores recomendados por versão do VVR, consulte Notas importantes.

jdbcBinlogSlotName

String

Não

Nome do slot da tabela de source de log binário no modo JDBC. Tem efeito apenas quando sdkMode=jdbc. Se não especificado, o conector cria um slot automaticamente. Caso utilize Hologres V2.1 ou posterior com VVR 8.0.5 ou superior, omita esta opção — o conector não tentará criar um slot automaticamente. Consulte Consumo de log binário no modo JDBC.

binlogMaxRetryTimes

Integer

Não

60

Número de tentativas após falha na leitura de dados de log binário.

binlogRetryIntervalMs

Long

Não

2000

Intervalo entre tentativas após falha na leitura de dados de log binário, em milissegundos.

binlogBatchReadSize

Integer

Não

100

Quantidade de linhas lidas do log binário por lote.

cdcMode

Boolean

Não

Ver descrição

Define se a leitura de dados de log binário ocorre no modo Change Data Capture (CDC). O padrão é false quando property-version=0, e true quando property-version=1.

upsertSource

Boolean

Não

false

Aplicável apenas no modo CDC. true: apenas mensagens upsert (INSERT, DELETE, UPDATE_AFTER). false: todos os tipos de mensagem (INSERT, DELETE, UPDATE_BEFORE, UPDATE_AFTER). Defina como true se existirem operadores de retração na tabela de destino — por exemplo, ao usar ROW_NUMBER() com uma cláusula OVER para deduplicação.

binlogStartupMode

String

Não

earliestOffset

Modo de consumo do log binário. initial: consome primeiro todos os dados existentes e depois os logs binários. earliestOffset: inicia a partir do log binário mais antigo. timestamp: inicia a partir do horário definido por startTime. Se startTime estiver configurado ou um horário inicial for selecionado na inicialização do job, esta opção será definida automaticamente como timestamp.

startTime

String

Não

Horário inicial para consumo de dados do Hologres. Formato: yyyy-MM-dd hh:mm:ss. Se não definido e o job não for retomado de um estado salvo, o consumo começa pelo log binário mais antigo.

jdbcScanFetchSize

Integer

Não

256

Quantidade de registros armazenados em buffer por lote durante uma operação de varredura.

jdbcScanTimeoutSeconds

Integer

Não

60

Tempo limite para uma operação de varredura, em segundos.

jdbcScanTransactionSessionTimeoutSeconds

Integer

Não

600

Tempo limite da transação que contém a operação de varredura, em segundos. Corresponde ao parâmetro GUC do Hologres idle_in_transaction_session_timeout. Defina como 0 para desativar o tempo limite.

enable_filter_push_down

Boolean

Não

false

Indica se as condições de filtro devem ser delegadas ao Hologres durante a fase de leitura completa de dados. Aplica-se à leitura de tabelas de source com log binário desativado ou durante a fase de dados completos do consumo de log binário. Requer VVR 6.0.7 ou posterior.

partition-binlog.mode

Enum

Não

DISABLE

Modo para consumo de logs binários de uma tabela particionada. DISABLE: a tabela não é tratada como particionada — uma exceção será relatada caso ela seja. DYNAMIC: consome continuamente a partição mais recente; exige que o particionamento dinâmico esteja ativado. STATIC: consome partições fixas simultaneamente; não é possível adicionar ou remover partições durante o consumo.

partition-binlog-lateness-timeout-minutes

Integer

Não

60

Latência máxima permitida antes do tempo limite no modo de partição dinâmica, em minutos. O conector continua monitorando a partição anterior após alternar para a mais recente, para capturar dados atrasados. Não pode exceder a unidade de tempo do particionamento — para uma tabela particionada por dia, o máximo é 1.440 minutos (24 × 60).

partition-values-to-read

String

Não

Partições a serem consumidas no modo de partição estática. Especifique os valores das partições (não os nomes completos), separados por vírgulas. Se não definido, todas as partições serão consumidas. Expressões regulares não são suportadas.

Específicas de destino

Modos de gravação

Opção

Tipo de dados

Obrigatório

Padrão

Descrição

sdkMode

String

Não

jdbc

Modo SDK para gravação de dados. jdbc: utiliza driver JDBC. jdbc_copy: alto throughput e baixa latência; não suporta exclusão de dados, gravação em tabelas particionadas ou ignoreNullWhenUpdate. rpc: modo RPC; não suporta tipos de dados JSONB ou RoarinBitmap. jdbc_fixed (preview público): modo JDBC fixo, sem ocupação de conexões; não suporta JSONB, RoarinBitmap ou bancos de dados com mascaramento de dados ativado. Para valores recomendados por versão do VVR, consulte Notas importantes.

bulkload

Boolean

Não

false

Define se a gravação ocorre em modo de carga em massa. Tem efeito apenas quando sdkMode=jdbc_copy. Utilize esta opção para tabelas sem chave primária — os valores de chave primária devem ser únicos ao carregar em massa uma tabela que possua chave primária. O modo de carga em massa consome menos recursos do Hologres do que o modo jdbc_copy. Requer VVR 8.0.5 ou posterior e Hologres V2.1 ou posterior.

mutatetype

String

Não

Ver descrição

Define como lidar com registros duplicados. insertorignore: ignora duplicatas. insertorreplace: substitui linhas existentes. insertorupdate: atualiza apenas os campos definidos na DDL da tabela de destino, mantendo os demais inalterados. O padrão é insertorignore quando property-version=0, e insertorupdate quando property-version=1.

partitionrouter

Boolean

Não

false

Indica se os dados devem ser gravados em uma tabela particionada.

createparttable

Boolean

Não

false

Define se as partições devem ser criadas automaticamente com base nos valores recebidos. No modo RPC, a criação automática falha se os valores contiverem hifens (-). O VVR 8.0.3 ou posterior aceita campos do tipo DATE como chaves de partição. Certifique-se de que os valores estejam limpos — dados incorretos causam failover ao criar uma partição inválida. Não suportado quando sdkMode=jdbc_copy.

Buffer e flush

O operador de destino armazena registros em buffer e realiza o flush para o Hologres quando qualquer uma das seguintes condições for atendida:

  • A quantidade de registros em buffer atingir jdbcWriteBatchSize.

  • O tamanho total dos registros em buffer atingir jdbcWriteBatchByteSize.

  • O tempo desde o último flush atingir jdbcWriteFlushInterval.

Opção

Tipo de dados

Obrigatório

Padrão

Descrição

jdbcWriteBatchSize

Integer

Não

256

Quantidade máxima de registros a serem armazenados em buffer antes do flush, em linhas.

jdbcWriteBatchByteSize

Long

Não

2097152 (2 MB)

Tamanho total máximo dos registros em buffer antes do flush, em bytes.

jdbcWriteFlushInterval

Long

Não

10000

Tempo máximo de espera antes de realizar o flush dos registros em buffer, em milissegundos.

deduplication.enabled

Boolean

Não

true

Define se os registros devem ser deduplicados no buffer antes do flush. Quando ativado, apenas o registro mais recente de cada chave primária é mantido. Requer VVR 8.0.5 ou posterior.

Tratamento de nulos e dados

Opção

Tipo de dados

Obrigatório

Padrão

Descrição

ignoreNullWhenUpdate

Boolean

Não

false

Define se valores nulos devem ser ignorados ao gravar com mutatetype=insertOrUpdate. false: valores nulos são gravados no Hologres. true: campos nulos no registro recebido são ignorados. Não suportado quando sdkMode=jdbc_copy.

jdbcEnableDefaultForNotNullColumn

Boolean

Não

true

Define se um valor padrão deve ser substituído quando um nulo for gravado em uma coluna não nula sem padrão configurado. Quando true: colunas STRING ficam em branco, colunas NUMBER recebem 0 e colunas DATE/TIMESTAMP/TIMESTAMPTZ recebem 1970-01-01 00:00:00. Quando false: uma exceção é relatada.

remove-u0000-in-text.enabled

Boolean

Não

false

Define se caracteres \u0000 devem ser removidos de dados STRING antes da gravação. Quando false, dados incorretos podem causar ERROR: invalid byte sequence for encoding "UTF8": 0x00. Quando true, o conector remove os caracteres \u0000 — use com cautela, pois strings como aaa\u0000bbb tornam-se aaabbb, o que pode gerar inconsistências nos dados. Suportado com sdkMode=jdbc no VVR 8.0.1 ou posterior; suportado com sdkMode=jdbc_copy ou jdbc no VVR 8.0.8 ou posterior.

partial-insert.enabled

Boolean

Não

false

Define se apenas os campos declarados na instrução INSERT devem ser gravados. false: todos os campos definidos na DDL são gravados; campos ausentes na instrução INSERT recebem valor nulo. true: apenas os campos declarados são gravados. Tem efeito somente quando mutatetype=InsertOrUpdate.

Tratamento de exclusão

Opção

Tipo de dados

Obrigatório

Padrão

Descrição

sink.delete-strategy

String

Não

Estratégia para processar mensagens de retração. IGNORE_DELETE: ignora mensagens UPDATE_BEFORE e DELETE. NON_PK_FIELD_TO_NULL: ignora mensagens UPDATE_BEFORE; trata DELETE definindo campos de chave não primária como nulos (para cenários de atualização parcial). DELETE_ROW_ON_PK: ignora mensagens UPDATE_BEFORE; trata DELETE excluindo toda a linha com base na chave primária (para cenários de atualização parcial). CHANGELOG_STANDARD: segue o padrão de changelog do Flink SQL — trata UPDATE como DELETE + INSERT, garantindo precisão dos dados; utilize esta opção para cenários sem atualização parcial. Definir NON_PK_FIELD_TO_NULL pode resultar em registros com valores nulos em campos de chave não primária. Requer VVR 8.0.8 ou posterior.

Atualização condicional

Opção

Tipo de dados

Obrigatório

Padrão

Descrição

check-and-put.column

String

Não

Habilita o recurso de atualização condicional. Defina como o nome do campo a ser verificado. Requisitos: chave primária na tabela de destino, mutateType=Insertorupdate ou insertorreplace, e sdkMode=jdbc_fixed ou jdbc. Para consultas reversas, utilize uma tabela baseada em linhas ou híbrida (linha-coluna). Em dados com muitas duplicatas, o check-and-put regride para gravações únicas, reduzindo o throughput de escrita. Requer VVR 8.0.11 ou posterior.

check-and-put.operator

String

Não

GREATER

Operador de comparação para a atualização condicional. O campo de verificação do novo registro é comparado com o do registro existente; a atualização prossegue se a comparação for verdadeira. Valores válidos: GREATER, GREATER_OR_EQUAL, EQUAL, NOT_EQUAL, LESS, LESS_OR_EQUAL, IS_NULL, IS_NOT_NULL. Requer VVR 8.0.11 ou posterior.

check-and-put.null-as

String

Não

Define como tratar valores nulos no registro existente durante uma atualização condicional. No PostgreSQL, comparar qualquer valor com NULL retorna FALSE. Configure esta opção para especificar o valor substituto, equivalente à função COALESCE. Requer VVR 8.0.11 ou posterior.

Pool de conexões

Opção

Tipo de dados

Obrigatório

Padrão

Descrição

connectionSize

Integer

Não

3

Tamanho do pool de conexões JDBC para o job. Aumente este valor se o job apresentar baixo throughput.

connectionPoolName

String

Não

Nome do pool de conexões. Tabelas com o mesmo nome de pool no mesmo TaskManager compartilham um único pool. Defina como qualquer string diferente de 'default' e use o mesmo connectionSize para todas as tabelas que compartilharem o pool. No VVR 8.0.3 e anteriores, cada tabela possui seu próprio pool por padrão. No VVR 8.0.4 e posteriores, tabelas com o mesmo endpoint em um job compartilham um pool — se muitas tabelas compartilharem o mesmo pool, defina valores diferentes para connectionPoolName para evitar escassez de conexões.

aggressive.enabled

Boolean

Não

false

Define se um commit deve ser forçado durante períodos de ociosidade da conexão, mesmo que nenhuma condição de flush tenha sido atendida. Reduz a latência de gravação sob tráfego baixo. Suportado quando sdkMode=jdbc_fixed, jdbc ou jdbc_copy. Requer VVR 8.0.11 ou posterior.

Opções obsoletas

As opções a seguir estão obsoletas. Utilize as opções de substituição indicadas.

Opção

Substituição

Observações

useRpcMode

sdkMode=rpc

Definir useRpcMode=true equivale a sdkMode=rpc. Não disponível quando property-version=1.

ignoredelete

sink.delete-strategy

Tem efeito apenas quando mutatetype=insertorupdate. Para VVR 8.0.8 ou posterior, use sink.delete-strategy em vez disso. Se ambas forem definidas, apenas sink.delete-strategy será aplicada. O padrão é true quando property-version=0, e false quando property-version=1.

Específicas de tabela de dimensão

Modo SDK e conexão

Opção

Tipo de dados

Obrigatório

Padrão

Descrição

sdkMode

String

Não

jdbc

Modo SDK para consulta de dados. jdbc: suporta consultas pontuais (chave primária) e consultas sem chave primária; consultas sem chave primária são lentas. rpc: apenas consultas pontuais em chaves primárias; todos os campos de chave primária devem estar na cláusula ON; não suporta JSONB ou RoarinBitmap. jdbc_fixed: apenas consultas pontuais em chaves primárias; todos os campos de chave primária devem estar na cláusula ON; não suporta JSONB, RoarinBitmap ou bancos de dados com mascaramento de dados ativado. Para valores recomendados por versão do VVR, consulte Notas importantes.

useRpcMode

Boolean

Não

false

Define se a consulta deve usar RPC. Definir como true equivale a sdkMode=rpc.

connectionSize

Integer

Não

3

Tamanho do pool de conexões JDBC. Aumente este valor se o job apresentar baixo throughput.

connectionPoolName

String

Não

Nome do pool de conexões. Comportamento idêntico ao das tabelas de destino — consulte a opção connectionPoolName de destino para detalhes.

Lote e varredura

Opção

Tipo de dados

Obrigatório

Padrão

Descrição

jdbcReadBatchSize

Integer

Não

128

Quantidade máxima de registros por lote para consultas pontuais.

jdbcReadBatchQueueSize

Integer

Não

256

Quantidade máxima de solicitações enfileiradas por thread para consultas pontuais.

jdbcReadTimeoutMs

Long

Não

0

Tempo limite para consultas pontuais, em milissegundos. 0 significa sem tempo limite.

jdbcReadRetryCount

Integer

Não

1 (antes do VVR 8.0.5), 10 (VVR 8.0.5+)

Número de tentativas quando uma consulta pontual atinge o tempo limite. Difere de jdbcRetryCount, que se aplica a falhas de conexão.

jdbcScanFetchSize

Integer

Não

256

Quantidade de registros por lote durante uma operação de varredura em junções um-para-muitos (sem chave primária completa).

jdbcScanTimeoutSeconds

Integer

Não

60

Tempo limite para uma operação de varredura, em segundos.

Cache

Opção

Tipo de dados

Obrigatório

Padrão

Descrição

cache

String

Não

None

Política de cache. None: sem cache. LRU: armazena resultados de consultas em cache usando a política least-recently-used (menos recentemente usado).

cacheSize

Integer

Não

10000

Quantidade máxima de linhas a serem armazenadas em cache. Aplica-se apenas quando cache=LRU.

cacheTTLMs

Long

Não

Tempo limite do cache, em milissegundos. Quando cache=LRU, especifica o TTL — por padrão, as entradas de cache não expiram. Quando cache=None, esta opção não tem efeito.

cacheEmpty

Boolean

Não

true

Define se consultas JOIN que retornam resultados vazios devem ser armazenadas em cache.

async

Boolean

Não

false

Define se os resultados das consultas devem ser retornados de forma assíncrona. Quando true, os resultados não são ordenados.

Fusos horários do Realtime Compute for Apache Flink e Hologres

Tipos de tempo

Serviço

Tipo

Descrição

Flink

TIMESTAMP

Data e hora sem fuso horário. Representado como string, por exemplo, 1970-01-01 00:00:04.001.

Flink

TIMESTAMP_LTZ

Um ponto absoluto no tempo. Armazenado como LONG (milissegundos desde a época) ou INT (nanossegundos dentro dos milissegundos). A época é 00:00:00 UTC em 1º de janeiro de 1970. Interpretado e exibido com base no fuso horário da sessão, portanto o mesmo valor aparece como horários locais diferentes em fusos distintos — por exemplo, 2024-03-19T04:00:00Z aparece como 2024-03-19T12:00:00 em Xangai (UTC+8).

Hologres

TIMESTAMP

Data e hora sem fuso horário, semelhante ao TIMESTAMP do Flink. O valor não muda quando o fuso horário do cliente Hologres é alterado.

Hologres

TIMESTAMPTZ

Data e hora com fuso horário, semelhante ao TIMESTAMP_LTZ do Flink. Armazenado como UTC; convertido para o fuso horário do cliente quando consultado.

Mapeamentos de fuso horário

Com type-mapping.timestamp-converting.legacy=false (VVR 8.0.6 ou posterior), todas as conversões de tipo entre Flink e Hologres são suportadas sem desvio de dados.

Tipo Flink

Tipo Hologres

Comportamento

TIMESTAMP

TIMESTAMP

Sem conversão de fuso horário. Recomendado para leitura e gravação no Hologres.

TIMESTAMP_LTZ

TIMESTAMPTZ

TIMESTAMP

TIMESTAMPTZ

A conversão de fuso horário é realizada. Defina o fuso horário do Flink usando table.local-time-zone para garantir precisão. Por exemplo, 'table.local-time-zone': 'Asia/Shanghai' define o fuso horário do Flink como UTC+8. Gravar o valor TIMESTAMP 2022-01-01 01:01:01.123456 produz então o valor TIMESTAMPTZ 2022-01-01 01:01:01.123456+8.

TIMESTAMP_LTZ

TIMESTAMP

A conversão de fuso horário é realizada.

Com type-mapping.timestamp-converting.legacy=true (VVR 8.0.6 ou posterior) ou no VVR 8.0.5 e anteriores, pode ocorrer desvio de dados em conversões que não sejam de TIMESTAMP para TIMESTAMP.

Tipo Flink

Tipo Hologres

Comportamento

TIMESTAMP

TIMESTAMP

Sem conversão de fuso horário. Recomendado.

TIMESTAMP_LTZ

TIMESTAMPTZ

Pode ocorrer desvio de dados. Dados TIMESTAMP_LTZ são tratados como horário sem fuso horário durante a gravação. Por exemplo, 2024-03-19T04:00:00Z (que representa 2024-03-19T12:00:00 em Xangai, UTC+8) é gravado como 2024-03-19T04:00:00 e armazenado como 2024-03-19T04:00:00+08, gerando um desvio de 8 horas.

TIMESTAMP

TIMESTAMPTZ

Pode ocorrer desvio de dados se o fuso horário do Flink diferir do fuso horário da JVM. As conversões utilizam o fuso horário da JVM, não o do Flink.

TIMESTAMP_LTZ

TIMESTAMP