DB 서버와 프로토콜을 통해 통신하기 위한 Java 클라이언트 라이브러리입니다. 현재 구현은 HTTP 인터페이스만 지원합니다.
이 라이브러리는 서버에 요청을 전송하기 위한 자체 API를 제공하며, 다양한 바이너리 데이터 포맷(RowBinary* & Native*)을 처리하기 위한 도구도 함께 제공합니다.
액세스 토큰 또는 Bearer 토큰(예: JWT)을 통한 인증(authentication)을 사용하려면 SSL 클라이언트 인증서로 인증하려면
다음과 같은 애플리케이션은 자신을 식별하기 위해 HTTP 헤더 ⚠️ 중요: 작업별로 구성하려면 클라이언트 빌더 대신 이후 매개변수매개변수매개변수매개변수매개변수매개변수매개변수매개변수통합 방식애플리케이션에 관측성을 통합하는 주요 패턴은 두 가지입니다:V2 TSV 포맷 데이터 삽입.
Setup
- Maven Central (프로젝트 웹 페이지): https://mvnrepository.com/artifact/com.clickhouse/client-v2
- 나이틀리 빌드 (리포지토리 링크): https://central.sonatype.com/repository/maven-snapshots/
- Maven
- Gradle (Kotlin)
- Gradle
초기화
Client 객체는com.clickhouse.client.api.Client.Builder#build()를 통해 초기화됩니다. 각 클라이언트는 고유한 Context를 가지며, 클라이언트 간에 객체는 공유되지 않습니다.
Builder에는 편리한 설정을 위한 구성 메서드가 있습니다.예시:showLineNumbers
Client는 AutoCloseable이므로 더 이상 필요하지 않을 때 닫아야 합니다.인증(Authentication)
인증은 초기화 단계에서 클라이언트별로 구성됩니다. 지원되는 인증 방법은 비밀번호, 액세스 토큰, SSL 클라이언트 인증서의 세 가지입니다.password를 통한 인증(authentication)은setUsername(String) 및 setPassword(String)을 호출하여 username과 password를 설정해야 합니다:showLineNumbers
useBearerTokenAuth(String)을 호출하여(원시 액세스 토큰의 경우 setAccessToken(String) 호출) 토큰을 설정해야 합니다:showLineNumbers
setUsername(String), useSSLAuthentication(boolean), setClientCertificate(String), setClientKey(String)를 각각 호출하여 사용자 이름을 설정하고 SSL 인증을 활성화한 뒤 클라이언트 인증서와 클라이언트 키를 설정해야 합니다:showLineNumbers
SSL 인증은 SSL 라이브러리에서 발생하는 많은 오류가 충분한 정보를 제공하지 않기 때문에 운영 환경(production)에서는 트러블슈팅이 어려울 수 있습니다. 예를 들어 클라이언트 인증서와 키가 일치하지 않으면 서버가 즉시 connection을 종료합니다(HTTP의 경우, HTTP request가 전송되기 전인 connection 초기화 단계에서 종료되므로 응답도 전송되지 않습니다).인증서와 키를 검증하려면 openssl과 같은 도구를 사용하십시오:
- 키 무결성 확인:
openssl rsa -in [key-file.key] -check -noout - 클라이언트 인증서에 사용자와 일치하는 CN이 있는지 확인:
- 사용자 인증서에서 CN 가져오기 -
openssl x509 -noout -subject -in [user.cert] - 동일한 값이 데이터베이스에 설정되어 있는지 확인:
select name, auth_type, auth_params from system.users where auth_type = 'ssl_certificate'(auth_params에는{"common_names":["some_user"]}와 같은 값이 출력됩니다)
- 사용자 인증서에서 CN 가져오기 -
연결 풀링
Client는 내부 HTTP 연결 풀을 갖춘 Apache HttpClient 5를 사용합니다. 각 작업은 풀에서 연결을 가져와 요청을 전송하고, 응답을 스트리밍한 뒤 연결을 다시 풀에 반환합니다.Client.Builder의 주요 연결 풀 설정:권장 연결 풀 구성
showLineNumbers
구성
모든 설정은 인스턴스 메서드(구성 메서드라고도 함)로 정의되며, 각 값의 범위와 Context를 명확하게 나타냅니다. 주요 구성 매개변수는 하나의 범위(클라이언트 또는 작업)에서 정의되고, 서로 재정의되지 않습니다.구성은 클라이언트 생성 시 정의됩니다.com.clickhouse.client.api.Client.Builder를 참조하십시오.클라이언트 구성
- 연결 및 엔드포인트
- 인증(Authentication)
- 타임아웃 및 재시도
- 소켓 옵션
- 압축
- SSL/보안
- 프록시
- HTTP 및 헤더
- 서버 설정
- 시간대
- 고급
클라이언트 식별
쿼리 로그에는 요청을 발생시킨 애플리케이션을 식별하는 두 필드가 있습니다:client_name과 http_user_agent. 네이티브 TCP 프로토콜은 애플리케이션을 식별하기 위해 client_name을 사용하고, HTTP 프로토콜은 http_user_agent를 사용합니다. 클라이언트 빌더에는 두 프로토콜에 대해 올바른 값을 설정하는 setClientName 메서드가 있습니다.
http_user_agent 필드는 User-Agent 헤더의 일반 형식인 application-name[/version] [(operating-system; architecture; ...)]에 따라 설정됩니다.
이 값 집합은 애플리케이션, 클라이언트 라이브러리, HTTP 클라이언트 라이브러리 등 각 계층마다 반복됩니다. setClientName 메서드로 설정한 값이 목록의 맨 앞에 옵니다.예시:showLineNumbers
http_user_agent 값이 생성됩니다:User-Agent를 직접 설정할 수 있습니다. 단, clickhouse-java-v2/0.9.6-SNAPSHOT 부분이 헤더 끝에 자동으로 추가됩니다.작업 식별
쿼리 로그에는 작업을 식별하고 쿼리 로그에 추가 정보를 남기는 데 사용할 수 있는query_id와 log_comment라는 두 개의 필드가 더 있습니다.query_id는 작업의 고유 식별자입니다. QuerySettings 클래스의 setQueryId 메서드를 호출하면 애플리케이션에서 직접 설정할 수 있습니다.showLineNumbers
log_comment은 쿼리 로그에 추가할 수 있는 주석입니다. QuerySettings 클래스의 logComment 메서드를 호출하면 애플리케이션에서 설정할 수 있습니다.showLineNumbers
서버 설정
서버 측 설정은 클라이언트 생성 시 클라이언트 수준에서 한 번 지정하거나(Builder의 serverSetting 메서드 참조), 작업 수준에서도 지정할 수 있습니다(작업 설정 클래스의 serverSetting 참조).showLineNumbers
setOption 메서드(Client.Builder 또는 작업 설정 클래스)를 통해 옵션을 설정하는 경우, 서버 설정 이름 앞에 clickhouse_setting_을 접두사로 추가해야 합니다. 이 경우 com.clickhouse.client.api.ClientConfigProperties#serverSetting()을 사용하면 편리합니다.사용자 지정 HTTP 헤더
사용자 정의 HTTP headers는 모든 작업(클라이언트 수준) 또는 개별 작업(작업 수준)에 설정할 수 있습니다. 작업 설정은 이름이 같은 클라이언트 수준 header를 재정의합니다.showLineNumbers
Client.Builder 또는 작업 설정 클래스의 setOption을 통해 옵션을 설정할 때는 헤더 이름에 http_header_ 접두사를 붙이십시오. ClientConfigProperties.httpHeader(String)이 해당 키를 생성합니다.
헤더 이름은 단순한 String 키이므로 대문자나 소문자 중 하나로 통일해야 합니다. 그렇지 않으면 중복 값으로 인해 정의되지 않은 동작이 발생합니다. ClientConfigProperties.httpHeader(String)이 이 문제를 해결합니다.showLineNumbers
ClickHouse Cloud 기능
ClickHouse Cloud에 연결할 때 적용되는 기능입니다.Replica-aware 라우팅 (CLOUD)
ClickHouse Cloud에서는 서로 관련된 HTTP 요청을 동일한 레플리카로 보내도록 고정할 수 있습니다. Cloud 프록시가 같은 태그를 가진 모든 요청을 하나의 레플리카로 라우팅하도록X-ClickHouse-Replica-Tag 헤더를 전송하십시오. 임시 테이블(temporary tables)과 같이 세션 범위에서 사용하는 객체를 처리하거나, 레플리카의 로컬 캐시를 재사용하거나, 쓰기 후 읽기 일관성을 확보할 때 이 기능을 사용하십시오.
자세히 알아보기: https://clickhouse.com/docs/products/cloud/features/infrastructure/replica-aware-routing.설정할 항목: HTTP 헤더 X-ClickHouse-Replica-Tag (com.clickhouse.client.api.http.ClickHouseHttpProto.HEADER_REPLICA_TAG). 동일한 레플리카로 전달되어야 하는 모든 요청에는 같은 태그 값을 사용하십시오.showLineNumbers
QuerySettings, InsertSettings 또는 CommandSettings에 헤더를 설정하십시오.JWT 인증 (CLOUD)
JWT 인증을 사용하면 ClickHouse Cloud에서 JSON Web Token(JWT)으로 사용자를 인증할 수 있습니다. ClickHouse는 미리 생성된 데이터베이스 사용자(database users) 대신, 각 토큰에 포함된 클레임을 기반으로 임시 사용자를 동적으로 생성합니다.초기 구성
클라이언트에서 초기 JWT 인증을 구성하려면Client 인스턴스를 빌드할 때 useBearerTokenAuth(token)을 사용하십시오(이 메서드는 Bearer_ 접두사를 자동으로 추가합니다.
HTTP 인터페이스 문서 참조):showLineNumbers
useBearerTokenAuth(token)은 Authorization HTTP 헤더 앞에 Bearer 접두사를 자동으로 붙입니다.런타임에 토큰 갱신
JWT는 수명이 짧고 임시 사용자는 토큰의 수명 동안에만 존재하므로, 작업이 실패하지 않도록 현재 토큰이 만료되기 전에 새 JWT 토큰을 설정해야 합니다.클라이언트를 다시 생성하지 않고도 런타임에 기존Client 인스턴스의 Bearer 토큰을 업데이트할 수 있습니다:showLineNumbers
Client 인스턴스에서 수행되는 모든 요청에는 갱신된 JWT 토큰이 사용됩니다.공통 정의
ClickHouseFormat
지원되는 포맷의 enum입니다. ClickHouse가 지원하는 모든 포맷이 포함됩니다.raw- raw 데이터는 사용자가 직접 트랜스코딩해야 합니다full- 클라이언트가 직접 데이터를 트랜스코딩할 수 있으며, 원시 데이터 스트림을 수신합니다-- 이 포맷에서는 ClickHouse가 해당 작업을 지원하지 않습니다
삽입 API
insert(String tableName, InputStream data, ClickHouseFormat format)
지정된 포맷으로 바이트의InputStream 형태로 데이터를 받습니다. data는 format으로 인코딩되어 있어야 합니다.시그니처tableName - 대상 테이블 이름입니다.data - 인코딩된 데이터의 입력 스트림입니다.format - 데이터가 인코딩되는 포맷입니다.settings - 요청 설정입니다.반환 값InsertResponse 유형의 Future - 작업 결과와 서버 측 메트릭 등의 추가 정보입니다.예시showLineNumbers
insert(String tableName, List<?> data, InsertSettings settings)
데이터베이스에 쓰기 요청을 보냅니다. 객체 목록은 효율적인 포맷으로 변환된 후 서버로 전송됩니다. 목록 항목의 클래스는register(Class, TableSchema) 메서드를 사용해 사전에 등록해야 합니다.시그니처tableName - 대상 테이블의 이름입니다.data - 컬렉션 DTO(Data Transfer Object) 객체.settings - 요청 설정입니다.반환 값InsertResponse 유형의 Future로, 작업 결과 및 서버 측 메트릭 등의 추가 정보를 포함합니다.예시showLineNumbers
InsertSettings
삽입 작업의 구성 옵션입니다.구성 방법InsertResponse
삽입 작업의 결과를 담는 응답 객체입니다. 클라이언트가 서버로부터 응답을 받은 경우에만 사용 가능합니다.이 객체는 연결을 해제하기 위해 가능한 한 빨리 닫아야 합니다. 이전 응답의 데이터를 모두 완전히 읽기 전까지는 해당 연결을 재사용할 수 없기 때문입니다.
쿼리 API
포맷 선택Client는 서버의 응답 스트림에 직접 접근할 수 있도록 합니다. 요청에서 원하는 ClickHouse 포맷을 자유롭게 선택하고QueryResponse 객체의
InputStream을 통해 데이터를 읽을 수 있습니다.
다음 방법으로 포맷을 요청할 수 있습니다:QuerySettings#setFormat()- 요청에 포맷 헤더를 설정합니다.- 쿼리 자체의
FORMAT절에서 지정합니다. - 서버 설정(server settings)
default_format(/reference/settings/session-settings/default#default_format)
- Client <
0.11.0& ClickHouse <26.8-FORMAT절이 요청 포맷 헤더보다 우선합니다. - 클라이언트 >
0.11.0& ClickHouse >26.8- 요청 헤더가FORMAT절보다 우선합니다.QuerySettings에 포맷이 지정되지 않으면 클라이언트가 헤더를 설정하므로, 쿼리에서 포맷을 재정의할 수 없습니다.
- Client는
0.11.0버전부터format의 기본값을 작업 수준이 아닌 클라이언트 수준에서 설정합니다. 따라서 기존 코드는 수정 없이 그대로 작동하며, 새 코드에서는 클라이언트의format을null로 설정하여FORMAT절을 사용할 수 있습니다.
query(String sqlQuery)
sqlQuery를 그대로 전송합니다. 응답 포맷은 쿼리 설정에 따라 결정됩니다. QueryResponse는 해당 포맷을 지원하는 리더(reader)가 읽어야 하는 응답 스트림에 대한 참조를 보유합니다.시그니처sqlQuery - 단일 SQL 구문입니다. 쿼리는 수정 없이 그대로 서버로 전송됩니다.settings - 요청 설정입니다.반환 값QueryResponse 유형의 Future로, 결과 데이터셋과 서버 측 메트릭 등의 추가 정보를 포함합니다. 데이터셋을 모두 사용한 후에는 Response 객체를 닫아야 합니다.예시query(String sqlQuery, Map<String, Object> queryParams, QuerySettings settings)
sqlQuery를 그대로 전송합니다. 또한 서버가 SQL 표현식을 컴파일할 수 있도록 쿼리 매개변수도 함께 전송합니다.시그니처sqlQuery - 자리 표시자 {}가 포함된 SQL 표현식입니다.queryParams - 서버에서 SQL 표현식을 완성하는 데 사용되는 변수들의 맵입니다.settings - 요청 설정입니다.반환 값QueryResponse 유형의 Future로, 결과 데이터셋과 서버 측 메트릭 등의 추가 정보를 포함합니다. 데이터셋을 모두 사용한 후에는 Response 객체를 닫아야 합니다.예시showLineNumbers
queryAll(String sqlQuery)
RowBinaryWithNamesAndTypes 포맷으로 데이터를 쿼리합니다. 결과를 컬렉션으로 반환합니다. 읽기 성능은 reader와 동일하지만, 전체 데이터셋을 메모리에 유지해야 하므로 더 많은 메모리가 필요합니다.시그니처sqlQuery - 서버에서 데이터를 쿼리하기 위한 SQL 표현식입니다.반환 값결과 데이터에 행(row) 방식으로 접근할 수 있는 GenericRecord 객체 목록으로 표현된 전체 데이터셋입니다.예시showLineNumbers
QuerySettings
쿼리 작업에 대한 구성 옵션입니다.구성 방법QueryResponse
쿼리 실행 결과를 담는 응답 객체입니다. 클라이언트가 서버로부터 응답을 받은 경우에만 사용할 수 있습니다.이 객체는 연결을 해제하기 위해 가능한 한 빨리 닫아야 합니다. 이전 응답의 데이터를 모두 완전히 읽기 전까지는 해당 연결을 재사용할 수 없기 때문입니다.
예시
공통 API
getTableSchema(String table)
table의 테이블 스키마(schema)를 가져옵니다.시그니처table - 스키마 데이터를 가져올 테이블 이름입니다.database - 대상 테이블이 정의된 데이터베이스입니다.반환 값테이블 컬럼 목록이 포함된 TableSchema 객체를 반환합니다.getTableSchemaFromQuery(String sql)
SQL 구문(statement)에서 스키마(schema)를 가져옵니다.시그니처sql - 스키마를 반환할 “SELECT” SQL 문입니다.반환 값sql 표현식에 맞는 컬럼이 포함된 TableSchema 객체를 반환합니다.TableSchema
register(Class<?> clazz, TableSchema schema)
schema를 사용해 데이터를 읽고 쓰는 데 사용할 Java 클래스용 직렬화(serialization) 및 역직렬화(deserialization) 레이어를 컴파일합니다. 이 메서드는 getter/setter 쌍과 이에 대응하는 컬럼에 대한 직렬화기 및 역직렬화기를 생성합니다.
컬럼 매칭은 메서드 이름에서 컬럼 이름을 추출하여 수행됩니다. 예를 들어 getFirstName은 컬럼 first_name 또는 firstname에 해당합니다.시그니처clazz - 데이터를 읽고 쓰는 데 사용되는 POJO를 나타내는 클래스입니다.schema - POJO 속성과 매칭하는 데 사용하는 데이터 스키마입니다.예시showLineNumbers
사용 예시
전체 예시 코드는 저장소의 ‘example` 폴더에서 확인할 수 있습니다:- client-v2 - 주요 예시 모음.
- demo-service - Spring Boot 애플리케이션에서 클라이언트를 사용하는 방법을 보여주는 예시입니다.
- demo-kotlin-service - Ktor(Kotlin) 애플리케이션에서 클라이언트를 사용하는 방법을 보여주는 예시입니다.
데이터 읽기
데이터를 읽는 일반적인 방법은 두 가지입니다:- 데이터가 포함된
InputStream을 담은 저수준QueryResponse객체를 반환하는query()메서드입니다. 일반적으로 스트리밍 읽기를 위해ClickHouseBinaryFormatReader와 함께 사용되지만 다른 사용자 지정 리더 구현에서도 사용할 수 있습니다.QueryResponse는 결과 집합 메타데이터와 메트릭에도 접근할 수 있게 해줍니다. queryAll()메서드와GenericRecord를 사용하면 행에 더 편리하게 접근할 수 있습니다. 이 경우 전체 결과 세트가 메모리에 로드됩니다.queryRecords()메서드는GenericRecord객체를 위한 반복자인com.clickhouse.client.api.query.Records를 반환합니다. 이 메서드는 스트리밍 방식을 사용하므로 (데이터를 메모리에 로드하지 않음)GenericRecord를 통해 데이터에 접근합니다.
배열 읽기
ClickHouseBinaryFormatReader 메서드getList(...)- 모든Array(...)를List<T>로 읽습니다. 유연한 타입 읽기에 적합한 기본값입니다. 중첩 배열도 지원합니다.getByteArray(...),getShortArray(...),getIntArray(...),getLongArray(...),getFloatArray(...),getDoubleArray(...),getBooleanArray(...)- 기본형과 호환되는 값으로 이루어진 1차원 배열에 가장 적합합니다.getStringArray(...)-Array(String)용(이름으로 표현된 enum 값도 포함).getObjectArray(...)- 중첩 배열을 포함한 모든Array(...)요소 타입에 사용할 수 있는 범용 옵션입니다. 널 허용 값을 포함하는 배열과 중첩 배열을 읽는 데 사용합니다.
GenericRecord 메서드getList(...)- 모든Array(...)를List<T>로 읽습니다. 유연한 타입 읽기에 적합한 기본값입니다. 중첩 배열도 지원합니다.getByteArray(...),getShortArray(...),getIntArray(...),getLongArray(...),getFloatArray(...),getDoubleArray(...),getBooleanArray(...)- 기본형과 호환되는 값으로 이루어진 1차원 배열에 가장 적합합니다.getStringArray(...)-Array(String)용(이름으로 표현된 enum 값도 포함).getObjectArray(...)- 중첩 배열을 포함한 모든Array(...)요소 타입에 사용할 수 있는 범용 옵션입니다. 널 허용 값을 포함하는 배열과 중첩 배열을 읽는 데 사용합니다.
관측성 및 모니터링
ClickHouse Java 클라이언트(V2)는 OpenTelemetry 시맨틱 규약과 Micrometer 메트릭을 기반으로 설계된 관측성 기능을 기본으로 제공합니다. 클라이언트를 통해 작업 소요 시간, 처리량, 재시도, 서버 실행 통계, 연결 풀 상태, 분산 추적(distributed tracing) 스팬을 모니터링할 수 있습니다.클라이언트 V2 구성, 연결 풀링(Connection Pooling),@Async 경계를 넘는 추적 컨텍스트 전파, 완전한 텔레메트리 통합을 보여 주는 운영 환경 수준의 전체 Spring Boot 애플리케이션 예시는 이 리포지토리의 examples/demo-spring-service 모듈을 참조하십시오.Client Builder 관측성 API
Client.Builder는 관측성과 메트릭 수집을 구성할 수 있는 주요 메서드 3개를 제공합니다:setMetricsRecorder(MetricsRecorder recorder): 작업 메트릭(소요 시간, 발생 횟수, 재시도, 오류)을 내보내는 메트릭 기록기를 등록합니다. 명시적으로 설정하지 않으면DefaultMetricsRecorder.NOOP가 기본값으로 사용됩니다.setSpanRecorder(SpanRecorder recorder): 분산 추적(distributed tracing)을 위한 스팬 기록기를 등록합니다(작업 스팬 및 전송 요청 스팬). 명시적으로 설정하지 않으면DefaultSpanRecorder.NOOP가 기본값으로 사용됩니다.registerClientMetrics(Object registry, String groupName): Apache HttpClient의 연결 풀 메트릭(사용 가능한 연결, 사용 중인 연결, 대기 중인 요청, 연결 생성 시간 등)을 MicrometerMeterRegistry에 연결합니다.
OpenTelemetrySpanRecorder 및 MicrometerMetricsRecorder 클래스는 client-v2 패키지의 일부로 제공됩니다. 그러나 런타임에 애플리케이션 클래스패스에 OpenTelemetry API(io.opentelemetry:opentelemetry-api) 및 Micrometer(io.micrometer:micrometer-core) 라이브러리가 있어야 합니다. 기본 클라이언트 빌드 산출물은 이러한 타사 의존성을 포함하지 않으며, 전이적으로 가져오지도 않습니다. OpenTelemetry 추적 또는 Micrometer 메트릭을 사용하는 애플리케이션은 프로젝트 빌드 구성(pom.xml 또는 build.gradle)에 이러한 의존성을 명시적으로 선언해야 합니다.빌더 구성 예시- OpenTelemetry 에이전트 및 전역 자동 구성(Autoconfiguration):
- OpenTelemetry Java 에이전트 또는 전역 SDK 자동 구성을 사용하는 애플리케이션에서는 각 클래스의 인수 없는 기본 생성자를 사용하여
OpenTelemetrySpanRecorder와MicrometerMetricsRecorder의 인스턴스를 생성하십시오. - 기본 생성자를 사용하면
GlobalOpenTelemetry.get()과 Micrometer의Metrics.globalRegistry에 자동으로 연결됩니다.
- OpenTelemetry Java 에이전트 또는 전역 SDK 자동 구성을 사용하는 애플리케이션에서는 각 클래스의 인수 없는 기본 생성자를 사용하여
- 명시적 클라이언트 수준 통합:
- 명시적으로 생성한
OpenTelemetry,Tracer또는 MicrometerMeterRegistry인스턴스를 recorder 생성자에 직접 전달합니다. - 텔레메트리 싱크가 서로 독립된 여러 격리 클라이언트나 멀티 테넌트 서비스를 관리할 때 적합합니다.
- 명시적으로 생성한
보고되는 메트릭
작업 메트릭
MetricsRecorder를 통해 내보내는 메트릭은 데이터베이스 클라이언트 메트릭에 대한 OpenTelemetry 의미론적 규약(MetricName 및 MetricAttribute)을 따릅니다:메트릭 속성 / 태그
MicrometerMetricsRecorder가 생성하는 미터(Meter)에는 카디널리티(cardinality)가 낮은 태그(MetricAttribute)가 포함됩니다:연결 풀 메트릭
registerClientMetrics(meterRegistry, "groupName")를 호출하면 HTTP 연결 풀 게이지가 Micrometer에 등록됩니다:httpcomponents.httpclient.pool.total.max: 구성에서 허용한 지속 연결의 최대 수입니다.httpcomponents.httpclient.pool.total.connections(state="available"또는state="leased"태그가 지정됨): 풀 내 활성 연결입니다.httpcomponents.httpclient.pool.total.pending: 사용 가능한 연결을 기다리는 연결 요청 수입니다.httpcomponents.httpclient.pool.route.max.default: 구성에 지정된 경로당 최대 연결 수의 기본값입니다.httpcomponents.httpclient.connect.time: 연결 수립에 걸리는 시간의 누적 평균입니다.
응답 메트릭 API
메트릭 기록기 외에도 응답 객체(QueryResponse, InsertResponse)에서 OperationMetrics를 통해 상세 실행 통계를 직접 확인할 수 있습니다:보고된 스팬
클라이언트 V2의 추적(tracing)은 부모-자식 계층 구조로 이루어진 두 종류의 스팬(span)을 생성합니다:- 작업 스팬(Operation Span): 상위 수준의 클라이언트 작업(
QUERY <database>또는INSERT <database>.<table_name>)을 나타냅니다. 현재 스레드의 추적 컨텍스트(Context.current()) 아래에서 시작되므로, 데이터베이스 작업이 호출자의 활성 트레이스 스팬에 포함됩니다. - 전송 요청 스팬(Transport Request Span): 개별 HTTP 전송 요청 시도(
POST)를 나타냅니다. 해당 작업 스팬의 자식으로 생성됩니다. 재시도할 때마다 작업 스팬 아래에 새로운 전송 요청 스팬이 생성됩니다.
스팬 속성
스팬에는 표준 OpenTelemetry 속성(SpanAttribute)이 기록됩니다:비동기 경계를 넘는 컨텍스트 전파: 클라이언트 V2는
Context.current()를 상속하므로 활성 트레이스 스팬이 있는 스레드에서 시작된 작업은 자동으로 해당 트레이스에 포함됩니다. 스레드 풀 간에 작업을 위임할 때(예: Spring @Async 또는 사용자 정의 ExecutorService)는 OpenTelemetry 컨텍스트를 명시적으로 전파하십시오:사용자 정의 레코더 개발
사용자 정의 관측성 백엔드를 사용하는 애플리케이션은DefaultMetricsRecorder(메트릭용) 또는 DefaultSpanRecorder(추적용)를 확장하여 사용자 정의 레코더를 구현할 수 있습니다.DefaultMetricsRecorder:MetricsRecorder의 기본 구현입니다.recordQuerySuccess,recordQueryFailure등 필요한 콜백을 재정의하여 사용하십시오.MetricsSupport.DEFAULT를 사용하면 표준 메트릭 이름(MetricName), 단위, 속성 맵(MetricAttribute)을 도출할 수 있습니다.DefaultSpanRecorder:SpanRecorder의 기본 구현입니다.startQuerySpan,startInsertSpan,startRequestSpan등 스팬 생성 콜백을 재정의하여 사용하십시오.SpanSupport.DEFAULT를 사용하면 표준 OpenTelemetry 스팬 이름과 속성(SpanAttribute)을 계산할 수 있습니다.
com.clickhouse.client.api.observability.otel.OpenTelemetrySpanRecorder(OpenTelemetry 추적 통합)com.clickhouse.client.api.observability.micrometer.MicrometerMetricsRecorder(Micrometer 메트릭 통합)
마이그레이션 가이드
이전 클라이언트(V1)는com.clickhouse.client.ClickHouseClient#builder를 시작점으로 사용했습니다. 새 클라이언트(V2)는 com.clickhouse.client.api.Client.Builder를 사용하는 유사한 패턴을 따릅니다. 주요 차이점은 다음과 같습니다:- 구현을 가져오기 위해 service loader를 사용하지 않습니다.
com.clickhouse.client.api.Client는 향후 다양한 구현을 위한 파사드 클래스입니다. - 구성 소스 수가 더 적습니다. 하나는 빌더에 제공되고, 다른 하나는 작업 설정(
QuerySettings,InsertSettings)에 있습니다. 이전 버전에서는 노드별 구성을 사용했고, 경우에 따라 환경 변수도 불러왔습니다.
구성 매개변수 일치
V1에는 구성과 관련된 enum 클래스가 3개 있습니다:com.clickhouse.client.config.ClickHouseDefaults- 대부분의 사용 사례에서 설정해야 하는 구성 매개변수입니다. 예를 들어USER및PASSWORD가 있습니다.com.clickhouse.client.config.ClickHouseClientOption- 클라이언트 전용 구성 매개변수입니다. 예:HEALTH_CHECK_INTERVAL.com.clickhouse.client.http.config.ClickHouseHttpOption- HTTP 인터페이스 전용 구성 매개변수입니다. 예:RECEIVE_QUERY_PROGRESS.
com.clickhouse.client.config.ClickHouseDefaults#ASYNC와
com.clickhouse.client.config.ClickHouseClientOption#ASYNC 간에 차이가 있는지 불분명한 경우 등). 새로운 V2 클라이언트는 com.clickhouse.client.api.Client.Builder를 가능한 모든 클라이언트 구성 옵션의 단일 딕셔너리로 사용합니다. 모든 구성 매개변수 이름은
com.clickhouse.client.api.ClientConfigProperties에 나열되어 있습니다.아래 표에서는 새 클라이언트에서 지원되는 기존 옵션과 해당 옵션의 새로운 의미를 확인할 수 있습니다.범례: ✔ = 지원됨, ✗ = 삭제됨- 연결 및 인증
- SSL 및 보안
- 소켓 옵션
- 압축
- 프록시
- 타임아웃 및 재시도
- 시간대
- 버퍼 및 성능
- 스레딩 & 비동기
- HTTP 및 헤더
- 포맷 및 쿼리
- 노드 디스커버리 및 부하 분산
- 기타
일반적인 차이점
- Client V2는 이식성을 높이기 위해 전용 클래스 사용을 줄였습니다. 예를 들어 V2는 서버에 데이터를 쓰는 데
java.io.InputStream의 모든 구현을 사용할 수 있습니다. - Client V2에서
async설정의 기본값은off입니다. 즉, 추가 스레드가 생성되지 않으며 클라이언트 제어를 애플리케이션에서 더 많이 할 수 있습니다. 이 설정은 대부분의 사용 사례에서off로 유지해야 합니다.async를 활성화하면 요청마다 별도의 스레드가 생성됩니다. 이는 애플리케이션에서 제어하는 실행기를 사용할 때만 의미가 있습니다(참조:com.clickhouse.client.api.Client.Builder#setSharedOperationExecutor)
데이터 쓰기
java.io.InputStream의 어떤 구현이든 사용할 수 있습니다. V1com.clickhouse.data.ClickHouseInputStream도 지원하지만 권장하지는 않습니다.- 입력 스트림의 끝이 감지되면 그에 맞게 처리됩니다. 그에 앞서 요청의 출력 스트림을 닫아야 합니다.
- 호출할 메서드는 하나뿐입니다. 추가 요청 객체를 생성하지 않아도 됩니다.
- 모든 데이터가 복사되면 요청 본문 스트림이 자동으로 닫힙니다.
- 새로운 저수준 API
com.clickhouse.client.api.Client#insert(java.lang.String, java.util.List<java.lang.String>, com.clickhouse.client.api.DataStreamWriter, com.clickhouse.data.ClickHouseFormat, com.clickhouse.client.api.insert.InsertSettings)를 사용할 수 있습니다.com.clickhouse.client.api.DataStreamWriter는 사용자 정의 데이터 쓰기 로직을 구현할 수 있도록 설계되었습니다. 예를 들어, 큐에서 데이터를 읽는 로직을 구현할 때 사용할 수 있습니다.
데이터 읽기
- 기본적으로 데이터는
RowBinaryWithNamesAndTypes포맷으로 읽어옵니다. 현재 데이터 바인딩이 필요한 경우에는 이 포맷만 지원됩니다. - 데이터는
List<GenericRecord> com.clickhouse.client.api.Client#queryAll(java.lang.String)메서드를 사용해 레코드 컬렉션으로 읽을 수 있습니다. 이 메서드는 데이터를 메모리에 읽어 들인 뒤 connection을 해제합니다. 별도의 추가 처리는 필요하지 않습니다.GenericRecord는 데이터에 접근할 수 있게 해 주며, 일부 변환 기능도 제공합니다.