Biblioteca cliente en C++ - ClickHouse Documentation

clickhouse-cpp es la biblioteca cliente oficial de ClickHouse para C++, que proporciona una interfaz rápida y con seguridad de tipos para ClickHouse mediante su protocolo binario nativo. Las instrucciones de compilación, los ejemplos de uso y la documentación adicional están disponibles en el repositorio de GitHub del proyecto: https://github.com/ClickHouse/clickhouse-cpp.

La biblioteca está en desarrollo activo. Aunque ya admite la funcionalidad principal de ClickHouse, es posible que algunas características y tipos de datos aún no estén completamente implementados o no sean compatibles.Sus comentarios son muy valiosos y ayudan a orientar la priorización de nuevas características y mejoras. Si encuentra limitaciones, funciones faltantes o un comportamiento inesperado, por favor comparta sus observaciones o solicitudes de nuevas características a través del rastreador de incidencias en https://github.com/ClickHouse/clickhouse-cpp/issues

Incluir la biblioteca en tu proyecto

La forma más sencilla de incorporar la biblioteca a tu proyecto es usar el módulo FetchContent de CMake. Este enfoque te permite fijar una versión exacta de la biblioteca y compilarla como parte de tu flujo de trabajo habitual en CMake.

include(FetchContent)

set(WITH_OPENSSL YES CACHE BOOL "Enable OpenSSL in clickhouse-cpp" FORCE)
FetchContent_Declare(
    clickhouse-cpp
    GIT_REPOSITORY https://github.com/ClickHouse/clickhouse-cpp.git
    GIT_TAG v2.6.0   # también puede ser `master` u otra rama
)
FetchContent_MakeAvailable(clickhouse-cpp)

La opción WITH_OPENSSL habilita la compatibilidad con TLS en la biblioteca y es necesaria al conectarse a ClickHouse Cloud u otros despliegues de ClickHouse con SSL habilitado. Aunque puede omitirse para conexiones sin TLS, en general se recomienda habilitarla. Compilar con compatibilidad con SSL requiere que estén instalados los paquetes de desarrollo de OpenSSL. Instale libssl-dev en Debian, Ubuntu o sus derivados; openssl-devel en Fedora, Red Hat; o openssl en macOS, usando Homebrew. Una vez que la dependencia esté disponible, enlace su target con el target de biblioteca exportado:

target_link_libraries(your-target PRIVATE clickhouse-cpp-lib)

Ejemplos

Configuración del objeto Client

Cree una instancia de Client para establecer una conexión con ClickHouse. El siguiente ejemplo muestra cómo conectarse a una instancia local de ClickHouse, donde no se requiere contraseña y SSL no está habilitado.

#include <clickhouse/client.h>

clickhouse::Client client{clickhouse::ClientOptions().SetHost("localhost")};

En configuraciones más avanzadas, se requiere una configuración adicional. El siguiente ejemplo muestra cómo conectarse a una instancia de ClickHouse Cloud usando varios parámetros adicionales:

#include <clickhouse/client.h>

clickhouse::Client client{
    clickhouse::ClientOptions{}
      .SetHost("your.instance.clickhouse.cloud")
      .SetUser("default")
      .SetPassword("your-password")
      .SetSSLOptions({})   // Habilitar SSL
      .SetPort(9440)       // para conexiones SSL, ClickHouse Cloud usa el puerto 9440
    };

Crear tablas y ejecutar consultas sin datos

Para ejecutar una consulta que no devuelva ningún dato, como crear tablas, use el método Execute. El mismo enfoque se aplica a otras sentencias como ALTER TABLE, DROP, etc.

client.Execute(R"(
    CREATE TABLE IF NOT EXISTS greetings (
        id UInt64,
        message String,
        language String) 
    ENGINE = MergeTree ORDER BY id)");

Inserción de datos

Para insertar datos en una tabla, construya un Block y complételo con objetos de columna que coincidan con el esquema de la tabla. Los datos se agregan columna por columna y luego se insertan en una sola operación mediante el método Insert, que está optimizado para inserciones por lotes eficientes.

auto id = std::make_shared<clickhouse::ColumnUInt64>();
auto message = std::make_shared<clickhouse::ColumnString>();
auto language = std::make_shared<clickhouse::ColumnString>();

id->Append(1);
message->Append("Hello, World!");
language->Append("English");

id->Append(2);
message->Append("¡Hola, Mundo!");
language->Append("Spanish");

id->Append(3);
message->Append("Hallo wereld!");
language->Append("Dutch");

clickhouse::Block block{};
block.AppendColumn("id", id);
block.AppendColumn("message", message);
block.AppendColumn("language", language);

client.Insert("greetings", block);

Seleccionar los datos

Para ejecutar una consulta que devuelva datos, use el método Select y proporcione una función de callback para procesar el resultado. Los resultados de la consulta se entregan como objetos Block, lo que refleja la representación de datos nativa orientada a columna de ClickHouse.

client.Select(
    "SELECT id, message, language FROM greetings",
    [](const clickhouse::Block & block){
        for (size_t i = 0; i < block.GetRowCount(); ++i) {
            auto id = block[0]->AsStrict<clickhouse::ColumnUInt64>()->At(i);
            auto message = block[1]->AsStrict<clickhouse::ColumnString>()->At(i);
            auto language = block[2]->AsStrict<clickhouse::ColumnString>()->At(i);
            std::cout << id << "\t" << message << "\t" << language << "\n";
        }
    });

Tipos de datos compatibles

UInt8, UInt16, UInt32, UInt64, Int8, Int16, Int32, Int64
UInt128, Int128
Decimal32, Decimal64, Decimal128
Float32, Float64
Date
DateTime, DateTime64
DateTime([timezone]), DateTime64(N, [timezone])
UUID
Enum8, Enum16
String
FixedString(N)
LowCardinality(String) y LowCardinality(FixedString(N))
Nullable(T)
Array(T)
Tuple
Map
IPv4, IPv6
Point, Ring, Polygon, MultiPolygon

​Incluir la biblioteca en tu proyecto

​Ejemplos

​Configuración del objeto Client

​Crear tablas y ejecutar consultas sin datos

​Inserción de datos

​Seleccionar los datos

​Tipos de datos compatibles