HBase 실전 가이드: 대규모 NoSQL 데이터 저장소 설계부터 운영까지

┌────────────────────────────────────────────────────────┐
│                       Client                           │
│   (HBase Shell, Java API, REST, Thrift)                │
└───────────────────────┬────────────────────────────────┘
                        │
                ┌───────▼───────┐
                │   ZooKeeper   │
                │  (coordination│
                │   & discovery)│
                └───┬───────┬───┘
                    │       │
            ┌───────▼──┐  ┌─▼──────────┐
            │  HMaster  │  │  HMaster   │
            │ (Active)  │  │ (Standby)  │
            └───────┬───┘  └────────────┘
                    │
     ┌──────────────┼──────────────┐
     │              │              │
┌────▼─────┐  ┌────▼─────┐  ┌────▼─────┐
│RegionSvr │  │RegionSvr │  │RegionSvr │
│┌────────┐│  │┌────────┐│  │┌────────┐│
││Region A││  ││Region C││  ││Region E││
│├────────┤│  │├────────┤│  │├────────┤│
││Region B││  ││Region D││  ││Region F││
│└────────┘│  │└────────┘│  │└────────┘│
└──────────┘  └──────────┘  └──────────┘
       │              │              │
       └──────────────┼──────────────┘
                      │
               ┌──────▼──────┐
               │    HDFS     │
               │ (Storage)   │
               └─────────────┘

┌─────────────── Region ──────────────────┐
│                                          │
│  ┌─── Column Family: cf1 ─────────────┐ │
│  │  ┌──────────┐                      │ │
│  │  │ MemStore │  (메모리, 쓰기 버퍼)  │ │
│  │  └──────────┘                      │ │
│  │  ┌──────────┐  ┌──────────┐       │ │
│  │  │ HFile 1  │  │ HFile 2  │       │ │
│  │  └──────────┘  └──────────┘       │ │
│  └────────────────────────────────────┘ │
│                                          │
│  ┌─── Column Family: cf2 ─────────────┐ │
│  │  ┌──────────┐                      │ │
│  │  │ MemStore │                      │ │
│  │  └──────────┘                      │ │
│  │  ┌──────────┐                      │ │
│  │  │ HFile 1  │                      │ │
│  │  └──────────┘                      │ │
│  └────────────────────────────────────┘ │
│                                          │
│  ┌──────────────────────────────────┐   │
│  │         WAL (Write-Ahead Log)    │   │
│  └──────────────────────────────────┘   │
└──────────────────────────────────────────┘

1. Client → RegionServer에 Put 요청
2. WAL(Write-Ahead Log)에 기록 (HDFS에 저장, 장애 복구용)
3. MemStore에 기록 (메모리)
4. Client에 성공 응답
5. MemStore가 가득 차면 → HFile로 Flush (HDFS에 저장)

1. Client → RegionServer에 Get 요청
2. Block Cache 확인 (메모리)
3. MemStore 확인 (메모리)
4. HFile 확인 (디스크, Bloom Filter로 빠르게 필터링)
5. 결과 병합 (최신 버전 반환)

Table: user_activity
─────────────────────────────────────────────────────────────────
RowKey          | Column Family: info      | Column Family: stats
                | name     | email        | login_count | last_login
─────────────────────────────────────────────────────────────────
user001         | 김영주   | yj@email.com | 142         | 2026-03-08
user002         | 박서준   | sj@email.com | 87          | 2026-03-07
user003         | 이하나   | hn@email.com | 256         | 2026-03-08
─────────────────────────────────────────────────────────────────

# 실제로는 Column Family 단위로 별도 저장
# Key-Value 형태: (RowKey, CF:Qualifier, Timestamp) → Value

# Column Family: info
(user001, info:name, t3) → "김영주"
(user001, info:name, t1) → "김영주(구)"     # 이전 버전
(user001, info:email, t2) → "yj@email.com"
(user002, info:name, t4) → "박서준"
(user002, info:email, t4) → "sj@email.com"

# Column Family: stats (별도 HFile)
(user001, stats:login_count, t5) → 142
(user001, stats:last_login, t5) → "2026-03-08"

# 잘못된 RowKey: 순차적 키
# → 모든 쓰기가 마지막 Region에 집중 (핫스팟)

RowKey: 20260308_000001
RowKey: 20260308_000002
RowKey: 20260308_000003
        ↓ 모든 쓰기가 한 Region에 집중!

┌──────────┐ ┌──────────┐ ┌──────────┐
│ Region 1 │ │ Region 2 │ │ Region 3 │
│ (한가함)  │ │ (한가함)  │ │ (과부하!) │
└──────────┘ └──────────┘ └──────────┘

// 원래 RowKey: "20260308_user001"
// Salt 적용: hash("20260308_user001") % NUM_REGIONS + "_" + 원래키

int numRegions = 10;
String originalKey = "20260308_user001";
int salt = Math.abs(originalKey.hashCode() % numRegions);
String saltedKey = String.format("%02d_%s", salt, originalKey);
// 결과: "07_20260308_user001"

// 데이터가 Region에 균등 분배됨
// Region 0: 00_xxx, Region 1: 01_xxx, ... Region 9: 09_xxx

// 도메인 기반 RowKey를 뒤집어서 분산
// 원래: "com.google.www" → 뒤집기: "www.google.com"
// 원래: "com.google.mail" → 뒤집기: "liam.elgoog.moc"

// 타임스탬프 뒤집기
long reverseTimestamp = Long.MAX_VALUE - System.currentTimeMillis();
String rowKey = userId + "_" + reverseTimestamp;
// 최신 데이터가 먼저 정렬됨 (가장 흔한 쿼리 패턴)

// MD5 해시의 앞 N자리를 prefix로 사용
String hashPrefix = DigestUtils.md5Hex(userId).substring(0, 4);
String rowKey = hashPrefix + "_" + userId + "_" + timestamp;
// 결과: "a3f2_user001_20260308120000"

# 시계열 데이터 (IoT 센서)
salt_deviceId_reverseTimestamp
예: 03_sensor042_9223370449055775807

# 사용자 활동 로그
userId_reverseTimestamp_activityType
예: user001_9223370449055775807_login

# 웹 페이지 크롤링
reversedDomain_path_timestamp
예: moc.elgoog_/search_20260308

# 메시징 시스템
chatRoomId_reverseTimestamp_messageId
예: room001_9223370449055775807_msg12345

# HBase Shell 시작
hbase shell

# 테이블 생성
create 'user_activity', \
  {NAME => 'info', VERSIONS => 3, COMPRESSION => 'SNAPPY', BLOOMFILTER => 'ROW'}, \
  {NAME => 'stats', VERSIONS => 1, COMPRESSION => 'SNAPPY', TTL => 2592000}

# 테이블 목록
list

# 테이블 상세 정보
describe 'user_activity'

# 테이블 비활성화/삭제
disable 'user_activity'
drop 'user_activity'

# 테이블 구조 변경 (비활성화 필요)
disable 'user_activity'
alter 'user_activity', {NAME => 'info', VERSIONS => 5}
alter 'user_activity', {NAME => 'logs'}  # 새 CF 추가
enable 'user_activity'

# Pre-split 테이블 생성 (핫스팟 방지)
create 'events', 'data', SPLITS => ['10', '20', '30', '40', '50', '60', '70', '80', '90']

# Put (삽입/업데이트)
put 'user_activity', 'user001', 'info:name', '김영주'
put 'user_activity', 'user001', 'info:email', 'yj@email.com'
put 'user_activity', 'user001', 'stats:login_count', '142'

# Get (단일 행 조회)
get 'user_activity', 'user001'
get 'user_activity', 'user001', {COLUMN => 'info:name'}
get 'user_activity', 'user001', {COLUMN => 'info:name', VERSIONS => 3}
get 'user_activity', 'user001', {TIMERANGE => [1709856000000, 1709942400000]}

# Scan (범위 스캔)
scan 'user_activity'
scan 'user_activity', {LIMIT => 10}
scan 'user_activity', {STARTROW => 'user001', STOPROW => 'user010'}
scan 'user_activity', {COLUMNS => ['info:name', 'stats:login_count']}
scan 'user_activity', {FILTER => "SingleColumnValueFilter('info','name',=,'binary:김영주')"}

# Delete
delete 'user_activity', 'user001', 'info:email'  # 특정 컬럼 삭제
deleteall 'user_activity', 'user001'               # 전체 행 삭제

# Count (주의: 대량 데이터에서는 느림)
count 'user_activity'
count 'user_activity', INTERVAL => 100000

# Truncate
truncate 'user_activity'

# 클러스터 상태
status
status 'detailed'
status 'simple'

# Region 관리
list_regions 'user_activity'

# 수동 Region Split
split 'user_activity', 'user500'

