메인 콘텐츠로 건너뛰기
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   # `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을 설치하십시오. 의존성을 사용할 수 있게 되면, 대상에 내보낸 라이브러리 타깃을 링크하십시오: 
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({})   // SSL 활성화
      .SetPort(9440)       // SSL 연결 시 ClickHouse Cloud는 포트 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을 생성한 뒤 테이블 스키마에 맞는 컬럼 객체를 채우십시오. 데이터는 컬럼별로 추가되며, 이후 효율적인 배치 쓰기에 최적화된 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 메서드를 사용하고, 결과를 처리할 콜백을 제공하십시오. 쿼리 결과는 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
마지막 수정일 2026년 6월 10일