Update docs.md

update doc for schemaless

documentation20/cn/05.insert/docs.md

@@ -27,13 +27,18 @@ 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="schemaless"></a>Schemaless 写入
+## <a class="anchor" id="schemaless"></a>无模式（Schemaless）写入
+**前言**
+<br/>在物联网应用中，常会采集比较多的数据项，用于实现智能控制、业务分析、设备监控等。由于应用逻辑的版本升级，或者设备自身的硬件调整等原因，数据采集项就有可能比较频繁地出现变动。为了在这种情况下方便地完成数据记录工作，TDengine 从 2.2.0.0 版本开始，提供调用 Schemaless 写入方式，可以免于预先创建超级表/子表的步骤，随着数据写入写入接口能够自动创建与数据对应的存储结构。并且在必要时，Schemaless 将自动增加必要的数据列，保证用户写入的数据可以被正确存储。
+<br/>目前，TDengine 的 C/C++ Connector 提供支持 Schemaless 的操作接口，详情请参见 Schemaless 方式写入接口 章节。这里对 Schemaless 的数据表达格式进行了描述。
+<br/>无模式写入方式建立的超级表及其对应的子表与通过 SQL 直接建立的超级表和子表完全没有区别，您也可以通过 SQL 语句直接向其中写入数据。需要注意的是，通过无模式写入方式建立的表，其表名是基于标签值按照固定的映射规则生成，所以无法明确地进行表意，缺乏可读性。
 
-在物联网应用中，常会采集比较多的数据项，用于实现智能控制、业务分析、设备监控等。由于应用逻辑的版本升级，或者设备自身的硬件调整等原因，数据采集项就有可能比较频繁地出现变动。为了在这种情况下方便地完成数据记录工作，TDengine 从 2.2.0.0 版本开始，提供 Schemaless 写入方式，可以免于预先创建超级表/数据子表，而是随着数据写入，自动创建与数据对应的存储结构。并且在必要时，Schemaless 将自动增加必要的数据列，保证用户写入的数据可以被正确存储。目前，TDengine 的 C/C++ Connector 提供支持 Schemaless 的操作接口，详情请参见 [Schemaless 方式写入接口](https://www.taosdata.com/cn/documentation/connector#schemaless) 章节。这里对 Schemaless 的数据表达格式进行描述。
+**无模式写入行协议**
+<br/>TDengine 的无模式写入的行协议兼容 InfluxDB 的 行协议（Line Protocol）、OpenTSDB 的 telnet 行协议、OpenTSDB 的 Json 格式协议。但是使用这三种协议的时候，需要在 API 中指定输入内容使用解析协议的标准。
 
-### Schemaless 数据行协议
+对于InfluxDB、OpenTSDB的标准写入协议请参考各自的文档。下面首先以 InfluxDB 的行协议为基础，介绍 TDengine 扩展的协议内容，允许用户采用更加精细的方式控制（超级表）模式。
 
-Schemaless 采用一个字符串来表达最终存储的一个数据行（可以向 Schemaless 写入 API 中一次传入多个字符串来实现多个数据行的批量写入），其格式约定如下：
+Schemaless 采用一个字符串来表达一个数据行（可以向写入 API 中一次传入多行字符串来实现多个数据行的批量写入），其格式约定如下：
 ```json
 measurement,tag_set field_set timestamp
 ```
@@ -44,51 +49,103 @@ measurement,tag_set field_set timestamp
 * field_set 将作为普通列数据，其格式形如 `<field_key>=<field_value>,<field_key>=<field_value>`，同样是使用英文逗号来分隔多个普通列的数据。它与 timestamp 之间使用一个半角空格来分隔。
 * timestamp 即本行数据对应的主键时间戳。
 
-在 Schemaless 的数据行协议中，tag_set、field_set 中的每个数据项都需要对自身的数据类型进行描述。具体来说：
+tag_set 中的所有的数据自动转化为 nchar 数据类型，并不需要使用双引号（")。
+<br/>在无模式写入数据行协议中，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) 类型；
+
+| **序号** | **后缀**        | **映射类型** | **大小(字节)** | 
+| ---- | ------------------- | ------------ | -------- |
+| 1    | 无或f64              |    double   |     8    |
+| 2    | f32              |    float   |     4    |
+| 3    | i8              |    TinyInt   |     1    |
+| 4    | i16              |    SmallInt   |     2    |
+| 5    | i32              |    Int   |     4    |
+| 6    | i64或i              |    Bigint   |     8    |
 * t, T, true, True, TRUE, f, F, false, False 将直接作为 BOOL 型来处理。