# Major Compaction (수동 실행, 피크 시간 피하기)
major_compact 'user_activity'

# Flush
flush 'user_activity'

# Balancer 상태
balancer_enabled
balance_switch true

import org.apache.hadoop.conf.Configuration;
import org.apache.hadoop.hbase.*;
import org.apache.hadoop.hbase.client.*;
import org.apache.hadoop.hbase.util.Bytes;

// Configuration 생성
Configuration config = HBaseConfiguration.create();
config.set("hbase.zookeeper.quorum", "zk1,zk2,zk3");
config.set("hbase.zookeeper.property.clientPort", "2181");

// Connection (스레드 세이프, 애플리케이션 수명과 동일)
Connection connection = ConnectionFactory.createConnection(config);

// Table (스레드 세이프하지 않음, 사용 후 close)
Table table = connection.getTable(TableName.valueOf("user_activity"));

// Put (쓰기)
Put put = new Put(Bytes.toBytes("user001"));
put.addColumn(Bytes.toBytes("info"), Bytes.toBytes("name"), Bytes.toBytes("김영주"));
put.addColumn(Bytes.toBytes("info"), Bytes.toBytes("email"), Bytes.toBytes("yj@email.com"));
put.addColumn(Bytes.toBytes("stats"), Bytes.toBytes("login_count"), Bytes.toBytes(142));
table.put(put);

// Batch Put (대량 쓰기)
List<Put> puts = new ArrayList<>();
for (int i = 0; i < 10000; i++) {
    Put p = new Put(Bytes.toBytes(String.format("user%06d", i)));
    p.addColumn(Bytes.toBytes("info"), Bytes.toBytes("name"),
                Bytes.toBytes("User " + i));
    puts.add(p);
}
table.put(puts);

// Get (읽기)
Get get = new Get(Bytes.toBytes("user001"));
get.addColumn(Bytes.toBytes("info"), Bytes.toBytes("name"));
Result result = table.get(get);
byte[] value = result.getValue(Bytes.toBytes("info"), Bytes.toBytes("name"));
System.out.println("Name: " + Bytes.toString(value));

// Scan (범위 스캔)
Scan scan = new Scan();
scan.withStartRow(Bytes.toBytes("user001"));
scan.withStopRow(Bytes.toBytes("user100"));
scan.addColumn(Bytes.toBytes("info"), Bytes.toBytes("name"));
scan.setCaching(500);   // RPC당 반환 행 수
scan.setBatch(10);      // 한 행에서 반환할 컬럼 수

try (ResultScanner scanner = table.getScanner(scan)) {
    for (Result r : scanner) {
        String rowKey = Bytes.toString(r.getRow());
        String name = Bytes.toString(r.getValue(Bytes.toBytes("info"), Bytes.toBytes("name")));
        System.out.println(rowKey + ": " + name);
    }
}

// Delete
Delete delete = new Delete(Bytes.toBytes("user001"));
delete.addColumn(Bytes.toBytes("info"), Bytes.toBytes("email"));
table.delete(delete);

// 자원 해제
table.close();
connection.close();

BufferedMutatorParams params = new BufferedMutatorParams(TableName.valueOf("user_activity"))
    .writeBufferSize(5 * 1024 * 1024); // 5MB 버퍼

try (BufferedMutator mutator = connection.getBufferedMutator(params)) {
    for (int i = 0; i < 1000000; i++) {
        Put put = new Put(Bytes.toBytes(String.format("user%08d", i)));
        put.addColumn(Bytes.toBytes("info"), Bytes.toBytes("name"),
                      Bytes.toBytes("User " + i));
        mutator.mutate(put);
    }
    mutator.flush(); // 버퍼에 남은 데이터 전송
}

# 1. CSV를 HFile로 변환 (MapReduce)
hbase org.apache.hadoop.hbase.mapreduce.ImportTsv \
  -Dimporttsv.separator=',' \
  -Dimporttsv.columns='HBASE_ROW_KEY,info:name,info:email,stats:login_count' \
  -Dimporttsv.bulk.output='/tmp/hbase-bulkload' \
  user_activity \
  /input/users.csv

# 2. HFile을 HBase에 로드
hbase org.apache.hadoop.hbase.tool.LoadIncrementalHFiles \
  /tmp/hbase-bulkload \
  user_activity

# Region이 일정 크기에 도달하면 자동 분할
# 기본 분할 정책: IncreasingToUpperBoundRegionSplitPolicy

