doc: SQL reference guide

docs/zh/12-taos-sql/02-database.md

@@ -8,10 +8,10 @@ description: "创建、删除数据库，查看、修改数据库参数"
 
 ```sql
 CREATE DATABASE [IF NOT EXISTS] db_name [database_options]
- 
+
 database_options:
     database_option ...
- 
+
 database_option: {
     BUFFER value
   | CACHEMODEL {'none' | 'last_row' | 'last_value' | 'both'}
@@ -39,41 +39,42 @@ database_option: {
 ```
 
 ### 参数说明
-- buffer: 一个 VNODE 写入内存池大小，单位为MB，默认为96，最小为3，最大为16384。
-- CACHEMODEL：表示是否在内存中缓存子表的最近数据。默认为none。
-   - none：表示不缓存。
-   - last_row：表示缓存子表最近一行数据。这将显著改善 LAST_ROW 函数的性能表现。
-   - last_value：表示缓存子表每一列的最近的非 NULL 值。这将显著改善无特殊影响（WHERE、ORDER BY、GROUP BY、INTERVAL）下的 LAST 函数的性能表现。
-   - both：表示同时打开缓存最近行和列功能。
+
+- buffer: 一个 VNODE 写入内存池大小，单位为 MB，默认为 96，最小为 3，最大为 16384。
+- CACHEMODEL：表示是否在内存中缓存子表的最近数据。默认为 none。
+  - none：表示不缓存。
+  - last_row：表示缓存子表最近一行数据。这将显著改善 LAST_ROW 函数的性能表现。
+  - last_value：表示缓存子表每一列的最近的非 NULL 值。这将显著改善无特殊影响（WHERE、ORDER BY、GROUP BY、INTERVAL）下的 LAST 函数的性能表现。
+  - both：表示同时打开缓存最近行和列功能。
 - CACHESIZE：表示缓存子表最近数据的内存大小。默认为 1 ，范围是[1, 65536]，单位是 MB。
 - COMP：表示数据库文件压缩标志位，缺省值为 2，取值范围为 [0, 2]。
