INSERT 최대 관련 설정

테이블에 삽입할 블록의 최대 크기, 병렬 쓰기용 지연 스트림 수, INSERT 쿼리 실행 스레드 수 등을 제어하는 설정들이에요. 블록 형성 방식을 세밀하게 조절할 수 있답니다. 이 설정들은 system.settings 테이블에서 확인할 수 있고 소스 코드에서 자동 생성된 값들이에요.

출처: 문서

본문

이 설정들은 system.settings에서 확인할 수 있고, 소스 코드에서 자동 생성된 값들이에요.

max_insert_block_size

별칭: max_insert_block_size_rows

테이블에 삽입할 블록의 최대 크기(행 수)예요.

이 설정은 두 맥락에서 블록 형성을 제어해요:

포맷 파싱: 서버가 어떤 인터페이스(HTTP, clickhouse-client 인라인 데이터, gRPC, PostgreSQL wire 프로토콜)에서든 행 기반 입력 포맷(CSV, TSV, JSONEachRow 등)을 파싱할 때, 다음 경우에 블록이 생성돼요:
- min_insert_block_size_rows AND min_insert_block_size_bytes가 모두 도달했을 때, 또는
- max_insert_block_size_rows 또는 max_insert_block_size_bytes 중 하나가 도달했을 때
참고: clickhouse-client나 clickhouse-local로 파일을 읽을 때는 클라이언트 자체가 데이터를 파싱하고 이 설정이 클라이언트 측에 적용돼요.
INSERT 작업: INSERT 쿼리 중과 데이터가 머티리얼라이즈드 뷰를 통해 흐를 때 이 설정의 동작은 use_strict_insert_block_limits에 의존해요:
- 활성화: 다음 경우에 블록이 생성돼요. 최소 임계값(AND): min_insert_block_size_rows AND min_insert_block_size_bytes가 모두 도달. 최대 임계값(OR): max_insert_block_size_rows 또는 max_insert_block_size_bytes 중 하나 도달.
- 비활성화: min_insert_block_size_rows 또는 min_insert_block_size_bytes가 도달할 때 블록이 생성돼요. max_insert_block_size 설정은 적용되지 않아요.

가능한 값: 양의 정수.

max_insert_block_size_bytes

테이블에 삽입할 블록의 최대 크기(바이트)예요. 이 설정은 max_insert_block_size_rows와 함께 작동하며 같은 맥락에서 블록 형성을 제어해요. 이 설정들이 언제, 어떻게 적용되는지에 대한 자세한 내용은 max_insert_block_size_rows를 참조하세요.

가능한 값:

양의 정수.
0 — 설정이 블록 형성에 참여하지 않아요.

max_insert_delayed_streams_for_parallel_write

최종 파트 flush를 지연할 최대 스트림(컬럼) 수예요. 기본값은 auto(기본 스토리지가 병렬 쓰기를 지원하면 100, 예: S3, 그렇지 않으면 비활성화).

클라우드 기본값: 50.

max_insert_threads

INSERT 쿼리를 실행할 최대 스레드 수예요. 이는 INSERT SELECT와 clickhouse-client 또는 HTTP 인터페이스를 통해 데이터가 전송되는 일반 INSERT 모두에 적용돼요. 파이프라인의 쓰기 측(블록 스쿼시 및 대상 테이블에 쓰기)은 최대 이 수의 스레드로 병렬화돼요.

가능한 값:

0 — 자동. 서버에서 사용 가능한 CPU 코어 수를 사용해요(max_threads와 같은 자동 값). 메모리 압박 아래에서는 max_insert_threads_min_free_memory_per_thread로 줄어들어요.
1 — INSERT가 단일 스레드로 실행돼요(병렬 실행 없음). INSERT ... SELECT의 삽입 순서를 보존하려면 이를 사용하세요.
1보다 큰 양의 정수 — 지정된 스레드 수로 병렬 실행.

26.8 이전 버전에서는 기본값이 1이었어요(병렬 실행 없음). 26.8부터 기본값(0)이 CPU 코어 수로 해석되므로 INSERT가 기본적으로 병렬화돼요. 이전 동작을 복원하려면 max_insert_threads를 1로 설정하세요(또는 compatibility 설정 사용).

클라우드 기본값:

8 GiB 메모리 노드의 경우 1
16 GiB 메모리 노드의 경우 2
더 큰 노드의 경우 4

병렬 INSERT SELECT는 SELECT 부분이 병렬로 실행될 때만 효과가 있어요(max_threads 설정 참조). 일반 INSERT의 경우 입력 데이터는 단일 스트림으로 읽고 파싱한 뒤, 파이프라인이 쓰기용으로 이 수의 스트림으로 리사이즈돼요.

쓰기 측 병렬화는 안전할 때만 적용돼요. 그렇지 않으면 단일 스트림을 유지하고 이 설정은 그에 영향이 없어요. 특히 다음 경우에는 쓰기가 단일 스트림으로 유지돼요. use_strict_insert_block_limits가 활성화되고, 대상 테이블(또는 그가 전달하는 테이블)이 삽입된 블록을 중복 제거하고 쿼리에 대한 삽입 중복 제거가 활성화된 경우(deduplicate_insert 참조), 대상이 종속 머티리얼라이즈드 뷰를 가질 때 — 대상이 전달하는 테이블의 뷰를 포함해(예: Alias 뒤) — (parallel_view_processing이 활성화되고 종속 뷰 체인이 중복 제거 위험이 없거나 — 뷰의 중복 제거가 비활성화(deduplicate_blocks_in_dependent_materialized_views)되거나 어떤 종속 뷰 경로도 중복 제거할 수 없을 때 — 제외), 그리고 항상 Buffer와 Distributed 대상의 경우. Buffer는 자신의 컨텍스트에서 flush하고 Distributed는 쓰기를 원격 샤드로 전달하므로(그 자체가 데이터를 버퍼링할 수 있음) 이 쿼리의 중복 제거 설정이 최종 쓰기를 지배하지 않고, 그와 무관하게 단일 스트림으로 유지돼요. 비-병렬 쿼럼 삽입(insert_quorum이 2 이상이거나 'auto', 그리고 insert_quorum_parallel이 비활성화)도 테이블당 하나의 진행 중 쿼럼 파트만 허용하므로 단일 스트림을 유지해요.

값이 높을수록 메모리 사용량이 높아져요.

max_insert_threads_min_free_memory_per_thread

max_threads_min_free_memory_per_thread와 같지만 max_threads 대신 max_insert_threads에 적용돼요. 기본값이 더 높은 이유는 삽입 파이프라인이 읽기 파이프라인보다 더 큰 스레드당 버퍼(머지 트리 파트, 압축 블록)를 보통 보유하기 때문이에요.

여유 메모리가 max_insert_threads에 이 값을 곱한 것보다 적으면 max_insert_threads가 맞도록 줄어들고 최소 1로 내려가요.

이 제한을 비활성화하려면 0으로 설정하세요.

INSERT 최대 관련 설정