Google Cloud Storage를 ClickHouse Cloud에 통합하기

객체 스토리지를 ClickHouse Cloud에 원활하게 연결합니다.

GCS ClickPipe는 Google Cloud Storage(GCS)에서 데이터를 수집할 수 있는 완전 관리형의 복원력이 뛰어난 방식을 제공합니다. 일회성 수집과 지속적인 수집을 모두 지원하며, 정확히 한 번 처리 의미 체계를 보장합니다.

GCS ClickPipes는 ClickPipes UI를 사용해 수동으로 배포 및 관리할 수 있으며, OpenAPI와 Terraform을 사용해 프로그래밍 방식으로도 배포 및 관리할 수 있습니다.

​

지원 포맷

• JSON
• CSV
• TSV
• Parquet
• Avro

​

기능

​

일회성 수집

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

​

지속적인 수집

지속적인 수집이 활성화되면 ClickPipes는 지정된 경로에서 데이터를 지속적으로 수집합니다. 수집 순서를 결정할 때 GCS ClickPipe는 기본적으로 파일 이름의 암묵적인 사전식 순서를 따릅니다. 또한 버킷에 대한 알림을 제공하도록 구성된 Google Cloud Pub/Sub subscription을 사용해 파일을 임의의 순서로 수집하도록 구성할 수도 있습니다.

​

사전식 순서

GCS ClickPipe는 파일이 버킷에 사전식 순서로 추가된다고 가정하며, 이 묵시적인 순서에 따라 파일을 순차적으로 수집합니다. 즉, 새 파일은 마지막으로 수집된 파일보다 사전식으로 반드시 더 뒤에 와야 합니다. 예를 들어 file1, file2, file3라는 이름의 파일은 순차적으로 수집되지만, 새 file 0이 버킷에 추가되면 파일 이름이 마지막으로 수집된 파일보다 사전식으로 뒤에 있지 않으므로 무시됩니다.

이 모드에서 GCS ClickPipe는 지정된 경로의 모든 파일을 초기 적재한 후, 구성 가능한 인터벌로 새 파일을 폴링합니다(기본값: 30초). 특정 파일 이후부터 지속적인 수집을 시작하려면 Start after를 구성하십시오. ClickPipes는 구성된 값보다 사전식으로 작거나 같은 파일을 건너뛰고, 해당 지점부터 더 새로운 파일을 계속 수집합니다.

​

임의의 순서

단계별 지침은 지속적인 수집을 위한 unordered mode 구성을 참조하세요.

버킷에서 알림을 받는 Google Cloud Pub/Sub subscription을 설정하면, 암묵적인 순서가 없는 파일도 GCS ClickPipe에서 수집하도록 구성할 수 있습니다. 이렇게 하면 ClickPipes가 객체 생성 이벤트를 수신하여 파일 이름 규칙과 관계없이 새 파일을 수집할 수 있습니다.

공개 버킷에서는 unordered mode가 지원되지 않습니다. 이 기능을 사용하려면 Service Account 인증과 버킷에 연결된 Google Cloud Pub/Sub subscription이 필요합니다.

이 모드에서는 GCS ClickPipe가 선택한 경로의 모든 파일을 초기 적재한 다음, 지정된 경로와 일치하는 Pub/Sub subscription의 OBJECT_FINALIZE 알림을 수신합니다. 이전에 확인한 파일에 대한 메시지, 지정된 경로와 일치하지 않는 파일, 또는 다른 유형의 이벤트는 모두 무시됩니다. subscription을 통해 전달되는 파일만 수집하려면 Skip initial load를 활성화하세요. 활성화하면 ClickPipes는 선택한 경로에 있는 기존 파일의 초기 스캔을 건너뛰고 Pub/Sub subscription을 통해 전달되는 파일만 처리합니다.

​

파일 패턴 매칭

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

​

지원되는 패턴

