10180 words
51 minutes
[ClickHouse] 경로가 병목일 때: Iceberg Parquet 직접 읽기로 발행 84분 → 3분
  • 레이크하우스(Iceberg) → 서빙 DB(ClickHouse) 발행 배치에서 볼 수 있는 증상
    • 한 달치 1억 행 발행에 1시간 넘게 걸림
    • ClickHouse INSERT를 의심했는데 튜닝해도 거의 안 줄어듦
    • 클라이언트 옵션, 페이지 크기를 바꿔도 효과가 미미함
  • 세 줄 요약
    • 무엇을 했나 : ClickHouse가 Iceberg의 Parquet 파일을 오브젝트 스토리지에서 직접 읽게 바꿔, 같은 데이터 1.14억 행의 발행을 84분에서 3.1분으로 줄임
    • 무엇이 문제였나 : ClickHouse도 Trino의 파일 읽기도 아니었음. 이미 컬럼 파일로 있는 데이터를 HTTP, JSON, Python, Arrow를 거쳐 한 줄기로 옮기는 경로 자체가 문제
    • 대가는 무엇인가 : 직접 읽기는 Iceberg 엔진을 우회함. 엔진이 대신 처리해 주던 시간대 해석, 현재 파일 선택, 삭제 행 반영을 이제 우리가 책임짐
  • 여기서 다루는 내용
    • 병목 측정과 원인 분석, 대안 선택
    • 엔진을 우회할 때 생기는 함정
    • 운영에서 실제로 터진 트러블슈팅 3건 : 삭제 파일, 조용한 NULL 변환, 배포 확인

1. 배경: 발행은 무엇을 하는 단계인가#

1.1 데이터 흐름#

Terminal window
원천 DB → Iceberg bronze/silver → dbt → Iceberg gold
│
│ 발행 (이 글의 주제)
▼
ClickHouse (서빙)
  • 레이크(Iceberg + 오브젝트 스토리지) : 값싸게 많이 저장하고 Trino로 크게 계산하는 곳
  • ClickHouse : 낮은 지연으로 조회를 받아 주는 서빙 저장소
  • 발행 : gold 결과를 ClickHouse로 옮기는 단계
    • 공용 엔진 하나를 수십 개 대상 테이블이 같이 씀
    • 대상 테이블 예 : 월 1.1~1.4억 행, day(send_day) 파티션, dbt incremental + delete+insert

1.2 교체 방식: staging + 파티션 교체#

  • 발행 엔진은 본 테이블에 직접 쓰지 않음
Terminal window
1. 본 테이블과 같은 구조의 __staging 생성
2. staging에 적재
3. 행 수 등 검사
4. ALTER TABLE ... REPLACE PARTITION 으로 파티션만 교체
5. staging 삭제
  • 조회하는 쪽은 반쯤 찬 데이터를 보지 않음
  • 실패해도 본 테이블은 그대로 → 실패 범위가 staging 안으로 격리됨
  • 이 구조 덕분에 뒤에서 “staging을 채우는 법”만 바꾸는 좁은 변경이 가능했음

Concept

  • Staging Table : 본 테이블에 반영하기 전 데이터를 채우고 검사하는 임시 테이블. 실패 범위를 본 테이블 밖으로 격리함
  • Atomic Partition Swap : 준비된 파티션을 메타데이터 수준에서 한 번에 교체하는 방식. 복사가 없어 빠르고 읽는 쪽에 중간 상태가 보이지 않음
  • Delete+Insert Incremental : 다시 계산할 구간을 지우고 새로 넣는 증분 전략. 늦게 도착한 데이터와 재처리를 단순하게 다룰 수 있음
  • Backfill : 과거 구간을 일괄로 채우거나 다시 만드는 작업. 일상 배치와 규모가 달라 일상에서 안 보이던 병목이 드러남

2. 측정: 어디가 느린지 재기#

2.1 첫 분해#

  • ClickHouse system.query_log의 INSERT 시간과 Airflow 태스크 시간을 맞춰 봄
구간시간비중
받아서 Arrow로 만들기까지약 4,711초 (배치당 20.6초 × 229회)94%
ClickHouse INSERT 229회 (회당 1.34초)306초6%
REPLACE PARTITION 26개0.1초0%
  • 구간 합계 5,017초, 태스크 시간 5,053.5초 → 차이 1% 미만
  • 이 표 하나로 쓰기 쪽 튜닝은 후보에서 빠짐

암달의 법칙 : INSERT를 공짜로 만들어도 전체는 최대 6%만 줄어든다.

2.2 94% 안쪽 (로컬에서 약 50만 행)#

단계시간메모
HTTP 대기8.3~9.1초62~63회 왕복
값마다 타입 변환 (RowMapper)1.74초약 16%
JSON 파싱0.6초약 5%
polars 변환0.35~1.0초
fetchone 반복0.01초처음엔 의심했지만 무시할 수준

2.3 측정에 속을 뻔한 지점#

  • 이 표만 보면 “Trino 수신이 병목”이라고 말하고 싶어짐 → 실제로 처음엔 그렇게 적었다가 고침
  • 같은 노트북에서 Trino와 무관한 200MiB 다운로드를 받아 보니 10~11MiB/s, Trino 응답은 약 8MiB/s
  • 재고 있던 것은 Trino가 아니라 노트북 회선의 상한에 가까웠음
  • 여기서 얻는 규칙
    • 측정 환경이 운영과 다르면 절대값을 옮겨 쓰지 않음 (비율만 참고)
    • “병목”이라고 말하기 전에 측정 도구의 상한을 따로 잼 (기준선 측정)

2.4 병목이 아니었던 것#

후보근거
ClickHouse INSERT6%
파티션 교체0.1초
Trino의 Parquet 읽기50만 행 내보내는 동안 쿼리 CPU 1.4초. 이미 소비보다 약 3배 앞서 읽고 있었음 → 스캔이 아니라 내보내는 쪽에서 막힘
fetchmany 행 반복0.01초
Arrow 변환0.1초 미만
  • 끝내 재지 못한 것도 있음
    • 운영 pod에서 배치당 20.6초가 어떻게 나뉘는지는 모름 (로컬보다 약 2배 느림)
    • 이 구간을 경로에서 아예 없앴으므로 이번엔 필요 없었음
    • 그래서 “Python이 병목”, “수신이 병목”이라고 단정하지 않음

