Apache IoTDB 常用 CLI 命令与工具详解
详解 Apache IoTDB 2.0.11 CLI 客户端（start-cli.sh）全部启动参数、交互式客户端命令与常用 SQL（建库建测点、插入、查询、聚合、分页）及配套运维工具脚本，命令与回显均实测。
Apache IoTDBApache IoTDB数据库Apache运维时间序列2026/10/11
Apache IoTDB 常用 CLI 命令与工具详解
目标：完整讲解 Apache IoTDB 2.0.11 的 CLI 客户端
sbin/start-cli.sh的启动参数、交互式命令与常用 SQL，以及安装目录tools/下的运维/导入导出工具脚本。文中所有参数帮助与命令回显均取自/opt/iotdb-exp/apache-iotdb-2.0.11-all-bin实测输出。
一、环境信息
- 版本：Apache IoTDB 2.0.11（Build 7c0de06）
- 安装根目录：
/opt/iotdb-exp/apache-iotdb-2.0.11-all-bin - CLI 脚本：
sbin/start-cli.sh（Windows 为sbin/windows/start-cli.bat） - 服务地址：
127.0.0.1:6667（dn_rpc_port） - 测试账号：root / 密码
q1w2e3r4 - JDK：OpenJDK 17.0.20.1
二、工具概览
| 工具 | 位置 | 用途 |
|---|---|---|
| CLI 客户端 | sbin/start-cli.sh | 连接 DataNode，执行 SQL |
| 数据导出 | tools/export-data.sh | 导出数据（CSV） |
| 数据导入 | tools/import-data.sh | 导入 CSV 数据 |
| TsFile 导出/校验 | tools/export-tsfile.sh、tools/tsfile/*.sh | 导出/校验 TsFile |
| Schema 导入导出 | tools/schema/export-schema.sh、import-schema.sh | 迁移测点元数据 |
| 运维检查 | tools/ops/health_check.sh、collect-info.sh、backup.sh | 健康检查/信息收集/备份 |
| WAL 查看 | tools/wal/print-wal.sh | 解析 WAL 文件 |
三、前置条件
- 服务端已启动（
start-standalone.sh拉起 ConfigNode + DataNode），6667端口可连通。 - 已设置
JAVA_HOME或PATH中能找到 Java 17+（CLI 同样依赖 JDK）。 - 知道服务地址、端口、用户名与密码（本文示例 root /
q1w2e3r4）。
四、CLI 客户端详解（start-cli.sh）
4.1 启动参数（-help 实测）
cd /opt/iotdb-exp/apache-iotdb-2.0.11-all-bin
sbin/start-cli.sh -help
实测回显：
usage: ./start-cli.sh(start-cli.bat if Windows) [-c] [-disableISO8601] [-e <execute>]
[-h <host>] [-help] [-kpw <key_store_pwd>] [-ks <key_store>] [-p <port>] [-pw
<password>] [-sql_dialect <sql_dialect>] [-ssl_protocol <ssl_protocol>] [-timeout
<queryTimeout>] [-tpw <trust_store_pwd>] [-ts <trust_store>] -u <username>
[-usessl <use_ssl>]
-c Enable or disable Rpc Compression.
(optional)
-disableISO8601 Display timestamp in numeric format.
(optional)
-e <execute> Execute a statement. (optional)
-h <host> Host Name. Default is 127.0.0.1.
(optional)
-help Display help information. (optional)
-kpw,--key_store_pwd <key_store_pwd> Key store password for mutual SSL.
(optional)
-ks,--key_store <key_store> Key store for mutual SSL. (optional)
-p <port> Port. Default is 6667. (optional)
-pw <password> Password. Default is root. (optional)
-sql_dialect <sql_dialect> Currently supports tree and table; uses
tree if not set. (optional)
-ssl_protocol,--ssl_protocol <ssl_protocol> SSL protocol. (optional)
-timeout <queryTimeout> The timeout in seconds. Uses the server
configuration if not set. (optional)
-tpw,--trust_store_pwd <trust_store_pwd> Trust store password. (optional)
-ts,--trust_store <trust_store> Trust store. (optional)
-u <username> User name. (required)
-usessl <use_ssl> Use SSL statement. (optional)
💡 说明：常用参数为
-h <地址>、-p <端口>、-u <用户>、-pw <密码>、-e "<SQL>"（单条执行）与-disableISO8601（时间戳显示为长整型）。
4.2 非交互单条执行
sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw q1w2e3r4 -e "SHOW VERSION;"
回显：
+-------+---------+
|Version|BuildInfo|
+-------+---------+
| 2.0.11| 7c0de06|
+-------+---------+
Total line number = 1
It costs 0.026s
4.3 交互式连接
sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw q1w2e3r4
连接成功横幅（实测）：
---------------------
Starting IoTDB Cli
---------------------
_____ _________ ______ ______
|_ _| | _ _ ||_ _ `.|_ _ \
| | .--.|_/ | | \_| | | `. \ | |_) |
| | / .'`\ \ | | | | | | | __'.
_| |_| \__. | _| |_ _| |_.' /_| |__) |
|_____|'.__.' |_____| |______.'|_______/ version 2.0.11 (Build: 7c0de06)
Successfully login at 127.0.0.1:6667
IoTDB>
输入 exit 或 quit 退出；Ctrl+C 中断当前查询。
4.4 交互式客户端命令（help; 实测）
IoTDB> help;
<your-sql> execute your sql statment
show timeseries show how many timeseries are in iotdb
set time_display_type=xxx eg. long, default, ISO8601, yyyy-MM-dd HH:mm:ss.
show time_display_type show time display type
set time_zone=xxx eg. +08:00, Asia/Shanghai.
show time_zone show cli time zone
set fetch_size=xxx set fetch size when querying data from server.
show fetch_size show fetch size
💡 说明：上面帮助文本中的取值示意符（如
set time_display_type=后接long、ISO8601等）是 CLI 工具自身帮助文字，并非本指南待填的部署占位。
客户端会话内设置（实测回显）：
SET TIME_ZONE=+08:00;
-- 回显: Current time zone: +08:00
SET FETCH_SIZE=100;
-- 回显: Fetch size has set to 100
SET TIME_DISPLAY_TYPE=long;
-- 回显: Time display type has set to long
五、常用 SQL 详解
5.1 建库（database）与查库
CREATE DATABASE root.iot;
-- 回显: Msg: The statement is executed successfully.
SHOW DATABASES;
SHOW DATABASES; 回显（实测）：
+--------+-----------------------+---------------------+-------------------+---------------------+
|Database|SchemaReplicationFactor|DataReplicationFactor|TimePartitionOrigin|TimePartitionInterval|
+--------+-----------------------+---------------------+-------------------+---------------------+
|root.iot| 1| 1| 0| 604800000|
+--------+-----------------------+---------------------+-------------------+---------------------+
Total line number = 1
It costs 0.123s
5.2 建测点（时间序列 schema）
CREATE TIMESERIES root.iot.sensor.temperature WITH DATATYPE=FLOAT, ENCODING=PLAIN, COMPRESSOR=SNAPPY;
CREATE TIMESERIES root.iot.sensor.humidity WITH DATATYPE=DOUBLE, ENCODING=PLAIN, COMPRESSOR=SNAPPY;
SHOW TIMESERIES;
SHOW TIMESERIES; 回显（实测）：
+---------------------------+-----+--------+--------+--------+-----------+----+----------+--------+------------------+--------+
| Timeseries|Alias|Database|DataType|Encoding|Compression|Tags|Attributes|Deadband|DeadbandParameters|ViewType|
+---------------------------+-----+--------+--------+--------+-----------+----+----------+--------+------------------+--------+
|root.iot.sensor.temperature| null|root.iot| FLOAT| PLAIN| SNAPPY|null| null| null| null| BASE|
| root.iot.sensor.humidity| null|root.iot| DOUBLE| PLAIN| SNAPPY|null| null| null| null| BASE|
+---------------------------+-----+--------+--------+--------+-----------+----+----------+--------+------------------+--------+
Total line number = 2
It costs 0.963s
5.3 插入数据
单条与批量插入（实测）：
INSERT INTO root.iot.sensor(timestamp, temperature, humidity) VALUES (1690000000000, 25.5, 60.0);
-- 回显: Msg: The statement is executed successfully.
INSERT INTO root.iot.sensor(timestamp, temperature, humidity) VALUES (1690000001000, 26.2, 58.8), (1690000002000, 27.0, 61.5);
-- 回显: Msg: The statement is executed successfully.
5.4 数据查询
全量查询（实测）：
SELECT * FROM root.iot.sensor;
+------------------------+---------------------------+------------------------+
| Time|root.iot.sensor.temperature|root.iot.sensor.humidity|
+------------------------+---------------------------+------------------------+
|2023-07-22T04:26:40.000Z| 25.5| 60.0|
|2023-07-22T04:26:41.000Z| 26.2| 58.8|
|2023-07-22T04:26:42.000Z| 27.0| 61.5|
+------------------------+---------------------------+------------------------+
Total line number = 3
It costs 0.332s
时间范围过滤（实测）：
SELECT temperature FROM root.iot.sensor WHERE time >= 1690000001000 AND time <= 1690000002000;
+------------------------+---------------------------+
| Time|root.iot.sensor.temperature|
+------------------------+---------------------------+
|2023-07-22T04:26:41.000Z| 26.2|
|2023-07-22T04:26:42.000Z| 27.0|
+------------------------+---------------------------+
Total line number = 2
It costs 0.095s
时间戳以长整型显示（-disableISO8601 实测）：
+-------------+---------------------------+------------------------+
| Time|root.iot.sensor.temperature|root.iot.sensor.humidity|
+-------------+---------------------------+------------------------+
|1690000000000| 25.5| 60.0|
|1690000001000| 26.2| 58.8|
|1690000002000| 27.0| 61.5|
+-------------+---------------------------+------------------------+
Total line number = 3
It costs 0.111s
5.5 聚合与分组查询
聚合函数（SHOW FUNCTIONS 中 FunctionType=native 的完整清单，实测）：
COUNT COUNT_TIME COUNT_IF SUM AVG EXTREME MAX_VALUE MIN_VALUE FIRST_VALUE LAST_VALUE
MAX_TIME MIN_TIME MAX_BY MIN_BY STDDEV STDDEV_POP STDDEV_SAMP VARIANCE VAR_POP VAR_SAMP
SKEWNESS KURTOSIS MODE TIME_DURATION REGR_SLOPE REGR_INTERCEPT CORR COVAR_POP COVAR_SAMP
⚠️ 注意：2.0.11 中
MAX/MIN不是内置聚合函数（实测报UDF MAX has not been registered），应使用MAX_VALUE/MIN_VALUE。
单测点聚合（实测）：
SELECT AVG(temperature) FROM root.iot.sensor;
-- 回显:
-- +--------------------------------+
-- |AVG(root.iot.sensor.temperature)|
-- +--------------------------------+
-- | 26.233333587646484|
-- +--------------------------------+
-- Total line number = 1
-- It costs 0.037s
多函数聚合（实测）：
SELECT max_value(humidity), min_value(temperature), first_value(temperature), last_value(humidity) FROM root.iot.sensor;
+-----------------------------------+--------------------------------------+----------------------------------------+------------------------------------+
|max_value(root.iot.sensor.humidity)|min_value(root.iot.sensor.temperature)|first_value(root.iot.sensor.temperature)|last_value(root.iot.sensor.humidity)|
+-----------------------------------+--------------------------------------+----------------------------------------+------------------------------------+
| 61.5| 25.5| 25.5| 61.5|
+-----------------------------------+--------------------------------------+----------------------------------------+------------------------------------+
Total line number = 1
It costs 0.041s
计数（实测）：
SELECT COUNT(*) FROM root.iot.sensor;
+----------------------------------+-------------------------------+
|COUNT(root.iot.sensor.temperature)|COUNT(root.iot.sensor.humidity)|
+----------------------------------+-------------------------------+
| 3| 3|
+----------------------------------+-------------------------------+
Total line number = 1
It costs 0.093s
按秒分组（实测）：
SELECT count(*) FROM root.iot.sensor GROUP BY ([1690000000000, 1690000003000), 1s);
+------------------------+----------------------------------+-------------------------------+
| Time|count(root.iot.sensor.temperature)|count(root.iot.sensor.humidity)|
+------------------------+----------------------------------+-------------------------------+
|2023-07-22T04:26:40.000Z| 1| 1|
|2023-07-22T04:26:41.000Z| 1| 1|
|2023-07-22T04:26:42.000Z| 1| 1|
+------------------------+----------------------------------+-------------------------------+
Total line number = 3
It costs 0.068s
💡 说明：
GROUP BY ([左闭, 右开), 间隔)中左闭右开，间隔单位支持1s/1m/1h等。原生数据列与聚合列不能混查（实测报Raw data and aggregation hybrid query is not supported），需拆成两条 SQL。
5.6 设备与元数据查看
SHOW DEVICES;
-- 回显:
-- +---------------+---------+--------+-------+
-- | Device|IsAligned|Template|TTL(ms)|
-- +---------------+---------+--------+-------+
-- |root.iot.sensor| false| null| INF|
-- +---------------+---------+--------+-------+
-- Total line number = 1
-- It costs 0.040s
SHOW FUNCTIONS; -- 列出全部 UDTF 与原生聚合函数
5.7 用户与权限
ALTER USER root SET PASSWORD "q1w2e3r4";
-- 回显: Msg: The statement is executed successfully.
⚠️ 注意：IoTDB 默认 root 密码为
root，首次连接后应立即修改；SET PASSWORD的参数为字符串，注意引号转义。
六、配套工具脚本详解
6.1 数据导入导出
cd /opt/iotdb-exp/apache-iotdb-2.0.11-all-bin
tools/export-data.sh -h 127.0.0.1 -p 6667 -u root -pw q1w2e3r4 -q "SELECT * FROM root.iot.sensor"
tools/import-data.sh -h 127.0.0.1 -p 6667 -u root -pw q1w2e3r4 -f /tmp/export.csv
💡 说明：
export-data.sh按-q查询导出 CSV，import-data.sh支持-f <文件>导入；参数细节可用-help查看。
6.2 Schema 迁移
tools/schema/export-schema.sh -h 127.0.0.1 -p 6667 -u root -pw q1w2e3r4 -f /tmp/schema.sql
tools/schema/import-schema.sh -h 127.0.0.1 -p 6667 -u root -pw q1w2e3r4 -f /tmp/schema.sql
6.3 健康检查与信息收集
tools/ops/health_check.sh
tools/ops/collect-info.sh
6.4 TsFile 校验与 WAL 查看
tools/tsfile/validate-tsfile.sh
tools/tsfile/print-tsfile.sh
tools/wal/print-wal.sh
七、注意事项
- CLI 单条执行用
-e "SQL"；交互模式命令以;结尾。 - 时间戳默认显示 ISO8601；脚本加
-disableISO8601或会话内SET TIME_DISPLAY_TYPE=long可显示长整型。 - 聚合函数与原生列不能出现在同一条
SELECT中。 MAX/MIN非内置聚合，用MAX_VALUE/MIN_VALUE。DESCRIBE关键字在 2.0.11 不支持（实测报语法错误），查看测点用SHOW TIMESERIES。
八、常见问题
Q1：连不上 127.0.0.1:6667？
原因：DataNode 未就绪或端口未监听。确认 start-standalone.sh 已执行、netstat -tlnp | grep 6667 有监听，并稍等日志出现 IoTDB DataNode is set up successfully。
Q2：报 Error occurred while parsing SQL to physical plan？
原因：SQL 语法在当前方言不支持（如 DESCRIBE、混查聚合与原生列）。换成 SHOW TIMESERIES 或拆 SQL 重试。
Q3：SELECT MAX(列) 报 UDF MAX has not been registered？
原因：MAX 不是内置函数名。改用 max_value(列) 聚合函数。
Q4：中文/引号导致 -e 执行失败？
原因：-e 参数里的引号需转义。例如改密码用 -e "ALTER USER root SET PASSWORD \"q1w2e3r4\";"；多语句建议进交互模式执行。
九、参考链接
- Apache IoTDB 用户指南（中文）：
https://iotdb.apache.org/zh/UserGuide/latest/ - 官方下载：
https://downloads.apache.org/iotdb/ - 配置与安装见《Apache IoTDB 配置参数详解》与《Ubuntu 22.04 安装 Apache IoTDB 2.0.11 指南》篇。
章节目录