Merge pull request #11441 from taosdata/docs/dingbo/TD-14075

docs: add introduction to schemaless protocols

docs-cn/06-insert-data/01-sql-writing.mdx

@@ -19,27 +19,34 @@ import CsStmt from "./_cs_stmt.mdx";
 import CSQL from "./_c_sql.mdx";
 import CStmt from "./_c_stmt.mdx";
 
-## SQL 写入
+## SQL 写入简介
 
-应用通过连接器执行 insert 语句来插入数据，用户还可以通过 TAOS Shell，手动输入 insert 语句插入数据。比如下面这条 insert 就将一条记录写入到表 d1001 中：
+应用通过连接器执行 INSERT 语句来插入数据，用户还可以通过 TAOS Shell，手动输入 INSERT 语句插入数据。
+
+### 一次写入一条
+下面这条 INSERT 就将一条记录写入到表 d1001 中：
 
 ```sql
 INSERT INTO d1001 VALUES (1538548685000, 10.3, 219, 0.31);
 ```
 
+### 一次写入多条
+
 TDengine 支持一次写入多条记录，比如下面这条命令就将两条记录写入到表 d1001 中：
 
 ```sql
 INSERT INTO d1001 VALUES (1538548684000, 10.2, 220, 0.23) (1538548696650, 10.3, 218, 0.25);
 ```
 
+### 一次写入多表
+
 TDengine 也支持一次向多个表写入数据，比如下面这条命令就向 d1001 写入两条记录，向 d1002 写入一条记录：
 
 ```sql
 INSERT INTO d1001 VALUES (1538548685000, 10.3, 219, 0.31) (1538548695000, 12.6, 218, 0.33) d1002 VALUES (1538548696800, 12.3, 221, 0.31);
 ```
 
-详细的 SQL INSERT 语法规则请见 [TAOS SQL 的数据写入](/reference/taos-sql/insert) 章节。
+详细的 SQL INSERT 语法规则参考 [TAOS SQL 的数据写入](/reference/taos-sql/insert)。
 
 :::info
 

docs-cn/06-insert-data/02-influxdb-line.mdx

 ---
-sidebar_label: InfluxDB Line 协议
-title: InfluxDB Line 协议
+sidebar_label: InfluxDB 行协议
+title: InfluxDB 行协议
 ---
 
 import Tabs from "@theme/Tabs";
@@ -13,7 +13,35 @@ import NodeLine from "./_js_line.mdx";
 import CsLine from "./_cs_line.mdx";
 import CLine from "./_c_line.mdx";
 
