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

C++ 클라이언트 라이브러리 (C++ client library)

clickhouse-cpp는 ClickHouse의 공식 C++ 클라이언트 라이브러리로, 네이티브 바이너리 프로토콜을 사용해 빠르고 타입 안전한 인터페이스를 제공해요. 여기서는 프로젝트에 포함하는 방법과 주요 사용 예시를 설명해 드릴게요.

출처: 문서

본문

clickhouse-cpp는 ClickHouse의 공식 C++ 클라이언트 라이브러리로, 네이티브 바이너리 프로토콜을 사용해 빠르고 타입 안전한 인터페이스를 제공해요.

빌드 지침, 사용 예시 및 추가 문서는 프로젝트의 GitHub 저장소에 있어요: https://github.com/ClickHouse/clickhouse-cpp.

참고: 이 라이브러리는 활발히 개발 중이에요. 핵심 ClickHouse 기능은 이미 지원하지만, 일부 기능과 데이터 타입은 아직 완전히 구현되거나 지원되지 않을 수 있어요. 여러분의 피드백은 매우 가치 있으며 새 기능과 개선의 우선순위를 정하는 데 도움이 돼요. 제한 사항, 누락된 기능 또는 예상치 못한 동작을 발견하면 https://github.com/ClickHouse/clickhouse-cpp/issues의 이슈 트래커를 통해 의견이나 기능 요청을 공유해 주세요.

프로젝트에 라이브러리 포함하기 (Including the library into your project)

라이브러리를 프로젝트에 통합하는 가장 간단한 방법은 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)

예시 (Examples)

클라이언트 객체 설정 (Setting the client object)

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
    };

데이터 없이 테이블 만들기 및 쿼리 실행 (Creating tables and running queries without data)

데이터를 반환하지 않는 쿼리(예: 테이블 만들기)를 실행하려면 Execute 메서드를 사용해요. ALTER TABLE, DROP 등 다른 문에도 같은 방식이 적용돼요.

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

데이터 삽입 (Inserting Data)

테이블에 데이터를 삽입하려면 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);

데이터 조회 (Selecting the data)

데이터를 반환하는 쿼리를 실행하려면 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";
        }
    });

지원되는 데이터 타입 (Supported Data Types)

  • 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) and LowCardinality(FixedString(N))
  • Nullable(T)
  • Array(T)
  • Tuple
  • Map
  • IPv4, IPv6
  • Point, Ring, Polygon, MultiPolygon

더 알아보기 (Learn more)