메인 콘텐츠로 건너뛰기
ClickHouse의 비동기 삽입은 클라이언트 측 배칭이 어렵거나 적합하지 않을 때 강력한 대안이 됩니다. 이는 특히 수백 개 또는 수천 개의 에이전트가 로그, 메트릭, 트레이스 데이터를 지속적으로, 대개는 작은 실시간 payload로 전송하는 관측성 워크로드에서 매우 유용합니다. 이러한 환경에서 클라이언트 측 버퍼링을 사용하면 충분히 큰 batch를 보낼 수 있도록 중앙 집중식 큐가 필요해져 복잡성이 커집니다.
동기 모드에서 작은 batch를 많이 전송하는 것은 권장되지 않습니다. 이 경우 많은 파트가 생성되어 쿼리 성능이 저하되고 “too many part” 오류가 발생할 수 있습니다.
비동기 삽입은 들어오는 데이터를 메모리 내 버퍼에 기록한 뒤, 구성 가능한 임계값에 따라 스토리지에 플러시함으로써 배칭 책임을 클라이언트에서 서버로 옮깁니다. 이 방식은 파트 생성 오버헤드를 크게 줄이고, CPU 사용량을 낮추며, 높은 동시성에서도 수집이 효율적으로 유지되도록 합니다. 핵심 동작은 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만 행)를 초과하면 한 번의 플러시로 여러 파트가 생성될 수 있습니다.
비동기 삽입을 사용하더라도 파티셔닝 키의 cardinality가 높으면 “too many parts” 오류가 발생할 수 있습니다.

​
중복 제거 및 안정성

기본적으로 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
이를 통해 서버가 중지되기 전에 버퍼링된 데이터가 모두 스토리지에 기록됩니다.

​
Buffer 테이블과의 비교

비동기 삽입은 Buffer 테이블을 대체하는 최신 방식입니다. 주요 차이점은 다음과 같습니다.
  • DDL 변경이 필요하지 않습니다. 비동기 삽입은 투명하게 동작하므로 추가 테이블을 생성할 필요 없이 설정만 활성화하면 됩니다.
  • 쿼리 shape별 버퍼링. 비동기 삽입은 고유한 각 쿼리 shape와 설정 조합마다 별도의 버퍼를 유지하므로 세분화된 플러시 정책을 적용할 수 있습니다. Buffer 테이블은 대상 테이블마다 단일 버퍼를 사용합니다.
  • 내구성. 기본 모드(wait_for_async_insert=1)에서는 클라이언트가 확인 응답을 받기 전에 데이터가 디스크에 기록된 것이 보장됩니다. Buffer 테이블은 fire-and-forget 방식으로 동작하므로 장애가 발생하면 버퍼링된 데이터가 손실됩니다.
  • 클러스터 동작. 클러스터에서는 비동기 삽입 버퍼가 노드별로 유지됩니다. Buffer 테이블은 각 노드에 명시적으로 생성해야 합니다.
마지막 수정일 2026년 6월 10일