Maintenance Statement

1. Status Checking

1.1 Viewing the Cluster Version

Description: Returns the current cluster version.

Syntax:

showVersionStatement
    : SHOW VERSION
    ;

Example:

IoTDB> SHOW VERSION;

Result:

+-------+-----------+
|Version|  BuildInfo|
+-------+-----------+
|1.3.4.1|e5334cf-dev|
+-------+-----------+

1.2 Viewing Cluster Key Parameters

Description: Returns key parameters of the current cluster.

Syntax:

showVariablesStatement
    : SHOW VARIABLES
    ;

Key Parameters:

ClusterName: The name of the current cluster.
DataReplicationFactor: Number of data replicas per DataRegion.
SchemaReplicationFactor: Number of schema replicas per SchemaRegion.
DataRegionConsensusProtocolClass: Consensus protocol class for DataRegions.
SchemaRegionConsensusProtocolClass: Consensus protocol class for SchemaRegions.
ConfigNodeConsensusProtocolClass: Consensus protocol class for ConfigNodes.
TimePartitionOrigin: The starting timestamp of database time partitions.
TimePartitionInterval: The interval of database time partitions (in milliseconds).
ReadConsistencyLevel: The consistency level for read operations.
SchemaRegionPerDataNode: Number of SchemaRegions per DataNode.
DataRegionPerDataNode: Number of DataRegions per DataNode.
SeriesSlotNum: Number of SeriesSlots per DataRegion.
SeriesSlotExecutorClass: Implementation class for SeriesSlots.
DiskSpaceWarningThreshold: Disk space warning threshold (in percentage).
TimestampPrecision: Timestamp precision.

Example:

IoTDB> SHOW VARIABLES;

Result:

+----------------------------------+-----------------------------------------------------------------+
|                          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.3 Viewing the Current Timestamp of Database

Description: Returns the current timestamp of the database.

Syntax:

showCurrentTimestampStatement
    : SHOW CURRENT_TIMESTAMP
    ;

Example:

IoTDB> SHOW CURRENT_TIMESTAMP;

Result:

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

1.4 Viewing Executing Queries

Description: Displays information about all currently executing queries.

Syntax:

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

Parameters:

WHERE Clause: Filters the result set based on specified conditions.
ORDER BY Clause: Sorts the result set based on specified columns.
limitOffsetClause: Limits the number of rows returned.
1. Format: LIMIT <offset>, <row_count>.

Columns in QUERIES Table:

time: Timestamp when the query started.
queryid: Unique ID of the query.
datanodeid: ID of the DataNode executing the query.
elapsedtime: Time elapsed since the query started (in seconds).
statement: The SQL statement being executed.

Example:

IoTDB> SHOW QUERIES WHERE elapsedtime > 0.003

Result:

+-----------------------------+-----------------------+----------+-----------+--------------------------------------+
|                         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.5 Viewing Region Information

Description: Displays regions' information of the current cluster.

Syntax:

showRegionsStatement
    : SHOW REGIONS
    ;

Example:

IoTDB> SHOW REGIONS

Result:

+--------+------------+-------+-------------+-------------+-----------+----------+----------+-------+---------------+------+-----------------------+----------+
|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|
+--------+------------+-------+-------------+-------------+-----------+----------+----------+-------+---------------+------+-----------------------+----------+

2. Status Setting

2.1 Updating Configuration Items

Description: Updates configuration items. Changes take effect immediately without restarting if the items support hot modification.

Syntax:

setConfigurationStatement
    : SET CONFIGURATION propertyAssignments (ON INTEGER_VALUE)?
    ;

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

propertyValue
    : DEFAULT
    | expression
    ;

Parameters:

propertyAssignments: A list of properties to update.
1. Format: property (',' property)*.
2. Values:
  - DEFAULT: Resets the configuration to its default value.
  - expression: A specific value (must be a string).
ON INTEGER_VALUE (Optional): Specifies the node ID to update.
1. If not specified or set to a negative value, updates all ConfigNodes and DataNodes.

Example:

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

2.2 Loading Manually Modified Configuration Files

Description: Loads manually modified configuration files and hot-loads the changes. Configuration items that support hot modification take effect immediately.

Syntax:

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

Parameters:

