Maintenance Statement

Maintenance Statement

1. Status Checking

1.1 Viewing the Cluster Version

Description: Returns the current cluster version.

Syntax:

1. showVersionStatement
2. : SHOW VERSION
3. ;

Example:

1. IoTDB> SHOW VERSION;

Result:

1. +-------+-----------+
2. |Version|  BuildInfo|
3. +-------+-----------+
4. |1.3.4.1|e5334cf-dev|
5. +-------+-----------+

1.2 Viewing Cluster Key Parameters

Description: Returns key parameters of the current cluster.

Syntax:

1. showVariablesStatement
2. : SHOW VARIABLES
3. ;

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:

1. IoTDB> SHOW VARIABLES;

Result:

1. +----------------------------------+-----------------------------------------------------------------+
2. |                          Variable|                                                            Value|
3. +----------------------------------+-----------------------------------------------------------------+
4. |                       ClusterName|                                                   defaultCluster|
5. |             DataReplicationFactor|                                                                1|
6. |           SchemaReplicationFactor|                                                                1|
7. |  DataRegionConsensusProtocolClass|                      org.apache.iotdb.consensus.iot.IoTConsensus|
8. |SchemaRegionConsensusProtocolClass|                  org.apache.iotdb.consensus.ratis.RatisConsensus|
9. |  ConfigNodeConsensusProtocolClass|                  org.apache.iotdb.consensus.ratis.RatisConsensus|
10. |               TimePartitionOrigin|                                                                0|
11. |             TimePartitionInterval|                                                        604800000|
12. |              ReadConsistencyLevel|                                                           strong|
13. |           SchemaRegionPerDataNode|                                                                1|
14. |             DataRegionPerDataNode|                                                                0|
15. |                     SeriesSlotNum|                                                             1000|
16. |           SeriesSlotExecutorClass|org.apache.iotdb.commons.partition.executor.hash.BKDRHashExecutor|
17. |         DiskSpaceWarningThreshold|                                                             0.05|
18. |                TimestampPrecision|                                                               ms|
19. +----------------------------------+-----------------------------------------------------------------+

1.3 Viewing the Current Timestamp of Database

Description: Returns the current timestamp of the database.

Syntax:

1. showCurrentTimestampStatement
2. : SHOW CURRENT_TIMESTAMP
3. ;

Example:

1. IoTDB> SHOW CURRENT_TIMESTAMP;

Result:

1. +-----------------------------+
2. |             CurrentTimestamp|
3. +-----------------------------+
4. |2025-02-17T11:11:52.987+08:00|
5. +-----------------------------+

1.4 Viewing Executing Queries

Description: Displays information about all currently executing queries.

Syntax:

1. showQueriesStatement
2. : SHOW (QUERIES | QUERY PROCESSLIST)
3. (WHERE where=booleanExpression)?
4. (ORDER BY sortItem (',' sortItem)*)?
5. limitOffsetClause
6. ;

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.
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:

1. IoTDB> SHOW QUERIES WHERE elapsedtime > 0.003

Result:

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

1.5 Viewing Region Information

Description: Displays regions’ information of the current cluster.

Syntax:

1. showRegionsStatement
2. : SHOW REGIONS
3. ;

Example:

1. IoTDB> SHOW REGIONS

Result:

1. +--------+------------+-------+-------------+-------------+-----------+----------+----------+-------+---------------+------+-----------------------+----------+
2. |RegionId|        Type| Status|     Database|SeriesSlotNum|TimeSlotNum|DataNodeId|RpcAddress|RpcPort|InternalAddress|  Role|             CreateTime|TsFileSize|
3. +--------+------------+-------+-------------+-------------+-----------+----------+----------+-------+---------------+------+-----------------------+----------+
4. |       9|SchemaRegion|Running|root.__system|           21|          0|         1|   0.0.0.0|   6667|      127.0.0.1|Leader|2025-08-01T17:37:01.555|          |
5. |      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|
6. |      65|SchemaRegion|Running|      root.ln|            1|          0|         1|   0.0.0.0|   6667|      127.0.0.1|Leader|2025-08-25T14:46:50.113|          |
7. |      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|
8. +--------+------------+-------+-------------+-------------+-----------+----------+----------+-------+---------------+------+-----------------------+----------+

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:

1. setConfigurationStatement
2. : SET CONFIGURATION propertyAssignments (ON INTEGER_VALUE)?
3. ;

5. propertyAssignments
6. : property (',' property)*
7. ;

9. property
10. : identifier EQ propertyValue
11. ;

13. propertyValue
14. : DEFAULT
15. | expression
16. ;

Parameters:

propertyAssignments: A list of properties to update.
Format: property (',' property)*.
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.
If not specified or set to a negative value, updates all ConfigNodes and DataNodes.

Example:

1. 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:

1. loadConfigurationStatement
2. : LOAD CONFIGURATION localOrClusterMode?
3. ;

5. localOrClusterMode
6. : (ON (LOCAL | CLUSTER))
7. ;

Parameters:

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

Example:

1. IoTDB> LOAD CONFIGURATION ON LOCAL;

2.3 Setting the System Status

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

Syntax:

1. setSystemStatusStatement
2. : SET SYSTEM TO (READONLY | RUNNING) localOrClusterMode?
3. ;

5. localOrClusterMode
6. : (ON (LOCAL | CLUSTER))
7. ;

Parameters:

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

Example:

1. 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:

1. flushStatement
2. : FLUSH identifier? (',' identifier)* booleanValue? localOrClusterMode?
3. ;

5. booleanValue
6. : TRUE | FALSE
7. ;

9. localOrClusterMode
10. : (ON (LOCAL | CLUSTER))
11. ;

Parameters:

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

Example:

1. 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:

1. startRepairDataStatement
2. : START REPAIR DATA localOrClusterMode?
3. ;

5. localOrClusterMode
6. : (ON (LOCAL | CLUSTER))
7. ;

Parameters:

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

Example:

1. 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:

1. stopRepairDataStatement
2. : STOP REPAIR DATA localOrClusterMode?
3. ;

5. localOrClusterMode
6. : (ON (LOCAL | CLUSTER))
7. ;

Parameters:

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

Example:

1. 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:

1. extendRegionStatement
2. : EXTEND REGION <region_id>(, <region_id>)* TO <data_node_id>
3. ;

Example:

1. 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:

1. removeRegionStatement
2. : REMOVE REGION <region_id>(, <region_id>)* FROM <data_node_id>
3. ;

Example:

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

6. Query Termination

6.1 Terminating Queries

Description: Terminates one or more running queries.

Syntax:

1. killQueryStatement
2. : KILL (QUERY queryId=string | ALL QUERIES)
3. ;

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:

1. IoTDB> KILL QUERY 20250108_101015_00000_1;

Terminate all queries:

1. IoTDB> KILL ALL QUERIES;

Maintenance statement