패턴	설명	예시	일치하는 항목
?	정확히 1개의 문자(/ 제외)와 일치합니다	data-?.csv	data-1.csv, data-a.csv, data-x.csv
*	0개 이상의 문자(/ 제외)와 일치합니다	data-*.csv	data-1.csv, data-001.csv, data-report.csv, data-.csv
** 재귀	0개 이상의 문자(/ 포함)와 일치합니다. 재귀적으로 디렉터리를 순회할 수 있습니다.	logs/**/error.log	logs/error.log, logs/2024/error.log, logs/2024/01/error.log

예시:

• https://bucket.s3.amazonaws.com/folder/*.csv
• https://bucket.s3.amazonaws.com/logs/**/data.json
• https://bucket.s3.amazonaws.com/file-?.parquet
• https://bucket.s3.amazonaws.com/data-2024-*.csv.gz

​

지원되지 않는 패턴

패턴	설명	예시	대안
{abc,def}	중괄호 확장 - 대체 항목 지정	{logs,data}/file.csv	각 경로에 대해 별도의 ClickPipes를 생성하십시오.
{N..M}	숫자 범위 확장	file-{1..100}.csv	file-*.csv 또는 file-?.csv를 사용하십시오.

예시:

• https://bucket.s3.amazonaws.com/{documents-01,documents-02}.json
• https://bucket.s3.amazonaws.com/file-{1..100}.csv
• https://bucket.s3.amazonaws.com/{logs,metrics}/data.parquet

​

정확히 한 번 처리 의미 체계

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

​

가상 컬럼

어떤 파일이 수집되었는지 추적하려면 컬럼 매핑 목록에 _file 가상 컬럼을 포함하세요. _file 가상 컬럼에는 원본 객체의 파일명이 포함되어 있으며, 이를 사용해 어떤 파일이 처리되었는지 쿼리할 수 있습니다.

​

접근 제어

​

권한

GCS ClickPipe는 공개 및 비공개 버킷을 지원합니다. Requester Pays 버킷은 지원하지 않습니다.

​

GCS 버킷

ClickPipes에서 사용하는 서비스 계정에는 버킷 수준에서 다음 작업이 허용되어야 합니다:

• roles/storage.objectViewer