Concept

  • Bottleneck Analysis : 전체 시간을 구간으로 나눠 가장 오래 걸리는 구간을 찾는 분석. 측정 없이 고치면 병목이 아닌 곳을 최적화하게 됨
  • Amdahl’s Law : 전체 개선 폭은 개선 대상이 차지하는 비중에 제한된다는 법칙. 비중 6% 구간은 무한히 빨라져도 전체를 6%만 줄임
  • Measurement Validity : 측정값이 재려는 대상을 실제로 반영하는지의 문제. 환경이 운영과 다르면 절대값을 옮겨 쓰지 않음
  • Baseline Measurement : 비교 기준을 먼저 재는 일. 측정 도구나 회선의 상한을 알아야 결과를 해석할 수 있음
  • Backpressure : 소비가 느려 생산이 막히는 현상. 쿼리 엔진이 소비보다 앞서 있으면 병목은 생산이 아니라 소비 쪽에 있음
  • Premature Optimization : 근거 없이 먼저 고치는 최적화. 의심 지점 하나를 바로 고쳤다면 6% 구간에 시간을 썼을 것

3. 원인: 경로의 구조#

3.1 기존 경로#

Terminal window
Iceberg Parquet (컬럼, 압축)
→ Trino가 읽어 JSON 행으로 변환
→ HTTP 페이지 왕복 (연결 1개, 페이지당 약 8천 행, 약 1.15MiB)
→ Python: JSON 파싱, 값마다 타입 변환, 50만 행까지 모음
→ polars → Arrow (다시 컬럼)
→ ClickHouse INSERT
→ 다음 50만 행 (수신과 INSERT가 번갈아 실행, 동시 진행 없음)
  • 코드 자체는 fetchmany → DataFrame → insert를 반복하는 단순한 루프
  • 틀린 코드는 아님. 어떤 대상이든, 어떤 뷰든 옮길 수 있는 범용 경로
  • 다만 한 달치 1억 행에는 맞지 않았음

3.2 네 가지 원인#

  1. 직렬 구조
    • 연결 하나로 페이지를 차례로 받고, 50만 행이 차야 INSERT
    • 받는 동안 쓰지 않고, 쓰는 동안 받지 않음
  2. 작은 페이지
    • 50만 행에 62~63회 왕복
    • targetResultSize=16MB를 붙여도 62페이지 그대로
  3. 형식 왕복
    • 컬럼 → JSON 행 → Python 리스트 → 다시 컬럼
    • 같은 데이터가 Parquet 39바이트/행, JSON 148바이트/행
  4. 값 단위 Python 처리
    • 8개 컬럼 × 50만 행의 값마다 함수 호출
    • 단일 스레드라 코어를 늘려도 빨라지지 않음

3.3 핵심은 직렬 구조라고 판단#

원인왜 핵심이 아닌가
2. 작은 페이지직렬 구조에서 왕복이 늘어나는 증상. 설정을 바꿔도 페이지 수가 그대로
3. 형식 왕복지나가는 양과 변환 비용을 키우지만, 형식만 바꿔도 통로는 여전히 하나
4. Python 처리약 16%. 건너뛰는 옵션(legacy_primitive_types)도 약 20% 단축에 그침
  • 총 시간 = 행 수 ÷ 그 한 줄의 처리량
  • 나머지 원인은 그 처리량을 깎는 요소일 뿐, 상한은 직렬 구조가 정함
  • 단, 이것은 판단이지 증명이 아님
    • 뒤에서 고른 해결책이 네 가지를 한꺼번에 없앴으므로 개선 폭을 원인별로 나눌 수 없음
    • 가르려면 Trino 스풀링 프로토콜처럼 “형식 왕복은 남기고 직렬만 푸는” 비교를 따로 해야 함

Concept

  • Serial Bottleneck : 모든 작업이 한 줄로 지나가 그 줄의 처리량이 전체 상한이 되는 구조. 앞뒤 단계를 키워도 전체가 빨라지지 않음
  • Client-Mediated Transfer : 클라이언트가 소스에서 받아 대상에 다시 쓰는 전송 방식. 구현이 쉽고 범용적이지만 클라이언트 처리량이 상한이 됨
  • Serialization Overhead : 전송 형식으로 바꾸고 되돌리는 비용. 컬럼 데이터를 행으로 풀었다 다시 묶으면 비용이 두 번 듦
  • Symptom vs Root Cause : 관찰된 현상과 그것을 만드는 구조의 구분. 증상을 조정하는 설정은 근본 원인이 남으면 효과가 작음
  • Attribution Problem : 여러 요인을 동시에 바꾸면 개선을 요인별로 나눌 수 없다는 문제. 원인을 단정하려면 하나씩 바꾸는 시험이 필요함

4. 대안과 결정#

대안결과판단
ClickHouse 쓰기 튜닝INSERT가 6%라 최대 6%기각
클라이언트 옵션 legacy_primitive_types수신 약 20% 단축, 날짜·시각 변환을 따로 해야 함기각
targetResultSize 증가페이지 수 그대로기각
Trino 스풀링 프로토콜측정 안 함. Trino 설정과 저장소 구성 필요보류. 파일이 없는 뷰에는 유력
날짜별 병렬 발행약 25분 추정. staging 구조 변경 필요보류
ClickHouse가 Parquet 직접 읽기하루치 시험에서 해시 일치, 초당 약 74만 행채택

4.1 튜닝 대신 제거#

  • 데이터는 이미 컬럼 파일로 저장소에 있고, ClickHouse는 s3() 테이블 함수로 Parquet을 읽을 수 있음
  • 중간을 거칠 이유가 사라짐
