Visão geral dos clientes Java

Opções para se conectar ao ClickHouse usando Java

• Cliente 0.8+
• JDBC 0.8+
• R2DBC Driver

​

Cliente ClickHouse

O cliente Java é uma biblioteca que implementa uma API própria, abstraindo os detalhes da comunicação de rede com o servidor ClickHouse. Atualmente, apenas a interface HTTP é compatível. A biblioteca fornece utilitários para trabalhar com diferentes formatos do ClickHouse e outras funções relacionadas.

O cliente Java foi desenvolvido em 2015. Sua base de código ficou muito difícil de manter, a API é confusa e é difícil otimizá-la ainda mais. Por isso, ele foi refatorado em 2024 em um novo componente, client-v2. Ele tem uma API mais clara, uma base de código mais enxuta e melhorias de desempenho, além de melhor suporte aos formatos do ClickHouse (principalmente RowBinary e Native). O JDBC usará esse cliente em breve.

​

Tipos de dados compatíveis

Tipo de dado	Suporte do Client V2	Suporte do Client V1
Int8	✔	✔
Int16	✔	✔
Int32	✔	✔
Int64	✔	✔
Int128	✔	✔
Int256	✔	✔
UInt8	✔	✔
UInt16	✔	✔
UInt32	✔	✔
UInt64	✔	✔
UInt128	✔	✔
UInt256	✔	✔
Float32	✔	✔
Float64	✔	✔
Decimal	✔	✔
Decimal32	✔	✔
Decimal64	✔	✔
Decimal128	✔	✔
Decimal256	✔	✔
Bool	✔	✔
String	✔	✔
FixedString	✔	✔
Nullable	✔	✔
Date	✔	✔
Date32	✔	✔
DateTime	✔	✔
DateTime32	✔	✔
DateTime64	✔	✔
Interval	✗	✗
Enum	✔	✔
Enum8	✔	✔
Enum16	✔	✔
Array	✔	✔
Map	✔	✔
Nested	✔	✔
Tuple	✔	✔
UUID	✔	✔
IPv4	✔	✔
IPv6	✔	✔
Object	✗	✔
Point	✔	✔
Nothing	✔	✔
MultiPolygon	✔	✔
Ring	✔	✔
Polygon	✔	✔
SimpleAggregateFunction	✔	✔
AggregateFunction*	✔	✔
Variant	✔	✗
Dynamic	✔	✗
JSON	✔	✗

Tipos de dados do ClickHouse

Suporte parcial

• AggregateFunction — Apenas groupBitmap é compatível com leituras binárias diretas. Para outras funções de agregação (min, max, avg etc.), use combinadores -Merge na sua consulta (por exemplo, minMerge(), avgMerge()) para resolver o estado no lado do servidor. SELECT * FROM table ... não é compatível com colunas do tipo AggregateFunction.

Observações sobre tipos de dados

• Decimal — SET output_format_decimal_trailing_zeros=1 na versão 21.9+ para manter a consistência.
• Enum — pode ser tratado tanto como string quanto como inteiro.
• UInt64 — mapeado para long no client-v1.

​

Funcionalidades

Tabela de funcionalidades dos clientes:

Nome	Client V2	Client V1	Comentários
Conexão HTTP	✔	✔
Compressão HTTP (LZ4)	✔	✔
Compressão controlada pela aplicação	✔	✗
Compressão da resposta do servidor - LZ4	✔	✔
Compressão da requisição do cliente - LZ4	✔	✔
HTTPS	✔	✔
Certificado SSL do cliente (mTLS)	✔	✔
Proxy HTTP	✔	✔
SerDe de POJO	✔	✗
Pool de conexões	✔	✔	Quando o Apache HTTP Client é usado
Parâmetros nomeados	✔	✔
Nova tentativa em caso de falha	✔	✔
Failover	✗	✔
Balanceamento de carga	✗	✔
Descoberta automática do servidor	✗	✔
Comentário de log	✔	✔
Papéis de sessão	✔	✔
Autenticação SSL do cliente	✔	✔
Configuração de SNI	✔	✗
Fuso horário da sessão	✔	✔

O driver JDBC herda as mesmas funcionalidades da implementação de cliente subjacente. Outras funcionalidades do JDBC estão listadas em sua página.

​

Compatibilidade

• Todos os projetos neste repositório são testados com todas as versões LTS ativas do ClickHouse.
• Política de suporte
• Recomendamos atualizar o cliente continuamente para não perder correções de segurança nem novas melhorias.
• Se você tiver algum problema com a migração para a API v2, crie uma issue e responderemos!

​

Logging

Nosso cliente Java usa SLF4J para logging. Você pode usar qualquer framework de logging compatível com SLF4J, como Logback ou Log4j. Por exemplo, se você estiver usando Maven, poderá adicionar a seguinte dependência ao arquivo pom.xml:

pom.xml

<dependencies>
    <!-- API SLF4J -->
    <dependency>
        <groupId>org.slf4j</groupId>
        <artifactId>slf4j-api</artifactId>
        <version>2.0.16</version> <!-- Use a versão mais recente -->
    </dependency>

    <!-- Logback Core -->
    <dependency>
        <groupId>ch.qos.logback</groupId>
        <artifactId>logback-core</artifactId>
        <version>1.5.16</version> <!-- Use a versão mais recente -->
    </dependency>

    <!-- Logback Classic (conecta o SLF4J ao Logback) -->
    <dependency>
        <groupId>ch.qos.logback</groupId>
        <artifactId>logback-classic</artifactId>
        <version>1.5.16</version> <!-- Use a versão mais recente -->
    </dependency>
</dependencies>

​

Configurando o logging

Isso depende do framework de logging que você está usando. Por exemplo, se estiver usando Logback, você pode configurar o logging em um arquivo chamado logback.xml:

logback.xml

<configuration>
    <!-- Appender de Console -->
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>[%d{yyyy-MM-dd HH:mm:ss}] [%level] [%thread] %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <!-- Appender de Arquivo -->
    <appender name="FILE" class="ch.qos.logback.core.FileAppender">
        <file>logs/app.log</file>
        <append>true</append>
        <encoder>
            <pattern>[%d{yyyy-MM-dd HH:mm:ss}] [%level] [%thread] %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <!-- Logger Raiz -->
    <root level="info">
        <appender-ref ref="STDOUT" />
        <appender-ref ref="FILE" />
    </root>

    <!-- Níveis de Log Personalizados para Pacotes Específicos -->
    <logger name="com.clickhouse" level="info" />
</configuration>

Changelog