Requisitos
- Java 11+ (para o Flink 1.17+) ou 17+ (para o Flink 2.0+)
- Apache Flink 1.17+
Matriz de compatibilidade das versões do Flink
O conector não foi testado com versões do Flink anteriores à versão 1.17.2
Instalação e configuração
Importar como dependência
Para o Flink 2.0+
- Maven
- Gradle
- SBT
Para o Flink 1.17+
- Maven
- Gradle
- SBT
Baixe o binário
flink_versioné2.0.0ou1.17stable_versioné uma versão estável do artefato
Como usar a API do DataStream
Trecho
- Java
Exemplo de início rápido
Opções de conexão com a API DataStream
Opções do cliente ClickHouse
options e serverSettings devem ser passados ao cliente como Map<String, String>. Um mapa vazio em qualquer um deles usará os padrões do cliente ou do servidor, respectivamente.
Todas as opções disponíveis do Java client estão listadas em ClientConfigProperties.java e nesta página da documentação.Todas as configurações de sessão disponíveis do servidor estão listadas nesta página da documentação.
- Java
Opções do sink
AsyncSinkBase do Flink:
Tipos de dados compatíveis
Inserção de dados do Flink no ClickHouse
Observações:
- Um
ZoneIddeve ser fornecido ao realizar operações com data. - Precisão e escala devem ser fornecidas ao realizar operações decimais.
- Para que o ClickHouse consiga interpretar uma String Java como JSON, é necessário habilitar
enableJsonSupportAsStringemClickHouseClientConfig. - O conector requer um
ElementConvertorpara mapear elementos noDataStreamde entrada para payloads do ClickHouse. Para isso, o conector forneceClickHouseConvertorePOJOConvertor, que podem ser usados para implementar esse mapeamento com os métodos de serialização deDataWriteracima.
Formatos de entrada suportados
setClickHouseFormat. Por exemplo:
Por padrão, o conector usará RowBinaryWithDefaults ou RowBinary caso
setSupportDefault em ClickHouseClientConfig seja explicitamente definido como true ou false, respectivamente.Métricas
Limitações
- No momento, o sink oferece uma garantia de entrega at-least-once. O suporte à semântica exactly-once está sendo acompanhado aqui.
- O sink ainda não oferece suporte a uma fila de dead-letter (DLQ) para armazenar temporariamente registros que não podem ser processados. Enquanto isso, o conector tentará reinserir os registros com falha e os descartará em caso de insucesso. Esse recurso está sendo acompanhado aqui.
- O sink ainda não oferece suporte à criação por meio da Table API do Flink ou do Flink SQL. Esse recurso está sendo acompanhado aqui.
Compatibilidade de versões do ClickHouse e segurança
- O conector é testado diariamente, por meio de um workflow de CI, com uma variedade de versões recentes do ClickHouse, incluindo latest e head. As versões testadas são atualizadas periodicamente à medida que novos lançamentos do ClickHouse entram em atividade. Veja aqui as versões com as quais o conector é testado diariamente.
- Consulte a política de segurança do ClickHouse para ver vulnerabilidades de segurança conhecidas e como relatar uma vulnerabilidade.
- Recomendamos atualizar o conector continuamente para não perder correções de segurança e outras melhorias.
- Se você tiver algum problema com a migração, crie uma issue no GitHub e responderemos!
Uso avançado e recomendado
- Para obter o melhor desempenho, garanta que o tipo de elemento do seu DataStream não seja um tipo genérico — veja aqui a distinção de tipos do Flink. Elementos não genéricos evitam a sobrecarga de serialização do Kryo e melhoram a vazão para o ClickHouse.
- Recomendamos definir
maxBatchSizepara pelo menos 1000 e, idealmente, entre 10.000 e 100.000. Veja este guia sobre inserções em massa para mais informações. - Para fazer desduplicação no estilo OLTP ou upsert no ClickHouse, consulte esta página da documentação. Observação: isso não deve ser confundido com a desduplicação em lote que ocorre em novas tentativas.
Solução de problemas
CANNOT_READ_ALL_DATA
Baixa vazão
numRequestSubmitted e actualRecordsPerBatch para ajudar a determinar como ajustar o tamanho do lote (maxBatchSize) e a frequência de flush. Além disso, consulte Uso avançado e recomendado para recomendações de dimensionamento de lote.
Faltam linhas na minha tabela do ClickHouse
ClickHouseClientConfig.setNumberOfRetries()). Observação: por padrão, o conector tentará reinserir um lote em até 3 tentativas antes de descartá-lo.
Solução: Inspecione os logs do TaskManager e/ou os stack traces para identificar a causa raiz.