> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8a08bda2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Документация по клиентской библиотеке ClickHouse для C++ и интеграции с фреймворком u-server

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

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

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

<Note>
  Библиотека находится в активной разработке. Хотя она уже поддерживает основную функциональность ClickHouse,
  некоторые возможности и типы данных пока могут быть реализованы не полностью или не поддерживаться.

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

<div id="including-library-into-project">
  ## Подключение библиотеки к проекту
</div>

Самый простой способ добавить библиотеку в проект — использовать модуль CMake `FetchContent`.
Этот подход позволяет зафиксировать точную версию библиотеки и собирать её в рамках обычного
рабочего процесса CMake.

```cmake theme={null}
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.

После установки зависимости свяжите целевой объект с экспортируемой библиотечной целью:

```cmake theme={null}
target_link_libraries(your-target PRIVATE clickhouse-cpp-lib)
```

<div id="examples">
  ## Примеры
</div>

<div id="example-setup-client">
  ### Настройка объекта клиента
</div>

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

```cpp theme={null}
#include <clickhouse/client.h>

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

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

```cpp theme={null}
#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
    };
```

<div id="example-create-table">
  ### Создание таблиц и выполнение запросов без возврата данных
</div>

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

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

<div id="example-insert-data">
  ### Вставка данных
</div>

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

```cpp theme={null}
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);
```

<div id="example-select">
  ### Выборка данных
</div>

Чтобы выполнить запрос, возвращающий данные, используйте метод `Select` и передайте функцию обратного вызова для обработки
результата. Результаты запроса возвращаются в виде объектов `Block`, что отражает нативное
столбцовое представление данных в ClickHouse.

```cpp theme={null}
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";
        }
    });
```

<div id="supported-data-types">
  ## Поддерживаемые типы данных
</div>

* `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`