Merge pull request #7963 from taosdata/docs/Update-Latest-Feature

Docs/update latest feature

documentation20/cn/08.connector/docs.md

@@ -1166,7 +1166,7 @@ var affectRows = cursor.execute('insert into test.weather values(now, 22.3, 34);
 
 execute方法的返回值为该语句影响的行数，上面的sql向test库的weather表中，插入了一条数据，则返回值affectRows为1。
 
-TDengine目前还不支持update和delete语句。
+TDengine 目前还不支持 delete 语句。但从 2.0.8.0 版本开始，可以通过 `CREATE DATABASE` 时指定的 UPDATE 参数来启用对数据行的 update。
 
 #### 查询
 

documentation20/cn/11.administrator/docs.md

@@ -216,7 +216,7 @@ taosd -C
 | 98    | maxBinaryDisplayWidth   |          | **C**    |          | Taos shell中binary 和 nchar字段的显示宽度上限，超过此限制的部分将被隐藏 | 5    -                                                       | 30                                                           | 实际上限按以下规则计算：如果字段值的长度大于 maxBinaryDisplayWidth，则显示上限为 **字段名长度** 和 **maxBinaryDisplayWidth** 的较大者。否则，上限为 **字段名长度** 和 **字段值长度** 的较大者。可在 shell 中通过命令 set max_binary_display_width nn动态修改此选项 |
 | 99    | queryBufferSize         |          | **S**    | MB       | 为所有并发查询占用保留的内存大小。                           |                                                              |                                                              | 计算规则可以根据实际应用可能的最大并发数和表的数字相乘，再乘 170 。（2.0.15 以前的版本中，此参数的单位是字节） |
 | 100   | ratioOfQueryCores       |          | **S**    |          | 设置查询线程的最大数量。                                     |                                                              |                                                              | 最小值0 表示只有1个查询线程；最大值2表示最大建立2倍CPU核数的查询线程。默认为1，表示最大和CPU核数相等的查询线程。该值可以为小数，即0.5表示最大建立CPU核数一半的查询线程。 |
-| 101   | update                  |          | **S**    |          | 允许更新已存在的数据行                                         | 0 \| 1                                                       | 0                                                            | 从 2.0.8.0 版本开始                                                       |
+| 101   | update                  |          | **S**    |          | 允许更新已存在的数据行                                         | 0：不允许更新；1：允许整行更新；2：允许部分列更新。（2.1.7.0 版本开始此参数支持设为 2，在此之前取值只能是 [0, 1]）                                                      | 0                                                            | 2.0.8.0 版本之前，不支持此参数。                                                       |
 | 102   | cacheLast               |          | **S**    |          | 是否在内存中缓存子表的最近数据                                  | 0：关闭；1：缓存子表最近一行数据；2：缓存子表每一列的最近的非NULL值；3：同时打开缓存最近行和列功能。（2.1.2.0 版本开始此参数支持 0～3 的取值范围，在此之前取值只能是 [0, 1]）                      | 0                                                            | 2.1.2.0 版本之前、2.0.20.7 版本之前在 taos.cfg 文件中不支持此参数。                                             |
 | 103   | numOfCommitThreads      | YES      | **S**    |          | 设置写入线程的最大数量                                       |                                                              |                                                              |                                                              |
 | 104   | maxWildCardsLength      |          | **C**    | bytes    | 设定 LIKE 算子的通配符字符串允许的最大长度                     | 0-16384                                                       | 100                                                          | 2.1.6.1 版本新增。                                                     |
@@ -239,7 +239,7 @@ taosd -C
 | 10    | fsync            | 毫秒     | 当wal设置为2时，执行fsync的周期。设置为0，表示每次写入，立即执行fsync。                         |                                                  | 3000       |
 | 11    | replica          |          | （可通过 alter database 修改）副本个数                                                     | 1-3                                            | 1          |
 | 12    | precision        |          | 时间戳精度标识（2.1.2.0 版本之前、2.0.20.7 版本之前在 taos.cfg 文件中不支持此参数。）（从 2.1.5.0 版本开始，新增对纳秒时间精度的支持）           | ms 表示毫秒，us 表示微秒，ns 表示纳秒                 | ms         |
-| 13    | update           |          | 是否允许更新                                                  | 0：不允许；1：允许                                           | 0          |
+| 13    | update           |          | 是否允许数据更新（从 2.1.7.0 版本开始此参数支持 0～2 的取值范围，在此之前取值只能是 [0, 1]；而 2.0.8.0 之前的版本在 SQL 指令中不支持此参数。）                                                  | 0：不允许；1：允许更新整行；2：允许部分列更新。                                           | 0          |
 | 14    | cacheLast        |          | （可通过 alter database 修改）是否在内存中缓存子表的最近数据（从 2.1.2.0 版本开始此参数支持 0～3 的取值范围，在此之前取值只能是 [0, 1]；而 2.0.11.0 之前的版本在 SQL 指令中不支持此参数。）（2.1.2.0 版本之前、2.0.20.7 版本之前在 taos.cfg 文件中不支持此参数。）                         | 0：关闭；1：缓存子表最近一行数据；2：缓存子表每一列的最近的非NULL值；3：同时打开缓存最近行和列功能               | 0          |
 
 对于一个应用场景，可能有多种数据特征的数据并存，最佳的设计是将具有相同数据特征的表放在一个库里，这样一个应用有多个库，而每个库可以配置不同的存储参数，从而保证系统有最优的性能。TDengine允许应用在创建库时指定上述存储参数，如果指定，该参数就将覆盖对应的系统配置参数。举例，有下述SQL：

documentation20/cn/12.taos-sql/docs.md

@@ -70,7 +70,7 @@ TDengine 缺省的时间戳是毫秒精度，但通过在 CREATE DATABASE 时传
  
     1) KEEP是该数据库的数据保留多长天数，缺省是3650天(10年)，数据库会自动删除超过时限的数据；<!-- REPLACE_OPEN_TO_ENTERPRISE__KEEP_PARAM_DESCRIPTION -->
  
