카탈로그 속성
카탈로그 속성 (Catalog properties)
아이스버그 카탈로그는 카탈로그 속성을 사용해서 카탈로그 동작을 구성할 수 있어요. 이 문서에서는 공통 카탈로그 속성, REST 카탈로그 속성(인증 포함), 잠금 관련 카탈로그 속성, 하둡 구성에 대해 표로 정리해드릴게요. 카탈로그 동작을 원하는 대로 튜닝하는 데 필요한 모든 속성을 한눈에 확인할 수 있어요.
출처: 문서
본문
공통 속성 (Common properties)
아이스버그 카탈로그는 카탈로그 속성을 사용해서 카탈로그 동작을 구성하는 것을 지원해요. 자주 사용되는 카탈로그 속성 목록은 다음과 같아요.
| 속성 | 기본값 | 설명 |
|---|---|---|
| catalog-impl | null | 엔진이 사용할 커스텀 Catalog 구현 |
| io-impl | null | 카탈로그에서 사용할 커스텀 FileIO 구현 |
| warehouse | null | 데이터 웨어하우스의 루트 경로 |
| uri | null | Hive metastore URI 같은 URI 문자열 |
| clients | 2 | 클라이언트 풀 크기 |
| cache-enabled | true | 카탈로그 항목을 캐시할지 여부 |
| cache.expiration-interval-ms | 30000 | 카탈로그 항목이 로컬에 캐시되는 시간(밀리초); 0이면 캐시 비활성화, 음수면 만료 비활성화 |
| metrics-reporter-impl | org.apache.iceberg.metrics.LoggingMetricsReporter | 카탈로그에서 사용할 커스텀 MetricsReporter 구현. 자세한 내용은 메트릭 보고(Metrics reporting) 섹션 참조 |
| unique-table-location | false | 새 테이블에 고유 위치를 사용할지 여부 |
| encryption.kms-impl | null | KMS(키 관리 서비스)와의 상호작용을 위해 카탈로그에서 사용할 커스텀 KeyManagementClient 구현. 자세한 내용은 암호화(Encryption) 문서 참조 |
HadoopCatalog와 HiveCatalog는 생성자에서 이 속성들에 접근할 수 있어요. 다른 커스텀 카탈로그는 Catalog.initialize(catalogName, catalogProperties)를 구현해서 이 속성들에 접근할 수 있어요. 이 속성들은 수동으로 만들거나 스파크·플링크 같은 컴퓨트 엔진에서 전달받을 수 있어요. 스파크는 세션 속성을 카탈로그 속성으로 사용해요. 자세한 내용은 스파크 구성(Spark configuration) 섹션 참조. 플링크는 CREATE CATALOG 문을 통해 카탈로그 속성을 전달해요. 자세한 내용은 플링크(Flink) 섹션 참조.
REST 카탈로그 속성 (REST catalog properties)
다음 속성들은 REST 카탈로그 클라이언트의 동작을 구성해요.
| 속성 | 기본값 | 설명 |
|---|---|---|
| snapshot-loading-mode | ALL | REST 서버에서 스냅샷을 로드하는 방식을 제어해요. 지원 값: ALL(모든 스냅샷 로드), REFS(참조된 스냅샷만 로드). |
| rest-metrics-reporting-enabled | true | REST 서버로 메트릭 보고를 활성화할지 여부. |
| view-endpoints-supported | false | 이전 REST 서버와의 하위 호환을 위해 사용. 서버가 view 엔드포인트를 지원하지만 ConfigResponse에 endpoints 필드를 보내지 않는다면 true로 설정해요. |
| rest-page-size | null | 네임스페이스, 테이블 또는 다른 페이지네이션 리소스를 나열할 때 사용할 페이지 크기. |
| namespace-separator | %1F | REST 서버와 통신할 때 네임스페이스 수준에 사용되는 구분 문자. |
| scan-planning-mode | CLIENT | 스캔 계획이 수행되는 위치를 제어해요. 지원 값: CLIENT(클라이언트측 계획), SERVER(서버측 계획). 서버가 LoadTableResponse에서 테이블별로 재정의할 수 있어요. |
테이블 캐시 속성 (Table cache properties)
다음 속성들은 신선도 인식(freshness-aware) 테이블 로딩에 사용되는 테이블 캐시를 구성해요. 이 캐시는 일반적으로 카탈로그 수준에서 구성할 수 있는 캐시와 다르다는 점에 유의해주세요.
| 속성 | 기본값 | 설명 |
|---|---|---|
| rest-table-cache.expire-after-write-ms | 300000 (5 min) | 캐시된 테이블 항목이 만료되는 시간(밀리초). |
| rest-table-cache.max-entries | 100 | 캐시할 테이블 항목의 최대 수. |
인증 속성 (Auth properties)
다음 카탈로그 속성들은 REST 카탈로그의 인증을 구성해요. Basic, OAuth2, SigV4, Google 인증을 지원해요.
REST 인증 속성 (REST auth properties)
| 속성 | 기본값 | 설명 |
|---|---|---|
| rest.auth.type | none | REST 카탈로그 접근의 인증 메커니즘. 지원 값: none, basic, oauth2, sigv4, google. |
| rest.auth.basic.username | null | Basic 인증용 사용자 이름. rest.auth.type = basic이면 필수. |
| rest.auth.basic.password | null | Basic 인증용 비밀번호. rest.auth.type = basic이면 필수. |
| rest.auth.sigv4.delegate-auth-type | oauth2 | sigv4 서명 후 위임할 인증 타입. |
OAuth2 인증 속성 (OAuth2 auth properties)
oauth2 인증을 사용할 때 포함할 필수 및 선택 속성
| 속성 | 기본값 | 설명 |
|---|---|---|
| token | null | 서버와 상호작용하기 위한 Bearer 토큰. token 또는 credential 중 하나가 필요해요. |
| credential | null | OAuth2 클라이언트 자격증명 흐름에서 토큰과 교환할 client_id:client_secret 형식의 자격증명 문자열. token 또는 credential 중 하나가 필요해요. |
| oauth2-server-uri | v1/oauth/tokens | OAuth2 토큰 엔드포인트 URI. REST 카탈로그가 OAuth2 인증 서버가 아니면 필수. |
| token-expires-in-ms | 3600000 (1 hour) | 이후에 Bearer 토큰이 만료된 것으로 간주되는 시간(밀리초). 토큰을 언제 갱신하거나 재교환할지 결정하는 데 사용돼요. |
| token-refresh-enabled | true | 만료 정보가 있을 때 토큰이 자동으로 갱신되는지 결정해요. |
| token-exchange-enabled | true | 새 토큰을 얻기 위해 토큰 교환 흐름을 사용할지 결정해요. 비활성화하면 클라이언트 자격증명 흐름으로 폴백할 수 있어요. |
| scope | catalog | oauth2를 위한 추가 스코프. |
| audience | null | 토큰 audience를 지정하는 선택적 파라미터 |
| resource | null | 리소스를 지정하는 선택적 파라미터 |
Google 인증 속성 (Google auth properties)
google 인증을 사용할 때 포함할 필수 및 선택 속성
| 속성 | 기본값 | 설명 |
|---|---|---|
| gcp.auth.credentials-path | Application Default Credentials (ADC) | 서비스 계정 JSON 키 파일의 경로. |
| gcp.auth.credentials-json | Application Default Credentials (ADC) | 서비스 계정 자격증명의 JSON 문자열. |
| gcp.auth.scopes | https://www.googleapis.com/auth/cloud-platform | 요청할 OAuth 스코프의 쉼표 구분 목록. |
잠금 카탈로그 속성 (Lock catalog properties)
여기 잠금과 관련된 카탈로그 속성이 있어요. 일부 카탈로그 구현이 커밋 중 잠금 동작을 제어하는 데 사용돼요.
| 속성 | 기본값 | 설명 |
|---|---|---|
| lock-impl | null | 잠금 관리자의 커스텀 구현. 실제 인터페이스는 사용되는 카탈로그에 따라 달라져요 |
| lock.table | null | 잠금을 위한 보조 테이블 (예: AWS DynamoDB 잠금 관리자) |
| lock.acquire-interval-ms | 5000 (5 s) | 잠금 획득을 시도할 때마다 기다리는 간격 |
| lock.acquire-timeout-ms | 180000 (3 min) | 잠금 획득을 시도하는 최대 시간 |
| lock.heartbeat-interval-ms | 3000 (3 s) | 잠금 획득 후 각 하트비트 사이에 기다리는 간격 |
| lock.heartbeat-timeout-ms | 15000 (15 s) | 잠금이 만료된 것으로 간주하는 하트비트 없는 최대 시간 |
하둡 구성 (Hadoop configuration)
HadoopTables 잠금 구성 (HadoopTables Lock Configuration)
HadoopTables(카탈로그 없는 테이블)를 사용할 때 잠금 카탈로그 속성 섹션의 잠금 속성에 iceberg.tables.hadoop. 프리픽스를 붙여 구성할 수 있어요. 이렇게 하면 네이티브 쓰기 상호배제가 없는 S3 같은 파일 시스템에서 원자적 커밋을 보장해요.
정보 (Info)
HadoopTables에서 잠금 관리자로 DynamoDB를 사용하려면 iceberg.tables.hadoop.lock-impl을 org.apache.iceberg.aws.dynamodb.DynamoDbLockManager로 설정하고 iceberg.tables.hadoop.lock.table을 DynamoDB 테이블 이름으로 설정해주세요. 자세한 내용은 DynamoDB 잠금 관리자(DynamoDB Lock Manager)를 참고해주세요.
하이브 메타스토어 구성 (Hive Metastore Configuration)
하이브 메타스토어 커넥터가 사용하는 하둡 구성 속성은 다음과 같아요. HMS 테이블 잠금은 2단계 프로세스예요.
- 잠금 생성(Lock Creation): HMS에 잠금을 만들고 획득을 위해 큐에 넣기
- 잠금 확인(Lock Check): 잠금이 성공적으로 획득됐는지 확인
| 속성 | 기본값 | 설명 |
|---|---|---|
| iceberg.hive.client-pool-size | 5 | HMS에서 테이블을 추적할 때의 하이브 클라이언트 풀 크기 |
| iceberg.hive.lock-creation-timeout-ms | 180000 (3 min) | HMS에서 잠금을 만드는 최대 시간(밀리초) |
| iceberg.hive.lock-creation-min-wait-ms | 50 | HMS에서 잠금 생성 재시도 사이의 최소 시간(밀리초) |
| iceberg.hive.lock-creation-max-wait-ms | 5000 | HMS에서 잠금 생성 재시도 사이의 최대 시간(밀리초) |
| iceberg.hive.lock-timeout-ms | 180000 (3 min) | 잠금을 획득하는 최대 시간(밀리초) |
| iceberg.hive.lock-check-min-wait-ms | 50 | 잠금 획득을 확인하는 사이의 최소 시간(밀리초) |
| iceberg.hive.lock-check-max-wait-ms | 5000 | 잠금 획득을 확인하는 사이의 최대 시간(밀리초) |
| iceberg.hive.lock-heartbeat-interval-ms | 240000 (4 min) | HMS 잠금의 하트비트 간격 |
| iceberg.hive.metadata-refresh-max-retries | 2 | 메타데이터 파일이 없을 때의 최대 재시도 횟수 |
| iceberg.hive.table-level-lock-evict-ms | 600000 (10 min) | JVM 테이블 잠금의 타임아웃 |
| iceberg.engine.hive.lock-enabled | true | 커밋의 원자성을 보장하기 위해 HMS 잠금을 사용 |
참고: iceberg.hive.lock-check-max-wait-ms와 iceberg.hive.lock-heartbeat-interval-ms는 Hive Metastore의 트랜잭션 타임아웃(hive.txn.timeout 또는 최신 버전의 metastore.txn.timeout)보다 작아야 해요. 그렇지 않으면 잠금에 대한 하트비트(잠금 확인 중에 발생)가 아이스버그가 잠금을 재시도하기 전에 Hive Metastore에서 만료될 수 있어요.
경고 (Warn)
iceberg.engine.hive.lock-enabled=false로 설정하면 HiveCatalog가 하이브 잠금을 사용하지 않고 테이블에 커밋하게 돼요. 다음 조건이 모두 충족될 때만 false로 설정해야 해요:
- Hive Metastore 서버에 HIVE-26882가 있음
- Hive Metastore가 MySQL 또는 MariaDB로 뒷받침된다면 HIVE-28121도 서버에 있음
- 이 HiveCatalog가 커밋하는 테이블에 커밋하는 다른 모든 HiveCatalog가 Iceberg 1.3 이상임
- 이 HiveCatalog가 커밋하는 테이블에 커밋하는 다른 모든 HiveCatalog도 커밋 시 하이브 잠금을 비활성화했음
이 조건들을 보장하지 않으면 테이블이 손상될 위험이 있어요.
iceberg.engine.hive.lock-enabled가 false로 설정돼 있어도, HiveCatalog는 테이블 속성 engine.hive.lock-enabled=true를 설정해서 개별 테이블에 대해 여전히 잠금을 사용할 수 있어요. 이는 다른 HiveCatalog를 업그레이드해서 하이브 잠금 없이 커밋하도록 설정할 수 없는 경우에 유용해요.