Skip to content

docs: document last cache configuration for V2.0.12 #1243

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
+390 −214
Open

docs: document last cache configuration for V2.0.12 #1243

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
21 changes: 14 additions & 7 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 @@ -74,12 +74,15 @@ CREATE DATABASE (IF NOT EXISTS)? <DATABASE_NAME> (WITH properties)?
| `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` |
| `NEED_LAST_CACHE` | Whether the last cache needs to be actively maintained. Valid values are `true` and `false`: `true` maintains the last cache according to the existing policy; `false` means that the object does not actively require the last cache. | `true` |

**Notes:**

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

- `NEED_LAST_CACHE` is supported since V2.0.12. When set to `false`, tables/views subsequently created in this database without an explicit `need_last_cache` setting do not actively require the last cache by default.

**Example:**

```SQL
Expand Down Expand Up @@ -150,6 +153,7 @@ SHOW DATABASES (DETAILS)?
| 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. |
| NeedLastCache | Returned when using `DETAILS`, showing the database-level default for the last cache. The value is `true` if not explicitly configured. Supported since V2.0.12. |

**Example:**

Expand All @@ -158,12 +162,12 @@ SHOW DATABASES DETAILS;
```

```shell
+------------------+-------+-----------------------+---------------------+---------------------+--------------------+-----------------------+------------------+---------------------+
| 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|
+------------------+-------+-----------------------+---------------------+---------------------+--------------------+-----------------------+------------------+---------------------+
+------------------+-------+-----------------------+---------------------+---------------------+--------------------+-----------------------+------------------+---------------------+-------------+
| Database|TTL(ms)|SchemaReplicationFactor|DataReplicationFactor|TimePartitionInterval|SchemaRegionGroupNum|MaxSchemaRegionGroupNum|DataRegionGroupNum|MaxDataRegionGroupNum|NeedLastCache|
+------------------+-------+-----------------------+---------------------+---------------------+--------------------+-----------------------+------------------+---------------------+-------------+
| database1| INF| 1| 1| 604800000| 1| 1| 2| 2| true|
|information_schema| INF| null| null| null| null| null| null| null| false|
+------------------+-------+-----------------------+---------------------+---------------------+--------------------+-----------------------+------------------+---------------------+-------------+
```

### 2.5 Count Databases
Expand Down Expand Up @@ -199,15 +203,18 @@ ALTER DATABASE (IF EXISTS)? database=identifier SET PROPERTIES propertyAssignmen

**Description:**

1. `ALTER DATABASE` currently supports modifying only `MAX_SCHEMA_REGION_GROUP_NUM`, `MAX_DATA_REGION_GROUP_NUM`, and `TTL`.
1. The `ALTER DATABASE` operation currently supports modifications to the database's `MAX_SCHEMA_REGION_GROUP_NUM`, `MAX_DATA_REGION_GROUP_NUM`, `TTL`, and `NEED_LAST_CACHE` (supported since V2.0.12) properties.

**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;
ALTER DATABASE database1 SET PROPERTIES need_last_cache=false;
```

`ALTER DATABASE ... SET PROPERTIES need_last_cache=DEFAULT` restores the database-level default value of `true`.

### 2.7 Delete a Database

Deletes a database.
Expand Down
36 changes: 24 additions & 12 deletions src/UserGuide/Master/Table/Basic-Concept/Table-Management_apache.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,6 +125,7 @@ comment
```
6. columnDefinition column names have the same characteristics as table names and can include the special character `.`.
7. COMMENT adds a comment to the table.
8. Starting from V2.0.12, the Boolean property `need_last_cache` specifies whether the table actively maintains the last cache. Valid values are `true` and `false`. If explicitly specified when creating the table, the table-level setting is used; otherwise, the table inherits the database's `need_last_cache` setting at the time of creation.

**Examples:**

