RonJay
09/01/2026, 6:41 AMRocky
09/01/2026, 6:41 AM$files, $partitions) to the original table name. This provides "native" Iceberg information rather than StarRocks' internal cost-based statistics.
* View record counts and file sizes per partition:
sql
SELECT * FROM catalog.db.table$partitions;
* View per-file statistics (row counts, null counts, lower/upper bounds):
sql
SELECT * FROM catalog.db.table$files;
* View snapshot history:
sql
SELECT * FROM catalog.db.table$snapshots;
* View row counts in manifests:
sql
SELECT * FROM catalog.db.table$manifests;
2. StarRocks CBO Statistics
If you want to see the statistics that StarRocks' Optimizer (CBO) uses for query planning (which may include histograms or manually triggered analysis), use the following:
* Trigger manual collection:
StarRocks supports ANALYZE for Iceberg tables since v3.2.
sql
ANALYZE TABLE catalog.db.table_name;
* View collected statistics:
sql
SHOW STATISTICS FOR TABLE catalog.db.table_name;
Summary of Metadata Tables
Metadata Table | Useful Statistics
$partitions | record_count, file_count, total_data_file_size_in_bytes
$files | record_count, null_value_counts, lower_bounds, upper_bounds
$manifests | added_rows_count, existing_rows_count, deleted_rows_count
If you are using a version earlier than v3.4.1, you can only use SHOW STATISTICS after running an ANALYZE task, or rely on StarRocks' automatic sampling of Iceberg metadata during query time-of-query.
References
• data_source/catalog/iceberg/iceberg_meta_table.md
• data_source/feature-support-data-lake-analytics.mdRonJay
09/01/2026, 1:47 PMRocky
09/01/2026, 1:48 PMALTER CATALOG <iceberg_Catalog> SET ("enable_get_stats_from_external_metadata" = 'true') 설정을 통해 얻을 수 있는 주요 효과는 *Iceberg의 자체 메타데이터에 포함된 통계 정보를 StarRocks의 CBO(Cost-Based Optimizer)가 직접 활용할 수 있게 하는 것*입니다.
이 설정의 구체적인 효과와 장점은 다음과 같습니다.
1. 쿼리 최적화 성능 향상 (CBO 정밀도 개선)
* 효과: Iceberg의 매니페스트(Manifest) 파일이나 AWS Glue 등에 저장된 통계 정보(행 수, 컬럼별 Min/Max, Null 개수 등)를 StarRocks 옵티마이저가 즉시 참조합니다.
* 결과: 통계 정보가 없을 때보다 훨씬 더 정확한 실행 계획(Query Plan)을 생성합니다. 특히 Join 순서 결정(Join Reordering), Join 방식(Broadcast vs Shuffle) 선택 시 최적의 경로를 선택할 확률이 높아집니다.
2. ANALYZE 작업 없이 통계 확보
* 효과: 일반적으로 외부 테이블의 통계 정보를 얻으려면 StarRocks에서 ANALYZE TABLE 명령을 수동으로 실행하여 데이터를 스캔해야 합니다.
* 결과: 이 옵션을 켜면 데이터 파일을 직접 스캔하는 무거운 작업 없이도 Iceberg가 이미 가진 메타데이터에서 통계치를 가져오므로, 클러스터의 *리소스(CPU/IO)를 절약*하면서 최신 통계치를 반영할 수 있습니다.
3. 실시간에 가까운 통계 업데이트 반영
* 효과: Spark, Flink 등을 통해 Iceberg 테이블에 새로운 데이터가 써지면 매니페스트 파일에 관련 통계가 업데이트됩니다.
* 결과: StarRocks는 이 메타데이터를 직접 읽기 때문에, 별도의 통계 수집 주기를 기다리지 않고도 데이터 변화에 따른 통계치 업데이트를 실행 계획에 즉각 반영할 수 있습니다.
4. 메타데이터 기반 Pruning 강화
* 효과: Iceberg 파일 레벨의 통계(Lower/Upper bounds)를 옵티마이저 단계에서 더 적극적으로 활용합니다.
* 결과: 불필요한 파일을 더 효율적으로 걸러내어(Pruning), 실제 데이터 스캔 양을 줄이고 쿼리 속도를 높입니다.
──────────
주의사항
* 버전 확인: 이 기능은 StarRocks 최신 버전(v3.1 이상 권장)에서 Iceberg 및 Glue Catalog를 사용할 때 효과적입니다.
* 메타데이터의 정확도: 이 설정은 Iceberg 자체가 생성한 메타데이터에 의존합니다. 만약 외부 엔진(Spark/Flink 등)이 데이터를 쓸 때 통계 정보를 정확히 기록하지 않도록 설정되어 있다면 효과가 제한적일 수 있습니다.
* 완전한 통계 대체: 만약 매우 정교한 통계(예: Histogram)가 필요한 복잡한 쿼리라면, 이 옵션과 별개로 `ANALYZE TABLE`을 통한 정밀 통계 수집이 병행되어야 할 수도 있습니다.
참고 문서
• data_source/catalog/iceberg/iceberg_catalog.md
• using_starrocks/Cost_based_optimizer.md
References
• administration/management/FE_configuration.md
• unloading/Spark_connector.md
• administration/management/BE_configuration.mdRonJay
09/01/2026, 1:57 PMRocky
09/01/2026, 1:57 PMdisable_table_stats_from_metadata_fro_single_table (또는 오타를 수정한 disable_table_stats_from_metadata_for_single_table) 세션 변수는 StarRocks의 공식 문서상에 공개된 표준 변수는 아닙니다. 하지만 변수명과 StarRocks의 동작 방식을 고려할 때, 이는 *특정 테이블에 대해 외부 메타데이터(Iceberg/Glue 등)로부터 통계 정보를 가져오는 기능을 비활성화*하기 위해 사용되는 세션 레벨의 제어 스위치입니다.
일반적으로 사용되는 enable_get_stats_from_external_metadata 설정과 연계하여 다음과 같은 효과를 가집니다.
1. 주요 효과: 메타데이터 기반 통계 강제 무시
카탈로그 설정(enable_get_stats_from_external_metadata = true)에 의해 모든 테이블이 Iceberg 등의 자체 메타데이터를 사용하도록 되어 있더라도, 이 세션 변수를 사용하면 *특정 테이블에 대해서만 이 과정을 생략*하게 할 수 있습니다.
* 상황: Iceberg 테이블의 메타데이터에 기록된 행 수(Row count)나 파일 통계가 실제 데이터와 크게 다르거나 오염되어 쿼리 실행 계획(Query Plan)이 잘못 생성되는 경우.
* 결과: StarRocks는 외부 메타데이터 대신 StarRocks가 직접 수집한 통계(ANALYZE 결과) 또는 기본 예측치(Default estimate)를 사용하여 실행 계획을 수립합니다.
2. 성능 문제 해결 (Troubleshooting)
외부 메타데이터를 가져오는 과정(예: Glue API 호출 또는 Iceberg 매니페스트 읽기)에서 지연이 발생하거나, 특정 테이블의 메타데이터가 너무 커서 통계 수집 단계에서 쿼리 플래닝 시간이 길어질 때 이를 일시적으로 회피하는 용도로 사용될 수 있습니다.
3. 관련 설정 및 변수
만약 해당 변수가 작동하지 않거나 비슷한 제어가 필요하다면 다음의 표준 설정들을 확인해 보시기 바랍니다.
* enable_get_stats_from_external_metadata (Catalog Property): 카탈로그 전체에 대해 메타데이터 기반 통계 사용 여부를 결정합니다.
* enable_iceberg_column_statistics (Session Variable): Iceberg 테이블의 컬럼 레벨 통계(min/max, null count 등)를 가져올지 여부를 제어합니다 (v3.4+).
* enable_query_trigger_analyze (Session Variable): 쿼리 실행 시 자동으로 통계를 수집하는 기능을 켜고 끕니다 (v3.4+).
요약
이 변수는 "전역 설정은 유지하되, 특정 테이블이나 특정 쿼리에서만 외부 메타데이터 통계 사용을 막고 싶을 때" 사용하는 디버깅 또는 최적화용 변수일 가능성이 매우 높습니다. 만약 특정 테이블의 실행 계획이 이상하여 이 변수를 찾으신 것이라면, 해당 테이블에 대해 `ANALYZE TABLE <table_name>`을 실행하여 StarRocks 자체 통계를 최신화한 뒤 쿼리를 다시 시도해 보시는 것을 권장합니다.
References
• data_source/catalog/iceberg/iceberg_catalog.md
• sql-reference/System_variable.md
• using_starrocks/Cost_based_optimizer.md
References
• using_starrocks/Cost_based_optimizer.md
• using_starrocks/async_mv/use_cases/query_rewrite_with_materialized_views.md
• faq/Sql_faq.md
• sql-reference/System_variable.md
• administration/management/FE_configuration.md