-## InfluxDB Line 协议介绍
+## 协议介绍
+
+InfluxDB Line 协议采用一行字符串来表示一行数据。分为四部分：
+
+```
+measurement,tag_set field_set timestamp
+```
+
+- measurement 将作为超级表名。它与 tag_set 之间使用一个英文逗号来分隔。
+- tag_set 将作为标签数据，其格式形如 `<tag_key>=<tag_value>,<tag_key>=<tag_value>`，也即可以使用英文逗号来分隔多个标签数据。它与 field_set 之间使用一个半角空格来分隔。
+- field_set 将作为普通列数据，其格式形如 `<field_key>=<field_value>,<field_key>=<field_value>`，同样是使用英文逗号来分隔多个普通列的数据。它与 timestamp 之间使用一个半角空格来分隔。
+- timestamp 即本行数据对应的主键时间戳。
+
+例如：
+
+```
+meters,location=Beijing.Haidian,groupid=2 current=13.4,voltage=223,phase=0.29 1648432611249500
+```
+
+:::note
+
+- tag_set 中的所有的数据自动转化为 nchar 数据类型;
+- field_set 中的每个数据项都需要对自身的数据类型进行描述, 比如 1.2f32 代表 float 类型的数值 1.2, 如果不带类型后缀会被当作 double 处理;
+- timestamp 支持多种时间精度。写入数据的时候需要用参数指定时间精度，支持从小时到纳秒的 6 种时间精度。
+
+:::
+
+要了解更多可参考：[InfluxDB Line 协议官方文档](https://docs.influxdata.com/influxdb/v2.0/reference/syntax/line-protocol/) 和 [TDengine 无模式写入参考指南](/reference/schemaless/#无模式写入行协议)
+
 
 ## 示例代码
 

docs-cn/06-insert-data/03-opentsdb-telnet.mdx

 ---
-sidebar_label: OpentsDB Telnet 协议
-title: OpentsDB Telnet 协议
+sidebar_label: OpentsDB 行协议
+title: OpentsDB 行协议
 ---
 
 import Tabs from "@theme/Tabs";
@@ -13,6 +13,27 @@ import NodeTelnet from "./_js_opts_telnet.mdx";
 import CsTelnet from "./_cs_opts_telnet.mdx";
 import CTelnet from "./_c_opts_telnet.mdx";
 
+## 协议介绍
+
+OpentsDB 行协议同样采用一行字符串来表示一行数据。OpentsDB 采用的是单列模型，因此一行只能包含一个普通数据列。标签列依然可以有多个。分为四部分，具体格式约定如下：
+
+```txt
+<metric> <timestamp> <value> <tagk_1>=<tagv_1>[ <tagk_n>=<tagv_n>]
+```
+
+- metric 将作为超级表名。
+- timestamp 本行数据对应的时间戳。根据时间戳的长度自动识别时间精度。支持秒和毫秒两种时间精度
+- value 度量值，必须为一个数值。对应的列名也是 “value”。
+- 最后一部分是标签集， 用空格分隔不同标签。
+
+例如：
+
+```txt
+meters.current 1648432611250 11.3 location=Beijing.Haidian groupid=3
+```
+
+参考[OpenTSDB Telnet API文档](http://opentsdb.net/docs/build/html/api_telnet/put.html)。
+
 ## 示例代码
 
 <Tabs defaultValue="java" groupId="lang">

docs-cn/06-insert-data/04-opentsdb-json.mdx

@@ -13,6 +13,42 @@ import NodeJson from "./_js_opts_json.mdx";
 import CsJson from "./_cs_opts_json.mdx";
 import CJson from "./_c_opts_json.mdx";
 
+## 协议介绍
+
+OpentsDB JSON 格式协议采用一个 JSON 字符串表示一行或多行数据。例如：
+
+```json
+[
+    {
+        "metric": "sys.cpu.nice",
+        "timestamp": 1346846400,
+        "value": 18,
+        "tags": {
+           "host": "web01",
+           "dc": "lga"
+        }
+    },
+    {
+        "metric": "sys.cpu.nice",
+        "timestamp": 1346846400,
+        "value": 9,
+        "tags": {
+           "host": "web02",
+           "dc": "lga"
+        }
+    }
+]
+```
+
+与 OpentsDB 行协议类似， metric 将作为超级表名， timestamp 表示时间戳，value 表示度量值， tags 表示标签集。
+
+参考[OpenTSDB HTTP API文档](http://opentsdb.net/docs/build/html/api_http/put.html)。
+
+:::note
+TDengine 只接收 JSON **数组格式**的字符串，即使一行数据也需要转换成数组形式。
+
+:::
+
 ## 示例代码
 
 <Tabs defaultValue="java" groupId="lang">

docs-cn/06-insert-data/_category_.yml

@@ -2,4 +2,4 @@ label: 写入数据
 link:
   type: generated-index
   slug: /insert-data/
-  description: "TDengine 支持多种接口写入协议，包括 SQL，InfluxDB Line 协议, OpentsDB Telnet 协议， OpentsDB JSON 格式协议。数据可以单条插入，也可以批量插入，可以插入一个数据采集点的数据，也可以同时插入多个数据采集点的数据。支持多线程插入，支持时间乱序数据插入，也支持历史数据插入。"
+  description: "TDengine 支持多种接口写入协议，包括 SQL，InfluxDB Line 协议, OpentsDB Telnet 协议， OpentsDB JSON 格式协议。数据可以单条插入，也可以批量插入，可以插入一个数据采集点的数据，也可以同时插入多个数据采集点的数据。支持多线程插入，支持时间乱序数据插入，也支持历史数据插入。InfluxDB Line 协议、 OpentsDB Telnet 协议和 OpentsDB JSON 格式协议是 TDengine 支持的三种无模式写入协议。使用无模式方式写入无需提前创建超级表和子表，并且引擎能自适用数据对表结构做调整。"

docs-cn/07-query-data/index.mdx

@@ -19,7 +19,7 @@ import CAsync from "./_c_async.mdx";
 
 ## 主要查询功能
 
-TDengine 采用 SQL 作为查询语言。应用程序可以通过 C/C++, Java, Go, C#, Python, Node.js 连接器发送 SQL 语句，用户可以通过 TDengine 提供的命令行（Command Line Interface, CLI）工具 TAOS Shell 手动执行 SQL 即席查询（Ad-Hoc Query）。TDengine 支持如下查询功能：
+TDengine 采用 SQL 作为查询语言。应用程序可以通过连接器发送 SQL 语句，用户可以通过命令行（Command Line Interface, CLI）工具 TAOS Shell 手动执行 SQL 即席查询（Ad-Hoc Query）。TDengine 支持如下查询功能：
 
 - 单列、多列数据查询
 - 标签和数值的多种过滤条件：>, <, =, <\>, like 等
@@ -43,11 +43,13 @@ Query OK, 2 row(s) in set (0.001100s)
 
 具体的查询语法请看 [TAOS SQL 的数据查询](https://www.taosdata.com/cn/documentation/taos-sql#select) 章节。
 
-## 多表聚合查询
+### 多表聚合查询
 
 物联网场景中，往往同一个类型的数据采集点有多个。TDengine 采用超级表(STable)的概念来描述某一个类型的数据采集点，一张普通的表来描述一个具体的数据采集点。同时 TDengine 使用标签来描述数据采集点的静态属性，一个具体的数据采集点有具体的标签值。通过指定标签的过滤条件，TDengine 提供了一高效的方法将超级表(某一类型的数据采集点)所属的子表进行聚合查询。对普通表的聚合函数以及绝大部分操作都适用于超级表，语法完全一样。
 
-**示例 1**：在 TAOS Shell，查找北京所有智能电表采集的电压平均值，并按照 location 分组
+#### 示例一
+
+在 TAOS Shell，查找北京所有智能电表采集的电压平均值，并按照 location 分组。
 
 ```
 taos> SELECT AVG(voltage) FROM meters GROUP BY location;
@@ -58,7 +60,8 @@ taos> SELECT AVG(voltage) FROM meters GROUP BY location;
 Query OK, 2 row(s) in set (0.002136s)
 ```
 
-**示例 2**：在 TAOS shell, 查找 groupId 为 2 的所有智能电表过去 24 小时的记录条数，电流的最大值
+#### 示例二
+在 TAOS shell, 查找 groupId 为 2 的所有智能电表过去 24 小时的记录条数，电流的最大值。
 
 ```
 taos> SELECT count(*), max(current) FROM meters where groupId = 2 and ts > now - 24h;
@@ -70,7 +73,7 @@ Query OK, 1 row(s) in set (0.002136s)
 
 TDengine 仅容许对属于同一个超级表的表之间进行聚合查询，不同超级表之间的聚合查询不支持。在 [TAOS SQL 的数据查询](https://www.taosdata.com/cn/documentation/taos-sql#select) 一章，查询类操作都会注明是否支持超级表。
 
-## 降采样查询、插值
+### 降采样查询、插值
 
 物联网场景里，经常需要通过降采样（down sampling）将采集的数据按时间段进行聚合。TDengine 提供了一个简便的关键词 interval 让按照时间窗口的查询操作变得极为简单。比如，将智能电表 d1001 采集的电流值每 10 秒钟求和
 
@@ -113,7 +116,7 @@ Query OK, 5 row(s) in set (0.001521s)
 
 物联网场景里，每个数据采集点采集数据的时间是难同步的，但很多分析算法(比如 FFT)需要把采集的数据严格按照时间等间隔的对齐，在很多系统里，需要应用自己写程序来处理，但使用 TDengine 的降采样操作就轻松解决。如果一个时间间隔里，没有采集的数据，TDengine 还提供插值计算的功能。
 
-语法规则细节请见 [TAOS SQL 的时间维度聚合](https://www.taosdata.com/cn/documentation/taos-sql#aggregation) 章节。
+语法规则细节请见 [TAOS SQL 的按时间窗口切分聚合](/reference/taos-sql/interval) 章节。
 
 ## 示例代码
 

docs-examples/java/pom.xml

@@ -17,11 +17,13 @@
   </properties>
 
   <dependencies>
+<!--    ANCHOR: dep-->
     <dependency>
       <groupId>com.taosdata.jdbc</groupId>
       <artifactId>taos-jdbcdriver</artifactId>
       <version>2.0.38</version>
     </dependency>
+<!--    ANCHOR_END: dep-->
     <dependency>
       <groupId>junit</groupId>
       <artifactId>junit</artifactId>