Expand Down Expand Up @@ -164,17 +165,19 @@ SHOW TABLES (DETAILS)? ((FROM | IN) database_name)?
2. `PRE_CREATE`: The table is in the process of being created or the creation has failed; the table is not available.
3. `PRE_DELETE`: The table is in the process of being deleted or the deletion has failed; the table will remain permanently unavailable.

Starting from V2.0.12, the result set of `SHOW TABLES DETAILS` includes the `NeedLastCache` column.

**Examples:**

```sql
show tables details from database1;
```
```shell
+---------------+-----------+------+-------+
| TableName| TTL(ms)|Status|Comment|
+---------------+-----------+------+-------+
| table1|31536000000| USING| table1|
+---------------+-----------+------+-------+
+---------------+-----------+------+-------+----------+-------------+
| TableName| TTL(ms)|Status|Comment| TableType|NeedLastCache|
+---------------+-----------+------+-------+----------+-------------+
| table1|31536000000| USING| table1|BASE TABLE| true|
+---------------+-----------+------+-------+----------+-------------+
```

### 2.3 View Table Columns
Expand Down Expand Up @@ -232,18 +235,19 @@ SHOW CREATE TABLE <TABLE_NAME>
**Note:：**

1. This statement does not support queries on system tables.
2. Starting from V2.0.12, the returned table creation statement includes the `need_last_cache` property.

**Example:**

```SQL
show create table table1;
```
```shell
+------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Table| Create Table|
+------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|table1|CREATE TABLE "table1" ("region" STRING TAG,"plant_id" STRING TAG,"device_id" STRING TAG,"model_id" STRING ATTRIBUTE,"maintenance" STRING ATTRIBUTE,"temperature" FLOAT FIELD,"humidity" FLOAT FIELD,"status" BOOLEAN FIELD,"arrival_time" TIMESTAMP FIELD) WITH (ttl=31536000000)|
+------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Table| Create Table|
+------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|table1|CREATE TABLE "table1" ("region" STRING TAG,"plant_id" STRING TAG,"device_id" STRING TAG,"model_id" STRING ATTRIBUTE,"maintenance" STRING ATTRIBUTE,"temperature" FLOAT FIELD,"humidity" FLOAT FIELD,"status" BOOLEAN FIELD,"arrival_time" TIMESTAMP FIELD) WITH (ttl=31536000000, need_last_cache=true)|
+------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
```


Expand All @@ -259,15 +263,15 @@ ALTER TABLE (IF EXISTS)? tableName=qualifiedName ADD COLUMN (IF NOT EXISTS)? col
#dropColumn;
| ALTER TABLE (IF EXISTS)? tableName=qualifiedName DROP COLUMN (IF EXISTS)? column=identifier;
#setTableProperties;
// set TTL can use this;
// set TTL or need_last_cache can use this;
| ALTER TABLE (IF EXISTS)? tableName=qualifiedName SET PROPERTIES propertyAssignments;
| COMMENT ON TABLE tableName=qualifiedName IS 'table_comment';
| COMMENT ON COLUMN tableName.column IS 'column_comment';
```

**Note:：**

1. The `SET PROPERTIES` operation currently only supports configuring the `TTL` property of a table
1. The `SET PROPERTIES` operation supports configuring the `TTL` property of a table. Starting from V2.0.12, it also supports the `need_last_cache` property.
2. The delete column function only supports deleting the ATTRIBUTE and FILD columns, and the TAG column does not support deletion.
3. The modified comment will overwrite the original comment. If null is specified, the previous comment will be erased.

Expand All @@ -288,6 +292,14 @@ COMMENT ON TABLE table1 IS 'table1';
COMMENT ON COLUMN table1.a IS null;
```

Set `need_last_cache` for table1

```SQL
ALTER TABLE table1 SET PROPERTIES need_last_cache=false;
```

Note: `ALTER TABLE ... SET PROPERTIES need_last_cache=DEFAULT` restores the database default semantics. If `need_last_cache` is explicitly configured for the database, the table uses that database-level value; otherwise, the table uses the default value `true`.

### 2.6 Delete Tables

Used to delete a table.
Expand Down
Loading