+<br/>例如如下数据行表示：向名为 st 的超级表下的 t1 标签为 "3"（NCHAR）、t2 标签为 "4"（NCHAR）、t3 标签为 "t3"（NCHAR）的数据子表，写入 c1 列为 3（BIGINT）、c2 列为 false（BOOL）、c3 列为 "passit"（BINARY）、c4 列为 4（DOUBLE）、主键时间戳为 1626006833639000000 的一行数据。
+```json
+st,t1=3,t2=4,t3=t3 c1=3i64,c3="passit",c2=false,c4=4f64 1626006833639000000
+```
+需要注意的是，如果描述数据类型后缀时使用了错误的大小写，或者为数据指定的数据类型有误，均可能引发报错提示而导致数据写入失败。
 
-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（纳秒精度）的一行数据。
+无模式写入按照如下原则来处理行数据：
+1. 当 tag_set 中有 ID 字段时，该字段的值将作为子表的表名。
+2. 没有 ID 字段时，将使用如下规则来生成子表名：
+首先将measurement 的名称和标签的 key 和 value 组合成为如下的字符串
+```json
+"measurement,tag_key1=tag_value1,tag_key2=tag_value2"
+```
+需要注意的是，这里的tag_key1, tag_key2并不是用户输入的标签的原始顺序，而是使用了标签名称按照字符串升序排列后的结果。所以，tag_key1 并不是在行协议中输入的第一个标签。
+排列完成以后计算该字符串的 MD5 散列值 "md5_val"。然后将计算的结果与字符串组合生成表名：“t_md5_val”。其中的 “t_” 是固定的前缀，每个通过该映射关系自动生成的表都具有该前缀。
+<br/>3. 如果解析行协议获得的超级表不存在，则会创建这个超级表。
+<br/>4. 如果解析行协议获得子表不存在，则 Schemaless 会按照步骤 1 或 2 确定的子表名来创建子表。
+<br/>5. 如果数据行中指定的标签列或普通列不存在，则在超级表中增加对应的标签列或普通列（只增不减）。
+<br/>6. 如果超级表中存在一些标签列或普通列未在一个数据行中被指定取值，那么这些列的值在这一行中会被置为 NULL。
+<br/>7. 对 BINARY 或 NCHAR 列，如果数据行中所提供值的长度超出了列类型的限制，自动增加该列允许存储的字符长度上限（只增不减），以保证数据的完整保存。
+<br/>8. 如果指定的数据子表已经存在，而且本次指定的标签列取值跟已保存的值不一样，那么最新的数据行中的值会覆盖旧的标签列取值。
+<br/>9. 整个处理过程中遇到的错误会中断写入过程，并返回错误代码。
+
+**备注：**
+<br/>无模式所有的处理逻辑，仍会遵循 TDengine 对数据结构的底层限制，例如每行数据的总长度不能超过 16k 字节。这方面的具体限制约束请参见 [TAOS SQL 边界限制](https://www.taosdata.com/cn/documentation/taos-sql#limitation) 章节。
+
+**时间分辨率识别**
+<br/>无模式写入过程中支持三个指定的模式，具体如下
+
+| **序号** | **值**        | **说明** |
+| ---- | ------------------- | ------------ |
+| 1    | SML_LINE_PROTOCOL           |    InfluxDB行协议（Line Protocol)   |
+| 2    | SML_TELNET_PROTOCOL              |    OpenTSDB文本行协议   |
+| 3    | SML_JSON_PROTOCOL              |    Json协议格式   |
+
+在 SML_LINE_PROTOCOL 解析模式下，需要用户指定输入的时间戳的时间分辨率。可用的时间分辨率如下表所示：
+| **序号** | **时间分辨率定义**        | **含义** |
+| ---- | ----------------------------- | --------- |
+| 1    | TSDB_SML_TIMESTAMP_NOT_CONFIGURED     | 未定义（无效） |
+| 2    | TSDB_SML_TIMESTAMP_HOURS              |   小时        |
+| 3    | TSDB_SML_TIMESTAMP_MINUTES            |   分钟        |
+| 4    | TSDB_SML_TIMESTAMP_SECONDS            |   秒          |
+| 5    | TSDB_SML_TIMESTAMP_MILLI_SECONDS      |   毫秒        |
+| 6    | TSDB_SML_TIMESTAMP_MICRO_SECONDS      |   微秒        |
+| 7    | TSDB_SML_TIMESTAMP_NANO_SECONDS       |   纳秒        |
+
+在 SML_TELNET_PROTOCOL 和 SML_JSON_PROTOCOL 模式下，根据时间戳的长度来确定时间精度（与 OpenTSDB 标准操作方式相同），此时会忽略用户指定的时间分辨率。
+
+**数据模式变更处理**
+<br/>本节将说明不同行数据写入情况下，对于数据模式的影响。
+
+在使用行协议写入一个明确的标识的字段类型的时候，后续更改该字段的类型定义，会出现明确的数据模式错误，即会触发写入 API 报告错误。如下所示，
 ```json
-st,t1=3i64,t2=4f64,t3="t3" c1=3i64,c3=L"passit",c2=false,c4=4f64 1626006833639000000ns
+st,t1=3,t2=4,t3=t3 c1=3i64,c3="passit",c2=false,c4=4    1626006833639000000
+st,t1=3,t2=4,t3=t3 c1=3i64,c3="passit",c2=false,c4=4i   1626006833640000000
 ```
