HBase Shell 是 HBase 自带的交互式命令行工具，它基于 JRuby 实现，把用户输入的每个命令翻译成对应的 Admin 或 Table 操作。对运维和开发来说，Shell 并不只是一个调试入口，很多生产环境中的表结构变更、数据排查、Region 调整都可以直接通过命令完成，不必单独编写客户端程序。下面按照日常使用频率，把命令拆成连接信息、表结构、数据读写、过滤与集群运维四个部分，每部分都附带可复制的示例。
一、连接 HBase 与查看基本信息
进入 HBase Shell 的最常用方式是直接执行 hbase shell。如果集群配置了自定义的 hbase-site.xml，可以通过 --config 参数指定配置目录，例如 hbase --config /etc/hbase/conf shell。连接成功后，Shell 会输出 HBase 版本和 Java 环境信息。退出 Shell 使用 exit 或 quit。
启动后建议先确认集群是否健康。status 命令会返回当前活跃的 RegionServer 数量；version 显示 HBase 版本；whoami 显示当前连接用户。表相关的基础查询命令包括 list 列出所有表、exists '表名' 判断表是否存在、describe '表名' 查看列族和表属性。这些命令不需要进入表上下文，在 Shell 顶层直接执行即可。
hbase shell status version whoami list exists 'user' describe 'user'
需要说明的是，HBase Shell 的命令名和参数是大小写敏感的，字符串参数必须用单引号或双引号包起来。输入 help 可以查看所有可用命令，输入 help '命令名' 可以查看单个命令的参数说明，比如 help 'create' 会列出 create 的完整语法和选项。
二、命名空间与表结构管理
命名空间是 HBase 中表的逻辑分组，默认命名空间为 default，系统表位于 hbase 和 hbase_meta 命名空间。创建命名空间使用 create_namespace 'ns1'，查看所有命名空间用 list_namespace，查看某个命名空间下的表用 list_namespace_tables 'ns1'。删除命名空间前必须保证其中没有表。
create_namespace 'ns1' list_namespace list_namespace_tables 'ns1' drop_namespace 'ns1'
创建表时需要至少指定一个列族。常用 create 命令的基本格式为 create '表名', '列族名'。如果要在创建时就设置版本数、TTL、压缩方式等属性，可以使用哈希参数。例如下面这条命令创建了一个包含 info 和 addr 两个列族的 user 表，info 列族保留 3 个版本，addr 列族使用 GZ 压缩。
create 'user', {NAME => 'info', VERSIONS => 3}, {NAME => 'addr', COMPRESSION => 'GZ'}
修改表结构使用 alter，可以新增列族、修改列族属性或删除列族。删除列族时使用 alter 'user', 'delete' => 'addr'，注意删除列族前不要误操作。表结构变更通常需要表处于 enabled 状态，个别操作需要先 disable。删除表必须先 disable 再 drop，否则命令会失败。truncate 'user' 会清空表数据但保留表结构，truncate_preserve 'user' 则同时保留 Region 划分，只清空数据，适合需要快速恢复写入的场景。
alter 'user', NAME => 'newcf', VERSIONS => 5 alter 'user', 'delete' => 'newcf' disable 'user' drop 'user' truncate 'user' truncate_preserve 'user'
对于写入量较大的表，可以在创建时进行预分区，避免数据只写入少数 Region 造成热点。预分区可以手动指定 SPLITS 数组，也可以使用十六进制前缀自动切分。例如 create 'log', 'data', SPLITS => ['100','200','300'] 会创建 4 个 Region。预分区策略直接影响后续写入负载分布，建表前应当估算 key 的分布情况。
三、数据写入、读取与扫描
写入单条数据使用 put 命令，格式为 put '表名', '行键', '列族:列名', '值'。HBase 支持指定时间戳，默认使用当前时间。下面示例向 user 表的 rk001 行写入 info:name 和 addr:city 两列，并指定时间戳。
put 'user', 'rk001', 'info:name', 'Tom' put 'user', 'rk001', 'addr:city', 'Beijing', 1700000000000
读取单行数据使用 get，可以指定列族、列名、版本数或时间范围。例如 get 'user', 'rk001', 'info:name' 只返回 name 列的最新值。如果要查看历史版本，需要带上 COLUMN 和 VERSIONS 参数，因为 HBase 默认只返回最新一个版本。
get 'user', 'rk001'
get 'user', 'rk001', 'info:name', {VERSIONS => 3}
get 'user', 'rk001', {COLUMN => 'info', TIMERANGE => [1699999999000, 1700000001000]}
批量读取数据使用 scan，支持指定起始行、结束行、返回行数、反转扫描等。默认情况下 scan 'user' 会扫描全表，生产环境建议配合 LIMIT 或行键范围使用。例如只扫描 rk001 到 rk099 之间的 50 行，并按行键倒序返回。
scan 'user', {STARTROW => 'rk001', STOPROW => 'rk100', LIMIT => 50}
scan 'user', {STARTROW => 'rk100', STOPROW => 'rk000', REVERSED => true}
scan 'user', {VERSIONS => 3}
删除数据有三个层次：delete 删除指定列的最新版本，deleteall 删除指定行的所有列，truncate 清空整表。HBase 的删除本质是写入墓碑标记，数据并不会立刻从磁盘消失，而是在后续 compaction 时被清理。因此删除后如果立即扫描，可能需要设置 RAW => true 才能看到原始数据。
delete 'user', 'rk001', 'info:name'
deleteall 'user', 'rk001'
scan 'user', {RAW => true, VERSIONS => 10}
四、过滤器与集群运维命令
当数据量较大时，仅仅依赖 STARTROW 和 STOPROW 往往不够灵活。HBase Shell 支持在 scan 中使用过滤器，例如 RowFilter 按行键匹配，PrefixFilter 按行键前缀过滤，ValueFilter 按单元格值过滤，SingleColumnValueFilter 按某列的值过滤整行。过滤器需要 import Java 类，命令会稍长一些，但可以大幅减少返回的数据量。
import org.apache.hadoop.hbase.filter.PrefixFilter
scan 'user', {FILTER => PrefixFilter.new('rk00')}
import org.apache.hadoop.hbase.filter.SingleColumnValueFilter
import org.apache.hadoop.hbase.filter.CompareFilter
import org.apache.hadoop.hbase.filter.BinaryComparator
scan 'user', {FILTER => SingleColumnValueFilter.new(Bytes.toBytes('info'), Bytes.toBytes('age'), CompareFilter::CompareOp.valueOf('EQUAL'), BinaryComparator.new(Bytes.toBytes('30')))}
集群运维命令中，list_regions '表名' 可以查看表的所有 Region 及分布位置；move 用于手动迁移某个 Region 到指定 RegionServer；split 手动分裂 Region；merge_region 合并相邻 Region。日常最常用的是 balancer 开关，它控制集群是否自动均衡 Region。例如在高写入时段可以先执行 balance_switch false 暂停均衡，减少网络开销。
list_regions 'user' move 'hash_of_region', 'hostname,16020,1699999999999' split 'hash_of_region' merge_region 'hash1', 'hash2' balance_switch false balancer
另外，flush 'user' 会把 MemStore 数据刷写到 HFile，major_compact 'user' 触发大合并，compact 'user' 触发小合并，用于清理墓碑和合并文件。快照命令 snapshot 'snapshot_name', 'user' 可以快速备份表元数据和文件引用，list_snapshots 查看快照，restore_snapshot 'snapshot_name' 恢复快照。这些命令在数据恢复和例行维护中非常实用。
flush 'user' compact 'user' major_compact 'user' snapshot 'user_snapshot_01', 'user' list_snapshots restore_snapshot 'user_snapshot_01'
进行 Region 合并、大合并或快照恢复前，建议先检查磁盘空间和写入负载，避免操作时间过长影响在线读写。可以通过 status 'detailed' 查看各 RegionServer 的请求指标，判断是否有热点 Region，再决定是否执行手动分裂或均衡。
HBase Shell常用命令HBase运维修改时间：2026-09-27 21:24:48