Клиентская библиотека для C++

clickhouse-cpp — официальная клиентская библиотека ClickHouse для C++, предоставляющая быстрый и типобезопасный интерфейс к ClickHouse через его native-бинарный протокол. Инструкции по сборке, примеры использования и дополнительная документация доступны в GitHub-репозитории проекта: https://github.com/ClickHouse/clickhouse-cpp.

Библиотека находится в активной разработке. Хотя она уже поддерживает основную функциональность ClickHouse, некоторые возможности и типы данных могут быть ещё не полностью реализованы или не поддерживаться.Ваши отзывы очень важны и помогают определять приоритеты новых возможностей и улучшений. Если вы столкнётесь с ограничениями, отсутствующей функциональностью или неожиданным поведением, пожалуйста, поделитесь своими наблюдениями или запросами на новые возможности через трекер задач: https://github.com/ClickHouse/clickhouse-cpp/issues

Подключение библиотеки к вашему проекту

Самый простой способ подключить библиотеку к вашему проекту — использовать модуль CMake FetchContent. Такой подход позволяет закрепить точную версию библиотеки и собирать её в рамках стандартного рабочего процесса 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   # можно также указать `master` или другую ветку
)
FetchContent_MakeAvailable(clickhouse-cpp)

Параметр WITH_OPENSSL включает поддержку TLS в библиотеке и обязателен при подключении к ClickHouse Cloud или другим развертываниям ClickHouse с поддержкой SSL. Хотя для соединений без TLS его можно не указывать, в большинстве случаев рекомендуется его включить. Для сборки с поддержкой SSL должны быть установлены пакеты разработки OpenSSL. Установите libssl-dev в Debian, Ubuntu или их производных; openssl-devel в Fedora, Red Hat; или openssl в macOS через Homebrew. После установки зависимости свяжите целевой объект сборки с экспортируемой библиотечной целью:

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

Примеры

Настройка объекта клиента

Создайте экземпляр Client, чтобы установить соединение с ClickHouse. В следующем примере показано подключение к локальному экземпляру ClickHouse, где пароль не требуется и SSL не включен.

#include <clickhouse/client.h>

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

В более сложных сценариях требуется дополнительная настройка. В следующем примере показано, как подключиться к экземпляру ClickHouse Cloud с использованием нескольких дополнительных параметров:

#include <clickhouse/client.h>

clickhouse::Client client{
    clickhouse::ClientOptions{}
      .SetHost("your.instance.clickhouse.cloud")
      .SetUser("default")
      .SetPassword("your-password")
      .SetSSLOptions({})   // Включить SSL
      .SetPort(9440)       // для подключений через SSL ClickHouse Cloud использует порт 9440
    };

Создание таблиц и выполнение запросов без возврата данных

Чтобы выполнить запрос, который не возвращает данных, например для создания таблиц, используйте метод Execute. Тот же подход применяется и к другим командам, таким как ALTER TABLE, DROP и т. д.

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

Вставка данных

Чтобы вставить данные в таблицу, создайте Block и заполните его объектами столбцов, соответствующими схеме таблицы. Данные добавляются столбец за столбцом, а затем вставляются одной операцией с помощью метода Insert, оптимизированного для эффективной пакетной записи.

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

Выборка данных

Чтобы выполнить запрос, возвращающий данные, используйте метод Select и передайте функцию обратного вызова для обработки результата. Результаты запроса передаются в виде объектов Block, отражающих нативное для 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) и LowCardinality(FixedString(N))
Nullable(T)
Array(T)
Tuple
Map
IPv4, IPv6
Point, Ring, Polygon, MultiPolygon

​Подключение библиотеки к вашему проекту

​Примеры

​Настройка объекта клиента

​Создание таблиц и выполнение запросов без возврата данных

​Вставка данных

​Выборка данных

​Поддерживаемые типы данных