Bibliothèque client C++

clickhouse-cpp est la bibliothèque client C++ officielle de ClickHouse. Elle fournit une interface rapide et à typage sûr à ClickHouse via son protocole binaire natif.

Les instructions de compilation, des exemples d’utilisation et une documentation complémentaire sont disponibles dans le dépôt GitHub du projet : https://github.com/ClickHouse/clickhouse-cpp.

La manière la plus simple d’inclure la bibliothèque dans votre projet consiste à utiliser le module FetchContent de CMake. Cette approche vous permet de fixer une version précise de la bibliothèque et de l’intégrer à votre processus de build CMake habituel.

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)

L’option WITH_OPENSSL active la prise en charge de TLS dans la bibliothèque et est requise lors d’une connexion à ClickHouse Cloud ou à d’autres déploiements ClickHouse prenant en charge SSL. Bien qu’elle puisse être omise pour les connexions sans TLS, il est généralement recommandé de l’activer.

La compilation avec la prise en charge de SSL nécessite l’installation des paquets de développement OpenSSL. Installez libssl-dev sur Debian, Ubuntu ou leurs dérivés ; openssl-devel sur Fedora et Red Hat ; ou openssl sur macOS, avec Homebrew.

Une fois la dépendance installée, liez votre cible à la cible de bibliothèque exportée :

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

Créez une instance de Client pour établir une connexion à ClickHouse. L’exemple suivant montre comment se connecter à une instance locale de ClickHouse, pour laquelle aucun mot de passe n’est requis et SSL n’est pas activé.

#include <clickhouse/client.h>

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

Dans des configurations plus avancées, des paramètres de configuration supplémentaires sont nécessaires. L'exemple suivant montre comment se connecter à une instance ClickHouse Cloud à l'aide de plusieurs paramètres supplémentaires :

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

Pour exécuter une requête qui ne renvoie aucune donnée, par exemple pour créer des tables, utilisez la méthode Execute. La même approche s’applique à d’autres instructions telles que ALTER TABLE, DROP, etc.

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

Pour insérer des données dans une table, construisez un Block et remplissez-le avec des objets de colonne correspondant au schéma de la table. Les données sont ajoutées colonne par colonne, puis insérées en une seule opération à l'aide de la méthode Insert, optimisée pour des écritures par lot efficaces.

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

Pour exécuter une requête qui renvoie des données, utilisez la méthode Select et fournissez une fonction de rappel pour traiter le résultat. Les résultats de la requête sont renvoyés sous forme d’objets Block, reflétant la représentation native colonnaire des données 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) et LowCardinality(FixedString(N))
• Nullable(T)
• Array(T)
• Tuple
• Map
• IPv4, IPv6
• Point, Ring, Polygon, MultiPolygon