C++ 클라이언트 라이브러리

clickhouse-cpp는 ClickHouse의 공식 C++ 클라이언트 라이브러리로, 네이티브 바이너리 프로토콜을 사용해 ClickHouse에 빠르고 type-safe한 인터페이스를 제공합니다. 빌드 지침, 사용 예시 및 추가 문서는 프로젝트의 GitHub 리포지토리에서 확인할 수 있습니다: https://github.com/ClickHouse/clickhouse-cpp.

이 라이브러리는 현재 활발히 개발되고 있습니다. 이미 ClickHouse의 핵심 기능을 지원하지만, 일부 기능과 데이터 타입은 아직 완전히 구현되지 않았거나 지원되지 않을 수 있습니다.피드백은 매우 중요하며, 새 기능과 개선 사항의 우선순위를 정하는 데 도움이 됩니다. 제한 사항, 누락된 기능 또는 예상치 못한 동작을 발견한 경우, 다음 issue tracker를 통해 확인한 내용이나 기능 요청을 공유해 주십시오: 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 또는 SSL이 활성화된 다른 ClickHouse 배포에 연결할 때 필요합니다. TLS를 사용하지 않는 연결에서는 생략할 수 있지만, 일반적으로는 활성화하는 것이 좋습니다. SSL 지원을 포함해 빌드하려면 OpenSSL 개발 패키지가 설치되어 있어야 합니다. Debian, Ubuntu 또는 그 파생 배포판에서는 libssl-dev를, Fedora 및 Red Hat에서는 openssl-devel를, macOS에서는 Homebrew를 사용하여 openssl을 설치하십시오. 종속성을 사용할 수 있게 되면, 타깃을 내보낸 라이브러리 타깃에 링크하십시오:

target_link_libraries(your-target PRIVATE clickhouse-cpp-lib)

예시

클라이언트 객체 설정

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

#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 등 다른 SQL 문에도 동일하게 적용됩니다.

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

데이터 삽입

테이블에 데이터를 삽입하려면 Block을 만들고 테이블 스키마(table schema)에 맞는 컬럼 객체를 채워 넣습니다. 데이터는 컬럼별로 추가되며, 그다음 효율적인 배치 쓰기에 최적화된 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 메서드를 사용하고, 결과를 처리할 콜백을 제공하십시오. 쿼리 결과는 ClickHouse의 네이티브 컬럼 지향 데이터 표현을 반영하는 Block 객체로 전달됩니다.

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

타사 클라이언트

프로젝트에 라이브러리 포함하기

예시

클라이언트 객체 설정

데이터 없이 테이블을 생성하고 쿼리 실행하기

데이터 삽입

데이터 조회

지원되는 데이터 타입

​프로젝트에 라이브러리 포함하기

​예시

​클라이언트 객체 설정

​데이터 없이 테이블을 생성하고 쿼리 실행하기

​데이터 삽입

​데이터 조회

​지원되는 데이터 타입

프로젝트에 라이브러리 포함하기

예시

클라이언트 객체 설정

데이터 없이 테이블을 생성하고 쿼리 실행하기

데이터 삽입

데이터 조회

지원되는 데이터 타입