Terminal window
기존: 파일 → Trino → HTTP/JSON → Python → Arrow → ClickHouse
새로: 파일 ────────────────────────────────────→ ClickHouse
  • 병렬화를 고르지 않은 이유
    • 병렬화는 병목 구간을 여러 줄로 늘릴 뿐, 형식 왕복과 Python 처리는 그대로
    • 직접 읽기는 그 구간 자체를 없앰

4.2 iceberg() 테이블 함수는?#

  • ClickHouse 최신 버전은 icebergS3()에서 position delete를 지원한다고 문서에 적혀 있음
  • 하지만 과거 이슈에는 “positional and equality deletes are not supported” 오류가 보고되어 있고, 지원 PR은 그 이후의 일
  • 운영 버전(23.5)에서는 기대할 수 없음 → 버전 업그레이드는 범위가 다른 작업
  • 삭제 파일을 읽을 때마다 적용하므로 큰 삭제 파일에서 느리다는 이슈도 있음

4.3 대가#

  • 공짜는 아님
    • ClickHouse가 저장소 인증과 Iceberg 파일 구조에 직접 의존
    • 엔진이 처리하던 일(현재 파일, 삭제 행, 시간대, 스키마 진화)이 우리 코드로 옴
    • 파일이 없는 뷰는 이 방법으로 옮길 수 없음
    • 코드 경로가 둘이 됨
  • 그래서 처음엔 백필에만 적용하고 일 배치는 그대로 둠

Concept

  • Data Path Elimination : 느린 중간 단계를 튜닝하지 않고 경로에서 빼는 최적화. 튜닝과 자릿수가 다른 개선이 나오기도 함
  • Server-Side Pull : 대상 시스템이 소스 저장소에서 직접 읽는 적재 방식. 중간 프로세스가 없어 빠르지만 대상이 저장소 권한과 포맷을 알아야 함
  • Abstraction Bypass : 빠른 경로를 위해 상위 계층을 건너뛰는 설계. 그 계층이 지키던 불변식을 직접 책임져야 함
  • Generality vs Performance : 범용 경로는 어떤 대상이든 처리하지만 큰 대상에서 느림. 큰 대상만 전용 경로를 두는 절충이 흔함
  • Spooled Result Protocol : 쿼리 결과를 저장소에 나눠 쓰고 클라이언트가 병렬로 받는 전송 방식. 클라이언트 경로를 유지하면서 직렬 수신을 풀 수 있음
  • Scope Containment : 새 방식을 위험이 낮은 범위에 먼저 적용하는 진행 방식. 백필로 검증한 뒤 상시 경로로 넓힘

5. 엔진을 우회할 때 생기는 함정#

5.1 처리 순서#

Terminal window
naive timestamp 컬럼 확인 (Trino, where false 로 타입만 조회)
staging 생성
날짜마다:
$files 로 현재 파일 조회 → 삭제 파일이 있으면 거부
파일이 없으면 그 날은 건너뜀 (교체도 안 함)
INSERT INTO staging
SELECT accurateCast(ifNull(col, 타입 기본값), 타입) ...
FROM s3('{a.parquet,b.parquet}', 'Parquet')
staging 누적 행 수 == record_count 누적 인지 검사
모든 날짜 성공 후: 적재한 날만 REPLACE PARTITION
staging 삭제

5.2 함정 1: 시각이 9시간 밀림#

  • gold의 업무 시각은 시간대 없는 KST 벽시계 (naive timestamp)
  • s3()는 이를 UTC로 해석 → 11/03 00:0023:59가 11/03 09:0011/04 08:59로 읽힘
  • 오류 없이 값만 바뀌는 유형
  • 벽시계 문자열을 그대로 꺼내 KST로 다시 해석해서 해결
toDateTime(substring(toString(sent_at, 'UTC'), 1, 19), 'Asia/Seoul')
  • 어느 컬럼이 naive인지는 Trino 결과 타입으로 판정
  • 대상이 DateTime64면 이 식이 소수 초를 잃으므로 거부

5.3 함정 2: 폴더를 읽으면 중복됨#

  • Iceberg는 재적재해도 예전 파일을 바로 지우지 않음 → 스냅샷 만료 전까지 폴더에 남음
  • *.parquet로 읽으면 옛 파일까지 읽힘
  • 첫 시험은 통과했음 → 그날 파일이 하나뿐이었기 때문
  • 해결 : $files가 가리키는 현재 파일만 이름으로 지정

테이블의 내용은 폴더가 아니라 메타데이터가 정한다.

  • 소소한 함정 : 파일 하나를 {a.parquet}처럼 중괄호로 감싸면 “파일 없음” 오류 → 하나일 때는 중괄호를 쓰지 않음

5.4 함정 3: 빈 날이 라이브 파티션을 지울 수 있음#

  • 코드 리뷰에서 발견
  • 파일이 없는 날에 REPLACE PARTITION을 실행하면 빈 staging 파티션으로 본 테이블 파티션이 비워짐
  • 실제로 적재한 날만 교체하고, 없는 날은 경고를 남기고 기존 데이터를 유지

5.5 함정 4: 키가 쿼리 로그에 남음#

  • 시험 중 s3() 호출에 저장소 키를 직접 넣었더니 system.query_log에 남음
    • ClickHouse는 secret은 가리고 access key는 남김 → 두 값이 같은 계정이면 그대로 노출
    • 문법 오류로 파싱 전에 실패한 쿼리에는 마스킹이 아예 적용되지 않음
  • 조치 : 키를 ClickHouse 서버 설정(named collection / s3 설정)에 등록하고 쿼리에는 URL만 씀
  • 확인 : “키 없이 읽혔다”로 끝내지 않고 음성 대조를 함
    • 서명 없는 요청 → 403
    • 설정 범위 밖 버킷 → Access Denied
    • → 공개 버킷이라서가 아니라 설정이 적용돼서 읽힌 것임을 증명
  • 남는 위험 : 설정 범위가 넓으면 s3()를 쓸 수 있는 계정은 키 없이 그 범위 전체를 읽을 수 있음 → 권한 범위를 같이 좁혀야 함