-   - 0：表示不压缩。
-   - 1：表示一阶段压缩。
-   - 2：表示两阶段压缩。
-- DURATION：数据文件存储数据的时间跨度。可以使用加单位的表示形式，如 DURATION 100h、DURATION 10d等，支持 m（分钟）、h（小时）和 d（天）三个单位。不加时间单位时默认单位为天，如 DURATION 50 表示 50 天。
-- FSYNC：当 WAL 参数设置为2时，落盘的周期。默认为3000，单位毫秒。最小为0，表示每次写入立即落盘；最大为180000，即三分钟。
-- MAXROWS：文件块中记录的最大条数，默认为4096条。
-- MINROWS：文件块中记录的最小条数，默认为100条。
-- KEEP：表示数据文件保存的天数，缺省值为 3650，取值范围 [1, 365000]，且必须大于或等于 DURATION 参数值。数据库会自动删除保存时间超过KEEP值的数据。KEEP 可以使用加单位的表示形式，如 KEEP 100h、KEEP 10d 等，支持m（分钟）、h（小时）和 d（天）三个单位。也可以不写单位，如 KEEP 50，此时默认单位为天。
-- PAGES：一个 VNODE 中元数据存储引擎的缓存页个数，默认为256，最小64。一个 VNODE 元数据存储占用 PAGESIZE * PAGES，默认情况下为1MB内存。
-- PAGESIZE：一个 VNODE 中元数据存储引擎的页大小，单位为KB，默认为4 KB。范围为1到16384，即1 KB到16 MB。
-- PRECISION：数据库的时间戳精度。ms表示毫秒，us表示微秒，ns表示纳秒，默认ms毫秒。
-- REPLICA：表示数据库副本数，取值为1或3，默认为1。在集群中使用，副本数必须小于或等于 DNODE 的数目。
-- RETENTIONS：表示数据的聚合周期和保存时长，如RETENTIONS 15s:7d,1m:21d,15m:50d表示数据原始采集周期为15秒，原始数据保存7天；按1分钟聚合的数据保存21天；按15分钟聚合的数据保存50天。目前支持且只支持三级存储周期。
-- STRICT：表示数据同步的一致性要求，默认为off。
-   - on 表示强一致，即运行标准的 raft 协议，半数提交返回成功。
-   - off表示弱一致，本地提交即返回成功。
-- WAL：WAL级别，默认为1。
-   - 1：写WAL，但不执行fsync。
-   - 2：写WAL，而且执行fsync。
-- VGROUPS：数据库中初始vgroup的数目。
+  - 0：表示不压缩。
+  - 1：表示一阶段压缩。
+  - 2：表示两阶段压缩。
+- DURATION：数据文件存储数据的时间跨度。可以使用加单位的表示形式，如 DURATION 100h、DURATION 10d 等，支持 m（分钟）、h（小时）和 d（天）三个单位。不加时间单位时默认单位为天，如 DURATION 50 表示 50 天。
+- FSYNC：当 WAL 参数设置为 2 时，落盘的周期。默认为 3000，单位毫秒。最小为 0，表示每次写入立即落盘；最大为 180000，即三分钟。
+- MAXROWS：文件块中记录的最大条数，默认为 4096 条。
+- MINROWS：文件块中记录的最小条数，默认为 100 条。
+- KEEP：表示数据文件保存的天数，缺省值为 3650，取值范围 [1, 365000]，且必须大于或等于 DURATION 参数值。数据库会自动删除保存时间超过 KEEP 值的数据。KEEP 可以使用加单位的表示形式，如 KEEP 100h、KEEP 10d 等，支持 m（分钟）、h（小时）和 d（天）三个单位。也可以不写单位，如 KEEP 50，此时默认单位为天。
+- PAGES：一个 VNODE 中元数据存储引擎的缓存页个数，默认为 256，最小 64。一个 VNODE 元数据存储占用 PAGESIZE \* PAGES，默认情况下为 1MB 内存。
+- PAGESIZE：一个 VNODE 中元数据存储引擎的页大小，单位为 KB，默认为 4 KB。范围为 1 到 16384，即 1 KB 到 16 MB。
+- PRECISION：数据库的时间戳精度。ms 表示毫秒，us 表示微秒，ns 表示纳秒，默认 ms 毫秒。
+- REPLICA：表示数据库副本数，取值为 1 或 3，默认为 1。在集群中使用，副本数必须小于或等于 DNODE 的数目。
+- RETENTIONS：表示数据的聚合周期和保存时长，如 RETENTIONS 15s:7d,1m:21d,15m:50d 表示数据原始采集周期为 15 秒，原始数据保存 7 天；按 1 分钟聚合的数据保存 21 天；按 15 分钟聚合的数据保存 50 天。目前支持且只支持三级存储周期。
+- STRICT：表示数据同步的一致性要求，默认为 off。
+  - on 表示强一致，即运行标准的 raft 协议，半数提交返回成功。
+  - off 表示弱一致，本地提交即返回成功。
+- WAL：WAL 级别，默认为 1。
+  - 1：写 WAL，但不执行 fsync。
+  - 2：写 WAL，而且执行 fsync。
+- VGROUPS：数据库中初始 vgroup 的数目。
 - SINGLE_STABLE：表示此数据库中是否只可以创建一个超级表，用于超级表列非常多的情况。
