Skip to main content
SeaweedFS 카탈로그 통합은 Iceberg 테이블에서만 지원됩니다.
ClickHouse는 여러 카탈로그(Unity, Glue, REST, Polaris 등)와의 통합을 지원합니다. 이 가이드에서는 ClickHouse와 SeaweedFS 카탈로그를 사용하여 데이터를 쿼리하는 방법을 안내합니다. SeaweedFS는 S3 호환 게이트웨이를 제공하는 오픈 소스 분산 파일 및 객체 저장소입니다. S3 Table Buckets는 Iceberg 배포에 필요한 두 구성 요소를 모두 제공합니다. 내장된 Iceberg REST 카탈로그는 테이블 메타데이터를 제공하며, 테이블 버킷은 동일한 S3 엔드포인트에서 테이블 데이터를 Parquet 파일로 저장합니다.
  • 단일 서비스 - 별도의 메타데이터 데이터베이스 없이 하나의 프로세스가 카탈로그 메타데이터와 Parquet 데이터를 제공합니다.
  • Iceberg REST 카탈로그 사양을 준수하는 REST API
  • 서버 측 유지 관리 - 외부 유지 관리 서비스 없이 Parquet 압축 및 스냅샷 만료를 자동으로 수행합니다.
이 기능은 실험적 기능이므로 다음을 사용하여 활성화해야 합니다. SET allow_experimental_database_iceberg = 1;

로컬 개발 환경 설정

로컬 개발 및 테스트 환경에서는 Docker Compose를 사용하여 SeaweedFS와 ClickHouse를 실행할 수 있습니다. 이 방식은 학습, 프로토타이핑 및 개발 환경에 적합합니다.

사전 요구 사항

  1. Docker 및 Docker Compose: Docker가 설치되어 실행 중이어야 합니다.
  2. 버전: SeaweedFS 4.42 이상, ClickHouse 26.8 이상(25.8 이상 버전에서는 읽기 및 삽입이 가능하지만, 카탈로그를 통한 테이블 생성에는 26.8 이상이 필요합니다)
  3. PyIceberg가 포함된 Python(선택 사항): 아래에서 샘플 데이터를 시드하는 데 사용됩니다.

로컬 SeaweedFS 카탈로그 설정

1단계: 예시를 실행할 새 폴더를 만든 후, S3 게이트웨이와 카탈로그의 자격 증명이 포함된 s3config.json 파일을 만드십시오:
2단계: 다음 구성으로 docker-compose.yml 파일을 생성합니다.
mini 명령은 전체 SeaweedFS 스택을 단일 컨테이너에서 시작합니다. -tableBucket=analytics 플래그는 Iceberg 웨어하우스로 사용될 analytics라는 이름의 S3 Tables 버킷을 미리 생성합니다. 3단계: 다음 명령을 실행하여 서비스를 시작하세요:

샘플 데이터 시드

카탈로그은 처음에는 비어 있습니다. PyIceberg(pip install pyiceberg pyarrow)를 사용하여 테이블을 만들고 몇 개의 행을 추가합니다:

로컬 SeaweedFS 카탈로그에 연결

ClickHouse 컨테이너에 연결합니다:
그런 다음 SeaweedFS 카탈로그에 연결할 데이터베이스 연결을 생성합니다:
엔진 인수에는 ClickHouse가 테이블 데이터를 읽는 데 사용하는 S3 자격 증명이 포함되며, catalog_credentialoauth_server_uri는 OAuth2 클라이언트 자격 증명 흐름을 통해 카탈로그 자체를 인증합니다. SeaweedFS에서는 두 경우에 동일한 액세스 키와 시크릿 키를 사용할 수 있습니다.

ClickHouse를 사용하여 SeaweedFS 카탈로그 테이블 쿼리하기

연결이 설정되었으므로 이제 SeaweedFS 카탈로그를 통해 쿼리할 수 있습니다. 예시:
백틱 필요ClickHouse는 네임스페이스를 하나만 지원하므로 백틱이 필요합니다.
테이블을 쿼리하려면:

ClickHouse에서 테이블 생성 및 데이터 쓰기

SeaweedFS 카탈로그에서 테이블을 생성하고 ClickHouse에서 직접 데이터를 쓸 수도 있습니다:
IcebergS3 엔진 절은 새 테이블의 스토리지 경로를 지정하고, write_full_path_in_iceberg_metadata는 ClickHouse가 전체 테이블 위치를 카탈로그에 등록하도록 합니다.
카탈로그를 통해 테이블을 생성하려면 ClickHouse 26.8 이상이 필요합니다. 26.4~26.7 버전은 네임스페이스를 등록하기 전에 테이블 파일을 작성하므로, 네임스페이스가 카탈로그에 이미 존재하지 않으면 SeaweedFS가 이를 거부합니다. 26.4 이전 버전은 성공한 것처럼 보이지만, 테이블 파일이 카탈로그에 등록되지 않은 채 객체 스토리지에 작성됩니다.
ClickHouse가 삽입을 커밋하면 SeaweedFS 카탈로그는 실험적 writer가 아직 생성하지 못하는 메타데이터를 보완합니다. 매니페스트에서 누락된 field ID를 채우고, 버킷 기준 파일 경로를 절대 위치로 재작성하며, 테이블에 기본 이름 매핑을 기록합니다. 그러면 PyIceberg 및 Spark와 같은 엄격한 reader도 ClickHouse가 작성한 행을 읽을 수 있습니다. 이를 위해서는 SeaweedFS 4.42 이상이 필요합니다.

데이터 레이크의 데이터를 ClickHouse로 로드하기

SeaweedFS 카탈로그의 데이터를 ClickHouse로 로드하려면 먼저 로컬 ClickHouse 테이블을 생성하십시오:
그런 다음 INSERT INTO SELECT를 사용하여 SeaweedFS 카탈로그 테이블에서 데이터를 삽입합니다:
마지막 수정일 2026년 8월 16일