Resumen de clientes Java - ClickHouse Documentation

Cliente de ClickHouse

El cliente de Java es una biblioteca que implementa una API propia y abstrae los detalles de la comunicación de red con el servidor ClickHouse. Actualmente, solo admite la interfaz HTTP. La biblioteca proporciona utilidades para trabajar con distintos formatos de ClickHouse y otras funciones relacionadas. El cliente de Java se desarrolló allá por 2015. Su base de código se volvió muy difícil de mantener, la API es confusa y resulta difícil seguir optimizándola. Por eso, en 2024 lo refactorizamos como un nuevo componente, client-v2. Tiene una API clara, una base de código más ligera, mejor rendimiento y una mejor compatibilidad con los formatos de ClickHouse (principalmente RowBinary y Native). JDBC usará este cliente en un futuro próximo.

Tipos de datos compatibles

Tipo de dato	Compatibilidad con el cliente V2	Compatibilidad con el cliente 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 datos de ClickHouse

Compatibilidad parcial

AggregateFunction — Solo groupBitmap es compatible con lecturas binarias directas. Para otras funciones de agregación (min, max, avg, etc.), use combinadores -Merge en su consulta (por ejemplo, minMerge(), avgMerge()) para resolver el estado del lado del servidor. SELECT * FROM table ... no es compatible con columnas de tipo AggregateFunction.

Notas sobre los tipos de datos

Decimal — SET output_format_decimal_trailing_zeros=1 en 21.9+ para mantener la coherencia.
Enum — puede tratarse tanto como cadena como entero.
UInt64 — se asigna a long en client-v1.

Características

Tabla de características de los clientes:

Nombre	Cliente V2	Cliente V1	Comentarios
Conexión HTTP	✔	✔
Compresión HTTP (LZ4)	✔	✔
Compresión controlada por la aplicación	✔	✗
Compresión de la respuesta del servidor - LZ4	✔	✔
Compresión de la solicitud del cliente - LZ4	✔	✔
HTTPS	✔	✔
Certificado SSL del cliente (mTLS)	✔	✔
Proxy HTTP	✔	✔
POJO SerDe	✔	✗
Pool de conexiones	✔	✔	Cuando se usa Apache HTTP Cliente
Parámetros con nombre	✔	✔
Reintento en caso de fallo	✔	✔
Conmutación por error	✗	✔
Balanceo de carga	✗	✔
Detección automática del servidor	✗	✔
Comentario de log	✔	✔
Roles de sesión	✔	✔
Autenticación del cliente mediante SSL	✔	✔
Configuración de SNI	✔	✗
Zona horaria de la sesión	✔	✔

El controlador JDBC hereda las mismas características que la implementación de cliente subyacente. Las demás características de JDBC se enumeran en su página.

Compatibilidad

Todos los proyectos de este repositorio se prueban con todas las versiones LTS activas de ClickHouse.
Política de soporte
Recomendamos actualizar el cliente de forma continua para no perder correcciones de seguridad ni nuevas mejoras.
Si tienes algún problema con la migración a la API v2, abre una incidencia y te responderemos.

Logging

Nuestro cliente de Java usa SLF4J para el logging. Puedes usar cualquier framework de logging compatible con SLF4J, como Logback o Log4j. Por ejemplo, si usas Maven, puedes añadir la siguiente dependencia a tu archivo pom.xml:

pom.xml

<dependencies>
    <!-- API de SLF4J -->
    <dependency>
        <groupId>org.slf4j</groupId>
        <artifactId>slf4j-api</artifactId>
        <version>2.0.16</version> <!-- Usa la versión más reciente -->
    </dependency>

    <!-- Logback Core -->
    <dependency>
        <groupId>ch.qos.logback</groupId>
        <artifactId>logback-core</artifactId>
        <version>1.5.16</version> <!-- Usa la versión más reciente -->
    </dependency>

    <!-- Logback Classic (conecta SLF4J con Logback) -->
    <dependency>
        <groupId>ch.qos.logback</groupId>
        <artifactId>logback-classic</artifactId>
        <version>1.5.16</version> <!-- Usa la versión más reciente -->
    </dependency>
</dependencies>

Configuración del logging

Esto dependerá del framework de logging que esté usando. Por ejemplo, si está usando Logback, podría configurar el logging en un archivo llamado logback.xml:

logback.xml

<configuration>
    <!-- Appender de consola -->
    <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 archivo -->
    <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 raíz -->
    <root level="info">
        <appender-ref ref="STDOUT" />
        <appender-ref ref="FILE" />
    </root>

    <!-- Niveles de log personalizados para paquetes específicos -->
    <logger name="com.clickhouse" level="info" />
</configuration>

Registro de cambios

​Cliente de ClickHouse

​Tipos de datos compatibles

​Características

​Compatibilidad

​Logging

​Configuración del logging

Cliente de ClickHouse

Tipos de datos compatibles

Características

Compatibilidad

Logging

Configuración del logging