자주 발생하는 오류
권한 부여 테스트에 실패했거나 권한 관련 작업이 실패하는 경우
*.*(모든 데이터베이스 및 테이블)에 대해 ALTER, CREATE DATABASE, CREATE TABLE, INSERT, SELECT 권한 부여가 필요합니다.
권한 부여 확인은
system.grants를 쿼리하며, 사용자에게 직접 부여된 권한 부여만 확인합니다. ClickHouse 역할을 통해 부여된 권한은 감지되지 않습니다. 자세한 내용은 역할 기반 권한 부여 섹션을 참조하십시오.모든 뮤테이션이 완료될 때까지 기다리는 동안 발생하는 오류
ALTER TABLE ... UPDATE 또는 ALTER TABLE ... DELETE 뮤테이션이 제출되었지만, 커넥터가 모든 레플리카에서 완료되기를 기다리다가 시간 초과되었습니다. 오류의 “initial cause” 부분에는 원래 ClickHouse 오류(보통 코드 341, “Unfinished”)가 포함되는 경우가 많습니다.
다음과 같은 경우 발생할 수 있습니다.
- ClickHouse Cloud 클러스터에 부하가 많이 걸린 경우
- 뮤테이션 실행 중 하나 이상의 노드가 다운된 경우
- 뮤테이션 진행 상황 확인: 대기 중인 뮤테이션을 확인하려면 다음 쿼리를 실행하세요.
- 클러스터 상태 확인: 모든 노드가 정상 상태인지 확인하세요.
- 대기 후 재시도: 클러스터가 정상 상태로 돌아오면 뮤테이션은 결국 완료됩니다. Fivetran이 동기화를 자동으로 다시 시도합니다.
컬럼 불일치 오류
- ClickHouse 테이블에 컬럼이 수동으로 추가되거나 삭제되었습니다.
- 소스의 스키마 변경 사항이 제대로 반영되지 않았습니다.
- Fivetran이 관리하는 테이블은 수동으로 수정하지 마십시오. 모범 사례를 참조하십시오.
- 컬럼을 원래대로 되돌립니다: 해당 컬럼이 어떤 유형이어야 하는지 알고 있다면, 유형 변환 매핑을 참고하여 컬럼을 예상되는 유형으로 다시 변경하십시오.
- 테이블을 다시 동기화합니다: Fivetran dashboard에서 영향을 받은 테이블에 대해 과거 데이터 재동기화를 실행하십시오.
- 삭제 후 다시 생성합니다: 최후의 수단으로 대상 테이블을 삭제하고, 다음 동기화 시 Fivetran이 다시 생성하도록 하십시오.
AST가 너무 큽니다 (코드 168)
mutation_batch_size와 hard_delete_batch_size 값을 낮추세요. 두 설정의 기본값은 모두 1500이며, 200부터 1500 사이의 값을 사용할 수 있습니다.
메모리 한도 초과 / OOM (코드 241)
INSERT 작업에 사용 가능한 메모리보다 더 많은 메모리가 필요합니다. 일반적으로 대규모 초기 동기화, 열이 많은 테이블(wide tables), 또는 동시 batch 작업 중에 발생합니다.
해결 방법:
write_batch_size줄이기: 큰 테이블의 경우 50,000으로 낮춰 보십시오.- 데이터베이스 부하 줄이기: ClickHouse Cloud 서비스의 부하를 확인하여 과부하 상태인지 살펴보십시오.
- ClickHouse Cloud 서비스 확장하기: 더 많은 메모리를 제공할 수 있도록 확장하십시오.
Unexpected EOF / 연결 오류
FAILURE_WITH_TASK가 표시됩니다.
원인:
- Fivetran 트래픽을 허용하도록 IP 액세스 목록이 구성되지 않았습니다.
- Fivetran과 ClickHouse Cloud 간에 일시적인 네트워크 문제가 발생했습니다.
- 손상되었거나 유효하지 않은 원본 데이터로 인해 대상 커넥터가 충돌합니다.
- IP 액세스 목록 확인: ClickHouse Cloud에서 설정 > 보안으로 이동한 다음 Fivetran IP 주소를 추가하거나 모든 위치의 액세스를 허용하십시오.
- 재시도: 최신 커넥터 버전은 EOF 오류를 자동으로 재시도합니다. 간헐적으로 발생하는 오류(하루 1~2회)는 일시적인 문제일 가능성이 높습니다.
- 문제가 지속되면: 오류가 발생한 시간 범위를 포함해 ClickHouse 지원팀에 지원 티켓을 여십시오. 또한 Fivetran 지원팀에 원본 데이터 품질 조사를 요청하십시오.
UInt64 유형을 매핑할 수 없음
LONG을 Int64로 매핑하며, UInt64로는 매핑하지 않습니다. 이 오류는 Fivetran이 관리하는 테이블에서 컬럼 타입을 수동으로 변경했을 때 발생합니다.
해결 방법:
- Fivetran이 관리하는 테이블에서는 컬럼 타입을 수동으로 변경하지 마십시오.
- 복구 방법: 컬럼을 예상 타입(예:
Int64)으로 다시 변경하거나 테이블을 삭제한 후 다시 동기화하십시오. - 사용자 지정 타입의 경우: Fivetran이 관리하는 테이블 위에 materialized view를 생성하십시오.
테이블에 프라이머리 키(primary key)가 없음
ORDER BY가 필요합니다. 소스에 프라이머리 키(primary key)가 없으면 Fivetran이 _fivetran_id를 자동으로 추가합니다. 이 오류는 소스에 PK가 정의되어 있지만 데이터에 해당 키가 없는 드문 경우에 발생합니다.
해결 방법:
- Fivetran 지원팀에 문의하세요. 소스 파이프라인을 조사할 수 있습니다.
- 소스 스키마를 확인하세요: 데이터에 프라이머리 키 컬럼이 포함되어 있는지 확인합니다.
역할 기반 권한 부여 실패
user_name = NULL이고 role_name = 'my_role'이므로, 이 검사에서는 확인되지 않습니다.
해결 방법:
Fivetran 사용자에게 privileges를 직접 부여하십시오:
권장 사항
Fivetran용 전용 ClickHouse 서비스
- Service A (writer): Fivetran 대상 + 기타 수집 도구(ClickPipes, Kafka 커넥터)
- Service B (reader): BI 도구, 대시보드, 애드혹 쿼리
읽기 쿼리 최적화
SharedReplacingMergeTree를 사용합니다. 이는 ClickHouse Cloud에서 제공되는 ReplacingMergeTree 테이블 엔진의 버전입니다. 동일한 프라이머리 키를 가진 중복 행이 존재하는 것은 정상입니다 — 중복 제거는 백그라운드 머지 중 비동기적으로 수행됩니다. 읽기 시점에는 중복 행이 반환되지 않도록 주의해야 합니다. 일부 행은 아직 중복 제거되지 않았을 수 있기 때문입니다.
중복 행을 피하는 가장 간단한 방법은 FINAL 키워드를 사용하는 것입니다. 이 키워드는 읽기 시점에 아직 중복 제거되지 않은 행을 머지하도록 강제합니다:
FINAL 작업은 최적화할 수 있습니다. 예를 들어 WHERE 조건으로 키 컬럼을 필터링할 수 있습니다. 자세한 내용은 ReplacingMergeTree 가이드의 FINAL 성능 섹션을 참조하십시오.
이러한 최적화로도 충분하지 않다면, FINAL을 사용하지 않으면서도 중복을 올바르게 처리할 수 있는 추가 옵션이 있습니다.
- 항상 증가하는 숫자 컬럼을 쿼리하려는 경우,
max(the_column)을 사용할 수 있습니다. - 특정 키에 대해 일부 컬럼의 최신 값을 조회해야 한다면,
argMax(the_column, _fivetran_id)를 사용할 수 있습니다.
Fivetran은 원본 테이블의 프라이머리 키를 ClickHouse의
ORDER BY 절에 그대로 사용합니다. 원본에 PK가 없으면 _fivetran_id(UUID)가 정렬 키가 되는데, ClickHouse는 ORDER BY 컬럼을 기반으로 희소 프라이머리 인덱스(sparse primary index)를 생성하므로 쿼리 성능이 저하될 수 있습니다.
다른 최적화만으로 충분하지 않을 경우 다음을 권장합니다.
- Fivetran 테이블을 원시 스테이징 테이블로 간주하십시오. 분석용으로 직접 쿼리하지 마십시오.
- 여전히 쿼리 성능이 충분하지 않다면, 갱신 가능 구체화 뷰를 사용해 쿼리 패턴에 맞게
ORDER BY를 최적화한 테이블 복사본을 만드십시오. 증분형 materialized view와 달리, 갱신 가능 구체화 뷰는 일정에 따라 전체 쿼리를 다시 실행하므로 Fivetran이 동기화 중 수행하는UPDATE및DELETE작업을 올바르게 처리합니다:
Fivetran이 관리하는 테이블에는 증분형(비갱신형) materialized view를 사용하지 마십시오. Fivetran은 데이터를 동기화 상태로 유지하기 위해
UPDATE 및 DELETE 작업을 수행하므로, 증분형 materialized view는 이러한 변경 사항을 반영하지 못해 오래되었거나 잘못된 데이터를 포함하게 됩니다.Fivetran이 관리하는 테이블을 수동으로 수정하지 마십시오
ALTER TABLE ... MODIFY COLUMN)을 적용하지 마십시오. connector는 자신이 생성한 스키마를 전제로 동작합니다. 수동 변경은 유형 매핑 오류와 스키마 불일치로 인한 실패를 초래할 수 있습니다.
사용자 지정 변환에는 materialized view를 사용하십시오.
디버깅 작업
- 서버 측 문제는 ClickHouse
system.query_log에서 확인하세요. - 클라이언트 측 문제는 Fivetran에 도움을 요청하세요.