Biblioteca cliente de C++

clickhouse-cpp es la biblioteca cliente oficial de C++ para ClickHouse, que proporciona una interfaz rápida y con tipado seguro 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 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 de 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   # can also be `master` or other banch
)
FetchContent_MakeAvailable(clickhouse-cpp)

La opción WITH_OPENSSL habilita la compatibilidad con TLS en la biblioteca y es obligatoria al conectarse a ClickHouse Cloud u otras implementaciones de ClickHouse con SSL habilitado. Aunque puede omitirse para las conexiones sin TLS, por lo general se recomienda habilitarla.

Compilar con compatibilidad con SSL requiere que los paquetes de desarrollo de OpenSSL estén instalados. Instale libssl-dev en Debian, Ubuntu o sus derivados; openssl-devel en Fedora, Red Hat; o openssl en macOS, con Homebrew.

Una vez que la dependencia esté disponible, enlace su objetivo con el objetivo de biblioteca exportado:

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

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({})   // Enable SSL
      .SetPort(9440)       // for connections over SSL ClickHouse Cloud uses port 9440
    };

Para ejecutar una consulta que no devuelve ningún dato, como al crear tablas, utiliza 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)");

Para insertar datos en una tabla, construya un Block y póblelo 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 operaciones de escritura 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);

Para ejecutar una consulta que devuelva datos, use el método Select y proporcione una función de devolución de llamada 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";
        }
    });

• 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