5.6 아직 모르는 것: 스키마 진화#

  • Iceberg는 컬럼을 ID로 추적하지만 s3()는 이름으로 읽음
  • 컬럼 이름을 바꾸거나, 옛 파일에 새 컬럼이 없으면 어떻게 되는지는 시험하지 않음
  • 컬럼 추가 때는 해당 구간을 모두 다시 만들어 이 문제를 피함

Concept

  • Table Metadata as Source of Truth : 테이블의 현재 내용은 폴더가 아니라 메타데이터가 정의한다는 원칙. 폴더에 있는 파일이 곧 테이블 내용은 아님
  • Naive Timestamp : 시간대 정보 없는 시각 값. 어떤 시간대로 해석할지 읽는 쪽에 맡기므로 시스템 경계에서 오해석되기 쉬움
  • Implicit Time Zone Conversion : 명시 없이 기본 시간대를 가정해 일어나는 변환. 오류 없이 값만 바뀌어 늦게 발견됨
  • Credential Externalization : 자격 증명을 쿼리와 코드 밖의 서버 설정이나 비밀 저장소에 두는 방식. 쓰는 쪽은 값을 몰라도 됨
  • Partial Masking Limitation : 로그 마스킹은 정해진 위치와 형식만 가린다는 한계. 파싱 실패 쿼리 등에는 원문이 남을 수 있음
  • Negative Control : 실패해야 할 경우가 실제로 실패하는지 보는 시험. 성공이 의도한 이유로 나왔음을 증명함
  • Schema Evolution : 기존 파일을 다시 쓰지 않고 스키마를 바꾸는 기능. 파일을 직접 읽으면 파일마다 스키마가 다를 수 있음

6. 트러블슈팅 ①: 재실행에서 생긴 삭제 파일#

  • 시험과 첫 백필은 모두 통과했는데 재실행에서 막힘

6.1 증상#

  • 컬럼을 하나 추가하면서 이미 적재한 달을 다시 만들어야 했음
  • 첫 적재 달은 성공, 이미 적재했던 달의 재실행 발행이 9초 만에 실패
Terminal window
ValueError: <table> 2026-09-01: delete files present, parquet cannot be read directly
  • 구현 때 넣어 둔 가드가 작동한 것
  • 실패 후 상태 : Iceberg는 새로 만들어짐, ClickHouse는 기존 데이터 그대로 → 본 테이블 손상 없음

6.2 원인: dbt delete+insert가 만든 position delete#

  • dbt-trino의 delete+insert가 실행하는 SQL
delete from target
where (send_day) in (select send_day from tmp);
  • Iceberg $snapshots 기록
작업추가된 데이터 파일삭제 파일지운 데이터 파일테이블 삭제 파일 수
append (다른 달 첫 적재)1160
delete (dbt, 재실행 달)+132132
append (dbt, 재실행 달)161132
delete (수동, 파티션 경계 조건)-1322930
append (재빌드)1230
  • 읽는 법
    • dbt의 delete : 한 달 전체 행을 지웠는데 파일은 그대로 두고 “이 파일의 이 위치는 지워짐”을 적은 삭제 파일 132개를 추가 → merge-on-read
    • 이어진 append : 새 파일 161개 추가 → 데이터 파일 293개. record_count만 합치면 그 달은 두 배
    • 수동 파티션 단위 delete : 데이터 파일 293개, 삭제 파일 132개를 메타데이터에서 통째로 빼고 삭제 파일은 하나도 만들지 않음 → metadata delete
  • 확인한 것 : 서브쿼리 조건 DELETE는 삭제 파일을 만들고, 파티션 경계 리터럴 DELETE는 만들지 않음
  • 추론한 것 : 서브쿼리 조건은 계획 시점에 “파티션 전체”로 증명되지 않으므로 행 단위 삭제로 간다고 봄 (실행 계획은 직접 확인하지 않음)
  • 첫 적재에서 문제가 없던 이유 : 지울 행이 없었기 때문
    • 첫 적재가 모두 통과한 것은 재실행에서도 안전하다는 근거가 되지 못함

6.3 가드가 막은 것#

  • 가드 없이 데이터 파일(content = 0)만 골랐다면?
    • 293개를 모두 읽어 staging에 2.8억 행을 넣음
    • 검증 대상인 record_count 합계도 같은 293개의 합 → 행 수 검사 통과
    • 그대로 교체하면 그 달이 두 배로 서빙됨
  • 교훈 두 가지
    1. 같은 출처끼리의 대조는 힘이 약함
      • 파일 목록과 그 목록의 record_count는 같은 메타데이터에서 나옴
      • 행 수 검사는 “읽기가 일부 실패했는가”는 잡지만 “읽어서는 안 될 파일을 골랐는가”는 못 잡음
      • 후자는 다른 불변식(삭제 파일 0, 유일 키 중복 0)이 잡아야 함
    2. 실패는 쓰기 전에, 시끄럽게
      • 가드는 staging에 쓰기 전에 실행되어 9초에 끝났고 본 테이블은 안전했음

6.4 조치: 파티션 경계로 먼저 지우고 다시 만들기#

-- 1. 파티션 경계에 맞춘 리터럴 조건으로 Iceberg 삭제 → metadata delete
delete from iceberg.gold.<table>
where send_day >= date '2026-09-01' and send_day < date '2026-10-01';
-- 2. 삭제 파일이 없는지 확인. content 0만 있어야 함
select "partition".send_day_day, content, count(*), sum(record_count)
from iceberg.gold."<table>$files"
group by 1, 2 order by 1, 2;
    1. 백필을 다시 실행 → 지울 행이 없으니 dbt의 DELETE도 삭제 파일을 만들지 않음
  • ClickHouse는 교체 전까지 기존 데이터를 계속 서빙하므로 조회가 끊기지 않음

6.5 틀렸던 판단#

  • 설계 단계에서 삭제 파일을 “있으면 거부”로만 다뤘고, “어떤 쓰기가 삭제 파일을 만드는가”는 따지지 않았음
  • 일 배치 전환도 “호출만 바꾸면 됨”이라고 봤는데 틀림
    • 일 배치는 최근 N일 창을 다시 만듦 → 기존 날짜에 delete+insert가 걸리면 매번 삭제 파일이 생김
  • 일 배치로 넓히려면
