Todos os produtos
Search
Central de documentação

Realtime Compute for Apache Flink:Hologres connector options (VVR 8 or earlier)

Última atualização: Nov 03, 2026

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

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 8.0.x do VVR.

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 default changes to 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 for 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

Gerais

As opções a seguir se aplicam a tabelas source, tabelas sink 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

—

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

tablename

String

Sim

—

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

username

String

Sim

—

O AccessKey id da sua conta Alibaba Cloud ou usuário RAM, ou um nome de usuário de conta personalizada no formato BASIC$<user_name>. Armazene as credenciais como variáveis — não as codifique diretamente (hardcode). Consulte gerencie keys.

password

String

Sim

—

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

endpoint

String

Sim

—

O endpoint do Hologres. Consulte Endpoints.

connection.ssl.mode

String

Não

disable

O modo SSL. Valores válidos: disable, require, verify-ca, verify-full. Os modos verify-ca e verify-full exigem o 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

—

O caminho do arquivo de certificado CA. Obrigatório quando connection.ssl.mode é verify-ca ou verify-full. Faça o upload do certificado usando o recurso artifacts — ele é 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 uma falha de conexão ao ler ou gravar dados.

jdbcRetrySleepInitMs

Long

Não

1000

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

jdbcRetrySleepStepMs

Long

Não

5000

Componente incremental do tempo de espera por tentativa, em milissegundos. O tempo de espera real é 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 excedem esse valor são fechadas e liberadas.

jdbcMetaCacheTTL

Long

Não

60000

Tempo máximo para manter as 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 cai abaixo desse limiar, o cache é atualizado automaticamente.

type-mapping.timestamp-converting.legacy

Boolean

Não

Consulte a descrição

Base de fuso horário para conversões entre os 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 Time zones. Requer VVR 8.0.6 ou posterior.

property-version

Integer

Não

0

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

Específicas para 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

Consulte a descrição

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

sdkMode

String

Não

holohub

O modo sdk para consumo de binary log. holohub: modo HoloHub. jdbc: modo JDBC. jdbc_fixed: modo JDBC fixo, não sujeito a limites de conexão, mas não suporta bancos de dados com data masking ativado. Para valores recomendados por versão do VVR, consulte Important notes.

jdbcBinlogSlotName

String

Não

—

O nome do slot da tabela source de binary log no modo JDBC. Tem efeito apenas quando sdkMode=jdbc. Se não for especificado, o conector crie um slot automaticamente. Se você usar o Hologres V2.1 ou posterior com o VVR 8.0.5 ou posterior, omita esta opção — o conector não tenta criar um slot automaticamente. Consulte Binary log consumption in JDBC mode.

binlogMaxRetryTimes

Integer

Não

60

Número de tentativas após falha ao ler dados de binary log.

binlogRetryIntervalMs

Long

Não

2000

Intervalo entre tentativas após falha ao ler dados de binary log, em milissegundos.

binlogRequestTimeoutMs

Long

Não

300000

Tempo limite para leitura de dados de binary log, em milissegundos.

binlogBatchReadSize

Integer

Não

100

Número de linhas lidas do binary log por lote.

cdcMode

Boolean

Não

Consulte a descrição

Indica se deve ler dados de binary log 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

Tem efeito apenas no modo CDC. true: apenas mensagens de 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 sink — por exemplo, quando ROW_NUMBER() é usado com uma cláusula OVER para deduplicação.

binlogStartupMode

String

Não

earliestOffset

O modo de consumo de binary log. initial: consome todos os dados existentes primeiro, depois os binary logs. earliestOffset: inicia a partir do binary log mais antigo. timestamp: inicia a partir do horário definido por startTime. Se startTime estiver configurado ou um horário de início for selecionado na inicialização do job, esta opção é automaticamente definida como timestamp.

startTime

String

Não

—

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

jdbcScanFetchSize

Integer

Não

256

Número de registros armazenados em buffer por lote durante uma operação de scan.

jdbcScanTimeoutSeconds

Integer

Não

60

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

jdbcScanTransactionSessionTimeoutSeconds

Integer

Não

600

Tempo limite para a transação que contém a operação de scan, em segundos. Corresponde ao GUC parameteridle_in_transaction_session_timeout do Hologres. defina como 0 para não ter tempo limite.

