Merge pull request #11573 from taosdata/docs/jtao1735-doc

docs: update 01-intro.md

docs-cn/01-intro/01-intro.md

@@ -24,15 +24,16 @@ TDengine 是一款高性能、分布式、支持 SQL 的时序数据库。而且
 
 - **互动 Console**: 通过命令行 console，不用编程，执行 SQL 语句就能做即席查询、各种数据库的操作、管理以及集群的维护.
 
-采用 TDengine，可将典型的物联网、车联网、工业互联网大数据平台的总拥有成本大幅降低。但需要指出的是，因充分利用了物联网时序数据的特点，它无法用来处理网络爬虫、微博、微信、电商、ERP、CRM 等通用型数据。
+采用 TDengine，可将典型的物联网、车联网、工业互联网大数据平台的总拥有成本大幅降低。表现在几个方面，1：由于其超强性能，它能将系统需要的计算资源和存储资源大幅降低；2：因为采用SQL接口，能与众多第三放软件无缝集成，学习迁移成本大幅下降；3：因为其All In One的特性，系统复杂度降低，能降研发成本；4：因为运维维护简单，运营维护成本能大幅降低。
 
+在整个时序大数据平台中，TDengine在其中扮演的角色如下：
 ![TDengine技术生态图](eco_system.png)
 
 <center>图 1. TDengine技术生态图</center>
 
 ## TDengine 总体适用场景
 
-作为一个高性能、分布式、支持 SQL 的时序数据库，TDengine 的典型适用场景包括但不限于 IoT 和 DevOps，尤其是在大数据量的情况下。本文后续的介绍主要针对这些应用场景。
+作为一个高性能、分布式、支持 SQL 的时序数据库，TDengine 的典型适用场景包括但不限于 IoT、工业互联网、车联网、IT运维、能源、金融证券等领域。需要指出的是，TDengine是针对时序数据场景设计的专用数据库和专用大数据处理工具，因充分利用了时序大数据的特点，它无法用来处理网络爬虫、微博、微信、电商、ERP、CRM 等通用型数据。本文对适用场景做更多详细的分析。
 
 ### 数据源特点和需求
 

docs-cn/02-concept/02-concept.md

 ---
-title: 基本概念
+title: 数据模型和基本概念
 ---
 
 ## 物联网典型场景
 
