효율적인 데이터 수집은 고성능 ClickHouse 배포의 기반입니다. 적절한 삽입 전략을 선택하면 처리량, 비용, 안정성에 큰 차이가 생길 수 있습니다. 이 섹션에서는 워크로드에 맞는 결정을 내릴 수 있도록 모범 사례, 장단점, 구성 옵션을 설명합니다.
아래 내용은 클라이언트를 통해 ClickHouse로 데이터를 푸시하는 경우를 가정합니다. s3 및 gcs와 같은 기본 제공 테이블 함수를 사용해 ClickHouse로 데이터를 가져오는 경우에는 “S3 삽입 및 읽기 성능 최적화” 가이드를 참조하시기 바랍니다. 클라이언트 측에서 데이터를 일괄 처리할 수 있다면 동기 삽입을 사용하세요그렇지 않다면 아래의 비동기 삽입을 참조하세요. 삽입 크기와 관계없이 삽입 쿼리 수는 초당 약 1개 수준으로 유지하는 것을 권장합니다. 그 이유는 생성된 파트가 백그라운드에서 더 큰 파트로 머지되기 때문입니다(읽기 쿼리에 맞게 데이터를 최적화하기 위해 수행됩니다). 초당 너무 많은 삽입 쿼리를 보내면 백그라운드 머지가 새로 생성되는 파트 수를 따라가지 못할 수 있습니다. 다만 asynchronous inserts를 사용하는 경우에는 초당 더 높은 삽입 쿼리 속도를 사용할 수 있습니다(Asynchronous inserts 참조).
- 삽입은 성공했지만 네트워크 중단으로 인해 클라이언트가 확인 응답을 받지 못했습니다.
- 서버 측에서 삽입이 실패한 뒤 시간 초과가 발생했습니다.
두 경우 모두 배치의 내용과 순서가 완전히 동일하게 유지되는 한 삽입을 재시도해도 안전합니다. 따라서 클라이언트는 데이터를 수정하거나 순서를 바꾸지 않고 일관되게 재시도해야 합니다.
샤딩된 cluster에서는 두 가지 옵션이 있습니다:
- MergeTree 또는 ReplicatedMergeTree 테이블에 직접 삽입합니다. 클라이언트가 세그먼트 간 부하 분산을 수행할 수 있다면 이것이 가장 효율적인 방법입니다.
internal_replication = true를 사용하면 ClickHouse가 복제를 투명하게 처리합니다.
- 분산 테이블에 삽입합니다. 이렇게 하면 클라이언트가 어느 노드로든 데이터를 보낼 수 있고, ClickHouse가 이를 올바른 세그먼트로 전달합니다. 더 단순하지만 추가 전달 단계가 있으므로 성능은 약간 떨어집니다. 이 경우에도
internal_replication = true를 권장합니다.
ClickHouse Cloud에서는 모든 노드가 동일한 단일 세그먼트에 읽기 및 쓰기를 수행합니다. 삽입은 노드 간에 자동으로 분산됩니다. 제공된 엔드포인트로 삽입을 보내면 됩니다.
ClickHouse에서 효율적으로 데이터를 수집하려면 적절한 입력 형식을 선택하는 것이 매우 중요합니다. 지원되는 포맷이 70개가 넘기 때문에, 가장 성능이 좋은 옵션을 선택하면 삽입 속도, CPU 및 메모리 사용량, 전반적인 시스템 효율성에 큰 차이가 날 수 있습니다.
유연성은 데이터 엔지니어링 작업과 파일 기반 가져오기에 유용하지만, 애플리케이션에서는 성능 중심 포맷을 우선해야 합니다:
- Native 형식 (권장): 가장 효율적입니다. 컬럼 지향 방식이며, 서버 측에서 파싱이 거의 필요하지 않습니다. Go 및 Python 클라이언트에서 기본으로 사용됩니다.
- RowBinary: 효율적인 행 기반 포맷으로, 클라이언트 측에서 컬럼 지향 변환이 어려울 때 적합합니다. Java 클라이언트에서 사용됩니다.
- JSONEachRow: 사용하기 쉽지만 파싱 비용이 큽니다. 적은 양의 데이터 처리나 빠른 통합에 적합합니다.
압축은 네트워크 오버헤드를 줄이고, 삽입 속도를 높이며, ClickHouse의 스토리지 비용을 낮추는 데 중요한 역할을 합니다. 압축을 효과적으로 사용하면 데이터 포맷이나 스키마를 변경하지 않고도 수집 성능을 향상할 수 있습니다.
삽입 데이터를 압축하면 네트워크를 통해 전송되는 페이로드 크기가 줄어들어 대역폭 사용을 최소화하고 전송 속도를 높일 수 있습니다.
삽입에서는 압축을 Native 형식과 함께 사용할 때 특히 효과적입니다. Native 형식은 이미 ClickHouse의 내부 열 지향 스토리지 모델과 일치합니다. 이 구성에서는 서버가 최소한의 변환만으로 데이터를 효율적으로 압축 해제해 직접 저장할 수 있습니다.
속도가 중요하면 LZ4, 압축률이 중요하면 ZSTD를 사용하십시오
- LZ4: 빠르고 가볍습니다. CPU 오버헤드를 거의 늘리지 않으면서 데이터 크기를 크게 줄여 주므로, 처리량이 높은 삽입에 적합하며 대부분의 ClickHouse 클라이언트에서 기본값으로 사용됩니다.
- ZSTD: 압축률은 더 높지만 CPU 사용량이 더 많습니다. 리전 간 전송이나 클라우드 제공업체 환경처럼 네트워크 전송 비용이 높은 경우에 유용하지만, 클라이언트 측 컴퓨트와 서버 측 압축 해제 시간이 약간 늘어납니다.
모범 사례: 대역폭 제약이 있거나 데이터 egress 비용이 발생하는 경우가 아니라면 LZ4를 사용하고, 그런 경우에는 ZSTD를 고려하십시오.
FastFormats benchmark 테스트에서는 LZ4로 압축한 Native 삽입으로 데이터 크기를 50% 이상 줄였고, 5.6 GiB 데이터셋의 수집 시간을 150초에서 131초로 단축했습니다. ZSTD로 전환하면 동일한 데이터셋이 1.69 GiB까지 압축되었지만, 서버 측 처리 시간은 약간 증가했습니다. 동기 모드에서 작은 batch를 많이 전송하는 것은 권장되지 않습니다. 이 경우 많은 파트가 생성되어 쿼리 성능이 저하되고 “too many part” 오류가 발생할 수 있습니다. async_insert 설정으로 제어됩니다.
비동기 삽입은 HTTP와 네이티브 TCP 인터페이스 모두에서 지원됩니다.
활성화되면 (async_insert = 1) 삽입은 버퍼링되며, 다음 플러시 조건 중 하나를 충족할 때만 디스크에 기록됩니다:
가장 먼저 도달한 임계값이 플러시를 트리거합니다.
이 배칭 과정은 클라이언트에 보이지 않으며, ClickHouse가 여러 소스에서 들어오는 삽입 트래픽을 효율적으로 머지하는 데 도움이 됩니다. 다만 플러시가 일어나기 전까지는 데이터를 쿼리할 수 없습니다. 중요한 점은 삽입 shape와 설정 조합별로 여러 버퍼가 존재하고, 클러스터에서는 노드별로 버퍼가 유지된다는 것입니다. 이를 통해 멀티 테넌트 환경 전반에서 세밀하게 제어할 수 있습니다. 그 밖의 삽입 메커니즘은 동기 삽입에서 설명한 내용과 동일합니다.
비동기 삽입의 동작은 wait_for_async_insert 설정으로 더 세밀하게 조정할 수 있습니다.
이 값을 1(기본값)로 설정하면 ClickHouse는 데이터가 디스크에 성공적으로 플러시된 후에만 삽입을 승인합니다. 이렇게 하면 강력한 내구성이 보장되고 오류 처리도 단순해집니다. 즉, 플러시 중 문제가 발생하면 해당 오류가 클라이언트에 반환됩니다. 이 모드는 대부분의 프로덕션 환경, 특히 삽입 실패를 신뢰성 있게 추적해야 하는 경우에 권장됩니다.
벤치마크에 따르면 적응형 삽입과 안정적인 파트 생성 방식 덕분에 200개 클라이언트든 500개 클라이언트든 높은 동시성에서도 우수하게 확장됩니다.
wait_for_async_insert = 0으로 설정하면 “fire-and-forget” 모드가 활성화됩니다. 이 경우 서버는 데이터가 저장소에 기록될 때까지 기다리지 않고, 데이터가 버퍼에 적재되는 즉시 삽입을 승인합니다.
이 방식은 매우 낮은 지연 시간의 삽입과 최대 처리량을 제공하므로, 빠르게 유입되지만 중요도가 낮은 데이터에 적합합니다. 하지만 그만큼의 대가도 따릅니다. 데이터가 영구 저장된다는 보장이 없고, 오류는 플러시 중에만 드러나며, 실패한 삽입을 위한 데드 레터 큐도 없습니다. 따라서 실패를 추적하려면 사후에 서버 로그와 시스템 테이블을 점검해야 합니다. 워크로드가 데이터 손실을 감수할 수 있는 경우에만 이 모드를 사용하십시오.
벤치마크에서도 버퍼 플러시가 드문 경우(예: 30초마다) 파트 수가 크게 줄고 CPU 사용량도 낮아지는 것으로 나타났지만, 조용한 실패의 위험은 여전히 남아 있습니다.
비동기 삽입을 사용하는 경우 async_insert=1,wait_for_async_insert=1을 사용할 것을 강력히 권장합니다. wait_for_async_insert=0을 사용하는 것은 매우 위험합니다. 오류가 발생해도 INSERT 클라이언트가 이를 인지하지 못할 수 있으며, ClickHouse 서버가 서비스의 신뢰성을 보장하기 위해 쓰기 속도를 늦추고 백프레셔를 형성해야 하는 상황에서도 클라이언트가 계속 빠르게 쓰기를 수행해 잠재적인 과부하를 초래할 수 있기 때문입니다.
ClickHouse는 버전 24.2부터 기본적으로 적응형 플러시 타임아웃(async_insert_use_adaptive_busy_timeout)을 사용합니다. 고정된 플러시 인터벌 대신, 유입되는 데이터 속도에 따라 타임아웃이 최소값(async_insert_busy_timeout_min_ms, 기본값 50 ms)과 최대값(async_insert_busy_timeout_max_ms, 기본값 200 ms, Cloud에서는 1000 ms) 사이에서 동적으로 조정됩니다.
데이터가 자주 들어오면 더 빨리 플러시되어 엔드 투 엔드 지연 시간이 줄어들도록 타임아웃이 최소값에 가깝게 유지됩니다. 데이터가 희소하면 더 큰 배치를 모을 수 있도록 최대값 쪽으로 증가합니다. 이는 특히 기본 모드(wait_for_async_insert=1)에서 유용합니다. 고정된 높은 타임아웃을 사용하면 플러시할 데이터가 이미 준비되어 있어도 클라이언트가 전체 인터벌 동안 대기해야 하기 때문입니다.
스키마 검증과 데이터 파싱은 삽입이 수신될 때가 아니라 버퍼가 플러시될 때 수행됩니다. 삽입 쿼리의 행 중 하나라도 파싱 또는 유형 오류가 있으면 해당 쿼리의 데이터는 전혀 플러시되지 않으며 쿼리의 전체 payload가 거부됩니다. 기본 모드(wait_for_async_insert=1)에서는 오류가 클라이언트에 반환됩니다. fire-and-forget 모드에서는 오류가 서버 로그와 system.asynchronous_inserts 테이블에 기록됩니다.
각 플러시는 버퍼 내에서 서로 다른 각 파티션 키 값마다 최소 1개의 파트를 생성합니다. 파티션 키가 없는 테이블에서도 버퍼링된 데이터가 max_insert_block_size (기본값 약 100만 행)를 초과하면 한 번의 플러시로 여러 파트가 생성될 수 있습니다.
기본적으로 ClickHouse는 동기 삽입에 대해 자동 중복 제거를 수행하므로, 장애 상황에서 재시도해도 안전합니다. 하지만 비동기 삽입에서는 명시적으로 활성화하지 않는 한 이 기능이 비활성화됩니다(종속된 materialized view가 있는 경우에는 활성화하지 마십시오 — issue 참조).
실제로 중복 제거가 활성화되어 있으면, 예를 들어 timeout이나 네트워크 연결 끊김으로 인해 동일한 삽입을 다시 시도하더라도 ClickHouse가 중복 데이터를 안전하게 무시할 수 있습니다. 이렇게 하면 멱등성을 유지하고 데이터가 두 번 기록되는 것을 방지할 수 있습니다.
비동기 삽입은 특정 사용자 또는 특정 쿼리에 대해 활성화할 수 있습니다.
-
사용자 수준에서 비동기 삽입을 활성화할 수 있습니다. 이 예시에서는 사용자
default를 사용합니다. 다른 사용자를 생성했다면 해당 사용자 이름으로 바꾸십시오.
ALTER USER default SETTINGS async_insert = 1
-
삽입 쿼리의 SETTINGS 절을 사용해 비동기 삽입 설정을 지정할 수 있습니다.
INSERT INTO YourTable SETTINGS async_insert=1, wait_for_async_insert=1 VALUES (...)
-
ClickHouse 프로그래밍 언어 클라이언트를 사용할 때는 연결 매개변수로 비동기 삽입 설정을 지정할 수도 있습니다.
예를 들어, ClickHouse Cloud에 연결할 때 ClickHouse Java JDBC 드라이버를 사용한다면 JDBC 연결 문자열에서 다음과 같이 설정할 수 있습니다.
"jdbc:ch://HOST.clickhouse.cloud:8443/?user=default&password=PASSWORD&ssl=true&custom_http_params=async_insert=1,wait_for_async_insert=1"
비동기 삽입은 INSERT INTO ... SELECT 쿼리에는 적용되지 않습니다. 삽입에 SELECT 절이 포함된 경우에는 async_insert 설정과 관계없이 쿼리가 항상 동기식으로 실행됩니다.
SYSTEM FLUSH ASYNC INSERT QUEUE
- DDL 변경이 필요하지 않습니다. 비동기 삽입은 투명하게 동작하므로 추가 테이블을 생성할 필요 없이 설정만 활성화하면 됩니다.
- 쿼리 shape별 버퍼링. 비동기 삽입은 고유한 각 쿼리 shape와 설정 조합마다 별도의 버퍼를 유지하므로 세분화된 플러시 정책을 적용할 수 있습니다. Buffer 테이블은 대상 테이블마다 단일 버퍼를 사용합니다.
- 내구성. 기본 모드(
wait_for_async_insert=1)에서는 클라이언트가 확인 응답을 받기 전에 데이터가 디스크에 기록된 것이 보장됩니다. Buffer 테이블은 fire-and-forget 방식으로 동작하므로 장애가 발생하면 버퍼링된 데이터가 손실됩니다.
- 클러스터 동작. 클러스터에서는 비동기 삽입 버퍼가 노드별로 유지됩니다. Buffer 테이블은 각 노드에 명시적으로 생성해야 합니다.
ClickHouse는 데이터 수집을 위한 두 가지 주요 인터페이스, 즉 네이티브 인터페이스와 HTTP 인터페이스를 제공합니다. 각 인터페이스는 성능과 유연성 측면에서 서로 다른 장단점이 있습니다. clickhouse-client와 Go, C++ 같은 일부 언어 클라이언트에서 사용하는 네이티브 인터페이스는 성능에 최적화되도록 설계되었습니다. 이 인터페이스는 항상 ClickHouse의 매우 효율적인 Native 형식으로 데이터를 전송하고, LZ4 또는 ZSTD를 사용하는 블록 단위 압축을 지원하며, 구문 분석 및 포맷 변환 같은 작업을 클라이언트로 넘겨 서버 측 처리를 최소화합니다.
또한 클라이언트 측에서 MATERIALIZED 및 DEFAULT 컬럼 값을 계산할 수 있으므로 서버는 이 단계를 완전히 건너뛸 수 있습니다. 따라서 네이티브 인터페이스는 효율성이 중요한 고처리량 수집 시나리오에 이상적입니다.
많은 기존 데이터베이스와 달리 ClickHouse는 HTTP 인터페이스도 지원합니다. 반대로 HTTP 인터페이스는 호환성과 유연성에 더 중점을 둡니다. 이를 사용하면 지원되는 모든 포맷으로 데이터를 전송할 수 있으며(JSON, CSV, Parquet 등 포함), Python, Java, JavaScript, Rust를 비롯한 대부분의 ClickHouse 클라이언트에서 폭넓게 지원됩니다.
이 방식은 로드 밸런서를 통해 트래픽을 쉽게 전환할 수 있으므로 ClickHouse의 네이티브 프로토콜보다 더 적합한 경우가 많습니다. 네이티브 프로토콜은 오버헤드가 약간 더 적기 때문에 삽입 성능에서 소폭의 차이가 날 수 있습니다.
하지만 네이티브 프로토콜만큼 긴밀하게 통합되지는 않으며, 값 구체화 계산이나 Native 형식으로의 자동 변환과 같은 클라이언트 측 최적화도 수행할 수 없습니다. HTTP 삽입에서도 표준 HTTP 헤더(예: Content-Encoding: lz4)를 사용해 압축할 수 있지만, 압축은 개별 데이터 블록이 아니라 전체 payload에 적용됩니다. 따라서 이 인터페이스는 순수 성능보다 프로토콜 단순성, 로드 밸런싱, 또는 폭넓은 포맷 호환성이 더 중요한 환경에서 선호되는 경우가 많습니다.
이러한 인터페이스에 대한 자세한 설명은 여기를 참조하십시오. 
