Skip to content

docs: update V2.0.11 database region group details #1203

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
leto-bbq wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: update V2.0.11 database region group details #1203

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
138 changes: 86 additions & 52 deletions src/UserGuide/Master/Table/Basic-Concept/Database-Management_apache.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,60 +21,90 @@

# 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 <DATABASE_NAME>`.

### 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)? <DATABASE_NAME> (WITH properties)?
CREATE DATABASE (IF NOT EXISTS)? <DATABASE_NAME> (WITH properties)?
```

**Note: **
**Description:**

1. `<DATABASE_NAME>`: 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. `<DATABASE_NAME>` 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:**

```SQL
USE <DATABASE_NAME>
```

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

Expand All @@ -88,6 +118,7 @@ SHOW CURRENT_DATABASE
USE database1;
SHOW CURRENT_DATABASE;
```

```shell
+---------------+
|CurrentDatabase|
Expand All @@ -96,8 +127,7 @@ SHOW CURRENT_DATABASE;
+---------------+
```


### 1.4 View All Databases
### 2.4 View All Databases

Displays all databases and their properties.

Expand All @@ -107,66 +137,70 @@ 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:**

```SQL
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:**

```SQL
DROP DATABASE (IF EXISTS)? <DATABASE_NAME>
```

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

Expand Down
32 changes: 17 additions & 15 deletions src/UserGuide/Master/Table/Reference/System-Tables_apache.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading