HBase 테이블을 백업하거나 다른 클러스터로 옮기고, CSV/TSV 를 대량으로 적재한다. 방식은 크게 세 가지다. MapReduce Export/Import, 스냅샷 ExportSnapshot, 그리고 HFile 을 직접 만들어 넣는 벌크로드다.
Export 는 테이블을 스캔해 HDFS 에 SequenceFile 로 쓴다. 타임스탬프 범위를 줄 수 있어 증분 추출에 쓴다.
hbase org.apache.hadoop.hbase.mapreduce.Export \
<table> <outputdir> [versions] [starttime] [endtime]
hbase org.apache.hadoop.hbase.mapreduce.Export orders /backup/orders
hbase org.apache.hadoop.hbase.mapreduce.Export \
orders /backup/orders_2025-12 1 0 1733011200000
starttime 과 endtime 은 epoch milliseconds 이며, 셀 타임스탬프를 기준으로 거른다. 되돌리는 쪽은 Import 이고, 대상 테이블이 먼저 존재해야 한다.
echo "create 'orders', 'cf'" | hbase shell -n
hbase org.apache.hadoop.hbase.mapreduce.Import orders /backup/orders
속도가 부족하면 스캐너 캐시를 올린다. hbase.client.scanner.caching 의 기본값은 최신 HBase 에서 매우 크게 잡혀 있으므로(설정 파일 기준 2147483647), 오히려 메모리 압박이 있을 때 낮추는 방향으로 조정하는 편이 많다.
hbase org.apache.hadoop.hbase.mapreduce.Export \
-Dhbase.client.scanner.caching=5000 \
-Dmapreduce.job.running.map.limit=20 \
orders /backup/orders
java.io.IOException: Mkdirs failed to create file:... 가 나면 출력 경로 문제다. 경로 앞에 스킴이 없어 로컬 파일시스템으로 해석됐거나, 이미 존재하거나, 실행 사용자에게 쓰기 권한이 없는 경우다. hdfs:// 또는 s3a:// 스킴을 명시하고, 기존 디렉터리를 지운 뒤 다시 돌린다.
hbase org.apache.hadoop.hbase.mapreduce.ImportTsv \
-Dimporttsv.separator=, \
-Dimporttsv.columns=HBASE_ROW_KEY,cf:o_custkey,cf:o_orderstatus,cf:o_totalprice \
orders /staging/orders.csv
이 형태는 각 행을 Put 으로 밀어 넣으므로 대량 적재에는 느리다. 대량이면 HFile 을 먼저 만들고 벌크로드한다.
hbase org.apache.hadoop.hbase.mapreduce.ImportTsv \
-Dimporttsv.separator=, \
-Dimporttsv.columns=HBASE_ROW_KEY,cf:c1,cf:c2 \
-Dimporttsv.bulk.output=/staging/hfiles/orders \
orders /staging/orders.csv
hbase org.apache.hadoop.hbase.tool.LoadIncrementalHFiles /staging/hfiles/orders orders
LoadIncrementalHFiles 는 HBase 2.x 에서 org.apache.hadoop.hbase.tool 패키지에 있다. 1.x 계열의 org.apache.hadoop.hbase.mapreduce.LoadIncrementalHFiles 경로를 그대로 쓰면 클래스를 찾지 못한다.
벌크로드나 CopyTable 후 로드 단계에서 다음 오류가 난다.
ERROR tool.LoadIncrementalHFiles: Trying to load more than 256 hfiles
to family cf of region with start key ...
한 리전의 한 컬럼 패밀리에 넣으려는 HFile 개수가 제한을 넘었다는 뜻이다. 급한 대로 한도를 올릴 수 있다.
hbase org.apache.hadoop.hbase.tool.LoadIncrementalHFiles \
-Dhbase.mapreduce.bulkload.max.hfiles.perRegion.perFamily=1024 \
/staging/hfiles/orders orders
근본 해결은 생성되는 HFile 수를 줄이는 것이다. 리듀서 수를 대상 테이블의 리전 수에 맞추고 HFileOutputFormat2.configureIncrementalLoad 가 붙이는 TotalOrderPartitioner 를 그대로 쓰면, 리전·패밀리당 HFile 이 하나로 떨어진다. 키 분포가 한쪽으로 쏠려 있으면 샘플링과 사전 분할(pre-split)을 다시 본다. 로드가 끝난 뒤에는 major compaction 으로 StoreFile 을 정리한다.
| 상황 | 방식 |
|---|---|
| 전체 테이블을 다른 클러스터로 | ExportSnapshot - HFile 을 그대로 복사해 가장 빠르다 |
| 기간을 잘라 증분 추출 | Export 의 starttime/endtime |
| 외부 파일을 대량 적재 | ImportTsv + bulk.output + LoadIncrementalHFiles |
| 소량 수정 | 셸 put 또는 클라이언트 API |
| CSV 로 떨어뜨려 분석 | Hive/Impala 외부 테이블 매핑 후 INSERT ... SELECT |
Export 출력은 SequenceFile 이라 사람이 바로 읽을 수 없다. CSV 가 필요하면 HBase 테이블을 Hive 외부 테이블로 매핑해 텍스트 테이블로 다시 쓰는 편이 간단하다.