-在典型的物联网、车联网、运维监测场景中，往往有多种不同类型的数据采集设备，采集一个到多个不同的物理量。而同一种采集设备类型，往往又有多个具体的采集设备分布在不同的地点。大数据处理系统就是要将各种采集的数据汇总，然后进行计算和分析。对于同一类设备，其采集的数据类似如下的表格：
-
-| Device ID |  Time Stamp   | Value 1 | Value 2 | Value 3 | Tag 1 | Tag 2 |
-| :-------: | :-----------: | :-----: | :-----: | :-----: | :---: | :---: |
-|   D1001   | 1538548685000 |  10.3   |   219   |  0.31   |  Red  | Tesla |
-|   D1002   | 1538548684000 |  10.2   |   220   |  0.23   | Blue  |  BMW  |
-|   D1003   | 1538548686500 |  11.5   |   221   |  0.35   | Black | Honda |
-|   D1004   | 1538548685500 |  13.4   |   223   |  0.29   |  Red  | Volvo |
-|   D1001   | 1538548695000 |  12.6   |   218   |  0.33   |  Red  | Tesla |
-|   D1004   | 1538548696600 |  11.8   |   221   |  0.28   | Black | Honda |
-
-
-每一条记录都有设备 ID，时间戳，采集的物理量，还有与每个设备相关的静态标签。每个设备是受外界的触发，或按照设定的周期采集数据。采集的数据点是时序的，是一个数据流。
-
-**数据特征**
-
-除时序特征外，仔细研究发现，物联网、车联网、运维监测类数据还具有很多其他明显的特征。
+在典型的物联网、车联网、运维监测场景中，往往有多种不同类型的数据采集设备或采集点，采集一个到多个不同的物理量。而同一种采集设备类型，往往又有多个具体的采集设备分布在不同的地点。采集的物理量都带有时间标签，而且数据量随时间不断增长，但每个数据采集设备或采集点还有自身的静态属性。对于同一类设备，其采集的数据以及静态属性都是很规则的。以智能电表为例，假设每个智能电表采集电流、电压、相位三个量，其采集的数据类似如下的表格：
+
+<table>
+<thead><tr>
+    <th >设备ID</th>
+    <th >时间戳</th>
+    <th  colspan="3">采集量</th>
+    <th  colspan="2">标签</th>
+    </tr>
+<tr>
+<th >Device ID</th>
+<th >Time Stamp</th>
+<th >current</th>
+<th >voltage</th>
+<th >phase</th>
+<th >location</th>
+<th >groupId</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td >d1001</td>
+<td >1538548685000</td>
+<td >10.3</td>
+<td >219</td>
+<td >0.31</td>
+<td >Beijing.Chaoyang</td>
+<td >2</td>
+</tr>
+<tr>
+<td >d1002</td>
+<td >1538548684000</td>
+<td >10.2</td>
+<td >220</td>
+<td >0.23</td>
+<td >Beijing.Chaoyang</td>
+<td >3</td>
+</tr>
+<tr>
+<td >d1003</td>
+<td >1538548686500</td>
+<td >11.5</td>
+<td >221</td>
+<td >0.35</td>
+<td >Beijing.Haidian</td>
+<td >3</td>
+</tr>
+<tr>
+<td >d1004</td>
+<td >1538548685500</td>
+<td >13.4</td>
+<td >223</td>
+<td >0.29</td>
+<td >Beijing.Haidian</td>
+<td >2</td>
+</tr>
+<tr>
+<td >d1001</td>
+<td >1538548695000</td>
+<td >12.6</td>
+<td >218</td>
+<td >0.33</td>
+<td >Beijing.Chaoyang</td>
+<td >2</td>
+</tr>
+<tr>
+<td >d1004</td>
+<td >1538548696600</td>
+<td >11.8</td>
+<td >221</td>
+<td >0.28</td>
+<td >Beijing.Haidian</td>
+<td >2</td>
+</tr>
+<tr>
+<td >d1002</td>
+<td >1538548696650</td>
+<td >10.3</td>
+<td >218</td>
+<td >0.25</td>
+<td >Beijing.Chaoyang</td>
+<td >3</td>
+</tr>
+<tr>
+<td >d1001</td>
+<td >1538548696800</td>
+<td >12.3</td>
+<td >221</td>
+<td >0.31</td>
+<td >Beijing.Chaoyang</td>
+<td >2</td>
+</tr>
+</tbody>
+</table>
+
+<center> <a href="#model_table1">表 1：智能电表数据示例</a></center>
+
+每一条记录都有设备 ID，时间戳，采集的物理量（如上图中的电流、电压、相位），还有与每个设备相关的静态标签（如上述表 1 中的位置 location 和分组 groupId）。每个设备是受外界的触发，或按照设定的周期采集数据。采集的数据点是时序的，是一个数据流。
+
+## 数据特征
+
+除时序特征外，仔细研究发现，物联网、车联网、运维监测类数据及其应用还具有很多其他明显的特征。
 
 1. 数据是结构化的；
 2. 数据极少有更新或删除操作；
@@ -30,41 +115,62 @@ title: 基本概念
 6. 用户关注的是一段时间的趋势，而不是某一特点时间点的值；
 7. 数据是有保留期限的；
 8. 数据的查询分析一定是基于时间段和地理区域的；
-9. 除存储查询外，还往往需要各种统计和实时计算操作；
+9. 系统需要各种实时计算和统计操作，包括降采样、插值等特种操作；
 10. 数据量巨大，一天采集的数据就可以超过 100 亿条。
 
 充分利用上述特征，TDengine 采取了一特殊的优化的存储和计算设计来处理时序数据，能将系统处理能力显著提高。
 
-## 数据采集点
+## 采集量(Metric)
+
+采集量是指传感器、设备或其他类型采集点采集的物理量，比如电流、电压、温度、压力、GPS位置等，是随时间变化的，数据类型可以是整型、浮点型、布尔型，也可是字符串。随着时间的推移，存储的采集量的数据量越来越大。
+
+## 标签(Label/Tag)
+
+标签是指传感器、设备或其他类型采集点的静态属性，不是随时间变化的，比如设备型号、颜色、设备的所在地等，数据类型可以是任何类型。虽然是静态的，但TDengine容许用户修改、删除或增加标签值。与采集量不一样的是，随时间的推移，存储的标签的数据量不会有什么变化。
+
+## 数据采集点(Data Colletion Point)
+
+数据采集点是指按照预设时间周期或受事件触发采集物理量的硬件或软件。一个数据采集点可以采集一个或多个物理量，**但这些物理量都是同一时刻采集的，具有相同的时间戳**。对于复杂的设备，往往有多个数据采集点，每个采集点采集的周期都可能不一样，而且完全独立，不同步。比如对于一台汽车，有数据采集点专门采集GPS位置，有数据采集点专门采集发动机状态，有数据采集点专门采集车内的环境，这样一台汽车就有三个数据采集点。
+
+## 关系型数据库模型
+
+因为采集的数据一般是结构化数据，同时为降低学习门槛，TDengine 采用传统的关系型数据库模型管理数据。用户需要先创建库，然后创建表，之后才能插入或查询数据。TDengine 采用的是结构化存储，而不是 NoSQL 的 key-value 存储。
+
+与通用数据库相比，TDengine通过一个数据采集点一张表，来大幅提高单个数据采集点的插入和查询速度。同时TDengine引入了超级表的概念，让每个表都带有标签，解决多个数据采集点之间的聚合分析问题。
 
