본문으로 건너뛰기
최종 수정: 에

메타데이터 캐시

요약 Apache Doris가 Hive, Iceberg, Hudi 또는 Paimon을 쿼리할 때 전체 소요 시간의 대부분이 파티션 목록 조회, 매니페스트 파싱, Hive Metastore 요청에 쓰일 수 있습니다. Apache Doris 메타데이터 캐시는 스키마, 파티션 값, 파일 목록, Iceberg 매니페스트 항목, Paimon 스냅샷을 모두 저장합니다. 캐시에는 TTL이 적용되며(기본값: 이름 목록은 24시간, 파티션과 파일은 8시간), Hive Metastore 이벤트를 통해 초 단위 지연으로 갱신할 수 있습니다. 또한 REFRESH CATALOG로 명시적으로 무효화할 수 있습니다. Iceberg와 Paimon에는 포맷별 특성을 반영한 무효화가 적용되므로, 불변 매니페스트는 계속 참조되는 동안 캐시에 유지됩니다.

Apache Doris 메타데이터 캐시: 외부 Catalog 메타데이터를 위한 다층 캐시로, 테이블 목록, 스키마, 파티션, 파일 목록, Iceberg 매니페스트를 캐싱하여 쿼리 계획 시간을 ms 단위로 유지합니다.

Apache Doris 메타데이터 캐시를 사용하는 이유는 무엇인가요?​

Apache Doris 메타데이터 캐시는 전체 소요 시간의 대부분을 차지하는 HMS 왕복 요청, S3/HDFS LIST, Iceberg 매니페스트 읽기를 캐시로 처리하여 레이크하우스 쿼리 계획 시간을 초 단위에서 밀리초 단위로 줄입니다. 레이크하우스 쿼리 계획 시간은 데이터보다 메타데이터에 좌우됩니다. 파티셔닝된 Hive 테이블을 쿼리하려면 다음 작업이 필요합니다.

  • Hive Metastore에 왕복 요청을 보내 데이터베이스 목록, 테이블 목록, 컬럼 스키마, 파티션 목록을 가져옵니다.
  • 필터링 후 남은 각 파티션 경로에 S3 또는 HDFS LIST를 요청하여 데이터 파일을 찾습니다.
  • Iceberg의 경우 metadata.json, 매니페스트 목록, N개의 매니페스트 파일을 차례로 읽습니다(각 파일당 원격 읽기 한 번).
  • Hudi의 경우 타임라인을 가져오고, FileSystemView를 구성한 다음, 쿼리 시점에 어떤 파일 슬라이스가 보이는지 확인합니다.

캐시가 준비되지 않은 Catalog에 파티션이 10K개 있다면 실행보다 계획에 더 오래 걸릴 수 있습니다. 흔히 다음과 같은 상황이 발생합니다.

  • 날짜로 필터링하는 대시보드가 매분 플래너에서 파티션을 새로 조회하여, HMS가 감당하지 못할 때까지 요청을 쏟아냅니다.
  • 매니페스트가 30개인 Iceberg 테이블은 쿼리마다 데이터 읽기에 더해 매니페스트 메타데이터를 가져오는 S3 GET 요청을 30번 수행합니다.
  • 배포 후 새 FE가 시작되면 첫 쿼리들이 getPartitionsByNames에서 수 초를 소비합니다.

메타데이터 캐시는 이 모든 요청을 처리하며, 원본이 실제로 변경될 때마다 갱신 경로를 통해 정확한 상태를 복구합니다.

Apache Doris 메타데이터 캐시란 무엇인가요?​

Apache Doris 메타데이터 캐시는 파일의 바이트 데이터 자체를 제외하고 외부 Catalog가 제공하는 모든 정보를 저장하는 FE의 인메모리 캐시입니다. 각 백엔드(Hive, Iceberg, Hudi, Paimon, JDBC)는 공통 프레임워크를 자체적으로 구현하므로, 사용자는 일관된 모델을 사용할 수 있습니다. 이 모델은 캐시별 TTL, 캐시별 크기 제한, 소수의 기본 갱신 연산으로 구성됩니다.

주요 용어

  • Schema cache: 컬럼 목록, 타입, 테이블 식별 정보를 저장합니다. 테이블 식별자와 스키마 ID(Iceberg/Paimon의 경우)를 키로 사용합니다.
  • Partition cache: 파티션 값과 위치를 포함한 Hive 또는 Hudi 테이블의 파티션 목록입니다.
  • File cache (FE-side): S3/HDFS LIST로 채워지는 파티션 경로의 파일 목록과 기본 파일 메타데이터입니다. BE 측 Data Cache와 구분됩니다.
  • Manifest cache: 파싱된 Iceberg 매니페스트 항목입니다(매니페스트에 속한 데이터 파일과 삭제 파일의 목록). TTL이 아닌 항목 수로 제한됩니다.
  • HMS event listener: Hive Metastore 알림 이벤트를 소비하고 영향을 받는 항목을 증분 방식으로 무효화하는 폴링 클라이언트입니다.

