Beeline 使用方法完全指南

Beeline 是 Apache Hive 官方推荐的命令行客户端，从 Hive 0.11 版本开始引入，用于替代老旧的 Hive CLI。它基于 SQLLine 构建，通过 JDBC 协议连接 HiveServer2，支持多用户并发访问、Kerberos 认证、HTTP 传输等企业级特性。

一、为什么用 Beeline 而不是 Hive CLI

架构更优：Beeline 是瘦客户端，所有计算都在 HiveServer2 端完成；Hive CLI 每个实例都会启动一个完整的 Hive 驱动
并发安全：支持多用户同时连接，适合生产环境
认证完善：原生支持 Kerberos、LDAP、自定义认证
传输灵活：支持 TCP 和 HTTP 两种传输模式
官方趋势：Hive 社区已明确废弃 Hive CLI，后续版本将彻底移除

二、快速上手：连接 HiveServer2

2.1 最简连接

beeline -u jdbc:hive2://localhost:10000

默认端口 10000，无认证环境下直接连接。进入交互式界面后，提示符为：

0: jdbc:hive2://localhost:10000>

2.2 带用户名密码连接

beeline -u jdbc:hive2://hadoop01:10000 -n hive -p hive123

2.3 指定数据库连接

beeline -u jdbc:hive2://hadoop01:10000/default -n hive

2.4 交互式内连接

进入 Beeline 后手动连接：

beeline
!connect jdbc:hive2://hadoop01:10000
# 按提示输入用户名和密码

2.5 HTTP 模式连接

如果 HiveServer2 配置了 HTTP 传输（常用于跨防火墙场景）：

beeline -u "jdbc:hive2://hadoop01:10001/;transportMode=http;httpPath=cliservice"

三、核心命令行参数

3.1 连接类参数

参数	说明
`-u <url>`	JDBC 连接地址，最核心参数
`-n <username>`	用户名
`-p <password>`	密码
`-d <driver>`	JDBC 驱动类，默认 `org.apache.hive.jdbc.HiveDriver`
`-r`	重连到上次保存的连接

3.2 执行类参数

参数	说明
`-e <sql>`	执行单条 SQL，执行完自动退出
`-f <file>`	执行 SQL 脚本文件，执行完自动退出
`-i <file>`	启动时先执行初始化脚本，保留交互式界面

示例：

# 执行单条查询
beeline -u jdbc:hive2://hadoop01:10000 -e "SELECT * FROM users LIMIT 10;"

# 执行脚本文件
beeline -u jdbc:hive2://hadoop01:10000 -f /path/to/query.hql

注意：-f 执行完退出，-i 执行完留在交互界面。

3.3 变量传递

参数	说明
`--hiveconf key=value`	设置 Hive 配置项
`--hivevar name=value`	定义 SQL 中可引用的变量

示例：

beeline -u jdbc:hive2://hadoop01:10000 \
  --hiveconf hive.exec.dynamic.partition=true \
  --hivevar dt=20260825 \
  -e "SELECT * FROM logs WHERE dt='${dt}';"

3.4 输出格式控制

参数	说明
`--outputformat=<format>`	输出格式：table/vertical/csv/tsv/dsv
`--showHeader=[true/false]`	是否显示列名表头
`--color=[true/false]`	是否彩色输出
`--showDbInPrompt=[true/false]`	提示符中显示当前数据库

导出 CSV 示例：

beeline -u jdbc:hive2://hadoop01:10000 \
  --outputformat=csv --showHeader=false \
  -e "SELECT id,name FROM users;" > result.csv

四、交互式命令（! 开头）

进入 Beeline 后，所有以 ! 开头的是 Beeline 自身命令，不以 ; 结尾。

4.1 连接管理

!connect <url> [user] [pass]   # 新建连接
!close                          # 关闭当前连接
!closeall                       # 关闭所有连接
!reconnect                      # 重连当前连接
!list                           # 列出所有连接
!quit / !exit                   # 退出 Beeline

4.2 元数据查看

