运维语句

1. 状态查看

1.1 查看连接的模型

含义：返回当前连接的 sql_dialect 是树模型/表模型。

语法：

showCurrentSqlDialectStatement
    : SHOW CURRENT_SQL_DIALECT
    ;

示例：

IoTDB> SHOW CURRENT_SQL_DIALECT

执行结果如下：

+-----------------+
|CurrentSqlDialect|
+-----------------+
|             TREE|
+-----------------+

1.2 查看集群版本

含义：返回当前集群的版本。

语法：

showVersionStatement
    : SHOW VERSION
    ;

示例：

IoTDB> SHOW VERSION

执行结果如下：

+-------+---------+
|Version|BuildInfo|
+-------+---------+
|2.0.1.2|  1ca4008|
+-------+---------+

1.3 查看集群关键参数

含义：返回当前集群的关键参数。

语法：

showVariablesStatement
    : SHOW VARIABLES
    ;

关键参数如下：

ClusterName：当前集群的名称。
DataReplicationFactor：数据副本的数量，表示每个数据分区（DataRegion）的副本数。
SchemaReplicationFactor：元数据副本的数量，表示每个元数据分区（SchemaRegion）的副本数。
DataRegionConsensusProtocolClass：数据分区（DataRegion）使用的共识协议类。
SchemaRegionConsensusProtocolClass：元数据分区（SchemaRegion）使用的共识协议类。
ConfigNodeConsensusProtocolClass：配置节点（ConfigNode）使用的共识协议类。
TimePartitionOrigin：数据库时间分区的起始时间戳。
TimePartitionInterval：数据库的时间分区间隔（单位：毫秒）。
ReadConsistencyLevel：读取操作的一致性级别。
SchemaRegionPerDataNode：数据节点（DataNode）上的元数据分区（SchemaRegion）数量。
DataRegionPerDataNode：数据节点（DataNode）上的数据分区（DataRegion）数量。
SeriesSlotNum：数据分区（DataRegion）的序列槽（SeriesSlot）数量。
SeriesSlotExecutorClass：序列槽的实现类。
DiskSpaceWarningThreshold：磁盘空间告警阈值（单位：百分比）。
TimestampPrecision：时间戳精度。

示例：

IoTDB> SHOW VARIABLES

执行结果如下：

+----------------------------------+-----------------------------------------------------------------+
|                          Variable|                                                            Value|
+----------------------------------+-----------------------------------------------------------------+
|                       ClusterName|                                                   defaultCluster|
|             DataReplicationFactor|                                                                1|
|           SchemaReplicationFactor|                                                                1|
|  DataRegionConsensusProtocolClass|                      org.apache.iotdb.consensus.iot.IoTConsensus|
|SchemaRegionConsensusProtocolClass|                  org.apache.iotdb.consensus.ratis.RatisConsensus|
|  ConfigNodeConsensusProtocolClass|                  org.apache.iotdb.consensus.ratis.RatisConsensus|
|               TimePartitionOrigin|                                                                0|
|             TimePartitionInterval|                                                        604800000|
|              ReadConsistencyLevel|                                                           strong|
|           SchemaRegionPerDataNode|                                                                1|
|             DataRegionPerDataNode|                                                                0|
|                     SeriesSlotNum|                                                             1000|
|           SeriesSlotExecutorClass|org.apache.iotdb.commons.partition.executor.hash.BKDRHashExecutor|
|         DiskSpaceWarningThreshold|                                                             0.05|
|                TimestampPrecision|                                                               ms|
+----------------------------------+-----------------------------------------------------------------+

1.4 查看数据库当前时间

语法：

含义：返回数据库当前时间。

showCurrentTimestampStatement
    : SHOW CURRENT_TIMESTAMP
    ;

示例：

IoTDB> SHOW CURRENT_TIMESTAMP

执行结果如下：

+-----------------------------+
|             CurrentTimestamp|
+-----------------------------+
|2025-02-17T11:11:52.987+08:00|
+-----------------------------+

1.5 查看正在执行的查询信息

含义：用于显示所有正在执行的查询信息。

语法：

