본문으로 건너뛰기

ClickHouse 데이터 소스 구성

최근 업데이트 2026. 11. 03.

ClickHouse 데이터 소스는 오프라인 동기화를 통해 ClickHouse와 플랫폼의 기본 스토리지 간에 테이블 데이터를 전송하는 데 사용됩니다. 이 문서에서는 연결 설정, 양방향 소스 및 목적지 설정, 지원하는 필드 타입, 동기화 검증과 워크플로우 스케줄을 설명합니다.

연동 전 준비 사항 및 사용 제한​

지원 버전​

ClickHouse 24.0 이상 버전.

준비 사항​

설정을 시작하기 전에 다음 사항을 확인하십시오.

  • ClickHouse → 기본 스토리지 및 기본 스토리지 → ClickHouse를 지원합니다. 이 계획에서는 ClickHouse와 다른 외부 데이터 소스 간의 직접 전송을 지원하지 않습니다.
  • ClickHouse의 서비스 주소/IP, 포트, 데이터베이스 이름, 사용자 이름 및 비밀번호를 준비합니다. 플랫폼 실행 환경에서 해당 서비스에 접근할 수 있어야 합니다. 네트워크 접근 제한이 있으면 플랫폼 서버의 실제 아웃바운드 주소와 허용된 접근 범위를 확인하십시오.
  • 접근 계정에는 데이터베이스에 접근하고 선택한 테이블의 메타데이터를 조회할 권한이 필요합니다. 소스 테이블을 읽으려면 읽기 권한이, 타겟 테이블에 쓰려면 해당 쓰기 권한이 필요합니다. 분산 테이블을 사용하는 경우 해당 클러스터 및 샤딩 정보도 가져올 수 있어야 합니다.
  • 타겟 테이블을 미리 준비하고 필드 타입, NULL 제약 조건 및 파티션 정의를 확인합니다. 기본 스토리지의 타겟 테이블 생성 방법은 워크스페이스 테이블 생성 및 관리를 참조하십시오. ClickHouse 타겟 테이블은 해당 데이터베이스에 미리 생성해야 합니다.
  • 테이블 선택기에 표시되는 사용 가능한 테이블을 기준으로 합니다. Aggregating 계열 엔진 테이블과 구체화 뷰는 일반 선택 가능한 테이블로 사용하지 않습니다. ClickHouse에서 지원하는 모든 엔진이나 타입을 이 계획에서 동기화할 수 있다고 간주하지 마십시오.
환경 설정 방식설정 요구 사항
환경 구분 없음개발 환경과 운영 환경에서 하나의 연결 및 자격 증명 설정을 공유
독립 환경 설정개발 환경과 운영 환경을 각각 설정. 두 설정 모두 계획에서 선택한 데이터베이스와 테이블에 접근할 수 있어야 함

데이터 미리보기는 개발 환경 설정을 사용하고 수동 실행은 운영 환경 설정을 사용합니다. 두 설정의 서비스 주소, 데이터베이스 및 테이블 권한, 네트워크 접근을 각각 확인하십시오. 비밀번호는 안전한 방법으로 전달하고 스크린샷, 로그 또는 공개 문서에 자격 증명을 노출하지 마십시오.

ClickHouse 데이터 소스 생성​

  1. 데이터 개발 플랫폼 > 통합 > 데이터 소스로 이동하여 + 데이터 소스를 클릭합니다.
  2. ClickHouse를 선택하고 다음을 클릭한 후 데이터 소스 이름과 비고를 입력합니다.
  3. 환경 구분 없음 또는 독립 환경 설정을 선택합니다. 독립 환경 설정에서는 개발 환경과 운영 환경의 정보를 각각 입력해야 합니다.
  4. 다음 연결 파라미터를 입력합니다. 연결 테스트에서 테스트를 클릭하고 테스트를 통과했는지 확인한 후 완료를 클릭합니다.
