[TD-6404] <docs>: describe Schemaless Insert.

documentation20/cn/05.insert/docs.md

@@ -2,7 +2,7 @@
 
 TDengine支持多种接口写入数据，包括SQL, Prometheus, Telegraf, EMQ MQTT Broker, HiveMQ Broker, CSV文件等，后续还将提供Kafka, OPC等接口。数据可以单条插入，也可以批量插入，可以插入一个数据采集点的数据，也可以同时插入多个数据采集点的数据。支持多线程插入，支持时间乱序数据插入，也支持历史数据插入。
 
-## <a class="anchor" id="sql"></a>SQL写入
+## <a class="anchor" id="sql"></a>SQL 写入
 
 应用通过C/C++、JDBC、GO、C#或Python Connector 执行SQL insert语句来插入数据，用户还可以通过TAOS Shell，手动输入SQL insert语句插入数据。比如下面这条insert 就将一条记录写入到表d1001中：
 ```mysql
@@ -27,11 +27,73 @@ INSERT INTO d1001 VALUES (1538548685000, 10.3, 219, 0.31) (1538548695000, 12.6,
 - 对同一张表，如果新插入记录的时间戳已经存在，默认情形下（UPDATE=0）新记录将被直接抛弃，也就是说，在一张表里，时间戳必须是唯一的。如果应用自动生成记录，很有可能生成的时间戳是一样的，这样，成功插入的记录条数会小于应用插入的记录条数。如果在创建数据库时使用了 UPDATE 1 选项，插入相同时间戳的新记录将覆盖原有记录。
 - 写入的数据的时间戳必须大于当前时间减去配置参数keep的时间。如果keep配置为3650天，那么无法写入比3650天还早的数据。写入数据的时间戳也不能大于当前时间加配置参数days。如果days为2，那么无法写入比当前时间还晚2天的数据。
 
-## <a class="anchor" id="prometheus"></a>Prometheus直接写入
+## <a class="anchor" id="schemaless"></a>Schemaless 写入
+
+在物联网应用中，常会采集比较多的数据项，用于实现智能控制、业务分析、设备监控等。由于应用逻辑的版本升级，或者设备自身的硬件调整等原因，数据采集项就有可能比较频繁地出现变动。为了在这种情况下方便地完成数据记录工作，TDengine 从 2.2.0.0 版本开始，提供 Schemaless 写入方式，可以免于预先创建超级表/数据子表，而是随着数据写入，自动创建与数据对应的存储结构。并且在必要时，Schemaless 将自动增加必要的数据列，保证用户写入的数据可以被正确存储。目前，TDengine 的 C/C++ Connector 提供支持 Schemaless 的操作接口，详情请参见 [Schemaless 方式写入接口](https://www.taosdata.com/cn/documentation/connector#schemaless) 章节。这里对 Schemaless 的数据表达格式进行描述。
+
+### Schemaless 数据行协议
+
+Schemaless 采用一个字符串来表达最终存储的一个数据行（可以向 Schemaless 写入 API 中一次传入多个字符串来实现多个数据行的批量写入），其格式约定如下：
+```json
+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 即本行数据对应的主键时间戳。
+
+在 Schemaless 的数据行协议中，tag_set、field_set 中的每个数据项都需要对自身的数据类型进行描述。具体来说：
+* 如果两边有英文双引号，表示 BIANRY(32) 类型。例如 `"abc"`。
+* 如果两边有英文双引号而且带有 L 前缀，表示 NCHAR(32) 类型。例如 `L"报错信息"`。
+* 对空格、等号（=）、逗号（,）、双引号（"），前面需要使用反斜杠（\）进行转义。（都指的是英文半角符号）
+* 数值类型将通过后缀来区分数据类型：
+  - 没有后缀，为 FLOAT 类型；
+  - 后缀为 f32，为 FLOAT 类型；
+  - 后缀为 f64，为 DOUBLE 类型；
+  - 后缀为 i8，表示为 TINYINT (INT8) 类型；
+  - 后缀为 i16，表示为 SMALLINT (INT16) 类型；
+  - 后缀为 i32，表示为 INT (INT32) 类型；
+  - 后缀为 i64，表示为 BIGINT (INT64) 类型；
+  - 后缀为 b，表示为 BOOL 类型。
+* t, T, true, True, TRUE, f, F, false, False 将直接作为 BOOL 型来处理。
+
+timestamp 位置的时间戳通过后缀来声明时间精度，具体如下：
+* 不带任何后缀的长整数会被当作微秒来处理；
+* 当后缀为 s 时，表示秒时间戳；
+* 当后缀为 ms 时，表示毫秒时间戳；
+* 当后缀为 us 时，表示微秒时间戳；
+* 当后缀为 ns 时，表示纳秒时间戳；
+* 当时间戳为 0 时，表示采用客户端的当前时间（因此，同一批提交的数据中，时间戳 0 会被解释为同一个时间点，于是就有可能导致时间戳重复）。
+
+例如，如下 Schemaless 数据行表示：向名为 st 的超级表下的 t1 标签为 3（BIGINT 类型）、t2 标签为 4（DOUBLE 类型）、t3 标签为 "t3"（BINARY 类型）的数据子表，写入 c1 列为 3（BIGINT 类型）、c2 列为 false（BOOL 类型）、c3 列为 "passit"（NCHAR 类型）、c4 列为 4（DOUBLE 类型）、主键时间戳为 1626006833639000000（纳秒精度）的一行数据。
+```json
+st,t1=3i64,t2=4f64,t3="t3" c1=3i64,c3=L"passit",c2=false,c4=4f64 1626006833639000000ns
+```
+
+### Schemaless 的处理逻辑
+
+Schemaless 按照如下原则来处理行数据：
+1. 当 tag_set 中有 ID 字段时，该字段的值将作为数据子表的表名。
+2. 没有 ID 字段时，将使用 `measurement + tag_value1 + tag_value2 + ...` 的 md5 值来作为子表名。
+3. 如果指定的超级表名不存在，则 Schemaless 会创建这个超级表。
+4. 如果指定的数据子表不存在，则 Schemaless 会使用 tag values 创建这个数据子表。
+5. 如果数据行中指定的标签列或普通列不存在，则 Schemaless 会在超级表中增加对应的标签列或普通列（只增不减）。
+6. 如果超级表中存在一些标签列或普通列未在一个数据行中被指定取值，那么这些列的值在这一行中会被置为 NULL。
+7. 对 BINARY 或 NCHAR 列，如果数据行中所提供值的长度超出了列类型的限制，那么 Schemaless 会增加该列允许存储的字符长度上限（只增不减），以保证数据的完整保存。
+8. 如果指定的数据子表已经存在，而且本次指定的标签列取值跟已保存的值不一样，那么最新的数据行中的值会覆盖旧的标签列取值。
+9. 整个处理过程中遇到的错误会中断写入过程，并返回错误代码。
+
+**注意：**Schemaless 所有的处理逻辑，仍会遵循 TDengine 对数据结构的底层限制，例如每行数据的总长度不能超过 16k 字节。这方面的具体限制约束请参见 [TAOS SQL 边界限制](https://www.taosdata.com/cn/documentation/taos-sql#limitation) 章节。
+
+关于 Schemaless 的字符串编码处理、时区设置等，均会沿用 TAOSC 客户端的设置。
+
+## <a class="anchor" id="prometheus"></a>Prometheus 直接写入
 
 [Prometheus](https://www.prometheus.io/)作为Cloud Native Computing Fundation毕业的项目，在性能监控以及K8S性能监控领域有着非常广泛的应用。TDengine提供一个小工具[Bailongma](https://github.com/taosdata/Bailongma)，只需对Prometheus做简单配置，无需任何代码，就可将Prometheus采集的数据直接写入TDengine，并按规则在TDengine自动创建库和相关表项。博文[用Docker容器快速搭建一个Devops监控Demo](https://www.taosdata.com/blog/2020/02/03/1189.html)即是采用Bailongma将Prometheus和Telegraf的数据写入TDengine中的示例，可以参考。
 
-### 从源代码编译blm_prometheus
+### 从源代码编译 blm_prometheus
 
 用户需要从github下载[Bailongma](https://github.com/taosdata/Bailongma)的源码，使用Golang语言编译器编译生成可执行文件。在开始编译前，需要准备好以下条件：
 - Linux操作系统的服务器
@@ -46,11 +108,11 @@ go build
 
 一切正常的情况下，就会在对应的目录下生成一个blm_prometheus的可执行程序。
 
-### 安装Prometheus
+### 安装 Prometheus
 
 通过Prometheus的官网下载安装。具体请见：[下载地址](https://prometheus.io/download/)。
 
-### 配置Prometheus
+### 配置 Prometheus
 
 参考Prometheus的[配置文档](https://prometheus.io/docs/prometheus/latest/configuration/configuration/)，在Prometheus的配置文件中的<remote_write>部分，增加以下配置：
 
@@ -60,7 +122,8 @@ go build
 
 启动Prometheus后，可以通过taos客户端查询确认数据是否成功写入。
 
-### 启动blm_prometheus程序
+### 启动 blm_prometheus 程序
+
 blm_prometheus程序有以下选项，在启动blm_prometheus程序时可以通过设定这些选项来设定blm_prometheus的配置。
 ```bash
 --tdengine-name
@@ -94,7 +157,8 @@ remote_write:
   - url: "http://10.1.2.3:8088/receive"
 ```
 
-### 查询prometheus写入数据
+### 查询 prometheus 写入数据
+
 prometheus产生的数据格式如下：
 ```json
 {
@@ -105,10 +169,10 @@ prometheus产生的数据格式如下：
     instance="192.168.99.116:8443", 
     job="kubernetes-apiservers", 
     le="125000", 
-    resource="persistentvolumes", s
-    cope="cluster",
+    resource="persistentvolumes", 
+    scope="cluster",
     verb="LIST", 
-    version=“v1" 
+    version="v1" 
   }
 }
 ```
@@ -118,11 +182,11 @@ use prometheus;
 select * from apiserver_request_latencies_bucket;
 ```
 
-## <a class="anchor" id="telegraf"></a>Telegraf直接写入
+## <a class="anchor" id="telegraf"></a>Telegraf 直接写入
 
 [Telegraf](https://www.influxdata.com/time-series-platform/telegraf/)是一流行的IT运维数据采集开源工具，TDengine提供一个小工具[Bailongma](https://github.com/taosdata/Bailongma)，只需在Telegraf做简单配置，无需任何代码，就可将Telegraf采集的数据直接写入TDengine，并按规则在TDengine自动创建库和相关表项。博文[用Docker容器快速搭建一个Devops监控Demo](https://www.taosdata.com/blog/2020/02/03/1189.html)即是采用bailongma将Prometheus和Telegraf的数据写入TDengine中的示例，可以参考。
 
-### 从源代码编译blm_telegraf
+### 从源代码编译 blm_telegraf
 
 用户需要从github下载[Bailongma](https://github.com/taosdata/Bailongma)的源码，使用Golang语言编译器编译生成可执行文件。在开始编译前，需要准备好以下条件：
 
@@ -139,11 +203,11 @@ go build
 
 一切正常的情况下，就会在对应的目录下生成一个blm_telegraf的可执行程序。
 
-### 安装Telegraf
+### 安装 Telegraf
 
 目前TDengine支持Telegraf 1.7.4以上的版本。用户可以根据当前的操作系统，到Telegraf官网下载安装包，并执行安装。下载地址如下：https://portal.influxdata.com/downloads 。
 
-### 配置Telegraf
+### 配置 Telegraf
 
 修改Telegraf配置文件/etc/telegraf/telegraf.conf中与TDengine有关的配置项。 
 
@@ -160,7 +224,8 @@ go build
 
 关于如何使用Telegraf采集数据以及更多有关使用Telegraf的信息，请参考Telegraf官方的[文档](https://docs.influxdata.com/telegraf/v1.11/)。
 
-### 启动blm_telegraf程序
+### 启动 blm_telegraf 程序
+
 blm_telegraf程序有以下选项，在启动blm_telegraf程序时可以通过设定这些选项来设定blm_telegraf的配置。
 
 ```bash
@@ -196,7 +261,7 @@ blm_telegraf对telegraf提供服务的端口号。
 url = "http://10.1.2.3:8089/telegraf"
 ```
 
-### 查询telegraf写入数据
+### 查询 telegraf 写入数据
 
 telegraf产生的数据格式如下：
 ```json

documentation20/cn/08.connector/docs.md

@@ -403,6 +403,25 @@ typedef struct TAOS_MULTI_BIND {
   （2.1.3.0 版本新增）  
   用于在其他 stmt API 返回错误（返回错误码或空指针）时获取错误信息。
 
+<a class="anchor" id="schemaless"></a>
+### Schemaless 方式写入接口
+
+除了使用 SQL 方式或者使用参数绑定 API 写入数据外，还可以使用 Schemaless 的方式完成写入。Schemaless 可以免于预先创建超级表/数据子表的数据结构，而是可以直接写入数据，TDengine 系统会根据写入的数据内容自动创建和维护所需要的表结构。Schemaless 的使用方式详见 [Schemaless 写入](https://www.taosdata.com/cn/documentation/insert#schemaless) 章节，这里介绍与之配套使用的 C/C++ API。
+
+- `int taos_insert_lines(TAOS* taos, char* lines[], int numLines)`
+
+  （2.2.0.0 版本新增）  
+  以 Schemaless 格式写入多行数据。其中：
+    * taos：调用 taos_connect 返回的数据库连接。
+    * lines：由 char 字符串指针组成的数组，指向本次想要写入数据库的多行数据。
+    * numLines：lines 数据的总行数。 
+
+  返回值为 0 表示写入成功，非零值表示出错。具体错误代码请参见 [taoserror.h](https://github.com/taosdata/TDengine/blob/develop/src/inc/taoserror.h) 文件。
+
+  说明：
+    1. 此接口是一个同步阻塞式接口，使用时机与 `taos_query()` 一致。
+    2. 在调用此接口之前，必须先调用 `taos_select_db()` 来确定目前是在向哪个 DB 来写入。
+
 ### 连续查询接口
 
 TDengine提供时间驱动的实时流式计算API。可以每隔一指定的时间段，对一张或多张数据库的表(数据流)进行各种实时聚合计算操作。操作简单，仅有打开、关闭流的API。具体如下：