-    2) UPDATE 标志数据库支持更新相同时间戳数据；
+    2) UPDATE 标志数据库支持更新相同时间戳数据；（从 2.1.7.0 版本开始此参数支持设为 2，表示允许部分列更新，也即更新数据行时未被设置的列会保留原值。）（从 2.0.8.0 版本开始支持此参数。注意此参数不能通过 `ALTER DATABASE` 指令进行修改。）
  
     3) 数据库名最大长度为33；
  
@@ -573,16 +573,24 @@ Query OK, 2 row(s) in set (0.003112s)
 
 注意：普通表的通配符 * 中并不包含 _标签列_。
 
-##### 获取标签列的去重取值
+#### 获取标签列或普通列的去重取值
 
-从 2.0.15 版本开始，支持在超级表查询标签列时，指定 DISTINCT 关键字，这样将返回指定标签列的所有不重复取值。
-```mysql
-SELECT DISTINCT tag_name FROM stb_name;
+从 2.0.15.0 版本开始，支持在超级表查询标签列时，指定 DISTINCT 关键字，这样将返回指定标签列的所有不重复取值。注意，在 2.1.6.0 版本之前，DISTINCT 只支持处理单个标签列，而从 2.1.6.0 版本开始，DISTINCT 可以对多个标签列进行处理，输出这些标签列取值不重复的组合。
+```sql
+SELECT DISTINCT tag_name [, tag_name ...] FROM stb_name;
 ```
 
-注意：目前 DISTINCT 关键字只支持对超级表的标签列进行去重，而不能用于普通列。
+从 2.1.7.0 版本开始，DISTINCT 也支持对数据子表或普通表进行处理，也即支持获取单个普通列的不重复取值，或多个普通列取值的不重复组合。
+```sql
+SELECT DISTINCT col_name [, col_name ...] FROM tb_name;
+```
 
+需要注意的是，DISTINCT 目前不支持对超级表中的普通列进行处理。如果需要进行此类操作，那么需要把超级表放在子查询中，再对子查询的计算结果执行 DISTINCT。
 
+说明：
+1. cfg 文件中的配置参数 maxNumOfDistinctRes 将对 DISTINCT 能够输出的数据行数进行限制。其最小值是 100000，最大值是 100000000，默认值是 10000000。如果实际计算结果超出了这个限制，那么会仅输出这个数量范围内的部分。
+2. 由于浮点数天然的精度机制原因，在特定情况下，对 FLOAT 和 DOUBLE 列使用 DISTINCT 并不能保证输出值的完全唯一性。
+3. 在当前版本下，DISTINCT 不能在嵌套查询的子查询中使用，也不能与聚合函数、GROUP BY、或 JOIN 在同一条语句中混用。
 
 #### 结果集列名
 

documentation20/cn/13.faq/docs.md

@@ -96,6 +96,8 @@ TDengine 目前尚不支持删除功能，未来根据用户需求可能会支
 
 另需注意，在 UPDATE 设置为 0 时，后发送的相同时间戳的数据会被直接丢弃，但并不会报错，而且仍然会被计入 affected rows （所以不能利用 INSERT 指令的返回信息进行时间戳查重）。这样设计的主要原因是，TDengine 把写入的数据看做一个数据流，无论时间戳是否出现冲突，TDengine 都认为产生数据的原始设备真实地产生了这样的数据。UPDATE 参数只是控制这样的流数据在进行持久化时要怎样处理——UPDATE 为 0 时，表示先写入的数据覆盖后写入的数据；而 UPDATE 为 1 时，表示后写入的数据覆盖先写入的数据。这种覆盖关系如何选择，取决于对数据的后续使用和统计中，希望以先还是后生成的数据为准。
 
+此外，从 2.1.7.0 版本开始，支持将 UPDATE 参数设为 2，表示“支持部分列更新”。也即，当 UPDATE 设为 1 时，如果更新一个数据行，其中某些列没有提供取值，那么这些列会被设为 NULL；而当 UPDATE 设为 2 时，如果更新一个数据行，其中某些列没有提供取值，那么这些列会保持原有数据行中的对应值。
+
 ## 10. 我怎么创建超过1024列的表？
 
 使用 2.0 及其以上版本，默认支持 1024 列；2.0 之前的版本，TDengine 最大允许创建 250 列的表。但是如果确实超过限值，建议按照数据特性，逻辑地将这个宽表分解成几个小表。（从 2.1.7.0 版本开始，表的最大列数增加到了 4096 列。）