이 역할에는 지정된 버킷의 객체를 ClickPipes가 나열하고 가져올 수 있게 해주는 storage.objects.list 및 `storage.objects.get IAM 권한이 포함됩니다.

​

Pub/Sub subscription

unordered mode를 사용할 때 서비스 계정에는 Pub/Sub subscription에 대해 다음 역할이 있어야 합니다.

• roles/pubsub.subscriber — 메시지를 수신하고 승인하기 위해 필요합니다.
• roles/pubsub.viewer — subscription 메타데이터를 조회하기 위해 필요합니다.

​

인증

​

서비스 계정

Pub/Sub 알림을 사용하는 unordered mode에서는 서비스 계정 인증이 필요합니다. 인증 메서드로 Service Account를 선택하고 서비스 계정 키가 포함된 JSON 파일을 업로드하세요.

​

HMAC 자격 증명

인증에 HMAC keys를 사용하려면 ClickPipe 연결을 설정할 때 인증 방법에서 Credentials를 선택하십시오. 그런 다음 Access key와 Secret key에 각각 액세스 키(예: GOOGTS7C7FUP3AIRVJTE2BCDKINBTES3HC2GY5CBFJDCQ2SYHV6A6XXVTJFSA)와 시크릿 키(예: bGoa+V7g/yqDXvKRqq+JTFn4uQZbPiQJo4pf9RzJ)를 입력하십시오.

HMAC 키가 포함된 서비스 계정을 생성하려면 이 가이드를 따르십시오.

​

네트워크 액세스

GCS ClickPipes는 메타데이터 디스커버리와 데이터 수집에 각각 서로 다른 두 개의 네트워크 경로를 사용합니다. 각각 ClickPipes 서비스와 ClickHouse Cloud 서비스가 사용됩니다. 추가적인 네트워크 보안 계층(예: 컴플라이언스 요구 사항)을 구성하려면 두 경로 모두에 대해 네트워크 액세스를 구성해야 합니다.

• IP 기반 액세스 제어의 경우, GCS 버킷의 IP 필터링 규칙에서 여기에 나열된 ClickPipes 서비스 리전의 고정 IP와 ClickHouse Cloud 서비스의 고정 IP를 모두 허용해야 합니다. 사용 중인 ClickHouse Cloud 리전의 고정 IP를 확인하려면 터미널을 열고 다음 명령을 실행하십시오:

  # <your-region>을 ClickHouse Cloud 리전으로 바꾸십시오
  curl -s https://api.clickhouse.cloud/static-ips.json | jq -r '.gcp[] | select(.region == "<your-region>") | .egress_ips[]'
  

​

고급 설정

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

설정	기본값	설명
Max insert bytes	10GB	단일 삽입 배치에서 처리할 바이트 수입니다.
Max file count	100	단일 삽입 배치에서 처리할 최대 파일 수입니다.
Max threads	auto(3)	파일 처리를 위한 최대 동시 스레드 수입니다.
Max insert threads	1	파일 처리를 위한 최대 동시 삽입 스레드 수입니다.
Min insert block size bytes	1GB	테이블에 삽입할 수 있는 블록의 최소 바이트 크기입니다.
Max download threads	4	최대 동시 다운로드 스레드 수입니다.
Object storage polling interval	30s	ClickHouse 클러스터에 데이터를 삽입하기 전까지의 최대 대기 시간을 설정합니다.
Start after	None	정렬된 지속적인 수집의 경우, 구성된 파일 이름 또는 경로보다 사전식으로 작거나 같은 파일을 건너뜁니다.
Skip initial load	false	비정렬 지속적인 수집의 경우, 기존 파일의 초기 스캔을 건너뛰고 구성된 Pub/Sub subscription의 객체 알림만 처리합니다.
Parallel distributed insert select	2	병렬 분산 insert select 설정입니다.
Parallel view processing	false	attached 상태인 뷰로의 푸시를 순차 처리 대신 동시에 수행할지 여부입니다.
Use cluster function	true	여러 노드에서 파일을 병렬로 처리할지 여부입니다.

​

스케일링

객체 스토리지 ClickPipes는 구성된 수직 자동 스케일링 설정에 따라 결정된 최소 ClickHouse 서비스 크기를 기준으로 스케일링됩니다. ClickPipe의 크기는 파이프를 생성할 때 결정됩니다. 이후 ClickHouse 서비스 설정을 변경해도 ClickPipe 크기에는 영향을 주지 않습니다.

대규모 수집 작업의 처리량을 높이려면 ClickPipe를 생성하기 전에 ClickHouse 서비스를 먼저 스케일링하는 것을 권장합니다.

​

알려진 제한 사항

​

파일 크기

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

​

호환성

GCS ClickPipe는 상호 운용성을 위해 Cloud Storage XML API를 사용하므로, gs:// 대신 https://storage.googleapis.com/ 버킷 접두사를 사용해야 하며 인증에는 HMAC keys를 사용해야 합니다.

​

뷰 지원

대상 테이블의 materialized view도 지원합니다. ClickPipes는 대상 테이블뿐만 아니라, 이에 종속된 모든 materialized view에 대해서도 스테이징 테이블을 생성합니다.

구체화되지 않은 뷰에 대해서는 스테이징 테이블을 생성하지 않습니다. 즉, 대상 테이블에 하나 이상의 하위 materialized view가 있는 경우, 해당 materialized view에서는 대상 테이블의 데이터를 뷰를 통해 조회하지 않도록 해야 합니다. 그렇지 않으면 materialized view에 일부 데이터가 누락될 수 있습니다.