localOrClusterMode (Optional):
1. Specifies the scope of configuration loading.
2. Default: CLUSTER.
3. Values:
  - LOCAL: Loads configuration only on the DataNode directly connected to the client.
  - CLUSTER: Loads configuration on all DataNodes in the cluster.

Example:

IoTDB> LOAD CONFIGURATION ON LOCAL;

2.3 Setting the System Status

Description: Sets the system status to either READONLY or RUNNING.

Syntax:

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

Parameters:

RUNNING | READONLY:
1. RUNNING: Sets the system to running mode, allowing both read and write operations.
2. READONLY: Sets the system to read-only mode, allowing only read operations and prohibiting writes.
localOrClusterMode (Optional):
1. LOCAL: Applies the status change only to the DataNode directly connected to the client.
2. CLUSTER: Applies the status change to all DataNodes in the cluster.
3. Default: ON CLUSTER.

Example:

IoTDB> SET SYSTEM TO READONLY ON CLUSTER;

3. Data Management

3.1 Flushing Data from Memory to Disk

Description: Flushes data from the memory table to disk.

Syntax:

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

booleanValue
    : TRUE | FALSE
    ;

localOrClusterMode
    : (ON (LOCAL | CLUSTER))
    ;

Parameters:

identifier (Optional):
1. Specifies the name of the path to flush.
2. If not specified, all path are flushed.
3. Multiple Paths: Multiple path names can be specified, separated by commas (e.g., FLUSH root.ln, root.lnm.**).
booleanValue (Optional):
1. Specifies the type of data to flush.
2. TRUE: Flushes only the sequential memory table.
3. FALSE: Flushes only the unsequential MemTable.
4. Default: Flushes both sequential and unsequential memory tables.
localOrClusterMode (Optional):
1. ON LOCAL: Flushes only the memory tables on the DataNode directly connected to the client.
2. ON CLUSTER: Flushes memory tables on all DataNodes in the cluster.
3. Default: ON CLUSTER.

Example:

IoTDB> FLUSH root.ln TRUE ON LOCAL;

4. Data Repair

4.1 Starting Background Scan and Repair of TsFiles

Description: Starts a background task to scan and repair TsFiles, fixing issues such as timestamp disorder within data files.

Syntax:

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

Parameters:

localOrClusterMode（Optional）:
1. ON LOCAL: Executes the repair task only on the DataNode directly connected to the client.
2. ON CLUSTER: Executes the repair task on all DataNodes in the cluster.
3. Default: ON CLUSTER.

Example:

IoTDB> START REPAIR DATA ON CLUSTER;

4.2 Pausing Background TsFile Repair Task

Description: Pauses the background repair task. The paused task can be resumed by executing the START REPAIR DATA command again.

Syntax:

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

Parameters:

localOrClusterMode (Optional):
1. ON LOCAL: Executes the pause command only on the DataNode directly connected to the client.
2. ON CLUSTER: Executes the pause command on all DataNodes in the cluster.
3. Default: ON CLUSTER.

Example:

IoTDB> STOP REPAIR DATA ON CLUSTER;

5. Replica Repair

This function has supported passing in a regionId list since V1.3.6, allowing multiple regions to be processed at one time.

5.1 Manual Expansion

Description: Expand the specified Region to the specified DataNode.

Syntax:

extendRegionStatement
    : EXTEND REGION <region_id>(, <region_id>)* TO <data_node_id>
    ;

Example:

IoTDB> EXTEND REGION 1,2,3 TO 3;

5.2 Manual Capacity Reduction

Description: Remove the specified Region from the specified DataNode.

Note: Manual capacity reduction can only reduce the number of replicas to 1 at most, and cannot be reduced to 0.

Syntax:

removeRegionStatement
    : REMOVE REGION <region_id>(, <region_id>)* FROM <data_node_id>
    ;

Example:

IoTDB> REMOVE REGION 1,2,3 FROM 2;

6. Query Termination

6.1 Terminating Queries

Description: Terminates one or more running queries.

Syntax:

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

Parameters:

QUERY queryId: Specifies the ID of the query to terminate.

To obtain the queryId, use the SHOW QUERIES command.

ALL QUERIES: Terminates all currently running queries.

Example:

Terminate a specific query:

IoTDB> KILL QUERY 20250108_101015_00000_1;

Terminate all queries:

IoTDB> KILL ALL QUERIES;