> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.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 또는 SSL이 활성화된 다른 ClickHouse 배포에 연결할 때 필요합니다. TLS를 사용하지 않는
연결에는 생략할 수 있지만, 일반적으로는 활성화하는 것이 좋습니다.

SSL 지원을 포함해 빌드하려면 OpenSSL 개발 패키지가 설치되어 있어야 합니다. Debian, Ubuntu 또는 그 파생판에서는
`libssl-dev`를, Fedora, Red Hat에서는 `openssl-devel`을, macOS에서는
Homebrew를 사용해 `openssl`을 설치하십시오.

의존성을 사용할 수 있게 되면, 대상에 내보낸 라이브러리 타깃을 링크하십시오:

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

<div id="examples">
  ## 예시
</div>

<div id="example-setup-client">
  ### 클라이언트 객체 설정
</div>

ClickHouse에 연결하려면 `Client` 인스턴스를 생성합니다. 다음 예시는
비밀번호가 필요하지 않고 SSL이 활성화되지 않은 로컬 ClickHouse 인스턴스에 연결하는 방법을
보여줍니다.

```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` 등의 다른 SQL 문에도 적용됩니다.

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