방법내용
쓰기 방식 변경 (권장)dbt가 서브쿼리 대신 창 경계 리터럴로 파티션을 먼저 지우고 append
발행 전 optimize창 파티션을 다시 써서 삭제 파일 제거. 비용 확인 필요
ClickHouse 업그레이드 + icebergS3()엔진이 삭제 파일을 처리. 범위가 크고 읽기 성능 이슈 있음

Concept

  • Merge-on-Read : 삭제와 수정을 별도 파일에 적고 읽을 때 합치는 방식. 쓰기는 빠르지만 데이터 파일만 직접 읽으면 삭제된 행까지 읽힘
  • Position Delete File : “어느 파일의 몇 번째 행이 지워졌는가”를 적은 Iceberg v2 파일. 읽는 쪽이 이를 적용해야 올바른 결과가 나옴
  • Metadata Delete : 파일을 건드리지 않고 메타데이터에서 파일 전체를 빼는 삭제. 조건이 파티션 경계와 맞을 때 가능하고 비용이 거의 없음
  • Copy-on-Write : 수정 시 영향받는 파일을 통째로 다시 쓰는 방식. 쓰기 비용이 크지만 읽는 쪽이 단순함
  • Fail-Fast Guard : 쓰기 전에 전제 조건을 검사해 바로 실패하는 장치. 조용한 오염을 시끄러운 실패로 바꿈
  • Reconciliation Independence : 대조의 강도는 두 값이 얼마나 독립된 출처인가에 달렸다는 원칙. 같은 메타데이터끼리의 일치는 선택 오류를 잡지 못함
  • First-Run vs Rerun Behavior : 처음 실행과 재실행이 다른 코드 경로를 탈 수 있다는 점. 멱등성 시험은 재실행까지 해 봐야 함

7. 트러블슈팅 ②: 기존 경로는 NULL을 조용히 바꾸고 있었음#

  • 같은 방식을 다른 파이프라인으로 넓히면서 만난 문제
  • 처음 판단 : 새 경로는 non-Nullable 대상에 NULL이 오면 CAST로 실패하게 만듦 → “조용히 바뀌는 것보다 실패가 낫다”
  • 이 판단이 뒤집힘

7.1 증상#

  • 고빈도 배치 대상 6개를 사전 검증 (새 경로 SELECT vs 현재 ClickHouse, 전체 컬럼 해시)
  • 4개는 일치, 2개는 읽기 단계에서 실패
Terminal window
Code: 349. Cannot convert NULL value to non-Nullable type
... accurateCast(site_name, 'String') (CANNOT_INSERT_NULL_IN_ORDINARY_COLUMN)

7.2 이상한 점#

  • 같은 데이터를 기존 경로는 13분마다 문제없이 싣고 있었음
  • 기존 경로 코드에는 NULL을 채우는 곳이 없음
  • 그러면 기존 경로는 이 NULL을 어떻게 처리하고 있었나?

7.3 가설과 증거#

  • 가설 : 기존 경로는 Arrow 입력 형식으로 INSERT함. ClickHouse 입력 형식 설정 input_format_null_as_default가 켜져 있으면 non-Nullable 컬럼에 온 NULL을 타입 기본값으로 바꿈
  • 증거 : non-Nullable 컬럼마다 Iceberg의 NULL 수와 ClickHouse의 기본값 수를 셈
컬럼 (CH 타입)Iceberg NULLClickHouse
site_name (String)8'' 8
trk_period (Int64)3,4020 3,402
채널 컬럼 3개 (String)각 1'' 각 1
  • 서버 설정 input_format_null_as_default = 1 확인 → 수가 정확히 맞음
  • 기존 경로는 오류 없이 NULL을 ''와 0으로 바꿔 넣고 있었음
  • 새 경로(s3() + accurateCast)는 입력 형식이 아니라 함수 변환이라 이 설정과 상관없이 실패

7.4 선택지#

안내용판단
A. 실패 유지새 경로는 NULL이면 실패잘 돌던 대상이 전환만으로 장애가 됨. 탈락
B. 대상 DDL을 Nullable로Nullable(String) 등으로 변경하류가 ''·0을 전제로 씀. 서빙 스키마 변경이라 이관과 범위가 다름. 탈락
C. dbt에서 coalesce원천 모델에서 NULL 제거모델마다 손대야 하고 다른 대상에서 또 생김. 탈락
D. 기존과 같게non-Nullable 대상만 ifNull(col, 기본값) 후 accurateCast채택. 결과가 기존과 같고 공용 함수 한 곳만 바뀜
-- non-Nullable 대상
accurateCast(ifNull(site_name, defaultValueOfTypeName('String')), 'String')
-- Nullable 대상은 그대로
accurateCast(pur_at, 'Nullable(DateTime(\'Asia/Seoul\'))')
  • 결과 : 6개 모두 행 수와 전체 컬럼 해시가 현재 ClickHouse와 일치

7.5 지킨 것: CAST 대신 accurateCast#

  • NULL 정책만 기존과 맞췄고, 범위 초과를 잡는 안전장치는 유지
  • ClickHouse 23.5에서 확인한 차이
입력CASTaccurateCast
-1 → UInt8255 (오류 없음)오류
50억 → UInt32705032704 (오류 없음)오류
Decimal(38,2) 범위 밖 → Decimal(18,2)오류 (DECIMAL_OVERFLOW)
Decimal 소수 자리 초과버림버림
Date32 범위 밖 → Date순환 (1960 → 2139)순환 (못 잡음)
  • CAST는 음수를 큰 양수로 바꿈 → 시간대 함정처럼 오류 없이 값만 틀리는 경우가 하나 더 생김
  • 날짜 범위는 둘 다 못 잡음 → 알려진 한계로 둠
  • ClickHouse 23.5 타입 기본값 : String '', Decimal 0, DateTime('Asia/Seoul') 1970-01-01 09:00:00, Date 1970-01-01, Bool false