ClickHouse 서비스 주소, 포트 및 접근 자격 증명 설정
구성 항목설명
데이터 소스 이름현재 공간에서 이 연결을 식별하는 이름. 생성 후 수정할 수 없음
비고선택 사항. 연결 용도를 설명할 수 있음
서비스 주소/IPClickHouse 서비스 호스트 주소. 여러 주소는 쉼표로 구분하며 포트는 아래에 별도로 입력. 주소에 포트를 중복으로 입력하지 않음
포트ClickHouse에 접근하는 서비스 포트. 관리자에게 확인
데이터베이스 이름ClickHouse에 이미 생성되어 있고 접근 계정에 접근 권한이 있는 데이터베이스
사용자 이름이번 읽기 또는 쓰기에 필요한 권한을 가진 계정
비밀번호사용자 이름에 해당하는 비밀번호
고급 설정필요에 따라 JSON 형식의 확장 설정을 입력. 추가 설정이 필요하지 않으면 비워 둘 수 있음

연결 테스트를 통과한 후에도 동기화 계획에서 데이터베이스와 테이블을 불러오고 소스 데이터를 미리 본 다음 실행하여 실제 테이블 권한과 읽기 및 쓰기 결과를 검증해야 합니다. 비밀번호를 교체하거나 데이터베이스 권한을 변경한 후에는 연결 및 관련 계획을 다시 검증하십시오.

데이터 소스 설정​

ClickHouse 데이터를 기본 스토리지로 읽기​

  1. 데이터 개발 플랫폼 > 통합 > 오프라인 동기화로 이동하여 + 통합 방안을 클릭합니다.
  2. 데이터 소스에서 ClickHouse와 생성한 데이터 소스를 선택합니다.
  3. 데이터 가져오기 방식을 선택하고 전체 테이블 읽기 또는 사용자 정의 쿼리로 소스를 설정합니다.
  4. 데이터 미리보기를 클릭하여 소스 필드, 실제 값 및 읽기 범위를 확인합니다.
  5. 데이터 목적지에서 플랫폼의 기본 스토리지를 선택한 후 타겟 워크스페이스 테이블을 선택하고 타겟 파티션 및 쓰기 모드를 설정합니다.
데이터 가져오기 방식설정 방법
전체 테이블데이터베이스와 데이터 테이블을 선택. 일부 데이터만 읽으려면 데이터 필터링을 켜고 필터 조건을 입력
사용자 정의 쿼리동기화할 필드를 반환하는 읽기 전용 SQL 쿼리를 입력하고 필터 조건을 쿼리에 포함. 이 방식에서는 전체 테이블 방식의 데이터베이스, 데이터 테이블 선택 항목이나 데이터 필터링을 별도로 설정하지 않음

전체 테이블 방식의 데이터 필터링에는 WHERE status = 'active'와 같이 WHERE가 포함된 전체 조건을 입력하고 전체 SELECT 쿼리는 입력하지 마십시오. 사용자 정의 쿼리에서는 접근하는 데이터베이스를 확인하고 필요하면 SQL에 데이터베이스 이름과 테이블 이름을 명시해야 합니다. 반환 필드의 이름이 명확하고 타입을 인식할 수 있는지도 확인하십시오.

기본 스토리지 목적지 설정 항목설명
타겟 테이블이번 데이터를 받을 기본 스토리지의 워크스페이스 테이블. 테이블이 없으면 먼저 테이블로 이동하여 생성
파티션 정보타겟이 파티션 테이블이면 타겟 테이블 요구 사항에 따라 파티션 값을 입력. 공간 파라미터를 사용하여 실행 시 파티션을 설정할 수 있음
쓰기 모드타겟 데이터 보존 요구 사항에 따라 새 데이터 삽입 또는 덮어쓰기를 선택하고 실행 전에 타겟 테이블, 타겟 파티션 및 데이터 보존 요구 사항을 다시 확인

데이터 소스, 데이터베이스, 데이터 테이블 또는 데이터 가져오기 방식을 변경한 후에는 읽기 범위, 미리보기 결과 및 필드 매핑을 다시 확인하십시오. 소스 테이블 구조나 쿼리 결과가 변경된 경우에도 필드를 다시 분석하고 매핑을 확인해야 합니다.

데이터 목적지 설정​

기본 스토리지 데이터를 ClickHouse에 쓰기​

