Merge pull request #26175 from taosdata/doc/TS-5019-3.0

docs: add ttl/comment spec for 'alter table'

docs/en/12-taos-sql/03-table.md

@@ -25,7 +25,7 @@ create_definition:
     col_name column_definition
 
 column_definition:
-    type_name [comment 'string_value'] [PRIMARY KEY] [ENCODE 'encode_type'] [COMPRESS 'compress_type'] [LEVEL 'level_type'] 
+    type_name [comment 'string_value'] [PRIMARY KEY] [ENCODE 'encode_type'] [COMPRESS 'compress_type'] [LEVEL 'level_type']
 
 table_options:
     table_option ...
@@ -52,9 +52,9 @@ table_option: {
 
 **Parameter description**
 
-1. COMMENT: specifies comments for the table. This parameter can be used with supertables, standard tables, and subtables.
+1. COMMENT: specifies comments for the table. This parameter can be used with supertables, standard tables, and subtables. The maximum length of the comment is 1024 bytes.
 2. SMA: specifies functions on which to enable small materialized aggregates (SMA). SMA is user-defined precomputation of aggregates based on data blocks. Enter one of the following values: max, min, or sum This parameter can be used with supertables and standard tables.
-3. TTL: specifies the time to live (TTL) for the table. If TTL is specified when creatinga table, after the time period for which the table has been existing is over TTL, TDengine will automatically delete the table. Please be noted that the system may not delete the table at the exact moment that the TTL expires but guarantee there is such a system and finally the table will be deleted. The unit of TTL is in days. The default value is 0, i.e. never expire.
+3. TTL: specifies the time to live (TTL) for the table. If TTL is specified when creatinga table, after the time period for which the table has been existing is over TTL, TDengine will automatically delete the table. Please be noted that the system may not delete the table at the exact moment that the TTL expires but guarantee there is such a system and finally the table will be deleted. The unit of TTL is in days. The value range is [0, 2147483647]. The default value is 0, i.e. never expire.
 
 ## Create Subtables
 
@@ -112,6 +112,11 @@ You can perform the following modifications on existing tables:
 4. RENAME COLUMN: renames a specified column in the table.
 5. The primary key column of a table cannot be modified or added or deleted using ADD/DROP COLUMN.
 
+**Parameter description**
+
+1. COMMENT: specifies comments for the table. This parameter can be used with supertables, standard tables, and subtables. The maximum length of the comment is 1024 bytes.
+2. TTL: specifies the time to live (TTL) for the table. If TTL is specified when creatinga table, after the time period for which the table has been existing is over TTL, TDengine will automatically delete the table. Please be noted that the system may not delete the table at the exact moment that the TTL expires but guarantee there is such a system and finally the table will be deleted. The unit of TTL is in days. The value range is [0, 2147483647]. The default value is 0, i.e. never expire.
+
 ### Add a Column
 
 ```sql
@@ -136,6 +141,18 @@ ALTER TABLE tb_name MODIFY COLUMN field_name data_type(length);
 ALTER TABLE tb_name RENAME COLUMN old_col_name new_col_name
 ```
 
+### Alter Table TTL
+
+```sql
+ALTER TABLE tb_name TTL value
+```
+
+### Alter Table Comment
+
+```sql
+ALTER TABLE tb_name COMMENT 'string_value'
+```
+
 ## Modify a Subtable
 
 ```sql
@@ -159,12 +176,29 @@ alter_table_option: {
 
 1. Only the value of a tag can be modified directly. For all other modifications, you must modify the supertable from which the subtable was created.
 
+**Parameter description**
+
+1. COMMENT: specifies comments for the table. This parameter can be used with supertables, standard tables, and subtables. The maximum length of the comment is 1024 bytes.
+2. TTL: specifies the time to live (TTL) for the table. If TTL is specified when creatinga table, after the time period for which the table has been existing is over TTL, TDengine will automatically delete the table. Please be noted that the system may not delete the table at the exact moment that the TTL expires but guarantee there is such a system and finally the table will be deleted. The unit of TTL is in days. The value range is [0, 2147483647]. The default value is 0, i.e. never expire.
+
 ### Change Tag Value Of Sub Table
 
 ```
 ALTER TABLE tb_name SET TAG tag_name=new_tag_value;
 ```
 
+### Alter Table TTL
+
+```sql
+ALTER TABLE tb_name TTL value
+```
+
+### Alter Table Comment
+
+```sql
+ALTER TABLE tb_name COMMENT 'string_value'
+```
+
 ## Delete a Table
 
 The following SQL statement deletes one or more tables.

docs/zh/12-taos-sql/03-table.md

@@ -23,10 +23,10 @@ create_subtable_clause: {
 }
 
 create_definition:
-    col_name column_definition 
+    col_name column_definition
 
 column_definition:
-    type_name [comment 'string_value'] [PRIMARY KEY] [ENCODE 'encode_type'] [COMPRESS 'compress_type'] [LEVEL 'level_type'] 
+    type_name [comment 'string_value'] [PRIMARY KEY] [ENCODE 'encode_type'] [COMPRESS 'compress_type'] [LEVEL 'level_type']
 
 table_options:
     table_option ...
@@ -52,9 +52,9 @@ table_option: {
 
 **参数说明**
 
-1. COMMENT：表注释。可用于超级表、子表和普通表。
+1. COMMENT：表注释。可用于超级表、子表和普通表。最大长度为 1024 个字节。
 2. SMA：Small Materialized Aggregates，提供基于数据块的自定义预计算功能。预计算类型包括 MAX、MIN 和 SUM。可用于超级表/普通表。
-3. TTL：Time to Live，是用户用来指定表的生命周期的参数。如果创建表时指定了这个参数，当该表的存在时间超过 TTL 指定的时间后，TDengine 自动删除该表。这个 TTL 的时间只是一个大概时间，系统不保证到了时间一定会将其删除，而只保证存在这样一个机制且最终一定会删除。TTL 单位是天，默认为 0，表示不限制，到期时间为表创建时间加上 TTL 时间。TTL 与数据库 KEEP 参数没有关联，如果 KEEP 比 TTL 小，在表被删除之前数据也可能已经被删除。
+3. TTL：Time to Live，是用户用来指定表的生命周期的参数。如果创建表时指定了这个参数，当该表的存在时间超过 TTL 指定的时间后，TDengine 自动删除该表。这个 TTL 的时间只是一个大概时间，系统不保证到了时间一定会将其删除，而只保证存在这样一个机制且最终一定会删除。TTL 单位是天，取值范围为[0, 2147483647]，默认为 0，表示不限制，到期时间为表创建时间加上 TTL 时间。TTL 与数据库 KEEP 参数没有关联，如果 KEEP 比 TTL 小，在表被删除之前数据也可能已经被删除。
 
 ## 创建子表
 
@@ -112,6 +112,11 @@ alter_table_option: {
 4. RENAME COLUMN：修改列名称。
 5. 普通表的主键列不能被修改，也不能通过 ADD/DROP COLUMN 来添加/删除主键列。
 
+**参数说明**
+
+1. COMMENT：表注释。可用于超级表、子表和普通表。最大长度为 1024 个字节。
+2. TTL：Time to Live，是用户用来指定表的生命周期的参数。如果创建表时指定了这个参数，当该表的存在时间超过 TTL 指定的时间后，TDengine 自动删除该表。这个 TTL 的时间只是一个大概时间，系统不保证到了时间一定会将其删除，而只保证存在这样一个机制且最终一定会删除。TTL 单位是天，取值范围为[0, 2147483647]，默认为 0，表示不限制，到期时间为表创建时间加上 TTL 时间。TTL 与数据库 KEEP 参数没有关联，如果 KEEP 比 TTL 小，在表被删除之前数据也可能已经被删除。
+
 ### 增加列
 
 ```sql
@@ -136,6 +141,18 @@ ALTER TABLE tb_name MODIFY COLUMN field_name data_type(length);
 ALTER TABLE tb_name RENAME COLUMN old_col_name new_col_name
 ```
 
+### 修改表生命周期
+
+```sql
+ALTER TABLE tb_name TTL value
+```
+
+### 修改表注释
+
+```sql
+ALTER TABLE tb_name COMMENT 'string_value'
+```
+
 ## 修改子表
 
 ```sql
@@ -159,12 +176,29 @@ alter_table_option: {
 
 1. 对子表的列和标签的修改，除了更改标签值以外，都要通过超级表才能进行。
 
+**参数说明**
+
+1. COMMENT：表注释。可用于超级表、子表和普通表。最大长度为 1024 个字节。
+2. TTL：Time to Live，是用户用来指定表的生命周期的参数。如果创建表时指定了这个参数，当该表的存在时间超过 TTL 指定的时间后，TDengine 自动删除该表。这个 TTL 的时间只是一个大概时间，系统不保证到了时间一定会将其删除，而只保证存在这样一个机制且最终一定会删除。TTL 单位是天，取值范围为[0, 2147483647]，默认为 0，表示不限制，到期时间为表创建时间加上 TTL 时间。TTL 与数据库 KEEP 参数没有关联，如果 KEEP 比 TTL 小，在表被删除之前数据也可能已经被删除。
+
 ### 修改子表标签值
 
 ```
 ALTER TABLE tb_name SET TAG tag_name=new_tag_value;
 ```
 
+### 修改表生命周期
+
+```sql
+ALTER TABLE tb_name TTL value
+```
+
+### 修改表注释
+
+```sql
+ALTER TABLE tb_name COMMENT 'string_value'
+```
+
 ## 删除表
 
 可以在一条 SQL 语句中删除一个或多个普通表或子表。