-   - 0：表示可以创建多张超级表。
-   - 1：表示只可以创建一张超级表。
-- WAL_RETENTION_PERIOD：wal文件的额外保留策略，用于数据订阅。wal的保存时长，单位为s。默认为0，即落盘后立即删除。-1表示不删除。
-- WAL_RETENTION_SIZE：wal文件的额外保留策略，用于数据订阅。wal的保存的最大上限，单位为KB。默认为0，即落盘后立即删除。-1表示不删除。
-- WAL_ROLL_PERIOD：wal文件切换时长，单位为s。当wal文件创建并写入后，经过该时间，会自动创建一个新的wal文件。默认为0，即仅在落盘时创建新文件。
-- WAL_SEGMENT_SIZE：wal单个文件大小，单位为KB。当前写入文件大小超过上限后会自动创建一个新的wal文件。默认为0，即仅在落盘时创建新文件。
+  - 0：表示可以创建多张超级表。
+  - 1：表示只可以创建一张超级表。
+- WAL_RETENTION_PERIOD：wal 文件的额外保留策略，用于数据订阅。wal 的保存时长，单位为 s。默认为 0，即落盘后立即删除。-1 表示不删除。
+- WAL_RETENTION_SIZE：wal 文件的额外保留策略，用于数据订阅。wal 的保存的最大上限，单位为 KB。默认为 0，即落盘后立即删除。-1 表示不删除。
+- WAL_ROLL_PERIOD：wal 文件切换时长，单位为 s。当 wal 文件创建并写入后，经过该时间，会自动创建一个新的 wal 文件。默认为 0，即仅在落盘时创建新文件。
+- WAL_SEGMENT_SIZE：wal 单个文件大小，单位为 KB。当前写入文件大小超过上限后会自动创建一个新的 wal 文件。默认为 0，即仅在落盘时创建新文件。
 
 ### 创建数据库示例
 
@@ -104,10 +105,10 @@ DROP DATABASE [IF EXISTS] db_name
 
 ```sql
 ALTER DATABASE db_name [alter_database_options]
- 
+
 alter_database_options:
     alter_database_option ...
- 
+
 alter_database_option: {
     CACHEMODEL {'none' | 'last_row' | 'last_value' | 'both'}
   | CACHESIZE value
@@ -118,7 +119,7 @@ alter_database_option: {
 ```
 
 :::note
-其它参数在3.0.0.0中暂不支持修改
+其它参数在 3.0.0.0 中暂不支持修改
 
 :::
 
@@ -139,3 +140,17 @@ SHOW CREATE DATABASE db_name;
 常用于数据库迁移。对一个已经存在的数据库，返回其创建语句；在另一个集群中执行该语句，就能得到一个设置完全相同的 Database。
 
 ### 查看数据库参数
+
+```sql
+SHOW DATABASES \G;
+```
+
+会列出系统中所有数据库的配置参数，并且每行只显示一个参数。
+
+## 删除过期数据
+
+```sql
+TRIM DATABASE db_name;
+```
+
+删除过期数据，并根据多级存储的配置归整数据。

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

@@ -192,5 +192,5 @@ SHOW CREATE TABLE tb_name;
 ### 获取表结构信息
 
 ```
-DESCRIBE tb_name;
+DESCRIBE [db_name.]tb_name;
 ```
\ No newline at end of file

docs/zh/12-taos-sql/04-stable.md

@@ -46,7 +46,7 @@ SHOW CREATE STABLE stb_name;
 ### 获取超级表的结构信息
 
 ```
-DESCRIBE stb_name;
+DESCRIBE [db_name.]stb_name;
 ```
 
 ## 删除超级表

docs/zh/12-taos-sql/13-tmq.md

+---
+sidebar_label: 消息队列
+title: 消息队列
+---
+
+TDengine 3.0.0.0 开始对消息队列做了大幅的优化和增强以简化用户的解决方案。
+
+## 创建订阅主题
+
+```sql
+CREATE TOPIC [IF NOT EXISTS] topic_name AS {subquery | DATABASE db_name | STABLE stb_name };
+```
+
+订阅主题包括三种：列订阅、超级表订阅和数据库订阅。
+
+**列订阅是**用 subquery 描述，支持过滤和标量函数和 UDF 标量函数，不支持 JOIN、GROUP BY、窗口切分子句、聚合函数和 UDF 聚合函数。列订阅规则如下：
+
+1. TOPIC 一旦创建则返回结果的字段确定
+2. 被订阅或用于计算的列不可被删除、修改，
+3. 列可以新增，但新增的列不出现在订阅结果字段中
+4. 对于 select \*，则订阅展开为创建时所有的列（子表、普通表为数据列，超级表为数据列加标签列）
+
+**超级表订阅和数据库订阅**规则如下：
+
+1. 被订阅主体的 schema 变更不受限
+2. 返回消息中 schema 是块级别的，每块的 schema 可能不一样
+3. 列变更后写入的数据若未落盘，将以写入时的 schema 返回
+4. 列变更后写入的数据若未已落盘，将以落盘时的 schema 返回
+
+## 删除订阅主题
+
+```sql
+DROP TOPIC [IF EXISTS] topic_name;
+```
+
+此时如果该订阅主题上存在 consumer，则此 consumer 会收到一个错误。
+
+## 查看订阅主题
+
+## SHOW TOPICS
+
+```sql
+SHOW TOPICS;
+```
+
+显示当前数据库下的所有主题的信息。
+
+## 创建消费组
+
+消费组的创建只能通过 TDengine 客户端驱动或者连接器所提供的API创建。
+
+## 删除消费组
+
+```sql
+DROP CONSUMER GROUP [IF EXISTS] cgroup_name ON topic_name;
+```
+
+删除主题 topic_name 上的消费组 cgroup_name。
+
+## 查看消费组
+
+```sql
+SHOW CONSUMERS;
+```
+
+显示当前数据库下所有活跃的消费者的信息。

docs/zh/12-taos-sql/21-node.md

+---
+sidebar_label: 集群管理
+title: 集群管理
+---
+
+组成 TDengine 集群的物理实体是 dnode (data node 的缩写)，它是一个运行在操作系统之上的进程。在 dnode 中可以建立负责时序数据存储的 vnode (virtual node)，在多节点集群环境下当某个数据库的 replica 为 3 时，该数据库中的每个 vgroup 由 3 个 vnode 组成；当数据库的 replica 为 1 时，该数据库中的每个 vgroup 由 1 个 vnode 组成。如果要想配置某个数据库为多副本，则集群中的 dnode 数量至少为 3。在 dnode 还可以创建 mnode (management node)，单个集群中最多可以创建三个 mnode。在 TDengine 3.0.0.0 中为了支持存算分离，引入了一种新的逻辑节点 qnode (query node)，qnode 和 vnode 既可以共存在一个 dnode 中，也可以完全分离在不同的 dnode 上。
+
+## 创建数据节点
+
+```sql
+CREATE DNODE {dnode_endpoint | dnode_host_name PORT port_val}
+```
+
+其中 `dnode_endpoint` 是形成 `hostname:port`的格式。也可以分开指定 hostname 和 port。
+
+实际操作中推荐先创建 dnode，再启动相应的 dnode 进程，这样该 dnode 就可以立即根据其配置文件中的 firstEP 加入集群。每个 dnode 在加入成功后都会被分配一个 ID。
+
+## 查看数据节点
+
+```sql
+SHOW DNODES;
+```
+
+可以列出集群中所有的数据节点，所列出的字段有 dnode 的 ID, endpoint, status。
+
+## 删除数据节点
+
+```sql
+DROP DNODE {dnode_id | dnode_endpoint}
+```
+
+可以用 dnoe_id 或 endpoint 两种方式从集群中删除一个 dnode。注意删除 dnode 不等于停止相应的进程。实际中推荐先将一个 dnode 删除之后再停止其所对应的进程。
+
+## 修改数据节点配置
+
+```sql
+ALTER DNODE dnode_id dnode_option
+
+ALTER ALL DNODES dnode_option
+
+dnode_option: {
+    'resetLog'
+  | 'resetQueryCache'
+  | 'balance' value
+  | 'monitor' value
+  | 'debugFlag' value
+  | 'monDebugFlag' value
+  | 'vDebugFlag' value
+  | 'mDebugFlag' value
+  | 'cDebugFlag' value
+  | 'httpDebugFlag' value
+  | 'qDebugflag' value
+  | 'sdbDebugFlag' value
+  | 'uDebugFlag' value
+  | 'tsdbDebugFlag' value
+  | 'sDebugflag' value
+  | 'rpcDebugFlag' value
+  | 'dDebugFlag' value
+  | 'mqttDebugFlag' value
+  | 'wDebugFlag' value
+  | 'tmrDebugFlag' value
+  | 'cqDebugFlag' value
+}
+```
+
+上面语法中的这些可修改配置项其配置方式与 dnode 配置文件中的配置方式相同，区别是修改是动态的立即生效，且不需要重启 dnode。
+
+## 添加管理节点
+
+```sql
+CREATE MNODE ON DNODE dnode_id
+```
+
+系统启动默认在 firstEP 节点上创建一个 MNODE，用户可以使用此语句创建更多的 MNODE 来提高系统可用性。一个集群最多存在三个 MNODE，一个 DNODE 上只能创建一个 MNODE。
+
+## 查看管理节点
+
+```sql
+SHOW MNODES;
+```
+
+列出集群中所有的管理节点，包括其 ID，所在 DNODE 以及状态。
+
+## 删除管理节点
+
+```sql
+DROP MNODE ON DNODE dnode_id;
+```
+
+删除 dnode_id 所指定的 DNODE 上的 MNODE。
+
+## 创建查询节点
+
+```sql
+CREATE QNODE ON DNODE dnode_id;
+```
+
+系统启动默认没有 QNODE，用户可以创建 QNODE 来实现计算和存储的分离。一个 DNODE 上只能创建一个 QNODE。一个 DNODE 的 `supportVnodes` 参数如果不为 0，同时又在其上创建上 QNODE，则在该 dnode 中既有负责存储管理的 vnode 又有负责查询计算的 qnode，如果还在该 dnode 上创建了 mnode，则一个 dnode 上最多三种逻辑节点都可以存在。但通过配置也可以使其彻底分离。将一个 dnode 的`supportVnodes`配置为 0，可以选择在其上创建 mnode 或者 qnode 中的一种，这样可以实现三种逻辑节点在物理上的彻底分离。
+
+## 查看查询节点
+
+```sql
+SHOW QNODES;
+```
+
+列出集群中所有查询节点，包括 ID，及所在 DNODE。
+
+## 删除查询节点
+
+```sql
+DROP QNODE ON DNODE dnode_id;
+```
+
+删除 ID 为 dnode_id 的 DNODE 上的 QNODE，但并不会影响该 dnode 的状态。
+
+## 修改客户端配置
+
+如果将客户端也看作广义的集群的一部分，可以通过如下命令动态修改客户端配置参数。
+
+```sql
+ALTER LOCAL local_option
+
+local_option: {
+    'resetLog'
+  | 'rpcDebugFlag' value
+  | 'tmrDebugFlag' value
+  | 'cDebugFlag' value
+  | 'uDebugFlag' value
+  | 'debugFlag' value
+}
+```
+
+上面语法中的参数与在配置文件中配置客户端的用法相同，但不需要重启客户端，修改后立即生效。
+
+## 查看客户端配置
+
+```sql
+SHOW LOCAL VARIABLES;
+```
+
+## 合并 vgroup
+
+```sql
+MERGE VGROUP vgroup_no1 vgroup_no2;
+```
+
+如果在系统实际运行一段时间后，因为不同时间线的数据特征不同导致在 vgroups 之间的数据和负载分布不均衡，可以通过合并或拆分 vgroups 的方式逐步实现负载均衡。
+
+## 拆分 vgroup
+
+```sql
+SPLIT VGROUP vgroup_no;
+```
+
+会创建一个新的 vgroup，并将指定 vgroup 中的数据按照一致性 HASH 迁移一部分到新的 vgroup 中。此过程中，原 vgroup 可以正常提供读写服务。