Apache Doris 메타데이터 캐시는 어떻게 동작하나요?​

모든 Apache Doris 쿼리는 외부 RPC를 보내기 전에 캐시를 거칩니다. 조회, TTL에 따른 제거, 크기에 따른 제거, 포맷별 특성을 반영한 무효화, HMS 이벤트 폴링, 명시적 REFRESH가 함께 동작하여 자주 사용하는 메타데이터는 메모리에 유지하고 오래된 항목은 제거합니다.

  1. 조회. 플래너가 테이블의 스키마, 파티션 또는 파일을 요청하면 Caffeine 기반 로더를 사용하여 먼저 캐시를 확인합니다. 캐시 미스가 발생하면 기반 Catalog에서 데이터를 가져오고(HMS Thrift 호출, Iceberg 메타데이터 읽기, Hudi 타임라인 스캔) 결과를 저장합니다.
  2. TTL에 따른 제거. 각 캐시 모듈에는 자체 TTL이 있습니다. 3.0.7 이후에는 접근할 때마다 타이머가 재설정되므로, 자주 사용하는 테이블은 계속 쿼리되는 동안 캐시에 유지됩니다. 기본값은 보수적으로 설정되어 있습니다. 이름 목록은 TTL이 24시간이고 갱신 간격이 10분이며, 파티션 및 파일 캐시의 TTL은 8시간입니다.
  3. 크기에 따른 제거. 캐시는 크기 제한(max_external_schema_cache_num, max_external_file_cache_num 등) 내에서 LRU를 사용하므로, 드물게 사용되는 수많은 테이블이 자주 사용하는 테이블을 계속 밀어내지 못합니다.
  4. 포맷별 특성을 반영한 무효화. Iceberg 매니페스트 캐시 항목은 매니페스트 경로를 키로 사용하며 TTL 없이 유지됩니다. 한 번 파싱된 매니페스트는 어떤 스냅샷에서든 계속 참조하는 한 유효합니다. Paimon은 최신 스냅샷 참조를 캐싱하고 테이블이 다음 상태로 변경될 때만 다시 로드합니다. Hive는 이 방식을 사용할 수 없으므로 HMS 이벤트가 그 빈틈을 메웁니다.
  5. HMS 이벤트 기반 갱신. enable_hms_events_incremental_sync가 활성화되면 FE는 hms_events_polling_interval_ms 간격으로 Hive Metastore 알림 로그를 폴링하고 CREATE / ALTER / DROP / INSERT 이벤트를 재생합니다. 전체 캐시를 비우지 않고도 영향을 받는 항목을 수 초 내에 무효화합니다.
  6. 명시적 갱신. REFRESH CATALOG, REFRESH DATABASE, REFRESH TABLE은 HMS를 거치지 않는 쓰기(직접 파일 업로드, Apache Doris 외부에서 수행한 Iceberg 커밋)에 대응하거나 테스트할 때 사용할 수 있습니다.

일반 경로에서는 메모리 접근 수준의 지연 시간으로 메타데이터를 제공합니다. 복구 경로에서는 원본이 변경되면 수 초 내에 이를 따라잡습니다.

빠른 시작​

-- Inspect cache state.
SELECT * FROM information_schema.catalog_meta_cache_statistics
WHERE catalog_name = 'hive_ctl';

-- Refresh just the table whose partition you just added.
REFRESH TABLE hive_ctl.sales.orders;

-- For a fast-changing fact table, disable the file listing cache.
ALTER CATALOG hive_ctl SET PROPERTIES (
  "meta.cache.hive.file.ttl-second" = "0"
);

-- For seconds-level auto-refresh on Hive, turn on the HMS event listener
-- (FE config; restart required):
--   enable_hms_events_incremental_sync = true
--   hms_events_polling_interval_ms = 10000

예상 결과

+--------------+-------------+-----------+---------+----------+
| catalog_name | cache_name  | hit_count | miss_count | size  |
+--------------+-------------+-----------+---------+----------+
| hive_ctl     | schema      |     12480 |       7 |       42 |
| hive_ctl     | partition   |      9821 |      14 |       28 |
| hive_ctl     | file        |      9520 |      31 |      612 |
+--------------+-------------+-----------+---------+----------+

