This is an automated email from the ASF dual-hosted git repository.
qiaojialin pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/iotdb.git
The following commit(s) were added to refs/heads/master by this push:
new 94ca2b54bef [IOTDB-6018] Heterogeneous Database document (#10258)
94ca2b54bef is described below
commit 94ca2b54bef78242e1b1184d894dbbfce7bc1110
Author: YongzaoDan <[email protected]>
AuthorDate: Thu Jun 22 21:41:46 2023 +0800
[IOTDB-6018] Heterogeneous Database document (#10258)
---
docs/UserGuide/Operate-Metadata/Database.md | 90 ++++++++++++++++++++++++++
docs/zh/UserGuide/Operate-Metadata/Database.md | 90 ++++++++++++++++++++++++++
2 files changed, 180 insertions(+)
diff --git a/docs/UserGuide/Operate-Metadata/Database.md
b/docs/UserGuide/Operate-Metadata/Database.md
index 029cb7b63b3..36062d4eafe 100644
--- a/docs/UserGuide/Operate-Metadata/Database.md
+++ b/docs/UserGuide/Operate-Metadata/Database.md
@@ -135,3 +135,93 @@ It costs 0.002s
Total line number = 1
It costs 0.002s
```
+
+### 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-common.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:
+
+```
+CREATE DATABASE prefixPath (WITH databaseAttributeClause (COMMA?
databaseAttributeClause)*)?
+```
+
+For example:
+```
+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:
+
+```
+ALTER DATABASE prefixPath WITH databaseAttributeClause (COMMA?
databaseAttributeClause)*
+```
+
+For example:
+```
+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:
+
+```
+SHOW DATABASES DETAILS prefixPath?
+```
+
+For example:
+
+```
+IoTDB> 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
\ No newline at end of file
diff --git a/docs/zh/UserGuide/Operate-Metadata/Database.md
b/docs/zh/UserGuide/Operate-Metadata/Database.md
index 75ea79cf22e..3b8642872b7 100644
--- a/docs/zh/UserGuide/Operate-Metadata/Database.md
+++ b/docs/zh/UserGuide/Operate-Metadata/Database.md
@@ -135,3 +135,93 @@ It costs 0.002s
Total line number = 1
It costs 0.002s
```
+
+### 设置异构数据库（进阶操作）
+
+在熟悉 IoTDB 元数据建模的前提下，用户可以在 IoTDB 中设置异构的数据库，以便应对不同的生产需求。
+
+目前支持的数据库异构参数有：
+
+| 参数名 | 参数类型 | 参数描述 |
+|---------------------------|---------|---------------------------|
+| 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-common.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 运行时调整部分异构参数。
+
+#### 创建 Database 时设置异构参数
+
+用户可以在创建 Database 时设置上述任意异构参数，SQL 语句如下所示：
+
+```
+CREATE DATABASE prefixPath (WITH databaseAttributeClause (COMMA?
databaseAttributeClause)*)?
+```
+
+例如：
+```
+CREATE DATABASE root.db WITH SCHEMA_REPLICATION_FACTOR=1,
DATA_REPLICATION_FACTOR=3, SCHEMA_REGION_GROUP_NUM=1, DATA_REGION_GROUP_NUM=2;
+```
+
+#### 运行时调整异构参数
+
+用户可以在 IoTDB 运行时调整部分异构参数，SQL 语句如下所示：
+
+```
+ALTER DATABASE prefixPath WITH databaseAttributeClause (COMMA?
databaseAttributeClause)*
+```
+
+例如：
+```
+ALTER DATABASE root.db WITH SCHEMA_REGION_GROUP_NUM=1, DATA_REGION_GROUP_NUM=2;
+```
+
+注意，运行时只能调整下列异构参数：
++ SCHEMA_REGION_GROUP_NUM
++ DATA_REGION_GROUP_NUM
+
+#### 查看异构数据库
+
+用户可以查询每个 Database 的具体异构配置，SQL 语句如下所示：
+
+```
+SHOW DATABASES DETAILS prefixPath?
+```
+
+例如：
+
+```
+IoTDB> 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
+```
+
+各列查询结果依次为：
++ 数据库名称
++ 数据库的 TTL
++ 数据库的元数据副本数
++ 数据库的数据副本数
++ 数据库的时间分区间隔
++ 数据库当前拥有的 SchemaRegionGroup 数量
++ 数据库需要拥有的最小 SchemaRegionGroup 数量
++ 数据库允许拥有的最大 SchemaRegionGroup 数量
++ 数据库当前拥有的 DataRegionGroup 数量
++ 数据库需要拥有的最小 DataRegionGroup 数量
++ 数据库允许拥有的最大 DataRegionGroup 数量
\ No newline at end of file
