Перейти к основному содержанию
clickhouse-cpp — официальная клиентская библиотека ClickHouse для C++, предоставляющая быстрый и типобезопасный интерфейс к ClickHouse через его нативный бинарный протокол. Инструкции по сборке, примеры использования и дополнительная документация доступны в 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
Последнее изменение 10 июня 2026 г.