-持续按照预设频率生成数据的软件或硬件设备称为数据采集点。TDengine中推荐一个数据采集点生成的数据存储在对应的一个或若干个表中。采集点产生的数据通常是包括时间戳、测量值、标签等必要信息构成的元组。
+## 一个数据采集点一张表
 
-## 采集量
+为充分利用其数据的时序性和其他数据特点，TDengine 要求**对每个数据采集点单独建表**（比如有一千万个智能电表，就需创建一千万张表，上述表格中的 d1001，d1002，d1003，d1004 都需单独建表），用来存储这个采集点所采集的时序数据。这种设计有几大优点：
 
-数据采集点生成的具有时间、测量值、标签的元组信息。除了时间戳、标签信息以外的测量值称为采集量。
+1. 由于不同采集设备产生数据的过程完全独立，每个设备的数据源是唯一的，一张表也就只有一个写入者，这样就可采用无锁方式来写，写入速度就能大幅提升。
+2. 对于一个数据采集点而言，其产生的数据是按照时间排序的，因此写的操作可用追加的方式实现，进一步大幅提高数据写入速度。
+3. 一个数据采集点的数据是以块为单位连续存储的。如果读取一个时间段的数据，它能大幅减少随机读取操作，成数量级的提升读取和查询速度。
+4. 一个数据块内部，采用列式存储，对于不同数据类型，采用不同压缩算法，而且由于一个数据采集点的采集量的变化是缓慢的，压缩率更高。
 
-## 标签
+如果采用传统的方式，将多个设备的数据写入一张表，由于网络延时不可控，不同设备的数据到达服务器的时序是无法保证的，写入操作是要有锁保护的，而且一个设备的数据是难以保证连续存储在一起的。**采用一个数据采集点一张表的方式，能最大程度的保证单个数据采集点的插入和查询的性能是最优的。**
 
-表的结构化描述信息，以一维数组形式存在。标签模式需要在创建超级表的时候指定，后续可动态调整。只有基于超级表创建的子表才具有标签。标签信息的内容首次创建子表的时候指定，并可按需调整。可以看到，TDengine中标签信息是表级别，而不是记录级别。
+TDengine 建议用数据采集点的名字（如上表中的 D1001）来做表名。每个数据采集点可能同时采集多个物理量（如上表中的 curent，voltage，phase），每个物理量对应一张表中的一列，数据类型可以是整型、浮点型、字符串等。除此之外，表的第一列必须是时间戳，即数据类型为 timestamp。对采集的数据，TDengine 将自动按照时间戳建立索引，但对采集的物理量不建任何索引。数据用列式存储方式保存。
 
-## 数据库
+对于复杂的设备，比如汽车，它有多个数据采集点，那么就需要为一台汽车建立多张表。
 
- TDengine中数据库与普通数据库管理系统中的数据库语义和行为相同，但是结合应用需求增加了若干配置参数用以控制其行为。
+## 超级表：同一类型数据采集点的集合
 
-## 超级表
+由于一个数据采集点一张表，导致表的数量巨增，难以管理，而且应用经常需要做采集点之间的聚合操作，聚合的操作也变得复杂起来。为解决这个问题，TDengine 引入超级表（Super Table，简称为 STable）的概念。
 
-超级表（Super Table, STable）是TDengine中一个重要的概念。超级表是面向相同数据模式的数据表，提供（数据+标签）模式管理和查询处理的逻辑抽象。通常将基于超级表创建的表称为该超级表的子表，并在系统内部建立逻辑关联。超级表与（基于其创建的）子表的关系体现在以下几个方面：
+超级表是指某一特定类型的数据采集点的集合。同一类型的数据采集点，其表的结构是完全一样的，但每个表（数据采集点）的静态属性（标签）是不一样的。描述一个超级表（某一特定类型的数据采集点的集合），除需要定义采集量的表结构之外，还需要定义其标签的 schema，标签的数据类型可以是整数、浮点数、字符串，标签可以有多个，可以事后增加、删除或修改。如果整个系统有 N 个不同类型的数据采集点，就需要建立 N 个超级表。
 
