Biblioteca cliente en C++

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 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)

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
    };

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)");

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);

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";
        }
    });

• 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