+第一行的数据类型映射将 c4 列定义为 Double， 但是第二行的数据又通过数值后缀方式声明该列为 BigInt， 由此会触发无模式写入的解析错误。
 
-需要注意的是，如果描述数据类型后缀时使用了错误的大小写，或者为数据指定的数据类型有误，均可能引发报错提示而导致数据写入失败。
+如果列前面的行协议将数据列声明为了 binary， 后续的要求长度更长的binary长度，此时会触发超级表模式的变更。
+```json
+st,t1=3,t2=4,t3=t3 c1=3i64,c5="pass"     1626006833639000000
+st,t1=3,t2=4,t3=t3 c1=3i64,c5="passit"   1626006833640000000
+```
+第一行中行协议解析会声明 c5 列是一个 binary(4)的字段，第二次行数据写入会提取列 c5 仍然是 binary 列，但是其宽度为 6，此时需要将binary的宽度增加到能够容纳 新字符串的宽度。
+```json
+st,t1=3,t2=4,t3=t3 c1=3i64               1626006833639000000
+st,t1=3,t2=4,t3=t3 c1=3i64,c6="passit"   1626006833640000000
+```
+第二行数据相对于第一行来说增加了一个列 c6，类型为binary(6)。那么此时会自动增加一个列 c6， 类型为  binary(6)。
 
-### Schemaless 的处理逻辑
+**写入完整性**
+<br/>TDengine 提供数据写入的幂等性保证，即您可以反复调用 API 进行出错数据的写入操作。但是不提供多行数据写入的原子性保证。即在多行数据一批次写入过程中，会出现部分数据写入成功，部分数据写入失败的情况。
 
-Schemaless 按照如下原则来处理行数据：
-1. 当 tag_set 中有 ID 字段时，该字段的值将作为数据子表的表名。
-2. 没有 ID 字段时，将使用 `measurement + tag_value1 + tag_value2 + ...` 的 md5 值来作为子表名。
-3. 如果指定的超级表名不存在，则 Schemaless 会创建这个超级表。
-4. 如果指定的数据子表不存在，则 Schemaless 会按照步骤 1 或 2 确定的子表名来创建子表。
-5. 如果数据行中指定的标签列或普通列不存在，则 Schemaless 会在超级表中增加对应的标签列或普通列（只增不减）。
-6. 如果超级表中存在一些标签列或普通列未在一个数据行中被指定取值，那么这些列的值在这一行中会被置为 NULL。
-7. 对 BINARY 或 NCHAR 列，如果数据行中所提供值的长度超出了列类型的限制，那么 Schemaless 会增加该列允许存储的字符长度上限（只增不减），以保证数据的完整保存。
-8. 如果指定的数据子表已经存在，而且本次指定的标签列取值跟已保存的值不一样，那么最新的数据行中的值会覆盖旧的标签列取值。
-9. 整个处理过程中遇到的错误会中断写入过程，并返回错误代码。
+**错误码**
+<br/>如果是无模式写入过程中的数据本身错误，应用会得到 TSDB_CODE_TSC_LINE_SYNTAX_ERROR 错误信息，该错误信息表明错误发生在写入文本中。其他的错误码与原系统一致，可以通过 taos_errstr 获取具体的错误原因。
 
-**注意：**Schemaless 所有的处理逻辑，仍会遵循 TDengine 对数据结构的底层限制，例如每行数据的总长度不能超过 16k 字节。这方面的具体限制约束请参见 [TAOS SQL 边界限制](https://www.taosdata.com/cn/documentation/taos-sql#limitation) 章节。
+**后续升级计划**
+<br/>当前版本只提供了 C 版本的 API，后续将提供 其他高级语言的 API，例如 Java/Go/Python/C# 等。此外，在TDengine v2.3及后续版本中，您还可以通过 BLM v3 采用 REST 的方式直接写入无模式数据。
 
-关于 Schemaless 的字符串编码处理、时区设置等，均会沿用 TAOSC 客户端的设置。
 
 ## <a class="anchor" id="prometheus"></a>Prometheus 直接写入