!tables                         # 列出当前库所有表
!columns <table>                # 列出表的所有字段
!describe <table>               # 描述表结构
!indexes <table>                # 列出表索引

4.3 输出与脚本

!record <file>                  # 开始记录输出到文件
!record                         # 停止记录
!run <file>                     # 执行脚本文件
!script <file>                  # 将后续操作保存为脚本

4.4 环境设置

!set <key> <value>              # 设置 Beeline 变量
!set fetchsize 2000             # 设置每次拉取行数
!set timeout 300                # 设置查询超时秒数
!verbose                        # 切换详细模式
!sh <command>                   # 执行本地 Shell 命令

4.5 其他

!help                           # 查看所有命令
!history                        # 查看命令历史
!save                           # 保存当前配置

五、Hive SQL 常用操作

进入连接后，正常的 HiveQL 语句以 ; 结尾，和 Hive CLI 基本一致。

5.1 库表操作

-- 查看数据库
SHOW DATABASES;

-- 切换数据库
USE default;

-- 查看表
SHOW TABLES;
SHOW TABLES LIKE '*user*';

-- 查看表结构
DESC users;
DESC FORMATTED users;  -- 详细信息

5.2 配置管理

-- 查看所有已覆盖配置
SET;

-- 查看所有配置（含默认值）
SET -v;

-- 设置参数
SET hive.exec.dynamic.partition.mode=nonstrict;
SET hive.execution.engine=spark;

-- 重置为默认
RESET;
RESET hive.exec.dynamic.partition.mode;

5.3 资源加载

-- 添加 Jar 包
ADD JAR /path/to/udf.jar;

-- 添加文件
ADD FILE /path/to/mapper.py;

-- 查看已添加资源
LIST JARS;
LIST FILES;

六、进阶技巧

6.1 免密连接配置

创建 beeline.properties 文件：

beeline.url=jdbc:hive2://hadoop01:10000/default
beeline.username=hive
beeline.password=hive123

启动时指定：

beeline -i beeline.properties

6.2 批量执行多个 SQL 文件

for sql in *.hql; do
  beeline -u jdbc:hive2://hadoop01:10000 -f "$sql"
done

6.3 美化输出与排错

# 垂直显示，适合宽表
beeline --outputformat=vertical -e "SELECT * FROM users LIMIT 1;"

# 开启详细日志
beeline --verbose=true -u jdbc:hive2://hadoop01:10000

6.4 Kerberos 环境连接

kinit -kt /etc/security/keytabs/hive.keytab hive/hadoop01@EXAMPLE.COM
beeline -u "jdbc:hive2://hadoop01:10000/;principal=hive/_HOST@EXAMPLE.COM"

七、常见问题排查

1. Connection refused

检查 HiveServer2 是否启动：ps aux | grep HiveServer2
确认端口和主机名是否正确
检查防火墙和网络连通性

2. 连接卡住无响应

大概率是认证方式不匹配。服务端 NoSASL 时，客户端需加 ;auth=noSasl
检查 ZooKeeper 和 Metastore 状态

3. 输出中文乱码

启动前设置：export LANG=en_US.UTF-8
JDBC URL 追加：?characterEncoding=UTF-8

4. 查询结果显示不全

增大 fetchsize：!set fetchsize 5000
或使用 --incremental=true 增量输出

八、最佳实践

生产环境用 Beeline，抛弃 Hive CLI：官方已废弃，新特性不再支持
脚本化用 -f，交互式直接进：各司其职，不要混用
敏感配置不要写死在命令行：用配置文件或环境变量传递密码
大结果集导出用 CSV + 重定向：比默认表格格式快得多
复杂查询前先 EXPLAIN：观察执行计划，避免全表扫描
定期清理会话：长时间不操作主动 !quit，释放服务端资源

Beeline 的核心就两件事：怎么连和怎么查。掌握了连接参数和常用的 ! 命令，日常开发基本够用。剩下的就是 Hive SQL 本身的功力了。

知识花园

探索

Beeline