Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

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

View as MarkdownEdit this pageReport an issueSet up docs MCP

clickhouse-cpp — официальная клиентская библиотека ClickHouse для C++, обеспечивающая быстрый и типобезопасный доступ к ClickHouse через его нативный бинарный протокол.

Инструкции по сборке, примеры использования и дополнительная документация доступны в GitHub-репозитории проекта: https://github.com/ClickHouse/clickhouse-cpp.

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

Самый простой способ подключить библиотеку к проекту — использовать модуль 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
Navigation