7.6 왜 처음에 못 잡았나#

  • “NULL이면 실패”를 정할 때 비교 기준을 “옳은 동작” 으로 잡았지 “기존 경로의 동작” 으로 잡지 않았음
  • 앞선 두 대상에는 해당 NULL이 없어서 해시 대조가 통과했음
    • 이미 배포한 일 배치도 같은 잠재 장애를 갖고 있었음. NULL이 하나라도 생기면 기존 경로는 통과하고 새 경로만 실패하는 상태

해시 대조는 데이터에 있는 경우만 검증한다. 검증을 통과한 것은 코드가 아니라 그 데이터다.


Concept

  • Behavioral Parity : 이관할 때 새 시스템이 기존 시스템과 같은 입력에 같은 결과를 내게 맞추는 원칙. 개선은 동등성을 확인한 뒤 따로 함
  • Implicit Default Coercion : 입력 형식 설정 등에 의해 NULL이나 잘못된 값이 오류 없이 기본값으로 바뀌는 변환. 코드에 보이지 않아 경로를 바꿀 때 드러남
  • Data-Dependent Defect : 특정 값이 있을 때만 나타나는 결함. 그 값을 가진 데이터로 시험하기 전까지 테스트와 대조를 모두 통과함
  • Checked Narrowing Conversion : 좁은 타입으로 바꿀 때 범위를 넘으면 실패하는 변환. 조용한 순환(wraparound)을 시끄러운 실패로 바꿈
  • Characterization Testing : 기존 시스템의 실제 동작을 먼저 기록해 기준으로 삼는 시험. 레거시 이관에서 “옳은 동작”보다 “지금 동작”을 고정함

8. 트러블슈팅 ③: 배포됐는데 내 코드가 아니었음#

8.1 이미지 태그 확인#

  • “배포 완료”라는 보고를 받고 이미지 태그를 확인
차례이미지이 커밋 포함
1main 최신아니오. 브랜치가 아직 main에 머지되지 않음
21차와 동일아니오. 값이 같은 재배포
3새 태그예
  • 배포 파이프라인이 main 기준으로 이미지를 만들기 때문
  • 확인 방법
    • helm get values의 태그, 떠 있는 pod의 이미지
    • git merge-base --is-ancestor <commit> <tag>로 커밋 포함 여부
    • git으로 볼 수 없을 땐 pod 안의 코드를 직접 열어 새 함수가 있는지 확인
  • 확인하지 않았다면 다음 날 정기 실행이 기존 경로로 돌고, “새 경로가 왜 느리지?”를 찾느라 시간을 썼을 것

8.2 이미지가 맞아도 첫 런은 옛 코드일 수 있음#

  • helm 완료 직후 첫 런의 발행 시간이 기존과 같았음 (148초)
  • 로그가 기존 경로의 Arrow 배치 로그(inserted batch: cumulative_rows=500000)였고 새 경로의 loaded from files 줄이 없음
  • 원인 : scheduler가 아직 옛 이미지 → KubernetesExecutor task pod도 옛 이미지로 뜸
  • 다음 런부터 새 경로
  • 규칙 : 첫 측정값은 경로를 증명하는 로그 한 줄을 확인한 뒤에만 씀

Concept

  • Deployment Verification : 배포 완료 보고가 아니라 실제로 도는 산출물(이미지 태그, 코드)에 변경이 들어 있는지 확인하는 절차
  • Release Provenance : 배포 산출물이 어떤 커밋에서 만들어졌는지 추적하는 방법. 이미지 라벨, 태그 규칙, 조상 관계 확인
  • Rollout Lag : 배포 완료 후에도 일부 컴포넌트가 옛 버전으로 남아 있는 구간. 측정값이 어느 버전 것인지 로그로 증명해야 함

9. 결과와 검증#

9.1 같은 데이터로 비교#

  • 처음엔 다른 달끼리 비교하고 있었음 → 재실행 덕분에 같은 데이터로 잰 값이 생김
데이터행 수기존 경로s3 경로배수
같은 한 달114,154,8635,053.5초 (84.2분)186.9초 (3.1분)약 27배
3일치11,247,2351,288.8초16.5초약 78배
  • 대표 수치로는 27배를 씀
    • 78배 쪽은 기존 경로가 다른 일 배치와 겹쳐 느렸을 수 있음
    • 27배는 같은 달, 같은 행 수, 전체 태스크 시간을 비교한 값
  • 4개월치 약 4.9억 행을 한 번씩 발행한 시간 합계 12.4분 (기존 처리량으로 환산하면 약 6시간. 실측 아닌 환산)

9.2 병목이 옮겨 감#

항목값
태스크 시간 대비 INSERT 비중약 91% (기존 6%)
쿼리 실패0회
최대 메모리1.11GiB
S3 읽기 요청2,694회, 오류 6회(재시도로 성공), 스로틀 0회
  • 비중이 6% → 91%로 뒤집힘
  • 이제 태스크 시간의 대부분은 ClickHouse와 저장소 자체의 처리 → 더 빠르게 하려면 ClickHouse 설정이나 저장소를 봐야 함
  • 다른 파이프라인으로 넓혔을 때도 같은 현상
    • 일 배치 : 평일 발행 53~77분 → 32초, DAG 전체 72.5분 → 11.4분. 남은 시간의 대부분(약 8.3분)은 dbt 빌드
    • 13분 배치 : 데이터 이동 110초 → 11초, 태스크 전체 148초 → 51초. 남은 시간의 2/3는 dbt view 재생성
  • 다음 개선 대상은 발행이 아님

9.3 검증 방법#