-超级表的子表共享其数据模式和标签模式。因此，不能通过子表调整数据或标签的模式。对于超级表的数据模式修改立即对所有的子表生效。
+在 TDengine 的设计里，**表用来代表一个具体的数据采集点，超级表用来代表一组相同类型的数据采集点集合**。当为某个具体数据采集点创建表时，用户使用超级表的定义做模板，同时指定该具体采集点（表）的标签值。与传统的关系型数据库相比，表（一个数据采集点）是带有静态标签的，而且这些标签可以事后增加、删除、修改。超级表与与基于超级表建立的子表之间的关系表现在：
 
-超级表自身不能存储任何数据或标签信息。因此，不能向一个超级表写入数据，只能将数据写入子表中。
+1. 一张超级表包含有多张子表，这些子表具有相同的采集量 schema，但带有不同的标签值。
+2. 不能通过子表调整数据或标签的模式，对于超级表的数据模式修改立即对所有的子表生效。
+3. 超级表只定义一个模板，自身不存储任何数据或标签信息。因此，不能向一个超级表写入数据，只能将数据写入子表中。
 
-针对超级表的查询，将所有子表中的数据视为一个整体数据集进行处理。但是可以直接发起针对某个或若干个子表的查询，此时查询请求将该子表视为一个普通的表进行处理。
+针对超级表的查询，TDengine将把所有子表中的数据视为一个整体数据集进行处理，会先把满足标签过滤条件的表从超级表中找出来，然后再扫描这些表的时序数据，进行聚合操作，这样需要扫描的数据集会大幅减少，从而显著提高查询的性能。本质上，TDengine通过对超级表查询的支持，实现了多个同类数据采集点的高效聚合。
 
-## 表
+## FQDN & End Point
 
-一系列二维数组的集合，用来代表和储存数据对象之间的关系，由纵向的列和横向的行组成。TDengine中的表与普通数据库中的表没有差别。
+FQDN (fully qualified domain name, 完全限定域名)是 Internet 上特定计算机或主机的完整域名。FQDN由两部分组成:主机名和域名。例如，假设邮件服务器的FQDN可能是mail.tdengine.com。主机名是mail，主机位于域名tdengine.com中。DNS(Domain Name System)，负责将FQDN翻译成IP，是互联网应用的寻址方式。对于没有DNS的系统，可以通过配置hosts文件来解决。
 
-但是，对于通过超级表创建的子表，还具有额外的标签数据信息。不能针对某个子表调整数据模式。每个子表具有与其关联的标签数据，并可按需调整内容。但是模式调整必须要通过超级表模式调整来完成。
+TDengine集群的每个节点是由End Point来唯一标识的，End Point是由 FQDN 外加 Port 组成，比如 h1.tdengine.com:6030。这样当IP发生变化的时候，我们依然可以使用 FQDN 来动态找到节点，不需要更改集群的任何配置。而且采用 FQDN，便于内网和外网对同一个集群的统一访问。
 
