Skip to main content
ABS ClickPipe는 Azure Blob Storage의 데이터를 ClickHouse Cloud로 수집할 수 있는 완전관리형의 복원력 높은 방식을 제공합니다. 일회성 및 지속적인 수집을 모두 지원하며, 정확히 한 번 처리 의미 체계를 보장합니다. ABS ClickPipes는 ClickPipes UI를 통해 수동으로 배포하고 관리할 수 있으며, OpenAPI와 Terraform을 사용해 프로그래밍 방식으로도 배포하고 관리할 수 있습니다.

​
지원 포맷

​
기능

​
일회성 수집

ABS ClickPipe는 지정된 컨테이너에서 패턴과 일치하는 모든 파일을 단일 배치 작업으로 ClickHouse 대상 테이블에 로드합니다. 수집 작업이 완료되면 ClickPipe가 자동으로 중지됩니다. 이 일회성 수집 모드는 정확히 한 번 처리 의미 체계를 제공하므로 각 파일이 중복 없이 안정적으로 처리됩니다.

​
지속적인 수집

지속적인 수집이 활성화되면 ClickPipes는 지정된 경로에서 데이터를 계속 수집합니다. 수집 순서를 결정할 때 ABS ClickPipe는 파일에 암묵적으로 적용되는 사전식 순서를 따릅니다.

​
사전식 순서

ABS ClickPipe는 파일이 컨테이너에 사전식 순서로 추가된다고 가정하고, 이 암묵적인 순서를 기준으로 파일을 순차적으로 수집합니다. 즉, 새 파일은 마지막으로 수집된 파일보다 사전식으로 반드시 더 뒤에 있어야 합니다. 예를 들어 file1, file2, file3라는 이름의 파일은 순차적으로 수집되지만, 컨테이너에 새 file 0이 추가되면 파일 이름이 마지막으로 수집된 파일보다 사전식으로 더 뒤에 있지 않으므로 무시됩니다. 이 모드에서 ABS ClickPipe는 지정된 경로의 모든 파일을 초기 적재한 다음, 구성 가능한 인터벌(기본값: 30초)로 새 파일을 폴링합니다. 특정 파일 이후부터 지속적인 수집을 시작하려면 Start after를 구성하십시오. ClickPipes는 구성된 값보다 사전식으로 작거나 같은 파일을 건너뛰고, 해당 지점부터 더 새로운 파일을 계속 수집합니다.

​
파일 패턴 매칭

객체 스토리지 ClickPipes는 파일 패턴 매칭에 POSIX 표준을 따릅니다. 모든 패턴은 대소문자를 구분하며 컨테이너 이름 뒤의 전체 경로를 기준으로 일치합니다. 성능을 높이려면 가능한 한 구체적인 패턴을 사용하세요(예: *.csv 대신 data-2024-*.csv).

​
지원되는 패턴

예시:
  • https://storageaccount.blob.core.windows.net/container/folder/*.csv
  • https://storageaccount.blob.core.windows.net/container/logs/**/data.json
  • https://storageaccount.blob.core.windows.net/container/file-?.parquet
  • https://storageaccount.blob.core.windows.net/container/data-2024-*.csv.gz

​
지원되지 않는 패턴

예시:
  • https://storageaccount.blob.core.windows.net/container/{documents-01,documents-02}.json
  • https://storageaccount.blob.core.windows.net/container/file-{1..100}.csv
  • https://storageaccount.blob.core.windows.net/container/{logs,metrics}/data.parquet

​
정확히 한 번 처리 의미 체계

대규모 데이터셋을 수집할 때는 다양한 유형의 장애가 발생할 수 있으며, 이로 인해 일부만 삽입되거나 데이터가 중복될 수 있습니다. 객체 스토리지 ClickPipes는 삽입 실패에 복원력이 있으며 정확히 한 번 처리 의미 체계를 제공합니다. 이는 임시 “스테이징” 테이블을 사용해 구현됩니다. 데이터는 먼저 스테이징 테이블에 삽입됩니다. 이 삽입 과정에서 문제가 발생하면 스테이징 테이블을 TRUNCATE하고 초기 상태에서 삽입을 다시 시도할 수 있습니다. 삽입이 성공적으로 완료된 경우에만 스테이징 테이블의 파티션이 대상 테이블로 이동됩니다. 이 전략에 관해 더 자세히 알아보려면 이 블로그 게시물을 확인하십시오.

​
가상 컬럼

어떤 파일이 수집되었는지 추적하려면 컬럼 매핑 목록에 _file 가상 컬럼을 추가하십시오. _file 가상 컬럼에는 원본 객체의 파일 이름이 저장되며, 이를 사용해 어떤 파일이 처리되었는지 쿼리할 수 있습니다.

​
액세스 제어

​
권한

ABS ClickPipe는 비공개 컨테이너만 지원합니다. 공개 컨테이너는 지원하지 않습니다. 버킷 정책에서 s3:GetObject 및 s3:ListBucket 액션을 허용해야 합니다.

​
인증