showQueriesStatement
    : SHOW (QUERIES | QUERY PROCESSLIST)
        (WHERE where=booleanExpression)?
        (ORDER BY sortItem (',' sortItem)*)?
        limitOffsetClause
    ;

参数解释：

WHERE 子句：需保证过滤的目标列是结果集中存在的列
ORDER BY 子句：需保证sortKey是结果集中存在的列
limitOffsetClause：
- 含义：用于限制结果集的返回数量。
- 格式：LIMIT <offset>, <row_count>， <offset> 是偏移量，<row_count> 是返回的行数。
QUERIES 表中的列：
- time：查询开始的时间戳，时间戳精度与系统精度一致
- queryid：查询语句的 ID
- datanodeid：发起查询语句的 DataNode 的ID
- elapsedtime：查询的执行耗时，单位是秒
- statement：查询的 SQL 语句

示例：

IoTDB> SHOW QUERIES WHERE elapsedtime > 0.003

执行结果如下：

+-----------------------------+-----------------------+----------+-----------+--------------------------------------+
|                         Time|                QueryId|DataNodeId|ElapsedTime|                             Statement|
+-----------------------------+-----------------------+----------+-----------+--------------------------------------+
|2025-05-09T15:16:01.293+08:00|20250509_071601_00015_1|         1|      0.006|SHOW QUERIES WHERE elapsedtime > 0.003|
+-----------------------------+-----------------------+----------+-----------+--------------------------------------+

1.6 查看分区信息

含义：返回当前集群的分区信息。

语法：

showRegionsStatement
    : SHOW REGIONS
    ;

示例：

IoTDB> SHOW REGIONS

执行结果如下：

+--------+------------+-------+-------------+-------------+-----------+----------+----------+-------+---------------+------+-----------------------+----------+
|RegionId|        Type| Status|     Database|SeriesSlotNum|TimeSlotNum|DataNodeId|RpcAddress|RpcPort|InternalAddress|  Role|             CreateTime|TsFileSize|
+--------+------------+-------+-------------+-------------+-----------+----------+----------+-------+---------------+------+-----------------------+----------+
|       9|SchemaRegion|Running|root.__system|           21|          0|         1|   0.0.0.0|   6667|      127.0.0.1|Leader|2025-08-01T17:37:01.555|          |
|      10|  DataRegion|Running|root.__system|           21|         21|         1|   0.0.0.0|   6667|      127.0.0.1|Leader|2025-08-01T17:37:01.556|   8.27 KB|
|      65|SchemaRegion|Running|      root.ln|            1|          0|         1|   0.0.0.0|   6667|      127.0.0.1|Leader|2025-08-25T14:46:50.113|          |
|      66|  DataRegion|Running|      root.ln|            1|          1|         1|   0.0.0.0|   6667|      127.0.0.1|Leader|2025-08-25T14:46:50.425|     524 B|
+--------+------------+-------+-------------+-------------+-----------+----------+----------+-------+---------------+------+-----------------------+----------+

1.7 查看可用节点

含义：返回当前集群所有可用的 DataNode 的 RPC 地址和端口。注意：这里对于“可用”的定义为：处于非 REMOVING 状态的 DN 节点。

V2.0.8 起支持该功能

语法：

showAvailableUrlsStatement
    : SHOW AVAILABLE URLS
    ;

示例：

IoTDB> SHOW AVAILABLE URLS

执行结果如下：

+----------+-------+
|RpcAddress|RpcPort|
+----------+-------+
|   0.0.0.0|   6667|
+----------+-------+

1.8 查看服务信息

含义：返回当前集群所有正常工作（RUNNING 或 READ-ONLY） DN 上的服务信息（MQTT 服务、REST 服务）。

V2.0.8.2 起支持该功能

语法：

showServicesStatement
    : SHOW SERVICES <ON dataNodeId>
    ;

示例：

IoTDB> SHOW SERVICES
IoTDB> SHOW SERVICES ON 1

执行结果如下：

+------------+-----------+-------+
|service_name|datanode_id|  state|
+------------+-----------+-------+
|        MQTT|          1|STOPPED|
|        REST|          1|RUNNING|
+------------+-----------+-------+