docs/zh/12-taos-sql/25-grant.md

@@ -23,6 +23,23 @@ password最长为128字节，合法字符包括"a-zA-Z0-9!?$%^&*()_–+={[}]:;@~
 DROP USER user_name;
 ```
 
+## 修改用户信息
+
+```sql
+ALTER USER user_name alter_user_clause
+ 
+alter_user_clause: {
+    PASS 'literal'
+  | ENABLE value
+  | SYSINFO value
+}
+```
+
+- PASS：修改用户密码。
+- ENABLE：修改用户是否启用。1表示启用此用户，0表示禁用此用户。
+- SYSINFO：修改用户是否可查看系统信息。1表示可以查看系统信息，0表示不可以查看系统信息。
+
+
 ## 授权
 
 ```sql

docs/zh/12-taos-sql/26-udf.md

+---
+sidebar_label: 自定义函数
+title: 用户自定义函数
+---
+
+除了 TDengine 的内置函数以外，用户还可以编写自己的函数逻辑并加入TDengine系统中。
+
+## 创建函数
+
+```sql
+CREATE [AGGREGATE] FUNCTION func_name AS library_path OUTPUTTYPE type_name [BUFSIZE value]
+```
+
+语法说明：
+
+AGGREGATE：标识此函数是标量函数还是聚集函数。
+func_name：函数名，必须与函数实现中udfNormalFunc的实际名称一致。
+library_path：包含UDF函数实现的动态链接库的绝对路径，是在客户端侧主机上的绝对路径。
+OUTPUTTYPE：标识此函数的返回类型。
+BUFSIZE：中间结果的缓冲区大小，单位是字节。不设置则默认为0。最大不可超过512字节。
+
+关于如何开发自定义函数，请参考 [UDF使用说明](../develop/udf)。
+
+## 删除自定义函数
+
+```sql
+DROP FUNCTION func_name
+```
\ No newline at end of file