데이터 소스에서 기본 스토리지의 소스 테이블을 설정합니다. 데이터 목적지에서 ClickHouse와 생성한 데이터 소스를 선택한 후 ClickHouse의 타겟 데이터베이스와 데이터 테이블을 선택합니다.

기존 계획의 ClickHouse 쓰기 대상 테이블, 샤딩 필드 및 배치 건수
구성 항목설명
데이터 소스 이름현재 공간에 생성된 ClickHouse 데이터 소스. 아직 생성하지 않은 경우 데이터 소스 관리에서 설정할 수 있음
데이터베이스 이름이번에 데이터를 쓸 ClickHouse 데이터베이스
데이터 테이블 이름ClickHouse에 미리 준비되어 있고 접근 계정에 쓰기 권한이 있는 타겟 테이블
샤딩 필드 사용아래 샤딩 조건을 충족하면 켤 수 있음. 켜기 전에 필드 매핑에 해당 타겟 샤딩 필드가 포함되어야 함
쓰기 모드새 데이터 삽입만 지원하며 타겟 테이블에 데이터를 추가. 재실행 전에 중복 레코드가 생성될 수 있는지 평가
일괄 건수고급 설정에 위치(화면의 배치 건수 항목). 화면 기본값은 20000이며 설정 범위는 10000–100000

ClickHouse 목적지는 덮어쓰기나 업데이트 삽입 모드를 제공하지 않습니다. 동일한 소스 범위로 재시도해야 하는 경우 이전 실행 결과와 타겟 데이터를 먼저 확인하여 중복 추가를 방지하십시오.

샤딩 필드 사용​

샤딩 기능은 조건에 맞는 분산 테이블에 데이터를 쓰는 데 사용되며 다음 조건을 모두 충족해야 합니다.

  • 타겟 테이블이 Distributed 엔진 테이블이고 해당 클러스터에서 internal_replication이 활성화되어 있어야 합니다.
  • 플랫폼에서 타겟 테이블이 사용하는 샤딩 필드를 인식할 수 있어야 합니다. 임의의 샤딩 표현식을 직접 선택할 수 있는 필드로 간주할 수 없습니다.
  • 필드 매핑에 해당 타겟 샤딩 필드가 포함되어 있고 유효한 소스 대응 관계가 설정되어 있어야 합니다.

조건을 충족하면 샤딩 필드 사용을 켭니다. 스위치를 사용할 수 없으면 타겟 테이블, 클러스터 설정 및 필드 매핑을 확인하십시오. 타겟 데이터베이스나 테이블을 변경하거나 샤딩 필드 매핑을 제거한 후에는 이 설정을 다시 확인해야 합니다.

필드 매핑 및 지원하는 필드 타입​

소스와 목적지 설정을 완료한 후 필드 매핑에서 소스 필드와 타겟 필드의 대응 관계를 설정합니다. 필드를 개별적으로 선택하거나 동일 이름 매핑 또는 동일 행 매핑을 사용한 후 항목별로 확인할 수 있습니다. 하나의 타겟 필드는 하나의 소스 필드에만 대응할 수 있습니다.

기존 ClickHouse 계획의 필드 대응 관계 예시

그림은 기존 계획의 필드 대응 관계를 보여 주며, 현재 연결, 필드 분석 및 실제 동기화 결과의 검증을 대신할 수 없습니다.

읽기를 지원하는 필드 타입​

ClickHouse를 데이터 소스로 사용할 때 올바르게 분석할 수 있는 다음 기본 타입을 지원합니다. 파라미터 또는 래퍼가 있는 타입은 아래 사용 제한도 충족해야 합니다.

타입 분류지원하는 ClickHouse 필드 타입
불리언Bool, boolean
정수Int8, UInt8, Int16, UInt16, Int32, UInt32, Int64, UInt64, Int128, UInt128, Int256, UInt256
부동 소수점Float32, Float64
고정 소수점Decimal, Decimal32, Decimal64, Decimal128, Decimal256
문자열 및 열거형String, FixedString, Enum, Enum8, Enum16
날짜 및 시간Date, DateTime, DateTime32, DateTime64
지리 타입Point, Ring, Polygon
간격IntervalYear, IntervalQuarter, IntervalMonth, IntervalWeek, IntervalDay, IntervalHour, IntervalMinute, IntervalSecond
복합 타입Array, Map. 전체 구조 확인 필요