1.9 查看集群激活状态

含义：返回当前集群的激活状态。

语法：

showActivationStatement
    : SHOW ACTIVATION
    ;

示例：

IoTDB> SHOW ACTIVATION

执行结果如下：

+---------------+---------+-----------------------------+
|    LicenseInfo|    Usage|                        Limit|
+---------------+---------+-----------------------------+
|         Status|ACTIVATED|                            -|
|    ExpiredTime|        -|2026-04-30T00:00:00.000+08:00|
|  DataNodeLimit|        1|                    Unlimited|
|       CpuLimit|       16|                    Unlimited|
|    DeviceLimit|       30|                    Unlimited|
|TimeSeriesLimit|       72|                1,000,000,000|
+---------------+---------+-----------------------------+

1.10 查看磁盘空间占用情况

含义：返回指定 pattern 的磁盘空间占用情况，包括 ChunkGroup 的大小和 Metadata 大小。

注意：统计基于 TsFile 中数据的真实大小，因此不会考虑 mods 删除的情况。

V2.0.9.1 起支持该功能

语法：

showDiskUsageStatement
    : SHOW DISK_USAGE FROM pathPattern 
    whereClause?
    orderByClause?
    rowPaginationClause?
    ;
pathPattern
    : ROOT (DOT nodeName)*
    ;

说明：Pattern 用于匹配设备，需要使用 root 作为开头，路径的中间节点支持 * 或 **。

结果集

列名	列类型	含义
Database	string	Database 名
DataNodeId	int32	DataNode 节点 id
RegionId	int32	Region id
TimePartition	int64	时间分区 id
SizeInBytes	int64	占用磁盘空间(byte)

示例：

SHOW DISK_USAGE FROM root.ln.**；

执行结果如下：

+--------+----------+--------+-------------+-----------+
|Database|DataNodeId|RegionId|TimePartition|SizeInBytes|
+--------+----------+--------+-------------+-----------+
| root.ln|         1|      13|         2932|        203|
+--------+----------+--------+-------------+-----------+

2. 状态设置

2.1 设置连接的模型

含义：将当前连接的 sql_dialect 置为树模型/表模型，在树模型和表模型中均可使用该命令。

语法：

SET SQL_DIALECT EQ (TABLE | TREE)

示例：

IoTDB> SET SQL_DIALECT=TREE
IoTDB> SHOW CURRENT_SQL_DIALECT

执行结果如下：

+-----------------+
|CurrentSqlDialect|
+-----------------+
|            TREE|
+-----------------+

2.2 更新配置项

含义：用于更新配置项，执行完成后会进行配置项的热加载，对于支持热修改的配置项会立即生效。

语法：

setConfigurationStatement
    : SET CONFIGURATION propertyAssignments (ON INTEGER_VALUE)?
    ;

propertyAssignments
    : property (',' property)*
    ;
    
property
    : identifier EQ propertyValue
    ;

propertyValue
    : DEFAULT
    | expression
    ;

参数解释：

propertyAssignments
- 含义：更新的配置列表，由多个 property 组成。
- 可以更新多个配置列表，用逗号分隔。
- 取值：
  - DEFAULT：将配置项恢复为默认值。
  - expression：具体的值，必须是一个字符串。
ON INTEGER_VALUE
- 含义：指定要更新配置的节点 ID。
- 可选性：可选。如果不指定或指定的值低于 0，则更新所有 ConfigNode 和 DataNode 的配置。

示例：

IoTDB> SET CONFIGURATION 'disk_space_warning_threshold'='0.05','heartbeat_interval_in_ms'='1000' ON 1;

2.3 读取手动修改的配置文件

含义：用于读取手动修改过的配置文件，并对配置项进行热加载，对于支持热修改的配置项会立即生效。

语法：

loadConfigurationStatement
    : LOAD CONFIGURATION localOrClusterMode?
    ;
    
localOrClusterMode
    : (ON (LOCAL | CLUSTER))
    ;

参数解释：

