Set up docs MCPClickHouse Cloud를 데이터 카탈로그에 연결하면 오픈 테이블 포맷 테이블에 액세스할 수 있습니다. 데이터 소스 UI에서 연결을 설정할 수 있습니다. SQL로 설정하려면 원하는 SQL Editor에서 DataLakeCatalog 데이터베이스 엔진을 사용하십시오.
연결이 완료되면 선택한 데이터베이스 이름 아래의 SQL 콘솔에 카탈로그 테이블이 표시됩니다. 표준 ClickHouse SQL로 쿼리하고, MergeTree 테이블과 조인하거나, materialized views의 소스로 사용할 수 있습니다.
사전 요구 사항
카탈로그를 연결하기 전에 다음 사항을 확인하십시오.
- 서비스 권한. 데이터 소스 페이지에 액세스하고 카탈로그를 추가하려면
control-plane:service:manage권한이 필요합니다. - 실행 중인 서비스. 서비스가 유휴 상태인 경우 연결하거나 연결된 카탈로그를 보기 전에 데이터 소스 또는 서비스 설정 페이지에서 서비스를 활성화하십시오.
- 카탈로그 자격 증명. 플라이아웃을 열기 전에 카탈로그 유형에 필요한 연결 정보를 준비하십시오. 카탈로그마다 사용하는 필드와 인증 방식이 다릅니다. 아래의 카탈로그 연결 추가를 참조하십시오.
카탈로그 연결하기
데이터 카탈로그 플라이아웃 열기
- 왼쪽 탐색 메뉴에서 데이터 소스를 선택합니다.
- 아직 데이터 소스를 설정하지 않았다면 + 카탈로그 추가를 클릭합니다. 이미 설정한 데이터 소스가 있으면 데이터 소스 추가 > 데이터 레이크 카탈로그 추가를 클릭합니다.
- 데이터 카탈로그 연결 플라이아웃의 카탈로그 선택 드롭다운에서 카탈로그를 선택합니다. 카탈로그가 여러 오픈 테이블 포맷을 지원하는 경우 오픈 테이블 포맷에서 포맷을 선택합니다.
카탈로그 연결을 추가합니다
아래에서 카탈로그를 선택하여 안내와 필수 조건을 확인하십시오. 그런 다음 연결 매개변수와 데이터베이스 이름(SQL 콘솔에서 카탈로그 테이블을 노출하는 ClickHouse 데이터베이스)을 입력하십시오.
AWS Glue Catalog은 Glue Data Catalog에 등록된 Iceberg 테이블을 제공합니다.
연결하기 전에 다음 사항을 확인하십시오.
- ClickHouse 버전이 25.12 이상입니다.
- 대상 리전의 AWS Glue Data Catalog에 Iceberg 테이블이 등록되어 있습니다.
- 액세스 키 인증을 사용하는 경우 Glue 메타데이터와 기본 S3 객체를 읽을 권한이 있는 IAM 사용자 액세스 키가 있습니다.
- IAM 역할 인증(26.2+)을 사용하는 경우 ClickHouse 서비스 역할을 신뢰하도록 설정된 IAM 역할이 있습니다. 역할 신뢰 정책에 Settings → Network security information의 서비스 역할 ARN을 포함하십시오. IAM 정책 예시는 Iceberg 데이터에 안전하게 액세스하기를 참조하십시오.
플라이아웃에서 AWS Region(예: us-west-2)을 입력한 후 인증 방법을 선택하십시오.
액세스 키 인증
- Authentication method에서 AWS Access Key를 선택합니다.
- Access Key ID와 Secret Access Key를 입력합니다.
- Glue 테이블을 제공할 ClickHouse 데이터베이스의 Database name을 입력합니다.
IAM 역할 인증(26.2+)
- Authentication method에서 AWS IAM Role을 선택합니다.
- 플라이아웃 패널에서 **Service role ID (IAM)**를 복사하여 IAM 역할 신뢰 정책에 추가합니다.
- AWS Role ARN과 선택 사항인 AWS Role Session Name을 입력합니다.
- Glue 테이블을 제공할 ClickHouse 데이터베이스의 Database name을 입력합니다.
Databricks 서비스 주체의 OAuth 클라이언트 자격 증명을 사용하여 외부 스토리지 위치를 사용하는 Unity Catalog Iceberg 테이블을 쿼리합니다. 전체 설정 방법은 Unity Catalog 가이드를 참조하십시오.
연결하기 전에 다음 사항을 확인하십시오.
- ClickHouse 버전이 25.12 이상입니다.
- Unity Catalog가 외부 데이터 액세스용으로 구성되어 있습니다.
- OAuth 클라이언트 ID와 시크릿이 있는 Databricks 서비스 주체가 있습니다. 서비스 주체에 쿼리할 테이블에 대한
USE CATALOG,USE SCHEMA,USE EXTERNAL SCHEMA,SELECT권한이 있습니다.
플라이아웃에서 다음을 수행하십시오.
- Databricks 워크스페이스 URL을 입력하십시오(예:
dbc-1234567a-cbde.cloud.databricks.com). - 연결할 Databricks 카탈로그 이름을 입력하십시오(예:
icebench). - 서비스 주체의 OAuth 클라이언트 ID와 클라이언트 시크릿을 입력하십시오.
- Unity Catalog 테이블을 노출하는 ClickHouse 데이터베이스의 데이터베이스 이름을 입력하십시오.
Databricks Personal Access Token(PAT)을 사용하여 외부 스토리지 위치를 사용하는 Unity Catalog Delta Lake 테이블을 쿼리합니다. 전체 설정 방법은 Unity Catalog 가이드를 참조하십시오.
연결하기 전에 다음 사항을 확인하십시오.
- ClickHouse 버전 25.12 이상
- Unity Catalog가 외부 데이터 액세스에 사용하도록 구성되어 있음
- 대상 테이블에 대해 최소
EXTERNAL USE SCHEMA,USE CATALOG,USE SCHEMA,SELECT권한이 있는 Databricks Personal Access Token
플라이아웃에서 다음을 수행하십시오.
- Databricks Workspace URL(예:
dbc-1234567a-cbde.azuredatabricks.net)을 입력합니다. - 연결할 Databricks catalog name을 입력합니다.
- Personal Access Token을 입력합니다.
- Delta 테이블을 노출하는 ClickHouse 데이터베이스의 Database name을 입력합니다.
Iceberg REST 카탈로그 사양을 구현하는 모든 카탈로그에 연결할 수 있습니다. 전체 설정 방법은 REST 카탈로그 가이드를 참조하십시오.
연결하기 전에 다음을 확인하십시오.
- ClickHouse 버전이 25.12 이상입니다.
- ClickHouse Cloud에서 REST 카탈로그 endpoint에 연결할 수 있습니다.
- 카탈로그 구성에 따라 OAuth 클라이언트 자격 증명 또는 bearer token이 있습니다.
- 테이블 데이터용 S3 또는 호환 가능한 Storage Endpoint URI가 있습니다(예:
s3://my-bucket/path).
플라이아웃에서 다음을 수행하십시오.
- Catalog URL을 입력하십시오(예:
https://catalog.example.com/v1). - Warehouse 또는 카탈로그 네임스페이스를 입력하십시오(예:
demo). - 테이블 스토리지용 Storage Endpoint URI 접두사를 입력하십시오.
- Authentication method로 OAuth Client Credentials 또는 Bearer Token을 선택한 후 해당 자격 증명을 입력하십시오.
- REST 카탈로그 테이블을 노출하는 ClickHouse 데이터베이스의 Database name을 입력하십시오.
Azure AD 애플리케이션 자격 증명을 사용하여 Microsoft Fabric OneLake의 Iceberg 테이블을 쿼리합니다. 전체 설정 방법은 Fabric OneLake 가이드를 참조하십시오.
연결하기 전에 다음 사항을 확인하십시오.
- ClickHouse 버전이 25.12 이상입니다.
- Fabric 워크스페이스에 Iceberg 테이블이 있습니다.
- 클라이언트 ID와 시크릿이 포함된 Entra ID(Azure AD) 애플리케이션이 있습니다.
- 테넌트 ID, 워크스페이스 ID, 데이터 항목 ID가 있습니다. Lakehouse 페이지 URL에서 Lakehouse ID를 사용하십시오. 이러한 값을 찾는 방법은 Microsoft OneLake 사전 요구 사항을 참조하십시오.
플라이아웃에서 다음을 입력하십시오.
- Fabric Workspace ID
- Data Item ID — Lakehouse ID를 사용하십시오. Warehouse ID는 지원되지 않습니다.
- Entra ID Tenant ID, Application (client) ID, Client secret
- OneLake 테이블을 제공할 ClickHouse 데이터베이스의 Database name
Iceberg 테이블에 사용할 Snowflake Open Catalog(Polaris) 배포에 연결합니다. 전체 설정 방법은 Polaris catalog 가이드를 참조하십시오.
연결하기 전에 다음 사항을 확인하십시오.
- ClickHouse 버전이 26.2 이상입니다.
- OAuth 클라이언트 자격 증명이 구성된 Polaris catalog가 있습니다.
- Iceberg 테이블 데이터용 스토리지 엔드포인트 URI가 있습니다(예:
s3://company-iceberg-prod/warehouse/).
플라이아웃에서 다음을 수행하십시오.
- Catalog Account Identifier를 입력하십시오(예:
ab12345.snowflakecomputing.com). - Catalog Name을 입력하십시오(예:
snowflake_open_catalog). - OAuth Client ID와 Client Secret을 입력하십시오.
- 테이블 스토리지의 Storage Endpoint URI 접두사를 입력하십시오.
- Polaris 테이블을 노출할 ClickHouse 데이터베이스의 Database name을 입력하십시오.
GCS의 Iceberg 테이블용 Google Cloud BigLake Metastore(즉, Lakehouse 런타임 카탈로그)에 연결합니다. 전체 설정 방법은 BigLake Metastore 가이드를 참조하십시오.
연결하기 전에 다음 사항을 확인하십시오.
- ClickHouse 버전이 26.2 이상입니다.
- GCS에 Iceberg 테이블이 있는 BigLake 메타스토어 인스턴스가 있습니다.
- 클라이언트 ID, 클라이언트 시크릿, 갱신 토큰, 할당량 프로젝트 ID가 포함된 Google Application Default Credentials(ADC)가 있습니다.
플라이아웃에서 다음을 수행하십시오.
- Google ADC 클라이언트 ID, 클라이언트 시크릿, 갱신 토큰, 할당량 프로젝트 ID를 입력하십시오.
- 테이블 데이터가 저장된 Cloud Storage 버킷 URI를 입력하십시오(예:
gs://biglake-public-nyc-taxi-iceberg). - BigLake 테이블을 노출할 ClickHouse 데이터베이스의 데이터베이스 이름을 입력하십시오.
연결 저장
필드를 입력한 후:
- 카탈로그 추가를 클릭합니다. 저장 시 ClickHouse가 연결 및 자격 증명을 검증합니다.
- 성공하면 SQL 콘솔에서 보기 링크가 포함된 확인 토스트가 표시됩니다. 카탈로그는 연결 상태와 테이블 수와 함께 연결된 카탈로그 테이블에 표시됩니다.
연결된 카탈로그 행의 작업 메뉴에서 카탈로그 연결을 삭제할 수 있습니다. 삭제하면 ClickHouse에서 해당 카탈로그의 데이터베이스만 제거되며, 외부 카탈로그의 데이터는 삭제되지 않습니다.
데이터 쿼리
카탈로그 테이블 보기
데이터 소스 페이지의 Linked catalogs 테이블에서 카탈로그를 찾아 View tables를 클릭하세요.
ClickHouse가 카탈로그 데이터베이스가 선택된 SQL 콘솔을 열고 사용 가능한 테이블을 표시합니다.
쿼리 실행
SQL Editor에서 쿼리를 작성하고 Run을 클릭하세요. 전체 테이블 이름은 백틱으로 묶으세요.
SELECT * FROM `identity_profiles.identity_profiles_iceberg`
문제 해결
- SQL 콘솔에 테이블이 표시되지 않으면 자격 증명, 네트워크 액세스 및 카탈로그의 테이블 타입을 확인하십시오. 표시되어야 하는 테이블이 지원되는 파일 및 테이블 포맷을 사용하는지 확인하십시오.
관련 항목
- lakehouse 데이터 분석 가속 — 반복 쿼리를 위해 카탈로그 테이블을 MergeTree에 로드
- Iceberg 데이터에 안전하게 액세스하기 — AWS Iceberg 및 Glue 액세스를 위한 IAM role 설정