단계내용
하루 비교스크래치 테이블에 새 경로로 적재 → 기존 데이터와 행 수, 전체 컬럼 해시, NULL 수, 시각 범위 비교
달마다Iceberg와 ClickHouse의 날짜별 행 수·유니크 수, 다른 파티션 불변, staging 잔존 없음
최종유일 키 중복 0, 필수 컬럼 빈 값 0, 시각과 날짜 파티션 불일치 0, Iceberg 삭제 파일 0
  • 행 해시는 순서에 영향받지 않도록 행별 cityHash64를 합산
  • NULL과 빈 문자열을 구분하도록 NULL을 '\0'으로 바꿔서 해시
  • 전체 컬럼 해시는 이틀만 했음 → “전 기간 해시 일치”라고 말하면 안 됨

9.4 말할 때 주의할 수치#

  • 같은 데이터로 잰 비교(27배)와 다른 날 실행끼리 잰 비교(53~77분 → 32초)를 구분
  • 후자는 통제된 비교가 아니므로 배수 대신 범위로 말함
  • 태스크 전체 개선(약 3배)과 적재 부분 개선(10배)을 섞지 않음

Concept

  • Controlled Comparison : 비교 대상을 뺀 나머지를 같게 맞춘 비교. 같은 데이터로 잰 값이 다른 달끼리의 비교보다 강함
  • Throughput : 단위 시간당 처리량. 크기가 다른 작업을 비교할 때 총 소요 시간보다 공정함
  • Bottleneck Migration : 한 병목을 없애면 다음으로 느린 곳이 병목이 되는 현상. 개선 후에 다시 재야 다음 지점이 보임
  • Order-Independent Checksum : 행 해시를 합산해 순서와 무관하게 집합을 비교하는 방법. 데이터를 옮기지 않고 대규모 비교가 가능함
  • Shadow Load : 운영 테이블과 별도 공간에 새 경로로 적재해 비교하는 시험. 운영 영향 없이 실제 데이터로 검증함
  • Extrapolation Risk : 작은 표본 결과를 큰 규모로 환산할 때 생기는 오차. 환산치와 실측치를 구분해 말해야 함

10. 다른 파이프라인으로 넓힐 때#

10.1 전부 옮기지 않음#

  • 같은 공용 함수를 쓰는 대상이 수십 개지만 시간은 소수에 몰려 있음
  • 전환 판단 기준 네 가지
    1. 시간을 많이 쓰는가 : 작은 대상은 옮겨도 코드 경로만 늘어남
    2. 파일로 존재하는가 : 뷰는 s3()로 읽지 못함 → 스풀링이나 물질화 검토
    3. 쓰기 방식이 삭제 파일을 만드는가 : 지금 $files에 삭제 파일이 0이어도 재실행하면 생길 수 있음. dbt table은 안전, delete+insert·merge는 확인 필요
    4. 상시 부하를 감당하는가 : 백필 몇 번과 13분마다 도는 상시 읽기는 다른 문제. 저장소 503 이력 확인

10.2 일부 행만 적재할 때의 대조#

  • 원천이 파티션 없이 한 폴더이고, 그중 일부 행만 싣는 대상도 있음
  • 행 필터는 s3() 읽기에 직접 붙임 (predicate pushdown)
    • 단, naive timestamp 컬럼은 s3()가 UTC로 읽으므로 where에 쓰면 거부
  • 이때는 파일 record_count 합과 비교할 수 없음 → 같은 조건으로 Trino가 센 count(*) 와 비교
    • Trino 집계는 Iceberg 엔진이 계산하므로 우리가 고른 파일 목록과 독립된 출처
  • 경합(TOCTOU) 주의
    • 세는 동안 dbt가 테이블을 CREATE OR REPLACE하면 행 수는 같아도 옛 파일을 읽을 수 있음
    • 순서를 다음처럼 고정
Terminal window
files = $files 현재 데이터 파일 (삭제 파일 있으면 거부)
expect = Trino count(*) where ...
files 다시 조회 → 다르면 거부
INSERT INTO staging SELECT accurateCast(...) FROM s3(files) where ...
staging 행 수 == expect 확인

10.3 바꾼 범위를 좁게#

  • 파티션 교체, 창 밖 파티션 거부, 부분 실패 처리 같은 기존 로직은 그대로 둠
  • 바꾼 범위를 “staging을 채우는 법”으로 한정 → 되돌리기도 이전 이미지 배포 한 번

Concept

  • Pareto Prioritization : 소수의 대상이 대부분의 비용을 차지한다는 관찰에 따라 상위부터 처리하는 방식. 전체 일괄 변경보다 대가가 작음
  • Materialization Strategy : 모델 결과를 뷰, 전체 테이블, 증분 테이블 중 무엇으로 저장할지의 선택. 이후 어떤 읽기 경로가 가능한지까지 정함
  • Independent Reconciliation Source : 검증 대상과 다른 경로로 계산한 기준값과 대조하는 방법. 같은 출처끼리의 대조는 선택 오류를 잡지 못함
  • TOCTOU (Time-of-Check to Time-of-Use) : 확인한 시점과 사용하는 시점 사이에 상태가 바뀌는 경합. 사용 직전에 다시 확인해 좁힘
  • Predicate Pushdown : 행 필터를 데이터를 읽는 단계로 내려 읽는 양을 줄이는 기법. 필터가 읽는 쪽의 값 해석(시간대 등)과 맞아야 함
  • Sustained vs Burst Load : 일시 부하와 상시 부하의 차이. 일회성 백필의 성공이 상시 운영을 보증하지 않음
  • Strangler Fig Migration : 기존 경로를 대상 단위로 조금씩 새 경로로 바꾸는 이관 방식. 대상별로 되돌릴 수 있음