Nested, UUID, IPv4, IPv6, Date32, MultiPolygon 등 목록에 없는 타입과 기타 인식되지 않는 타입은 지원하지 않습니다. Tuple, Nullable(T), LowCardinality(T)의 제한은 아래를 참조하십시오. 이름만으로 지원 여부를 판단할 수 없습니다.

쓰기를 지원하는 필드 타입​

ClickHouse를 데이터 목적지로 사용할 때 지원하는 기본 타입과 지원하지 않는 타입은 위 표와 동일합니다. 타겟 테이블은 미리 생성해야 하며, 필드의 파라미터, 전체 구조 및 제약 조건은 실제 쓰기 요구 사항을 충족해야 합니다.

MATERIALIZED, EPHEMERAL, ALIAS 등 읽기 전용 생성 필드는 일반 쓰기 필드로 설정할 수 없습니다. 이는 필드 종류에 대한 제한이며 필드 자체의 데이터 타입과는 무관합니다.

필드 타입 사용 제한​

타입 또는 상황지원 조건 및 제한
정수, 고정 소수점, 고정 길이 문자열 및 열거형전체 값 범위, 정밀도, 소수 자릿수, 길이 및 열거형 허용 값을 확인. 기본 타입 목록에 포함되어 있어도 모든 필드 정의와 실제 값에 적용되는 것은 아님
파라미터가 있는 타입전체 테이블과 사용자 정의 쿼리의 필드 분석 결과가 다를 수 있음. 숫자 길이 또는 정밀도 파라미터는 전체 정의를 확인해야 하며, 시간대 텍스트가 포함된 시간 타입과 허용 값이 있는 열거형은 현재 데이터 가져오기 방식에서 올바르게 분석되는지 확인 필요
Nullable(T)가장 바깥쪽 래퍼만 내부 타입으로 인식할 수 있음. 내부 타입도 지원되어야 하며 타겟 필드의 NULL 제약 조건을 확인해야 함. 모든 중첩 래퍼 형식에 적용할 수는 없음
LowCardinality(T)내부 타입의 자동 인식을 보장하지 않음. 현재 필드 분석 결과와 사용 가능 상태를 확인해야 하며, 내부 타입이 지원된다는 이유만으로 해당 래퍼 타입을 사용할 수 있다고 판단할 수 없음
Tuple(...)파라미터가 있는 Tuple의 올바른 인식을 보장하지 않음. 현재의 전체 필드 정의와 분석 결과를 기준으로 하며, 조건 없이 지원하는 타입으로 나열하지 않음
Array, Map 및 중첩 구조전체 요소 및 키-값 정의와 NULL 제약 조건을 확인. 최상위 타입이 지원되어도 모든 내부 구조가 지원되는 것은 아님

ClickHouse 타입 정의는 ClickHouse 공식 데이터 타입 설명을 참조하십시오. 데이터베이스가 지원하는 모든 타입을 이 계획에서 지원하는 것은 아닙니다. 소스 또는 타겟 테이블의 구조가 변경되면 필드를 다시 분석하고 필드 대응 관계를 확인하십시오. 데이터 미리보기에 표시되어도 동기화 검증을 대신할 수 없습니다.

저장, 검증 및 스케줄링​

기본 정보 및 동기화 검증​

  1. 소스 테이블 또는 쿼리, 필터 범위, 타겟 테이블 및 파티션, 쓰기 모드 및 필드 매핑을 확인합니다. 먼저 소스의 데이터 미리보기를 사용하여 필드와 샘플 값을 확인합니다.
  2. 계획 이름, 담당자, 동기화 속도 및 비고를 입력하고 저장을 클릭합니다. 계획 이름은 저장 후 수정할 수 없습니다.
  3. 수동 실행을 클릭하고 팝업의 안내에 따라 실행 모드를 선택한 후 이번 파라미터 값을 확인하고 실행을 시작합니다. 수동 실행은 운영 환경 설정을 사용합니다. 실행 모드는 개발 환경과 운영 환경을 전환하는 용도가 아닙니다.
  4. 수동 실행 기록에서 상태와 로그를 확인합니다. 작업이 성공하면 타겟 테이블에서 데이터 양, 필드 대응 관계, 숫자, 시간, 복합 타입 및 NULL 등의 샘플을 확인합니다.

