Lakehouse for Apache Iceberg는 Lakehouse 런타임 카탈로그를 통해 메타데이터를 관리합니다. Apache Iceberg REST 카탈로그 엔드포인트를 사용하면 시스템에서 데이터를 엄격한 리소스 계층 구조로 정리합니다. 카탈로그 구성은 지원되는 스토리지 유형, 리전 라우팅 동작, 쿼리 페더레이션 옵션을 결정합니다.
기능 및 규정 준수
Lakehouse 런타임 카탈로그는 표준 테이블 형식을 지원하고 개방형 API를 준수하여 Iceberg 호환 쿼리 엔진과 통합되도록 빌드됩니다.
지원되는 표 형식
Apache Iceberg V2 테이블 (정식 버전) 및 V3 테이블 (미리보기)이 지원됩니다. Iceberg V1 테이블은 지원되지 않습니다. Apache Iceberg REST 카탈로그 엔드포인트에서 기존 V1 테이블을 사용하려면 지원되는 버전으로 업그레이드해야 합니다. 자세한 내용은 Iceberg V1 테이블을 V2로 업그레이드를 참고하세요.
API 규정 준수 및 REST 작업
Lakehouse 런타임 카탈로그는 개방형 표준 Apache Iceberg REST 카탈로그 API를 구현합니다. 클라이언트 쿼리 엔진은 표준 REST 카탈로그 API를 사용하여 카탈로그와 상호작용합니다. 자세한 내용은 Lakehouse에서 Apache Iceberg REST 카탈로그 API를 구현하는 방법을 참고하세요.
리소스 계층 구조
Apache Iceberg REST 카탈로그 엔드포인트는 리소스 계층 구조를 사용하여 데이터를 구성합니다. 다음 표에서는 이러한 리소스를 대략적으로 살펴봅니다.
| 리소스 | 설명 |
|---|---|
| 카탈로그 | 최상위 컨테이너인 카탈로그를 사용하면 네임스페이스와 테이블을 여러 카탈로그로 분할하여 논리적 그룹으로 정리할 수 있습니다. 각 카탈로그는 기본 메타데이터와 데이터 파일을 저장하는 지정된 웨어하우스 스토리지 위치 (예: Cloud Storage 버킷 또는 BigQuery 페더레이션 프록시)로 지원됩니다. |
| 네임스페이스 | 카탈로그 내에서 테이블을 구성하는 데 사용되는 논리적 그룹으로, 데이터베이스, 스키마 또는 디렉터리와 같은 기능을 합니다. |
| 표 | 테이블에는 쿼리할 수 있는 행과 열의 정의가 포함됩니다. |
카탈로그 및 스토리지 위치
카탈로그의 구성은 카탈로그가 작동하고 Google Cloud 서비스와 통합되는 방식을 결정합니다. 여러 버킷 (bl://) 카탈로그(권장) 또는 단일 버킷 (gs://) 카탈로그를 구성할 수 있습니다.
두 옵션 모두 세분화된 액세스 제어를 위한 사용자 인증 정보 판매를 지원합니다.
여러 버킷 (bl://) 카탈로그 (권장)
이 방법을 사용하면 버킷 이름과 관계없이 카탈로그 이름을 지정할 수 있으며 하나의 카탈로그에 여러 버킷을 구성할 수 있습니다. 기본 API에서 이는 CATALOG_TYPE_BIGLAKE 구성에 해당합니다.
고려사항:
- 기본 위치: 기본 스토리지 위치로 사용할 버킷 (
default_location) 또는 하위 경로 (예:gs://my-bucket/path)의 경로를 제공합니다. 모든 카탈로그 리소스 (네임스페이스 및 테이블)는 지정된 경로 아래에 있어야 합니다. 예를 들어gs://my-bucket/path을 지정하면gs://my-bucket/another/path아래에 네임스페이스나 테이블을 호스팅할 수 없습니다. 지정된 위치 없이 생성된 네임스페이스의 경우default_location가 사용됩니다. - 제한된 위치: 네임스페이스와 테이블을 만들 수 있는 추가 버킷 또는 경로에 선택적
restricted_locations구성을 제공할 수도 있습니다. 하위 경로 (예:gs://my-bucket/path)를 지정하면 해당 구성을 사용하여 생성된 모든 리소스가 해당 경로 아래에 있어야 합니다 (예:gs://my-bucket/another/path은 네임스페이스나 테이블을 호스팅할 수 없음). - 지리적 리전 그룹 요구사항: 버킷은 프로젝트 간, 리전 간일 수 있고 구성 (예: 단일 리전, 이중 리전 또는 멀티 리전)이 다를 수 있지만 기본 위치와 제한된 위치의 모든 Cloud Storage 위치는 동일한 지리적 리전 그룹 (예: 미국, 유럽, 캐나다 또는 아시아)에 있어야 합니다. 예를 들어 유럽 또는 캐나다의 버킷으로 미국 멀티 리전 버킷을 구성할 수 없습니다.
- 버킷당 여러 카탈로그: 여러 카탈로그가 동일한 버킷을 가리키도록 할 수 있습니다 (예: 다른 기본 위치 또는 제한된 위치 사용). 하지만 이 구성은 메타데이터 충돌, 실수로 인한 데이터 덮어쓰기 또는 권한 누출과 같은 보안 문제로 이어질 수 있으므로 권장되지 않습니다.
- 네임스페이스: 기본 또는 제한된 위치에 구성된 경로 아래에 있는 경우 맞춤 네임스페이스 위치를 지정할 수 있습니다.
이러한 카탈로그에서 생성된 테이블에는 충돌을 방지하기 위해 물리적 경로에 임의의 문자열 접미사가 자동으로 추가됩니다 (예:
gs://{bucket_name}/{namespace_name}/{table_name}/{random_suffix}). 자세한 내용은 테이블 관리 및 보안 규칙을 참고하세요.
단일 버킷 (gs://) 카탈로그
이 방법은 카탈로그가 사용자가 지정한 단일 Cloud Storage 버킷에서 Apache Iceberg 메타데이터와 데이터 파일을 직접 관리하는 기존 방식입니다. 기본 API에서 이는 CATALOG_TYPE_GCS_BUCKET 구성에 해당합니다.
단일 버킷 카탈로그의 경우 카탈로그 이름이 버킷 이름으로 설정됩니다.
예를 들어 카탈로그를 저장하기 위해 버킷을 만들고 이름을 iceberg-bucket로 지정한 경우 카탈로그 이름과 버킷 이름이 모두 iceberg-bucket입니다. 이는 나중에 P.C.N.T 구문을 사용하여 BigQuery에서 카탈로그를 쿼리할 때 사용됩니다. 예: my-project.lakehouse-catalog-id.quickstart_namespace.quickstart_table
고려사항:
기존 카탈로그 유형 제한사항 새 프로젝트에는 기존 단일 버킷 구성을 사용하지 않는 것이 좋습니다. 이 구성에는 다음과 같은 몇 가지 심각한 제한사항이 있습니다.
- 카탈로그 이름: 기본 Cloud Storage 버킷 이름으로 잠겨 있습니다.
- 프로젝트: 버킷의 프로젝트로 잠깁니다 (교차 프로젝트 카탈로그는 지원되지 않음).
- 리전: 버킷의 위치에서 엄격하게 파생되며 맞춤설정할 수 없습니다.
- 스토리지: 카탈로그를 단일 버킷으로 제한합니다 (제한된 위치 없음).
버킷당 하나의 카탈로그 제한: 이 기존 카탈로그 유형의 경우 버킷당 하나의 카탈로그만 있을 수 있으며 카탈로그 이름은 버킷 이름과 일치해야 합니다.
다중 버킷 (
bl://) 카탈로그로 업그레이드 (권장): 기존 단일 버킷 (gs://) 카탈로그를 다중 버킷 (bl://) 카탈로그로 업그레이드할 수 있습니다 (권장). 업그레이드된 카탈로그는 원래 버킷의 이름을 유지합니다. 그런 다음 카탈로그에 여러 버킷을 연결하고 제한된 위치를 구성할 수 있습니다.
버킷 및 카탈로그 리전
레이크하우스 런타임 카탈로그에 있는 카탈로그 엔드포인트의 리전은 기본 Cloud Storage 버킷의 리전에 따라 결정됩니다.
- 여러 버킷 (
bl://) 카탈로그(권장): 카탈로그 리전은default_location에 구성된 버킷에서 파생됩니다. - 단일 버킷 (
gs://): 카탈로그 리전은 카탈로그와 연결된 버킷에서 엄격하게 파생되며 맞춤설정할 수 없습니다.
매핑된 카탈로그 리전은 버킷의 리전 유형에 따라 다릅니다.
- 단일 리전: 카탈로그 리전이 버킷의 리전과 정확히 일치합니다.
- 이중 리전: 카탈로그 리전이 버킷의 이중 리전 (예:
ASIA1또는NAM4)과 일치합니다. - 멀티 리전: 카탈로그 리전이 멀티 리전의 지리적 도메인 내 특정 리전 위치로 설정됩니다. 기본적으로 이는
US및EU과 같은 일반적인 BigQuery 멀티 리전과 일치하지 않을 수 있습니다(예:US멀티 리전 버킷이us-central1또는us-east4에 매핑됨).
BigQuery가 이러한 카탈로그의 테이블에 대해 쿼리를 실행하면 쿼리가 카탈로그의 기본 리전으로 라우팅됩니다. 특정 가상 리전 (예: US 또는 EU)의 테이블을 쿼리하는데 카탈로그 메타데이터가 해당 위치에 없으면 쿼리가 실패합니다.
멀티 리전의 기본 리전
BigQuery가 US 또는 EU 멀티 리전에서 카탈로그 테이블을 쿼리하도록 하려면 카탈로그를 만들 때 US 또는 EU을 기본 리전으로 지정하세요.
다음 구성에서 멀티 리전 (US 또는 EU)을 기본 리전으로 지정할 수 있습니다.
default_location 버킷이 다음과 같은 경우
US또는EU멀티 리전 버킷- 이러한 멀티 리전 내의 단일 리전 버킷 (예:
us-central1또는europe-west4) - 해당 영역 내의 이중 리전 또는 맞춤 이중 리전 버킷 (예:
NAM4또는EUR4)
기본 복제본은 카탈로그를 만들 때 정의되지만 FailoverCatalog를 호출하여 동적으로 장애 조치를 실행할 수 있습니다. 자세한 내용은 카탈로그 만들기를 참고하세요.
BigQuery에서 카탈로그 쿼리
BigQuery에서 Lakehouse 런타임 카탈로그 테이블을 쿼리할 때는 4부분으로 된 이름 지정 구조를 사용하며, 이를 P.C.N.T라고도 합니다.
- Project: 카탈로그를 소유하는 Google Cloud 프로젝트 ID입니다.
- Catalog: Lakehouse 런타임 카탈로그의 이름입니다.
- Namespace: Apache Iceberg 네임스페이스 (BigQuery 데이터 세트와 동일)입니다.
- Table: 테이블의 이름입니다.
예를 들면 my-project.lakehouse-catalog-id.my-namespace.my-table입니다.