enable_filter_push_down

Boolean

Não

false

Indica se deve enviar as condições de filtro para o Hologres durante a fase de leitura completa de dados. Aplica-se ao ler de uma tabela source com binary logging desativado, ou durante a fase de dados completos do consumo de binary log. Requer VVR 6.0.7 ou posterior.

partition-binlog.mode

Enum

Não

DISABLE

Modo para consumo de binary logs de uma tabela particionada. DISABLE: a tabela não é tratada como particionada — uma exceção é relatada se for. DYNAMIC: consome continuamente a partição mais recente; requer que dynamic partitioning esteja ativado. STATIC: consome partições fixas simultaneamente; as partições não podem ser adicionadas ou removidas durante o consumo.

partition-binlog-lateness-timeout-minutes

Integer

Não

60

Latência máxima permitida antes de um 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 que chegam atrasados. Não pode exceder o tempo da unidade de 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 de partição (não os nomes completos das partições), separados por vírgulas. Se não for definido, todas as partições são consumidas. Expressões regulares não são suportadas.

Específicas para sink

Modos de gravação

Opção

Tipo de dados

Obrigatório

Padrão

Descrição

sdkMode

String

Não

jdbc

O modo sdk para gravação de dados. jdbc: usa um driver JDBC. jdbc_copy: indica se deve usar o modo de cópia fixa para gravação. A cópia fixa é um modo de gravação de streaming de alto desempenho com 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 os tipos de dados JSONB ou RoarinBitmap. jdbc_fixed (preview público): modo JDBC fixo, sem ocupação de conexão; não suporta JSONB, RoarinBitmap ou bancos de dados com data masking ativado. Para valores recomendados por versão do VVR, consulte Important notes.

bulkload

Boolean

Não

false

Indica se deve gravar no modo de bulk load. Tem efeito apenas quando sdkMode=jdbc_copy. Use isso para tabelas sem chave primária — os valores de chave primária devem ser únicos ao fazer bulk load em uma tabela com chave primária. O modo bulk load usa 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

Consulte a descrição

Como os registros duplicados são tratados. insertorignore: ignora duplicatas. insertorreplace: substitui as linhas existentes. insertorupdate: atualize apenas os campos definidos na DDL da tabela sink, deixando os outros campos inalterados. O padrão é insertorignore quando property-version=0, e insertorupdate quando property-version=1.

partitionrouter

Boolean

Não

false

Indica se deve gravar dados em uma tabela particionada.

createparttable

Boolean

Não

false

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

Buffer e flush

O operador sink armazena registros em buffer e faz o flush deles para o Hologres quando qualquer uma das seguintes condições é atendida:

  • O número de registros em buffer atinge jdbcWriteBatchSize.

  • O tamanho total dos registros em buffer atinge jdbcWriteBatchByteSize.

  • O tempo desde o último flush atinge jdbcWriteFlushInterval.

Opção

Tipo de dados

Obrigatório

Padrão

Descrição

jdbcWriteBatchSize

Integer

Não

256

Número máximo de registros para armazenar 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 fazer o flush dos registros em buffer, em milissegundos.

deduplication.enabled

Boolean

Não

true

Indica se deve deduplicar registros no buffer antes do flush. Quando ativado, apenas o registro mais recente para 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

Indica se deve ignorar valores nulos 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

Indica se deve substituir por um valor padrão quando um nulo é gravado em uma coluna não nula que não tem um padrão configurado. Quando true: colunas STRING são deixadas em branco, colunas NUMBER são definidas como 0, e colunas DATE/TIMESTAMP/TIMESTAMPTZ são definidas como 1970-01-01 00:00:00. Quando false: uma exceção é relatada.

remove-u0000-in-text.enabled

Boolean

Não

false

Indica se deve remover caracteres \u0000 dos 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 se tornam aaabbb, o que pode causar incompatibilidades de 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