localOrClusterMode
- 含义：指定配置热加载的范围。
- 可选性：可选。默认值为 CLUSTER。
- 取值：
  - LOCAL：只对客户端直连的 DataNode 进行配置热加载。
  - CLUSTER：对集群中所有 DataNode 进行配置热加载。

示例：

IoTDB> LOAD CONFIGURATION ON LOCAL;

2.4 设置系统的状态

含义：用于设置系统的状态。

语法：

setSystemStatusStatement
    : SET SYSTEM TO (READONLY | RUNNING) localOrClusterMode?
    ;    
    
localOrClusterMode
    : (ON (LOCAL | CLUSTER))
    ;

参数解释：

RUNNING | READONLY
- 含义：指定系统的新状态。
- 取值：
  - RUNNING：将系统设置为运行状态，允许读写操作。
  - READONLY：将系统设置为只读状态，只允许读取操作，禁止写入操作。
localOrClusterMode
- 含义：指定状态变更的范围。
- 可选性：可选。默认值为 CLUSTER。
- 取值：
  - LOCAL：仅对客户端直连的 DataNode 生效。
  - CLUSTER：对集群中所有 DataNode 生效。

示例：

IoTDB> SET SYSTEM TO READONLY ON CLUSTER;

3. 数据管理

3.1 刷写内存表中的数据到磁盘

含义：将内存表中的数据刷写到磁盘上。

语法：

flushStatement
    : FLUSH identifier? (',' identifier)* booleanValue? localOrClusterMode?
    ;

booleanValue
    : TRUE | FALSE
    ;

localOrClusterMode
    : (ON (LOCAL | CLUSTER))
    ;

参数解释：

identifier
- 含义：指定要刷写的路径名称。
- 可选性：可选。如果不指定，则默认刷写所有路径。
- 多个路径：可以指定多个路径名称，用逗号分隔。例如：FLUSH root.ln, root.lnm。
booleanValue
- 含义：指定刷写的内容。
- 可选性：可选。如果不指定，则默认刷写顺序和乱序空间的内存。
- 取值：
  - TRUE：只刷写顺序空间的内存表。
  - FALSE：只刷写乱序空间的MemTable。
localOrClusterMode
- 含义：指定刷写的范围。
- 可选性：可选。默认值为 CLUSTER。
- 取值：
  - ON LOCAL：只刷写客户端直连的 DataNode 上的内存表。
  - ON CLUSTER：刷写集群中所有 DataNode 上的内存表。

示例：

IoTDB> FLUSH root.ln TRUE ON LOCAL;

4. 数据修复

4.1 启动后台扫描并修复 tsfile 任务

含义：启动一个后台任务，开始扫描并修复 tsfile，能够修复数据文件内的时间戳乱序类异常。

语法：

startRepairDataStatement
    : START REPAIR DATA localOrClusterMode?
    ;
    
localOrClusterMode
    : (ON (LOCAL | CLUSTER))
    ;

参数解释：

localOrClusterMode
- 含义：指定数据修复的范围。
- 可选性：可选。默认值为 CLUSTER。
- 取值：
  - ON LOCAL：仅对客户端直连的 DataNode 执行。
  - ON CLUSTER：对集群中所有 DataNode 执行。

示例：

IoTDB> START REPAIR DATA ON CLUSTER;

4.2 暂停后台修复 tsfile 任务

含义：暂停后台的修复任务，暂停中的任务可通过再次执行 start repair data 命令恢复。

语法：

stopRepairDataStatement
    : STOP REPAIR DATA localOrClusterMode?
    ;
    
localOrClusterMode
    : (ON (LOCAL | CLUSTER))
    ;

参数解释：

localOrClusterMode
- 含义：指定数据修复的范围。
- 可选性：可选。默认值为 CLUSTER。
- 取值：
  - ON LOCAL：仅对客户端直连的 DataNode 执行。
  - ON CLUSTER：对集群中所有 DataNode 执行。

示例：

IoTDB> STOP REPAIR DATA ON CLUSTER;

5. 终止查询

5.1 主动终止查询

含义：使用该命令主动地终止查询。

语法：

killQueryStatement
    : KILL (QUERY queryId=string | ALL QUERIES)
    ;

