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

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   # can also be `master` or other banch
)
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

Создайте экземпляр 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({})   // Enable SSL
      .SetPort(9440)       // for connections over SSL ClickHouse Cloud uses port 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 и передайте callback для обработки результата. Результаты запроса возвращаются в виде объектов 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

Python

Сторонние клиенты

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

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

Примеры

Настройка объекта Client

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

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

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

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

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

​Примеры

​Настройка объекта Client

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

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

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

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

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

Примеры

Настройка объекта Client

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

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

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

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