-使用TDengine存储和管理物联网数据的时候，推荐使用一个子表存储一个数据采集点生成的数据，而使用超级表用来代表一组相同类型的数据采集点的集合。
+TDengine 不建议采用直接的IP地址访问集群，不利于管理。不了解 FQDN 概念，请看博文[《一篇文章说清楚 TDengine 的 FQDN》](https://www.taosdata.com/blog/2020/09/11/1824.html)。

docs-cn/04-connect/index.mdx

@@ -14,21 +14,54 @@ import ConnCSNative from "./_connect_cs_native.mdx";
 import ConnC from "./_connect_c.mdx";
 import ConnR from "./_connect_r.mdx";
 
-TDengine 提高了多种编程语言的连接器方便用户开发应用程序。本节介绍如何使用连接器建立与 TDengine 的连接。
+TDengine 提供RESTful接口，容许在任何平台的任何应用程序通过它访问TDengine运行实例，详细介绍请看 [RESTful API](https://docs.taosdata.com/reference/restful-api/)。除RESTful之外，TDengine还提供多种编程语言的连接器方便用户开发应用程序，其中包括 C/C++、Java、Python、Go、Node.js、C# 、RESTful 等。 本节介绍如何使用连接器建立与 TDengine 的连接，给出连接器安装、连接的简单说明。关于各连接器的详细功能说明，请查看[连接器](https://docs.taosdata.com/reference/connector/)
 
 ## 连接器建立连接的方式
 
-连接器建立连接的方式，从本质上分为三种:
-  1. 通过 taosAdapter 组件提供的 RESTful API 建立连接。
-  2. 通过 taosAdapter 组件提供的 WebSocket API 建立连接（目前只有 Java 连接器支持）。
-  3. 通过客户端驱动程序直接与服务端程序 taosd 建立连接，这种连接方式下文中简称“本地连接”。
+连接器建立连接的方式，TDengine提供两种:
+  1. 通过 taosAdapter 组件提供的 RESTful API 建立与 taosd 的连接，这种连接方式下文中简称" 
+  2. 通过客户端驱动程序 taosc 直接与服务端程序 taosd 建立连接，这种连接方式下文中简称“本地连接”。
 
-无论使用何种方式建立连接，连接器都提供了相同或相似的 API 操作数据库，都可以执行 SQL 语句，只是初始化连接的方式稍有不同，用户在使用上不会感到太大差别。
+无论使用何种方式建立连接，连接器都提供了相同或相似的 API 操作数据库，都可以执行 SQL 语句，只是初始化连接的方式稍有不同，用户在使用上不会感到什么差别。
 
 关键不同点在于：
-1. 使用 RESTful 方式，用户无需安装客户端驱动程序，具有跨平台和易用的优势。
-2. WebSocket 方式可以看作对 RESTful 方式的优化，在批量拉取大量数据的场景具有性能优势。
-3. 使用本地连接可以体验 TDengine 的全部功能，如[原生接口写入](/reference/connector/cpp#参数绑定-api)、[订阅](reference/connector/cpp#数据订阅接口)等等。
+1. 使用 RESTful 方式，用户无需安装客户端驱动程序 taosc，具有跨平台易用的优势，但性能要下降30%左右。
+2. 使用本地连接可以体验 TDengine 的全部功能，如[原生接口写入](/reference/connector/cpp#参数绑定-api)、[订阅](reference/connector/cpp#数据订阅接口)等等。
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+import InstallOnWindows from "../14-reference/03-connector/_linux_install.mdx";
+import InstallOnLinux from "../14-reference/03-connector/_windows_install.mdx";
+import VerifyWindows from "../14-reference/03-connector/_verify_linux.mdx";
+import VerifyLinux from "../14-reference/03-connector/_verify_windows.mdx";
+
+## 安装客户端驱动taosc
+
+如果选择本地连接，而且应用程序不在TDengine同一台服务器上运行，你需要先安装客户端驱动，否则可以跳过此一步。为避免客户端驱动和服务端不兼容，请使用一致的版本
+
+### 安装步骤
+
+<Tabs defaultValue="linux" groupId="os">
+  <TabItem value="linux" label="Linux">
+    <InstallOnWindows />
+  </TabItem>
+  <TabItem value="windows" label="Windows">
+    <InstallOnLinux />
+  </TabItem>
+</Tabs>
+
+### 安装验证
+
+以上安装和配置完成后，并确认 TDengine 服务已经正常启动运行，此时可以执行 taos 客户端进行登录。
+
+<Tabs defaultValue="linux" groupId="os">
+  <TabItem value="linux" label="Linux">
+    <VerifyLinux />
+  </TabItem>
+  <TabItem value="windows" label="Windows">
+    <VerifyWindows />
+  </TabItem>
+</Tabs>
 
 ## 安装连接器
 
@@ -152,7 +185,7 @@ install.packages("RJDBC")
 
 ## 建立连接
 
-在执行这一步之前，请确保有一个正在运行的，且可以访问到的 TDengine。以下示例代码，都假设 TDengine 安装在本机，且 fqdn（默认 localhost） 和 serverPort（默认 6030） 都使用默认配置。
+在执行这一步之前，请确保有一个正在运行的，且可以访问到的 TDengine，而且服务端的FQDN配置正确。以下示例代码，都假设 TDengine 安装在本机，且 FQDN（默认 localhost） 和 serverPort（默认 6030） 都使用默认配置。
 
 <Tabs groupId="lang" defaultValue="java">
   <TabItem label="Java" value="java">
@@ -183,8 +216,7 @@ install.packages("RJDBC")
 </Tabs>
 
 :::tip
-在没有安装 TDengine 服务端程序的机器上建立本地连接，需要单独[安装客户端驱动](/reference/connector/#安装客户端驱动)。
-为避免客户端驱动和服务端不兼容，请尽量使用一致的版本。另外还要配置好[FQDN](https://www.taosdata.com/blog/2020/09/11/1824.html)。
+如果建立连接失败，大部分情况下是FQDN的配置不正确，详细的排查方法请看[常见问题及反馈](https://docs.taosdata.com/train-fqa/faq)中的“遇到错误Unable to establish connection, 我怎么办？”
 
 :::