Indica se deve gravar apenas os campos declarados na instrução INSERT. false: todos os campos definidos na DDL são gravados; campos que não estão na instrução INSERT são definidos como nulos. true: apenas os campos declarados são gravados. Tem efeito apenas 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 processamento de mensagens de retração. IGNORE_DELETE: ignora mensagens UPDATE_BEFORE e DELETE. NON_PK_FIELD_TO_NULL: ignora mensagens UPDATE_BEFORE; trata o 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 o DELETE: exclua a linha inteira 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 o UPDATE como DELETE + INSERT, garantindo a precisão dos dados; use isso para cenários sem atualização parcial. defina 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

—

Ativa o recurso de atualização condicional. defina como o nome do campo e verifique. Requisitos: uma chave primária na tabela sink, mutateType=Insertorupdate ou insertorreplace, e sdkMode=jdbc_fixed ou jdbc. Para consultas reversas, use uma tabela baseada em linhas ou híbrida de linhas e colunas. Em dados com muitas duplicatas, o check-and-put degrada para gravações únicas, reduzindo o throughput de gravação. 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 campo de verificação do registro existente; a atualização prossegue se a comparação corresponder. 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

—

Como tratar nulos no registro existente durante uma atualização condicional. No PostgreSQL, comparar qualquer valor com NULL retorna FALSE. defina esta opção e especifique 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 tiver um throughput ruim.

connectionPoolName

String

Não

—

Nome do pool de conexões. Tabelas com o mesmo nome de pool no mesmo TaskManager compartilham um pool de conexões. defina isso como qualquer string diferente de 'default' e use o mesmo connectionSize para todas as tabelas que compartilham o pool. No VVR 8.0.3 e anteriores, cada tabela tem 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 um pool, defina valores diferentes de connectionPoolName para evitar falta de conexões.

aggressive.enabled

Boolean

Não

false

Indica se deve forçar um commit durante períodos de conexão ociosa, mesmo que nenhuma condição de flush tenha sido atendida. Reduz a latência de gravação sob baixo tráfego. 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. Use as opções de substituição em seu lugar.

Opção

Substituição

Notas

useRpcMode

sdkMode=rpc

defina useRpcMode=true é equivalente 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 seu lugar. Se ambos estiverem definidos, apenas sink.delete-strategy se aplica. O padrão é true quando property-version=0, e false quando property-version=1.

Específicas para 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

O 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: consultas pontuais apenas 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: consultas pontuais apenas 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 data masking ativado. Para valores recomendados por versão do VVR, consulte Important notes.

useRpcMode

Boolean

Não

false

Indica se deve consultar usando RPC. defina como true é equivalente a sdkMode=rpc.

connectionSize

Integer

Não

3

Tamanho do pool de conexões JDBC. Aumente este valor se o job tiver um throughput ruim.

connectionPoolName

String

Não

—

Nome do pool de conexões. Mesmo comportamento das tabelas sink — consulte a opção connectionPoolName do sink para mais detalhes.

Lote e scan

Opção

Tipo de dados

Obrigatório

Padrão

Descrição

jdbcReadBatchSize

Integer

Não

128

Número máximo de registros por lote para consultas pontuais.

jdbcReadBatchQueueSize

Integer

Não

256

Número máximo 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. Isso é diferente de jdbcRetryCount, que se aplica a falhas de conexão.

jdbcScanFetchSize

Integer

Não

256

Número de registros por lote durante uma operação de scan em um join de um para muitos (sem chave primária completa).

jdbcScanTimeoutSeconds

Integer

Não

60

Tempo limite para uma operação de scan, 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 uma política de menos recentemente usado.

cacheSize

Integer

Não

10000

Número máximo de linhas para armazenar 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

Indica se deve armazenar em cache consultas JOIN que retornam resultados vazios.

async

Boolean

Não

false

Indica se deve retornar resultados de consultas 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

Service

Tipo

Descrição

Flink

TIMESTAMP

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

Flink

TIMESTAMP_LTZ

Um ponto absoluto no tempo. Armazenado como LONG (milissegundos desde a epoch) ou INT (nanossegundos dentro dos milissegundos). A epoch é 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 horários diferentes — 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 muda.

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 a 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 ou anterior, pode ocorrer desvio de dados para conversões diferentes 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. Os dados TIMESTAMP_LTZ são tratados como um horário sem fuso horário quando gravados. 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, produzindo um desvio de 8 horas.

TIMESTAMP

TIMESTAMPTZ

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

TIMESTAMP_LTZ

TIMESTAMP

—