Microsoft Entra ID 인증(Managed Identities 포함)은 현재 지원하지 않습니다.
Azure Blob Storage 인증에는 액세스 키와 공유 액세스 서명(SAS)을 모두 지원하는 connection string을 사용합니다.

​
액세스 키

계정 액세스 키를 사용해 인증하려면 다음 형식의 connection string을 제공하십시오:
스토리지 계정 이름과 액세스 키는 Azure Portal의 Storage Account > Access keys 메뉴에서 확인할 수 있습니다.

​
공유 액세스 서명(SAS)

공유 액세스 서명(SAS)을 사용하여 인증하려면 SAS 토큰이 포함된 connection string을 제공하십시오:
Azure Portal의 스토리지 계정 > 공유 액세스 서명에서 수집할 컨테이너와 blob에 대해 적절한 권한(Read, List)을 선택한 뒤 SAS 토큰을 생성합니다.

​
네트워크 액세스

ABS ClickPipes는 메타데이터 디스커버리와 데이터 수집에 서로 다른 두 개의 네트워크 경로를 사용하며, 각각 ClickPipes 서비스와 ClickHouse Cloud 서비스가 해당됩니다. 추가 네트워크 보안 계층을 구성하려는 경우(예: 컴플라이언스 요구 사항), 두 경로 모두에 대해 네트워크 액세스를 구성해야 합니다.
Azure Blob Storage 컨테이너가 ClickHouse Cloud 서비스와 동일한 Azure 리전에 있으면 IP 기반 액세스 제어는 작동하지 않습니다. 두 서비스가 동일한 리전에 있으면 트래픽은 퍼블릭 인터넷이 아니라 Azure 내부 네트워크를 통해 라우팅됩니다.
  • IP 기반 액세스 제어의 경우, Azure Storage 방화벽의 IP 네트워크 규칙에서 여기에 나열된 ClickPipes 서비스 리전의 고정 IP와 ClickHouse Cloud 서비스의 고정 IP를 모두 허용해야 합니다. ClickHouse Cloud 리전의 고정 IP를 확인하려면 터미널을 열고 다음을 실행하십시오:

​
고급 설정

ClickPipes는 대부분의 사용 사례 요구 사항을 충족하는 적절한 기본값을 제공합니다. 사용 사례에 추가적인 세부 조정이 필요하다면 다음 설정을 조정할 수 있습니다.

​
스케일링

객체 스토리지 ClickPipes는 설정된 수직 자동 스케일링 설정에 따라 결정되는 ClickHouse 서비스의 최소 크기를 기준으로 스케일링됩니다. ClickPipe 크기는 파이프 생성 시 결정됩니다. 이후 ClickHouse 서비스 설정을 변경해도 ClickPipe 크기에는 영향을 주지 않습니다. 대규모 수집 작업의 처리량을 높이려면 ClickPipe를 생성하기 전에 ClickHouse 서비스를 스케일링하는 것이 좋습니다.

​
알려진 제한 사항

​
파일 크기

ClickPipes는 크기가 10GB 이하인 객체만 수집합니다. 파일이 10GB를 초과하면 오류가 ClickPipes 전용 오류 테이블에 추가됩니다.

​
지연 시간

파일이 100,000개를 넘는 컨테이너에서는 Azure Blob Storage LIST 작업으로 인해 새 파일을 감지할 때 기본 폴링 간격 외에 추가 지연 시간이 발생합니다:
  • < 100k files: ~30초(기본 폴링 간격)
  • 100k files: ~40-45초
  • 250k files: ~55-70초
  • 500k+ files: 90초를 초과할 수 있습니다
지속적인 수집의 경우, ClickPipes는 마지막으로 수집한 파일보다 사전식 순서상 뒤에 있는 새 파일을 식별하기 위해 컨테이너를 스캔해야 합니다. 목록 조회 작업당 파일 수를 줄일 수 있도록 파일을 더 작은 컨테이너로 나누거나 계층형 디렉터리 구조를 사용하는 것을 권장합니다.

​
뷰 지원

대상 테이블의 materialized view도 지원합니다. ClickPipes는 대상 테이블뿐만 아니라, 이에 종속된 모든 materialized view에 대해서도 스테이징 테이블을 생성합니다. 구체화되지 않은 뷰에 대해서는 스테이징 테이블을 생성하지 않습니다. 즉, 하나 이상의 다운스트림 materialized view가 있는 대상 테이블이 있다면, 해당 materialized view는 대상 테이블의 데이터를 뷰를 거쳐 조회하지 않아야 합니다. 그렇지 않으면 materialized view에서 일부 데이터가 누락될 수 있습니다.

​
의존성

ClickPipe가 Running 상태인 동안 대상 테이블, 해당 materialized view(materialized view)(연쇄 materialized view 포함), 또는 materialized view의 대상 테이블을 변경하면 재시도 가능한 오류가 발생합니다. 이러한 의존성의 스키마를 변경하려면 ClickPipe를 일시 중지한 후 변경을 적용하고 다시 재개해야 합니다.
마지막 수정일 2026년 8월 14일