Iceberg 확장

druid-iceberg-extensions 확장을 이용하면 Apache Iceberg 테이블 포맷에 저장된 데이터를 Apache Druid로 수집할 수 있어요. IcebergInputSource가 Iceberg 카탈로그에서 테이블과 데이터 파일을 읽어오는 구조예요.

출처: 문서

본문

Iceberg Ingest extension

Apache Iceberg는 거대한 분석 데이터셋을 위한 오픈 테이블 포맷이에요. IcebergInputSource는 Iceberg 테이블 포맷에 저장된 데이터를 Apache Druid로 수집해요. Iceberg 확장을 사용하려면 로드된 확장 목록에 druid-iceberg-extensions를 추가해 주세요. 자세한 내용은 Loading extensions를 참고해요.

Iceberg는 대부분의 메타데이터를 오브젝트 스토리지의 메타데이터 파일로 관리해요. 하지만 특정 양의 메타데이터를 관리하기 위해 여전히 metastore에 의존해요. Iceberg는 이런 metastore를 카탈로그(catalog)라고 불러요. Iceberg 확장은 다음 Iceberg 카탈로그 타입에 연결할 수 있어요.

Glue catalog
REST-based catalog
Hive metastore catalog
Local catalog

주어진 카탈로그에 대해 Iceberg 입력 소스는 카탈로그에서 테이블 이름을 읽고, 필터를 적용하며, 최신 스냅샷까지의 모든 기본 라이브 데이터 파일을 추출해요. 데이터 파일은 Parquet, ORC, Avro 포맷일 수 있어요. 데이터 파일은 대개 warehouse 위치(주로 HDFS, S3, 또는 로컬 파일시스템)에 있어요. druid-iceberg-extensions 확장은 warehouse에서 데이터 파일을 읽는 데 Druid의 기존 입력 소스 커넥터를 사용해요. 그래서 Iceberg 입력 소스는 다른 입력 소스 구현에 파일 경로를 제공하는 중간 입력 소스(intermediate input source)로 볼 수 있어요.

Hive metastore catalog

Druid가 Hive metastore와 잘 통신하려면 hive-site.xml, core-site.xml 같은 Hive 구성 파일이 peon 프로세스의 Druid classpath에 있어야 해요. 수집 스펙의 catalogProperties 오브젝트 아래에 Hive 속성을 지정할 수도 있어요.

druid-iceberg-extensions 확장은 현재 HDFS, S3, GCS, 로컬 warehouse 디렉터리를 지원해요.

HDFS warehouse 읽기

HDFS warehouse에서 읽으려면 druid-hdfs-storage 확장을 로드해 주세요. Druid는 Hive metastore 카탈로그에서 데이터 파일 경로를 추출하고 HDFS 입력 소스로 이 파일들을 수집해요. 수집 스펙의 warehouseSource 타입은 hdfs여야 해요.

Kerberos화된 클러스터로 인증하려면 catalogProperties 오브젝트에 principal과 keytab 속성을 포함해 주세요.

"catalogProperties": {
  "principal": "krb_principal",
  "keytab": "/path/to/keytab"
}

현재는 Kerberos 기반 인증만 지원돼요.

S3 warehouse 읽기

S3 warehouse에서 읽으려면 druid-s3-extensions 확장을 로드해 주세요. Druid는 Hive metastore 카탈로그에서 데이터 파일 경로를 추출하고 S3InputSource로 이 파일들을 수집해요. 수집 스펙에서 warehouseSource 오브젝트의 type 속성을 s3로 설정해 주세요. warehouse용 S3 엔드포인트가 딥 스토리지로 구성된 엔드포인트와 다르다면, warehouseSource 오브젝트에 다음 속성들을 포함해 S3 엔드포인트 설정을 정의해요.

"warehouseSource": {
  "type": "s3",
  "endpointConfig": {
    "url": "S3_ENDPOINT_URL",
    "signingRegion": "us-east-1"
  },
  "clientConfig": {
    "protocol": "http",
    "disableChunkedEncoding": true,
    "enablePathStyleAccess": true,
    "crossRegionAccessEnabled": false
  },
  "properties": {
    "accessKeyId": {
      "type": "default",
      "password": "<ACCESS_KEY_ID"
    },
    "secretAccessKey": {
      "type": "default",
      "password": "<SECRET_ACCESS_KEY>"
    }
  }
}

이 확장은 Hadoop AWS 모듈로 S3에 연결해 메타데이터와 데이터 파일 경로를 가져와요. catalogProperties에 다음 속성들이 필요해요.

"catalogProperties": {
  "fs.s3a.access.key" : "S3_ACCESS_KEY",
  "fs.s3a.secret.key" : "S3_SECRET_KEY",
  "fs.s3a.endpoint" : "S3_API_ENDPOINT"
}

Hadoop AWS 커넥터가 s3a 파일시스템 클라이언트를 사용하므로, warehouse 경로를 s3://가 아닌 s3a:// 프로토콜로 지정해 주세요.

GCS warehouse 읽기

GCS warehouse에서 읽으려면 druid-google-extensions 확장을 로드해 주세요. Druid는 카탈로그에서 데이터 파일 경로를 추출하고 GoogleCloudStorageInputSource로 이 파일들을 수집해요. 수집 스펙에서 warehouseSource 오브젝트의 type 속성을 google로 설정해 주세요.

"warehouseSource": {
  "type": "google"
}