# Region 크기 계산:
# min(r^2 * memstore.flush.size * 2, hbase.hregion.max.filesize)
# r = 같은 테이블의 같은 RS에 있는 Region 수

# 수동 설정
hbase.hregion.max.filesize = 10737418240  # 10GB

# 분할 과정:
# 1. 분할 지점(midpoint) 결정
# 2. 두 개의 새 Region(daughter) 생성
# 3. 기존 Region 비활성화
# 4. 메타 테이블 업데이트
# 5. 새 Region 활성화
# 6. 기존 Region 정리 (compaction 후)

# Minor Compaction
# - 작은 HFile들을 더 큰 HFile로 병합
# - 삭제 마커(tombstone) 유지
# - 자동으로 수시 실행

# Major Compaction
# - 모든 HFile을 하나의 HFile로 병합
# - 삭제 마커 제거, 만료된 버전 제거
# - 디스크 I/O 많음 → 피크 시간 피하기
# - 기본 7일 주기 자동 실행

# 수동 Major Compaction
major_compact 'user_activity'

# Major Compaction 자동 실행 비활성화
# hbase-site.xml
# hbase.hregion.majorcompaction = 0
# → cron으로 비피크 시간에 수동 실행

<!-- hbase-site.xml Compaction 설정 -->
<configuration>
    <!-- Minor Compaction 트리거 임계값 -->
    <property>
        <name>hbase.hstore.compactionThreshold</name>
        <value>3</value>  <!-- HFile 3개 이상이면 Minor Compaction -->
    </property>

    <!-- Major Compaction 주기 (0 = 비활성화) -->
    <property>
        <name>hbase.hregion.majorcompaction</name>
        <value>604800000</value>  <!-- 7일, 0으로 설정 시 비활성화 -->
    </property>

    <!-- MemStore Flush 크기 -->
    <property>
        <name>hbase.hregion.memstore.flush.size</name>
        <value>134217728</value>  <!-- 128MB -->
    </property>
</configuration>

# HMaster UI: http://hmaster:16010
# RegionServer UI: http://regionserver:16030

# JMX 메트릭 확인
curl http://regionserver:16030/jmx?qry=Hadoop:service=HBase,name=RegionServer,sub=Server

#!/bin/bash
# HBase 클러스터 상태 체크 스크립트

echo "=== HBase Cluster Status ==="
echo "status" | hbase shell 2>/dev/null | grep -E "servers|dead|regions"

echo ""
echo "=== Region Distribution ==="
echo "status 'detailed'" | hbase shell 2>/dev/null | grep -E "regionserver|regions="

echo ""
echo "=== Table Sizes ==="
for table in $(echo "list" | hbase shell 2>/dev/null | grep -v "TABLE\|row(s)"); do
    size=$(hdfs dfs -du -s -h /hbase/data/default/$table 2>/dev/null | awk '{print $1 $2}')
    echo "$table: $size"
done

# RegionServer 상태 확인
echo "status" | hbase shell

# 특정 RegionServer 로그 확인
tail -f /var/log/hbase/hbase-hbase-regionserver-hostname.log

# Region 재할당
hbase hbck -reassign <encoded-region-name>

# hbck2 (HBase 2.x)
hbase hbck -j /path/to/hbase-hbck2.jar assigns <encoded-region-name>

# hbase-env.sh
export HBASE_REGIONSERVER_OPTS="
  -Xmx32g -Xms32g
  -XX:+UseG1GC
  -XX:MaxGCPauseMillis=100
  -XX:+ParallelRefProcEnabled
  -XX:G1HeapRegionSize=16m
  -XX:InitiatingHeapOccupancyPercent=65
  -verbose:gc
  -XX:+PrintGCDetails
  -XX:+PrintGCDateStamps
  -Xloggc:/var/log/hbase/gc-regionserver.log
"

# 특정 Region의 요청 수 확인
echo "status 'detailed'" | hbase shell | grep -A2 "requestsPerSecond"

# 핫스팟 Region 수동 분할
split 'ENCODED_REGION_NAME', 'split_key'

# 또는 테이블 레벨 분할
split 'user_activity', 'user500000'

# RIT 상태 확인
echo "status 'detailed'" | hbase shell | grep "transition"

# 강제 할당
hbase hbck -j /path/to/hbase-hbck2.jar assigns <region-encoded-name>

# 메타 테이블 복구
hbase hbck -j /path/to/hbase-hbck2.jar fixMeta