메타스토어
메타스토어 (Metastores)
객체 스토리지 접근은 메타스토어(metastore)를 통해 중개돼요. 메타스토어는 디렉토리 구조, 파일 형식, 저장된 데이터에 대한 메타데이터 정보를 제공해요.
출처: 문서
본문
객체 스토리지 접근은 메타스토어를 통해 중개돼요. 메타스토어는 디렉토리 구조, 파일 형식, 저장된 데이터에 대한 메타데이터를 제공해요. 객체 스토리지 커넥터는 하나 이상의 메타스토어 사용을 지원해요. 객체 스토리지 커넥터를 사용하려면 지원되는 메타스토어가 필요해요.
Athena 파티션 프로젝션(partition projection) 메타데이터를 가진 테이블에 접근하거나 Avro 테이블에 대한 일급 지원(first class support)을 구현하려면 추가 구성이 필요해요. 이러한 요구 사항은 이 문서 후반에 다뤄요.
일반 메타스토어 구성 프로퍼티 (General metastore configuration properties)
다음 표는 일반 메타스토어 구성 프로퍼티를 설명해요. 대부분은 두 메타스토어 모두에서 사용돼요.
각 Delta Lake, Hive, Hudi 객체 스토리지 카탈로그 파일은 최소한 hive.metastore 구성 프로퍼티를 설정해 사용할 메타스토어의 타입을 정의해야 해요. Iceberg 카탈로그는 대신 iceberg.catalog.type 구성 프로퍼티로 사용할 메타스토어 타입을 정의해요.
Thrift와 Glue 메타스토어에 특화된 추가 구성 프로퍼티도 있어요. 이 문서 후반에 다뤄요.
| 프로퍼티 이름 | 설명 | 기본값 |
|---|---|---|
hive.metastore |
사용할 Hive 메타스토어의 타입. Trino는 현재 메타데이터 소스로 기본 Hive Thrift 메타스토어(thrift)와 AWS Glue Catalog(glue)를 지원해요. Iceberg를 제외한 모든 객체 스토리지 카탈로그에 이 값을 사용해야 해요. |
thrift |
iceberg.catalog.type |
Iceberg 테이블 형식은 대부분의 메타데이터를 객체 스토리지 자체의 메타데이터 파일에서 관리해요. 하지만 소량의 메타데이터는 여전히 메타스토어 사용이 필요해요. Iceberg 생태계에서 이 더 작은 메타스토어를 Iceberg 메타데이터 카탈로그 또는 그냥 카탈로그라고 불러요. 각 하위 섹션의 예시는 Iceberg 커넥터를 사용해 서로 다른 Iceberg 메타데이터 카탈로그를 구성하는 Trino 카탈로그 파일의 내용을 보여 줘요. 모든 Iceberg 카탈로그 프로퍼티 파일에 이 프로퍼티를 설정해야 해요. 유효 값은 hive_metastore, glue, jdbc, rest, nessie, snowflake. |
hive_metastore |
hive.metastore-cache.cache-partitions |
파티션 메타데이터의 캐싱을 활성화해요. 캐싱으로 인한 비일관적 동작을 피하려면 캐싱을 비활성화할 수 있어요. | true |
hive.metastore-cache.cache-missing |
테이블이 없다는 사실을 캐싱해 그 테이블에 대한 향후 메타스토어 호출을 방지해요. | true |
hive.metastore-cache.cache-missing-partitions |
파티션이 없다는 사실을 캐싱해 그 파티션에 대한 향후 메타스토어 호출을 방지해요. | false |
hive.metastore-cache.cache-missing-stats |
특정 테이블의 테이블 통계가 없다는 사실을 캐싱해 향후 메타스토어 호출을 방지해요. | false |
hive.metastore-cache-ttl |
캐시된 메타스토어 데이터가 유효하다고 간주되는 시간. | 0s |
hive.metastore-stats-cache-ttl |
캐시된 메타스토어 통계가 유효하다고 간주되는 시간. | 5m |
hive.metastore-cache-maximum-size |
Hive metastore 캐시의 최대 메타스토어 데이터 객체 수. | 20000 |
hive.metastore-refresh-interval |
캐시된 메타스토어 데이터가 만료되지는 않았지만 이보다 오래되면 접근 후 비동기적으로 새로 고쳐, 이후 접근이 최신 데이터를 볼 수 있게 해요. | |
hive.metastore-refresh-max-threads |
캐시된 메타스토어 데이터를 새로 고치는 데 사용되는 최대 스레드 수. | 10 |
hive.user-metastore-cache-ttl |
사용자 가장(user impersonation) 시나리오에서 사용자 특정인 캐시된 메타스토어 통계가 유효하다고 간주되는 시간. | 0s |
hive.user-metastore-cache-maximum-size |
사용자 가장 시나리오에서 사용자 특정인 Hive metastore 캐시의 최대 메타스토어 데이터 객체 수. | 1000 |
hive.hide-delta-lake-tables |
테이블 목록에서 Delta Lake 테이블을 숨길지 여부를 제어해요. 현재 AWS Glue 메타스토어를 사용할 때만 적용돼요. | false |
Thrift 메타스토어 구성 프로퍼티 (Thrift metastore configuration properties)
Hive Thrift 메타스토어를 사용하려면 hive.metastore=thrift로 메타스토어를 구성하고 다음 프로퍼티로 추가 세부 사항을 제공해야 해요.
| 프로퍼티 이름 | 설명 | 기본값 |
|---|---|---|
hive.metastore.uri |
Thrift 프로토콜로 연결할 Hive metastore의 URI. 쉼표로 구분된 URI 목록이 제공되면 첫 번째 URI가 기본으로 사용되고 나머지 URI는 폴백 메타스토어예요. 필수 프로퍼티. 예: thrift://192.0.2.3:9083 또는 thrift://192.0.2.3:9083,thrift://192.0.2.4:9083. |
|
hive.metastore.username |
Trino가 Hive metastore에 접근할 때 사용하는 사용자 이름. | |
hive.metastore.authentication.type |
Hive metastore 인증 타입. 가능한 값은 NONE 또는 KERBEROS. |
NONE |
hive.metastore.thrift.client.connect-timeout |
metastore 클라이언트의 소켓 연결 타임아웃. | 10s |
hive.metastore.thrift.client.read-timeout |
metastore 클라이언트의 소켓 읽기 타임아웃. | 10s |
hive.metastore.thrift.impersonation.enabled |
Hive metastore 최종 사용자 가장을 활성화해요. | |
hive.metastore.thrift.use-spark-table-statistics-fallback |
Hive 테이블 통계를 사용할 수 없을 때 Apache Spark가 생성한 테이블 통계 사용을 활성화해요. | true |
hive.metastore.thrift.delegation-token.cache-ttl |
metastore용 delegation token 캐시의 유효 시간(Time to live). | 1h |
hive.metastore.thrift.delegation-token.cache-maximum-size |
delegation token 캐시의 최대 크기. | 1000 |
hive.metastore.thrift.client.ssl.enabled |
metastore에 연결할 때 SSL 사용. | false |
hive.metastore.thrift.client.ssl.key |
개인키와 클라이언트 인증서(key store)의 경로. | |
hive.metastore.thrift.client.ssl.key-password |
개인키의 비밀번호. | |
hive.metastore.thrift.client.ssl.trust-certificate |
서버 인증서 체인(trust store)의 경로. SSL이 활성화될 때 필수. | |
hive.metastore.thrift.client.ssl.trust-certificate-password |
trust store의 비밀번호. | |
hive.metastore.service.principal |
Hive metastore 서비스의 Kerberos principal. | |
hive.metastore.client.principal |
Trino가 Hive metastore 서비스에 연결할 때 사용하는 Kerberos principal. | |
hive.metastore.client.keytab |
Hive metastore 클라이언트 keytab 위치. | |
hive.metastore.thrift.delete-files-on-drop |
drop table 또는 partition 작업 시 관리 테이블(managed table)의 파일을 적극적으로 삭제해요. 메타스토어가 파일을 삭제하지 않을 때 사용. | false |
hive.metastore.thrift.assume-canonical-partition-keys |
파티션 컬럼의 값을 문자열 값으로 변환할 수 있다고 메타스토어가 가정하게 허용해요. 파티션 컬럼에 필터를 적용하는 쿼리의 성능을 향상시킬 수 있어요. TIMESTAMP 타입의 파티션 키는 canonicalize되지 않아요. |
false |
hive.metastore.thrift.client.socks-proxy |
Thrift Hive metastore에 사용할 SOCKS 프록시. | |
hive.metastore.thrift.client.max-retries |
metastore 요청의 최대 재시도 횟수. | 9 |
hive.metastore.thrift.client.backoff-scale-factor |
metastore 요청 재시도 지연의 스케일 계수. | 2.0 |
hive.metastore.thrift.client.max-retry-time |
metastore 요청이 재시도될 수 있는 총 허용 시간 제한. | 30s |
hive.metastore.thrift.client.min-backoff-delay |
metastore 요청 재시도 사이의 최소 지연. | 1s |
hive.metastore.thrift.client.max-backoff-delay |
metastore 요청 재시도 사이의 최대 지연. | 1s |
hive.metastore.thrift.txn-lock-max-wait |
hive 트랜잭션 잠금을 획득하기 위해 대기할 최대 시간. | 10m |
hive.metastore.thrift.catalog-name |
"Hive metastore catalog name"이라는 용어는 Hive 안의 추상화 개념으로, 다양한 시스템이 metastore에 저장된 별개의 독립 카탈로그에 연결할 수 있게 해줘요. 기본적으로 Hive metastore의 카탈로그 이름은 "hive"로 설정돼요. 이 구성 프로퍼티가 비어 있으면 Hive metastore의 기본 카탈로그에 접근해요. |
Iceberg 전용 Hive 카탈로그 구성 프로퍼티 (Iceberg-specific Hive catalog configuration properties)
Hive 카탈로그를 사용할 때 Iceberg 커넥터는 앞서 설명한 일반 Thrift metastore 구성 프로퍼티와 함께 다음 추가 프로퍼티를 지원해요.
| 프로퍼티 이름 | 설명 | 기본값 |
|---|---|---|
iceberg.hive-catalog.locking-enabled |
Hive 잠금을 사용해 테이블에 커밋해요. | true |
⚠️ 경고:
iceberg.hive-catalog.locking-enabled=false로 설정하면 Hive 잠금 없이 테이블에 커밋하게 돼요. 다음 조건이 모두 충족될 때만 false로 설정해야 해요.
- Hive metastore 서버에 HIVE-26882가 사용 가능함. 버전 2.3.10, 4.0.0-beta-1 이상 필요.
- MySQL 또는 MariaDB가 뒷받침되는 경우 Hive metastore 서버에 HIVE-28121이 사용 가능함. 버전 2.3.10, 4.1.0, 4.0.1 이상 필요.
- 이 카탈로그가 커밋하는 테이블에 커밋하는 다른 모든 카탈로그도 Iceberg 1.3 이상이고, 커밋 시 Hive 잠금을 비활성화했음.
Thrift 메타스토어 인증 (Thrift metastore authentication)
Kerberos화된 Hadoop 클러스터에서 Trino는 SASL을 사용해 Hive metastore Thrift 서비스에 연결하고 Kerberos로 인증해요. metastore에 대한 Kerberos 인증은 커넥터의 프로퍼티 파일에서 다음 선택적 프로퍼티로 구성돼요.
| 프로퍼티 값 | 설명 | 기본값 |
|---|---|---|
hive.metastore.authentication.type |
Hive metastore 인증 타입. NONE 또는 KERBEROS 중 하나. 기본값 NONE을 사용하면 Kerberos 인증이 비활성화되고 다른 프로퍼티를 구성할 필요가 없어요. KERBEROS로 설정하면 Hive 커넥터가 SASL로 Hive metastore Thrift 서비스에 연결하고 Kerberos로 인증해요. |
NONE |
hive.metastore.thrift.impersonation.enabled |
Hive metastore 최종 사용자 가장을 활성화해요. 자세한 내용은 KERBEROS authentication with impersonation을 참고하세요. | false |
hive.metastore.service.principal |
Hive metastore 서비스의 Kerberos principal. 코디네이터가 이를 사용해 Hive metastore를 인증해요. 이 프로퍼티 값에는 _HOST 플레이스홀더를 사용할 수 있어요. Hive metastore에 연결할 때 Hive 커넥터는 연결하는 metastore 서버의 호스트명을 대입해요. metastore가 여러 호스트에서 실행될 때 유용해요. 예: hive/... 또는 hive/.... |
|
hive.metastore.client.principal |
Trino가 Hive metastore 서비스에 연결할 때 사용하는 Kerberos principal. 예: trino/... 또는 trino/.... 이 프로퍼티 값에는 _HOST 플레이스홀더를 사용할 수 있어요. Hive metastore에 연결할 때 Hive 커넥터는 Trino가 실행되는 워커 노드의 호스트명을 대입해요. 각 워커 노드가 고유한 Kerberos principal을 가질 때 유용해요. 가장이 포함된 KERBEROS 인증이 활성화되지 않았다면, hive.metastore.client.principal로 지정된 principal은 hive/warehouse 디렉토리 안의 파일과 디렉토리를 제거할 수 있는 충분한 권한을 가져야 해요. 경고: principal이 충분한 권한이 없다면 메타데이터만 제거되고 데이터는 디스크 공간을 계속 차지해요. Hive metastore가 내부 테이블 데이터 삭제를 담당하기 때문이에요. metastore가 Kerberos 인증을 사용하도록 구성되면 metastore가 수행하는 모든 HDFS 작업이 가장돼요. 데이터 삭제 오류는 조용히 무시돼요. |
|
hive.metastore.client.keytab |
hive.metastore.client.principal로 지정된 principal의 키를 담은 keytab 파일의 경로. 이 파일은 Trino를 실행하는 운영체제 사용자가 읽을 수 있어야 해요. |
다음 섹션은 Hive 커넥터와 함께 Hive metastore Thrift 서비스를 사용하는 데 필요한 다양한 인증 구성의 구성 프로퍼티와 값을 설명해요.
가장 없는 기본 NONE 인증
hive.metastore.authentication.type=NONE
Hive metastore의 기본 인증 타입은 NONE이에요. 인증 타입이 NONE이면 Trino는 보안되지 않은 Hive metastore에 연결해요. Kerberos는 사용되지 않아요.
가장이 있는 KERBEROS 인증
hive.metastore.authentication.type=KERBEROS
hive.metastore.thrift.impersonation.enabled=true
hive.metastore.service.principal=hive/...
hive.metastore.client.principal=trino/...
hive.metastore.client.keytab=/etc/trino/hive.keytab
Hive metastore Thrift 서비스의 인증 타입이 KERBEROS이면 Trino는 hive.metastore.client.principal 프로퍼티로 지정된 Kerberos principal로 연결해요. Trino는 hive.metastore.client.keytab 프로퍼티로 지정된 keytab으로 이 principal을 인증하고, metastore의 신원이 hive.metastore.service.principal과 일치하는지 검증해요.
가장이 있는 KERBEROS metastore 인증을 사용할 때, hive.metastore.client.principal 프로퍼티로 지정된 principal은 HDFS impersonation 섹션에서 설명한 대로 현재 Trino 사용자를 가장하도록 허용되어야 해요.
Keytab 파일은 Trino 클러스터의 모든 노드에 배포되어야 해요.
AWS Glue 카탈로그 구성 프로퍼티 (AWS Glue catalog configuration properties)
AWS Glue 카탈로그를 사용하려면 카탈로그 파일을 다음과 같이 구성해야 해요.
hive.metastore=glue, 그리고 다음 프로퍼티로 추가 세부 사항을 제공해요.
| 프로퍼티 이름 | 설명 | 기본값 |
|---|---|---|
hive.metastore.glue.region |
Glue Catalog의 AWS 리전. EC2에서 실행하지 않거나 카탈로그가 다른 리전에 있을 때 필요. 예: us-east-1. |
|
hive.metastore.glue.endpoint-url |
Glue API 엔드포인트 URL(선택). 예: https://glue.us-east-1.amazonaws.com. |
|
hive.metastore.glue.sts.region |
인증할 STS 서비스의 AWS 리전. GovCloud 리전에서 실행할 때 필요. 예: us-gov-east-1. |
|
hive.metastore.glue.sts.endpoint |
Glue에 인증할 때 사용할 STS 엔드포인트 URL(선택). 예: https://sts.us-gov-east-1.amazonaws.com. |
|
hive.metastore.glue.pin-client-to-current-region |
Glue 요청을 Trino가 실행되는 EC2 인스턴스와 같은 리전으로 고정해요. | false |
hive.metastore.glue.max-connections |
Glue에 대한 동시 연결의 최대 수. | 30 |
hive.metastore.glue.max-error-retries |
Glue 클라이언트의 최대 오류 재시도 횟수. | 10 |
hive.metastore.glue.default-warehouse-dir |
명시적 location 프로퍼티 없이 생성된 스키마의 기본 웨어하우스 디렉토리. |
|
hive.metastore.glue.use-web-identity-token-credentials-provider |
Amazon EKS에서 Trino를 실행하고 Kubernetes service account로 인증한다면 이 프로퍼티를 true로 설정할 수 있어요. true로 설정하면 Trino가 기본 자격 증명 제공자 체인의 다른 자격 증명 제공자를 시도하지 않고, service account의 자격 증명을 직접 사용하게 돼요. |
false |
hive.metastore.glue.aws-access-key |
Glue Catalog에 연결할 때 사용할 AWS access key. hive.metastore.glue.aws-secret-key와 함께 지정되면 이 파라미터가 hive.metastore.glue.iam-role보다 우선해요. |
|
hive.metastore.glue.aws-secret-key |
Glue Catalog에 연결할 때 사용할 AWS secret key. hive.metastore.glue.aws-access-key와 함께 지정되면 이 파라미터가 hive.metastore.glue.iam-role보다 우선해요. |
|
hive.metastore.glue.catalogid |
메타데이터 데이터베이스가 있는 Glue Catalog의 ID. | |
hive.metastore.glue.iam-role |
Glue Catalog에 연결할 때 맡을 IAM 역할의 ARN. | |
hive.metastore.glue.external-id |
Glue Catalog에 연결할 때 IAM 역할 신뢰 정책의 외부 ID. | |
hive.metastore.glue.partitions-segments |
파티셔닝된 Glue 테이블의 세그먼트 수. | 5 |
hive.metastore.glue.skip-archive |
AWS Glue는 이전 테이블 버전을 보관(archive)할 수 있고, 필요시 테이블을 이전 버전으로 롤백할 수 있어요. 기본적으로 Glue가 뒷받침하는 Hive 커넥터는 이전 테이블 버전의 보관을 건너뛰지 않아요. | false |
Iceberg 전용 Glue 카탈로그 구성 프로퍼티 (Iceberg-specific Glue catalog configuration properties)
Glue 카탈로그를 사용할 때 Iceberg 커넥터는 앞서 설명한 일반 Glue 구성 프로퍼티와 함께 다음 추가 프로퍼티를 지원해요.
| 프로퍼티 이름 | 설명 | 기본값 |
|---|---|---|
iceberg.glue.cache-table-metadata |
AWS Glue에서 테이블을 업데이트하는 동안, information_schema.columns와 system.metadata.table_comments 쿼리를 가속화하는 목적으로 테이블 메타데이터를 저장해요. |
true |
Iceberg 전용 메타스토어 (Iceberg-specific metastores)
Iceberg 테이블 형식은 대부분의 메타데이터를 객체 스토리지 자체의 메타데이터 파일에서 관리해요. 하지만 소량의 메타데이터는 여전히 메타스토어 사용이 필요해요. Iceberg 생태계에서 이 더 작은 메타스토어를 Iceberg 메타데이터 카탈로그, 또는 그냥 카탈로그라고 불러요.
HMS나 AWS Glue 같은 일반 메타스토어를 사용하거나, 이 섹션에서 설명하는 Iceberg 전용 REST, Nessie, JDBC 메타데이터 카탈로그를 사용할 수 있어요.
REST 카탈로그
Iceberg REST 카탈로그를 사용하려면 iceberg.catalog.type=rest로 카탈로그 타입을 구성하고 다음 프로퍼티로 추가 세부 사항을 제공해요.
| 프로퍼티 이름 | 설명 |
|---|---|
iceberg.rest-catalog.uri |
REST 서버 API 엔드포인트 URI(필수). 예: http://iceberg-with-rest:8181. |
iceberg.rest-catalog.prefix |
REST 카탈로그 서버에 사용할 리소스 경로의 접두사(선택). 예: dev. |
iceberg.rest-catalog.warehouse |
카탈로그의 웨어하우스 식별자/위치(선택). 예: s3://my_bucket/warehouse_location. |
iceberg.rest-catalog.security |
사용할 보안 타입(기본: NONE). 가능한 값은 NONE, SIGV4, GOOGLE, OAUTH2. OAUTH2는 token 또는 credential이 필요해요. |
iceberg.rest-catalog.session |
REST Catalog와 통신할 때 포함되는 세션 정보. 옵션은 NONE 또는 USER(기본: NONE). |
iceberg.rest-catalog.connection-timeout |
소켓 연결 요청이 타임아웃되기 전에 완료될 수 있는 최대 시간. |
iceberg.rest-catalog.socket-timeout |
소켓 읽기·쓰기 작업이 타임아웃되기 전의 최대 시간. |
iceberg.rest-catalog.session-timeout |
인증 세션을 캐시에 유지하는 시간. 기본값은 1h. |
iceberg.rest-catalog.oauth2.token |
서버와의 상호작용에 사용되는 bearer token. OAUTH2 보안에는 token 또는 credential이 필요. 예: AbCdEf123456. |
iceberg.rest-catalog.oauth2.credential |
서버와의 OAuth2 client credentials 플로우에서 토큰으로 교환할 자격 증명. OAUTH2 보안에는 token 또는 credential이 필요. 예: AbCdEf123456. |
iceberg.rest-catalog.oauth2.scope |
REST Catalog와 통신할 때 사용할 scope. credential을 사용할 때만 적용. |
iceberg.rest-catalog.oauth2.server-uri |
OAuth2 서버에서 access token을 가져올 엔드포인트. |
iceberg.rest-catalog.oauth2.token-refresh-enabled |
만료 시간 정보를 사용할 수 있으면 토큰을 새로 고칠지 제어. 기본값은 true. |
iceberg.rest-catalog.oauth2.token-exchange-enabled |
새 토큰을 획득할 때 token exchange 플로우를 사용할지 제어. 기본값은 true. |
iceberg.rest-catalog.vended-credentials-enabled |
파일시스템 접근에 REST 백엔드가 제공하는 자격 증명을 사용해요. 기본값은 false. |
iceberg.rest-catalog.nested-namespace-enabled |
중첩 네임스페이스 아래의 객체 쿼리 지원. 기본값은 false. |
iceberg.rest-catalog.view-endpoints-enabled |
뷰 엔드포인트 활성화. 기본값은 true. |
iceberg.rest-catalog.signing-name |
AWS SigV4 서명 서비스 이름. 기본값은 execute-api. |
iceberg.rest-catalog.google-project-id |
Google Cloud 프로젝트 이름. iceberg.rest-catalog.security 구성 프로퍼티가 GOOGLE로 설정될 때 이 프로퍼티를 설정해야 해요. 예: development-123456. |
iceberg.rest-catalog.case-insensitive-name-matching |
네임스페이스·테이블·뷰 이름을 대소문자 구분 없이 매칭. 기본값은 false. |
iceberg.rest-catalog.case-insensitive-name-matching.cache-ttl |
대소문자 구분 없는 네임스페이스·테이블·뷰 이름이 캐시되는 시간. 기본값은 1m. |
iceberg.rest-catalog.http-headers |
REST 카탈로그에 보내는 요청에 포함할 추가 비민감 HTTP 헤더. 예: Header-1: value 1, Header-2: value 2. |
다음 예시는 Iceberg REST 메타데이터 카탈로그를 사용하는 최소 카탈로그 구성을 보여 줘요.
connector.name=iceberg
iceberg.catalog.type=rest
iceberg.rest-catalog.uri=http://iceberg-with-rest:8181
Iceberg REST 카탈로그로 Databricks Unity catalog에 연결할 때 iceberg.security는 read_only여야 해요.
connector.name=iceberg
iceberg.catalog.type=rest
iceberg.rest-catalog.uri=https://dbc-12345678-9999.cloud.databricks.com/api/2.1/unity-catalog/iceberg
iceberg.security=read_only
iceberg.rest-catalog.security=OAUTH2
iceberg.rest-catalog.oauth2.token=***
Iceberg REST 카탈로그로 BigLake metastore에 연결할 때 iceberg.rest-catalog.security는 GOOGLE이어야 해요.
connector.name=iceberg
iceberg.catalog.type=rest
iceberg.unique-table-location=false
iceberg.rest-catalog.warehouse=gs://example-bucket
iceberg.rest-catalog.uri=https://biglake.googleapis.com/iceberg/v1beta/restcatalog
iceberg.rest-catalog.security=GOOGLE
iceberg.rest-catalog.google-project-id=example-project-id
iceberg.rest-catalog.view-endpoints-enabled=false
fs.gcs.enabled=true
gcs.json-key-file-path=/path/to/gcs_keyfile.json
gcs.json-key-file-path는 선택적이에요. 생략하면 Application Default Credentials(ADC)가 사용되며, 이는 GKE Workload Identity와 환경 기반 자격 증명 소스를 지원해요.
REST 카탈로그는 Iceberg View 스펙을 사용한 뷰 관리를 지원해요. REST 카탈로그는 구체화된 뷰(materialized view) 관리를 지원하지 않아요.
JDBC 카탈로그
Iceberg JDBC 카탈로그는 Iceberg 커넥터에서 지원돼요. 최소한 iceberg.jdbc-catalog.driver-class, iceberg.jdbc-catalog.connection-url, iceberg.jdbc-catalog.default-warehouse-dir, iceberg.jdbc-catalog.catalog-name을 구성해야 해요. PostgreSQL 이외의 데이터베이스를 사용할 때는 JDBC driver jar 파일을 플러그인 디렉토리에 두어야 해요.
| 프로퍼티 이름 | 설명 |
|---|---|
iceberg.jdbc-catalog.driver-class |
JDBC 드라이버 클래스 이름. |
iceberg.jdbc-catalog.connection-url |
JDBC 서버에 연결할 URI. |
iceberg.jdbc-catalog.connection-user |
JDBC 클라이언트의 사용자 이름. |
iceberg.jdbc-catalog.connection-password |
JDBC 클라이언트의 비밀번호. |
iceberg.jdbc-catalog.catalog-name |
Iceberg JDBC metastore 카탈로그 이름. |
iceberg.jdbc-catalog.default-warehouse-dir |
JDBC에 사용할 기본 웨어하우스 디렉토리. |
iceberg.jdbc-catalog.schema-version |
JDBC 카탈로그 스키마 버전. 유효 값은 V0 또는 V1. 기본값은 V1. |
iceberg.jdbc-catalog.retryable-status-codes |
JDBC metastore에 연결 오류가 발생하면, 이 JDBC 상태 코드 중 하나라면 재시도해요. 유효 값은 상태 코드의 쉼표로 구분된 목록. 참고: JDBC 카탈로그는 항상 08000,08003,08006,08007,40001 상태 코드를 재시도해요. 여기에는 추가 코드(PostgreSQL 드라이버를 사용하면 57000,57P03,57P04 등)만 지정해요. |
⚠️ 경고: Iceberg가 향후 호환성을 깨는 변경을 도입하면 JDBC 카탈로그에 호환성 문제가 있을 수 있어요. 대안으로 REST 카탈로그를 고려하세요.
JDBC 카탈로그는 메타데이터 테이블이 이미 존재해야 해요. 테이블 생성은 Iceberg 저장소를 참고하세요.
다음 예시는 Iceberg JDBC 메타데이터 카탈로그를 사용하는 최소 카탈로그 구성을 보여 줘요.
connector.name=iceberg
iceberg.catalog.type=jdbc
iceberg.jdbc-catalog.catalog-name=test
iceberg.jdbc-catalog.driver-class=org.postgresql.Driver
iceberg.jdbc-catalog.connection-url=jdbc:postgresql://example.net:5432/database
iceberg.jdbc-catalog.connection-user=admin
iceberg.jdbc-catalog.connection-password=test
iceberg.jdbc-catalog.default-warehouse-dir=s3://bucket
JDBC 카탈로그는 구체화된 뷰 관리를 지원하지 않아요.
Nessie 카탈로그
Nessie 카탈로그를 사용하려면 iceberg.catalog.type=nessie로 카탈로그 타입을 구성하고 다음 프로퍼티로 추가 세부 사항을 제공해요.
| 프로퍼티 이름 | 설명 |
|---|---|
iceberg.nessie-catalog.uri |
Nessie API 엔드포인트 URI(필수). 예: https://localhost:19120/api/v2. |
iceberg.nessie-catalog.ref |
Nessie에 사용할 branch/tag. 기본값은 main. |
iceberg.nessie-catalog.default-warehouse-dir |
명시적 location 프로퍼티 없이 생성된 스키마의 기본 웨어하우스 디렉토리. 예: /tmp. |
iceberg.nessie-catalog.read-timeout |
Nessie 서버에 대한 요청의 읽기 타임아웃. 기본값은 25s. |
iceberg.nessie-catalog.connection-timeout |
Nessie 서버에 대한 연결 요청의 연결 타임아웃. 기본값은 5s. |
iceberg.nessie-catalog.enable-compression |
Nessie 서버에 대한 요청에 압축을 활성화할지 여부 구성. 기본값은 true. |
iceberg.nessie-catalog.authentication.type |
사용할 인증 타입. 사용 가능한 값은 BEARER. 기본적으로 인증 없음. |
iceberg.nessie-catalog.authentication.token |
BEARER 인증에 사용할 토큰. 예: SXVLUXUhIExFQ0tFUiEK. |
iceberg.nessie-catalog.client-api-version |
사용할 클라이언트 API 버전(선택). 기본적으로 iceberg.nessie-catalog.uri 값에서 추론돼요. 유효 값은 V1 또는 V2. |
connector.name=iceberg
iceberg.catalog.type=nessie
iceberg.nessie-catalog.uri=https://localhost:19120/api/v2
iceberg.nessie-catalog.default-warehouse-dir=/tmp
Nessie 카탈로그는 뷰 관리와 구체화된 뷰 관리를 지원하지 않아요.
Snowflake 카탈로그
Snowflake 카탈로그를 사용하려면 iceberg.catalog.type=snowflake로 카탈로그 타입을 구성하고 다음 프로퍼티로 추가 세부 사항을 제공해요.
| 프로퍼티 이름 | 설명 |
|---|---|
iceberg.snowflake-catalog.account-uri |
Snowflake JDBC 계정 URI(필수). 예: jdbc:snowflake://example123456789.snowflakecomputing.com. |
iceberg.snowflake-catalog.user |
Snowflake 사용자(필수). |
iceberg.snowflake-catalog.password |
Snowflake 비밀번호(필수). |
iceberg.snowflake-catalog.database |
Snowflake 데이터베이스 이름(필수). |
iceberg.snowflake-catalog.role |
Snowflake 역할 이름. |
connector.name=iceberg
iceberg.catalog.type=snowflake
iceberg.snowflake-catalog.account-uri=jdbc:snowflake://example1234567890.snowflakecomputing.com
iceberg.snowflake-catalog.user=user
iceberg.snowflake-catalog.password=secret
iceberg.snowflake-catalog.database=db
Snowflake 카탈로그를 사용할 때, 테이블 생성 같은 데이터 관리 작업은 Snowflake에서 수행해야 해요. Trino 같은 외부 시스템에서 카탈로그를 사용하면 SELECT 쿼리와 다른 읽기 작업만 지원되기 때문이에요.
또한 Snowflake가 만든 Iceberg 테이블은 파티셔닝 정보를 노출하지 않아 효율적인 병렬 읽기를 막고, 따라서 상당한 성능 저하가 있을 수 있어요.
Snowflake 카탈로그는 뷰 관리와 구체화된 뷰 관리를 지원하지 않아요. 자세한 내용은 Snowflake 카탈로그 문서를 참고하세요.
Athena 파티션 프로젝션 메타데이터가 있는 테이블 접근 (Access tables with Athena partition projection metadata)
파티션 프로젝션(partition projection)은 AWS Athena의 기능으로, Hive 커넥터를 사용할 때 고도로 파티셔닝된 테이블의 쿼리 처리를 빠르게 하는 데 자주 쓰여요.
Trino는 Hive metastore 또는 Glue 카탈로그에 저장된 파티션 프로젝션 테이블 프로퍼티를 지원하고, 이 기능을 다시 구현해요. 현재 AWS Athena와 비교해 date projection에 제한이 있는데, DAYS, HOURS, MINUTES, SECONDS 간격만 지원해요.
파티션 프로젝션이 활성화된 테이블에 접근을 막는 호환성 문제가 있다면, 테이블에 partition_projection_ignore 테이블 프로퍼티를 true로 설정해 오류를 우회해요.
파티션 프로젝션 구성은 Table properties와 Column properties 문서를 참고하세요.
Avro용 메타스토어 구성 (Configure metastore for Avro)
Hive 커넥터를 사용하는 카탈로그의 경우, Hive 3.x 사용 시 Avro 테이블에 대한 일급 지원을 활성화하려면 Hive metastore 구성 파일 hive-site.xml에 다음 프로퍼티 정의를 추가하고 metastore 서비스를 재시작해야 해요.
<property>
<!-- https://community.hortonworks.com/content/supportkb/247055/errorjavalangunsupportedoperationexception-storage.html -->
<name>metastore.storage.schema.reader.impl</name>
<value>org.apache.hadoop.hive.metastore.SerDeStorageSchemaReader</value>
</property>
더 알아보기 (Learn more)
메타스토어로 객체 스토리지 메타데이터를 관리하는 방법을 배웠어요. 이어서 객체 스토리지 파일 형식(Object storage file formats)을 살펴보면 좋아요.