参数解释：

QUERY queryId=string
- 含义：指定要终止的查询的 ID。 <queryId> 是正在执行的查询的唯一标识符。
- 获取查询 ID：可以通过 SHOW QUERIES 命令获取所有正在执行的查询及其 ID。
ALL QUERIES
- 含义：终止所有正在执行的查询。

示例：

通过指定 queryId 可以中止指定的查询，为了获取正在执行的查询 id，用户可以使用 show queries 命令，该命令将显示所有正在执行的查询列表。

IoTDB> KILL QUERY 20250108_101015_00000_1; -- 终止指定query
IoTDB> KILL ALL QUERIES; -- 终止所有query

6. 调试查询

6.1 DEBUG SQL

含义：在 SQL 查询语句开头添加 debug 关键字，执行时将输出 debug 日志，包括涉及到的底层文件 scan 信息。

V2.0.9.1 起支持该功能

语法：

debugSQLStatement
    : DEBUG ? query
    ;

说明：

日志输出目录为： logs/log_datanode_query_debug.log

示例：

执行以下 SQL 进行 DEBUG 查询

debug select * from root.ln.**;

观察log_datanode_query_debug.log 的日志内容，查看查询涉及到的文件 scan 信息。

2026-03-24 10:06:18,755 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0] INFO  o.a.i.d.s.b.TimeSeriesMetadataCache:159 - Cache miss: root.ln.wf01.wt01.temperature in file: /home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile 
2026-03-24 10:06:18,757 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0] INFO  o.a.i.d.s.b.TimeSeriesMetadataCache:160 - Device: root.ln.wf01.wt01, all sensors: [temperature] 
2026-03-24 10:06:18,758 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0] INFO  o.a.i.d.s.b.BloomFilterCache:110 - get bloomFilter from cache where filePath is: /home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile 
2026-03-24 10:06:18,759 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0] INFO  o.a.i.d.s.b.TimeSeriesMetadataCache:227 - Get timeseries: root.ln.wf01.wt01.temperature  metadata in file: /home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile  from cache: TimeseriesMetadata{timeSeriesMetadataType=0, chunkMetaDataListDataSize=8, measurementId='temperature', dataType=DOUBLE, statistics=startTime: 1773824951259 endTime: 1773824951259 count: 1 [minValue:12.9,maxValue:12.9,firstValue:12.9,lastValue:12.9,sumValue:12.9], modified=false, isSeq=true, chunkMetadataList=[measurementId: temperature, datatype: DOUBLE, version: 0, Statistics: startTime: 1773824951259 endTime: 1773824951259 count: 1 [minValue:12.9,maxValue:12.9,firstValue:12.9,lastValue:12.9,sumValue:12.9], deleteIntervalList: null]}. 
2026-03-24 10:06:18,759 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0] INFO  o.a.i.d.s.d.r.r.c.m.DiskChunkMetadataLoader:97 - Modifications size is 0 for file Path: /home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile  
2026-03-24 10:06:18,759 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0] INFO  o.a.i.d.s.d.r.r.c.m.DiskChunkMetadataLoader:109 - After modification Chunk meta data list is:  
2026-03-24 10:06:18,759 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0] INFO  o.a.i.d.s.d.r.r.c.m.DiskChunkMetadataLoader:110 - measurementId: temperature, datatype: DOUBLE, version: 0, Statistics: startTime: 1773824951259 endTime: 1773824951259 count: 1 [minValue:12.9,maxValue:12.9,firstValue:12.9,lastValue:12.9,sumValue:12.9], deleteIntervalList: null 
2026-03-24 10:06:18,760 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0] INFO  o.a.i.d.s.b.ChunkCache:167 - get chunk from cache whose key is: ChunkCacheKey{filePath='/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile', regionId=13, timePartitionId=2932, tsFileVersion=1, compactionVersion=0, offsetOfChunkHeader=27} 
2026-03-24 10:06:18,761 [pool-69-IoTDB-ClientRPC-Processor-1$20260324_020618_00052_1] INFO  o.a.i.d.q.p.Coordinator:902 - debug select * from root.ln.**