독립 환경 설정에서 개발 환경의 데이터를 불러오거나 미리 볼 수 있다고 해서 운영 환경의 자격 증명 및 읽기·쓰기 권한도 준비된 것은 아닙니다. 최초 실행 전에 두 설정의 데이터베이스, 테이블, 파티션 및 파라미터를 각각 확인하십시오. 기본 스토리지에 덮어쓸 때는 타겟 범위를 확인하고 ClickHouse에 추가로 쓸 때는 재시도와 반복 실행의 영향을 평가해야 합니다.

작업 플로우에 연결​

수동 검증을 통과한 후 계획을 작업 플로우에 연결하여 스케줄링 주기에 따라 실행할 수 있습니다.

  1. 저장된 계획을 열고 작업 플로우에 연결을 클릭하여 타겟 작업 플로우를 선택합니다. 해당 작업 플로우가 없으면 선택기에서 새로 생성하거나 작업 플로우 생성을 참조하십시오. 목록에 타겟 작업 플로우가 표시되지 않으면 새로고침한 후 다시 선택할 수 있습니다.
  2. 노드 이름, 실행 모드, 담당자 등의 정보를 입력하고 노드 생성 및 연결을 클릭하여 현재 계획과 연결된 오프라인 동기화 계획 노드를 생성합니다.
  3. 작업 플로우로 이동을 클릭하고 노드 및 상하위 종속성을 확인한 후 스케줄링에 사용되는 데이터베이스, 테이블, 파티션 및 공간 파라미터를 확인합니다.
  4. 작업 플로우 스케줄 설정을 완료하고 저장한 후 작업 플로우를 배포합니다. 연결에 성공했다고 해서 노드가 이미 배포되어 운영 중인 것은 아닙니다.

계획을 작업 플로우에 연결한 후에는 계획 상세 페이지에서 더 이상 수동 실행하지 않습니다. 작업 플로우에서 해당 노드를 실행하고 검증하십시오.

작업 플로우 연결 해제​

  • 작업 플로우가 아직 배포되지 않은 경우 작업 플로우의 개발 모드에서 해당 오프라인 동기화 계획 노드를 삭제하면 됩니다.
  • 작업 플로우가 이미 배포된 경우 먼저 개발 모드에서 해당 노드를 삭제하고 작업 플로우를 다시 배포해야 운영 환경에서 해당 노드의 연결이 해제됩니다.

자주 묻는 질문​

증상확인 항목
연결 테스트 실패서비스 주소, 별도로 입력한 포트, 데이터베이스, 계정 및 비밀번호, 플랫폼 서버의 네트워크 접근 범위를 확인
연결은 가능하지만 테이블을 찾을 수 없거나 미리 볼 수 없음데이터베이스 및 테이블 이름, 메타데이터 및 읽기 권한, 테이블 엔진을 선택할 수 있는지 확인. 사용자 정의 쿼리는 SQL의 데이터베이스 및 필드 타입도 확인
샤딩 스위치를 사용할 수 없음Distributed 테이블, 클러스터의 internal_replication, 인식 가능한 샤딩 필드 및 매핑에 해당 타겟 필드가 포함되어 있는지 확인
미리보기는 정상이지만 실행 실패운영 환경 자격 증명, 타겟 쓰기 권한, 데이터베이스와 테이블 및 파티션, 파라미터 및 실제 실행 로그를 확인
반복 실행 후 중복 레코드 발생추가 쓰기 범위와 이전 실행 결과를 확인하여 동일한 데이터 배치를 중복으로 읽고 썼는지 확인
이 문서가 도움이 되었나요?