Iceberg 카탈로그가 GCS에서 자체 메타데이터 파일을 읽으려면 catalogProperties에 io-impl을 org.apache.iceberg.gcp.gcs.GCSFileIO로 설정해 주세요.

"catalogProperties": {
  "io-impl": "org.apache.iceberg.gcp.gcs.GCSFileIO",
  "gcs.project-id": "my-gcp-project",
  "warehouse": "gs://my-bucket/warehouse"
}

인증은 Application Default Credentials(ADC)를 사용해요. Druid 프로세스가 유효한 GCP 자격 증명(예: 서비스 계정 키 파일, workload identity, 또는 metadata server)에 접근할 수 있는지 확인해 주세요.

Local catalog

로컬 카탈로그 타입은 로컬 파일시스템에 구성된 카탈로그에 사용할 수 있어요. icebergCatalog 타입을 local로 설정해 주세요. 데모나 로컬 테스트에 사용할 수 있어요. 프로덕션 사용 사례에는 권장되지 않아요. 이 카탈로그는 로컬 파일시스템에서만 읽기를 지원하므로 warehouseSource는 local로 설정돼요.

REST catalog

Iceberg REST Catalog 서버에 연결하려면 icebergCatalog 타입을 rest로 구성해요. Iceberg REST Open API 스펙은 카탈로그가 구현에 대해 더 큰 제어권을 갖게 해 주고, 대부분의 경우 클라이언트가 warehousePath를 제공하지 않아도 돼요. 보안 자격 증명은 catalogProperties 오브젝트에 제공될 수 있어요.

Glue catalog

icebergCatalog 타입을 glue로 구성해요. warehousePath와 속성은 catalogProperties 오브젝트에 제공해야 해요. 속성 설정에 대해서는 Iceberg Glue Catalog 문서를 참고해 주세요.

Downloading Iceberg extension

druid-iceberg-extensions를 다운로드하려면 원하는 Druid 버전으로 <VERSION>을 바꾼 뒤 다음 명령을 실행해요.

java \
  -cp "lib/*" \
  -Ddruid.extensions.directory="extensions" \
  org.apache.druid.cli.Main tools pull-deps \
  -c "org.apache.druid.extensions.contrib:druid-iceberg-extensions:<VERSION>"

자세한 내용은 Loading community extensions를 참고해요.

Residual filter handling

Iceberg 필터가 비-파티션 열에 적용되면 필터링은 파일 메타데이터 수준(열 통계 사용)에서만 발생해요. 일치하는 행을 포함할 수 있는 파일이 반환되지만, 이 파일들에는 실제로 필터와 일치하지 않는 "잔여(residual)" 행이 포함될 수 있어요. 이 잔여 행들은 Druid 쪽의 transformSpec 필터로 걸러지지 않으면 수집돼요.

이 동작을 제어하려면 Iceberg 입력 소스에 residualFilterMode 속성을 설정할 수 있어요.

모드	설명
`ignore`	기본값. `transformSpec`으로 걸러지지 않으면 잔여 행이 경고 로그와 함께 수집돼요.
`fail`	잔여 필터가 감지되면 수집 작업을 실패시켜요. 필터가 파티션 열만 타겟팅하도록 하려면 이 모드를 사용해요.

예시:

{
  "type": "iceberg",
  "tableName": "events",
  "namespace": "analytics",
  "icebergCatalog": { ... },
  "icebergFilter": {
    "type": "timeWindow",
    "filterColumn": "event_time",
    "lookbackDuration": "P1D"
  },
  "residualFilterMode": "fail",
  "warehouseSource": { ... }
}

residualFilterMode가 fail로 설정되고 잔여 필터가 감지되면, 어떤 필터 표현식이 잔여를 만들었는지 알려주는 오류 메시지와 함께 작업이 실패해요. 의도하지 않은 행이 수집되는 것을 막아 데이터 품질을 보장하는 데 도움이 돼요.

Known limitations

이 섹션은 Iceberg 확장에 적용되는 알려진 제한 사항을 나열해요.

이 확장은 스냅샷이나 스키마 진화(schema evolution) 같은 Iceberg 기능을 완전히 활용하지 않아요.
Iceberg 입력 소스는 최신 스냅샷까지의 Iceberg 테이블에 있는 모든 라이브 파일을 하나하나 읽어서 테이블 스캔이 덜 성능적이에요. 가져오는 데이터 파일 수를 제한하려면 수집 스펙에서 파티션 열에 Iceberg 필터를 사용하는 걸 권장해요. Druid는 마지막으로 수집된 iceberg 스냅샷 ID를 저장하지 않으므로, 그 스냅샷과 Iceberg의 최신 스냅샷 사이에 생성된 파일을 식별할 수 없어요.
아직 Iceberg 스키마 진화를 처리하지 않아요. 기존 Iceberg 테이블 열이 삭제되고 같은 이름으로 다시 생성된 경우, 이 테이블을 Druid로 수집하면 삭제되기 전의 이 열 데이터도 가져올 수 있어요.
Hive 카탈로그는 Hadoop 2.x.x에서 테스트되지 않았고 Hadoop 2에서 동작한다는 보장이 없어요.

더 알아보기 (Learn more)

커뮤니티 확장 불러오기 방법은 Loading community extensions를 참고해 주세요.
유사한 테이블 포맷 확장으로 Delta Lake 확장도 참고해 보세요.
Iceberg 카탈로그 세부 설정은 Iceberg 문서에서 확인해 보세요.