Key takeaways#

  1. 측정이 가설을 뒤집음
    • “ClickHouse INSERT가 느리다”는 첫 의심과 달리 INSERT는 6%
    • 쓰기를 공짜로 만들어도 6%밖에 안 줄어듦
  2. 병목은 한 지점이 아니라 경로일 수 있음
    • 94%는 수신과 변환이 한 줄로 이어진 구조
    • 옵션 튜닝은 약 20%에 그쳤고 페이지 크기 설정은 페이지 수를 바꾸지 못함
  3. 튜닝보다 제거
    • 데이터가 이미 대상이 읽을 수 있는 형식으로 저장소에 있다면 중간 단계를 뺄 수 있는지 먼저 봄
  4. 추상화를 우회하면 그 추상화가 지키던 불변식을 넘겨받음
    • 시간대 해석, 현재 파일 선택, 삭제 행 반영, 스키마 진화
  5. 테이블의 내용은 폴더가 아니라 메타데이터가 정함
    • 폴더를 통째로 읽으면 옛 파일까지 읽힘. $files의 현재 파일만 지정
  6. 첫 실행이 되는 방식이 재실행에서도 되는 것은 아님
    • 첫 적재 달은 삭제 파일 0개, 재실행 달은 132개
    • 시험을 첫 적재로만 했다면 놓칠 차이
  7. 가드는 제일 위험한 실패를 시끄러운 실패로 바꿈
    • 삭제 파일 거부 가드가 쓰기 전에 9초 만에 멈춤
    • 없었다면 행 수 검증도 통과한 채 두 배로 적재될 수 있었음
  8. 대조는 독립된 출처와 해야 함
    • 같은 메타데이터에서 나온 두 값의 일치는 “잘못 고른 파일”을 못 잡음
  9. 이관의 기준은 이상적인 동작이 아니라 기존 동작
    • 새 경로만 엄격하면 데이터는 좋아지지 않고 장애만 생김
    • 정책을 바꾸고 싶으면 이관과 따로, 하류와 합의해서 함
  10. 조용한 변환은 양쪽 경로에 다 있었음
    • 새 경로의 CAST는 -1을 255로, 기존 경로는 설정 하나로 NULL을 ''로
    • 둘 다 오류가 없었음 → 범위 초과는 accurateCast로 시끄럽게, NULL은 기존과 같게
  11. 검증을 통과한 것은 코드가 아니라 그 데이터
    • 데이터 의존 결함은 그 데이터가 있는 대상에서만 드러남
  12. “배포됐다”와 “내 코드가 돈다”는 다름
    • 이미지 태그, 커밋 조상 관계, 경로를 증명하는 로그 한 줄까지 확인
  13. 성능 개선은 병목을 없애지 않고 옮김
    • INSERT 비중 6% → 91%, 그 다음엔 dbt 빌드로. 개선 후 다시 재야 다음 지점이 보임

부록: 진단 SQL#

-- [Trino] 어떤 작업이 삭제 파일을 만들었나
-- summary['키']는 키가 없으면 "Key not present in map" 오류 → element_at 사용
select committed_at, operation,
element_at(summary, 'added-data-files'),
element_at(summary, 'added-delete-files'),
element_at(summary, 'added-position-deletes'),
element_at(summary, 'deleted-data-files'),
element_at(summary, 'removed-delete-files'),
element_at(summary, 'total-delete-files')
from iceberg.<schema>."<table>$snapshots"
order by committed_at;
-- [Trino] 파티션별 파일 구성. content 0 = 데이터, 1 = position delete, 2 = equality delete
select "partition", content, count(*), sum(record_count)
from iceberg.<schema>."<table>$files"
group by 1, 2 order by 1, 2;
-- [ClickHouse] s3 INSERT 집계. query 원문은 출력하지 않음 (키 노출 방지)
select type, exception_code, count(),
sum(query_duration_ms) / 1000,
sum(written_rows),
max(memory_usage),
sum(ProfileEvents['S3ReadRequestsCount']),
sum(ProfileEvents['S3ReadRequestsErrors']),
sum(ProfileEvents['S3ReadRequestsThrottling'])
from system.query_log
where event_time >= '<시작>' and query_kind = 'Insert'
and query like '%<table>__staging%' and query like '%s3(%'
and type != 'QueryStart'
group by type, exception_code;
-- [Trino] non-Nullable 대상 컬럼에 올 NULL 수
select count_if(col_a is null), count_if(col_b is null) from iceberg.<schema>.<table>;
-- [ClickHouse] 기존 경로가 넣은 기본값 수. 위 숫자와 같으면 null_as_default로 바뀐 것
select countIf(col_a = ''), countIf(col_b = 0) from <db>.<table>;
-- [ClickHouse] 새 경로 SELECT와 현재 테이블의 순서 무관 해시
select count(), sum(cityHash64(toString(tuple(*)))) from (<새 경로 SELECT>);
select count(), sum(cityHash64(toString(tuple(<대상 컬럼>)))) from <db>.<table>;
Terminal window
# 배포된 이미지에 커밋이 들어갔는지
helm get values <release> -n <ns> | grep -E '^\s*tag:'
git merge-base --is-ancestor <commit> <tag> && echo included

더 공부할 것#

  • Iceberg Row-Level Deletes : 위치 삭제, 등치 삭제, v3 deletion vector의 차이와 읽기 비용
  • Copy-on-Write vs Merge-on-Read 운영 : 쓰기 빈도와 읽기 비용에 따른 선택과 compaction 주기
  • Trino Spooled Protocol : 결과를 저장소에 나눠 쓰고 병렬로 받는 클라이언트 프로토콜
  • ClickHouse Iceberg Integration : icebergS3()의 버전별 지원 범위와 메타데이터 처리
  • ClickHouse Parallel Parquet Reading : max_insert_threads, max_threads, 파일별 병렬 읽기의 관계
  • ClickHouse Input Format Settings : input_format_null_as_default, input_format_defaults_for_omitted_fields 등 입력 형식별 기본값 처리
  • Apache Arrow Flight : Arrow 컬럼 데이터를 네트워크로 빠르게 전송하는 RPC 프레임워크
  • Object Store Backpressure : 저장소 과부하 때의 503 응답과 재시도 설계
  • Idempotent Pipeline Design : 재실행이 결과와 부수 산출물을 모두 같게 만들도록 설계하는 방법

참고 자료#

[ClickHouse] 경로가 병목일 때: Iceberg Parquet 직접 읽기로 발행 84분 → 3분
https://yjinheon.netlify.app/posts/02de/00-storage/clickhouse-s3-direct-publish/
Author
Datamind
Published at
2026-11-06
License
CC BY-NC-SA 4.0