From 8ead162a8329752ff354200f6f0bd40e7943e1dd Mon Sep 17 00:00:00 2001 From: leto-bbq Date: Thu, 27 Aug 2026 12:04:35 +0800 Subject: [PATCH] docs: update V2.0.11 database region group details --- .../Database-Management_apache.md | 138 ++++++++----- .../Table/Reference/System-Tables_apache.md | 32 +-- .../Basic-Concept/Operate-Metadata_apache.md | 182 +++++++++--------- .../Database-Management_apache.md | 138 ++++++++----- .../Reference/System-Tables_apache.md | 32 +-- .../Basic-Concept/Operate-Metadata_apache.md | 182 +++++++++--------- .../Database-Management_apache.md | 100 ++++++---- .../Table/Reference/System-Tables_apache.md | 32 +-- .../Basic-Concept/Operate-Metadata_apache.md | 54 ++---- .../Database-Management_apache.md | 100 ++++++---- .../Reference/System-Tables_apache.md | 32 +-- .../Basic-Concept/Operate-Metadata_apache.md | 54 ++---- 12 files changed, 588 insertions(+), 488 deletions(-) diff --git a/src/UserGuide/Master/Table/Basic-Concept/Database-Management_apache.md b/src/UserGuide/Master/Table/Basic-Concept/Database-Management_apache.md index b8469018e..9519572f8 100644 --- a/src/UserGuide/Master/Table/Basic-Concept/Database-Management_apache.md +++ b/src/UserGuide/Master/Table/Basic-Concept/Database-Management_apache.md @@ -21,44 +21,74 @@ # Database Management -## 1. Database Management +In the table model, a database is the top-level organizational structure for tables and is used to manage a group of business-related tables. Before creating tables, writing data, or querying data, you usually need to create a database and specify the database used by the current session through `USE `. -### 1.1 Create a Database +A database can be configured with properties such as TTL, time partition interval, the maximum number of SchemaRegionGroups, and the maximum number of DataRegionGroups. The database-level TTL is used as the default data retention period for tables in the database. If a table has its own TTL, the table-level TTL takes precedence. -This command is used to create a database. +## 1. Basic Concepts + +### 1.1 Database + +A database organizes and manages multiple tables. Databases can be divided by business domain, project, tenant, or data isolation requirements. For example, tables for a group of devices in the same business system can be placed in one database to manage their lifecycle, permissions, and query scope uniformly. + +In the table model, a database name is also the namespace for its tables. After `USE database1` is executed, subsequent table operations that do not explicitly specify a database name apply to `database1` by default. + +### 1.2 TTL + +TTL specifies how long data is retained, in milliseconds. Data that exceeds the TTL is automatically expired and deleted. Setting an appropriate TTL controls disk space usage and prevents accumulated historical data from affecting storage costs and query performance. + +TTL can be set at either the database level or the table level. For more information, see [TTL Delete Data](../Basic-Concept/TTL-Delete-Data_apache.md). + +### 1.3 Time Partition Interval + +The time partition interval determines the time range used to group data into directories on disk. The default value is 604800000 ms, or one week, and is suitable for most scenarios. + +### 1.4 RegionGroup + +IoTDB divides metadata and data into Regions managed by DataNodes. The `MAX_SCHEMA_REGION_GROUP_NUM` and `MAX_DATA_REGION_GROUP_NUM` database properties specify the maximum numbers of schema replica groups and data replica groups, respectively. These properties generally do not need to be changed manually. + +## 2. Database Management + +### 2.1 Create a Database + +Creates a database. **Syntax:** ```SQL - CREATE DATABASE (IF NOT EXISTS)? (WITH properties)? +CREATE DATABASE (IF NOT EXISTS)? (WITH properties)? ``` -**Note: ** +**Description:** -1. ``: The name of the database, with the following characteristics: - - Case-insensitive. After creation, it will be displayed uniformly in lowercase. - - Can include commas (`,`), underscores (`_`), numbers, letters, and Chinese characters. - - Maximum length is 64 characters. - - Names with special characters or Chinese characters must be enclosed in double quotes (`""`). +1. `` is the database name and has the following characteristics: + - It is case-insensitive and is displayed in lowercase after the database is created. + - It cannot exceed 64 characters. + - A name that contains underscores (`_`), digits (except as the first character), or English letters can be created directly. + - A name that contains special characters (such as a backtick), Chinese characters, or starts with a digit must be enclosed in double quotation marks (`""`). +2. The `WITH properties` clause supports the following properties: -2. `WITH properties`: Property names are case-insensitive. For more details, refer to the case sensitivity rules [case-sensitivity](../SQL-Manual/Identifier.md#2-case-sensitivity)。Configurable properties include: +| Property | Description | Default Value | +| --- | --- | --- | +| `TTL` | Automatic data expiration time, in milliseconds. The value must be a positive integer. | `INF` | +| `TIME_PARTITION_INTERVAL` | Time partition interval for the database, in milliseconds. The value must be a positive integer. | `604800000` | +| `MAX_SCHEMA_REGION_GROUP_NUM` | Maximum number of SchemaRegionGroups to which the database can automatically expand. The value must be a positive integer. Supported starting from V2.0.11. | `1` | +| `MAX_DATA_REGION_GROUP_NUM` | Maximum number of DataRegionGroups to which the database can automatically expand. The value must be a positive integer. Supported starting from V2.0.11. | `2` | -| Property | Description | Default Value | -| ----------------------- | ------------------------------------------------------------ | -------------------- | -| TTL | Automatic data expiration time, in milliseconds | `INF` | -| TIME_PARTITION_INTERVAL | Time partition interval for the database, in milliseconds | `604800000` (7 days) | -| SCHEMA_REGION_GROUP_NUM | Number of metadata replica groups; generally does not require modification | `1` | -| DATA_REGION_GROUP_NUM | Number of data replica groups; generally does not require modification | `2` | +**Notes:** -**Examples:** +- Property names are case-insensitive. For details, see [Case Sensitivity](../SQL-Manual/Identifier.md#2-case-sensitivity). +- The maximum schema/data region group quotas, `maxSchemaRegionGroupNum` and `maxDataRegionGroupNum`, can be set or adjusted through SQL when creating or modifying a database only when `schema_region_group_extension_policy` and `data_region_group_extension_policy` in `iotdb-common.properties` are set to `CUSTOM`. + +**Example:** ```SQL -CREATE DATABASE IF NOT EXISTS database1 with(TTL=31536000000); +CREATE DATABASE IF NOT EXISTS database1 WITH (TTL=31536000000); ``` -### 1.2 Use a Database +### 2.2 Use a Database -Specify the current database as the namespace for table operations. +Specifies the current database as the namespace for tables. **Syntax:** @@ -66,15 +96,15 @@ Specify the current database as the namespace for table operations. USE ``` -**Example:** +**Example:** ```SQL USE database1; ``` -### 1.3 View the Current Database +### 2.3 View the Current Database -Displays the name of the currently connected database. If no USE statement has been executed, the default is `null`. +Returns the name of the database used by the current session. If no database has been specified with a `USE` statement, the default value is `null`. **Syntax:** @@ -88,6 +118,7 @@ SHOW CURRENT_DATABASE USE database1; SHOW CURRENT_DATABASE; ``` + ```shell +---------------+ |CurrentDatabase| @@ -96,8 +127,7 @@ SHOW CURRENT_DATABASE; +---------------+ ``` - -### 1.4 View All Databases +### 2.4 View All Databases Displays all databases and their properties. @@ -107,35 +137,38 @@ Displays all databases and their properties. SHOW DATABASES (DETAILS)? ``` -**Columns Explained:** - +**Columns:** -| Column Name | Description | -| ----------------------- |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| database | Name of the database. | -| TTL | Data retention period. If TTL is specified when creating a database, it applies to all tables within the database. You can also set or update the TTL of individual tables using [create table](../Basic-Concept/Table-Management_apache.md#11-create-a-table) 、[alter table](../Basic-Concept/Table-Management_apache.md#14-update-tables) . | -| SchemaReplicationFactor | Number of metadata replicas, ensuring metadata high availability. This can be configured in the `iotdb-system.properties` file under the `schema_replication_factor` property. | -| DataReplicationFactor | Number of data replicas, ensuring data high availability. This can be configured in the `iotdb-system.properties` file under the `data_replication_factor` property. | -| TimePartitionInterval | Time partition interval, determining how often data is grouped into directories on disk. The default is typically one week. | -| Model | Returned when using the `DETAILS` option, showing the data model corresponding to each database (e.g., timeseries tree model or device table model). | +| Column Name | Description | +| --- | --- | +| Database | Database name. | +| TTL | Data retention period. A database-level TTL applies to all tables in the database by default. You can also set or update a table-level TTL through [CREATE TABLE](../Basic-Concept/Table-Management_apache.md#21-create-a-table) or [ALTER TABLE](../Basic-Concept/Table-Management_apache.md#25-update-tables). | +| SchemaReplicationFactor | Number of schema replicas used to ensure metadata availability. This value can be changed through `schema_replication_factor` in `iotdb-system.properties`. | +| DataReplicationFactor | Number of data replicas used to ensure data availability. This value can be changed through `data_replication_factor` in `iotdb-system.properties`. | +| TimePartitionInterval | Time partition interval, which determines the time range used to group data into directories on disk. The default value of one week is suitable for most scenarios. | +| SchemaRegionGroupNum | Returned with `DETAILS`. Number of schema replica groups currently owned by the database. | +| MaxSchemaRegionGroupNum | Returned with `DETAILS`. Maximum number of schema replica groups allowed for the database. | +| DataRegionGroupNum | Returned with `DETAILS`. Number of data replica groups currently owned by the database. | +| MaxDataRegionGroupNum | Returned with `DETAILS`. Maximum number of data replica groups allowed for the database. | -**Examples:** +**Example:** ```SQL SHOW DATABASES DETAILS; ``` + ```shell -+------------------+-------+-----------------------+---------------------+---------------------+--------------------+------------------+ -| Database|TTL(ms)|SchemaReplicationFactor|DataReplicationFactor|TimePartitionInterval|SchemaRegionGroupNum|DataRegionGroupNum| -+------------------+-------+-----------------------+---------------------+---------------------+--------------------+------------------+ -| database1| INF| 1| 1| 604800000| 1| 2| -|information_schema| INF| null| null| null| null| null| -+------------------+-------+-----------------------+---------------------+---------------------+--------------------+------------------+ ++------------------+-------+-----------------------+---------------------+---------------------+--------------------+-----------------------+------------------+---------------------+ +| Database|TTL(ms)|SchemaReplicationFactor|DataReplicationFactor|TimePartitionInterval|SchemaRegionGroupNum|MaxSchemaRegionGroupNum|DataRegionGroupNum|MaxDataRegionGroupNum| ++------------------+-------+-----------------------+---------------------+---------------------+--------------------+-----------------------+------------------+---------------------+ +| database1| INF| 1| 1| 604800000| 1| 1| 2| 2| +|information_schema| INF| null| null| null| null| null| null| null| ++------------------+-------+-----------------------+---------------------+---------------------+--------------------+-----------------------+------------------+---------------------+ ``` -### 1.5 Update a Database +### 2.5 Update a Database -Used to modify some attributes in the database. +Modifies supported database properties. **Syntax:** @@ -143,19 +176,20 @@ Used to modify some attributes in the database. ALTER DATABASE (IF EXISTS)? database=identifier SET PROPERTIES propertyAssignments ``` -**Note:** +**Description:** -1. The `ALTER DATABASE` operation currently only supports modifications to the database's `SCHEMA_REGION_GROUP_NUM`, `DATA_REGION_GROUP_NUM`, and `TTL` attributes. +1. `ALTER DATABASE` currently supports modifying only `MAX_SCHEMA_REGION_GROUP_NUM`, `MAX_DATA_REGION_GROUP_NUM`, and `TTL`. **Example:** ```SQL ALTER DATABASE database1 SET PROPERTIES TTL=31536000000; +ALTER DATABASE database1 SET PROPERTIES MAX_SCHEMA_REGION_GROUP_NUM=2, MAX_DATA_REGION_GROUP_NUM=4; ``` -### 1.6 Delete a Database +### 2.6 Delete a Database -Deletes the specified database and all associated tables and data. +Deletes a database. **Syntax:** @@ -163,10 +197,10 @@ Deletes the specified database and all associated tables and data. DROP DATABASE (IF EXISTS)? ``` -**Note:** +**Description:** -1. A database currently in use can still be dropped. -2. Deleting a database removes all its tables and stored data. +1. A database can be dropped even if it is the current database selected by `USE`. +2. Dropping a database deletes all tables in the database and all data stored in those tables. **Example:** diff --git a/src/UserGuide/Master/Table/Reference/System-Tables_apache.md b/src/UserGuide/Master/Table/Reference/System-Tables_apache.md index d2c58b41c..0b8788fea 100644 --- a/src/UserGuide/Master/Table/Reference/System-Tables_apache.md +++ b/src/UserGuide/Master/Table/Reference/System-Tables_apache.md @@ -77,27 +77,29 @@ IoTDB> show tables from information_schema * Contains information about all databases in the cluster. * Table structure is as follows: -| Column Name | Data Type | Column Type | Description | -| --------------------------------- | ----------- | ------------- | -------------------------------- | -| `database` | STRING | TAG | Database name | -| `ttl(ms)` | STRING | ATTRIBUTE | Data retention time | -| `schema_replication_factor` | INT32 | ATTRIBUTE | Schema replica count | -| `data_replication_factor` | INT32 | ATTRIBUTE | Data replica count | -| `time_partition_interval` | INT64 | ATTRIBUTE | Time partition interval | -| `schema_region_group_num` | INT32 | ATTRIBUTE | Number of schema region groups | -| `data_region_group_num` | INT32 | ATTRIBUTE | Number of data region groups | +| Column Name | Data Type | Column Type | Description | +| --- | --- | --- | --- | +| `database` | STRING | TAG | Database name | +| `ttl(ms)` | STRING | ATTRIBUTE | Data retention time | +| `schema_replication_factor` | INT32 | ATTRIBUTE | Number of schema replicas | +| `data_replication_factor` | INT32 | ATTRIBUTE | Number of data replicas | +| `time_partition_interval` | INT64 | ATTRIBUTE | Time partition interval | +| `schema_region_group_num` | INT32 | ATTRIBUTE | Number of schema regions | +| `max_schema_region_group_num` | INT32 | ATTRIBUTE | Maximum number of schema regions to which the database can expand. Supported starting from V2.0.11. | +| `data_region_group_num` | INT32 | ATTRIBUTE | Number of data regions | +| `max_data_region_group_num` | INT32 | ATTRIBUTE | Maximum number of data regions to which the database can expand. Supported starting from V2.0.11. | * The query results only display the collection of databases for which you have any permission on the database itself or any table within the database. * Query Example: ```sql IoTDB> select * from information_schema.databases -+------------------+-------+-------------------------+-----------------------+-----------------------+-----------------------+---------------------+ -| database|ttl(ms)|schema_replication_factor|data_replication_factor|time_partition_interval|schema_region_group_num|data_region_group_num| -+------------------+-------+-------------------------+-----------------------+-----------------------+-----------------------+---------------------+ -|information_schema| INF| null| null| null| null| null| -| database1| INF| 1| 1| 604800000| 0| 0| -+------------------+-------+-------------------------+-----------------------+-----------------------+-----------------------+---------------------+ ++------------------+-------+-------------------------+-----------------------+-----------------------+-----------------------+---------------------------+---------------------+-------------------------+ +| database|ttl(ms)|schema_replication_factor|data_replication_factor|time_partition_interval|schema_region_group_num|max_schema_region_group_num|data_region_group_num|max_data_region_group_num| ++------------------+-------+-------------------------+-----------------------+-----------------------+-----------------------+---------------------------+---------------------+-------------------------+ +|information_schema| INF| null| null| null| null| null| null| null| +| database1| INF| 1| 1| 604800000| 1| 1| 2| 2| ++------------------+-------+-------------------------+-----------------------+-----------------------+-----------------------+---------------------------+---------------------+-------------------------+ ``` ### 2.2 TABLES diff --git a/src/UserGuide/Master/Tree/Basic-Concept/Operate-Metadata_apache.md b/src/UserGuide/Master/Tree/Basic-Concept/Operate-Metadata_apache.md index 98d44745f..c6af247a0 100644 --- a/src/UserGuide/Master/Tree/Basic-Concept/Operate-Metadata_apache.md +++ b/src/UserGuide/Master/Tree/Basic-Concept/Operate-Metadata_apache.md @@ -154,102 +154,7 @@ Total line number = 1 It costs 0.002s ``` -### 1.5 Setting up heterogeneous databases (Advanced operations) - -Under the premise of familiar with IoTDB metadata modeling, -users can set up heterogeneous databases in IoTDB to cope with different production needs. - -Currently, the following database heterogeneous parameters are supported: - -| Parameter | Type | Description | -| ------------------------- | ------- | --------------------------------------------- | -| TTL | Long | TTL of the Database | -| SCHEMA_REPLICATION_FACTOR | Integer | The schema replication number of the Database | -| DATA_REPLICATION_FACTOR | Integer | The data replication number of the Database | -| SCHEMA_REGION_GROUP_NUM | Integer | The SchemaRegionGroup number of the Database | -| DATA_REGION_GROUP_NUM | Integer | The DataRegionGroup number of the Database | - -Note the following when configuring heterogeneous parameters: - -+ TTL and TIME_PARTITION_INTERVAL must be positive integers. -+ SCHEMA_REPLICATION_FACTOR and DATA_REPLICATION_FACTOR must be smaller than or equal to the number of deployed DataNodes. -+ The function of SCHEMA_REGION_GROUP_NUM and DATA_REGION_GROUP_NUM are related to the parameter `schema_region_group_extension_policy` and `data_region_group_extension_policy` in iotdb-system.properties configuration file. Take DATA_REGION_GROUP_NUM as an example: - If `data_region_group_extension_policy=CUSTOM` is set, DATA_REGION_GROUP_NUM serves as the number of DataRegionGroups owned by the Database. - If `data_region_group_extension_policy=AUTO`, DATA_REGION_GROUP_NUM is used as the lower bound of the DataRegionGroup quota owned by the Database. That is, when the Database starts writing data, it will have at least this number of DataRegionGroups. - -Users can set any heterogeneous parameters when creating a Database, or adjust some heterogeneous parameters during a stand-alone/distributed IoTDB run. - -#### Set heterogeneous parameters when creating a Database - -The user can set any of the above heterogeneous parameters when creating a Database. The SQL statement is as follows: - -```sql -CREATE DATABASE prefixPath (WITH databaseAttributeClause (COMMA? databaseAttributeClause)*)? -``` - -For example: - -```sql -CREATE DATABASE root.db WITH SCHEMA_REPLICATION_FACTOR=1, DATA_REPLICATION_FACTOR=3, SCHEMA_REGION_GROUP_NUM=1, DATA_REGION_GROUP_NUM=2; -``` - -#### Adjust heterogeneous parameters at run time - -Users can adjust some heterogeneous parameters during the IoTDB runtime, as shown in the following SQL statement: - -```sql -ALTER DATABASE prefixPath WITH databaseAttributeClause (COMMA? databaseAttributeClause)* -``` - -For example: - -```sql -ALTER DATABASE root.db WITH SCHEMA_REGION_GROUP_NUM=1, DATA_REGION_GROUP_NUM=2; -``` - -Note that only the following heterogeneous parameters can be adjusted at runtime: - -+ SCHEMA_REGION_GROUP_NUM -+ DATA_REGION_GROUP_NUM - -#### Show heterogeneous databases - -The user can query the specific heterogeneous configuration of each Database, and the SQL statement is as follows: - -```sql -SHOW DATABASES DETAILS prefixPath? -``` - -For example: - -```sql -SHOW DATABASES DETAILS -+--------+--------+-----------------------+---------------------+---------------------+--------------------+-----------------------+-----------------------+------------------+---------------------+---------------------+ -|Database| TTL|SchemaReplicationFactor|DataReplicationFactor|TimePartitionInterval|SchemaRegionGroupNum|MinSchemaRegionGroupNum|MaxSchemaRegionGroupNum|DataRegionGroupNum|MinDataRegionGroupNum|MaxDataRegionGroupNum| -+--------+--------+-----------------------+---------------------+---------------------+--------------------+-----------------------+-----------------------+------------------+---------------------+---------------------+ -|root.db1| null| 1| 3| 604800000| 0| 1| 1| 0| 2| 2| -|root.db2|86400000| 1| 1| 604800000| 0| 1| 1| 0| 2| 2| -|root.db3| null| 1| 1| 604800000| 0| 1| 1| 0| 2| 2| -+--------+--------+-----------------------+---------------------+---------------------+--------------------+-----------------------+-----------------------+------------------+---------------------+---------------------+ -Total line number = 3 -It costs 0.058s -``` - -The query results in each column are as follows: - -+ The name of the Database -+ The TTL of the Database -+ The schema replication number of the Database -+ The data replication number of the Database -+ The time partition interval of the Database -+ The current SchemaRegionGroup number of the Database -+ The required minimum SchemaRegionGroup number of the Database -+ The permitted maximum SchemaRegionGroup number of the Database -+ The current DataRegionGroup number of the Database -+ The required minimum DataRegionGroup number of the Database -+ The permitted maximum DataRegionGroup number of the Database - -### 1.6 TTL +### 1.5 TTL IoTDB supports setting data retention time (TTL) at the device level, allowing the system to automatically and periodically delete old data to effectively control disk space and maintain high query performance and low memory usage. TTL is set in milliseconds by default. Once data expires, it cannot be queried or written, but physical deletion is delayed until compaction. Please note that changes to TTL may temporarily affect data queryability, and if TTL is reduced or removed, previously invisible data due to TTL may reappear. @@ -360,6 +265,91 @@ show devices ``` All devices will definitely have a TTL, meaning it cannot be null. INF represents infinity. +### 1.6 Setting Up Heterogeneous Databases (Advanced Operations) + +With a solid understanding of IoTDB metadata modeling, users can configure heterogeneous databases in IoTDB to meet different production requirements. + +The following heterogeneous database parameters are supported: + +| Parameter | Type | Description | +| --- | --- | --- | +| TTL | Long | TTL of the database. The value must be a positive integer. | +| TIME_PARTITION_INTERVAL | Long | Time partition interval of the database. The value must be a positive integer. | +| MAX_SCHEMA_REGION_GROUP_NUM | Integer | Maximum number of SchemaRegionGroups to which the database can automatically expand. The value must be a positive integer. | +| MAX_DATA_REGION_GROUP_NUM | Integer | Maximum number of DataRegionGroups to which the database can automatically expand. The value must be a positive integer. | + +Note the following when configuring heterogeneous parameters: + ++ The maximum schema/data region group quotas, `maxSchemaRegionGroupNum` and `maxDataRegionGroupNum`, can be set or adjusted through SQL when creating or modifying a database only when `schema_region_group_extension_policy` and `data_region_group_extension_policy` in `iotdb-common.properties` are set to `CUSTOM`. ++ `MAX_SCHEMA_REGION_GROUP_NUM` and `MAX_DATA_REGION_GROUP_NUM` are supported starting from V2.0.11. + +#### Set Heterogeneous Parameters When Creating a Database + +You can set any of the preceding heterogeneous parameters when creating a database. The SQL statement is as follows: + +```sql +CREATE DATABASE prefixPath (WITH databaseAttributeClause (COMMA? databaseAttributeClause)*)? +``` + +For example: + +```sql +CREATE DATABASE root.db WITH TTL=360000, MAX_SCHEMA_REGION_GROUP_NUM=1, MAX_DATA_REGION_GROUP_NUM=2; +``` + +#### Adjust Heterogeneous Parameters at Runtime + +You can adjust some heterogeneous parameters while IoTDB is running. The SQL statement is as follows: + +```sql +ALTER DATABASE prefixPath WITH databaseAttributeClause (COMMA? databaseAttributeClause)* +``` + +For example: + +```sql +ALTER DATABASE root.db WITH MAX_SCHEMA_REGION_GROUP_NUM=2, MAX_DATA_REGION_GROUP_NUM=3; +``` + +Only the following heterogeneous parameters can be adjusted at runtime: + ++ MAX_SCHEMA_REGION_GROUP_NUM ++ MAX_DATA_REGION_GROUP_NUM + +#### Show Heterogeneous Databases + +You can query the heterogeneous configuration of each database. The SQL statement is as follows: + +```sql +SHOW DATABASES DETAILS prefixPath? +``` + +For example: + +```sql +SHOW DATABASES DETAILS; +``` + +```shell ++-------------+-----------------------+---------------------+-------------------+---------------------+--------------------+-----------------------+------------------+---------------------+ +| Database|SchemaReplicationFactor|DataReplicationFactor|TimePartitionOrigin|TimePartitionInterval|SchemaRegionGroupNum|MaxSchemaRegionGroupNum|DataRegionGroupNum|MaxDataRegionGroupNum| ++-------------+-----------------------+---------------------+-------------------+---------------------+--------------------+-----------------------+------------------+---------------------+ +| root.db| 1| 1| 0| 604800000| 0| 2| 0| 3| ++-------------+-----------------------+---------------------+-------------------+---------------------+--------------------+-----------------------+------------------+---------------------+ +``` + +The columns in the query result are, in order: + ++ Database name ++ Number of schema replicas for the database ++ Number of data replicas for the database ++ Time partition origin of the database ++ Time partition interval of the database ++ Number of SchemaRegionGroups currently owned by the database ++ Maximum number of SchemaRegionGroups allowed for the database ++ Number of DataRegionGroups currently owned by the database ++ Maximum number of DataRegionGroups allowed for the database + ## 2. Device Template IoTDB supports the device template function, enabling different entities of the same type to share metadata, reduce the memory usage of metadata, and simplify the management of numerous entities and measurements. diff --git a/src/UserGuide/latest-Table/Basic-Concept/Database-Management_apache.md b/src/UserGuide/latest-Table/Basic-Concept/Database-Management_apache.md index b8469018e..9519572f8 100644 --- a/src/UserGuide/latest-Table/Basic-Concept/Database-Management_apache.md +++ b/src/UserGuide/latest-Table/Basic-Concept/Database-Management_apache.md @@ -21,44 +21,74 @@ # Database Management -## 1. Database Management +In the table model, a database is the top-level organizational structure for tables and is used to manage a group of business-related tables. Before creating tables, writing data, or querying data, you usually need to create a database and specify the database used by the current session through `USE `. -### 1.1 Create a Database +A database can be configured with properties such as TTL, time partition interval, the maximum number of SchemaRegionGroups, and the maximum number of DataRegionGroups. The database-level TTL is used as the default data retention period for tables in the database. If a table has its own TTL, the table-level TTL takes precedence. -This command is used to create a database. +## 1. Basic Concepts + +### 1.1 Database + +A database organizes and manages multiple tables. Databases can be divided by business domain, project, tenant, or data isolation requirements. For example, tables for a group of devices in the same business system can be placed in one database to manage their lifecycle, permissions, and query scope uniformly. + +In the table model, a database name is also the namespace for its tables. After `USE database1` is executed, subsequent table operations that do not explicitly specify a database name apply to `database1` by default. + +### 1.2 TTL + +TTL specifies how long data is retained, in milliseconds. Data that exceeds the TTL is automatically expired and deleted. Setting an appropriate TTL controls disk space usage and prevents accumulated historical data from affecting storage costs and query performance. + +TTL can be set at either the database level or the table level. For more information, see [TTL Delete Data](../Basic-Concept/TTL-Delete-Data_apache.md). + +### 1.3 Time Partition Interval + +The time partition interval determines the time range used to group data into directories on disk. The default value is 604800000 ms, or one week, and is suitable for most scenarios. + +### 1.4 RegionGroup + +IoTDB divides metadata and data into Regions managed by DataNodes. The `MAX_SCHEMA_REGION_GROUP_NUM` and `MAX_DATA_REGION_GROUP_NUM` database properties specify the maximum numbers of schema replica groups and data replica groups, respectively. These properties generally do not need to be changed manually. + +## 2. Database Management + +### 2.1 Create a Database + +Creates a database. **Syntax:** ```SQL - CREATE DATABASE (IF NOT EXISTS)? (WITH properties)? +CREATE DATABASE (IF NOT EXISTS)? (WITH properties)? ``` -**Note: ** +**Description:** -1. ``: The name of the database, with the following characteristics: - - Case-insensitive. After creation, it will be displayed uniformly in lowercase. - - Can include commas (`,`), underscores (`_`), numbers, letters, and Chinese characters. - - Maximum length is 64 characters. - - Names with special characters or Chinese characters must be enclosed in double quotes (`""`). +1. `` is the database name and has the following characteristics: + - It is case-insensitive and is displayed in lowercase after the database is created. + - It cannot exceed 64 characters. + - A name that contains underscores (`_`), digits (except as the first character), or English letters can be created directly. + - A name that contains special characters (such as a backtick), Chinese characters, or starts with a digit must be enclosed in double quotation marks (`""`). +2. The `WITH properties` clause supports the following properties: -2. `WITH properties`: Property names are case-insensitive. For more details, refer to the case sensitivity rules [case-sensitivity](../SQL-Manual/Identifier.md#2-case-sensitivity)。Configurable properties include: +| Property | Description | Default Value | +| --- | --- | --- | +| `TTL` | Automatic data expiration time, in milliseconds. The value must be a positive integer. | `INF` | +| `TIME_PARTITION_INTERVAL` | Time partition interval for the database, in milliseconds. The value must be a positive integer. | `604800000` | +| `MAX_SCHEMA_REGION_GROUP_NUM` | Maximum number of SchemaRegionGroups to which the database can automatically expand. The value must be a positive integer. Supported starting from V2.0.11. | `1` | +| `MAX_DATA_REGION_GROUP_NUM` | Maximum number of DataRegionGroups to which the database can automatically expand. The value must be a positive integer. Supported starting from V2.0.11. | `2` | -| Property | Description | Default Value | -| ----------------------- | ------------------------------------------------------------ | -------------------- | -| TTL | Automatic data expiration time, in milliseconds | `INF` | -| TIME_PARTITION_INTERVAL | Time partition interval for the database, in milliseconds | `604800000` (7 days) | -| SCHEMA_REGION_GROUP_NUM | Number of metadata replica groups; generally does not require modification | `1` | -| DATA_REGION_GROUP_NUM | Number of data replica groups; generally does not require modification | `2` | +**Notes:** -**Examples:** +- Property names are case-insensitive. For details, see [Case Sensitivity](../SQL-Manual/Identifier.md#2-case-sensitivity). +- The maximum schema/data region group quotas, `maxSchemaRegionGroupNum` and `maxDataRegionGroupNum`, can be set or adjusted through SQL when creating or modifying a database only when `schema_region_group_extension_policy` and `data_region_group_extension_policy` in `iotdb-common.properties` are set to `CUSTOM`. + +**Example:** ```SQL -CREATE DATABASE IF NOT EXISTS database1 with(TTL=31536000000); +CREATE DATABASE IF NOT EXISTS database1 WITH (TTL=31536000000); ``` -### 1.2 Use a Database +### 2.2 Use a Database -Specify the current database as the namespace for table operations. +Specifies the current database as the namespace for tables. **Syntax:** @@ -66,15 +96,15 @@ Specify the current database as the namespace for table operations. USE ``` -**Example:** +**Example:** ```SQL USE database1; ``` -### 1.3 View the Current Database +### 2.3 View the Current Database -Displays the name of the currently connected database. If no USE statement has been executed, the default is `null`. +Returns the name of the database used by the current session. If no database has been specified with a `USE` statement, the default value is `null`. **Syntax:** @@ -88,6 +118,7 @@ SHOW CURRENT_DATABASE USE database1; SHOW CURRENT_DATABASE; ``` + ```shell +---------------+ |CurrentDatabase| @@ -96,8 +127,7 @@ SHOW CURRENT_DATABASE; +---------------+ ``` - -### 1.4 View All Databases +### 2.4 View All Databases Displays all databases and their properties. @@ -107,35 +137,38 @@ Displays all databases and their properties. SHOW DATABASES (DETAILS)? ``` -**Columns Explained:** - +**Columns:** -| Column Name | Description | -| ----------------------- |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| database | Name of the database. | -| TTL | Data retention period. If TTL is specified when creating a database, it applies to all tables within the database. You can also set or update the TTL of individual tables using [create table](../Basic-Concept/Table-Management_apache.md#11-create-a-table) 、[alter table](../Basic-Concept/Table-Management_apache.md#14-update-tables) . | -| SchemaReplicationFactor | Number of metadata replicas, ensuring metadata high availability. This can be configured in the `iotdb-system.properties` file under the `schema_replication_factor` property. | -| DataReplicationFactor | Number of data replicas, ensuring data high availability. This can be configured in the `iotdb-system.properties` file under the `data_replication_factor` property. | -| TimePartitionInterval | Time partition interval, determining how often data is grouped into directories on disk. The default is typically one week. | -| Model | Returned when using the `DETAILS` option, showing the data model corresponding to each database (e.g., timeseries tree model or device table model). | +| Column Name | Description | +| --- | --- | +| Database | Database name. | +| TTL | Data retention period. A database-level TTL applies to all tables in the database by default. You can also set or update a table-level TTL through [CREATE TABLE](../Basic-Concept/Table-Management_apache.md#21-create-a-table) or [ALTER TABLE](../Basic-Concept/Table-Management_apache.md#25-update-tables). | +| SchemaReplicationFactor | Number of schema replicas used to ensure metadata availability. This value can be changed through `schema_replication_factor` in `iotdb-system.properties`. | +| DataReplicationFactor | Number of data replicas used to ensure data availability. This value can be changed through `data_replication_factor` in `iotdb-system.properties`. | +| TimePartitionInterval | Time partition interval, which determines the time range used to group data into directories on disk. The default value of one week is suitable for most scenarios. | +| SchemaRegionGroupNum | Returned with `DETAILS`. Number of schema replica groups currently owned by the database. | +| MaxSchemaRegionGroupNum | Returned with `DETAILS`. Maximum number of schema replica groups allowed for the database. | +| DataRegionGroupNum | Returned with `DETAILS`. Number of data replica groups currently owned by the database. | +| MaxDataRegionGroupNum | Returned with `DETAILS`. Maximum number of data replica groups allowed for the database. | -**Examples:** +**Example:** ```SQL SHOW DATABASES DETAILS; ``` + ```shell -+------------------+-------+-----------------------+---------------------+---------------------+--------------------+------------------+ -| Database|TTL(ms)|SchemaReplicationFactor|DataReplicationFactor|TimePartitionInterval|SchemaRegionGroupNum|DataRegionGroupNum| -+------------------+-------+-----------------------+---------------------+---------------------+--------------------+------------------+ -| database1| INF| 1| 1| 604800000| 1| 2| -|information_schema| INF| null| null| null| null| null| -+------------------+-------+-----------------------+---------------------+---------------------+--------------------+------------------+ ++------------------+-------+-----------------------+---------------------+---------------------+--------------------+-----------------------+------------------+---------------------+ +| Database|TTL(ms)|SchemaReplicationFactor|DataReplicationFactor|TimePartitionInterval|SchemaRegionGroupNum|MaxSchemaRegionGroupNum|DataRegionGroupNum|MaxDataRegionGroupNum| ++------------------+-------+-----------------------+---------------------+---------------------+--------------------+-----------------------+------------------+---------------------+ +| database1| INF| 1| 1| 604800000| 1| 1| 2| 2| +|information_schema| INF| null| null| null| null| null| null| null| ++------------------+-------+-----------------------+---------------------+---------------------+--------------------+-----------------------+------------------+---------------------+ ``` -### 1.5 Update a Database +### 2.5 Update a Database -Used to modify some attributes in the database. +Modifies supported database properties. **Syntax:** @@ -143,19 +176,20 @@ Used to modify some attributes in the database. ALTER DATABASE (IF EXISTS)? database=identifier SET PROPERTIES propertyAssignments ``` -**Note:** +**Description:** -1. The `ALTER DATABASE` operation currently only supports modifications to the database's `SCHEMA_REGION_GROUP_NUM`, `DATA_REGION_GROUP_NUM`, and `TTL` attributes. +1. `ALTER DATABASE` currently supports modifying only `MAX_SCHEMA_REGION_GROUP_NUM`, `MAX_DATA_REGION_GROUP_NUM`, and `TTL`. **Example:** ```SQL ALTER DATABASE database1 SET PROPERTIES TTL=31536000000; +ALTER DATABASE database1 SET PROPERTIES MAX_SCHEMA_REGION_GROUP_NUM=2, MAX_DATA_REGION_GROUP_NUM=4; ``` -### 1.6 Delete a Database +### 2.6 Delete a Database -Deletes the specified database and all associated tables and data. +Deletes a database. **Syntax:** @@ -163,10 +197,10 @@ Deletes the specified database and all associated tables and data. DROP DATABASE (IF EXISTS)? ``` -**Note:** +**Description:** -1. A database currently in use can still be dropped. -2. Deleting a database removes all its tables and stored data. +1. A database can be dropped even if it is the current database selected by `USE`. +2. Dropping a database deletes all tables in the database and all data stored in those tables. **Example:** diff --git a/src/UserGuide/latest-Table/Reference/System-Tables_apache.md b/src/UserGuide/latest-Table/Reference/System-Tables_apache.md index d2c58b41c..0b8788fea 100644 --- a/src/UserGuide/latest-Table/Reference/System-Tables_apache.md +++ b/src/UserGuide/latest-Table/Reference/System-Tables_apache.md @@ -77,27 +77,29 @@ IoTDB> show tables from information_schema * Contains information about all databases in the cluster. * Table structure is as follows: -| Column Name | Data Type | Column Type | Description | -| --------------------------------- | ----------- | ------------- | -------------------------------- | -| `database` | STRING | TAG | Database name | -| `ttl(ms)` | STRING | ATTRIBUTE | Data retention time | -| `schema_replication_factor` | INT32 | ATTRIBUTE | Schema replica count | -| `data_replication_factor` | INT32 | ATTRIBUTE | Data replica count | -| `time_partition_interval` | INT64 | ATTRIBUTE | Time partition interval | -| `schema_region_group_num` | INT32 | ATTRIBUTE | Number of schema region groups | -| `data_region_group_num` | INT32 | ATTRIBUTE | Number of data region groups | +| Column Name | Data Type | Column Type | Description | +| --- | --- | --- | --- | +| `database` | STRING | TAG | Database name | +| `ttl(ms)` | STRING | ATTRIBUTE | Data retention time | +| `schema_replication_factor` | INT32 | ATTRIBUTE | Number of schema replicas | +| `data_replication_factor` | INT32 | ATTRIBUTE | Number of data replicas | +| `time_partition_interval` | INT64 | ATTRIBUTE | Time partition interval | +| `schema_region_group_num` | INT32 | ATTRIBUTE | Number of schema regions | +| `max_schema_region_group_num` | INT32 | ATTRIBUTE | Maximum number of schema regions to which the database can expand. Supported starting from V2.0.11. | +| `data_region_group_num` | INT32 | ATTRIBUTE | Number of data regions | +| `max_data_region_group_num` | INT32 | ATTRIBUTE | Maximum number of data regions to which the database can expand. Supported starting from V2.0.11. | * The query results only display the collection of databases for which you have any permission on the database itself or any table within the database. * Query Example: ```sql IoTDB> select * from information_schema.databases -+------------------+-------+-------------------------+-----------------------+-----------------------+-----------------------+---------------------+ -| database|ttl(ms)|schema_replication_factor|data_replication_factor|time_partition_interval|schema_region_group_num|data_region_group_num| -+------------------+-------+-------------------------+-----------------------+-----------------------+-----------------------+---------------------+ -|information_schema| INF| null| null| null| null| null| -| database1| INF| 1| 1| 604800000| 0| 0| -+------------------+-------+-------------------------+-----------------------+-----------------------+-----------------------+---------------------+ ++------------------+-------+-------------------------+-----------------------+-----------------------+-----------------------+---------------------------+---------------------+-------------------------+ +| database|ttl(ms)|schema_replication_factor|data_replication_factor|time_partition_interval|schema_region_group_num|max_schema_region_group_num|data_region_group_num|max_data_region_group_num| ++------------------+-------+-------------------------+-----------------------+-----------------------+-----------------------+---------------------------+---------------------+-------------------------+ +|information_schema| INF| null| null| null| null| null| null| null| +| database1| INF| 1| 1| 604800000| 1| 1| 2| 2| ++------------------+-------+-------------------------+-----------------------+-----------------------+-----------------------+---------------------------+---------------------+-------------------------+ ``` ### 2.2 TABLES diff --git a/src/UserGuide/latest/Basic-Concept/Operate-Metadata_apache.md b/src/UserGuide/latest/Basic-Concept/Operate-Metadata_apache.md index 98d44745f..c6af247a0 100644 --- a/src/UserGuide/latest/Basic-Concept/Operate-Metadata_apache.md +++ b/src/UserGuide/latest/Basic-Concept/Operate-Metadata_apache.md @@ -154,102 +154,7 @@ Total line number = 1 It costs 0.002s ``` -### 1.5 Setting up heterogeneous databases (Advanced operations) - -Under the premise of familiar with IoTDB metadata modeling, -users can set up heterogeneous databases in IoTDB to cope with different production needs. - -Currently, the following database heterogeneous parameters are supported: - -| Parameter | Type | Description | -| ------------------------- | ------- | --------------------------------------------- | -| TTL | Long | TTL of the Database | -| SCHEMA_REPLICATION_FACTOR | Integer | The schema replication number of the Database | -| DATA_REPLICATION_FACTOR | Integer | The data replication number of the Database | -| SCHEMA_REGION_GROUP_NUM | Integer | The SchemaRegionGroup number of the Database | -| DATA_REGION_GROUP_NUM | Integer | The DataRegionGroup number of the Database | - -Note the following when configuring heterogeneous parameters: - -+ TTL and TIME_PARTITION_INTERVAL must be positive integers. -+ SCHEMA_REPLICATION_FACTOR and DATA_REPLICATION_FACTOR must be smaller than or equal to the number of deployed DataNodes. -+ The function of SCHEMA_REGION_GROUP_NUM and DATA_REGION_GROUP_NUM are related to the parameter `schema_region_group_extension_policy` and `data_region_group_extension_policy` in iotdb-system.properties configuration file. Take DATA_REGION_GROUP_NUM as an example: - If `data_region_group_extension_policy=CUSTOM` is set, DATA_REGION_GROUP_NUM serves as the number of DataRegionGroups owned by the Database. - If `data_region_group_extension_policy=AUTO`, DATA_REGION_GROUP_NUM is used as the lower bound of the DataRegionGroup quota owned by the Database. That is, when the Database starts writing data, it will have at least this number of DataRegionGroups. - -Users can set any heterogeneous parameters when creating a Database, or adjust some heterogeneous parameters during a stand-alone/distributed IoTDB run. - -#### Set heterogeneous parameters when creating a Database - -The user can set any of the above heterogeneous parameters when creating a Database. The SQL statement is as follows: - -```sql -CREATE DATABASE prefixPath (WITH databaseAttributeClause (COMMA? databaseAttributeClause)*)? -``` - -For example: - -```sql -CREATE DATABASE root.db WITH SCHEMA_REPLICATION_FACTOR=1, DATA_REPLICATION_FACTOR=3, SCHEMA_REGION_GROUP_NUM=1, DATA_REGION_GROUP_NUM=2; -``` - -#### Adjust heterogeneous parameters at run time - -Users can adjust some heterogeneous parameters during the IoTDB runtime, as shown in the following SQL statement: - -```sql -ALTER DATABASE prefixPath WITH databaseAttributeClause (COMMA? databaseAttributeClause)* -``` - -For example: - -```sql -ALTER DATABASE root.db WITH SCHEMA_REGION_GROUP_NUM=1, DATA_REGION_GROUP_NUM=2; -``` - -Note that only the following heterogeneous parameters can be adjusted at runtime: - -+ SCHEMA_REGION_GROUP_NUM -+ DATA_REGION_GROUP_NUM - -#### Show heterogeneous databases - -The user can query the specific heterogeneous configuration of each Database, and the SQL statement is as follows: - -```sql -SHOW DATABASES DETAILS prefixPath? -``` - -For example: - -```sql -SHOW DATABASES DETAILS -+--------+--------+-----------------------+---------------------+---------------------+--------------------+-----------------------+-----------------------+------------------+---------------------+---------------------+ -|Database| TTL|SchemaReplicationFactor|DataReplicationFactor|TimePartitionInterval|SchemaRegionGroupNum|MinSchemaRegionGroupNum|MaxSchemaRegionGroupNum|DataRegionGroupNum|MinDataRegionGroupNum|MaxDataRegionGroupNum| -+--------+--------+-----------------------+---------------------+---------------------+--------------------+-----------------------+-----------------------+------------------+---------------------+---------------------+ -|root.db1| null| 1| 3| 604800000| 0| 1| 1| 0| 2| 2| -|root.db2|86400000| 1| 1| 604800000| 0| 1| 1| 0| 2| 2| -|root.db3| null| 1| 1| 604800000| 0| 1| 1| 0| 2| 2| -+--------+--------+-----------------------+---------------------+---------------------+--------------------+-----------------------+-----------------------+------------------+---------------------+---------------------+ -Total line number = 3 -It costs 0.058s -``` - -The query results in each column are as follows: - -+ The name of the Database -+ The TTL of the Database -+ The schema replication number of the Database -+ The data replication number of the Database -+ The time partition interval of the Database -+ The current SchemaRegionGroup number of the Database -+ The required minimum SchemaRegionGroup number of the Database -+ The permitted maximum SchemaRegionGroup number of the Database -+ The current DataRegionGroup number of the Database -+ The required minimum DataRegionGroup number of the Database -+ The permitted maximum DataRegionGroup number of the Database - -### 1.6 TTL +### 1.5 TTL IoTDB supports setting data retention time (TTL) at the device level, allowing the system to automatically and periodically delete old data to effectively control disk space and maintain high query performance and low memory usage. TTL is set in milliseconds by default. Once data expires, it cannot be queried or written, but physical deletion is delayed until compaction. Please note that changes to TTL may temporarily affect data queryability, and if TTL is reduced or removed, previously invisible data due to TTL may reappear. @@ -360,6 +265,91 @@ show devices ``` All devices will definitely have a TTL, meaning it cannot be null. INF represents infinity. +### 1.6 Setting Up Heterogeneous Databases (Advanced Operations) + +With a solid understanding of IoTDB metadata modeling, users can configure heterogeneous databases in IoTDB to meet different production requirements. + +The following heterogeneous database parameters are supported: + +| Parameter | Type | Description | +| --- | --- | --- | +| TTL | Long | TTL of the database. The value must be a positive integer. | +| TIME_PARTITION_INTERVAL | Long | Time partition interval of the database. The value must be a positive integer. | +| MAX_SCHEMA_REGION_GROUP_NUM | Integer | Maximum number of SchemaRegionGroups to which the database can automatically expand. The value must be a positive integer. | +| MAX_DATA_REGION_GROUP_NUM | Integer | Maximum number of DataRegionGroups to which the database can automatically expand. The value must be a positive integer. | + +Note the following when configuring heterogeneous parameters: + ++ The maximum schema/data region group quotas, `maxSchemaRegionGroupNum` and `maxDataRegionGroupNum`, can be set or adjusted through SQL when creating or modifying a database only when `schema_region_group_extension_policy` and `data_region_group_extension_policy` in `iotdb-common.properties` are set to `CUSTOM`. ++ `MAX_SCHEMA_REGION_GROUP_NUM` and `MAX_DATA_REGION_GROUP_NUM` are supported starting from V2.0.11. + +#### Set Heterogeneous Parameters When Creating a Database + +You can set any of the preceding heterogeneous parameters when creating a database. The SQL statement is as follows: + +```sql +CREATE DATABASE prefixPath (WITH databaseAttributeClause (COMMA? databaseAttributeClause)*)? +``` + +For example: + +```sql +CREATE DATABASE root.db WITH TTL=360000, MAX_SCHEMA_REGION_GROUP_NUM=1, MAX_DATA_REGION_GROUP_NUM=2; +``` + +#### Adjust Heterogeneous Parameters at Runtime + +You can adjust some heterogeneous parameters while IoTDB is running. The SQL statement is as follows: + +```sql +ALTER DATABASE prefixPath WITH databaseAttributeClause (COMMA? databaseAttributeClause)* +``` + +For example: + +```sql +ALTER DATABASE root.db WITH MAX_SCHEMA_REGION_GROUP_NUM=2, MAX_DATA_REGION_GROUP_NUM=3; +``` + +Only the following heterogeneous parameters can be adjusted at runtime: + ++ MAX_SCHEMA_REGION_GROUP_NUM ++ MAX_DATA_REGION_GROUP_NUM + +#### Show Heterogeneous Databases + +You can query the heterogeneous configuration of each database. The SQL statement is as follows: + +```sql +SHOW DATABASES DETAILS prefixPath? +``` + +For example: + +```sql +SHOW DATABASES DETAILS; +``` + +```shell ++-------------+-----------------------+---------------------+-------------------+---------------------+--------------------+-----------------------+------------------+---------------------+ +| Database|SchemaReplicationFactor|DataReplicationFactor|TimePartitionOrigin|TimePartitionInterval|SchemaRegionGroupNum|MaxSchemaRegionGroupNum|DataRegionGroupNum|MaxDataRegionGroupNum| ++-------------+-----------------------+---------------------+-------------------+---------------------+--------------------+-----------------------+------------------+---------------------+ +| root.db| 1| 1| 0| 604800000| 0| 2| 0| 3| ++-------------+-----------------------+---------------------+-------------------+---------------------+--------------------+-----------------------+------------------+---------------------+ +``` + +The columns in the query result are, in order: + ++ Database name ++ Number of schema replicas for the database ++ Number of data replicas for the database ++ Time partition origin of the database ++ Time partition interval of the database ++ Number of SchemaRegionGroups currently owned by the database ++ Maximum number of SchemaRegionGroups allowed for the database ++ Number of DataRegionGroups currently owned by the database ++ Maximum number of DataRegionGroups allowed for the database + ## 2. Device Template IoTDB supports the device template function, enabling different entities of the same type to share metadata, reduce the memory usage of metadata, and simplify the management of numerous entities and measurements. diff --git a/src/zh/UserGuide/Master/Table/Basic-Concept/Database-Management_apache.md b/src/zh/UserGuide/Master/Table/Basic-Concept/Database-Management_apache.md index 6acfe7e9a..ba5865dc6 100644 --- a/src/zh/UserGuide/Master/Table/Basic-Concept/Database-Management_apache.md +++ b/src/zh/UserGuide/Master/Table/Basic-Concept/Database-Management_apache.md @@ -21,16 +21,42 @@ # 数据库管理 -## 1. 数据库管理 +在表模型中，数据库是表的上层组织结构，用于管理一组业务相关的表。创建表、写入数据或查询数据前，通常需要先创建数据库，并通过 `USE ` 指定当前会话使用的数据库。 -### 1.1 创建数据库 +数据库可以设置 TTL、时间分区间隔、SchemaRegionGroup 数量和 DataRegionGroup 数量等属性。其中 TTL 会作为数据库下表的默认数据保留周期；如果表单独设置了 TTL，则以表级 TTL 为准。 + +## 1. 基础概念 + +### 1.1 数据库 + +数据库用于组织和管理多张表。通常可以按业务域、项目、租户或数据隔离需求划分数据库。例如，将同一业务系统的一组设备表放在同一个数据库中，便于统一管理生命周期、权限和查询空间。 + +在表模型中，数据库名称也是表的命名空间。执行 `USE database1` 后，后续未显式指定数据库名的表操作会默认作用于 `database1`。 + +### 1.2 TTL + +TTL 用于指定数据保存时间，单位为毫秒。超过 TTL 的数据会被自动过期删除。合理设置 TTL 可以控制磁盘空间占用，避免历史数据持续累积影响存储成本和查询性能。 + +TTL 可以在数据库级别设置，也可以在表级别设置。如需了解更详细的功能介绍可查阅：[数据保留时间](../Basic-Concept/TTL-Delete-Data_apache.md)。 + +### 1.3 时间分区间隔 + +时间分区间隔决定数据在磁盘上按多长时间进行目录分组，默认值为 604800000 ms，即 1 周。通常采用默认值即可。 + +### 1.4 RegionGroup + +IoTDB 会将元数据和数据划分为 Region，并由 DataNode 管理。数据库级属性中的 `MAX_SCHEMA_REGION_GROUP_NUM` 和 `MAX_DATA_REGION_GROUP_NUM` 分别用于表示元数据副本组和数据副本组允许达到的最大数量，一般不需要手动修改。 + +## 2. 数据库管理 + +### 2.1 创建数据库 用于创建数据库。 **语法：** ```SQL - CREATE DATABASE (IF NOT EXISTS)? (WITH properties)? +CREATE DATABASE (IF NOT EXISTS)? (WITH properties)? ``` **说明：** @@ -39,26 +65,29 @@ - 大小写不敏感，创建成功后，统一显示为小写 - 名称的长度不得超过 64 个字符。 - 名称中包含下划线（_）、数字（非开头）、英文字母可以直接创建 - - 名称中包含特殊字符（如`）、中文字符、数字开头时，必须用双引号 "" 括起来。 + - 名称中包含特殊字符（如反引号）、中文字符、数字开头时，必须用双引号 `""` 括起来。 2. WITH properties 子句可配置如下属性： -> 注：属性的大小写不敏感，有关详细信息[大小写敏感规则](../SQL-Manual/Identifier.md#大小写敏感性)。 +| 属性 | 含义 | 默认值 | +| --- | --- | --- | +| `TTL` | 数据自动过期删除，单位 ms，此值需要为正整数 | INF | +| `TIME_PARTITION_INTERVAL` | 数据库的时间分区间隔，单位 ms，此值需要为正整数 | 604800000 | +| `MAX_SCHEMA_REGION_GROUP_NUM` | 数据库自动扩展 SchemaRegionGroup 时允许达到的最大 SchemaRegionGroup 数量，此值需要为正整数，V2.0.11 起支持 | 1 | +| `MAX_DATA_REGION_GROUP_NUM` | 数据库自动扩展 DataRegionGroup 时允许达到的最大 DataRegionGroup 数量，此值需要为正整数，V2.0.11 起支持 | 2 | + +**注意：** -| 属性 | 含义 | 默认值 | -| ------------------------- | ---------------------------------------- | --------- | -| `TTL` | 数据自动过期删除，单位 ms | INF | -| `TIME_PARTITION_INTERVAL` | 数据库的时间分区间隔，单位 ms | 604800000 | -| `SCHEMA_REGION_GROUP_NUM` | 数据库的元数据副本组数量，一般不需要修改 | 1 | -| `DATA_REGION_GROUP_NUM` | 数据库的数据副本组数量，一般不需要修改 | 2 | +- 属性的大小写不敏感，有关详细信息请参阅[大小写敏感规则](../SQL-Manual/Identifier.md#大小写敏感性)。 +- 仅当 `iotdb-common.properties` 配置文件中的 `schema_region_group_extension_policy` 和 `data_region_group_extension_policy` 参数设置为 `CUSTOM` 策略时，才支持通过 SQL 在创建或修改数据库时设置或调整 schema/data region group 最大配额，即 `maxSchemaRegionGroupNum` 和 `maxDataRegionGroupNum`。 **示例：** ```SQL -CREATE DATABASE IF NOT EXISTS database1 with(TTL=31536000000); +CREATE DATABASE IF NOT EXISTS database1 WITH (TTL=31536000000); ``` -### 1.2 使用数据库 +### 2.2 使用数据库 用于指定当前数据库作为表的命名空间。 @@ -74,7 +103,7 @@ USE USE database1; ``` -### 1.3 查看当前数据库 +### 2.3 查看当前数据库 返回当前会话所连接的数据库名称，若未执行过 `use`语句指定数据库，则默认为 `null`。 @@ -90,6 +119,7 @@ SHOW CURRENT_DATABASE USE database1; SHOW CURRENT_DATABASE; ``` + ```shell +---------------+ |CurrentDatabase| @@ -98,7 +128,7 @@ SHOW CURRENT_DATABASE; +---------------+ ``` -### 1.4 查看所有数据库 +### 2.4 查看所有数据库 用于查看所有数据库和数据库的属性信息。 @@ -110,31 +140,34 @@ SHOW DATABASES (DETAILS)? **语句返回列含义如下：** -| 列名 | 含义 | -| ----------------------- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| database | database名称。 | -| TTL | 数据保留周期。如果在创建数据库的时候指定TTL，则TTL对该数据库下所有表的TTL生效。也可以再通过 [create table](../Basic-Concept/Table-Management_apache.md#11-创建表) 、[alter table](../Basic-Concept/Table-Management_apache.md#14-修改表) 来设置或更新表的TTL时间。 | -| SchemaReplicationFactor | 元数据副本数，用于确保元数据的高可用性。可以在`iotdb-system.properties`中修改`schema_replication_factor`配置项。 | -| DataReplicationFactor | 数据副本数，用于确保数据的高可用性。可以在`iotdb-system.properties`中修改`data_replication_factor`配置项。 | -| TimePartitionInterval | 时间分区间隔，决定了数据在磁盘上按多长时间进行目录分组，通常采用默认1周即可。 | -| SchemaRegionGroupNum | 使用`DETAILS`语句会返回此列，展示数据库的元数据副本组数量，一般不需要修改 | -| DataRegionGroupNum | 使用`DETAILS`语句会返回此列，展示数据库的数据副本组数量，一般不需要修改 | +| 列名 | 含义 | +| --- | --- | +| Database | 数据库名称。 | +| TTL | 数据保留周期。如果在创建数据库时指定 TTL，则 TTL 默认对该数据库下所有表生效。也可以通过 [CREATE TABLE](../Basic-Concept/Table-Management_apache.md#21-创建表) 或 [ALTER TABLE](../Basic-Concept/Table-Management_apache.md#25-修改表) 设置或更新表的 TTL。 | +| SchemaReplicationFactor | 元数据副本数，用于确保元数据的高可用性。可以在 `iotdb-system.properties` 中修改 `schema_replication_factor` 配置项。 | +| DataReplicationFactor | 数据副本数，用于确保数据的高可用性。可以在 `iotdb-system.properties` 中修改 `data_replication_factor` 配置项。 | +| TimePartitionInterval | 时间分区间隔，决定数据在磁盘上按多长时间进行目录分组，通常采用默认值 1 周即可。 | +| SchemaRegionGroupNum | 使用 `DETAILS` 语句会返回此列，展示数据库当前拥有的元数据副本组数量。 | +| MaxSchemaRegionGroupNum | 使用 `DETAILS` 语句会返回此列，展示数据库允许拥有的最大元数据副本组数量。 | +| DataRegionGroupNum | 使用 `DETAILS` 语句会返回此列，展示数据库当前拥有的数据副本组数量。 | +| MaxDataRegionGroupNum | 使用 `DETAILS` 语句会返回此列，展示数据库允许拥有的最大数据副本组数量。 | **示例:** ```SQL SHOW DATABASES DETAILS; ``` + ```shell -+------------------+-------+-----------------------+---------------------+---------------------+--------------------+------------------+ -| Database|TTL(ms)|SchemaReplicationFactor|DataReplicationFactor|TimePartitionInterval|SchemaRegionGroupNum|DataRegionGroupNum| -+------------------+-------+-----------------------+---------------------+---------------------+--------------------+------------------+ -| database1| INF| 1| 1| 604800000| 1| 2| -|information_schema| INF| null| null| null| null| null| -+------------------+-------+-----------------------+---------------------+---------------------+--------------------+------------------+ ++------------------+-------+-----------------------+---------------------+---------------------+--------------------+-----------------------+------------------+---------------------+ +| Database|TTL(ms)|SchemaReplicationFactor|DataReplicationFactor|TimePartitionInterval|SchemaRegionGroupNum|MaxSchemaRegionGroupNum|DataRegionGroupNum|MaxDataRegionGroupNum| ++------------------+-------+-----------------------+---------------------+---------------------+--------------------+-----------------------+------------------+---------------------+ +| database1| INF| 1| 1| 604800000| 1| 1| 2| 2| +|information_schema| INF| null| null| null| null| null| null| null| ++------------------+-------+-----------------------+---------------------+---------------------+--------------------+-----------------------+------------------+---------------------+ ``` -### 1.5 修改数据库 +### 2.5 修改数据库 用于修改数据库中的部分属性。 @@ -146,15 +179,16 @@ ALTER DATABASE (IF EXISTS)? database=identifier SET PROPERTIES propertyAssignmen **说明：** -1. `ALTER DATABASE`操作目前仅支持对数据库的`SCHEMA_REGION_GROUP_NUM`、`DATA_REGION_GROUP_NUM`以及`TTL`属性进行修改。 +1. `ALTER DATABASE` 操作目前仅支持对数据库的 `MAX_SCHEMA_REGION_GROUP_NUM`、`MAX_DATA_REGION_GROUP_NUM` 以及 `TTL` 属性进行修改。 **示例:** ```SQL ALTER DATABASE database1 SET PROPERTIES TTL=31536000000; +ALTER DATABASE database1 SET PROPERTIES MAX_SCHEMA_REGION_GROUP_NUM=2, MAX_DATA_REGION_GROUP_NUM=4; ``` -### 1.6 删除数据库 +### 2.6 删除数据库 用于删除数据库。 diff --git a/src/zh/UserGuide/Master/Table/Reference/System-Tables_apache.md b/src/zh/UserGuide/Master/Table/Reference/System-Tables_apache.md index cb7787393..76aa2b4d7 100644 --- a/src/zh/UserGuide/Master/Table/Reference/System-Tables_apache.md +++ b/src/zh/UserGuide/Master/Table/Reference/System-Tables_apache.md @@ -77,27 +77,29 @@ IoTDB> show tables from information_schema * 包含集群中所有数据库的信息 * 表结构如下表所示： -| 列名 | 数据类型 | 列类型 | 说明 | -| ----------------------------- | ---------- | ----------- | ---------------- | -| database | STRING | TAG | 数据库名称 | -| ttl(ms) | STRING | ATTRIBUTE | 数据保留时间 | -| schema\_replication\_factor | INT32 | ATTRIBUTE | 元数据副本数 | -| data\_replication\_factor | INT32 | ATTRIBUTE | 数据副本数 | -| time\_partition\_interval | INT64 | ATTRIBUTE | 时间分区间隔 | -| schema\_region\_group\_num | INT32 | ATTRIBUTE | 元数据分区数量 | -| data\_region\_group\_num | INT32 | ATTRIBUTE | 数据分区数量 | +| 列名 | 数据类型 | 列类型 | 说明 | +| --- | --- | --- | --- | +| database | STRING | TAG | 数据库名称 | +| ttl(ms) | STRING | ATTRIBUTE | 数据保留时间 | +| schema\_replication\_factor | INT32 | ATTRIBUTE | 元数据副本数 | +| data\_replication\_factor | INT32 | ATTRIBUTE | 数据副本数 | +| time\_partition\_interval | INT64 | ATTRIBUTE | 时间分区间隔 | +| schema\_region\_group\_num | INT32 | ATTRIBUTE | 元数据分区数量 | +| max\_schema\_region\_group\_num | INT32 | ATTRIBUTE | 可扩展最大元数据分区数量，V2.0.11 起支持 | +| data\_region\_group\_num | INT32 | ATTRIBUTE | 数据分区数量 | +| max\_data\_region\_group\_num | INT32 | ATTRIBUTE | 可扩展最大数据分区数量，V2.0.11 起支持 | * 查询结果只展示自身对该数据库本身或库中任意表有任意权限的数据库集合 * 查询示例： ```sql IoTDB> select * from information_schema.databases -+------------------+-------+-------------------------+-----------------------+-----------------------+-----------------------+---------------------+ -| database|ttl(ms)|schema_replication_factor|data_replication_factor|time_partition_interval|schema_region_group_num|data_region_group_num| -+------------------+-------+-------------------------+-----------------------+-----------------------+-----------------------+---------------------+ -|information_schema| INF| null| null| null| null| null| -| database1| INF| 1| 1| 604800000| 0| 0| -+------------------+-------+-------------------------+-----------------------+-----------------------+-----------------------+---------------------+ ++------------------+-------+-------------------------+-----------------------+-----------------------+-----------------------+---------------------------+---------------------+-------------------------+ +| database|ttl(ms)|schema_replication_factor|data_replication_factor|time_partition_interval|schema_region_group_num|max_schema_region_group_num|data_region_group_num|max_data_region_group_num| ++------------------+-------+-------------------------+-----------------------+-----------------------+-----------------------+---------------------------+---------------------+-------------------------+ +|information_schema| INF| null| null| null| null| null| null| null| +| database1| INF| 1| 1| 604800000| 1| 1| 2| 2| ++------------------+-------+-------------------------+-----------------------+-----------------------+-----------------------+---------------------------+---------------------+-------------------------+ ``` ### 2.2 TABLES 表 diff --git a/src/zh/UserGuide/Master/Tree/Basic-Concept/Operate-Metadata_apache.md b/src/zh/UserGuide/Master/Tree/Basic-Concept/Operate-Metadata_apache.md index 0b1aeadb6..85f63d844 100644 --- a/src/zh/UserGuide/Master/Tree/Basic-Concept/Operate-Metadata_apache.md +++ b/src/zh/UserGuide/Master/Tree/Basic-Concept/Operate-Metadata_apache.md @@ -277,23 +277,17 @@ show devices; 目前支持的数据库异构参数有： -| 参数名 | 参数类型 | 参数描述 | -|---------------------------|---------|---------------------------| -| TTL | Long | 数据库的 TTL | -| SCHEMA_REPLICATION_FACTOR | Integer | 数据库的元数据副本数 | -| DATA_REPLICATION_FACTOR | Integer | 数据库的数据副本数 | -| SCHEMA_REGION_GROUP_NUM | Integer | 数据库的 SchemaRegionGroup 数量 | -| DATA_REGION_GROUP_NUM | Integer | 数据库的 DataRegionGroup 数量 | - -用户在配置异构参数时需要注意以下三点： -+ TTL 和 TIME_PARTITION_INTERVAL 必须为正整数。 -+ SCHEMA_REPLICATION_FACTOR 和 DATA_REPLICATION_FACTOR 必须小于等于已部署的 DataNode 数量。 -+ SCHEMA_REGION_GROUP_NUM 和 DATA_REGION_GROUP_NUM 的功能与 iotdb-system.properties 配置文件中的 -`schema_region_group_extension_policy` 和 `data_region_group_extension_policy` 参数相关，以 DATA_REGION_GROUP_NUM 为例： -若设置 `data_region_group_extension_policy=CUSTOM`，则 DATA_REGION_GROUP_NUM 将作为 Database 拥有的 DataRegionGroup 的数量； -若设置 `data_region_group_extension_policy=AUTO`，则 DATA_REGION_GROUP_NUM 将作为 Database 拥有的 DataRegionGroup 的配额下界，即当该 Database 开始写入数据时，将至少拥有此数量的 DataRegionGroup。 - -用户可以在创建 Database 时设置任意异构参数，或在单机/分布式 IoTDB 运行时调整部分异构参数。 +| 参数名 | 参数类型 | 参数描述 | +| --- | --- | --- | +| TTL | Long | 数据库的 TTL，此值需要为正整数 | +| TIME_PARTITION_INTERVAL | Long | 数据库的时间分区间隔，此值需要为正整数 | +| MAX_SCHEMA_REGION_GROUP_NUM | Integer | 数据库自动扩展 SchemaRegionGroup 时允许达到的最大 SchemaRegionGroup 数量，此值需要为正整数 | +| MAX_DATA_REGION_GROUP_NUM | Integer | 数据库自动扩展 DataRegionGroup 时允许达到的最大 DataRegionGroup 数量，此值需要为正整数 | + +用户在配置异构参数时需要注意： + ++ 仅当 `iotdb-common.properties` 配置文件中的 `schema_region_group_extension_policy` 和 `data_region_group_extension_policy` 参数设置为 `CUSTOM` 策略时，才支持通过 SQL 在创建或修改数据库时设置或调整 schema/data region group 最大配额，即 `maxSchemaRegionGroupNum` 和 `maxDataRegionGroupNum`。 ++ `MAX_SCHEMA_REGION_GROUP_NUM` 和 `MAX_DATA_REGION_GROUP_NUM` 自 V2.0.11 版本起支持。 #### 创建 Database 时设置异构参数 @@ -305,7 +299,7 @@ CREATE DATABASE prefixPath (WITH databaseAttributeClause (COMMA? databaseAttribu 例如： ```sql -CREATE DATABASE root.db WITH SCHEMA_REPLICATION_FACTOR=1, DATA_REPLICATION_FACTOR=3, SCHEMA_REGION_GROUP_NUM=1, DATA_REGION_GROUP_NUM=2; +CREATE DATABASE root.db WITH TTL=360000, MAX_SCHEMA_REGION_GROUP_NUM=1, MAX_DATA_REGION_GROUP_NUM=2; ``` #### 运行时调整异构参数 @@ -318,12 +312,12 @@ ALTER DATABASE prefixPath WITH databaseAttributeClause (COMMA? databaseAttribute 例如： ```sql -ALTER DATABASE root.db WITH SCHEMA_REGION_GROUP_NUM=1, DATA_REGION_GROUP_NUM=2; +ALTER DATABASE root.db WITH MAX_SCHEMA_REGION_GROUP_NUM=2, MAX_DATA_REGION_GROUP_NUM=3; ``` 注意，运行时只能调整下列异构参数： -+ SCHEMA_REGION_GROUP_NUM -+ DATA_REGION_GROUP_NUM ++ MAX_SCHEMA_REGION_GROUP_NUM ++ MAX_DATA_REGION_GROUP_NUM #### 查看异构数据库 @@ -339,28 +333,22 @@ SHOW DATABASES DETAILS prefixPath? SHOW DATABASES DETAILS; ``` ```shell -+--------+--------+-----------------------+---------------------+---------------------+--------------------+-----------------------+-----------------------+------------------+---------------------+---------------------+ -|Database| TTL|SchemaReplicationFactor|DataReplicationFactor|TimePartitionInterval|SchemaRegionGroupNum|MinSchemaRegionGroupNum|MaxSchemaRegionGroupNum|DataRegionGroupNum|MinDataRegionGroupNum|MaxDataRegionGroupNum| -+--------+--------+-----------------------+---------------------+---------------------+--------------------+-----------------------+-----------------------+------------------+---------------------+---------------------+ -|root.db1| null| 1| 3| 604800000| 0| 1| 1| 0| 2| 2| -|root.db2|86400000| 1| 1| 604800000| 0| 1| 1| 0| 2| 2| -|root.db3| null| 1| 1| 604800000| 0| 1| 1| 0| 2| 2| -+--------+--------+-----------------------+---------------------+---------------------+--------------------+-----------------------+-----------------------+------------------+---------------------+---------------------+ -Total line number = 3 -It costs 0.058s ++-------------+-----------------------+---------------------+-------------------+---------------------+--------------------+-----------------------+------------------+---------------------+ +| Database|SchemaReplicationFactor|DataReplicationFactor|TimePartitionOrigin|TimePartitionInterval|SchemaRegionGroupNum|MaxSchemaRegionGroupNum|DataRegionGroupNum|MaxDataRegionGroupNum| ++-------------+-----------------------+---------------------+-------------------+---------------------+--------------------+-----------------------+------------------+---------------------+ +| root.db| 1| 1| 0| 604800000| 0| 2| 0| 3| ++-------------+-----------------------+---------------------+-------------------+---------------------+--------------------+-----------------------+------------------+---------------------+ ``` 各列查询结果依次为： + 数据库名称 -+ 数据库的 TTL + 数据库的元数据副本数 + 数据库的数据副本数 ++ 数据库的时间分区原点 + 数据库的时间分区间隔 + 数据库当前拥有的 SchemaRegionGroup 数量 -+ 数据库需要拥有的最小 SchemaRegionGroup 数量 + 数据库允许拥有的最大 SchemaRegionGroup 数量 + 数据库当前拥有的 DataRegionGroup 数量 -+ 数据库需要拥有的最小 DataRegionGroup 数量 + 数据库允许拥有的最大 DataRegionGroup 数量 diff --git a/src/zh/UserGuide/latest-Table/Basic-Concept/Database-Management_apache.md b/src/zh/UserGuide/latest-Table/Basic-Concept/Database-Management_apache.md index 6acfe7e9a..ba5865dc6 100644 --- a/src/zh/UserGuide/latest-Table/Basic-Concept/Database-Management_apache.md +++ b/src/zh/UserGuide/latest-Table/Basic-Concept/Database-Management_apache.md @@ -21,16 +21,42 @@ # 数据库管理 -## 1. 数据库管理 +在表模型中，数据库是表的上层组织结构，用于管理一组业务相关的表。创建表、写入数据或查询数据前，通常需要先创建数据库，并通过 `USE ` 指定当前会话使用的数据库。 -### 1.1 创建数据库 +数据库可以设置 TTL、时间分区间隔、SchemaRegionGroup 数量和 DataRegionGroup 数量等属性。其中 TTL 会作为数据库下表的默认数据保留周期；如果表单独设置了 TTL，则以表级 TTL 为准。 + +## 1. 基础概念 + +### 1.1 数据库 + +数据库用于组织和管理多张表。通常可以按业务域、项目、租户或数据隔离需求划分数据库。例如，将同一业务系统的一组设备表放在同一个数据库中，便于统一管理生命周期、权限和查询空间。 + +在表模型中，数据库名称也是表的命名空间。执行 `USE database1` 后，后续未显式指定数据库名的表操作会默认作用于 `database1`。 + +### 1.2 TTL + +TTL 用于指定数据保存时间，单位为毫秒。超过 TTL 的数据会被自动过期删除。合理设置 TTL 可以控制磁盘空间占用，避免历史数据持续累积影响存储成本和查询性能。 + +TTL 可以在数据库级别设置，也可以在表级别设置。如需了解更详细的功能介绍可查阅：[数据保留时间](../Basic-Concept/TTL-Delete-Data_apache.md)。 + +### 1.3 时间分区间隔 + +时间分区间隔决定数据在磁盘上按多长时间进行目录分组，默认值为 604800000 ms，即 1 周。通常采用默认值即可。 + +### 1.4 RegionGroup + +IoTDB 会将元数据和数据划分为 Region，并由 DataNode 管理。数据库级属性中的 `MAX_SCHEMA_REGION_GROUP_NUM` 和 `MAX_DATA_REGION_GROUP_NUM` 分别用于表示元数据副本组和数据副本组允许达到的最大数量，一般不需要手动修改。 + +## 2. 数据库管理 + +### 2.1 创建数据库 用于创建数据库。 **语法：** ```SQL - CREATE DATABASE (IF NOT EXISTS)? (WITH properties)? +CREATE DATABASE (IF NOT EXISTS)? (WITH properties)? ``` **说明：** @@ -39,26 +65,29 @@ - 大小写不敏感，创建成功后，统一显示为小写 - 名称的长度不得超过 64 个字符。 - 名称中包含下划线（_）、数字（非开头）、英文字母可以直接创建 - - 名称中包含特殊字符（如`）、中文字符、数字开头时，必须用双引号 "" 括起来。 + - 名称中包含特殊字符（如反引号）、中文字符、数字开头时，必须用双引号 `""` 括起来。 2. WITH properties 子句可配置如下属性： -> 注：属性的大小写不敏感，有关详细信息[大小写敏感规则](../SQL-Manual/Identifier.md#大小写敏感性)。 +| 属性 | 含义 | 默认值 | +| --- | --- | --- | +| `TTL` | 数据自动过期删除，单位 ms，此值需要为正整数 | INF | +| `TIME_PARTITION_INTERVAL` | 数据库的时间分区间隔，单位 ms，此值需要为正整数 | 604800000 | +| `MAX_SCHEMA_REGION_GROUP_NUM` | 数据库自动扩展 SchemaRegionGroup 时允许达到的最大 SchemaRegionGroup 数量，此值需要为正整数，V2.0.11 起支持 | 1 | +| `MAX_DATA_REGION_GROUP_NUM` | 数据库自动扩展 DataRegionGroup 时允许达到的最大 DataRegionGroup 数量，此值需要为正整数，V2.0.11 起支持 | 2 | + +**注意：** -| 属性 | 含义 | 默认值 | -| ------------------------- | ---------------------------------------- | --------- | -| `TTL` | 数据自动过期删除，单位 ms | INF | -| `TIME_PARTITION_INTERVAL` | 数据库的时间分区间隔，单位 ms | 604800000 | -| `SCHEMA_REGION_GROUP_NUM` | 数据库的元数据副本组数量，一般不需要修改 | 1 | -| `DATA_REGION_GROUP_NUM` | 数据库的数据副本组数量，一般不需要修改 | 2 | +- 属性的大小写不敏感，有关详细信息请参阅[大小写敏感规则](../SQL-Manual/Identifier.md#大小写敏感性)。 +- 仅当 `iotdb-common.properties` 配置文件中的 `schema_region_group_extension_policy` 和 `data_region_group_extension_policy` 参数设置为 `CUSTOM` 策略时，才支持通过 SQL 在创建或修改数据库时设置或调整 schema/data region group 最大配额，即 `maxSchemaRegionGroupNum` 和 `maxDataRegionGroupNum`。 **示例：** ```SQL -CREATE DATABASE IF NOT EXISTS database1 with(TTL=31536000000); +CREATE DATABASE IF NOT EXISTS database1 WITH (TTL=31536000000); ``` -### 1.2 使用数据库 +### 2.2 使用数据库 用于指定当前数据库作为表的命名空间。 @@ -74,7 +103,7 @@ USE USE database1; ``` -### 1.3 查看当前数据库 +### 2.3 查看当前数据库 返回当前会话所连接的数据库名称，若未执行过 `use`语句指定数据库，则默认为 `null`。 @@ -90,6 +119,7 @@ SHOW CURRENT_DATABASE USE database1; SHOW CURRENT_DATABASE; ``` + ```shell +---------------+ |CurrentDatabase| @@ -98,7 +128,7 @@ SHOW CURRENT_DATABASE; +---------------+ ``` -### 1.4 查看所有数据库 +### 2.4 查看所有数据库 用于查看所有数据库和数据库的属性信息。 @@ -110,31 +140,34 @@ SHOW DATABASES (DETAILS)? **语句返回列含义如下：** -| 列名 | 含义 | -| ----------------------- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| database | database名称。 | -| TTL | 数据保留周期。如果在创建数据库的时候指定TTL，则TTL对该数据库下所有表的TTL生效。也可以再通过 [create table](../Basic-Concept/Table-Management_apache.md#11-创建表) 、[alter table](../Basic-Concept/Table-Management_apache.md#14-修改表) 来设置或更新表的TTL时间。 | -| SchemaReplicationFactor | 元数据副本数，用于确保元数据的高可用性。可以在`iotdb-system.properties`中修改`schema_replication_factor`配置项。 | -| DataReplicationFactor | 数据副本数，用于确保数据的高可用性。可以在`iotdb-system.properties`中修改`data_replication_factor`配置项。 | -| TimePartitionInterval | 时间分区间隔，决定了数据在磁盘上按多长时间进行目录分组，通常采用默认1周即可。 | -| SchemaRegionGroupNum | 使用`DETAILS`语句会返回此列，展示数据库的元数据副本组数量，一般不需要修改 | -| DataRegionGroupNum | 使用`DETAILS`语句会返回此列，展示数据库的数据副本组数量，一般不需要修改 | +| 列名 | 含义 | +| --- | --- | +| Database | 数据库名称。 | +| TTL | 数据保留周期。如果在创建数据库时指定 TTL，则 TTL 默认对该数据库下所有表生效。也可以通过 [CREATE TABLE](../Basic-Concept/Table-Management_apache.md#21-创建表) 或 [ALTER TABLE](../Basic-Concept/Table-Management_apache.md#25-修改表) 设置或更新表的 TTL。 | +| SchemaReplicationFactor | 元数据副本数，用于确保元数据的高可用性。可以在 `iotdb-system.properties` 中修改 `schema_replication_factor` 配置项。 | +| DataReplicationFactor | 数据副本数，用于确保数据的高可用性。可以在 `iotdb-system.properties` 中修改 `data_replication_factor` 配置项。 | +| TimePartitionInterval | 时间分区间隔，决定数据在磁盘上按多长时间进行目录分组，通常采用默认值 1 周即可。 | +| SchemaRegionGroupNum | 使用 `DETAILS` 语句会返回此列，展示数据库当前拥有的元数据副本组数量。 | +| MaxSchemaRegionGroupNum | 使用 `DETAILS` 语句会返回此列，展示数据库允许拥有的最大元数据副本组数量。 | +| DataRegionGroupNum | 使用 `DETAILS` 语句会返回此列，展示数据库当前拥有的数据副本组数量。 | +| MaxDataRegionGroupNum | 使用 `DETAILS` 语句会返回此列，展示数据库允许拥有的最大数据副本组数量。 | **示例:** ```SQL SHOW DATABASES DETAILS; ``` + ```shell -+------------------+-------+-----------------------+---------------------+---------------------+--------------------+------------------+ -| Database|TTL(ms)|SchemaReplicationFactor|DataReplicationFactor|TimePartitionInterval|SchemaRegionGroupNum|DataRegionGroupNum| -+------------------+-------+-----------------------+---------------------+---------------------+--------------------+------------------+ -| database1| INF| 1| 1| 604800000| 1| 2| -|information_schema| INF| null| null| null| null| null| -+------------------+-------+-----------------------+---------------------+---------------------+--------------------+------------------+ ++------------------+-------+-----------------------+---------------------+---------------------+--------------------+-----------------------+------------------+---------------------+ +| Database|TTL(ms)|SchemaReplicationFactor|DataReplicationFactor|TimePartitionInterval|SchemaRegionGroupNum|MaxSchemaRegionGroupNum|DataRegionGroupNum|MaxDataRegionGroupNum| ++------------------+-------+-----------------------+---------------------+---------------------+--------------------+-----------------------+------------------+---------------------+ +| database1| INF| 1| 1| 604800000| 1| 1| 2| 2| +|information_schema| INF| null| null| null| null| null| null| null| ++------------------+-------+-----------------------+---------------------+---------------------+--------------------+-----------------------+------------------+---------------------+ ``` -### 1.5 修改数据库 +### 2.5 修改数据库 用于修改数据库中的部分属性。 @@ -146,15 +179,16 @@ ALTER DATABASE (IF EXISTS)? database=identifier SET PROPERTIES propertyAssignmen **说明：** -1. `ALTER DATABASE`操作目前仅支持对数据库的`SCHEMA_REGION_GROUP_NUM`、`DATA_REGION_GROUP_NUM`以及`TTL`属性进行修改。 +1. `ALTER DATABASE` 操作目前仅支持对数据库的 `MAX_SCHEMA_REGION_GROUP_NUM`、`MAX_DATA_REGION_GROUP_NUM` 以及 `TTL` 属性进行修改。 **示例:** ```SQL ALTER DATABASE database1 SET PROPERTIES TTL=31536000000; +ALTER DATABASE database1 SET PROPERTIES MAX_SCHEMA_REGION_GROUP_NUM=2, MAX_DATA_REGION_GROUP_NUM=4; ``` -### 1.6 删除数据库 +### 2.6 删除数据库 用于删除数据库。 diff --git a/src/zh/UserGuide/latest-Table/Reference/System-Tables_apache.md b/src/zh/UserGuide/latest-Table/Reference/System-Tables_apache.md index cb7787393..76aa2b4d7 100644 --- a/src/zh/UserGuide/latest-Table/Reference/System-Tables_apache.md +++ b/src/zh/UserGuide/latest-Table/Reference/System-Tables_apache.md @@ -77,27 +77,29 @@ IoTDB> show tables from information_schema * 包含集群中所有数据库的信息 * 表结构如下表所示： -| 列名 | 数据类型 | 列类型 | 说明 | -| ----------------------------- | ---------- | ----------- | ---------------- | -| database | STRING | TAG | 数据库名称 | -| ttl(ms) | STRING | ATTRIBUTE | 数据保留时间 | -| schema\_replication\_factor | INT32 | ATTRIBUTE | 元数据副本数 | -| data\_replication\_factor | INT32 | ATTRIBUTE | 数据副本数 | -| time\_partition\_interval | INT64 | ATTRIBUTE | 时间分区间隔 | -| schema\_region\_group\_num | INT32 | ATTRIBUTE | 元数据分区数量 | -| data\_region\_group\_num | INT32 | ATTRIBUTE | 数据分区数量 | +| 列名 | 数据类型 | 列类型 | 说明 | +| --- | --- | --- | --- | +| database | STRING | TAG | 数据库名称 | +| ttl(ms) | STRING | ATTRIBUTE | 数据保留时间 | +| schema\_replication\_factor | INT32 | ATTRIBUTE | 元数据副本数 | +| data\_replication\_factor | INT32 | ATTRIBUTE | 数据副本数 | +| time\_partition\_interval | INT64 | ATTRIBUTE | 时间分区间隔 | +| schema\_region\_group\_num | INT32 | ATTRIBUTE | 元数据分区数量 | +| max\_schema\_region\_group\_num | INT32 | ATTRIBUTE | 可扩展最大元数据分区数量，V2.0.11 起支持 | +| data\_region\_group\_num | INT32 | ATTRIBUTE | 数据分区数量 | +| max\_data\_region\_group\_num | INT32 | ATTRIBUTE | 可扩展最大数据分区数量，V2.0.11 起支持 | * 查询结果只展示自身对该数据库本身或库中任意表有任意权限的数据库集合 * 查询示例： ```sql IoTDB> select * from information_schema.databases -+------------------+-------+-------------------------+-----------------------+-----------------------+-----------------------+---------------------+ -| database|ttl(ms)|schema_replication_factor|data_replication_factor|time_partition_interval|schema_region_group_num|data_region_group_num| -+------------------+-------+-------------------------+-----------------------+-----------------------+-----------------------+---------------------+ -|information_schema| INF| null| null| null| null| null| -| database1| INF| 1| 1| 604800000| 0| 0| -+------------------+-------+-------------------------+-----------------------+-----------------------+-----------------------+---------------------+ ++------------------+-------+-------------------------+-----------------------+-----------------------+-----------------------+---------------------------+---------------------+-------------------------+ +| database|ttl(ms)|schema_replication_factor|data_replication_factor|time_partition_interval|schema_region_group_num|max_schema_region_group_num|data_region_group_num|max_data_region_group_num| ++------------------+-------+-------------------------+-----------------------+-----------------------+-----------------------+---------------------------+---------------------+-------------------------+ +|information_schema| INF| null| null| null| null| null| null| null| +| database1| INF| 1| 1| 604800000| 1| 1| 2| 2| ++------------------+-------+-------------------------+-----------------------+-----------------------+-----------------------+---------------------------+---------------------+-------------------------+ ``` ### 2.2 TABLES 表 diff --git a/src/zh/UserGuide/latest/Basic-Concept/Operate-Metadata_apache.md b/src/zh/UserGuide/latest/Basic-Concept/Operate-Metadata_apache.md index 0b1aeadb6..85f63d844 100644 --- a/src/zh/UserGuide/latest/Basic-Concept/Operate-Metadata_apache.md +++ b/src/zh/UserGuide/latest/Basic-Concept/Operate-Metadata_apache.md @@ -277,23 +277,17 @@ show devices; 目前支持的数据库异构参数有： -| 参数名 | 参数类型 | 参数描述 | -|---------------------------|---------|---------------------------| -| TTL | Long | 数据库的 TTL | -| SCHEMA_REPLICATION_FACTOR | Integer | 数据库的元数据副本数 | -| DATA_REPLICATION_FACTOR | Integer | 数据库的数据副本数 | -| SCHEMA_REGION_GROUP_NUM | Integer | 数据库的 SchemaRegionGroup 数量 | -| DATA_REGION_GROUP_NUM | Integer | 数据库的 DataRegionGroup 数量 | - -用户在配置异构参数时需要注意以下三点： -+ TTL 和 TIME_PARTITION_INTERVAL 必须为正整数。 -+ SCHEMA_REPLICATION_FACTOR 和 DATA_REPLICATION_FACTOR 必须小于等于已部署的 DataNode 数量。 -+ SCHEMA_REGION_GROUP_NUM 和 DATA_REGION_GROUP_NUM 的功能与 iotdb-system.properties 配置文件中的 -`schema_region_group_extension_policy` 和 `data_region_group_extension_policy` 参数相关，以 DATA_REGION_GROUP_NUM 为例： -若设置 `data_region_group_extension_policy=CUSTOM`，则 DATA_REGION_GROUP_NUM 将作为 Database 拥有的 DataRegionGroup 的数量； -若设置 `data_region_group_extension_policy=AUTO`，则 DATA_REGION_GROUP_NUM 将作为 Database 拥有的 DataRegionGroup 的配额下界，即当该 Database 开始写入数据时，将至少拥有此数量的 DataRegionGroup。 - -用户可以在创建 Database 时设置任意异构参数，或在单机/分布式 IoTDB 运行时调整部分异构参数。 +| 参数名 | 参数类型 | 参数描述 | +| --- | --- | --- | +| TTL | Long | 数据库的 TTL，此值需要为正整数 | +| TIME_PARTITION_INTERVAL | Long | 数据库的时间分区间隔，此值需要为正整数 | +| MAX_SCHEMA_REGION_GROUP_NUM | Integer | 数据库自动扩展 SchemaRegionGroup 时允许达到的最大 SchemaRegionGroup 数量，此值需要为正整数 | +| MAX_DATA_REGION_GROUP_NUM | Integer | 数据库自动扩展 DataRegionGroup 时允许达到的最大 DataRegionGroup 数量，此值需要为正整数 | + +用户在配置异构参数时需要注意： + ++ 仅当 `iotdb-common.properties` 配置文件中的 `schema_region_group_extension_policy` 和 `data_region_group_extension_policy` 参数设置为 `CUSTOM` 策略时，才支持通过 SQL 在创建或修改数据库时设置或调整 schema/data region group 最大配额，即 `maxSchemaRegionGroupNum` 和 `maxDataRegionGroupNum`。 ++ `MAX_SCHEMA_REGION_GROUP_NUM` 和 `MAX_DATA_REGION_GROUP_NUM` 自 V2.0.11 版本起支持。 #### 创建 Database 时设置异构参数 @@ -305,7 +299,7 @@ CREATE DATABASE prefixPath (WITH databaseAttributeClause (COMMA? databaseAttribu 例如： ```sql -CREATE DATABASE root.db WITH SCHEMA_REPLICATION_FACTOR=1, DATA_REPLICATION_FACTOR=3, SCHEMA_REGION_GROUP_NUM=1, DATA_REGION_GROUP_NUM=2; +CREATE DATABASE root.db WITH TTL=360000, MAX_SCHEMA_REGION_GROUP_NUM=1, MAX_DATA_REGION_GROUP_NUM=2; ``` #### 运行时调整异构参数 @@ -318,12 +312,12 @@ ALTER DATABASE prefixPath WITH databaseAttributeClause (COMMA? databaseAttribute 例如： ```sql -ALTER DATABASE root.db WITH SCHEMA_REGION_GROUP_NUM=1, DATA_REGION_GROUP_NUM=2; +ALTER DATABASE root.db WITH MAX_SCHEMA_REGION_GROUP_NUM=2, MAX_DATA_REGION_GROUP_NUM=3; ``` 注意，运行时只能调整下列异构参数： -+ SCHEMA_REGION_GROUP_NUM -+ DATA_REGION_GROUP_NUM ++ MAX_SCHEMA_REGION_GROUP_NUM ++ MAX_DATA_REGION_GROUP_NUM #### 查看异构数据库 @@ -339,28 +333,22 @@ SHOW DATABASES DETAILS prefixPath? SHOW DATABASES DETAILS; ``` ```shell -+--------+--------+-----------------------+---------------------+---------------------+--------------------+-----------------------+-----------------------+------------------+---------------------+---------------------+ -|Database| TTL|SchemaReplicationFactor|DataReplicationFactor|TimePartitionInterval|SchemaRegionGroupNum|MinSchemaRegionGroupNum|MaxSchemaRegionGroupNum|DataRegionGroupNum|MinDataRegionGroupNum|MaxDataRegionGroupNum| -+--------+--------+-----------------------+---------------------+---------------------+--------------------+-----------------------+-----------------------+------------------+---------------------+---------------------+ -|root.db1| null| 1| 3| 604800000| 0| 1| 1| 0| 2| 2| -|root.db2|86400000| 1| 1| 604800000| 0| 1| 1| 0| 2| 2| -|root.db3| null| 1| 1| 604800000| 0| 1| 1| 0| 2| 2| -+--------+--------+-----------------------+---------------------+---------------------+--------------------+-----------------------+-----------------------+------------------+---------------------+---------------------+ -Total line number = 3 -It costs 0.058s ++-------------+-----------------------+---------------------+-------------------+---------------------+--------------------+-----------------------+------------------+---------------------+ +| Database|SchemaReplicationFactor|DataReplicationFactor|TimePartitionOrigin|TimePartitionInterval|SchemaRegionGroupNum|MaxSchemaRegionGroupNum|DataRegionGroupNum|MaxDataRegionGroupNum| ++-------------+-----------------------+---------------------+-------------------+---------------------+--------------------+-----------------------+------------------+---------------------+ +| root.db| 1| 1| 0| 604800000| 0| 2| 0| 3| ++-------------+-----------------------+---------------------+-------------------+---------------------+--------------------+-----------------------+------------------+---------------------+ ``` 各列查询结果依次为： + 数据库名称 -+ 数据库的 TTL + 数据库的元数据副本数 + 数据库的数据副本数 ++ 数据库的时间分区原点 + 数据库的时间分区间隔 + 数据库当前拥有的 SchemaRegionGroup 数量 -+ 数据库需要拥有的最小 SchemaRegionGroup 数量 + 数据库允许拥有的最大 SchemaRegionGroup 数量 + 数据库当前拥有的 DataRegionGroup 数量 -+ 数据库需要拥有的最小 DataRegionGroup 数量 + 数据库允许拥有的最大 DataRegionGroup 数量