Maintenance Statement

February 20, 2025About 5 min

Maintenance Statement

1. Status Checking

1.1 Viewing the Connected Model

Description: Returns the current SQL dialect model (Tree or Table).

Syntax:

showCurrentSqlDialectStatement
    : SHOW CURRENT_SQL_DIALECT
    ;

Example:

IoTDB> SHOW CURRENT_SQL_DIALECT;

Result：

+-----------------+
|CurrentSqlDialect|
+-----------------+
|            TABLE|
+-----------------+

1.2 Viewing the Logged-in Username

Description: Returns the currently logged-in username.

Syntax:

showCurrentUserStatement
    : SHOW CURRENT_USER
    ;

Example:

IoTDB> SHOW CURRENT_USER;

Result:

+-----------+
|CurrentUser|
+-----------+
|       root|
+-----------+

1.3 Viewing the Connected Database Name

Description: Returns the name of the currently connected database. If no USE statement has been executed, it returns null.

Syntax:

showCurrentDatabaseStatement
    : SHOW CURRENT_DATABASE
    ;

Example:

IoTDB> SHOW CURRENT_DATABASE;
IoTDB> USE test;
IoTDB> SHOW CURRENT_DATABASE;

Result:

+---------------+
|CurrentDatabase|
+---------------+
|           null|
+---------------+
+---------------+
|CurrentDatabase|
+---------------+
|           test|
+---------------+

1.4 Viewing the Cluster Version

Description: Returns the current cluster version.

Syntax:

showVersionStatement
    : SHOW VERSION
    ;

Example:

IoTDB> SHOW VERSION;

Result:

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

1.5 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.6 Viewing the Cluster ID

Description: Returns the ID of the current cluster.

Syntax:

showClusterIdStatement
    : SHOW (CLUSTERID | CLUSTER_ID)
    ;

Example:

IoTDB> SHOW CLUSTER_ID;

Result:

+------------------------------------+
|                           ClusterId|
+------------------------------------+
|40163007-9ec1-4455-aa36-8055d740fcda|
+------------------------------------+

1.7 Viewing the Timestamp of the Connected DataNode

Description: Returns the current timestamp of the DataNode process directly connected to the client.

Syntax:

showCurrentTimestampStatement
    : SHOW CURRENT_TIMESTAMP
    ;

Example:

IoTDB> SHOW CURRENT_TIMESTAMP;

Result:

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

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

query_id: Unique ID of the query.
start_time: Timestamp when the query started.
datanode_id: ID of the DataNode executing the query.
elapsed_time: Time elapsed since the query started (in seconds).
statement: The SQL statement being executed.
user: The user who initiated the query.

Example:

IoTDB> SHOW QUERIES WHERE elapsed_time > 30;

Result:

+-----------------------+-----------------------------+-----------+------------+------------+----+
|               query_id|                   start_time|datanode_id|elapsed_time|   statement|user|
+-----------------------+-----------------------------+-----------+------------+------------+----+
|20250108_101015_00000_1|2025-01-08T18:10:15.935+08:00|          1|      32.283|show queries|root|
+-----------------------+-----------------------------+-----------+------------+------------+----+

2. Status Setting

2.1 Setting the Connected Model

Description: Sets the current SQL dialect model to Tree or Table.

Syntax:

SET SQL_DIALECT = (TABLE | TREE);

Example:

IoTDB> SET SQL_DIALECT=TABLE;
IoTDB> SHOW CURRENT_SQL_DIALECT;

Result:

+-----------------+
|CurrentSqlDialect|
+-----------------+
|            TABLE|
+-----------------+

2.2 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 "a"='1',b='1' ON 1;

2.3 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:
  - ON LOCAL: Loads configuration only on the DataNode directly connected to the client.
  - ON CLUSTER: Loads configuration on all DataNodes in the cluster.

Example:

IoTDB> LOAD CONFIGURATION ON LOCAL;

2.4 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. ON LOCAL: Applies the status change only to the DataNode directly connected to the client.
2. ON 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 database to flush.
2. If not specified, all databases are flushed.
3. Multiple Databases: Multiple database names can be specified, separated by commas (e.g., FLUSH test_db1, test_db2).
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 test_db TRUE ON LOCAL;

3.2 Clearing Cache on DataNode

Description: Clears a specific type of cache on DataNode.

Syntax:

clearCacheStatement
    : CLEAR clearCacheOptions? CACHE localOrClusterMode?
    ;

clearCacheOptions
    : ATTRIBUTE
    | QUERY
    | ALL
    ;

localOrClusterMode
    : (ON (LOCAL | CLUSTER))
    ;

Parameters:

clearCacheOptions（Optional）:
1. Specifies the type of cache to clear.
2. ATTRIBUTE: Clears device attribute cache.
3. QUERY: Clears query cache in the storage engine.
4. ALL: Clears all caches, including device attribute cache, query cache, and schema cache in the tree model.
5. Default: QUERY.
localOrClusterMode（Optional）:
1. ON LOCAL: Clears cache only on the DataNode directly connected to the client.
2. ON CLUSTER: Clears cache on all DataNodes in the cluster.
3. Default: ON CLUSTER.

Example:

IoTDB> CLEAR ALL CACHE 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. Query Termination

5.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;