캐시가 준비된 후에는 스키마 및 파티션 캐시의 적중률이 99%를 넘습니다. 캐시 미스는 새 테이블에 처음 접근하거나 항목이 만료되었을 때 발생합니다.

Apache Doris 메타데이터 캐시는 언제 사용해야 하나요?​

Apache Doris 메타데이터 캐시는 모든 외부 Catalog에서 기본적으로 활성화되어 있습니다. 실제로 고려할 점은 워크로드 유형별로 어떻게 조정하고, 어떤 경우에 완전히 비활성화할지입니다.

적합한 경우

  • 스키마가 안정적이고 쓰기 빈도가 적당한 Hive 테이블. 기본 TTL과 HMS 이벤트 리스너를 함께 사용하면 초 단위의 최신성을 유지할 수 있습니다.
  • 모든 규모의 Iceberg, Paimon, Hudi 테이블. 스냅샷의 불변성 덕분에 매니페스트 항목을 캐시에 무기한 유지할 수 있습니다. 무효화가 필요한 것은 현재 스냅샷 포인터뿐이며, Apache Doris가 쿼리마다 이를 처리합니다.
  • 수천 개의 Catalog와 테이블이 있는 멀티 테넌트 레이크하우스. 스키마 및 파티션 캐시는 드물게 사용하는 수많은 객체가 메모리 용량을 초과하더라도 계획 시간을 짧게 유지합니다. 자주 사용하는 항목은 남고 드물게 사용하는 항목은 제거됩니다.
  • 동시 쿼리가 많은 대시보드. 캐시가 없으면 동시에 실행되는 모든 쿼리가 같은 파티션의 목록을 다시 조회합니다. 캐시가 있으면 목록을 한 번만 구성하여 공유합니다.

적합하지 않은 경우

  • HMS 외부에서 쓰기가 이루어지는 Hive 테이블(hadoop fs -put, S3 직접 업로드). HMS는 변경을 감지하지 못하므로 이벤트 리스너도 이를 포착할 수 없습니다. 쓰기가 HMS를 거치도록 하거나, 파일 캐시 TTL을 0으로 설정하거나, 각 배치 작업 후 REFRESH TABLE을 호출하세요.
  • 몇 초마다 변경되며 엄격한 최신성을 요구하는 테이블. TTL 기반 캐시는 적합하지 않습니다. 해당 테이블의 관련 캐시 모듈을 비활성화하거나(ttl-second = 0), 이벤트 리스너로 인해 최대 N초 동안 오래된 상태가 유지될 수 있음을 수용해야 합니다.
  • 메모리가 부족한 환경에서 수백만 개의 테이블을 포함하는 Catalog. max_external_schema_cache_num을 FE 힙이 감당할 수 있는 수준 이상으로 늘리면 OOM이 발생할 수 있습니다. 제한을 적절히 설정하고 catalog_meta_cache_statistics를 모니터링하세요.
  • Iceberg를 Hive처럼 취급하는 경우. Iceberg에서 매분 REFRESH CATALOG를 실행하면 완전히 유효한 불변 매니페스트 항목까지 버리게 됩니다. 스냅샷 모델을 신뢰하고 캐시가 제 역할을 하도록 두세요.

더 읽어보기​

  • 메타데이터 캐시 참조 문서: 모듈별 TTL, 크기 제한, 갱신 전략에 대한 상세 설명입니다.
  • REFRESH 문: REFRESH CATALOG, REFRESH DATABASE, REFRESH TABLE의 SQL 구문과 invalid_cache 속성을 설명합니다.
  • Hive Catalog: 캐시별 meta.cache.* 속성과 HMS 이벤트 리스너 설정(enable_hms_events_incremental_sync)을 설명합니다.
  • Iceberg Catalog: 매니페스트 캐시 설정과 스냅샷을 고려한 무효화를 설명합니다.
  • Data Cache 및 Page Cache: 메타데이터 캐시 아래에 위치한 바이트 단위의 스토리지 캐시를 설명합니다.
  • Parquet 리더 최적화: 메타데이터로 읽을 파일을 결정한 후, 해당 파일을 효율적으로 읽는 방법을 설명합니다.
  • 차세대 데이터 레이크하우스 구축(Apache Doris 블로그): Meta Cache와 HMS 이벤트 리스너를 소개하는 아키텍처 개요입니다.
  • Iceberg: 원격 객체 스토리지에서 매니페스트 목록과 스냅샷 메타데이터가 메타데이터 캐시의 이점을 가장 크게 누리는 Catalog를 설명합니다.
Report issue