docs/zh/12-taos-sql/27-index.md

+---
+sidebar_label: 索引
+title: 使用索引
+---
+
+TDengine 从 3.0.0.0 版本开始引入了索引功能，支持 SMA 索引和 FULLTEXT 索引。
+
+## 创建索引
+
+```sql
+CREATE FULLTEXT INDEX index_name ON tb_name (col_name [, col_name] ...)
+
+CREATE SMA INDEX index_name ON tb_name index_option
+
+index_option:
+    FUNCTION(functions) INTERVAL(interval_val [, interval_offset]) [SLIDING(sliding_val)] [WATERMARK(watermark_val)] [MAX_DELAY(max_delay_val)]
+
+functions:
+    function [, function] ...
+```
+
+### SMA 索引
+
+对指定列按 INTERVAL 子句定义的时间窗口创建进行预聚合计算，预聚合计算类型由 functions_string 指定。SMA 索引能提升指定时间段的聚合查询的性能。目前，限制一个超级表只能创建一个 SMA INDEX。
+
+- 支持的函数包括 MAX、MIN 和 SUM。
+- WATERMARK: 最小单位毫秒，取值范围 [0ms, 900000ms]，默认值为 5 秒，只可用于超级表。
+- MAX_DELAY: 最小单位毫秒，取值范围 [1ms, 900000ms]，默认值为 interval 的值(但不能超过最大值)，只可用于超级表。注：不建议 MAX_DELAY 设置太小，否则会过于频繁的推送结果，影响存储和查询性能，如无特殊需求，取默认值即可。
+
+### FULLTEXT 索引
+
+对指定列建立文本索引，可以提升含有文本过滤的查询的性能。FULLTEXT 索引不支持 index_option 语法。现阶段只支持对 JSON 类型的标签列创建 FULLTEXT 索引。不支持多列联合索引，但可以为每个列分布创建 FULLTEXT 索引。
+
+## 删除索引
+
+```sql
+DROP INDEX index_name;
+```
+
+## 查看索引
+
+````sql
+```sql
+SHOW INDEXES FROM tbl_name [FROM db_name];
+````
+
+显示在所指定的数据库或表上已创建的索引。

docs/zh/12-taos-sql/28-recovery.md

+---
+sidebar_label: 异常恢复
+title: 异常恢复
+---
+
+在一个复杂的应用场景中，连接和查询任务等有可能进入一种错误状态或者耗时过长迟迟无法结束，此时需要有能够终止这些连接或任务的方法。
+
+## 终止连接
+
+```sql
+KILL CONNECTION conn_id;
+```
+
+conn_id 可以通过 `SHOW CONNECTIONS` 获取。
+
+## 终止查询
+
+```sql
+SHOW QUERY query_id;
+```
+
+query_id 可以通过 `SHOW QUERIES` 获取。
+
+## 终止事务
+
+```sql
+KILL TRANSACTION trans_id
+```
+
+trans_id 可以通过 `SHOW TRANSACTIONS` 获取。
+
+## 重置客户端缓存
+
+```sql
+RESET QUERY CACHE;
+```
+
+如果在多客户端情况下出现元数据不同步的情况，可以用这条命令强制清空客户端缓存，随后客户端会从服务端拉取最新的元数据。