Sangwon
06/08/2026, 12:33 AMRocky
06/08/2026, 12:33 AMlake_datafile_gc)을 사용하여 수동으로 정리해야 할 수도 있습니다.
3. 권장 운영 팁
1. MinIO 보관 정책(Lifecycle Policy): StarRocks가 직접 파일을 지우기 때문에, MinIO 자체의 Lifecycle 정책(예: 30일 뒤 자동 삭제 등)을 StarRocks 데이터 경로에 절대 설정하지 마세요. 데이터 유실의 원인이 됩니다.
2. 용량 모니터링: StarRocks 내부에서 SHOW PROC '/dbs/<db_name>/<table_name>/partitions'; 명령어를 통해 `DataSize`를 확인하고, 실제 MinIO 버킷의 사용량과 크게 차이가 나는지 가끔 체크해보는 것이 좋습니다.
3. 버전 업데이트: 가비지 컬렉션 성능과 안정성이 계속 개선되고 있으므로, 가급적 최신 마이너 버전을 유지하는 것이 스토리지 관리 측면에서 유리합니다.
요약하자면: StarRocks가 파일을 알아서 잘 치우고 관리하므로 따로 관리하실 필요는 없으나, 데이터가 비정상적으로 계속 쌓이는 느낌이 든다면 StarRocks 버전 확인 및 가비지 컬렉션 상태를 점검해보시면 됩니다.
References
• administration/management/compaction.md
• knowledge/admin_and_operation/shared_data_garbage_cleanup.md
• knowledge/admin_and_operation/shared_data_compaction.mdSangwon
06/08/2026, 12:37 AMRocky
06/08/2026, 12:37 AMtext
s3://<bucket>/<cluster_id>/<db_id>/<table_id>/<partition_id>/
├── data/ # 실제 데이터 파일 (Segment 파일) 저장
└── meta/ # 태블릿(Tablet)의 메타데이터 및 스냅샷 저장
* db_<id> (예: db_00010): StarRocks 내부에서 생성된 *데이터베이스 ID*입니다. 사용자가 `CREATE DATABASE`로 만든 이름 대신 시스템이 관리하는 고유 번호를 사용하여 폴더를 생성합니다.
* `<table_id>`: 해당 데이터베이스 안에 생성된 *테이블 ID*입니다.
* `<partition_id>`: 테이블의 *파티션 ID*입니다.
* data/ 폴더: 데이터 로딩 시 생성되는 파일들이 저장되며, Compaction 과정을 통해 이 파일들이 병합되거나 정리됩니다.
* meta/ 폴더: 데이터 파일들의 위치 정보나 버전 정보를 담고 있는 메타데이터가 저장됩니다.
2. ID와 실제 이름 매칭 확인 방법 (SQL)
MinIO의 `db_00010`이 어떤 DB인지, 그 안의 폴더가 어떤 테이블인지 확인하려면 StarRocks에서 다음 명령어를 실행하면 됩니다.
* 전체 DB ID 확인:
sql
SHOW PROC '/dbs';
-- 결과 테이블에서 DbId 열과 DbName 열을 매칭해볼 수 있습니다.
* 특정 DB 내의 테이블 ID 및 경로 확인:
sql
SHOW PROC '/dbs/10'; -- 위에서 확인한 db_id가 10일 경우
-- 결과의 TableId와 StoragePath 컬럼을 통해 MinIO 경로와 테이블 이름을 확인할 수 있습니다.
* 파티션 및 세부 경로 확인:
sql
SHOW PROC '/dbs/10/20123/partitions'; -- db_id/table_id 순서
3. 왜 이렇게 관리하나요?
* 중복 방지: 데이터베이스나 테이블 이름을 변경(RENAME)하더라도 내부 ID는 변하지 않으므로, 스토리지 레벨에서 파일을 옮길 필요가 없어 효율적입니다.
* 자동 관리: 이전 답변에서 언급했듯이, StarRocks FE/CN 노드가 이 ID들을 기준으로 *Compaction(병합)*과 *GC(가비지 컬렉션)*를 수행합니다.
* 주의: 사용자가 MinIO에서 직접 이 폴더나 파일을 삭제/수정하면 StarRocks 메타데이터와 불일치가 발생하여 *데이터 유실이나 쿼리 오류*가 발생할 수 있습니다. 수동 관리는 권장하지 않습니다.
관련 문서 링크
더 자세한 기술적 구조는 아래 공식 문서에서 확인하실 수 있습니다.
* StarRocks Shared-data 아키텍처 개요
* 데이터 스토리지 경로 확인 방법 (FAQ)
혹시 특정 폴더(catalog.db 등)가 예상과 다르게 생성되어 관리가 필요하다고 느끼시는 상황인가요? 상황을 더 알려주시면 추가로 도움을 드릴 수 있습니다.
References
• faq/shared_data_faq.md
• table_design/table_design.md
• deployment/shared_data/hdfs.md
• data_source/catalog/catalog_overview.md
• data_source/catalog/default_catalog.mdSangwon
06/08/2026, 12:50 AMRocky
06/08/2026, 12:51 AMSHOW TABLET 명령어에서 확인되는 수천 개의 태블릿과 그 크기가 KB 단위인 현상은 *"컴팩션(Compaction)이 안 되고 있는 것"*이라기보다, *"버킷(Bucket) 설정이 너무 잘게 쪼개진 상태(Over-sharding)"*일 가능성이 매우 높습니다.
이 상황을 이해하기 위한 핵심 포인트 3가지를 설명해 드립니다.
1. 컴팩션은 '태블릿 개수'를 줄이지 않습니다
* 컴팩션의 역할: 하나의 태블릿(Shard) 안에 쌓인 여러 개의 작은 *데이터 파일(Segment)*들을 병합하여 파일 숫자를 줄이는 작업입니다.
* 태블릿의 정체: 태블릿은 테이블을 논리적으로 나눈 '통'입니다. 테이블 생성 시 `DISTRIBUTED BY HASH(...) BUCKETS 100`이라고 설정했다면, 데이터가 10KB든 10GB든 무조건 100개의 태블릿이 생성됩니다.
* 즉, SHOW TABLET 결과에 나오는 행(태블릿)의 개수는 컴팩션과 상관없이 *테이블 설계 시 결정된 버킷 수 × 파티션 수*입니다.
2. 왜 KB 단위의 태블릿이 수천 개나 생겼을까요? (Over-sharding)
태블릿 크기가 너무 작고 개수가 많다면 보통 다음과 같은 이유 때문입니다.
* 너무 많은 버킷 수: 데이터 양에 비해 BUCKETS 숫자를 너무 크게 잡았을 때 발생합니다. (예: 데이터는 100MB인데 버킷을 1,000개 잡으면 태블릿당 100KB가 됨)
* 너무 세분화된 파티션: 날짜별로 파티션을 나눴는데, 각 날짜당 데이터는 적고 버킷 수는 기본값으로 유지된 경우입니다.
* 영향: 태블릿이 너무 많으면 StarRocks가 관리해야 할 메타데이터가 늘어나고, MinIO에 아주 작은 파일들이 대량으로 생성되어 *오히려 쿼리 성능이 떨어지고 스토리지 관리 부하가 증가*합니다.
3. 컴팩션이 실제로 돌고 있는지 확인하는 방법
그래도 파일 병합(컴팩션)이 정상인지 확인하고 싶다면 다음 지표를 보셔야 합니다.
1. Compaction Score 확인:
sql
-- 특정 파티션의 상태 확인
SHOW PROC '/dbs/<db_id>/<table_id>/partitions';
* 결과 열 중 *`MaxCS` (Max Compaction Score)*를 확인하세요.
* 이 점수가 *10 미만*이라면 컴팩션이 아주 잘 되어 있는 상태입니다.
* 만약 이 점수가 수백~수천 대라면 파일이 너무 많이 꼬여 있어 컴팩션이 필요한 상태입니다.
2. 진행 중인 작업 확인:
sql
SHOW PROC '/compactions';
* 현재 실행 중이거나 최근에 끝난 컴팩션 작업 목록을 볼 수 있습니다.
권장 조치 사항
현재 데이터 양에 비해 태블릿이 너무 작다면(KB 단위라면), 다음 설정을 검토해 보세요.
* 버킷 수 최적화: 보통 태블릿 하나당 100MB ~ 1GB 정도의 데이터를 담는 것이 가장 이상적입니다.
* Automatic Bucketing 활용: 테이블 생성 시 버킷 수를 직접 지정하는 대신, StarRocks가 데이터 양에 맞춰 자동으로 조절하게 할 수 있습니다.
sql
DISTRIBUTED BY HASH(col) BUCKETS AUTO; -- v2.5+ 이상 권장
요약하자면: 지금 보시는 현상은 컴팩션의 문제가 아니라, 테이블의 버킷 설정이 데이터 규모에 비해 너무 많아서 발생하는 현상일 가능성이 큽니다. 데이터 양이 적다면 버킷 수를 줄여서 테이블을 다시 생성하거나 조정하는 것을 권장합니다.
References
• knowledge/admin_and_operation/shared_data_compaction.md
• administration/management/compaction.md
• faq/shared_data_faq.md
• deployment/shared_data/minio.md
• table_design/table_design.md
• quick_start/shared-data.md
• quick_start/iceberg.md
berg.md)
• data_source/catalog/catalog_overview.md
• data_source/catalog/default_catalog.md
• deployment/shared_data/hdfs.md
• administration/management/compaction.md
• knowledge/admin_and_operation/shared_data_compaction.md
• knowledge/admin_and_operation/shared_data_garbage_cleanup.md
• knowledge/admin_and_operation/shared_data_compaction.md
• faq/shared_data_faq.md
• table_design/table_design.md
• deployment/shared_data/hdfs.md
• data_source/catalog/catalog_overview.md
• data_source/catalog/default_catalog.md
• deployment/shared_data/minio.mdRocky
06/08/2026, 12:51 AMSangwon
06/08/2026, 1:42 AMRocky
06/08/2026, 1:42 AM전체 태블릿(Tablet) 개수 = 파티션(Partition) 개수 × 버킷(Bucket) 개수계층 | 개념 설명 | 연관 관계 테이블 (Table) | 최상위 논리적 단위 | - 파티션 (Partition) | 데이터를 시간(날짜)이나 범위로 나눈 큰 덩어리 | 1개 테이블은 여러 파티션을 가짐 태블릿 (Tablet) | 파티션을 다시 여러 개로 쪼갠 데이터 분산의 최소 단위 | 1개 파티션은 N개의 태블릿을 가짐 (버킷 수만큼) 세그먼트 (File) | 태블릿 안에 실제로 저장되는 물리적 파일 (.dat) | 1개 태블릿은 여러 개의 파일을 가짐 ────────── 2. 각 단계별 확인 방법 (SQL 명령어) ① 파티션(Partition) 확인 테이블이 어떻게 날짜별/범위별로 나뉘어 있는지 확인합니다.
sql
SHOW PARTITIONS FROM {table_nm};
* 중요 컬럼: PartitionName, `BucketCount`(이 파티션이 몇 개의 태블릿으로 구성되었는지), DataSize.
② 태블릿(Tablet) 확인
특정 테이블에 속한 모든 태블릿 목록과 그 상태를 확인합니다.
sql
SHOW TABLET FROM {table_nm};
* 중요 컬럼: TabletId, PartitionName, DataSize.
* 여기서 태블릿 개수가 너무 많다면(예: 데이터는 적은데 태블릿은 수천 개), 버킷 설정을 너무 크게 잡은 것입니다.
③ 실제 파일(Segment File) 확인
태블릿 하나가 MinIO에 어떤 파일들로 구성되어 있는지 확인합니다.
sql
-- 1. 먼저 SHOW TABLET에서 특정 TabletId를 하나 복사합니다. (예: 10001)
-- 2. 해당 태블릿의 세부 정보(파일 위치 등)를 조회합니다.
SHOW PROC '/dbs/{db_id}/{table_id}/partitions/{partition_id}/{tablet_id}';
* 이 명령어를 통해 해당 태블릿의 데이터가 MinIO의 어느 경로에 어떤 파일명으로 저장되어 있는지 볼 수 있습니다.
──────────
3. 상세 연관 관계 시나리오
예를 들어, 다음과 같은 테이블이 있다고 가정해 보겠습니다.
* 파티션: 날짜별로 30일치 (30개)
* 버킷 설정: DISTRIBUTED BY HASH(id) BUCKETS 10 (10개)
1. 태블릿 개수: 이 테이블은 총 *300개*(30파티션 × 10버킷)의 태블릿을 가집니다.
2. 데이터 저장 흐름:
* 사용자가 데이터를 INSERT 하면, 해당 날짜의 *파티션*을 찾습니다.
* id 값을 해시 함수에 돌려 10개의 태블릿 중 하나를 선택합니다.
* 그 태블릿 안에 *세그먼트 파일*로 데이터가 써집니다.
3. 컴팩션(Compaction)의 역할:
* 데이터를 계속 넣으면 태블릿 하나 안에 작은 파일들이 수십 개 생깁니다.
* StarRocks는 이 작은 파일들을 합쳐서 *큰 파일 1~2개*로 만듭니다.
* 주의: 컴팩션이 일어나도 태블릿 개수(300개)는 변하지 않습니다. 파일의 개수와 크기만 변합니다.
──────────
4. 운영 가이드라인 (최적화)
* 태블릿 1개의 적정 크기: 공유 스토리지(MinIO) 환경에서는 태블릿 하나당 수백 MB ~ 1GB 정도의 데이터를 담는 것이 성능상 가장 좋습니다.
* KB 단위의 태블릿이 문제인 이유:
* MinIO에 너무 많은 작은 파일 요청(S3 API Call)이 발생하여 리스트 조회 속도가 느려집니다.
* 쿼리 실행 시 CPU가 처리해야 할 태블릿 단위 작업(Task)이 너무 많아져 오버헤드가 발생합니다.
* 해결책:
* 데이터 양이 적다면 파티션을 너무 잘게 나누지 마세요.
* BUCKETS AUTO 설정을 사용하여 StarRocks가 데이터 양에 따라 태블릿 개수를 스스로 조절하게 하세요.
요약하자면: `SHOW TABLET`에서 보이는 수천 개의 행은 사용자가 설정한 `PARTITIONS`와 `BUCKETS`의 곱이며, 그 안의 물리적 파일들은 StarRocks가 컴팩션을 통해 자동으로 병합/관리합니다. 태스크를 수행하며 관리합니다.
References
• table_design/data_distribution.md
• table_design/table_design.md
• administration/management/compaction.md
• faq/shared_data_faq.md
• sql-reference/sql-statements/data-definition/CREATE_TABLE.mdSangwon
06/08/2026, 1:51 AMRocky
06/08/2026, 1:52 AMsql
SHOW CREATE TABLE {table_nm};
-- 결과 하단의 DISTRIBUTED BY HASH(...) 부분에 BUCKETS 숫자가 어떻게 찍혀있는지 확인
3. 해결 방법
방법 A: 기존 테이블의 버킷 수 수정 (v3.2 이상)
StarRocks v3.2 버전부터는 ALTER TABLE 명령어로 버킷 수를 변경할 수 있습니다. (단, 공유 스토리지 모드에서는 제약이 있을 수 있으므로 실행 전 확인이 필요합니다.)
sql
-- 버킷 수를 1개로 줄이기 (데이터가 아주 적을 경우)
ALTER TABLE {table_nm} DISTRIBUTED BY HASH({column}) BUCKETS 1;
이 작업은 데이터를 재배치하므로 데이터 양에 따라 시간이 소요될 수 있습니다.
방법 B: 새 테이블로 마이그레이션 (가장 확실한 방법)
데이터가 수십 KB 수준이라면 테이블을 새로 만들어 데이터를 옮기는 것이 가장 빠르고 깔끔합니다.
1. 버킷 수를 1로 지정하여 테이블 생성:
sql
CREATE TABLE {new_table} ( ... )
PARTITION BY ...
DISTRIBUTED BY HASH({col}) BUCKETS 1; -- 데이터가 적으므로 1개면 충분합니다.
2. 데이터 복사:
sql
INSERT INTO {new_table} SELECT * FROM {old_table};
방법 C: 파티션 전략 수정
데이터가 적은데 파티션을 너무 잘게(예: 매일) 나누고 있지는 않은지 확인해 보세요.
* 데이터 양이 적다면 파티션을 *월 단위(Monthly)*로 합치거나, 아예 파티션을 없애고 단일 테이블로 관리하는 것이 MinIO와 StarRocks 모두에게 훨씬 효율적입니다.
4. 권장 가이드라인
* 태블릿 1개당 적정 크기: 약 100MB ~ 1GB (공유 스토리지 모드 기준).
* 데이터가 적은 테이블: 무조건 `BUCKETS 1`로 설정하십시오.
* 자동 버킷팅 주의: 데이터가 계속 늘어날 테이블이 아니라면, 수동으로 `BUCKETS 1`을 지정하는 것이 "과분산"을 막는 가장 좋은 방법입니다.
요약: 지금 상태는 "너무 작은 그릇이 너무 많이 만들어진 상태"입니다. `BUCKETS 1`로 설정한 새 테이블을 만들어 데이터를 옮기시거나, v3.2 이상이라면 `ALTER TABLE`로 버킷 수를 줄여보시는 것을 추천합니다.
References
• table_design/data_distribution.md
• sql-reference/sql-statements/table_bucket_part_index/ALTER_TABLE.md
• faq/shared_data_faq.md
• administration/management/FE_configuration.md
• knowledge/usage/best-practice.md
References
• faq/shared_data_faq.md
• deployment/shared_data/feature-support-shared-data.md
• faq/Deploy_faq.mdSangwon
06/08/2026, 2:07 AMRocky
06/08/2026, 2:07 AMuser_id, order_id, device_id, log_id 처럼 값이 매우 다양한 컬럼.
* 비추천: gender (남/여), status (성공/실패), is_deleted (Y/N).
_ _이유:* 값이 몇 개 안 되면 특정 태블릿에만 데이터가 몰리는 데이터 스큐(Data Skew) 현상이 발생하여, 특정 노드만 과부하가 걸리고 전체 쿼리 속도가 느려집니다.
2. 쿼리 조건(WHERE 절)에 자주 쓰이는 컬럼
조회할 때 자주 필터링하는 컬럼을 버킷 키로 잡으면 버킷 프루닝(Bucket Pruning) 효과를 볼 수 있습니다.
* 예를 들어, `WHERE user_id = 123`이라는 쿼리를 자주 던진다면, `user_id`를 버킷 키로 잡아야 합니다.
* 이렇게 하면 StarRocks는 수천 개의 태블릿을 다 뒤지지 않고, `123`이 들어있는 *특정 태블릿 하나만 딱 찍어서 조회*하므로 속도가 수십 배 빨라집니다.
3. 조인(JOIN) 키로 자주 쓰이는 컬럼
두 테이블을 조인할 때 똑같은 컬럼을 버킷 키로 설정하면 *Colocated Join*이 가능해집니다.
* 테이블 A와 B가 모두 `user_id`로 버킷팅되어 있다면, 조인할 때 네트워크를 통해 데이터를 주고받는 과정(Shuffle) 없이 각 노드 안에서 바로 조인이 일어나 성능이 극대화됩니다.
──────────
💡 실전 팁
* 적당한 컬럼이 없다면? (Composite Keys)
하나의 컬럼으로 부족하다면 여러 컬럼을 합쳐서 지정할 수 있습니다.
DISTRIBUTED BY HASH(user_id, region_code) BUCKETS 10;
* 모르겠다면? (Primary Key)
`Primary Key`나 `Aggregate Key`가 있는 테이블이라면, 보통 그 키의 *앞부분 컬럼들*을 버킷 키로 사용하면 성능이 무난하게 잘 나옵니다.
* 데이터가 너무 적다면? (Random Distribution)
데이터가 워낙 적고(수십 KB~MB 단위) 어떤 컬럼으로 쪼갤지 고민된다면, 특정 컬럼 대신 랜덤하게 나누도록 설정할 수도 있습니다. (단, 버킷 프루닝 효과는 포기해야 합니다.)
DISTRIBUTED BY RANDOM BUCKETS 1; (데이터가 적을 땐 버킷 1개가 제일 좋습니다.)
결론:
가장 자주 조회 조건으로 쓰이면서 중복이 없는 *ID 형태의 컬럼*을 선택하는 것이 베스트입니다. 현재처럼 데이터가 수십 KB 수준으로 적다면, 어떤 컬럼을 고르느냐보다 *버킷 수(BUCKETS)를 1로 줄이는 것*이 성능 최적화에 훨씬 효과적입니다.
References
• table_design/data_distribution.md
• sql-reference/sql-statements/data-definition/CREATE_TABLE.md
• table_design/table_design.md
• faq/shared_data_faq.md
• administration/management/compaction.md
• deployment/shared_data/minio.md
• data_source/catalog/catalog_overview.md
• data_source/catalog/default_catalog.md
• quick_start/shared-data.md
• quick_start/iceberg.md
• deployment/shared_data/hdfs.md
• knowledge/admin_and_operation/shared_data_compaction.md
• knowledge/admin_and_operation/shared_data_garbage_cleanup.md