diff --git a/docs-cn/01-index.md b/docs-cn/01-index.md new file mode 100644 index 0000000000000000000000000000000000000000..d2e6706892f3997af115e71d1da455ebce2ecbec --- /dev/null +++ b/docs-cn/01-index.md @@ -0,0 +1,25 @@ +--- +title: TDengine 文档 +sidebar_label: 文档首页 +slug: / +--- + +TDengine 是一款[高性能](https://www.taosdata.com/fast)、[分布式](https://www.taosdata.com/scalable)、[支持 SQL](https://www.taosdata.com/sql-support) 的时序数据库 (Database)。本文档是 TDengine 用户手册，主要是介绍 TDengine 的基本概念、安装、使用、功能、开发接口、运营维护、TDengine 内核设计等等，它主要是面向架构师、开发者与系统管理员的。 + +TDengine 充分利用了时序数据的特点，提出了“一个数据采集点一张表”与“超级表”的概念，设计了创新的存储引擎，让数据的写入、查询和存储效率都得到极大的提升。为正确理解并使用TDengine, 无论如何，请您仔细阅读[基本概念](./concept)一章。 + +如果你是开发者，请一定仔细阅读[开发指南](./develop)一章，该部分对数据库连接、建模、插入数据、查询、连续查询、缓存、数据订阅、用户自定义函数等功能都做了详细介绍，并配有各种编程语言的示例代码。大部分情况下，你只要把示例代码拷贝粘贴，针对自己的应用稍作改动，就能跑起来。 + +我们已经生活在大数据的时代，纵向扩展已经无法满足日益增长的业务需求，任何系统都必须具有水平扩展的能力，集群成为大数据以及 database 系统的不可缺失功能。TDengine 团队不仅实现了集群功能，而且将这一重要核心功能开源。怎么部署、管理和维护 TDengine 集群，请参考[集群管理](./cluster)一章。 + +TDengine 采用 SQL 作为其查询语言，大大降低学习成本、降低迁移成本，但同时针对时序数据场景，又做了一些扩展，以支持插值、降采样、时间加权平均等操作。[SQL 手册](./taos-sql)一章详细描述了 SQL 语法、详细列出了各种支持的命令和函数。 + +如果你是系统管理员，关心安装、升级、容错灾备、关心数据导入、导出，配置参数，怎么监测 TDengine 是否健康运行，怎么提升系统运行的性能，那么请仔细参考[运维指南](./operation)一章。 + +如果你对 TDengine 外围工具，REST API, 各种编程语言的连接器想做更多详细了解，请看[参考指南](./reference)一章。 + +如果你对 TDengine 内部的架构设计很有兴趣，欢迎仔细阅读[技术内幕](./tdinternal)一章，里面对集群的设计、数据分区、分片、写入、读出、查询、聚合查询的流程都做了详细的介绍。如果你想研读 TDengine 代码甚至贡献代码，请一定仔细读完这一章。 + +最后，作为一个开源软件，欢迎大家的参与。如果发现文档的任何错误，描述不清晰的地方，都请在每个页面的最下方，点击“编辑本文档“直接进行修改。 + +Together, we make a difference! diff --git a/docs-cn/02-intro.md b/docs-cn/02-intro.md new file mode 100644 index 0000000000000000000000000000000000000000..2a56c5e9e667b511003b1ee08801ddcb54ff2ec4 --- /dev/null +++ b/docs-cn/02-intro.md @@ -0,0 +1,125 @@ +--- +title: 产品简介 +toc_max_heading_level: 2 +--- + +TDengine 是一款高性能、分布式、支持 SQL 的时序数据库 (Database)，其核心代码，包括集群功能全部开源（开源协议，AGPL v3.0）。TDengine 能被广泛运用于物联网、工业互联网、车联网、IT 运维、金融等领域。除核心的时序数据库 (Database) 功能外，TDengine 还提供[缓存](/develop/cache/)、[数据订阅](/develop/subscribe)、[流式计算](/develop/continuous-query)等大数据平台所需要的系列功能，最大程度减少研发和运维的复杂度。 + +本章节介绍TDengine的主要功能、竞争优势、适用场景、与其他数据库的对比测试等等，让大家对TDengine有个整体的了解。 + +## 主要功能 + +TDengine的主要功能如下： + +1. 高速数据写入，除 [SQL 写入](/develop/insert-data/sql-writing)外，还支持 [Schemaless 写入](/reference/schemaless/)，支持 [InfluxDB LINE 协议](/develop/insert-data/influxdb-line)，[OpenTSDB Telnet](/develop/insert-data/opentsdb-telnet), [OpenTSDB JSON ](/develop/insert-data/opentsdb-json)等协议写入； +2. 第三方数据采集工具 [Telegraf](/third-party/telegraf)，[Prometheus](/third-party/prometheus)，[StatsD](/third-party/statsd)，[collectd](/third-party/collectd)，[icinga2](/third-party/icinga2), [TCollector](/third-party/tcollector), [EMQ](/third-party/emq-broker), [HiveMQ](/third-party/hive-mq-broker) 等都可以进行配置后，不用任何代码，即可将数据写入； +3. 支持[各种查询](/develop/query-data),包括聚合查询、嵌套查询、降采样查询、插值等 +4. 支持[用户自定义函数](/develop/udf) +5. 支持[缓存](/develop/cache)，将每张表的最后一条记录缓存起来，这样无需 Redis +6. 支持[连续查询](/develop/continuous-query)(Continuous Query) +7. 支持[数据订阅](/develop/subscribe)，而且可以指定过滤条件 +8. 支持[集群](/cluster/)，可以通过多节点进行水平扩展，并通过多副本实现高可靠 +9. 提供[命令行程序](/reference/taos-shell)，便于管理集群，检查系统状态，做即席查询 +10. 提供多种数据的[导入](/operation/import)、[导出](/operation/export) +11. 支持对[TDengine 集群本身的监控](/operation/monitor) +12. 提供 [C/C++](/reference/connector/cpp), [Java](/reference/connector/java), [Python](/reference/connector/python), [Go](/reference/connector/go), [Rust](/reference/connector/rust), [Node.js](/reference/connector/node) 等多种编程语言的[连接器](/reference/connector/) +13. 支持 [REST 接口](/reference/rest-api/) +14. 支持与[ Grafana 无缝集成](/third-party/grafana) +15. 支持与 Google Data Studio 无缝集成 + +更多细小的功能，请阅读整个文档。 + +## 竞争优势 + +由于 TDengine 充分利用了[时序数据特点](https://www.taosdata.com/blog/2019/07/09/105.html)，比如结构化、无需事务、很少删除或更新、写多读少等等，设计了全新的针对时序数据的存储引擎和计算引擎，因此与其他时序数据库相比，TDengine 有以下特点： + +- **[高性能](https://www.taosdata.com/fast)**：通过创新的存储引擎设计，无论是数据写入还是查询，TDengine 的性能比通用数据库快 10 倍以上，也远超其他时序数据库，而且存储空间也大为节省。 + +- **[分布式](https://www.taosdata.com/scalable)**：通过原生分布式的设计，TDengine 提供了水平扩展的能力，只需要增加节点就能获得更强的数据处理能力，同时通过多副本机制保证了系统的高可用。 + +- **[支持 SQL](https://www.taosdata.com/sql-support)**：TDengine 采用 SQL 作为数据查询语言，减少学习和迁移成本，同时提供 SQL 扩展来处理时序数据特有的分析，而且支持方便灵活的 schemaless 数据写入。 + +- **All in One**：将数据库、消息队列、缓存、流式计算等功能融合一起，应用无需再集成 Kafka/Redis/HBase/Spark 等软件，大幅降低应用开发和维护成本。 + +- **零管理**：安装、集群几秒搞定，无任何依赖，不用分库分表，系统运行状态监测能与 Grafana 或其他运维工具无缝集成。 + +- **零学习成本**：采用 SQL 查询语言，支持 C/C++、Python、Java、Go、Rust、Node.js、C#、Lua（社区贡献）、PHP（社区贡献） 等多种编程语言,与 MySQL 相似，零学习成本。 + +- **无缝集成**：不用一行代码，即可与 Telegraf、Grafana、Prometheus、EMQX、HiveMQ、StatsD、collectd、icinga、TCollector、Matlab、R 等第三方工具无缝集成。 + +- **互动 Console**: 通过命令行 console，不用编程，执行 SQL 语句就能做即席查询、各种数据库的操作、管理以及集群的维护. + +采用 TDengine，可将典型的物联网、车联网、工业互联网大数据平台的总拥有成本大幅降低。表现在几个方面： + +1. 由于其超强性能，它能将系统需要的计算资源和存储资源大幅降低 +2. 因为采用 SQL 接口，能与众多第三放软件无缝集成，学习迁移成本大幅下降 +3. 因为其 All In One 的特性，系统复杂度降低，能降研发成本 +4. 因为运维维护简单，运营维护成本能大幅降低 + +## 技术生态 + +在整个时序大数据平台中，TDengine 在其中扮演的角色如下： + +
+ +![TDengine技术生态图](eco_system.png) + +
+
图 1. TDengine技术生态图
+ +上图中，左侧是各种数据采集或消息队列，包括 OPC-UA、MQTT、Telegraf、也包括 Kafka, 他们的数据将被源源不断的写入到 TDengine。右侧则是可视化、BI 工具、组态软件、应用程序。下侧则是 TDengine 自身提供的命令行程序 (CLI) 以及可视化管理管理。 + +## 总体适用场景 + +作为一个高性能、分布式、支持 SQL 的时序数据库 （Database)，TDengine 的典型适用场景包括但不限于 IoT、工业互联网、车联网、IT 运维、能源、金融证券等领域。需要指出的是，TDengine 是针对时序数据场景设计的专用数据库和专用大数据处理工具，因充分利用了时序大数据的特点，它无法用来处理网络爬虫、微博、微信、电商、ERP、CRM 等通用型数据。本文对适用场景做更多详细的分析。 + +### 数据源特点和需求 + +从数据源角度，设计人员可以从下面几个角度分析 TDengine 在目标应用系统里面的适用性。 + +| 数据源特点和需求 | 不适用 | 可能适用 | 非常适用 | 简单说明 | +| ---------------------------- | ------ | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- | +| 总体数据量巨大 | | | √ | TDengine 在容量方面提供出色的水平扩展功能，并且具备匹配高压缩的存储结构，达到业界最优的存储效率。 | +| 数据输入速度偶尔或者持续巨大 | | | √ | TDengine 的性能大大超过同类产品，可以在同样的硬件环境下持续处理大量的输入数据，并且提供很容易在用户环境里面运行的性能评估工具。 | +| 数据源数目巨大 | | | √ | TDengine 设计中包含专门针对大量数据源的优化，包括数据的写入和查询，尤其适合高效处理海量（千万或者更多量级）的数据源。 | + +### 系统架构要求 + +| 系统架构要求 | 不适用 | 可能适用 | 非常适用 | 简单说明 | +| ---------------------- | ------ | -------- | -------- | ----------------------------------------------------------------------------------------------------- | +| 要求简单可靠的系统架构 | | | √ | TDengine 的系统架构非常简单可靠，自带消息队列，缓存，流式计算，监控等功能，无需集成额外的第三方产品。 | +| 要求容错和高可靠 | | | √ | TDengine 的集群功能，自动提供容错灾备等高可靠功能。 | +| 标准化规范 | | | √ | TDengine 使用标准的 SQL 语言提供主要功能，遵守标准化规范。 | + +### 系统功能需求 + +| 系统功能需求 | 不适用 | 可能适用 | 非常适用 | 简单说明 | +| -------------------------- | ------ | -------- | -------- | --------------------------------------------------------------------------------------------------------------------- | +| 要求完整的内置数据处理算法 | | √ | | TDengine 的实现了通用的数据处理算法，但是还没有做到妥善处理各行各业的所有要求，因此特殊类型的处理还需要应用层面处理。 | +| 需要大量的交叉查询处理 | | √ | | 这种类型的处理更多应该用关系型数据系统处理，或者应该考虑 TDengine 和关系型数据系统配合实现系统功能。 | + +### 系统性能需求 + +| 系统性能需求 | 不适用 | 可能适用 | 非常适用 | 简单说明 | +| ---------------------- | ------ | -------- | -------- | ------------------------------------------------------------------------------------------------------ | +| 要求较大的总体处理能力 | | | √ | TDengine 的集群功能可以轻松地让多服务器配合达成处理能力的提升。 | +| 要求高速处理数据 | | | √ | TDengine 的专门为 IoT 优化的存储和数据处理的设计，一般可以让系统得到超出同类产品多倍数的处理速度提升。 | +| 要求快速处理小粒度数据 | | | √ | 这方面 TDengine 性能可以完全对标关系型和 NoSQL 型数据处理系统。 | + +### 系统维护需求 + +| 系统维护需求 | 不适用 | 可能适用 | 非常适用 | 简单说明 | +| ---------------------- | ------ | -------- | -------- | --------------------------------------------------------------------------------------------------------------------- | +| 要求系统可靠运行 | | | √ | TDengine 的系统架构非常稳定可靠，日常维护也简单便捷，对维护人员的要求简洁明了，最大程度上杜绝人为错误和事故。 | +| 要求运维学习成本可控 | | | √ | 同上。 | +| 要求市场有大量人才储备 | √ | | | TDengine 作为新一代产品，目前人才市场里面有经验的人员还有限。但是学习成本低，我们作为厂家也提供运维的培训和辅助服务。 | + +## 与其他数据库的对比测试 + +- [用 InfluxDB 开源的性能测试工具对比 InfluxDB 和 TDengine](https://www.taosdata.com/blog/2020/01/13/1105.html) +- [TDengine 与 OpenTSDB 对比测试](https://www.taosdata.com/blog/2019/08/21/621.html) +- [TDengine 与 Cassandra 对比测试](https://www.taosdata.com/blog/2019/08/14/573.html) +- [TDengine 与 InfluxDB 对比测试](https://www.taosdata.com/blog/2019/07/19/419.html) +- [TDengine VS InfluxDB ，写入性能大 PK ！](https://www.taosdata.com/2021/11/05/3248.html) +- [TDengine 和 InfluxDB 查询性能对比测试报告](https://www.taosdata.com/2022/02/22/5969.html) +- [TDengine 与 InfluxDB、OpenTSDB、Cassandra、MySQL、ClickHouse 等数据库的对比测试报告](https://www.taosdata.com/downloads/TDengine_Testing_Report_cn.pdf) diff --git a/docs-cn/04-concept/_category_.yml b/docs-cn/04-concept/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..aad75dce21f63a6510bc0b8da4c93952767adfdf --- /dev/null +++ b/docs-cn/04-concept/_category_.yml @@ -0,0 +1 @@ +label: 基本概念 \ No newline at end of file diff --git a/docs-cn/04-concept/index.md b/docs-cn/04-concept/index.md new file mode 100644 index 0000000000000000000000000000000000000000..ca25595260953f8d941ccaf367bdc45a8325488f --- /dev/null +++ b/docs-cn/04-concept/index.md @@ -0,0 +1,173 @@ +--- +title: 数据模型和基本概念 +--- + +为了便于解释基本概念，便于撰写示例程序，整个 TDengine 文档以智能电表作为典型时序数据场景。假设每个智能电表采集电流、电压、相位三个量，有多个智能电表，每个电表有位置 location 和分组 group ID 的静态属性. 其采集的数据类似如下的表格： + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Device IDTime StampCollected MetricsTags
Device IDTime StampcurrentvoltagephaselocationgroupId
d1001153854868500010.32190.31Beijing.Chaoyang2
d1002153854868400010.22200.23Beijing.Chaoyang3
d1003153854868650011.52210.35Beijing.Haidian3
d1004153854868550013.42230.29Beijing.Haidian2
d1001153854869500012.62180.33Beijing.Chaoyang2
d1004153854869660011.82210.28Beijing.Haidian2
d1002153854869665010.32180.25Beijing.Chaoyang3
d1001153854869680012.32210.31Beijing.Chaoyang2
+表 1：智能电表数据示例 +
+ +每一条记录都有设备 ID，时间戳，采集的物理量以及每个设备相关的静态标签。每个设备是受外界的触发，或按照设定的周期采集数据。采集的数据点是时序的，是一个数据流。 + +## 采集量 (Metric) + +采集量是指传感器、设备或其他类型采集点采集的物理量，比如电流、电压、温度、压力、GPS 位置等，是随时间变化的，数据类型可以是整型、浮点型、布尔型，也可是字符串。随着时间的推移，存储的采集量的数据量越来越大。 + +## 标签 (Label/Tag) + +标签是指传感器、设备或其他类型采集点的静态属性，不是随时间变化的，比如设备型号、颜色、设备的所在地等，数据类型可以是任何类型。虽然是静态的，但 TDengine 容许用户修改、删除或增加标签值。与采集量不一样的是，随时间的推移，存储的标签的数据量不会有什么变化。 + +## 数据采集点 (Data Collection Point) + +数据采集点是指按照预设时间周期或受事件触发采集物理量的硬件或软件。一个数据采集点可以采集一个或多个采集量，**但这些采集量都是同一时刻采集的，具有相同的时间戳**。对于复杂的设备，往往有多个数据采集点，每个数据采集点采集的周期都可能不一样，而且完全独立，不同步。比如对于一台汽车，有数据采集点专门采集 GPS 位置，有数据采集点专门采集发动机状态，有数据采集点专门采集车内的环境，这样一台汽车就有三个数据采集点。 + +## 表 (Table) + +因为采集量一般是结构化数据，同时为降低学习门槛，TDengine 采用传统的关系型数据库模型管理数据。用户需要先创建库，然后创建表，之后才能插入或查询数据。 + +为充分利用其数据的时序性和其他数据特点，TDengine 采取**一个数据采集点一张表**的策略，要求对每个数据采集点单独建表（比如有一千万个智能电表，就需创建一千万张表，上述表格中的 d1001，d1002，d1003，d1004 都需单独建表），用来存储这个数据采集点所采集的时序数据。这种设计有几大优点： + +1. 由于不同数据采集点产生数据的过程完全独立，每个数据采集点的数据源是唯一的，一张表也就只有一个写入者，这样就可采用无锁方式来写，写入速度就能大幅提升。 +2. 对于一个数据采集点而言，其产生的数据是按照时间排序的，因此写的操作可用追加的方式实现，进一步大幅提高数据写入速度。 +3. 一个数据采集点的数据是以块为单位连续存储的。如果读取一个时间段的数据，它能大幅减少随机读取操作，成数量级的提升读取和查询速度。 +4. 一个数据块内部，采用列式存储，对于不同数据类型，采用不同压缩算法，而且由于一个数据采集点的采集量的变化是缓慢的，压缩率更高。 + +如果采用传统的方式，将多个数据采集点的数据写入一张表，由于网络延时不可控，不同数据采集点的数据到达服务器的时序是无法保证的，写入操作是要有锁保护的，而且一个数据采集点的数据是难以保证连续存储在一起的。**采用一个数据采集点一张表的方式，能最大程度的保证单个数据采集点的插入和查询的性能是最优的。** + +TDengine 建议用数据采集点的名字（如上表中的 D1001）来做表名。每个数据采集点可能同时采集多个采集量（如上表中的 current，voltage，phase），每个采集量对应一张表中的一列，数据类型可以是整型、浮点型、字符串等。除此之外，表的第一列必须是时间戳，即数据类型为 timestamp。对采集量，TDengine 将自动按照时间戳建立索引，但对采集量本身不建任何索引。数据用列式存储方式保存。 + +对于复杂的设备，比如汽车，它有多个数据采集点，那么就需要为一台汽车建立多张表。 + +## 超级表 (STable) + +由于一个数据采集点一张表，导致表的数量巨增，难以管理，而且应用经常需要做采集点之间的聚合操作，聚合的操作也变得复杂起来。为解决这个问题，TDengine 引入超级表（Super Table，简称为 STable）的概念。 + +超级表是指某一特定类型的数据采集点的集合。同一类型的数据采集点，其表的结构是完全一样的，但每个表（数据采集点）的静态属性（标签）是不一样的。描述一个超级表（某一特定类型的数据采集点的集合），除需要定义采集量的表结构之外，还需要定义其标签的 schema，标签的数据类型可以是整数、浮点数、字符串，标签可以有多个，可以事后增加、删除或修改。如果整个系统有 N 个不同类型的数据采集点，就需要建立 N 个超级表。 + +在 TDengine 的设计里，**表用来代表一个具体的数据采集点，超级表用来代表一组相同类型的数据采集点集合**。 + +## 子表 (Subtable) + +当为某个具体数据采集点创建表时，用户可以使用超级表的定义做模板，同时指定该具体采集点（表）的具体标签值来创建该表。**通过超级表创建的表称之为子表**。正常的表与子表的差异在于： + +1. 子表就是表，因此所有正常表的SQL操作都可以在子表上执行。 +2. 子表在正常表的基础上有扩展，它是带有静态标签的，而且这些标签可以事后增加、删除、修改，而正常的表没有。 +3. 子表一定属于一张超级表，但普通表不属于任何超级表 +4. 普通表无法转为子表，子表也无法转为普通表。 + +超级表与与基于超级表建立的子表之间的关系表现在： + +1. 一张超级表包含有多张子表，这些子表具有相同的采集量 schema，但带有不同的标签值。 +2. 不能通过子表调整数据或标签的模式，对于超级表的数据模式修改立即对所有的子表生效。 +3. 超级表只定义一个模板，自身不存储任何数据或标签信息。因此，不能向一个超级表写入数据，只能将数据写入子表中。 + +查询既可以在表上进行，也可以在超级表上进行。针对超级表的查询，TDengine 将把所有子表中的数据视为一个整体数据集进行处理，会先把满足标签过滤条件的表从超级表中找出来，然后再扫描这些表的时序数据，进行聚合操作，这样需要扫描的数据集会大幅减少，从而显著提高查询的性能。本质上，TDengine 通过对超级表查询的支持，实现了多个同类数据采集点的高效聚合。 + +TDengine系统建议给一个数据采集点建表，需要通过超级表建表，而不是建普通表。 + +## 库 (database) + +库是指一组表的集合。TDengine 容许一个运行实例有多个库，而且每个库可以配置不同的存储策略。不同类型的数据采集点往往具有不同的数据特征，包括数据采集频率的高低，数据保留时间的长短，副本的数目，数据块的大小，是否允许更新数据等等。为了在各种场景下 TDengine 都能最大效率的工作，TDengine 建议将不同数据特征的超级表创建在不同的库里。 + +一个库里，可以有一到多个超级表，但一个超级表只属于一个库。一个超级表所拥有的子表全部存在一个库里。 + +## FQDN & End Point + +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 不建议采用直接的 IP 地址访问集群，不利于管理。不了解 FQDN 概念，请看博文[《一篇文章说清楚 TDengine 的 FQDN》](https://www.taosdata.com/blog/2020/09/11/1824.html)。 diff --git a/docs-cn/05-get-started/_apt_get_install.mdx b/docs-cn/05-get-started/_apt_get_install.mdx new file mode 100644 index 0000000000000000000000000000000000000000..b1bc4a13517bbfdc9eda86a58b89aee8e41fa470 --- /dev/null +++ b/docs-cn/05-get-started/_apt_get_install.mdx @@ -0,0 +1,26 @@ +可以使用 apt-get 工具从官方仓库安装。 + +**安装包仓库** + +``` +wget -qO - http://repos.taosdata.com/tdengine.key | sudo apt-key add - +echo "deb [arch=amd64] http://repos.taosdata.com/tdengine-stable stable main" | sudo tee /etc/apt/sources.list.d/tdengine-stable.list +``` + +如果安装 Beta 版需要安装包仓库 + +``` +echo "deb [arch=amd64] http://repos.taosdata.com/tdengine-beta beta main" | sudo tee /etc/apt/sources.list.d/tdengine-beta.list +``` + +**使用 apt-get 命令安装** + +``` +sudo apt-get update +apt-cache policy tdengine +sudo apt-get install tdengine +``` + +:::tip +apt-get 方式只适用于 Debian 或 Ubuntu 系统 +:::: diff --git a/docs-cn/05-get-started/_category_.yml b/docs-cn/05-get-started/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..b2348fade63c7bb717eac3e6e6b8dfda3c73b17a --- /dev/null +++ b/docs-cn/05-get-started/_category_.yml @@ -0,0 +1 @@ +label: 立即开始 diff --git a/docs-cn/05-get-started/_pkg_install.mdx b/docs-cn/05-get-started/_pkg_install.mdx new file mode 100644 index 0000000000000000000000000000000000000000..83c987af8bcf24a9593105b680d32a0421344d5f --- /dev/null +++ b/docs-cn/05-get-started/_pkg_install.mdx @@ -0,0 +1,17 @@ +import PkgList from "/components/PkgList"; + +TDengine 的安装非常简单，从下载到安装成功仅仅只要几秒钟。 + +为方便使用，从 2.4.0.10 开始，标准的服务端安装包包含了 taos、taosd、taosAdapter、taosdump、taosBenchmark、TDinsight 安装脚本和示例代码；如果您只需要用到服务端程序和客户端连接的 C/C++ 语言支持，也可以仅下载 lite 版本的安装包。 + +在安装包格式上，我们提供 tar.gz, rpm 和 deb 格式，为企业客户提供 tar.gz 格式安装包，以方便在特定操作系统上使用。需要注意的是，rpm 和 deb 包不含 taosdump、taosBenchmark 和 TDinsight 安装脚本，这些工具需要通过安装 taosTool 包获得。 + +发布版本包括稳定版和 Beta 版，Beta 版含有更多新功能。正式上线或测试建议安装稳定版。您可以根据需要选择下载： + + + +具体的安装方法，请参见[安装包的安装和卸载](/operation/pkg-install)。 + +下载其他组件、最新 Beta 版及之前版本的安装包，请点击[这里](https://www.taosdata.com/all-downloads) + +查看 Release Notes, 请点击[这里](https://github.com/taosdata/TDengine/releases) diff --git a/docs-cn/05-get-started/index.md b/docs-cn/05-get-started/index.md new file mode 100644 index 0000000000000000000000000000000000000000..458df909166b9769af2052ba654699e869d2081c --- /dev/null +++ b/docs-cn/05-get-started/index.md @@ -0,0 +1,173 @@ +--- +title: 立即开始 +description: '从 Docker，安装包或使用 apt-get 快速安装 TDengine, 通过命令行程序TAOS CLI和工具 taosdemo 快速体验 TDengine 功能' +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import PkgInstall from "./\_pkg_install.mdx"; +import AptGetInstall from "./\_apt_get_install.mdx"; + +## 安装 + +TDengine 完整的软件包包括服务端（taosd）、用于与第三方系统对接并提供 RESTful 接口的 taosAdapter、应用驱动（taosc）、命令行程序 (CLI，taos) 和一些工具软件，目前 2.X 版服务端 taosd 和 taosAdapter 仅在 Linux 系统上安装和运行，后续将支持 Windows、macOS 等系统。应用驱动 taosc 与 TDengine CLI 可以在 Windows 或 Linux 上安装和运行。TDengine 除了提供多种语言的连接器之外，还通过 [taosAdapter](/reference/taosadapter) 提供 [RESTful 接口](/reference/rest-api)。但在 2.4 之前的版本中没有 taosAdapter，RESTful 接口是由 taosd 内置的 HTTP 服务提供的。 + +TDengine 支持 X64/ARM64/MIPS64/Alpha64 硬件平台，后续将支持 ARM32、RISC-V 等 CPU 架构。 + + + +如果已经安装了 docker， 只需执行下面的命令。 + +```shell +docker run -d -p 6030-6049:6030-6049 -p 6030-6049:6030-6049/udp tdengine/tdengine +``` + +确定该容器已经启动并且在正常运行 + +```shell +docker ps +``` + +进入该容器并执行 bash + +```shell +docker exec -it bash +``` + +然后就可以执行相关的 Linux 命令操作和访问 TDengine + +详细操作方法请参照 [通过 Docker 快速体验 TDengine](/train-faq/docker)。 + +:::info +从 2.4.0.10 开始，除 taosd 以外，Docker 镜像还包含：taos、taosAdapter、taosdump、taosBenchmark、TDinsight 安装脚本和示例代码。启动 Docker 容器时，将同时启动 taosAdapter 和 taosd，实现对 RESTful 的支持。 + +::: + + + + + + + + + + +如果您希望对 TDengine 贡献代码或对内部实现感兴趣，请参考我们的 [TDengine GitHub 主页](https://github.com/taosdata/TDengine) 下载源码构建和安装. + +下载其他组件、最新 Beta 版及之前版本的安装包，请点击[这里](https://www.taosdata.com/cn/all-downloads/)。 + + + + +## 启动 + +安装后，请使用 `systemctl` 命令来启动 TDengine 的服务进程。 + +```bash +systemctl start taosd +``` + +检查服务是否正常工作： + +```bash +systemctl status taosd +``` + +如果 TDengine 服务正常工作，那么您可以通过 TDengine 的命令行程序 `taos` 来访问并体验 TDengine。 + +:::info + +- systemctl 命令需要 _root_ 权限来运行，如果您非 _root_ 用户，请在命令前添加 sudo 。 +- 为更好的获得产品反馈，改善产品，TDengine 会采集基本的使用信息，但您可以修改系统配置文件 taos.cfg 里的配置参数 telemetryReporting，将其设为 0，就可将其关闭。 +- TDengine 采用 FQDN（一般就是 hostname）作为节点的 ID，为保证正常运行，需要给运行 taosd 的服务器配置好 FQDN，在 TDengine CLI 或应用运行的机器配置好 DNS 服务或 hosts 文件，保证 FQDN 能够解析。 +- `systemctl stop taosd` 指令在执行后并不会马上停止 TDengine 服务，而是会等待系统中必要的落盘工作正常完成。在数据量很大的情况下，这可能会消耗较长时间。 + +TDengine 支持在使用 [`systemd`](https://en.wikipedia.org/wiki/Systemd) 做进程服务管理的 Linux 系统上安装，用 `which systemctl` 命令来检测系统中是否存在 `systemd` 包: + +```bash +which systemctl +``` + +如果系统中不支持 `systemd`，也可以用手动运行 `/usr/local/taos/bin/taosd` 方式启动 TDengine 服务。 + +:::note + +## TDengine 命令行 (CLI) + +为便于检查 TDengine 的状态，执行数据库 (Database) 的各种即席(Ad Hoc)查询，TDengine 提供一命令行应用程序(以下简称为 TDengine CLI) taos。要进入 TDengine 命令行，您只要在安装有 TDengine 的 Linux 终端执行 `taos` 即可。 + +```bash +taos +``` + +如果连接服务成功，将会打印出欢迎消息和版本信息。如果失败，则会打印错误消息出来（请参考 [FAQ](/train-faq/faq) 来解决终端连接服务端失败的问题）。 TDengine CLI 的提示符号如下： + +```cmd +taos> +``` + +在 TDengine CLI 中，用户可以通过 SQL 命令来创建/删除数据库、表等，并进行数据库(database)插入查询操作。在终端中运行的 SQL 语句需要以分号结束来运行。示例： + +```sql +create database demo; +use demo; +create table t (ts timestamp, speed int); +insert into t values ('2019-07-15 00:00:00', 10); +insert into t values ('2019-07-15 01:00:00', 20); +select * from t; + ts | speed | +======================================== + 2019-07-15 00:00:00.000 | 10 | + 2019-07-15 01:00:00.000 | 20 | +Query OK, 2 row(s) in set (0.003128s) +``` + +除执行 SQL 语句外，系统管理员还可以从 TDengine CLI 进行检查系统运行状态、添加删除用户账号等操作。TAOS CLI 连同应用驱动也可以独立安装在 Linux 或 Windows 机器上运行，更多细节请参考 [这里](../reference/taos-shell/) + +## 使用 taosBenchmark 体验写入速度 + +启动 TDengine 的服务，在 Linux 终端执行 `taosBenchmark` （曾命名为 `taosdemo`）： + +```bash +taosBenchmark +``` + +该命令将在数据库 test 下面自动创建一张超级表 meters，该超级表下有 1 万张表，表名为 "d0" 到 "d9999"，每张表有 1 万条记录，每条记录有 (ts, current, voltage, phase) 四个字段，时间戳从 "2017-07-14 10:40:00 000" 到 "2017-07-14 10:40:09 999"，每张表带有标签 location 和 groupId，groupId 被设置为 1 到 10， location 被设置为 "beijing" 或者 "shanghai"。 + +这条命令很快完成 1 亿条记录的插入。具体时间取决于硬件性能，即使在一台普通的 PC 服务器往往也仅需十几秒。 + +taosBenchmark 命令本身带有很多选项，配置表的数目、记录条数等等，您可以设置不同参数进行体验，请执行 `taosBenchmark --help` 详细列出。taosBenchmark 详细使用方法请参照 [如何使用 taosBenchmark 对 TDengine 进行性能测试](https://www.taosdata.com/2021/10/09/3111.html)。 + +## 使用 TDengine CLI 体验查询速度 + +使用上述 taosBenchmark 插入数据后，可以在 TDengine CLI 输入查询命令，体验查询速度。 + +查询超级表下记录总条数： + +```sql +taos> select count(*) from test.meters; +``` + +查询 1 亿条记录的平均值、最大值、最小值等： + +```sql +taos> select avg(current), max(voltage), min(phase) from test.meters; +``` + +查询 location="beijing" 的记录总条数： + +```sql +taos> select count(*) from test.meters where location="beijing"; +``` + +查询 groupId=10 的所有记录的平均值、最大值、最小值等： + +```sql +taos> select avg(current), max(voltage), min(phase) from test.meters where groupId=10; +``` + +对表 d10 按 10s 进行平均值、最大值和最小值聚合统计： + +```sql +taos> select avg(current), max(voltage), min(phase) from test.d10 interval(10s); +``` diff --git a/docs-cn/07-develop/01-connect/_category_.yml b/docs-cn/07-develop/01-connect/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..f75d563ac9e061f8b8d66392031413f4051e351e --- /dev/null +++ b/docs-cn/07-develop/01-connect/_category_.yml @@ -0,0 +1 @@ +label: 建立连接 diff --git a/docs-cn/07-develop/01-connect/_connect_c.mdx b/docs-cn/07-develop/01-connect/_connect_c.mdx new file mode 100644 index 0000000000000000000000000000000000000000..9cd8669561195b49e8428ed490ad97bb5653ae6a --- /dev/null +++ b/docs-cn/07-develop/01-connect/_connect_c.mdx @@ -0,0 +1,3 @@ +```c title="原生连接" +{{#include docs-examples/c/connect_example.c}} +``` diff --git a/docs-cn/07-develop/01-connect/_connect_cs.mdx b/docs-cn/07-develop/01-connect/_connect_cs.mdx new file mode 100644 index 0000000000000000000000000000000000000000..821820e8fe1d87a35e01943530179eeb6e0f48be --- /dev/null +++ b/docs-cn/07-develop/01-connect/_connect_cs.mdx @@ -0,0 +1,8 @@ +```csharp title="原生连接" +{{#include docs-examples/csharp/ConnectExample.cs}} +``` + +:::info +C# 连接器目前只支持原生连接。 + +::: diff --git a/docs-cn/07-develop/01-connect/_connect_go.mdx b/docs-cn/07-develop/01-connect/_connect_go.mdx new file mode 100644 index 0000000000000000000000000000000000000000..478768caaacc8aceb9a3f5a85f008dde00125eb7 --- /dev/null +++ b/docs-cn/07-develop/01-connect/_connect_go.mdx @@ -0,0 +1,17 @@ +#### 使用数据库访问统一接口 + +```go title="原生连接" +{{#include docs-examples/go/connect/cgoexample/main.go}} +``` + +```go title="REST 连接" +{{#include docs-examples/go/connect/restexample/main.go}} +``` + +#### 使用高级封装 + +也可以使用 driver-go 的 af 包建立连接。这个模块封装了 TDengine 的高级功能, 如：参数绑定、订阅等。 + +```go title="使用 af 包建立原生连接" +{{#include docs-examples/go/connect/afconn/main.go}} +``` diff --git a/docs-cn/07-develop/01-connect/_connect_java.mdx b/docs-cn/07-develop/01-connect/_connect_java.mdx new file mode 100644 index 0000000000000000000000000000000000000000..635f39ceb28ffc3fd0b0d8edb057d9aa01c593de --- /dev/null +++ b/docs-cn/07-develop/01-connect/_connect_java.mdx @@ -0,0 +1,15 @@ +```java title="原生连接" +{{#include docs-examples/java/src/main/java/com/taos/example/JNIConnectExample.java}} +``` + +```java title="REST 连接" +{{#include docs-examples/java/src/main/java/com/taos/example/RESTConnectExample.java:main}} +``` + +使用 REST 连接时，如果查询数据量比较大，还可开启批量拉取功能。 + +```java title="开启批量拉取功能" {4} +{{#include docs-examples/java/src/main/java/com/taos/example/WSConnectExample.java:main}} +``` + +更多连接参数配置，参考[Java 连接器](/reference/connector/java) diff --git a/docs-cn/07-develop/01-connect/_connect_node.mdx b/docs-cn/07-develop/01-connect/_connect_node.mdx new file mode 100644 index 0000000000000000000000000000000000000000..199a6e3faa88fcb295379309a250990bf97fa973 --- /dev/null +++ b/docs-cn/07-develop/01-connect/_connect_node.mdx @@ -0,0 +1,7 @@ +```js title="原生连接" +{{#include docs-examples/node/nativeexample/connect.js}} +``` + +```js title="REST 连接" +{{#include docs-examples/node/restexample/connect.js}} +``` diff --git a/docs-cn/07-develop/01-connect/_connect_php.mdx b/docs-cn/07-develop/01-connect/_connect_php.mdx new file mode 100644 index 0000000000000000000000000000000000000000..2431df2a722659ae6e5962a955fba139be3e5f67 --- /dev/null +++ b/docs-cn/07-develop/01-connect/_connect_php.mdx @@ -0,0 +1,3 @@ +```php title="原生连接" +{{#include docs-examples/php/connect.php}} +``` diff --git a/docs-cn/07-develop/01-connect/_connect_python.mdx b/docs-cn/07-develop/01-connect/_connect_python.mdx new file mode 100644 index 0000000000000000000000000000000000000000..c0043c752e14bcc38f97c1046f2852a3f7fa2b7b --- /dev/null +++ b/docs-cn/07-develop/01-connect/_connect_python.mdx @@ -0,0 +1,3 @@ +```python title="原生连接" +{{#include docs-examples/python/connect_example.py}} +``` diff --git a/docs-cn/07-develop/01-connect/_connect_r.mdx b/docs-cn/07-develop/01-connect/_connect_r.mdx new file mode 100644 index 0000000000000000000000000000000000000000..8aab6121a66b38540bf1b8ebf5b48a513282ac7a --- /dev/null +++ b/docs-cn/07-develop/01-connect/_connect_r.mdx @@ -0,0 +1,3 @@ +```r title="原生连接" +{{#include docs-examples/R/connect_native.r:demo}} +``` diff --git a/docs-cn/07-develop/01-connect/_connect_rust.mdx b/docs-cn/07-develop/01-connect/_connect_rust.mdx new file mode 100644 index 0000000000000000000000000000000000000000..9e64724c178ba2c72e14fc9878bf9c3237bb50e7 --- /dev/null +++ b/docs-cn/07-develop/01-connect/_connect_rust.mdx @@ -0,0 +1,8 @@ +```rust title="原生连接/REST 连接" +{{#include docs-examples/rust/nativeexample/examples/connect.rs}} +``` + +:::note +对于 Rust 连接器， 连接方式的不同只体现在使用的特性不同。如果启用了 "rest" 特性，那么只有 RESTful 的实现会被编译进来。 + +::: diff --git a/docs-cn/07-develop/01-connect/index.md b/docs-cn/07-develop/01-connect/index.md new file mode 100644 index 0000000000000000000000000000000000000000..ebdefc77b9cc23712626f7543e0e5cc29db3e080 --- /dev/null +++ b/docs-cn/07-develop/01-connect/index.md @@ -0,0 +1,284 @@ +--- +title: 建立连接 +description: "本节介绍如何使用连接器建立与 TDengine 的连接，给出连接器安装、连接的简单说明。" +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import ConnJava from "./_connect_java.mdx"; +import ConnGo from "./_connect_go.mdx"; +import ConnRust from "./_connect_rust.mdx"; +import ConnNode from "./_connect_node.mdx"; +import ConnPythonNative from "./_connect_python.mdx"; +import ConnCSNative from "./_connect_cs.mdx"; +import ConnC from "./_connect_c.mdx"; +import ConnR from "./_connect_r.mdx"; +import ConnPHP from "./_connect_php.mdx"; +import InstallOnWindows from "../../14-reference/03-connector/_linux_install.mdx"; +import InstallOnLinux from "../../14-reference/03-connector/_windows_install.mdx"; +import VerifyLinux from "../../14-reference/03-connector/_verify_linux.mdx"; +import VerifyWindows from "../../14-reference/03-connector/_verify_windows.mdx"; + +TDengine 提供了丰富的应用程序开发接口，为了便于用户快速开发自己的应用，TDengine 支持了多种编程语言的连接器，其中官方连接器包括支持 C/C++、Java、Python、Go、Node.js、C#、Rust、Lua（社区贡献）和 PHP （社区贡献）的连接器。这些连接器支持使用原生接口（taosc）和 REST 接口（部分语言暂不支持）连接 TDengine 集群。社区开发者也贡献了多个非官方连接器，例如 ADO.NET 连接器、Lua 连接器和 PHP 连接器。 + +## 连接器建立连接的方式 + +连接器建立连接的方式，TDengine 提供两种: + +1. 通过 taosAdapter 组件提供的 REST API 建立与 taosd 的连接，这种连接方式下文中简称“REST 连接” +2. 通过客户端驱动程序 taosc 直接与服务端程序 taosd 建立连接，这种连接方式下文中简称“原生连接”。 + +无论使用何种方式建立连接，连接器都提供了相同或相似的 API 操作数据库，都可以执行 SQL 语句，只是初始化连接的方式稍有不同，用户在使用上不会感到什么差别。 + +关键不同点在于： + +1. 使用 REST 连接，用户无需安装客户端驱动程序 taosc，具有跨平台易用的优势，但性能要下降 30%左右。 +2. 使用原生连接可以体验 TDengine 的全部功能，如[参数绑定接口](/reference/connector/cpp#参数绑定-api)、[订阅](reference/connector/cpp#数据订阅接口)等等。 + +## 安装客户端驱动 taosc + +如果选择原生连接，而且应用程序不在 TDengine 同一台服务器上运行，你需要先安装客户端驱动，否则可以跳过此一步。为避免客户端驱动和服务端不兼容，请使用一致的版本。 + +### 安装步骤 + + + + + + + + + + +### 安装验证 + +以上安装和配置完成后，并确认 TDengine 服务已经正常启动运行，此时可以执行安装包里带有的 TDengine 命令行程序 taos 进行登录。 + + + + + + + + + + +## 安装连接器 + + + + +如果使用 maven 管理项目，只需在 pom.xml 中加入以下依赖。 + +```xml + + com.taosdata.jdbc + taos-jdbcdriver + 2.0.38 + +``` + + + + +使用 `pip` 从 PyPI 安装: + +``` +pip install taospy +``` + +从 Git URL 安装： + +``` +pip install git+https://github.com/taosdata/taos-connector-python.git +``` + + + + +编辑 `go.mod` 添加 `driver-go` 依赖即可。 + +```go-mod title=go.mod +module goexample + +go 1.17 + +require github.com/taosdata/driver-go/v2 develop +``` + +:::note +driver-go 使用 cgo 封装了 taosc 的 API。cgo 需要使用 gcc 编译 C 的源码。因此需要确保你的系统上有 gcc。 + +::: + + + + +编辑 `Cargo.toml` 添加 `libtaos` 依赖即可。 + +```toml title=Cargo.toml +[dependencies] +libtaos = { version = "0.4.2"} +``` + +:::info +Rust 连接器通过不同的特性区分不同的连接方式。如果要建立 REST 连接，需要开启 `rest` 特性： + +```toml +libtaos = { version = "*", features = ["rest"] } +``` + +::: + + + + +Node.js 连接器通过不同的包提供不同的连接方式。 + +1. 安装 Node.js 原生连接器 + + ``` + npm i td2.0-connector + ``` + +:::note +推荐 Node 版本大于等于 `node-v12.8.0` 小于 `node-v13.0.0` +::: + +2. 安装 Node.js REST 连接器 + + ``` + npm i td2.0-rest-connector + ``` + + + + +编辑项目配置文件中添加 [TDengine.Connector](https://www.nuget.org/packages/TDengine.Connector/) 的引用即可： + +```xml title=csharp.csproj {12} + + + + Exe + net6.0 + enable + enable + TDengineExample.AsyncQueryExample + + + + + + + +``` + +也可通过 dotnet 命令添加： + +``` +dotnet add package TDengine.Connector +``` + +:::note +以下示例代码，均基于 dotnet6.0，如果使用其它版本，可能需要做适当调整。 + +::: + + + + +1. 下载 [taos-jdbcdriver-version-dist.jar](https://repo1.maven.org/maven2/com/taosdata/jdbc/taos-jdbcdriver/2.0.38/)。 +2. 安装 R 的依赖包`RJDBC`： + +```R +install.packages("RJDBC") +``` + + + + +如果已经安装了 TDengine 服务端软件或 TDengine 客户端驱动 taosc， 那么已经安装了 C 连接器，无需额外操作。 +
+ + + + +**下载代码并解压：** + +```shell +curl -L -o php-tdengine.tar.gz https://github.com/Yurunsoft/php-tdengine/archive/refs/tags/v1.0.2.tar.gz \ +&& mkdir php-tdengine \ +&& tar -xzf php-tdengine.tar.gz -C php-tdengine --strip-components=1 +``` + +> 版本 `v1.0.0` 可替换为任意更新的版本，可在 Release 中查看最新版本。 + +**非 Swoole 环境：** + +```shell +phpize && ./configure && make -j && make install +``` + +**手动指定 TDengine 目录：** + +```shell +phpize && ./configure --with-tdengine-dir=/usr/local/Cellar/tdengine/2.4.0.0 && make -j && make install +``` + +> `--with-tdengine-dir=` 后跟上 TDengine 目录。 +> 适用于默认找不到的情况，或者 macOS 系统用户。 + +**Swoole 环境：** + +```shell +phpize && ./configure --enable-swoole && make -j && make install +``` + +**启用扩展：** + +方法一：在 `php.ini` 中加入 `extension=tdengine` + +方法二：运行带参数 `php -d extension=tdengine test.php` + + + + +## 建立连接 + +在执行这一步之前，请确保有一个正在运行的，且可以访问到的 TDengine，而且服务端的 FQDN 配置正确。以下示例代码，都假设 TDengine 安装在本机，且 FQDN（默认 localhost） 和 serverPort（默认 6030） 都使用默认配置。 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +:::tip +如果建立连接失败，大部分情况下是 FQDN 或防火墙的配置不正确，详细的排查方法请看[《常见问题及反馈》](https://docs.taosdata.com/train-faq/faq)中的“遇到错误 Unable to establish connection, 我怎么办？” + +::: diff --git a/docs-cn/07-develop/02-model/_category_.yml b/docs-cn/07-develop/02-model/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..e5dae7c27cf17ff737aa8301bc79aad468c28791 --- /dev/null +++ b/docs-cn/07-develop/02-model/_category_.yml @@ -0,0 +1,2 @@ +label: 数据建模 + diff --git a/docs-cn/07-develop/02-model/index.mdx b/docs-cn/07-develop/02-model/index.mdx new file mode 100644 index 0000000000000000000000000000000000000000..a060e3c84b8c5b8e25714ce15fb2bc7afc7d49d2 --- /dev/null +++ b/docs-cn/07-develop/02-model/index.mdx @@ -0,0 +1,86 @@ +--- +title: TDengine 数据建模 +--- + +TDengine 采用类关系型数据模型，需要建库、建表。因此对于一个具体的应用场景，需要考虑库、超级表和普通表的设计。本节不讨论细致的语法规则，只介绍概念。 + +关于数据建模请参考[视频教程](https://www.taosdata.com/blog/2020/11/11/1945.html)。 + +## 创建库 + +不同类型的数据采集点往往具有不同的数据特征，包括数据采集频率的高低，数据保留时间的长短，副本的数目，数据块的大小，是否允许更新数据等等。为了在各种场景下 TDengine 都能最大效率的工作，TDengine 建议将不同数据特征的表创建在不同的库里，因为每个库可以配置不同的存储策略。创建一个库时，除 SQL 标准的选项外，还可以指定保留时长、副本数、内存块个数、时间精度、文件块里最大最小记录条数、是否压缩、一个数据文件覆盖的天数等多种参数。比如： + +```sql +CREATE DATABASE power KEEP 365 DAYS 10 BLOCKS 6 UPDATE 1; +``` + +上述语句将创建一个名为 power 的库，这个库的数据将保留 365 天（超过 365 天将被自动删除），每 10 天一个数据文件，内存块数为 6，允许更新数据。详细的语法及参数请见 [数据库管理](/taos-sql/database) 章节。 + +创建库之后，需要使用 SQL 命令 `USE` 将当前库切换过来，例如： + +```sql +USE power; +``` + +将当前连接里操作的库换为 power，否则对具体表操作前，需要使用“库名.表名”来指定库的名字。 + +:::note + +- 任何一张表或超级表必须属于某个库，在创建表之前，必须先创建库。 +- 处于两个不同库的表是不能进行 JOIN 操作的。 +- 创建并插入记录、查询历史记录的时候，均需要指定时间戳。 + +::: + +## 创建超级表 + +一个物联网系统，往往存在多种类型的设备，比如对于电网，存在智能电表、变压器、母线、开关等等。为便于多表之间的聚合，使用 TDengine, 需要对每个类型的数据采集点创建一个超级表。以[表 1](/tdinternal/arch#model_table1) 中的智能电表为例，可以使用如下的 SQL 命令创建超级表： + +```sql +CREATE STABLE meters (ts timestamp, current float, voltage int, phase float) TAGS (location binary(64), groupId int); +``` + +:::note +这一指令中的 STABLE 关键字，在 2.0.15 之前的版本中需写作 TABLE 。 +::: + +与创建普通表一样，创建超级表时，需要提供表名（示例中为 meters），表结构 Schema，即数据列的定义。第一列必须为时间戳（示例中为 ts)，其他列为采集的物理量（示例中为 current, voltage, phase)，数据类型可以为整型、浮点型、字符串等。除此之外，还需要提供标签的 schema (示例中为 location, groupId)，标签的数据类型可以为整型、浮点型、字符串等。采集点的静态属性往往可以作为标签，比如采集点的地理位置、设备型号、设备组 ID、管理员 ID 等等。标签的 schema 可以事后增加、删除、修改。具体定义以及细节请见 [TAOS SQL 的超级表管理](/taos-sql/stable) 章节。 + +每一种类型的数据采集点需要建立一个超级表，因此一个物联网系统，往往会有多个超级表。对于电网，我们就需要对智能电表、变压器、母线、开关等都建立一个超级表。在物联网中，一个设备就可能有多个数据采集点（比如一台风力发电的风机，有的采集点采集电流、电压等电参数，有的采集点采集温度、湿度、风向等环境参数），这个时候，对这一类型的设备，需要建立多张超级表。 + +一张超级表最多容许 4096 列 （在 2.1.7.0 版本之前，列数限制为 1024 列），如果一个采集点采集的物理量个数超过 4096，需要建多张超级表来处理。一个系统可以有多个 DB，一个 DB 里可以有一到多个超级表。 + +## 创建表 + +TDengine 对每个数据采集点需要独立建表。与标准的关系型数据库一样，一张表有表名，Schema，但除此之外，还可以带有一到多个标签。创建时，需要使用超级表做模板，同时指定标签的具体值。以[表 1](/tdinternal/arch#model_table1)中的智能电表为例，可以使用如下的 SQL 命令建表： + +```sql +CREATE TABLE d1001 USING meters TAGS ("Beijing.Chaoyang", 2); +``` + +其中 d1001 是表名，meters 是超级表的表名，后面紧跟标签 Location 的具体标签值 ”Beijing.Chaoyang"，标签 groupId 的具体标签值 2。虽然在创建表时，需要指定标签值，但可以事后修改。详细细则请见 [TAOS SQL 的表管理](/taos-sql/table) 章节。 + +:::warning +目前 TDengine 没有从技术层面限制使用一个 database (db1) 的超级表作为模板建立另一个 database (db2) 的子表，后续会禁止这种用法，不建议使用这种方法建表。 + +::: + +TDengine 建议将数据采集点的全局唯一 ID 作为表名(比如设备序列号）。但对于有的场景，并没有唯一的 ID，可以将多个 ID 组合成一个唯一的 ID。不建议将具有唯一性的 ID 作为标签值。 + +### 自动建表 + +在某些特殊场景中，用户在写数据时并不确定某个数据采集点的表是否存在，此时可在写入数据时使用自动建表语法来创建不存在的表，若该表已存在则不会建立新表且后面的 USING 语句被忽略。比如： + +```sql +INSERT INTO d1001 USING meters TAGS ("Beijng.Chaoyang", 2) VALUES (now, 10.2, 219, 0.32); +``` + +上述 SQL 语句将记录`(now, 10.2, 219, 0.32)`插入表 d1001。如果表 d1001 还未创建，则使用超级表 meters 做模板自动创建，同时打上标签值 `"Beijing.Chaoyang", 2`。 + +关于自动建表的详细语法请参见 [插入记录时自动建表](/taos-sql/insert#插入记录时自动建表) 章节。 + +## 多列模型 vs 单列模型 + +TDengine 支持多列模型，只要物理量是一个数据采集点同时采集的（时间戳一致），这些量就可以作为不同列放在一张超级表里。但还有一种极限的设计，单列模型，每个采集的物理量都单独建表，因此每种类型的物理量都单独建立一超级表。比如电流、电压、相位，就建三张超级表。 + +TDengine 建议尽可能采用多列模型，因为插入效率以及存储效率更高。但对于有些场景，一个采集点的采集量的种类经常变化，这个时候，如果采用多列模型，就需要频繁修改超级表的结构定义，让应用变的复杂，这个时候，采用单列模型会显得更简单。 diff --git a/docs-cn/07-develop/03-insert-data/01-sql-writing.mdx b/docs-cn/07-develop/03-insert-data/01-sql-writing.mdx new file mode 100644 index 0000000000000000000000000000000000000000..e63ffce6dd07366da99fe1f41d0a2a8d7a623f31 --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/01-sql-writing.mdx @@ -0,0 +1,137 @@ +--- +title: SQL 写入 +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import JavaSQL from "./_java_sql.mdx"; +import JavaStmt from "./_java_stmt.mdx"; +import PySQL from "./_py_sql.mdx"; +import PyStmt from "./_py_stmt.mdx"; +import GoSQL from "./_go_sql.mdx"; +import GoStmt from "./_go_stmt.mdx"; +import RustSQL from "./_rust_sql.mdx"; +import RustStmt from "./_rust_stmt.mdx"; +import NodeSQL from "./_js_sql.mdx"; +import NodeStmt from "./_js_stmt.mdx"; +import CsSQL from "./_cs_sql.mdx"; +import CsStmt from "./_cs_stmt.mdx"; +import CSQL from "./_c_sql.mdx"; +import CStmt from "./_c_stmt.mdx"; +import PhpSQL from "./_php_sql.mdx"; +import PhpStmt from "./_php_stmt.mdx"; + +## SQL 写入简介 + +应用通过连接器执行 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 的数据写入](/taos-sql/insert)。 + +:::info + +- 要提高写入效率，需要批量写入。一批写入的记录条数越多，插入效率就越高。但一条记录不能超过 16K，一条 SQL 语句总长度不能超过 1M 。 +- TDengine 支持多线程同时写入，要进一步提高写入速度，一个客户端需要打开 20 个以上的线程同时写。但线程数达到一定数量后，无法再提高，甚至还会下降，因为线程频繁切换，带来额外开销。 + +::: + +:::warning + +- 对同一张表，如果新插入记录的时间戳已经存在，默认情形下（UPDATE=0）新记录将被直接抛弃，也就是说，在一张表里，时间戳必须是唯一的。如果应用自动生成记录，很有可能生成的时间戳是一样的，这样，成功插入的记录条数会小于应用插入的记录条数。如果在创建数据库时使用了 UPDATE 1 选项，插入相同时间戳的新记录将覆盖原有记录。 +- 写入的数据的时间戳必须大于当前时间减去配置参数 keep 的时间。如果 keep 配置为 3650 天，那么无法写入比 3650 天还早的数据。写入数据的时间戳也不能大于当前时间加配置参数 days。如果 days 为 2，那么无法写入比当前时间还晚 2 天的数据。 + +::: + +## 示例程序 + +### 普通 SQL 写入 + + + + + + + + + + + + + + + + + + + + + + + + + + + + +:::note + +1. 无论 RESTful 方式建立连接还是本地驱动方式建立连接，以上示例代码都能正常工作。 +2. 唯一需要注意的是：由于 RESTful 接口无状态， 不能使用 `use db` 语句来切换数据库, 所以在上面示例中使用了`dbName.tbName`指定表名。 + +::: + +### 参数绑定写入 + +TDengine 也提供了支持参数绑定的 Prepare API，与 MySQL 类似，这些 API 目前也仅支持用问号 `?` 来代表待绑定的参数。从 2.1.1.0 和 2.1.2.0 版本开始，TDengine 大幅改进了参数绑定接口对数据写入（INSERT）场景的支持。这样在通过参数绑定接口写入数据时，就避免了 SQL 语法解析的资源消耗，从而在绝大多数情况下显著提升写入性能。 + +需要注意的是，只有使用原生连接的连接器，才能使用参数绑定功能。 + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs-cn/07-develop/03-insert-data/02-influxdb-line.mdx b/docs-cn/07-develop/03-insert-data/02-influxdb-line.mdx new file mode 100644 index 0000000000000000000000000000000000000000..dedd7f0e70834e21257bda78dd184f5ddc520160 --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/02-influxdb-line.mdx @@ -0,0 +1,70 @@ +--- +sidebar_label: InfluxDB 行协议 +title: InfluxDB 行协议 +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import JavaLine from "./_java_line.mdx"; +import PyLine from "./_py_line.mdx"; +import GoLine from "./_go_line.mdx"; +import RustLine from "./_rust_line.mdx"; +import NodeLine from "./_js_line.mdx"; +import CsLine from "./_cs_line.mdx"; +import CLine from "./_c_line.mdx"; + +## 协议介绍 + +InfluxDB Line 协议采用一行字符串来表示一行数据。分为四部分： + +``` +measurement,tag_set field_set timestamp +``` + +- measurement 将作为超级表名。它与 tag_set 之间使用一个英文逗号来分隔。 +- tag_set 将作为标签数据，其格式形如 `=,=`，也即可以使用英文逗号来分隔多个标签数据。它与 field_set 之间使用一个半角空格来分隔。 +- field_set 将作为普通列数据，其格式形如 `=,=`，同样是使用英文逗号来分隔多个普通列的数据。它与 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/#无模式写入行协议) + + +## 示例代码 + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs-cn/07-develop/03-insert-data/03-opentsdb-telnet.mdx b/docs-cn/07-develop/03-insert-data/03-opentsdb-telnet.mdx new file mode 100644 index 0000000000000000000000000000000000000000..dfbe6efda67b6928999287900637e0a251b86562 --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/03-opentsdb-telnet.mdx @@ -0,0 +1,84 @@ +--- +sidebar_label: OpenTSDB 行协议 +title: OpenTSDB 行协议 +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import JavaTelnet from "./_java_opts_telnet.mdx"; +import PyTelnet from "./_py_opts_telnet.mdx"; +import GoTelnet from "./_go_opts_telnet.mdx"; +import RustTelnet from "./_rust_opts_telnet.mdx"; +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 度量值，必须为一个数值。对应的列名也是 “value”。 +- 最后一部分是标签集， 用空格分隔不同标签， 所有标签自动转化为 nchar 数据类型; + +例如： + +```txt +meters.current 1648432611250 11.3 location=Beijing.Haidian groupid=3 +``` + +参考[OpenTSDB Telnet API文档](http://opentsdb.net/docs/build/html/api_telnet/put.html)。 + +## 示例代码 + + + + + + + + + + + + + + + + + + + + + + + + + +以上示例代码会自动创建 2 个超级表， 每个超级表有 4 条数据。 + +```cmd +taos> use test; +Database changed. + +taos> show stables; + name | created_time | columns | tags | tables | +============================================================================================ + meters.current | 2022-03-30 17:04:10.877 | 2 | 2 | 2 | + meters.voltage | 2022-03-30 17:04:10.882 | 2 | 2 | 2 | +Query OK, 2 row(s) in set (0.002544s) + +taos> select tbname, * from `meters.current`; + tbname | ts | value | groupid | location | +================================================================================================================================== + t_0e7bcfa21a02331c06764f275... | 2022-03-28 09:56:51.249 | 10.800000000 | 3 | Beijing.Haidian | + t_0e7bcfa21a02331c06764f275... | 2022-03-28 09:56:51.250 | 11.300000000 | 3 | Beijing.Haidian | + t_7e7b26dd860280242c6492a16... | 2022-03-28 09:56:51.249 | 10.300000000 | 2 | Beijing.Chaoyang | + t_7e7b26dd860280242c6492a16... | 2022-03-28 09:56:51.250 | 12.600000000 | 2 | Beijing.Chaoyang | +Query OK, 4 row(s) in set (0.005399s) +``` diff --git a/docs-cn/07-develop/03-insert-data/04-opentsdb-json.mdx b/docs-cn/07-develop/03-insert-data/04-opentsdb-json.mdx new file mode 100644 index 0000000000000000000000000000000000000000..5d445997d061ca052e4f3673b8e881ea4acf0ade --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/04-opentsdb-json.mdx @@ -0,0 +1,99 @@ +--- +sidebar_label: OpenTSDB JSON 格式协议 +title: OpenTSDB JSON 格式协议 +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import JavaJson from "./_java_opts_json.mdx"; +import PyJson from "./_py_opts_json.mdx"; +import GoJson from "./_go_opts_json.mdx"; +import RustJson from "./_rust_opts_json.mdx"; +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 +- 对于 JSON 格式协议，TDengine 并不会自动把所有标签转成 nchar 类型， 字符串将将转为 nchar 类型， 数值将同样转换为 double 类型。 +- TDengine 只接收 JSON **数组格式**的字符串，即使一行数据也需要转换成数组形式。 + +::: + +## 示例代码 + + + + + + + + + + + + + + + + + + + + + + + + + +以上示例代码会自动创建 2 个超级表， 每个超级表有 2 条数据。 + +```cmd +taos> use test; +Database changed. + +taos> show stables; + name | created_time | columns | tags | tables | +============================================================================================ + meters.current | 2022-03-29 16:05:25.193 | 2 | 2 | 1 | + meters.voltage | 2022-03-29 16:05:25.200 | 2 | 2 | 1 | +Query OK, 2 row(s) in set (0.001954s) + +taos> select * from `meters.current`; + ts | value | groupid | location | +=================================================================================================================== + 2022-03-28 09:56:51.249 | 10.300000000 | 2.000000000 | Beijing.Chaoyang | + 2022-03-28 09:56:51.250 | 12.600000000 | 2.000000000 | Beijing.Chaoyang | +Query OK, 2 row(s) in set (0.004076s) +``` diff --git a/docs-cn/07-develop/03-insert-data/_c_line.mdx b/docs-cn/07-develop/03-insert-data/_c_line.mdx new file mode 100644 index 0000000000000000000000000000000000000000..5ef2e9af774c54e9f090357286f83d2280c2ab11 --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/_c_line.mdx @@ -0,0 +1,3 @@ +```c +{{#include docs-examples/c/line_example.c:main}} +``` \ No newline at end of file diff --git a/docs-cn/07-develop/03-insert-data/_c_opts_json.mdx b/docs-cn/07-develop/03-insert-data/_c_opts_json.mdx new file mode 100644 index 0000000000000000000000000000000000000000..22ad2e0122797248a372734aac0f3a16a1356530 --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/_c_opts_json.mdx @@ -0,0 +1,3 @@ +```c +{{#include docs-examples/c/json_protocol_example.c:main}} +``` \ No newline at end of file diff --git a/docs-cn/07-develop/03-insert-data/_c_opts_telnet.mdx b/docs-cn/07-develop/03-insert-data/_c_opts_telnet.mdx new file mode 100644 index 0000000000000000000000000000000000000000..508d7bc98a149f49766bcd0a474ffe226cbe30bb --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/_c_opts_telnet.mdx @@ -0,0 +1,3 @@ +```c +{{#include docs-examples/c/telnet_line_example.c:main}} +``` \ No newline at end of file diff --git a/docs-cn/07-develop/03-insert-data/_c_sql.mdx b/docs-cn/07-develop/03-insert-data/_c_sql.mdx new file mode 100644 index 0000000000000000000000000000000000000000..f4153fd2c427677a338d0c377663d0335f2672f0 --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/_c_sql.mdx @@ -0,0 +1,3 @@ +```c +{{#include docs-examples/c/insert_example.c}} +``` \ No newline at end of file diff --git a/docs-cn/07-develop/03-insert-data/_c_stmt.mdx b/docs-cn/07-develop/03-insert-data/_c_stmt.mdx new file mode 100644 index 0000000000000000000000000000000000000000..01ac067519a2bd224e313fd70169722ba5f20413 --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/_c_stmt.mdx @@ -0,0 +1,6 @@ +```c title=一次绑定一行 +{{#include docs-examples/c/stmt_example.c}} +``` +```c title=一次绑定多行 72:117 +{{#include docs-examples/c/multi_bind_example.c}} +``` \ No newline at end of file diff --git a/docs-cn/07-develop/03-insert-data/_category_.yml b/docs-cn/07-develop/03-insert-data/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..430b3e4209ec12c6abdbfa825c9a95582376d058 --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/_category_.yml @@ -0,0 +1 @@ +label: 写入数据 \ No newline at end of file diff --git a/docs-cn/07-develop/03-insert-data/_cs_line.mdx b/docs-cn/07-develop/03-insert-data/_cs_line.mdx new file mode 100644 index 0000000000000000000000000000000000000000..9c275ee3d7c7a1e52fbb34dbae922004543ee3ce --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/_cs_line.mdx @@ -0,0 +1,3 @@ +```csharp +{{#include docs-examples/csharp/InfluxDBLineExample.cs}} +``` diff --git a/docs-cn/07-develop/03-insert-data/_cs_opts_json.mdx b/docs-cn/07-develop/03-insert-data/_cs_opts_json.mdx new file mode 100644 index 0000000000000000000000000000000000000000..3d538b8506b298241faecd8098f89571359135c9 --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/_cs_opts_json.mdx @@ -0,0 +1,3 @@ +```csharp +{{#include docs-examples/csharp/OptsJsonExample.cs}} +``` diff --git a/docs-cn/07-develop/03-insert-data/_cs_opts_telnet.mdx b/docs-cn/07-develop/03-insert-data/_cs_opts_telnet.mdx new file mode 100644 index 0000000000000000000000000000000000000000..c53bf3d7233115351e5af03b7d9e6318aa4a0da6 --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/_cs_opts_telnet.mdx @@ -0,0 +1,3 @@ +```csharp +{{#include docs-examples/csharp/OptsTelnetExample.cs}} +``` diff --git a/docs-cn/07-develop/03-insert-data/_cs_sql.mdx b/docs-cn/07-develop/03-insert-data/_cs_sql.mdx new file mode 100644 index 0000000000000000000000000000000000000000..c7688bfbe77a1135424d829fe9b29fbb1bc93ae2 --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/_cs_sql.mdx @@ -0,0 +1,3 @@ +```csharp +{{#include docs-examples/csharp/SQLInsertExample.cs}} +``` diff --git a/docs-cn/07-develop/03-insert-data/_cs_stmt.mdx b/docs-cn/07-develop/03-insert-data/_cs_stmt.mdx new file mode 100644 index 0000000000000000000000000000000000000000..97c3b910ffeb9e0c88fc143a02014115e819c147 --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/_cs_stmt.mdx @@ -0,0 +1,3 @@ +```csharp +{{#include docs-examples/csharp/StmtInsertExample.cs}} +``` diff --git a/docs-cn/07-develop/03-insert-data/_go_line.mdx b/docs-cn/07-develop/03-insert-data/_go_line.mdx new file mode 100644 index 0000000000000000000000000000000000000000..cd225945b70e28bef2ca7fdaf0d9be0ad7ffc18c --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/_go_line.mdx @@ -0,0 +1,3 @@ +```go +{{#include docs-examples/go/insert/line/main.go}} +``` diff --git a/docs-cn/07-develop/03-insert-data/_go_opts_json.mdx b/docs-cn/07-develop/03-insert-data/_go_opts_json.mdx new file mode 100644 index 0000000000000000000000000000000000000000..0c0d3e5b6330e046988cdd02234285ec67e92f01 --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/_go_opts_json.mdx @@ -0,0 +1,3 @@ +```go +{{#include docs-examples/go/insert/json/main.go}} +``` diff --git a/docs-cn/07-develop/03-insert-data/_go_opts_telnet.mdx b/docs-cn/07-develop/03-insert-data/_go_opts_telnet.mdx new file mode 100644 index 0000000000000000000000000000000000000000..d5ca40cc146e62412476289853e8e2739e0e9e4b --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/_go_opts_telnet.mdx @@ -0,0 +1,3 @@ +```go +{{#include docs-examples/go/insert/telnet/main.go}} +``` diff --git a/docs-cn/07-develop/03-insert-data/_go_sql.mdx b/docs-cn/07-develop/03-insert-data/_go_sql.mdx new file mode 100644 index 0000000000000000000000000000000000000000..613a65add1741eb763a4b24e65d180d05f7d670f --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/_go_sql.mdx @@ -0,0 +1,3 @@ +```go +{{#include docs-examples/go/insert/sql/main.go}} +``` diff --git a/docs-cn/07-develop/03-insert-data/_go_stmt.mdx b/docs-cn/07-develop/03-insert-data/_go_stmt.mdx new file mode 100644 index 0000000000000000000000000000000000000000..7bb6792d6df5b250850bd0a0021ecceba994aa09 --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/_go_stmt.mdx @@ -0,0 +1,8 @@ +```go +{{#include docs-examples/go/insert/stmt/main.go}} +``` + +:::tip +driver-go 的模块 `github.com/taosdata/driver-go/v2/wrapper` 是 C 接口的底层封装。使用这个模块也可以实现参数绑定写入。 + +::: diff --git a/docs-cn/07-develop/03-insert-data/_java_line.mdx b/docs-cn/07-develop/03-insert-data/_java_line.mdx new file mode 100644 index 0000000000000000000000000000000000000000..2e59a5d4701b2a2ab04ec5711845dc5c80067a1e --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/_java_line.mdx @@ -0,0 +1,3 @@ +```java +{{#include docs-examples/java/src/main/java/com/taos/example/LineProtocolExample.java}} +``` diff --git a/docs-cn/07-develop/03-insert-data/_java_opts_json.mdx b/docs-cn/07-develop/03-insert-data/_java_opts_json.mdx new file mode 100644 index 0000000000000000000000000000000000000000..826a1a07d9405cb193849f9d21e5444f68517914 --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/_java_opts_json.mdx @@ -0,0 +1,3 @@ +```java +{{#include docs-examples/java/src/main/java/com/taos/example/JSONProtocolExample.java}} +``` diff --git a/docs-cn/07-develop/03-insert-data/_java_opts_telnet.mdx b/docs-cn/07-develop/03-insert-data/_java_opts_telnet.mdx new file mode 100644 index 0000000000000000000000000000000000000000..954dcc1a482a150dea0b190e1e0593adbfbde796 --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/_java_opts_telnet.mdx @@ -0,0 +1,3 @@ +```java +{{#include docs-examples/java/src/main/java/com/taos/example/TelnetLineProtocolExample.java}} +``` diff --git a/docs-cn/07-develop/03-insert-data/_java_sql.mdx b/docs-cn/07-develop/03-insert-data/_java_sql.mdx new file mode 100644 index 0000000000000000000000000000000000000000..a863378defe43b1f22c1f98087a34f053a7d6619 --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/_java_sql.mdx @@ -0,0 +1,3 @@ +```java +{{#include docs-examples/java/src/main/java/com/taos/example/RestInsertExample.java:insert}} +``` \ No newline at end of file diff --git a/docs-cn/07-develop/03-insert-data/_java_stmt.mdx b/docs-cn/07-develop/03-insert-data/_java_stmt.mdx new file mode 100644 index 0000000000000000000000000000000000000000..54443e535fa84bdf8dc9161ed4ad00f50b26266c --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/_java_stmt.mdx @@ -0,0 +1,3 @@ +```java +{{#include docs-examples/java/src/main/java/com/taos/example/StmtInsertExample.java}} +``` diff --git a/docs-cn/07-develop/03-insert-data/_js_line.mdx b/docs-cn/07-develop/03-insert-data/_js_line.mdx new file mode 100644 index 0000000000000000000000000000000000000000..172c9bc17b8cff8b2620720b235a9c8e69bd4197 --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/_js_line.mdx @@ -0,0 +1,3 @@ +```js +{{#include docs-examples/node/nativeexample/influxdb_line_example.js}} +``` diff --git a/docs-cn/07-develop/03-insert-data/_js_opts_json.mdx b/docs-cn/07-develop/03-insert-data/_js_opts_json.mdx new file mode 100644 index 0000000000000000000000000000000000000000..20ac9ec91e8dc6675828b16d7da0acb09afd3b5f --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/_js_opts_json.mdx @@ -0,0 +1,3 @@ +```js +{{#include docs-examples/node/nativeexample/opentsdb_json_example.js}} +``` diff --git a/docs-cn/07-develop/03-insert-data/_js_opts_telnet.mdx b/docs-cn/07-develop/03-insert-data/_js_opts_telnet.mdx new file mode 100644 index 0000000000000000000000000000000000000000..c3c8c40bd642f4f443de88e3db006ad50724d514 --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/_js_opts_telnet.mdx @@ -0,0 +1,3 @@ +```js +{{#include docs-examples/node/nativeexample/opentsdb_telnet_example.js}} +``` diff --git a/docs-cn/07-develop/03-insert-data/_js_sql.mdx b/docs-cn/07-develop/03-insert-data/_js_sql.mdx new file mode 100644 index 0000000000000000000000000000000000000000..f5e17c76892a57a94192a95451b508b1c176c984 --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/_js_sql.mdx @@ -0,0 +1,3 @@ +```js +{{#include docs-examples/node/nativeexample/insert_example.js}} +``` diff --git a/docs-cn/07-develop/03-insert-data/_js_stmt.mdx b/docs-cn/07-develop/03-insert-data/_js_stmt.mdx new file mode 100644 index 0000000000000000000000000000000000000000..17a6c9785c7dc1e3c3fa6a59982913f1f139f9c2 --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/_js_stmt.mdx @@ -0,0 +1,12 @@ +```js title=一次绑定一行 +{{#include docs-examples/node/nativeexample/param_bind_example.js}} +``` + +```js title=一次绑定多行 +{{#include docs-examples/node/nativeexample/multi_bind_example.js:insertData}} +``` + +:::info +一次绑定一行效率不如一次绑定多行，但支持非 INSERT 语句。一次绑定多行效率更高，但仅支持 INSERT 语句。 + +::: diff --git a/docs-cn/07-develop/03-insert-data/_php_sql.mdx b/docs-cn/07-develop/03-insert-data/_php_sql.mdx new file mode 100644 index 0000000000000000000000000000000000000000..42d6a548479d526e7ecdba12807cf9cafb911ee5 --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/_php_sql.mdx @@ -0,0 +1,3 @@ +```php +{{#include docs-examples/php/insert.php}} +``` diff --git a/docs-cn/07-develop/03-insert-data/_php_stmt.mdx b/docs-cn/07-develop/03-insert-data/_php_stmt.mdx new file mode 100644 index 0000000000000000000000000000000000000000..c1ba4ed3b160514fafb50886d799fc27e60927ed --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/_php_stmt.mdx @@ -0,0 +1,3 @@ +```php +{{#include docs-examples/php/insert_stmt.php}} +``` diff --git a/docs-cn/07-develop/03-insert-data/_py_line.mdx b/docs-cn/07-develop/03-insert-data/_py_line.mdx new file mode 100644 index 0000000000000000000000000000000000000000..d3bb1ebb3403b53fa43bfc9d5d1a0de9764d7583 --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/_py_line.mdx @@ -0,0 +1,3 @@ +```py +{{#include docs-examples/python/line_protocol_example.py}} +``` diff --git a/docs-cn/07-develop/03-insert-data/_py_opts_json.mdx b/docs-cn/07-develop/03-insert-data/_py_opts_json.mdx new file mode 100644 index 0000000000000000000000000000000000000000..cfbfe13ccfdb4f3f34b77300812863fdf70d0f59 --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/_py_opts_json.mdx @@ -0,0 +1,3 @@ +```py +{{#include docs-examples/python/json_protocol_example.py}} +``` diff --git a/docs-cn/07-develop/03-insert-data/_py_opts_telnet.mdx b/docs-cn/07-develop/03-insert-data/_py_opts_telnet.mdx new file mode 100644 index 0000000000000000000000000000000000000000..14bc65a7a3da815abadf7f25c8deffeac666c8d7 --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/_py_opts_telnet.mdx @@ -0,0 +1,3 @@ +```py +{{#include docs-examples/python/telnet_line_protocol_example.py}} +``` diff --git a/docs-cn/07-develop/03-insert-data/_py_sql.mdx b/docs-cn/07-develop/03-insert-data/_py_sql.mdx new file mode 100644 index 0000000000000000000000000000000000000000..c0e15b8ec115b9244d50a47c9eafec04bcfdd70c --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/_py_sql.mdx @@ -0,0 +1,3 @@ +```py +{{#include docs-examples/python/native_insert_example.py}} +``` diff --git a/docs-cn/07-develop/03-insert-data/_py_stmt.mdx b/docs-cn/07-develop/03-insert-data/_py_stmt.mdx new file mode 100644 index 0000000000000000000000000000000000000000..8241ea86bc64ac64d842dc0a6cddc0eae0399503 --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/_py_stmt.mdx @@ -0,0 +1,12 @@ +```py title=一次绑定一行 +{{#include docs-examples/python/bind_param_example.py}} +``` + +```py title=一次绑定多行 +{{#include docs-examples/python/multi_bind_example.py:bind_batch}} +``` + +:::info +一次绑定一行效率不如一次绑定多行，但支持非 INSERT 语句。一次绑定多行效率更高，但仅支持 INSERT 语句。 + +::: \ No newline at end of file diff --git a/docs-cn/07-develop/03-insert-data/_rust_line.mdx b/docs-cn/07-develop/03-insert-data/_rust_line.mdx new file mode 100644 index 0000000000000000000000000000000000000000..696ddb7b854751b8dee01047066f97f74212933f --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/_rust_line.mdx @@ -0,0 +1,3 @@ +```rust +{{#include docs-examples/rust/schemalessexample/examples/influxdb_line_example.rs}} +``` diff --git a/docs-cn/07-develop/03-insert-data/_rust_opts_json.mdx b/docs-cn/07-develop/03-insert-data/_rust_opts_json.mdx new file mode 100644 index 0000000000000000000000000000000000000000..97d9052dacd1894cc7548a59951ecfaad9caee87 --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/_rust_opts_json.mdx @@ -0,0 +1,3 @@ +```rust +{{#include docs-examples/rust/schemalessexample/examples/opentsdb_json_example.rs}} +``` diff --git a/docs-cn/07-develop/03-insert-data/_rust_opts_telnet.mdx b/docs-cn/07-develop/03-insert-data/_rust_opts_telnet.mdx new file mode 100644 index 0000000000000000000000000000000000000000..14021f43d8aff30c35dc30c5d278d4e51f375024 --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/_rust_opts_telnet.mdx @@ -0,0 +1,3 @@ +```rust +{{#include docs-examples/rust/schemalessexample/examples/opentsdb_telnet_example.rs}} +``` diff --git a/docs-cn/07-develop/03-insert-data/_rust_sql.mdx b/docs-cn/07-develop/03-insert-data/_rust_sql.mdx new file mode 100644 index 0000000000000000000000000000000000000000..8e8013e4ad734efcc262ea2f750b82210a538e49 --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/_rust_sql.mdx @@ -0,0 +1,3 @@ +```rust +{{#include docs-examples/rust/restexample/examples/insert_example.rs}} +``` diff --git a/docs-cn/07-develop/03-insert-data/_rust_stmt.mdx b/docs-cn/07-develop/03-insert-data/_rust_stmt.mdx new file mode 100644 index 0000000000000000000000000000000000000000..590a7a0e717426ed0235331c49dfc578bc55b2f7 --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/_rust_stmt.mdx @@ -0,0 +1,3 @@ +```rust +{{#include docs-examples/rust/nativeexample/examples/stmt_example.rs}} +``` diff --git a/docs-cn/07-develop/03-insert-data/index.md b/docs-cn/07-develop/03-insert-data/index.md new file mode 100644 index 0000000000000000000000000000000000000000..55a28e4a8ba13501e2f481c9aba67b7300da98d0 --- /dev/null +++ b/docs-cn/07-develop/03-insert-data/index.md @@ -0,0 +1,12 @@ +--- +title: 写入数据 +--- + +TDengine 支持多种写入协议，包括 SQL，InfluxDB Line 协议, OpenTSDB Telnet 协议，OpenTSDB JSON 格式协议。数据可以单条插入，也可以批量插入，可以插入一个数据采集点的数据，也可以同时插入多个数据采集点的数据。同时，TDengine 支持多线程插入，支持时间乱序数据插入，也支持历史数据插入。InfluxDB Line 协议、OpenTSDB Telnet 协议和 OpenTSDB JSON 格式协议是 TDengine 支持的三种无模式写入协议。使用无模式方式写入无需提前创建超级表和子表，并且引擎能自适用数据对表结构做调整。 + +```mdx-code-block +import DocCardList from '@theme/DocCardList'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + + +``` \ No newline at end of file diff --git a/docs-cn/07-develop/04-query-data/_c.mdx b/docs-cn/07-develop/04-query-data/_c.mdx new file mode 100644 index 0000000000000000000000000000000000000000..76c9067e2f6af19465cf7c52c3e9b48bb868547d --- /dev/null +++ b/docs-cn/07-develop/04-query-data/_c.mdx @@ -0,0 +1,3 @@ +```c +{{#include docs-examples/c/query_example.c}} +``` \ No newline at end of file diff --git a/docs-cn/07-develop/04-query-data/_c_async.mdx b/docs-cn/07-develop/04-query-data/_c_async.mdx new file mode 100644 index 0000000000000000000000000000000000000000..09f3d3b3ff6d6644f837642ef41db459ba7c5753 --- /dev/null +++ b/docs-cn/07-develop/04-query-data/_c_async.mdx @@ -0,0 +1,3 @@ +```c +{{#include docs-examples/c/async_query_example.c:demo}} +``` \ No newline at end of file diff --git a/docs-cn/07-develop/04-query-data/_category_.yml b/docs-cn/07-develop/04-query-data/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..69273cb31cc54fd438bf82b408e529f8d3d9ccb4 --- /dev/null +++ b/docs-cn/07-develop/04-query-data/_category_.yml @@ -0,0 +1 @@ +label: 查询数据 diff --git a/docs-cn/07-develop/04-query-data/_cs.mdx b/docs-cn/07-develop/04-query-data/_cs.mdx new file mode 100644 index 0000000000000000000000000000000000000000..2ab52feb564eff0fe251bc9900ea2539171e5dba --- /dev/null +++ b/docs-cn/07-develop/04-query-data/_cs.mdx @@ -0,0 +1,3 @@ +```csharp +{{#include docs-examples/csharp/QueryExample.cs}} +``` diff --git a/docs-cn/07-develop/04-query-data/_cs_async.mdx b/docs-cn/07-develop/04-query-data/_cs_async.mdx new file mode 100644 index 0000000000000000000000000000000000000000..f868994b303e62016b5e2f9304275135855c6ae5 --- /dev/null +++ b/docs-cn/07-develop/04-query-data/_cs_async.mdx @@ -0,0 +1,3 @@ +```csharp +{{#include docs-examples/csharp/AsyncQueryExample.cs}} +``` diff --git a/docs-cn/07-develop/04-query-data/_go.mdx b/docs-cn/07-develop/04-query-data/_go.mdx new file mode 100644 index 0000000000000000000000000000000000000000..417c12315c06517e2f3de850ac9a379b7714b519 --- /dev/null +++ b/docs-cn/07-develop/04-query-data/_go.mdx @@ -0,0 +1,3 @@ +```go +{{#include docs-examples/go/query/sync/main.go}} +``` diff --git a/docs-cn/07-develop/04-query-data/_go_async.mdx b/docs-cn/07-develop/04-query-data/_go_async.mdx new file mode 100644 index 0000000000000000000000000000000000000000..72fff411b980a0dcbdcaf4274722c63e0351db6f --- /dev/null +++ b/docs-cn/07-develop/04-query-data/_go_async.mdx @@ -0,0 +1,3 @@ +```go +{{#include docs-examples/go/query/async/main.go}} +``` diff --git a/docs-cn/07-develop/04-query-data/_java.mdx b/docs-cn/07-develop/04-query-data/_java.mdx new file mode 100644 index 0000000000000000000000000000000000000000..519b9266144486231caf3ee593e973d438941ee4 --- /dev/null +++ b/docs-cn/07-develop/04-query-data/_java.mdx @@ -0,0 +1,3 @@ +```java +{{#include docs-examples/java/src/main/java/com/taos/example/RestQueryExample.java}} +``` diff --git a/docs-cn/07-develop/04-query-data/_js.mdx b/docs-cn/07-develop/04-query-data/_js.mdx new file mode 100644 index 0000000000000000000000000000000000000000..c5e4c4f3fc20d3940a2bc6e13e6a5dea8a15ff13 --- /dev/null +++ b/docs-cn/07-develop/04-query-data/_js.mdx @@ -0,0 +1,3 @@ +```js +{{#include docs-examples/node/nativeexample/query_example.js}} +``` diff --git a/docs-cn/07-develop/04-query-data/_js_async.mdx b/docs-cn/07-develop/04-query-data/_js_async.mdx new file mode 100644 index 0000000000000000000000000000000000000000..c65d54ed12f6c4bbeb333e0de0ba9ca4638bff84 --- /dev/null +++ b/docs-cn/07-develop/04-query-data/_js_async.mdx @@ -0,0 +1,3 @@ +```js +{{#include docs-examples/node/nativeexample/async_query_example.js}} +``` diff --git a/docs-cn/07-develop/04-query-data/_php.mdx b/docs-cn/07-develop/04-query-data/_php.mdx new file mode 100644 index 0000000000000000000000000000000000000000..6264bd99f534fbd800f1f349d93ac69b31c77397 --- /dev/null +++ b/docs-cn/07-develop/04-query-data/_php.mdx @@ -0,0 +1,3 @@ +```go +{{#include docs-examples/php/query.php}} +``` diff --git a/docs-cn/07-develop/04-query-data/_py.mdx b/docs-cn/07-develop/04-query-data/_py.mdx new file mode 100644 index 0000000000000000000000000000000000000000..6a1bacdd3ef91e9484c1d87d6a22de8b128e2144 --- /dev/null +++ b/docs-cn/07-develop/04-query-data/_py.mdx @@ -0,0 +1,11 @@ +通过迭代逐行获取查询结果。 + +```py +{{#include docs-examples/python/query_example.py:iter}} +``` + +一次获取所有查询结果，并把每一行转化为一个字典返回。 + +```py +{{#include docs-examples/python/query_example.py:fetch_all}} +``` diff --git a/docs-cn/07-develop/04-query-data/_py_async.mdx b/docs-cn/07-develop/04-query-data/_py_async.mdx new file mode 100644 index 0000000000000000000000000000000000000000..2399a50df645804788036e17bf223c53482d4eaf --- /dev/null +++ b/docs-cn/07-develop/04-query-data/_py_async.mdx @@ -0,0 +1,8 @@ +```py +{{#include docs-examples/python/async_query_example.py}} +``` + +:::note +这个示例程序，目前在 Windows 系统上还无法运行 + +::: diff --git a/docs-cn/07-develop/04-query-data/_rust.mdx b/docs-cn/07-develop/04-query-data/_rust.mdx new file mode 100644 index 0000000000000000000000000000000000000000..742d70fd025ff44b573eedf78441c9d73defad45 --- /dev/null +++ b/docs-cn/07-develop/04-query-data/_rust.mdx @@ -0,0 +1,3 @@ +```rust +{{#include docs-examples/rust/restexample/examples/query_example.rs}} +``` diff --git a/docs-cn/07-develop/04-query-data/index.mdx b/docs-cn/07-develop/04-query-data/index.mdx new file mode 100644 index 0000000000000000000000000000000000000000..b0a6bad3eaad174a97d8dce4e1ba0125cbf5dc03 --- /dev/null +++ b/docs-cn/07-develop/04-query-data/index.mdx @@ -0,0 +1,181 @@ +--- +title: 查询数据 +description: "主要查询功能，通过连接器执行同步查询和异步查询" +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import JavaQuery from "./_java.mdx"; +import PyQuery from "./_py.mdx"; +import GoQuery from "./_go.mdx"; +import RustQuery from "./_rust.mdx"; +import NodeQuery from "./_js.mdx"; +import CsQuery from "./_cs.mdx"; +import CQuery from "./_c.mdx"; +import PhpQuery from "./_php.mdx"; +import PyAsync from "./_py_async.mdx"; +import NodeAsync from "./_js_async.mdx"; +import CsAsync from "./_cs_async.mdx"; +import CAsync from "./_c_async.mdx"; + +## 主要查询功能 + +TDengine 采用 SQL 作为查询语言。应用程序可以通过 REST API 或连接器发送 SQL 语句，用户还可以通过 TDengine 命令行工具 taos 手动执行 SQL 即席查询（Ad-Hoc Query）。TDengine 支持如下查询功能： + +- 单列、多列数据查询 +- 标签和数值的多种过滤条件：>, <, =, <\>, like 等 +- 聚合结果的分组（Group by）、排序（Order by）、约束输出（Limit/Offset） +- 数值列及聚合结果的四则运算 +- 时间戳对齐的连接查询（Join Query: 隐式连接）操作 +- 多种聚合/计算函数: count, max, min, avg, sum, twa, stddev, leastsquares, top, bottom, first, last, percentile, apercentile, last_row, spread, diff 等 + +例如：在命令行工具 taos 中，从表 d1001 中查询出 voltage > 215 的记录，按时间降序排列，仅仅输出 2 条。 + +```sql +taos> select * from d1001 where voltage > 215 order by ts desc limit 2; + ts | current | voltage | phase | +====================================================================================== + 2018-10-03 14:38:16.800 | 12.30000 | 221 | 0.31000 | + 2018-10-03 14:38:15.000 | 12.60000 | 218 | 0.33000 | +Query OK, 2 row(s) in set (0.001100s) +``` + +为满足物联网场景的需求，TDengine 支持几个特殊的函数，比如 twa(时间加权平均)，spread (最大值与最小值的差)，last_row(最后一条记录)等，更多与物联网场景相关的函数将添加进来。TDengine 还支持连续查询。 + +具体的查询语法请看 [TAOS SQL 的数据查询](/taos-sql/select) 章节。 + +## 多表聚合查询 + +物联网场景中，往往同一个类型的数据采集点有多个。TDengine 采用超级表(STable)的概念来描述某一个类型的数据采集点，一张普通的表来描述一个具体的数据采集点。同时 TDengine 使用标签来描述数据采集点的静态属性，一个具体的数据采集点有具体的标签值。通过指定标签的过滤条件，TDengine 提供了一高效的方法将超级表(某一类型的数据采集点)所属的子表进行聚合查询。对普通表的聚合函数以及绝大部分操作都适用于超级表，语法完全一样。 + +### 示例一 + +在 TAOS Shell，查找北京所有智能电表采集的电压平均值，并按照 location 分组。 + +``` +taos> SELECT AVG(voltage) FROM meters GROUP BY location; + avg(voltage) | location | +============================================================= + 222.000000000 | Beijing.Haidian | + 219.200000000 | Beijing.Chaoyang | +Query OK, 2 row(s) in set (0.002136s) +``` + +### 示例二 + +在 TAOS shell, 查找 groupId 为 2 的所有智能电表过去 24 小时的记录条数，电流的最大值。 + +``` +taos> SELECT count(*), max(current) FROM meters where groupId = 2 and ts > now - 24h; + cunt(*) | max(current) | +================================== + 5 | 13.4 | +Query OK, 1 row(s) in set (0.002136s) +``` + +TDengine 仅容许对属于同一个超级表的表之间进行聚合查询，不同超级表之间的聚合查询不支持。在 [TAOS SQL 的数据查询](/taos-sql/select) 一章，查询类操作都会注明是否支持超级表。 + +## 降采样查询、插值 + +物联网场景里，经常需要通过降采样（down sampling）将采集的数据按时间段进行聚合。TDengine 提供了一个简便的关键词 interval 让按照时间窗口的查询操作变得极为简单。比如，将智能电表 d1001 采集的电流值每 10 秒钟求和 + +``` +taos> SELECT sum(current) FROM d1001 INTERVAL(10s); + ts | sum(current) | +====================================================== + 2018-10-03 14:38:00.000 | 10.300000191 | + 2018-10-03 14:38:10.000 | 24.900000572 | +Query OK, 2 row(s) in set (0.000883s) +``` + +降采样操作也适用于超级表，比如：将北京所有智能电表采集的电流值每秒钟求和 + +``` +taos> SELECT SUM(current) FROM meters where location like "Beijing%" INTERVAL(1s); + ts | sum(current) | +====================================================== + 2018-10-03 14:38:04.000 | 10.199999809 | + 2018-10-03 14:38:05.000 | 32.900000572 | + 2018-10-03 14:38:06.000 | 11.500000000 | + 2018-10-03 14:38:15.000 | 12.600000381 | + 2018-10-03 14:38:16.000 | 36.000000000 | +Query OK, 5 row(s) in set (0.001538s) +``` + +降采样操作也支持时间偏移，比如：将所有智能电表采集的电流值每秒钟求和，但要求每个时间窗口从 500 毫秒开始 + +``` +taos> SELECT SUM(current) FROM meters INTERVAL(1s, 500a); + ts | sum(current) | +====================================================== + 2018-10-03 14:38:04.500 | 11.189999809 | + 2018-10-03 14:38:05.500 | 31.900000572 | + 2018-10-03 14:38:06.500 | 11.600000000 | + 2018-10-03 14:38:15.500 | 12.300000381 | + 2018-10-03 14:38:16.500 | 35.000000000 | +Query OK, 5 row(s) in set (0.001521s) +``` + +物联网场景里，每个数据采集点采集数据的时间是难同步的，但很多分析算法(比如 FFT)需要把采集的数据严格按照时间等间隔的对齐，在很多系统里，需要应用自己写程序来处理，但使用 TDengine 的降采样操作就轻松解决。 + +如果一个时间间隔里，没有采集的数据，TDengine 还提供插值计算的功能。 + +语法规则细节请见 [TAOS SQL 的按时间窗口切分聚合](/taos-sql/interval) 章节。 + +## 示例代码 + +### 查询数据 + +在 [SQL 写入](/develop/insert-data/sql-writing) 一章，我们创建了 power 数据库，并向 meters 表写入了一些数据，以下示例代码展示如何查询这个表的数据。 + + + + + + + + + + + + + + + + + + + + + + + + + + + + +:::note + +1. 无论是使用 REST 连接还是原生连接的连接器，以上示例代码都能正常工作。 +2. 唯一需要注意的是：由于 REST 接口无状态， 不能使用 `use db` 语句来切换数据库。 + +::: + +### 异步查询 + +除同步查询 API 之外，TDengine 还提供性能更高的异步调用 API 处理数据插入、查询操作。在软硬件环境相同的情况下，异步 API 处理数据插入的速度比同步 API 快 2-4 倍。异步 API 采用非阻塞式的调用方式，在系统真正完成某个具体数据库操作前，立即返回。调用的线程可以去处理其他工作，从而可以提升整个应用的性能。异步 API 在网络延迟严重的情况下，优点尤为突出。 + +需要注意的是，只有使用原生连接的连接器，才能使用异步查询功能。 + + + + + + + + + + + + diff --git a/docs-cn/07-develop/05-continuous-query.mdx b/docs-cn/07-develop/05-continuous-query.mdx new file mode 100644 index 0000000000000000000000000000000000000000..2fd1b3cc755188f513fe511541a84efa3558d3ea --- /dev/null +++ b/docs-cn/07-develop/05-continuous-query.mdx @@ -0,0 +1,84 @@ +--- +sidebar_label: 连续查询 +description: "连续查询是一个按照预设频率自动执行的查询功能，提供按照时间窗口的聚合查询能力，是一种简化的时间驱动流式计算。" +title: "连续查询（Continuous Query）" +--- + +连续查询是 TDengine 定期自动执行的查询，采用滑动窗口的方式进行计算，是一种简化的时间驱动的流式计算。针对库中的表或超级表，TDengine 可提供定期自动执行的连续查询，用户可让 TDengine 推送查询的结果，也可以将结果再写回到 TDengine 中。每次执行的查询是一个时间窗口，时间窗口随着时间流动向前滑动。在定义连续查询的时候需要指定时间窗口（time window, 参数 interval）大小和每次前向增量时间（forward sliding times, 参数 sliding）。 + +TDengine 的连续查询采用时间驱动模式，可以直接使用 TAOS SQL 进行定义，不需要额外的操作。使用连续查询，可以方便快捷地按照时间窗口生成结果，从而对原始采集数据进行降采样（down sampling）。用户通过 TAOS SQL 定义连续查询以后，TDengine 自动在最后的一个完整的时间周期末端拉起查询，并将计算获得的结果推送给用户或者写回 TDengine。 + +TDengine 提供的连续查询与普通流计算中的时间窗口计算具有以下区别： + +- 不同于流计算的实时反馈计算结果，连续查询只在时间窗口关闭以后才开始计算。例如时间周期是 1 天，那么当天的结果只会在 23:59:59 以后才会生成。 +- 如果有历史记录写入到已经计算完成的时间区间，连续查询并不会重新进行计算，也不会重新将结果推送给用户。对于写回 TDengine 的模式，也不会更新已经存在的计算结果。 +- 使用连续查询推送结果的模式，服务端并不缓存客户端计算状态，也不提供 Exactly-Once 的语义保证。如果用户的应用端崩溃，再次拉起的连续查询将只会从再次拉起的时间开始重新计算最近的一个完整的时间窗口。如果使用写回模式，TDengine 可确保数据写回的有效性和连续性。 + +## 连续查询语法 + +```sql +[CREATE TABLE AS] SELECT select_expr [, select_expr ...] + FROM {tb_name_list} + [WHERE where_condition] + [INTERVAL(interval_val [, interval_offset]) [SLIDING sliding_val]] + +``` + +INTERVAL: 连续查询作用的时间窗口 + +SLIDING: 连续查询的时间窗口向前滑动的时间间隔 + +## 使用连续查询 + +下面以智能电表场景为例介绍连续查询的具体使用方法。假设我们通过下列 SQL 语句创建了超级表和子表： + +```sql +create table meters (ts timestamp, current float, voltage int, phase float) tags (location binary(64), groupId int); +create table D1001 using meters tags ("Beijing.Chaoyang", 2); +create table D1002 using meters tags ("Beijing.Haidian", 2); +... +``` + +可以通过下面这条 SQL 语句以一分钟为时间窗口、30 秒为前向增量统计这些电表的平均电压。 + +```sql +select avg(voltage) from meters interval(1m) sliding(30s); +``` + +每次执行这条语句，都会重新计算所有数据。 如果需要每隔 30 秒执行一次来增量计算最近一分钟的数据，可以把上面的语句改进成下面的样子，每次使用不同的 `startTime` 并定期执行： + +```sql +select avg(voltage) from meters where ts > {startTime} interval(1m) sliding(30s); +``` + +这样做没有问题，但 TDengine 提供了更简单的方法，只要在最初的查询语句前面加上 `create table {tableName} as` 就可以了，例如： + +```sql +create table avg_vol as select avg(voltage) from meters interval(1m) sliding(30s); +``` + +会自动创建一个名为 `avg_vol` 的新表，然后每隔 30 秒，TDengine 会增量执行 `as` 后面的 SQL 语句，并将查询结果写入这个表中，用户程序后续只要从 `avg_vol` 中查询数据即可。例如： + +```sql +taos> select * from avg_vol; + ts | avg_voltage_ | +=================================================== + 2020-07-29 13:37:30.000 | 222.0000000 | + 2020-07-29 13:38:00.000 | 221.3500000 | + 2020-07-29 13:38:30.000 | 220.1700000 | + 2020-07-29 13:39:00.000 | 223.0800000 | +``` + +需要注意，查询时间窗口的最小值是 10 毫秒，没有时间窗口范围的上限。 + +此外，TDengine 还支持用户指定连续查询的起止时间。如果不输入开始时间，连续查询将从第一条原始数据所在的时间窗口开始；如果没有输入结束时间，连续查询将永久运行；如果用户指定了结束时间，连续查询在系统时间达到指定的时间以后停止运行。比如使用下面的 SQL 创建的连续查询将运行一小时，之后会自动停止。 + +```sql +create table avg_vol as select avg(voltage) from meters where ts > now and ts <= now + 1h interval(1m) sliding(30s); +``` + +需要说明的是，上面例子中的 `now` 是指创建连续查询的时间，而不是查询执行的时间，否则，查询就无法自动停止了。另外，为了尽量避免原始数据延迟写入导致的问题，TDengine 中连续查询的计算有一定的延迟。也就是说，一个时间窗口过去后，TDengine 并不会立即计算这个窗口的数据，所以要稍等一会（一般不会超过 1 分钟）才能查到计算结果。 + +## 管理连续查询 + +用户可在控制台中通过 `show streams` 命令来查看系统中全部运行的连续查询，并可以通过 `kill stream` 命令杀掉对应的连续查询。后续版本会提供更细粒度和便捷的连续查询管理命令。 diff --git a/docs-cn/07-develop/06-subscribe.mdx b/docs-cn/07-develop/06-subscribe.mdx new file mode 100644 index 0000000000000000000000000000000000000000..d471c114e827d7c4b40195c2c1b3c8f6a9d26ed4 --- /dev/null +++ b/docs-cn/07-develop/06-subscribe.mdx @@ -0,0 +1,253 @@ +--- +sidebar_label: 数据订阅 +description: "轻量级的数据订阅与推送服务。连续写入到 TDengine 中的时序数据能够被自动推送到订阅客户端。" +title: 数据订阅 +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import Java from "./_sub_java.mdx"; +import Python from "./_sub_python.mdx"; +import Go from "./_sub_go.mdx"; +import Rust from "./_sub_rust.mdx"; +import Node from "./_sub_node.mdx"; +import CSharp from "./_sub_cs.mdx"; +import CDemo from "./_sub_c.mdx"; + +基于数据天然的时间序列特性，TDengine 的数据写入（insert）与消息系统的数据发布（pub）逻辑上一致，均可视为系统中插入一条带时间戳的新记录。同时，TDengine 在内部严格按照数据时间序列单调递增的方式保存数据。本质上来说，TDengine 中每一张表均可视为一个标准的消息队列。 + +TDengine 内嵌支持轻量级的消息订阅与推送服务。使用系统提供的 API，用户可使用普通查询语句订阅数据库中的一张或多张表。订阅的逻辑和操作状态的维护均是由客户端完成，客户端定时轮询服务器是否有新的记录到达，有新的记录到达就会将结果反馈到客户。 + +TDengine 的订阅与推送服务的状态是由客户端维持，TDengine 服务端并不维持。因此如果应用重启，从哪个时间点开始获取最新数据，由应用决定。 + +TDengine 的 API 中，与订阅相关的主要有以下三个： + +```c +taos_subscribe +taos_consume +taos_unsubscribe +``` + +这些 API 的文档请见 [C/C++ Connector](/reference/connector/cpp)，下面仍以智能电表场景为例介绍一下它们的具体用法（超级表和子表结构请参考上一节“连续查询”），完整的示例代码可以在 [这里](https://github.com/taosdata/TDengine/blob/master/examples/c/subscribe.c) 找到。 + +如果我们希望当某个电表的电流超过一定限制（比如 10A）后能得到通知并进行一些处理， 有两种方法：一是分别对每张子表进行查询，每次查询后记录最后一条数据的时间戳，后续只查询这个时间戳之后的数据： + +```sql +select * from D1001 where ts > {last_timestamp1} and current > 10; +select * from D1002 where ts > {last_timestamp2} and current > 10; +... +``` + +这确实可行，但随着电表数量的增加，查询数量也会增加，客户端和服务端的性能都会受到影响，当电表数增长到一定的程度，系统就无法承受了。 + +另一种方法是对超级表进行查询。这样，无论有多少电表，都只需一次查询： + +```sql +select * from meters where ts > {last_timestamp} and current > 10; +``` + +但是，如何选择 `last_timestamp` 就成了一个新的问题。因为，一方面数据的产生时间（也就是数据时间戳）和数据入库的时间一般并不相同，有时偏差还很大；另一方面，不同电表的数据到达 TDengine 的时间也会有差异。所以，如果我们在查询中使用最慢的那台电表的数据的时间戳作为 `last_timestamp`，就可能重复读入其它电表的数据；如果使用最快的电表的时间戳，其它电表的数据就可能被漏掉。 + +TDengine 的订阅功能为上面这个问题提供了一个彻底的解决方案。 + +首先是使用 `taos_subscribe` 创建订阅： + +```c +TAOS_SUB* tsub = NULL; +if (async) { +　　// create an asynchronized subscription, the callback function will be called every 1s +　　tsub = taos_subscribe(taos, restart, topic, sql, subscribe_callback, &blockFetch, 1000); +} else { +　　// create an synchronized subscription, need to call 'taos_consume' manually +　　tsub = taos_subscribe(taos, restart, topic, sql, NULL, NULL, 0); +} +``` + +TDengine 中的订阅既可以是同步的，也可以是异步的，上面的代码会根据从命令行获取的参数 `async` 的值来决定使用哪种方式。这里，同步的意思是用户程序要直接调用 `taos_consume` 来拉取数据，而异步则由 API 在内部的另一个线程中调用 `taos_consume`，然后把拉取到的数据交给回调函数 `subscribe_callback`去处理。（注意，`subscribe_callback` 中不宜做较为耗时的操作，否则有可能导致客户端阻塞等不可控的问题。） + +参数 `taos` 是一个已经建立好的数据库连接，在同步模式下无特殊要求。但在异步模式下，需要注意它不会被其它线程使用，否则可能导致不可预计的错误，因为回调函数在 API 的内部线程中被调用，而 TDengine 的部分 API 不是线程安全的。 + +参数 `sql` 是查询语句，可以在其中使用 where 子句指定过滤条件。在我们的例子中，如果只想订阅电流超过 10A 时的数据，可以这样写： + +```sql +select * from meters where current > 10; +``` + +注意，这里没有指定起始时间，所以会读到所有时间的数据。如果只想从一天前的数据开始订阅，而不需要更早的历史数据，可以再加上一个时间条件： + +```sql +select * from meters where ts > now - 1d and current > 10; +``` + +订阅的 `topic` 实际上是它的名字，因为订阅功能是在客户端 API 中实现的，所以没必要保证它全局唯一，但需要它在一台客户端机器上唯一。 + +如果名为 `topic` 的订阅不存在，参数 `restart` 没有意义；但如果用户程序创建这个订阅后退出，当它再次启动并重新使用这个 `topic` 时，`restart` 就会被用于决定是从头开始读取数据，还是接续上次的位置进行读取。本例中，如果 `restart` 是 **true**（非零值），用户程序肯定会读到所有数据。但如果这个订阅之前就存在了，并且已经读取了一部分数据，且 `restart` 是 **false**（**0**），用户程序就不会读到之前已经读取的数据了。 + +`taos_subscribe`的最后一个参数是以毫秒为单位的轮询周期。在同步模式下，如果前后两次调用 `taos_consume` 的时间间隔小于此时间，`taos_consume` 会阻塞，直到间隔超过此时间。异步模式下，这个时间是两次调用回调函数的最小时间间隔。 + +`taos_subscribe` 的倒数第二个参数用于用户程序向回调函数传递附加参数，订阅 API 不对其做任何处理，只原样传递给回调函数。此参数在同步模式下无意义。 + +订阅创建以后，就可以消费其数据了，同步模式下，示例代码是下面的 else 部分： + +```c +if (async) { +　　getchar(); +} else while(1) { +　　TAOS_RES* res = taos_consume(tsub); +　　if (res == NULL) { +　　　　printf("failed to consume data."); +　　　　break; +　　} else { +　　　　print_result(res, blockFetch); +　　　　getchar(); +　　} +} +``` + +这里是一个 **while** 循环，用户每按一次回车键就调用一次 `taos_consume`，而 `taos_consume` 的返回值是查询到的结果集，与 `taos_use_result` 完全相同，例子中使用这个结果集的代码是函数 `print_result`： + +```c +void print_result(TAOS_RES* res, int blockFetch) { +　　TAOS_ROW row = NULL; +　　int num_fields = taos_num_fields(res); +　　TAOS_FIELD* fields = taos_fetch_fields(res); +　　int nRows = 0; +　　if (blockFetch) { +　　　　nRows = taos_fetch_block(res, &row); +　　　　for (int i = 0; i < nRows; i++) { +　　　　　　char temp[256]; +　　　　　　taos_print_row(temp, row + i, fields, num_fields); +　　　　　　puts(temp); +　　　　} +　　} else { +　　　　while ((row = taos_fetch_row(res))) { +　　　　　　char temp[256]; +　　　　　　taos_print_row(temp, row, fields, num_fields); +　　　　　　puts(temp); +　　　　　　nRows++; +　　　　} +　　} +　　printf("%d rows consumed.\n", nRows); +} +``` + +其中的 `taos_print_row` 用于处理订阅到数据，在我们的例子中，它会打印出所有符合条件的记录。而异步模式下，消费订阅到的数据则显得更为简单： + +```c +void subscribe_callback(TAOS_SUB* tsub, TAOS_RES *res, void* param, int code) { +　　print_result(res, *(int*)param); +} +``` + +当要结束一次数据订阅时，需要调用 `taos_unsubscribe`： + +```c +taos_unsubscribe(tsub, keep); +``` + +其第二个参数，用于决定是否在客户端保留订阅的进度信息。如果这个参数是**false**（**0**），那无论下次调用 `taos_subscribe` 时的 `restart` 参数是什么，订阅都只能重新开始。另外，进度信息的保存位置是 _{DataDir}/subscribe/_ 这个目录下，每个订阅有一个与其 `topic` 同名的文件，删掉某个文件，同样会导致下次创建其对应的订阅时只能重新开始。 + +代码介绍完毕，我们来看一下实际的运行效果。假设： + +- 示例代码已经下载到本地 +- TDengine 也已经在同一台机器上安装好 +- 示例所需的数据库、超级表、子表已经全部创建好 + +则可以在示例代码所在目录执行以下命令来编译并启动示例程序： + +```bash +make +./subscribe -sql='select * from meters where current > 10;' +``` + +示例程序启动后，打开另一个终端窗口，启动 TDengine CLI 向 **D1001** 插入一条电流为 12A 的数据： + +```sql +$ taos +> use test; +> insert into D1001 values(now, 12, 220, 1); +``` + +这时，因为电流超过了 10A，您应该可以看到示例程序将它输出到了屏幕上。您可以继续插入一些数据观察示例程序的输出。 + +## 示例程序 + +下面的示例程序展示是如何使用连接器订阅所有电流超过 10A 的记录。 + +### 准备数据 + +``` +# create database "power" +taos> create database power; +# use "power" as the database in following operations +taos> use power; +# create super table "meters" +taos> create table meters(ts timestamp, current float, voltage int, phase int) tags(location binary(64), groupId int); +# create tabes using the schema defined by super table "meters" +taos> create table d1001 using meters tags ("Beijing.Chaoyang", 2); +taos> create table d1002 using meters tags ("Beijing.Haidian", 2); +# insert some rows +taos> insert into d1001 values("2020-08-15 12:00:00.000", 12, 220, 1),("2020-08-15 12:10:00.000", 12.3, 220, 2),("2020-08-15 12:20:00.000", 12.2, 220, 1); +taos> insert into d1002 values("2020-08-15 12:00:00.000", 9.9, 220, 1),("2020-08-15 12:10:00.000", 10.3, 220, 1),("2020-08-15 12:20:00.000", 11.2, 220, 1); +# filter out the rows in which current is bigger than 10A +taos> select * from meters where current > 10; + ts | current | voltage | phase | location | groupid | +=========================================================================================================== + 2020-08-15 12:10:00.000 | 10.30000 | 220 | 1 | Beijing.Haidian | 2 | + 2020-08-15 12:20:00.000 | 11.20000 | 220 | 1 | Beijing.Haidian | 2 | + 2020-08-15 12:00:00.000 | 12.00000 | 220 | 1 | Beijing.Chaoyang | 2 | + 2020-08-15 12:10:00.000 | 12.30000 | 220 | 2 | Beijing.Chaoyang | 2 | + 2020-08-15 12:20:00.000 | 12.20000 | 220 | 1 | Beijing.Chaoyang | 2 | +Query OK, 5 row(s) in set (0.004896s) +``` +### 示例代码 + + + + + + + + + {/* + + */} + + + + {/* + + + + + */} + + + + + +### 运行示例程序 + +示例程序会先消费符合查询条件的所有历史数据： + +```bash +ts: 1597464000000 current: 12.0 voltage: 220 phase: 1 location: Beijing.Chaoyang groupid : 2 +ts: 1597464600000 current: 12.3 voltage: 220 phase: 2 location: Beijing.Chaoyang groupid : 2 +ts: 1597465200000 current: 12.2 voltage: 220 phase: 1 location: Beijing.Chaoyang groupid : 2 +ts: 1597464600000 current: 10.3 voltage: 220 phase: 1 location: Beijing.Haidian groupid : 2 +ts: 1597465200000 current: 11.2 voltage: 220 phase: 1 location: Beijing.Haidian groupid : 2 +``` + +接着，使用 TDengine CLI 向表中新增一条数据： + +``` +# taos +taos> use power; +taos> insert into d1001 values(now, 12.4, 220, 1); +``` + +因为这条数据的电流大于 10A，示例程序会将其消费： + +``` +ts: 1651146662805 current: 12.4 voltage: 220 phase: 1 location: Beijing.Chaoyang groupid: 2 +``` diff --git a/docs-cn/07-develop/07-cache.md b/docs-cn/07-develop/07-cache.md new file mode 100644 index 0000000000000000000000000000000000000000..fd31335310d62d792e5173e38a9aa778ee6c6c60 --- /dev/null +++ b/docs-cn/07-develop/07-cache.md @@ -0,0 +1,21 @@ +--- +sidebar_label: 缓存 +title: 缓存 +description: "提供写驱动的缓存管理机制，将每个表最近写入的一条记录持续保存在缓存中，可以提供高性能的最近状态查询。" +--- + +TDengine 采用时间驱动缓存管理策略（First-In-First-Out，FIFO），又称为写驱动的缓存管理机制。这种策略有别于读驱动的数据缓存模式（Least-Recent-Used，LRU），直接将最近写入的数据保存在系统的缓存中。当缓存达到临界值的时候，将最早的数据批量写入磁盘。一般意义上来说，对于物联网数据的使用，用户最为关心最近产生的数据，即当前状态。TDengine 充分利用了这一特性，将最近到达的（当前状态）数据保存在缓存中。 + +TDengine 通过查询函数向用户提供毫秒级的数据获取能力。直接将最近到达的数据保存在缓存中，可以更加快速地响应用户针对最近一条或一批数据的查询分析，整体上提供更快的数据库查询响应能力。从这个意义上来说，可通过设置合适的配置参数将 TDengine 作为数据缓存来使用，而不需要再部署额外的缓存系统，可有效地简化系统架构，降低运维的成本。需要注意的是，TDengine 重启以后系统的缓存将被清空，之前缓存的数据均会被批量写入磁盘，缓存的数据将不会像专门的 key-value 缓存系统再将之前缓存的数据重新加载到缓存中。 + +TDengine 分配固定大小的内存空间作为缓存空间，缓存空间可根据应用的需求和硬件资源配置。通过适当的设置缓存空间，TDengine 可以提供极高性能的写入和查询的支持。TDengine 中每个虚拟节点（virtual node）创建时分配独立的缓存池。每个虚拟节点管理自己的缓存池，不同虚拟节点间不共享缓存池。每个虚拟节点内部所属的全部表共享该虚拟节点的缓存池。 + +TDengine 将内存池按块划分进行管理，数据在内存块里是以行（row）的形式存储。一个 vnode 的内存池是在 vnode 创建时按块分配好，而且每个内存块按照先进先出的原则进行管理。在创建内存池时，块的大小由系统配置参数 cache 决定；每个 vnode 中内存块的数目则由配置参数 blocks 决定。因此对于一个 vnode，总的内存大小为：`cache * blocks`。一个 cache block 需要保证每张表能存储至少几十条以上记录，才会有效率。 + +你可以通过函数 last_row() 快速获取一张表或一张超级表的最后一条记录，这样很便于在大屏显示各设备的实时状态或采集值。例如： + +```sql +select last_row(voltage) from meters where location='Beijing.Chaoyang'; +``` + +该 SQL 语句将获取所有位于北京朝阳区的电表最后记录的电压值。 diff --git a/docs-cn/07-develop/08-udf.md b/docs-cn/07-develop/08-udf.md new file mode 100644 index 0000000000000000000000000000000000000000..09681650db32200e60c0fdb787d3e455dd339d85 --- /dev/null +++ b/docs-cn/07-develop/08-udf.md @@ -0,0 +1,208 @@ +--- +sidebar_label: 用户定义函数 +title: UDF（用户定义函数） +description: "支持用户编码的聚合函数和标量函数，在查询中嵌入并使用用户定义函数，拓展查询的能力和功能。" +--- + +在有些应用场景中，应用逻辑需要的查询无法直接使用系统内置的函数来表示。利用 UDF 功能，TDengine 可以插入用户编写的处理代码并在查询中使用它们，就能够很方便地解决特殊应用场景中的使用需求。 UDF 通常以数据表中的一列数据做为输入，同时支持以嵌套子查询的结果作为输入。 + +从 2.2.0.0 版本开始，TDengine 支持通过 C/C++ 语言进行 UDF 定义。接下来结合示例讲解 UDF 的使用方法。 + +用户可以通过 UDF 实现两类函数： 标量函数 和 聚合函数。 + +## 用 C/C++ 语言来定义 UDF + +### 标量函数 + +用户可以按照下列函数模板定义自己的标量计算函数 + + `void udfNormalFunc(char* data, short itype, short ibytes, int numOfRows, long long* ts, char* dataOutput, char* interBuf, char* tsOutput, int* numOfOutput, short otype, short obytes, SUdfInit* buf)` + + 其中 udfNormalFunc 是函数名的占位符，以上述模板实现的函数对行数据块进行标量计算，其参数项是固定的，用于按照约束完成与引擎之间的数据交换。 + +- udfNormalFunc 中各参数的具体含义是： + - data：输入数据。 + - itype：输入数据的类型。这里采用的是短整型表示法，与各种数据类型对应的值可以参见 [column_meta 中的列类型说明](/reference/rest-api/)。例如 4 用于表示 INT 型。 + - iBytes：输入数据中每个值会占用的字节数。 + - numOfRows：输入数据的总行数。 + - ts：主键时间戳在输入中的列数据(只读)。 + - dataOutput：输出数据的缓冲区，缓冲区大小为用户指定的输出类型大小 \* numOfRows。 + - interBuf：中间计算结果的缓冲区，大小为用户在创建 UDF 时指定的 BUFSIZE 大小。通常用于计算中间结果与最终结果不一致时使用，由引擎负责分配与释放。 + - tsOutput：主键时间戳在输出时的列数据，如果非空可用于输出结果对应的时间戳。 + - numOfOutput：输出结果的个数（行数）。 + - oType：输出数据的类型。取值含义与 itype 参数一致。 + - oBytes：输出数据中每个值占用的字节数。 + - buf：用于在 UDF 与引擎间的状态控制信息传递块。 + + [add_one.c](https://github.com/taosdata/TDengine/blob/develop/tests/script/sh/add_one.c) 是结构最简单的 UDF 实现，也即上面定义的 udfNormalFunc 函数的一个具体实现。其功能为：对传入的一个数据列（可能因 WHERE 子句进行了筛选）中的每一项，都输出 +1 之后的值，并且要求输入的列数据类型为 INT。 + +### 聚合函数 + +用户可以按照如下函数模板定义自己的聚合函数。 + +`void abs_max_merge(char* data, int32_t numOfRows, char* dataOutput, int32_t* numOfOutput, SUdfInit* buf)` + +其中 udfMergeFunc 是函数名的占位符，以上述模板实现的函数用于对计算中间结果进行聚合，只有针对超级表的聚合查询才需要调用该函数。其中各参数的具体含义是： + + - data：udfNormalFunc 的输出数据数组，如果使用了 interBuf 那么 data 就是 interBuf 的数组。 + - numOfRows：data 中数据的行数。 + - dataOutput：输出数据的缓冲区，大小等于一条最终结果的大小。如果此时输出还不是最终结果，可以选择输出到 interBuf 中即 data 中。 + - numOfOutput：输出结果的个数（行数）。 + - buf：用于在 UDF 与引擎间的状态控制信息传递块。 + +[abs_max.c](https://github.com/taosdata/TDengine/blob/develop/tests/script/sh/abs_max.c) 实现的是一个聚合函数，功能是对一组数据按绝对值取最大值。 + +其计算过程为：与所在查询语句相关的数据会被分为多个行数据块，对每个行数据块调用 udfNormalFunc（在本例的实现代码中，实际函数名是 `abs_max`)来生成每个子表的中间结果，再将子表的中间结果调用 udfMergeFunc（本例中，其实际的函数名是 `abs_max_merge`）进行聚合，生成超级表的最终聚合结果或中间结果。聚合查询最后还会通过 udfFinalizeFunc（本例中，其实际的函数名是 `abs_max_finalize`）再把超级表的中间结果处理为最终结果，最终结果只能含 0 或 1 条结果数据。 + +其他典型场景，如协方差的计算，也可通过定义聚合 UDF 的方式实现。 + +### 最终计算 + +用户可以按下面的函数模板实现自己的函数对计算结果进行最终计算，通常用于有 interBuf 使用的场景。 + +`void abs_max_finalize(char* dataOutput, char* interBuf, int* numOfOutput, SUdfInit* buf)` + +其中 udfFinalizeFunc 是函数名的占位符 ，其中各参数的具体含义是： + - dataOutput：输出数据的缓冲区。 + - interBuf：中间结算结果缓冲区，可作为输入。 + - numOfOutput：输出数据的个数，对聚合函数来说只能是 0 或者 1。 + - buf：用于在 UDF 与引擎间的状态控制信息传递块。 + +## UDF 实现方式的规则总结 + +三类 UDF 函数： udfNormalFunc、udfMergeFunc、udfFinalizeFunc ，其函数名约定使用相同的前缀，此前缀即 udfNormalFunc 的实际函数名，也即 udfNormalFunc 函数不需要在实际函数名后添加后缀；而udfMergeFunc 的函数名要加上后缀 `_merge`、udfFinalizeFunc 的函数名要加上后缀 `_finalize`，这是 UDF 实现规则的一部分，系统会按照这些函数名后缀来调用相应功能。 + +根据 UDF 函数类型的不同，用户所要实现的功能函数也不同： + +- 标量函数：UDF 中需实现 udfNormalFunc。 +- 聚合函数：UDF 中需实现 udfNormalFunc、udfMergeFunc（对超级表查询）、udfFinalizeFunc。 + +:::note +如果对应的函数不需要具体的功能，也需要实现一个空函数。 + +::: + +## 编译 UDF + +用户定义函数的 C 语言源代码无法直接被 TDengine 系统使用，而是需要先编译为 动态链接库，之后才能载入 TDengine 系统。 + +例如，按照上一章节描述的规则准备好了用户定义函数的源代码 add_one.c，以 Linux 为例可以执行如下指令编译得到动态链接库文件： + +```bash +gcc -g -O0 -fPIC -shared add_one.c -o add_one.so +``` + +这样就准备好了动态链接库 add_one.so 文件，可以供后文创建 UDF 时使用了。为了保证可靠的系统运行，编译器 GCC 推荐使用 7.5 及以上版本。 + +## 在系统中管理和使用 UDF + +### 创建 UDF + +用户可以通过 SQL 指令在系统中加载客户端所在主机上的 UDF 函数库（不能通过 RESTful 接口或 HTTP 管理界面来进行这一过程）。一旦创建成功，则当前 TDengine 集群的所有用户都可以在 SQL 指令中使用这些函数。UDF 存储在系统的 MNode 节点上，因此即使重启 TDengine 系统，已经创建的 UDF 也仍然可用。 + +在创建 UDF 时，需要区分标量函数和聚合函数。如果创建时声明了错误的函数类别，则可能导致通过 SQL 指令调用函数时出错。此外， UDF 支持输入与输出类型不一致，用户需要保证输入数据类型与 UDF 程序匹配，UDF 输出数据类型与 OUTPUTTYPE 匹配。 + +- 创建标量函数 +```sql +CREATE FUNCTION ids(X) AS ids(Y) OUTPUTTYPE typename(Z) [ BUFSIZE B ]; +``` + + - ids(X)：标量函数未来在 SQL 指令中被调用时的函数名，必须与函数实现中 udfNormalFunc 的实际名称一致； + - ids(Y)：包含 UDF 函数实现的动态链接库的库文件绝对路径（指的是库文件在当前客户端所在主机上的保存路径，通常是指向一个 .so 文件），这个路径需要用英文单引号或英文双引号括起来； + - typename(Z)：此函数计算结果的数据类型，与上文中 udfNormalFunc 的 itype 参数不同，这里不是使用数字表示法，而是直接写类型名称即可； + - B：中间计算结果的缓冲区大小，单位是字节，最小 0，最大 512，如果不使用可以不设置。 + + 例如，如下语句可以把 add_one.so 创建为系统中可用的 UDF： + + ```sql + CREATE FUNCTION add_one AS "/home/taos/udf_example/add_one.so" OUTPUTTYPE INT; + ``` + +- 创建聚合函数： +```sql +CREATE AGGREGATE FUNCTION ids(X) AS ids(Y) OUTPUTTYPE typename(Z) [ BUFSIZE B ]; +``` + + - ids(X)：聚合函数未来在 SQL 指令中被调用时的函数名，必须与函数实现中 udfNormalFunc 的实际名称一致； + - ids(Y)：包含 UDF 函数实现的动态链接库的库文件绝对路径（指的是库文件在当前客户端所在主机上的保存路径，通常是指向一个 .so 文件），这个路径需要用英文单引号或英文双引号括起来； + - typename(Z)：此函数计算结果的数据类型，与上文中 udfNormalFunc 的 itype 参数不同，这里不是使用数字表示法，而是直接写类型名称即可； + - B：中间计算结果的缓冲区大小，单位是字节，最小 0，最大 512，如果不使用可以不设置。 + + 关于中间计算结果的使用，可以参考示例程序[demo.c](https://github.com/taosdata/TDengine/blob/develop/tests/script/sh/demo.c) + + 例如，如下语句可以把 demo.so 创建为系统中可用的 UDF： + + ```sql + CREATE AGGREGATE FUNCTION demo AS "/home/taos/udf_example/demo.so" OUTPUTTYPE DOUBLE bufsize 14; + ``` + +### 管理 UDF + +- 删除指定名称的用户定义函数： +``` +DROP FUNCTION ids(X); +``` + +- ids(X)：此参数的含义与 CREATE 指令中的 ids(X) 参数一致，也即要删除的函数的名字，例如 +```sql +DROP FUNCTION add_one; +``` +- 显示系统中当前可用的所有 UDF： +```sql +SHOW FUNCTIONS; +``` + +### 调用 UDF + +在 SQL 指令中，可以直接以在系统中创建 UDF 时赋予的函数名来调用用户定义函数。例如： +```sql +SELECT X(c) FROM table/stable; +``` + +表示对名为 c 的数据列调用名为 X 的用户定义函数。SQL 指令中用户定义函数可以配合 WHERE 等查询特性来使用。 + +## UDF 的一些使用限制 + +在当前版本下，使用 UDF 存在如下这些限制： + +1. 在创建和调用 UDF 时，服务端和客户端都只支持 Linux 操作系统； +2. UDF 不能与系统内建的 SQL 函数混合使用，暂不支持在一条 SQL 语句中使用多个不同名的 UDF ； +3. UDF 只支持以单个数据列作为输入； +4. UDF 只要创建成功，就会被持久化存储到 MNode 节点中； +5. 无法通过 RESTful 接口来创建 UDF； +6. UDF 在 SQL 中定义的函数名，必须与 .so 库文件实现中的接口函数名前缀保持一致，也即必须是 udfNormalFunc 的名称，而且不可与 TDengine 中已有的内建 SQL 函数重名。 + +## 示例代码 + +### 标量函数示例 [add_one](https://github.com/taosdata/TDengine/blob/develop/tests/script/sh/add_one.c) + +
+add_one.c + +```c +{{#include tests/script/sh/add_one.c}} +``` + +
+ +### 向量函数示例 [abs_max](https://github.com/taosdata/TDengine/blob/develop/tests/script/sh/abs_max.c) + +
+abs_max.c + +```c +{{#include tests/script/sh/abs_max.c}} +``` + +
+ +### 使用中间计算结果示例 [demo](https://github.com/taosdata/TDengine/blob/develop/tests/script/sh/demo.c) + +
+demo.c + +```c +{{#include tests/script/sh/demo.c}} +``` + +
diff --git a/docs-cn/07-develop/_category_.yml b/docs-cn/07-develop/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..509a9405c42939a4819b87669a4c5b244bd29a8b --- /dev/null +++ b/docs-cn/07-develop/_category_.yml @@ -0,0 +1 @@ +label: 开发指南 \ No newline at end of file diff --git a/docs-cn/07-develop/_sub_c.mdx b/docs-cn/07-develop/_sub_c.mdx new file mode 100644 index 0000000000000000000000000000000000000000..95fef0042d0a277f9136e6e6f8c15558487232f9 --- /dev/null +++ b/docs-cn/07-develop/_sub_c.mdx @@ -0,0 +1,3 @@ +```c +{{#include docs-examples/c/subscribe_demo.c}} +``` \ No newline at end of file diff --git a/docs-cn/07-develop/_sub_cs.mdx b/docs-cn/07-develop/_sub_cs.mdx new file mode 100644 index 0000000000000000000000000000000000000000..80934aa4d014a076896dce7f41e520f06ffd735d --- /dev/null +++ b/docs-cn/07-develop/_sub_cs.mdx @@ -0,0 +1,3 @@ +```csharp +{{#include docs-examples/csharp/SubscribeDemo.cs}} +``` \ No newline at end of file diff --git a/docs-cn/07-develop/_sub_go.mdx b/docs-cn/07-develop/_sub_go.mdx new file mode 100644 index 0000000000000000000000000000000000000000..cd908fc12c3a35f49ca108ee56c3951c5388a95f --- /dev/null +++ b/docs-cn/07-develop/_sub_go.mdx @@ -0,0 +1,3 @@ +```go +{{#include docs-examples/go/sub/main.go}} +``` \ No newline at end of file diff --git a/docs-cn/07-develop/_sub_java.mdx b/docs-cn/07-develop/_sub_java.mdx new file mode 100644 index 0000000000000000000000000000000000000000..1ee0cb1a21e35f6760f8680e2ba6dedee92201cd --- /dev/null +++ b/docs-cn/07-develop/_sub_java.mdx @@ -0,0 +1,7 @@ +```java +{{#include docs-examples/java/src/main/java/com/taos/example/SubscribeDemo.java}} +``` +:::note +目前 Java 接口没有提供异步订阅模式，但用户程序可以通过创建 `TimerTask` 等方式达到同样的效果。 + +::: \ No newline at end of file diff --git a/docs-cn/07-develop/_sub_node.mdx b/docs-cn/07-develop/_sub_node.mdx new file mode 100644 index 0000000000000000000000000000000000000000..c93ad627ce9a77ca71a014b41d571089e6c1727b --- /dev/null +++ b/docs-cn/07-develop/_sub_node.mdx @@ -0,0 +1,3 @@ +```js +{{#include docs-examples/node/nativeexample/subscribe_demo.js}} +``` \ No newline at end of file diff --git a/docs-cn/07-develop/_sub_python.mdx b/docs-cn/07-develop/_sub_python.mdx new file mode 100644 index 0000000000000000000000000000000000000000..b817deeba6e283a3ba16fee0d580d3823c999536 --- /dev/null +++ b/docs-cn/07-develop/_sub_python.mdx @@ -0,0 +1,3 @@ +```py +{{#include docs-examples/python/subscribe_demo.py}} +``` \ No newline at end of file diff --git a/docs-cn/07-develop/_sub_rust.mdx b/docs-cn/07-develop/_sub_rust.mdx new file mode 100644 index 0000000000000000000000000000000000000000..4750cf7a3b871db48c9e5a26b22ab4b8a03f11be --- /dev/null +++ b/docs-cn/07-develop/_sub_rust.mdx @@ -0,0 +1,3 @@ +```rs +{{#include docs-examples/rust/nativeexample/examples/subscribe_demo.rs}} +``` \ No newline at end of file diff --git a/docs-cn/07-develop/index.md b/docs-cn/07-develop/index.md new file mode 100644 index 0000000000000000000000000000000000000000..0393a87ab2ae7a5b08eea75d7a0bea95614b8131 --- /dev/null +++ b/docs-cn/07-develop/index.md @@ -0,0 +1,24 @@ +--- +title: 开发指南 +--- + +开发一个应用，如果你准备采用TDengine作为时序数据处理的工具，那么有如下几个事情要做： +1. 确定应用到TDengine的链接方式。无论你使用何种编程语言，你总可以使用REST接口, 但也可以使用每种编程语言独有的连接器方便的进行链接。 +2. 根据自己的应用场景，确定数据模型。根据数据特征，决定建立一个还是多个库；分清静态标签、采集量，建立正确的超级表，建立子表。 +3. 决定插入数据的方式。TDengine支持使用标准的SQL写入，但同时也支持schemaless模式写入，这样不用手工建表，可以将数据直接写入。 +4. 根据业务要求，看需要撰写哪些SQL查询语句。 +5. 如果你要基于时序数据做实时的统计分析，包括各种监测看板，那么建议你采用TDengine的连续查询功能，而不用上线Spark, Flink等复杂的流式计算系统。 +6. 如果你的应用有模块需要消费插入的数据，希望有新的数据插入时，就能获取通知，那么建议你采用TDengine提供的数据订阅功能，而无需专门部署Kafka或其他消息队列软件。 +7. 在很多场景下(如车辆管理)，应用需要获取每个数据采集点的最新状态，那么建议你采用TDengine的cache功能，而不用单独部署Redis等缓存软件。 +8. 如果你发现TDengine的函数无法满足你的要求，那么你可以使用用户自定义函数来解决问题。 + +本部分内容就是按照上述的顺序组织的。为便于理解，TDengine为每个功能为每个支持的编程语言都提供了示例代码。如果你希望深入了解SQL的使用，需要查看[SQL手册](/taos-sql/)。如果想更深入地了解各连接器的使用，请阅读[连接器参考指南](/reference/connector/)。如果还希望想将TDengine与第三方系统集成起来，比如Grafana, 请参考[第三方工具](/third-party/)。 + +如果在开发过程中遇到任何问题，请点击每个页面下方的["反馈问题"](https://github.com/taosdata/TDengine/issues/new/choose), 在GitHub上直接递交issue。 + +```mdx-code-block +import DocCardList from '@theme/DocCardList'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + + +``` diff --git a/docs-cn/10-cluster/01-deploy.md b/docs-cn/10-cluster/01-deploy.md new file mode 100644 index 0000000000000000000000000000000000000000..cee140c0ec13bc9c8052a599a2147acc1aa15a8d --- /dev/null +++ b/docs-cn/10-cluster/01-deploy.md @@ -0,0 +1,138 @@ +--- +title: 集群部署 +--- + +## 准备工作 + +### 第零步 + +规划集群所有物理节点的 FQDN，将规划好的 FQDN 分别添加到每个物理节点的 /etc/hosts；修改每个物理节点的 /etc/hosts，将所有集群物理节点的 IP 与 FQDN 的对应添加好。【如部署了 DNS，请联系网络管理员在 DNS 上做好相关配置】 + +### 第一步 + +如果搭建集群的物理节点中，存有之前的测试数据、装过 1.X 的版本，或者装过其他版本的 TDengine，请先将其删除，并清空所有数据（如果需要保留原有数据，请联系涛思交付团队进行旧版本升级、数据迁移），具体步骤请参考博客[《TDengine 多种安装包的安装和卸载》](https://www.taosdata.com/blog/2019/08/09/566.html)。 + +:::note +因为 FQDN 的信息会写进文件，如果之前没有配置或者更改 FQDN，且启动了 TDengine。请一定在确保数据无用或者备份的前提下，清理一下之前的数据（rm -rf /var/lib/taos/\*）； +::: + +:::note +客户端所在服务器也需要配置，确保它可以正确解析每个节点的 FQDN 配置，不管是通过 DNS 服务，还是修改 hosts 文件。 +::: + +### 第二步 + +建议关闭所有物理节点的防火墙，至少保证端口：6030 - 6042 的 TCP 和 UDP 端口都是开放的。强烈建议先关闭防火墙，集群搭建完毕之后，再来配置端口； + +### 第三步 + +在所有物理节点安装 TDengine，且版本必须是一致的，但不要启动 taosd。安装时，提示输入是否要加入一个已经存在的 TDengine 集群时，第一个物理节点直接回车创建新集群，后续物理节点则输入该集群任何一个在线的物理节点的 FQDN:端口号（默认 6030）； + +### 第四步 + +检查所有数据节点，以及应用程序所在物理节点的网络设置： + +每个物理节点上执行命令 `hostname -f`，查看和确认所有节点的 hostname 是不相同的（应用驱动所在节点无需做此项检查）； + +每个物理节点上执行 ping host，其中 host 是其他物理节点的 hostname，看能否 ping 通其它物理节点；如果不能 ping 通，需要检查网络设置，或 /etc/hosts 文件（Windows 系统默认路径为 C:\Windows\system32\drivers\etc\hosts），或 DNS 的配置。如果无法 ping 通，是无法组成集群的； + +从应用运行的物理节点，ping taosd 运行的数据节点，如果无法 ping 通，应用是无法连接 taosd 的，请检查应用所在物理节点的 DNS 设置或 hosts 文件； + +每个数据节点的 End Point 就是输出的 hostname 外加端口号，比如 h1.taosdata.com:6030。 + +### 第五步 + +修改 TDengine 的配置文件（所有节点的文件 /etc/taos/taos.cfg 都需要修改）。假设准备启动的第一个数据节点 End Point 为 h1.taosdata.com:6030，其与集群配置相关参数如下： + +```c +// firstEp 是每个数据节点首次启动后连接的第一个数据节点 +firstEp h1.taosdata.com:6030 + +// 必须配置为本数据节点的 FQDN，如果本机只有一个 hostname，可注释掉本项 +fqdn h1.taosdata.com + +// 配置本数据节点的端口号，缺省是 6030 +serverPort 6030 + +// 副本数为偶数的时候，需要配置，请参考《Arbitrator 的使用》的部分 +arbitrator ha.taosdata.com:6042 +``` + +一定要修改的参数是 firstEp 和 fqdn。在每个数据节点，firstEp 需全部配置成一样，但 fqdn 一定要配置成其所在数据节点的值。其他参数可不做任何修改，除非你很清楚为什么要修改。 + +加入到集群中的数据节点 dnode，涉及集群相关的下表 9 项参数必须完全相同，否则不能成功加入到集群中。 + +| **#** | **配置参数名称** | **含义** | +| ----- | ------------------ | ------------------------------------------- | +| 1 | numOfMnodes | 系统中管理节点个数 | +| 2 | mnodeEqualVnodeNum | 一个 mnode 等同于 vnode 消耗的个数 | +| 3 | offlineThreshold | dnode 离线阈值，超过该时间将导致 Dnode 离线 | +| 4 | statusInterval | dnode 向 mnode 报告状态时长 | +| 5 | arbitrator | 系统中裁决器的 End Point | +| 6 | timezone | 时区 | +| 7 | balance | 是否启动负载均衡 | +| 8 | maxTablesPerVnode | 每个 vnode 中能够创建的最大表个数 | +| 9 | maxVgroupsPerDb | 每个 DB 中能够使用的最大 vgroup 个数 | + +:::note +在 2.0.19.0 及更早的版本中，除以上 9 项参数外，dnode 加入集群时，还会要求 locale 和 charset 参数的取值也一致。 + +::: + +## 启动集群 + +### 启动第一个数据节点 + +按照《立即开始》里的步骤，启动第一个数据节点，例如 h1.taosdata.com，然后执行 taos，启动 taos shell，从 shell 里执行命令“SHOW DNODES”，如下所示： + +``` +Welcome to the TDengine shell from Linux, Client Version:2.0.0.0 + + +Copyright (c) 2017 by TAOS Data, Inc. All rights reserved. + +taos> show dnodes; + id | end_point | vnodes | cores | status | role | create_time | +===================================================================================== + 1 | h1.taos.com:6030 | 0 | 2 | ready | any | 2020-07-31 03:49:29.202 | +Query OK, 1 row(s) in set (0.006385s) + +taos> +``` + +上述命令里，可以看到刚启动的数据节点的 End Point 是：h1.taos.com:6030，就是这个新集群的 firstEp。 + +### 启动后续数据节点 + +将后续的数据节点添加到现有集群，具体有以下几步： + +按照《立即开始》一章的方法在每个物理节点启动 taosd；（注意：每个物理节点都需要在 taos.cfg 文件中将 firstEp 参数配置为新集群首个节点的 End Point——在本例中是 h1.taos.com:6030） + +在第一个数据节点，使用 CLI 程序 taos，登录进 TDengine 系统，执行命令： + +```sql +CREATE DNODE "h2.taos.com:6030"; +``` + +将新数据节点的 End Point（准备工作中第四步获知的）添加进集群的 EP 列表。“fqdn:port”需要用双引号引起来，否则出错。请注意将示例的“h2.taos.com:6030” 替换为这个新数据节点的 End Point。 + +然后执行命令 + +```sql +SHOW DNODES; +``` + +查看新节点是否被成功加入。如果该被加入的数据节点处于离线状态，请做两个检查： + +查看该数据节点的 taosd 是否正常工作，如果没有正常运行，需要先检查为什么? +查看该数据节点 taosd 日志文件 taosdlog.0 里前面几行日志（一般在 /var/log/taos 目录），看日志里输出的该数据节点 fqdn 以及端口号是否为刚添加的 End Point。如果不一致，需要将正确的 End Point 添加进去。 +按照上述步骤可以源源不断的将新的数据节点加入到集群。 + +:::tip + +任何已经加入集群在线的数据节点，都可以作为后续待加入节点的 firstEp。 +firstEp 这个参数仅仅在该数据节点首次加入集群时有作用，加入集群后，该数据节点会保存最新的 mnode 的 End Point 列表，不再依赖这个参数。 +接下来，配置文件中的 firstEp 参数就主要在客户端连接的时候使用了，例如 taos shell 如果不加参数，会默认连接由 firstEp 指定的节点。 +两个没有配置 firstEp 参数的数据节点 dnode 启动后，会独立运行起来。这个时候，无法将其中一个数据节点加入到另外一个数据节点，形成集群。无法将两个独立的集群合并成为新的集群。 + +::: diff --git a/docs-cn/10-cluster/02-cluster-mgmt.md b/docs-cn/10-cluster/02-cluster-mgmt.md new file mode 100644 index 0000000000000000000000000000000000000000..6ab8ec091b898e8f441d75ef898dc0ff06fce6be --- /dev/null +++ b/docs-cn/10-cluster/02-cluster-mgmt.md @@ -0,0 +1,216 @@ +--- +title: 数据节点管理 +--- + +上面已经介绍如何从零开始搭建集群。集群组建完成后，可以随时查看集群中当前的数据节点的状态，还可以添加新的数据节点进行扩容，删除数据节点，甚至手动进行数据节点之间的负载均衡操作。 + +:::note + +以下所有执行命令的操作需要先登陆进 TDengine 系统，必要时请使用 root 权限。 + +::: + +## 查看数据节点 + +启动 TDengine CLI 程序 taos，然后执行： + +```sql +SHOW DNODES; +``` + +它将列出集群中所有的 dnode，每个 dnode 的 ID，end_point（fqdn:port），状态（ready，offline 等），vnode 数目，还未使用的 vnode 数目等信息。在添加或删除一个数据节点后，可以使用该命令查看。 + +输出如下（具体内容仅供参考，取决于实际的集群配置） + +``` +taos> show dnodes; + id | end_point | vnodes | cores | status | role | create_time | offline reason | +====================================================================================================================================== + 1 | localhost:6030 | 9 | 8 | ready | any | 2022-04-15 08:27:09.359 | | +Query OK, 1 row(s) in set (0.008298s) +``` + +## 查看虚拟节点组 + +为充分利用多核技术，并提供 scalability，数据需要分片处理。因此 TDengine 会将一个 DB 的数据切分成多份，存放在多个 vnode 里。这些 vnode 可能分布在多个数据节点 dnode 里，这样就实现了水平扩展。一个 vnode 仅仅属于一个 DB，但一个 DB 可以有多个 vnode。vnode 所在的数据节点是 mnode 根据当前系统资源的情况，自动进行分配的，无需任何人工干预。 + +启动 CLI 程序 taos，然后执行： + +```sql +USE SOME_DATABASE; +SHOW VGROUPS; +``` + +输出如下（具体内容仅供参考，取决于实际的集群配置） + +``` +taos> show dnodes; + id | end_point | vnodes | cores | status | role | create_time | offline reason | +====================================================================================================================================== + 1 | localhost:6030 | 9 | 8 | ready | any | 2022-04-15 08:27:09.359 | | +Query OK, 1 row(s) in set (0.008298s) + +taos> use db; +Database changed. + +taos> show vgroups; + vgId | tables | status | onlines | v1_dnode | v1_status | compacting | +========================================================================================== + 14 | 38000 | ready | 1 | 1 | master | 0 | + 15 | 38000 | ready | 1 | 1 | master | 0 | + 16 | 38000 | ready | 1 | 1 | master | 0 | + 17 | 38000 | ready | 1 | 1 | master | 0 | + 18 | 37001 | ready | 1 | 1 | master | 0 | + 19 | 37000 | ready | 1 | 1 | master | 0 | + 20 | 37000 | ready | 1 | 1 | master | 0 | + 21 | 37000 | ready | 1 | 1 | master | 0 | +Query OK, 8 row(s) in set (0.001154s) +``` + +## 添加数据节点 + +启动 CLI 程序 taos，然后执行： + +```sql +CREATE DNODE "fqdn:port"; +``` + +将新数据节点的 End Point 添加进集群的 EP 列表。“fqdn:port“需要用双引号引起来，否则出错。一个数据节点对外服务的 fqdn 和 port 可以通过配置文件 taos.cfg 进行配置，缺省是自动获取。【强烈不建议用自动获取方式来配置 FQDN，可能导致生成的数据节点的 End Point 不是所期望的】 + +示例如下： +``` +taos> create dnode "localhost:7030"; +Query OK, 0 of 0 row(s) in database (0.008203s) + +taos> show dnodes; + id | end_point | vnodes | cores | status | role | create_time | offline reason | +====================================================================================================================================== + 1 | localhost:6030 | 9 | 8 | ready | any | 2022-04-15 08:27:09.359 | | + 2 | localhost:7030 | 0 | 0 | offline | any | 2022-04-19 08:11:42.158 | status not received | +Query OK, 2 row(s) in set (0.001017s) +``` + +在上面的示例中可以看到新创建的 dnode 的状态为 offline，待该 dnode 被启动并连接上配置文件中指定的 firstEp后再次查看，得到如下结果（示例） + +``` +taos> show dnodes; + id | end_point | vnodes | cores | status | role | create_time | offline reason | +====================================================================================================================================== + 1 | localhost:6030 | 3 | 8 | ready | any | 2022-04-15 08:27:09.359 | | + 2 | localhost:7030 | 6 | 8 | ready | any | 2022-04-19 08:14:59.165 | | +Query OK, 2 row(s) in set (0.001316s) +``` +从中可以看到两个 dnode 状态都为 ready + + +## 删除数据节点 + +启动 CLI 程序 taos，然后执行： + +```sql +DROP DNODE "fqdn:port"; +``` +或者 +```sql +DROP DNODE dnodeId; +``` + +通过 “fqdn:port” 或 dnodeID 来指定一个具体的节点都是可以的。其中 fqdn 是被删除的节点的 FQDN，port 是其对外服务器的端口号；dnodeID 可以通过 SHOW DNODES 获得。 + +示例如下： +``` +taos> show dnodes; + id | end_point | vnodes | cores | status | role | create_time | offline reason | +====================================================================================================================================== + 1 | localhost:6030 | 9 | 8 | ready | any | 2022-04-15 08:27:09.359 | | + 2 | localhost:7030 | 0 | 0 | offline | any | 2022-04-19 08:11:42.158 | status not received | +Query OK, 2 row(s) in set (0.001017s) + +taos> drop dnode 2; +Query OK, 0 of 0 row(s) in database (0.000518s) + +taos> show dnodes; + id | end_point | vnodes | cores | status | role | create_time | offline reason | +====================================================================================================================================== + 1 | localhost:6030 | 9 | 8 | ready | any | 2022-04-15 08:27:09.359 | | +Query OK, 1 row(s) in set (0.001137s) +``` + +上面的示例中，初次执行 `show dnodes` 列出了两个 dnode, 执行 `drop dnode 2` 删除其中 ID 为 2 的 dnode 之后再次执行 `show dnodes`，可以看到只剩下 ID 为 1 的 dnode 。 + +:::warning + +数据节点一旦被 drop 之后，不能重新加入集群。需要将此节点重新部署（清空数据文件夹）。集群在完成 `drop dnode` 操作之前，会将该 dnode 的数据迁移走。 +请注意 `drop dnode` 和 停止 taosd 进程是两个不同的概念，不要混淆：因为删除 dnode 之前要执行迁移数据的操作，因此被删除的 dnode 必须保持在线状态。待删除操作结束之后，才能停止 taosd 进程。 +一个数据节点被 drop 之后，其他节点都会感知到这个 dnodeID 的删除操作，任何集群中的节点都不会再接收此 dnodeID 的请求。 +dnodeID 是集群自动分配的，不得人工指定。它在生成时是递增的，不会重复。 + +::: + +## 手动迁移数据节点 + +手动将某个 vnode 迁移到指定的 dnode。 + +启动 CLI 程序 taos，然后执行： + +```sql +ALTER DNODE BALANCE "VNODE:-DNODE:"; +``` + +其中：source-dnodeId 是源 dnodeId，也就是待迁移的 vnode 所在的 dnodeID；vgId 可以通过 SHOW VGROUPS 获得，列表的第一列；dest-dnodeId 是目标 dnodeId。 + +首先执行 `show vgroups` 查看 vgroup 的分布情况 +``` +taos> show vgroups; + vgId | tables | status | onlines | v1_dnode | v1_status | compacting | +========================================================================================== + 14 | 38000 | ready | 1 | 3 | master | 0 | + 15 | 38000 | ready | 1 | 3 | master | 0 | + 16 | 38000 | ready | 1 | 3 | master | 0 | + 17 | 38000 | ready | 1 | 3 | master | 0 | + 18 | 37001 | ready | 1 | 3 | master | 0 | + 19 | 37000 | ready | 1 | 1 | master | 0 | + 20 | 37000 | ready | 1 | 1 | master | 0 | + 21 | 37000 | ready | 1 | 1 | master | 0 | +Query OK, 8 row(s) in set (0.001314s) +``` + +从中可以看到在 dnode 3 中有5个 vgroup，而 dnode 1 有 3 个 vgroup，假定我们想将其中 vgId 为18 的 vgroup 从 dnode 3 迁移到 dnode 1 + +``` +taos> alter dnode 3 balance "vnode:18-dnode:1"; + +DB error: Balance already enabled (0.00755 +``` + +上面的结果表明目前所在数据库已经启动了 balance 选项，所以无法进行手动迁移。 + +停止整个集群，将两个 dnode 的配置文件中的 balance 都设置为 0 （默认为1）之后，重新启动集群，再次执行 ` alter dnode` 和 `show vgroups` 命令如下 +``` +taos> alter dnode 3 balance "vnode:18-dnode:1"; +Query OK, 0 row(s) in set (0.000575s) + +taos> show vgroups; + vgId | tables | status | onlines | v1_dnode | v1_status | v2_dnode | v2_status | compacting | +================================================================================================================= + 14 | 38000 | ready | 1 | 3 | master | 0 | NULL | 0 | + 15 | 38000 | ready | 1 | 3 | master | 0 | NULL | 0 | + 16 | 38000 | ready | 1 | 3 | master | 0 | NULL | 0 | + 17 | 38000 | ready | 1 | 3 | master | 0 | NULL | 0 | + 18 | 37001 | ready | 2 | 1 | slave | 3 | master | 0 | + 19 | 37000 | ready | 1 | 1 | master | 0 | NULL | 0 | + 20 | 37000 | ready | 1 | 1 | master | 0 | NULL | 0 | + 21 | 37000 | ready | 1 | 1 | master | 0 | NULL | 0 | +Query OK, 8 row(s) in set (0.001242s) +``` + +从上面的输出可以看到 vgId 为 18 的 vnode 被从 dnode 3 迁移到了 dnode 1。 + +:::warning + +只有在集群的自动负载均衡选项关闭时（balance 设置为 0），才允许手动迁移。 +只有处于正常工作状态的 vnode 才能被迁移：master/slave；当处于 offline/unsynced/syncing 状态时，是不能迁移的。 +迁移前，务必核实目标 dnode 的资源足够：CPU、内存、硬盘。 + +::: + diff --git a/docs-cn/10-cluster/03-ha-and-lb.md b/docs-cn/10-cluster/03-ha-and-lb.md new file mode 100644 index 0000000000000000000000000000000000000000..3d15feb11c47fe821fa4689de2665a65ea17cbe9 --- /dev/null +++ b/docs-cn/10-cluster/03-ha-and-lb.md @@ -0,0 +1,87 @@ +--- +title: 高可用与负载均衡 +--- + +## Vnode 的高可用性 + +TDengine 通过多副本的机制来提供系统的高可用性，包括 vnode 和 mnode 的高可用性。 + +vnode 的副本数是与 DB 关联的，一个集群里可以有多个 DB，根据运营的需求，每个 DB 可以配置不同的副本数。创建数据库时，通过参数 replica 指定副本数（缺省为 1）。如果副本数为 1，系统的可靠性无法保证，只要数据所在的节点宕机，就将无法提供服务。集群的节点数必须大于等于副本数，否则创建表时将返回错误“more dnodes are needed”。比如下面的命令将创建副本数为 3 的数据库 demo： + +```sql +CREATE DATABASE demo replica 3; +``` + +一个 DB 里的数据会被切片分到多个 vnode group，vnode group 里的 vnode 数目就是 DB 的副本数，同一个 vnode group 里各 vnode 的数据是完全一致的。为保证高可用性，vnode group 里的 vnode 一定要分布在不同的数据节点 dnode 里（实际部署时，需要在不同的物理机上），只要一个 vnode group 里超过半数的 vnode 处于工作状态，这个 vnode group 就能正常的对外服务。 + +一个数据节点 dnode 里可能有多个 DB 的数据，因此一个 dnode 离线时，可能会影响到多个 DB。如果一个 vnode group 里的一半或一半以上的 vnode 不工作，那么该 vnode group 就无法对外服务，无法插入或读取数据，这样会影响到它所属的 DB 的一部分表的读写操作。 + +因为 vnode 的引入，无法简单地给出结论：“集群中过半数据节点 dnode 工作，集群就应该工作”。但是对于简单的情形，很好下结论。比如副本数为 3，只有三个 dnode，那如果仅有一个节点不工作，整个集群还是可以正常工作的，但如果有两个数据节点不工作，那整个集群就无法正常工作了。 + +## Mnode 的高可用性 + +TDengine 集群是由 mnode（taosd 的一个模块，管理节点）负责管理的，为保证 mnode 的高可用，可以配置多个 mnode 副本，副本数由系统配置参数 numOfMnodes 决定，有效范围为 1-3。为保证元数据的强一致性，mnode 副本之间是通过同步的方式进行数据复制的。 + +一个集群有多个数据节点 dnode，但一个 dnode 至多运行一个 mnode 实例。多个 dnode 情况下，哪个 dnode 可以作为 mnode 呢？这是完全由系统根据整个系统资源情况，自动指定的。用户可通过 CLI 程序 taos，在 TDengine 的 console 里，执行如下命令： + +```sql +SHOW MNODES; +``` + +来查看 mnode 列表，该列表将列出 mnode 所处的 dnode 的 End Point 和角色（master，slave，unsynced 或 offline）。当集群中第一个数据节点启动时，该数据节点一定会运行一个 mnode 实例，否则该数据节点 dnode 无法正常工作，因为一个系统是必须有至少一个 mnode 的。如果 numOfMnodes 配置为 2，启动第二个 dnode 时，该 dnode 也将运行一个 mnode 实例。 + +为保证 mnode 服务的高可用性，numOfMnodes 必须设置为 2 或更大。因为 mnode 保存的元数据必须是强一致的，如果 numOfMnodes 大于 2，复制参数 quorum 自动设为 2，也就是说，至少要保证有两个副本写入数据成功，才通知客户端应用写入成功。 + +:::note +一个 TDengine 高可用系统，无论是 vnode 还是 mnode，都必须配置多个副本。 + +::: + +## 负载均衡 + +有三种情况，将触发负载均衡，而且都无需人工干预。 + +当一个新数据节点添加进集群时，系统将自动触发负载均衡，一些节点上的数据将被自动转移到新数据节点上，无需任何人工干预。 +当一个数据节点从集群中移除时，系统将自动把该数据节点上的数据转移到其他数据节点，无需任何人工干预。 +如果一个数据节点过热（数据量过大），系统将自动进行负载均衡，将该数据节点的一些 vnode 自动挪到其他节点。 +当上述三种情况发生时，系统将启动各个数据节点的负载计算，从而决定如何挪动。 + +:::tip +负载均衡由参数 balance 控制，它决定是否启动自动负载均衡，0 表示禁用，1 表示启用自动负载均衡。 + +::: + +## 数据节点离线处理 + +如果一个数据节点离线，TDengine 集群将自动检测到。有如下两种情况： + +该数据节点离线超过一定时间（taos.cfg 里配置参数 offlineThreshold 控制时长），系统将自动把该数据节点删除，产生系统报警信息，触发负载均衡流程。如果该被删除的数据节点重新上线时，它将无法加入集群，需要系统管理员重新将其添加进集群才会开始工作。 + +离线后，在 offlineThreshold 的时长内重新上线，系统将自动启动数据恢复流程，等数据完全恢复后，该节点将开始正常工作。 + +:::note +如果一个虚拟节点组（包括 mnode 组）里所归属的每个数据节点都处于离线或 unsynced 状态，必须等该虚拟节点组里的所有数据节点都上线、都能交换状态信息后，才能选出 Master，该虚拟节点组才能对外提供服务。比如整个集群有 3 个数据节点，副本数为 3，如果 3 个数据节点都宕机，然后 2 个数据节点重启，是无法工作的，只有等 3 个数据节点都重启成功，才能对外服务。 + +::: + +## Arbitrator 的使用 + +如果副本数为偶数，当一个 vnode group 里一半或超过一半的 vnode 不工作时，是无法从中选出 master 的。同理，一半或超过一半的 mnode 不工作时，是无法选出 mnode 的 master 的，因为存在“split brain”问题。 + +为解决这个问题，TDengine 引入了 Arbitrator 的概念。Arbitrator 模拟一个 vnode 或 mnode 在工作，但只简单的负责网络连接，不处理任何数据插入或访问。只要包含 Arbitrator 在内，超过半数的 vnode 或 mnode 工作，那么该 vnode group 或 mnode 组就可以正常的提供数据插入或查询服务。比如对于副本数为 2 的情形，如果一个节点 A 离线，但另外一个节点 B 正常，而且能连接到 Arbitrator，那么节点 B 就能正常工作。 + +总之，在目前版本下，TDengine 建议在双副本环境要配置 Arbitrator，以提升系统的可用性。 + +Arbitrator 的执行程序名为 tarbitrator。该程序对系统资源几乎没有要求，只需要保证有网络连接，找任何一台 Linux 服务器运行它即可。以下简要描述安装配置的步骤： + +请点击 安装包下载，在 TDengine Arbitrator Linux 一节中，选择合适的版本下载并安装。 +该应用的命令行参数 -p 可以指定其对外服务的端口号，缺省是 6042。 + +修改每个 taosd 实例的配置文件，在 taos.cfg 里将参数 arbitrator 设置为 tarbitrator 程序所对应的 End Point。（如果该参数配置了，当副本数为偶数时，系统将自动连接配置的 Arbitrator。如果副本数为奇数，即使配置了 Arbitrator，系统也不会去建立连接。） + +在配置文件中配置了的 Arbitrator，会出现在 SHOW DNODES 指令的返回结果中，对应的 role 列的值会是“arb”。 +查看集群 Arbitrator 的状态【2.0.14.0 以后支持】 + +```sql +SHOW DNODES; +``` diff --git a/docs-cn/10-cluster/_category_.yml b/docs-cn/10-cluster/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..3cee5ce4cdc29e7febf456e567ba08cf2753d305 --- /dev/null +++ b/docs-cn/10-cluster/_category_.yml @@ -0,0 +1 @@ +label: 集群管理 diff --git a/docs-cn/10-cluster/index.md b/docs-cn/10-cluster/index.md new file mode 100644 index 0000000000000000000000000000000000000000..ef2a7253c977cbdbd101ba6af5d7e1584aaf34bd --- /dev/null +++ b/docs-cn/10-cluster/index.md @@ -0,0 +1,14 @@ +--- +title: 集群管理 +--- + +TDengine 支持集群，提供水平扩展的能力。如果需要获得更高的处理能力，只需要多增加节点即可。TDengine 采用虚拟节点技术，将一个节点虚拟化为多个虚拟节点，以实现负载均衡。同时，TDengine可以将多个节点上的虚拟节点组成虚拟节点组，通过多副本机制，以保证供系统的高可用。TDengine的集群功能完全开源。 + +本章节主要介绍集群的部署、维护，以及如何实现高可用和负载均衡。 + +```mdx-code-block +import DocCardList from '@theme/DocCardList'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + + +``` diff --git a/docs-cn/12-taos-sql/01-data-type.md b/docs-cn/12-taos-sql/01-data-type.md new file mode 100644 index 0000000000000000000000000000000000000000..be5c9a8cb4ed7f4ed9f9c7e11faf1b0f8f6e51b8 --- /dev/null +++ b/docs-cn/12-taos-sql/01-data-type.md @@ -0,0 +1,50 @@ +--- +sidebar_label: 支持的数据类型 +title: 支持的数据类型 +description: "TDengine 支持的数据类型: 时间戳、浮点型、JSON 类型等" +--- + +使用 TDengine，最重要的是时间戳。创建并插入记录、查询历史记录的时候，均需要指定时间戳。时间戳有如下规则： + +- 时间格式为 `YYYY-MM-DD HH:mm:ss.MS`，默认时间分辨率为毫秒。比如：`2017-08-12 18:25:58.128` +- 内部函数 now 是客户端的当前时间 +- 插入记录时，如果时间戳为 now，插入数据时使用提交这条记录的客户端的当前时间 +- Epoch Time：时间戳也可以是一个长整数，表示从格林威治时间 1970-01-01 00:00:00.000 (UTC/GMT) 开始的毫秒数（相应地，如果所在 Database 的时间精度设置为“微秒”，则长整型格式的时间戳含义也就对应于从格林威治时间 1970-01-01 00:00:00.000 (UTC/GMT) 开始的微秒数；纳秒精度逻辑类似。） +- 时间可以加减，比如 now-2h，表明查询时刻向前推 2 个小时（最近 2 小时）。数字后面的时间单位可以是 b(纳秒)、u(微秒)、a(毫秒)、s(秒)、m(分)、h(小时)、d(天)、w(周)。 比如 `select * from t1 where ts > now-2w and ts <= now-1w`，表示查询两周前整整一周的数据。在指定降采样操作（down sampling）的时间窗口（interval）时，时间单位还可以使用 n (自然月) 和 y (自然年)。 + +TDengine 缺省的时间戳精度是毫秒，但通过在 `CREATE DATABASE` 时传递的 PRECISION 参数也可以支持微秒和纳秒。（从 2.1.5.0 版本开始支持纳秒精度） + +```sql +CREATE DATABASE db_name PRECISION 'ns'; +``` + +在 TDengine 中，普通表的数据模型中可使用以下 10 种数据类型。 + +| # | **类型** | **Bytes** | **说明** | +| --- | :-------: | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | TIMESTAMP | 8 | 时间戳。缺省精度毫秒，可支持微秒和纳秒。从格林威治时间 1970-01-01 00:00:00.000 (UTC/GMT) 开始，计时不能早于该时间。（从 2.0.18.0 版本开始，已经去除了这一时间范围限制）（从 2.1.5.0 版本开始支持纳秒精度） | +| 2 | INT | 4 | 整型，范围 [-2^31+1, 2^31-1], -2^31 用作 NULL | +| 3 | BIGINT | 8 | 长整型，范围 [-2^63+1, 2^63-1], -2^63 用作 NULL | +| 4 | FLOAT | 4 | 浮点型，有效位数 6-7，范围 [-3.4E38, 3.4E38] | +| 5 | DOUBLE | 8 | 双精度浮点型，有效位数 15-16，范围 [-1.7E308, 1.7E308] | +| 6 | BINARY | 自定义 | 记录单字节字符串，建议只用于处理 ASCII 可见字符，中文等多字节字符需使用 nchar。理论上，最长可以有 16374 字节。binary 仅支持字符串输入，字符串两端需使用单引号引用。使用时须指定大小，如 binary(20) 定义了最长为 20 个单字节字符的字符串，每个字符占 1 byte 的存储空间，总共固定占用 20 bytes 的空间，此时如果用户字符串超出 20 字节将会报错。对于字符串内的单引号，可以用转义字符反斜线加单引号来表示，即 `\’`。 | +| 7 | SMALLINT | 2 | 短整型， 范围 [-32767, 32767], -32768 用作 NULL | +| 8 | TINYINT | 1 | 单字节整型，范围 [-127, 127], -128 用作 NULL | +| 9 | BOOL | 1 | 布尔型，{true, false} | +| 10 | NCHAR | 自定义 | 记录包含多字节字符在内的字符串，如中文字符。每个 nchar 字符占用 4 bytes 的存储空间。字符串两端使用单引号引用，字符串内的单引号需用转义字符 `\’`。nchar 使用时须指定字符串大小，类型为 nchar(10) 的列表示此列的字符串最多存储 10 个 nchar 字符，会固定占用 40 bytes 的空间。如果用户字符串长度超出声明长度，将会报错。 | +| 11 | JSON | | json 数据类型， 只有 tag 可以是 json 格式 | + +:::tip +TDengine 对 SQL 语句中的英文字符不区分大小写，自动转化为小写执行。因此用户大小写敏感的字符串及密码，需要使用单引号将字符串引起来。 + +::: + +:::note +虽然 BINARY 类型在底层存储上支持字节型的二进制字符，但不同编程语言对二进制数据的处理方式并不保证一致，因此建议在 BINARY 类型中只存储 ASCII 可见字符，而避免存储不可见字符。多字节的数据，例如中文字符，则需要使用 NCHAR 类型进行保存。如果强行使用 BINARY 类型保存中文字符，虽然有时也能正常读写，但并不带有字符集信息，很容易出现数据乱码甚至数据损坏等情况。 + +::: + +:::note +SQL 语句中的数值类型将依据是否存在小数点，或使用科学计数法表示，来判断数值类型是否为整型或者浮点型，因此在使用时要注意相应类型越界的情况。例如，9999999999999999999 会认为超过长整型的上边界而溢出，而 9999999999999999999.0 会被认为是有效的浮点数。 + +::: diff --git a/docs-cn/12-taos-sql/02-database.md b/docs-cn/12-taos-sql/02-database.md new file mode 100644 index 0000000000000000000000000000000000000000..1454d1d34415ea5af9b019ae6eea36923e6d05be --- /dev/null +++ b/docs-cn/12-taos-sql/02-database.md @@ -0,0 +1,128 @@ +--- +sidebar_label: 数据库管理 +title: 数据库管理 +description: "创建、删除数据库，查看、修改数据库参数" +--- + +## 创建数据库 + +``` +CREATE DATABASE [IF NOT EXISTS] db_name [KEEP keep] [DAYS days] [UPDATE 1]; +``` + +:::info +1. KEEP 是该数据库的数据保留多长天数，缺省是 3650 天(10 年)，数据库会自动删除超过时限的数据； +2. UPDATE 标志数据库支持更新相同时间戳数据；（从 2.1.7.0 版本开始此参数支持设为 2，表示允许部分列更新，也即更新数据行时未被设置的列会保留原值。）（从 2.0.8.0 版本开始支持此参数。注意此参数不能通过 `ALTER DATABASE` 指令进行修改。） + 1. UPDATE 设为 0 时，表示不允许更新数据，后发送的相同时间戳的数据会被直接丢弃； + 2. UPDATE 设为 1 时，表示更新全部列数据，即如果更新一个数据行，其中某些列没有提供取值，那么这些列会被设为 NULL； + 3. UPDATE 设为 2 时，表示支持更新部分列数据，即如果更新一个数据行，其中某些列没有提供取值，那么这些列会保持原有数据行中的对应值； + 4. 更多关于 UPDATE 参数的用法，请参考[FAQ](/train-faq/faq)。 +3. 数据库名最大长度为 33； +4. 一条 SQL 语句的最大长度为 65480 个字符； +5. 创建数据库时可用的参数有： + - cache: [Description](/reference/config/#cache) + - blocks: [Description](/reference/config/#blocks) + - days: [Description](/reference/config/#days) + - keep: [Description](/reference/config/#keep) + - minRows: [Description](/reference/config/#minrows) + - maxRows: [Description](/reference/config/#maxrows) + - wal: [Description](/reference/config/#wallevel) + - fsync: [Description](/reference/config/#fsync) + - update: [Description](/reference/config/#update) + - cacheLast: [Description](/reference/config/#cachelast) + - replica: [Description](/reference/config/#replica) + - quorum: [Description](/reference/config/#quorum) + - maxVgroupsPerDb: [Description](/reference/config/#maxvgroupsperdb) + - comp: [Description](/reference/config/#comp) + - precision: [Description](/reference/config/#precision) +6. 请注意上面列出的所有参数都可以配置在配置文件 `taosd.cfg` 中作为创建数据库时使用的默认配置， `create database` 的参数中明确指定的会覆盖配置文件中的设置。 + +::: + +### 创建数据库示例 + +创建时间精度为纳秒的数据库, 保留 1 年数据： + +```sql +CREATE DATABASE test PRECISION 'ns' KEEP 365; +``` + +## 显示系统当前参数 + +``` +SHOW VARIABLES; +``` + +## 使用数据库 + +``` +USE db_name; +``` + +使用/切换数据库（在 REST 连接方式下无效）。 + +## 删除数据库 + +``` +DROP DATABASE [IF EXISTS] db_name; +``` + +删除数据库。指定 Database 所包含的全部数据表将被删除，谨慎使用！ + +## 修改数据库参数 + +``` +ALTER DATABASE db_name COMP 2; +``` + +COMP 参数是指修改数据库文件压缩标志位，缺省值为 2，取值范围为 [0, 2]。0 表示不压缩，1 表示一阶段压缩，2 表示两阶段压缩。 + +``` +ALTER DATABASE db_name REPLICA 2; +``` + +REPLICA 参数是指修改数据库副本数，取值范围 [1, 3]。在集群中使用，副本数必须小于或等于 DNODE 的数目。 + +``` +ALTER DATABASE db_name KEEP 365; +``` + +KEEP 参数是指修改数据文件保存的天数，缺省值为 3650，取值范围 [days, 365000]，必须大于或等于 days 参数值。 + +``` +ALTER DATABASE db_name QUORUM 2; +``` + +QUORUM 参数是指数据写入成功所需要的确认数，取值范围 [1, 2]。对于异步复制，quorum 设为 1，具有 master 角色的虚拟节点自己确认即可。对于同步复制，quorum 设为 2。原则上，Quorum >= 1 并且 Quorum <= replica(副本数)，这个参数在启动一个同步模块实例时需要提供。 + +``` +ALTER DATABASE db_name BLOCKS 100; +``` + +BLOCKS 参数是每个 VNODE (TSDB) 中有多少 cache 大小的内存块，因此一个 VNODE 的用的内存大小粗略为（cache \* blocks）。取值范围 [3, 1000]。 + +``` +ALTER DATABASE db_name CACHELAST 0; +``` + +CACHELAST 参数控制是否在内存中缓存子表的最近数据。缺省值为 0，取值范围 [0, 1, 2, 3]。其中 0 表示不缓存，1 表示缓存子表最近一行数据，2 表示缓存子表每一列的最近的非 NULL 值，3 表示同时打开缓存最近行和列功能。（从 2.0.11.0 版本开始支持参数值 [0, 1]，从 2.1.2.0 版本开始支持参数值 [0, 1, 2, 3]。） +说明：缓存最近行，将显著改善 LAST_ROW 函数的性能表现；缓存每列的最近非 NULL 值，将显著改善无特殊影响（WHERE、ORDER BY、GROUP BY、INTERVAL）下的 LAST 函数的性能表现。 + +:::tip +以上所有参数修改后都可以用 show databases 来确认是否修改成功。另外，从 2.1.3.0 版本开始，修改这些参数后无需重启服务器即可生效。 +::: + +## 显示系统所有数据库 + +``` +SHOW DATABASES; +``` + +## 显示一个数据库的创建语句 + +``` +SHOW CREATE DATABASE db_name; +``` + +常用于数据库迁移。对一个已经存在的数据库，返回其创建语句；在另一个集群中执行该语句，就能得到一个设置完全相同的 Database。 + diff --git a/docs-cn/12-taos-sql/03-table.md b/docs-cn/12-taos-sql/03-table.md new file mode 100644 index 0000000000000000000000000000000000000000..675c157b3def0d670f771f55b767f3ca4f2a28af --- /dev/null +++ b/docs-cn/12-taos-sql/03-table.md @@ -0,0 +1,123 @@ +--- +title: 表管理 +--- + +## 创建数据表 + +``` +CREATE TABLE [IF NOT EXISTS] tb_name (timestamp_field_name TIMESTAMP, field1_name data_type1 [, field2_name data_type2 ...]); +``` + +:::info 说明 + +1. 表的第一个字段必须是 TIMESTAMP，并且系统自动将其设为主键； +2. 表名最大长度为 192； +3. 表的每行长度不能超过 16k 个字符;（注意：每个 BINARY/NCHAR 类型的列还会额外占用 2 个字节的存储位置） +4. 子表名只能由字母、数字和下划线组成，且不能以数字开头，不区分大小写 +5. 使用数据类型 binary 或 nchar，需指定其最长的字节数，如 binary(20)，表示 20 字节； +6. 为了兼容支持更多形式的表名，TDengine 引入新的转义符 "\`"，可以让表名与关键词不冲突，同时不受限于上述表名称合法性约束检查。但是同样具有长度限制要求。使用转义字符以后，不再对转义字符中的内容进行大小写统一。 + 例如：\`aBc\` 和 \`abc\` 是不同的表名，但是 abc 和 aBc 是相同的表名。 + 需要注意的是转义字符中的内容必须是可打印字符。 + 上述的操作逻辑和约束要求与 MySQL 数据的操作一致。 + 从 2.3.0.0 版本开始支持这种方式。 + +::: + +### 以超级表为模板创建数据表 + +``` +CREATE TABLE [IF NOT EXISTS] tb_name USING stb_name TAGS (tag_value1, ...); +``` + +以指定的超级表为模板，指定 TAGS 的值来创建数据表。 + +### 以超级表为模板创建数据表，并指定具体的 TAGS 列 + +``` +CREATE TABLE [IF NOT EXISTS] tb_name USING stb_name (tag_name1, ...) TAGS (tag_value1, ...); +``` + +以指定的超级表为模板，指定一部分 TAGS 列的值来创建数据表（没被指定的 TAGS 列会设为空值）。 +说明：从 2.0.17.0 版本开始支持这种方式。在之前的版本中，不允许指定 TAGS 列，而必须显式给出所有 TAGS 列的取值。 + +### 批量创建数据表 + +``` +CREATE TABLE [IF NOT EXISTS] tb_name1 USING stb_name TAGS (tag_value1, ...) [IF NOT EXISTS] tb_name2 USING stb_name TAGS (tag_value2, ...) ...; +``` + +以更快的速度批量创建大量数据表（服务器端 2.0.14 及以上版本）。 + +:::info + +1.批量建表方式要求数据表必须以超级表为模板。 2.在不超出 SQL 语句长度限制的前提下，单条语句中的建表数量建议控制在 1000 ～ 3000 之间，将会获得比较理想的建表速度。 + +::: + +## 删除数据表 + +``` +DROP TABLE [IF EXISTS] tb_name; +``` + +## 显示当前数据库下的所有数据表信息 + +``` +SHOW TABLES [LIKE tb_name_wildchar]; +``` + +显示当前数据库下的所有数据表信息。 + +## 显示一个数据表的创建语句 + +``` +SHOW CREATE TABLE tb_name; +``` + +常用于数据库迁移。对一个已经存在的数据表，返回其创建语句；在另一个集群中执行该语句，就能得到一个结构完全相同的数据表。 + +## 获取表的结构信息 + +``` +DESCRIBE tb_name; +``` + +## 修改表定义 + +### 表增加列 + +``` +ALTER TABLE tb_name ADD COLUMN field_name data_type; +``` + +:::info + +1. 列的最大个数为 1024，最小个数为 2；（从 2.1.7.0 版本开始，改为最多允许 4096 列） +2. 列名最大长度为 64。 + +::: + +### 表删除列 + +``` +ALTER TABLE tb_name DROP COLUMN field_name; +``` + +如果表是通过超级表创建，更改表结构的操作只能对超级表进行。同时针对超级表的结构更改对所有通过该结构创建的表生效。对于不是通过超级表创建的表，可以直接修改表结构。 + +### 表修改列宽 + +``` +ALTER TABLE tb_name MODIFY COLUMN field_name data_type(length); +``` + +如果数据列的类型是可变长格式（BINARY 或 NCHAR），那么可以使用此指令修改其宽度（只能改大，不能改小）。（2.1.3.0 版本新增） +如果表是通过超级表创建，更改表结构的操作只能对超级表进行。同时针对超级表的结构更改对所有通过该结构创建的表生效。对于不是通过超级表创建的表，可以直接修改表结构。 + +### 修改子表标签值 + +``` +ALTER TABLE tb_name SET TAG tag_name=new_tag_value; +``` + +如果表是通过超级表创建，可以使用此指令修改其标签值 diff --git a/docs-cn/12-taos-sql/04-stable.md b/docs-cn/12-taos-sql/04-stable.md new file mode 100644 index 0000000000000000000000000000000000000000..a3c227317c85917b64b2477994d335710610ec70 --- /dev/null +++ b/docs-cn/12-taos-sql/04-stable.md @@ -0,0 +1,125 @@ +--- +sidebar_label: 超级表管理 +title: 超级表 STable 管理 +--- + +:::note + +在 2.0.15.0 及以后的版本中开始支持 STABLE 保留字。也即，在本节后文的指令说明中，CREATE、DROP、ALTER 三个指令在 2.0.15.0 之前的版本中 STABLE 保留字需写作 TABLE。 + +::: + +## 创建超级表 + +``` +CREATE STABLE [IF NOT EXISTS] stb_name (timestamp_field_name TIMESTAMP, field1_name data_type1 [, field2_name data_type2 ...]) TAGS (tag1_name tag_type1, tag2_name tag_type2 [, tag3_name tag_type3]); +``` + +创建 STable，与创建表的 SQL 语法相似，但需要指定 TAGS 字段的名称和类型。 + +:::info + +1. TAGS 列的数据类型不能是 timestamp 类型；（从 2.1.3.0 版本开始，TAGS 列中支持使用 timestamp 类型，但需注意在 TAGS 中的 timestamp 列写入数据时需要提供给定值，而暂不支持四则运算，例如 `NOW + 10s` 这类表达式） +2. TAGS 列名不能与其他列名相同； +3. TAGS 列名不能为预留关键字（参见：[参数限制与保留关键字](/taos-sql/keywords/) 章节）； +4. TAGS 最多允许 128 个，至少 1 个，总长度不超过 16 KB。 + +::: + +## 删除超级表 + +``` +DROP STABLE [IF EXISTS] stb_name; +``` + +删除 STable 会自动删除通过 STable 创建的子表。 + +## 显示当前数据库下的所有超级表信息 + +``` +SHOW STABLES [LIKE tb_name_wildcard]; +``` + +查看数据库内全部 STable，及其相关信息，包括 STable 的名称、创建时间、列数量、标签（TAG）数量、通过该 STable 建表的数量。 + +## 显示一个超级表的创建语句 + +``` +SHOW CREATE STABLE stb_name; +``` + +常用于数据库迁移。对一个已经存在的超级表，返回其创建语句；在另一个集群中执行该语句，就能得到一个结构完全相同的超级表。 + +## 获取超级表的结构信息 + +``` +DESCRIBE stb_name; +``` + +## 修改超级表普通列 + +### 超级表增加列 + +``` +ALTER STABLE stb_name ADD COLUMN field_name data_type; +``` + +### 超级表删除列 + +``` +ALTER STABLE stb_name DROP COLUMN field_name; +``` + +### 超级表修改列宽 + +``` +ALTER STABLE stb_name MODIFY COLUMN field_name data_type(length); +``` + +如果数据列的类型是可变长格式（BINARY 或 NCHAR），那么可以使用此指令修改其宽度（只能改大，不能改小）。（2.1.3.0 版本新增） + +## 修改超级表标签列 + +### 添加标签 + +``` +ALTER STABLE stb_name ADD TAG new_tag_name tag_type; +``` + +为 STable 增加一个新的标签，并指定新标签的类型。标签总数不能超过 128 个，总长度不超过 16k 个字符。 + +### 删除标签 + +``` +ALTER STABLE stb_name DROP TAG tag_name; +``` + +删除超级表的一个标签，从超级表删除某个标签后，该超级表下的所有子表也会自动删除该标签。 + +### 修改标签名 + +``` +ALTER STABLE stb_name CHANGE TAG old_tag_name new_tag_name; +``` + +修改超级表的标签名，从超级表修改某个标签名后，该超级表下的所有子表也会自动更新该标签名。 + +### 修改标签列宽度 + +``` +ALTER STABLE stb_name MODIFY TAG tag_name data_type(length); +``` + +如果标签的类型是可变长格式（BINARY 或 NCHAR），那么可以使用此指令修改其宽度（只能改大，不能改小）。（2.1.3.0 版本新增） + +### 超级表查询 +使用 SELECT 语句可以完成在超级表上的投影及聚合两类查询，在 WHERE 语句中可以对标签及列进行筛选及过滤。 + +如果在超级表查询语句中不加 ORDER BY, 返回顺序是先返回一个子表的所有数据，然后再返回下个子表的所有数据，所以返回的数据是无序的。如果增加了 ORDER BY 语句，会严格按 ORDER BY 语句指定的顺序返回的。 + + + +:::note +除了更新标签的值的操作是针对子表进行，其他所有的标签操作（添加标签、删除标签等）均只能作用于 STable，不能对单个子表操作。对 STable 添加标签以后，依托于该 STable 建立的所有表将自动增加了一个标签，所有新增标签的默认值都是 NULL。 + +::: diff --git a/docs-cn/12-taos-sql/05-insert.md b/docs-cn/12-taos-sql/05-insert.md new file mode 100644 index 0000000000000000000000000000000000000000..e542e442b78c9033ae37196f4913a7c67fb19d8b --- /dev/null +++ b/docs-cn/12-taos-sql/05-insert.md @@ -0,0 +1,149 @@ +--- +sidebar_label: 数据写入 +title: 数据写入 +--- + +## 写入语法 + +``` +INSERT INTO + tb_name + [USING stb_name [(tag1_name, ...)] TAGS (tag1_value, ...)] + [(field1_name, ...)] + VALUES (field1_value, ...) [(field1_value2, ...) ...] | FILE csv_file_path + [tb2_name + [USING stb_name [(tag1_name, ...)] TAGS (tag1_value, ...)] + [(field1_name, ...)] + VALUES (field1_value, ...) [(field1_value2, ...) ...] | FILE csv_file_path + ...]; +``` + +## 插入一条或多条记录 + +指定已经创建好的数据子表的表名，并通过 VALUES 关键字提供一行或多行数据，即可向数据库写入这些数据。例如，执行如下语句可以写入一行记录： + +``` +INSERT INTO d1001 VALUES (NOW, 10.2, 219, 0.32); +``` + +或者，可以通过如下语句写入两行记录： + +``` +INSERT INTO d1001 VALUES ('2021-07-13 14:06:32.272', 10.2, 219, 0.32) (1626164208000, 10.15, 217, 0.33); +``` + +:::note + +1. 在第二个例子中，两行记录的首列时间戳使用了不同格式的写法。其中字符串格式的时间戳写法不受所在 DATABASE 的时间精度设置影响；而长整形格式的时间戳写法会受到所在 DATABASE 的时间精度设置影响——例子中的时间戳在毫秒精度下可以写作 1626164208000，而如果是在微秒精度设置下就需要写为 1626164208000000，纳秒精度设置下需要写为 1626164208000000000。 +2. 在使用“插入多条记录”方式写入数据时，不能把第一列的时间戳取值都设为 NOW，否则会导致语句中的多条记录使用相同的时间戳，于是就可能出现相互覆盖以致这些数据行无法全部被正确保存。其原因在于，NOW 函数在执行中会被解析为所在 SQL 语句的实际执行时间，出现在同一语句中的多个 NOW 标记也就会被替换为完全相同的时间戳取值。 +3. 允许插入的最老记录的时间戳，是相对于当前服务器时间，减去配置的 keep 值（数据保留的天数）；允许插入的最新记录的时间戳，是相对于当前服务器时间，加上配置的 days 值（数据文件存储数据的时间跨度，单位为天）。keep 和 days 都是可以在创建数据库时指定的，缺省值分别是 3650 天和 10 天。 + +::: + +## 插入记录，数据对应到指定的列 + +向数据子表中插入记录时，无论插入一行还是多行，都可以让数据对应到指定的列。对于 SQL 语句中没有出现的列，数据库将自动填充为 NULL。主键（时间戳）不能为 NULL。例如： + +``` +INSERT INTO d1001 (ts, current, phase) VALUES ('2021-07-13 14:06:33.196', 10.27, 0.31); +``` + +:::info +如果不指定列，也即使用全列模式——那么在 VALUES 部分提供的数据，必须为数据表的每个列都显式地提供数据。全列模式写入速度会远快于指定列，因此建议尽可能采用全列写入方式，此时空列可以填入 NULL。 + +::: + +## 向多个表插入记录 + +可以在一条语句中，分别向多个表插入一条或多条记录，并且也可以在插入过程中指定列。例如： + +``` +INSERT INTO d1001 VALUES ('2021-07-13 14:06:34.630', 10.2, 219, 0.32) ('2021-07-13 14:06:35.779', 10.15, 217, 0.33) + d1002 (ts, current, phase) VALUES ('2021-07-13 14:06:34.255', 10.27, 0.31）; +``` + +## 插入记录时自动建表 + +如果用户在写数据时并不确定某个表是否存在，此时可以在写入数据时使用自动建表语法来创建不存在的表，若该表已存在则不会建立新表。自动建表时，要求必须以超级表为模板，并写明数据表的 TAGS 取值。例如： + +``` +INSERT INTO d21001 USING meters TAGS ('Beijing.Chaoyang', 2) VALUES ('2021-07-13 14:06:32.272', 10.2, 219, 0.32); +``` + +也可以在自动建表时，只是指定部分 TAGS 列的取值，未被指定的 TAGS 列将置为 NULL。例如： + +``` +INSERT INTO d21001 USING meters (groupId) TAGS (2) VALUES ('2021-07-13 14:06:33.196', 10.15, 217, 0.33); +``` + +自动建表语法也支持在一条语句中向多个表插入记录。例如： + +``` +INSERT INTO d21001 USING meters TAGS ('Beijing.Chaoyang', 2) VALUES ('2021-07-13 14:06:34.630', 10.2, 219, 0.32) ('2021-07-13 14:06:35.779', 10.15, 217, 0.33) + d21002 USING meters (groupId) TAGS (2) VALUES ('2021-07-13 14:06:34.255', 10.15, 217, 0.33) + d21003 USING meters (groupId) TAGS (2) (ts, current, phase) VALUES ('2021-07-13 14:06:34.255', 10.27, 0.31); +``` + +:::info +在 2.0.20.5 版本之前，在使用自动建表语法并指定列时，子表的列名必须紧跟在子表名称后面，而不能如例子里那样放在 TAGS 和 VALUES 之间。从 2.0.20.5 版本开始，两种写法都可以，但不能在一条 SQL 语句中混用，否则会报语法错误。 +::: + +## 插入来自文件的数据记录 + +除了使用 VALUES 关键字插入一行或多行数据外，也可以把要写入的数据放在 CSV 文件中（英文逗号分隔、英文单引号括住每个值）供 SQL 指令读取。其中 CSV 文件无需表头。例如，如果 /tmp/csvfile.csv 文件的内容为： + +``` +'2021-07-13 14:07:34.630', '10.2', '219', '0.32' +'2021-07-13 14:07:35.779', '10.15', '217', '0.33' +``` + +那么通过如下指令可以把这个文件中的数据写入子表中： + +``` +INSERT INTO d1001 FILE '/tmp/csvfile.csv'; +``` + +## 插入来自文件的数据记录，并自动建表 + +从 2.1.5.0 版本开始，支持在插入来自 CSV 文件的数据时，以超级表为模板来自动创建不存在的数据表。例如： + +``` +INSERT INTO d21001 USING meters TAGS ('Beijing.Chaoyang', 2) FILE '/tmp/csvfile.csv'; +``` + +也可以在一条语句中向多个表以自动建表的方式插入记录。例如： + +``` +INSERT INTO d21001 USING meters TAGS ('Beijing.Chaoyang', 2) FILE '/tmp/csvfile_21001.csv' + d21002 USING meters (groupId) TAGS (2) FILE '/tmp/csvfile_21002.csv'; +``` + +## 历史记录写入 + +可使用 IMPORT 或者 INSERT 命令，IMPORT 的语法，功能与 INSERT 完全一样。 + +针对 insert 类型的 SQL 语句，我们采用的流式解析策略，在发现后面的错误之前，前面正确的部分 SQL 仍会执行。下面的 SQL 中，INSERT 语句是无效的，但是 d1001 仍会被创建。 + +``` +taos> CREATE TABLE meters(ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS(location BINARY(30), groupId INT); +Query OK, 0 row(s) affected (0.008245s) + +taos> SHOW STABLES; + name | created_time | columns | tags | tables | +============================================================================================ + meters | 2020-08-06 17:50:27.831 | 4 | 2 | 0 | +Query OK, 1 row(s) in set (0.001029s) + +taos> SHOW TABLES; +Query OK, 0 row(s) in set (0.000946s) + +taos> INSERT INTO d1001 USING meters TAGS('Beijing.Chaoyang', 2) VALUES('a'); + +DB error: invalid SQL: 'a' (invalid timestamp) (0.039494s) + +taos> SHOW TABLES; + table_name | created_time | columns | stable_name | +====================================================================================================== + d1001 | 2020-08-06 17:52:02.097 | 4 | meters | +Query OK, 1 row(s) in set (0.001091s) +``` diff --git a/docs-cn/12-taos-sql/06-select.md b/docs-cn/12-taos-sql/06-select.md new file mode 100644 index 0000000000000000000000000000000000000000..3a860119cfe664f9ac3b0ebd046b5f4f0a612118 --- /dev/null +++ b/docs-cn/12-taos-sql/06-select.md @@ -0,0 +1,462 @@ +--- +sidebar_label: 数据查询 +title: 数据查询 +--- + +## 查询语法 + +``` +SELECT select_expr [, select_expr ...] + FROM {tb_name_list} + [WHERE where_condition] + [SESSION(ts_col, tol_val)] + [STATE_WINDOW(col)] + [INTERVAL(interval_val [, interval_offset]) [SLIDING sliding_val]] + [FILL(fill_mod_and_val)] + [GROUP BY col_list] + [ORDER BY col_list { DESC | ASC }] + [SLIMIT limit_val [SOFFSET offset_val]] + [LIMIT limit_val [OFFSET offset_val]] + [>> export_file]; +``` + +## 通配符 + +通配符 \* 可以用于代指全部列。对于普通表，结果中只有普通列。 + +``` +taos> SELECT * FROM d1001; + ts | current | voltage | phase | +====================================================================================== + 2018-10-03 14:38:05.000 | 10.30000 | 219 | 0.31000 | + 2018-10-03 14:38:15.000 | 12.60000 | 218 | 0.33000 | + 2018-10-03 14:38:16.800 | 12.30000 | 221 | 0.31000 | +Query OK, 3 row(s) in set (0.001165s) +``` + +在针对超级表，通配符包含 _标签列_ 。 + +``` +taos> SELECT * FROM meters; + ts | current | voltage | phase | location | groupid | +===================================================================================================================================== + 2018-10-03 14:38:05.500 | 11.80000 | 221 | 0.28000 | Beijing.Haidian | 2 | + 2018-10-03 14:38:16.600 | 13.40000 | 223 | 0.29000 | Beijing.Haidian | 2 | + 2018-10-03 14:38:05.000 | 10.80000 | 223 | 0.29000 | Beijing.Haidian | 3 | + 2018-10-03 14:38:06.500 | 11.50000 | 221 | 0.35000 | Beijing.Haidian | 3 | + 2018-10-03 14:38:04.000 | 10.20000 | 220 | 0.23000 | Beijing.Chaoyang | 3 | + 2018-10-03 14:38:16.650 | 10.30000 | 218 | 0.25000 | Beijing.Chaoyang | 3 | + 2018-10-03 14:38:05.000 | 10.30000 | 219 | 0.31000 | Beijing.Chaoyang | 2 | + 2018-10-03 14:38:15.000 | 12.60000 | 218 | 0.33000 | Beijing.Chaoyang | 2 | + 2018-10-03 14:38:16.800 | 12.30000 | 221 | 0.31000 | Beijing.Chaoyang | 2 | +Query OK, 9 row(s) in set (0.002022s) +``` + +通配符支持表名前缀，以下两个 SQL 语句均为返回全部的列： + +``` +SELECT * FROM d1001; +SELECT d1001.* FROM d1001; +``` + +在 JOIN 查询中，带前缀的\*和不带前缀\*返回的结果有差别， \*返回全部表的所有列数据（不包含标签），带前缀的通配符，则只返回该表的列数据。 + +``` +taos> SELECT * FROM d1001, d1003 WHERE d1001.ts=d1003.ts; + ts | current | voltage | phase | ts | current | voltage | phase | +================================================================================================================================== + 2018-10-03 14:38:05.000 | 10.30000| 219 | 0.31000 | 2018-10-03 14:38:05.000 | 10.80000| 223 | 0.29000 | +Query OK, 1 row(s) in set (0.017385s) +``` + +``` +taos> SELECT d1001.* FROM d1001,d1003 WHERE d1001.ts = d1003.ts; + ts | current | voltage | phase | +====================================================================================== + 2018-10-03 14:38:05.000 | 10.30000 | 219 | 0.31000 | +Query OK, 1 row(s) in set (0.020443s) +``` + +在使用 SQL 函数来进行查询的过程中，部分 SQL 函数支持通配符操作。其中的区别在于： +`count(*)`函数只返回一列。`first`、`last`、`last_row`函数则是返回全部列。 + +``` +taos> SELECT COUNT(*) FROM d1001; + count(*) | +======================== + 3 | +Query OK, 1 row(s) in set (0.001035s) +``` + +``` +taos> SELECT FIRST(*) FROM d1001; + first(ts) | first(current) | first(voltage) | first(phase) | +========================================================================================= + 2018-10-03 14:38:05.000 | 10.30000 | 219 | 0.31000 | +Query OK, 1 row(s) in set (0.000849s) +``` + +## 标签列 + +从 2.0.14 版本开始，支持在普通表的查询中指定 _标签列_，且标签列的值会与普通列的数据一起返回。 + +``` +taos> SELECT location, groupid, current FROM d1001 LIMIT 2; + location | groupid | current | +====================================================================== + Beijing.Chaoyang | 2 | 10.30000 | + Beijing.Chaoyang | 2 | 12.60000 | +Query OK, 2 row(s) in set (0.003112s) +``` + +注意：普通表的通配符 \* 中并不包含 _标签列_。 + +## 获取标签列或普通列的去重取值 + +从 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; +``` + +从 2.1.7.0 版本开始，DISTINCT 也支持对数据子表或普通表进行处理，也即支持获取单个普通列的不重复取值，或多个普通列取值的不重复组合。 + +```sql +SELECT DISTINCT col_name [, col_name ...] FROM tb_name; +``` + +:::info + +1. cfg 文件中的配置参数 maxNumOfDistinctRes 将对 DISTINCT 能够输出的数据行数进行限制。其最小值是 100000，最大值是 100000000，默认值是 10000000。如果实际计算结果超出了这个限制，那么会仅输出这个数量范围内的部分。 +2. 由于浮点数天然的精度机制原因，在特定情况下，对 FLOAT 和 DOUBLE 列使用 DISTINCT 并不能保证输出值的完全唯一性。 +3. 在当前版本下，DISTINCT 不能在嵌套查询的子查询中使用，也不能与聚合函数、GROUP BY、或 JOIN 在同一条语句中混用。 + +::: + +## 结果集列名 + +`SELECT`子句中，如果不指定返回结果集合的列名，结果集列名称默认使用`SELECT`子句中的表达式名称作为列名称。此外，用户可使用`AS`来重命名返回结果集合中列的名称。例如： + +``` +taos> SELECT ts, ts AS primary_key_ts FROM d1001; + ts | primary_key_ts | +==================================================== + 2018-10-03 14:38:05.000 | 2018-10-03 14:38:05.000 | + 2018-10-03 14:38:15.000 | 2018-10-03 14:38:15.000 | + 2018-10-03 14:38:16.800 | 2018-10-03 14:38:16.800 | +Query OK, 3 row(s) in set (0.001191s) +``` + +但是针对`first(*)`、`last(*)`、`last_row(*)`不支持针对单列的重命名。 + +## 隐式结果列 + +`Select_exprs`可以是表所属列的列名，也可以是基于列的函数表达式或计算式，数量的上限 256 个。当用户使用了`interval`或`group by tags`的子句以后，在最后返回结果中会强制返回时间戳列（第一列）和 group by 子句中的标签列。后续的版本中可以支持关闭 group by 子句中隐式列的输出，列输出完全由 select 子句控制。 + +## 表（超级表）列表 + +FROM 关键字后面可以是若干个表（超级表）列表，也可以是子查询的结果。 +如果没有指定用户的当前数据库，可以在表名称之前使用数据库的名称来指定表所属的数据库。例如：`power.d1001` 方式来跨库使用表。 + +``` +SELECT * FROM power.d1001; +------------------------------ +USE power; +SELECT * FROM d1001; +``` + +## 特殊功能 + +部分特殊的查询功能可以不使用 FROM 子句执行。获取当前所在的数据库 database()： + +``` +taos> SELECT DATABASE(); + database() | +================================= + power | +Query OK, 1 row(s) in set (0.000079s) +``` + +如果登录的时候没有指定默认数据库，且没有使用`USE`命令切换数据，则返回 NULL。 + +``` +taos> SELECT DATABASE(); + database() | +================================= + NULL | +Query OK, 1 row(s) in set (0.000184s) +``` + +获取服务器和客户端版本号： + +``` +taos> SELECT CLIENT_VERSION(); + client_version() | +=================== + 2.0.0.0 | +Query OK, 1 row(s) in set (0.000070s) + +taos> SELECT SERVER_VERSION(); + server_version() | +=================== + 2.0.0.0 | +Query OK, 1 row(s) in set (0.000077s) +``` + +服务器状态检测语句。如果服务器正常，返回一个数字（例如 1）。如果服务器异常，返回 error code。该 SQL 语法能兼容连接池对于 TDengine 状态的检查及第三方工具对于数据库服务器状态的检查。并可以避免出现使用了错误的心跳检测 SQL 语句导致的连接池连接丢失的问题。 + +``` +taos> SELECT SERVER_STATUS(); + server_status() | +================== + 1 | +Query OK, 1 row(s) in set (0.000074s) + +taos> SELECT SERVER_STATUS() AS status; + status | +============== + 1 | +Query OK, 1 row(s) in set (0.000081s) +``` + +## \_block_dist 函数 + +**功能说明**: 用于获得指定的（超级）表的数据块分布信息 + +```txt title="语法" +SELECT _block_dist() FROM { tb_name | stb_name } +``` + +**返回结果类型**：字符串。 + +**适用数据类型**：不能输入任何参数。 + +**嵌套子查询支持**：不支持子查询或嵌套查询。 + +**返回结果**: + +- 返回 FROM 子句中输入的表或超级表的数据块分布情况。不支持查询条件。 +- 返回的结果是该表或超级表的数据块所包含的行数的数据分布直方图。 + +```txt title="返回结果" +summary: +5th=[392], 10th=[392], 20th=[392], 30th=[392], 40th=[792], 50th=[792] 60th=[792], 70th=[792], 80th=[792], 90th=[792], 95th=[792], 99th=[792] Min=[392(Rows)] Max=[800(Rows)] Avg=[666(Rows)] Stddev=[2.17] Rows=[2000], Blocks=[3], Size=[5.440(Kb)] Comp=[0.23] RowsInMem=[0] SeekHeaderTime=[1(us)] +``` + +**上述信息的说明如下**: + +- 查询的（超级）表所包含的存储在文件中的数据块（data block）中所包含的数据行的数量分布直方图信息：5%， 10%， 20%， 30%， 40%， 50%， 60%， 70%， 80%， 90%， 95%， 99% 的数值； +- 所有数据块中，包含行数最少的数据块所包含的行数量， 其中的 Min 指标 392 行。 +- 所有数据块中，包含行数最多的数据块所包含的行数量， 其中的 Max 指标 800 行。 +- 所有数据块行数的算数平均值 666 行（其中的 Avg 项）。 +- 所有数据块中行数分布的均方差为 2.17 ( stddev ）。 +- 数据块包含的行的总数为 2000 行（Rows）。 +- 数据块总数是 3 个数据块 （Blocks）。 +- 数据块占用磁盘空间大小 5.44 Kb （size）。 +- 压缩后的数据块的大小除以原始数据的所获得的压缩比例： 23%（Comp），及压缩后的数据规模是原始数据规模的 23%。 +- 内存中存在的数据行数是 0，表示内存中没有数据缓存。 +- 获取数据块信息的过程中读取头文件的时间开销 1 微秒（SeekHeaderTime）。 + +**支持版本**：指定计算算法的功能从 2.1.0.x 版本开始，2.1.0.0 之前的版本不支持指定使用算法的功能。 + +## TAOS SQL 中特殊关键词 + +- `TBNAME`： 在超级表查询中可视为一个特殊的标签，代表查询涉及的子表名 +- `_c0`: 表示表（超级表）的第一列 + +## 小技巧 + +获取一个超级表所有的子表名及相关的标签信息： + +``` +SELECT TBNAME, location FROM meters; +``` + +统计超级表下辖子表数量： + +``` +SELECT COUNT(TBNAME) FROM meters; +``` + +以上两个查询均只支持在 WHERE 条件子句中添加针对标签（TAGS）的过滤条件。例如： + +``` +taos> SELECT TBNAME, location FROM meters; + tbname | location | +================================================================== + d1004 | Beijing.Haidian | + d1003 | Beijing.Haidian | + d1002 | Beijing.Chaoyang | + d1001 | Beijing.Chaoyang | +Query OK, 4 row(s) in set (0.000881s) + +taos> SELECT COUNT(tbname) FROM meters WHERE groupId > 2; + count(tbname) | +======================== + 2 | +Query OK, 1 row(s) in set (0.001091s) +``` + +- 可以使用 \* 返回所有列，或指定列名。可以对数字列进行四则运算，可以给输出的列取列名。 + - 暂不支持含列名的四则运算表达式用于条件过滤算子（例如，不支持 `where a*2>6;`，但可以写 `where a>6/2;`）。 + - 暂不支持含列名的四则运算表达式作为 SQL 函数的应用对象（例如，不支持 `select min(2*a) from t;`，但可以写 `select 2*min(a) from t;`）。 +- WHERE 语句可以使用各种逻辑判断来过滤数字值，或使用通配符来过滤字符串。 +- 输出结果缺省按首列时间戳升序排序，但可以指定按降序排序( \_c0 指首列时间戳)。使用 ORDER BY 对其他字段进行排序,排序结果顺序不确定。 +- 参数 LIMIT 控制输出条数，OFFSET 指定从第几条开始输出。LIMIT/OFFSET 对结果集的执行顺序在 ORDER BY 之后。且 `LIMIT 5 OFFSET 2` 可以简写为 `LIMIT 2, 5`。 + - 在有 GROUP BY 子句的情况下，LIMIT 参数控制的是每个分组中至多允许输出的条数。 +- 参数 SLIMIT 控制由 GROUP BY 指令划分的分组中，至多允许输出几个分组的数据。且 `SLIMIT 5 SOFFSET 2` 可以简写为 `SLIMIT 2, 5`。 +- 通过 “>>” 输出结果可以导出到指定文件。 + +## 条件过滤操作 + +| **Operation** | **Note** | **Applicable Data Types** | +| ------------- | ------------------------ | ----------------------------------------- | +| > | larger than | all types except bool | +| < | smaller than | all types except bool | +| >= | larger than or equal to | all types except bool | +| <= | smaller than or equal to | all types except bool | +| = | equal to | all types | +| <\> | not equal to | all types | +| is [not] null | is null or is not null | all types | +| between and | within a certain range | all types except bool | +| in | match any value in a set | all types except first column `timestamp` | +| like | match a wildcard string | **`binary`** **`nchar`** | +| match/nmatch | filter regex | **`binary`** **`nchar`** | + +**使用说明**: + +- <\> 算子也可以写为 != ，请注意，这个算子不能用于数据表第一列的 timestamp 字段。 +- like 算子使用通配符字符串进行匹配检查。 + - 在通配符字符串中：'%'（百分号）匹配 0 到任意个字符；'\_'（下划线）匹配单个任意 ASCII 字符。 + - 如果希望匹配字符串中原本就带有的 \_（下划线）字符，那么可以在通配符字符串中写作 `\_`，也即加一个反斜线来进行转义。（从 2.2.0.0 版本开始支持） + - 通配符字符串最长不能超过 20 字节。（从 2.1.6.1 版本开始，通配符字符串的长度放宽到了 100 字节，并可以通过 taos.cfg 中的 maxWildCardsLength 参数来配置这一长度限制。但不建议使用太长的通配符字符串，将有可能严重影响 LIKE 操作的执行性能。） +- 同时进行多个字段的范围过滤，需要使用关键词 AND 来连接不同的查询条件，暂不支持 OR 连接的不同列之间的查询过滤条件。 + - 从 2.3.0.0 版本开始，已支持完整的同一列和/或不同列间的 AND/OR 运算。 +- 针对单一字段的过滤，如果是时间过滤条件，则一条语句中只支持设定一个；但针对其他的（普通）列或标签列，则可以使用 `OR` 关键字进行组合条件的查询过滤。例如： `((value > 20 AND value < 30) OR (value < 12))`。 + - 从 2.3.0.0 版本开始，允许使用多个时间过滤条件，但首列时间戳的过滤运算结果只能包含一个区间。 +- 从 2.0.17.0 版本开始，条件过滤开始支持 BETWEEN AND 语法，例如 `WHERE col2 BETWEEN 1.5 AND 3.25` 表示查询条件为“1.5 ≤ col2 ≤ 3.25”。 +- 从 2.1.4.0 版本开始，条件过滤开始支持 IN 算子，例如 `WHERE city IN ('Beijing', 'Shanghai')`。说明：BOOL 类型写作 `{true, false}` 或 `{0, 1}` 均可，但不能写作 0、1 之外的整数；FLOAT 和 DOUBLE 类型会受到浮点数精度影响，集合内的值在精度范围内认为和数据行的值完全相等才能匹配成功；TIMESTAMP 类型支持非主键的列。 +- 从 2.3.0.0 版本开始，条件过滤开始支持正则表达式，关键字 match/nmatch，不区分大小写。 + +## 正则表达式过滤 + +### 语法 + +```txt +WHERE (column|tbname) **match/MATCH/nmatch/NMATCH** _regex_ +``` + +### 正则表达式规范 + +确保使用的正则表达式符合 POSIX 的规范，具体规范内容可参见[Regular Expressions](https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html) + +### 使用限制 + +只能针对表名（即 tbname 筛选）、binary/nchar 类型标签值进行正则表达式过滤，不支持普通列的过滤。 + +正则匹配字符串长度不能超过 128 字节。可以通过参数 _maxRegexStringLen_ 设置和调整最大允许的正则匹配字符串，该参数是客户端配置参数，需要重启才能生效。 + +## JOIN 子句 + +从 2.2.0.0 版本开始，TDengine 对内连接（INNER JOIN）中的自然连接（Natural join）操作实现了完整的支持。也即支持“普通表与普通表之间”、“超级表与超级表之间”、“子查询与子查询之间”进行自然连接。自然连接与内连接的主要区别是，自然连接要求参与连接的字段在不同的表/超级表中必须是同名字段。也即，TDengine 在连接关系的表达中，要求必须使用同名数据列/标签列的相等关系。 + +在普通表与普通表之间的 JOIN 操作中，只能使用主键时间戳之间的相等关系。例如： + +```sql +SELECT * +FROM temp_tb_1 t1, pressure_tb_1 t2 +WHERE t1.ts = t2.ts +``` + +在超级表与超级表之间的 JOIN 操作中，除了主键时间戳一致的条件外，还要求引入能实现一一对应的标签列的相等关系。例如： + +```sql +SELECT * +FROM temp_stable t1, temp_stable t2 +WHERE t1.ts = t2.ts AND t1.deviceid = t2.deviceid AND t1.status=0; +``` + +类似地，也可以对多个子查询的查询结果进行 JOIN 操作。 + +:::note + +JOIN语句存在如下限制要求： + +- 参与一条语句中 JOIN 操作的表/超级表最多可以有 10 个。 +- 在包含 JOIN 操作的查询语句中不支持 FILL。 +- 暂不支持参与 JOIN 操作的表之间聚合后的四则运算。 +- 不支持只对其中一部分表做 GROUP BY。 +- JOIN 查询的不同表的过滤条件之间不能为 OR。 +- JOIN 查询要求连接条件不能是普通列，只能针对标签和主时间字段列（第一列）。 + +::: + +## 嵌套查询 + +“嵌套查询”又称为“子查询”，也即在一条 SQL 语句中，“内层查询”的计算结果可以作为“外层查询”的计算对象来使用。 + +从 2.2.0.0 版本开始，TDengine 的查询引擎开始支持在 FROM 子句中使用非关联子查询（“非关联”的意思是，子查询不会用到父查询中的参数）。也即在普通 SELECT 语句的 tb_name_list 位置，用一个独立的 SELECT 语句来代替（这一 SELECT 语句被包含在英文圆括号内），于是完整的嵌套查询 SQL 语句形如： + +``` +SELECT ... FROM (SELECT ... FROM ...) ...; +``` + +:::info + +- 目前仅支持一层嵌套，也即不能在子查询中再嵌入子查询。 +- 内层查询的返回结果将作为“虚拟表”供外层查询使用，此虚拟表可以使用 AS 语法做重命名，以便于外层查询中方便引用。 +- 目前不能在“连续查询”功能中使用子查询。 +- 在内层和外层查询中，都支持普通的表间/超级表间 JOIN。内层查询的计算结果也可以再参与数据子表的 JOIN 操作。 +- 目前内层查询、外层查询均不支持 UNION 操作。 +- 内层查询支持的功能特性与非嵌套的查询语句能力是一致的。 + - 内层查询的 ORDER BY 子句一般没有意义，建议避免这样的写法以免无谓的资源消耗。 +- 与非嵌套的查询语句相比，外层查询所能支持的功能特性存在如下限制： + - 计算函数部分： + - 如果内层查询的结果数据未提供时间戳，那么计算过程依赖时间戳的函数在外层会无法正常工作。例如：TOP, BOTTOM, FIRST, LAST, DIFF。 + - 计算过程需要两遍扫描的函数，在外层查询中无法正常工作。例如：此类函数包括：STDDEV, PERCENTILE。 + - 外层查询中不支持 IN 算子，但在内层中可以使用。 + - 外层查询不支持 GROUP BY。 + +::: + +## UNION ALL 子句 + +```txt title=语法 +SELECT ... +UNION ALL SELECT ... +[UNION ALL SELECT ...] +``` + +TDengine 支持 UNION ALL 操作符。也就是说，如果多个 SELECT 子句返回结果集的结构完全相同（列名、列类型、列数、顺序），那么可以通过 UNION ALL 把这些结果集合并到一起。目前只支持 UNION ALL 模式，也即在结果集的合并过程中是不去重的。在同一个 sql 语句中，UNION ALL 最多支持 100 个。 + +### SQL 示例 + +对于下面的例子，表 tb1 用以下语句创建： + +``` +CREATE TABLE tb1 (ts TIMESTAMP, col1 INT, col2 FLOAT, col3 BINARY(50)); +``` + +查询 tb1 刚过去的一个小时的所有记录： + +``` +SELECT * FROM tb1 WHERE ts >= NOW - 1h; +``` + +查询表 tb1 从 2018-06-01 08:00:00.000 到 2018-06-02 08:00:00.000 时间范围，并且 col3 的字符串是'nny'结尾的记录，结果按照时间戳降序： + +``` +SELECT * FROM tb1 WHERE ts > '2018-06-01 08:00:00.000' AND ts <= '2018-06-02 08:00:00.000' AND col3 LIKE '%nny' ORDER BY ts DESC; +``` + +查询 col1 与 col2 的和，并取名 complex, 时间大于 2018-06-01 08:00:00.000, col2 大于 1.2，结果输出仅仅 10 条记录，从第 5 条开始： + +``` +SELECT (col1 + col2) AS 'complex' FROM tb1 WHERE ts > '2018-06-01 08:00:00.000' AND col2 > 1.2 LIMIT 10 OFFSET 5; +``` + +查询过去 10 分钟的记录，col2 的值大于 3.14，并且将结果输出到文件 `/home/testoutput.csv`： + +``` +SELECT COUNT(*) FROM tb1 WHERE ts >= NOW - 10m AND col2 > 3.14 >> /home/testoutput.csv; +``` diff --git a/docs-cn/12-taos-sql/07-function.md b/docs-cn/12-taos-sql/07-function.md new file mode 100644 index 0000000000000000000000000000000000000000..a0c1932cb2fa2a373d0d0662d1c7972a36470540 --- /dev/null +++ b/docs-cn/12-taos-sql/07-function.md @@ -0,0 +1,876 @@ +--- +sidebar_label: SQL 函数 +title: SQL 函数 +--- + +## 聚合函数 + +TDengine 支持针对数据的聚合查询。提供支持的聚合和选择函数如下： + +### COUNT + +``` +SELECT COUNT([*|field_name]) FROM tb_name [WHERE clause]; +``` + +**功能说明**：统计表/超级表中记录行数或某列的非空值个数。 + +**返回数据类型**：长整型 INT64。 + +**应用字段**：应用全部字段。 + +**适用于**：表、超级表。 + +**使用说明**: + +- 可以使用星号(\*)来替代具体的字段，使用星号(\*)返回全部记录数量。 +- 针对同一表的（不包含 NULL 值）字段查询结果均相同。 +- 如果统计对象是具体的列，则返回该列中非 NULL 值的记录数量。 + +**示例**： + +``` +taos> SELECT COUNT(*), COUNT(voltage) FROM meters; + count(*) | count(voltage) | +================================================ + 9 | 9 | +Query OK, 1 row(s) in set (0.004475s) + +taos> SELECT COUNT(*), COUNT(voltage) FROM d1001; + count(*) | count(voltage) | +================================================ + 3 | 3 | +Query OK, 1 row(s) in set (0.001075s) +``` + +### AVG + +``` +SELECT AVG(field_name) FROM tb_name [WHERE clause]; +``` + +**功能说明**：统计表/超级表中某列的平均值。 + +**返回数据类型**：双精度浮点数 Double。 + +**应用字段**：不能应用在 timestamp、binary、nchar、bool 字段。 + +**适用于**：表、超级表。 + +**示例**： + +``` +taos> SELECT AVG(current), AVG(voltage), AVG(phase) FROM meters; + avg(current) | avg(voltage) | avg(phase) | +==================================================================================== + 11.466666751 | 220.444444444 | 0.293333333 | +Query OK, 1 row(s) in set (0.004135s) + +taos> SELECT AVG(current), AVG(voltage), AVG(phase) FROM d1001; + avg(current) | avg(voltage) | avg(phase) | +==================================================================================== + 11.733333588 | 219.333333333 | 0.316666673 | +Query OK, 1 row(s) in set (0.000943s) +``` + +### TWA + +``` +SELECT TWA(field_name) FROM tb_name WHERE clause; +``` + +**功能说明**：时间加权平均函数。统计表中某列在一段时间内的时间加权平均。 + +**返回数据类型**：双精度浮点数 Double。 + +**应用字段**：不能应用在 timestamp、binary、nchar、bool 类型字段。 + +**适用于**：表、超级表。 + +**使用说明**： + +- 从 2.1.3.0 版本开始，TWA 函数可以在由 GROUP BY 划分出单独时间线的情况下用于超级表（也即 GROUP BY tbname）。 + +### IRATE + +``` +SELECT IRATE(field_name) FROM tb_name WHERE clause; +``` + +**功能说明**：计算瞬时增长率。使用时间区间中最后两个样本数据来计算瞬时增长速率；如果这两个值呈递减关系，那么只取最后一个数用于计算，而不是使用二者差值。 + +**返回数据类型**：双精度浮点数 Double。 + +**应用字段**：不能应用在 timestamp、binary、nchar、bool 类型字段。 + +**适用于**：表、超级表。 + +**使用说明**： + +- 从 2.1.3.0 版本开始此函数可用，IRATE 可以在由 GROUP BY 划分出单独时间线的情况下用于超级表（也即 GROUP BY tbname）。 + +### SUM + +``` +SELECT SUM(field_name) FROM tb_name [WHERE clause]; +``` + +**功能说明**：统计表/超级表中某列的和。 + +**返回数据类型**：双精度浮点数 Double 和长整型 INT64。 + +**应用字段**：不能应用在 timestamp、binary、nchar、bool 类型字段。 + +**适用于**：表、超级表。 + +**示例**： + +``` +taos> SELECT SUM(current), SUM(voltage), SUM(phase) FROM meters; + sum(current) | sum(voltage) | sum(phase) | +================================================================================ + 103.200000763 | 1984 | 2.640000001 | +Query OK, 1 row(s) in set (0.001702s) + +taos> SELECT SUM(current), SUM(voltage), SUM(phase) FROM d1001; + sum(current) | sum(voltage) | sum(phase) | +================================================================================ + 35.200000763 | 658 | 0.950000018 | +Query OK, 1 row(s) in set (0.000980s) +``` + +### STDDEV + +``` +SELECT STDDEV(field_name) FROM tb_name [WHERE clause]; +``` + +**功能说明**：统计表中某列的均方差。 + +**返回数据类型**：双精度浮点数 Double。 + +**应用字段**：不能应用在 timestamp、binary、nchar、bool 类型字段。 + +**适用于**：表、超级表（从 2.0.15.1 版本开始） + +**示例**： + +``` +taos> SELECT STDDEV(current) FROM d1001; + stddev(current) | +============================ + 1.020892909 | +Query OK, 1 row(s) in set (0.000915s) +``` + +### LEASTSQUARES + +``` +SELECT LEASTSQUARES(field_name, start_val, step_val) FROM tb_name [WHERE clause]; +``` + +**功能说明**：统计表中某列的值是主键（时间戳）的拟合直线方程。start_val 是自变量初始值，step_val 是自变量的步长值。 + +**返回数据类型**：字符串表达式（斜率, 截距）。 + +**应用字段**：不能应用在 timestamp、binary、nchar、bool 类型字段。 + +**适用于**：表。 + +**示例**： + +``` +taos> SELECT LEASTSQUARES(current, 1, 1) FROM d1001; + leastsquares(current, 1, 1) | +===================================================== +{slop:1.000000, intercept:9.733334} | +Query OK, 1 row(s) in set (0.000921s) +``` + +## 选择函数 + +在使用所有的选择函数的时候，可以同时指定输出 ts 列或标签列（包括 tbname），这样就可以方便地知道被选出的值是源于哪个数据行的。 + +### MIN + +``` +SELECT MIN(field_name) FROM {tb_name | stb_name} [WHERE clause]; +``` + +**功能说明**：统计表/超级表中某列的值最小值。 + +**返回数据类型**：同应用的字段。 + +**应用字段**：不能应用在 timestamp、binary、nchar、bool 类型字段。 + +**适用于**：表、超级表。 + +**示例**： + +``` +taos> SELECT MIN(current), MIN(voltage) FROM meters; + min(current) | min(voltage) | +====================================== + 10.20000 | 218 | +Query OK, 1 row(s) in set (0.001765s) + +taos> SELECT MIN(current), MIN(voltage) FROM d1001; + min(current) | min(voltage) | +====================================== + 10.30000 | 218 | +Query OK, 1 row(s) in set (0.000950s) +``` + +### MAX + +``` +SELECT MAX(field_name) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**功能说明**：统计表/超级表中某列的值最大值。 + +**返回数据类型**：同应用的字段。 + +**应用字段**：不能应用在 timestamp、binary、nchar、bool 类型字段。 + +**适用于**：表、超级表。 + +**示例**： + +``` +taos> SELECT MAX(current), MAX(voltage) FROM meters; + max(current) | max(voltage) | +====================================== + 13.40000 | 223 | +Query OK, 1 row(s) in set (0.001123s) + +taos> SELECT MAX(current), MAX(voltage) FROM d1001; + max(current) | max(voltage) | +====================================== + 12.60000 | 221 | +Query OK, 1 row(s) in set (0.000987s) +``` + +### FIRST + +``` +SELECT FIRST(field_name) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**功能说明**：统计表/超级表中某列的值最先写入的非 NULL 值。 + +**返回数据类型**：同应用的字段。 + +**应用字段**：所有字段。 + +**适用于**：表、超级表。 + +**使用说明**: + +- 如果要返回各个列的首个（时间戳最小）非 NULL 值，可以使用 FIRST(\*)； +- 如果结果集中的某列全部为 NULL 值，则该列的返回结果也是 NULL； +- 如果结果集中所有列全部为 NULL 值，则不返回结果。 + +**示例**： + +``` +taos> SELECT FIRST(*) FROM meters; + first(ts) | first(current) | first(voltage) | first(phase) | +========================================================================================= +2018-10-03 14:38:04.000 | 10.20000 | 220 | 0.23000 | +Query OK, 1 row(s) in set (0.004767s) + +taos> SELECT FIRST(current) FROM d1002; + first(current) | +======================= + 10.20000 | +Query OK, 1 row(s) in set (0.001023s) +``` + +### LAST + +``` +SELECT LAST(field_name) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**功能说明**：统计表/超级表中某列的值最后写入的非 NULL 值。 + +**返回数据类型**：同应用的字段。 + +**应用字段**：所有字段。 + +**适用于**：表、超级表。 + +**使用说明**: + +- 如果要返回各个列的最后（时间戳最大）一个非 NULL 值，可以使用 LAST(\*)； +- 如果结果集中的某列全部为 NULL 值，则该列的返回结果也是 NULL；如果结果集中所有列全部为 NULL 值，则不返回结果。 +- 在用于超级表时，时间戳完全一样且同为最大的数据行可能有多个，那么会从中随机返回一条，而并不保证多次运行所挑选的数据行必然一致。 + + +**示例**： + +``` +taos> SELECT LAST(*) FROM meters; + last(ts) | last(current) | last(voltage) | last(phase) | +======================================================================================== +2018-10-03 14:38:16.800 | 12.30000 | 221 | 0.31000 | +Query OK, 1 row(s) in set (0.001452s) + +taos> SELECT LAST(current) FROM d1002; + last(current) | +======================= + 10.30000 | +Query OK, 1 row(s) in set (0.000843s) +``` + +### TOP + +``` +SELECT TOP(field_name, K) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**功能说明**： 统计表/超级表中某列的值最大 _k_ 个非 NULL 值。如果多条数据取值一样，全部取用又会超出 k 条限制时，系统会从相同值中随机选取符合要求的数量返回。 + +**返回数据类型**：同应用的字段。 + +**应用字段**：不能应用在 timestamp、binary、nchar、bool 类型字段。 + +**适用于**：表、超级表。 + +**使用说明**: + +- *k*值取值范围 1≤*k*≤100； +- 系统同时返回该记录关联的时间戳列； +- 限制：TOP 函数不支持 FILL 子句。 + +**示例**： + +``` +taos> SELECT TOP(current, 3) FROM meters; + ts | top(current, 3) | +================================================= +2018-10-03 14:38:15.000 | 12.60000 | +2018-10-03 14:38:16.600 | 13.40000 | +2018-10-03 14:38:16.800 | 12.30000 | +Query OK, 3 row(s) in set (0.001548s) + +taos> SELECT TOP(current, 2) FROM d1001; + ts | top(current, 2) | +================================================= +2018-10-03 14:38:15.000 | 12.60000 | +2018-10-03 14:38:16.800 | 12.30000 | +Query OK, 2 row(s) in set (0.000810s) +``` + +### BOTTOM + +``` +SELECT BOTTOM(field_name, K) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**功能说明**：统计表/超级表中某列的值最小 _k_ 个非 NULL 值。如果多条数据取值一样，全部取用又会超出 k 条限制时，系统会从相同值中随机选取符合要求的数量返回。 + +**返回数据类型**：同应用的字段。 + +**应用字段**：不能应用在 timestamp、binary、nchar、bool 类型字段。 + +**适用于**：表、超级表。 + +**使用说明**: + +- *k*值取值范围 1≤*k*≤100； +- 系统同时返回该记录关联的时间戳列； +- 限制：BOTTOM 函数不支持 FILL 子句。 + +**示例**： + +``` +taos> SELECT BOTTOM(voltage, 2) FROM meters; + ts | bottom(voltage, 2) | +=============================================== +2018-10-03 14:38:15.000 | 218 | +2018-10-03 14:38:16.650 | 218 | +Query OK, 2 row(s) in set (0.001332s) + +taos> SELECT BOTTOM(current, 2) FROM d1001; + ts | bottom(current, 2) | +================================================= +2018-10-03 14:38:05.000 | 10.30000 | +2018-10-03 14:38:16.800 | 12.30000 | +Query OK, 2 row(s) in set (0.000793s) +``` + +### PERCENTILE + +``` +SELECT PERCENTILE(field_name, P) FROM { tb_name } [WHERE clause]; +``` + +**功能说明**：统计表中某列的值百分比分位数。 + +**返回数据类型**： 双精度浮点数 Double。 + +**应用字段**：不能应用在 timestamp、binary、nchar、bool 类型字段。 + +**适用于**：表。 + +**使用说明**：*P*值取值范围 0≤*P*≤100，为 0 的时候等同于 MIN，为 100 的时候等同于 MAX。 + +**示例**： + +``` +taos> SELECT PERCENTILE(current, 20) FROM d1001; +percentile(current, 20) | +============================ + 11.100000191 | +Query OK, 1 row(s) in set (0.000787s) +``` + +### APERCENTILE + +``` +SELECT APERCENTILE(field_name, P[, algo_type]) +FROM { tb_name | stb_name } [WHERE clause] +``` + +**功能说明**：统计表/超级表中指定列的值百分比分位数，与 PERCENTILE 函数相似，但是返回近似结果。 + +**返回数据类型**： 双精度浮点数 Double。 + +**应用字段**：不能应用在 timestamp、binary、nchar、bool 类型字段。 + +**适用于**：表、超级表。 + +**使用说明** + +- **P**值有效取值范围 0≤P≤100，为 0 的时候等同于 MIN，为 100 的时候等同于 MAX； +- **algo_type**的有效输入：**default** 和 **t-digest** +- 用于指定计算近似分位数的算法。可不提供第三个参数的输入，此时将使用 default 的算法进行计算，即 apercentile(column_name, 50, "default") 与 apercentile(column_name, 50) 等价。 +- 当使用“t-digest”参数的时候，将使用 t-digest 方式采样计算近似分位数。但该参数指定计算算法的功能从 2.2.0.x 版本开始支持，2.2.0.0 之前的版本不支持指定使用算法的功能。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +``` +taos> SELECT APERCENTILE(current, 20) FROM d1001; +apercentile(current, 20) | +============================ + 10.300000191 | +Query OK, 1 row(s) in set (0.000645s) + +taos> select apercentile (count, 80, 'default') from stb1; + apercentile (c0, 80, 'default') | +================================== + 601920857.210056424 | +Query OK, 1 row(s) in set (0.012363s) + +taos> select apercentile (count, 80, 't-digest') from stb1; + apercentile (c0, 80, 't-digest') | +=================================== + 605869120.966666579 | +Query OK, 1 row(s) in set (0.011639s) +``` + +### LAST_ROW + +``` +SELECT LAST_ROW(field_name) FROM { tb_name | stb_name }; +``` + +**功能说明**：返回表/超级表的最后一条记录。 + +**返回数据类型**：同应用的字段。 + +**应用字段**：所有字段。 + +**适用于**：表、超级表。 + +**使用说明**： + +- 在用于超级表时，时间戳完全一样且同为最大的数据行可能有多个，那么会从中随机返回一条，而并不保证多次运行所挑选的数据行必然一致。 +- 不能与 INTERVAL 一起使用。 + +**示例**： + +``` + taos> SELECT LAST_ROW(current) FROM meters; + last_row(current) | + ======================= + 12.30000 | + Query OK, 1 row(s) in set (0.001238s) + + taos> SELECT LAST_ROW(current) FROM d1002; + last_row(current) | + ======================= + 10.30000 | + Query OK, 1 row(s) in set (0.001042s) +``` + +### INTERP [2.3.1 及之后的版本] + +``` +SELECT INTERP(field_name) FROM { tb_name | stb_name } [WHERE where_condition] [ RANGE(timestamp1,timestamp2) ] [EVERY(interval)] [FILL ({ VALUE | PREV | NULL | LINEAR | NEXT})]; +``` + +**功能说明**：返回表/超级表的指定时间截面指定列的记录值（插值）。 + +**返回数据类型**：同字段类型。 + +**应用字段**：数值型字段。 + +**适用于**：表、超级表、嵌套查询。 + + +**使用说明** + +- INTERP 用于在指定时间断面获取指定列的记录值，如果该时间断面不存在符合条件的行数据，那么会根据 FILL 参数的设定进行插值。 +- INTERP 的输入数据为指定列的数据，可以通过条件语句（where 子句）来对原始列数据进行过滤，如果没有指定过滤条件则输入为全部数据。 +- INTERP 的输出时间范围根据 RANGE(timestamp1,timestamp2)字段来指定，需满足 timestamp1<=timestamp2。其中 timestamp1（必选值）为输出时间范围的起始值，即如果 timestamp1 时刻符合插值条件则 timestamp1 为输出的第一条记录，timestamp2（必选值）为输出时间范围的结束值，即输出的最后一条记录的 timestamp 不能大于 timestamp2。如果没有指定 RANGE，那么满足过滤条件的输入数据中第一条记录的 timestamp 即为 timestamp1，最后一条记录的 timestamp 即为 timestamp2，同样也满足 timestamp1 <= timestamp2。 +- INTERP 根据 EVERY 字段来确定输出时间范围内的结果条数，即从 timestamp1 开始每隔固定长度的时间（EVERY 值）进行插值。如果没有指定 EVERY，则默认窗口大小为无穷大，即从 timestamp1 开始只有一个窗口。 +- INTERP 根据 FILL 字段来决定在每个符合输出条件的时刻如何进行插值，如果没有 FILL 字段则默认不插值，即输出为原始记录值或不输出（原始记录不存在）。 +- INTERP 只能在一个时间序列内进行插值，因此当作用于超级表时必须跟 group by tbname 一起使用，当作用嵌套查询外层时内层子查询不能含 GROUP BY 信息。 +- INTERP 的插值结果不受 ORDER BY timestamp 的影响，ORDER BY timestamp 只影响输出结果的排序。 + +**SQL示例（基于文档中广泛使用的电表 schema )**： + +- 单点线性插值 + +``` + taos> SELECT INTERP(current) FROM t1 RANGE('2017-7-14 18:40:00','2017-7-14 18:40:00') FILL(LINEAR); +``` + +- 在2017-07-14 18:00:00到2017-07-14 19:00:00间每隔5秒钟进行取值(不插值) + +``` + taos> SELECT INTERP(current) FROM t1 RANGE('2017-7-14 18:00:00','2017-7-14 19:00:00') EVERY(5s); +``` + +- 在2017-07-14 18:00:00到2017-07-14 19:00:00间每隔5秒钟进行线性插值 + +``` + taos> SELECT INTERP(current) FROM t1 RANGE('2017-7-14 18:00:00','2017-7-14 19:00:00') EVERY(5s) FILL(LINEAR); +``` + +- 在所有时间范围内每隔 5 秒钟进行向后插值 + +``` + taos> SELECT INTERP(current) FROM t1 EVERY(5s) FILL(NEXT); +``` + +- 根据 2017-07-14 17:00:00 到 2017-07-14 20:00:00 间的数据进行从 2017-07-14 18:00:00 到 2017-07-14 19:00:00 间每隔 5 秒钟进行线性插值 + +``` + taos> SELECT INTERP(current) FROM t1 where ts >= '2017-07-14 17:00:00' and ts <= '2017-07-14 20:00:00' RANGE('2017-7-14 18:00:00'，'2017-7-14 19:00:00') EVERY(5s) FILL(LINEAR); +``` + +### INTERP [2.3.1 之前的版本] + +``` +SELECT INTERP(field_name) FROM { tb_name | stb_name } WHERE ts='timestamp' [FILL ({ VALUE | PREV | NULL | LINEAR | NEXT})]; +``` + +**功能说明**：返回表/超级表的指定时间截面、指定字段的记录。 + +**返回数据类型**：同字段类型。 + +**应用字段**：数值型字段。 + +**适用于**：表、超级表。 + +**使用说明**: + +- 从 2.0.15.0 及以后版本可用 +- INTERP 必须指定时间断面，如果该时间断面不存在直接对应的数据，那么会根据 FILL 参数的设定进行插值。此外，条件语句里面可附带筛选条件，例如标签、tbname。 +- INTERP 查询要求查询的时间区间必须位于数据集合（表）的所有记录的时间范围之内。如果给定的时间戳位于时间范围之外，即使有插值指令，仍然不返回结果。 +- 单个 INTERP 函数查询只能够针对一个时间点进行查询，如果需要返回等时间间隔的断面数据，可以通过 INTERP 配合 EVERY 的方式来进行查询处理（而不是使用 INTERVAL），其含义是每隔固定长度的时间进行插值 + +**示例**： + +``` + taos> SELECT INTERP(*) FROM meters WHERE ts='2017-7-14 18:40:00.004'; + interp(ts) | interp(current) | interp(voltage) | interp(phase) | + ========================================================================================== + 2017-07-14 18:40:00.004 | 9.84020 | 216 | 0.32222 | + Query OK, 1 row(s) in set (0.002652s) +``` + +如果给定的时间戳无对应的数据，在不指定插值生成策略的情况下，不会返回结果，如果指定了插值策略，会根据插值策略返回结果。 + +``` + taos> SELECT INTERP(*) FROM meters WHERE tbname IN ('d636') AND ts='2017-7-14 18:40:00.005'; + Query OK, 0 row(s) in set (0.004022s) + + taos> SELECT INTERP(*) FROM meters WHERE tbname IN ('d636') AND ts='2017-7-14 18:40:00.005' FILL(PREV); + interp(ts) | interp(current) | interp(voltage) | interp(phase) | + ========================================================================================== + 2017-07-14 18:40:00.005 | 9.88150 | 217 | 0.32500 | + Query OK, 1 row(s) in set (0.003056s) +``` + +如下所示代码表示在时间区间 `['2017-7-14 18:40:00', '2017-7-14 18:40:00.014']` 中每隔 5 毫秒 进行一次断面计算。 + +``` + taos> SELECT INTERP(current) FROM d636 WHERE ts>='2017-7-14 18:40:00' AND ts<='2017-7-14 18:40:00.014' EVERY(5a); + ts | interp(current) | + ================================================= + 2017-07-14 18:40:00.000 | 10.04179 | + 2017-07-14 18:40:00.010 | 10.16123 | + Query OK, 2 row(s) in set (0.003487s) +``` + +## 计算函数 + +### DIFF + + ```sql + SELECT {DIFF(field_name, ignore_negative) | DIFF(field_name)} FROM tb_name [WHERE clause]; + ``` + +**功能说明**：统计表中某列的值与前一行对应值的差。 ignore_negative 取值为 0|1 , 可以不填，默认值为 0. 不忽略负值。ignore_negative 为 1 时表示忽略负数。 + +**返回结果数据类型**：同应用字段。 + +**应用字段**：不能应用在 timestamp、binary、nchar、bool 类型字段。 + +**适用于**：表、超级表。 + +**使用说明**: + +- 输出结果行数是范围内总行数减一，第一行没有结果输出。 +- 从 2.1.3.0 版本开始，DIFF 函数可以在由 GROUP BY 划分出单独时间线的情况下用于超级表（也即 GROUP BY tbname）。 + +**示例**： + + ```sql + taos> SELECT DIFF(current) FROM d1001; + ts | diff(current) | + ================================================= + 2018-10-03 14:38:15.000 | 2.30000 | + 2018-10-03 14:38:16.800 | -0.30000 | + Query OK, 2 row(s) in set (0.001162s) + ``` + +### DERIVATIVE + +``` +SELECT DERIVATIVE(field_name, time_interval, ignore_negative) FROM tb_name [WHERE clause]; +``` + +**功能说明**：统计表中某列数值的单位变化率。其中单位时间区间的长度可以通过 time_interval 参数指定，最小可以是 1 秒（1s）；ignore_negative 参数的值可以是 0 或 1，为 1 时表示忽略负值。 + +**返回数据类型**：双精度浮点数。 + +**应用字段**：不能应用在 timestamp、binary、nchar、bool 类型字段。 + +**适用于**：表、超级表 + +**使用说明**: + +- 从 2.1.3.0 及以后版本可用；输出结果行数是范围内总行数减一，第一行没有结果输出。 +- DERIVATIVE 函数可以在由 GROUP BY 划分出单独时间线的情况下用于超级表（也即 GROUP BY tbname）。 + +**示例**： + +``` +taos> select derivative(current, 10m, 0) from t1; + ts | derivative(current, 10m, 0) | +======================================================== + 2021-08-20 10:11:22.790 | 0.500000000 | + 2021-08-20 11:11:22.791 | 0.166666620 | + 2021-08-20 12:11:22.791 | 0.000000000 | + 2021-08-20 13:11:22.792 | 0.166666620 | + 2021-08-20 14:11:22.792 | -0.666666667 | +Query OK, 5 row(s) in set (0.004883s) +``` + +### SPREAD + +``` +SELECT SPREAD(field_name) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**功能说明**：统计表/超级表中某列的最大值和最小值之差。 + +**返回数据类型**：双精度浮点数。 + +**应用字段**：不能应用在 binary、nchar、bool 类型字段。 + +**适用于**：表、超级表。 + +**使用说明**：可用于 TIMESTAMP 字段，此时表示记录的时间覆盖范围。 + +**示例**： + +``` +taos> SELECT SPREAD(voltage) FROM meters; + spread(voltage) | +============================ + 5.000000000 | +Query OK, 1 row(s) in set (0.001792s) + +taos> SELECT SPREAD(voltage) FROM d1001; + spread(voltage) | +============================ + 3.000000000 | +Query OK, 1 row(s) in set (0.000836s) +``` + +### CEIL + +``` +SELECT CEIL(field_name) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**功能说明**：获得指定列的向上取整数的结果。 + +**返回结果类型**：与指定列的原始数据类型一致。例如，如果指定列的原始数据类型为 Float，那么返回的数据类型也为 Float；如果指定列的原始数据类型为 Double，那么返回的数据类型也为 Double。 + +**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列，无论 tag 列的类型是什么类型。 + +**适用于**: 普通表、超级表。 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**使用说明**: + +- 支持 +、-、\*、/ 运算，如 ceil(col1) + ceil(col2)。 +- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 + +### FLOOR + +``` +SELECT FLOOR(field_name) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**功能说明**：获得指定列的向下取整数的结果。 + 其他使用说明参见 CEIL 函数描述。 + +### ROUND + +``` +SELECT ROUND(field_name) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**功能说明**：获得指定列的四舍五入的结果。 + 其他使用说明参见 CEIL 函数描述。 + +### CSUM + +```sql + SELECT CSUM(field_name) FROM { tb_name | stb_name } [WHERE clause] +``` + + **功能说明**：累加和（Cumulative sum），输出行与输入行数相同。 + + **返回结果类型**： 输入列如果是整数类型返回值为长整型 （int64_t），浮点数返回值为双精度浮点数（Double）。无符号整数类型返回值为无符号长整型（uint64_t）。 返回结果中同时带有每行记录对应的时间戳。 + + **适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在标签之上。 + + **嵌套子查询支持**： 适用于内层查询和外层查询。 + + **使用说明**： + + - 不支持 +、-、*、/ 运算，如 csum(col1) + csum(col2)。 + - 只能与聚合（Aggregation）函数一起使用。 该函数可以应用在普通表和超级表上。 + - 使用在超级表上的时候，需要搭配 Group by tbname使用，将结果强制规约到单个时间线。 + +**支持版本**： 从2.3.0.x开始支持 + +### MAVG + +```sql + SELECT MAVG(field_name, K) FROM { tb_name | stb_name } [WHERE clause] +``` + + **功能说明**： 计算连续 k 个值的移动平均数（moving average）。如果输入行数小于 k，则无结果输出。参数 k 的合法输入范围是 1≤ k ≤ 1000。 + + **返回结果类型**： 返回双精度浮点数类型。 + + **适用数据类型**： 不能应用在 timestamp、binary、nchar、bool 类型上；在超级表查询中使用时，不能应用在标签之上。 + + **嵌套子查询支持**： 适用于内层查询和外层查询。 + + **使用说明**： + + - 不支持 +、-、*、/ 运算，如 mavg(col1, k1) + mavg(col2, k1); + - 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用； + - 该函数可以应用在普通表和超级表上；使用在超级表上的时候，需要搭配 Group by tbname使用，将结果强制规约到单个时间线。 + +**支持版本**： 从2.3.0.x开始支持 + +### SAMPLE + +```sql + SELECT SAMPLE(field_name, K) FROM { tb_name | stb_name } [WHERE clause] +``` + + **功能说明**： 获取数据的 k 个采样值。参数 k 的合法输入范围是 1≤ k ≤ 1000。 + + **返回结果类型**： 同原始数据类型， 返回结果中带有该行记录的时间戳。 + + **适用数据类型**： 在超级表查询中使用时，不能应用在标签之上。 + + **嵌套子查询支持**： 适用于内层查询和外层查询。 + + **使用说明**： + + - 不能参与表达式计算；该函数可以应用在普通表和超级表上； + - 使用在超级表上的时候，需要搭配 Group by tbname 使用，将结果强制规约到单个时间线。 + +**支持版本**： 从2.3.0.x开始支持 + +### 四则运算 + +``` +SELECT field_name [+|-|*|/|%][Value|field_name] FROM { tb_name | stb_name } [WHERE clause]; +``` + +**功能说明**：统计表/超级表中某列或多列间的值加、减、乘、除、取余计算结果。 + +**返回数据类型**：双精度浮点数。 + +**应用字段**：不能应用在 timestamp、binary、nchar、bool 类型字段。 + +**适用于**：表、超级表。 + +**使用说明**： + +- 支持两列或多列之间进行计算，可使用括号控制计算优先级； +- NULL 字段不参与计算，如果参与计算的某行中包含 NULL，该行的计算结果为 NULL。 + +``` +taos> SELECT current + voltage * phase FROM d1001; +(current+(voltage*phase)) | +============================ + 78.190000713 | + 84.540003240 | + 80.810000718 | +Query OK, 3 row(s) in set (0.001046s) +``` + +**示例**： + +``` +taos> select ts,dbig from statef2; + ts | dbig | +======================================================== +2021-10-15 00:31:33.000000000 | 1 | +2021-10-17 00:31:31.000000000 | NULL | +2021-12-24 00:31:34.000000000 | 2 | +2022-01-01 08:00:05.000000000 | 19 | +2022-01-01 08:00:06.000000000 | NULL | +2022-01-01 08:00:07.000000000 | 9 | +Query OK, 6 row(s) in set (0.002977s) + +taos> select stateCount(dbig,GT,2) from statef2; +ts | dbig | statecount(dbig,gt,2) | +================================================================================ +2021-10-15 00:31:33.000000000 | 1 | -1 | +2021-10-17 00:31:31.000000000 | NULL | NULL | +2021-12-24 00:31:34.000000000 | 2 | -1 | +2022-01-01 08:00:05.000000000 | 19 | 1 | +2022-01-01 08:00:06.000000000 | NULL | NULL | +2022-01-01 08:00:07.000000000 | 9 | 2 | +Query OK, 6 row(s) in set (0.002791s) +``` + diff --git a/docs-cn/12-taos-sql/08-interval.md b/docs-cn/12-taos-sql/08-interval.md new file mode 100644 index 0000000000000000000000000000000000000000..d62e11b0dbd0ba49ceedb3807e05361f060969b3 --- /dev/null +++ b/docs-cn/12-taos-sql/08-interval.md @@ -0,0 +1,113 @@ +--- +sidebar_label: 按窗口切分聚合 +title: 按窗口切分聚合 +--- + + +TDengine 支持按时间段窗口切分方式进行聚合结果查询，比如温度传感器每秒采集一次数据，但需查询每隔 10 分钟的温度平均值。这种场景下可以使用窗口子句来获得需要的查询结果。 +窗口子句用于针对查询的数据集合进行按照窗口切分成为查询子集并进行聚合，窗口包含时间窗口（time window）、状态窗口（status window）、会话窗口（session window）三种窗口。其中时间窗口又可划分为滑动时间窗口和翻转时间窗口。 + +## 时间窗口 + +INTERVAL 子句用于产生相等时间周期的窗口，SLIDING 用以指定窗口向前滑动的时间。每次执行的查询是一个时间窗口，时间窗口随着时间流动向前滑动。在定义连续查询的时候需要指定时间窗口（time window ）大小和每次前向增量时间（forward sliding times）。如图，[t0s, t0e] ，[t1s , t1e]， [t2s, t2e] 是分别是执行三次连续查询的时间窗口范围，窗口的前向滑动的时间范围 sliding time 标识 。查询过滤、聚合等操作按照每个时间窗口为独立的单位执行。当 SLIDING 与 INTERVAL 相等的时候，滑动窗口即为翻转窗口。 + +![时间窗口示意图](/img/sql/timewindow-1.png) + +INTERVAL 和 SLIDING 子句需要配合聚合和选择函数来使用。以下 SQL 语句非法： + +``` +SELECT * FROM temp_tb_1 INTERVAL(1m); +``` + +SLIDING 的向前滑动的时间不能超过一个窗口的时间范围。以下语句非法： + +``` +SELECT COUNT(*) FROM temp_tb_1 INTERVAL(1m) SLIDING(2m); +``` + +当 SLIDING 与 INTERVAL 取值相等的时候，滑动窗口即为翻转窗口。 +_ 聚合时间段的窗口宽度由关键词 INTERVAL 指定，最短时间间隔 10 毫秒（10a）；并且支持偏移 offset（偏移必须小于间隔），也即时间窗口划分与“UTC 时刻 0”相比的偏移量。SLIDING 语句用于指定聚合时间段的前向增量，也即每次窗口向前滑动的时长。 +_ 从 2.1.5.0 版本开始，INTERVAL 语句允许的最短时间间隔调整为 1 微秒（1u），当然如果所查询的 DATABASE 的时间精度设置为毫秒级，那么允许的最短时间间隔为 1 毫秒（1a）。 \* **注意**：用到 INTERVAL 语句时，除非极特殊的情况，都要求把客户端和服务端的 taos.cfg 配置文件中的 timezone 参数配置为相同的取值，以避免时间处理函数频繁进行跨时区转换而导致的严重性能影响。 + +## 状态窗口 + +使用整数（布尔值）或字符串来标识产生记录时候设备的状态量。产生的记录如果具有相同的状态量数值则归属于同一个状态窗口，数值改变后该窗口关闭。如下图所示，根据状态量确定的状态窗口分别是[2019-04-28 14:22:07，2019-04-28 14:22:10]和[2019-04-28 14:22:11，2019-04-28 14:22:12]两个。（状态窗口暂不支持对超级表使用） + +![时间窗口示意图](/img/sql/timewindow-3.png) + +使用 STATE_WINDOW 来确定状态窗口划分的列。例如： + +``` +SELECT COUNT(*), FIRST(ts), status FROM temp_tb_1 STATE_WINDOW(status); +``` + +## 会话窗口 + +会话窗口根据记录的时间戳主键的值来确定是否属于同一个会话。如下图所示，如果设置时间戳的连续的间隔小于等于 12 秒，则以下 6 条记录构成 2 个会话窗口，分别是：[2019-04-28 14:22:10，2019-04-28 14:22:30]和[2019-04-28 14:23:10，2019-04-28 14:23:30]。因为 2019-04-28 14:22:30 与 2019-04-28 14:23:10 之间的时间间隔是 40 秒，超过了连续时间间隔（12 秒）。 + +![时间窗口示意图](/img/sql/timewindow-2.png) + +在 tol_value 时间间隔范围内的结果都认为归属于同一个窗口，如果连续的两条记录的时间超过 tol_val，则自动开启下一个窗口。（会话窗口暂不支持对超级表使用） + +``` + +SELECT COUNT(*), FIRST(ts) FROM temp_tb_1 SESSION(ts, tol_val); +``` + +这种类型的查询语法如下： + +``` +SELECT function_list FROM tb_name + [WHERE where_condition] + [SESSION(ts_col, tol_val)] + [STATE_WINDOW(col)] + [INTERVAL(interval [, offset]) [SLIDING sliding]] + [FILL({NONE | VALUE | PREV | NULL | LINEAR | NEXT})] + +SELECT function_list FROM stb_name + [WHERE where_condition] + [INTERVAL(interval [, offset]) [SLIDING sliding]] + [FILL({NONE | VALUE | PREV | NULL | LINEAR | NEXT})] + [GROUP BY tags] +``` + +- 在聚合查询中，function_list 位置允许使用聚合和选择函数，并要求每个函数仅输出单个结果（例如：COUNT、AVG、SUM、STDDEV、LEASTSQUARES、PERCENTILE、MIN、MAX、FIRST、LAST），而不能使用具有多行输出结果的函数（例如：DIFF 以及四则运算）。 +- 此外 LAST_ROW 查询也不能与窗口聚合同时出现。 +- 标量函数（如：CEIL/FLOOR 等）也不能使用在窗口聚合查询中。 +- + +- WHERE 语句可以指定查询的起止时间和其他过滤条件。 +- FILL 语句指定某一窗口区间数据缺失的情况下的填充模式。填充模式包括以下几种： + 1. 不进行填充：NONE（默认填充模式）。 + 2. VALUE 填充：固定值填充，此时需要指定填充的数值。例如：FILL(VALUE, 1.23)。 + 3. PREV 填充：使用前一个非 NULL 值填充数据。例如：FILL(PREV)。 + 4. NULL 填充：使用 NULL 填充数据。例如：FILL(NULL)。 + 5. LINEAR 填充：根据前后距离最近的非 NULL 值做线性插值填充。例如：FILL(LINEAR)。 + 6. NEXT 填充：使用下一个非 NULL 值填充数据。例如：FILL(NEXT)。 + +:::info + +1. 使用 FILL 语句的时候可能生成大量的填充输出，务必指定查询的时间区间。针对每次查询，系统可返回不超过 1 千万条具有插值的结果。 +2. 在时间维度聚合中，返回的结果中时间序列严格单调递增。 +3. 如果查询对象是超级表，则聚合函数会作用于该超级表下满足值过滤条件的所有表的数据。如果查询中没有使用 GROUP BY 语句，则返回的结果按照时间序列严格单调递增；如果查询中使用了 GROUP BY 语句分组，则返回结果中每个 GROUP 内不按照时间序列严格单调递增。 + +::: + +时间聚合也常被用于连续查询场景，可以参考文档 [连续查询(Continuous Query)](/develop/continuous-query)。 + +## 示例 + +智能电表的建表语句如下： + +``` +CREATE TABLE meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT); +``` + +针对智能电表采集的数据，以 10 分钟为一个阶段，计算过去 24 小时的电流数据的平均值、最大值、电流的中位数。如果没有计算值，用前一个非 NULL 值填充。使用的查询语句如下： + +``` +SELECT AVG(current), MAX(current), APERCENTILE(current, 50) FROM meters + WHERE ts>=NOW-1d and ts<=now + INTERVAL(10m) + FILL(PREV); +``` diff --git a/docs-cn/12-taos-sql/09-limit.md b/docs-cn/12-taos-sql/09-limit.md new file mode 100644 index 0000000000000000000000000000000000000000..3c86a3862174377e6a00d046fb69627c773fe76e --- /dev/null +++ b/docs-cn/12-taos-sql/09-limit.md @@ -0,0 +1,54 @@ +--- +sidebar_label: 边界限制 +title: 边界限制 +--- + +## 一般限制 + +- 数据库名最大长度为 32。 +- 表名最大长度为 192，不包括数据库名前缀和分隔符 +- 每行数据最大长度 16k 个字符, 从 2.1.7.0 版本开始，每行数据最大长度 48k 个字符（注意：数据行内每个 BINARY/NCHAR 类型的列还会额外占用 2 个字节的存储位置）。 +- 列名最大长度为 64，最多允许 4096 列，最少需要 2 列，第一列必须是时间戳。注：从 2.1.7.0 版本（不含)以前最多允许 4096 列 +- 标签名最大长度为 64，最多允许 128 个，至少要有 1 个标签，一个表中标签值的总长度不超过 16k 个字符。 +- SQL 语句最大长度 1048576 个字符，也可通过客户端配置参数 maxSQLLength 修改，取值范围 65480 ~ 1048576。 +- SELECT 语句的查询结果，最多允许返回 4096 列（语句中的函数调用可能也会占用一些列空间），超限时需要显式指定较少的返回数据列，以避免语句执行报错。注： 2.1.7.0 版本（不含）之前为最多允许 1024 列 +- 库的数目，超级表的数目、表的数目，系统不做限制，仅受系统资源限制。 + +## GROUP BY 的限制 + +TAOS SQL 支持对标签、TBNAME 进行 GROUP BY 操作，也支持普通列进行 GROUP BY，前提是：仅限一列且该列的唯一值小于 10 万个。注意：group by 不支持 float,double 类型。 + +## IS NOT NULL 的限制 + +IS NOT NULL 与不为空的表达式适用范围。 + +IS NOT NULL 支持所有类型的列。不为空的表达式为 <\>""，仅对非数值类型的列适用。 + +## ORDER BY 的限制 + +- 非超级表只能有一个 order by. +- 超级表最多两个 order by， 并且第二个必须为 ts. +- order by tag，必须和 group by tag 一起，并且是同一个 tag。 tbname 和 tag 一样逻辑。 只适用于超级表 +- order by 普通列，必须和 group by 一起或者和 top/bottom 一起，并且是同一个普通列。 适用于超级表和普通表。如果同时存在 group by 和 top/bottom 一起，order by 优先必须和 group by 同一列。 +- order by ts. 适用于超级表和普通表。 +- order by ts 同时含有 group by 时 针对 group 内部用 ts 排序 + +## 表(列)名合法性说明 + +### TDengine 中的表（列）名命名规则如下： +只能由字母、数字、下划线构成，数字不能在首位，长度不能超过 192 字节，不区分大小写。这里表名称不包括数据库名的前缀和分隔符。 + +### 转义后表（列）名规则： +为了兼容支持更多形式的表（列）名，TDengine 引入新的转义符 "`"，可以避免表名与关键词的冲突，同时不受限于上述表名合法性约束检查，转义符不计入表名的长度。 +转义后的表（列）名同样受到长度限制要求，且长度计算的时候不计算转义符。使用转义字符以后，不再对转义字符中的内容进行大小写统一。 + +例如： +\`aBc\` 和 \`abc\` 是不同的表（列）名，但是 abc 和 aBc 是相同的表（列）名。 + +:::note +转义字符中的内容必须是可打印字符。 + +::: + +### 支持版本 +支持转义符的功能从 2.3.0.1 版本开始。 \ No newline at end of file diff --git a/docs-cn/12-taos-sql/10-json.md b/docs-cn/12-taos-sql/10-json.md new file mode 100644 index 0000000000000000000000000000000000000000..4a4a8cca732ac433ba5ada1ec3805ebfa663edb3 --- /dev/null +++ b/docs-cn/12-taos-sql/10-json.md @@ -0,0 +1,91 @@ +--- +sidebar_label: JSON 类型使用说明 +title: JSON 类型使用说明 +--- + + +## 语法说明 + +1. 创建 json 类型 tag + + ``` + create stable s1 (ts timestamp, v1 int) tags (info json) + + create table s1_1 using s1 tags ('{"k1": "v1"}') + ``` + +2. json 取值操作符 -> + + ``` + select * from s1 where info->'k1' = 'v1' + + select info->'k1' from s1 + ``` + +3. json key 是否存在操作符 contains + + ``` + select * from s1 where info contains 'k2' + + select * from s1 where info contains 'k1' + ``` + +## 支持的操作 + +1. 在 where 条件中时，支持函数 match/nmatch/between and/like/and/or/is null/is no null，不支持 in + + ``` + select * from s1 where info->'k1' match 'v*'; + + select * from s1 where info->'k1' like 'v%' and info contains 'k2'; + + select * from s1 where info is null; + + select * from s1 where info->'k1' is not null + ``` + +2. 支持 json tag 放在 group by、order by、join 子句、union all 以及子查询中，比如 group by json->'key' + +3. 支持 distinct 操作. + + ``` + select distinct info->'k1' from s1 + ``` + +4. 标签操作 + + 支持修改 json 标签值（全量覆盖） + + 支持修改 json 标签名 + + 不支持添加 json 标签、删除 json 标签、修改 json 标签列宽 + +## 其他约束条件 + +1. 只有标签列可以使用 json 类型，如果用 json 标签，标签列只能有一个。 + +2. 长度限制：json 中 key 的长度不能超过 256，并且 key 必须为可打印 ascii 字符；json 字符串总长度不超过 4096 个字节。 + +3. json 格式限制： + + 1. json 输入字符串可以为空（"","\t"," "或 null）或 object，不能为非空的字符串，布尔型和数组。 + 2. object 可为{}，如果 object 为{}，则整个 json 串记为空。key 可为""，若 key 为""，则 json 串中忽略该 k-v 对。 + 3. value 可以为数字(int/double)或字符串或 bool 或 null，暂不可以为数组。不允许嵌套。 + 4. 若 json 字符串中出现两个相同的 key，则第一个生效。 + 5. json 字符串里暂不支持转义。 + +4. 当查询 json 中不存在的 key 时，返回 NULL + +5. 当 json tag 作为子查询结果时，不再支持上层查询继续对子查询中的 json 串做解析查询。 + + 比如暂不支持 + + ``` + select jtag->'key' from (select jtag from stable) + ``` + + 不支持 + + ``` + select jtag->'key' from (select jtag from stable) where jtag->'key'>0 + ``` diff --git a/docs-cn/12-taos-sql/11-escape.md b/docs-cn/12-taos-sql/11-escape.md new file mode 100644 index 0000000000000000000000000000000000000000..756e5c81591e7414827fdc65e228cfafc96214ad --- /dev/null +++ b/docs-cn/12-taos-sql/11-escape.md @@ -0,0 +1,30 @@ +--- +title: 转义字符说明 +--- + +## 转义字符表 + +| 字符序列 | **代表的字符** | +| :------: | -------------- | +| `\'` | 单引号' | +| `\"` | 双引号" | +| \n | 换行符 | +| \r | 回车符 | +| \t | tab 符 | +| `\\` | 斜杠\ | +| `\%` | % 规则见下 | +| `\_` | \_ 规则见下 | + +:::note +转义符的功能从 2.4.0.4 版本开始 + +::: + +## 转义字符使用规则 + +1. 标识符里有转义字符（数据库名、表名、列名） + 1. 普通标识符： 直接提示错误的标识符，因为标识符规定必须是数字、字母和下划线，并且不能以数字开头。 + 2. 反引号``标识符： 保持原样，不转义 +2. 数据里有转义字符 + 1. 遇到上面定义的转义字符会转义（%和\_见下面说明），如果没有匹配的转义字符会忽略掉转义符\。 + 2. 对于%和\_，因为在 like 里这两个字符是通配符，所以在模式匹配 like 里用`\%`%和`\_`表示字符里本身的%和\_，如果在 like 模式匹配上下文之外使用`\%`或`\_`，则它们的计算结果为字符串`\%`和`\_`，而不是%和\_。 diff --git a/docs-cn/12-taos-sql/12-keywords/_category_.yml b/docs-cn/12-taos-sql/12-keywords/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..67738650a4564477f017542aea81767b3de72922 --- /dev/null +++ b/docs-cn/12-taos-sql/12-keywords/_category_.yml @@ -0,0 +1 @@ +label: 参数限制与保留关键字 \ No newline at end of file diff --git a/docs-cn/12-taos-sql/12-keywords/index.md b/docs-cn/12-taos-sql/12-keywords/index.md new file mode 100644 index 0000000000000000000000000000000000000000..608d4e080967cfd97072706cf0963ae669960be6 --- /dev/null +++ b/docs-cn/12-taos-sql/12-keywords/index.md @@ -0,0 +1,87 @@ +--- +sidebar_label: 参数限制与保留关键字 +title: TDengine 参数限制与保留关键字 +--- + +## 名称命名规则 + +1. 合法字符：英文字符、数字和下划线 +2. 允许英文字符或下划线开头，不允许以数字开头 +3. 不区分大小写 +4. 转义后表（列）名规则： + 为了兼容支持更多形式的表（列）名，TDengine 引入新的转义符 "`"。可用让表名与关键词不冲突，同时不受限于上述表名称合法性约束检查。 + 转义后的表（列）名同样受到长度限制要求，且长度计算的时候不计算转义符。使用转义字符以后，不再对转义字符中的内容进行大小写统一。 + + 例如：\`aBc\` 和 \`abc\` 是不同的表（列）名，但是 abc 和 aBc 是相同的表（列）名。 + 需要注意的是转义字符中的内容必须是可打印字符。 + 支持转义符的功能从 2.3.0.1 版本开始。 + +## 密码合法字符集 + +`[a-zA-Z0-9!?$%^&*()_–+={[}]:;@~#|<,>.?/]` + +去掉了 `` ‘“`\ `` (单双引号、撇号、反斜杠、空格) + +- 数据库名：不能包含“.”以及特殊字符，不能超过 32 个字符 +- 表名：不能包含“.”以及特殊字符，与所属数据库名一起，不能超过 192 个字符，每行数据最大长度 16k 个字符 +- 表的列名：不能包含特殊字符，不能超过 64 个字符 +- 数据库名、表名、列名，都不能以数字开头，合法的可用字符集是“英文字符、数字和下划线” +- 表的列数：不能超过 1024 列，最少需要 2 列，第一列必须是时间戳（从 2.1.7.0 版本开始，改为最多支持 4096 列） +- 记录的最大长度：包括时间戳 8 byte，不能超过 16KB（每个 BINARY/NCHAR 类型的列还会额外占用 2 个 byte 的存储位置） +- 单条 SQL 语句默认最大字符串长度：1048576 byte，但可通过系统配置参数 maxSQLLength 修改，取值范围 65480 ~ 1048576 byte +- 数据库副本数：不能超过 3 +- 用户名：不能超过 23 个 byte +- 用户密码：不能超过 15 个 byte +- 标签(Tags)数量：不能超过 128 个，可以 0 个 +- 标签的总长度：不能超过 16K byte +- 记录条数：仅受存储空间限制 +- 表的个数：仅受节点个数限制 +- 库的个数：仅受节点个数限制 +- 单个库上虚拟节点个数：不能超过 64 个 +- 库的数目，超级表的数目、表的数目，系统不做限制，仅受系统资源限制 +- SELECT 语句的查询结果，最多允许返回 1024 列（语句中的函数调用可能也会占用一些列空间），超限时需要显式指定较少的返回数据列，以避免语句执行报错。（从 2.1.7.0 版本开始，改为最多允许 4096 列） + +## 保留关键字 + +目前 TDengine 有将近 200 个内部保留关键字，这些关键字无论大小写均不可以用作库名、表名、STable 名、数据列名及标签列名等。这些关键字列表如下： + +| 关键字列表 | | | | | +| ----------- | ---------- | --------- | ---------- | ------------ | +| ABORT | CREATE | IGNORE | NULL | STAR | +| ACCOUNT | CTIME | IMMEDIATE | OF | STATE | +| ACCOUNTS | DATABASE | IMPORT | OFFSET | STATEMENT | +| ADD | DATABASES | IN | OR | STATE_WINDOW | +| AFTER | DAYS | INITIALLY | ORDER | STORAGE | +| ALL | DBS | INSERT | PARTITIONS | STREAM | +| ALTER | DEFERRED | INSTEAD | PASS | STREAMS | +| AND | DELIMITERS | INT | PLUS | STRING | +| AS | DESC | INTEGER | PPS | SYNCDB | +| ASC | DESCRIBE | INTERVAL | PRECISION | TABLE | +| ATTACH | DETACH | INTO | PREV | TABLES | +| BEFORE | DISTINCT | IS | PRIVILEGE | TAG | +| BEGIN | DIVIDE | ISNULL | QTIME | TAGS | +| BETWEEN | DNODE | JOIN | QUERIES | TBNAME | +| BIGINT | DNODES | KEEP | QUERY | TIMES | +| BINARY | DOT | KEY | QUORUM | TIMESTAMP | +| BITAND | DOUBLE | KILL | RAISE | TINYINT | +| BITNOT | DROP | LE | REM | TOPIC | +| BITOR | EACH | LIKE | REPLACE | TOPICS | +| BLOCKS | END | LIMIT | REPLICA | TRIGGER | +| BOOL | EQ | LINEAR | RESET | TSERIES | +| BY | EXISTS | LOCAL | RESTRICT | UMINUS | +| CACHE | EXPLAIN | LP | ROW | UNION | +| CACHELAST | FAIL | LSHIFT | RP | UNSIGNED | +| CASCADE | FILE | LT | RSHIFT | UPDATE | +| CHANGE | FILL | MATCH | SCORES | UPLUS | +| CLUSTER | FLOAT | MAXROWS | SELECT | USE | +| COLON | FOR | MINROWS | SEMI | USER | +| COLUMN | FROM | MINUS | SESSION | USERS | +| COMMA | FSYNC | MNODES | SET | USING | +| COMP | GE | MODIFY | SHOW | VALUES | +| COMPACT | GLOB | MODULES | SLASH | VARIABLE | +| CONCAT | GRANTS | NCHAR | SLIDING | VARIABLES | +| CONFLICT | GROUP | NE | SLIMIT | VGROUPS | +| CONNECTION | GT | NONE | SMALLINT | VIEW | +| CONNECTIONS | HAVING | NOT | SOFFSET | VNODES | +| CONNS | ID | NOTNULL | STABLE | WAL | +| COPY | IF | NOW | STABLES | WHERE | diff --git a/docs-cn/12-taos-sql/_category_.yml b/docs-cn/12-taos-sql/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..62290997ece68ce1a61d391c3976e338033c0dd1 --- /dev/null +++ b/docs-cn/12-taos-sql/_category_.yml @@ -0,0 +1 @@ +label: SQL 手册 diff --git a/docs-cn/12-taos-sql/index.md b/docs-cn/12-taos-sql/index.md new file mode 100644 index 0000000000000000000000000000000000000000..269bc1d2b5ddfa25c42652d8f639bfe2fb1d42e5 --- /dev/null +++ b/docs-cn/12-taos-sql/index.md @@ -0,0 +1,40 @@ +--- +title: TAOS SQL +description: "TAOS SQL 支持的语法规则、主要查询功能、支持的 SQL 查询函数，以及常用技巧等内容" +--- + +本文档说明 TAOS SQL 支持的语法规则、主要查询功能、支持的 SQL 查询函数，以及常用技巧等内容。阅读本文档需要读者具有基本的 SQL 语言的基础。 + +TAOS SQL 是用户对 TDengine 进行数据写入和查询的主要工具。TAOS SQL 为了便于用户快速上手，在一定程度上提供与标准 SQL 类似的风格和模式。严格意义上，TAOS SQL 并不是也不试图提供标准的 SQL 语法。此外，由于 TDengine 针对的时序性结构化数据不提供删除功能，因此在 TAO SQL 中不提供数据删除的相关功能。 + +TAOS SQL 不支持关键字的缩写，例如 DESCRIBE 不能缩写为 DESC。 + +本章节 SQL 语法遵循如下约定： + +- <\> 里的内容是用户需要输入的，但不要输入 <\> 本身 +- \[ \] 表示内容为可选项，但不能输入 [] 本身 +- | 表示多选一，选择其中一个即可，但不能输入 | 本身 +- … 表示前面的项可重复多个 + +为更好地说明 SQL 语法的规则及其特点，本文假设存在一个数据集。以智能电表(meters)为例，假设每个智能电表采集电流、电压、相位三个量。其建模如下： + +``` +taos> DESCRIBE meters; + Field | Type | Length | Note | +================================================================================= + ts | TIMESTAMP | 8 | | + current | FLOAT | 4 | | + voltage | INT | 4 | | + phase | FLOAT | 4 | | + location | BINARY | 64 | TAG | + groupid | INT | 4 | TAG | +``` + +数据集包含 4 个智能电表的数据，按照 TDengine 的建模规则，对应 4 个子表，其名称分别是 d1001, d1002, d1003, d1004。 + +```mdx-code-block +import DocCardList from '@theme/DocCardList'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + + +``` \ No newline at end of file diff --git a/docs-cn/13-operation/01-pkg-install.md b/docs-cn/13-operation/01-pkg-install.md new file mode 100644 index 0000000000000000000000000000000000000000..92b04a42ec9b3a80187d4482f465190288038f8d --- /dev/null +++ b/docs-cn/13-operation/01-pkg-install.md @@ -0,0 +1,283 @@ +--- +title: 安装和卸载 +description: 安装、卸载、启动、停止和升级 +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +TDengine 开源版本提供 deb 和 rpm 格式安装包，用户可以根据自己的运行环境选择合适的安装包。其中 deb 支持 Debian/Ubuntu 及衍生系统，rpm 支持 CentOS/RHEL/SUSE 及衍生系统。同时我们也为企业用户提供 tar.gz 格式安装包。 + +## 安装 + + + + +1、从官网下载获得 deb 安装包，例如 TDengine-server-2.4.0.7-Linux-x64.deb； +2、进入到 TDengine-server-2.4.0.7-Linux-x64.deb 安装包所在目录，执行如下的安装命令： + +``` +$ sudo dpkg -i TDengine-server-2.4.0.7-Linux-x64.deb +(Reading database ... 137504 files and directories currently installed.) +Preparing to unpack TDengine-server-2.4.0.7-Linux-x64.deb ... +TDengine is removed successfully! +Unpacking tdengine (2.4.0.7) over (2.4.0.7) ... +Setting up tdengine (2.4.0.7) ... +Start to install TDengine... + +System hostname is: ubuntu-1804 + +Enter FQDN:port (like h1.taosdata.com:6030) of an existing TDengine cluster node to join +OR leave it blank to build one: + +Enter your email address for priority support or enter empty to skip: +Created symlink /etc/systemd/system/multi-user.target.wants/taosd.service → /etc/systemd/system/taosd.service. + +To configure TDengine : edit /etc/taos/taos.cfg +To start TDengine : sudo systemctl start taosd +To access TDengine : taos -h ubuntu-1804 to login into TDengine server + + +TDengine is installed successfully! +``` + + + + + +1、从官网下载获得 rpm 安装包，例如 TDengine-server-2.4.0.7-Linux-x64.rpm； +2、进入到 TDengine-server-2.4.0.7-Linux-x64.rpm 安装包所在目录，执行如下的安装命令： + +``` +$ sudo rpm -ivh TDengine-server-2.4.0.7-Linux-x64.rpm +Preparing... ################################# [100%] +Updating / installing... + 1:tdengine-2.4.0.7-3 ################################# [100%] +Start to install TDengine... + +System hostname is: centos7 + +Enter FQDN:port (like h1.taosdata.com:6030) of an existing TDengine cluster node to join +OR leave it blank to build one: + +Enter your email address for priority support or enter empty to skip: + +Created symlink from /etc/systemd/system/multi-user.target.wants/taosd.service to /etc/systemd/system/taosd.service. + +To configure TDengine : edit /etc/taos/taos.cfg +To start TDengine : sudo systemctl start taosd +To access TDengine : taos -h centos7 to login into TDengine server + + +TDengine is installed successfully! +``` + + + + + +1、从官网下载获得 tar.gz 安装包，例如 TDengine-server-2.4.0.7-Linux-x64.tar.gz； +2、进入到 TDengine-server-2.4.0.7-Linux-x64.tar.gz 安装包所在目录，先解压文件后，进入子目录，执行其中的 install.sh 安装脚本： + +``` +$ tar xvzf TDengine-enterprise-server-2.4.0.7-Linux-x64.tar.gz +TDengine-enterprise-server-2.4.0.7/ +TDengine-enterprise-server-2.4.0.7/driver/ +TDengine-enterprise-server-2.4.0.7/driver/vercomp.txt +TDengine-enterprise-server-2.4.0.7/driver/libtaos.so.2.4.0.7 +TDengine-enterprise-server-2.4.0.7/install.sh +TDengine-enterprise-server-2.4.0.7/examples/ +... + +$ ll +total 43816 +drwxrwxr-x 3 ubuntu ubuntu 4096 Feb 22 09:31 ./ +drwxr-xr-x 20 ubuntu ubuntu 4096 Feb 22 09:30 ../ +drwxrwxr-x 4 ubuntu ubuntu 4096 Feb 22 09:30 TDengine-enterprise-server-2.4.0.7/ +-rw-rw-r-- 1 ubuntu ubuntu 44852544 Feb 22 09:31 TDengine-enterprise-server-2.4.0.7-Linux-x64.tar.gz + +$ cd TDengine-enterprise-server-2.4.0.7/ + + $ ll +total 40784 +drwxrwxr-x 4 ubuntu ubuntu 4096 Feb 22 09:30 ./ +drwxrwxr-x 3 ubuntu ubuntu 4096 Feb 22 09:31 ../ +drwxrwxr-x 2 ubuntu ubuntu 4096 Feb 22 09:30 driver/ +drwxrwxr-x 10 ubuntu ubuntu 4096 Feb 22 09:30 examples/ +-rwxrwxr-x 1 ubuntu ubuntu 33294 Feb 22 09:30 install.sh* +-rw-rw-r-- 1 ubuntu ubuntu 41704288 Feb 22 09:30 taos.tar.gz + +$ sudo ./install.sh + +Start to update TDengine... +Created symlink /etc/systemd/system/multi-user.target.wants/taosd.service → /etc/systemd/system/taosd.service. +Nginx for TDengine is updated successfully! + +To configure TDengine : edit /etc/taos/taos.cfg +To configure Taos Adapter (if has) : edit /etc/taos/taosadapter.toml +To start TDengine : sudo systemctl start taosd +To access TDengine : use taos -h ubuntu-1804 in shell OR from http://127.0.0.1:6060 + +TDengine is updated successfully! +Install taoskeeper as a standalone service +taoskeeper is installed, enable it by `systemctl enable taoskeeper` +``` + +:::info +install.sh 安装脚本在执行过程中，会通过命令行交互界面询问一些配置信息。如果希望采取无交互安装方式，那么可以用 -e no 参数来执行 install.sh 脚本。运行 `./install.sh -h` 指令可以查看所有参数的详细说明信息。 + +::: + + + + +:::note +当安装第一个节点时，出现 Enter FQDN：提示的时候，不需要输入任何内容。只有当安装第二个或以后更多的节点时，才需要输入已有集群中任何一个可用节点的 FQDN，支持该新节点加入集群。当然也可以不输入，而是在新节点启动前，配置到新节点的配置文件中。 + +::: + +## 卸载 + + + + +卸载命令如下: + +``` +$ sudo dpkg -r tdengine +(Reading database ... 137504 files and directories currently installed.) +Removing tdengine (2.4.0.7) ... +TDengine is removed successfully! + +``` + + + + + +卸载命令如下: + +``` +$ sudo rpm -e tdengine +TDengine is removed successfully! +``` + + + + + +卸载命令如下: + +``` +$ rmtaos +Nginx for TDengine is running, stopping it... +TDengine is removed successfully! + +taosKeeper is removed successfully! +``` + + + + +:::info +- TDengine 提供了多种安装包，但最好不要在一个系统上同时使用 tar.gz 安装包和 deb 或 rpm 安装包。否则会相互影响，导致在使用时出现问题。 + +- 对于 deb 包安装后，如果安装目录被手工误删了部分，出现卸载、或重新安装不能成功。此时，需要清除 TDengine 包的安装信息，执行如下命令： + + ``` + $ sudo rm -f /var/lib/dpkg/info/tdengine* + ``` + +然后再重新进行安装就可以了。 + +- 对于 rpm 包安装后，如果安装目录被手工误删了部分，出现卸载、或重新安装不能成功。此时，需要清除 TDengine 包的安装信息，执行如下命令： + + ``` + $ sudo rpm -e --noscripts tdengine + ``` + +然后再重新进行安装就可以了。 + +::: + +## 安装目录说明 + +TDengine 成功安装后，主安装目录是 /usr/local/taos，目录内容如下： + +``` +$ cd /usr/local/taos +$ ll +$ ll +total 28 +drwxr-xr-x 7 root root 4096 Feb 22 09:34 ./ +drwxr-xr-x 12 root root 4096 Feb 22 09:34 ../ +drwxr-xr-x 2 root root 4096 Feb 22 09:34 bin/ +drwxr-xr-x 2 root root 4096 Feb 22 09:34 cfg/ +lrwxrwxrwx 1 root root 13 Feb 22 09:34 data -> /var/lib/taos/ +drwxr-xr-x 2 root root 4096 Feb 22 09:34 driver/ +drwxr-xr-x 10 root root 4096 Feb 22 09:34 examples/ +drwxr-xr-x 2 root root 4096 Feb 22 09:34 include/ +lrwxrwxrwx 1 root root 13 Feb 22 09:34 log -> /var/log/taos/ +``` + +- 自动生成配置文件目录、数据库目录、日志目录。 +- 配置文件缺省目录：/etc/taos/taos.cfg， 软链接到 /usr/local/taos/cfg/taos.cfg； +- 数据库缺省目录：/var/lib/taos， 软链接到 /usr/local/taos/data； +- 日志缺省目录：/var/log/taos， 软链接到 /usr/local/taos/log； +- /usr/local/taos/bin 目录下的可执行文件，会软链接到 /usr/bin 目录下； +- /usr/local/taos/driver 目录下的动态库文件，会软链接到 /usr/lib 目录下； +- /usr/local/taos/include 目录下的头文件，会软链接到到 /usr/include 目录下； + +## 卸载和更新文件说明 + +卸载安装包的时候，将保留配置文件、数据库文件和日志文件，即 /etc/taos/taos.cfg 、 /var/lib/taos 、 /var/log/taos 。如果用户确认后不需保留，可以手工删除，但一定要慎重，因为删除后，数据将永久丢失，不可以恢复！ + +如果是更新安装，当缺省配置文件（ /etc/taos/taos.cfg ）存在时，仍然使用已有的配置文件，安装包中携带的配置文件修改为 taos.cfg.orig 保存在 /usr/local/taos/cfg/ 目录，可以作为设置配置参数的参考样例；如果不存在配置文件，就使用安装包中自带的配置文件。 + +## 启动和停止 + +TDengine 使用 Linux 系统的 systemd/systemctl/service 来管理系统的启动和、停止、重启操作。TDengine 的服务进程是 taosd，默认情况下 TDengine 在系统启动后将自动启动。DBA 可以通过 systemd/systemctl/service 手动操作停止、启动、重新启动服务。 + +以 systemctl 为例，命令如下： + +- 启动服务进程：`systemctl start taosd` + +- 停止服务进程：`systemctl stop taosd` + +- 重启服务进程：`systemctl restart taosd` + +- 查看服务状态：`systemctl status taosd` + +注意：TDengine 在 2.4 版本之后包含一个独立组件 taosAdapter 需要使用 systemctl 命令管理 taosAdapter 服务的启动和停止。 + +如果服务进程处于活动状态，则 status 指令会显示如下的相关信息： + + ``` + Active: active (running) + ``` + +如果后台服务进程处于停止状态，则 status 指令会显示如下的相关信息： + + ``` + Active: inactive (dead) + ``` + +## 升级 +升级分为两个层面：升级安装包 和 升级运行中的实例。 + +升级安装包请遵循前述安装和卸载的步骤先卸载旧版本再安装新版本。 + +升级运行中的实例则要复杂得多，首先请注意版本号，TDengine 的版本号目前分为四段，如 2.4.0.14 和 2.4.0.16，只有前三段版本号一致（即只有第四段版本号不同）才能把一个运行中的实例进行升级。升级步骤如下： +- 停止数据写入 +- 确保所有数据落盘，即写入时序数据库 +- 停止 TDengine 集群 +- 卸载旧版本并安装新版本 +- 重新启动 TDengine 集群 +- 进行简单的查询操作确认旧数据没有丢失 +- 进行简单的写入操作确认 TDengine 集群可用 +- 重新恢复业务数据的写入 + +:::warning +TDengine 不保证低版本能够兼容高版本的数据，所以任何时候都不推荐降级 + +::: \ No newline at end of file diff --git a/docs-cn/13-operation/02-planning.mdx b/docs-cn/13-operation/02-planning.mdx new file mode 100644 index 0000000000000000000000000000000000000000..954ba7ca00ebdcb10cfcad515292d96127106ff3 --- /dev/null +++ b/docs-cn/13-operation/02-planning.mdx @@ -0,0 +1,81 @@ +--- +sidebar_label: 容量规划 +title: 容量规划 +--- + +使用 TDengine 来搭建一个物联网大数据平台，计算资源、存储资源需要根据业务场景进行规划。下面分别讨论系统运行所需要的内存、CPU 以及硬盘空间。 + +## 内存需求 + +每个 Database 可以创建固定数目的 vgroup，默认与 CPU 核数相同，可通过 maxVgroupsPerDb 配置；vgroup 中的每个副本会是一个 vnode；每个 vnode 会占用固定大小的内存（大小与数据库的配置参数 blocks 和 cache 有关)；每个 Table 会占用与标签总长度有关的内存；此外，系统会有一些固定的内存开销。因此，每个 DB 需要的系统内存可通过如下公式计算： + +``` +Database Memory Size = maxVgroupsPerDb * replica * (blocks * cache + 10MB) + numOfTables * (tagSizePerTable + 0.5KB) +``` + +示例：假设 maxVgroupPerDB 是缺省值 64，cache 是缺省大小 16M, blocks 是缺省值 6，并且一个 DB 中有 10 万张表，单副本，标签总长度是 256 字节，则这个 DB 总的内存需求为：64 \* 1 \* (16 \* 6 + 10) + 100000 \* (0.25 + 0.5) / 1000 = 6792M。 + +在实际的系统运维中，我们通常会更关心 TDengine 服务进程（taosd）会占用的内存量。 + +``` +taosd 内存总量 = vnode 内存 + mnode 内存 + 查询内存 +``` + +其中： + +1. “vnode 内存”指的是集群中所有的 Database 存储分摊到当前 taosd 节点上所占用的内存资源。可以按上文“Database Memory Size”计算公式估算每个 DB 的内存占用量进行加总，再按集群中总共的 TDengine 节点数做平均（如果设置为多副本，则还需要乘以对应的副本倍数）。 +2. “mnode 内存”指的是集群中管理节点所占用的资源。如果一个 taosd 节点上分布有 mnode 管理节点，则内存消耗还需要增加“0.2KB \* 集群中数据表总数”。 +3. “查询内存”指的是服务端处理查询请求时所需要占用的内存。单条查询语句至少会占用“0.2KB \* 查询涉及的数据表总数”的内存量。 + +注意：以上内存估算方法，主要讲解了系统的“必须内存需求”，而不是“内存总数上限”。在实际运行的生产环境中，由于操作系统缓存、资源管理调度等方面的原因，内存规划应当在估算结果的基础上保留一定冗余，以维持系统状态和系统性能的稳定性。并且，生产环境通常会配置系统资源的监控工具，以便及时发现硬件资源的紧缺情况。 + +最后，如果内存充裕，可以考虑加大 Blocks 的配置，这样更多数据将保存在内存里，提高写入和查询速度。 + +### 客户端内存需求 + +客户端应用采用 taosc 客户端驱动连接服务端，会有内存需求的开销。 + +客户端的内存开销主要由写入过程中的 SQL 语句、表的元数据信息缓存、以及结构性开销构成。系统最大容纳的表数量为 N（每个通过超级表创建的表的 meta data 开销约 256 字节），最大并行写入线程数量 T，最大 SQL 语句长度 S（通常是 1 Mbytes）。由此可以进行客户端内存开销的估算（单位 MBytes）： + +``` +M = (T * S * 3 + (N / 4096) + 100) +``` + +举例如下：用户最大并发写入线程数 100，子表数总数 10,000,000，那么客户端的内存最低要求是： + +``` +100 * 3 + (10000000 / 4096) + 100 = 2741 (MBytes) +``` + +即配置 3 GBytes 内存是最低要求。 + +## CPU 需求 + +CPU 的需求取决于如下两方面： + +- **数据插入** TDengine 单核每秒能至少处理一万个插入请求。每个插入请求可以带多条记录，一次插入一条记录与插入 10 条记录，消耗的计算资源差别很小。因此每次插入，条数越大，插入效率越高。如果一个插入请求带 200 条以上记录，单核就能达到每秒插入 100 万条记录的速度。但对前端数据采集的要求越高，因为需要缓存记录，然后一批插入。 +- **查询需求** TDengine 提供高效的查询，但是每个场景的查询差异很大，查询频次变化也很大，难以给出客观数字。需要用户针对自己的场景，写一些查询语句，才能确定。 + +因此仅对数据插入而言，CPU 是可以估算出来的，但查询所耗的计算资源无法估算。在实际运营过程中，不建议 CPU 使用率超过 50%，超过后，需要增加新的节点，以获得更多计算资源。 + +## 存储需求 + +TDengine 相对于通用数据库，有超高的压缩比，在绝大多数场景下，TDengine 的压缩比不会低于 5 倍，有的场合，压缩比可达到 10 倍以上，取决于实际场景的数据特征。压缩前的原始数据大小可通过如下方式计算： + +``` +Raw DataSize = numOfTables * rowSizePerTable * rowsPerTable +``` + +示例：1000 万台智能电表，每台电表每 15 分钟采集一次数据，每次采集的数据 128 字节，那么一年的原始数据量是：10000000 \* 128 \* 24 \* 60 / 15 \* 365 = 44.8512T。TDengine 大概需要消耗 44.851 / 5 = 8.97024T 空间。 + +用户可以通过参数 keep，设置数据在磁盘中的最大保存时长。为进一步减少存储成本，TDengine 还提供多级存储，最冷的数据可以存放在最廉价的存储介质上，应用的访问不用做任何调整，只是读取速度降低了。 + +为提高速度，可以配置多块硬盘，这样可以并发写入或读取数据。需要提醒的是，TDengine 采取多副本的方式提供数据的高可靠，因此不再需要采用昂贵的磁盘阵列。 + +## 物理机或虚拟机台数 + +根据上面的内存、CPU、存储的预估，就可以知道整个系统需要多少核、多少内存、多少存储空间。如果数据副本数不为 1，总需求量需要再乘以副本数。 + +因为 TDengine 具有很好的水平扩展能力，根据总量，再根据单个物理机或虚拟机的资源，就可以轻松决定需要购置多少台物理机或虚拟机了。 + +**立即计算 CPU、内存、存储，请参见：[资源估算方法](https://www.taosdata.com/config/config.html)。** diff --git a/docs-cn/13-operation/03-tolerance.md b/docs-cn/13-operation/03-tolerance.md new file mode 100644 index 0000000000000000000000000000000000000000..2c466819621adc10423c452328714c81e6f6f966 --- /dev/null +++ b/docs-cn/13-operation/03-tolerance.md @@ -0,0 +1,28 @@ +--- +title: 容错和灾备 +--- + +## 容错 + +TDengine 支持**WAL**（Write Ahead Log）机制，实现数据的容错能力，保证数据的高可用。 + +TDengine 接收到应用的请求数据包时，先将请求的原始数据包写入数据库日志文件，等数据成功写入数据库数据文件后，再删除相应的 WAL。这样保证了 TDengine 能够在断电等因素导致的服务重启时从数据库日志文件中恢复数据，避免数据的丢失。 + +涉及的系统配置参数有两个： + +- walLevel：WAL 级别，0：不写 WAL; 1：写 WAL, 但不执行 fsync; 2：写 WAL, 而且执行 fsync。 +- fsync：当 walLevel 设置为 2 时，执行 fsync 的周期。设置为 0，表示每次写入，立即执行 fsync。 + +如果要 100%的保证数据不丢失，需要将 walLevel 设置为 2，fsync 设置为 0。这时写入速度将会下降。但如果应用侧启动的写数据的线程数达到一定的数量(超过 50)，那么写入数据的性能也会很不错，只会比 fsync 设置为 3000 毫秒下降 30%左右。 + +## 灾备 + +TDengine 的集群通过多个副本的机制，来提供系统的高可用性，实现灾备能力。 + +TDengine 集群是由 mnode 负责管理的，为保证 mnode 的高可靠，可以配置多个 mnode 副本，副本数由系统配置参数 numOfMnodes 决定，为了支持高可靠，需要设置大于 1。为保证元数据的强一致性，mnode 副本之间通过同步方式进行数据复制，保证了元数据的强一致性。 + +TDengine 集群中的时序数据的副本数是与数据库关联的，一个集群里可以有多个数据库，每个数据库可以配置不同的副本数。创建数据库时，通过参数 replica 指定副本数。为了支持高可靠，需要设置副本数大于 1。 + +TDengine 集群的节点数必须大于等于副本数，否则创建表时将报错。 + +当 TDengine 集群中的节点部署在不同的物理机上，并设置多个副本数时，就实现了系统的高可靠性，无需再使用其他软件或工具。TDengine 企业版还可以将副本部署在不同机房，从而实现异地容灾。 diff --git a/docs-cn/13-operation/06-admin.md b/docs-cn/13-operation/06-admin.md new file mode 100644 index 0000000000000000000000000000000000000000..7934d31eafb774fb45e1902bee29e8b518d152d6 --- /dev/null +++ b/docs-cn/13-operation/06-admin.md @@ -0,0 +1,42 @@ +--- +title: 用户管理 +--- + +系统管理员可以在 CLI 界面里添加、删除用户，也可以修改密码。CLI 里 SQL 语法如下： + +```sql +CREATE USER PASS <'password'>; +``` + +创建用户，并指定用户名和密码，密码需要用单引号引起来，单引号为英文半角 + +```sql +DROP USER ; +``` + +删除用户，限 root 用户使用 + +```sql +ALTER USER PASS <'password'>; +``` + +修改用户密码，为避免被转换为小写，密码需要用单引号引用，单引号为英文半角 + +```sql +ALTER USER PRIVILEGE ; +``` + +修改用户权限为：write 或 read，不需要添加单引号 + +说明：系统内共有 super/write/read 三种权限级别，但目前不允许通过 alter 指令把 super 权限赋予用户。 + +```sql +SHOW USERS; +``` + +显示所有用户 + +:::note +SQL 语法中，< >表示需要用户输入的部分，但请不要输入< >本身。 + +::: diff --git a/docs-cn/13-operation/07-import.md b/docs-cn/13-operation/07-import.md new file mode 100644 index 0000000000000000000000000000000000000000..7dee05720d4c3446181e8e0d81a5c27e35300ba8 --- /dev/null +++ b/docs-cn/13-operation/07-import.md @@ -0,0 +1,61 @@ +--- +title: 数据导入 +--- + +TDengine 提供多种方便的数据导入功能，一种按脚本文件导入，一种按数据文件导入，一种是 taosdump 工具导入本身导出的文件。 + +## 按脚本文件导入 + +TDengine 的 shell 支持 source filename 命令，用于批量运行文件中的 SQL 语句。用户可将建库、建表、写数据等 SQL 命令写在同一个文件中，每条命令单独一行，在 shell 中运行 source 命令，即可按顺序批量运行文件中的 SQL 语句。以‘#’开头的 SQL 语句被认为是注释，shell 将自动忽略。 + +## 按数据文件导入 + +TDengine 也支持在 shell 对已存在的表从 CSV 文件中进行数据导入。CSV 文件只属于一张表且 CSV 文件中的数据格式需与要导入表的结构相同，在导入的时候，其语法如下： + +```sql +insert into tb1 file 'path/data.csv'; +``` + +:::note +注意：如果 CSV 文件首行存在描述信息，请手动删除后再导入。如某列为空，填 NULL，无引号。\*\* + +::: + +例如，现在存在一个子表 d1001, 其表结构如下： + +```sql +taos> DESCRIBE d1001 + Field | Type | Length | Note | +================================================================================= + ts | TIMESTAMP | 8 | | + current | FLOAT | 4 | | + voltage | INT | 4 | | + phase | FLOAT | 4 | | + location | BINARY | 64 | TAG | + groupid | INT | 4 | TAG | +``` + +要导入的 data.csv 的格式如下： + +```csv +'2018-10-04 06:38:05.000',10.30000,219,0.31000 +'2018-10-05 06:38:15.000',12.60000,218,0.33000 +'2018-10-06 06:38:16.800',13.30000,221,0.32000 +'2018-10-07 06:38:05.000',13.30000,219,0.33000 +'2018-10-08 06:38:05.000',14.30000,219,0.34000 +'2018-10-09 06:38:05.000',15.30000,219,0.35000 +'2018-10-10 06:38:05.000',16.30000,219,0.31000 +'2018-10-11 06:38:05.000',17.30000,219,0.32000 +'2018-10-12 06:38:05.000',18.30000,219,0.31000 +``` + +那么可以用如下命令导入数据： + +```sql +taos> insert into d1001 file '~/data.csv'; +Query OK, 9 row(s) affected (0.004763s) +``` + +## taosdump 工具导入 + +TDengine 提供了方便的数据库导入导出工具 taosdump。用户可以将 taosdump 从一个系统导出的数据，导入到其他系统中。具体使用方法，请参见：[TDengine 数据备份工具: taosdump](/reference/taosdump)。 diff --git a/docs-cn/13-operation/08-export.md b/docs-cn/13-operation/08-export.md new file mode 100644 index 0000000000000000000000000000000000000000..042ecc7ba29f976d50bbca1e3155bd03b2ae7ccc --- /dev/null +++ b/docs-cn/13-operation/08-export.md @@ -0,0 +1,20 @@ +--- +title: 数据导出 +--- + +为方便数据导出，TDengine 提供了两种导出方式，分别是按表导出和用 taosdump 导出。 + +## 按表导出 CSV 文件 + +如果用户需要导出一个表或一个 STable 中的数据，可在 taos shell 中运行： + +```sql +select * from >> data.csv; +``` + +这样，表 tb_name 中的数据就会按照 CSV 格式导出到文件 data.csv 中。 + +## 用 taosdump 导出数据 + +利用 taosdump，用户可以根据需要选择导出所有数据库、一个数据库或者数据库中的一张表，所有数据或一时间段的数据，甚至仅仅表的定义。具体使用方法，请参见： +[TDengine 数据备份工具: taosdump](/reference/taosdump)。 diff --git a/docs-cn/13-operation/09-status.md b/docs-cn/13-operation/09-status.md new file mode 100644 index 0000000000000000000000000000000000000000..e7ae78bace91f6dab06591340965ba04efdd5edb --- /dev/null +++ b/docs-cn/13-operation/09-status.md @@ -0,0 +1,53 @@ +--- +title: 系统连接、任务查询管理 +--- + +系统管理员可以从 CLI 查询系统的连接、正在进行的查询、流式计算，并且可以关闭连接、停止正在进行的查询和流式计算。 + +## 显示数据库的连接 + +```sql +SHOW CONNECTIONS; +``` + +其结果中的一列显示 ip:port, 为连接的 IP 地址和端口号。 + +## 强制关闭数据库连接 + +```sql +KILL CONNECTION ; +``` + +其中的 connection-id 是 SHOW CONNECTIONS 中显示的第一列的数字。 + +## 显示数据查询 + +```sql +SHOW QUERIES; +``` + +其中第一列显示的以冒号隔开的两个数字为 query-id，为发起该 query 应用连接的 connection-id 和查询次数。 + +## 强制关闭数据查询 + +```sql +KILL QUERY ; +``` + +其中 query-id 是 SHOW QUERIES 中显示的 connection-id:query-no 字串，如“105:2”，拷贝粘贴即可。 + +## 显示连续查询 + +```sql +SHOW STREAMS; +``` + +其中第一列显示的以冒号隔开的两个数字为 stream-id, 为启动该 stream 应用连接的 connection-id 和发起 stream 的次数。 + +## 强制关闭连续查询 + +```sql +KILL STREAM ; +``` + +其中的 stream-id 是 SHOW STREAMS 中显示的 connection-id:stream-no 字串，如 103:2，拷贝粘贴即可。 diff --git a/docs-cn/13-operation/10-monitor.md b/docs-cn/13-operation/10-monitor.md new file mode 100644 index 0000000000000000000000000000000000000000..e30be775fb5c337b2a621bea92d3af31a2cb5cc0 --- /dev/null +++ b/docs-cn/13-operation/10-monitor.md @@ -0,0 +1,54 @@ +--- +title: 系统监控 +--- + +TDengine 启动后，会自动创建一个监测数据库 log，并自动将服务器的 CPU、内存、硬盘空间、带宽、请求数、磁盘读写速度、慢查询等信息定时写入该数据库。TDengine 还将重要的系统操作（比如登录、创建、删除数据库等）日志以及各种错误报警信息记录下来存放在 log 库里。系统管理员可以从 CLI 直接查看这个数据库，也可以在 WEB 通过图形化界面查看这些监测信息。 + +这些监测信息的采集缺省是打开的，但可以修改配置文件里的选项 monitor 将其关闭或打开。 + +## TDinsight - 使用监控数据库 + Grafana 对 TDengine 进行监控的解决方案 + +从 2.3.3.0 开始，监控数据库将提供更多的监控项，您可以从 [TDinsight Grafana Dashboard](https://grafana.com/grafana/dashboards/15167) 了解如何使用 TDinsight 方案对 TDengine 进行监控。 + +我们提供了一个自动化脚本 `TDinsight.sh` 对 TDinsight 进行部署。 + +下载 `TDinsight.sh`： + +```bash +wget https://github.com/taosdata/grafanaplugin/raw/master/dashboards/TDinsight.sh +chmod +x TDinsight.sh +``` + +准备： + +1. TDengine Server 信息： + + - TDengine RESTful 服务：对本地而言，可以是 `http://localhost:6041`，使用参数 `-a`。 + - TDengine 用户名和密码，使用 `-u` `-p` 参数设置。 + +2. Grafana 告警通知 + + - 使用已经存在的 Grafana Notification Channel `uid`，参数 `-E`。该参数可以使用 `curl -u admin:admin localhost:3000/api/alert-notifications |jq` 来获取。 + + ```bash + sudo ./TDinsight.sh -a http://localhost:6041 -u root -p taosdata -E + ``` + + - 使用 TDengine 数据源插件内置的阿里云短信告警通知，使用 `-s` 启用之，并设置如下参数： + + 1. 阿里云短信服务 Key ID，参数 `-I` + 2. 阿里云短信服务 Key Secret，参数 `K` + 3. 阿里云短信服务签名，参数 `-S` + 4. 短信通知模板号，参数 `-C` + 5. 短信通知模板输入参数，JSON 格式，参数 `-T`，如 `{"alarm_level":"%s","time":"%s","name":"%s","content":"%s"}` + 6. 逗号分隔的通知手机列表，参数 `-B` + + ```bash + sudo ./TDinsight.sh -a http://localhost:6041 -u root -p taosdata -s \ + -I XXXXXXX -K XXXXXXXX -S taosdata -C SMS_1111111 -B 18900000000 \ + -T '{"alarm_level":"%s","time":"%s","name":"%s","content":"%s"}' + ``` + +运行程序并重启 Grafana 服务，打开面板：`http://localhost:3000/d/tdinsight`。 + +更多使用场景和限制请参考[TDinsight](/reference/tdinsight/) 文档。 diff --git a/docs-cn/13-operation/11-optimize.md b/docs-cn/13-operation/11-optimize.md new file mode 100644 index 0000000000000000000000000000000000000000..1ca9e8c44492a5882613a0b55d959d7abca8b5f6 --- /dev/null +++ b/docs-cn/13-operation/11-optimize.md @@ -0,0 +1,100 @@ +--- +title: 性能优化 +--- + +因数据行 [update](/train-faq/faq/#update)、表删除、数据过期等原因，TDengine 的磁盘存储文件有可能出现数据碎片，影响查询操作的性能表现。从 2.1.3.0 版本开始，新增 SQL 指令 COMPACT 来启动碎片重整过程： + +```sql +COMPACT VNODES IN (vg_id1, vg_id2, ...) +``` + +COMPACT 命令对指定的一个或多个 VGroup 启动碎片重整，系统会通过任务队列尽快安排重整操作的具体执行。COMPACT 指令所需的 VGroup id，可以通过 `SHOW VGROUPS;` 指令的输出结果获取；而且在 `SHOW VGROUPS;` 中会有一个 compacting 列，值为 2 时表示对应的 VGroup 处于排队等待进行重整的状态，值为 1 时表示正在进行碎片重整，为 0 时则表示并没有处于重整状态（未要求进行重整或已经完成重整）。 + +需要注意的是，碎片重整操作会大幅消耗磁盘 I/O。因此在重整进行期间，有可能会影响节点的写入和查询性能，甚至在极端情况下导致短时间的阻写。 + +## 存储参数优化 + +不同应用场景的数据往往具有不同的数据特征，比如保留天数、副本数、采集频次、记录大小、采集点的数量、压缩等都可完全不同。为获得在存储上的最高效率，TDengine 提供如下存储相关的系统配置参数（既可以作为 create database 指令的参数，也可以写在 taos.cfg 配置文件中用来设定创建新数据库时所采用的默认值）： + +| # | 配置参数名称 | 单位 | 含义 | **取值范围** | **缺省值** | +| --- | ------------ | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ---------- | +| 1 | days | 天 | 一个数据文件存储数据的时间跨度 | 1-3650 | 10 | +| 2 | keep | 天 | （可通过 alter database 修改）数据库中数据保留的天数。 | 1-36500 | 3650 | +| 3 | cache | MB | 内存块的大小 | 1-128 | 16 | +| 4 | blocks | | （可通过 alter database 修改）每个 VNODE（TSDB）中有多少个 cache 大小的内存块。因此一个 VNODE 使用的内存大小粗略为（cache \* blocks）。 | 3-10000 | 6 | +| 5 | quorum | | （可通过 alter database 修改）多副本环境下指令执行的确认数要求 | 1-2 | 1 | +| 6 | minRows | | 文件块中记录的最小条数 | 10-1000 | 100 | +| 7 | maxRows | | 文件块中记录的最大条数 | 200-10000 | 4096 | +| 8 | comp | | （可通过 alter database 修改）文件压缩标志位 | 0：关闭，1:一阶段压缩，2:两阶段压缩 | 2 | +| 9 | walLevel | | （作为 database 的参数时名为 wal；在 taos.cfg 中作为参数时需要写作 walLevel）WAL 级别 | 1：写 WAL，但不执行 fsync；2：写 WAL, 而且执行 fsync | 1 | +| 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 | | 是否允许数据更新（从 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： + +```sql + CREATE DATABASE demo DAYS 10 CACHE 32 BLOCKS 8 REPLICA 3 UPDATE 1; +``` + +该 SQL 创建了一个库 demo, 每个数据文件存储 10 天数据，内存块为 32 兆字节，每个 VNODE 占用 8 个内存块，副本数为 3，允许更新，而其他参数与系统配置完全一致。 + +一个数据库创建成功后，仅部分参数可以修改并实时生效，其余参数不能修改： + +| **参数名** | **能否修改** | **范围** | **修改语法示例** | +| ----------- | ------------ | ---------------------------------------------------------- | -------------------------------------- | +| name | | | | +| create time | | | | +| ntables | | | | +| vgroups | | | | +| replica | **YES** | 在线 dnode 数目为:
1：1-1；
2：1-2；
\>=3：1-3 | ALTER DATABASE REPLICA _n_ | +| quorum | **YES** | 1-2 | ALTER DATABASE QUORUM _n_ | +| days | | | | +| keep | **YES** | days-365000 | ALTER DATABASE KEEP _n_ | +| cache | | | | +| blocks | **YES** | 3-1000 | ALTER DATABASE BLOCKS _n_ | +| minrows | | | | +| maxrows | | | | +| wal | | | | +| fsync | | | | +| comp | **YES** | 0-2 | ALTER DATABASE COMP _n_ | +| precision | | | | +| status | | | | +| update | | | | +| cachelast | **YES** | 0 \| 1 \| 2 \| 3 | ALTER DATABASE CACHELAST _n_ | + +**说明：**在 2.1.3.0 版本之前，通过 ALTER DATABASE 语句修改这些参数后，需要重启服务器才能生效。 + +TDengine 集群中加入一个新的 dnode 时，涉及集群相关的一些参数必须与已有集群的配置相同，否则不能成功加入到集群中。会进行校验的参数如下： + +- numOfMnodes：系统中管理节点个数。默认值：3。（2.0 版本从 2.0.20.11 开始、2.1 及以上版本从 2.1.6.0 开始，numOfMnodes 默认值改为 1。） +- mnodeEqualVnodeNum: 一个 mnode 等同于 vnode 消耗的个数。默认值：4。 +- offlineThreshold: dnode 离线阈值，超过该时间将导致该 dnode 从集群中删除。单位为秒，默认值：86400\*10（即 10 天）。 +- statusInterval: dnode 向 mnode 报告状态时长。单位为秒，默认值：1。 +- maxTablesPerVnode: 每个 vnode 中能够创建的最大表个数。默认值：1000000。 +- maxVgroupsPerDb: 每个数据库中能够使用的最大 vgroup 个数。 +- arbitrator: 系统中裁决器的 endpoint，缺省为空。 +- timezone、locale、charset 的配置见客户端配置。（2.0.20.0 及以上的版本里，集群中加入新节点已不要求 locale 和 charset 参数取值一致） +- balance：是否启用负载均衡。0：否，1：是。默认值：1。 +- flowctrl：是否启用非阻塞流控。0：否，1：是。默认值：1。 +- slaveQuery：是否启用 slave vnode 参与查询。0：否，1：是。默认值：1。 +- adjustMaster：是否启用 vnode master 负载均衡。0：否，1：是。默认值：1。 + +为方便调试，可通过 SQL 语句临时调整每个 dnode 的日志配置，系统重启后会失效： + +```sql +ALTER DNODE +``` + +- dnode_id: 可以通过 SQL 语句"SHOW DNODES"命令获取 +- config: 要调整的日志参数，在如下列表中取值 + > resetlog 截断旧日志文件，创建一个新日志文件 + > debugFlag < 131 | 135 | 143 > 设置 debugFlag 为 131、135 或者 143 + +例如： + +``` +alter dnode 1 debugFlag 135; +``` diff --git a/docs-cn/13-operation/17-diagnose.md b/docs-cn/13-operation/17-diagnose.md new file mode 100644 index 0000000000000000000000000000000000000000..e2a2ef035a33a295b206c77ec08edf8f7842671f --- /dev/null +++ b/docs-cn/13-operation/17-diagnose.md @@ -0,0 +1,131 @@ +--- +title: 诊断及其他 +--- + +## 网络连接诊断 + +当出现客户端应用无法访问服务端时，需要确认客户端与服务端之间网络的各端口连通情况，以便有针对性地排除故障。 + +目前网络连接诊断支持在：Linux 与 Linux，Linux 与 Windows 之间进行诊断测试。 + +诊断步骤： + +1. 如拟诊断的端口范围与服务器 taosd 实例的端口范围相同，须先停掉 taosd 实例 +2. 服务端命令行输入：`taos -n server -P -l ` 以服务端身份启动对端口 port 为基准端口的监听 +3. 客户端命令行输入：`taos -n client -h -P -l ` 以客户端身份启动对指定的服务器、指定的端口发送测试包 + +-l ： 测试网络包的大小（单位：字节）。最小值是 11、最大值是 64000，默认值为 1000。 +注：两端命令行中指定的测试包长度必须一致，否则测试显示失败。 + +服务端运行正常的话会输出以下信息： + +```bash +# taos -n server -P 6000 +12/21 14:50:13.522509 0x7f536f455200 UTL work as server, host:172.27.0.7 startPort:6000 endPort:6011 pkgLen:1000 + +12/21 14:50:13.522659 0x7f5352242700 UTL TCP server at port:6000 is listening +12/21 14:50:13.522727 0x7f5351240700 UTL TCP server at port:6001 is listening +... +... +... +12/21 14:50:13.523954 0x7f5342fed700 UTL TCP server at port:6011 is listening +12/21 14:50:13.523989 0x7f53437ee700 UTL UDP server at port:6010 is listening +12/21 14:50:13.524019 0x7f53427ec700 UTL UDP server at port:6011 is listening +12/21 14:50:22.192849 0x7f5352242700 UTL TCP: read:1000 bytes from 172.27.0.8 at 6000 +12/21 14:50:22.192993 0x7f5352242700 UTL TCP: write:1000 bytes to 172.27.0.8 at 6000 +12/21 14:50:22.237082 0x7f5351a41700 UTL UDP: recv:1000 bytes from 172.27.0.8 at 6000 +12/21 14:50:22.237203 0x7f5351a41700 UTL UDP: send:1000 bytes to 172.27.0.8 at 6000 +12/21 14:50:22.237450 0x7f5351240700 UTL TCP: read:1000 bytes from 172.27.0.8 at 6001 +12/21 14:50:22.237576 0x7f5351240700 UTL TCP: write:1000 bytes to 172.27.0.8 at 6001 +12/21 14:50:22.281038 0x7f5350a3f700 UTL UDP: recv:1000 bytes from 172.27.0.8 at 6001 +12/21 14:50:22.281141 0x7f5350a3f700 UTL UDP: send:1000 bytes to 172.27.0.8 at 6001 +... +... +... +12/21 14:50:22.677443 0x7f5342fed700 UTL TCP: read:1000 bytes from 172.27.0.8 at 6011 +12/21 14:50:22.677576 0x7f5342fed700 UTL TCP: write:1000 bytes to 172.27.0.8 at 6011 +12/21 14:50:22.721144 0x7f53427ec700 UTL UDP: recv:1000 bytes from 172.27.0.8 at 6011 +12/21 14:50:22.721261 0x7f53427ec700 UTL UDP: send:1000 bytes to 172.27.0.8 at 6011 +``` + +客户端运行正常会输出以下信息： + +```bash +# taos -n client -h 172.27.0.7 -P 6000 +12/21 14:50:22.192434 0x7fc95d859200 UTL work as client, host:172.27.0.7 startPort:6000 endPort:6011 pkgLen:1000 + +12/21 14:50:22.192472 0x7fc95d859200 UTL server ip:172.27.0.7 is resolved from host:172.27.0.7 +12/21 14:50:22.236869 0x7fc95d859200 UTL successed to test TCP port:6000 +12/21 14:50:22.237215 0x7fc95d859200 UTL successed to test UDP port:6000 +... +... +... +12/21 14:50:22.676891 0x7fc95d859200 UTL successed to test TCP port:6010 +12/21 14:50:22.677240 0x7fc95d859200 UTL successed to test UDP port:6010 +12/21 14:50:22.720893 0x7fc95d859200 UTL successed to test TCP port:6011 +12/21 14:50:22.721274 0x7fc95d859200 UTL successed to test UDP port:6011 +``` + +仔细阅读打印出来的错误信息，可以帮助管理员找到原因，以解决问题。 + +## 启动状态及 RPC 诊断 + +`taos -n startup -h ` + +判断 taosd 服务端是否成功启动，是数据库管理员经常遇到的一种情形。特别当若干台服务器组成集群时，判断每个服务端实例是否成功启动就会是一个重要问题。除检索 taosd 服务端日志文件进行问题定位、分析外，还可以通过 `taos -n startup -h ` 来诊断一个 taosd 进程的启动状态。 + +针对多台服务器组成的集群，当服务启动过程耗时较长时，可通过该命令行来诊断每台服务器的 taosd 实例的启动状态，以准确定位问题。 + +`taos -n rpc -h ` + +该命令用来诊断已经启动的 taosd 实例的端口是否可正常访问。如果 taosd 程序异常或者失去响应，可以通过 `taos -n rpc -h ` 来发起一个与指定 fqdn 的 rpc 通信，看看 taosd 是否能收到，以此来判定是网络问题还是 taosd 程序异常问题。 + +## sync 及 arbitrator 诊断 + +``` +taos -n sync -P 6040 -h +taos -n sync -P 6042 -h +``` + +用来诊断 sync 端口是否工作正常，判断服务端 sync 模块是否成功工作。另外，-P 6042 用来诊断 arbitrator 是否配置正常，判断指定服务器的 arbitrator 是否能正常工作。 + +## 网络速度诊断 + +`taos -n speed -h -P 6030 -N 10 -l 10000000 -S TCP` + +从 2.2.0.0 版本开始，taos 工具新提供了一个网络速度诊断的模式，可以对一个正在运行中的 taosd 实例或者 `taos -n server` 方式模拟的一个服务端实例，以非压缩传输的方式进行网络测速。这个模式下可供调整的参数如下： + +-n：设为“speed”时，表示对网络速度进行诊断。 +-h：所要连接的服务端的 FQDN 或 ip 地址。如果不设置这一项，会使用本机 taos.cfg 文件中 FQDN 参数的设置作为默认值。 +-P：所连接服务端的网络端口。默认值为 6030。 +-N：诊断过程中使用的网络包总数。最小值是 1、最大值是 10000，默认值为 100。 +-l：单个网络包的大小（单位：字节）。最小值是 1024、最大值是 1024 `*` 1024 `*` 1024，默认值为 1024。 +-S：网络封包的类型。可以是 TCP 或 UDP，默认值为 TCP。 + +## FQDN 解析速度诊断 + +`taos -n fqdn -h ` + +从 2.2.0.0 版本开始，taos 工具新提供了一个 FQDN 解析速度的诊断模式，可以对一个目标 FQDN 地址尝试解析，并记录解析过程中所消耗的时间。这个模式下可供调整的参数如下： + +-n：设为“fqdn”时，表示对 FQDN 解析进行诊断。 +-h：所要解析的目标 FQDN 地址。如果不设置这一项，会使用本机 taos.cfg 文件中 FQDN 参数的设置作为默认值。 + +## 服务端日志 + +taosd 服务端日志文件标志位 debugflag 默认为 131，在 debug 时往往需要将其提升到 135 或 143 。 + +一旦设定为 135 或 143，日志文件增长很快，特别是写入、查询请求量较大时，增长速度惊人。如合并保存日志，很容易把日志内的关键信息（如配置信息、错误信息等）冲掉。为此，服务端将重要信息日志与其他日志分开存放： + +- taosinfo 存放重要信息日志, 包括：INFO/ERROR/WARNING 级别的日志信息。不记录 DEBUG、TRACE 级别的日志。 +- taosdlog 服务器端生成的日志，记录 taosinfo 中全部信息外，还根据设置的日志输出级别，记录 DEBUG（日志级别 135）、TRACE（日志级别是 143）。 + +## 客户端日志 + +每个独立运行的客户端（一个进程）生成一个独立的客户端日志，其命名方式采用 taoslog+<序号> 的方式命名。文件标志位 debugflag 默认为 131，在 debug 时往往需要将其提升到 135 或 143 。 + +- taoslog 客户端（driver）生成的日志，默认记录客户端 INFO/ERROR/WARNING 级别日志，还根据设置的日志输出级别，记录 DEBUG（日志级别 135）、TRACE（日志级别是 143）。 + +其中，日志文件最大长度由 numOfLogLines 来进行配置，一个 taosd 实例最多保留两个文件。 + +taosd 服务端日志采用异步落盘写入机制，优点是可以避免硬盘写入压力太大，对性能造成很大影响。缺点是，在极端情况下，存在少量日志行数丢失的可能。 diff --git a/docs-cn/13-operation/_category_.yml b/docs-cn/13-operation/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..315839970c47e4ac76f6f19f65331a44fd93229e --- /dev/null +++ b/docs-cn/13-operation/_category_.yml @@ -0,0 +1 @@ +label: 运维指南 diff --git a/docs-cn/13-operation/index.md b/docs-cn/13-operation/index.md new file mode 100644 index 0000000000000000000000000000000000000000..bc06fbdc138ee593c1206475095ef48d32493b37 --- /dev/null +++ b/docs-cn/13-operation/index.md @@ -0,0 +1,12 @@ +--- +title: 运维指南 +--- + +本章节主要为系统管理员写的，覆盖安装、下载、数据导入、导出、运行系统的监测、用户管理、连接管理等内容，同时介绍根据业务量，如何做容量规划，系统运行一段时间后，如何做系统优化。 + +```mdx-code-block +import DocCardList from '@theme/DocCardList'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + + +``` diff --git a/docs-cn/14-reference/02-rest-api/02-rest-api.mdx b/docs-cn/14-reference/02-rest-api/02-rest-api.mdx new file mode 100644 index 0000000000000000000000000000000000000000..c7680ab3e9e109dbb328711f62881283241444fb --- /dev/null +++ b/docs-cn/14-reference/02-rest-api/02-rest-api.mdx @@ -0,0 +1,307 @@ +--- +title: REST API +--- + +为支持各种不同类型平台的开发，TDengine 提供符合 REST 设计标准的 API，即 REST API。为最大程度降低学习成本，不同于其他数据库 REST API 的设计方法，TDengine 直接通过 HTTP POST 请求 BODY 中包含的 SQL 语句来操作数据库，仅需要一个 URL。REST 连接器的使用参见[视频教程](https://www.taosdata.com/blog/2020/11/11/1965.html)。 + +:::note +与原生连接器的一个区别是，RESTful 接口是无状态的，因此 `USE db_name` 指令没有效果，所有对表名、超级表名的引用都需要指定数据库名前缀。从 2.2.0.0 版本开始，支持在 RESTful URL 中指定 db_name，这时如果 SQL 语句中没有指定数据库名前缀的话，会使用 URL 中指定的这个 db_name。从 2.4.0.0 版本开始，RESTful 默认由 taosAdapter 提供，要求必须在 URL 中指定 db_name。 +::: + +## 安装 + +RESTful 接口不依赖于任何 TDengine 的库，因此客户端不需要安装任何 TDengine 的库，只要客户端的开发语言支持 HTTP 协议即可。 + +## 验证 + +在已经安装 TDengine 服务器端的情况下，可以按照如下方式进行验证。 + +下面以 Ubuntu 环境中使用 curl 工具（确认已经安装）来验证 RESTful 接口的正常。 + +下面示例是列出所有的数据库，请把 h1.taosdata.com 和 6041（缺省值）替换为实际运行的 TDengine 服务 FQDN 和端口号： + +```html +curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'show databases;' h1.taosdata.com:6041/rest/sql +``` + +返回值结果如下表示验证通过： + +```json +{ + "status": "succ", + "head": [ + "name", + "created_time", + "ntables", + "vgroups", + "replica", + "quorum", + "days", + "keep1,keep2,keep(D)", + "cache(MB)", + "blocks", + "minrows", + "maxrows", + "wallevel", + "fsync", + "comp", + "precision", + "status" + ], + "data": [ + [ + "log", + "2020-09-02 17:23:00.039", + 4, + 1, + 1, + 1, + 10, + "30,30,30", + 1, + 3, + 100, + 4096, + 1, + 3000, + 2, + "us", + "ready" + ] + ], + "rows": 1 +} +``` + +## HTTP 请求格式 + +``` +http://:/rest/sql/[db_name] +``` + +参数说明： + +- fqnd: 集群中的任一台主机 FQDN 或 IP 地址 +- port: 配置文件中 httpPort 配置项，缺省为 6041 +- db_name: 可选参数，指定本次所执行的 SQL 语句的默认数据库库名。（从 2.2.0.0 版本开始支持） + +例如：`http://h1.taos.com:6041/rest/sql/test` 是指向地址为 `h1.taos.com:6041` 的 URL，并将默认使用的数据库库名设置为 `test`。 + +HTTP 请求的 Header 里需带有身份认证信息，TDengine 支持 Basic 认证与自定义认证两种机制，后续版本将提供标准安全的数字签名机制来做身份验证。 + +- 自定义身份认证信息如下所示（token 稍后介绍） + + ``` + Authorization: Taosd + ``` + +- Basic 身份认证信息如下所示 + + ``` + Authorization: Basic + ``` + +HTTP 请求的 BODY 里就是一个完整的 SQL 语句，SQL 语句中的数据表应提供数据库前缀，例如 db_name.tb_name。如果表名不带数据库前缀，又没有在 URL 中指定数据库名的话，系统会返回错误。因为 HTTP 模块只是一个简单的转发，没有当前 DB 的概念。 + +使用 `curl` 通过自定义身份认证方式来发起一个 HTTP Request，语法如下： + +```bash +curl -H 'Authorization: Basic ' -d '' :/rest/sql/[db_name] +``` + +或者 + +```bash +curl -u username:password -d '' :/rest/sql/[db_name] +``` + +其中，`TOKEN` 为 `{username}:{password}` 经过 Base64 编码之后的字符串，例如 `root:taosdata` 编码后为 `cm9vdDp0YW9zZGF0YQ==` + +## HTTP 返回格式 + +返回值为 JSON 格式，如下: + +```json +{ + "status": "succ", + "head": ["ts","current", …], + "column_meta": [["ts",9,8],["current",6,4], …], + "data": [ + ["2018-10-03 14:38:05.000", 10.3, …], + ["2018-10-03 14:38:15.000", 12.6, …] + ], + "rows": 2 +} +``` + +说明： + +- status: 告知操作结果是成功还是失败。 +- head: 表的定义，如果不返回结果集，则仅有一列 “affected_rows”。（从 2.0.17.0 版本开始，建议不要依赖 head 返回值来判断数据列类型，而推荐使用 column_meta。在后续版本中，有可能会从返回值中去掉 head 这一项。） +- column_meta: 从 2.0.17.0 版本开始，返回值中增加这一项来说明 data 里每一列的数据类型。具体每个列会用三个值来说明，分别为：列名、列类型、类型长度。例如`["current",6,4]`表示列名为“current”；列类型为 6，也即 float 类型；类型长度为 4，也即对应 4 个字节表示的 float。如果列类型为 binary 或 nchar，则类型长度表示该列最多可以保存的内容长度，而不是本次返回值中的具体数据长度。当列类型是 nchar 的时候，其类型长度表示可以保存的 unicode 字符数量，而不是 bytes。 +- data: 具体返回的数据，一行一行的呈现，如果不返回结果集，那么就仅有 [[affected_rows]]。data 中每一行的数据列顺序，与 column_meta 中描述数据列的顺序完全一致。 +- rows: 表明总共多少行数据。 + +column_meta 中的列类型说明： + +- 1：BOOL +- 2：TINYINT +- 3：SMALLINT +- 4：INT +- 5：BIGINT +- 6：FLOAT +- 7：DOUBLE +- 8：BINARY +- 9：TIMESTAMP +- 10：NCHAR + +## 自定义授权码 + +HTTP 请求中需要带有授权码 ``，用于身份识别。授权码通常由管理员提供，可简单的通过发送 `HTTP GET` 请求来获取授权码，操作如下： + +```bash +curl http://:/rest/login// +``` + +其中，`fqdn` 是 TDengine 数据库的 FQDN 或 IP 地址，`port` 是 TDengine 服务的端口号，`username` 为数据库用户名，`password` 为数据库密码，返回值为 JSON 格式，各字段含义如下： + +- status：请求结果的标志位 + +- code：返回值代码 + +- desc：授权码 + +获取授权码示例： + +```bash +curl http://192.168.0.1:6041/rest/login/root/taosdata +``` + +返回值： + +```json +{ + "status": "succ", + "code": 0, + "desc": "/KfeAzX/f9na8qdtNZmtONryp201ma04bEl8LcvLUd7a8qdtNZmtONryp201ma04" +} +``` + +## 使用示例 + +- 在 demo 库里查询表 d1001 的所有记录： + + ```bash + curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.d1001' 192.168.0.1:6041/rest/sql + ``` + + 返回值： + + ```json + { + "status": "succ", + "head": ["ts", "current", "voltage", "phase"], + "column_meta": [ + ["ts", 9, 8], + ["current", 6, 4], + ["voltage", 4, 4], + ["phase", 6, 4] + ], + "data": [ + ["2018-10-03 14:38:05.000", 10.3, 219, 0.31], + ["2018-10-03 14:38:15.000", 12.6, 218, 0.33] + ], + "rows": 2 + } + ``` + +- 创建库 demo： + + ```bash + curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'create database demo' 192.168.0.1:6041/rest/sql + ``` + + 返回值： + + ```json + { + "status": "succ", + "head": ["affected_rows"], + "column_meta": [["affected_rows", 4, 4]], + "data": [[1]], + "rows": 1 + } + ``` + +## 其他用法 + +### 结果集采用 Unix 时间戳 + +HTTP 请求 URL 采用 `/rest/sqlt` 时，返回结果集的时间戳将采用 Unix 时间戳格式表示，例如 + +```bash +curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.d1001' 192.168.0.1:6041/rest/sqlt +``` + +返回结果： + +```json +{ + "status": "succ", + "head": ["ts", "current", "voltage", "phase"], + "column_meta": [ + ["ts", 9, 8], + ["current", 6, 4], + ["voltage", 4, 4], + ["phase", 6, 4] + ], + "data": [ + [1538548685000, 10.3, 219, 0.31], + [1538548695000, 12.6, 218, 0.33] + ], + "rows": 2 +} +``` + +### 结果集采用 UTC 时间字符串 + +HTTP 请求 URL 采用 `/rest/sqlutc` 时，返回结果集的时间戳将采用 UTC 时间字符串表示，例如 + +```bash + curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.t1' 192.168.0.1:6041/rest/sqlutc +``` + +返回值： + +```json +{ + "status": "succ", + "head": ["ts", "current", "voltage", "phase"], + "column_meta": [ + ["ts", 9, 8], + ["current", 6, 4], + ["voltage", 4, 4], + ["phase", 6, 4] + ], + "data": [ + ["2018-10-03T14:38:05.000+0800", 10.3, 219, 0.31], + ["2018-10-03T14:38:15.000+0800", 12.6, 218, 0.33] + ], + "rows": 2 +} +``` + +## 重要配置项 + +下面仅列出一些与 RESTful 接口有关的配置参数，其他系统参数请看配置文件里的说明。 + +- 对外提供 RESTful 服务的端口号，默认绑定到 6041（实际取值是 serverPort + 11，因此可以通过修改 serverPort 参数的设置来修改）。 +- httpMaxThreads: 启动的线程数量，默认为 2（2.0.17.0 版本开始，默认值改为 CPU 核数的一半向下取整）。 +- restfulRowLimit: 返回结果集（JSON 格式）的最大条数，默认值为 10240。 +- httpEnableCompress: 是否支持压缩，默认不支持，目前 TDengine 仅支持 gzip 压缩格式。 +- httpDebugFlag: 日志开关，默认 131。131：仅错误和报警信息，135：调试信息，143：非常详细的调试信息。 +- httpDbNameMandatory: 是否必须在 RESTful URL 中指定默认的数据库名。默认为 0，即关闭此检查。如果设置为 1，那么每个 RESTful URL 中都必须设置一个默认数据库名，否则无论此时执行的 SQL 语句是否需要指定数据库，都会返回一个执行错误，拒绝执行此 SQL 语句。 + +:::note +如果使用 taosd 提供的 REST API, 那么以上配置需要写在 taosd 的配置文件 taos.cfg 中。如果使用 taosAdapter 提供的 REST API, 那么需要参考 taosAdapter [对应的配置方法](/reference/taosadapter/)。 +::: diff --git a/docs-cn/14-reference/02-rest-api/_category_.yml b/docs-cn/14-reference/02-rest-api/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..57a20d8458e937f60c41806be4392ebb2d13e0f7 --- /dev/null +++ b/docs-cn/14-reference/02-rest-api/_category_.yml @@ -0,0 +1 @@ +label: REST API diff --git a/docs-cn/14-reference/03-connector/03-connector.mdx b/docs-cn/14-reference/03-connector/03-connector.mdx new file mode 100644 index 0000000000000000000000000000000000000000..c0e714f148a7821e070be38a5484484fdd747e9a --- /dev/null +++ b/docs-cn/14-reference/03-connector/03-connector.mdx @@ -0,0 +1,117 @@ +--- +title: 连接器 +--- + +TDengine 提供了丰富的应用程序开发接口，为了便于用户快速开发自己的应用，TDengine 支持了多种编程语言的连接器，其中官方连接器包括支持 C/C++、Java、Python、Go、Node.js、C# 和 Rust 的连接器。这些连接器支持使用原生接口（taosc）和 REST 接口（部分语言暂不支持）连接 TDengine 集群。社区开发者也贡献了多个非官方连接器，例如 ADO.NET 连接器、Lua 连接器和 PHP 连接器。 + +![image-connector](/img/connector.png) + +## 支持的平台 + +目前 TDengine 的原生接口连接器可支持的平台包括：X64/X86/ARM64/ARM32/MIPS/Alpha 等硬件平台，以及 Linux/Win64/Win32 等开发环境。对照矩阵如下： + +| **CPU** | **OS** | **JDBC** | **Python** | **Go** | **Node.js** | **C#** | **Rust** | C/C++ | +| -------------- | --------- | -------- | ---------- | ------ | ----------- | ------ | -------- | ----- | +| **X86 64bit** | **Linux** | ● | ● | ● | ● | ● | ● | ● | +| **X86 64bit** | **Win64** | ● | ● | ● | ● | ● | ● | ● | +| **X86 64bit** | **Win32** | ● | ● | ● | ● | ○ | ○ | ● | +| **X86 32bit** | **Win32** | ○ | ○ | ○ | ○ | ○ | ○ | ● | +| **ARM64** | **Linux** | ● | ● | ● | ● | ○ | ○ | ● | +| **ARM32** | **Linux** | ● | ● | ● | ● | ○ | ○ | ● | +| **MIPS 龙芯** | **Linux** | ○ | ○ | ○ | ○ | ○ | ○ | ○ | +| **Alpha 申威** | **Linux** | ○ | ○ | -- | -- | -- | -- | ○ | +| **X86 海光** | **Linux** | ○ | ○ | ○ | -- | -- | -- | ○ | + +其中 ● 表示官方测试验证通过，○ 表示非官方测试验证通过，-- 表示未经验证。 + +使用 REST 连接由于不依赖客户端驱动可以支持更广泛的操作系统。 + +## 版本支持 + +TDengine 版本更新往往会增加新的功能特性，列表中的连接器版本为连接器最佳适配版本。 + +| **TDengine 版本** | **Java** | **Python** | **Go** | **C#** | **Node.js** | **Rust** | +| --------------------- | -------- | ---------- | ------------ | ------------- | --------------- | -------- | +| **2.4.0.14 及以上** | 2.0.38 | 当前版本 | develop 分支 | 1.0.2 - 1.0.6 | 2.0.10 - 2.0.12 | 当前版本 | +| **2.4.0.6 及以上** | 2.0.37 | 当前版本 | develop 分支 | 1.0.2 - 1.0.6 | 2.0.10 - 2.0.12 | 当前版本 | +| **2.4.0.4 - 2.4.0.5** | 2.0.37 | 当前版本 | develop 分支 | 1.0.2 - 1.0.6 | 2.0.10 - 2.0.12 | 当前版本 | +| **2.2.x.x ** | 2.0.36 | 当前版本 | master 分支 | n/a | 2.0.7 - 2.0.9 | 当前版本 | +| **2.0.x.x ** | 2.0.34 | 当前版本 | master 分支 | n/a | 2.0.1 - 2.0.6 | 当前版本 | + +## 功能特性 + +连接器对 TDengine 功能特性的支持对照如下： + +### 使用原生接口（taosc） + +| **功能特性** | **Java** | **Python** | **Go** | **C#** | **Node.js** | **Rust** | +| -------------- | -------- | ---------- | ------ | ------ | ----------- | -------- | +| **连接管理** | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 | +| **普通查询** | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 | +| **连续查询** | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 | +| **参数绑定** | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 | +| **订阅功能** | 支持 | 支持 | 支持 | 支持 | 支持 | 暂不支持 | +| **Schemaless** | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 | +| **DataFrame** | 不支持 | 支持 | 不支持 | 不支持 | 不支持 | 不支持 | + +:::info +由于不同编程语言数据库框架规范不同，并不意味着所有 C/C++ 接口都需要对应封装支持。 +::: + +### 使用 REST 接口 + +| **功能特性** | **Java** | **Python** | **Go** | **C#（暂不支持）** | **Node.js** | **Rust** | +| ------------------------------ | -------- | ---------- | -------- | ------------------ | ----------- | -------- | +| **连接管理** | 支持 | 支持 | 支持 | N/A | 支持 | 支持 | +| **普通查询** | 支持 | 支持 | 支持 | N/A | 支持 | 支持 | +| **连续查询** | 支持 | 支持 | 支持 | N/A | 支持 | 支持 | +| **参数绑定** | 不支持 | 不支持 | 不支持 | N/A | 不支持 | 不支持 | +| **订阅功能** | 不支持 | 不支持 | 不支持 | N/A | 不支持 | 不支持 | +| **Schemaless** | 暂不支持 | 暂不支持 | 暂不支持 | N/A | 暂不支持 | 暂不支持 | +| **批量拉取（基于 WebSocket）** | 支持 | 暂不支持 | 暂不支持 | N/A | 暂不支持 | 暂不支持 | +| **DataFrame** | 不支持 | 支持 | 不支持 | N/A | 不支持 | 不支持 | + +:::warning + +- 无论选用何种编程语言的连接器，2.0 及以上版本的 TDengine 推荐数据库应用的每个线程都建立一个独立的连接，或基于线程建立连接池，以避免连接内的“USE statement”状态量在线程之间相互干扰（但连接的查询和写入操作都是线程安全的）。 + +::: + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import InstallOnWindows from "./_linux_install.mdx"; +import InstallOnLinux from "./_windows_install.mdx"; +import VerifyWindows from "./_verify_windows.mdx"; +import VerifyLinux from "./_verify_linux.mdx"; + +## 安装客户端驱动 + +:::info +只有在没有安装 TDengine 服务端软件的系统上使用原生接口连接器才需要安装客户端驱动。 + +::: + +### 安装步骤 + + + + + + + + + + +### 安装验证 + +以上安装和配置完成后，并确认 TDengine 服务已经正常启动运行，此时可以执行 TDengine CLI 工具进行登录。 + + + + + + + + + + diff --git a/docs-cn/14-reference/03-connector/_category_.yml b/docs-cn/14-reference/03-connector/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..abd3f666f3b93697fde59931ffd7b10a0308b6b7 --- /dev/null +++ b/docs-cn/14-reference/03-connector/_category_.yml @@ -0,0 +1 @@ +label: "连接器" \ No newline at end of file diff --git a/docs-cn/14-reference/03-connector/_linux_install.mdx b/docs-cn/14-reference/03-connector/_linux_install.mdx new file mode 100644 index 0000000000000000000000000000000000000000..eb7f68328809fdf75ce11a3bddb324b59bfe8dcb --- /dev/null +++ b/docs-cn/14-reference/03-connector/_linux_install.mdx @@ -0,0 +1,30 @@ +import PkgList from "/components/PkgList"; + +1. 下载客户端安装包 + + + + [所有下载](https://www.taosdata.com/cn/all-downloads/) + +2. 解压缩软件包 + + 将软件包放置在当前用户可读写的任意目录下，然后执行下面的命令：`tar -xzvf TDengine-client-VERSION.tar.gz` + 其中 VERSION 需要替换为实际版本的字符串。 +3. 执行安装脚本 + + 解压软件包之后，会在解压目录下看到以下文件(目录)： + - _ install_client.sh_：安装脚本，用于应用驱动程序 + - _ taos.tar.gz_：应用驱动安装包 + - _ driver_：TDengine 应用驱动 driver + - _examples_: 各种编程语言的示例程序(c/C#/go/JDBC/MATLAB/python/R) + 运行 install_client.sh 进行安装。 +4. 配置 taos.cfg + + 编辑 `taos.cfg` 文件（默认路径/etc/taos/taos.cfg），将 `firstEP` 修改为 TDengine 服务器的 End Point，例如：`h1.tdengine.com:6030` + +:::tip + +1. 如本机没有部署 TDengine 服务，仅安装了应用驱动，则 `taos.cfg` 中仅需配置 `firstEP`，无需在本机配置 `FQDN`。 +2. 为防止与服务器端连接时出现“Unable to resolve FQDN”错误，建议确认本机的 `/etc/hosts` 文件已经配置了服务器正确的 FQDN 值，或配置好了 DNS 服务。 + +::: diff --git a/docs-cn/14-reference/03-connector/_preparition.mdx b/docs-cn/14-reference/03-connector/_preparition.mdx new file mode 100644 index 0000000000000000000000000000000000000000..87538ebfd8c60507aec90ee86e427d85979dbc4a --- /dev/null +++ b/docs-cn/14-reference/03-connector/_preparition.mdx @@ -0,0 +1,10 @@ +- 已安装客户端驱动（使用原生连接必须安装，使用 REST 连接无需安装） + +:::info + +由于 TDengine 的客户端驱动使用 C 语言编写，使用原生连接时需要加载系统对应安装在本地的客户端驱动共享库文件，通常包含在 TDengine 安装包。TDengine Linux 服务端安装包附带了 TDengine 客户端，也可以单独安装 [Linux 客户端](/get-started/) 。在 Windows 环境开发时需要安装 TDengine 对应的 [Windows 客户端](https://www.taosdata.com/cn/all-downloads/#TDengine-Windows-Client) 。 + +- libtaos.so: 在 Linux 系统中成功安装 TDengine 后，依赖的 Linux 版客户端驱动 libtaos.so 文件会被自动拷贝至 /usr/lib/libtaos.so，该目录包含在 Linux 自动扫描路径上，无需单独指定。 +- taos.dll: 在 Windows 系统中安装完客户端之后，依赖的 Windows 版客户端驱动 taos.dll 文件会自动拷贝到系统默认搜索路径 C:/Windows/System32 下，同样无需要单独指定。 + +::: diff --git a/docs-cn/14-reference/03-connector/_verify_linux.mdx b/docs-cn/14-reference/03-connector/_verify_linux.mdx new file mode 100644 index 0000000000000000000000000000000000000000..fcb8aae6ae27cdcec58e000c4ab2e8a7ec6d9a5e --- /dev/null +++ b/docs-cn/14-reference/03-connector/_verify_linux.mdx @@ -0,0 +1,14 @@ +在 Linux shell 下直接执行 `taos` 连接到 TDengine 服务，进入到 TDengine CLI 界面，示例如下： + +```text +$ taos +Welcome to the TDengine shell from Linux, Client Version:2.0.5.0 +Copyright (c) 2017 by TAOS Data, Inc. All rights reserved. +taos> show databases; +name | created_time | ntables | vgroups | replica | quorum | days | keep1,keep2,keep(D) | cache(MB)| blocks | minrows | maxrows | wallevel | fsync | comp | precision | status | +========================================================================================================================================================================================================================= +test | 2020-10-14 10:35:48.617 | 10 | 1 | 1 | 1 | 2 | 3650,3650,3650 | 16| 6 | 100 | 4096 | 1 | 3000 | 2 | ms | ready | +log | 2020-10-12 09:08:21.651 | 4 | 1 | 1 | 1 | 10 | 30,30,30 | 1| 3 | 100 | 4096 | 1 | 3000 | 2 | us | ready | +Query OK, 2 row(s) in set (0.001198s) +taos> +``` diff --git a/docs-cn/14-reference/03-connector/_verify_windows.mdx b/docs-cn/14-reference/03-connector/_verify_windows.mdx new file mode 100644 index 0000000000000000000000000000000000000000..87c9fbd024f2c80b88434d47f35d919ed1ea77b2 --- /dev/null +++ b/docs-cn/14-reference/03-connector/_verify_windows.mdx @@ -0,0 +1,14 @@ +在 cmd 下进入到 C:\TDengine 目录下直接执行 `taos.exe`，连接到 TDengine 服务，进入到 TDengine CLI 界面，示例如下： + +```text + C:\TDengine>taos + Welcome to the TDengine shell from Linux, Client Version:2.0.5.0 + Copyright (c) 2017 by TAOS Data, Inc. All rights reserved. + taos> show databases; + name | created_time | ntables | vgroups | replica | quorum | days | keep1,keep2,keep(D) | cache(MB) | blocks | minrows | maxrows | wallevel | fsync | comp | precision | status | + =================================================================================================================================================================================================================================================================== + test | 2020-10-14 10:35:48.617 | 10 | 1 | 1 | 1 | 2 | 3650,3650,3650 | 16 | 6 | 100 | 4096 | 1 | 3000 | 2 | ms | ready | + log | 2020-10-12 09:08:21.651 | 4 | 1 | 1 | 1 | 10 | 30,30,30 | 1 | 3 | 100 | 4096 | 1 | 3000 | 2 | us | ready | + Query OK, 2 row(s) in set (0.045000s) + taos> +``` diff --git a/docs-cn/14-reference/03-connector/_windows_install.mdx b/docs-cn/14-reference/03-connector/_windows_install.mdx new file mode 100644 index 0000000000000000000000000000000000000000..755f96b2d728621de5752ce752e5d249cda0f6d9 --- /dev/null +++ b/docs-cn/14-reference/03-connector/_windows_install.mdx @@ -0,0 +1,31 @@ +import PkgList from "/components/PkgList"; + +1. 下载客户端安装包 + + + + [所有下载](https://www.taosdata.com/cn/all-downloads/) + +2. 执行安装程序，按提示选择默认值，完成安装 +3. 安装路径 + + 默认安装路径为：C:\TDengine，其中包括以下文件(目录)： + + - _taos.exe_：TDengine CLI 命令行程序 + - _cfg_ : 配置文件目录 + - _driver_: 应用驱动动态链接库 + - _examples_: 示例程序 bash/C/C#/go/JDBC/Python/Node.js + - _include_: 头文件 + - _log_ : 日志文件 + - _unins000.exe_: 卸载程序 + +4. 配置 taos.cfg + + 编辑 taos.cfg 文件（默认路径 C:\TDengine\cfg\taos.cfg），将 firstEP 修改为 TDengine 服务器的 End Point，例如：`h1.tdengine.com:6030`。 + +:::tip + +1. 如利用 FQDN 连接服务器，必须确认本机网络环境 DNS 已配置好，或在 hosts 文件中添加 FQDN 寻址记录, 如编辑 C:\Windows\system32\drivers\etc\hosts，添加类似如下的记录：`192.168.1.99 h1.taos.com` +2. 卸载：运行 unins000.exe 可卸载 TDengine 应用驱动。 + +::: diff --git a/docs-cn/14-reference/03-connector/cpp.mdx b/docs-cn/14-reference/03-connector/cpp.mdx new file mode 100644 index 0000000000000000000000000000000000000000..aba1d6c717dfec9228f38e89f90cbf1be0021045 --- /dev/null +++ b/docs-cn/14-reference/03-connector/cpp.mdx @@ -0,0 +1,451 @@ +--- +sidebar_position: 1 +sidebar_label: C/C++ +title: C/C++ Connector +--- + +C/C++ 开发人员可以使用 TDengine 的客户端驱动，即 C/C++连接器 （以下都用 TDengine 客户端驱动表示），开发自己的应用来连接 TDengine 集群完成数据存储、查询以及其他功能。TDengine 客户端驱动的 API 类似于 MySQL 的 C API。应用程序使用时，需要包含 TDengine 头文件 _taos.h_，里面列出了提供的 API 的函数原型；应用程序还要链接到所在平台上对应的动态库。 + +```c +#include +``` + +TDengine 服务端或客户端安装后，`taos.h` 位于： + +- Linux：`/usr/local/taos/include` +- Windows：`C:\TDengine\include` + +TDengine 客户端驱动的动态库位于： + +- Linux: `/usr/local/taos/driver/libtaos.so` +- Windows: `C:\TDengine\taos.dll` + +## 支持的平台 + +请参考[支持的平台列表](/reference/connector#支持的平台) + +## 支持的版本 + +TDengine 客户端驱动的版本号与 TDengine 服务端的版本号是一一对应的强对应关系，建议使用与 TDengine 服务端完全相同的客户端驱动。虽然低版本的客户端驱动在前三段版本号一致（即仅第四段版本号不同）的情况下也能够与高版本的服务端相兼容，但这并非推荐用法。强烈不建议使用高版本的客户端驱动访问低版本的服务端。 + +## 安装步骤 + +TDengine 客户端驱动的安装请参考 [安装指南](/reference/connector#安装步骤) + +## 建立连接 + +使用客户端驱动访问 TDengine 集群的基本过程为：建立连接、查询和写入、关闭连接、清除资源。 + +下面为建立连接的示例代码，其中省略了查询和写入部分，展示了如何建立连接、关闭连接以及清除资源。 + +```c + TAOS *taos = taos_connect("localhost:6030", "root", "taosdata", NULL, 0); + if (taos == NULL) { + printf("failed to connect to server, reason:%s\n", "null taos" /*taos_errstr(taos)*/); + exit(1); + } + + /* put your code here for read and write */ + + taos_close(taos); + taos_cleanup(); +``` + +在上面的示例代码中， `taos_connect()` 建立到客户端程序所在主机的 6030 端口的连接，`taos_close()`关闭当前连接，`taos_cleanup()`清除客户端驱动所申请和使用的资源。 + +:::note + +- 如未特别说明，当 API 的返回值是整数时，_0_ 代表成功，其它是代表失败原因的错误码，当返回值是指针时， _NULL_ 表示失败。 +- 所有的错误码以及对应的原因描述在 `taoserror.h` 文件中。 + +::: + +## 示例程序 + +本节展示了使用客户端驱动访问 TDengine 集群的常见访问方式的示例代码。 + +### 同步查询示例 + +
+同步查询 + +```c +{{#include examples/c/demo.c}} +``` + +
+ +### 异步查询示例 + +
+异步查询 + +```c +{{#include examples/c/asyncdemo.c}} +``` + +
+ +### 参数绑定示例 + +
+参数绑定 + +```c +{{#include examples/c/prepare.c}} +``` + +
+ +### 无模式写入示例 + +
+无模式写入 + +```c +{{#include examples/c/schemaless.c}} +``` + +
+ +### 订阅和消费示例 + +
+订阅和消费 + +```c +{{#include examples/c/subscribe.c}} +``` + +
+ +:::info +更多示例代码及下载请见 [GitHub](https://github.com/taosdata/TDengine/tree/develop/examples/c)。 +也可以在安装目录下的 `examples/c` 路径下找到。 该目录下有 makefile，在 Linux 环境下，直接执行 make 就可以编译得到执行文件。 +**提示：**在 ARM 环境下编译时，请将 makefile 中的 `-msse4.2` 去掉，这个选项只有在 x64/x86 硬件平台上才能支持。 + +::: + +## API 参考 + +以下分别介绍 TDengine 客户端驱动的基础 API、同步 API、异步 API、订阅 API 和无模式写入 API。 + +### 基础 API + +基础 API 用于完成创建数据库连接等工作，为其它 API 的执行提供运行时环境。 + +- `void taos_init()` + + 初始化运行环境。如果没有主动调用该 API，那么调用 `taos_connect()` 时驱动将自动调用该 API，故程序一般无需手动调用。 + +- `void taos_cleanup()` + + 清理运行环境，应用退出前应调用。 + +- `int taos_options(TSDB_OPTION option, const void * arg, ...)` + + 设置客户端选项，目前支持区域设置（`TSDB_OPTION_LOCALE`）、字符集设置（`TSDB_OPTION_CHARSET`）、时区设置（`TSDB_OPTION_TIMEZONE`）、配置文件路径设置（`TSDB_OPTION_CONFIGDIR`）。区域设置、字符集、时区默认为操作系统当前设置。 + +- `char *taos_get_client_info()` + + 获取客户端版本信息。 + +- `TAOS *taos_connect(const char *host, const char *user, const char *pass, const char *db, int port)` + + 创建数据库连接，初始化连接上下文。其中需要用户提供的参数包含： + + - host：TDengine 集群中任一节点的 FQDN + - user：用户名 + - pass：密码 + - db： 数据库名字，如果用户没有提供，也可以正常连接，用户可以通过该连接创建新的数据库，如果用户提供了数据库名字，则说明该数据库用户已经创建好，缺省使用该数据库 + - port：taosd 程序监听的端口 + + 返回值为空表示失败。应用程序需要保存返回的参数，以便后续使用。 + + :::info + 同一进程可以根据不同的 host/port 连接多个 TDengine 集群 + + ::: + +- `char *taos_get_server_info(TAOS *taos)` + + 获取服务端版本信息。 + +- `int taos_select_db(TAOS *taos, const char *db)` + + 将当前的缺省数据库设置为 `db`。 + +- `void taos_close(TAOS *taos)` + + 关闭连接，其中`taos`是 `taos_connect()` 返回的句柄。 + +### 同步查询 API + +本小节介绍 API 均属于同步接口。应用调用后，会阻塞等待响应，直到获得返回结果或错误信息。 + +- `TAOS_RES* taos_query(TAOS *taos, const char *sql)` + + 执行 SQL 语句，可以是 DQL、DML 或 DDL 语句。 其中的 `taos` 参数是通过 `taos_connect()` 获得的句柄。不能通过返回值是否是 `NULL` 来判断执行结果是否失败，而是需要用 `taos_errno()` 函数解析结果集中的错误代码来进行判断。 + +- `int taos_result_precision(TAOS_RES *res)` + + 返回结果集时间戳字段的精度，`0` 代表毫秒，`1` 代表微秒，`2` 代表纳秒。 + +- `TAOS_ROW taos_fetch_row(TAOS_RES *res)` + + 按行获取查询结果集中的数据。 + +- `int taos_fetch_block(TAOS_RES *res, TAOS_ROW *rows)` + + 批量获取查询结果集中的数据，返回值为获取到的数据的行数。 + +- `int taos_num_fields(TAOS_RES *res)` 和 `int taos_field_count(TAOS_RES *res)` + + 这两个 API 等价，用于获取查询结果集中的列数。 + +- `int* taos_fetch_lengths(TAOS_RES *res)` + + 获取结果集中每个字段的长度。返回值是一个数组，其长度为结果集的列数。 + +- `int taos_affected_rows(TAOS_RES *res)` + + 获取被所执行的 SQL 语句影响的行数。 + +- `TAOS_FIELD *taos_fetch_fields(TAOS_RES *res)` + + 获取查询结果集每列数据的属性（列的名称、列的数据类型、列的长度），与 `taos_num_fileds()` 配合使用，可用来解析 `taos_fetch_row()` 返回的一个元组(一行)的数据。 `TAOS_FIELD` 的结构如下： + +```c +typedef struct taosField { + char name[65]; // column name + uint8_t type; // data type + int16_t bytes; // length, in bytes +} TAOS_FIELD; +``` + +- `void taos_stop_query(TAOS_RES *res)` + + 停止当前查询的执行。 + +- `void taos_free_result(TAOS_RES *res)` + + 释放查询结果集以及相关的资源。查询完成后，务必调用该 API 释放资源，否则可能导致应用内存泄露。但也需注意，释放资源后，如果再调用 `taos_consume()` 等获取查询结果的函数，将导致应用崩溃。 + +- `char *taos_errstr(TAOS_RES *res)` + + 获取最近一次 API 调用失败的原因,返回值为字符串标识的错误提示信息。 + +- `int taos_errno(TAOS_RES *res)` + + 获取最近一次 API 调用失败的原因，返回值为错误代码。 + +:::note +2.0 及以上版本 TDengine 推荐数据库应用的每个线程都建立一个独立的连接，或基于线程建立连接池。而不推荐在应用中将该连接 (TAOS\*) 结构体传递到不同的线程共享使用。基于 TAOS 结构体发出的查询、写入等操作具有多线程安全性，但 “USE statement” 等状态量有可能在线程之间相互干扰。此外，C 语言的连接器可以按照需求动态建立面向数据库的新连接（该过程对用户不可见），同时建议只有在程序最后退出的时候才调用 `taos_close()` 关闭连接。 + +::: + +### 异步查询 API + +TDengine 还提供性能更高的异步 API 处理数据插入、查询操作。在软硬件环境相同的情况下，异步 API 处理数据插入的速度比同步 API 快 2 ～ 4 倍。异步 API 采用非阻塞式的调用方式，在系统真正完成某个具体数据库操作前，立即返回。调用的线程可以去处理其他工作，从而可以提升整个应用的性能。异步 API 在网络延迟严重的情况下，优势尤为突出。 + +异步 API 都需要应用提供相应的回调函数，回调函数参数设置如下：前两个参数都是一致的，第三个参数依不同的 API 而定。第一个参数 param 是应用调用异步 API 时提供给系统的，用于回调时，应用能够找回具体操作的上下文，依具体实现而定。第二个参数是 SQL 操作的结果集，如果为空，比如 insert 操作，表示没有记录返回，如果不为空，比如 select 操作，表示有记录返回。 + +异步 API 对于使用者的要求相对较高，用户可根据具体应用场景选择性使用。下面是两个重要的异步 API： + +- `void taos_query_a(TAOS *taos, const char *sql, void (*fp)(void *param, TAOS_RES *, int code), void *param);` + + 异步执行 SQL 语句。 + + - taos：调用 `taos_connect()` 返回的数据库连接 + - sql：需要执行的 SQL 语句 + - fp：用户定义的回调函数，其第三个参数 `code` 用于指示操作是否成功，`0` 表示成功，负数表示失败（调用 `taos_errstr()` 可获取失败原因）。应用在定义回调函数的时候，主要处理第二个参数 `TAOS_RES *`，该参数是查询返回的结果集 + - param：应用提供一个用于回调的参数 + +- `void taos_fetch_rows_a(TAOS_RES *res, void (*fp)(void *param, TAOS_RES *, int numOfRows), void *param);` + + 批量获取异步查询的结果集，只能与 `taos_query_a()` 配合使用。其中： + + - res：`taos_query_a()` 回调时返回的结果集 + - fp：回调函数。其参数 `param` 是用户可定义的传递给回调函数的参数结构体；`numOfRows` 是获取到的数据的行数（不是整个查询结果集的函数）。 在回调函数中，应用可以通过调用 `taos_fetch_row()` 前向迭代获取批量记录中每一行记录。读完一块内的所有记录后，应用需要在回调函数中继续调用 `taos_fetch_rows_a()` 获取下一批记录进行处理，直到返回的记录数 `numOfRows` 为零（结果返回完成）或记录数为负值（查询出错）。 + +TDengine 的异步 API 均采用非阻塞调用模式。应用程序可以用多线程同时打开多张表，并可以同时对每张打开的表进行查询或者插入操作。需要指出的是，**客户端应用必须确保对同一张表的操作完全串行化**，即对同一个表的插入或查询操作未完成时（未返回时），不能够执行第二个插入或查询操作。 + +### 参数绑定 API + +除了直接调用 `taos_query()` 进行查询，TDengine 也提供了支持参数绑定的 Prepare API，风格与 MySQL 类似，目前也仅支持用问号 `?` 来代表待绑定的参数。 + +从 2.1.1.0 和 2.1.2.0 版本开始，TDengine 大幅改进了参数绑定接口对数据写入（INSERT）场景的支持。这样在通过参数绑定接口写入数据时，就避免了 SQL 语法解析的资源消耗，从而在绝大多数情况下显著提升写入性能。此时的典型操作步骤如下： + +1. 调用 `taos_stmt_init()` 创建参数绑定对象； +2. 调用 `taos_stmt_prepare()` 解析 INSERT 语句； +3. 如果 INSERT 语句中预留了表名但没有预留 TAGS，那么调用 `taos_stmt_set_tbname()` 来设置表名； +4. 如果 INSERT 语句中既预留了表名又预留了 TAGS（例如 INSERT 语句采取的是自动建表的方式），那么调用 `taos_stmt_set_tbname_tags()` 来设置表名和 TAGS 的值； +5. 调用 `taos_stmt_bind_param_batch()` 以多列的方式设置 VALUES 的值，或者调用 `taos_stmt_bind_param()` 以单行的方式设置 VALUES 的值； +6. 调用 `taos_stmt_add_batch()` 把当前绑定的参数加入批处理； +7. 可以重复第 3 ～ 6 步，为批处理加入更多的数据行； +8. 调用 `taos_stmt_execute()` 执行已经准备好的批处理指令； +9. 执行完毕，调用 `taos_stmt_close()` 释放所有资源。 + +说明：如果 `taos_stmt_execute()` 执行成功，假如不需要改变 SQL 语句的话，那么是可以复用 `taos_stmt_prepare()` 的解析结果，直接进行第 3 ～ 6 步绑定新数据的。但如果执行出错，那么并不建议继续在当前的环境上下文下继续工作，而是建议释放资源，然后从 `taos_stmt_init()` 步骤重新开始。 + +接口相关的具体函数如下（也可以参考 [prepare.c](https://github.com/taosdata/TDengine/blob/develop/examples/c/prepare.c) 文件中使用对应函数的方式）： + +- `TAOS_STMT* taos_stmt_init(TAOS *taos)` + + 创建一个 TAOS_STMT 对象用于后续调用。 + +- `int taos_stmt_prepare(TAOS_STMT *stmt, const char *sql, unsigned long length)` + + 解析一条 SQL 语句，将解析结果和参数信息绑定到 stmt 上，如果参数 length 大于 0，将使用此参数作为 SQL 语句的长度，如等于 0，将自动判断 SQL 语句的长度。 + +- `int taos_stmt_bind_param(TAOS_STMT *stmt, TAOS_BIND *bind)` + + 不如 `taos_stmt_bind_param_batch()` 效率高，但可以支持非 INSERT 类型的 SQL 语句。 + 进行参数绑定，bind 指向一个数组（代表所要绑定的一行数据），需保证此数组中的元素数量和顺序与 SQL 语句中的参数完全一致。TAOS_BIND 的使用方法与 MySQL 中的 MYSQL_BIND 类似，具体定义如下： + + ```c + typedef struct TAOS_BIND { + int buffer_type; + void * buffer; + uintptr_t buffer_length; // not in use + uintptr_t * length; + int * is_null; + int is_unsigned; // not in use + int * error; // not in use + } TAOS_BIND; + ``` + +- `int taos_stmt_set_tbname(TAOS_STMT* stmt, const char* name)` + + （2.1.1.0 版本新增，仅支持用于替换 INSERT 语句中的参数值） + 当 SQL 语句中的表名使用了 `?` 占位时，可以使用此函数绑定一个具体的表名。 + +- `int taos_stmt_set_tbname_tags(TAOS_STMT* stmt, const char* name, TAOS_BIND* tags)` + + （2.1.2.0 版本新增，仅支持用于替换 INSERT 语句中的参数值） + 当 SQL 语句中的表名和 TAGS 都使用了 `?` 占位时，可以使用此函数绑定具体的表名和具体的 TAGS 取值。最典型的使用场景是使用了自动建表功能的 INSERT 语句（目前版本不支持指定具体的 TAGS 列）。TAGS 参数中的列数量需要与 SQL 语句中要求的 TAGS 数量完全一致。 + +- `int taos_stmt_bind_param_batch(TAOS_STMT* stmt, TAOS_MULTI_BIND* bind)` + + （2.1.1.0 版本新增，仅支持用于替换 INSERT 语句中的参数值） + 以多列的方式传递待绑定的数据，需要保证这里传递的数据列的顺序、列的数量与 SQL 语句中的 VALUES 参数完全一致。TAOS_MULTI_BIND 的具体定义如下： + + ```c + typedef struct TAOS_MULTI_BIND { + int buffer_type; + void * buffer; + uintptr_t buffer_length; + uintptr_t * length; + char * is_null; + int num; // the number of columns + } TAOS_MULTI_BIND; + ``` + +- `int taos_stmt_add_batch(TAOS_STMT *stmt)` + + 将当前绑定的参数加入批处理中，调用此函数后，可以再次调用 `taos_stmt_bind_param()` 或 `taos_stmt_bind_param_batch()` 绑定新的参数。需要注意，此函数仅支持 INSERT/IMPORT 语句，如果是 SELECT 等其他 SQL 语句，将返回错误。 + +- `int taos_stmt_execute(TAOS_STMT *stmt)` + + 执行准备好的语句。目前，一条语句只能执行一次。 + +- `TAOS_RES* taos_stmt_use_result(TAOS_STMT *stmt)` + + 获取语句的结果集。结果集的使用方式与非参数化调用时一致，使用完成后，应对此结果集调用 `taos_free_result()` 以释放资源。 + +- `int taos_stmt_close(TAOS_STMT *stmt)` + + 执行完毕，释放所有资源。 + +- `char * taos_stmt_errstr(TAOS_STMT *stmt)` + + （2.1.3.0 版本新增） + 用于在其他 STMT API 返回错误（返回错误码或空指针）时获取错误信息。 + +### 无模式（schemaless）写入 API + +除了使用 SQL 方式或者使用参数绑定 API 写入数据外，还可以使用 Schemaless 的方式完成写入。Schemaless 可以免于预先创建超级表/数据子表的数据结构，而是可以直接写入数据，TDengine 系统会根据写入的数据内容自动创建和维护所需要的表结构。Schemaless 的使用方式详见 [Schemaless 写入](/reference/schemaless/) 章节，这里介绍与之配套使用的 C/C++ API。 + +- `TAOS_RES* taos_schemaless_insert(TAOS* taos, const char* lines[], int numLines, int protocol, int precision)` + + **功能说明** + 该接口将行协议的文本数据写入到 TDengine 中。 + + **参数说明** + taos: 数据库连接，通过 `taos_connect()` 函数建立的数据库连接。 + lines：文本数据。满足解析格式要求的无模式文本字符串。 + numLines:文本数据的行数，不能为 0 。 + protocol: 行协议类型，用于标识文本数据格式。 + precision：文本数据中的时间戳精度字符串。 + + **返回值** + TAOS_RES 结构体，应用可以通过使用 `taos_errstr()` 获得错误信息，也可以使用 `taos_errno()` 获得错误码。 + 在某些情况下，返回的 TAOS_RES 为 `NULL`，此时仍然可以调用 `taos_errno()` 来安全地获得错误码信息。 + 返回的 TAOS_RES 需要调用方来负责释放，否则会出现内存泄漏。 + + **说明** + 协议类型是枚举类型，包含以下三种格式： + + - TSDB_SML_LINE_PROTOCOL：InfluxDB 行协议（Line Protocol) + - TSDB_SML_TELNET_PROTOCOL: OpenTSDB Telnet 文本行协议 + - TSDB_SML_JSON_PROTOCOL: OpenTSDB Json 协议格式 + + 时间戳分辨率的定义，定义在 `taos.h` 文件中，具体内容如下： + + - TSDB_SML_TIMESTAMP_NOT_CONFIGURED = 0, + - TSDB_SML_TIMESTAMP_HOURS, + - TSDB_SML_TIMESTAMP_MINUTES, + - TSDB_SML_TIMESTAMP_SECONDS, + - TSDB_SML_TIMESTAMP_MILLI_SECONDS, + - TSDB_SML_TIMESTAMP_MICRO_SECONDS, + - TSDB_SML_TIMESTAMP_NANO_SECONDS + + 需要注意的是，时间戳分辨率参数只在协议类型为 `SML_LINE_PROTOCOL` 的时候生效。 + 对于 OpenTSDB 的文本协议，时间戳的解析遵循其官方解析规则 — 按照时间戳包含的字符的数量来确认时间精度。 + + **支持版本** + 该功能接口从 2.3.0.0 版本开始支持。 + +### 订阅和消费 API + +订阅 API 目前支持订阅一张或多张表，并通过定期轮询的方式不断获取写入表中的最新数据。 + +- `TAOS_SUB *taos_subscribe(TAOS* taos, int restart, const char* topic, const char *sql, TAOS_SUBSCRIBE_CALLBACK fp, void *param, int interval)` + + 该函数负责启动订阅服务，成功时返回订阅对象，失败时返回 `NULL`，其参数为： + + - taos：已经建立好的数据库连接 + - restart：如果订阅已经存在，是重新开始，还是继续之前的订阅 + - topic：订阅的主题（即名称），此参数是订阅的唯一标识 + - sql：订阅的查询语句，此语句只能是 `select` 语句，只应查询原始数据，只能按时间正序查询数据 + - fp：收到查询结果时的回调函数（稍后介绍函数原型），只在异步调用时使用，同步调用时此参数应该传 `NULL` + - param：调用回调函数时的附加参数，系统 API 将其原样传递到回调函数，不进行任何处理 + - interval：轮询周期，单位为毫秒。异步调用时，将根据此参数周期性的调用回调函数，为避免对系统性能造成影响，不建议将此参数设置的过小；同步调用时，如两次调用 `taos_consume()` 的间隔小于此周期，API 将会阻塞，直到时间间隔超过此周期。 + +- `typedef void (*TAOS_SUBSCRIBE_CALLBACK)(TAOS_SUB* tsub, TAOS_RES *res, void* param, int code)` + + 异步模式下，回调函数的原型，其参数为： + + - tsub：订阅对象 + - res：查询结果集，注意结果集中可能没有记录 + - param：调用 `taos_subscribe()` 时客户程序提供的附加参数 + - code：错误码 + + :::note + 在这个回调函数里不可以做耗时过长的处理，尤其是对于返回的结果集中数据较多的情况，否则有可能导致客户端阻塞等异常状态。如果必须进行复杂计算，则建议在另外的线程中进行处理。 + + ::: + +- `TAOS_RES *taos_consume(TAOS_SUB *tsub)` + + 同步模式下，该函数用来获取订阅的结果。 用户应用程序将其置于一个循环之中。 如两次调用 `taos_consume()` 的间隔小于订阅的轮询周期，API 将会阻塞，直到时间间隔超过此周期。如果数据库有新记录到达，该 API 将返回该最新的记录，否则返回一个没有记录的空结果集。 如果返回值为 `NULL`，说明系统出错。 异步模式下，用户程序不应调用此 API。 + + :::note + 在调用 `taos_consume()` 之后，用户应用应确保尽快调用 `taos_fetch_row()` 或 `taos_fetch_block()` 来处理订阅结果，否则服务端会持续缓存查询结果数据等待客户端读取，极端情况下会导致服务端内存消耗殆尽，影响服务稳定性。 + + ::: + +- `void taos_unsubscribe(TAOS_SUB *tsub, int keepProgress)` + + 取消订阅。 如参数 `keepProgress` 不为 0，API 会保留订阅的进度信息，后续调用 `taos_subscribe()` 时可以基于此进度继续；否则将删除进度信息，后续只能重新开始读取数据。 + diff --git a/docs-cn/14-reference/03-connector/csharp.mdx b/docs-cn/14-reference/03-connector/csharp.mdx new file mode 100644 index 0000000000000000000000000000000000000000..c2fbb3b67f640ae01766b417e4247d52da4fd334 --- /dev/null +++ b/docs-cn/14-reference/03-connector/csharp.mdx @@ -0,0 +1,189 @@ +--- +toc_max_heading_level: 4 +sidebar_position: 7 +sidebar_label: C# +title: C# Connector +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +import Preparition from "./_preparition.mdx" +import CSInsert from "../../07-develop/03-insert-data/_cs_sql.mdx" +import CSInfluxLine from "../../07-develop/03-insert-data/_cs_line.mdx" +import CSOpenTSDBTelnet from "../../07-develop/03-insert-data/_cs_opts_telnet.mdx" +import CSOpenTSDBJson from "../../07-develop/03-insert-data/_cs_opts_json.mdx" +import CSQuery from "../../07-develop/04-query-data/_cs.mdx" +import CSAsyncQuery from "../../07-develop/04-query-data/_cs_async.mdx" + +`TDengine.Connector` 是 TDengine 提供的 C# 语言连接器。C# 开发人员可以通过它开发存取 TDengine 集群数据的 C# 应用软件。 + +`TDengine.Connector` 连接器支持通过 TDengine 客户端驱动（taosc）建立与 TDengine 运行实例的连接，提供数据写入、查询、订阅、schemaless 数据写入、参数绑定接口数据写入等功能 `TDengine.Connector` 目前暂未提供 REST 连接方式，用户可以参考 [RESTful APIs](https://docs.taosdata.com//reference/restful-api/) 文档自行编写。 + +本文介绍如何在 Linux 或 Windows 环境中安装 `TDengine.Connector`，并通过 `TDengine.Connector` 连接 TDengine 集群，进行数据写入、查询等基本操作。 + +`TDengine.Connector` 的源码托管在 [GitHub](https://github.com/taosdata/taos-connector-dotnet)。 + +## 支持的平台 + +支持的平台和 TDengine 客户端驱动支持的平台一致。 + +## 版本支持 + +请参考[版本支持列表](/reference/connector#版本支持) + +## 支持的功能特性 + +1. 连接管理 +2. 普通查询 +3. 连续查询 +4. 参数绑定 +5. 订阅功能 +6. Schemaless + +## 安装步骤 + +### 安装前准备 + +* 安装 [.NET SDK](https://dotnet.microsoft.com/download) +* [Nuget 客户端](https://docs.microsoft.com/en-us/nuget/install-nuget-client-tools) （可选安装） +* 安装 TDengine 客户端驱动，具体步骤请参考[安装客户端驱动](/reference/connector#安装客户端驱动) + +### 使用 dotnet CLI 安装 + + + + +可以在当前 .NET 项目的路径下，通过 dotnet 命令引用 Nuget 中发布的 `TDengine.Connector` 到当前项目。 + +``` bash +dotnet add package TDengine.Connector +``` + + + + +可以下载 TDengine 的源码，直接引用最新版本的 TDengine.Connector 库 + +```bash +git clone https://github.com/taosdata/TDengine.git +cd TDengine/src/connector/C#/src/ +cp -r TDengineDriver/ myProject + +cd myProject +dotnet add TDengineDriver/TDengineDriver.csproj +``` + + + +## 建立连接 + +``` C# +using TDengineDriver; + +namespace TDengineExample +{ + + internal class EstablishConnection + { + static void Main(String[] args) + { + string host = "localhost"; + short port = 6030; + string username = "root"; + string password = "taosdata"; + string dbname = ""; + + var conn = TDengine.Connect(host, username, password, dbname, port); + if (conn == IntPtr.Zero) + { + Console.WriteLine("Connect to TDengine failed"); + } + else + { + Console.WriteLine("Connect to TDengine success"); + } + TDengine.Close(conn); + TDengine.Cleanup(); + } + } +} + +``` + +## 使用示例 + +### 写入数据 + +#### SQL 写入 + + + +#### InfluxDB 行协议写入 + + + +#### OpenTSDB Telnet 行协议写入 + + + +#### OpenTSDB JSON 行协议写入 + + + +### 查询数据 + +#### 同步查询 + + + +#### 异步查询 + + + +### 更多示例程序 + +|示例程序 | 示例程序描述 | +|--------------------------------------------------------------------------------------------------------------------|--------------------------------------------| +| [C#checker](https://github.com/taosdata/TDengine/tree/develop/examples/C%23/C%23checker) | 使用 TDengine.Connector 可以通过 help 命令中提供的参数，测试C# Driver的同步写入和查询 | +| [TDengineTest](https://github.com/taosdata/TDengine/tree/develop/examples/C%23/TDengineTest) | 使用 TDengine.Connector 实现的简单写入和查询的示例 | +| [insertCn](https://github.com/taosdata/TDengine/tree/develop/examples/C%23/insertCn) | 使用 TDengine.Connector 实现的写入和查询中文字符的示例 | +| [jsonTag](https://github.com/taosdata/TDengine/tree/develop/examples/C%23/jsonTag) | 使用 TDengine.Connector 实现的写入和查询 json tag 类型数据的示例 | +| [stmt](https://github.com/taosdata/TDengine/tree/develop/examples/C%23/stmt) | 使用 TDengine.Connector 实现的参数绑定的示例 | +| [schemaless](https://github.com/taosdata/TDengine/tree/develop/examples/C%23/schemaless) | 使用 TDengine.Connector 实现的使用 schemaless 写入的示例 | +| [benchmark](https://github.com/taosdata/TDengine/tree/develop/examples/C%23/taosdemo) | 使用 TDengine.Connector 实现的简易 Benchmark | +| [async query](https://github.com/taosdata/taos-connector-dotnet/blob/develop/examples/QueryAsyncSample.cs) | 使用 TDengine.Connector 实现的异步查询的示例 | +| [subscribe](https://github.com/taosdata/taos-connector-dotnet/blob/develop/examples/SubscribeSample.cs) | 使用 TDengine.Connector 实现的订阅数据的示例 | + +## 重要更新记录 + +| TDengine.Connector | 说明 | +|--------------------|--------------------------------| +| 1.0.6 | 修复 schemaless 在 1.0.4 和 1.0.5 中失效 bug。 | +| 1.0.5 | 修复 Windows 同步查询中文报错 bug。 | +| 1.0.4 | 新增异步查询，订阅等功能。修复绑定参数 bug。 | +| 1.0.3 | 新增参数绑定、schemaless、 json tag等功能。 | +| 1.0.2 | 新增连接管理、同步查询、错误信息等功能。 | + +## 其他说明 + +### 第三方驱动 + +`Maikebing.Data.Taos` 是一个 TDengine 的 ADO.NET 连接器，支持 Linux，Windows 平台。该连接器由社区贡献者`麦壳饼@@maikebing` 提供，具体请参考: + +* 接口下载: +* 用法说明: + +## 常见问题 + +1. "Unable to establish connection"，"Unable to resolve FQDN" + + 一般是因为 FQDN 配置不正确。可以参考[如何彻底搞懂 TDengine 的 FQDN](https://www.taosdata.com/blog/2021/07/29/2741.html)解决。 + +2. Unhandled exception. System.DllNotFoundException: Unable to load DLL 'taos' or one of its dependencies: 找不到指定的模块。 + + 一般是因为程序没有找到依赖的客户端驱动。解决方法为：Windows 下可以将 `C:\TDengine\driver\taos.dll` 拷贝到 `C:\Windows\System32\ ` 目录下，Linux 下建立如下软链接 `ln -s /usr/local/taos/driver/libtaos.so.x.x.x.x /usr/lib/libtaos.so` 即可。 + +## API 参考 + +[API 参考](https://docs.taosdata.com/api/connector-csharp/html/860d2ac1-dd52-39c9-e460-0829c4e5a40b.htm) diff --git a/docs-cn/14-reference/03-connector/go.mdx b/docs-cn/14-reference/03-connector/go.mdx new file mode 100644 index 0000000000000000000000000000000000000000..88b09aa5d0b0161973e3e7eabb4cf04357c134f3 --- /dev/null +++ b/docs-cn/14-reference/03-connector/go.mdx @@ -0,0 +1,411 @@ +--- +toc_max_heading_level: 4 +sidebar_position: 4 +sidebar_label: Go +title: TDengine Go Connector +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +import Preparition from "./_preparition.mdx" +import GoInsert from "../../07-develop/03-insert-data/_go_sql.mdx" +import GoInfluxLine from "../../07-develop/03-insert-data/_go_line.mdx" +import GoOpenTSDBTelnet from "../../07-develop/03-insert-data/_go_opts_telnet.mdx" +import GoOpenTSDBJson from "../../07-develop/03-insert-data/_go_opts_json.mdx" +import GoQuery from "../../07-develop/04-query-data/_go.mdx" + +`driver-go` 是 TDengine 的官方 Go 语言连接器，实现了 Go 语言[ database/sql ](https://golang.org/pkg/database/sql/) 包的接口。Go 开发人员可以通过它开发存取 TDengine 集群数据的应用软件。 + +`driver-go` 提供两种建立连接的方式。一种是**原生连接**，它通过 TDengine 客户端驱动程序（taosc）原生连接 TDengine 运行实例，支持数据写入、查询、订阅、schemaless 接口和参数绑定接口等功能。另外一种是 **REST 连接**，它通过 taosAdapter 提供的 REST 接口连接 TDengine 运行实例。REST 连接实现的功能特性集合和原生连接有少量不同。 + +本文介绍如何安装 `driver-go`，并通过 `driver-go` 连接 TDengine 集群、进行数据查询、数据写入等基本操作。 + +`driver-go` 的源码托管在 [GitHub](https://github.com/taosdata/driver-go)。 + +## 支持的平台 + +原生连接支持的平台和 TDengine 客户端驱动支持的平台一致。 +REST 连接支持所有能运行 Go 的平台。 + +## 版本支持 + +请参考[版本支持列表](/reference/connector#版本支持) + +## 支持的功能特性 + +### 原生连接 + +“原生连接”指连接器通过 TDengine 客户端驱动（taosc）直接与 TDengine 运行实例建立的连接。支持的功能特性有： + +* 普通查询 +* 连续查询 +* 订阅 +* schemaless 接口 +* 参数绑定接口 + +### REST 连接 + +"REST 连接"指连接器通过 taosAdapter 组件提供的 REST API 与 TDengine 运行实例建立的连接。支持的功能特性有： + +* 普通查询 +* 连续查询 + +## 安装步骤 + +### 安装前准备 + +* 安装 Go 开发环境（Go 1.14 及以上，GCC 4.8.5 及以上） +* 如果使用原生连接器，请安装 TDengine 客户端驱动，具体步骤请参考[安装客户端驱动](/reference/connector#安装客户端驱动) + +配置好环境变量，检查命令： + +* ```go env``` +* ```gcc -v``` + +### 使用 go get 安装 + +`go get -u github.com/taosdata/driver-go/v2@develop` + +### 使用 go mod 管理 + +1. 使用 `go mod` 命令初始化项目： + + ```text + go mod init taos-demo + ``` + +2. 引入 taosSql ： + + ```go + import ( + "database/sql" + _ "github.com/taosdata/driver-go/v2/taosSql" + ) + ``` + +3. 使用 `go mod tidy` 更新依赖包： + + ```text + go mod tidy + ``` + +4. 使用 `go run taos-demo` 运行程序或使用 `go build` 命令编译出二进制文件。 + + ```text + go run taos-demo + go build + ``` + +## 建立连接 + +### 数据源名称（DSN） + +数据源名称具有通用格式，例如 [PEAR DB](http://pear.php.net/manual/en/package.database.db.intro-dsn.php)，但没有类型前缀（方括号表示可选）： + +``` text +[username[:password]@][protocol[(address)]]/[dbname][?param1=value1&...¶mN=valueN] +``` + +完整形式的 DSN： + +```text +username:password@protocol(address)/dbname?param=value +``` +### 使用连接器进行连接 + + + + +_taosSql_ 通过 cgo 实现了 Go 的 `database/sql/driver` 接口。只需要引入驱动就可以使用 [`database/sql`](https://golang.org/pkg/database/sql/) 的接口。 + +使用 `taosSql` 作为 `driverName` 并且使用一个正确的 [DSN](#DSN) 作为 `dataSourceName`，DSN 支持的参数： + +* configPath 指定 taos.cfg 目录 + +示例： + +```go +package main + +import ( + "database/sql" + "fmt" + + _ "github.com/taosdata/driver-go/v2/taosSql" +) + +func main() { + var taosUri = "root:taosdata@tcp(localhost:6030)/" + taos, err := sql.Open("taosSql", taosUri) + if err != nil { + fmt.Println("failed to connect TDengine, err:", err) + return + } +} +``` + + + + +_taosRestful_ 通过 `http client` 实现了 Go 的 `database/sql/driver` 接口。只需要引入驱动就可以使用[`database/sql`](https://golang.org/pkg/database/sql/)的接口。 + +使用 `taosRestful` 作为 `driverName` 并且使用一个正确的 [DSN](#DSN) 作为 `dataSourceName`，DSN 支持的参数： + +* `disableCompression` 是否接受压缩数据，默认为 true 不接受压缩数据，如果传输数据使用 gzip 压缩设置为 false。 +* `readBufferSize` 读取数据的缓存区大小默认为 4K（4096），当查询结果数据量多时可以适当调大该值。 + +示例： + +```go +package main + +import ( + "database/sql" + "fmt" + + _ "github.com/taosdata/driver-go/v2/taosRestful" +) + +func main() { + var taosUri = "root:taosdata@http(localhost:6041)/" + taos, err := sql.Open("taosRestful", taosUri) + if err != nil { + fmt.Println("failed to connect TDengine, err:", err) + return + } +} +``` + + + +## 使用示例 + +### 写入数据 + +#### SQL 写入 + + + +#### InfluxDB 行协议写入 + + + +#### OpenTSDB Telnet 行协议写入 + + + +#### OpenTSDB JSON 行协议写入 + + + +### 查询数据 + + + +### 更多示例程序 + +* [示例程序](https://github.com/taosdata/TDengine/tree/develop/examples/go) +* [视频教程](https://www.taosdata.com/blog/2020/11/11/1951.html)。 + +## 使用限制 + +由于 REST 接口无状态所以 `use db` 语法不会生效，需要将 db 名称放到 SQL 语句中，如：`create table if not exists tb1 (ts timestamp, a int)`改为`create table if not exists test.tb1 (ts timestamp, a int)`否则将报错`[0x217] Database not specified or available`。 + +也可以将 db 名称放到 DSN 中，将 `root:taosdata@http(localhost:6041)/` 改为 `root:taosdata@http(localhost:6041)/test`，此方法在 TDengine 2.4.0.5 版本的 taosAdapter 开始支持。当指定的 db 不存在时执行 `create database` 语句不会报错，而执行针对该 db 的其他查询或写入操作会报错。 + +完整示例如下： + +```go +package main + +import ( + "database/sql" + "fmt" + "time" + + _ "github.com/taosdata/driver-go/v2/taosRestful" +) + +func main() { + var taosDSN = "root:taosdata@http(localhost:6041)/test" + taos, err := sql.Open("taosRestful", taosDSN) + if err != nil { + fmt.Println("failed to connect TDengine, err:", err) + return + } + defer taos.Close() + taos.Exec("create database if not exists test") + taos.Exec("create table if not exists tb1 (ts timestamp, a int)") + _, err = taos.Exec("insert into tb1 values(now, 0)(now+1s,1)(now+2s,2)(now+3s,3)") + if err != nil { + fmt.Println("failed to insert, err:", err) + return + } + rows, err := taos.Query("select * from tb1") + if err != nil { + fmt.Println("failed to select from table, err:", err) + return + } + + defer rows.Close() + for rows.Next() { + var r struct { + ts time.Time + a int + } + err := rows.Scan(&r.ts, &r.a) + if err != nil { + fmt.Println("scan error:\n", err) + return + } + fmt.Println(r.ts, r.a) + } +} +``` + +## 常见问题 + +1. 无法找到包 `github.com/taosdata/driver-go/v2/taosRestful` + + 将 `go.mod` 中 require 块对`github.com/taosdata/driver-go/v2`的引用改为`github.com/taosdata/driver-go/v2 develop`，之后执行 `go mod tidy`。 + +2. database/sql 中 stmt（参数绑定）相关接口崩溃 + + REST 不支持参数绑定相关接口，建议使用`db.Exec`和`db.Query`。 + +3. 使用 `use db` 语句后执行其他语句报错 `[0x217] Database not specified or available` + + 在 REST 接口中 SQL 语句的执行无上下文关联，使用 `use db` 语句不会生效，解决办法见上方使用限制章节。 + +4. 使用 taosSql 不报错使用 taosRestful 报错 `[0x217] Database not specified or available` + + 因为 REST 接口无状态，使用 `use db` 语句不会生效，解决办法见上方使用限制章节。 + +5. 升级 `github.com/taosdata/driver-go/v2/taosRestful` + + 将 `go.mod` 文件中对 `github.com/taosdata/driver-go/v2` 的引用改为 `github.com/taosdata/driver-go/v2 develop`，之后执行 `go mod tidy`。 + +6. `readBufferSize` 参数调大后无明显效果 + + `readBufferSize` 调大后会减少获取结果时 `syscall` 的调用。如果查询结果的数据量不大，修改该参数不会带来明显提升，如果该参数修改过大，瓶颈会在解析 JSON 数据。如果需要优化查询速度，需要根据实际情况调整该值来达到查询效果最优。 + +7. `disableCompression` 参数设置为 `false` 时查询效率降低 + + 当 `disableCompression` 参数设置为 `false` 时查询结果会使用 `gzip` 压缩后传输，拿到数据后要先进行 `gzip` 解压。 + +8. `go get` 命令无法获取包，或者获取包超时 + + 设置 Go 代理 `go env -w GOPROXY=https://goproxy.cn,direct`。 + +## 常用 API + +### database/sql API + +* `sql.Open(DRIVER_NAME string, dataSourceName string) *DB` + + 该 API 用来打开 DB，返回一个类型为 \*DB 的对象。 + +:::info +该 API 成功创建的时候，并没有做权限等检查，只有在真正执行 Query 或者 Exec 的时候才能真正的去创建连接，并同时检查 user/password/host/port 是不是合法。 +::: + +* `func (db *DB) Exec(query string, args ...interface{}) (Result, error)` + + `sql.Open` 内置的方法，用来执行非查询相关 SQL。 + +* `func (db *DB) Query(query string, args ...interface{}) (*Rows, error)` + + `sql.Open` 内置的方法，用来执行查询语句。 + +### 高级功能（af）API + +`af` 包封装了连接管理、订阅、schemaless、参数绑定等 TDengine 高级功能。 + +#### 连接管理 + +* `af.Open(host, user, pass, db string, port int) (*Connector, error)` + + 该 API 通过 cgo 创建与 taosd 的连接。 + +* `func (conn *Connector) Close() error` + + 关闭与 taosd 的连接。 + +#### 订阅 + +* `func (conn *Connector) Subscribe(restart bool, topic string, sql string, interval time.Duration) (Subscriber, error)` + + 订阅数据。 + +* `func (s *taosSubscriber) Consume() (driver.Rows, error)` + + 消费订阅数据，返回 `database/sql/driver` 包的 `Rows` 结构。 + +* `func (s *taosSubscriber) Unsubscribe(keepProgress bool)` + + 取消订阅数据。 + +#### schemaless + +* `func (conn *Connector) InfluxDBInsertLines(lines []string, precision string) error` + + 写入 influxDB 行协议。 + +* `func (conn *Connector) OpenTSDBInsertTelnetLines(lines []string) error` + + 写入 OpenTDSB telnet 协议数据。 + +* `func (conn *Connector) OpenTSDBInsertJsonPayload(payload string) error` + + 写入 OpenTSDB JSON 协议数据。 + +#### 参数绑定 + +* `func (conn *Connector) StmtExecute(sql string, params *param.Param) (res driver.Result, err error)` + + 参数绑定单行插入。 + +* `func (conn *Connector) StmtQuery(sql string, params *param.Param) (rows driver.Rows, err error)` + + 参数绑定查询，返回 `database/sql/driver` 包的 `Rows` 结构。 + +* `func (conn *Connector) InsertStmt() *insertstmt.InsertStmt` + + 初始化参数。 + +* `func (stmt *InsertStmt) Prepare(sql string) error` + + 参数绑定预处理 SQL 语句。 + +* `func (stmt *InsertStmt) SetTableName(name string) error` + + 参数绑定设置表名。 + +* `func (stmt *InsertStmt) SetSubTableName(name string) error` + + 参数绑定设置子表名。 + +* `func (stmt *InsertStmt) BindParam(params []*param.Param, bindType *param.ColumnType) error` + + 参数绑定多行数据。 + +* `func (stmt *InsertStmt) AddBatch() error` + + 添加到参数绑定批处理。 + +* `func (stmt *InsertStmt) Execute() error` + + 执行参数绑定。 + +* `func (stmt *InsertStmt) GetAffectedRows() int` + + 获取参数绑定插入受影响行数。 + +* `func (stmt *InsertStmt) Close() error` + + 结束参数绑定。 + +## API 参考 + +全部 API 见 [driver-go 文档](https://pkg.go.dev/github.com/taosdata/driver-go/v2) diff --git a/docs-cn/14-reference/03-connector/java.mdx b/docs-cn/14-reference/03-connector/java.mdx new file mode 100644 index 0000000000000000000000000000000000000000..55abf84fd50fe1c4b5b6a07b28731a00d4534a05 --- /dev/null +++ b/docs-cn/14-reference/03-connector/java.mdx @@ -0,0 +1,839 @@ +--- +toc_max_heading_level: 4 +sidebar_position: 2 +sidebar_label: Java +title: TDengine Java Connector +description: TDengine Java 连接器基于标准 JDBC API 实现, 并提供原生连接与 REST连接两种连接器。 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +`taos-jdbcdriver` 是 TDengine 的官方 Java 语言连接器，Java 开发人员可以通过它开发存取 TDengine 数据库的应用软件。`taos-jdbcdriver` 实现了 JDBC driver 标准的接口，并提供两种形式的连接器。一种是通过 TDengine 客户端驱动程序（taosc）原生连接 TDengine 实例，支持数据写入、查询、订阅、schemaless 接口和参数绑定接口等功能，一种是通过 taosAdapter 提供的 REST 接口连接 TDengine 实例（2.4.0.0 及更高版本）。REST 连接实现的功能集合和原生连接有少量不同。 + +![tdengine-connector](tdengine-jdbc-connector.png) + +上图显示了两种 Java 应用使用连接器访问 TDengine 的两种方式： + +- JDBC 原生连接：Java 应用在物理节点 1（pnode1）上使用 TSDBDriver 直接调用客户端驱动（libtaos.so 或 taos.dll）的 API 将写入和查询请求发送到位于物理节点 2（pnode2）上的 taosd 实例。 +- JDBC REST 连接：Java 应用通过 RestfulDriver 将 SQL 封装成一个 REST 请求，发送给物理节点 2 的 REST 服务器（taosAdapter），通过 REST 服务器请求 taosd 并返回结果。 + +使用 REST 连接，不依赖 TDengine 客户端驱动，可以跨平台，更加方便灵活，但性能比原生连接器低约 30%。 + +:::info +TDengine 的 JDBC 驱动实现尽可能与关系型数据库驱动保持一致，但 TDengine 与关系对象型数据库的使用场景和技术特征存在差异，所以`taos-jdbcdriver` 与传统的 JDBC driver 也存在一定差异。在使用时需要注意以下几点： + +- TDengine 目前不支持针对单条数据记录的删除操作。 +- 目前不支持事务操作。 + +::: + +## 支持的平台 + +原生连接支持的平台和 TDengine 客户端驱动支持的平台一致。 +REST 连接支持所有能运行 Java 的平台。 + +## 版本支持 + +请参考[版本支持列表](/reference/connector#版本支持) + +## TDengine DataType 和 Java DataType + +TDengine 目前支持时间戳、数字、字符、布尔类型，与 Java 对应类型转换如下： + +| TDengine DataType | JDBCType （driver 版本 < 2.0.24） | JDBCType （driver 版本 >= 2.0.24） | +| ----------------- | --------------------------------- | ---------------------------------- | +| TIMESTAMP | java.lang.Long | java.sql.Timestamp | +| INT | java.lang.Integer | java.lang.Integer | +| BIGINT | java.lang.Long | java.lang.Long | +| FLOAT | java.lang.Float | java.lang.Float | +| DOUBLE | java.lang.Double | java.lang.Double | +| SMALLINT | java.lang.Short | java.lang.Short | +| TINYINT | java.lang.Byte | java.lang.Byte | +| BOOL | java.lang.Boolean | java.lang.Boolean | +| BINARY | java.lang.String | byte array | +| NCHAR | java.lang.String | java.lang.String | +| JSON | - | java.lang.String | + +**注意**：JSON 类型仅在 tag 中支持。 + +## 安装步骤 + +### 安装前准备 + +使用 Java Connector 连接数据库前，需要具备以下条件： + +- 已安装 Java 1.8 或以上版本运行时环境和 Maven 3.6 或以上版本 +- 已安装 TDengine 客户端驱动（使用原生连接必须安装，使用 REST 连接无需安装），具体步骤请参考[安装客户端驱动](/reference/connector#安装客户端驱动) + +### 安装连接器 + + + + +目前 taos-jdbcdriver 已经发布到 [Sonatype Repository](https://search.maven.org/artifact/com.taosdata.jdbc/taos-jdbcdriver) 仓库，且各大仓库都已同步。 + +- [sonatype](https://search.maven.org/artifact/com.taosdata.jdbc/taos-jdbcdriver) +- [mvnrepository](https://mvnrepository.com/artifact/com.taosdata.jdbc/taos-jdbcdriver) +- [maven.aliyun](https://maven.aliyun.com/mvn/search) + +Maven 项目中，在 pom.xml 中添加以下依赖： + +```xml-dtd + + com.taosdata.jdbc + taos-jdbcdriver + 2.0.** + +``` + + + + +可以通过下载 TDengine 的源码，自己编译最新版本的 Java connector + +```shell +git clone https://github.com/taosdata/TDengine.git +cd TDengine/src/connector/jdbc +mvn clean install -Dmaven.test.skip=true +``` + +编译后，在 target 目录下会产生 taos-jdbcdriver-2.0.XX-dist.jar 的 jar 包，并自动将编译的 jar 文件放在本地的 Maven 仓库中。 + + + + +## 建立连接 + +TDengine 的 JDBC URL 规范格式为： +`jdbc:[TAOS|TAOS-RS]://[host_name]:[port]/[database_name]?[user={user}|&password={password}|&charset={charset}|&cfgdir={config_dir}|&locale={locale}|&timezone={timezone}]` + +对于建立连接，原生连接与 REST 连接有细微不同。 + + + + +```java +Class.forName("com.taosdata.jdbc.TSDBDriver"); +String jdbcUrl = "jdbc:TAOS://taosdemo.com:6030/test?user=root&password=taosdata"; +Connection conn = DriverManager.getConnection(jdbcUrl); +``` + +以上示例，使用了 JDBC 原生连接的 TSDBDriver，建立了到 hostname 为 taosdemo.com，端口为 6030（TDengine 的默认端口），数据库名为 test 的连接。这个 URL 中指定用户名（user）为 root，密码（password）为 taosdata。 + +**注意**：使用 JDBC 原生连接，taos-jdbcdriver 需要依赖客户端驱动（Linux 下是 libtaos.so；Windows 下是 taos.dll）。 + +url 中的配置参数如下： + +- user：登录 TDengine 用户名，默认值 'root'。 +- password：用户登录密码，默认值 'taosdata'。 +- cfgdir：客户端配置文件目录路径，Linux OS 上默认值 `/etc/taos`，Windows OS 上默认值 `C:/TDengine/cfg`。 +- charset：客户端使用的字符集，默认值为系统字符集。 +- locale：客户端语言环境，默认值系统当前 locale。 +- timezone：客户端使用的时区，默认值为系统当前时区。 +- batchfetch: true：在执行查询时批量拉取结果集；false：逐行拉取结果集。默认值为：false。开启批量拉取同时获取一批数据在查询数据量较大时批量拉取可以有效的提升查询性能。 +- batchErrorIgnore：true：在执行 Statement 的 executeBatch 时，如果中间有一条 SQL 执行失败将继续执行下面的 SQL。false：不再执行失败 SQL 后的任何语句。默认值为：false。 + +JDBC 原生连接的使用请参见[视频教程](https://www.taosdata.com/blog/2020/11/11/1955.html)。 + +**使用 TDengine 客户端驱动配置文件建立连接 ** + +当使用 JDBC 原生连接连接 TDengine 集群时，可以使用 TDengine 客户端驱动配置文件，在配置文件中指定集群的 firstEp、secondEp 等参数。如下所示： + +1. 在 Java 应用中不指定 hostname 和 port + +```java +public Connection getConn() throws Exception{ + Class.forName("com.taosdata.jdbc.TSDBDriver"); + String jdbcUrl = "jdbc:TAOS://:/test?user=root&password=taosdata"; + Properties connProps = new Properties(); + connProps.setProperty(TSDBDriver.PROPERTY_KEY_CHARSET, "UTF-8"); + connProps.setProperty(TSDBDriver.PROPERTY_KEY_LOCALE, "en_US.UTF-8"); + connProps.setProperty(TSDBDriver.PROPERTY_KEY_TIME_ZONE, "UTC-8"); + Connection conn = DriverManager.getConnection(jdbcUrl, connProps); + return conn; +} +``` + +2. 在配置文件中指定 firstEp 和 secondEp + +```shell +# first fully qualified domain name (FQDN) for TDengine system +firstEp cluster_node1:6030 + +# second fully qualified domain name (FQDN) for TDengine system, for cluster only +secondEp cluster_node2:6030 + +# default system charset +# charset UTF-8 + +# system locale +# locale en_US.UTF-8 +``` + +以上示例，jdbc 会使用客户端的配置文件，建立到 hostname 为 cluster_node1、端口为 6030、数据库名为 test 的连接。当集群中 firstEp 节点失效时，JDBC 会尝试使用 secondEp 连接集群。 + +TDengine 中，只要保证 firstEp 和 secondEp 中一个节点有效，就可以正常建立到集群的连接。 + +> **注意**：这里的配置文件指的是调用 JDBC Connector 的应用程序所在机器上的配置文件，Linux OS 上默认值 /etc/taos/taos.cfg ，Windows OS 上默认值 C://TDengine/cfg/taos.cfg。 + + + + +```java +Class.forName("com.taosdata.jdbc.rs.RestfulDriver"); +String jdbcUrl = "jdbc:TAOS-RS://taosdemo.com:6041/test?user=root&password=taosdata"; +Connection conn = DriverManager.getConnection(jdbcUrl); +``` + +以上示例，使用了 JDBC REST 连接的 RestfulDriver，建立了到 hostname 为 taosdemo.com，端口为 6041，数据库名为 test 的连接。这个 URL 中指定用户名（user）为 root，密码（password）为 taosdata。 + +使用 JDBC REST 连接，不需要依赖客户端驱动。与 JDBC 原生连接相比，仅需要： + +1. driverClass 指定为“com.taosdata.jdbc.rs.RestfulDriver”； +2. jdbcUrl 以“jdbc:TAOS-RS://”开头； +3. 使用 6041 作为连接端口。 + +url 中的配置参数如下： + +- user：登录 TDengine 用户名，默认值 'root'。 +- password：用户登录密码，默认值 'taosdata'。 +- batchfetch: true：在执行查询时批量拉取结果集；false：逐行拉取结果集。默认值为：false。逐行拉取结果集使用 HTTP 方式进行数据传输。从 taos-jdbcdriver-2.0.38 和 TDengine 2.4.0.12 版本开始，JDBC REST 连接增加批量拉取数据功能。taos-jdbcdriver 与 TDengine 之间通过 WebSocket 连接进行数据传输。相较于 HTTP，WebSocket 可以使 JDBC REST 连接支持大数据量查询，并提升查询性能。 +- batchErrorIgnore：true：在执行 Statement 的 executeBatch 时，如果中间有一条 SQL 执行失败，继续执行下面的 SQL 了。false：不再执行失败 SQL 后的任何语句。默认值为：false。 + +**注意**：部分配置项（比如：locale、timezone）在 REST 连接中不生效。 + +:::note + +- 与原生连接方式不同，REST 接口是无状态的。在使用 JDBC REST 连接时，需要在 SQL 中指定表、超级表的数据库名称。例如： + +```sql +INSERT INTO test.t1 USING test.weather (ts, temperature) TAGS('beijing') VALUES(now, 24.6); +``` + +- 从 taos-jdbcdriver-2.0.36 和 TDengine 2.2.0.0 版本开始，如果在 url 中指定了 dbname，那么，JDBC REST 连接会默认使用/rest/sql/dbname 作为 restful 请求的 url，在 SQL 中不需要指定 dbname。例如：url 为 jdbc:TAOS-RS://127.0.0.1:6041/test，那么，可以执行 sql：insert into t1 using weather(ts, temperature) tags('beijing') values(now, 24.6); + +::: + + + + +### 指定 URL 和 Properties 获取连接 + +除了通过指定的 URL 获取连接，还可以使用 Properties 指定建立连接时的参数。 + +**注意**： + +- 应用中设置的 client parameter 为进程级别的，即如果要更新 client 的参数，需要重启应用。这是因为 client parameter 是全局参数，仅在应用程序的第一次设置生效。 +- 以下示例代码基于 taos-jdbcdriver-2.0.36。 + +```java +public Connection getConn() throws Exception{ + Class.forName("com.taosdata.jdbc.TSDBDriver"); + String jdbcUrl = "jdbc:TAOS://taosdemo.com:6030/test?user=root&password=taosdata"; + Properties connProps = new Properties(); + connProps.setProperty(TSDBDriver.PROPERTY_KEY_CHARSET, "UTF-8"); + connProps.setProperty(TSDBDriver.PROPERTY_KEY_LOCALE, "en_US.UTF-8"); + connProps.setProperty(TSDBDriver.PROPERTY_KEY_TIME_ZONE, "UTC-8"); + connProps.setProperty("debugFlag", "135"); + connProps.setProperty("maxSQLLength", "1048576"); + Connection conn = DriverManager.getConnection(jdbcUrl, connProps); + return conn; +} + +public Connection getRestConn() throws Exception{ + Class.forName("com.taosdata.jdbc.rs.RestfulDriver"); + String jdbcUrl = "jdbc:TAOS-RS://taosdemo.com:6041/test?user=root&password=taosdata"; + Properties connProps = new Properties(); + connProps.setProperty(TSDBDriver.PROPERTY_KEY_BATCH_LOAD, "true"); + Connection conn = DriverManager.getConnection(jdbcUrl, connProps); + return conn; +} +``` + +以上示例，建立一个到 hostname 为 taosdemo.com，端口为 6030/6041，数据库名为 test 的连接。这个连接在 url 中指定了用户名(user)为 root，密码（password）为 taosdata，并在 connProps 中指定了使用的字符集、语言环境、时区、是否开启批量拉取等信息。 + +properties 中的配置参数如下： + +- TSDBDriver.PROPERTY_KEY_USER：登录 TDengine 用户名，默认值 'root'。 +- TSDBDriver.PROPERTY_KEY_PASSWORD：用户登录密码，默认值 'taosdata'。 +- TSDBDriver.PROPERTY_KEY_BATCH_LOAD: true：在执行查询时批量拉取结果集；false：逐行拉取结果集。默认值为：false。 +- TSDBDriver.PROPERTY_KEY_BATCH_ERROR_IGNORE：true：在执行 Statement 的 executeBatch 时，如果中间有一条 SQL 执行失败，继续执行下面的 sq 了。false：不再执行失败 SQL 后的任何语句。默认值为：false。 +- TSDBDriver.PROPERTY_KEY_CONFIG_DIR：仅在使用 JDBC 原生连接时生效。客户端配置文件目录路径，Linux OS 上默认值 `/etc/taos`，Windows OS 上默认值 `C:/TDengine/cfg`。 +- TSDBDriver.PROPERTY_KEY_CHARSET：仅在使用 JDBC 原生连接时生效。 客户端使用的字符集，默认值为系统字符集。 +- TSDBDriver.PROPERTY_KEY_LOCALE：仅在使用 JDBC 原生连接时生效。 客户端语言环境，默认值系统当前 locale。 +- TSDBDriver.PROPERTY_KEY_TIME_ZONE：仅在使用 JDBC 原生连接时生效。 客户端使用的时区，默认值为系统当前时区。 +- 此外对 JDBC 原生连接，通过指定 URL 和 Properties 还可以指定其他参数，比如日志级别、SQL 长度等。更多详细配置请参考[客户端配置](/reference/config/#仅客户端适用)。 + +### 配置参数的优先级 + +通过前面三种方式获取连接，如果配置参数在 url、Properties、客户端配置文件中有重复，则参数的`优先级由高到低`分别如下： + +1. JDBC URL 参数，如上所述，可以在 JDBC URL 的参数中指定。 +2. Properties connProps +3. 使用原生连接时，TDengine 客户端驱动的配置文件 taos.cfg + +例如：在 url 中指定了 password 为 taosdata，在 Properties 中指定了 password 为 taosdemo，那么，JDBC 会使用 url 中的 password 建立连接。 + +## 使用示例 + +### 创建数据库和表 + +```java +Statement stmt = conn.createStatement(); + +// create database +stmt.executeUpdate("create database if not exists db"); + +// use database +stmt.executeUpdate("use db"); + +// create table +stmt.executeUpdate("create table if not exists tb (ts timestamp, temperature int, humidity float)"); +``` + +> **注意**：如果不使用 `use db` 指定数据库，则后续对表的操作都需要增加数据库名称作为前缀，如 db.tb。 + +### 插入数据 + +```java +// insert data +int affectedRows = stmt.executeUpdate("insert into tb values(now, 23, 10.3) (now + 1s, 20, 9.3)"); + +System.out.println("insert " + affectedRows + " rows."); +``` + +> now 为系统内部函数，默认为客户端所在计算机当前时间。 +> `now + 1s` 代表客户端当前时间往后加 1 秒，数字后面代表时间单位：a(毫秒)，s(秒)，m(分)，h(小时)，d(天)，w(周)，n(月)，y(年)。 + +### 查询数据 + +```java +// query data +ResultSet resultSet = stmt.executeQuery("select * from tb"); + +Timestamp ts = null; +int temperature = 0; +float humidity = 0; +while(resultSet.next()){ + + ts = resultSet.getTimestamp(1); + temperature = resultSet.getInt(2); + humidity = resultSet.getFloat("humidity"); + + System.out.printf("%s, %d, %s\n", ts, temperature, humidity); +} +``` + +> 查询和操作关系型数据库一致，使用下标获取返回字段内容时从 1 开始，建议使用字段名称获取。 + +### 处理异常 + +在报错后，通过 SQLException 可以获取到错误的信息和错误码： + +```java +try (Statement statement = connection.createStatement()) { + // executeQuery + ResultSet resultSet = statement.executeQuery(sql); + // print result + printResult(resultSet); +} catch (SQLException e) { + System.out.println("ERROR Message: " + e.getMessage()); + System.out.println("ERROR Code: " + e.getErrorCode()); + e.printStackTrace(); +} +``` + +JDBC 连接器可能报错的错误码包括 3 种：JDBC driver 本身的报错（错误码在 0x2301 到 0x2350 之间），原生连接方法的报错（错误码在 0x2351 到 0x2400 之间），TDengine 其他功能模块的报错。 + +具体的错误码请参考： + +- [TDengine Java Connector](https://github.com/taosdata/TDengine/blob/develop/src/connector/jdbc/src/main/java/com/taosdata/jdbc/TSDBErrorNumbers.java) +- [TDengine_ERROR_CODE](https://github.com/taosdata/TDengine/blob/develop/src/inc/taoserror.h) + +### 通过参数绑定写入数据 + +从 2.1.2.0 版本开始，TDengine 的 JDBC 原生连接实现大幅改进了参数绑定方式对数据写入（INSERT）场景的支持。采用这种方式写入数据时，能避免 SQL 语法解析的资源消耗，从而在很多情况下显著提升写入性能。 + +**注意**： + +- JDBC REST 连接目前不支持参数绑定 +- 以下示例代码基于 taos-jdbcdriver-2.0.36 +- binary 类型数据需要调用 setString 方法，nchar 类型数据需要调用 setNString 方法 +- setString 和 setNString 都要求用户在 size 参数里声明表定义中对应列的列宽 + +```java +public class ParameterBindingDemo { + + private static final String host = "127.0.0.1"; + private static final Random random = new Random(System.currentTimeMillis()); + private static final int BINARY_COLUMN_SIZE = 20; + private static final String[] schemaList = { + "create table stable1(ts timestamp, f1 tinyint, f2 smallint, f3 int, f4 bigint) tags(t1 tinyint, t2 smallint, t3 int, t4 bigint)", + "create table stable2(ts timestamp, f1 float, f2 double) tags(t1 float, t2 double)", + "create table stable3(ts timestamp, f1 bool) tags(t1 bool)", + "create table stable4(ts timestamp, f1 binary(" + BINARY_COLUMN_SIZE + ")) tags(t1 binary(" + BINARY_COLUMN_SIZE + "))", + "create table stable5(ts timestamp, f1 nchar(" + BINARY_COLUMN_SIZE + ")) tags(t1 nchar(" + BINARY_COLUMN_SIZE + "))" + }; + private static final int numOfSubTable = 10, numOfRow = 10; + + public static void main(String[] args) throws SQLException { + + String jdbcUrl = "jdbc:TAOS://" + host + ":6030/"; + Connection conn = DriverManager.getConnection(jdbcUrl, "root", "taosdata"); + + init(conn); + + bindInteger(conn); + + bindFloat(conn); + + bindBoolean(conn); + + bindBytes(conn); + + bindString(conn); + + conn.close(); + } + + private static void init(Connection conn) throws SQLException { + try (Statement stmt = conn.createStatement()) { + stmt.execute("drop database if exists test_parabind"); + stmt.execute("create database if not exists test_parabind"); + stmt.execute("use test_parabind"); + for (int i = 0; i < schemaList.length; i++) { + stmt.execute(schemaList[i]); + } + } + } + + private static void bindInteger(Connection conn) throws SQLException { + String sql = "insert into ? using stable1 tags(?,?,?,?) values(?,?,?,?,?)"; + + try (TSDBPreparedStatement pstmt = conn.prepareStatement(sql).unwrap(TSDBPreparedStatement.class)) { + + for (int i = 1; i <= numOfSubTable; i++) { + // set table name + pstmt.setTableName("t1_" + i); + // set tags + pstmt.setTagByte(0, Byte.parseByte(Integer.toString(random.nextInt(Byte.MAX_VALUE)))); + pstmt.setTagShort(1, Short.parseShort(Integer.toString(random.nextInt(Short.MAX_VALUE)))); + pstmt.setTagInt(2, random.nextInt(Integer.MAX_VALUE)); + pstmt.setTagLong(3, random.nextLong()); + // set columns + ArrayList tsList = new ArrayList<>(); + long current = System.currentTimeMillis(); + for (int j = 0; j < numOfRow; j++) + tsList.add(current + j); + pstmt.setTimestamp(0, tsList); + + ArrayList f1List = new ArrayList<>(); + for (int j = 0; j < numOfRow; j++) + f1List.add(Byte.parseByte(Integer.toString(random.nextInt(Byte.MAX_VALUE)))); + pstmt.setByte(1, f1List); + + ArrayList f2List = new ArrayList<>(); + for (int j = 0; j < numOfRow; j++) + f2List.add(Short.parseShort(Integer.toString(random.nextInt(Short.MAX_VALUE)))); + pstmt.setShort(2, f2List); + + ArrayList f3List = new ArrayList<>(); + for (int j = 0; j < numOfRow; j++) + f3List.add(random.nextInt(Integer.MAX_VALUE)); + pstmt.setInt(3, f3List); + + ArrayList f4List = new ArrayList<>(); + for (int j = 0; j < numOfRow; j++) + f4List.add(random.nextLong()); + pstmt.setLong(4, f4List); + + // add column + pstmt.columnDataAddBatch(); + } + // execute column + pstmt.columnDataExecuteBatch(); + } + } + + private static void bindFloat(Connection conn) throws SQLException { + String sql = "insert into ? using stable2 tags(?,?) values(?,?,?)"; + + TSDBPreparedStatement pstmt = conn.prepareStatement(sql).unwrap(TSDBPreparedStatement.class); + + for (int i = 1; i <= numOfSubTable; i++) { + // set table name + pstmt.setTableName("t2_" + i); + // set tags + pstmt.setTagFloat(0, random.nextFloat()); + pstmt.setTagDouble(1, random.nextDouble()); + // set columns + ArrayList tsList = new ArrayList<>(); + long current = System.currentTimeMillis(); + for (int j = 0; j < numOfRow; j++) + tsList.add(current + j); + pstmt.setTimestamp(0, tsList); + + ArrayList f1List = new ArrayList<>(); + for (int j = 0; j < numOfRow; j++) + f1List.add(random.nextFloat()); + pstmt.setFloat(1, f1List); + + ArrayList f2List = new ArrayList<>(); + for (int j = 0; j < numOfRow; j++) + f2List.add(random.nextDouble()); + pstmt.setDouble(2, f2List); + + // add column + pstmt.columnDataAddBatch(); + } + // execute + pstmt.columnDataExecuteBatch(); + // close if no try-with-catch statement is used + pstmt.close(); + } + + private static void bindBoolean(Connection conn) throws SQLException { + String sql = "insert into ? using stable3 tags(?) values(?,?)"; + + try (TSDBPreparedStatement pstmt = conn.prepareStatement(sql).unwrap(TSDBPreparedStatement.class)) { + for (int i = 1; i <= numOfSubTable; i++) { + // set table name + pstmt.setTableName("t3_" + i); + // set tags + pstmt.setTagBoolean(0, random.nextBoolean()); + // set columns + ArrayList tsList = new ArrayList<>(); + long current = System.currentTimeMillis(); + for (int j = 0; j < numOfRow; j++) + tsList.add(current + j); + pstmt.setTimestamp(0, tsList); + + ArrayList f1List = new ArrayList<>(); + for (int j = 0; j < numOfRow; j++) + f1List.add(random.nextBoolean()); + pstmt.setBoolean(1, f1List); + + // add column + pstmt.columnDataAddBatch(); + } + // execute + pstmt.columnDataExecuteBatch(); + } + } + + private static void bindBytes(Connection conn) throws SQLException { + String sql = "insert into ? using stable4 tags(?) values(?,?)"; + + try (TSDBPreparedStatement pstmt = conn.prepareStatement(sql).unwrap(TSDBPreparedStatement.class)) { + + for (int i = 1; i <= numOfSubTable; i++) { + // set table name + pstmt.setTableName("t4_" + i); + // set tags + pstmt.setTagString(0, new String("abc")); + + // set columns + ArrayList tsList = new ArrayList<>(); + long current = System.currentTimeMillis(); + for (int j = 0; j < numOfRow; j++) + tsList.add(current + j); + pstmt.setTimestamp(0, tsList); + + ArrayList f1List = new ArrayList<>(); + for (int j = 0; j < numOfRow; j++) { + f1List.add(new String("abc")); + } + pstmt.setString(1, f1List, BINARY_COLUMN_SIZE); + + // add column + pstmt.columnDataAddBatch(); + } + // execute + pstmt.columnDataExecuteBatch(); + } + } + + private static void bindString(Connection conn) throws SQLException { + String sql = "insert into ? using stable5 tags(?) values(?,?)"; + + try (TSDBPreparedStatement pstmt = conn.prepareStatement(sql).unwrap(TSDBPreparedStatement.class)) { + + for (int i = 1; i <= numOfSubTable; i++) { + // set table name + pstmt.setTableName("t5_" + i); + // set tags + pstmt.setTagNString(0, "北京-abc"); + + // set columns + ArrayList tsList = new ArrayList<>(); + long current = System.currentTimeMillis(); + for (int j = 0; j < numOfRow; j++) + tsList.add(current + j); + pstmt.setTimestamp(0, tsList); + + ArrayList f1List = new ArrayList<>(); + for (int j = 0; j < numOfRow; j++) { + f1List.add("北京-abc"); + } + pstmt.setNString(1, f1List, BINARY_COLUMN_SIZE); + + // add column + pstmt.columnDataAddBatch(); + } + // execute + pstmt.columnDataExecuteBatch(); + } + } +} +``` + +用于设定 TAGS 取值的方法总共有： + +```java +public void setTagNull(int index, int type) +public void setTagBoolean(int index, boolean value) +public void setTagInt(int index, int value) +public void setTagByte(int index, byte value) +public void setTagShort(int index, short value) +public void setTagLong(int index, long value) +public void setTagTimestamp(int index, long value) +public void setTagFloat(int index, float value) +public void setTagDouble(int index, double value) +public void setTagString(int index, String value) +public void setTagNString(int index, String value) +``` + +用于设定 VALUES 数据列的取值的方法总共有： + +```java +public void setInt(int columnIndex, ArrayList list) throws SQLException +public void setFloat(int columnIndex, ArrayList list) throws SQLException +public void setTimestamp(int columnIndex, ArrayList list) throws SQLException +public void setLong(int columnIndex, ArrayList list) throws SQLException +public void setDouble(int columnIndex, ArrayList list) throws SQLException +public void setBoolean(int columnIndex, ArrayList list) throws SQLException +public void setByte(int columnIndex, ArrayList list) throws SQLException +public void setShort(int columnIndex, ArrayList list) throws SQLException +public void setString(int columnIndex, ArrayList list, int size) throws SQLException +public void setNString(int columnIndex, ArrayList list, int size) throws SQLException +``` + +### 无模式写入 + +从 2.2.0.0 版本开始，TDengine 增加了对无模式写入功能。无模式写入兼容 InfluxDB 的 行协议（Line Protocol）、OpenTSDB 的 telnet 行协议和 OpenTSDB 的 JSON 格式协议。详情请参见[无模式写入](/reference/schemaless/)。 + +**注意**： + +- JDBC REST 连接目前不支持无模式写入 +- 以下示例代码基于 taos-jdbcdriver-2.0.36 + +```java +public class SchemalessInsertTest { + private static final String host = "127.0.0.1"; + private static final String lineDemo = "st,t1=3i64,t2=4f64,t3=\"t3\" c1=3i64,c3=L\"passit\",c2=false,c4=4f64 1626006833639000000"; + private static final String telnetDemo = "stb0_0 1626006833 4 host=host0 interface=eth0"; + private static final String jsonDemo = "{\"metric\": \"meter_current\",\"timestamp\": 1346846400,\"value\": 10.3, \"tags\": {\"groupid\": 2, \"location\": \"Beijing\", \"id\": \"d1001\"}}"; + + public static void main(String[] args) throws SQLException { + final String url = "jdbc:TAOS://" + host + ":6030/?user=root&password=taosdata"; + try (Connection connection = DriverManager.getConnection(url)) { + init(connection); + + SchemalessWriter writer = new SchemalessWriter(connection); + writer.write(lineDemo, SchemalessProtocolType.LINE, SchemalessTimestampType.NANO_SECONDS); + writer.write(telnetDemo, SchemalessProtocolType.TELNET, SchemalessTimestampType.MILLI_SECONDS); + writer.write(jsonDemo, SchemalessProtocolType.JSON, SchemalessTimestampType.NOT_CONFIGURED); + } + } + + private static void init(Connection connection) throws SQLException { + try (Statement stmt = connection.createStatement()) { + stmt.executeUpdate("drop database if exists test_schemaless"); + stmt.executeUpdate("create database if not exists test_schemaless"); + stmt.executeUpdate("use test_schemaless"); + } + } +} +``` + +### 订阅 + +TDengine Java 连接器支持订阅功能，应用 API 如下： + +#### 创建订阅 + +```java +TSDBSubscribe sub = ((TSDBConnection)conn).subscribe("topic", "select * from meters", false); +``` + +`subscribe` 方法的三个参数含义如下： + +- topic：订阅的主题（即名称），此参数是订阅的唯一标识 +- sql：订阅的查询语句，此语句只能是 `select` 语句，只应查询原始数据，只能按时间正序查询数据 +- restart：如果订阅已经存在，是重新开始，还是继续之前的订阅 + +如上面的例子将使用 SQL 语句 `select * from meters` 创建一个名为 `topic` 的订阅，如果这个订阅已经存在，将继续之前的查询进度，而不是从头开始消费所有的数据。 + +#### 订阅消费数据 + +```java +int total = 0; +while(true) { + TSDBResultSet rs = sub.consume(); + int count = 0; + while(rs.next()) { + count++; + } + total += count; + System.out.printf("%d rows consumed, total %d\n", count, total); + Thread.sleep(1000); +} +``` + +`consume` 方法返回一个结果集，其中包含从上次 `consume` 到目前为止的所有新数据。请务必按需选择合理的调用 `consume` 的频率（如例子中的 `Thread.sleep(1000)`），否则会给服务端造成不必要的压力。 + +#### 关闭订阅 + +```java +sub.close(true); +``` + +`close` 方法关闭一个订阅。如果其参数为 `true` 表示保留订阅进度信息，后续可以创建同名订阅继续消费数据；如为 `false` 则不保留订阅进度。 + +### 关闭资源 + +```java +resultSet.close(); +stmt.close(); +conn.close(); +``` + +> `注意务必要将 connection 进行关闭`，否则会出现连接泄露。 + +### 与连接池使用 + +#### HikariCP + +使用示例如下： + +```java + public static void main(String[] args) throws SQLException { + HikariConfig config = new HikariConfig(); + // jdbc properties + config.setJdbcUrl("jdbc:TAOS://127.0.0.1:6030/log"); + config.setUsername("root"); + config.setPassword("taosdata"); + // connection pool configurations + config.setMinimumIdle(10); //minimum number of idle connection + config.setMaximumPoolSize(10); //maximum number of connection in the pool + config.setConnectionTimeout(30000); //maximum wait milliseconds for get connection from pool + config.setMaxLifetime(0); // maximum life time for each connection + config.setIdleTimeout(0); // max idle time for recycle idle connection + config.setConnectionTestQuery("select server_status()"); //validation query + + HikariDataSource ds = new HikariDataSource(config); //create datasource + + Connection connection = ds.getConnection(); // get connection + Statement statement = connection.createStatement(); // get statement + + //query or insert + // ... + + connection.close(); // put back to conneciton pool +} +``` + +> 通过 HikariDataSource.getConnection() 获取连接后，使用完成后需要调用 close() 方法，实际上它并不会关闭连接，只是放回连接池中。 +> 更多 HikariCP 使用问题请查看[官方说明](https://github.com/brettwooldridge/HikariCP)。 + +#### Druid + +使用示例如下： + +```java +public static void main(String[] args) throws Exception { + + DruidDataSource dataSource = new DruidDataSource(); + // jdbc properties + dataSource.setDriverClassName("com.taosdata.jdbc.TSDBDriver"); + dataSource.setUrl(url); + dataSource.setUsername("root"); + dataSource.setPassword("taosdata"); + // pool configurations + dataSource.setInitialSize(10); + dataSource.setMinIdle(10); + dataSource.setMaxActive(10); + dataSource.setMaxWait(30000); + dataSource.setValidationQuery("select server_status()"); + + Connection connection = dataSource.getConnection(); // get connection + Statement statement = connection.createStatement(); // get statement + //query or insert + // ... + + connection.close(); // put back to conneciton pool +} +``` + +> 更多 druid 使用问题请查看[官方说明](https://github.com/alibaba/druid)。 + +**注意事项：** + +- TDengine `v1.6.4.1` 版本开始提供了一个专门用于心跳检测的函数 `select server_status()`，所以在使用连接池时推荐使用 `select server_status()` 进行 Validation Query。 + +如下所示，`select server_status()` 执行成功会返回 `1`。 + +```sql +taos> select server_status(); +server_status()| +================ +1 | +Query OK, 1 row(s) in set (0.000141s) +``` + +### 更多示例程序 + +示例程序源码位于 `TDengine/examples/JDBC` 下: + +- JDBCDemo：JDBC 示例源程序。 +- JDBCConnectorChecker：JDBC 安装校验源程序及 jar 包。 +- connectionPools：HikariCP, Druid, dbcp, c3p0 等连接池中使用 taos-jdbcdriver。 +- SpringJdbcTemplate：Spring JdbcTemplate 中使用 taos-jdbcdriver。 +- mybatisplus-demo：Springboot + Mybatis 中使用 taos-jdbcdriver。 + +请参考：[JDBC example](https://github.com/taosdata/TDengine/tree/develop/examples/JDBC) + +## 最近更新记录 + +| taos-jdbcdriver 版本 | 主要变化 | +| :------------------: | :----------------------------: | +| 2.0.38 | JDBC REST 连接增加批量拉取功能 | +| 2.0.37 | 增加对 json tag 支持 | +| 2.0.36 | 增加对 schemaless 写入支持 | + +## 常见问题 + +1. 使用 Statement 的 `addBatch()` 和 `executeBatch()` 来执行“批量写入/更新”，为什么没有带来性能上的提升？ + + **原因**：TDengine 的 JDBC 实现中，通过 `addBatch` 方法提交的 SQL 语句，会按照添加的顺序，依次执行，这种方式没有减少与服务端的交互次数，不会带来性能上的提升。 + + **解决方法**：1. 在一条 insert 语句中拼接多个 values 值；2. 使用多线程的方式并发插入；3. 使用参数绑定的写入方式 + +2. java.lang.UnsatisfiedLinkError: no taos in java.library.path + + **原因**：程序没有找到依赖的本地函数库 taos。 + + **解决方法**：Windows 下可以将 C:\TDengine\driver\taos.dll 拷贝到 C:\Windows\System32\ 目录下，Linux 下将建立如下软链 `ln -s /usr/local/taos/driver/libtaos.so.x.x.x.x /usr/lib/libtaos.so` 即可。 + +3. java.lang.UnsatisfiedLinkError: taos.dll Can't load AMD 64 bit on a IA 32-bit platform + + **原因**：目前 TDengine 只支持 64 位 JDK。 + + **解决方法**：重新安装 64 位 JDK。 + +4. 其它问题请参考 [FAQ](/train-faq/faq) + +## API 参考 + +[taos-jdbcdriver doc](https://docs.taosdata.com/api/taos-jdbcdriver) diff --git a/docs-cn/14-reference/03-connector/node.mdx b/docs-cn/14-reference/03-connector/node.mdx new file mode 100644 index 0000000000000000000000000000000000000000..12345fa9fe995c41828df07703f0efb61a2e029d --- /dev/null +++ b/docs-cn/14-reference/03-connector/node.mdx @@ -0,0 +1,259 @@ +--- +toc_max_heading_level: 4 +sidebar_position: 6 +sidebar_label: Node.js +title: TDengine Node.js Connector +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +import Preparition from "./_preparition.mdx"; +import NodeInsert from "../../07-develop/03-insert-data/_js_sql.mdx"; +import NodeInfluxLine from "../../07-develop/03-insert-data/_js_line.mdx"; +import NodeOpenTSDBTelnet from "../../07-develop/03-insert-data/_js_opts_telnet.mdx"; +import NodeOpenTSDBJson from "../../07-develop/03-insert-data/_js_opts_json.mdx"; +import NodeQuery from "../../07-develop/04-query-data/_js.mdx"; +import NodeAsyncQuery from "../../07-develop/04-query-data/_js_async.mdx"; + +`td2.0-connector` 和 `td2.0-rest-connector` 是 TDengine 的官方 Node.js 语言连接器。Node.js 开发人员可以通过它开发可以存取 TDengine 集群数据的应用软件。 + +`td2.0-connector` 是**原生连接器**，它通过 TDengine 客户端驱动程序（taosc）连接 TDengine 运行实例，支持数据写入、查询、订阅、schemaless 接口和参数绑定接口等功能。`td2.0-rest-connector` 是 **REST 连接器**，它通过 taosAdapter 提供的 REST 接口连接 TDengine 的运行实例。REST 连接器可以在任何平台运行，但性能略为下降，接口实现的功能特性集合和原生接口有少量不同。 + +Node.js 连接器源码托管在 [GitHub](https://github.com/taosdata/taos-connector-node)。 + +## 支持的平台 + +原生连接器支持的平台和 TDengine 客户端驱动支持的平台一致。 +REST 连接器支持所有能运行 Node.js 的平台。 + +## 版本支持 + +请参考[版本支持列表](/reference/connector#版本支持) + +## 支持的功能特性 + +### 原生连接器 + +1. 连接管理 +2. 普通查询 +3. 连续查询 +4. 参数绑定 +5. 订阅功能 +6. Schemaless + +### REST 连接器 + +1. 连接管理 +2. 普通查询 +3. 连续查询 + +## 安装步骤 + +### 安装前准备 + +- 安装 Node.js 开发环境 +- 如果使用 REST 连接器，跳过此步。但如果使用原生连接器，请安装 TDengine 客户端驱动，具体步骤请参考[安装客户端驱动](/reference/connector#安装客户端驱动)。我们使用 [node-gyp](https://github.com/nodejs/node-gyp) 和 TDengine 实例进行交互，还需要根据具体操作系统来安装下文提到的一些依赖工具。 + + + + +- `python` (建议`v2.7` , `v3.x.x` 目前还不支持) +- `td2.0-connector` 2.0.6 支持 Node.js LTS v10.9.0 或更高版本, Node.js LTS v12.8.0 或更高版本；2.0.5 及更早版本支持 Node.js LTS v10.x 版本。其他版本可能存在包兼容性的问题 +- `make` +- C 语言编译器，[GCC](https://gcc.gnu.org) v4.8.5 或更高版本 + + + + +- 安装方法 1 + +使用微软的[ windows-build-tools ](https://github.com/felixrieseberg/windows-build-tools)在`cmd` 命令行界面执行`npm install --global --production windows-build-tools` 即可安装所有的必备工具。 + +- 安装方法 2 + +手动安装以下工具： + +- 安装 Visual Studio 相关：[Visual Studio Build 工具](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=BuildTools) 或者 [Visual Studio 2017 Community](https://visualstudio.microsoft.com/pl/thank-you-downloading-visual-studio/?sku=Community) +- 安装 [Python](https://www.python.org/downloads/) 2.7(`v3.x.x` 暂不支持) 并执行 `npm config set python python2.7` +- 进入`cmd`命令行界面，`npm config set msvs_version 2017` + +参考微软的 Node.js 用户手册[ Microsoft's Node.js Guidelines for Windows](https://github.com/Microsoft/nodejs-guidelines/blob/master/windows-environment.md#compiling-native-addon-modules)。 + +如果在 Windows 10 ARM 上使用 ARM64 Node.js，还需添加 "Visual C++ compilers and libraries for ARM64" 和 "Visual C++ ATL for ARM64"。 + + + + +### 使用 npm 安装 + + + + +```bash +npm install td2.0-connector +``` + + + + +```bash +npm i td2.0-rest-connector +``` + + + + +### 安装验证 + +在安装好 TDengine 客户端后，使用 nodejsChecker.js 程序能够验证当前环境是否支持 Node.js 方式访问 TDengine。 + +验证方法： + +- 新建安装验证目录，例如：`~/tdengine-test`，下载 GitHub 上 [nodejsChecker.js 源代码](https://github.com/taosdata/TDengine/tree/develop/examples/nodejs/nodejsChecker.js)到本地。 + +- 在命令行中执行以下命令。 + +```bash +npm init -y +npm install td2.0-connector +node nodejsChecker.js host=localhost +``` + +- 执行以上步骤后，在命令行会输出 nodejsChecker.js 连接 TDengine 实例，并执行简单插入和查询的结果。 + +## 建立连接 + +请选择使用一种连接器。 + + + + +安装并引用 `td2.0-connector` 包。 + +```javascript +//A cursor also needs to be initialized in order to interact with TDengine from Node.js. +const taos = require("td2.0-connector"); +var conn = taos.connect({ + host: "127.0.0.1", + user: "root", + password: "taosdata", + config: "/etc/taos", + port: 0, +}); +var cursor = conn.cursor(); // Initializing a new cursor + +//Close a connection +conn.close(); +``` + + + + +安装并引用 `td2.0-rest-connector` 包。 + +```javascript +//A cursor also needs to be initialized in order to interact with TDengine from Node.js. +import { options, connect } from "td2.0-rest-connector"; +options.path = "/rest/sqlt"; +// set host +options.host = "localhost"; +// set other options like user/passwd + +let conn = connect(options); +let cursor = conn.cursor(); +``` + + + + +## 使用示例 + +### 写入数据 + +#### SQL 写入 + + + +#### InfluxDB 行协议写入 + + + +#### OpenTSDB Telnet 行协议写入 + + + +#### OpenTSDB JSON 行协议写入 + + + +### 查询数据 + +#### 同步查询 + + + +#### 异步查询 + + + +## 更多示例程序 + +| 示例程序 | 示例程序描述 | +| ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------- | +| [connection](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/cursorClose.js) | 建立连接的示例。 | +| [stmtBindBatch](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/stmtBindParamBatchSample.js) | 绑定多行参数插入的示例。 | +| [stmtBind](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/stmtBindParamSample.js) | 一行一行绑定参数插入的示例。 | +| [stmtBindSingleParamBatch](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/stmtBindSingleParamBatchSample.js) | 按列绑定参数插入的示例。 | +| [stmtUseResult](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/stmtUseResultSample.js) | 绑定参数查询的示例。 | +| [json tag](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/testJsonTag.js) | Json tag 的使用示例。 | +| [Nanosecond](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/testNanoseconds.js) | 时间戳为纳秒精度的使用的示例。 | +| [Microsecond](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/testMicroseconds.js) | 时间戳为微秒精度的使用的示例。 | +| [schemless insert](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/testSchemalessInsert.js) | schemless 插入的示例。 | +| [subscribe](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/testSubscribe.js) | 订阅的使用示例。 | +| [asyncQuery](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/tset.js) | 异步查询的使用示例。 | +| [REST](https://github.com/taosdata/taos-connector-node/blob/develop/typescript-rest/example/example.ts) | 使用 REST 连接的 TypeScript 使用示例。 | + +## 使用限制 + +Node.js 连接器 >= v2.0.6 目前支持 node 的版本为：支持 >=v12.8.0 <= v12.9.1 || >=v10.20.0 <= v10.9.0 ；2.0.5 及更早版本支持 v10.x 版本，其他版本可能存在包兼容性的问题。 + +## 其他说明 + +Node.js 连接器的使用参见[视频教程](https://www.taosdata.com/blog/2020/11/11/1957.html)。 + +## 常见问题 + +1. 使用 REST 连接需要启动 taosadapter。 + + ```bash + sudo systemctl start taosadapter + ``` + +2. Node.js 版本 + + 连接器 >v2.0.6 目前兼容的 Node.js 版本为：>=v10.20.0 <= v10.9.0 || >=v12.8.0 <= v12.9.1 + +3. "Unable to establish connection"，"Unable to resolve FQDN" + + 一般都是因为配置 FQDN 不正确。 可以参考[如何彻底搞懂 TDengine 的 FQDN](https://www.taosdata.com/blog/2021/07/29/2741.html) 。 + +## 重要更新记录 + +### 原生连接器 + +| td2.0-connector 版本 | 说明 | +| -------------------- | ---------------------------------------------------------------- | +| 2.0.12 | 修复 cursor.close() 报错的 bug。 | +| 2.0.11 | 支持绑定参数、json tag、schemaless 接口等功能。 | +| 2.0.10 | 支持连接管理，普通查询、连续查询、获取系统信息、订阅功能等功能。 | + +### REST 连接器 + +| td2.0-rest-connector 版本 | 说明 | +| ------------------------- | ---------------------------------------------------------------- | +| 1.0.3 | 支持连接管理、普通查询、获取系统信息、错误信息、连续查询等功能。 | + +## API 参考 + +[API 参考](https://docs.taosdata.com/api/td2.0-connector/) diff --git a/docs-cn/14-reference/03-connector/python.mdx b/docs-cn/14-reference/03-connector/python.mdx new file mode 100644 index 0000000000000000000000000000000000000000..6608fb7bd21ab586216d82c1b137830576a1e432 --- /dev/null +++ b/docs-cn/14-reference/03-connector/python.mdx @@ -0,0 +1,349 @@ +--- +sidebar_position: 3 +sidebar_label: Python +title: TDengine Python Connector +description: "taospy 是 TDengine 的官方 Python 连接器。taospy 提供了丰富的 API， 使得 Python 应用可以很方便地使用 TDengine。tasopy 对 TDengine 的原生接口和 REST 接口都进行了封装， 分别对应 tasopy 的两个子模块：tasos 和 taosrest。除了对原生接口和 REST 接口的封装，taospy 还提供了符合 Python 数据访问规范(PEP 249)的编程接口。这使得 taospy 和很多第三方工具集成变得简单，比如 SQLAlchemy 和 pandas" +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +`taospy` 是 TDengine 的官方 Python 连接器。`taospy` 提供了丰富的 API， 使得 Python 应用可以很方便地使用 TDengine。`taospy` 对 TDengine 的[原生接口](/reference/connector/cpp)和 [REST 接口](/reference/rest-api)都进行了封装， 分别对应 `taospy` 包的 `taos` 模块 和 `taosrest` 模块。 +除了对原生接口和 REST 接口的封装，`taospy` 还提供了符合 [Python 数据访问规范(PEP 249)](https://peps.python.org/pep-0249/) 的编程接口。这使得 `taospy` 和很多第三方工具集成变得简单，比如 [SQLAlchemy](https://www.sqlalchemy.org/) 和 [pandas](https://pandas.pydata.org/)。 + +使用客户端驱动提供的原生接口直接与服务端建立的连接的方式下文中称为“原生连接”；使用 taosAdapter 提供的 REST 接口与服务端建立的连接的方式下文中称为“REST 连接”。 + +Python 连接器的源码托管在 [GitHub](https://github.com/taosdata/taos-connector-python)。 + +## 支持的平台 + +- 原生连接[支持的平台](/reference/connector/#支持的平台)和 TDengine 客户端支持的平台一致。 +- REST 连接支持所有能运行 Python 的平台。 + +## 版本选择 + +无论使用什么版本的 TDengine 都建议使用最新版本的 `taospy`。 + +## 支持的功能 + +- 原生连接支持 TDeingine 的所有核心功能， 包括： 连接管理、执行 SQL、参数绑定、订阅、无模式写入（schemaless）。 +- REST 连接支持的功能包括：连接管理、执行 SQL。 (通过执行 SQL 可以： 管理数据库、管理表和超级表、写入数据、查询数据、创建连续查询等)。 + +## 安装 + +### 准备 + +1. 安装 Python。建议使用 Python >= 3.6。如果系统上还没有 Python 可参考 [Python BeginnersGuide](https://wiki.python.org/moin/BeginnersGuide/Download) 安装。 +2. 安装 [pip](https://pypi.org/project/pip/)。大部分情况下 Python 的安装包都自带了 pip 工具， 如果没有请参考 [pip docuemntation](https://pip.pypa.io/en/stable/installation/) 安装。 +3. 如果使用原生连接，还需[安装客户端驱动](../#安装客户端驱动)。客户端软件包含了 TDengine 客户端动态链接库(libtaos.so 或 taos.dll) 和 TDengine CLI。 + +### 使用 pip 安装 + +#### 卸载旧版本 + +如果以前安装过旧版本的 Python 连接器, 请提前卸载。 + +``` +pip3 uninstall taos taospy +``` + +:::note +较早的 TDengine 客户端软件包含了 Python 连接器。如果从客户端软件的安装目录安装了 Python 连接器，那么对应的 Python 包名是 `taos`。 所以上述卸载命令包含了 `taos`， 不存在也没关系。 + +::: + +#### 安装 `taospy` + + + + +安装最新版本 + +``` +pip3 install taospy +``` + +也可以指定某个特定版本安装。 + +``` +pip3 install taospy==2.3.0 +``` + + + + +``` +pip3 install git+https://github.com/taosdata/taos-connector-python.git +``` + + + + +### 安装验证 + + + + +对于原生连接，需要验证客户端驱动和 Python 连接器本身是否都正确安装。如果能成功导入 `taos` 模块，则说明已经正确安装了客户端驱动和 Python 连接器。可在 Python 交互式 Shell 中输入： + +```python +import taos +``` + + + + +对于 REST 连接，只需验证是否能成功导入 `taosrest` 模块。可在 Python 交互式 Shell 中输入： + +```python +import taosrest +``` + + + + +:::tip +如果系统上有多个版本的 Python，则可能有多个 `pip` 命令。要确保使用的 `pip` 命令路径是正确的。上面我们用 `pip3` 命令安装，排除了使用 Python 2.x 版本对应的 `pip` 的可能性。但是如果系统上有多个 Python 3.x 版本，仍需检查安装路径是否正确。最简单的验证方式是，在命令再次输入 `pip3 install taospy`, 就会打印出 `taospy` 的具体安装位置，比如在 Windows 上： + +``` +C:\> pip3 install taospy +Looking in indexes: https://pypi.tuna.tsinghua.edu.cn/simple +Requirement already satisfied: taospy in c:\users\username\appdata\local\programs\python\python310\lib\site-packages (2.3.0) +``` + +::: + +## 建立连接 + +### 连通性测试 + +在用连接器建立连接之前，建议先测试本地 TDengine CLI 到 TDengine 集群的连通性。 + + + + +请确保 TDengine 集群已经启动， 且集群中机器的 FQDN （如果启动的是单机版，FQDN 默认为 hostname）在本机能够解析, 可用 `ping` 命令进行测试： + +``` +ping +``` + +然后测试用 TDengine CLI 能否正常连接集群： + +``` +taos -h -p +``` + +上面的 FQDN 可以为集群中任意一个 dnode 的 FQDN， PORT 为这个 dnode 对应的 serverPort。 + + + + +对于 REST 连接， 除了确保集群已经启动，还要确保 taosAdapter 组件已经启动。可以使用如下 curl 命令测试： + +``` +curl -u root:taosdata http://:/rest/sql -d "select server_version()" +``` + +上面的 FQDN 为运行 taosAdapter 的机器的 FQDN， PORT 为 taosAdapter 配置的监听端口， 默认为 6041。 +如果测试成功，会输出服务器版本信息，比如： + +```json +{ + "status": "succ", + "head": ["server_version()"], + "column_meta": [["server_version()", 8, 8]], + "data": [["2.4.0.16"]], + "rows": 1 +} +``` + + + + +### 使用连接器建立连接 + +以下示例代码假设 TDengine 安装在本机， 且 FQDN 和 serverPort 都使用了默认配置。 + + + + +```python +{{#include docs-examples/python/connect_native_reference.py}} +``` + +`connect` 函数的所有参数都是可选的关键字参数。下面是连接参数的具体说明： + +- `host` ： 要连接的节点的 FQDN。 没有默认值。如果不同提供此参数，则会连接客户端配置文件中的 firstEP。 +- `user` ：TDengine 用户名。 默认值是 root。 +- `password` ： TDengine 用户密码。 默认值是 taosdata。 +- `port` ： 要连接的数据节点的起始端口，即 serverPort 配置。默认值是 6030。只有在提供了 host 参数的时候，这个参数才生效。 +- `config` ： 客户端配置文件路径。 在 Windows 系统上默认是 `C:\TDengine\cfg`。 在 Linux 系统上默认是 `/etc/taos/`。 +- `timezone` ： 查询结果中 TIMESTAMP 类型的数据，转换为 python 的 datetime 对象时使用的时区。默认为本地时区。 + +:::warning +`config` 和 `timezone` 都是进程级别的配置。建议一个进程建立的所有连接都使用相同的参数值。否则可能产生无法预知的错误。 +::: + +:::tip +`connect` 函数返回 `taos.TaosConnection` 实例。 在客户端多线程的场景下，推荐每个线程申请一个独立的连接实例，而不建议多线程共享一个连接。 + +::: + + + + +```python +{{#include docs-examples/python/connect_rest_examples.py:connect}} +``` + +`connect()` 函数的所有参数都是可选的关键字参数。下面是连接参数的具体说明： + +- `host`： 要连接的主机。默认是 localhost。 +- `user`： TDenigne 用户名。默认是 root。 +- `password`： TDeingine 用户密码。默认是 taosdata。 +- `port`: taosAdapter REST 服务监听端口。默认是 6041. +- `timeout`: HTTP 请求超时时间。单位为秒。默认为 `socket._GLOBAL_DEFAULT_TIMEOUT`。 一般无需配置。 + + + + +## 示例程序 + +### 基本使用 + + + + +##### TaosConnection 类的使用 + +`TaosConnection` 类既包含对 PEP249 Connection 接口的实现(如：`cursor`方法和 `close` 方法)，也包含很多扩展功能（如： `execute`、 `query`、`schemaless_insert` 和 `subscribe` 方法。 + +```python title="execute 方法" +{{#include docs-examples/python/connection_usage_native_reference.py:insert}} +``` + +```python title="query 方法" +{{#include docs-examples/python/connection_usage_native_reference.py:query}} +``` + +:::tip +查询结果只能获取一次。比如上面的示例中 `fetch_all()` 和 `fetch_all_into_dict()` 只能用一个。重复获取得到的结果为空列表。 +::: + +##### TaosResult 类的使用 + +上面 `TaosConnection` 类的使用示例中，我们已经展示了两种获取查询结果的方法： `fetch_all()` 和 `fetch_all_into_dict()`。除此之外 `TaosResult` 还提供了按行迭代(`rows_iter`)或按数据块迭代(`blocks_iter`)结果集的方法。在查询数据量较大的场景，使用这两个方法会更高效。 + +```python title="blocks_iter 方法" +{{#include docs-examples/python/result_set_examples.py}} +``` +##### TaosCursor 类的使用 + +`TaosConnection` 类和 `TaosResult` 类已经实现了原生接口的所有功能。如果你对 PEP249 规范中的接口比较熟悉也可以使用 `TaosCursor` 类提供的方法。 + +```python title="TaosCursor 的使用" +{{#include docs-examples/python/cursor_usage_native_reference.py}} +``` + +:::note +TaosCursor 类使用原生连接进行写入、查询操作。在客户端多线程的场景下，这个游标实例必须保持线程独享，不能跨线程共享使用，否则会导致返回结果出现错误。 + +::: + + + + +##### TaosRestCursor 类的使用 + +`TaosRestCursor` 类是对 PEP249 Cursor 接口的实现。 + +```python title="TaosRestCursor 的使用" +{{#include docs-examples/python/connect_rest_examples.py:basic}} +``` +- `cursor.execute` ： 用来执行任意 SQL 语句。 +- `cursor.rowcount`： 对于写入操作返回写入成功记录数。对于查询操作，返回结果集行数。 +- `cursor.description` ： 返回字段的描述信息。关于描述信息的具体格式请参考[TaosRestCursor](https://docs.taosdata.com/api/taospy/taosrest/cursor.html)。 + +##### RestClient 类的使用 + +`RestClient` 类是对于 [REST API](/reference/rest-api) 的直接封装。它只包含一个 `sql()` 方法用于执行任意 SQL 语句， 并返回执行结果。 + +```python title="RestClient 的使用" +{{#include docs-examples/python/rest_client_example.py}} +``` + +对于 `sql()` 方法更详细的介绍， 请参考 [RestClient](https://docs.taosdata.com/api/taospy/taosrest/restclient.html)。 + + + + + + +### 与 pandas 一起使用 + + + + +```python +{{#include docs-examples/python/conn_native_pandas.py}} +``` + + + + +```python +{{#include docs-examples/python/conn_rest_pandas.py}} +``` + + + + +### 其它示例程序 + +| 示例程序链接 | 示例程序内容 | +| ------------------------------------------------------------------------------------------------------------- | ----------------------- | +| [bind_multi.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/bind-multi.py) | 参数绑定， 一次绑定多行 | +| [bind_row.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/bind-row.py) | 参数绑定，一次绑定一行 | +| [insert_lines.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/insert-lines.py) | InfluxDB 行协议写入 | +| [json_tag.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/json-tag.py) | 使用 JSON 类型的标签 | +| [subscribe-async.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/subscribe-async.py) | 异步订阅 | +| [subscribe-sync.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/subscribe-sync.py) | 同步订阅 | + +## 其它说明 + +### 异常处理 + +所有数据库操作如果出现异常，都会直接抛出来。由应用程序负责异常处理。比如： + +```python +{{#include docs-examples/python/handle_exception.py}} +``` + +### 关于纳秒 (nanosecond) + +由于目前 Python 对 nanosecond 支持的不完善(见下面的链接)，目前的实现方式是在 nanosecond 精度时返回整数，而不是 ms 和 us 返回的 datetime 类型，应用开发者需要自行处理，建议使用 pandas 的 to_datetime()。未来如果 Python 正式完整支持了纳秒，Python 连接器可能会修改相关接口。 + +1. https://stackoverflow.com/questions/10611328/parsing-datetime-strings-containing-nanoseconds +2. https://www.python.org/dev/peps/pep-0564/ + + +## 常见问题 + +欢迎[提问或报告问题](https://github.com/taosdata/taos-connector-python/issues)。 + +## 重要更新 + +| 连接器版本 | 重要更新 | 发布日期 | +| ---------- | --------------------------------------------------------------------------------- | ---------- | +| 2.3.1 | 1. support TDengine REST API
2. remove support for Python version below 3.6 | 2022-04-28 | +| 2.2.5 | support timezone option when connect | 2022-04-13 | +| 2.2.2 | support sqlalchemy dialect plugin | 2022-03-28 | + + +[**Release Notes**](https://github.com/taosdata/taos-connector-python/releases) + +## API 参考 + +- [taos](https://docs.taosdata.com/api/taospy/taos/) +- [taosrest](https://docs.taosdata.com/api/taospy/taosrest) diff --git a/docs-cn/14-reference/03-connector/rust.mdx b/docs-cn/14-reference/03-connector/rust.mdx new file mode 100644 index 0000000000000000000000000000000000000000..25a8409b6e6faca651d1eaf3e02fbd4a0199c557 --- /dev/null +++ b/docs-cn/14-reference/03-connector/rust.mdx @@ -0,0 +1,388 @@ +--- +toc_max_heading_level: 4 +sidebar_position: 5 +sidebar_label: Rust +title: TDengine Rust Connector +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +import Preparition from "./_preparition.mdx" +import RustInsert from "../../07-develop/03-insert-data/_rust_sql.mdx" +import RustInfluxLine from "../../07-develop/03-insert-data/_rust_line.mdx" +import RustOpenTSDBTelnet from "../../07-develop/03-insert-data/_rust_opts_telnet.mdx" +import RustOpenTSDBJson from "../../07-develop/03-insert-data/_rust_opts_json.mdx" +import RustQuery from "../../07-develop/04-query-data/_rust.mdx" + +[![Crates.io](https://img.shields.io/crates/v/libtaos)](https://crates.io/crates/libtaos) ![Crates.io](https://img.shields.io/crates/d/libtaos) [![docs.rs](https://img.shields.io/docsrs/libtaos)](https://docs.rs/libtaos) + +`libtaos` 是 TDengine 的官方 Rust 语言连接器。Rust 开发人员可以通过它开发存取 TDengine 数据库的应用软件。 + +`libtaos` 提供两种建立连接的方式。一种是**原生连接**，它通过 TDengine 客户端驱动程序（taosc）连接 TDengine 运行实例。另外一种是 **REST 连接**，它通过 taosAdapter 的 REST 接口连接 TDengine 运行实例。你可以通过不同的 “特性（即 Cargo 关键字 features）” 来指定使用哪种连接器。REST 连接支持任何平台，但原生连接支持所有 TDengine 客户端能运行的平台。 + +`libtaos` 的源码托管在 [GitHub](https://github.com/taosdata/libtaos-rs)。 + +## 支持的平台 + +原生连接支持的平台和 TDengine 客户端驱动支持的平台一致。 +REST 连接支持所有能运行 Rust 的平台。 + +## 版本支持 + +请参考[版本支持列表](/reference/connector#版本支持) + +Rust 连接器仍然在快速开发中，1.0 之前无法保证其向后兼容。建议使用 2.4 版本以上的 TDengine，以避免已知问题。 + +## 安装 + +### 安装前准备 +* 安装 Rust 开发工具链 +* 如果使用原生连接，请安装 TDengine 客户端驱动，具体步骤请参考[安装客户端驱动](/reference/connector#安装客户端驱动) + +### 添加 libtaos 依赖 + +根据选择的连接方式，按照如下说明在 [Rust](https://rust-lang.org) 项目中添加 [libtaos][libtaos] 依赖： + + + + +在 `Cargo.toml` 文件中添加 [libtaos][libtaos]： + +```toml +[dependencies] +# use default feature +libtaos = "*" +``` + + + + +在 `Cargo.toml` 文件中添加 [libtaos][libtaos]，并启用 `rest` 特性。 + +```toml +[dependencies] +# use rest feature +libtaos = { version = "*", features = ["rest"]} +``` + + + + + +### 使用连接池 + +请在 `Cargo.toml` 中启用 `r2d2` 特性。 + +```toml +[dependencies] +# with taosc +libtaos = { version = "*", features = ["r2d2"] } +# or rest +libtaos = { version = "*", features = ["rest", "r2d2"] } +``` + +## 建立连接 + +[TaosCfgBuilder] 为使用者提供构造器形式的 API，以便于后续创建连接或使用连接池。 + +```rust +let cfg: TaosCfg = TaosCfgBuilder::default() + .ip("127.0.0.1") + .user("root") + .pass("taosdata") + .db("log") // do not set if not require a default database. + .port(6030u16) + .build() + .expect("TaosCfg builder error"); +} +``` + +现在您可以使用该对象创建连接： + +```rust +let conn = cfg.connect()?; +``` + +连接对象可以创建多个： + +```rust +let conn = cfg.connect()?; +let conn2 = cfg.connect()?; +``` + +可以在应用中使用连接池： + +```rust +let pool = r2d2::Pool::builder() + .max_size(10000) // max connections + .build(cfg)?; + +// ... +// Use pool to get connection +let conn = pool.get()?; +``` + +之后您可以对数据库进行相关操作： + +```rust +async fn demo() -> Result<(), Error> { + // get connection ... + + // create database + conn.exec("create database if not exists demo").await?; + // change database context + conn.exec("use demo").await?; + // create table + conn.exec("create table if not exists tb1 (ts timestamp, v int)").await?; + // insert + conn.exec("insert into tb1 values(now, 1)").await?; + // query + let rows = conn.query("select * from tb1").await?; + for row in rows.rows { + println!("{}", row.into_iter().join(",")); + } +} +``` + +## 使用示例 + +### 写入数据 + +#### SQL 写入 + + + +#### InfluxDB 行协议写入 + + + +#### OpenTSDB Telnet 行协议写入 + + + +#### OpenTSDB JSON 行协议写入 + + + +### 查询数据 + + + +### 更多示例程序 + +| 程序路径 | 程序说明 | +| -------------- | ----------------------------------------------------------------------------- | +| [demo.rs] | 基本API 使用示例 | +| [bailongma-rs] | 使用 TDengine 作为存储后端的 Prometheus 远程存储 API 适配器，使用 r2d2 连接池 | + +## API 参考 + +### 连接构造器 API + +[Builder Pattern](https://doc.rust-lang.org/1.0.0/style/ownership/builders.html) 构造器模式是 Rust 处理复杂数据类型或可选配置类型的解决方案。[libtaos] 实现中，使用连接构造器 [TaosCfgBuilder] 作为 TDengine Rust 连接器的入口。[TaosCfgBuilder] 提供对服务器、端口、数据库、用户名和密码等的可选配置。 + +使用 `default()` 方法可以构建一个默认参数的 [TaosCfg]，用于后续连接数据库或建立连接池。 + +```rust +let cfg = TaosCfgBuilder::default().build()?; +``` + +使用构造器模式，用户可按需设置： + +```rust +let cfg = TaosCfgBuilder::default() + .ip("127.0.0.1") + .user("root") + .pass("taosdata") + .db("log") + .port(6030u16) + .build()?; +``` + +使用 [TaosCfg] 对象创建 TDengine 连接： + +```rust +let conn: Taos = cfg.connect(); +``` + +### 连接池 + +在复杂应用中，建议启用连接池。[libtaos] 的连接池使用 [r2d2] 实现。 + +如下，可以生成一个默认参数的连接池。 + +```rust +let pool = r2d2::Pool::new(cfg)?; +``` + +同样可以使用连接池的构造器，对连接池参数进行设置： + +```rust + use std::time::Duration; + let pool = r2d2::Pool::builder() + .max_size(5000) // max connections + .max_lifetime(Some(Duration::from_minutes(100))) // lifetime of each connection + .min_idle(Some(1000)) // minimal idle connections + .connection_timeout(Duration::from_minutes(2)) + .build(cfg); +``` + +在应用代码中，使用 `pool.get()?` 来获取一个连接对象 [Taos]。 + +```rust +let taos = pool.get()?; +``` + +### 连接 + +[Taos] 结构体是 [libtaos] 中的连接管理者，主要提供了两个 API： + +1. `exec`: 执行某个非查询类 SQL 语句，例如 `CREATE`，`ALTER`，`INSERT` 等。 + + ```rust + taos.exec().await?; + ``` + +2. `query`：执行查询语句，返回 [TaosQueryData] 对象。 + + ```rust + let q = taos.query("select * from log.logs").await?; + ``` + + [TaosQueryData] 对象存储了查询结果数据和返回的列的基本信息（列名，类型，长度）： + + 列信息使用 [ColumnMeta] 存储： + + ```rust + let cols = &q.column_meta; + for col in cols { + println!("name: {}, type: {:?}, bytes: {}", col.name, col.type_, col.bytes); + } + ``` + + 逐行获取数据： + + ```rust + for (i, row) in q.rows.iter().enumerate() { + for (j, cell) in row.iter().enumerate() { + println!("cell({}, {}) data: {}", i, j, cell); + } + } + ``` + +需要注意的是，需要使用 Rust 异步函数和异步运行时。 + +[Taos] 提供部分 SQL 的 Rust 方法化以减少 `format!` 代码块的频率： + +- `.describe(table: &str)`: 执行 `DESCRIBE` 并返回一个 Rust 数据结构。 +- `.create_database(database: &str)`: 执行 `CREATE DATABASE` 语句。 +- `.use_database(database: &str)`: 执行 `USE` 语句。 + +除此之外，该结构也是 [参数绑定](#参数绑定接口) 和 [行协议接口](#行协议接口) 的入口，使用方法请参考具体的 API 说明。 + +### 参数绑定接口 + +与 C 接口类似，Rust 提供参数绑定接口。首先，通过 [Taos] 对象创建一个 SQL 语句的参数绑定对象 [Stmt]： + +```rust +let mut stmt: Stmt = taos.stmt("insert into ? values(?,?)")?; +``` + +参数绑定对象提供了一组接口用于实现参数绑定： + +##### `.set_tbname(tbname: impl ToCString)` + +用于绑定表名。 + +##### `.set_tbname_tags(tbname: impl ToCString, tags: impl IntoParams)` + +当 SQL 语句使用超级表时，用于绑定子表表名和标签值： + +```rust +let mut stmt = taos.stmt("insert into ? using stb0 tags(?) values(?,?)")?; +// tags can be created with any supported type, here is an example using JSON +let v = Field::Json(serde_json::from_str("{\"tag1\":\"一二三四五六七八九十\"}").unwrap()); +stmt.set_tbname_tags("tb0", [&tag])?; +``` + +##### `.bind(params: impl IntoParams)` + +用于绑定值类型。使用 [Field] 结构体构建需要的类型并绑定： + +```rust +let ts = Field::Timestamp(Timestamp::now()); +let value = Field::Float(0.0); +stmt.bind(vec![ts, value].iter())?; +``` + +##### `.execute()` + +执行 SQL。[Stmt] 对象可以复用，在执行后可以重新绑定并执行。 + +```rust +stmt.execute()?; + +// next bind cycle. +//stmt.set_tbname()?; +//stmt.bind()?; +//stmt.execute()?; +``` + +### 行协议接口 + +行协议接口支持多种模式和不同精度，需要引入 schemaless 模块中的常量以进行设置： + +```rust +use libtaos::*; +use libtaos::schemaless::*; +``` + +- InfluxDB 行协议 + + ```rust + let lines = [ + "st,t1=abc,t2=def,t3=anything c1=3i64,c3=L\"pass\",c2=false 1626006833639000000" + "st,t1=abc,t2=def,t3=anything c1=3i64,c3=L\"abc\",c4=4f64 1626006833639000000" + ]; + taos.schemaless_insert(&lines, TSDB_SML_LINE_PROTOCOL, TSDB_SML_TIMESTAMP_NANOSECONDS)?; + ``` + +- OpenTSDB Telnet 协议 + + ```rust + let lines = ["sys.if.bytes.out 1479496100 1.3E3 host=web01 interface=eth0"]; + taos.schemaless_insert(&lines, TSDB_SML_LINE_PROTOCOL, TSDB_SML_TIMESTAMP_SECONDS)?; + ``` + +- OpenTSDB JSON 协议 + + ```rust + let lines = [r#" + { + "metric": "st", + "timestamp": 1626006833, + "value": 10, + "tags": { + "t1": true, + "t2": false, + "t3": 10, + "t4": "123_abc_.!@#$%^&*:;,./?|+-=()[]{}<>" + } + }"#]; + taos.schemaless_insert(&lines, TSDB_SML_LINE_PROTOCOL, TSDB_SML_TIMESTAMP_SECONDS)?; + ``` + +其他相关结构体 API 使用说明请移步 Rust 文档托管网页：。 + +[libtaos]: https://github.com/taosdata/libtaos-rs +[tdengine]: https://github.com/taosdata/TDengine +[bailongma-rs]: https://github.com/taosdata/bailongma-rs +[r2d2]: https://crates.io/crates/r2d2 +[demo.rs]: https://github.com/taosdata/libtaos-rs/blob/main/examples/demo.rs +[TaosCfgBuilder]: https://docs.rs/libtaos/latest/libtaos/struct.TaosCfgBuilder.html +[TaosCfg]: https://docs.rs/libtaos/latest/libtaos/struct.TaosCfg.html +[Taos]: https://docs.rs/libtaos/latest/libtaos/struct.Taos.html +[TaosQueryData]: https://docs.rs/libtaos/latest/libtaos/field/struct.TaosQueryData.html +[Field]: https://docs.rs/libtaos/latest/libtaos/field/enum.Field.html +[Stmt]: https://docs.rs/libtaos/latest/libtaos/stmt/struct.Stmt.html diff --git a/docs-cn/14-reference/03-connector/tdengine-jdbc-connector.png b/docs-cn/14-reference/03-connector/tdengine-jdbc-connector.png new file mode 100644 index 0000000000000000000000000000000000000000..1cb8401ea30b01d8db652ed4ea70ecc511de7461 Binary files /dev/null and b/docs-cn/14-reference/03-connector/tdengine-jdbc-connector.png differ diff --git a/docs-cn/14-reference/04-taosadapter.md b/docs-cn/14-reference/04-taosadapter.md new file mode 100644 index 0000000000000000000000000000000000000000..90a31ec94c94559311e2c91cd34f75af7e87e9a0 --- /dev/null +++ b/docs-cn/14-reference/04-taosadapter.md @@ -0,0 +1,338 @@ +--- +title: "taosAdapter" +description: "taosAdapter 是一个 TDengine 的配套工具，是 TDengine 集群和应用程序之间的桥梁和适配器。它提供了一种易于使用和高效的方式来直接从数据收集代理软件（如 Telegraf、StatsD、collectd 等）摄取数据。它还提供了 InfluxDB/OpenTSDB 兼容的数据摄取接口，允许 InfluxDB/OpenTSDB 应用程序无缝移植到 TDengine" +sidebar_label: "taosAdapter" +--- + +import Prometheus from "./_prometheus.mdx" +import CollectD from "./_collectd.mdx" +import StatsD from "./_statsd.mdx" +import Icinga2 from "./_icinga2.mdx" +import TCollector from "./_tcollector.mdx" + +taosAdapter 是一个 TDengine 的配套工具，是 TDengine 集群和应用程序之间的桥梁和适配器。它提供了一种易于使用和高效的方式来直接从数据收集代理软件（如 Telegraf、StatsD、collectd 等）摄取数据。它还提供了 InfluxDB/OpenTSDB 兼容的数据摄取接口，允许 InfluxDB/OpenTSDB 应用程序无缝移植到 TDengine。 + +taosAdapter 提供以下功能： + +- RESTful 接口 +- 兼容 InfluxDB v1 写接口 +- 兼容 OpenTSDB JSON 和 telnet 格式写入 +- 无缝连接到 Telegraf +- 无缝连接到 collectd +- 无缝连接到 StatsD +- 支持 Prometheus remote_read 和 remote_write + +## taosAdapter 架构图 + +![taosAdapter Architecture](taosAdapter-architecture.png) + +## taosAdapter 部署方法 + +### 安装 taosAdapter + +taosAdapter 从 TDengine v2.4.0.0 版本开始成为 TDengine 服务端软件 的一部分，如果您使用 TDengine server 您不需要任何额外的步骤来安装 taosAdapter。您可以从[涛思数据官方网站](https://taosdata.com/cn/all-downloads/)下载 TDengine server（taosAdapter 包含在 v2.4.0.0 及以上版本）安装包。如果需要将 taosAdapter 分离部署在 TDengine server 之外的服务器上，则应该在该服务器上安装完整的 TDengine 来安装 taosAdapter。如果您需要使用源代码编译生成 taosAdapter，您可以参考[构建 taosAdapter](https://github.com/taosdata/taosadapter/blob/develop/BUILD-CN.md)文档。 + +### start/stop taosAdapter + +在 Linux 系统上 taosAdapter 服务默认由 systemd 管理。使用命令 `systemctl start taosadapter` 可以启动 taosAdapter 服务。使用命令 `systemctl stop taosadapter` 可以停止 taosAdapter 服务。 + +### 移除 taosAdapter + +使用命令 rmtaos 可以移除包括 taosAdapter 在内的 TDengine server 软件。 + +### 升级 taosAdapter + +taosAdapter 和 TDengine server 需要使用相同版本。请通过升级 TDengine server 来升级 taosAdapter。 +与 taosd 分离部署的 taosAdapter 必须通过升级其所在服务器的 TDengine server 才能得到升级。 + +## taosAdapter 参数列表 + +taosAdapter 支持通过命令行参数、环境变量和配置文件来进行配置。默认配置文件是 /etc/taos/taosadapter.toml。 + +命令行参数优先于环境变量优先于配置文件，命令行用法是 arg=val，如 taosadapter -p=30000 --debug=true，详细列表如下： + +```shell +Usage of taosAdapter: + --collectd.db string collectd db name. Env "TAOS_ADAPTER_COLLECTD_DB" (default "collectd") + --collectd.enable enable collectd. Env "TAOS_ADAPTER_COLLECTD_ENABLE" (default true) + --collectd.password string collectd password. Env "TAOS_ADAPTER_COLLECTD_PASSWORD" (default "taosdata") + --collectd.port int collectd server port. Env "TAOS_ADAPTER_COLLECTD_PORT" (default 6045) + --collectd.user string collectd user. Env "TAOS_ADAPTER_COLLECTD_USER" (default "root") + --collectd.worker int collectd write worker. Env "TAOS_ADAPTER_COLLECTD_WORKER" (default 10) + -c, --config string config path default /etc/taos/taosadapter.toml + --cors.allowAllOrigins cors allow all origins. Env "TAOS_ADAPTER_CORS_ALLOW_ALL_ORIGINS" (default true) + --cors.allowCredentials cors allow credentials. Env "TAOS_ADAPTER_CORS_ALLOW_Credentials" + --cors.allowHeaders stringArray cors allow HEADERS. Env "TAOS_ADAPTER_ALLOW_HEADERS" + --cors.allowOrigins stringArray cors allow origins. Env "TAOS_ADAPTER_ALLOW_ORIGINS" + --cors.allowWebSockets cors allow WebSockets. Env "TAOS_ADAPTER_CORS_ALLOW_WebSockets" + --cors.exposeHeaders stringArray cors expose headers. Env "TAOS_ADAPTER_Expose_Headers" + --debug enable debug mode. Env "TAOS_ADAPTER_DEBUG" + --help Print this help message and exit + --influxdb.enable enable influxdb. Env "TAOS_ADAPTER_INFLUXDB_ENABLE" (default true) + --log.path string log path. Env "TAOS_ADAPTER_LOG_PATH" (default "/var/log/taos") + --log.rotationCount uint log rotation count. Env "TAOS_ADAPTER_LOG_ROTATION_COUNT" (default 30) + --log.rotationSize string log rotation size(KB MB GB), must be a positive integer. Env "TAOS_ADAPTER_LOG_ROTATION_SIZE" (default "1GB") + --log.rotationTime duration log rotation time. Env "TAOS_ADAPTER_LOG_ROTATION_TIME" (default 24h0m0s) + --logLevel string log level (panic fatal error warn warning info debug trace). Env "TAOS_ADAPTER_LOG_LEVEL" (default "info") + --monitor.collectDuration duration Set monitor duration. Env "TAOS_MONITOR_COLLECT_DURATION" (default 3s) + --monitor.identity string The identity of the current instance, or 'hostname:port' if it is empty. Env "TAOS_MONITOR_IDENTITY" + --monitor.incgroup Whether running in cgroup. Env "TAOS_MONITOR_INCGROUP" + --monitor.password string TDengine password. Env "TAOS_MONITOR_PASSWORD" (default "taosdata") + --monitor.pauseAllMemoryThreshold float Memory percentage threshold for pause all. Env "TAOS_MONITOR_PAUSE_ALL_MEMORY_THRESHOLD" (default 80) + --monitor.pauseQueryMemoryThreshold float Memory percentage threshold for pause query. Env "TAOS_MONITOR_PAUSE_QUERY_MEMORY_THRESHOLD" (default 70) + --monitor.user string TDengine user. Env "TAOS_MONITOR_USER" (default "root") + --monitor.writeInterval duration Set write to TDengine interval. Env "TAOS_MONITOR_WRITE_INTERVAL" (default 30s) + --monitor.writeToTD Whether write metrics to TDengine. Env "TAOS_MONITOR_WRITE_TO_TD" (default true) + --node_exporter.caCertFile string node_exporter ca cert file path. Env "TAOS_ADAPTER_NODE_EXPORTER_CA_CERT_FILE" + --node_exporter.certFile string node_exporter cert file path. Env "TAOS_ADAPTER_NODE_EXPORTER_CERT_FILE" + --node_exporter.db string node_exporter db name. Env "TAOS_ADAPTER_NODE_EXPORTER_DB" (default "node_exporter") + --node_exporter.enable enable node_exporter. Env "TAOS_ADAPTER_NODE_EXPORTER_ENABLE" + --node_exporter.gatherDuration duration node_exporter gather duration. Env "TAOS_ADAPTER_NODE_EXPORTER_GATHER_DURATION" (default 5s) + --node_exporter.httpBearerTokenString string node_exporter http bearer token. Env "TAOS_ADAPTER_NODE_EXPORTER_HTTP_BEARER_TOKEN_STRING" + --node_exporter.httpPassword string node_exporter http password. Env "TAOS_ADAPTER_NODE_EXPORTER_HTTP_PASSWORD" + --node_exporter.httpUsername string node_exporter http username. Env "TAOS_ADAPTER_NODE_EXPORTER_HTTP_USERNAME" + --node_exporter.insecureSkipVerify node_exporter skip ssl check. Env "TAOS_ADAPTER_NODE_EXPORTER_INSECURE_SKIP_VERIFY" (default true) + --node_exporter.keyFile string node_exporter cert key file path. Env "TAOS_ADAPTER_NODE_EXPORTER_KEY_FILE" + --node_exporter.password string node_exporter password. Env "TAOS_ADAPTER_NODE_EXPORTER_PASSWORD" (default "taosdata") + --node_exporter.responseTimeout duration node_exporter response timeout. Env "TAOS_ADAPTER_NODE_EXPORTER_RESPONSE_TIMEOUT" (default 5s) + --node_exporter.urls strings node_exporter urls. Env "TAOS_ADAPTER_NODE_EXPORTER_URLS" (default [http://localhost:9100]) + --node_exporter.user string node_exporter user. Env "TAOS_ADAPTER_NODE_EXPORTER_USER" (default "root") + --opentsdb.enable enable opentsdb. Env "TAOS_ADAPTER_OPENTSDB_ENABLE" (default true) + --opentsdb_telnet.dbs strings opentsdb_telnet db names. Env "TAOS_ADAPTER_OPENTSDB_TELNET_DBS" (default [opentsdb_telnet,collectd_tsdb,icinga2_tsdb,tcollector_tsdb]) + --opentsdb_telnet.enable enable opentsdb telnet,warning: without auth info(default false). Env "TAOS_ADAPTER_OPENTSDB_TELNET_ENABLE" + --opentsdb_telnet.maxTCPConnections int max tcp connections. Env "TAOS_ADAPTER_OPENTSDB_TELNET_MAX_TCP_CONNECTIONS" (default 250) + --opentsdb_telnet.password string opentsdb_telnet password. Env "TAOS_ADAPTER_OPENTSDB_TELNET_PASSWORD" (default "taosdata") + --opentsdb_telnet.ports ints opentsdb telnet tcp port. Env "TAOS_ADAPTER_OPENTSDB_TELNET_PORTS" (default [6046,6047,6048,6049]) + --opentsdb_telnet.tcpKeepAlive enable tcp keep alive. Env "TAOS_ADAPTER_OPENTSDB_TELNET_TCP_KEEP_ALIVE" + --opentsdb_telnet.user string opentsdb_telnet user. Env "TAOS_ADAPTER_OPENTSDB_TELNET_USER" (default "root") + --pool.idleTimeout duration Set idle connection timeout. Env "TAOS_ADAPTER_POOL_IDLE_TIMEOUT" (default 1h0m0s) + --pool.maxConnect int max connections to taosd. Env "TAOS_ADAPTER_POOL_MAX_CONNECT" (default 4000) + --pool.maxIdle int max idle connections to taosd. Env "TAOS_ADAPTER_POOL_MAX_IDLE" (default 4000) + -P, --port int http port. Env "TAOS_ADAPTER_PORT" (default 6041) + --prometheus.enable enable prometheus. Env "TAOS_ADAPTER_PROMETHEUS_ENABLE" (default true) + --restfulRowLimit int restful returns the maximum number of rows (-1 means no limit). Env "TAOS_ADAPTER_RESTFUL_ROW_LIMIT" (default -1) + --ssl.certFile string ssl cert file path. Env "TAOS_ADAPTER_SSL_CERT_FILE" + --ssl.enable enable ssl. Env "TAOS_ADAPTER_SSL_ENABLE" + --ssl.keyFile string ssl key file path. Env "TAOS_ADAPTER_SSL_KEY_FILE" + --statsd.allowPendingMessages int statsd allow pending messages. Env "TAOS_ADAPTER_STATSD_ALLOW_PENDING_MESSAGES" (default 50000) + --statsd.db string statsd db name. Env "TAOS_ADAPTER_STATSD_DB" (default "statsd") + --statsd.deleteCounters statsd delete counter cache after gather. Env "TAOS_ADAPTER_STATSD_DELETE_COUNTERS" (default true) + --statsd.deleteGauges statsd delete gauge cache after gather. Env "TAOS_ADAPTER_STATSD_DELETE_GAUGES" (default true) + --statsd.deleteSets statsd delete set cache after gather. Env "TAOS_ADAPTER_STATSD_DELETE_SETS" (default true) + --statsd.deleteTimings statsd delete timing cache after gather. Env "TAOS_ADAPTER_STATSD_DELETE_TIMINGS" (default true) + --statsd.enable enable statsd. Env "TAOS_ADAPTER_STATSD_ENABLE" (default true) + --statsd.gatherInterval duration statsd gather interval. Env "TAOS_ADAPTER_STATSD_GATHER_INTERVAL" (default 5s) + --statsd.maxTCPConnections int statsd max tcp connections. Env "TAOS_ADAPTER_STATSD_MAX_TCP_CONNECTIONS" (default 250) + --statsd.password string statsd password. Env "TAOS_ADAPTER_STATSD_PASSWORD" (default "taosdata") + --statsd.port int statsd server port. Env "TAOS_ADAPTER_STATSD_PORT" (default 6044) + --statsd.protocol string statsd protocol [tcp or udp]. Env "TAOS_ADAPTER_STATSD_PROTOCOL" (default "udp") + --statsd.tcpKeepAlive enable tcp keep alive. Env "TAOS_ADAPTER_STATSD_TCP_KEEP_ALIVE" + --statsd.user string statsd user. Env "TAOS_ADAPTER_STATSD_USER" (default "root") + --statsd.worker int statsd write worker. Env "TAOS_ADAPTER_STATSD_WORKER" (default 10) + --taosConfigDir string load taos client config path. Env "TAOS_ADAPTER_TAOS_CONFIG_FILE" + --version Print the version and exit +``` + +备注： +使用浏览器进行接口调用请根据实际情况设置如下跨源资源共享（CORS）参数： + +```text +AllowAllOrigins +AllowOrigins +AllowHeaders +ExposeHeaders +AllowCredentials +AllowWebSockets +``` + +如果不通过浏览器进行接口调用无需关心这几项配置。 + +关于 CORS 协议细节请参考：[https://www.w3.org/wiki/CORS_Enabled](https://www.w3.org/wiki/CORS_Enabled) 或 [https://developer.mozilla.org/zh-CN/docs/Web/HTTP/CORS](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/CORS)。 + +示例配置文件参见 [example/config/taosadapter.toml](https://github.com/taosdata/taosadapter/blob/develop/example/config/taosadapter.toml)。 + +## 功能列表 + +- 与 RESTful 接口兼容 + [https://www.taosdata.com/cn/documentation/connector#restful](https://www.taosdata.com/cn/documentation/connector#restful) +- 兼容 InfluxDB v1 写接口 + [https://docs.influxdata.com/influxdb/v2.0/reference/api/influxdb-1x/write/](https://docs.influxdata.com/influxdb/v2.0/reference/api/influxdb-1x/write/) +- 兼容 OpenTSDB JSON 和 telnet 格式写入 + - + - +- 与 collectd 无缝连接 + collectd 是一个系统统计收集守护程序，请访问 [https://collectd.org/](https://collectd.org/) 了解更多信息。 +- Seamless connection with StatsD + StatsD 是一个简单而强大的统计信息汇总的守护程序。请访问 [https://github.com/statsd/statsd](https://github.com/statsd/statsd) 了解更多信息。 +- 与 icinga2 的无缝连接 + icinga2 是一个收集检查结果指标和性能数据的软件。请访问 [https://icinga.com/docs/icinga-2/latest/doc/14-features/#opentsdb-writer](https://icinga.com/docs/icinga-2/latest/doc/14-features/#opentsdb-writer) 了解更多信息。 +- 与 tcollector 无缝连接 + TCollector 是一个客户端进程，从本地收集器收集数据，并将数据推送到 OpenTSDB。请访问 [http://opentsdb.net/docs/build/html/user_guide/utilities/tcollector.html](http://opentsdb.net/docs/build/html/user_guide/utilities/tcollector.html) 了解更多信息。 +- 无缝连接 node_exporter + node_export 是一个机器指标的导出器。请访问 [https://github.com/prometheus/node_exporter](https://github.com/prometheus/node_exporter) 了解更多信息。 +- 支持 Prometheus remote_read 和 remote_write + remote_read 和 remote_write 是 Prometheus 数据读写分离的集群方案。请访问[https://prometheus.io/blog/2019/10/10/remote-read-meets-streaming/#remote-apis](https://prometheus.io/blog/2019/10/10/remote-read-meets-streaming/#remote-apis) 了解更多信息。 + +## 接口 + +### TDengine RESTful 接口 + +您可以使用任何支持 http 协议的客户端通过访问 RESTful 接口地址 `http://:6041/` 来写入数据到 TDengine 或从 TDengine 中查询数据。细节请参考[官方文档](/reference/connector#restful)。支持如下 EndPoint ： + +```text +/rest/sql +/rest/sqlt +/rest/sqlutc +``` + +### InfluxDB + +您可以使用任何支持 http 协议的客户端访问 Restful 接口地址 `http://:6041/` 来写入 InfluxDB 兼容格式的数据到 TDengine。EndPoint 如下： + +```text +/influxdb/v1/write +``` + +支持 InfluxDB 查询参数如下： + +- `db` 指定 TDengine 使用的数据库名 +- `precision` TDengine 使用的时间精度 +- `u` TDengine 用户名 +- `p` TDengine 密码 + +注意： 目前不支持 InfluxDB 的 token 验证方式只支持 Basic 验证和查询参数验证。 + +### OpenTSDB + +您可以使用任何支持 http 协议的客户端访问 Restful 接口地址 `http://:6041/` 来写入 OpenTSDB 兼容格式的数据到 TDengine。EndPoint 如下： + +```text +/opentsdb/v1/put/json/:db +/opentsdb/v1/put/telnet/:db +``` + +### collectd + + + +### StatsD + + + +### icinga2 OpenTSDB writer + + + +### TCollector + + + +### node_exporter + +Prometheus 使用的由\*NIX 内核暴露的硬件和操作系统指标的输出器 + +- 启用 taosAdapter 的配置 node_exporter.enable +- 设置 node_exporter 的相关配置 +- 重新启动 taosAdapter + +### prometheus + + + +## 内存使用优化方法 + +taosAdapter 将监测自身运行过程中内存使用率并通过两个阈值进行调节。有效值范围为 -1 到 100 的整数，单位为系统物理内存的百分比。 + +- pauseQueryMemoryThreshold +- pauseAllMemoryThreshold + +当超过 pauseQueryMemoryThreshold 阈值时时停止处理查询请求。 + +http 返回内容： + +- code 503 +- body "query memory exceeds threshold" + +当超过 pauseAllMemoryThreshold 阈值时停止处理所有写入和查询请求。 + +http 返回内容： + +- code 503 +- body "memory exceeds threshold" + +当内存回落到阈值之下时恢复对应功能。 + +状态检查接口 `http://:6041/-/ping` + +- 正常返回 `code 200` +- 无参数 如果内存超过 pauseAllMemoryThreshold 将返回 `code 503` +- 请求参数 `action=query` 如果内存超过 pauseQueryMemoryThreshold 或 pauseAllMemoryThreshold 将返回 `code 503` + +对应配置参数 + +```text + monitor.collectDuration 监测间隔 环境变量 "TAOS_MONITOR_COLLECT_DURATION" (默认值 3s) + monitor.incgroup 是否是cgroup中运行(容器中运行设置为 true) 环境变量 "TAOS_MONITOR_INCGROUP" + monitor.pauseAllMemoryThreshold 不再进行插入和查询的内存阈值 环境变量 "TAOS_MONITOR_PAUSE_ALL_MEMORY_THRESHOLD" (默认值 80) + monitor.pauseQueryMemoryThreshold 不再进行查询的内存阈值 环境变量 "TAOS_MONITOR_PAUSE_QUERY_MEMORY_THRESHOLD" (默认值 70) +``` + +您可以根据具体项目应用场景和运营策略进行相应调整，并建议使用运营监控软件及时进行系统内存状态监控。负载均衡器也可以通过这个接口检查 taosAdapter 运行状态。 + +## taosAdapter 监控指标 + +taosAdapter 采集 http 相关指标、cpu 百分比和内存百分比。 + +### http 接口 + +提供符合 [OpenMetrics](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md) 接口： + +```text +http://:6041/metrics +``` + +### 写入 TDengine + +taosAdapter 支持将 http 监控、cpu 百分比和内存百分比写入 TDengine。 + +有关配置参数 + +| **配置项** | **描述** | **默认值** | +| ----------------------- | --------------------------------------------------------- | ---------- | +| monitor.collectDuration | cpu 和内存采集间隔 | 3s | +| monitor.identity | 当前 taosadapter 的标识符如果不设置将使用 'hostname:port' | | +| monitor.incgroup | 是否是 cgroup 中运行(容器中运行设置为 true) | false | +| monitor.writeToTD | 是否写入到 TDengine | true | +| monitor.user | TDengine 连接用户名 | root | +| monitor.password | TDengine 连接密码 | taosdata | +| monitor.writeInterval | 写入 TDengine 间隔 | 30s | + +## 结果返回条数限制 + +taosAdapter 通过参数 `restfulRowLimit` 来控制结果的返回条数，-1 代表无限制，默认无限制。 + +该参数控制以下接口返回 + +- `http://:6041/rest/sql` +- `http://:6041/rest/sqlt` +- `http://:6041/rest/sqlutc` +- `http://:6041/prometheus/v1/remote_read/:db` + +## 故障解决 + +您可以通过命令 `systemctl status taosadapter` 来检查 taosAdapter 运行状态。 + +您也可以通过设置 --logLevel 参数或者环境变量 TAOS_ADAPTER_LOG_LEVEL 来调节 taosAdapter 日志输出详细程度。有效值包括： panic、fatal、error、warn、warning、info、debug 以及 trace。 + +## 如何从旧版本 TDengine 迁移到 taosAdapter + +在 TDengine server 2.2.x.x 或更早期版本中，taosd 进程包含一个内嵌的 http 服务。如前面所述，taosAdapter 是一个使用 systemd 管理的独立软件，拥有自己的进程。并且两者有一些配置参数和行为是不同的，请见下表： + +| **#** | **embedded httpd** | **taosAdapter** | **comment** | +| ----- | ------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | +| 1 | httpEnableRecordSql | --logLevel=debug | | +| 2 | httpMaxThreads | n/a | taosAdapter 自动管理线程池，无需此参数 | +| 3 | telegrafUseFieldNum | 请参考 taosAdapter telegraf 配置方法 | | +| 4 | restfulRowLimit | restfulRowLimit | 内嵌 httpd 默认输出 10240 行数据，最大允许值为 102400。taosAdapter 也提供 restfulRowLimit 但是默认不做限制。您可以根据实际场景需求进行配置 | +| 5 | httpDebugFlag | 不适用 | httpdDebugFlag 对 taosAdapter 不起作用 | +| 6 | httpDBNameMandatory | 不适用 | taosAdapter 要求 URL 中必须指定数据库名 | diff --git a/docs-cn/14-reference/05-taosbenchmark.md b/docs-cn/14-reference/05-taosbenchmark.md new file mode 100644 index 0000000000000000000000000000000000000000..f34d12a5462a7c078b9c237ee8be19a86ed250a7 --- /dev/null +++ b/docs-cn/14-reference/05-taosbenchmark.md @@ -0,0 +1,434 @@ +--- +title: taosBenchmark +sidebar_label: taosBenchmark +toc_max_heading_level: 4 +description: 'taosBenchmark (曾用名 taosdemo ) 是一个用于测试 TDengine 产品性能的工具' +--- + +## 简介 + +taosBenchmark (曾用名 taosdemo ) 是一个用于测试 TDengine 产品性能的工具。taosBenchmark 可以测试 TDengine 的插入、查询和订阅等功能的性能，它可以模拟由大量设备产生的大量数据，还可以灵活地控制数据库、超级表、标签列的数量和类型、数据列的数量和类型、子表的数量、每张子表的数据量、插入数据的时间间隔、taosBenchmark 的工作线程数量、是否以及如何插入乱序数据等。为了兼容过往用户的使用习惯，安装包提供 了 taosdemo 作为 taosBenchmark 的软链接。 + +## 安装 + +taosBenchmark 有两种安装方式: + +- 安装 TDengine 官方安装包的同时会自动安装 taosBenchmark, 详情请参考[ TDengine 安装](/operation/pkg-install)。 + +- 单独编译 taos-tools 并安装, 详情请参考 [taos-tools](https://github.com/taosdata/taos-tools) 仓库。 + +## 运行 + +### 配置和运行方式 + +taosBenchmark 支持两种配置方式：[命令行参数](#命令行参数详解) 和 [JSON 配置文件](#配置文件参数详解)。这两种方式是互斥的，在使用配置文件时只能使用一个命令行参数 `-f ` 指定配置文件。在使用命令行参数运行 taosBenchmark 并控制其行为时则不能使用 `-f` 参数而要用其它参数来进行配置。除此之外，taosBenchmark 还提供了一种特殊的运行方式，即无参数运行。 + +taosBenchmark 支持对 TDengine 做完备的性能测试，其所支持的 TDengine 功能分为三大类：写入、查询和订阅。这三种功能之间是互斥的，每次运行 taosBenchmark 只能选择其中之一。值得注意的是，所要测试的功能类型在使用命令行配置方式时是不可配置的，命令行配置方式只能测试写入性能。若要测试 TDengine 的查询和订阅性能，必须使用配置文件的方式，通过配置文件中的参数 `filetype` 指定所要测试的功能类型。 + +**在运行 taosBenchmark 之前要确保 TDengine 集群已经在正确运行。** + +### 无命令行参数运行 + +执行下列命令即可快速体验 taosBenchmark 对 TDengine 进行基于默认配置的写入性能测试。 + +```bash +taosBenchmark +``` + +在无参数运行时，taosBenchmark 默认连接 `/etc/taos` 下指定的 TDengine 集群，并在 TDengine 中创建一个名为 test 的数据库，test 数据库下创建名为 meters 的一张超级表，超级表下创建 10000 张表，每张表中写入 10000 条记录。注意，如果已有 test 数据库，这个命令会先删除该数据库后建立一个全新的 test 数据库。 + +### 使用命令行配置参数运行 + +在使用命令行参数运行 taosBenchmark 并控制其行为时，`-f ` 参数不能使用。所有配置参数都必须通过命令行指定。以下是使用命令行方式测试 taosBenchmark 写入性能的一个示例。 + +```bash +taosBenchmark -I stmt -n 200 -t 100 +``` + +上面的命令 `taosBenchmark` 将创建一个名为`test`的数据库，在其中建立一张超级表`meters`，在该超级表中建立 100 张子表并使用参数绑定的方式为每张子表插入 200 条记录。 + +### 使用配置文件运行 + +taosBenchmark 安装包中提供了配置文件的示例，位于 `/examples/taosbenchmark-json` 下 + +使用如下命令行即可运行 taosBenchmark 并通过配置文件控制其行为。 + +```bash +taosBenchmark -f +``` + +**下面是几个配置文件的示例：** + +#### 插入场景 JSON 配置文件示例 + +
+insert.json + +```json +{{#include /taos-tools/example/insert.json}} +``` + +
+ +#### 查询场景 JSON 配置文件示例 + +
+query.json + +```json +{{#include /taos-tools/example/query.json}} +``` + +
+ +#### 订阅场景 JSON 配置文件示例 + +
+subscribe.json + +```json +{{#include /taos-tools/example/subscribe.json}} +``` + +
+ +## 命令行参数详解 + +- **-f/--file ** : + 要使用的 JSON 配置文件，由该文件指定所有参数，本参数与命令行其他参数不能同时使用。没有默认值。 + +- **-c/--config-dir ** : + TDengine 集群配置文件所在的目录，默认路径是 /etc/taos 。 + +- **-h/--host ** : + 指定要连接的 TDengine 服务端的 FQDN，默认值为 localhost 。 + +- **-P/--port ** : + 要连接的 TDengine 服务器的端口号，默认值为 6030 。 + +- **-I/--interface ** : + 插入模式，可选项有 taosc, rest, stmt, sml, sml-rest, 分别对应普通写入、restful 接口写入、参数绑定接口写入、schemaless 接口写入、restful schemaless 接口写入 (由 taosAdapter 提供)。默认值为 taosc。 + +- **-u/--user ** : + 用于连接 TDengine 服务端的用户名，默认为 root 。 + +- **-p/--password ** : + 用于连接 TDengine 服务端的密码，默认值为 taosdata。 + +- **-o/--output ** : + 结果输出文件的路径，默认值为 ./output.txt。 + +- **-T/--thread ** : + 插入数据的线程数量，默认为 8 。 + +- **-B/--interlace-rows ** : + 启用交错插入模式并同时指定向每个子表每次插入的数据行数。交错插入模式是指依次向每张子表插入由本参数所指定的行数并重复这个过程，直到所有子表的数据都插入完成。默认值为 0， 即向一张子表完成数据插入后才会向下一张子表进行数据插入。 + +- **-i/--insert-interval ** : + 指定交错插入模式的插入间隔，单位为 ms，默认值为 0。 只有当 `-B/--interlace-rows` 大于 0 时才起作用。意味着数据插入线程在为每个子表插入隔行扫描记录后，会等待该值指定的时间间隔后再进行下一轮写入。 + +- **-r/--rec-per-req ** : + 每次向 TDengine 请求写入的数据行数，默认值为 30000 。 + +- **-t/--tables ** : + 指定子表的数量，默认为 10000 。 + +- **-S/--timestampstep ** : + 每个子表中插入数据的时间戳步长，单位是 ms，默认值是 1。 + +- **-n/--records ** : + 每个子表插入的记录数，默认值为 10000 。 + +- **-d/--database ** : + 所使用的数据库的名称，默认值为 test 。 + +- **-b/--data-type ** : + 超级表的数据列的类型。如果不使用则默认为有三个数据列，其类型分别为 FLOAT, INT, FLOAT 。 + +- **-l/--columns ** : + 超级表的数据列的总数量。如果同时设置了该参数和 `-b/--data-type`，则最后的结果列数为两者取大。如果本参数指定的数量大于 `-b/--data-type` 指定的列数，则未指定的列类型默认为 INT， 例如: `-l 5 -b float,double`， 那么最后的列为 `FLOAT,DOUBLE,INT,INT,INT`。如果 columns 指定的数量小于或等于 `-b/--data-type` 指定的列数，则结果为 `-b/--data-type` 指定的列和类型，例如: `-l 3 -b float,double,float,bigint`，那么最后的列为 `FLOAT,DOUBLE,FLOAT,BIGINT` 。 + +- **-A/--tag-type ** : + 超级表的标签列类型。nchar 和 binary 类型可以同时设置长度，例如: + +``` +taosBenchmark -A INT,DOUBLE,NCHAR,BINARY(16) +``` + +如果没有设置标签类型，默认是两个标签，其类型分别为 INT 和 BINARY(16)。 +注意：在有的 shell 比如 bash 命令里面 “()” 需要转义，则上述指令应为： + +``` +taosBenchmark -A INT,DOUBLE,NCHAR,BINARY\(16\) +``` + +- **-w/--binwidth **: + nchar 和 binary 类型的默认长度，默认值为 64。 + +- **-m/--table-prefix ** : + 子表名称的前缀，默认值为 "d"。 + +- **-E/--escape-character** : + 开关参数，指定在超级表和子表名称中是否使用转义字符。默认值为不使用。 + +- **-C/--chinese** : + 开关参数，指定 nchar 和 binary 是否使用 Unicode 中文字符。默认值为不使用。 + +- **-N/--normal-table** : + 开关参数，指定只创建普通表，不创建超级表。默认值为 false。仅当插入模式为 taosc, stmt, rest 模式下可以使用。 + +- **-M/--random** : + 开关参数，插入数据为生成的随机值。默认值为 false。若配置此参数，则随机生成要插入的数据。对于数值类型的 标签列/数据列，其值为该类型取值范围内的随机值。对于 NCHAR 和 BINARY 类型的 标签列/数据列，其值为指定长度范围内的随机字符串。 + +- **-x/--aggr-func** : + 开关参数，指示插入后查询聚合函数。默认值为 false。 + +- **-y/--answer-yes** : + 开关参数，要求用户在提示后确认才能继续。默认值为 false 。 + +- **-O/--disorder ** : + 指定乱序数据的百分比概率，其值域为 [0,50]。默认为 0，即没有乱序数据。 + +- **-R/--disorder-range ** : + 指定乱序数据的时间戳回退范围。所生成的乱序时间戳为非乱序情况下应该使用的时间戳减去这个范围内的一个随机值。仅在 `-O/--disorder` 指定的乱序数据百分比大于 0 时有效。 + +- **-F/--prepare_rand ** : + 生成的随机数据中唯一值的数量。若为 1 则表示所有数据都相同。默认值为 10000 。 + +- **-a/--replica ** : + 创建数据库时指定其副本数，默认值为 1 。 + +- **-V/--version** : + 显示版本信息并退出。不能与其它参数混用。 + +- **-?/--help** : + 显示帮助信息并退出。不能与其它参数混用。 + +## 配置文件参数详解 + +### 通用配置参数 + +本节所列参数适用于所有功能模式。 + +- **filetype** : 要测试的功能，可选值为 `insert`, `query` 和 `subscribe`。分别对应插入、查询和订阅功能。每个配置文件中只能指定其中之一。 +- **cfgdir** : TDengine 集群配置文件所在的目录，默认路径是 /etc/taos 。 + +- **host** : 指定要连接的 TDengine 服务端的 FQDN，默认值为 localhost。 + +- **port** : 要连接的 TDengine 服务器的端口号，默认值为 6030。 + +- **user** : 用于连接 TDengine 服务端的用户名，默认为 root。 + +- **password** : 用于连接 TDengine 服务端的密码，默认值为 taosdata。 + +### 插入场景配置参数 + +插入场景下 `filetype` 必须设置为 `insert`，该参数及其它通用参数详见[通用配置参数](#通用配置参数) + +#### 数据库相关配置参数 + +创建数据库时的相关参数在 json 配置文件中的 `dbinfo` 中配置，具体参数如下。这些参数与 TDengine 中 `create database` 时所指定的数据库参数相对应。 + +- **name** : 数据库名。 + +- **drop** : 插入前是否删除数据库，默认为 true。 + +- **replica** : 创建数据库时指定的副本数。 + +- **days** : 单个数据文件中存储数据的时间跨度，默认值为 10。 + +- **cache** : 缓存块的大小，单位是 MB，默认值是 16。 + +- **blocks** : 每个 vnode 中缓存块的数量，默认为 6。 + +- **precision** : 数据库时间精度，默认值为 "ms"。 + +- **keep** : 保留数据的天数，默认值为 3650。 + +- **minRows** : 文件块中的最小记录数，默认值为 100。 + +- **maxRows** : 文件块中的最大记录数，默认值为 4096。 + +- **comp** : 文件压缩标志，默认值为 2。 + +- **walLevel** : WAL 级别，默认为 1。 + +- **cacheLast** : 是否允许将每个表的最后一条记录保留在内存中，默认值为 0，可选值为 0，1，2，3。 + +- **quorum** : 多副本模式下的写确认数量，默认值为 1。 + +- **fsync** : 当 wal 设置为 2 时，fsync 的间隔时间，单位为 ms，默认值为 3000。 + +- **update** : 是否支持数据更新，默认值为 0， 可选值为 0， 1， 2。 + +#### 超级表相关配置参数 + +创建超级表时的相关参数在 json 配置文件中的 `super_tables` 中配置，具体参数如下表。 + +- **name**: 超级表名，必须配置，没有默认值。 +- **child_table_exists** : 子表是否已经存在，默认值为 "no"，可选值为 "yes" 或 "no"。 + +- **child_table_count** : 子表的数量，默认值为 10。 + +- **child_table_prefix** : 子表名称的前缀，必选配置项，没有默认值。 + +- **escape_character** : 超级表和子表名称中是否包含转义字符，默认值为 "no"，可选值为 "yes" 或 "no"。 + +- **auto_create_table** : 仅当 insert_mode 为 taosc, rest, stmt 并且 childtable_exists 为 "no" 时生效，该参数为 "yes" 表示 taosBenchmark 在插入数据时会自动创建不存在的表；为 "no" 则表示先提前建好所有表再进行插入。 + +- **batch_create_tbl_num** : 创建子表时每批次的建表数量，默认为 10。注：实际的批数不一定与该值相同，当执行的 SQL 语句大于支持的最大长度时，会自动截断再执行，继续创建。 + +- **data_source** : 数据的来源，默认为 taosBenchmark 随机产生，可以配置为 "rand" 和 "sample"。为 "sample" 时使用 sample_file 参数指定的文件内的数据。 + +- **insert_mode** : 插入模式，可选项有 taosc, rest, stmt, sml, sml-rest, 分别对应普通写入、restful 接口写入、参数绑定接口写入、schemaless 接口写入、restful schemaless 接口写入 (由 taosAdapter 提供)。默认值为 taosc 。 + +- **non_stop_mode** : 指定是否持续写入，若为 "yes" 则 insert_rows 失效，直到 Ctrl + C 停止程序，写入才会停止。默认值为 "no"，即写入指定数量的记录后停止。注：即使在持续写入模式下 insert_rows 失效，但其也必须被配置为一个非零正整数。 + +- **line_protocol** : 使用行协议插入数据，仅当 insert_mode 为 sml 或 sml-rest 时生效，可选项为 line, telnet, json。 + +- **tcp_transfer** : telnet 模式下的通信协议，仅当 insert_mode 为 sml-rest 并且 line_protocol 为 telnet 时生效。如果不配置，则默认为 http 协议。 + +- **insert_rows** : 每个子表插入的记录数，默认为 0 。 + +- **childtable_offset** : 仅当 childtable_exists 为 yes 时生效，指定从超级表获取子表列表时的偏移量，即从第几个子表开始。 + +- **childtable_limit** : 仅当 childtable_exists 为 yes 时生效，指定从超级表获取子表列表的上限。 + +- **interlace_rows** : 启用交错插入模式并同时指定向每个子表每次插入的数据行数。交错插入模式是指依次向每张子表插入由本参数所指定的行数并重复这个过程，直到所有子表的数据都插入完成。默认值为 0， 即向一张子表完成数据插入后才会向下一张子表进行数据插入。 + +- **insert_interval** : 指定交错插入模式的插入间隔，单位为 ms，默认值为 0。 只有当 `-B/--interlace-rows` 大于 0 时才起作用。意味着数据插入线程在为每个子表插入隔行扫描记录后，会等待该值指定的时间间隔后再进行下一轮写入。 + +- **partial_col_num** : 若该值为正数 n 时， 则仅向前 n 列写入，仅当 insert_mode 为 taosc 和 rest 时生效，如果 n 为 0 则是向全部列写入。 + +- **disorder_ratio** : 指定乱序数据的百分比概率，其值域为 [0,50]。默认为 0，即没有乱序数据。 + +- **disorder_range** : 指定乱序数据的时间戳回退范围。所生成的乱序时间戳为非乱序情况下应该使用的时间戳减去这个范围内的一个随机值。仅在 `-O/--disorder` 指定的乱序数据百分比大于 0 时有效。 + +- **timestamp_step** : 每个子表中插入数据的时间戳步长，单位与数据库的 `precision` 一致，默认值是 1。 + +- **start_timestamp** : 每个子表的时间戳起始值，默认值是 now。 + +- **sample_format** : 样本数据文件的类型，现在只支持 "csv" 。 + +- **sample_file** : 指定 csv 格式的文件作为数据源，仅当 data_source 为 sample 时生效。若 csv 文件内的数据行数小于等于 prepared_rand，那么会循环读取 csv 文件数据直到与 prepared_rand 相同；否则则会只读取 prepared_rand 个数的行的数据。也即最终生成的数据行数为二者取小。 + +- **use_sample_ts** : 仅当 data_source 为 sample 时生效，表示 sample_file 指定的 csv 文件内是否包含第一列时间戳，默认为 no。 若设置为 yes， 则使用 csv 文件第一列作为时间戳，由于同一子表时间戳不能重复，生成的数据量取决于 csv 文件内的数据行数相同，此时 insert_rows 失效。 + +- **tags_file** : 仅当 insert_mode 为 taosc, rest 的模式下生效。 最终的 tag 的数值与 childtable_count 有关，如果 csv 文件内的 tag 数据行小于给定的子表数量，那么会循环读取 csv 文件数据直到生成 childtable_count 指定的子表数量；否则则只会读取 childtable_count 行 tag 数据。也即最终生成的子表数量为二者取小。 + +#### 标签列与数据列配置参数 + +指定超级表标签列与数据列的配置参数分别在 `super_tables` 中的 `columns` 和 `tag` 中。 + +- **type** : 指定列类型，可选值请参考 TDengine 支持的数据类型。 + 注：JSON 数据类型比较特殊，只能用于标签，当使用 JSON 类型作为 tag 时有且只能有这一个标签，此时 count 和 len 代表的意义分别是 JSON tag 内的 key-value pair 的个数和每个 KV pair 的 value 的值的长度，value 默认为 string。 + +- **len** : 指定该数据类型的长度，对 NCHAR，BINARY 和 JSON 数据类型有效。如果对其他数据类型配置了该参数，若为 0 ， 则代表该列始终都是以 null 值写入；如果不为 0 则被忽略。 + +- **count** : 指定该类型列连续出现的数量，例如 "count": 4096 即可生成 4096 个指定类型的列。 + +- **name** : 列的名字，若与 count 同时使用，比如 "name"："current", "count":3, 则 3 个列的名字分别为 current, current_2. current_3。 + +- **min** : 数据类型的 列/标签 的最小值。 + +- **max** : 数据类型的 列/标签 的最大值。 + +- **values** : nchar/binary 列/标签的值域，将从值中随机选择。 + +#### 插入行为配置参数 + +- **thread_count** : 插入数据的线程数量，默认为 8。 + +- **create_table_thread_count** : 建表的线程数量，默认为 8。 + +- **connection_pool_size** : 预先建立的与 TDengine 服务端之间的连接的数量。若不配置，则与所指定的线程数相同。 + +- **result_file** : 结果输出文件的路径，默认值为 ./output.txt。 + +- **confirm_parameter_prompt** : 开关参数，要求用户在提示后确认才能继续。默认值为 false 。 + +- **interlace_rows** : 启用交错插入模式并同时指定向每个子表每次插入的数据行数。交错插入模式是指依次向每张子表插入由本参数所指定的行数并重复这个过程，直到所有子表的数据都插入完成。默认值为 0， 即向一张子表完成数据插入后才会向下一张子表进行数据插入。 + 在 `super_tables` 中也可以配置该参数，若配置则以 `super_tables` 中的配置为高优先级，覆盖全局设置。 + +- **insert_interval** : + 指定交错插入模式的插入间隔，单位为 ms，默认值为 0。 只有当 `-B/--interlace-rows` 大于 0 时才起作用。意味着数据插入线程在为每个子表插入隔行扫描记录后，会等待该值指定的时间间隔后再进行下一轮写入。 + 在 `super_tables` 中也可以配置该参数，若配置则以 `super_tables` 中的配置为高优先级，覆盖全局设置。 + +- **num_of_records_per_req** : + 每次向 TDengine 请求写入的数据行数，默认值为 30000 。当其设置过大时，TDengine 客户端驱动会返回相应的错误信息，此时需要调低这个参数的设置以满足写入要求。 + +- **prepare_rand** : 生成的随机数据中唯一值的数量。若为 1 则表示所有数据都相同。默认值为 10000 。 + +### 查询场景配置参数 + +查询场景下 `filetype` 必须设置为 `query`，该参数及其它通用参数详见[通用配置参数](#通用配置参数) + +#### 执行指定查询语句的配置参数 + +查询子表或者普通表的配置参数在 `specified_table_query` 中设置。 + +- **query_interval** : 查询时间间隔，单位是秒，默认值为 0。 + +- **threads** : 执行查询 SQL 的线程数，默认值为 1。 + +- **sqls**： + - **sql**: 执行的 SQL 命令，必填。 + - **result**: 保存查询结果的文件，未指定则不保存。 + +#### 查询超级表的配置参数 + +查询超级表的配置参数在 `super_table_query` 中设置。 + +- **stblname** : 指定要查询的超级表的名称，必填。 + +- **query_interval** : 查询时间间隔，单位是秒，默认值为 0。 + +- **threads** : 执行查询 SQL 的线程数，默认值为 1。 + +- **sqls** ： + - **sql** : 执行的 SQL 命令，必填；对于超级表的查询 SQL，在 SQL 命令中保留 "xxxx"，程序会自动将其替换为超级表的所有子表名。 + 替换为超级表中所有的子表名。 + - **result** : 保存查询结果的文件，未指定则不保存。 + +### 订阅场景配置参数 + +订阅场景下 `filetype` 必须设置为 `subscribe`，该参数及其它通用参数详见[通用配置参数](#通用配置参数) + +#### 执行指定订阅语句的配置参数 + +订阅子表或者普通表的配置参数在 `specified_table_query` 中设置。 + +- **threads** : 执行 SQL 的线程数，默认为 1。 + +- **interval** : 执行订阅的时间间隔，单位为秒，默认为 0。 + +- **restart** : "yes" 表示开始新的订阅，"no" 表示继续之前的订阅，默认值为 "no"。 + +- **keepProgress** : "yes" 表示保留订阅进度，"no" 表示不保留，默认值为 "no"。 + +- **resubAfterConsume** : "yes" 表示取消之前的订阅然后再次订阅， "no" 表示继续之前的订阅，默认值为 "no"。 + +- **sqls** ： + - **sql** : 执行的 SQL 命令，必填。 + - **result** : 保存查询结果的文件，未指定则不保存。 + +#### 订阅超级表的配置参数 + +订阅超级表的配置参数在 `super_table_query` 中设置。 + +- **stblname** : 要订阅的超级表名称，必填。 + +- **threads** : 执行 SQL 的线程数，默认为 1。 + +- **interval** : 执行订阅的时间间隔，单位为秒，默认为 0。 + +- **restart** : "yes" 表示开始新的订阅，"no" 表示继续之前的订阅，默认值为 "no"。 + +- **keepProgress** : "yes" 表示保留订阅进度，"no" 表示不保留，默认值为 "no"。 + +- **resubAfterConsume** : "yes" 表示取消之前的订阅然后再次订阅， "no" 表示继续之前的订阅，默认值为 "no"。 + +- **sqls** ： + - **sql** : 执行的 SQL 命令，必填；对于超级表的查询 SQL，在 SQL 命令中保留 "xxxx"，程序会自动将其替换为超级表的所有子表名。 + 替换为超级表中所有的子表名。 + - **result** : 保存查询结果的文件，未指定则不保存。 diff --git a/docs-cn/14-reference/06-taosdump.md b/docs-cn/14-reference/06-taosdump.md new file mode 100644 index 0000000000000000000000000000000000000000..7131493ec9439225d8047288ed86026c887f0aac --- /dev/null +++ b/docs-cn/14-reference/06-taosdump.md @@ -0,0 +1,118 @@ +--- +title: taosdump +description: "taosdump 是一个支持从运行中的 TDengine 集群备份数据并将备份的数据恢复到相同或另一个运行中的 TDengine 集群中的工具应用程序" +--- + +## 简介 + +taosdump 是一个支持从运行中的 TDengine 集群备份数据并将备份的数据恢复到相同或另一个运行中的 TDengine 集群中的工具应用程序。 + +taosdump 可以用数据库、超级表或普通表作为逻辑数据单元进行备份，也可以对数据库、超级 +表和普通表中指定时间段内的数据记录进行备份。使用时可以指定数据备份的目录路径，如果 +不指定位置，taosdump 默认会将数据备份到当前目录。 + +如果指定的位置已经有数据文件，taosdump 会提示用户并立即退出，避免数据被覆盖。这意味着同一路径只能被用于一次备份。 +如果看到相关提示，请小心操作。 + +taosdump 是一个逻辑备份工具，它不应被用于备份任何原始数据、环境设置、 +硬件信息、服务端配置或集群的拓扑结构。taosdump 使用 +[ Apache AVRO ](https://avro.apache.org/)作为数据文件格式来存储备份数据。 + +## 安装 + +taosdump 有两种安装方式: + +- 安装 taosTools 官方安装包, 请从[所有下载链接](https://www.taosdata.com/all-downloads)页面找到 taosTools 并下载安装。 + +- 单独编译 taos-tools 并安装, 详情请参考 [taos-tools](https://github.com/taosdata/taos-tools) 仓库。 + +## 常用使用场景 + +### taosdump 备份数据 + +1. 备份所有数据库：指定 `-A` 或 `--all-databases` 参数； +2. 备份多个指定数据库：使用 `-D db1,db2,...` 参数； +3. 备份指定数据库中的某些超级表或普通表：使用 `dbname stbname1 stbname2 tbname1 tbname2 ...` 参数，注意这种输入序列第一个参数为数据库名称，且只支持一个数据库，第二个和之后的参数为该数据库中的超级表或普通表名称，中间以空格分隔； +4. 备份系统 log 库：TDengine 集群通常会包含一个系统数据库，名为 `log`，这个数据库内的数据为 TDengine 自我运行的数据，taosdump 默认不会对 log 库进行备份。如果有特定需求对 log 库进行备份，可以使用 `-a` 或 `--allow-sys` 命令行参数。 +5. “宽容”模式备份：taosdump 1.4.1 之后的版本提供 `-n` 参数和 `-L` 参数，用于备份数据时不使用转义字符和“宽容”模式，可以在表名、列名、标签名没使用转义字符的情况下减少备份数据时间和备份数据占用空间。如果不确定符合使用 `-n` 和 `-L` 条件时请使用默认参数进行“严格”模式进行备份。转义字符的说明请参考[官方文档](/taos-sql/escape)。 + +:::tip +- taosdump 1.4.1 之后的版本提供 `-I` 参数，用于解析 avro 文件 schema 和数据，如果指定 `-s` 参数将只解析 schema。 +- taosdump 1.4.2 之后的备份使用 `-B` 参数指定的批次数，默认值为 16384，如果在某些环境下由于网络速度或磁盘性能不足导致 "Error actual dump .. batch .." 可以通过 `-B` 参数挑战为更小的值进行尝试。 + +::: + +### taosdump 恢复数据 + +恢复指定路径下的数据文件：使用 `-i` 参数加上数据文件所在路径。如前面提及，不应该使用同一个目录备份不同数据集合，也不应该在同一路径多次备份同一数据集，否则备份数据会造成覆盖或多次备份。 + +:::tip +taosdump 内部使用 TDengine stmt binding API 进行恢复数据的写入，为提高数据恢复性能，目前使用 16384 为一次写入批次。如果备份数据中有比较多列数据，可能会导致产生 "WAL size exceeds limit" 错误，此时可以通过使用 `-B` 参数调整为一个更小的值进行尝试。 + +::: + +## 详细命令行参数列表 + +以下为 taosdump 详细命令行参数列表： + +``` +Usage: taosdump [OPTION...] dbname [tbname ...] + or: taosdump [OPTION...] --databases db1,db2,... + or: taosdump [OPTION...] --all-databases + or: taosdump [OPTION...] -i inpath + or: taosdump [OPTION...] -o outpath + + -h, --host=HOST Server host dumping data from. Default is + localhost. + -p, --password User password to connect to server. Default is + taosdata. + -P, --port=PORT Port to connect + -u, --user=USER User name used to connect to server. Default is + root. + -c, --config-dir=CONFIG_DIR Configure directory. Default is /etc/taos + -i, --inpath=INPATH Input file path. + -o, --outpath=OUTPATH Output file path. + -r, --resultFile=RESULTFILE DumpOut/In Result file path and name. + -a, --allow-sys Allow to dump system database + -A, --all-databases Dump all databases. + -D, --databases=DATABASES Dump inputted databases. Use comma to separate + databases' name. + -N, --without-property Dump database without its properties. + -s, --schemaonly Only dump tables' schema. + -y, --answer-yes Input yes for prompt. It will skip data file + checking! + -d, --avro-codec=snappy Choose an avro codec among null, deflate, snappy, + and lzma. + -S, --start-time=START_TIME Start time to dump. Either epoch or + ISO8601/RFC3339 format is acceptable. ISO8601 + format example: 2017-10-01T00:00:00.000+0800 or + 2017-10-0100:00:00:000+0800 or '2017-10-01 + 00:00:00.000+0800' + -E, --end-time=END_TIME End time to dump. Either epoch or ISO8601/RFC3339 + format is acceptable. ISO8601 format example: + 2017-10-01T00:00:00.000+0800 or + 2017-10-0100:00:00.000+0800 or '2017-10-01 + 00:00:00.000+0800' + -B, --data-batch=DATA_BATCH Number of data per query/insert statement when + backup/restore. Default value is 16384. If you see + 'error actual dump .. batch ..' when backup or if + you see 'WAL size exceeds limit' error when + restore, please adjust the value to a smaller one + and try. The workable value is related to the + length of the row and type of table schema. + -I, --inspect inspect avro file content and print on screen + -L, --loose-mode Using loose mode if the table name and column name + use letter and number only. Default is NOT. + -n, --no-escape No escape char '`'. Default is using it. + -T, --thread-num=THREAD_NUM Number of thread for dump in file. Default is + 5. + -g, --debug Print debug info. + -?, --help Give this help list + --usage Give a short usage message + -V, --version Print program version + +Mandatory or optional arguments to long options are also mandatory or optional +for any corresponding short options. + +Report bugs to . +``` diff --git a/docs-cn/14-reference/07-tdinsight/assets/15146-tdengine-monitor-dashboard.json b/docs-cn/14-reference/07-tdinsight/assets/15146-tdengine-monitor-dashboard.json new file mode 100644 index 0000000000000000000000000000000000000000..f651983528ca824b4e6b14586aac5a5bfb4ecab8 --- /dev/null +++ b/docs-cn/14-reference/07-tdinsight/assets/15146-tdengine-monitor-dashboard.json @@ -0,0 +1,3191 @@ +{ + "__inputs": [ + { + "name": "DS_TDENGINE", + "label": "TDengine", + "description": "", + "type": "datasource", + "pluginId": "tdengine-datasource", + "pluginName": "TDengine" + } + ], + "__requires": [ + { + "type": "panel", + "id": "gauge", + "name": "Gauge", + "version": "" + }, + { + "type": "grafana", + "id": "grafana", + "name": "Grafana", + "version": "7.5.10" + }, + { + "type": "panel", + "id": "graph", + "name": "Graph", + "version": "" + }, + { + "type": "panel", + "id": "piechart", + "name": "Pie chart v2", + "version": "" + }, + { + "type": "panel", + "id": "stat", + "name": "Stat", + "version": "" + }, + { + "type": "panel", + "id": "table", + "name": "Table", + "version": "" + }, + { + "type": "datasource", + "id": "tdengine-datasource", + "name": "TDengine", + "version": "3.1.0" + }, + { + "type": "panel", + "id": "text", + "name": "Text", + "version": "" + } + ], + "annotations": { + "list": [ + { + "builtIn": 1, + "datasource": "-- Grafana --", + "enable": true, + "hide": true, + "iconColor": "rgba(0, 211, 255, 1)", + "name": "Annotations & Alerts", + "type": "dashboard" + } + ] + }, + "description": "TDengine nodes metrics.", + "editable": true, + "gnetId": 15146, + "graphTooltip": 0, + "id": null, + "iteration": 1635263227798, + "links": [], + "panels": [ + { + "collapsed": false, + "datasource": null, + "gridPos": { + "h": 1, + "w": 24, + "x": 0, + "y": 0 + }, + "id": 57, + "panels": [], + "title": "Cluster Status", + "type": "row" + }, + { + "datasource": null, + "fieldConfig": { + "defaults": {}, + "overrides": [] + }, + "gridPos": { + "h": 3, + "w": 24, + "x": 0, + "y": 1 + }, + "id": 32, + "options": { + "content": "

TDengine Cluster Dashboard

>\n", + "mode": "markdown" + }, + "pluginVersion": "7.5.10", + "repeatDirection": "h", + "targets": [ + { + "alias": "mnodes", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "show mnodes", + "target": "select metric", + "timeshift": { + "period": null + }, + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "-- OVERVIEW --", + "transformations": [ + { + "id": "calculateField", + "options": { + "binary": { + "left": "Time", + "operator": "+", + "reducer": "sum", + "right": "" + }, + "mode": "binary", + "reduce": { + "reducer": "sum" + } + } + } + ], + "type": "text" + }, + { + "datasource": "${DS_TDENGINE}", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 3, + "w": 8, + "x": 0, + "y": 4 + }, + "id": 28, + "options": { + "colorMode": "value", + "graphMode": "area", + "justifyMode": "auto", + "orientation": "auto", + "reduceOptions": { + "calcs": ["lastNotNull"], + "fields": "", + "values": true + }, + "text": {}, + "textMode": "auto" + }, + "pluginVersion": "7.5.10", + "repeatDirection": "h", + "targets": [ + { + "alias": "dnodes", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "show mnodes", + "target": "select metric", + "timeshift": { + "period": null + }, + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Master MNode", + "transformations": [ + { + "id": "filterByValue", + "options": { + "filters": [ + { + "config": { + "id": "regex", + "options": { + "value": "master" + } + }, + "fieldName": "role" + } + ], + "match": "all", + "type": "include" + } + }, + { + "id": "filterFieldsByName", + "options": { + "include": { + "names": ["dnodes"] + } + } + } + ], + "type": "stat" + }, + { + "datasource": "${DS_TDENGINE}", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 3, + "w": 7, + "x": 8, + "y": 4 + }, + "id": 70, + "options": { + "colorMode": "value", + "graphMode": "area", + "justifyMode": "auto", + "orientation": "auto", + "reduceOptions": { + "calcs": ["lastNotNull"], + "fields": "/^Time$/", + "values": true + }, + "text": {}, + "textMode": "auto" + }, + "pluginVersion": "7.5.10", + "repeatDirection": "h", + "targets": [ + { + "alias": "dnodes", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "show mnodes", + "target": "select metric", + "timeshift": { + "period": null + }, + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Master MNode Create Time", + "transformations": [ + { + "id": "filterByValue", + "options": { + "filters": [ + { + "config": { + "id": "regex", + "options": { + "value": "master" + } + }, + "fieldName": "role" + } + ], + "match": "all", + "type": "include" + } + }, + { + "id": "filterFieldsByName", + "options": { + "include": { + "names": ["Time"] + } + } + }, + { + "id": "calculateField", + "options": { + "mode": "reduceRow", + "reduce": { + "reducer": "min" + } + } + } + ], + "type": "stat" + }, + { + "datasource": "${DS_TDENGINE}", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "custom": { + "align": null, + "filterable": false + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 9, + "w": 9, + "x": 15, + "y": 4 + }, + "id": 29, + "options": { + "showHeader": true + }, + "pluginVersion": "7.5.10", + "repeatDirection": "h", + "targets": [ + { + "alias": "dnodes", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "show variables", + "target": "select metric", + "timeshift": { + "period": null + }, + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Variables", + "transformations": [ + { + "id": "filterFieldsByName", + "options": { + "include": { + "names": ["value", "name"] + } + } + }, + { + "id": "filterByValue", + "options": { + "filters": [ + { + "config": { + "id": "regex", + "options": { + "value": ".*" + } + }, + "fieldName": "name" + } + ], + "match": "all", + "type": "include" + } + } + ], + "type": "table" + }, + { + "datasource": "${DS_TDENGINE}", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 3, + "w": 2, + "x": 0, + "y": 7 + }, + "id": 33, + "options": { + "colorMode": "value", + "graphMode": "area", + "justifyMode": "auto", + "orientation": "auto", + "reduceOptions": { + "calcs": ["lastNotNull"], + "fields": "/.*/", + "values": true + }, + "text": {}, + "textMode": "auto" + }, + "pluginVersion": "7.5.10", + "repeatDirection": "h", + "targets": [ + { + "alias": "dnodes", + "formatType": "Table", + "queryType": "SQL", + "refId": "A", + "sql": "select server_version()", + "target": "select metric", + "timeshift": { + "period": null + }, + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Server Version", + "transformations": [], + "type": "stat" + }, + { + "datasource": "${DS_TDENGINE}", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 3, + "w": 3, + "x": 2, + "y": 7 + }, + "id": 27, + "options": { + "colorMode": "value", + "graphMode": "area", + "justifyMode": "auto", + "orientation": "auto", + "reduceOptions": { + "calcs": ["lastNotNull"], + "fields": "", + "values": true + }, + "text": {}, + "textMode": "auto" + }, + "pluginVersion": "7.5.10", + "repeatDirection": "h", + "targets": [ + { + "alias": "dnodes", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "show mnodes", + "target": "select metric", + "timeshift": { + "period": null + }, + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Number of MNodes", + "transformations": [ + { + "id": "filterByValue", + "options": { + "filters": [ + { + "config": { + "id": "greater", + "options": { + "value": 0 + } + }, + "fieldName": "id" + } + ], + "match": "any", + "type": "include" + } + }, + { + "id": "reduce", + "options": { + "includeTimeField": false, + "mode": "reduceFields", + "reducers": ["count"] + } + }, + { + "id": "filterFieldsByName", + "options": { + "include": { + "names": ["id"] + } + } + } + ], + "type": "stat" + }, + { + "datasource": "${DS_TDENGINE}", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 3, + "w": 2, + "x": 5, + "y": 7 + }, + "id": 41, + "options": { + "colorMode": "value", + "graphMode": "none", + "justifyMode": "auto", + "orientation": "horizontal", + "reduceOptions": { + "calcs": ["last"], + "fields": "", + "values": false + }, + "text": {}, + "textMode": "value" + }, + "pluginVersion": "7.5.10", + "targets": [ + { + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "show dnodes", + "target": "select metric", + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Total Dnodes", + "transformations": [ + { + "id": "reduce", + "options": { + "includeTimeField": false, + "mode": "reduceFields", + "reducers": ["count"] + } + }, + { + "id": "filterFieldsByName", + "options": { + "include": { + "names": ["id"] + } + } + } + ], + "type": "stat" + }, + { + "datasource": "${DS_TDENGINE}", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 1 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 3, + "w": 2, + "x": 7, + "y": 7 + }, + "id": 31, + "options": { + "colorMode": "value", + "graphMode": "none", + "justifyMode": "auto", + "orientation": "horizontal", + "reduceOptions": { + "calcs": ["last"], + "fields": "", + "values": false + }, + "text": {}, + "textMode": "value" + }, + "pluginVersion": "7.5.10", + "targets": [ + { + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "show dnodes", + "target": "select metric", + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Offline Dnodes", + "transformations": [ + { + "id": "filterByValue", + "options": { + "filters": [ + { + "config": { + "id": "regex", + "options": { + "value": "ready" + } + }, + "fieldName": "status" + } + ], + "match": "all", + "type": "exclude" + } + }, + { + "id": "reduce", + "options": { + "includeTimeField": false, + "mode": "reduceFields", + "reducers": ["count"] + } + }, + { + "id": "filterFieldsByName", + "options": { + "include": { + "names": ["id"] + } + } + } + ], + "type": "stat" + }, + { + "datasource": "${DS_TDENGINE}", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 3, + "w": 3, + "x": 9, + "y": 7 + }, + "id": 65, + "options": { + "colorMode": "value", + "graphMode": "area", + "justifyMode": "auto", + "orientation": "auto", + "reduceOptions": { + "calcs": ["lastNotNull"], + "fields": "", + "values": true + }, + "text": {}, + "textMode": "auto" + }, + "pluginVersion": "7.5.10", + "repeatDirection": "h", + "targets": [ + { + "alias": "dnodes", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "show databases;", + "target": "select metric", + "timeshift": { + "period": null + }, + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Number of Databases", + "transformations": [ + { + "id": "reduce", + "options": { + "includeTimeField": false, + "mode": "reduceFields", + "reducers": ["count"] + } + }, + { + "id": "filterFieldsByName", + "options": { + "include": { + "names": ["name"] + } + } + } + ], + "type": "stat" + }, + { + "datasource": "${DS_TDENGINE}", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 3, + "w": 3, + "x": 12, + "y": 7 + }, + "id": 69, + "options": { + "colorMode": "value", + "graphMode": "area", + "justifyMode": "auto", + "orientation": "auto", + "reduceOptions": { + "calcs": ["lastNotNull"], + "fields": "", + "values": true + }, + "text": {}, + "textMode": "auto" + }, + "pluginVersion": "7.5.10", + "repeatDirection": "h", + "targets": [ + { + "alias": "dnodes", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "show databases;", + "target": "select metric", + "timeshift": { + "period": null + }, + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Total Number of Vgroups", + "transformations": [ + { + "id": "filterFieldsByName", + "options": { + "include": { + "names": ["vgroups"] + } + } + }, + { + "id": "reduce", + "options": { + "includeTimeField": false, + "mode": "reduceFields", + "reducers": ["sum"] + } + } + ], + "type": "stat" + }, + { + "datasource": "${DS_TDENGINE}", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "custom": { + "align": "center", + "displayMode": "auto", + "filterable": true + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + } + ] + } + }, + "overrides": [ + { + "matcher": { + "id": "byName", + "options": "role" + }, + "properties": [ + { + "id": "mappings", + "value": [ + { + "from": "", + "id": 1, + "text": "", + "to": "", + "type": 2, + "value": "" + } + ] + } + ] + } + ] + }, + "gridPos": { + "h": 3, + "w": 9, + "x": 0, + "y": 10 + }, + "id": 67, + "options": { + "showHeader": true + }, + "pluginVersion": "7.5.10", + "targets": [ + { + "formatType": "Table", + "queryType": "SQL", + "refId": "A", + "sql": "show dnodes", + "target": "select metric", + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Number of DNodes for each Role", + "transformations": [ + { + "id": "groupBy", + "options": { + "fields": { + "end_point": { + "aggregations": ["count"], + "operation": "aggregate" + }, + "role": { + "aggregations": [], + "operation": "groupby" + } + } + } + }, + { + "id": "filterFieldsByName", + "options": {} + }, + { + "id": "organize", + "options": { + "excludeByName": {}, + "indexByName": {}, + "renameByName": { + "end_point (count)": "Number of DNodes", + "role": "Dnode Role" + } + } + } + ], + "type": "table" + }, + { + "datasource": "${DS_TDENGINE}", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 3, + "w": 3, + "x": 9, + "y": 10 + }, + "id": 55, + "options": { + "colorMode": "value", + "graphMode": "area", + "justifyMode": "auto", + "orientation": "auto", + "reduceOptions": { + "calcs": ["lastNotNull"], + "fields": "", + "values": true + }, + "text": {}, + "textMode": "auto" + }, + "pluginVersion": "7.5.10", + "repeatDirection": "h", + "targets": [ + { + "alias": "dnodes", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "show connections", + "target": "select metric", + "timeshift": { + "period": null + }, + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Number of Connections", + "transformations": [ + { + "id": "reduce", + "options": { + "includeTimeField": false, + "mode": "reduceFields", + "reducers": ["count"] + } + }, + { + "id": "filterFieldsByName", + "options": { + "include": { + "names": ["connId"] + } + } + } + ], + "type": "stat" + }, + { + "datasource": "${DS_TDENGINE}", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 3, + "w": 3, + "x": 12, + "y": 10 + }, + "id": 68, + "options": { + "colorMode": "value", + "graphMode": "area", + "justifyMode": "auto", + "orientation": "auto", + "reduceOptions": { + "calcs": ["lastNotNull"], + "fields": "", + "values": true + }, + "text": {}, + "textMode": "auto" + }, + "pluginVersion": "7.5.10", + "repeatDirection": "h", + "targets": [ + { + "alias": "dnodes", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "show databases;", + "target": "select metric", + "timeshift": { + "period": null + }, + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Total Number of Tables", + "transformations": [ + { + "id": "filterFieldsByName", + "options": { + "include": { + "names": ["ntables"] + } + } + }, + { + "id": "reduce", + "options": { + "includeTimeField": false, + "mode": "reduceFields", + "reducers": ["sum"] + } + } + ], + "type": "stat" + }, + { + "collapsed": false, + "datasource": null, + "gridPos": { + "h": 1, + "w": 24, + "x": 0, + "y": 13 + }, + "id": 24, + "panels": [], + "title": "Dnodes Status", + "type": "row" + }, + { + "datasource": "${DS_TDENGINE}", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "custom": { + "align": "center", + "displayMode": "auto", + "filterable": true + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [ + { + "matcher": { + "id": "byName", + "options": "status" + }, + "properties": [ + { + "id": "custom.width", + "value": 86 + } + ] + }, + { + "matcher": { + "id": "byName", + "options": "vnodes" + }, + "properties": [ + { + "id": "custom.width", + "value": 77 + } + ] + }, + { + "matcher": { + "id": "byName", + "options": "role" + }, + "properties": [ + { + "id": "custom.width", + "value": 84 + } + ] + }, + { + "matcher": { + "id": "byName", + "options": "cores" + }, + "properties": [ + { + "id": "custom.width", + "value": 75 + } + ] + }, + { + "matcher": { + "id": "byName", + "options": "end_point" + }, + "properties": [ + { + "id": "custom.width", + "value": 205 + } + ] + }, + { + "matcher": { + "id": "byName", + "options": "id" + }, + "properties": [ + { + "id": "custom.width", + "value": 78 + } + ] + } + ] + }, + "gridPos": { + "h": 5, + "w": 16, + "x": 0, + "y": 14 + }, + "id": 36, + "options": { + "showHeader": true, + "sortBy": [] + }, + "pluginVersion": "7.5.10", + "targets": [ + { + "formatType": "Table", + "queryType": "SQL", + "refId": "A", + "sql": "show dnodes", + "target": "select metric", + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "DNodes Status", + "type": "table" + }, + { + "datasource": "${DS_TDENGINE}", + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 5, + "w": 8, + "x": 16, + "y": 14 + }, + "id": 40, + "options": { + "displayLabels": [], + "legend": { + "displayMode": "table", + "placement": "right", + "values": ["value"] + }, + "pieType": "pie", + "reduceOptions": { + "calcs": ["lastNotNull"], + "fields": "/.*/", + "values": false + }, + "text": { + "titleSize": 6 + } + }, + "pluginVersion": "7.5.10", + "targets": [ + { + "formatType": "Table", + "queryType": "SQL", + "refId": "A", + "sql": "show dnodes", + "target": "select metric", + "type": "timeserie" + } + ], + "title": "Offline Reasons", + "transformations": [ + { + "id": "filterByValue", + "options": { + "filters": [ + { + "config": { + "id": "regex", + "options": { + "value": "ready" + } + }, + "fieldName": "status" + } + ], + "match": "all", + "type": "exclude" + } + }, + { + "id": "filterFieldsByName", + "options": { + "include": { + "names": ["offline reason", "end_point"] + } + } + }, + { + "id": "groupBy", + "options": { + "fields": { + "Time": { + "aggregations": ["count"], + "operation": "aggregate" + }, + "end_point": { + "aggregations": ["count"], + "operation": "aggregate" + }, + "offline reason": { + "aggregations": [], + "operation": "groupby" + } + } + } + } + ], + "type": "piechart" + }, + { + "collapsed": false, + "datasource": null, + "gridPos": { + "h": 1, + "w": 24, + "x": 0, + "y": 19 + }, + "id": 22, + "panels": [], + "title": "Mnodes Status", + "type": "row" + }, + { + "datasource": "${DS_TDENGINE}", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "custom": { + "align": "center", + "filterable": false + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 5, + "w": 24, + "x": 0, + "y": 20 + }, + "id": 38, + "options": { + "showHeader": true + }, + "pluginVersion": "7.5.10", + "targets": [ + { + "formatType": "Table", + "queryType": "SQL", + "refId": "A", + "sql": "show mnodes;", + "target": "select metric", + "type": "timeserie" + } + ], + "title": "Mnodes Status", + "type": "table" + }, + { + "collapsed": false, + "datasource": null, + "gridPos": { + "h": 1, + "w": 24, + "x": 0, + "y": 25 + }, + "id": 20, + "panels": [], + "repeat": "fqdn", + "title": "节点资源占用 [ $fqdn ]", + "type": "row" + }, + { + "datasource": "${DS_TDENGINE}", + "description": "", + "fieldConfig": { + "defaults": { + "color": { + "mode": "continuous-GrYlRd" + }, + "mappings": [], + "min": 0, + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + } + ] + }, + "unit": "decmbytes" + }, + "overrides": [] + }, + "gridPos": { + "h": 6, + "w": 5, + "x": 0, + "y": 26 + }, + "id": 66, + "options": { + "orientation": "auto", + "reduceOptions": { + "calcs": ["mean"], + "fields": "/^taosd$/", + "values": false + }, + "showThresholdLabels": true, + "showThresholdMarkers": true, + "text": {} + }, + "pluginVersion": "7.5.10", + "targets": [ + { + "alias": "memory", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "select last(mem_taosd) as taosd, last(mem_total) as total from log.dn where fqdn = '$fqdn' and ts >= now -5m and ts < now", + "target": "select metric", + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Current Memory Usage of taosd", + "type": "gauge" + }, + { + "datasource": "${DS_TDENGINE}", + "description": "taosd max memery last 10 minutes", + "fieldConfig": { + "defaults": { + "color": { + "mode": "continuous-GrYlRd" + }, + "mappings": [], + "min": 0, + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "#EAB839", + "value": 0.5 + }, + { + "color": "red", + "value": 0.8 + } + ] + }, + "unit": "percentunit" + }, + "overrides": [ + { + "matcher": { + "id": "byName", + "options": "last(cpu_taosd)" + }, + "properties": [ + { + "id": "thresholds", + "value": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + } + ] + } + ] + }, + "gridPos": { + "h": 6, + "w": 5, + "x": 5, + "y": 26 + }, + "id": 45, + "options": { + "orientation": "auto", + "reduceOptions": { + "calcs": ["mean"], + "fields": "/^last\\(cpu_taosd\\)$/", + "values": false + }, + "showThresholdLabels": true, + "showThresholdMarkers": true, + "text": {} + }, + "pluginVersion": "7.5.10", + "targets": [ + { + "alias": "mem_taosd", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "select last(cpu_taosd) from log.dn where fqdn = '$fqdn'", + "target": "select metric", + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Current CPU Usage of taosd", + "type": "gauge" + }, + { + "datasource": "${DS_TDENGINE}", + "description": "avg band speed last one minute", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "mappings": [], + "max": 8192, + "min": 0, + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "#EAB839", + "value": 4916 + }, + { + "color": "red", + "value": 6554 + } + ] + }, + "unit": "Kbits" + }, + "overrides": [] + }, + "gridPos": { + "h": 6, + "w": 4, + "x": 10, + "y": 26 + }, + "id": 14, + "options": { + "orientation": "auto", + "reduceOptions": { + "calcs": ["last"], + "fields": "", + "values": false + }, + "showThresholdLabels": false, + "showThresholdMarkers": true, + "text": {} + }, + "pluginVersion": "7.5.10", + "targets": [ + { + "alias": "band_speed", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "select avg(band_speed) from log.dn where fqdn='$fqdn' and ts >= now-5m and ts < now interval(1m)", + "target": "select metric", + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "band speed", + "type": "gauge" + }, + { + "datasource": "${DS_TDENGINE}", + "description": "io read/write rate", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "mappings": [], + "max": 8192, + "min": 0, + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "#EAB839", + "value": 4916 + }, + { + "color": "red", + "value": 6554 + } + ] + }, + "unit": "Kbits" + }, + "overrides": [] + }, + "gridPos": { + "h": 6, + "w": 5, + "x": 14, + "y": 26 + }, + "id": 48, + "options": { + "orientation": "auto", + "reduceOptions": { + "calcs": ["last"], + "fields": "", + "values": false + }, + "showThresholdLabels": false, + "showThresholdMarkers": true, + "text": {} + }, + "pluginVersion": "7.5.10", + "targets": [ + { + "alias": "", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "select last(io_read) as io_read, last(io_write) as io_write from log.dn where fqdn='$fqdn' and ts >= now-1h and ts < now interval(1m)", + "target": "select metric", + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "IO Rate", + "type": "gauge" + }, + { + "datasource": "${DS_TDENGINE}", + "description": "", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "mappings": [], + "max": 1, + "min": 0, + "thresholds": { + "mode": "percentage", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "#EAB839", + "value": 75 + }, + { + "color": "red", + "value": 80 + }, + { + "color": "dark-red", + "value": 95 + } + ] + }, + "unit": "percentunit" + }, + "overrides": [] + }, + "gridPos": { + "h": 6, + "w": 5, + "x": 19, + "y": 26 + }, + "id": 51, + "options": { + "orientation": "auto", + "reduceOptions": { + "calcs": ["last"], + "fields": "/^disk_used_percent$/", + "values": false + }, + "showThresholdLabels": true, + "showThresholdMarkers": true, + "text": {} + }, + "pluginVersion": "7.5.10", + "targets": [ + { + "alias": "disk_used", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "select last(disk_used) as used from log.dn where fqdn = '$fqdn' and ts >= $from and ts < $to interval(1m)", + "target": "select metric", + "timeshift": { + "period": null + }, + "type": "timeserie" + }, + { + "alias": "disk_total", + "formatType": "Time series", + "hide": false, + "queryType": "SQL", + "refId": "B", + "sql": "select last(disk_total) as total from log.dn where fqdn = '$fqdn' and ts >= $from and ts < $to interval(1m)", + "target": "select metric", + "type": "timeserie" + }, + { + "alias": "disk_used_percent", + "expression": "A/B", + "formatType": "Time series", + "hide": false, + "queryType": "Arithmetic", + "refId": "C", + "target": "select metric", + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Disk Used", + "transformations": [ + { + "id": "reduce", + "options": { + "includeTimeField": false, + "mode": "reduceFields", + "reducers": ["lastNotNull"] + } + } + ], + "type": "gauge" + }, + { + "datasource": "${DS_TDENGINE}", + "description": "taosd max memery last 10 minutes", + "fieldConfig": { + "defaults": { + "color": { + "mode": "continuous-GrYlRd" + }, + "mappings": [], + "min": 0, + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + } + ] + }, + "unit": "decmbytes" + }, + "overrides": [] + }, + "gridPos": { + "h": 6, + "w": 5, + "x": 0, + "y": 32 + }, + "id": 12, + "options": { + "orientation": "auto", + "reduceOptions": { + "calcs": ["mean"], + "fields": "/^taosd$/", + "values": false + }, + "showThresholdLabels": true, + "showThresholdMarkers": true, + "text": {} + }, + "pluginVersion": "7.5.10", + "targets": [ + { + "alias": "memory", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "select max(mem_taosd) as taosd, max(mem_total) as total from log.dn where fqdn = '$fqdn' and ts >= now -5m and ts < now", + "target": "select metric", + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Max Memory Usage of taosd in Last 5 minute", + "type": "gauge" + }, + { + "datasource": "${DS_TDENGINE}", + "description": "taosd max memery last 10 minutes", + "fieldConfig": { + "defaults": { + "color": { + "mode": "continuous-GrYlRd" + }, + "mappings": [], + "max": 1, + "min": 0, + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "#EAB839", + "value": 0.5 + }, + { + "color": "red", + "value": 0.8 + } + ] + }, + "unit": "percentunit" + }, + "overrides": [] + }, + "gridPos": { + "h": 6, + "w": 5, + "x": 5, + "y": 32 + }, + "id": 43, + "options": { + "orientation": "auto", + "reduceOptions": { + "calcs": ["mean"], + "fields": "", + "values": false + }, + "showThresholdLabels": true, + "showThresholdMarkers": true, + "text": {} + }, + "pluginVersion": "7.5.10", + "targets": [ + { + "alias": "mem_taosd", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "select max(cpu_taosd) from log.dn where fqdn = '$fqdn' and ts >= now -5m and ts < now", + "target": "select metric", + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Max CPU Usage of taosd in Last 5 minute", + "type": "gauge" + }, + { + "datasource": "${DS_TDENGINE}", + "description": "avg band speed last one minute", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "mappings": [], + "max": 8192, + "min": 0, + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "#EAB839", + "value": 4916 + }, + { + "color": "red", + "value": 6554 + } + ] + }, + "unit": "Kbits" + }, + "overrides": [] + }, + "gridPos": { + "h": 6, + "w": 4, + "x": 10, + "y": 32 + }, + "id": 50, + "options": { + "orientation": "auto", + "reduceOptions": { + "calcs": ["last"], + "fields": "", + "values": false + }, + "showThresholdLabels": false, + "showThresholdMarkers": true, + "text": {} + }, + "pluginVersion": "7.5.10", + "targets": [ + { + "alias": "band_speed", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "select max(band_speed) from log.dn where fqdn = '$fqdn' and ts >= now-1h", + "target": "select metric", + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Max band speed in last hour", + "type": "gauge" + }, + { + "datasource": "${DS_TDENGINE}", + "description": "io read/write rate", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "mappings": [], + "max": 8192, + "min": 0, + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "#EAB839", + "value": 4916 + }, + { + "color": "red", + "value": 6554 + } + ] + }, + "unit": "Kbits" + }, + "overrides": [] + }, + "gridPos": { + "h": 6, + "w": 5, + "x": 14, + "y": 32 + }, + "id": 49, + "options": { + "orientation": "auto", + "reduceOptions": { + "calcs": ["last"], + "fields": "", + "values": false + }, + "showThresholdLabels": false, + "showThresholdMarkers": true, + "text": {} + }, + "pluginVersion": "7.5.10", + "targets": [ + { + "alias": "", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "select max(io_read) as io_read, max(io_write) as io_write from log.dn where fqdn = '$fqdn'", + "target": "select metric", + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Max IO Rate in last hour", + "type": "gauge" + }, + { + "datasource": "${DS_TDENGINE}", + "description": "io read/write rate", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "mappings": [], + "max": 8192, + "min": 0, + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "#EAB839", + "value": 4916 + }, + { + "color": "red", + "value": 6554 + } + ] + }, + "unit": "cpm" + }, + "overrides": [] + }, + "gridPos": { + "h": 6, + "w": 5, + "x": 19, + "y": 32 + }, + "id": 52, + "options": { + "orientation": "auto", + "reduceOptions": { + "calcs": ["last"], + "fields": "", + "values": false + }, + "showThresholdLabels": false, + "showThresholdMarkers": true, + "text": {} + }, + "pluginVersion": "7.5.10", + "targets": [ + { + "alias": "req-http", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "select sum(req_http) as req_http from log.dn where fqdn = '$fqdn' and ts >= now - 1h interval(1m)", + "target": "select metric", + "type": "timeserie" + }, + { + "alias": "req-inserts", + "formatType": "Time series", + "hide": false, + "queryType": "SQL", + "refId": "B", + "sql": "select sum(req_insert) as req_insert from log.dn where fqdn = '$fqdn' and ts >= now - 1h interval(1m)", + "target": "select metric", + "type": "timeserie" + }, + { + "alias": "req-selects", + "formatType": "Time series", + "hide": false, + "queryType": "SQL", + "refId": "C", + "sql": "select sum(req_select) as req_select from log.dn where fqdn = '$fqdn' and ts >= now - 1h interval(1m)", + "target": "select metric", + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Requests in last Minute", + "type": "gauge" + }, + { + "aliasColors": {}, + "bars": false, + "cacheTimeout": null, + "dashLength": 10, + "dashes": false, + "datasource": "${DS_TDENGINE}", + "description": "monitor system cpu", + "fieldConfig": { + "defaults": { + "links": [] + }, + "overrides": [] + }, + "fill": 1, + "fillGradient": 0, + "gridPos": { + "h": 11, + "w": 12, + "x": 0, + "y": 38 + }, + "hiddenSeries": false, + "hideTimeOverride": true, + "id": 2, + "legend": { + "avg": false, + "current": false, + "max": false, + "min": false, + "show": true, + "total": false, + "values": false + }, + "lines": true, + "linewidth": 1, + "links": [], + "nullPointMode": "null", + "options": { + "alertThreshold": true + }, + "percentage": false, + "pluginVersion": "7.5.10", + "pointradius": 2, + "points": false, + "renderer": "flot", + "seriesOverrides": [], + "spaceLength": 10, + "stack": false, + "steppedLine": false, + "targets": [ + { + "alias": "cpu_system", + "formatType": "Time series", + "hide": false, + "queryType": "SQL", + "refId": "A", + "sql": "select avg(cpu_system) from log.dn where fqdn='$fqdn' and ts >= now-1h and ts < now interval(30s)", + "target": "select metric", + "type": "timeserie" + }, + { + "alias": "cpu_taosd", + "formatType": "Time series", + "hide": false, + "queryType": "SQL", + "refId": "B", + "sql": "select avg(cpu_taosd) from log.dn where fqdn='$fqdn' and ts >= now-1h and ts < now interval(30s)", + "target": "select metric", + "type": "timeserie" + } + ], + "thresholds": [], + "timeFrom": "1h", + "timeRegions": [], + "timeShift": "30s", + "title": "CPU 资源占用情况", + "tooltip": { + "shared": true, + "sort": 0, + "value_type": "individual" + }, + "type": "graph", + "xaxis": { + "buckets": null, + "mode": "time", + "name": null, + "show": true, + "values": [] + }, + "yaxes": [ + { + "decimals": null, + "format": "percent", + "label": "使用占比", + "logBase": 1, + "max": null, + "min": null, + "show": true + }, + { + "format": "short", + "label": null, + "logBase": 1, + "max": null, + "min": null, + "show": false + } + ], + "yaxis": { + "align": false, + "alignLevel": null + } + }, + { + "aliasColors": {}, + "bars": false, + "cacheTimeout": null, + "dashLength": 10, + "dashes": false, + "datasource": "${DS_TDENGINE}", + "description": "monitor system cpu", + "fieldConfig": { + "defaults": { + "links": [] + }, + "overrides": [] + }, + "fill": 1, + "fillGradient": 0, + "gridPos": { + "h": 11, + "w": 12, + "x": 12, + "y": 38 + }, + "hiddenSeries": false, + "hideTimeOverride": true, + "id": 42, + "legend": { + "avg": false, + "current": false, + "max": false, + "min": false, + "show": true, + "total": false, + "values": false + }, + "lines": true, + "linewidth": 1, + "links": [], + "nullPointMode": "null", + "options": { + "alertThreshold": true + }, + "percentage": false, + "pluginVersion": "7.5.10", + "pointradius": 2, + "points": false, + "renderer": "flot", + "seriesOverrides": [], + "spaceLength": 10, + "stack": false, + "steppedLine": false, + "targets": [ + { + "alias": "system", + "formatType": "Time series", + "hide": false, + "queryType": "SQL", + "refId": "A", + "sql": "select avg(mem_system) from log.dn where fqdn = '$fqdn' and ts >= now-1h and ts < now interval(30s)", + "target": "select metric", + "type": "timeserie" + }, + { + "alias": "taosd", + "formatType": "Time series", + "hide": false, + "queryType": "SQL", + "refId": "B", + "sql": "select avg(mem_taosd) from log.dn where fqdn = '$fqdn' and ts >= now-1h and ts < now interval(30s)", + "target": "select metric", + "type": "timeserie" + }, + { + "alias": "total", + "formatType": "Time series", + "hide": false, + "queryType": "SQL", + "refId": "C", + "sql": "select avg(mem_total) from log.dn where fqdn = '$fqdn' and ts >= now-1h and ts < now interval(30s)", + "target": "select metric", + "type": "timeserie" + } + ], + "thresholds": [], + "timeFrom": "1h", + "timeRegions": [], + "timeShift": "30s", + "title": "内存资源占用情况", + "tooltip": { + "shared": true, + "sort": 0, + "value_type": "individual" + }, + "type": "graph", + "xaxis": { + "buckets": null, + "mode": "time", + "name": null, + "show": true, + "values": [] + }, + "yaxes": [ + { + "decimals": null, + "format": "decmbytes", + "label": "使用占比", + "logBase": 1, + "max": null, + "min": null, + "show": true + }, + { + "format": "short", + "label": null, + "logBase": 1, + "max": null, + "min": null, + "show": false + } + ], + "yaxis": { + "align": false, + "alignLevel": null + } + }, + { + "aliasColors": {}, + "bars": false, + "dashLength": 10, + "dashes": false, + "datasource": "${DS_TDENGINE}", + "fieldConfig": { + "defaults": {}, + "overrides": [] + }, + "fill": 1, + "fillGradient": 0, + "gridPos": { + "h": 9, + "w": 12, + "x": 0, + "y": 49 + }, + "hiddenSeries": false, + "id": 54, + "legend": { + "alignAsTable": false, + "avg": false, + "current": true, + "max": false, + "min": false, + "rightSide": false, + "show": true, + "total": false, + "values": true + }, + "lines": true, + "linewidth": 1, + "nullPointMode": "null", + "options": { + "alertThreshold": true + }, + "percentage": false, + "pluginVersion": "7.5.10", + "pointradius": 2, + "points": false, + "renderer": "flot", + "seriesOverrides": [ + { + "alias": "percent", + "yaxis": 2 + } + ], + "spaceLength": 10, + "stack": false, + "steppedLine": false, + "targets": [ + { + "alias": "disk_used", + "formatType": "Time series", + "hide": false, + "queryType": "SQL", + "refId": "A", + "sql": "select avg(disk_used) from log.dn where fqdn = '$fqdn' and ts >= $from and ts < $to interval(30s)", + "target": "select metric", + "timeshift": { + "period": null + }, + "type": "timeserie" + }, + { + "alias": "disk_total", + "formatType": "Time series", + "hide": false, + "queryType": "SQL", + "refId": "B", + "sql": "select avg(disk_total) from log.dn where fqdn = '$fqdn' and ts >= $from and ts < $to interval(30s)", + "target": "select metric", + "timeshift": { + "period": null + }, + "type": "timeserie" + }, + { + "alias": "percent", + "formatType": "Time series", + "hide": false, + "queryType": "SQL", + "refId": "D", + "sql": "select avg(disk_used)/avg(disk_total) * 100 from log.dn where fqdn = '$fqdn' and ts >= $from and ts < $to interval(30s)", + "target": "select metric", + "timeshift": { + "period": null + }, + "type": "timeserie" + } + ], + "thresholds": [], + "timeFrom": null, + "timeRegions": [], + "timeShift": null, + "title": "Disk Used Percent", + "tooltip": { + "shared": false, + "sort": 0, + "value_type": "individual" + }, + "type": "graph", + "xaxis": { + "buckets": null, + "mode": "time", + "name": null, + "show": true, + "values": [] + }, + "yaxes": [ + { + "format": "gbytes", + "label": null, + "logBase": 1, + "max": null, + "min": null, + "show": true + }, + { + "format": "percent", + "label": "Disk Used", + "logBase": 1, + "max": null, + "min": null, + "show": true + } + ], + "yaxis": { + "align": false, + "alignLevel": null + } + }, + { + "aliasColors": {}, + "bars": false, + "dashLength": 10, + "dashes": false, + "datasource": "${DS_TDENGINE}", + "fieldConfig": { + "defaults": {}, + "overrides": [] + }, + "fill": 1, + "fillGradient": 0, + "gridPos": { + "h": 9, + "w": 12, + "x": 12, + "y": 49 + }, + "hiddenSeries": false, + "id": 64, + "legend": { + "alignAsTable": false, + "avg": false, + "current": true, + "max": false, + "min": false, + "rightSide": false, + "show": true, + "total": false, + "values": true + }, + "lines": true, + "linewidth": 1, + "nullPointMode": "null", + "options": { + "alertThreshold": true + }, + "percentage": false, + "pluginVersion": "7.5.10", + "pointradius": 2, + "points": false, + "renderer": "flot", + "seriesOverrides": [], + "spaceLength": 10, + "stack": false, + "steppedLine": false, + "targets": [ + { + "alias": "disk_used", + "formatType": "Time series", + "hide": false, + "queryType": "SQL", + "refId": "A", + "sql": "select derivative(value, 1m, 0) from (select avg(disk_used) as value from log.dn where fqdn = '$fqdn' and ts >= $from and ts < $to interval(1m))", + "target": "select metric", + "timeshift": { + "period": null + }, + "type": "timeserie" + } + ], + "thresholds": [], + "timeFrom": null, + "timeRegions": [], + "timeShift": null, + "title": "Disk Used Increasing Rate per Minute", + "tooltip": { + "shared": false, + "sort": 0, + "value_type": "individual" + }, + "type": "graph", + "xaxis": { + "buckets": null, + "mode": "time", + "name": null, + "show": true, + "values": [] + }, + "yaxes": [ + { + "format": "percentunit", + "label": null, + "logBase": 1, + "max": null, + "min": null, + "show": true + }, + { + "format": "percentunit", + "label": "Disk Used", + "logBase": 1, + "max": null, + "min": null, + "show": true + } + ], + "yaxis": { + "align": false, + "alignLevel": null + } + }, + { + "aliasColors": {}, + "bars": false, + "cacheTimeout": null, + "dashLength": 10, + "dashes": false, + "datasource": "${DS_TDENGINE}", + "description": "total select request per minute last hour", + "fieldConfig": { + "defaults": { + "unit": "cpm" + }, + "overrides": [] + }, + "fill": 1, + "fillGradient": 0, + "gridPos": { + "h": 9, + "w": 12, + "x": 0, + "y": 58 + }, + "hiddenSeries": false, + "id": 8, + "interval": null, + "legend": { + "avg": false, + "current": false, + "max": false, + "min": false, + "show": true, + "total": false, + "values": false + }, + "lines": true, + "linewidth": 1, + "links": [], + "maxDataPoints": 100, + "nullPointMode": "null", + "options": { + "alertThreshold": true + }, + "percentage": false, + "pluginVersion": "7.5.10", + "pointradius": 2, + "points": false, + "renderer": "flot", + "seriesOverrides": [], + "spaceLength": 10, + "stack": false, + "steppedLine": false, + "targets": [ + { + "alias": "req_select", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "select sum(req_select) from log.dn where fqdn = '$fqdn' and ts >= $from and ts < $to interval(1m)", + "target": "select metric", + "timeshift": { + "period": null + }, + "type": "timeserie" + }, + { + "alias": "req_insert", + "formatType": "Time series", + "hide": false, + "queryType": "SQL", + "refId": "B", + "sql": "select sum(req_insert) from log.dn where fqdn = '$fqdn' and ts >= $from and ts < $to interval(1m)", + "target": "select metric", + "type": "timeserie" + }, + { + "alias": "req_http", + "formatType": "Time series", + "hide": false, + "queryType": "SQL", + "refId": "C", + "sql": "select sum(req_http) from log.dn where fqdn = '$fqdn' and ts >= $from and ts < $to interval(1m)", + "target": "select metric", + "type": "timeserie" + } + ], + "thresholds": [], + "timeFrom": null, + "timeRegions": [], + "timeShift": null, + "title": "Requets Count per Minutes $fqdn", + "tooltip": { + "shared": true, + "sort": 0, + "value_type": "individual" + }, + "type": "graph", + "xaxis": { + "buckets": null, + "mode": "time", + "name": null, + "show": true, + "values": [] + }, + "yaxes": [ + { + "format": "cpm", + "label": null, + "logBase": 1, + "max": null, + "min": "0", + "show": true + }, + { + "format": "short", + "label": null, + "logBase": 1, + "max": null, + "min": null, + "show": true + } + ], + "yaxis": { + "align": false, + "alignLevel": null + } + }, + { + "aliasColors": {}, + "bars": false, + "cacheTimeout": null, + "dashLength": 10, + "dashes": false, + "datasource": "${DS_TDENGINE}", + "description": "io", + "fieldConfig": { + "defaults": { + "links": [], + "unit": "Kbits" + }, + "overrides": [] + }, + "fill": 1, + "fillGradient": 0, + "gridPos": { + "h": 9, + "w": 12, + "x": 12, + "y": 58 + }, + "hiddenSeries": false, + "hideTimeOverride": true, + "id": 47, + "legend": { + "avg": false, + "current": false, + "max": false, + "min": false, + "show": true, + "total": false, + "values": false + }, + "lines": true, + "linewidth": 1, + "links": [], + "nullPointMode": "null", + "options": { + "alertThreshold": true + }, + "percentage": false, + "pluginVersion": "7.5.10", + "pointradius": 2, + "points": false, + "renderer": "flot", + "seriesOverrides": [], + "spaceLength": 10, + "stack": false, + "steppedLine": false, + "targets": [ + { + "alias": "io-read", + "formatType": "Time series", + "hide": false, + "queryType": "SQL", + "refId": "A", + "sql": "select avg(io_read) from log.dn where fqdn = '$fqdn' and ts >= now-1h and ts < now interval(1m)", + "target": "select metric", + "type": "timeserie" + }, + { + "alias": "io-write", + "formatType": "Time series", + "hide": false, + "queryType": "SQL", + "refId": "B", + "sql": "select avg(io_write) from log.dn where fqdn = '$fqdn' and ts >= now-1h and ts < now interval(1m)", + "target": "select metric", + "type": "timeserie" + }, + { + "alias": "io-read-last-hour", + "formatType": "Time series", + "hide": false, + "queryType": "SQL", + "refId": "C", + "sql": "select avg(io_read) from log.dn where fqdn = '$fqdn' and ts >= now-2h and ts < now - 1h interval(1m)", + "target": "select metric", + "timeshift": { + "period": 1, + "unit": "hours" + }, + "type": "timeserie" + }, + { + "alias": "io-write-last-hour", + "formatType": "Time series", + "hide": false, + "queryType": "SQL", + "refId": "D", + "sql": "select avg(io_write) from log.dn where fqdn = '$fqdn' and ts >= now-1h and ts < now interval(1m)", + "target": "select metric", + "timeshift": { + "period": 1, + "unit": "hours" + }, + "type": "timeserie" + } + ], + "thresholds": [], + "timeFrom": "1h", + "timeRegions": [], + "timeShift": "30s", + "title": "IO", + "tooltip": { + "shared": true, + "sort": 0, + "value_type": "individual" + }, + "type": "graph", + "xaxis": { + "buckets": null, + "mode": "time", + "name": null, + "show": true, + "values": [] + }, + "yaxes": [ + { + "decimals": null, + "format": "Kbits", + "label": "IO Rate", + "logBase": 1, + "max": null, + "min": null, + "show": true + }, + { + "format": "short", + "label": null, + "logBase": 1, + "max": null, + "min": null, + "show": false + } + ], + "yaxis": { + "align": false, + "alignLevel": null + } + }, + { + "collapsed": false, + "datasource": null, + "gridPos": { + "h": 1, + "w": 24, + "x": 0, + "y": 67 + }, + "id": 63, + "panels": [], + "title": "Login History", + "type": "row" + }, + { + "aliasColors": {}, + "bars": false, + "dashLength": 10, + "dashes": false, + "datasource": "${DS_TDENGINE}", + "fieldConfig": { + "defaults": { + "displayName": "Logins Per Minute", + "unit": "cpm" + }, + "overrides": [] + }, + "fill": 1, + "fillGradient": 0, + "gridPos": { + "h": 8, + "w": 12, + "x": 0, + "y": 68 + }, + "hiddenSeries": false, + "id": 61, + "legend": { + "avg": false, + "current": false, + "max": false, + "min": false, + "show": true, + "total": false, + "values": false + }, + "lines": true, + "linewidth": 1, + "nullPointMode": "null", + "options": { + "alertThreshold": true + }, + "percentage": false, + "pluginVersion": "7.5.10", + "pointradius": 2, + "points": false, + "renderer": "flot", + "seriesOverrides": [ + { + "alias": "logins", + "nullPointMode": "null as zero" + } + ], + "spaceLength": 10, + "stack": false, + "steppedLine": false, + "targets": [ + { + "alias": "logins", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "select count(*) from log.log where ts >= $from and ts < $to interval (1m)", + "target": "select metric", + "type": "timeserie" + } + ], + "thresholds": [], + "timeFrom": null, + "timeRegions": [], + "timeShift": null, + "title": "Login Counts per Minute", + "tooltip": { + "shared": true, + "sort": 0, + "value_type": "individual" + }, + "type": "graph", + "xaxis": { + "buckets": null, + "mode": "time", + "name": null, + "show": true, + "values": [] + }, + "yaxes": [ + { + "format": "cpm", + "label": null, + "logBase": 1, + "max": null, + "min": null, + "show": true + }, + { + "format": "short", + "label": null, + "logBase": 1, + "max": null, + "min": null, + "show": true + } + ], + "yaxis": { + "align": false, + "alignLevel": null + } + } + ], + "refresh": "1m", + "schemaVersion": 27, + "style": "dark", + "tags": ["TDengine", "multiple"], + "templating": { + "list": [ + { + "current": { + "selected": false, + "text": "TDengine", + "value": "TDengine" + }, + "description": "TDengine Data Source Selector", + "error": null, + "hide": 0, + "includeAll": false, + "label": "Datasource", + "multi": false, + "name": "ds", + "options": [], + "query": "tdengine-datasource", + "queryValue": "", + "refresh": 1, + "regex": "", + "skipUrlSync": false, + "type": "datasource" + }, + { + "allValue": null, + "current": {}, + "datasource": "${DS_TDENGINE}", + "definition": "select fqdn from log.dn", + "description": "TDengine Nodes FQDN (Hostname)", + "error": null, + "hide": 0, + "includeAll": false, + "label": null, + "multi": false, + "name": "fqdn", + "options": [], + "query": "select fqdn from log.dn", + "refresh": 1, + "regex": "", + "skipUrlSync": false, + "sort": 0, + "tagValuesQuery": "", + "tags": [], + "tagsQuery": "", + "type": "query", + "useTags": false + } + ] + }, + "time": { + "from": "now-1h", + "to": "now" + }, + "timepicker": { + "refresh_intervals": ["5s", "10s", "30s", "1m", "5m", "15m", "30m", "1h", "2h", "1d"] + }, + "timezone": "", + "title": "Multiple TDengines Monitoring", + "uid": "tdengine-multiple", + "version": 4 +} diff --git a/docs-cn/14-reference/07-tdinsight/assets/15155-tdengine-alert-demo.json b/docs-cn/14-reference/07-tdinsight/assets/15155-tdengine-alert-demo.json new file mode 100644 index 0000000000000000000000000000000000000000..ab98354aaeae8c4dc945aae085d12fec50b530d1 --- /dev/null +++ b/docs-cn/14-reference/07-tdinsight/assets/15155-tdengine-alert-demo.json @@ -0,0 +1,212 @@ +{ + "__inputs": [ + { + "name": "DS_TDENGINE", + "label": "TDengine", + "description": "", + "type": "datasource", + "pluginId": "tdengine-datasource", + "pluginName": "TDengine" + } + ], + "__requires": [ + { + "type": "grafana", + "id": "grafana", + "name": "Grafana", + "version": "7.5.10" + }, + { + "type": "panel", + "id": "graph", + "name": "Graph", + "version": "" + }, + { + "type": "datasource", + "id": "tdengine-datasource", + "name": "TDengine", + "version": "3.1.0" + } + ], + "annotations": { + "list": [ + { + "builtIn": 1, + "datasource": "-- Grafana --", + "enable": true, + "hide": true, + "iconColor": "rgba(0, 211, 255, 1)", + "name": "Annotations & Alerts", + "type": "dashboard" + } + ] + }, + "description": "", + "editable": true, + "gnetId": null, + "graphTooltip": 0, + "id": null, + "links": [], + "panels": [ + { + "alert": { + "alertRuleTags": {}, + "conditions": [ + { + "evaluator": { + "params": [5], + "type": "gt" + }, + "operator": { + "type": "and" + }, + "query": { + "params": ["A", "10s", "now"] + }, + "reducer": { + "params": [], + "type": "avg" + }, + "type": "query" + } + ], + "executionErrorState": "alerting", + "for": "5m", + "frequency": "10s", + "handler": 1, + "message": "This is a alert demo!", + "name": "cpu load average alert", + "noDataState": "no_data", + "notifications": [ + { + "uid": "4sKm9jd7k" + }, + { + "uid": "QyczKkFnk" + } + ] + }, + "aliasColors": {}, + "bars": false, + "dashLength": 10, + "dashes": false, + "datasource": "${DS_TDENGINE}", + "decimals": null, + "fieldConfig": { + "defaults": {}, + "overrides": [] + }, + "fill": 1, + "fillGradient": 0, + "gridPos": { + "h": 9, + "w": 12, + "x": 0, + "y": 0 + }, + "hiddenSeries": false, + "id": 2, + "legend": { + "avg": true, + "current": true, + "hideEmpty": false, + "max": true, + "min": true, + "show": true, + "total": false, + "values": true + }, + "lines": true, + "linewidth": 1, + "nullPointMode": "null", + "options": { + "alertThreshold": true + }, + "percentage": false, + "pluginVersion": "7.5.10", + "pointradius": 2, + "points": false, + "renderer": "flot", + "seriesOverrides": [], + "spaceLength": 10, + "stack": false, + "steppedLine": false, + "targets": [ + { + "alias": "system", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "select avg(cpu_system) as system from log.dn where ts >= now-1h and ts < now interval(30s)", + "target": "select metric", + "type": "timeserie" + } + ], + "thresholds": [ + { + "colorMode": "critical", + "fill": true, + "line": true, + "op": "gt", + "value": 5, + "visible": true + } + ], + "timeFrom": null, + "timeRegions": [], + "timeShift": null, + "title": "CPU Load Average", + "tooltip": { + "shared": true, + "sort": 0, + "value_type": "individual" + }, + "type": "graph", + "xaxis": { + "buckets": null, + "mode": "time", + "name": null, + "show": true, + "values": [] + }, + "yaxes": [ + { + "format": "percent", + "label": "Percent", + "logBase": 1, + "max": null, + "min": null, + "show": true + }, + { + "format": "short", + "label": "", + "logBase": 1, + "max": null, + "min": null, + "show": false + } + ], + "yaxis": { + "align": false, + "alignLevel": null + } + } + ], + "schemaVersion": 27, + "style": "dark", + "tags": ["TDengine"], + "templating": { + "list": [] + }, + "time": { + "from": "now-1h", + "to": "now" + }, + "timepicker": {}, + "timezone": "", + "title": "TDengine Alert Demo", + "uid": "aLN9ujOnk", + "version": 15 +} diff --git a/docs-cn/14-reference/07-tdinsight/assets/TDinsight-1-cluster-status.png b/docs-cn/14-reference/07-tdinsight/assets/TDinsight-1-cluster-status.png new file mode 100644 index 0000000000000000000000000000000000000000..4708f836feb21980f2db7fed4a55f799b23a6ec1 Binary files /dev/null and b/docs-cn/14-reference/07-tdinsight/assets/TDinsight-1-cluster-status.png differ diff --git a/docs-cn/14-reference/07-tdinsight/assets/TDinsight-2-dnodes.png b/docs-cn/14-reference/07-tdinsight/assets/TDinsight-2-dnodes.png new file mode 100644 index 0000000000000000000000000000000000000000..f2684e6eed70e8f56697eae42b495d6bd62815e8 Binary files /dev/null and b/docs-cn/14-reference/07-tdinsight/assets/TDinsight-2-dnodes.png differ diff --git a/docs-cn/14-reference/07-tdinsight/assets/TDinsight-3-mnodes.png b/docs-cn/14-reference/07-tdinsight/assets/TDinsight-3-mnodes.png new file mode 100644 index 0000000000000000000000000000000000000000..74686691e4106b8646c3deee1e0ce73b2f53f1ea Binary files /dev/null and b/docs-cn/14-reference/07-tdinsight/assets/TDinsight-3-mnodes.png differ diff --git a/docs-cn/14-reference/07-tdinsight/assets/TDinsight-4-requests.png b/docs-cn/14-reference/07-tdinsight/assets/TDinsight-4-requests.png new file mode 100644 index 0000000000000000000000000000000000000000..27964215567f9f961c0aeaf1b863188437008fb7 Binary files /dev/null and b/docs-cn/14-reference/07-tdinsight/assets/TDinsight-4-requests.png differ diff --git a/docs-cn/14-reference/07-tdinsight/assets/TDinsight-5-database.png b/docs-cn/14-reference/07-tdinsight/assets/TDinsight-5-database.png new file mode 100644 index 0000000000000000000000000000000000000000..b0d3abbf21ec4d4bd7bfb95fcc03a5f936b22665 Binary files /dev/null and b/docs-cn/14-reference/07-tdinsight/assets/TDinsight-5-database.png differ diff --git a/docs-cn/14-reference/07-tdinsight/assets/TDinsight-6-dnode-usage.png b/docs-cn/14-reference/07-tdinsight/assets/TDinsight-6-dnode-usage.png new file mode 100644 index 0000000000000000000000000000000000000000..2b54cbeb83bcff12f20461a4f57f882e2073f231 Binary files /dev/null and b/docs-cn/14-reference/07-tdinsight/assets/TDinsight-6-dnode-usage.png differ diff --git a/docs-cn/14-reference/07-tdinsight/assets/TDinsight-7-login-history.png b/docs-cn/14-reference/07-tdinsight/assets/TDinsight-7-login-history.png new file mode 100644 index 0000000000000000000000000000000000000000..eb3848657f13900c856ac595c20766465157e9c4 Binary files /dev/null and b/docs-cn/14-reference/07-tdinsight/assets/TDinsight-7-login-history.png differ diff --git a/docs-cn/14-reference/07-tdinsight/assets/TDinsight-8-taosadapter.png b/docs-cn/14-reference/07-tdinsight/assets/TDinsight-8-taosadapter.png new file mode 100644 index 0000000000000000000000000000000000000000..d94b2e02ac9855bb3d2f77d8902e068839db364f Binary files /dev/null and b/docs-cn/14-reference/07-tdinsight/assets/TDinsight-8-taosadapter.png differ diff --git a/docs-cn/14-reference/07-tdinsight/assets/TDinsight-full.png b/docs-cn/14-reference/07-tdinsight/assets/TDinsight-full.png new file mode 100644 index 0000000000000000000000000000000000000000..654df2934597ce600a1dc2dcd0cab7e29de7076d Binary files /dev/null and b/docs-cn/14-reference/07-tdinsight/assets/TDinsight-full.png differ diff --git a/docs-cn/14-reference/07-tdinsight/assets/alert-manager-status.png b/docs-cn/14-reference/07-tdinsight/assets/alert-manager-status.png new file mode 100644 index 0000000000000000000000000000000000000000..e3afa22c0326d70567ec4529c83101c746daac87 Binary files /dev/null and b/docs-cn/14-reference/07-tdinsight/assets/alert-manager-status.png differ diff --git a/docs-cn/14-reference/07-tdinsight/assets/alert-notification-channel.png b/docs-cn/14-reference/07-tdinsight/assets/alert-notification-channel.png new file mode 100644 index 0000000000000000000000000000000000000000..198bf37141c86a66cdd91b47a331bcdeb83daaf8 Binary files /dev/null and b/docs-cn/14-reference/07-tdinsight/assets/alert-notification-channel.png differ diff --git a/docs-cn/14-reference/07-tdinsight/assets/alert-query-demo.png b/docs-cn/14-reference/07-tdinsight/assets/alert-query-demo.png new file mode 100644 index 0000000000000000000000000000000000000000..ace3aa3c2f8f14fabdac54bc25ae2d9449445b69 Binary files /dev/null and b/docs-cn/14-reference/07-tdinsight/assets/alert-query-demo.png differ diff --git a/docs-cn/14-reference/07-tdinsight/assets/alert-rule-condition-notifications.png b/docs-cn/14-reference/07-tdinsight/assets/alert-rule-condition-notifications.png new file mode 100644 index 0000000000000000000000000000000000000000..7082e49f6beb8690c36f98a3f4ff2befdb8fd014 Binary files /dev/null and b/docs-cn/14-reference/07-tdinsight/assets/alert-rule-condition-notifications.png differ diff --git a/docs-cn/14-reference/07-tdinsight/assets/alert-rule-test.png b/docs-cn/14-reference/07-tdinsight/assets/alert-rule-test.png new file mode 100644 index 0000000000000000000000000000000000000000..ffd4911b53854c42dbf0ff11838cb604fa694138 Binary files /dev/null and b/docs-cn/14-reference/07-tdinsight/assets/alert-rule-test.png differ diff --git a/docs-cn/14-reference/07-tdinsight/assets/howto-add-datasource-button.png b/docs-cn/14-reference/07-tdinsight/assets/howto-add-datasource-button.png new file mode 100644 index 0000000000000000000000000000000000000000..802c7366f921301bd7fbc62458e56b2d1eaf195c Binary files /dev/null and b/docs-cn/14-reference/07-tdinsight/assets/howto-add-datasource-button.png differ diff --git a/docs-cn/14-reference/07-tdinsight/assets/howto-add-datasource-tdengine.png b/docs-cn/14-reference/07-tdinsight/assets/howto-add-datasource-tdengine.png new file mode 100644 index 0000000000000000000000000000000000000000..019ec921b6f808671f4f864ddf3380159d4a0dcc Binary files /dev/null and b/docs-cn/14-reference/07-tdinsight/assets/howto-add-datasource-tdengine.png differ diff --git a/docs-cn/14-reference/07-tdinsight/assets/howto-add-datasource-test.png b/docs-cn/14-reference/07-tdinsight/assets/howto-add-datasource-test.png new file mode 100644 index 0000000000000000000000000000000000000000..3963abb4ea8ae0e6f5557466f7a5b746c2d2ea3c Binary files /dev/null and b/docs-cn/14-reference/07-tdinsight/assets/howto-add-datasource-test.png differ diff --git a/docs-cn/14-reference/07-tdinsight/assets/howto-add-datasource.png b/docs-cn/14-reference/07-tdinsight/assets/howto-add-datasource.png new file mode 100644 index 0000000000000000000000000000000000000000..837100464b35a5cafac474723aef603f91945ebc Binary files /dev/null and b/docs-cn/14-reference/07-tdinsight/assets/howto-add-datasource.png differ diff --git a/docs-cn/14-reference/07-tdinsight/assets/howto-dashboard-display.png b/docs-cn/14-reference/07-tdinsight/assets/howto-dashboard-display.png new file mode 100644 index 0000000000000000000000000000000000000000..98223df25499effac343ff5723544a3c289f18fa Binary files /dev/null and b/docs-cn/14-reference/07-tdinsight/assets/howto-dashboard-display.png differ diff --git a/docs-cn/14-reference/07-tdinsight/assets/howto-dashboard-import-options.png b/docs-cn/14-reference/07-tdinsight/assets/howto-dashboard-import-options.png new file mode 100644 index 0000000000000000000000000000000000000000..07aba348f02b4fb8ef68e79664920c119b842d4c Binary files /dev/null and b/docs-cn/14-reference/07-tdinsight/assets/howto-dashboard-import-options.png differ diff --git a/docs-cn/14-reference/07-tdinsight/assets/howto-import-dashboard.png b/docs-cn/14-reference/07-tdinsight/assets/howto-import-dashboard.png new file mode 100644 index 0000000000000000000000000000000000000000..7e28939ead8bf3b6e2b4330e4f9b59c2e39b5c1c Binary files /dev/null and b/docs-cn/14-reference/07-tdinsight/assets/howto-import-dashboard.png differ diff --git a/docs-cn/14-reference/07-tdinsight/assets/import-dashboard-15167.png b/docs-cn/14-reference/07-tdinsight/assets/import-dashboard-15167.png new file mode 100644 index 0000000000000000000000000000000000000000..981f640b14d18aa6f0682768d8405a232df500f6 Binary files /dev/null and b/docs-cn/14-reference/07-tdinsight/assets/import-dashboard-15167.png differ diff --git a/docs-cn/14-reference/07-tdinsight/assets/import-dashboard-for-tdengine.png b/docs-cn/14-reference/07-tdinsight/assets/import-dashboard-for-tdengine.png new file mode 100644 index 0000000000000000000000000000000000000000..94ef4fa5fe63e535118a81707b413c028ce01f70 Binary files /dev/null and b/docs-cn/14-reference/07-tdinsight/assets/import-dashboard-for-tdengine.png differ diff --git a/docs-cn/14-reference/07-tdinsight/assets/import-via-grafana-dot-com.png b/docs-cn/14-reference/07-tdinsight/assets/import-via-grafana-dot-com.png new file mode 100644 index 0000000000000000000000000000000000000000..670cacc377c2801fa9437c3c132c5c7fbc361b0f Binary files /dev/null and b/docs-cn/14-reference/07-tdinsight/assets/import-via-grafana-dot-com.png differ diff --git a/docs-cn/14-reference/07-tdinsight/assets/import_dashboard.png b/docs-cn/14-reference/07-tdinsight/assets/import_dashboard.png new file mode 100644 index 0000000000000000000000000000000000000000..d74cd36c96ee0fd24ddc6feae2da07824816f745 Binary files /dev/null and b/docs-cn/14-reference/07-tdinsight/assets/import_dashboard.png differ diff --git a/docs-cn/14-reference/07-tdinsight/assets/tdengine-grafana-7.x.json b/docs-cn/14-reference/07-tdinsight/assets/tdengine-grafana-7.x.json new file mode 100644 index 0000000000000000000000000000000000000000..b4254c428b28a0084e54b5e3c509dd2e0ec651b9 --- /dev/null +++ b/docs-cn/14-reference/07-tdinsight/assets/tdengine-grafana-7.x.json @@ -0,0 +1,3358 @@ +{ + "annotations": { + "list": [ + { + "builtIn": 1, + "datasource": "-- Grafana --", + "enable": true, + "hide": true, + "iconColor": "rgba(0, 211, 255, 1)", + "name": "Annotations & Alerts", + "type": "dashboard" + } + ] + }, + "description": "TDengine nodes metrics.", + "editable": true, + "gnetId": null, + "graphTooltip": 0, + "id": 3, + "iteration": 1634275785625, + "links": [], + "panels": [ + { + "collapsed": false, + "datasource": null, + "gridPos": { + "h": 1, + "w": 24, + "x": 0, + "y": 0 + }, + "id": 57, + "panels": [], + "title": "Cluster Status", + "type": "row" + }, + { + "datasource": null, + "fieldConfig": { + "defaults": {}, + "overrides": [] + }, + "gridPos": { + "h": 3, + "w": 24, + "x": 0, + "y": 1 + }, + "id": 32, + "options": { + "content": "

TDengine Cluster Dashboard

>\n", + "mode": "markdown" + }, + "pluginVersion": "7.5.10", + "repeatDirection": "h", + "targets": [ + { + "alias": "mnodes", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "show mnodes", + "target": "select metric", + "timeshift": { + "period": null + }, + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "-- OVERVIEW --", + "transformations": [ + { + "id": "calculateField", + "options": { + "binary": { + "left": "Time", + "operator": "+", + "reducer": "sum", + "right": "" + }, + "mode": "binary", + "reduce": { + "reducer": "sum" + } + } + } + ], + "type": "text" + }, + { + "datasource": "${ds}", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 3, + "w": 8, + "x": 0, + "y": 4 + }, + "id": 28, + "options": { + "colorMode": "value", + "graphMode": "area", + "justifyMode": "auto", + "orientation": "auto", + "reduceOptions": { + "calcs": [ + "lastNotNull" + ], + "fields": "", + "values": true + }, + "text": {}, + "textMode": "auto" + }, + "pluginVersion": "7.5.10", + "repeatDirection": "h", + "targets": [ + { + "alias": "dnodes", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "show mnodes", + "target": "select metric", + "timeshift": { + "period": null + }, + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Master MNode", + "transformations": [ + { + "id": "filterByValue", + "options": { + "filters": [ + { + "config": { + "id": "regex", + "options": { + "value": "master" + } + }, + "fieldName": "role" + } + ], + "match": "all", + "type": "include" + } + }, + { + "id": "filterFieldsByName", + "options": { + "include": { + "names": [ + "dnodes" + ] + } + } + } + ], + "type": "stat" + }, + { + "datasource": "${ds}", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 3, + "w": 7, + "x": 8, + "y": 4 + }, + "id": 70, + "options": { + "colorMode": "value", + "graphMode": "area", + "justifyMode": "auto", + "orientation": "auto", + "reduceOptions": { + "calcs": [ + "lastNotNull" + ], + "fields": "/^Time$/", + "values": true + }, + "text": {}, + "textMode": "auto" + }, + "pluginVersion": "7.5.10", + "repeatDirection": "h", + "targets": [ + { + "alias": "dnodes", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "show mnodes", + "target": "select metric", + "timeshift": { + "period": null + }, + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Master MNode Create Time", + "transformations": [ + { + "id": "filterByValue", + "options": { + "filters": [ + { + "config": { + "id": "regex", + "options": { + "value": "master" + } + }, + "fieldName": "role" + } + ], + "match": "all", + "type": "include" + } + }, + { + "id": "filterFieldsByName", + "options": { + "include": { + "names": [ + "Time" + ] + } + } + }, + { + "id": "calculateField", + "options": { + "mode": "reduceRow", + "reduce": { + "reducer": "min" + } + } + } + ], + "type": "stat" + }, + { + "datasource": "${ds}", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "custom": { + "align": null, + "filterable": false + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 9, + "w": 9, + "x": 15, + "y": 4 + }, + "id": 29, + "options": { + "showHeader": true + }, + "pluginVersion": "7.5.10", + "repeatDirection": "h", + "targets": [ + { + "alias": "dnodes", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "show variables", + "target": "select metric", + "timeshift": { + "period": null + }, + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Variables", + "transformations": [ + { + "id": "filterFieldsByName", + "options": { + "include": { + "names": [ + "value", + "name" + ] + } + } + }, + { + "id": "filterByValue", + "options": { + "filters": [ + { + "config": { + "id": "regex", + "options": { + "value": ".*" + } + }, + "fieldName": "name" + } + ], + "match": "all", + "type": "include" + } + } + ], + "type": "table" + }, + { + "datasource": "${ds}", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 3, + "w": 2, + "x": 0, + "y": 7 + }, + "id": 33, + "options": { + "colorMode": "value", + "graphMode": "area", + "justifyMode": "auto", + "orientation": "auto", + "reduceOptions": { + "calcs": [ + "lastNotNull" + ], + "fields": "/.*/", + "values": true + }, + "text": {}, + "textMode": "auto" + }, + "pluginVersion": "7.5.10", + "repeatDirection": "h", + "targets": [ + { + "alias": "dnodes", + "formatType": "Table", + "queryType": "SQL", + "refId": "A", + "sql": "select server_version()", + "target": "select metric", + "timeshift": { + "period": null + }, + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Server Version", + "transformations": [], + "type": "stat" + }, + { + "datasource": "${ds}", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 3, + "w": 3, + "x": 2, + "y": 7 + }, + "id": 27, + "options": { + "colorMode": "value", + "graphMode": "area", + "justifyMode": "auto", + "orientation": "auto", + "reduceOptions": { + "calcs": [ + "lastNotNull" + ], + "fields": "", + "values": true + }, + "text": {}, + "textMode": "auto" + }, + "pluginVersion": "7.5.10", + "repeatDirection": "h", + "targets": [ + { + "alias": "dnodes", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "show mnodes", + "target": "select metric", + "timeshift": { + "period": null + }, + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Number of MNodes", + "transformations": [ + { + "id": "filterByValue", + "options": { + "filters": [ + { + "config": { + "id": "greater", + "options": { + "value": 0 + } + }, + "fieldName": "id" + } + ], + "match": "any", + "type": "include" + } + }, + { + "id": "reduce", + "options": { + "includeTimeField": false, + "mode": "reduceFields", + "reducers": [ + "count" + ] + } + }, + { + "id": "filterFieldsByName", + "options": { + "include": { + "names": [ + "id" + ] + } + } + } + ], + "type": "stat" + }, + { + "datasource": "${ds}", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 3, + "w": 2, + "x": 5, + "y": 7 + }, + "id": 41, + "options": { + "colorMode": "value", + "graphMode": "none", + "justifyMode": "auto", + "orientation": "horizontal", + "reduceOptions": { + "calcs": [ + "last" + ], + "fields": "", + "values": false + }, + "text": {}, + "textMode": "value" + }, + "pluginVersion": "7.5.10", + "targets": [ + { + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "show dnodes", + "target": "select metric", + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Total Dnodes", + "transformations": [ + { + "id": "reduce", + "options": { + "includeTimeField": false, + "mode": "reduceFields", + "reducers": [ + "count" + ] + } + }, + { + "id": "filterFieldsByName", + "options": { + "include": { + "names": [ + "id" + ] + } + } + } + ], + "type": "stat" + }, + { + "datasource": "${ds}", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 1 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 3, + "w": 2, + "x": 7, + "y": 7 + }, + "id": 31, + "options": { + "colorMode": "value", + "graphMode": "none", + "justifyMode": "auto", + "orientation": "horizontal", + "reduceOptions": { + "calcs": [ + "last" + ], + "fields": "", + "values": false + }, + "text": {}, + "textMode": "value" + }, + "pluginVersion": "7.5.10", + "targets": [ + { + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "show dnodes", + "target": "select metric", + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Offline Dnodes", + "transformations": [ + { + "id": "filterByValue", + "options": { + "filters": [ + { + "config": { + "id": "regex", + "options": { + "value": "ready" + } + }, + "fieldName": "status" + } + ], + "match": "all", + "type": "exclude" + } + }, + { + "id": "reduce", + "options": { + "includeTimeField": false, + "mode": "reduceFields", + "reducers": [ + "count" + ] + } + }, + { + "id": "filterFieldsByName", + "options": { + "include": { + "names": [ + "id" + ] + } + } + } + ], + "type": "stat" + }, + { + "datasource": "${ds}", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 3, + "w": 3, + "x": 9, + "y": 7 + }, + "id": 65, + "options": { + "colorMode": "value", + "graphMode": "area", + "justifyMode": "auto", + "orientation": "auto", + "reduceOptions": { + "calcs": [ + "lastNotNull" + ], + "fields": "", + "values": true + }, + "text": {}, + "textMode": "auto" + }, + "pluginVersion": "7.5.10", + "repeatDirection": "h", + "targets": [ + { + "alias": "dnodes", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "show databases;", + "target": "select metric", + "timeshift": { + "period": null + }, + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Number of Databases", + "transformations": [ + { + "id": "reduce", + "options": { + "includeTimeField": false, + "mode": "reduceFields", + "reducers": [ + "count" + ] + } + }, + { + "id": "filterFieldsByName", + "options": { + "include": { + "names": [ + "name" + ] + } + } + } + ], + "type": "stat" + }, + { + "datasource": "${ds}", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 3, + "w": 3, + "x": 12, + "y": 7 + }, + "id": 69, + "options": { + "colorMode": "value", + "graphMode": "area", + "justifyMode": "auto", + "orientation": "auto", + "reduceOptions": { + "calcs": [ + "lastNotNull" + ], + "fields": "", + "values": true + }, + "text": {}, + "textMode": "auto" + }, + "pluginVersion": "7.5.10", + "repeatDirection": "h", + "targets": [ + { + "alias": "dnodes", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "show databases;", + "target": "select metric", + "timeshift": { + "period": null + }, + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Total Number of Vgroups", + "transformations": [ + { + "id": "filterFieldsByName", + "options": { + "include": { + "names": [ + "vgroups" + ] + } + } + }, + { + "id": "reduce", + "options": { + "includeTimeField": false, + "mode": "reduceFields", + "reducers": [ + "sum" + ] + } + } + ], + "type": "stat" + }, + { + "datasource": "${ds}", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "custom": { + "align": "center", + "displayMode": "auto", + "filterable": true + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + } + ] + } + }, + "overrides": [ + { + "matcher": { + "id": "byName", + "options": "role" + }, + "properties": [ + { + "id": "mappings", + "value": [ + { + "from": "", + "id": 1, + "text": "", + "to": "", + "type": 2, + "value": "" + } + ] + } + ] + } + ] + }, + "gridPos": { + "h": 3, + "w": 9, + "x": 0, + "y": 10 + }, + "id": 67, + "options": { + "showHeader": true + }, + "pluginVersion": "7.5.10", + "targets": [ + { + "formatType": "Table", + "queryType": "SQL", + "refId": "A", + "sql": "show dnodes", + "target": "select metric", + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Number of DNodes for each Role", + "transformations": [ + { + "id": "groupBy", + "options": { + "fields": { + "end_point": { + "aggregations": [ + "count" + ], + "operation": "aggregate" + }, + "role": { + "aggregations": [], + "operation": "groupby" + } + } + } + }, + { + "id": "filterFieldsByName", + "options": {} + }, + { + "id": "organize", + "options": { + "excludeByName": {}, + "indexByName": {}, + "renameByName": { + "end_point (count)": "Number of DNodes", + "role": "Dnode Role" + } + } + } + ], + "type": "table" + }, + { + "datasource": "${ds}", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 3, + "w": 3, + "x": 9, + "y": 10 + }, + "id": 55, + "options": { + "colorMode": "value", + "graphMode": "area", + "justifyMode": "auto", + "orientation": "auto", + "reduceOptions": { + "calcs": [ + "lastNotNull" + ], + "fields": "", + "values": true + }, + "text": {}, + "textMode": "auto" + }, + "pluginVersion": "7.5.10", + "repeatDirection": "h", + "targets": [ + { + "alias": "dnodes", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "show connections", + "target": "select metric", + "timeshift": { + "period": null + }, + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Number of Connections", + "transformations": [ + { + "id": "reduce", + "options": { + "includeTimeField": false, + "mode": "reduceFields", + "reducers": [ + "count" + ] + } + }, + { + "id": "filterFieldsByName", + "options": { + "include": { + "names": [ + "connId" + ] + } + } + } + ], + "type": "stat" + }, + { + "datasource": "${ds}", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 3, + "w": 3, + "x": 12, + "y": 10 + }, + "id": 68, + "options": { + "colorMode": "value", + "graphMode": "area", + "justifyMode": "auto", + "orientation": "auto", + "reduceOptions": { + "calcs": [ + "lastNotNull" + ], + "fields": "", + "values": true + }, + "text": {}, + "textMode": "auto" + }, + "pluginVersion": "7.5.10", + "repeatDirection": "h", + "targets": [ + { + "alias": "dnodes", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "show databases;", + "target": "select metric", + "timeshift": { + "period": null + }, + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Total Number of Tables", + "transformations": [ + { + "id": "filterFieldsByName", + "options": { + "include": { + "names": [ + "ntables" + ] + } + } + }, + { + "id": "reduce", + "options": { + "includeTimeField": false, + "mode": "reduceFields", + "reducers": [ + "sum" + ] + } + } + ], + "type": "stat" + }, + { + "collapsed": false, + "datasource": null, + "gridPos": { + "h": 1, + "w": 24, + "x": 0, + "y": 13 + }, + "id": 24, + "panels": [], + "title": "Dnodes Status", + "type": "row" + }, + { + "datasource": "${ds}", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "custom": { + "align": "center", + "displayMode": "auto", + "filterable": true + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [ + { + "matcher": { + "id": "byName", + "options": "status" + }, + "properties": [ + { + "id": "custom.width", + "value": null + } + ] + }, + { + "matcher": { + "id": "byName", + "options": "vnodes" + }, + "properties": [ + { + "id": "custom.width", + "value": null + } + ] + } + ] + }, + "gridPos": { + "h": 5, + "w": 16, + "x": 0, + "y": 14 + }, + "id": 36, + "options": { + "showHeader": true, + "sortBy": [] + }, + "pluginVersion": "7.5.10", + "targets": [ + { + "formatType": "Table", + "queryType": "SQL", + "refId": "A", + "sql": "show dnodes", + "target": "select metric", + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "DNodes Status", + "type": "table" + }, + { + "datasource": "${ds}", + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 5, + "w": 8, + "x": 16, + "y": 14 + }, + "id": 40, + "options": { + "displayLabels": [], + "legend": { + "displayMode": "table", + "placement": "right", + "values": [ + "value" + ] + }, + "pieType": "pie", + "reduceOptions": { + "calcs": [ + "lastNotNull" + ], + "fields": "/.*/", + "values": false + }, + "text": { + "titleSize": 6 + } + }, + "pluginVersion": "7.5.10", + "targets": [ + { + "formatType": "Table", + "queryType": "SQL", + "refId": "A", + "sql": "show dnodes", + "target": "select metric", + "type": "timeserie" + } + ], + "title": "Offline Reasons", + "transformations": [ + { + "id": "filterByValue", + "options": { + "filters": [ + { + "config": { + "id": "regex", + "options": { + "value": "ready" + } + }, + "fieldName": "status" + } + ], + "match": "all", + "type": "exclude" + } + }, + { + "id": "filterFieldsByName", + "options": { + "include": { + "names": [ + "offline reason", + "end_point" + ] + } + } + }, + { + "id": "groupBy", + "options": { + "fields": { + "Time": { + "aggregations": [ + "count" + ], + "operation": "aggregate" + }, + "end_point": { + "aggregations": [ + "count" + ], + "operation": "aggregate" + }, + "offline reason": { + "aggregations": [], + "operation": "groupby" + } + } + } + } + ], + "type": "piechart" + }, + { + "collapsed": false, + "datasource": null, + "gridPos": { + "h": 1, + "w": 24, + "x": 0, + "y": 19 + }, + "id": 22, + "panels": [], + "title": "Mnodes Status", + "type": "row" + }, + { + "datasource": "${ds}", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "custom": { + "align": "center", + "filterable": false + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 5, + "w": 24, + "x": 0, + "y": 20 + }, + "id": 38, + "options": { + "showHeader": true + }, + "pluginVersion": "7.5.10", + "targets": [ + { + "formatType": "Table", + "queryType": "SQL", + "refId": "A", + "sql": "show mnodes;", + "target": "select metric", + "type": "timeserie" + } + ], + "title": "Mnodes Status", + "type": "table" + }, + { + "collapsed": false, + "datasource": null, + "gridPos": { + "h": 1, + "w": 24, + "x": 0, + "y": 25 + }, + "id": 20, + "panels": [], + "repeat": "fqdn", + "scopedVars": { + "fqdn": { + "selected": true, + "text": "huolinhe-TM1701:6030", + "value": "huolinhe-TM1701:6030" + } + }, + "title": "节点资源占用 [ $fqdn ]", + "type": "row" + }, + { + "datasource": "${ds}", + "description": "", + "fieldConfig": { + "defaults": { + "color": { + "mode": "continuous-GrYlRd" + }, + "mappings": [], + "min": 0, + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + } + ] + }, + "unit": "decmbytes" + }, + "overrides": [] + }, + "gridPos": { + "h": 6, + "w": 5, + "x": 0, + "y": 26 + }, + "id": 66, + "options": { + "orientation": "auto", + "reduceOptions": { + "calcs": [ + "mean" + ], + "fields": "/^taosd$/", + "values": false + }, + "showThresholdLabels": true, + "showThresholdMarkers": true, + "text": {} + }, + "pluginVersion": "7.5.10", + "scopedVars": { + "fqdn": { + "selected": true, + "text": "huolinhe-TM1701:6030", + "value": "huolinhe-TM1701:6030" + } + }, + "targets": [ + { + "alias": "memory", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "select last(mem_taosd) as taosd, last(mem_total) as total from log.dn where fqdn = '$fqdn' and ts >= now -5m and ts < now", + "target": "select metric", + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Current Memory Usage of taosd", + "type": "gauge" + }, + { + "datasource": "${ds}", + "description": "taosd max memery last 10 minutes", + "fieldConfig": { + "defaults": { + "color": { + "mode": "continuous-GrYlRd" + }, + "mappings": [], + "min": 0, + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "#EAB839", + "value": 0.5 + }, + { + "color": "red", + "value": 0.8 + } + ] + }, + "unit": "percentunit" + }, + "overrides": [ + { + "matcher": { + "id": "byName", + "options": "last(cpu_taosd)" + }, + "properties": [ + { + "id": "thresholds", + "value": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + } + ] + } + ] + }, + "gridPos": { + "h": 6, + "w": 5, + "x": 5, + "y": 26 + }, + "id": 45, + "options": { + "orientation": "auto", + "reduceOptions": { + "calcs": [ + "mean" + ], + "fields": "/^last\\(cpu_taosd\\)$/", + "values": false + }, + "showThresholdLabels": true, + "showThresholdMarkers": true, + "text": {} + }, + "pluginVersion": "7.5.10", + "scopedVars": { + "fqdn": { + "selected": true, + "text": "huolinhe-TM1701:6030", + "value": "huolinhe-TM1701:6030" + } + }, + "targets": [ + { + "alias": "mem_taosd", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "select last(cpu_taosd) from log.dn where fqdn = '$fqdn'", + "target": "select metric", + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Current CPU Usage of taosd", + "type": "gauge" + }, + { + "datasource": "${ds}", + "description": "avg band speed last one minute", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "mappings": [], + "max": 8192, + "min": 0, + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "#EAB839", + "value": 4916 + }, + { + "color": "red", + "value": 6554 + } + ] + }, + "unit": "Kbits" + }, + "overrides": [] + }, + "gridPos": { + "h": 6, + "w": 4, + "x": 10, + "y": 26 + }, + "id": 14, + "options": { + "orientation": "auto", + "reduceOptions": { + "calcs": [ + "last" + ], + "fields": "", + "values": false + }, + "showThresholdLabels": false, + "showThresholdMarkers": true, + "text": {} + }, + "pluginVersion": "7.5.10", + "scopedVars": { + "fqdn": { + "selected": true, + "text": "huolinhe-TM1701:6030", + "value": "huolinhe-TM1701:6030" + } + }, + "targets": [ + { + "alias": "band_speed", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "select avg(band_speed) from log.dn where fqdn='$fqdn' and ts >= now-5m and ts < now interval(1m)", + "target": "select metric", + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "band speed", + "type": "gauge" + }, + { + "datasource": "${ds}", + "description": "io read/write rate", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "mappings": [], + "max": 8192, + "min": 0, + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "#EAB839", + "value": 4916 + }, + { + "color": "red", + "value": 6554 + } + ] + }, + "unit": "Kbits" + }, + "overrides": [] + }, + "gridPos": { + "h": 6, + "w": 5, + "x": 14, + "y": 26 + }, + "id": 48, + "options": { + "orientation": "auto", + "reduceOptions": { + "calcs": [ + "last" + ], + "fields": "", + "values": false + }, + "showThresholdLabels": false, + "showThresholdMarkers": true, + "text": {} + }, + "pluginVersion": "7.5.10", + "scopedVars": { + "fqdn": { + "selected": true, + "text": "huolinhe-TM1701:6030", + "value": "huolinhe-TM1701:6030" + } + }, + "targets": [ + { + "alias": "", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "select last(io_read) as io_read, last(io_write) as io_write from log.dn where fqdn='$fqdn' and ts >= now-1h and ts < now interval(1m)", + "target": "select metric", + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "IO Rate", + "type": "gauge" + }, + { + "datasource": "${ds}", + "description": "", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "mappings": [], + "max": 1, + "min": 0, + "thresholds": { + "mode": "percentage", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "#EAB839", + "value": 75 + }, + { + "color": "red", + "value": 80 + }, + { + "color": "dark-red", + "value": 95 + } + ] + }, + "unit": "percentunit" + }, + "overrides": [] + }, + "gridPos": { + "h": 6, + "w": 5, + "x": 19, + "y": 26 + }, + "id": 51, + "options": { + "orientation": "auto", + "reduceOptions": { + "calcs": [ + "last" + ], + "fields": "/^disk_used_percent$/", + "values": false + }, + "showThresholdLabels": true, + "showThresholdMarkers": true, + "text": {} + }, + "pluginVersion": "7.5.10", + "scopedVars": { + "fqdn": { + "selected": true, + "text": "huolinhe-TM1701:6030", + "value": "huolinhe-TM1701:6030" + } + }, + "targets": [ + { + "alias": "disk_used", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "select last(disk_used) as used from log.dn where fqdn = '$fqdn' and ts >= $from and ts < $to interval(1m)", + "target": "select metric", + "timeshift": { + "period": null + }, + "type": "timeserie" + }, + { + "alias": "disk_total", + "formatType": "Time series", + "hide": false, + "queryType": "SQL", + "refId": "B", + "sql": "select last(disk_total) as total from log.dn where fqdn = '$fqdn' and ts >= $from and ts < $to interval(1m)", + "target": "select metric", + "type": "timeserie" + }, + { + "alias": "disk_used_percent", + "expression": "A/B", + "formatType": "Time series", + "hide": false, + "queryType": "Arithmetic", + "refId": "C", + "target": "select metric", + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Disk Used", + "transformations": [ + { + "id": "reduce", + "options": { + "includeTimeField": false, + "mode": "reduceFields", + "reducers": [ + "lastNotNull" + ] + } + } + ], + "type": "gauge" + }, + { + "datasource": "${ds}", + "description": "taosd max memery last 10 minutes", + "fieldConfig": { + "defaults": { + "color": { + "mode": "continuous-GrYlRd" + }, + "mappings": [], + "min": 0, + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + } + ] + }, + "unit": "decmbytes" + }, + "overrides": [] + }, + "gridPos": { + "h": 6, + "w": 5, + "x": 0, + "y": 32 + }, + "id": 12, + "options": { + "orientation": "auto", + "reduceOptions": { + "calcs": [ + "mean" + ], + "fields": "/^taosd$/", + "values": false + }, + "showThresholdLabels": true, + "showThresholdMarkers": true, + "text": {} + }, + "pluginVersion": "7.5.10", + "scopedVars": { + "fqdn": { + "selected": true, + "text": "huolinhe-TM1701:6030", + "value": "huolinhe-TM1701:6030" + } + }, + "targets": [ + { + "alias": "memory", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "select max(mem_taosd) as taosd, max(mem_total) as total from log.dn where fqdn = '$fqdn' and ts >= now -5m and ts < now", + "target": "select metric", + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Max Memory Usage of taosd in Last 5 minute", + "type": "gauge" + }, + { + "datasource": "${ds}", + "description": "taosd max memery last 10 minutes", + "fieldConfig": { + "defaults": { + "color": { + "mode": "continuous-GrYlRd" + }, + "mappings": [], + "max": 1, + "min": 0, + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "#EAB839", + "value": 0.5 + }, + { + "color": "red", + "value": 0.8 + } + ] + }, + "unit": "percentunit" + }, + "overrides": [] + }, + "gridPos": { + "h": 6, + "w": 5, + "x": 5, + "y": 32 + }, + "id": 43, + "options": { + "orientation": "auto", + "reduceOptions": { + "calcs": [ + "mean" + ], + "fields": "", + "values": false + }, + "showThresholdLabels": true, + "showThresholdMarkers": true, + "text": {} + }, + "pluginVersion": "7.5.10", + "scopedVars": { + "fqdn": { + "selected": true, + "text": "huolinhe-TM1701:6030", + "value": "huolinhe-TM1701:6030" + } + }, + "targets": [ + { + "alias": "mem_taosd", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "select max(cpu_taosd) from log.dn where fqdn = '$fqdn' and ts >= now -5m and ts < now", + "target": "select metric", + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Max CPU Usage of taosd in Last 5 minute", + "type": "gauge" + }, + { + "datasource": "${ds}", + "description": "avg band speed last one minute", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "mappings": [], + "max": 8192, + "min": 0, + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "#EAB839", + "value": 4916 + }, + { + "color": "red", + "value": 6554 + } + ] + }, + "unit": "Kbits" + }, + "overrides": [] + }, + "gridPos": { + "h": 6, + "w": 4, + "x": 10, + "y": 32 + }, + "id": 50, + "options": { + "orientation": "auto", + "reduceOptions": { + "calcs": [ + "last" + ], + "fields": "", + "values": false + }, + "showThresholdLabels": false, + "showThresholdMarkers": true, + "text": {} + }, + "pluginVersion": "7.5.10", + "scopedVars": { + "fqdn": { + "selected": true, + "text": "huolinhe-TM1701:6030", + "value": "huolinhe-TM1701:6030" + } + }, + "targets": [ + { + "alias": "band_speed", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "select max(band_speed) from log.dn where fqdn = '$fqdn' and ts >= now-1h", + "target": "select metric", + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Max band speed in last hour", + "type": "gauge" + }, + { + "datasource": "${ds}", + "description": "io read/write rate", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "mappings": [], + "max": 8192, + "min": 0, + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "#EAB839", + "value": 4916 + }, + { + "color": "red", + "value": 6554 + } + ] + }, + "unit": "Kbits" + }, + "overrides": [] + }, + "gridPos": { + "h": 6, + "w": 5, + "x": 14, + "y": 32 + }, + "id": 49, + "options": { + "orientation": "auto", + "reduceOptions": { + "calcs": [ + "last" + ], + "fields": "", + "values": false + }, + "showThresholdLabels": false, + "showThresholdMarkers": true, + "text": {} + }, + "pluginVersion": "7.5.10", + "scopedVars": { + "fqdn": { + "selected": true, + "text": "huolinhe-TM1701:6030", + "value": "huolinhe-TM1701:6030" + } + }, + "targets": [ + { + "alias": "", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "select max(io_read) as io_read, max(io_write) as io_write from log.dn where fqdn = '$fqdn'", + "target": "select metric", + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Max IO Rate in last hour", + "type": "gauge" + }, + { + "datasource": "${ds}", + "description": "io read/write rate", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "mappings": [], + "max": 8192, + "min": 0, + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "#EAB839", + "value": 4916 + }, + { + "color": "red", + "value": 6554 + } + ] + }, + "unit": "cpm" + }, + "overrides": [] + }, + "gridPos": { + "h": 6, + "w": 5, + "x": 19, + "y": 32 + }, + "id": 52, + "options": { + "orientation": "auto", + "reduceOptions": { + "calcs": [ + "last" + ], + "fields": "", + "values": false + }, + "showThresholdLabels": false, + "showThresholdMarkers": true, + "text": {} + }, + "pluginVersion": "7.5.10", + "scopedVars": { + "fqdn": { + "selected": true, + "text": "huolinhe-TM1701:6030", + "value": "huolinhe-TM1701:6030" + } + }, + "targets": [ + { + "alias": "req-http", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "select sum(req_http) as req_http from log.dn where fqdn = '$fqdn' and ts >= now - 1h interval(1m)", + "target": "select metric", + "type": "timeserie" + }, + { + "alias": "req-inserts", + "formatType": "Time series", + "hide": false, + "queryType": "SQL", + "refId": "B", + "sql": "select sum(req_insert) as req_insert from log.dn where fqdn = '$fqdn' and ts >= now - 1h interval(1m)", + "target": "select metric", + "type": "timeserie" + }, + { + "alias": "req-selects", + "formatType": "Time series", + "hide": false, + "queryType": "SQL", + "refId": "C", + "sql": "select sum(req_select) as req_select from log.dn where fqdn = '$fqdn' and ts >= now - 1h interval(1m)", + "target": "select metric", + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Requests in last Minute", + "type": "gauge" + }, + { + "aliasColors": {}, + "bars": false, + "cacheTimeout": null, + "dashLength": 10, + "dashes": false, + "datasource": "${ds}", + "description": "monitor system cpu", + "fieldConfig": { + "defaults": { + "links": [] + }, + "overrides": [] + }, + "fill": 1, + "fillGradient": 0, + "gridPos": { + "h": 11, + "w": 12, + "x": 0, + "y": 38 + }, + "hiddenSeries": false, + "hideTimeOverride": true, + "id": 2, + "legend": { + "avg": false, + "current": false, + "max": false, + "min": false, + "show": true, + "total": false, + "values": false + }, + "lines": true, + "linewidth": 1, + "links": [], + "nullPointMode": "null", + "options": { + "alertThreshold": true + }, + "percentage": false, + "pluginVersion": "7.5.10", + "pointradius": 2, + "points": false, + "renderer": "flot", + "scopedVars": { + "fqdn": { + "selected": true, + "text": "huolinhe-TM1701:6030", + "value": "huolinhe-TM1701:6030" + } + }, + "seriesOverrides": [], + "spaceLength": 10, + "stack": false, + "steppedLine": false, + "targets": [ + { + "alias": "cpu_system", + "formatType": "Time series", + "hide": false, + "queryType": "SQL", + "refId": "A", + "sql": "select avg(cpu_system) from log.dn where fqdn='$fqdn' and ts >= now-1h and ts < now interval(30s)", + "target": "select metric", + "type": "timeserie" + }, + { + "alias": "cpu_taosd", + "formatType": "Time series", + "hide": false, + "queryType": "SQL", + "refId": "B", + "sql": "select avg(cpu_taosd) from log.dn where fqdn='$fqdn' and ts >= now-1h and ts < now interval(30s)", + "target": "select metric", + "type": "timeserie" + } + ], + "thresholds": [], + "timeFrom": "1h", + "timeRegions": [], + "timeShift": "30s", + "title": "CPU 资源占用情况", + "tooltip": { + "shared": true, + "sort": 0, + "value_type": "individual" + }, + "type": "graph", + "xaxis": { + "buckets": null, + "mode": "time", + "name": null, + "show": true, + "values": [] + }, + "yaxes": [ + { + "$$hashKey": "object:58", + "decimals": null, + "format": "percent", + "label": "使用占比", + "logBase": 1, + "max": null, + "min": null, + "show": true + }, + { + "$$hashKey": "object:59", + "format": "short", + "label": null, + "logBase": 1, + "max": null, + "min": null, + "show": false + } + ], + "yaxis": { + "align": false, + "alignLevel": null + } + }, + { + "aliasColors": {}, + "bars": false, + "cacheTimeout": null, + "dashLength": 10, + "dashes": false, + "datasource": "${ds}", + "description": "monitor system cpu", + "fieldConfig": { + "defaults": { + "links": [] + }, + "overrides": [] + }, + "fill": 1, + "fillGradient": 0, + "gridPos": { + "h": 11, + "w": 12, + "x": 12, + "y": 38 + }, + "hiddenSeries": false, + "hideTimeOverride": true, + "id": 42, + "legend": { + "avg": false, + "current": false, + "max": false, + "min": false, + "show": true, + "total": false, + "values": false + }, + "lines": true, + "linewidth": 1, + "links": [], + "nullPointMode": "null", + "options": { + "alertThreshold": true + }, + "percentage": false, + "pluginVersion": "7.5.10", + "pointradius": 2, + "points": false, + "renderer": "flot", + "scopedVars": { + "fqdn": { + "selected": true, + "text": "huolinhe-TM1701:6030", + "value": "huolinhe-TM1701:6030" + } + }, + "seriesOverrides": [], + "spaceLength": 10, + "stack": false, + "steppedLine": false, + "targets": [ + { + "alias": "system", + "formatType": "Time series", + "hide": false, + "queryType": "SQL", + "refId": "A", + "sql": "select avg(mem_system) from log.dn where fqdn = '$fqdn' and ts >= now-1h and ts < now interval(30s)", + "target": "select metric", + "type": "timeserie" + }, + { + "alias": "taosd", + "formatType": "Time series", + "hide": false, + "queryType": "SQL", + "refId": "B", + "sql": "select avg(mem_taosd) from log.dn where fqdn = '$fqdn' and ts >= now-1h and ts < now interval(30s)", + "target": "select metric", + "type": "timeserie" + }, + { + "alias": "total", + "formatType": "Time series", + "hide": false, + "queryType": "SQL", + "refId": "C", + "sql": "select avg(mem_total) from log.dn where fqdn = '$fqdn' and ts >= now-1h and ts < now interval(30s)", + "target": "select metric", + "type": "timeserie" + } + ], + "thresholds": [], + "timeFrom": "1h", + "timeRegions": [], + "timeShift": "30s", + "title": "内存资源占用情况", + "tooltip": { + "shared": true, + "sort": 0, + "value_type": "individual" + }, + "type": "graph", + "xaxis": { + "buckets": null, + "mode": "time", + "name": null, + "show": true, + "values": [] + }, + "yaxes": [ + { + "$$hashKey": "object:58", + "decimals": null, + "format": "decmbytes", + "label": "使用占比", + "logBase": 1, + "max": null, + "min": null, + "show": true + }, + { + "$$hashKey": "object:59", + "format": "short", + "label": null, + "logBase": 1, + "max": null, + "min": null, + "show": false + } + ], + "yaxis": { + "align": false, + "alignLevel": null + } + }, + { + "aliasColors": {}, + "bars": false, + "dashLength": 10, + "dashes": false, + "datasource": "${ds}", + "fieldConfig": { + "defaults": { + "unit": "percent" + }, + "overrides": [] + }, + "fill": 1, + "fillGradient": 0, + "gridPos": { + "h": 9, + "w": 12, + "x": 0, + "y": 49 + }, + "hiddenSeries": false, + "id": 54, + "legend": { + "alignAsTable": false, + "avg": false, + "current": true, + "max": false, + "min": false, + "rightSide": false, + "show": true, + "total": false, + "values": true + }, + "lines": true, + "linewidth": 1, + "nullPointMode": "null", + "options": { + "alertThreshold": true + }, + "percentage": false, + "pluginVersion": "7.5.10", + "pointradius": 2, + "points": false, + "renderer": "flot", + "scopedVars": { + "fqdn": { + "selected": true, + "text": "huolinhe-TM1701:6030", + "value": "huolinhe-TM1701:6030" + } + }, + "seriesOverrides": [ + { + "$$hashKey": "object:249", + "alias": "disk_used", + "hiddenSeries": true + }, + { + "$$hashKey": "object:256", + "alias": "disk_total", + "hiddenSeries": true + } + ], + "spaceLength": 10, + "stack": false, + "steppedLine": false, + "targets": [ + { + "alias": "disk_used", + "formatType": "Time series", + "hide": false, + "queryType": "SQL", + "refId": "A", + "sql": "select avg(disk_used) from log.dn where fqdn = '$fqdn' and ts >= $from and ts < $to interval(30s)", + "target": "select metric", + "timeshift": { + "period": null + }, + "type": "timeserie" + }, + { + "alias": "disk_total", + "formatType": "Time series", + "hide": false, + "queryType": "SQL", + "refId": "B", + "sql": "select avg(disk_total) from log.dn where fqdn = '$fqdn' and ts >= $from and ts < $to interval(30s)", + "target": "select metric", + "timeshift": { + "period": null + }, + "type": "timeserie" + }, + { + "alias": "percent", + "expression": "A/B * 100", + "formatType": "Time series", + "hide": false, + "queryType": "Arithmetic", + "refId": "C", + "target": "select metric", + "type": "timeserie" + } + ], + "thresholds": [], + "timeFrom": null, + "timeRegions": [], + "timeShift": null, + "title": "Disk Used Percent", + "tooltip": { + "shared": false, + "sort": 0, + "value_type": "individual" + }, + "type": "graph", + "xaxis": { + "buckets": null, + "mode": "time", + "name": null, + "show": true, + "values": [] + }, + "yaxes": [ + { + "$$hashKey": "object:456", + "format": "percent", + "label": null, + "logBase": 1, + "max": "100", + "min": "0", + "show": true + }, + { + "$$hashKey": "object:457", + "format": "percentunit", + "label": "Disk Used", + "logBase": 1, + "max": null, + "min": null, + "show": false + } + ], + "yaxis": { + "align": false, + "alignLevel": null + } + }, + { + "aliasColors": {}, + "bars": false, + "dashLength": 10, + "dashes": false, + "datasource": "${ds}", + "fieldConfig": { + "defaults": {}, + "overrides": [] + }, + "fill": 1, + "fillGradient": 0, + "gridPos": { + "h": 9, + "w": 12, + "x": 12, + "y": 49 + }, + "hiddenSeries": false, + "id": 64, + "legend": { + "alignAsTable": false, + "avg": false, + "current": true, + "max": false, + "min": false, + "rightSide": false, + "show": true, + "total": false, + "values": true + }, + "lines": true, + "linewidth": 1, + "nullPointMode": "null", + "options": { + "alertThreshold": true + }, + "percentage": false, + "pluginVersion": "7.5.10", + "pointradius": 2, + "points": false, + "renderer": "flot", + "scopedVars": { + "fqdn": { + "selected": true, + "text": "huolinhe-TM1701:6030", + "value": "huolinhe-TM1701:6030" + } + }, + "seriesOverrides": [ + { + "$$hashKey": "object:834", + "alias": "percent", + "yaxis": 2 + } + ], + "spaceLength": 10, + "stack": false, + "steppedLine": false, + "targets": [ + { + "alias": "disk_used", + "formatType": "Time series", + "hide": false, + "queryType": "SQL", + "refId": "A", + "sql": "select avg(disk_used) from log.dn where fqdn = '$fqdn' and ts >= $from and ts < $to interval(30s)", + "target": "select metric", + "timeshift": { + "period": null + }, + "type": "timeserie" + }, + { + "alias": "disk_total", + "formatType": "Time series", + "hide": false, + "queryType": "SQL", + "refId": "B", + "sql": "select avg(disk_total) from log.dn where fqdn = '$fqdn' and ts >= $from and ts < $to interval(30s)", + "target": "select metric", + "timeshift": { + "period": null + }, + "type": "timeserie" + }, + { + "alias": "percent", + "expression": "A/B", + "formatType": "Time series", + "hide": false, + "queryType": "Arithmetic", + "refId": "C", + "target": "select metric", + "type": "timeserie" + } + ], + "thresholds": [], + "timeFrom": null, + "timeRegions": [], + "timeShift": null, + "title": "Disk Used", + "tooltip": { + "shared": false, + "sort": 0, + "value_type": "individual" + }, + "type": "graph", + "xaxis": { + "buckets": null, + "mode": "time", + "name": null, + "show": true, + "values": [] + }, + "yaxes": [ + { + "$$hashKey": "object:456", + "format": "decgbytes", + "label": null, + "logBase": 1, + "max": null, + "min": null, + "show": true + }, + { + "$$hashKey": "object:457", + "format": "percentunit", + "label": "Disk Used", + "logBase": 1, + "max": null, + "min": null, + "show": true + } + ], + "yaxis": { + "align": false, + "alignLevel": null + } + }, + { + "aliasColors": {}, + "bars": false, + "cacheTimeout": null, + "dashLength": 10, + "dashes": false, + "datasource": "${ds}", + "description": "total select request per minute last hour", + "fieldConfig": { + "defaults": { + "unit": "cpm" + }, + "overrides": [] + }, + "fill": 1, + "fillGradient": 0, + "gridPos": { + "h": 9, + "w": 12, + "x": 0, + "y": 58 + }, + "hiddenSeries": false, + "id": 8, + "interval": null, + "legend": { + "avg": false, + "current": false, + "max": false, + "min": false, + "show": true, + "total": false, + "values": false + }, + "lines": true, + "linewidth": 1, + "links": [], + "maxDataPoints": 100, + "nullPointMode": "null", + "options": { + "alertThreshold": true + }, + "percentage": false, + "pluginVersion": "7.5.10", + "pointradius": 2, + "points": false, + "renderer": "flot", + "scopedVars": { + "fqdn": { + "selected": true, + "text": "huolinhe-TM1701:6030", + "value": "huolinhe-TM1701:6030" + } + }, + "seriesOverrides": [], + "spaceLength": 10, + "stack": false, + "steppedLine": false, + "targets": [ + { + "alias": "req_select", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "select sum(req_select) from log.dn where fqdn = '$fqdn' and ts >= $from and ts < $to interval(1m)", + "target": "select metric", + "timeshift": { + "period": null + }, + "type": "timeserie" + }, + { + "alias": "req_insert", + "formatType": "Time series", + "hide": false, + "queryType": "SQL", + "refId": "B", + "sql": "select sum(req_insert) from log.dn where fqdn = '$fqdn' and ts >= $from and ts < $to interval(1m)", + "target": "select metric", + "type": "timeserie" + }, + { + "alias": "req_http", + "formatType": "Time series", + "hide": false, + "queryType": "SQL", + "refId": "C", + "sql": "select sum(req_http) from log.dn where fqdn = '$fqdn' and ts >= $from and ts < $to interval(1m)", + "target": "select metric", + "type": "timeserie" + } + ], + "thresholds": [], + "timeFrom": null, + "timeRegions": [], + "timeShift": null, + "title": "Requets Count per Minutes $fqdn", + "tooltip": { + "shared": true, + "sort": 0, + "value_type": "individual" + }, + "type": "graph", + "xaxis": { + "buckets": null, + "mode": "time", + "name": null, + "show": true, + "values": [] + }, + "yaxes": [ + { + "$$hashKey": "object:127", + "format": "cpm", + "label": null, + "logBase": 1, + "max": null, + "min": "0", + "show": true + }, + { + "$$hashKey": "object:128", + "format": "short", + "label": null, + "logBase": 1, + "max": null, + "min": null, + "show": true + } + ], + "yaxis": { + "align": false, + "alignLevel": null + } + }, + { + "aliasColors": {}, + "bars": false, + "cacheTimeout": null, + "dashLength": 10, + "dashes": false, + "datasource": "${ds}", + "description": "io", + "fieldConfig": { + "defaults": { + "links": [], + "unit": "Kbits" + }, + "overrides": [] + }, + "fill": 1, + "fillGradient": 0, + "gridPos": { + "h": 9, + "w": 12, + "x": 12, + "y": 58 + }, + "hiddenSeries": false, + "hideTimeOverride": true, + "id": 47, + "legend": { + "avg": false, + "current": false, + "max": false, + "min": false, + "show": true, + "total": false, + "values": false + }, + "lines": true, + "linewidth": 1, + "links": [], + "nullPointMode": "null", + "options": { + "alertThreshold": true + }, + "percentage": false, + "pluginVersion": "7.5.10", + "pointradius": 2, + "points": false, + "renderer": "flot", + "scopedVars": { + "fqdn": { + "selected": true, + "text": "huolinhe-TM1701:6030", + "value": "huolinhe-TM1701:6030" + } + }, + "seriesOverrides": [], + "spaceLength": 10, + "stack": false, + "steppedLine": false, + "targets": [ + { + "alias": "io-read", + "formatType": "Time series", + "hide": false, + "queryType": "SQL", + "refId": "A", + "sql": "select avg(io_read) from log.dn where fqdn = '$fqdn' and ts >= now-1h and ts < now interval(1m)", + "target": "select metric", + "type": "timeserie" + }, + { + "alias": "io-write", + "formatType": "Time series", + "hide": false, + "queryType": "SQL", + "refId": "B", + "sql": "select avg(io_write) from log.dn where fqdn = '$fqdn' and ts >= now-1h and ts < now interval(1m)", + "target": "select metric", + "type": "timeserie" + }, + { + "alias": "io-read-last-hour", + "formatType": "Time series", + "hide": false, + "queryType": "SQL", + "refId": "C", + "sql": "select avg(io_read) from log.dn where fqdn = '$fqdn' and ts >= now-2h and ts < now - 1h interval(1m)", + "target": "select metric", + "timeshift": { + "period": 1, + "unit": "hours" + }, + "type": "timeserie" + }, + { + "alias": "io-write-last-hour", + "formatType": "Time series", + "hide": false, + "queryType": "SQL", + "refId": "D", + "sql": "select avg(io_write) from log.dn where fqdn = '$fqdn' and ts >= now-1h and ts < now interval(1m)", + "target": "select metric", + "timeshift": { + "period": 1, + "unit": "hours" + }, + "type": "timeserie" + } + ], + "thresholds": [], + "timeFrom": "1h", + "timeRegions": [], + "timeShift": "30s", + "title": "IO", + "tooltip": { + "shared": true, + "sort": 0, + "value_type": "individual" + }, + "type": "graph", + "xaxis": { + "buckets": null, + "mode": "time", + "name": null, + "show": true, + "values": [] + }, + "yaxes": [ + { + "$$hashKey": "object:58", + "decimals": null, + "format": "Kbits", + "label": "使用占比", + "logBase": 1, + "max": null, + "min": null, + "show": true + }, + { + "$$hashKey": "object:59", + "format": "short", + "label": null, + "logBase": 1, + "max": null, + "min": null, + "show": false + } + ], + "yaxis": { + "align": false, + "alignLevel": null + } + }, + { + "collapsed": false, + "datasource": null, + "gridPos": { + "h": 1, + "w": 24, + "x": 0, + "y": 67 + }, + "id": 63, + "panels": [], + "title": "Login History", + "type": "row" + }, + { + "aliasColors": {}, + "bars": false, + "dashLength": 10, + "dashes": false, + "datasource": "${ds}", + "fieldConfig": { + "defaults": { + "displayName": "Logins Per Minute", + "unit": "cpm" + }, + "overrides": [] + }, + "fill": 1, + "fillGradient": 0, + "gridPos": { + "h": 8, + "w": 12, + "x": 0, + "y": 68 + }, + "hiddenSeries": false, + "id": 61, + "legend": { + "avg": false, + "current": false, + "max": false, + "min": false, + "show": true, + "total": false, + "values": false + }, + "lines": true, + "linewidth": 1, + "nullPointMode": "null", + "options": { + "alertThreshold": true + }, + "percentage": false, + "pluginVersion": "7.5.10", + "pointradius": 2, + "points": false, + "renderer": "flot", + "seriesOverrides": [ + { + "$$hashKey": "object:756", + "alias": "logins", + "nullPointMode": "null as zero" + } + ], + "spaceLength": 10, + "stack": false, + "steppedLine": false, + "targets": [ + { + "alias": "logins", + "formatType": "Time series", + "queryType": "SQL", + "refId": "A", + "sql": "select count(*) from log.log where ts >= $from and ts < $to interval (1m)", + "target": "select metric", + "type": "timeserie" + } + ], + "thresholds": [], + "timeFrom": null, + "timeRegions": [], + "timeShift": null, + "title": "Login Counts per Minute", + "tooltip": { + "shared": true, + "sort": 0, + "value_type": "individual" + }, + "type": "graph", + "xaxis": { + "buckets": null, + "mode": "time", + "name": null, + "show": true, + "values": [] + }, + "yaxes": [ + { + "$$hashKey": "object:585", + "format": "cpm", + "label": null, + "logBase": 1, + "max": null, + "min": null, + "show": true + }, + { + "$$hashKey": "object:586", + "format": "short", + "label": null, + "logBase": 1, + "max": null, + "min": null, + "show": true + } + ], + "yaxis": { + "align": false, + "alignLevel": null + } + } + ], + "refresh": "1m", + "schemaVersion": 27, + "style": "dark", + "tags": [ + "TDengine" + ], + "templating": { + "list": [ + { + "current": { + "selected": true, + "text": "TDengine", + "value": "TDengine" + }, + "description": "TDengine Data Source Selector", + "error": null, + "hide": 0, + "includeAll": false, + "label": "Datasource", + "multi": false, + "name": "ds", + "options": [], + "query": "tdengine-datasource", + "queryValue": "", + "refresh": 1, + "regex": "", + "skipUrlSync": false, + "type": "datasource" + }, + { + "allValue": null, + "current": { + "selected": false, + "text": "huolinhe-TM1701:6030", + "value": "huolinhe-TM1701:6030" + }, + "datasource": "${ds}", + "definition": "select fqdn from log.dn", + "description": "TDengine Nodes FQDN (Hostname)", + "error": null, + "hide": 0, + "includeAll": false, + "label": null, + "multi": false, + "name": "fqdn", + "options": [], + "query": "select fqdn from log.dn", + "refresh": 1, + "regex": "", + "skipUrlSync": false, + "sort": 0, + "tagValuesQuery": "", + "tags": [], + "tagsQuery": "", + "type": "query", + "useTags": false + } + ] + }, + "time": { + "from": "now-1h", + "to": "now" + }, + "timepicker": { + "refresh_intervals": [ + "5s", + "10s", + "30s", + "1m", + "5m", + "15m", + "30m", + "1h", + "2h", + "1d" + ] + }, + "timezone": "", + "title": "TDengine", + "uid": "tdengine", + "version": 8 +} \ No newline at end of file diff --git a/docs-cn/14-reference/07-tdinsight/assets/tdengine-grafana.json b/docs-cn/14-reference/07-tdinsight/assets/tdengine-grafana.json new file mode 100644 index 0000000000000000000000000000000000000000..7696cfce3fcca3dd5f9278c91d3df2c1b32b9c97 --- /dev/null +++ b/docs-cn/14-reference/07-tdinsight/assets/tdengine-grafana.json @@ -0,0 +1,627 @@ +{ + "annotations": { + "list": [ + { + "builtIn": 1, + "datasource": "-- Grafana --", + "enable": true, + "hide": true, + "iconColor": "rgba(0, 211, 255, 1)", + "name": "Annotations & Alerts", + "type": "dashboard" + } + ] + }, + "editable": true, + "gnetId": null, + "graphTooltip": 0, + "id": 3, + "links": [], + "panels": [ + { + "cacheTimeout": null, + "colorBackground": false, + "colorValue": true, + "colors": ["#299c46", "rgba(237, 129, 40, 0.89)", "#d44a3a"], + "datasource": "TDengine", + "description": "total select request per minute last hour", + "format": "none", + "gauge": { + "maxValue": 100, + "minValue": 0, + "show": false, + "thresholdLabels": false, + "thresholdMarkers": true + }, + "gridPos": { + "h": 6, + "w": 12, + "x": 0, + "y": 0 + }, + "id": 8, + "interval": null, + "links": [], + "mappingType": 1, + "mappingTypes": [ + { + "name": "value to text", + "value": 1 + }, + { + "name": "range to text", + "value": 2 + } + ], + "maxDataPoints": 100, + "nullPointMode": "connected", + "nullText": null, + "options": {}, + "postfix": "次数/min", + "postfixFontSize": "20%", + "prefix": "", + "prefixFontSize": "50%", + "rangeMaps": [ + { + "from": "null", + "text": "N/A", + "to": "null" + } + ], + "sparkline": { + "fillColor": "rgba(31, 118, 189, 0.18)", + "full": true, + "lineColor": "rgb(31, 120, 193)", + "show": true, + "ymax": null, + "ymin": null + }, + "tableColumn": "", + "targets": [ + { + "alias": "req_select", + "refId": "A", + "sql": "select sum(req_select) from log.dn where ts >= now-1h and ts < now interval(1m)", + "target": "select metric", + "type": "timeserie" + } + ], + "thresholds": "120,240", + "timeFrom": null, + "timeShift": null, + "title": "req select", + "type": "singlestat", + "valueFontSize": "150%", + "valueMaps": [ + { + "op": "=", + "text": "N/A", + "value": "null" + } + ], + "valueName": "total" + }, + { + "cacheTimeout": null, + "colorBackground": false, + "colorValue": true, + "colors": ["#299c46", "rgba(237, 129, 40, 0.89)", "#d44a3a"], + "datasource": "TDengine", + "description": "total insert request per minute for last hour", + "format": "none", + "gauge": { + "maxValue": 100, + "minValue": 0, + "show": false, + "thresholdLabels": false, + "thresholdMarkers": true + }, + "gridPos": { + "h": 6, + "w": 12, + "x": 12, + "y": 0 + }, + "id": 6, + "interval": null, + "links": [], + "mappingType": 1, + "mappingTypes": [ + { + "name": "value to text", + "value": 1 + }, + { + "name": "range to text", + "value": 2 + } + ], + "maxDataPoints": 100, + "nullPointMode": "connected", + "nullText": null, + "options": {}, + "postfix": "次数/min", + "postfixFontSize": "20%", + "prefix": "", + "prefixFontSize": "50%", + "rangeMaps": [ + { + "from": "null", + "text": "N/A", + "to": "null" + } + ], + "sparkline": { + "fillColor": "rgba(31, 118, 189, 0.18)", + "full": false, + "lineColor": "rgb(31, 120, 193)", + "show": true, + "ymax": null, + "ymin": null + }, + "tableColumn": "", + "targets": [ + { + "alias": "req_insert", + "refId": "A", + "sql": "select sum(req_insert) from log.dn where ts >= now-1h and ts < now interval(1m)", + "target": "select metric", + "type": "timeserie" + } + ], + "thresholds": "110,240", + "timeFrom": null, + "timeShift": null, + "title": "req insert", + "type": "singlestat", + "valueFontSize": "150%", + "valueMaps": [ + { + "op": "=", + "text": "N/A", + "value": "null" + } + ], + "valueName": "total" + }, + { + "datasource": "TDengine", + "description": "taosd max memery last 10 minutes", + "gridPos": { + "h": 6, + "w": 8, + "x": 0, + "y": 6 + }, + "id": 12, + "options": { + "fieldOptions": { + "calcs": ["mean"], + "defaults": { + "mappings": [], + "max": 4096, + "min": 0, + "thresholds": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + }, + { + "color": "#EAB839", + "value": 2048 + } + ], + "unit": "decmbytes" + }, + "thresholds": [ + { + "index": 0, + "color": "green", + "value": null + }, + { + "index": 1, + "color": "red", + "value": 80 + }, + { + "index": 2, + "color": "#EAB839", + "value": 2048 + } + ], + "override": {}, + "values": false + }, + "orientation": "auto", + "showThresholdLabels": true, + "showThresholdMarkers": true + }, + "pluginVersion": "6.4.3", + "targets": [ + { + "alias": "mem_taosd", + "refId": "A", + "sql": "select max(mem_taosd) from log.dn where ts >= now -10m and ts < now", + "target": "select metric", + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "taosd memery", + "type": "gauge" + }, + { + "datasource": "TDengine", + "description": "max System Memory last 1 hour", + "gridPos": { + "h": 6, + "w": 8, + "x": 8, + "y": 6 + }, + "id": 10, + "options": { + "fieldOptions": { + "calcs": ["last"], + "mappings": [], + "defaults": { + "mappings": [], + "max": 4, + "min": 0, + "thresholds": [ + { + "color": "green", + "value": null + }, + { + "color": "semi-dark-orange", + "value": 60 + }, + { + "color": "dark-red", + "value": 80 + } + ], + "title": "", + "unit": "decmbytes" + }, + "thresholds": [ + { + "index": 0, + "color": "green", + "value": null + }, + { + "index": 1, + "color": "semi-dark-orange", + "value": 60 + }, + { + "index": 2, + "color": "dark-red", + "value": 80 + } + ], + "override": {}, + "values": false + }, + "orientation": "auto", + "showThresholdLabels": true, + "showThresholdMarkers": true + }, + "pluginVersion": "6.4.3", + "targets": [ + { + "alias": "mem_system", + "refId": "A", + "sql": "select max(mem_system) from log.dn where ts >= now -10h and ts < now", + "target": "select metric", + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "system memory", + "type": "gauge" + }, + { + "datasource": "TDengine", + "description": "avg band speed last one minute", + "gridPos": { + "h": 6, + "w": 8, + "x": 16, + "y": 6 + }, + "id": 14, + "options": { + "fieldOptions": { + "calcs": ["last"], + "defaults": { + "mappings": [], + "max": 8192, + "min": 0, + "thresholds": [ + { + "color": "green", + "value": null + }, + { + "color": "#EAB839", + "value": 4916 + }, + { + "color": "red", + "value": 6554 + } + ], + "unit": "Kbits" + }, + "mappings": [], + "thresholds": [ + { + "index": 0, + "color": "green", + "value": null + }, + { + "index": 1, + "color": "#EAB839", + "value": 4916 + }, + { + "index": 2, + "color": "red", + "value": 6554 + } + ], + "override": {}, + "values": false + }, + "orientation": "auto", + "showThresholdLabels": false, + "showThresholdMarkers": true + }, + "pluginVersion": "6.4.3", + "targets": [ + { + "alias": "band_speed", + "refId": "A", + "sql": "select avg(band_speed) from log.dn where ts >= now-1h and ts < now interval(1m)", + "target": "select metric", + "type": "timeserie" + } + ], + "timeFrom": null, + "timeShift": null, + "title": "band speed", + "type": "gauge" + }, + { + "aliasColors": {}, + "bars": false, + "cacheTimeout": null, + "dashLength": 10, + "dashes": false, + "datasource": "TDengine", + "description": "monitor system cpu", + "fill": 1, + "fillGradient": 0, + "gridPos": { + "h": 11, + "w": 12, + "x": 0, + "y": 12 + }, + "hideTimeOverride": true, + "id": 2, + "legend": { + "avg": false, + "current": false, + "max": false, + "min": false, + "show": true, + "total": false, + "values": false + }, + "lines": true, + "linewidth": 1, + "links": [], + "nullPointMode": "null", + "options": { + "dataLinks": [] + }, + "percentage": false, + "pluginVersion": "6.4.3", + "pointradius": 2, + "points": false, + "renderer": "flot", + "seriesOverrides": [], + "spaceLength": 10, + "stack": false, + "steppedLine": false, + "targets": [ + { + "alias": "cpu_system11", + "hide": false, + "refId": "A", + "sql": "select avg(cpu_system) from log.dn where ts >= now-1h and ts < now interval(1s)", + "target": "select metric", + "type": "timeserie" + }, + { + "alias": "cpu_taosd", + "hide": false, + "refId": "B", + "sql": "select avg(cpu_taosd) from log.dn where ts >= now-1h and ts < now interval(1s)", + "target": "select metric", + "type": "timeserie" + } + ], + "thresholds": [], + "timeFrom": "1h", + "timeRegions": [], + "timeShift": "30s", + "title": "cpu_system", + "tooltip": { + "shared": true, + "sort": 0, + "value_type": "individual" + }, + "type": "graph", + "xaxis": { + "buckets": null, + "mode": "time", + "name": null, + "show": true, + "values": [] + }, + "yaxes": [ + { + "decimals": null, + "format": "percent", + "label": "使用占比", + "logBase": 1, + "max": null, + "min": null, + "show": true + }, + { + "format": "short", + "label": null, + "logBase": 1, + "max": null, + "min": null, + "show": false + } + ], + "yaxis": { + "align": false, + "alignLevel": null + } + }, + { + "aliasColors": {}, + "bars": false, + "dashLength": 10, + "dashes": false, + "datasource": "TDengine", + "fill": 1, + "fillGradient": 0, + "gridPos": { + "h": 11, + "w": 12, + "x": 12, + "y": 12 + }, + "id": 18, + "legend": { + "avg": false, + "current": false, + "max": false, + "min": false, + "show": true, + "total": false, + "values": false + }, + "lines": true, + "linewidth": 1, + "nullPointMode": "null", + "options": { + "dataLinks": [] + }, + "percentage": false, + "pointradius": 2, + "points": false, + "renderer": "flot", + "seriesOverrides": [], + "spaceLength": 10, + "stack": false, + "steppedLine": false, + "targets": [ + { + "alias": "", + "refId": "A", + "sql": "select avg(disk_used) disk_used from log.dn where ts >= $from and ts < $to interval(1s) group by fqdn", + "target": "select metric", + "type": "timeserie" + } + ], + "thresholds": [], + "timeFrom": null, + "timeRegions": [], + "timeShift": null, + "title": "avg_disk_used", + "tooltip": { + "shared": true, + "sort": 0, + "value_type": "individual" + }, + "type": "graph", + "xaxis": { + "buckets": null, + "mode": "time", + "name": null, + "show": true, + "values": [] + }, + "yaxes": [ + { + "format": "decgbytes", + "label": "", + "logBase": 1, + "max": null, + "min": null, + "show": true + }, + { + "format": "short", + "label": null, + "logBase": 1, + "max": null, + "min": null, + "show": true + } + ], + "yaxis": { + "align": false, + "alignLevel": null + } + } + ], + "refresh": "5s", + "schemaVersion": 20, + "style": "dark", + "tags": [], + "templating": { + "list": [] + }, + "time": { + "from": "now-1h", + "to": "now" + }, + "timepicker": { + "refresh_intervals": [ + "5s", + "10s", + "30s", + "1m", + "5m", + "15m", + "30m", + "1h", + "2h", + "1d" + ] + }, + "timezone": "", + "title": "TDengine", + "uid": "FE-vpe0Wk", + "version": 1 +} diff --git a/docs-cn/14-reference/07-tdinsight/assets/tdengine_dashboard.png b/docs-cn/14-reference/07-tdinsight/assets/tdengine_dashboard.png new file mode 100644 index 0000000000000000000000000000000000000000..0101e7430cb2ef673818de8bd3af53d0d082ad3f Binary files /dev/null and b/docs-cn/14-reference/07-tdinsight/assets/tdengine_dashboard.png differ diff --git a/docs-cn/14-reference/07-tdinsight/index.md b/docs-cn/14-reference/07-tdinsight/index.md new file mode 100644 index 0000000000000000000000000000000000000000..a554d7ee6b36797940282fa8401df2f22c4cf579 --- /dev/null +++ b/docs-cn/14-reference/07-tdinsight/index.md @@ -0,0 +1,428 @@ +--- +title: TDinsight - 基于Grafana的TDengine零依赖监控解决方案 +sidebar_label: TDinsight +--- + +TDinsight 是使用内置监控数据库和 [Grafana] 对 TDengine 进行监控的解决方案。 + +TDengine 启动后，会自动创建一个监测数据库 `log`，并自动将服务器的 CPU、内存、硬盘空间、带宽、请求数、磁盘读写速度、慢查询等信息定时写入该数据库，并对重要的系统操作（比如登录、创建、删除数据库等）以及各种错误报警信息进行记录。通过 [Grafana] 和 [TDengine 数据源插件](https://github.com/taosdata/grafanaplugin/releases)，TDinsight 将集群状态、节点信息、插入及查询请求、资源使用情况等进行可视化展示，同时还支持 vnode、dnode、mnode 节点状态异常告警，为开发者实时监控 TDengine 集群运行状态提供了便利。本文将指导用户安装 Grafana 服务器并通过 `TDinsight.sh` 安装脚本自动安装 TDengine 数据源插件及部署 TDinsight 可视化面板。 + +## 系统要求 + +要部署 TDinsight，需要一个单节点的 TDengine 服务器或一个多节点的 [TDengine] 集群，以及一个[Grafana]服务器。此仪表盘需要 TDengine 2.3.3.0 及以上，并启用 `log` 数据库（`monitor = 1`）。 + +## 安装 Grafana + +我们建议在此处使用最新的[Grafana] 7 或 8 版本。您可以在任何[支持的操作系统](https://grafana.com/docs/grafana/latest/installation/requirements/#supported-operating-systems)中，按照 [Grafana 官方文档安装说明](https://grafana.com/docs/grafana/latest/installation/) 安装 [Grafana]。 + +### 在 Debian 或 Ubuntu 上安装 Grafana + +对于 Debian 或 Ubuntu 操作系统，建议使用 Grafana 镜像仓库。使用如下命令从零开始安装： + +```bash +sudo apt-get install -y apt-transport-https +sudo apt-get install -y software-properties-common wget +wget -q -O - https://packages.grafana.com/gpg.key |\ + sudo apt-key add - +echo "deb https://packages.grafana.com/oss/deb stable main" |\ + sudo tee -a /etc/apt/sources.list.d/grafana.list +sudo apt-get update +sudo apt-get install grafana +``` + +### 在 CentOS / RHEL 上安装 Grafana + +您可以从官方 YUM 镜像仓库安装。 + +```bash +sudo tee /etc/yum.repos.d/grafana.repo << EOF +[grafana] +name=grafana +baseurl=https://packages.grafana.com/oss/rpm +repo_gpgcheck=1 +enabled=1 +gpgcheck=1 +gpgkey=https://packages.grafana.com/gpg.key +sslverify=1 +sslcacert=/etc/pki/tls/certs/ca-bundle.crt +EOF +sudo yum install grafana +``` + +或者用 RPM 安装： + +```bash +wget https://dl.grafana.com/oss/release/grafana-7.5.11-1.x86_64.rpm +sudo yum install grafana-7.5.11-1.x86_64.rpm +# or +sudo yum install \ + https://dl.grafana.com/oss/release/grafana-7.5.11-1.x86_64.rpm +``` + +## 自动部署 TDinsight + +我们提供了一个自动化安装脚本 [`TDinsight.sh`](https://github.com/taosdata/grafanaplugin/releases/latest/download/TDinsight.sh) 脚本以便用户快速进行安装配置。 + +您可以通过 `wget` 或其他工具下载该脚本： + +```bash +wget https://github.com/taosdata/grafanaplugin/releases/latest/download/TDinsight.sh +chmod +x TDinsight.sh +./TDinsight.sh +``` + +这个脚本会自动下载最新的[Grafana TDengine 数据源插件](https://github.com/taosdata/grafanaplugin/releases/latest) 和 [TDinsight 仪表盘](https://grafana.com/grafana/dashboards/15167) ，将命令行选项中的可配置参数转为 [Grafana Provisioning](https://grafana.com/docs/grafana/latest/administration/provisioning/) 配置文件，以进行自动化部署及更新等操作。利用该脚本提供的告警设置选项，你还可以获得内置的阿里云短信告警通知支持。 + +假设您在同一台主机上使用 TDengine 和 Grafana 的默认服务。运行 `./TDinsight.sh` 并打开 Grafana 浏览器窗口就可以看到 TDinsight 仪表盘了。 + +下面是 TDinsight.sh 的用法说明： + +```text +Usage: + ./TDinsight.sh + ./TDinsight.sh -h|--help + ./TDinsight.sh -n -a -u -p + +Install and configure TDinsight dashboard in Grafana on Ubuntu 18.04/20.04 system. + +-h, -help, --help Display help + +-V, -verbose, --verbose Run script in verbose mode. Will print out each step of execution. + +-v, --plugin-version TDengine datasource plugin version, [default: latest] + +-P, --grafana-provisioning-dir Grafana provisioning directory, [default: /etc/grafana/provisioning/] +-G, --grafana-plugins-dir Grafana plugins directory, [default: /var/lib/grafana/plugins] +-O, --grafana-org-id Grafana organization id. [default: 1] + +-n, --tdengine-ds-name TDengine datasource name, no space. [default: TDengine] +-a, --tdengine-api TDengine REST API endpoint. [default: http://127.0.0.1:6041] +-u, --tdengine-user TDengine user name. [default: root] +-p, --tdengine-password TDengine password. [default: taosdata] + +-i, --tdinsight-uid Replace with a non-space ASCII code as the dashboard id. [default: tdinsight] +-t, --tdinsight-title Dashboard title. [default: TDinsight] +-e, --tdinsight-editable If the provisioning dashboard could be editable. [default: false] + +-E, --external-notifier Apply external notifier uid to TDinsight dashboard. + +Aliyun SMS as Notifier: +-s, --sms-enabled To enable tdengine-datasource plugin builtin Aliyun SMS webhook. +-N, --sms-notifier-name Provisioning notifier name.[default: TDinsight Builtin SMS] +-U, --sms-notifier-uid Provisioning notifier uid, use lowercase notifier name by default. +-D, --sms-notifier-is-default Set notifier as default. +-I, --sms-access-key-id Aliyun SMS access key id +-K, --sms-access-key-secret Aliyun SMS access key secret +-S, --sms-sign-name Sign name +-C, --sms-template-code Template code +-T, --sms-template-param Template param, a escaped JSON string like '{"alarm_level":"%s","time":"%s","name":"%s","content":"%s"}' +-B, --sms-phone-numbers Comma-separated numbers list, eg "189xxxxxxxx,132xxxxxxxx" +-L, --sms-listen-addr [default: 127.0.0.1:9100] +``` + +大多数命令行选项都可以通过环境变量获得同样的效果。 + +| 短选项 | 长选项 | 环境变量 | 说明 | +| ------ | -------------------------- | ---------------------------- | --------------------------------------------------------------------------- | +| -v | --plugin-version | TDENGINE_PLUGIN_VERSION | TDengine 数据源插件版本，默认使用最新版。 | +| -P | --grafana-provisioning-dir | GF_PROVISIONING_DIR | Grafana 配置目录，默认为`/etc/grafana/provisioning/` | +| -G | --grafana-plugins-dir | GF_PLUGINS_DIR | Grafana 插件目录，默认为`/var/lib/grafana/plugins`。 | +| -O | --grafana-org-id | GF_ORG_ID | Grafana 组织 ID，默认为 1。 | +| -n | --tdengine-ds-name | TDENGINE_DS_NAME | TDengine 数据源名称，默认为 TDengine。 | +| -a | --tdengine-api | TDENGINE_API | TDengine REST API 端点。默认为`http://127.0.0.1:6041`。 | +| -u | --tdengine-user | TDENGINE_USER | TDengine 用户名。 [默认值：root] | +| -p | --tdengine-密码 | TDENGINE_PASSWORD | TDengine 密码。 [默认：taosdata] | +| -i | --tdinsight-uid | TDINSIGHT_DASHBOARD_UID | TDinsight 仪表盘`uid`。 [默认值：tdinsight] | +| -t | --tdinsight-title | TDINSIGHT_DASHBOARD_TITLE | TDinsight 仪表盘标题。 [默认：TDinsight] | +| -e | --tdinsight-可编辑 | TDINSIGHT_DASHBOARD_EDITABLE | 如果配置仪表盘可以编辑。 [默认值：false] | +| -E | --external-notifier | EXTERNAL_NOTIFIER | 将外部通知程序 uid 应用于 TDinsight 仪表盘。 | +| -s | --sms-enabled | SMS_ENABLED | 启用阿里云短信 webhook 内置的 tdengine-datasource 插件。 | +| -N | --sms-notifier-name | SMS_NOTIFIER_NAME | 供应通知程序名称。[默认：`TDinsight Builtin SMS`] | +| -U | --sms-notifier-uid | SMS_NOTIFIER_UID | "Notification Channel" `uid`，默认使用程序名称的小写，其他字符用 “-” 代替。 | +| -D | --sms-notifier-is-default | SMS_NOTIFIER_IS_DEFAULT | 将内置短信通知设置为默认值。 | +| -I | --sms-access-key-id | SMS_ACCESS_KEY_ID | 阿里云短信访问密钥 id | +| -K | --sms-access-key-secret | SMS_ACCESS_KEY_SECRET | 阿里云短信访问秘钥 | +| -S | --sms-sign-name | SMS_SIGN_NAME | 签名 | +| -C | --sms-template-code | SMS_TEMPLATE_CODE | 模板代码 | +| -T | --sms-template-param | SMS_TEMPLATE_PARAM | 模板参数的 JSON 模板 | +| -B | --sms-phone-numbers | SMS_PHONE_NUMBERS | 逗号分隔的手机号列表，例如`"189xxxxxxxx,132xxxxxxxx"` | +| -L | --sms-listen-addr | SMS_LISTEN_ADDR | 内置 SMS webhook 监听地址，默认为`127.0.0.1:9100` | + +假设您在主机 `tdengine` 上启动 TDengine 数据库，HTTP API 端口为 `6041`，用户为 `root1`，密码为 `pass5ord`。执行脚本： + +```bash +sudo ./TDinsight.sh -a http://tdengine:6041 -u root1 -p pass5ord +``` + +我们提供了一个“-E”选项，用于从命令行配置 TDinsight 使用现有的通知通道(Notification Channel)。假设你的 Grafana 用户和密码是 `admin:admin`，使用以下命令获取已有的通知通道的`uid`： + +```bash +curl --no-progress-meter -u admin:admin http://localhost:3000/api/alert-notifications | jq +``` + +使用上面获取的 `uid` 值作为 `-E` 输入。 + +```bash +sudo ./TDinsight.sh -a http://tdengine:6041 -u root1 -p pass5ord -E existing-notifier +``` + +如果你想使用[阿里云短信](https://www.aliyun.com/product/sms)服务作为通知渠道，你应该使用`-s`标志启用并添加以下参数： + +- `-N`：Notification Channel 名，默认为`TDinsight Builtin SMS`。 +- `-U`：Channel uid，默认是 `name` 的小写，任何其他字符都替换为 - ，对于默认的 `-N`，其 uid 为 `tdinsight-builtin-sms`。 +- `-I`：阿里云短信访问密钥 id。 +- `-K`：阿里云短信访问秘钥。 +- `-S`：阿里云短信签名。 +- `-C`：阿里云短信模板 ID。 +- `-T`：阿里云短信模板参数，为 JSON 格式模板，示例如下 `'{"alarm_level":"%s","time":"%s","name":"%s","content":"%s "}'`。有四个参数：告警级别、时间、名称和告警内容。 +- `-B`：电话号码列表，以逗号`,`分隔。 + +如果要监控多个 TDengine 集群，则需要设置多个 TDinsight 仪表盘。设置非默认 TDinsight 需要进行一些更改： `-n` `-i` `-t` 选项需要更改为非默认名称，如果使用 内置短信告警功能，`-N` 和 `-L` 也应该改变。 + +```bash +sudo ./TDengine.sh -n TDengine-Env1 -a http://another:6041 -u root -p taosdata -i tdinsight-env1 -t 'TDinsight Env1' +# 如果使用内置短信通知 +sudo ./TDengine.sh -n TDengine-Env1 -a http://another:6041 -u root -p taosdata -i tdinsight-env1 -t 'TDinsight Env1' \ + -s -N 'Env1 SMS' -I xx -K xx -S xx -C SMS_XX -T '' -B 00000000000 -L 127.0.0.01:10611 +``` + +请注意，配置数据源、通知 Channel 和仪表盘在前端是不可更改的。您应该再次通过此脚本更新配置或手动更改 `/etc/grafana/provisioning` 目录（这是 Grafana 的默认目录，根据需要使用`-P`选项更改）中的配置文件。 + +特别地，当您使用 Grafana Cloud 或其他组织时，`-O` 可用于设置组织 ID。 `-G` 可指定 Grafana 插件安装目录。 `-e` 参数将仪表盘设置为可编辑。 + +## 手动设置 TDinsight + +### 安装 TDengine 数据源插件 + +从 GitHub 安装 TDengine 最新版数据源插件。 + +```bash +get_latest_release() { + curl --silent "https://api.github.com/repos/taosdata/grafanaplugin/releases/latest" | + grep '"tag_name":' | + sed -E 's/.*"v([^"]+)".*/\1/' +} +TDENGINE_PLUGIN_VERSION=$(get_latest_release) +sudo grafana-cli \ + --pluginUrl https://github.com/taosdata/grafanaplugin/releases/download/v$TDENGINE_PLUGIN_VERSION/tdengine-datasource-$TDENGINE_PLUGIN_VERSION.zip \ + plugins install tdengine-datasource +``` + +:::note +3.1.6 和更早版本插件需要在配置文件 `/etc/grafana/grafana.ini` 中添加如下设置，以启用未签名插件。 + +```ini +[plugins] +allow_loading_unsigned_plugins = tdengine-datasource +``` +::: + +### 启动 Grafana 服务 + +```bash +sudo systemctl start grafana-server +sudo systemctl enable grafana-server +``` + +### 登录到 Grafana + +在 Web 浏览器中打开默认的 Grafana 网址：`http://localhost:3000`。 +默认用户名/密码都是 `admin`。Grafana 会要求在首次登录后更改密码。 + +### 添加 TDengine 数据源 + +指向 **Configurations** -> **Data Sources** 菜单，然后点击 **Add data source** 按钮。 + +![添加数据源按钮](./assets/howto-add-datasource-button.png) + +搜索并选择**TDengine**。 + +![添加数据源](./assets/howto-add-datasource-tdengine.png) + +配置 TDengine 数据源。 + +![数据源配置](./assets/howto-add-datasource.png) + +保存并测试，正常情况下会报告 'TDengine Data source is working'。 + +![数据源测试](./assets/howto-add-datasource-test.png) + +### 导入仪表盘 + +指向 **+** / **Create** - **import**（或 `/dashboard/import` url）。 + +![导入仪表盘和配置](./assets/import_dashboard.png) + +在 **Import via grafana.com** 位置键入仪表盘 ID `15167` 并 **Load**。 + +![通过 grafana.com 导入](./assets/import-dashboard-15167.png) + +导入完成后，TDinsight 的完整页面视图如下所示。 + +![显示](./assets/TDinsight-full.png) + +## TDinsight 仪表盘详细信息 + +TDinsight 仪表盘旨在提供 TDengine 相关资源使用情况[dnodes, mnodes, vnodes](https://www.taosdata.com/cn/documentation/architecture#cluster)或数据库的使用情况和状态。 + +指标详情如下： + +### 集群状态 + +![tdinsight-mnodes-overview](./assets/TDinsight-1-cluster-status.png) + +这部分包括集群当前信息和状态，告警信息也在此处（从左到右，从上到下）。 + +- **First EP**：当前 TDengine 集群中的`firstEp`设置。 +- **Version**：TDengine 服务器版本（master mnode）。 +- **Master Uptime**: 当前 Master MNode 被选举为 Master 后经过的时间。 +- **Expire Time** - 企业版过期时间。 +- **Used Measuring Points** - 企业版已使用的测点数。 +- **Databases** - 数据库个数。 +- **Connections** - 当前连接个数。 +- **DNodes/MNodes/VGroups/VNodes**：每种资源的总数和存活数。 +- **DNodes/MNodes/VGroups/VNodes Alive Percent**：每种资源的存活数/总数的比例，启用告警规则，并在资源存活率（1 分钟内平均健康资源比例）不足 100%时触发。 +- **Measuring Points Used**：启用告警规则的测点数用量（社区版无数据，默认情况下是健康的）。 +- **Grants Expire Time**：启用告警规则的企业版过期时间（社区版无数据，默认情况是健康的）。 +- **Error Rate**：启用警报的集群总合错误率（每秒平均错误数）。 +- **Variables**：`show variables` 表格展示。 + +### DNodes 状态 + +![tdinsight-mnodes-overview](./assets/TDinsight-2-dnodes.png) + +- **DNodes Status**：`show dnodes` 的简单表格视图。 +- **DNodes Lifetime**：从创建 dnode 开始经过的时间。 +- **DNodes Number**：DNodes 数量变化。 +- **Offline Reason**：如果有任何 dnode 状态为离线，则以饼图形式展示离线原因。 + +### MNode 概述 + +![tdinsight-mnodes-overview](./assets/TDinsight-3-mnodes.png) + +1. **MNodes Status**：`show mnodes` 的简单表格视图。 +2. **MNodes Number**：类似于`DNodes Number`，MNodes 数量变化。 + +### 请求 + +![tdinsight-requests](./assets/TDinsight-4-requests.png) + +1. **Requests Rate(Inserts per Second)**：平均每秒插入次数。 +2. **Requests (Selects)**：查询请求数及变化率（count of second）。 +3. **Requests (HTTP)**：HTTP 请求数和请求速率（count of second）。 + +### 数据库 + +![tdinsight-database](./assets/TDinsight-5-database.png) + +数据库使用情况，对变量 `$database` 的每个值即每个数据库进行重复多行展示。 + +1. **STables**：超级表数量。 +2. **Total Tables**：所有表数量。 +3. **Sub Tables**：所有超级表子表的数量。 +4. **Tables**：所有普通表数量随时间变化图。 +5. **Tables Number Foreach VGroups**：每个 VGroups 包含的表数量。 + +### DNode 资源使用情况 + +![dnode-usage](./assets/TDinsight-6-dnode-usage.png) + +数据节点资源使用情况展示，对变量 `$fqdn` 即每个数据节点进行重复多行展示。包括： + +1. **Uptime**：从创建 dnode 开始经过的时间。 +2. **Has MNodes?**：当前 dnode 是否为 mnode。 +3. **CPU Cores**：CPU 核数。 +4. **VNodes Number**：当前 dnode 的 VNodes 数量。 +5. **VNodes Masters**：处于 master 角色的 vnode 数量。 +6. **Current CPU Usage of taosd**：taosd 进程的 CPU 使用率。 +7. **Current Memory Usage of taosd**：taosd 进程的内存使用情况。 +8. **Disk Used**：taosd 数据目录的总磁盘使用百分比。 +9. **CPU Usage**：进程和系统 CPU 使用率。 +10. **RAM Usage**：RAM 使用指标时间序列视图。 +11. **Disk Used**：多级存储下每个级别使用的磁盘（默认为 level0 级）。 +12. **Disk Increasing Rate per Minute**：每分钟磁盘用量增加或减少的百分比。 +13. **Disk IO**：磁盘 IO 速率。 +14. **Net IO**：网络 IO，除本机网络之外的总合网络 IO 速率。 + +### 登录历史 + +![登录历史](./assets/TDinsight-7-login-history.png) + +目前只报告每分钟登录次数。 + +### 监控 taosAdapter + +![taosadapter](./assets/TDinsight-8-taosadapter.png) + +支持监控 taosAdapter 请求统计和状态详情。包括： + +1. **http_request**: 包含总请求数，请求失败数以及正在处理的请求数 +2. **top 3 request endpoint**: 按终端分组，请求排名前三的数据 +3. **Memory Used**: taosAdapter 内存使用情况 +4. **latency_quantile(ms)**: (1, 2, 5, 9, 99)阶段的分位数 +5. **top 3 failed request endpoint**: 按终端分组，请求失败排名前三的数据 +6. **CPU Used**: taosAdapter CPU 使用情况 + +## 升级 + +通过 `TDinsight.sh` 脚本安装的 TDinsight，可以通过重新运行该脚本就可以升级到最新的 Grafana 插件和 TDinsight Dashboard。 + +手动安装的情况下，可按照上述步骤自行安装新的 Grafana 插件和 Dashboard。 + +## 卸载 + +通过 `TDinsight.sh` 脚本安装的 TDinsight，可以使用命令行 `TDinsight.sh -R` 清理相关资源。 + +手动安装时，要完全卸载 TDinsight，需要清理以下内容： + +1. Grafana 中的 TDinsight Dashboard。 +2. Grafana 中的 Data Source 数据源。 +3. 从插件安装目录删除 `tdengine-datasource` 插件。 + +## 整合的 Docker 示例 + +```bash +git clone --depth 1 https://github.com/taosdata/grafanaplugin.git +cd grafanaplugin +``` + +根据需要在 `docker-compose.yml` 文件中修改： + +```yaml +version: '3.7' + +services: + grafana: + image: grafana/grafana:7.5.10 + volumes: + - ./dist:/var/lib/grafana/plugins/tdengine-datasource + - ./grafana/grafana.ini:/etc/grafana/grafana.ini + - ./grafana/provisioning/:/etc/grafana/provisioning/ + - grafana-data:/var/lib/grafana + environment: + TDENGINE_API: ${TDENGINE_API} + TDENGINE_USER: ${TDENGINE_USER} + TDENGINE_PASS: ${TDENGINE_PASS} + SMS_ACCESS_KEY_ID: ${SMS_ACCESS_KEY_ID} + SMS_ACCESS_KEY_SECRET: ${SMS_ACCESS_KEY_SECRET} + SMS_SIGN_NAME: ${SMS_SIGN_NAME} + SMS_TEMPLATE_CODE: ${SMS_TEMPLATE_CODE} + SMS_TEMPLATE_PARAM: '${SMS_TEMPLATE_PARAM}' + SMS_PHONE_NUMBERS: $SMS_PHONE_NUMBERS + SMS_LISTEN_ADDR: ${SMS_LISTEN_ADDR} + ports: + - 3000:3000 +volumes: + grafana-data: +``` + +替换`docker-compose.yml`中的环境变量或保存环境变量到`.env`文件，然后用`docker-compose up`启动 Grafana。`docker-compose` 工具的具体用法参见 [Docker Compose Reference](https://docs.docker.com/compose/) + +```bash +docker-compose up -d +``` + +TDinsight 已经通过 Provisioning 部署完毕，请到 http://localhost:3000/d/tdinsight/ 查看仪表盘。 + +[grafana]: https://grafana.com +[tdengine]: https://www.taosdata.com diff --git a/docs-cn/14-reference/08-taos-shell.md b/docs-cn/14-reference/08-taos-shell.md new file mode 100644 index 0000000000000000000000000000000000000000..d4a516d2d2c30c7ae7122a04006b646aa1103635 --- /dev/null +++ b/docs-cn/14-reference/08-taos-shell.md @@ -0,0 +1,88 @@ +--- +title: TDengine 命令行(CLI) +sidebar_label: TDengine CLI +description: TDengine CLI 的使用说明和技巧 +--- + +TDengine 命令行程序（以下简称 TDengine CLI）是用户操作 TDengine 实例并与之交互的最简洁最常用的方式。 + +## 安装 + +如果在 TDengine 服务器端执行，无需任何安装，已经自动安装好 TDengine CLI。如果要在非 TDengine 服务器端运行，需要安装 TDengine 客户端驱动安装包，具体安装，请参考 [连接器](/reference/connector/)。 + +## 执行 + +要进入 TDengine CLI，您只要在 Linux 终端或 Windows 终端执行 `taos` 即可。 + +```bash +taos +``` + +如果连接服务成功，将会打印出欢迎消息和版本信息。如果失败，则会打印错误消息。（请参考 [FAQ](/train-faq/faq) 来解决终端连接服务端失败的问题）。TDengine CLI 的提示符号如下： + +```cmd +taos> +``` + +进入 TDengine CLI 后，你可执行各种 SQL 语句，包括插入、查询以及各种管理命令。 + +## 执行 SQL 脚本 + +在 TDengine CLI 里可以通过 `source` 命令来运行脚本文件中的多条 SQL 命令。 + +```sql +taos> source ; +``` + +## 在线修改显示字符宽度 + +可以在 TDengine CLI 里使用如下命令调整字符显示宽度 + +```sql +taos> SET MAX_BINARY_DISPLAY_WIDTH ; +``` + +如显示的内容后面以 ... 结尾时，表示该内容已被截断，可通过本命令修改显示字符宽度以显示完整的内容。 + +## 命令行参数 + +您可通过配置命令行参数来改变 TDengine CLI 的行为。以下为常用的几个命令行参数： + +- -h, --host=HOST: 要连接的 TDengine 服务端所在服务器的 FQDN, 默认为连接本地服务 +- -P, --port=PORT: 指定服务端所用端口号 +- -u, --user=USER: 连接时使用的用户名 +- -p, --password=PASSWORD: 连接服务端时使用的密码 +- -?, --help: 打印出所有命令行参数 + +还有更多其他参数： + +- -c, --config-dir: 指定配置文件目录，Linux 环境下默认为 `/etc/taos`，该目录下的配置文件默认名称为 `taos.cfg` +- -C, --dump-config: 打印 -c 指定的目录中 `taos.cfg` 的配置参数 +- -d, --database=DATABASE: 指定连接到服务端时使用的数据库 +- -D, --directory=DIRECTORY: 导入指定路径中的 SQL 脚本文件 +- -f, --file=FILE: 以非交互模式执行 SQL 脚本文件。文件中一个 SQL 语句只能占一行 +- -k, --check=CHECK: 指定要检查的表 +- -l, --pktlen=PKTLEN: 网络测试时使用的测试包大小 +- -n, --netrole=NETROLE: 网络连接测试时的测试范围，默认为 `startup`, 可选值为 `client`、`server`、`rpc`、`startup`、`sync`、`speed` 和 `fqdn` 之一 +- -r, --raw-time: 将时间输出出无符号 64 位整数类型(即 C 语音中 uint64_t) +- -s, --commands=COMMAND: 以非交互模式执行的 SQL 命令 +- -S, --pkttype=PKTTYPE: 指定网络测试所用的包类型，默认为 TCP。只有 netrole 为 `speed` 时既可以指定为 TCP 也可以指定为 UDP +- -T, --thread=THREADNUM: 以多线程模式导入数据时的线程数 +- -s, --commands: 在不进入终端的情况下运行 TDengine 命令 +- -z, --timezone=TIMEZONE: 指定时区，默认为本地时区 +- -V, --version: 打印出当前版本号 + +示例： + +```bash +taos -h h1.taos.com -s "use db; show tables;" +``` + +## TDengine CLI 小技巧 + +- 可以使用上下光标键查看历史输入的指令 +- 在 TDengine CLI 中使用 `alter user` 命令可以修改用户密码，缺省密码为 `taosdata` +- Ctrl+C 中止正在进行中的查询 +- 执行 `RESET QUERY CACHE` 可清除本地表 Schema 的缓存 +- 批量执行 SQL 语句。可以将一系列的 TDengine CLI 命令（以英文 ; 结尾，每个 SQL 语句为一行）按行存放在文件里，在 TDengine CLI 里执行命令 `source ` 自动执行该文件里所有的 SQL 语句 +- 输入 `q` 或 `quit` 或 `exit` 回车，可以退出 TDengine CLI diff --git a/docs-cn/14-reference/09-support-platform/_category_.yml b/docs-cn/14-reference/09-support-platform/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..ce2aa5213b1e85bbd07b7242d8bb1c1525e5c687 --- /dev/null +++ b/docs-cn/14-reference/09-support-platform/_category_.yml @@ -0,0 +1 @@ +label: 支持平台列表 diff --git a/docs-cn/14-reference/09-support-platform/index.md b/docs-cn/14-reference/09-support-platform/index.md new file mode 100644 index 0000000000000000000000000000000000000000..d396e4be1fed2e3ecdf202c6e57d509bc1941ecd --- /dev/null +++ b/docs-cn/14-reference/09-support-platform/index.md @@ -0,0 +1,40 @@ +--- +title: 支持平台列表 +description: "TDengine 服务端、客户端和连接器支持的平台列表" +--- + +## TDengine 服务端支持的平台列表 + +| | **CentOS 7/8** | **Ubuntu 16/18/20** | **Other Linux** | **统信 UOS** | **银河/中标麒麟** | **凝思 V60/V80** | **华为 EulerOS** | +| ------------ | -------------- | ------------------- | --------------- | ------------ | ----------------- | ---------------- | ---------------- | +| X64 | ● | ● | | ○ | ● | ● | ● | +| 龙芯 MIPS64 | | | ● | | | | | +| 鲲鹏 ARM64 | | ○ | ○ | | ● | | | +| 申威 Alpha64 | | | ○ | ● | | | | +| 飞腾 ARM64 | | ○ 优麒麟 | | | | | | +| 海光 X64 | ● | ● | ● | ○ | ● | ● | | +| 瑞芯微 ARM64 | | | ○ | | | | | +| 全志 ARM64 | | | ○ | | | | | +| 炬力 ARM64 | | | ○ | | | | | +| 华为云 ARM64 | | | | | | | ● | + +注： ● 表示经过官方测试验证， ○ 表示非官方测试验证。 + +## TDengine 客户端和连接器支持的平台列表 + +目前 TDengine 的连接器可支持的平台广泛，目前包括：X64/X86/ARM64/ARM32/MIPS/Alpha 等硬件平台，以及 Linux/Win64/Win32 等开发环境。 + +对照矩阵如下： + +| **CPU** | **X64 64bit** | | | **X86 32bit** | **ARM64** | **ARM32** | **MIPS 龙芯** | **Alpha 申威** | **X64 海光** | +| ----------- | ------------- | --------- | --------- | ------------- | --------- | --------- | ------------- | -------------- | ------------ | +| **OS** | **Linux** | **Win64** | **Win32** | **Win32** | **Linux** | **Linux** | **Linux** | **Linux** | **Linux** | +| **C/C++** | ● | ● | ● | ○ | ● | ● | ● | ● | ● | +| **JDBC** | ● | ● | ● | ○ | ● | ● | ● | ● | ● | +| **Python** | ● | ● | ● | ○ | ● | ● | ● | -- | ● | +| **Go** | ● | ● | ● | ○ | ● | ● | ○ | -- | -- | +| **NodeJs** | ● | ● | ○ | ○ | ● | ● | ○ | -- | -- | +| **C#** | ● | ● | ○ | ○ | ○ | ○ | ○ | -- | -- | +| **RESTful** | ● | ● | ● | ● | ● | ● | ● | ● | ● | + +注：● 表示官方测试验证通过，○ 表示非官方测试验证通过，-- 表示未经验证。 diff --git a/docs-cn/14-reference/11-docker/_category_.yml b/docs-cn/14-reference/11-docker/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..68c16927f4a9098311dec116aab41e8faa07fe81 --- /dev/null +++ b/docs-cn/14-reference/11-docker/_category_.yml @@ -0,0 +1 @@ +label: TDengine Docker 镜像 \ No newline at end of file diff --git a/docs-cn/14-reference/11-docker/index.md b/docs-cn/14-reference/11-docker/index.md new file mode 100644 index 0000000000000000000000000000000000000000..d0b7f1420420655909f6ceec5b249d2dad16dd3c --- /dev/null +++ b/docs-cn/14-reference/11-docker/index.md @@ -0,0 +1,515 @@ +--- +title: 用 Docker 部署 TDengine +description: '本章主要介绍如何在容器中启动 TDengine 服务并访问它' +--- + +本章主要介绍如何在容器中启动 TDengine 服务并访问它。可以在 docker run 命令行中或者 docker-compose 文件中使用环境变量来控制容器中服务的行为。 + +## 启动 TDengine + +TDengine 镜像启动时默认激活 HTTP 服务，使用下列命令 + +```shell +docker run -d --name tdengine -p 6041:6041 tdengine/tdengine +``` + +以上命令启动了一个名为“tdengine”的容器，并把其中的 HTTP 服务的端 6041 映射到了主机端口 6041。使用如下命令可以验证该容器中提供的 HTTP 服务是否可用： + +```shell +curl -u root:taosdata -d "show databases" localhost:6041/rest/sql +``` + +使用如下命令可以在该容器中执行 TDengine 的客户端 taos 对 TDengine 进行访问： + +```shell +$ docker exec -it tdengine taos + +Welcome to the TDengine shell from Linux, Client Version:2.4.0.0 +Copyright (c) 2020 by TAOS Data, Inc. All rights reserved. + +taos> show databases; + name | created_time | ntables | vgroups | replica | quorum | days | keep | cache(MB) | blocks | minrows | maxrows | wallevel | fsync | comp | cachelast | precision | update | status | +==================================================================================================================================================================================================================================================================================== + log | 2022-01-17 13:57:22.270 | 10 | 1 | 1 | 1 | 10 | 30 | 1 | 3 | 100 | 4096 | 1 | 3000 | 2 | 0 | us | 0 | ready | +Query OK, 1 row(s) in set (0.002843s) +``` + +因为运行在容器中的 TDengine 服务端使用容器的 hostname 建立连接，使用 taos shell 或者各种连接器（例如 JDBC-JNI）从容器外访问容器内的 TDengine 比较复杂，所以上述方式是访问容器中 TDengine 服务的最简单的方法，适用于一些简单场景。如果在一些复杂场景下想要从容器化使用 taos shell 或者各种连接器访问容器中的 TDengine 服务，请参考下一节。 + +## 在 host 网络上启动 TDengine + +```shell +docker run -d --name tdengine --network host tdengine/tdengine +``` + +上面的命令在 host 网络上启动 TDengine，并使用主机的 FQDN 建立连接而不是使用容器的 hostname 。这种方式和在主机上使用 `systemctl` 启动 TDengine 效果相同。在主机已安装 TDengine 客户端情况下，可以直接使用下面的命令访问它。 + +```shell +$ taos + +Welcome to the TDengine shell from Linux, Client Version:2.4.0.0 +Copyright (c) 2020 by TAOS Data, Inc. All rights reserved. + +taos> show dnodes; + id | end_point | vnodes | cores | status | role | create_time | offline reason | +====================================================================================================================================== + 1 | myhost:6030 | 1 | 8 | ready | any | 2022-01-17 22:10:32.619 | | +Query OK, 1 row(s) in set (0.003233s) +``` + +## 以指定的 hostname 和 port 启动 TDengine + +利用 `TAOS_FQDN` 环境变量或者 `taos.cfg` 中的 `fqdn` 配置项可以使 TDengine 在指定的 hostname 上建立连接。这种方式可以为部署提供更大的灵活性。 + +```shell +docker run -d \ + --name tdengine \ + -e TAOS_FQDN=tdengine \ + -p 6030-6049:6030-6049 \ + -p 6030-6049:6030-6049/udp \ + tdengine/tdengine +``` + +上面的命令在容器中启动一个 TDengine 服务，其所监听的 hostname 为 tdengine ，并将容器的 6030 到 6049 端口段映射到主机的 6030 到 6049 端口段 （tcp 和 udp 都需要映射)。如果主机上该端口段已经被占用，可以修改上述命令指定一个主机上空闲的端口段。如果 `rpcForceTcp` 被设置为 `1` ，可以只映射 tcp 协议。 + +接下来，要确保 "tdengine" 这个 hostname 在 `/etc/hosts` 中可解析。 + +```shell +echo 127.0.0.1 tdengine |sudo tee -a /etc/hosts +``` + +最后，可以从 taos shell 或者任意连接器以 "tdengine" 为服务端地址访问 TDengine 服务。 + +```shell +taos -h tdengine -P 6030 +``` + +如果 `TAOS_FQDN` 被设置为与所在主机名相同，则效果与 “在 host 网络上启动 TDengine” 相同。 + +## 在指定网络上启动 TDengine + +也可以在指定的特定网络上启动 TDengine。下面是详细步骤： + +1. 首先，创建一个 docker 网络，命名为 td-net + + ```shell + docker network create td-net + ``` + +2. 启动 TDengine + + 以下命令在 td-net 网络上启动 TDengine 服务 + + ```shell + docker run -d --name tdengine --network td-net \ + -e TAOS_FQDN=tdengine \ + tdengine/tdengine + ``` + +3. 在同一网络上的另一容器中启动 TDengine 客户端 + + ```shell + docker run --rm -it --network td-net -e TAOS_FIRST_EP=tdengine tdengine/tdengine taos + # or + #docker run --rm -it --network td-net -e tdengine/tdengine taos -h tdengine + ``` + +## 在容器中启动客户端应用 + +如果想在容器中启动自己的应用的话，需要将相应的对 TDengine 的依赖也要加入到镜像中，例如： + +```docker +FROM ubuntu:20.04 +RUN apt-get update && apt-get install -y wget +ENV TDENGINE_VERSION=2.4.0.0 +RUN wget -c https://www.taosdata.com/assets-download/TDengine-client-${TDENGINE_VERSION}-Linux-x64.tar.gz \ + && tar xvf TDengine-client-${TDENGINE_VERSION}-Linux-x64.tar.gz \ + && cd TDengine-client-${TDENGINE_VERSION} \ + && ./install_client.sh \ + && cd ../ \ + && rm -rf TDengine-client-${TDENGINE_VERSION}-Linux-x64.tar.gz TDengine-client-${TDENGINE_VERSION} +## add your application next, eg. go, build it in builder stage, copy the binary to the runtime +#COPY --from=builder /path/to/build/app /usr/bin/ +#CMD ["app"] +``` + +以下是一个 go 应用程序的示例： + +```go +/* + * In this test program, we'll create a database and insert 4 records then select out. + */ +package main + +import ( + "database/sql" + "flag" + "fmt" + "time" + + _ "github.com/taosdata/driver-go/v2/taosSql" +) + +type config struct { + hostName string + serverPort string + user string + password string +} + +var configPara config +var taosDriverName = "taosSql" +var url string + +func init() { + flag.StringVar(&configPara.hostName, "h", "", "The host to connect to TDengine server.") + flag.StringVar(&configPara.serverPort, "p", "", "The TCP/IP port number to use for the connection to TDengine server.") + flag.StringVar(&configPara.user, "u", "root", "The TDengine user name to use when connecting to the server.") + flag.StringVar(&configPara.password, "P", "taosdata", "The password to use when connecting to the server.") + flag.Parse() +} + +func printAllArgs() { + fmt.Printf("============= args parse result: =============\n") + fmt.Printf("hostName: %v\n", configPara.hostName) + fmt.Printf("serverPort: %v\n", configPara.serverPort) + fmt.Printf("usr: %v\n", configPara.user) + fmt.Printf("password: %v\n", configPara.password) + fmt.Printf("================================================\n") +} + +func main() { + printAllArgs() + + url = "root:taosdata@/tcp(" + configPara.hostName + ":" + configPara.serverPort + ")/" + + taos, err := sql.Open(taosDriverName, url) + checkErr(err, "open database error") + defer taos.Close() + + taos.Exec("create database if not exists test") + taos.Exec("use test") + taos.Exec("create table if not exists tb1 (ts timestamp, a int)") + _, err = taos.Exec("insert into tb1 values(now, 0)(now+1s,1)(now+2s,2)(now+3s,3)") + checkErr(err, "failed to insert") + rows, err := taos.Query("select * from tb1") + checkErr(err, "failed to select") + + defer rows.Close() + for rows.Next() { + var r struct { + ts time.Time + a int + } + err := rows.Scan(&r.ts, &r.a) + if err != nil { + fmt.Println("scan error:\n", err) + return + } + fmt.Println(r.ts, r.a) + } +} + +func checkErr(err error, prompt string) { + if err != nil { + fmt.Println("ERROR: %s\n", prompt) + panic(err) + } +} +``` + +如下是完整版本的 dockerfile + +```docker +FROM golang:1.17.6-buster as builder +ENV TDENGINE_VERSION=2.4.0.0 +RUN wget -c https://www.taosdata.com/assets-download/TDengine-client-${TDENGINE_VERSION}-Linux-x64.tar.gz \ + && tar xvf TDengine-client-${TDENGINE_VERSION}-Linux-x64.tar.gz \ + && cd TDengine-client-${TDENGINE_VERSION} \ + && ./install_client.sh \ + && cd ../ \ + && rm -rf TDengine-client-${TDENGINE_VERSION}-Linux-x64.tar.gz TDengine-client-${TDENGINE_VERSION} +WORKDIR /usr/src/app/ +ENV GOPROXY="https://goproxy.io,direct" +COPY ./main.go ./go.mod ./go.sum /usr/src/app/ +RUN go env +RUN go mod tidy +RUN go build + +FROM ubuntu:20.04 +RUN apt-get update && apt-get install -y wget +ENV TDENGINE_VERSION=2.4.0.0 +RUN wget -c https://www.taosdata.com/assets-download/TDengine-client-${TDENGINE_VERSION}-Linux-x64.tar.gz \ + && tar xvf TDengine-client-${TDENGINE_VERSION}-Linux-x64.tar.gz \ + && cd TDengine-client-${TDENGINE_VERSION} \ + && ./install_client.sh \ + && cd ../ \ + && rm -rf TDengine-client-${TDENGINE_VERSION}-Linux-x64.tar.gz TDengine-client-${TDENGINE_VERSION} + +## add your application next, eg. go, build it in builder stage, copy the binary to the runtime +COPY --from=builder /usr/src/app/app /usr/bin/ +CMD ["app"] +``` + +目前我们已经有了 `main.go`, `go.mod`, `go.sum`, `app.dockerfile`， 现在可以构建出这个应用程序并在 `td-net` 网络上启动它 + +```shell +$ docker build -t app -f app.dockerfile +$ docker run --rm --network td-net app -h tdengine -p 6030 +============= args parse result: ============= +hostName: tdengine +serverPort: 6030 +usr: root +password: taosdata +================================================ +2022-01-17 15:56:55.48 +0000 UTC 0 +2022-01-17 15:56:56.48 +0000 UTC 1 +2022-01-17 15:56:57.48 +0000 UTC 2 +2022-01-17 15:56:58.48 +0000 UTC 3 +2022-01-17 15:58:01.842 +0000 UTC 0 +2022-01-17 15:58:02.842 +0000 UTC 1 +2022-01-17 15:58:03.842 +0000 UTC 2 +2022-01-17 15:58:04.842 +0000 UTC 3 +2022-01-18 01:43:48.029 +0000 UTC 0 +2022-01-18 01:43:49.029 +0000 UTC 1 +2022-01-18 01:43:50.029 +0000 UTC 2 +2022-01-18 01:43:51.029 +0000 UTC 3 +``` + +## 用 docker-compose 启动 TDengine 集群 + +1. 如下 docker-compose 文件启动一个 2 副本、2 管理节点、2 数据节点以及 1 个 arbitrator 的 TDengine 集群。 + + ```docker + version: "3" + services: + arbitrator: + image: tdengine/tdengine:$VERSION + command: tarbitrator + td-1: + image: tdengine/tdengine:$VERSION + environment: + TAOS_FQDN: "td-1" + TAOS_FIRST_EP: "td-1" + TAOS_NUM_OF_MNODES: "2" + TAOS_REPLICA: "2" + TAOS_ARBITRATOR: arbitrator:6042 + volumes: + - taosdata-td1:/var/lib/taos/ + - taoslog-td1:/var/log/taos/ + td-2: + image: tdengine/tdengine:$VERSION + environment: + TAOS_FQDN: "td-2" + TAOS_FIRST_EP: "td-1" + TAOS_NUM_OF_MNODES: "2" + TAOS_REPLICA: "2" + TAOS_ARBITRATOR: arbitrator:6042 + volumes: + - taosdata-td2:/var/lib/taos/ + - taoslog-td2:/var/log/taos/ + volumes: + taosdata-td1: + taoslog-td1: + taosdata-td2: + taoslog-td2: + ``` + +:::note + +- `VERSION` 环境变量被用来设置 tdengine image tag +- 在新创建的实例上必须设置 `TAOS_FIRST_EP` 以使其能够加入 TDengine 集群；如果有高可用需求，则需要同时使用 `TAOS_SECOND_EP` +- `TAOS_REPLICA` 用来设置缺省的数据库副本数量，其取值范围为[1,3] + 在双副本环境下，推荐使用 arbitrator, 用 TAOS_ARBITRATOR 来设置 + ::: + +2. 启动集群 + + ```shell + $ VERSION=2.4.0.0 docker-compose up -d + Creating network "test_default" with the default driver + Creating volume "test_taosdata-td1" with default driver + Creating volume "test_taoslog-td1" with default driver + Creating volume "test_taosdata-td2" with default driver + Creating volume "test_taoslog-td2" with default driver + Creating test_td-1_1 ... done + Creating test_arbitrator_1 ... done + Creating test_td-2_1 ... done + ``` + +3. 查看节点状态 + + ```shell + $ docker-compose ps + Name Command State Ports + --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + test_arbitrator_1 /usr/bin/entrypoint.sh tar ... Up 6030/tcp, 6031/tcp, 6032/tcp, 6033/tcp, 6034/tcp, 6035/tcp, 6036/tcp, 6037/tcp, 6038/tcp, 6039/tcp, 6040/tcp, 6041/tcp, 6042/tcp + test_td-1_1 /usr/bin/entrypoint.sh taosd Up 6030/tcp, 6031/tcp, 6032/tcp, 6033/tcp, 6034/tcp, 6035/tcp, 6036/tcp, 6037/tcp, 6038/tcp, 6039/tcp, 6040/tcp, 6041/tcp, 6042/tcp + test_td-2_1 /usr/bin/entrypoint.sh taosd Up 6030/tcp, 6031/tcp, 6032/tcp, 6033/tcp, 6034/tcp, 6035/tcp, 6036/tcp, 6037/tcp, 6038/tcp, 6039/tcp, 6040/tcp, 6041/tcp, 6042/tcp + ``` + +4. 用 taos shell 查看 dnodes + + ```shell + $ docker-compose exec td-1 taos -s "show dnodes" + + Welcome to the TDengine shell from Linux, Client Version:2.4.0.0 + Copyright (c) 2020 by TAOS Data, Inc. All rights reserved. + + taos> show dnodes + id | end_point | vnodes | cores | status | role | create_time | offline reason | + ====================================================================================================================================== + 1 | td-1:6030 | 1 | 8 | ready | any | 2022-01-18 02:47:42.871 | | + 2 | td-2:6030 | 0 | 8 | ready | any | 2022-01-18 02:47:43.518 | | + 0 | arbitrator:6042 | 0 | 0 | ready | arb | 2022-01-18 02:47:43.633 | - | + Query OK, 3 row(s) in set (0.000811s) + ``` + +## taosAdapter + +1. taosAdapter 在 TDengine 容器中默认是启动的。如果想要禁用它，在启动时指定环境变量 `TAOS_DISABLE_ADAPTER=true` + +2. 同时为了部署灵活起见，可以在独立的容器中启动 taosAdapter + + ```docker + services: + # ... + adapter: + image: tdengine/tdengine:$VERSION + command: taosadapter + ``` + + 如果要部署多个 taosAdapter 来提高吞吐量并提供高可用性，推荐配置方式为使用 nginx 等反向代理来提供统一的访问入口。具体配置方法请参考 nginx 的官方文档。如下是示例： + + ```docker + version: "3" + + networks: + inter: + api: + + services: + arbitrator: + image: tdengine/tdengine:$VERSION + command: tarbitrator + networks: + - inter + td-1: + image: tdengine/tdengine:$VERSION + networks: + - inter + environment: + TAOS_FQDN: "td-1" + TAOS_FIRST_EP: "td-1" + TAOS_NUM_OF_MNODES: "2" + TAOS_REPLICA: "2" + TAOS_ARBITRATOR: arbitrator:6042 + volumes: + - taosdata-td1:/var/lib/taos/ + - taoslog-td1:/var/log/taos/ + td-2: + image: tdengine/tdengine:$VERSION + networks: + - inter + environment: + TAOS_FQDN: "td-2" + TAOS_FIRST_EP: "td-1" + TAOS_NUM_OF_MNODES: "2" + TAOS_REPLICA: "2" + TAOS_ARBITRATOR: arbitrator:6042 + volumes: + - taosdata-td2:/var/lib/taos/ + - taoslog-td2:/var/log/taos/ + adapter: + image: tdengine/tdengine:$VERSION + command: taosadapter + networks: + - inter + environment: + TAOS_FIRST_EP: "td-1" + TAOS_SECOND_EP: "td-2" + deploy: + replicas: 4 + nginx: + image: nginx + depends_on: + - adapter + networks: + - inter + - api + ports: + - 6041:6041 + - 6044:6044/udp + command: [ + "sh", + "-c", + "while true; + do curl -s http://adapter:6041/-/ping >/dev/null && break; + done; + printf 'server{listen 6041;location /{proxy_pass http://adapter:6041;}}' + > /etc/nginx/conf.d/rest.conf; + printf 'stream{server{listen 6044 udp;proxy_pass adapter:6044;}}' + >> /etc/nginx/nginx.conf;cat /etc/nginx/nginx.conf; + nginx -g 'daemon off;'", + ] + volumes: + taosdata-td1: + taoslog-td1: + taosdata-td2: + taoslog-td2: + ``` + +## 使用 docker swarm 部署 + +如果要想将基于容器的 TDengine 集群部署在多台主机上，可以使用 docker swarm。首先要在这些主机上建立 docke swarm 集群，请参考 docker 官方文档。 + +docker-compose 文件可以参考上节。下面是使用 docker swarm 启动 TDengine 的命令： + +```shell +$ VERSION=2.4.0 docker stack deploy -c docker-compose.yml taos +Creating network taos_inter +Creating network taos_api +Creating service taos_arbitrator +Creating service taos_td-1 +Creating service taos_td-2 +Creating service taos_adapter +Creating service taos_nginx +``` + +查看和管理 + +```shell +$ docker stack ps taos +ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS +79ni8temw59n taos_nginx.1 nginx:latest TM1701 Running Running about a minute ago +3e94u72msiyg taos_adapter.1 tdengine/tdengine:2.4.0 TM1702 Running Running 56 seconds ago +100amjkwzsc6 taos_td-2.1 tdengine/tdengine:2.4.0 TM1703 Running Running about a minute ago +pkjehr2vvaaa taos_td-1.1 tdengine/tdengine:2.4.0 TM1704 Running Running 2 minutes ago +tpzvgpsr1qkt taos_arbitrator.1 tdengine/tdengine:2.4.0 TM1705 Running Running 2 minutes ago +rvss3g5yg6fa taos_adapter.2 tdengine/tdengine:2.4.0 TM1706 Running Running 56 seconds ago +i2augxamfllf taos_adapter.3 tdengine/tdengine:2.4.0 TM1707 Running Running 56 seconds ago +lmjyhzccpvpg taos_adapter.4 tdengine/tdengine:2.4.0 TM1708 Running Running 56 seconds ago +$ docker service ls +ID NAME MODE REPLICAS IMAGE PORTS +561t4lu6nfw6 taos_adapter replicated 4/4 tdengine/tdengine:2.4.0 +3hk5ct3q90sm taos_arbitrator replicated 1/1 tdengine/tdengine:2.4.0 +d8qr52envqzu taos_nginx replicated 1/1 nginx:latest *:6041->6041/tcp, *:6044->6044/udp +2isssfvjk747 taos_td-1 replicated 1/1 tdengine/tdengine:2.4.0 +9pzw7u02ichv taos_td-2 replicated 1/1 tdengine/tdengine:2.4.0 +``` + +从上面的输出可以看到有两个 dnode， 和两个 taosAdapter，以及一个 nginx 反向代理服务。 + +接下来，我们可以减少 taosAdapter 服务的数量 + +```shell +$ docker service scale taos_adapter=1 +taos_adapter scaled to 1 +overall progress: 1 out of 1 tasks +1/1: running [==================================================>] +verify: Service converged + +$ docker service ls -f name=taos_adapter +ID NAME MODE REPLICAS IMAGE PORTS +561t4lu6nfw6 taos_adapter replicated 1/1 tdengine/tdengine:2.4.0 +``` diff --git a/docs-cn/14-reference/12-config/_category_.yml b/docs-cn/14-reference/12-config/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..8d3cfcc8d0d8966bf1354f9ece83faea105f9c7a --- /dev/null +++ b/docs-cn/14-reference/12-config/_category_.yml @@ -0,0 +1 @@ +label: 配置参数 \ No newline at end of file diff --git a/docs-cn/14-reference/12-config/index.md b/docs-cn/14-reference/12-config/index.md new file mode 100644 index 0000000000000000000000000000000000000000..cbb3833b5bb170720c2aa7bea6687a50feeae7d5 --- /dev/null +++ b/docs-cn/14-reference/12-config/index.md @@ -0,0 +1,1131 @@ +--- +title: 配置参数 +description: 'TDengine 客户端和服务配置列表' +--- + +## 为服务端指定配置文件 + +TDengine 系统后台服务由 taosd 提供，可以在配置文件 taos.cfg 里修改配置参数，以满足不同场景的需求。配置文件的缺省位置在/etc/taos 目录，可以通过 taosd 命令行执行参数 -c 指定配置文件目录。比如，指定配置文件位于`/home/user` 这个目录： + +``` +taosd -c /home/user +``` + +另外可以使用 `-C` 显示当前服务器配置参数： + +``` +taosd -C +``` + +## 为客户端指定配置文件 + +TDengine 系统的前台交互客户端应用程序为 taos，以及应用驱动，它可以与 taosd 共享同一个配置文件 taos.cfg，也可以使用单独指定配置文件。运行 taos 时，使用参数-c 指定配置文件目录，如 taos -c /home/cfg，表示使用/home/cfg/目录下的 taos.cfg 配置文件中的参数，缺省目录是/etc/taos。更多 taos 的使用方法请见帮助信息 `taos --help`。 + +**2.0.10.0 之后版本支持命令行以下参数显示当前客户端参数的配置** + +```bash +taos -C +``` + +```bash +taos --dump-config +``` + +# 配置参数详细列表 + +:::note +本节内容覆盖产品的配置参数，适用于服务端的参数按其对产品行为的影响进行分类，这其中有部分参数也同时适用于客户端；但有少量参数仅适用于客户端，这部分参数进行了单独归类。 + +::: + +:::note +配置文件参数修改后，需要重启*taosd*服务，或客户端应用才能生效。 + +::: + +## 连接相关 + +### firstEp + +| 属性 | 说明 | +| -------- | --------------------------------------------------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | taosd 或者 taos 启动时，主动连接的集群中首个 dnode 的 endpoint | +| 缺省值 | localhost:6030 | + +### secondEp + +| 属性 | 说明 | +| -------- | -------------------------------------------------------------------------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | taosd 或者 taos 启动时，如果 firstEp 连接不上，尝试连接集群中第二个 dnode 的 endpoint | +| 缺省值 | 无 | + +### fqdn + +| 属性 | 说明 | +| -------- | ----------------------------------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 数据节点的 FQDN。如果习惯 IP 地址访问，可设置为该节点的 IP 地址。 | +| 缺省值 | 缺省为操作系统配置的第一个 hostname。 | +| 补充说明 | 这个参数值的长度需要控制在 96 个字符以内。 | + +### serverPort + +| 属性 | 说明 | +| -------- | ----------------------------------------------------------------------------------------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | taosd 启动后，对外服务的端口号 | +| 缺省值 | 6030 | +| 补充说明 | RESTful 服务在 2.4.0.0 之前（不含）由 taosd 提供，默认端口为 6041; 在 2.4.0.0 及后续版本由 taosAdapter，默认端口为 6041 | + +:::note +对于端口，TDengine 会使用从 serverPort 起 13 个连续的 TCP 和 UDP 端口号，请务必在防火墙打开。因此如果是缺省配置，需要打开从 6030 到 6042 共 13 个端口，而且必须 TCP 和 UDP 都打开。（详细的端口情况请参见下表） +::: +| 协议 | 默认端口 | 用途说明 | 修改方法 | +| :--- | :-------- | :---------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------- | +| TCP | 6030 | 客户端与服务端之间通讯。 | 由配置文件设置 serverPort 决定。 | +| TCP | 6035 | 多节点集群的节点间通讯。 | 随 serverPort 端口变化。 | +| TCP | 6040 | 多节点集群的节点间数据同步。 | 随 serverPort 端口变化。 | +| TCP | 6041 | 客户端与服务端之间的 RESTful 通讯。 | 随 serverPort 端口变化。注意 taosAdapter 配置或有不同，请参考相应[文档](/reference/taosadapter/)。 | +| TCP | 6042 | Arbitrator 的服务端口。 | 随 Arbitrator 启动参数设置变化。 | +| TCP | 6043 | TaosKeeper 监控服务端口。 | 随 TaosKeeper 启动参数设置变化。 | +| TCP | 6044 | 支持 StatsD 的数据接入端口。 | 随 taosAdapter 启动参数设置变化（2.3.0.1+以上版本）。 | +| UDP | 6045 | 支持 collectd 数据接入端口。 | 随 taosAdapter 启动参数设置变化（2.3.0.1+以上版本）。 | +| TCP | 6060 | 企业版内 Monitor 服务的网络端口。 | | +| UDP | 6030-6034 | 客户端与服务端之间通讯。 | 随 serverPort 端口变化。 | +| UDP | 6035-6039 | 多节点集群的节点间通讯。 | 随 serverPort 端口变化。 + +### maxShellConns + +| 属性 | 说明 | +| -------- | ----------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 一个 dnode 容许的连接数 | +| 取值范围 | 10-50000000 | +| 缺省值 | 5000 | + +### maxConnections + +| 属性 | 说明 | +| -------- | ------------------------------------------------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 一个数据库连接所容许的 dnode 连接数 | +| 取值范围 | 1-100000 | +| 缺省值 | 5000 | +| 补充说明 | 实际测试下来，如果默认没有配，选 50 个 worker thread 会产生 Network unavailable | + +### rpcForceTcp + +| 属性 | 说明 | +| -------- | --------------------------------------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | 强制使用 TCP 传输 | +| 取值范围 | 0: 不开启 1: 开启 | +| 缺省值 | 0 | +| 补充说明 | 在网络比较差的环境中，建议开启。
2.0 版本新增。 | + +## 监控相关 + +### monitor + +| 属性 | 说明 | +| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 服务器内部的系统监控开关。监控主要负责收集物理节点的负载状况，包括 CPU、内存、硬盘、网络带宽、HTTP 请求量的监控记录，记录信息存储在`LOG`库中。 | +| 取值范围 | 0：关闭监控服务， 1：激活监控服务。 | +| 缺省值 | 0 | + +### monitorInterval + +| 属性 | 说明 | +| -------- | -------------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 监控数据库记录系统参数（CPU/内存）的时间间隔 | +| 单位 | 秒 | +| 取值范围 | 1-600 | +| 缺省值 | 30 | + +### telemetryReporting + +| 属性 | 说明 | +| -------- | ---------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 是否允许 TDengine 采集和上报基本使用信息 | +| 取值范围 | 0：不允许 1：允许 | +| 缺省值 | 1 | + +## 查询相关 + +### queryBufferSize + +| 属性 | 说明 | +| -------- | ------------------------------------------------------------------------------------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 为所有并发查询占用保留的内存大小。 | +| 单位 | MB | +| 缺省值 | 无 | +| 补充说明 | 计算规则可以根据实际应用可能的最大并发数和表的数字相乘，再乘 170 。
（2.0.15 以前的版本中，此参数的单位是字节） | + +### ratioOfQueryCores + +| 属性 | 说明 | +| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 设置查询线程的最大数量。 | +| 缺省值 | 1 | +| 补充说明 | 最小值 0 表示只有 1 个查询线程
最大值 2 表示最大建立 2 倍 CPU 核数的查询线程。
默认为 1，表示最大和 CPU 核数相等的查询线程。
该值可以为小数，即 0.5 表示最大建立 CPU 核数一半的查询线程。 | + +### maxNumOfDistinctRes + +| 属性 | 说明 | +| -------- | -------------------------------- | --- | +| 适用范围 | 仅服务端适用 | +| 含义 | 允许返回的 distinct 结果最大行数 | +| 取值范围 | 默认值为 10 万，最大值 1 亿 | +| 缺省值 | 10 万 | +| 补充说明 | 2.3 版本新增。 | | + +## 区域相关 + +### timezone + +| 属性 | 说明 | +| -------- | ------------------------------ | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | 时区 | +| 缺省值 | 从系统中动态获取当前的时区设置 | + +:::info +为应对多时区的数据写入和查询问题，TDengine 采用 Unix 时间戳(Unix Timestamp)来记录和存储时间戳。Unix 时间戳的特点决定了任一时刻不论在任何时区，产生的时间戳均一致。需要注意的是，Unix 时间戳是在客户端完成转换和记录。为了确保客户端其他形式的时间转换为正确的 Unix 时间戳，需要设置正确的时区。 + +在 Linux 系统中，客户端会自动读取系统设置的时区信息。用户也可以采用多种方式在配置文件设置时区。例如： + +``` +timezone UTC-8 +timezone GMT-8 +timezone Asia/Shanghai +``` + +均是合法的设置东八区时区的格式。但需注意，Windows 下并不支持 `timezone Asia/Shanghai` 这样的写法，而必须写成 `timezone UTC-8`。 + +时区的设置对于查询和写入 SQL 语句中非 Unix 时间戳的内容（时间戳字符串、关键词 now 的解析）产生影响。例如： + +```sql +SELECT count(*) FROM table_name WHERE TS<'2019-04-11 12:01:08'; +``` + +在东八区，SQL 语句等效于 + +```sql +SELECT count(*) FROM table_name WHERE TS<1554955268000; +``` + +在 UTC 时区，SQL 语句等效于 + +```sql +SELECT count(*) FROM table_name WHERE TS<1554984068000; +``` + +为了避免使用字符串时间格式带来的不确定性，也可以直接使用 Unix 时间戳。此外，还可以在 SQL 语句中使用带有时区的时间戳字符串，例如：RFC3339 格式的时间戳字符串，2013-04-12T15:52:01.123+08:00 或者 ISO-8601 格式时间戳字符串 2013-04-12T15:52:01.123+0800。上述两个字符串转化为 Unix 时间戳不受系统所在时区的影响。 + +::: + +### locale + +| 属性 | 说明 | +| -------- | ----------------------------------------------------------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | 系统区位信息及编码格式 | +| 缺省值 | 系统中动态获取，如果自动获取失败，需要用户在配置文件设置或通过 API 设置 | + +:::info +TDengine 为存储中文、日文、韩文等非 ASCII 编码的宽字符，提供一种专门的字段类型 nchar。写入 nchar 字段的数据将统一采用 UCS4-LE 格式进行编码并发送到服务器。需要注意的是，编码正确性是客户端来保证。因此，如果用户想要正常使用 nchar 字段来存储诸如中文、日文、韩文等非 ASCII 字符，需要正确设置客户端的编码格式。 + +客户端的输入的字符均采用操作系统当前默认的编码格式，在 Linux 系统上多为 UTF-8，部分中文系统编码则可能是 GB18030 或 GBK 等。在 docker 环境中默认的编码是 POSIX。在中文版 Windows 系统中，编码则是 CP936。客户端需要确保正确设置自己所使用的字符集，即客户端运行的操作系统当前编码字符集，才能保证 nchar 中的数据正确转换为 UCS4-LE 编码格式。 + +在 Linux 中 locale 的命名规则为: <语言>\_<地区>.<字符集编码> 如：zh_CN.UTF-8，zh 代表中文，CN 代表大陆地区，UTF-8 表示字符集。字符集编码为客户端正确解析本地字符串提供编码转换的说明。Linux 系统与 Mac OSX 系统可以通过设置 locale 来确定系统的字符编码，由于 Windows 使用的 locale 中不是 POSIX 标准的 locale 格式，因此在 Windows 下需要采用另一个配置参数 charset 来指定字符编码。在 Linux 系统中也可以使用 charset 来指定字符编码。 + +::: + +### charset + +| 属性 | 说明 | +| -------- | ----------------------------------------------------------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | 字符集编码 | +| 缺省值 | 系统中动态获取，如果自动获取失败，需要用户在配置文件设置或通过 API 设置 | + +:::info +如果配置文件中不设置 charset，在 Linux 系统中，taos 在启动时候，自动读取系统当前的 locale 信息，并从 locale 信息中解析提取 charset 编码格式。如果自动读取 locale 信息失败，则尝试读取 charset 配置，如果读取 charset 配置也失败，则中断启动过程。 + +在 Linux 系统中，locale 信息包含了字符编码信息，因此正确设置了 Linux 系统 locale 以后可以不用再单独设置 charset。例如： + +``` +locale zh_CN.UTF-8 +``` + +在 Windows 系统中，无法从 locale 获取系统当前编码。如果无法从配置文件中读取字符串编码信息，taos 默认设置为字符编码为 CP936。其等效在配置文件中添加如下配置： + +``` +charset CP936 +``` + +如果需要调整字符编码，请查阅当前操作系统使用的编码，并在配置文件中正确设置。 + +在 Linux 系统中，如果用户同时设置了 locale 和字符集编码 charset，并且 locale 和 charset 的不一致，后设置的值将覆盖前面设置的值。 + +``` +locale zh_CN.UTF-8 +charset GBK +``` + +则 charset 的有效值是 GBK。 + +``` +charset GBK +locale zh_CN.UTF-8 +``` + +charset 的有效值是 UTF-8。 + +::: + +## 存储相关 + +### dataDir + +| 属性 | 说明 | +| -------- | ------------------------------------------ | +| 适用范围 | 仅服务端适用 | +| 含义 | 数据文件目录，所有的数据文件都将写入该目录 | +| 缺省值 | /var/lib/taos | + +### cache + +| 属性 | 说明 | +| -------- | ------------ | +| 适用范围 | 仅服务端适用 | +| 含义 | 内存块的大小 | +| 单位 | MB | +| 缺省值 | 16 | + +### blocks + +| 属性 | 说明 | +| -------- | ----------------------------------------------------------------------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 每个 vnode（tsdb）中有多少 cache 大小的内存块。因此一个 vnode 的用的内存大小粗略为（cache \* blocks） | +| 缺省值 | 6 | + +### days + +| 属性 | 说明 | +| -------- | -------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 数据文件存储数据的时间跨度 | +| 单位 | 天 | +| 缺省值 | 10 | + +### keep + +| 属性 | 说明 | +| -------- | -------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 数据保留的天数 | +| 单位 | 天 | +| 缺省值 | 3650 | + +### minRows + +| 属性 | 说明 | +| -------- | ---------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 文件块中记录的最小条数 | +| 缺省值 | 100 | + +### maxRows + +| 属性 | 说明 | +| -------- | ---------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 文件块中记录的最大条数 | +| 缺省值 | 4096 | + +### walLevel + +| 属性 | 说明 | +| -------- | --------------------------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | WAL 级别 | +| 取值范围 | 0: 不写WAL;
1：写 WAL, 但不执行 fsync
2：写 WAL, 而且执行 fsync | +| 缺省值 | 1 | + +### fsync + +| 属性 | 说明 | +| -------- | -------------------------------------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 当 WAL 设置为 2 时，执行 fsync 的周期 | +| 单位 | 毫秒 | +| 取值范围 | 最小为 0，表示每次写入，立即执行 fsync
最大为 180000（三分钟） | +| 缺省值 | 3000 | + +### update + +| 属性 | 说明 | +| -------- | ---------------------------------------------------------------------------------------------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 允许更新已存在的数据行 | +| 取值范围 | 0：不允许更新
1：允许整行更新
2：允许部分列更新。（2.1.7.0 版本开始此参数支持设为 2，在此之前取值只能是 [0, 1]） | +| 缺省值 | 0 | +| 补充说明 | 2.0.8.0 版本之前，不支持此参数。 | + +### cacheLast + +| 属性 | 说明 | +| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| 适用范围 | 仅服务端适用 | +| 含义 | 是否在内存中缓存子表的最近数据 | +| 取值范围 | 0：关闭
1：缓存子表最近一行数据
2：缓存子表每一列的最近的非 NULL 值
3：同时打开缓存最近行和列功能。（2.1.2.0 版本开始此参数支持 0 ～ 3 的取值范围，在此之前取值只能是 [0, 1]） | +| 缺省值 | 0 | +| 补充说明 | 2.1.2.0 版本之前、2.0.20.7 版本之前在 taos.cfg 文件中不支持此参数。 | + +### minimalTmpDirGB + +| 属性 | 说明 | +| -------- | ------------------------------------------------ | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | 当日志文件夹的磁盘大小小于该值时，停止写临时文件 | +| 单位 | GB | +| 缺省值 | 1.0 | + +### minimalDataDirGB + +| 属性 | 说明 | +| -------- | ------------------------------------------------ | +| 适用范围 | 仅服务端适用 | +| 含义 | 当日志文件夹的磁盘大小小于该值时，停止写时序数据 | +| 单位 | GB | +| 缺省值 | 2.0 | + +### vnodeBak + +| 属性 | 说明 | +| -------- | -------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 删除 vnode 时是否备份 vnode 目录 | +| 取值范围 | 0：否，1：是 | +| 缺省值 | 1 | + +## 集群相关 + +### numOfMnodes + +| 属性 | 说明 | +| -------- | ------------------ | +| 适用范围 | 仅服务端适用 | +| 含义 | 系统中管理节点个数 | +| 缺省值 | 3 | + +### replica + +| 属性 | 说明 | +| -------- | ------------ | +| 适用范围 | 仅服务端适用 | +| 含义 | 副本个数 | +| 取值范围 | 1-3 | +| 缺省值 | 1 | + +### quorum + +| 属性 | 说明 | +| -------- | -------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 多副本环境下指令执行的确认数要求 | +| 取值范围 | 1,2 | +| 缺省值 | 1 | + +### role + +| 属性 | 说明 | +| -------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | dnode 的可选角色 | +| 取值范围 | 0：any（既可作为 mnode，也可分配 vnode）
1：mgmt（只能作为 mnode，不能分配 vnode）
2：dnode（不能作为 mnode，只能分配 vnode） | +| 缺省值 | 0 | + +### balance + +| 属性 | 说明 | +| -------- | ---------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 是否启动负载均衡 | +| 取值范围 | 0，1 | +| 缺省值 | 1 | + +### balanceInterval + +| 属性 | 说明 | +| -------- | ------------------------------------------------ | +| 适用范围 | 仅服务端适用 | +| 含义 | 管理节点在正常运行状态下，检查负载均衡的时间间隔 | +| 单位 | 秒 | +| 取值范围 | 1-30000 | +| 缺省值 | 300 | + +### arbitrator + +| 属性 | 说明 | +| -------- | ------------------------------------------ | +| 适用范围 | 仅服务端适用 | +| 含义 | 系统中裁决器的 endpoint，其格式如 firstEp | +| 缺省值 | 空 | + +## 时间相关 + +### precision + +| 属性 | 说明 | +| -------- | ------------------------------------------------- | +| 适用范围 | 仅服务端 | +| 含义 | 创建数据库时使用的时间精度 | +| 取值范围 | ms: millisecond; us: microsecond ; ns: nanosecond | +| 缺省值 | ms | + +### rpcTimer + +| 属性 | 说明 | +| -------- | -------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | rpc 重试时长 | +| 单位 | 毫秒 | +| 取值范围 | 100-3000 | +| 缺省值 | 300 | + +### rpcMaxTime + +| 属性 | 说明 | +| -------- | -------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | rpc 等待应答最大时长 | +| 单位 | 秒 | +| 取值范围 | 100-7200 | +| 缺省值 | 600 | + +### statusInterval + +| 属性 | 说明 | +| -------- | --------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | dnode 向 mnode 报告状态间隔 | +| 单位 | 秒 | +| 取值范围 | 1-10 | +| 缺省值 | 1 | + +### shellActivityTimer + +| 属性 | 说明 | +| -------- | --------------------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | shell 客户端向 mnode 发送心跳间隔 | +| 单位 | 秒 | +| 取值范围 | 1-120 | +| 缺省值 | 3 | + +### tableMetaKeepTimer + +| 属性 | 说明 | +| -------- | --------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 表的元数据 cache 时长 | +| 单位 | 秒 | +| 取值范围 | 1-8640000 | +| 缺省值 | 7200 | + +### maxTmrCtrl + +| 属性 | 说明 | +| -------- | -------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | 定时器个数 | +| 单位 | 个 | +| 取值范围 | 8-2048 | +| 缺省值 | 512 | + +### offlineThreshold + +| 属性 | 说明 | +| -------- | ------------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | dnode 离线阈值，超过该时间将导致 dnode 离线 | +| 单位 | 秒 | +| 取值范围 | 5-7200000 | +| 缺省值 | 86400\*10（10 天） | + +## 性能调优 + +### numOfThreadsPerCore + +| 属性 | 说明 | +| -------- | ----------------------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | 每个 CPU 核生成的队列消费者线程数量 | +| 缺省值 | 1.0 | + +### ratioOfQueryThreads + +| 属性 | 说明 | +| -------- | ------------------------------------------------------------------------------------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 设置查询线程的最大数量 | +| 取值范围 | 0：表示只有 1 个查询线程
1：表示最大和 CPU 核数相等的查询线程
2：表示最大建立 2 倍 CPU 核数的查询线程。 | +| 缺省值 | 1 | +| 补充说明 | 该值可以为小数，即 0.5 表示最大建立 CPU 核数一半的查询线程。 | + +### maxVgroupsPerDb + +| 属性 | 说明 | +| -------- | ------------------------------------ | +| 适用范围 | 仅服务端适用 | +| 含义 | 每个 DB 中 能够使用的最大 vnode 个数 | +| 取值范围 | 0-8192 | +| 缺省值 | | + +### maxTablesPerVnode + +| 属性 | 说明 | +| -------- | --------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 每个 vnode 中能够创建的最大表个数 | +| 缺省值 | 1000000 | + +### minTablesPerVnode + +| 属性 | 说明 | +| -------- | --------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 每个 vnode 中必须创建表的最小数量 | +| 缺省值 | 1000 | + +### tableIncStepPerVnode + +| 属性 | 说明 | +| -------- | ------------------------------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 每个 vnode 中超过最小表数，i.e. minTablesPerVnode, 后递增步长 | +| 缺省值 | 1000 | + +### maxNumOfOrderedRes + +| 属性 | 说明 | +| -------- | -------------------------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | 支持超级表时间排序允许的最多记录数限制 | +| 缺省值 | 10 万 | + +### mnodeEqualVnodeNum + +| 属性 | 说明 | +| -------- | ------------------------------------ | +| 适用范围 | 仅服务端适用 | +| 含义 | 将一个 mnode 等同于 vnode 消耗的个数 | +| 缺省值 | 4 | + +### numOfCommitThreads + +| 属性 | 说明 | +| -------- | ---------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 设置写入线程的最大数量 | +| 缺省值 | | + +## 压缩相关 + +### comp + +| 属性 | 说明 | +| -------- | ----------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 文件压缩标志位 | +| 取值范围 | 0：关闭，1:一阶段压缩，2:两阶段压缩 | +| 缺省值 | 2 | + +### tsdbMetaCompactRatio + +| 属性 | 说明 | +| -------- | -------------------------------------------------------------- | +| 含义 | tsdb meta 文件中冗余数据超过多少阈值，开启 meta 文件的压缩功能 | +| 取值范围 | 0：不开启，[1-100]：冗余数据比例 | +| 缺省值 | 0 | + +### compressMsgSize + +| 属性 | 说明 | +| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 客户端与服务器之间进行消息通讯过程中，对通讯的消息进行压缩的阈值。如果要压缩消息，建议设置为 64330 字节，即大于 64330 字节的消息体才进行压缩。 | +| 单位 | bytes | +| 取值范围 | `0 `表示对所有的消息均进行压缩 >0: 超过该值的消息才进行压缩 -1: 不压缩 | +| 缺省值 | -1 | + +### compressColData + +| 属性 | 说明 | +| -------- | --------------------------------------------------------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 客户端与服务器之间进行消息通讯过程中，对服务器端查询结果进行列压缩的阈值。 | +| 单位 | bytes | +| 取值范围 | 0: 对所有查询结果均进行压缩 >0: 查询结果中任意列大小超过该值的消息才进行压缩 -1: 不压缩 | +| 缺省值 | -1 | +| 补充说明 | 2.3.0.0 版本新增。 | + +### lossyColumns + +| 属性 | 说明 | +| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| 适用范围 | 服务器端 | +| 含义 | 配置要进行有损压缩的浮点数据类型 | +| 取值范围 | 空字符串：关闭有损压缩
float：只对 float 类型进行有损压缩
double：只对 double 类型进行有损压缩
float \| double：float double 都进行有损压缩 | +| 缺省值 | 空字符串 | +| 补充说明 | 有损压缩默认为关闭状态，只有配置后才生效 | + +### fPrecision + +| 属性 | 说明 | +| -------- | -------------------------------- | +| 适用范围 | 服务器端 | +| 含义 | 设置 float 类型浮点数压缩精度 | +| 取值范围 | 0.1 ~ 0.00000001 | +| 缺省值 | 0.00000001 | +| 补充说明 | 小于此值的浮点数尾数部分将被截取 | + +### dPrecision + +| 属性 | 说明 | +| -------- | -------------------------------- | +| 适用范围 | 服务器端 | +| 含义 | 设置 double 类型浮点数压缩精度 | +| 取值范围 | 0.1 ~ 0.0000000000000001 | +| 缺省值 | 0.0000000000000001 | +| 补充说明 | 小于此值的浮点数尾数部分将被截取 | + +## 连续查询相关 + +### stream + +| 属性 | 说明 | +| -------- | ------------------------------ | +| 适用范围 | 仅服务端适用 | +| 含义 | 是否启用连续查询（流计算功能） | +| 取值范围 | 0：不允许
1：允许 | +| 缺省值 | 1 | + +### minSlidingTime + +| 属性 | 说明 | +| -------- | ----------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 最小滑动窗口时长 | +| 单位 | 毫秒 | +| 取值范围 | 10-1000000 | +| 缺省值 | 10 | +| 补充说明 | 支持 us 补值后，这个值就是 1us 了。 | + +### minIntervalTime + +| 属性 | 说明 | +| -------- | -------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 时间窗口最小值 | +| 单位 | 毫秒 | +| 取值范围 | 1-1000000 | +| 缺省值 | 10 | + +### maxStreamCompDelay + +| 属性 | 说明 | +| -------- | -------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 连续查询启动最大延迟 | +| 单位 | 毫秒 | +| 取值范围 | 10-1000000000 | +| 缺省值 | 20000 | + +### maxFirstStreamCompDelay + +| 属性 | 说明 | +| -------- | -------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 第一次连续查询启动最大延迟 | +| 单位 | 毫秒 | +| 取值范围 | 10-1000000000 | +| 缺省值 | 10000 | + +### retryStreamCompDelay + +| 属性 | 说明 | +| -------- | -------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 连续查询重试等待间隔 | +| 单位 | 毫秒 | +| 取值范围 | 10-1000000000 | +| 缺省值 | 10 | + +### streamCompDelayRatio + +| 属性 | 说明 | +| -------- | ---------------------------------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 连续查询的延迟时间计算系数，实际延迟时间为本参数乘以计算时间窗口 | +| 取值范围 | 0.1-0.9 | +| 缺省值 | 0.1 | + +:::info +为避免多个 stream 同时执行占用太多系统资源，程序中对 stream 的执行时间人为增加了一些随机的延时。
maxFirstStreamCompDelay 是 stream 第一次执行前最少要等待的时间。
streamCompDelayRatio 是延迟时间的计算系数，它乘以查询的 interval 后为延迟时间基准。
maxStreamCompDelay 是延迟时间基准的上限。
实际延迟时间为一个不超过延迟时间基准的随机值。
stream 某次计算失败后需要重试，retryStreamCompDelay 是重试的等待时间基准。
实际重试等待时间为不超过等待时间基准的随机值。 + +::: + +## HTTP 相关 + +:::note +HTTP 服务在 2.4.0.0（不含）以前的版本中由 taosd 提供，在 2.4.0.0 以后（含）由 taosAdapter 提供。 +本节的配置参数仅在 2.4.0.0（不含）以前的版本中生效。如果您使用的是 2.4.0.0（含）及以后的版本请参考[文档](/reference/taosadapter/)。 + +::: + +### http + +| 属性 | 说明 | +| -------- | --------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 服务器内部的 http 服务开关。 | +| 取值范围 | 0：关闭 http 服务， 1：激活 http 服务。 | +| 缺省值 | 1 | + +### httpEnableRecordSql + +| 属性 | 说明 | +| -------- | --------------------------------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 记录通过 RESTFul 接口，产生的 SQL 调用。 | +| 缺省值 | 0 | +| 补充说明 | 生成的文件（httpnote.0/httpnote.1），与服务端日志所在目录相同。 | + +### httpMaxThreads + +| 属性 | 说明 | +| -------- | ------------------------------------------------------------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | RESTFul 接口的线程数。taosAdapter 配置或有不同，请参考相应[文档](/reference/taosadapter/)。 | +| 缺省值 | 2 | + +### restfulRowLimit + +| 属性 | 说明 | +| -------- | ----------------------------------------------------------------------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | RESTFul 接口单次返回的记录条数。taosAdapter 配置或有不同，请参考相应[文档](/reference/taosadapter/)。 | +| 缺省值 | 10240 | +| 补充说明 | 最大 10,000,000 | + +### httpDBNameMandatory + +| 属性 | 说明 | +| -------- | ---------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 是否在 URL 中输入 数据库名称 | +| 取值范围 | 0：不开启，1：开启 | +| 缺省值 | 0 | +| 补充说明 | 2.3 版本新增。 | + +## 日志相关 + +### logDir + +| 属性 | 说明 | +| -------- | -------------------------------------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | 日志文件目录，客户端和服务器的运行日志将写入该目录 | +| 缺省值 | /var/log/taos | + +### minimalLogDirGB + +| 属性 | 说明 | +| -------- | -------------------------------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | 当日志文件夹的磁盘大小小于该值时，停止写日志 | +| 单位 | GB | +| 缺省值 | 1.0 | + +### numOfLogLines + +| 属性 | 说明 | +| -------- | ---------------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | 单个日志文件允许的最大行数。 | +| 缺省值 | 10,000,000 | + +### asyncLog + +| 属性 | 说明 | +| -------- | -------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | 日志写入模式 | +| 取值范围 | 0：同步、1：异步 | +| 缺省值 | 1 | + +### logKeepDays + +| 属性 | 说明 | +| -------- | ----------------------------------------------------------------------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | 日志文件的最长保存时间 | +| 单位 | 天 | +| 缺省值 | 0 | +| 补充说明 | 大于 0 时，日志文件会被重命名为 taosdlog.xxx，其中 xxx 为日志文件最后修改的时间戳。 | + +### debugFlag + +| 属性 | 说明 | +| -------- | ------------------------------------------------------------------------------------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | 运行日志开关 | +| 取值范围 | 131（输出错误和警告日志），135（输出错误、警告和调试日志），143（输出错误、警告、调试和跟踪日志） | +| 缺省值 | 131 或 135（不同模块有不同的默认值） | + +### mDebugFlag + +| 属性 | 说明 | +| -------- | ------------------ | +| 适用范围 | 仅服务端适用 | +| 含义 | 管理模块的日志开关 | +| 取值范围 | 同上 | +| 缺省值 | 135 | + +### dDebugFlag + +| 属性 | 说明 | +| -------- | -------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | dnode 模块的日志开关 | +| 取值范围 | 同上 | +| 缺省值 | 135 | + +### sDebugFlag + +| 属性 | 说明 | +| -------- | -------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | sync 模块的日志开关 | +| 取值范围 | 同上 | +| 缺省值 | 135 | + +### wDebugFlag + +| 属性 | 说明 | +| -------- | -------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | WAL 模块的日志开关 | +| 取值范围 | 同上 | +| 缺省值 | 135 | + +### sdbDebugFlag + +| 属性 | 说明 | +| -------- | -------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | sdb 模块的日志开关 | +| 取值范围 | 同上 | +| 缺省值 | 135 | + +### rpcDebugFlag + +| 属性 | 说明 | +| -------- | -------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | rpc 模块的日志开关 | +| 取值范围 | 同上 | +| 缺省值 | | + +### tmrDebugFlag + +| 属性 | 说明 | +| -------- | -------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | 定时器模块的日志开关 | +| 取值范围 | 同上 | +| 缺省值 | | + +### cDebugFlag + +| 属性 | 说明 | +| -------- | --------------------- | +| 适用范围 | 仅客户端适用 | +| 含义 | client 模块的日志开关 | +| 取值范围 | 同上 | +| 缺省值 | | + +### jniDebugFlag + +| 属性 | 说明 | +| -------- | ------------------ | +| 适用范围 | 仅客户端适用 | +| 含义 | jni 模块的日志开关 | +| 取值范围 | 同上 | +| 缺省值 | | + +### odbcDebugFlag + +| 属性 | 说明 | +| -------- | ------------------- | +| 适用范围 | 仅客户端适用 | +| 含义 | odbc 模块的日志开关 | +| 取值范围 | 同上 | +| 缺省值 | | + +### uDebugFlag + +| 属性 | 说明 | +| -------- | ---------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | 共用功能模块的日志开关 | +| 取值范围 | 同上 | +| 缺省值 | | + +### httpDebugFlag + +| 属性 | 说明 | +| -------- | ------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | http 模块的日志开关 | +| 取值范围 | 同上 | +| 缺省值 | | + +### mqttDebugFlag + +| 属性 | 说明 | +| -------- | ------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | mqtt 模块的日志开关 | +| 取值范围 | 同上 | +| 缺省值 | | + +### monitorDebugFlag + +| 属性 | 说明 | +| -------- | ------------------ | +| 适用范围 | 仅服务端适用 | +| 含义 | 监控模块的日志开关 | +| 取值范围 | 同上 | +| 缺省值 | | + +### qDebugFlag + +| 属性 | 说明 | +| -------- | -------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | 查询模块的日志开关 | +| 取值范围 | 同上 | +| 缺省值 | | + +### vDebugFlag + +| 属性 | 说明 | +| -------- | -------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | vnode 模块的日志开关 | +| 取值范围 | 同上 | +| 缺省值 | | + +### tsdbDebugFlag + +| 属性 | 说明 | +| -------- | ------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | TSDB 模块的日志开关 | +| 取值范围 | 同上 | +| 缺省值 | | + +### cqDebugFlag + +| 属性 | 说明 | +| -------- | ---------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | 连续查询模块的日志开关 | +| 取值范围 | 同上 | +| 缺省值 | | + +## 仅客户端适用 + +### maxSQLLength + +| 属性 | 说明 | +| -------- | --------------------------- | +| 适用范围 | 仅客户端适用 | +| 含义 | 单条 SQL 语句允许的最长限制 | +| 单位 | bytes | +| 取值范围 | 65480-1048576 | +| 缺省值 | 1048576 | + +### tscEnableRecordSql + +| 属性 | 说明 | +| -------- | ----------------------------------------------------------------------------------- | +| 含义 | 是否记录客户端 sql 语句到文件 | +| 取值范围 | 0：否，1：是 | +| 缺省值 | 0 | +| 补充说明 | 生成的文件（tscnote-xxxx.0/tscnote-xxx.1，xxxx 是 pid），与客户端日志所在目录相同。 | + +### maxBinaryDisplayWidth + +| 属性 | 说明 | +| -------- | -------------------------------------------------------------------------- | +| 含义 | Taos shell 中 binary 和 nchar 字段的显示宽度上限，超过此限制的部分将被隐藏 | +| 取值范围 | 5 - | +| 缺省值 | 30 | + +:::info +实际上限按以下规则计算：如果字段值的长度大于 maxBinaryDisplayWidth，则显示上限为 **字段名长度** 和 **maxBinaryDisplayWidth** 的较大者。
否则，上限为 **字段名长度** 和 **字段值长度** 的较大者。
可在 shell 中通过命令 set max_binary_display_width nn 动态修改此选项 + +::: + +### maxWildCardsLength + +| 属性 | 说明 | +| -------- | ------------------------------------------ | +| 含义 | 设定 LIKE 算子的通配符字符串允许的最大长度 | +| 单位 | bytes | +| 取值范围 | 0-16384 | +| 缺省值 | 100 | +| 补充说明 | 2.1.6.1 版本新增。 | + +### clientMerge + +| 属性 | 说明 | +| -------- | ---------------------------- | +| 含义 | 是否允许客户端对写入数据去重 | +| 取值范围 | 0：不开启，1：开启 | +| 缺省值 | 0 | +| 补充说明 | 2.3 版本新增。 | + +### maxRegexStringLen + +| 属性 | 说明 | +| -------- | -------------------------- | +| 含义 | 正则表达式最大允许长度 | +| 取值范围 | 默认值 128，最大长度 16384 | +| 缺省值 | 128 | +| 补充说明 | 2.3 版本新增。 | + +## 其他 + +### enableCoreFile + +| 属性 | 说明 | +| -------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | 是否开启服务 crash 时生成 core 文件 | +| 取值范围 | 0：否，1：是 | +| 缺省值 | 1 | +| 补充说明 | 不同的启动方式，生成 core 文件的目录如下：1、systemctl start taosd 启动：生成的 core 在根目录下
2、手动启动，就在 taosd 执行目录下。 | diff --git a/docs-cn/14-reference/12-directory.md b/docs-cn/14-reference/12-directory.md new file mode 100644 index 0000000000000000000000000000000000000000..f8c8cb4a082f691cf75db9bed3b42d0d6e1bc8a3 --- /dev/null +++ b/docs-cn/14-reference/12-directory.md @@ -0,0 +1,42 @@ +--- +title: 文件目录结构 +description: "TDengine 安装目录说明" +--- + +安装 TDengine 后，默认会在操作系统中生成下列目录或文件： + +| 目录/文件 | 说明 | +| ------------------------- | -------------------------------------------------------------------- | +| /usr/local/taos/bin | TDengine 可执行文件目录。其中的执行文件都会软链接到/usr/bin 目录下。 | +| /usr/local/taos/driver | TDengine 动态链接库目录。会软链接到/usr/lib 目录下。 | +| /usr/local/taos/examples | TDengine 各种语言应用示例目录。 | +| /usr/local/taos/include | TDengine 对外提供的 C 语言接口的头文件。 | +| /etc/taos/taos.cfg | TDengine 默认[配置文件] | +| /var/lib/taos | TDengine 默认数据文件目录。可通过[配置文件]修改位置。 | +| /var/log/taos | TDengine 默认日志文件目录。可通过[配置文件]修改位置。 | + +## 可执行文件 + +TDengine 的所有可执行文件默认存放在 _/usr/local/taos/bin_ 目录下。其中包括： + +- _taosd_：TDengine 服务端可执行文件 +- _taos_：TDengine Shell 可执行文件 +- _taosdump_：数据导入导出工具 +- _taosBenchmark_：TDengine 测试工具 +- _remove.sh_：卸载 TDengine 的脚本，请谨慎执行，链接到/usr/bin 目录下的**rmtaos**命令。会删除 TDengine 的安装目录/usr/local/taos，但会保留/etc/taos、/var/lib/taos、/var/log/taos +- _taosadapter_: 提供 RESTful 服务和接受其他多种软件写入请求的服务端可执行文件 +- _tarbitrator_: 提供双节点集群部署的仲裁功能 +- _run_taosd_and_taosadapter.sh_：同时启动 taosd 和 taosAdapter 的脚本 +- _TDinsight.sh_：用于下载 TDinsight 并安装的脚本 +- _set_core.sh_：用于方便调试设置系统生成 core dump 文件的脚本 +- _taosd-dump-cfg.gdb_：用于方便调试 taosd 的 gdb 执行脚本。 + +:::note +2.4.0.0 版本之后的 taosBenchmark 和 taosdump 需要安装独立安装包 taosTools。 + +::: + +:::tip +您可以通过修改系统配置文件 taos.cfg 来配置不同的数据目录和日志目录。 + +::: diff --git a/docs-cn/14-reference/13-schemaless/13-schemaless.md b/docs-cn/14-reference/13-schemaless/13-schemaless.md new file mode 100644 index 0000000000000000000000000000000000000000..4de310c248d7763690acef80cdca1c50f609d63b --- /dev/null +++ b/docs-cn/14-reference/13-schemaless/13-schemaless.md @@ -0,0 +1,165 @@ +--- +title: Schemaless 写入 +description: 'Schemaless 写入方式，可以免于预先创建超级表/子表的步骤，随着数据写入接口能够自动创建与数据对应的存储结构' +--- + +在物联网应用中，常会采集比较多的数据项，用于实现智能控制、业务分析、设备监控等。由于应用逻辑的版本升级，或者设备自身的硬件调整等原因，数据采集项就有可能比较频繁地出现变动。为了在这种情况下方便地完成数据记录工作，TDengine +从 2.2.0.0 版本开始，提供调用 Schemaless 写入方式，可以免于预先创建超级表/子表的步骤，随着数据写入接口能够自动创建与数据对应的存储结构。并且在必要时，Schemaless +将自动增加必要的数据列，保证用户写入的数据可以被正确存储。 + +无模式写入方式建立的超级表及其对应的子表与通过 SQL 直接建立的超级表和子表完全没有区别，你也可以通过，SQL 语句直接向其中写入数据。需要注意的是，通过无模式写入方式建立的表，其表名是基于标签值按照固定的映射规则生成，所以无法明确地进行表意，缺乏可读性。 + +## 无模式写入行协议 + +TDengine 的无模式写入的行协议兼容 InfluxDB 的 行协议（Line Protocol）、OpenTSDB 的 telnet 行协议、OpenTSDB 的 JSON 格式协议。但是使用这三种协议的时候，需要在 API 中指定输入内容使用解析协议的标准。 + +对于 InfluxDB、OpenTSDB 的标准写入协议请参考各自的文档。下面首先以 InfluxDB 的行协议为基础，介绍 TDengine 扩展的协议内容，允许用户采用更加精细的方式控制（超级表）模式。 + +Schemaless 采用一个字符串来表达一个数据行（可以向写入 API 中一次传入多行字符串来实现多个数据行的批量写入），其格式约定如下： + +```json +measurement,tag_set field_set timestamp +``` + +其中: + +- measurement 将作为数据表名。它与 tag_set 之间使用一个英文逗号来分隔。 +- tag_set 将作为标签数据，其格式形如 `=,=`，也即可以使用英文逗号来分隔多个标签数据。它与 field_set 之间使用一个半角空格来分隔。 +- field_set 将作为普通列数据，其格式形如 `=,=`，同样是使用英文逗号来分隔多个普通列的数据。它与 timestamp 之间使用一个半角空格来分隔。 +- timestamp 即本行数据对应的主键时间戳。 + +tag_set 中的所有的数据自动转化为 nchar 数据类型，并不需要使用双引号（")。 + +在无模式写入数据行协议中，field_set 中的每个数据项都需要对自身的数据类型进行描述。具体来说： + +- 如果两边有英文双引号，表示 BINARY(32) 类型。例如 `"abc"`。 +- 如果两边有英文双引号而且带有 L 前缀，表示 NCHAR(32) 类型。例如 `L"报错信息"`。 +- 对空格、等号（=）、逗号（,）、双引号（"），前面需要使用反斜杠（\）进行转义。（都指的是英文半角符号） +- 数值类型将通过后缀来区分数据类型： + +| **序号** | **后缀** | **映射类型** | **大小(字节)** | +| -------- | -------- | ------------ | -------------- | +| 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 型来处理。 + +例如如下数据行表示：向名为 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 +``` + +需要注意的是，如果描述数据类型后缀时使用了错误的大小写，或者为数据指定的数据类型有误，均可能引发报错提示而导致数据写入失败。 + +## 无模式写入的主要处理逻辑 + +无模式写入按照如下原则来处理行数据： + +1. 将使用如下规则来生成子表名：首先将 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\*” 是固定的前缀，每个通过该映射关系自动生成的表都具有该前缀。 + +2. 如果解析行协议获得的超级表不存在，则会创建这个超级表。 +3. 如果解析行协议获得子表不存在，则 Schemaless 会按照步骤 1 或 2 确定的子表名来创建子表。 +4. 如果数据行中指定的标签列或普通列不存在，则在超级表中增加对应的标签列或普通列（只增不减）。 +5. 如果超级表中存在一些标签列或普通列未在一个数据行中被指定取值，那么这些列的值在这一行中会被置为 + NULL。 +6. 对 BINARY 或 NCHAR 列，如果数据行中所提供值的长度超出了列类型的限制，自动增加该列允许存储的字符长度上限（只增不减），以保证数据的完整保存。 +7. 如果指定的数据子表已经存在，而且本次指定的标签列取值跟已保存的值不一样，那么最新的数据行中的值会覆盖旧的标签列取值。 +8. 整个处理过程中遇到的错误会中断写入过程，并返回错误代码。 + +:::tip +无模式所有的处理逻辑，仍会遵循 TDengine 对数据结构的底层限制，例如每行数据的总长度不能超过 +16k 字节。这方面的具体限制约束请参见 [TAOS SQL 边界限制](/taos-sql/limit) + +::: + +## 时间分辨率识别 + +无模式写入过程中支持三个指定的模式，具体如下 + +| **序号** | **值** | **说明** | +| -------- | ------------------- | ------------------------------- | +| 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 标准操作方式相同），此时会忽略用户指定的时间分辨率。 + +## 数据模式映射规则 + +本节将说明行协议的数据如何映射成为具有模式的数据。每个行协议中数据 measurement 映射为 +超级表名称。tag_set 中的 标签名称为 数据模式中的标签名，field_set 中的名称为列名称。以如下数据为例，说明映射规则： + +```json +st,t1=3,t2=4,t3=t3 c1=3i64,c3="passit",c2=false,c4=4f64 1626006833639000000 +``` + +该行数据映射生成一个超级表： st， 其包含了 3 个类型为 nchar 的标签，分别是：t1, t2, t3。五个数据列，分别是 ts（timestamp），c1 (bigint），c3(binary)，c2 (bool), c4 (bigint）。映射成为如下 SQL 语句： + +```json +create stable st (_ts timestamp, c1 bigint, c2 bool, c3 binary(6), c4 bigint) tags(t1 nchar(1), t2 nchar(1), t3 nchar(2)) +``` + +## 数据模式变更处理 + +本节将说明不同行数据写入情况下，对于数据模式的影响。 + +在使用行协议写入一个明确的标识的字段类型的时候，后续更改该字段的类型定义，会出现明确的数据模式错误，即会触发写入 API 报告错误。如下所示， + +```json +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)。 + +## 写入完整性 + +TDengine 提供数据写入的幂等性保证，即您可以反复调用 API 进行出错数据的写入操作。但是不提供多行数据写入的原子性保证。即在多行数据一批次写入过程中，会出现部分数据写入成功，部分数据写入失败的情况。 + +## 错误码 + +如果是无模式写入过程中的数据本身错误，应用会得到 TSDB_CODE_TSC_LINE_SYNTAX_ERROR +错误信息，该错误信息表明错误发生在写入文本中。其他的错误码与原系统一致，可以通过 +taos_errstr 获取具体的错误原因。 diff --git a/docs-cn/14-reference/13-schemaless/_category_.yml b/docs-cn/14-reference/13-schemaless/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..2e93df8b366a0d60d4af35ff35076b8345a1ad6a --- /dev/null +++ b/docs-cn/14-reference/13-schemaless/_category_.yml @@ -0,0 +1 @@ +label: Schemaless 写入 diff --git a/docs-cn/14-reference/_category_.yml b/docs-cn/14-reference/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..ae861a15ff626b1e0424a28838830702262aa377 --- /dev/null +++ b/docs-cn/14-reference/_category_.yml @@ -0,0 +1 @@ +label: 参考指南 \ No newline at end of file diff --git a/docs-cn/14-reference/_collectd.mdx b/docs-cn/14-reference/_collectd.mdx new file mode 100644 index 0000000000000000000000000000000000000000..af3388f680228cacee3ea1081e3c01faec54e670 --- /dev/null +++ b/docs-cn/14-reference/_collectd.mdx @@ -0,0 +1,85 @@ +### 配置 taosAdapter + +配置 taosAdapter 接收 collectd 数据的方法： + +- 在 taosAdapter 配置文件（默认位置为 /etc/taos/taosadapter.toml）中使能配置项 + +``` +... +[opentsdb_telnet] +enable = true +maxTCPConnections = 250 +tcpKeepAlive = false +dbs = ["opentsdb_telnet", "collectd", "icinga2", "tcollector"] +ports = [6046, 6047, 6048, 6049] +user = "root" +password = "taosdata" +... +``` + +其中 taosAdapter 默认写入的数据库名称为 `collectd`，也可以修改 taosAdapter 配置文件 dbs 项来指定不同的名称。user 和 password 填写实际 TDengine 配置的值。修改过配置文件 taosAdapter 需重新启动。 + +- 也可以使用 taosAdapter 命令行参数或设置环境变量启动的方式，使能 taosAdapter 接收 collectd 数据功能，具体细节请参考 [taosAdapter 的使用手册](/reference/taosadapter) + +### 配置 collectd +# +collectd 使用插件机制可以以多种形式将采集到的监控数据写入到不同的数据存储软件。TDengine 支持直接采集插件和 write_tsdb 插件。 + +#### 配置接收直接采集插件数据 + +修改 collectd 配置文件（默认位置 /etc/collectd/collectd.conf）相关配置项。 + +```text +LoadPlugin network + + Server "" "" + +``` + +其中 填写运行 taosAdapter 的服务器域名或 IP 地址。 填写 taosAdapter 用于接收 collectd 数据的端口（默认为 6045）。 + +示例如下： + +```text +LoadPlugin network + + Server "127.0.0.1" "6045" + +``` + +#### 配置 write_tsdb 插件数据 + +修改 collectd 配置文件（默认位置 /etc/collectd/collectd.conf）相关配置项。 + +```text +LoadPlugin write_tsdb + + + Host "" + Port "" + ... + + +``` + +其中 填写运行 taosAdapter 的服务器域名或 IP 地址。 填写 taosAdapter 用于接收 collectd write_tsdb 插件的数据（默认为 6047）。 + +```text +LoadPlugin write_tsdb + + + Host "127.0.0.1" + Port "6047" + HostTags "status=production" + StoreRates false + AlwaysAppendDS false + + +``` + +然后重启 collectd： + +``` +systemctl restart collectd +``` + diff --git a/docs-cn/14-reference/_icinga2.mdx b/docs-cn/14-reference/_icinga2.mdx new file mode 100644 index 0000000000000000000000000000000000000000..fdb341e264df8f9315ccd51abbc638adef65c06a --- /dev/null +++ b/docs-cn/14-reference/_icinga2.mdx @@ -0,0 +1,44 @@ +### 配置 taosAdapter + +配置 taosAdapter 接收 icinga2 数据的方法： + +- 在 taosAdapter 配置文件（默认位置 /etc/taos/taosadapter.toml）中使能配置项 + +``` +... +[opentsdb_telnet] +enable = true +maxTCPConnections = 250 +tcpKeepAlive = false +dbs = ["opentsdb_telnet", "collectd", "icinga2", "tcollector"] +ports = [6046, 6047, 6048, 6049] +user = "root" +password = "taosdata" +... +``` + +其中 taosAdapter 默认写入的数据库名称为 `icinga2`，也可以修改 taosAdapter 配置文件 dbs 项来指定不同的名称。user 和 password 填写实际 TDengine 配置的值。修改过 taosAdapter 需重新启动。 + +- 也可以使用 taosAdapter 命令行参数或设置环境变量启动的方式，使能 taosAdapter 接收 icinga2 数据功能，具体细节请参考 [taosAdapter 的使用手册](/reference/taosadapter) + +### 配置 icinga2 + +- 使能 icinga2 的 opentsdb-writer（参考链接 https://icinga.com/docs/icinga-2/latest/doc/14-features/#opentsdb-writer） +- 修改配置文件 `/etc/icinga2/features-enabled/opentsdb.conf` 填写 为运行 taosAdapter 的服务器的域名或 IP 地址， 填写 taosAdapter 支持接收 icinga2 数据的相应端口（默认为 6048） + +``` +object OpenTsdbWriter "opentsdb" { + host = "" + port = +} +``` + +示例文件： + +``` +object OpenTsdbWriter "opentsdb" { + host = "127.0.0.1" + port = 6048 +} +``` + diff --git a/docs-cn/14-reference/_prometheus.mdx b/docs-cn/14-reference/_prometheus.mdx new file mode 100644 index 0000000000000000000000000000000000000000..be73d95cbc001727ee1ea60759f37e0a836643c2 --- /dev/null +++ b/docs-cn/14-reference/_prometheus.mdx @@ -0,0 +1,31 @@ +配置 Prometheus 是通过编辑 Prometheus 配置文件 prometheus.yml （默认位置 /etc/prometheus/prometheus.yml）完成的。 + +### 配置第三方数据库地址 + +将其中的 remote_read url 和 remote_write url 指向运行 taosAdapter 服务的服务器域名或 IP 地址，REST 服务端口（taosAdapter 默认使用 6041），以及希望写入 TDengine 的数据库名称，并确保相应的 URL 形式如下： + +- remote_read url : `http://:/prometheus/v1/remote_read/` +- remote_write url : `http://:/prometheus/v1/remote_write/` + +### 配置 Basic 验证 + +- username： +- password： + +### prometheus.yml 文件中 remote_write 和 remote_read 相关部分配置示例 + +```yaml +remote_write: + - url: "http://localhost:6041/prometheus/v1/remote_write/prometheus_data" + basic_auth: + username: root + password: taosdata + +remote_read: + - url: "http://localhost:6041/prometheus/v1/remote_read/prometheus_data" + basic_auth: + username: root + password: taosdata + remote_timeout: 10s + read_recent: true +``` diff --git a/docs-cn/14-reference/_statsd.mdx b/docs-cn/14-reference/_statsd.mdx new file mode 100644 index 0000000000000000000000000000000000000000..b225c44267d7ae32e3845972f683f664e11e9cae --- /dev/null +++ b/docs-cn/14-reference/_statsd.mdx @@ -0,0 +1,55 @@ +### 配置 taosAdapter + +配置 taosAdapter 接收 StatsD 数据的方法： + +- 在 taosAdapter 配置文件（默认位置 /etc/taos/taosadapter.toml）中使能配置项 + +``` +... +[statsd] +enable = true +port = 6044 +db = "statsd" +user = "root" +password = "taosdata" +worker = 10 +gatherInterval = "5s" +protocol = "udp" +maxTCPConnections = 250 +tcpKeepAlive = false +allowPendingMessages = 50000 +deleteCounters = true +deleteGauges = true +deleteSets = true +deleteTimings = true +... +``` + +其中 taosAdapter 默认写入的数据库名称为 `statsd`，也可以修改 taosAdapter 配置文件 db 项来指定不同的名称。user 和 password 填写实际 TDengine 配置的值。修改过配置文件 taosAdapter 需重新启动。 + +- 也可以使用 taosAdapter 命令行参数或设置环境变量启动的方式，使能 taosAdapter 接收 StatsD 数据功能，具体细节请参考 [taosAdapter 的使用手册](/reference/taosadapter) + +### 配置 StatsD + +使用 StatsD 需要下载其[源代码](https://github.com/statsd/statsd)。其配置文件请参考其源代码下载到本地的根目录下的示例文件 `exampleConfig.js` 进行修改。其中 填写运行 taosAdapter 的服务器域名或 IP 地址，请填写 taosAdapter 接收 StatsD 数据的端口（默认为 6044）。 + +``` +backends 部分添加 "./backends/repeater" +repeater 部分添加 { host:'', port: } +``` + +示例配置文件： + +``` +{ +port: 8125 +, backends: ["./backends/repeater"] +, repeater: [{ host: '127.0.0.1', port: 6044}] +} +``` + +增加如下内容后启动 StatsD（假设配置文件修改为 config.js）。 + +``` +node stats.js config.js & +``` diff --git a/docs-cn/14-reference/_tcollector.mdx b/docs-cn/14-reference/_tcollector.mdx new file mode 100644 index 0000000000000000000000000000000000000000..8e51975b512d658e27a53b469d981e1c85a871dc --- /dev/null +++ b/docs-cn/14-reference/_tcollector.mdx @@ -0,0 +1,82 @@ + +### 配置 taosAdapter + +配置 taosAdapter 接收 TCollector 数据的方法： + +- 在 taosAdapter 配置文件（默认位置 /etc/taos/taosadapter.toml）中使能配置项 + +``` +... +[opentsdb_telnet] +enable = true +maxTCPConnections = 250 +tcpKeepAlive = false +dbs = ["opentsdb_telnet", "collectd", "icinga2", "tcollector"] +ports = [6046, 6047, 6048, 6049] +user = "root" +password = "taosdata" +... +``` + +其中 taosAdapter 默认写入的数据库名称为 `tcollector`，也可以修改 taosAdapter 配置文件 dbs 项来指定不同的名称。user 和 password 填写实际 TDengine 配置的值。修改过配置文件 taosAdapter 需重新启动。 + +- 也可以使用 taosAdapter 命令行参数或设置环境变量启动的方式，使能 taosAdapter 接收 tcollector 数据功能，具体细节请参考 [taosAdapter 的使用手册](/reference/taosadapter) + +### 配置 TCollector + +使用 TCollector 需下载其[源代码](https://github.com/OpenTSDB/tcollector)。其配置项在其源代码中。注意：TCollector 各个版本区别较大，这里仅以当前 master 分支最新代码 (git commit: 37ae920) 为例。 + +修改 `collectors/etc/config.py` 和 `tcollector.py` 两个文件中相应内容。将原指向 OpenTSDB 宿主机的地址修改为 taosAdapter 被部署的服务器域名或 IP 地址，修改端口为 taosAdapter 支持 TCollector 使用的相应端口（默认为 6049）。 + +示例为源代码修改内容的 git diff 输出： + +``` +index e7e7a1c..ec3e23c 100644 +--- a/collectors/etc/config.py ++++ b/collectors/etc/config.py +@@ -59,13 +59,13 @@ def get_defaults(): + 'http_password': False, + 'reconnectinterval': 0, + 'http_username': False, +- 'port': 4242, ++ 'port': 6049, + 'pidfile': '/var/run/tcollector.pid', + 'http': False, + 'http_api_path': "api/put", + 'tags': [], + 'remove_inactive_collectors': False, +- 'host': '', ++ 'host': '127.0.0.1', + 'logfile': '/var/log/tcollector.log', + 'cdir': default_cdir, + 'ssl': False, +diff --git a/tcollector.py b/tcollector.py +index 21f9b23..4c71ba2 100755 +--- a/tcollector.py ++++ b/tcollector.py +@@ -64,7 +64,7 @@ ALIVE = True + # exceptions, something is not right and tcollector will shutdown. + # Hopefully some kind of supervising daemon will then restart it. + MAX_UNCAUGHT_EXCEPTIONS = 100 +-DEFAULT_PORT = 4242 ++DEFAULT_PORT = 6049 + MAX_REASONABLE_TIMESTAMP = 2209212000 # Good until Tue 3 Jan 14:00:00 GMT 2040 + # How long to wait for datapoints before assuming + # a collector is dead and restarting it +@@ -943,13 +943,13 @@ def parse_cmdline(argv): + 'http_password': False, + 'reconnectinterval': 0, + 'http_username': False, +- 'port': 4242, ++ 'port': 6049, + 'pidfile': '/var/run/tcollector.pid', + 'http': False, + 'http_api_path': "api/put", + 'tags': [], + 'remove_inactive_collectors': False, +- 'host': '', ++ 'host': '127.0.0.1', + 'logfile': '/var/log/tcollector.log', + 'cdir': default_cdir, + 'ssl': False, +``` diff --git a/docs-cn/14-reference/_telegraf.mdx b/docs-cn/14-reference/_telegraf.mdx new file mode 100644 index 0000000000000000000000000000000000000000..bae46d66062ad7d5bfc2487900c02bd7a19ce4f6 --- /dev/null +++ b/docs-cn/14-reference/_telegraf.mdx @@ -0,0 +1,27 @@ + +在 Telegraf 配置文件（默认位置 /etc/telegraf/telegraf.conf） 增加 outputs.http 输出模块配置： + +``` +[[outputs.http]] + url = "http://:/influxdb/v1/write?db=" + ... + username = "" + password = "" + ... +``` + +其中 请填写运行 taosAdapter 服务的服务器域名或 IP 地址， 请填写 REST 服务的端口（默认为 6041）， 和 请填写当前运行的 TDengine 实际配置， 请填写希望在 TDengine 保存 Telegraf 数据的数据库名。 + +示例如下： + +``` +[[outputs.http]] + url = "http://127.0.0.1:6041/influxdb/v1/write?db=telegraf" + method = "POST" + timeout = "5s" + username = "root" + password = "taosdata" + data_format = "influx" + influx_max_line_bytes = 250 +``` + diff --git a/docs-cn/14-reference/index.md b/docs-cn/14-reference/index.md new file mode 100644 index 0000000000000000000000000000000000000000..f48ce31fcefd2f0d875aee64e7d92490f4e92fcb --- /dev/null +++ b/docs-cn/14-reference/index.md @@ -0,0 +1,12 @@ +--- +title: 参考指南 +--- + +参考指南是对 TDengine 本身、 TDengine 各语言连接器及自带的工具最详细的介绍。 + +```mdx-code-block +import DocCardList from '@theme/DocCardList'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + + +``` \ No newline at end of file diff --git a/docs-cn/14-reference/taosAdapter-architecture.png b/docs-cn/14-reference/taosAdapter-architecture.png new file mode 100644 index 0000000000000000000000000000000000000000..08a9018553aae6f86b42d127b372d0cecfa9bdf8 Binary files /dev/null and b/docs-cn/14-reference/taosAdapter-architecture.png differ diff --git a/docs-cn/20-third-party/01-grafana.mdx b/docs-cn/20-third-party/01-grafana.mdx new file mode 100644 index 0000000000000000000000000000000000000000..9a4c33d8aceb086ff8ba8dca0f38b1bcbf762005 --- /dev/null +++ b/docs-cn/20-third-party/01-grafana.mdx @@ -0,0 +1,105 @@ +--- +sidebar_label: Grafana +title: Grafana +--- + +TDengine 能够与开源数据可视化系统 [Grafana](https://www.grafana.com/) 快速集成搭建数据监测报警系统，整个过程无需任何代码开发，TDengine 中数据表的内容可以在仪表盘(DashBoard)上进行可视化展现。关于 TDengine 插件的使用您可以在[GitHub](https://github.com/taosdata/grafanaplugin/blob/master/README.md)中了解更多。 + +## 前置条件 + +要让 Grafana 能正常添加 TDengine 数据源，需要以下几方面的准备工作。 + +- TDengine 集群已经部署并正常运行 +- taosAdapter 已经安装并正常运行。具体细节请参考 [taosAdapter 的使用手册](/reference/taosadapter) + +## 安装 Grafana + +目前 TDengine 支持 Grafana 7.0 以上的版本。用户可以根据当前的操作系统，到 Grafana 官网下载安装包，并执行安装。下载地址如下：。 + +## 配置 Grafana + +TDengine 的 Grafana 插件托管在 GitHub，可从 下载，当前最新版本为 3.1.4。 + +推荐使用 [`grafana-cli` 命令行工具](https://grafana.com/docs/grafana/latest/administration/cli/) 进行插件安装。 + +```bash +sudo -u grafana grafana-cli \ + --pluginUrl https://github.com/taosdata/grafanaplugin/releases/download/v3.1.7/tdengine-datasource-3.1.7.zip \ + plugins install tdengine-datasource +``` + +或者下载到本地并解压到 Grafana 插件目录。 + +```bash +GF_VERSION=3.1.7 +wget https://github.com/taosdata/grafanaplugin/releases/download/v$GF_VERSION/tdengine-datasource-$GF_VERSION.zip +``` + +以 CentOS 7.2 操作系统为例，将插件包解压到 /var/lib/grafana/plugins 目录下，重新启动 grafana 即可。 + +```bash +sudo unzip tdengine-datasource-$GF_VERSION.zip -d /var/lib/grafana/plugins/ +``` + +:::note +3.1.6 和更早版本未签名，会在 Grafana 7.3+ / 8.x 版本签名检查时失败导致无法加载插件，需要在 grafana.ini 文件中修改配置如下： + +```ini +[plugins] +allow_loading_unsigned_plugins = tdengine-datasource +``` + +::: + +在 Docker 环境下，可以使用如下的环境变量设置自动安装并设置 TDengine 插件： + +```bash +GF_INSTALL_PLUGINS=https://github.com/taosdata/grafanaplugin/releases/download/v3.1.4/tdengine-datasource-3.1.4.zip;tdengine-datasource +GF_PLUGINS_ALLOW_LOADING_UNSIGNED_PLUGINS=tdengine-datasource +``` + +## 使用 Grafana + +### 配置数据源 + +用户可以直接通过 http://localhost:3000 的网址，登录 Grafana 服务器（用户名/密码：admin/admin），通过左侧 `Configuration -> Data Sources` 可以添加数据源，如下图所示： + +![img](/img/connections/add_datasource1.jpg) + +点击 `Add data source` 可进入新增数据源页面，在查询框中输入 TDengine 可选择添加，如下图所示： + +![img](/img/connections/add_datasource2.jpg) + +进入数据源配置页面，按照默认提示修改相应配置即可： + +![img](/img/connections/add_datasource3.jpg) + +- Host： TDengine 集群中提供 REST 服务 （在 2.4 之前由 taosd 提供， 从 2.4 开始由 taosAdapter 提供）的组件所在服务器的 IP 地址与 TDengine REST 服务的端口号(6041)，默认 http://localhost:6041。 +- User：TDengine 用户名。 +- Password：TDengine 用户密码。 + +点击 `Save & Test` 进行测试，成功会有如下提示： + +![img](/img/connections/add_datasource4.jpg) + +### 创建 Dashboard + +回到主界面创建 Dashboard，点击 Add Query 进入面板查询页面： + +![img](/img/connections/create_dashboard1.jpg) + +如上图所示，在 Query 中选中 `TDengine` 数据源，在下方查询框可输入相应 SQL 进行查询，具体说明如下： + +- INPUT SQL：输入要查询的语句（该 SQL 语句的结果集应为两列多行），例如：`select avg(mem_system) from log.dn where ts >= $from and ts < $to interval($interval)` ，其中，from、to 和 interval 为 TDengine 插件的内置变量，表示从 Grafana 插件面板获取的查询范围和时间间隔。除了内置变量外，`也支持可以使用自定义模板变量`。 +- ALIAS BY：可设置当前查询别名。 +- GENERATE SQL： 点击该按钮会自动替换相应变量，并生成最终执行的语句。 + +按照默认提示查询当前 TDengine 部署所在服务器指定间隔系统内存平均使用量如下： + +![img](/img/connections/create_dashboard2.jpg) + +> 关于如何使用 Grafana 创建相应的监测界面以及更多有关使用 Grafana 的信息，请参考 Grafana 官方的[文档](https://grafana.com/docs/)。 + +### 导入 Dashboard + +在 2.3.3.0 及以上版本，您可以导入 TDinsight Dashboard (Grafana Dashboard ID： [15167](https://grafana.com/grafana/dashboards/15167)) 作为 TDengine 集群的监控可视化工具。安装和使用说明请见 [TDinsight 用户手册](/reference/tdinsight/)。 diff --git a/docs-cn/20-third-party/02-prometheus.md b/docs-cn/20-third-party/02-prometheus.md new file mode 100644 index 0000000000000000000000000000000000000000..0fe534b8df263064e5269e1732b69893efd7a79a --- /dev/null +++ b/docs-cn/20-third-party/02-prometheus.md @@ -0,0 +1,89 @@ +--- +sidebar_label: Prometheus +title: Prometheus +--- + +import Prometheus from "../14-reference/_prometheus.mdx" + +Prometheus 是一款流行的开源监控告警系统。Prometheus 于2016年加入了 Cloud Native Computing Foundation （云原生云计算基金会，简称 CNCF），成为继 Kubernetes 之后的第二个托管项目，该项目拥有非常活跃的开发人员和用户社区。 + +Prometheus 提供了 `remote_write` 和 `remote_read` 接口来利用其它数据库产品作为它的存储引擎。为了让 Prometheus 生态圈的用户能够利用 TDengine 的高效写入和查询，TDengine 也提供了对这两个接口的支持。 + +通过适当的配置， Prometheus 的数据可以通过 `remote_write` 接口存储到 TDengine 中，也可以通过 `remote_read` 接口来查询存储在 TDengine 中的数据，充分利用 TDengine 对时序数据的高效存储查询性能和集群处理能力。 + +## 前置条件 + +要将 Prometheus 数据写入 TDengine 需要以下几方面的准备工作。 +- TDengine 集群已经部署并正常运行 +- taosAdapter 已经安装并正常运行。具体细节请参考 [taosAdapter 的使用手册](/reference/taosadapter) +- Prometheus 已经安装。安装 Prometheus 请参考[官方文档](https://prometheus.io/docs/prometheus/latest/installation/) + +## 配置步骤 + + +## 验证方法 + +重启 Prometheus 后可参考以下示例验证从 Prometheus 向 TDengine 写入数据并能够正确读出。 + +### 使用 TDengine CLI 查询写入数据 +``` +taos> show databases; + name | created_time | ntables | vgroups | replica | quorum | days | keep | cache(MB) | blocks | minrows | maxrows | wallevel | fsync | comp | cachelast | precision | update | status | +==================================================================================================================================================================================================================================================================================== + test | 2022-04-12 08:07:58.756 | 1 | 1 | 1 | 1 | 10 | 3650 | 16 | 6 | 100 | 4096 | 1 | 3000 | 2 | 0 | ms | 0 | ready | + log | 2022-04-20 07:19:50.260 | 2 | 1 | 1 | 1 | 10 | 3650 | 16 | 6 | 100 | 4096 | 1 | 3000 | 2 | 0 | ms | 0 | ready | + prometheus_data | 2022-04-20 07:21:09.202 | 158 | 1 | 1 | 1 | 10 | 3650 | 16 | 6 | 100 | 4096 | 1 | 3000 | 2 | 0 | ns | 2 | ready | + db | 2022-04-15 06:37:08.512 | 1 | 1 | 1 | 1 | 10 | 3650 | 16 | 6 | 100 | 4096 | 1 | 3000 | 2 | 0 | ms | 0 | ready | +Query OK, 4 row(s) in set (0.000585s) + +taos> use prometheus_data; +Database changed. + +taos> show stables; + name | created_time | columns | tags | tables | +============================================================================================ + metrics | 2022-04-20 07:21:09.209 | 2 | 1 | 1389 | +Query OK, 1 row(s) in set (0.000487s) + +taos> select * from metrics limit 10; + ts | value | labels | +============================================================================================= + 2022-04-20 07:21:09.193000000 | 0.000024996 | {"__name__":"go_gc_duration... | + 2022-04-20 07:21:14.193000000 | 0.000024996 | {"__name__":"go_gc_duration... | + 2022-04-20 07:21:19.193000000 | 0.000024996 | {"__name__":"go_gc_duration... | + 2022-04-20 07:21:24.193000000 | 0.000024996 | {"__name__":"go_gc_duration... | + 2022-04-20 07:21:29.193000000 | 0.000024996 | {"__name__":"go_gc_duration... | + 2022-04-20 07:21:09.193000000 | 0.000054249 | {"__name__":"go_gc_duration... | + 2022-04-20 07:21:14.193000000 | 0.000054249 | {"__name__":"go_gc_duration... | + 2022-04-20 07:21:19.193000000 | 0.000054249 | {"__name__":"go_gc_duration... | + 2022-04-20 07:21:24.193000000 | 0.000054249 | {"__name__":"go_gc_duration... | + 2022-04-20 07:21:29.193000000 | 0.000054249 | {"__name__":"go_gc_duration... | +Query OK, 10 row(s) in set (0.011146s) +``` + +### 使用 promql-cli 通过 remote_read 从 TDengine 读取数据 + +安装 promql-cli + +``` + go install github.com/nalbury/promql-cli@latest +``` + +在 TDengine 和 taosAdapter 服务运行状态对 Prometheus 数据进行查询 + +``` +ubuntu@shuduo-1804 ~ $ promql-cli --host "http://127.0.0.1:9090" "sum(up) by (job)" +JOB VALUE TIMESTAMP +prometheus 1 2022-04-20T08:05:26Z +node 1 2022-04-20T08:05:26Z +``` + +暂停 taosAdapter 服务后对 Prometheus 数据进行查询 + +``` +ubuntu@shuduo-1804 ~ $ sudo systemctl stop taosadapter.service +ubuntu@shuduo-1804 ~ $ promql-cli --host "http://127.0.0.1:9090" "sum(up) by (job)" +VALUE TIMESTAMP + +``` + diff --git a/docs-cn/20-third-party/03-telegraf.md b/docs-cn/20-third-party/03-telegraf.md new file mode 100644 index 0000000000000000000000000000000000000000..88a69211c0592940d7f75d34c03bcc0593cd74d6 --- /dev/null +++ b/docs-cn/20-third-party/03-telegraf.md @@ -0,0 +1,67 @@ +--- +sidebar_label: Telegraf +title: Telegraf 写入 +--- + +import Telegraf from "../14-reference/_telegraf.mdx" + +Telegraf 是一款十分流行的指标采集开源软件。在数据采集和平台监控系统中，Telegraf 可以采集多种组件的运行信息，而不需要自己手写脚本定时采集，降低数据获取的难度。 + +只需要将 Telegraf 的输出配置增加指向 taosAdapter 对应的 url 并修改若干配置项即可将 Telegraf 的数据写入到 TDengine 中。将 Telegraf 的数据存在到 TDengine 中可以充分利用 TDengine 对时序数据的高效存储查询性能和集群处理能力。 + +## 前置条件 + +要将 Telegraf 数据写入 TDengine 需要以下几方面的准备工作。 +- TDengine 集群已经部署并正常运行 +- taosAdapter 已经安装并正常运行。具体细节请参考 [taosAdapter 的使用手册](/reference/taosadapter) +- Telegraf 已经安装。安装 Telegraf 请参考[官方文档](https://docs.influxdata.com/telegraf/v1.22/install/) + +## 配置步骤 + + +## 验证方法 + +重启 Telegraf 服务： + +``` +sudo systemctl restart telegraf +``` + +使用 TDengine CLI 验证从 Telegraf 向 TDengine 写入数据并能够正确读出： + +``` +taos> show databases; + name | created_time | ntables | vgroups | replica | quorum | days | keep | cache(MB) | blocks | minrows | maxrows | wallevel | fsync | comp | cachelast | precision | update | status | +==================================================================================================================================================================================================================================================================================== + telegraf | 2022-04-20 08:47:53.488 | 22 | 1 | 1 | 1 | 10 | 3650 | 16 | 6 | 100 | 4096 | 1 | 3000 | 2 | 0 | ns | 2 | ready | + log | 2022-04-20 07:19:50.260 | 9 | 1 | 1 | 1 | 10 | 3650 | 16 | 6 | 100 | 4096 | 1 | 3000 | 2 | 0 | ms | 0 | ready | +Query OK, 2 row(s) in set (0.002401s) + +taos> use telegraf; +Database changed. + +taos> show stables; + name | created_time | columns | tags | tables | +============================================================================================ + swap | 2022-04-20 08:47:53.532 | 7 | 1 | 1 | + cpu | 2022-04-20 08:48:03.488 | 11 | 2 | 5 | + system | 2022-04-20 08:47:53.512 | 8 | 1 | 1 | + diskio | 2022-04-20 08:47:53.550 | 12 | 2 | 15 | + kernel | 2022-04-20 08:47:53.503 | 6 | 1 | 1 | + mem | 2022-04-20 08:47:53.521 | 35 | 1 | 1 | + processes | 2022-04-20 08:47:53.555 | 12 | 1 | 1 | + disk | 2022-04-20 08:47:53.541 | 8 | 5 | 2 | +Query OK, 8 row(s) in set (0.000521s) + +taos> select * from telegraf.system limit 10; + ts | load1 | load5 | load15 | n_cpus | n_users | uptime | uptime_format | host +| +============================================================================================================================================================================================================================================= + 2022-04-20 08:47:50.000000000 | 0.000000000 | 0.050000000 | 0.070000000 | 4 | 1 | 5533 | 1:32 | shuduo-1804 +| + 2022-04-20 08:48:00.000000000 | 0.000000000 | 0.050000000 | 0.070000000 | 4 | 1 | 5543 | 1:32 | shuduo-1804 +| + 2022-04-20 08:48:10.000000000 | 0.000000000 | 0.040000000 | 0.070000000 | 4 | 1 | 5553 | 1:32 | shuduo-1804 +| +Query OK, 3 row(s) in set (0.013269s) +``` diff --git a/docs-cn/20-third-party/05-collectd.md b/docs-cn/20-third-party/05-collectd.md new file mode 100644 index 0000000000000000000000000000000000000000..04892fd42e92e962fcccadf626f67c432e78d286 --- /dev/null +++ b/docs-cn/20-third-party/05-collectd.md @@ -0,0 +1,73 @@ +--- +sidebar_label: collectd +title: collectd 写入 +--- + +import CollectD from "../14-reference/_collectd.mdx" + +collectd 是一个用来收集系统性能的守护进程。collectd 提供各种存储方式来存储不同值的机制。它会在系统运行和存储信息时周期性的统计系统的相关统计信息。利用这些信息有助于查找当前系统性能瓶颈和预测系统未来的负载等。 + +只需要将 collectd 的配置指向运行 taosAdapter 的服务器域名（或 IP 地址）和相应端口即可将 collectd 采集的数据写入到 TDengine，可以充分利用 TDengine 对时序数据的高效存储查询性能和集群处理能力。 + +## 前置条件 + +要将 collectd 数据写入 TDengine，需要几方面的准备工作。 +- TDengine 集群已经部署并正常运行 +- taosAdapter 已经安装并正常运行，具体细节请参考[ taosAdapter 的使用手册](/reference/taosadapter) +- collectd 已经安装。安装 collectd 请参考[官方文档](https://collectd.org/download.shtml) + +## 配置步骤 + + +## 验证方法 + +重启 collectd + +``` +sudo systemctl restart collectd +``` + +使用 TDengine CLI 验证从 collectd 向 TDengine 写入数据并能够正确读出： + +``` +taos> show databases; + name | created_time | ntables | vgroups | replica | quorum | days | keep | cache(MB) | blocks | minrows | maxrows | wallevel | fsync | comp | cachelast | precision | update | status | +==================================================================================================================================================================================================================================================================================== + collectd | 2022-04-20 09:27:45.460 | 95 | 1 | 1 | 1 | 10 | 3650 | 16 | 6 | 100 | 4096 | 1 | 3000 | 2 | 0 | ns | 2 | ready | + log | 2022-04-20 07:19:50.260 | 11 | 1 | 1 | 1 | 10 | 3650 | 16 | 6 | 100 | 4096 | 1 | 3000 | 2 | 0 | ms | 0 | ready | +Query OK, 2 row(s) in set (0.003266s) + +taos> use collectd; +Database changed. + +taos> show stables; + name | created_time | columns | tags | tables | +============================================================================================ + load_1 | 2022-04-20 09:27:45.492 | 2 | 2 | 1 | + memory_value | 2022-04-20 09:27:45.463 | 2 | 3 | 6 | + df_value | 2022-04-20 09:27:45.463 | 2 | 4 | 25 | + load_2 | 2022-04-20 09:27:45.501 | 2 | 2 | 1 | + load_0 | 2022-04-20 09:27:45.485 | 2 | 2 | 1 | + interface_1 | 2022-04-20 09:27:45.488 | 2 | 3 | 12 | + irq_value | 2022-04-20 09:27:45.476 | 2 | 3 | 31 | + interface_0 | 2022-04-20 09:27:45.480 | 2 | 3 | 12 | + entropy_value | 2022-04-20 09:27:45.473 | 2 | 2 | 1 | + swap_value | 2022-04-20 09:27:45.477 | 2 | 3 | 5 | +Query OK, 10 row(s) in set (0.002236s) + +taos> select * from collectd.memory_value limit 10; + ts | value | host | type_instance | type | +========================================================================================================================================================= + 2022-04-20 09:27:45.459653462 | 54689792.000000000 | shuduo-1804 | buffered | memory | + 2022-04-20 09:27:55.453168283 | 57212928.000000000 | shuduo-1804 | buffered | memory | + 2022-04-20 09:28:05.453004291 | 57942016.000000000 | shuduo-1804 | buffered | memory | + 2022-04-20 09:27:45.459653462 | 6381330432.000000000 | shuduo-1804 | free | memory | + 2022-04-20 09:27:55.453168283 | 6357643264.000000000 | shuduo-1804 | free | memory | + 2022-04-20 09:28:05.453004291 | 6349987840.000000000 | shuduo-1804 | free | memory | + 2022-04-20 09:27:45.459653462 | 107040768.000000000 | shuduo-1804 | slab_recl | memory | + 2022-04-20 09:27:55.453168283 | 107536384.000000000 | shuduo-1804 | slab_recl | memory | + 2022-04-20 09:28:05.453004291 | 107634688.000000000 | shuduo-1804 | slab_recl | memory | + 2022-04-20 09:27:45.459653462 | 309137408.000000000 | shuduo-1804 | used | memory | +Query OK, 10 row(s) in set (0.010348s) +``` + diff --git a/docs-cn/20-third-party/06-statsd.md b/docs-cn/20-third-party/06-statsd.md new file mode 100644 index 0000000000000000000000000000000000000000..bcbd6c42ae5dd1c83be428797544d254e11a0238 --- /dev/null +++ b/docs-cn/20-third-party/06-statsd.md @@ -0,0 +1,68 @@ +--- +sidebar_label: StatsD +title: StatsD 直接写入 +--- + +import StatsD from "../14-reference/_statsd.mdx" + +StatsD 是汇总和总结应用指标的一个简单的守护进程，近些年来发展迅速，已经变成了一个用于收集应用性能指标的统一的协议。 + +只需要在 StatsD 的配置文件中填写运行 taosAdapter 的服务器域名（或 IP 地址）和相应端口即可将 StatsD 的数据写入到 TDengine 中，可以充分利用 TDengine 对时序数据的高效存储查询性能和集群处理能力。 + +## 前置条件 + +要将 StatsD 数据写入 TDengine 需要以下几方面的准备工作。 +- TDengine 集群已经部署并正常运行 +- taosAdapter 已经安装并正常运行。具体细节请参考 [taosAdapter 的使用手册](/reference/taosadapter) +- StatsD 已经安装。安装 StatsD 请参考[官方文档](https://github.com/statsd/statsd) + +## 配置步骤 + + +## 验证方法 + +运行 StatsD： + +``` +$ node stats.js config.js & +[1] 8546 +$ 20 Apr 09:54:41 - [8546] reading config file: exampleConfig.js +20 Apr 09:54:41 - server is up INFO +``` + +使用 nc 写入测试数据： + +``` +$ echo "foo:1|c" | nc -u -w0 127.0.0.1 8125 +``` + +使用 TDengine CLI 验证从 StatsD 向 TDengine 写入数据并能够正确读出： + +``` +Welcome to the TDengine shell from Linux, Client Version:2.4.0.0 +Copyright (c) 2020 by TAOS Data, Inc. All rights reserved. + +taos> show databases; + name | created_time | ntables | vgroups | replica | quorum | days | keep | cache(MB) | blocks | minrows | maxrows | wallevel | fsync | comp | cachelast | precision | update | status | +==================================================================================================================================================================================================================================================================================== + log | 2022-04-20 07:19:50.260 | 11 | 1 | 1 | 1 | 10 | 3650 | 16 | 6 | 100 | 4096 | 1 | 3000 | 2 | 0 | ms | 0 | ready | + statsd | 2022-04-20 09:54:51.220 | 1 | 1 | 1 | 1 | 10 | 3650 | 16 | 6 | 100 | 4096 | 1 | 3000 | 2 | 0 | ns | 2 | ready | +Query OK, 2 row(s) in set (0.003142s) + +taos> use statsd; +Database changed. + +taos> show stables; + name | created_time | columns | tags | tables | +============================================================================================ + foo | 2022-04-20 09:54:51.234 | 2 | 1 | 1 | +Query OK, 1 row(s) in set (0.002161s) + +taos> select * from foo; + ts | value | metric_type | +======================================================================================= + 2022-04-20 09:54:51.219614235 | 1 | counter | +Query OK, 1 row(s) in set (0.004179s) + +taos> +``` diff --git a/docs-cn/20-third-party/07-icinga2.md b/docs-cn/20-third-party/07-icinga2.md new file mode 100644 index 0000000000000000000000000000000000000000..ed1f1404a730eca5f51e2ff9bbcd54949018f8ea --- /dev/null +++ b/docs-cn/20-third-party/07-icinga2.md @@ -0,0 +1,74 @@ +--- +sidebar_label: icinga2 +title: icinga2 写入 +--- + +import Icinga2 from "../14-reference/_icinga2.mdx" + +icinga2 是一款开源主机、网络监控软件，最初由 Nagios 网络监控应用发展而来。目前，icinga2 遵从 GNU GPL v2 许可协议发行。 + +只需要将 icinga2 的配置修改指向 taosAdapter 对应的服务器和相应端口即可将 icinga2 采集的数据存在到 TDengine 中，可以充分利用 TDengine 对时序数据的高效存储查询性能和集群处理能力。 + +## 前置条件 + +要将 icinga2 数据写入 TDengine 需要以下几方面的准备工作。 +- TDengine 集群已经部署并正常运行 +- taosAdapter 已经安装并正常运行。具体细节请参考[ taosAdapter 的使用手册](/reference/taosadapter) +- icinga2 已经安装。安装 icinga2 请参考[官方文档](https://icinga.com/docs/icinga-2/latest/doc/02-installation/) + +## 配置步骤 + + +## 验证方法 + +重启 taosAdapter： +``` +sudo systemctl restart taosadapter +``` + +重启 icinga2： + +``` +sudo systemctl restart icinga2 +``` + +等待 10 秒左右后，使用 TDengine CLI 查询 TDengine 验证是否创建相应数据库并写入数据： + +``` +taos> show databases; + name | created_time | ntables | vgroups | replica | quorum | days | keep | cache(MB) | blocks | minrows | maxrows | wallevel | fsync | comp | cachelast | precision | update | status | +==================================================================================================================================================================================================================================================================================== + log | 2022-04-20 07:19:50.260 | 11 | 1 | 1 | 1 | 10 | 3650 | 16 | 6 | 100 | 4096 | 1 | 3000 | 2 | 0 | ms | 0 | ready | + icinga2 | 2022-04-20 12:11:39.697 | 13 | 1 | 1 | 1 | 10 | 3650 | 16 | 6 | 100 | 4096 | 1 | 3000 | 2 | 0 | ns | 2 | ready | +Query OK, 2 row(s) in set (0.001867s) + +taos> use icinga2; +Database changed. + +taos> show stables; + name | created_time | columns | tags | tables | +============================================================================================ + icinga.service.users.state_... | 2022-04-20 12:11:39.726 | 2 | 1 | 1 | + icinga.service.users.acknow... | 2022-04-20 12:11:39.756 | 2 | 1 | 1 | + icinga.service.procs.downti... | 2022-04-20 12:11:44.541 | 2 | 1 | 1 | + icinga.service.users.users | 2022-04-20 12:11:39.770 | 2 | 1 | 1 | + icinga.service.procs.procs_min | 2022-04-20 12:11:44.599 | 2 | 1 | 1 | + icinga.service.users.users_min | 2022-04-20 12:11:39.809 | 2 | 1 | 1 | + icinga.check.max_check_atte... | 2022-04-20 12:11:39.847 | 2 | 3 | 2 | + icinga.service.procs.state_... | 2022-04-20 12:11:44.522 | 2 | 1 | 1 | + icinga.service.procs.procs_... | 2022-04-20 12:11:44.576 | 2 | 1 | 1 | + icinga.service.users.users_... | 2022-04-20 12:11:39.796 | 2 | 1 | 1 | + icinga.check.latency | 2022-04-20 12:11:39.869 | 2 | 3 | 2 | + icinga.service.procs.procs_... | 2022-04-20 12:11:44.588 | 2 | 1 | 1 | + icinga.service.users.downti... | 2022-04-20 12:11:39.746 | 2 | 1 | 1 | + icinga.service.users.users_... | 2022-04-20 12:11:39.783 | 2 | 1 | 1 | + icinga.service.users.reachable | 2022-04-20 12:11:39.736 | 2 | 1 | 1 | + icinga.service.procs.procs | 2022-04-20 12:11:44.565 | 2 | 1 | 1 | + icinga.service.procs.acknow... | 2022-04-20 12:11:44.554 | 2 | 1 | 1 | + icinga.service.procs.state | 2022-04-20 12:11:44.509 | 2 | 1 | 1 | + icinga.service.procs.reachable | 2022-04-20 12:11:44.532 | 2 | 1 | 1 | + icinga.check.current_attempt | 2022-04-20 12:11:39.825 | 2 | 3 | 2 | + icinga.check.execution_time | 2022-04-20 12:11:39.898 | 2 | 3 | 2 | + icinga.service.users.state | 2022-04-20 12:11:39.704 | 2 | 1 | 1 | +Query OK, 22 row(s) in set (0.002317s) +``` diff --git a/docs-cn/20-third-party/08-tcollector.md b/docs-cn/20-third-party/08-tcollector.md new file mode 100644 index 0000000000000000000000000000000000000000..a1245e8c27f302d56f88fa382b5f38f9bd49a0aa --- /dev/null +++ b/docs-cn/20-third-party/08-tcollector.md @@ -0,0 +1,67 @@ +--- +sidebar_label: TCollector +title: TCollector 写入 +--- + +import TCollector from "../14-reference/_tcollector.mdx" + +TCollector 是 openTSDB 的一部分，它用来采集客户端日志发送给数据库。 + +只需要将 TCollector 的配置修改指向运行 taosAdapter 的服务器域名（或 IP 地址）和相应端口即可将 TCollector 采集的数据存在到 TDengine 中，可以充分利用 TDengine 对时序数据的高效存储查询性能和集群处理能力。 + +## 前置条件 + +要将 TCollector 数据写入 TDengine 需要以下几方面的准备工作。 +- TDengine 集群已经部署并正常运行 +- taosAdapter 已经安装并正常运行。具体细节请参考 [taosAdapter 的使用手册](/reference/taosadapter) +- TCollector 已经安装。安装 TCollector 请参考[官方文档](http://opentsdb.net/docs/build/html/user_guide/utilities/tcollector.html#installation-of-tcollector) + +## 配置步骤 + + +## 验证方法 + +重启 taosAdapter： + +``` +sudo systemctl restart taosadapter +``` + +手动执行 `sudo ./tcollector.py` + +等待数秒后使用 TDengine CLI 查询 TDengine 是否创建相应数据库并写入数据。 + +``` +taos> show databases; + name | created_time | ntables | vgroups | replica | quorum | days | keep | cache(MB) | blocks | minrows | maxrows | wallevel | fsync | comp | cachelast | precision | update | status | +==================================================================================================================================================================================================================================================================================== + tcollector | 2022-04-20 12:44:49.604 | 88 | 1 | 1 | 1 | 10 | 3650 | 16 | 6 | 100 | 4096 | 1 | 3000 | 2 | 0 | ns | 2 | ready | + log | 2022-04-20 07:19:50.260 | 11 | 1 | 1 | 1 | 10 | 3650 | 16 | 6 | 100 | 4096 | 1 | 3000 | 2 | 0 | ms | 0 | ready | +Query OK, 2 row(s) in set (0.002679s) + +taos> use tcollector; +Database changed. + +taos> show stables; + name | created_time | columns | tags | tables | +============================================================================================ + proc.meminfo.hugepages_rsvd | 2022-04-20 12:44:53.945 | 2 | 1 | 1 | + proc.meminfo.directmap1g | 2022-04-20 12:44:54.110 | 2 | 1 | 1 | + proc.meminfo.vmallocchunk | 2022-04-20 12:44:53.724 | 2 | 1 | 1 | + proc.meminfo.hugepagesize | 2022-04-20 12:44:54.004 | 2 | 1 | 1 | + tcollector.reader.lines_dro... | 2022-04-20 12:44:49.675 | 2 | 1 | 1 | + proc.meminfo.sunreclaim | 2022-04-20 12:44:53.437 | 2 | 1 | 1 | + proc.stat.ctxt | 2022-04-20 12:44:55.363 | 2 | 1 | 1 | + proc.meminfo.swaptotal | 2022-04-20 12:44:53.158 | 2 | 1 | 1 | + proc.uptime.total | 2022-04-20 12:44:52.813 | 2 | 1 | 1 | + tcollector.collector.lines_... | 2022-04-20 12:44:49.895 | 2 | 2 | 51 | + proc.meminfo.vmallocused | 2022-04-20 12:44:53.704 | 2 | 1 | 1 | + proc.meminfo.memavailable | 2022-04-20 12:44:52.939 | 2 | 1 | 1 | + sys.numa.foreign_allocs | 2022-04-20 12:44:57.929 | 2 | 2 | 1 | + proc.meminfo.committed_as | 2022-04-20 12:44:53.639 | 2 | 1 | 1 | + proc.vmstat.pswpin | 2022-04-20 12:44:54.177 | 2 | 1 | 1 | + proc.meminfo.cmafree | 2022-04-20 12:44:53.865 | 2 | 1 | 1 | + proc.meminfo.mapped | 2022-04-20 12:44:53.349 | 2 | 1 | 1 | + proc.vmstat.pgmajfault | 2022-04-20 12:44:54.251 | 2 | 1 | 1 | +... +``` diff --git a/docs-cn/20-third-party/09-emq-broker.md b/docs-cn/20-third-party/09-emq-broker.md new file mode 100644 index 0000000000000000000000000000000000000000..f57ccb20e6517c51b55093d11fa767bef7d0c9a8 --- /dev/null +++ b/docs-cn/20-third-party/09-emq-broker.md @@ -0,0 +1,192 @@ +--- +sidebar_label: EMQX Broker +title: EMQX Broker 写入 +--- + +MQTT 是流行的物联网数据传输协议，[EMQX](https://github.com/emqx/emqx)是一开源的 MQTT Broker 软件，无需任何代码，只需要在 EMQX Dashboard 里使用“规则”做简单配置，即可将 MQTT 的数据直接写入 TDengine。EMQX 支持通过 发送到 Web 服务的方式保存数据到 TDengine，也在企业版上提供原生的 TDengine 驱动实现直接保存。 + +## 前置条件 + +要让 EMQX 能正常添加 TDengine 数据源，需要以下几方面的准备工作。 +- TDengine 集群已经部署并正常运行 +- taosAdapter 已经安装并正常运行。具体细节请参考 [taosAdapter 的使用手册](/reference/taosadapter) +- 如果使用后文介绍的模拟写入程序，需要安装合适版本的 Node.js，推荐安装 v12。 + +## 安装并启动 EMQX + +用户可以根据当前的操作系统，到 EMQX 官网下载安装包，并执行安装。下载地址如下：。安装后使用 `sudo emqx start` 或 `sudo systemctl start emqx` 启动 EMQX 服务。 + +## 在 TDengine 中为接收 MQTT 数据创建相应数据库和表结构 + +### 以 Docker 安装 TDengine 为例 + +```bash + docker exec -it tdengine bash + taos +``` + +### 创建数据库和表 + +```sql + create database test; + use test; + create table: + + CREATE TABLE sensor_data (ts timestamp, temperature float, humidity float, volume float, PM10 float, pm25 float, SO2 float, NO2 float, CO float, sensor_id NCHAR(255), area TINYINT, coll_time timestamp); +``` + +注：表结构以博客[数据传输、存储、展现，EMQX + TDengine 搭建 MQTT 物联网数据可视化平台](https://www.taosdata.com/blog/2020/08/04/1722.html)为例。后续操作均以此博客场景为例进行，请你根据实际应用场景进行修改。 + +## 配置 EMQX 规则 + +由于 EMQX 不同版本配置界面所有不同，这里仅以 v4.4.3 为例，其他版本请参考相应官网文档。 + +### 登录 EMQX Dashboard + +使用浏览器打开网址 http://IP:18083 并登录 EMQX Dashboard。初次安装用户名为 `admin` 密码为：`public` + +![img](./emqx/login-dashboard.png) + +### 创建规则（Rule） + +选择左侧“规则引擎（Rule Engine）”中的“规则（Rule）”并点击“创建（Create）”按钮： + +![img](./emqx/rule-engine.png) + +### 编辑 SQL 字段 + +![img](./emqx/create-rule.png) + +### 新增“动作（action handler）” + +![img](./emqx/add-action-handler.png) + +### 新增“资源（Resource）” + +![img](./emqx/create-resource.png) + +选择“发送数据到 Web 服务“并点击“新建资源”按钮： + +### 编辑“资源（Resource）” + +选择“发送数据到 Web 服务“并填写 请求 URL 为 运行 taosAdapter 的服务器地址和端口（默认为 6041）。其他属性请保持默认值。 + +![img](./emqx/edit-resource.png) + +### 编辑“动作（action）” + +编辑资源配置，增加 Authorization 认证的键/值配对项，相关文档请参考[ TDengine REST API 文档](https://docs.taosdata.com/reference/rest-api/)。在消息体中输入规则引擎替换模板。 + +![img](./emqx/edit-action.png) + +## 编写模拟测试程序 + +```javascript + // mock.js + const mqtt = require('mqtt') + const Mock = require('mockjs') + const EMQX_SERVER = 'mqtt://localhost:1883' + const CLIENT_NUM = 10 + const STEP = 5000 // 模拟采集时间间隔 ms + const AWAIT = 5000 // 每次发送完后休眠时间，防止消息速率过快 ms + const CLIENT_POOL = [] + startMock() + function sleep(timer = 100) { + return new Promise(resolve => { + setTimeout(resolve, timer) + }) + } + async function startMock() { + const now = Date.now() + for (let i = 0; i < CLIENT_NUM; i++) { + const client = await createClient(`mock_client_${i}`) + CLIENT_POOL.push(client) + } + // last 24h every 5s + const last = 24 * 3600 * 1000 + for (let ts = now - last; ts <= now; ts += STEP) { + for (const client of CLIENT_POOL) { + const mockData = generateMockData() + const data = { + ...mockData, + id: client.clientId, + area: 0, + ts, + } + client.publish('sensor/data', JSON.stringify(data)) + } + const dateStr = new Date(ts).toLocaleTimeString() + console.log(`${dateStr} send success.`) + await sleep(AWAIT) + } + console.log(`Done, use ${(Date.now() - now) / 1000}s`) + } + /** + * Init a virtual mqtt client + * @param {string} clientId ClientID + */ + function createClient(clientId) { + return new Promise((resolve, reject) => { + const client = mqtt.connect(EMQX_SERVER, { + clientId, + }) + client.on('connect', () => { + console.log(`client ${clientId} connected`) + resolve(client) + }) + client.on('reconnect', () => { + console.log('reconnect') + }) + client.on('error', (e) => { + console.error(e) + reject(e) + }) + }) + } + /** + * Generate mock data + */ + function generateMockData() { + return { + "temperature": parseFloat(Mock.Random.float(22, 100).toFixed(2)), + "humidity": parseFloat(Mock.Random.float(12, 86).toFixed(2)), + "volume": parseFloat(Mock.Random.float(20, 200).toFixed(2)), + "PM10": parseFloat(Mock.Random.float(0, 300).toFixed(2)), + "pm25": parseFloat(Mock.Random.float(0, 300).toFixed(2)), + "SO2": parseFloat(Mock.Random.float(0, 50).toFixed(2)), + "NO2": parseFloat(Mock.Random.float(0, 50).toFixed(2)), + "CO": parseFloat(Mock.Random.float(0, 50).toFixed(2)), + "area": Mock.Random.integer(0, 20), + "ts": 1596157444170, + } + } +``` + +注意：代码中 CLIENT_NUM 在开始测试中可以先设置一个较小的值，避免硬件性能不能完全处理较大并发客户端数量。 + +![img](./emqx/client-num.png) + +## 执行测试模拟发送 MQTT 数据 + +``` +npm install mqtt mockjs --save --registry=https://registry.npm.taobao.org +node mock.js +``` + +![img](./emqx/run-mock.png) + +## 验证 EMQX 接收到数据 + +在 EMQX Dashboard 规则引擎界面进行刷新，可以看到有多少条记录被正确接收到： + +![img](./emqx/check-rule-matched.png) + +## 验证数据写入到 TDengine + +使用 TDengine CLI 程序登录并查询相应数据库和表，验证数据是否被正确写入到 TDengine 中： + +![img](./emqx/check-result-in-taos.png) + +TDengine 详细使用方法请参考 [TDengine 官方文档](https://docs.taosdata.com/)。 +EMQX 详细使用方法请参考 [EMQX 官方文档](https://www.emqx.io/docs/zh/v4.4/rule/rule-engine.html)。 + diff --git a/docs-cn/20-third-party/10-hive-mq-broker.md b/docs-cn/20-third-party/10-hive-mq-broker.md new file mode 100644 index 0000000000000000000000000000000000000000..f75ed793d6272ae27f92676e2096ef455f638aa6 --- /dev/null +++ b/docs-cn/20-third-party/10-hive-mq-broker.md @@ -0,0 +1,6 @@ +--- +sidebar_label: HiveMQ Broker +title: HiveMQ Broker 写入 +--- + +[HiveMQ](https://www.hivemq.com/) 是一个提供免费个人版和企业版的 MQTT 代理，主要用于企业和新兴的机器到机器 M2M 通讯和内部传输，满足可伸缩性、易管理和安全特性。HiveMQ 提供了开源的插件开发包。可以通过 HiveMQ extension - TDengine 保存数据到 TDengine。详细使用方法请参考 [HiveMQ extension - TDengine 说明文档](https://github.com/huskar-t/hivemq-tdengine-extension/blob/b62a26ecc164a310104df57691691b237e091c89/README.md)。 diff --git a/docs-cn/20-third-party/11-kafka.md b/docs-cn/20-third-party/11-kafka.md new file mode 100644 index 0000000000000000000000000000000000000000..d12d5fab75671d8a1e7356e766d0e8979c6519c2 --- /dev/null +++ b/docs-cn/20-third-party/11-kafka.md @@ -0,0 +1,379 @@ +--- +sidebar_label: Kafka +title: TDengine Kafka Connector 使用教程 +--- + +TDengine Kafka Connector 包含两个插件: TDengine Source Connector 和 TDengine Sink Connector。用户只需提供简单的配置文件，就可以将 Kafka 中指定 topic 的数据（批量或实时）同步到 TDengine， 或将 TDengine 中指定数据库的数据（批量或实时）同步到 Kafka。 + +## 什么是 Kafka Connect？ + +Kafka Connect 是 Apache Kafka 的一个组件，用于使其它系统，比如数据库、云服务、文件系统等能方便地连接到 Kafka。数据既可以通过 Kafka Connect 从其它系统流向 Kafka, 也可以通过 Kafka Connect 从 Kafka 流向其它系统。从其它系统读数据的插件称为 Source Connector, 写数据到其它系统的插件称为 Sink Connector。Source Connector 和 Sink Connector 都不会直接连接 Kafka Broker，Source Connector 把数据转交给 Kafka Connect。Sink Connector 从 Kafka Connect 接收数据。 + +![](kafka/Kafka_Connect.png) + +TDengine Source Connector 用于把数据实时地从 TDengine 读出来发送给 Kafka Connect。TDengine Sink Connector 用于 从 Kafka Connect 接收数据并写入 TDengine。 + +![](kafka/streaming-integration-with-kafka-connect.png) + +## 什么是 Confluent？ + +Confluent 在 Kafka 的基础上增加很多扩展功能。包括： + +1. Schema Registry +2. REST 代理 +3. 非 Java 客户端 +4. 很多打包好的 Kafka Connect 插件 +5. 管理和监控 Kafka 的 GUI —— Confluent 控制中心 + +这些扩展功能有的包含在社区版本的 Confluent 中，有的只有企业版能用。 +![](kafka/confluentPlatform.png) + +Confluent 企业版提供了 `confluent` 命令行工具管理各个组件。 + +## 前置条件 + +运行本教程中示例的前提条件。 + +1. Linux 操作系统 +2. 已安装 Java 8 和 Maven +3. 已安装 Git +4. 已安装并启动 TDengine。如果还没有可参考[安装和卸载](/operation/pkg-install) + +## 安装 Confluent + +Confluent 提供了 Docker 和二进制包两种安装方式。本文仅介绍二进制包方式安装。 + +在任意目录下执行： + +``` +curl -O http://packages.confluent.io/archive/7.1/confluent-7.1.1.tar.gz +tar xzf confluent-7.1.1.tar.gz -C /opt/test +``` + +然后需要把 `$CONFLUENT_HOME/bin` 目录加入 PATH。 + +```title=".profile" +export CONFLUENT_HOME=/opt/confluent-7.1.1 +PATH=$CONFLUENT_HOME/bin +export PATH +``` + +以上脚本可以追加到当前用户的 profile 文件（~/.profile 或 ~/.bash_profile） + +安装完成之后，可以输入`confluent version`做简单验证： + +``` +# confluent version +confluent - Confluent CLI + +Version: v2.6.1 +Git Ref: 6d920590 +Build Date: 2022-02-18T06:14:21Z +Go Version: go1.17.6 (linux/amd64) +Development: false +``` + +## 安装 TDengine Connector 插件 + +### 从源码安装 + +``` +git clone https://github.com:taosdata/kafka-connect-tdengine.git +cd kafka-connect-tdengine +mvn clean package +unzip -d $CONFLUENT_HOME/share/confluent-hub-components/ target/components/packages/taosdata-kafka-connect-tdengine-0.1.0.zip +``` + +以上脚本先 clone 项目源码，然后用 Maven 编译打包。打包完成后在 `target/components/packages/` 目录生成了插件的 zip 包。把这个 zip 包解压到安装插件的路径即可。安装插件的路径在配置文件 `$CONFLUENT_HOME/etc/kafka/connect-standalone.properties` 中。默认的路径为 `$CONFLUENT_HOME/share/confluent-hub-components/`。 + +### 用 confluent-hub 安装 + +[Confluent Hub](https://www.confluent.io/hub) 提供下载 Kafka Connect 插件的服务。在 TDengine Kafka Connector 发布到 Confluent Hub 后可以使用命令工具 `confluent-hub` 安装。 +**TDengine Kafka Connector 目前没有正式发布，不能用这种方式安装**。 + +## 启动 Confluent + +``` +confluent local services start +``` + +:::note +一定要先安装插件再启动 Confluent, 否则会出现找不到类的错误。Kafka Connect 的日志（默认路径: /tmp/confluent.xxxx/connect/logs/connect.log）中会输出成功安装的插件，据此可判断插件是否安装成功。 +::: + +:::tip +若某组件启动失败，可尝试清空数据，重新启动。数据目录在启动时将被打印到控制台，比如 ： + +```title="控制台输出日志" {1} +Using CONFLUENT_CURRENT: /tmp/confluent.106668 +Starting ZooKeeper +ZooKeeper is [UP] +Starting Kafka +Kafka is [UP] +Starting Schema Registry +Schema Registry is [UP] +Starting Kafka REST +Kafka REST is [UP] +Starting Connect +Connect is [UP] +Starting ksqlDB Server +ksqlDB Server is [UP] +Starting Control Center +Control Center is [UP] +``` + +清空数据可执行 `rm -rf /tmp/confluent.106668`。 +::: + +## TDengine Sink Connector 的使用 + +TDengine Sink Connector 的作用是同步指定 topic 的数据到 TDengine。用户无需提前创建数据库和超级表。可手动指定目标数据库的名字（见配置参数 connection.database）， 也可按一定规则生成(见配置参数 connection.database.prefix)。 + +TDengine Sink Connector 内部使用 TDengine [无模式写入接口](/reference/connector/cpp#无模式写入-api)写数据到 TDengine，目前支持三种格式的数据：[InfluxDB 行协议格式](/develop/insert-data/influxdb-line)、 [OpenTSDB Telnet 协议格式](/develop/insert-data/opentsdb-telnet) 和 [OpenTSDB JSON 协议格式](/develop/insert-data/opentsdb-json)。 + +下面的示例将主题 meters 的数据，同步到目标数据库 power。数据格式为 InfluxDB Line 协议格式。 + +### 添加配置文件 + +``` +mkdir ~/test +cd ~/test +vi sink-demo.properties +``` + +sink-demo.properties 内容如下： + +```ini title="sink-demo.properties" +name=tdengine-sink-demo +connector.class=com.taosdata.kafka.connect.sink.TDengineSinkConnector +tasks.max=1 +topics=meters +connection.url=jdbc:TAOS://127.0.0.1:6030 +connection.user=root +connection.password=taosdata +connection.database=power +db.schemaless=line +key.converter=org.apache.kafka.connect.storage.StringConverter +value.converter=org.apache.kafka.connect.storage.StringConverter +``` + +关键配置说明： + +1. `topics=meters` 和 `connection.database=power`, 表示订阅主题 meters 的数据，并写入数据库 power。 +2. `db.schemaless=line`, 表示使用 InfluxDB Line 协议格式的数据。 + +### 创建 Connector 实例 + +``` +confluent local services connect connector load TDengineSinkConnector --config ./sink-demo.properties +``` + +若以上命令执行成功，则有如下输出： + +```json +{ + "name": "TDengineSinkConnector", + "config": { + "connection.database": "power", + "connection.password": "taosdata", + "connection.url": "jdbc:TAOS://127.0.0.1:6030", + "connection.user": "root", + "connector.class": "com.taosdata.kafka.connect.sink.TDengineSinkConnector", + "db.schemaless": "line", + "key.converter": "org.apache.kafka.connect.storage.StringConverter", + "tasks.max": "1", + "topics": "meters", + "value.converter": "org.apache.kafka.connect.storage.StringConverter", + "name": "TDengineSinkConnector" + }, + "tasks": [], + "type": "sink" +} +``` + +### 写入测试数据 + +准备测试数据的文本文件，内容如下： + +```txt title="test-data.txt" +meters,location=Beijing.Haidian,groupid=2 current=11.8,voltage=221,phase=0.28 1648432611249000000 +meters,location=Beijing.Haidian,groupid=2 current=13.4,voltage=223,phase=0.29 1648432611250000000 +meters,location=Beijing.Haidian,groupid=3 current=10.8,voltage=223,phase=0.29 1648432611249000000 +meters,location=Beijing.Haidian,groupid=3 current=11.3,voltage=221,phase=0.35 1648432611250000000 +``` + +使用 kafka-console-producer 向主题 meters 添加测试数据。 + +``` +cat test-data.txt | kafka-console-producer --broker-list localhost:9092 --topic meters +``` + +:::note +如果目标数据库 power 不存在，那么 TDengine Sink Connector 会自动创建数据库。自动创建数据库使用的时间精度为纳秒，这就要求写入数据的时间戳精度也是纳秒。如果写入数据的时间戳精度不是纳秒，将会抛异常。 +::: + +### 验证同步是否成功 + +使用 TDengine CLI 验证同步是否成功。 + +``` +taos> use power; +Database changed. + +taos> select * from meters; + ts | current | voltage | phase | groupid | location | +=============================================================================================================================================================== + 2022-03-28 09:56:51.249000000 | 11.800000000 | 221.000000000 | 0.280000000 | 2 | Beijing.Haidian | + 2022-03-28 09:56:51.250000000 | 13.400000000 | 223.000000000 | 0.290000000 | 2 | Beijing.Haidian | + 2022-03-28 09:56:51.249000000 | 10.800000000 | 223.000000000 | 0.290000000 | 3 | Beijing.Haidian | + 2022-03-28 09:56:51.250000000 | 11.300000000 | 221.000000000 | 0.350000000 | 3 | Beijing.Haidian | +Query OK, 4 row(s) in set (0.004208s) +``` + +若看到了以上数据，则说明同步成功。若没有，请检查 Kafka Connect 的日志。配置参数的详细说明见[配置参考](#配置参考)。 + +## TDengine Source Connector 的使用 + +TDengine Source Connector 的作用是将 TDengine 某个数据库某一时刻之后的数据全部推送到 Kafka。TDengine Source Connector 的实现原理是，先分批拉取历史数据，再用定时查询的策略同步增量数据。同时会监控表的变化，可以自动同步新增的表。如果重启 Kafka Connect, 会从上次中断的位置继续同步。 + +TDengine Source Connector 会将 TDengine 数据表中的数据转换成 [InfluxDB Line 协议格式](/develop/insert-data/influxdb-line/) 或 [OpenTSDB JSON 协议格式](/develop/insert-data/opentsdb-json)， 然后写入 Kafka。 + +下面的示例程序同步数据库 test 中的数据到主题 tdengine-source-test。 + +### 添加配置文件 + +``` +vi source-demo.properties +``` + +输入以下内容： + +```ini title="source-demo.properties" +name=TDengineSourceConnector +connector.class=com.taosdata.kafka.connect.source.TDengineSourceConnector +tasks.max=1 +connection.url=jdbc:TAOS://127.0.0.1:6030 +connection.username=root +connection.password=taosdata +connection.database=test +connection.attempts=3 +connection.backoff.ms=5000 +topic.prefix=tdengine-source- +poll.interval.ms=1000 +fetch.max.rows=100 +out.format=line +key.converter=org.apache.kafka.connect.storage.StringConverter +value.converter=org.apache.kafka.connect.storage.StringConverter +``` + +### 准备测试数据 + +准备生成测试数据的 SQL 文件。 + +```sql title="prepare-source-data.sql" +DROP DATABASE IF EXISTS test; +CREATE DATABASE test; +USE test; +CREATE STABLE meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT); +INSERT INTO d1001 USING meters TAGS(Beijing.Chaoyang, 2) VALUES('2018-10-03 14:38:05.000',10.30000,219,0.31000) d1001 USING meters TAGS(Beijing.Chaoyang, 2) VALUES('2018-10-03 14:38:15.000',12.60000,218,0.33000) d1001 USING meters TAGS(Beijing.Chaoyang, 2) VALUES('2018-10-03 14:38:16.800',12.30000,221,0.31000) d1002 USING meters TAGS(Beijing.Chaoyang, 3) VALUES('2018-10-03 14:38:16.650',10.30000,218,0.25000) d1003 USING meters TAGS(Beijing.Haidian, 2) VALUES('2018-10-03 14:38:05.500',11.80000,221,0.28000) d1003 USING meters TAGS(Beijing.Haidian, 2) VALUES('2018-10-03 14:38:16.600',13.40000,223,0.29000) d1004 USING meters TAGS(Beijing.Haidian, 3) VALUES('2018-10-03 14:38:05.000',10.80000,223,0.29000) d1004 USING meters TAGS(Beijing.Haidian, 3) VALUES('2018-10-03 14:38:06.500',11.50000,221,0.35000); +``` + +使用 TDengine CLI, 执行 SQL 文件。 + +``` +taos -f prepare-source-data.sql +``` + +### 创建 Connector 实例 + +``` +confluent local services connect connector load TDengineSourceConnector --config source-demo.properties +``` + +### 查看 topic 数据 + +使用 kafka-console-consumer 命令行工具监控主题 tdengine-source-test 中的数据。一开始会输出所有历史数据， 往 TDengine 插入两条新的数据之后，kafka-console-consumer 也立即输出了新增的两条数据。 + +``` +kafka-console-consumer --bootstrap-server localhost:9092 --from-beginning --topic tdengine-source-test +``` + +输出： + +``` +...... +meters,location="beijing.chaoyang",groupid=2i32 current=10.3f32,voltage=219i32,phase=0.31f32 1538548685000000000 +meters,location="beijing.chaoyang",groupid=2i32 current=12.6f32,voltage=218i32,phase=0.33f32 1538548695000000000 +...... +``` + +此时会显示所有历史数据。切换到 TDengine CLI， 插入两条新的数据： + +``` +USE test; +INSERT INTO d1001 VALUES (now, 13.3, 229, 0.38); +INSERT INTO d1002 VALUES (now, 16.3, 233, 0.22); +``` + +再切换回 kafka-console-consumer， 此时命令行窗口已经打印出刚插入的 2 条数据。 + +### unload 插件 + +测试完毕之后，用 unload 命令停止已加载的 connector。 + +查看当前活跃的 connector： + +``` +confluent local services connect connector status +``` + +如果按照前述操作，此时应有两个活跃的 connector。使用下面的命令 unload： + +``` +confluent local services connect connector unload TDengineSourceConnector +confluent local services connect connector unload TDengineSourceConnector +``` + +## 配置参考 + +### 通用配置 + +以下配置项对 TDengine Sink Connector 和 TDengine Source Connector 均适用。 + +1. `name`: connector 名称。 +2. `connector.class`: connector 的完整类名， 如: com.taosdata.kafka.connect.sink.TDengineSinkConnector。 +3. `tasks.max`: 最大任务数, 默认 1。 +4. `topics`: 需要同步的 topic 列表， 多个用逗号分隔, 如 `topic1,topic2`。 +5. `connection.url`: TDengine JDBC 连接字符串， 如 `jdbc:TAOS://127.0.0.1:6030`。 +6. `connection.user`： TDengine 用户名， 默认 root。 +7. `connection.password` ：TDengine 用户密码， 默认 taosdata。 +8. `connection.attempts` ：最大尝试连接次数。默认 3。 +9. `connection.backoff.ms` ： 创建连接失败重试时间隔时间，单位为 ms。 默认 5000。 + +### TDengine Sink Connector 特有的配置 + +1. `connection.database`： 目标数据库名。如果指定的数据库不存在会则自动创建。自动建库使用的时间精度为纳秒。默认值为 null。为 null 时目标数据库命名规则参考 `connection.database.prefix` 参数的说明 +2. `connection.database.prefix`： 当 connection.database 为 null 时, 目标数据库的前缀。可以包含占位符 '${topic}'。 比如 kafka_${topic}, 对于主题 'orders' 将写入数据库 'kafka_orders'。 默认 null。当为 null 时，目标数据库的名字和主题的名字是一致的。 +3. `batch.size`: 分批写入每批记录数。当 Sink Connector 一次接收到的数据大于这个值时将分批写入。 +4. `max.retries`: 发生错误时的最大重试次数。默认为 1。 +5. `retry.backoff.ms`: 发送错误时重试的时间间隔。单位毫秒，默认 3000。 +6. `db.schemaless`: 数据格式，必须指定为： line、json、telnet 中的一个。分别代表 InfluxDB 行协议格式、 OpenTSDB JSON 格式、 OpenTSDB Telnet 行协议格式。 + +### TDengine Source Connector 特有的配置 + +1. `connection.database`: 源数据库名称，无缺省值。 +2. `topic.prefix`： 数据导入 kafka 后 topic 名称前缀。 使用 `topic.prefix` + `connection.database` 名称作为完整 topic 名。默认为空字符串 ""。 +3. `timestamp.initial`: 数据同步起始时间。格式为'yyyy-MM-dd HH:mm:ss'。默认 "1970-01-01 00:00:00"。 +4. `poll.interval.ms`: 拉取数据间隔，单位为 ms。默认 1000。 +5. `fetch.max.rows` : 检索数据库时最大检索条数。 默认为 100。 +6. `out.format`: 数据格式。取值 line 或 json。line 表示 InfluxDB Line 协议格式， json 表示 OpenTSDB JSON 格式。默认 line。 + +## 问题反馈 + +https://github.com/taosdata/kafka-connect-tdengine/issues + +## 参考 + +1. https://www.confluent.io/what-is-apache-kafka +2. https://developer.confluent.io/learn-kafka/kafka-connect/intro +3. https://docs.confluent.io/platform/current/platform.html diff --git a/docs-cn/20-third-party/_category_.yml b/docs-cn/20-third-party/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..514d8c19a878d9700bf11cd7f25208278dfa902e --- /dev/null +++ b/docs-cn/20-third-party/_category_.yml @@ -0,0 +1 @@ +label: 第三方工具 \ No newline at end of file diff --git a/docs-cn/20-third-party/_deploytaosadapter.mdx b/docs-cn/20-third-party/_deploytaosadapter.mdx new file mode 100644 index 0000000000000000000000000000000000000000..ec40744c9a4620801e59aadd49996a0b6381f1bc --- /dev/null +++ b/docs-cn/20-third-party/_deploytaosadapter.mdx @@ -0,0 +1,18 @@ +### 部署taosAdapter + +taosAdapter 可以和 TDengine 部署在同一个系统中，也可以分离部署。 + +启动 taosAdapter： + +``` +systemctl start taosadapter +``` + +检查 taosAdapter 的运行状态： + +``` +systemctl status taosadapter +``` + +taosAdapter 详细的配置参数和使用请参考 `taosadapter --help` 命令输出以及 [参考文档](/reference/taosadapter) 。 + diff --git a/docs-cn/20-third-party/emqx/add-action-handler.png b/docs-cn/20-third-party/emqx/add-action-handler.png new file mode 100644 index 0000000000000000000000000000000000000000..97a1f933ecfadfcab399938806d73c5a5ecc6427 Binary files /dev/null and b/docs-cn/20-third-party/emqx/add-action-handler.png differ diff --git a/docs-cn/20-third-party/emqx/check-result-in-taos.png b/docs-cn/20-third-party/emqx/check-result-in-taos.png new file mode 100644 index 0000000000000000000000000000000000000000..c17a5c1ea2b9bbd49263056c8bf09c9aabab07d5 Binary files /dev/null and b/docs-cn/20-third-party/emqx/check-result-in-taos.png differ diff --git a/docs-cn/20-third-party/emqx/check-rule-matched.png b/docs-cn/20-third-party/emqx/check-rule-matched.png new file mode 100644 index 0000000000000000000000000000000000000000..9e9a466946a1afa857e2bbc07b14956dd0f984b6 Binary files /dev/null and b/docs-cn/20-third-party/emqx/check-rule-matched.png differ diff --git a/docs-cn/20-third-party/emqx/client-num.png b/docs-cn/20-third-party/emqx/client-num.png new file mode 100644 index 0000000000000000000000000000000000000000..fff48cbf3b271c367079ddde425b3f9b014062f7 Binary files /dev/null and b/docs-cn/20-third-party/emqx/client-num.png differ diff --git a/docs-cn/20-third-party/emqx/create-resource.png b/docs-cn/20-third-party/emqx/create-resource.png new file mode 100644 index 0000000000000000000000000000000000000000..58da4c391a3692b9f5fa348d952701eab8bcb746 Binary files /dev/null and b/docs-cn/20-third-party/emqx/create-resource.png differ diff --git a/docs-cn/20-third-party/emqx/create-rule.png b/docs-cn/20-third-party/emqx/create-rule.png new file mode 100644 index 0000000000000000000000000000000000000000..73b0b6ee3e6065a142df98abe8c0dbb32b34f89d Binary files /dev/null and b/docs-cn/20-third-party/emqx/create-rule.png differ diff --git a/docs-cn/20-third-party/emqx/edit-action.png b/docs-cn/20-third-party/emqx/edit-action.png new file mode 100644 index 0000000000000000000000000000000000000000..2a43ee369a439cf11cee23c11f25d6a84b26d7dc Binary files /dev/null and b/docs-cn/20-third-party/emqx/edit-action.png differ diff --git a/docs-cn/20-third-party/emqx/edit-resource.png b/docs-cn/20-third-party/emqx/edit-resource.png new file mode 100644 index 0000000000000000000000000000000000000000..0a0b3560044f4ed6e0a8f040b74085a7e8948b1f Binary files /dev/null and b/docs-cn/20-third-party/emqx/edit-resource.png differ diff --git a/docs-cn/20-third-party/emqx/login-dashboard.png b/docs-cn/20-third-party/emqx/login-dashboard.png new file mode 100644 index 0000000000000000000000000000000000000000..d6c5035c98d860faf639ef6611c6719adf80c47b Binary files /dev/null and b/docs-cn/20-third-party/emqx/login-dashboard.png differ diff --git a/docs-cn/20-third-party/emqx/rule-engine.png b/docs-cn/20-third-party/emqx/rule-engine.png new file mode 100644 index 0000000000000000000000000000000000000000..db110a837b024c82ee9d22f02dcd3a9d06abdd55 Binary files /dev/null and b/docs-cn/20-third-party/emqx/rule-engine.png differ diff --git a/docs-cn/20-third-party/emqx/rule-header-key-value.png b/docs-cn/20-third-party/emqx/rule-header-key-value.png new file mode 100644 index 0000000000000000000000000000000000000000..b81b9a9684aa2f98d00b7ec21e5de411fb450312 Binary files /dev/null and b/docs-cn/20-third-party/emqx/rule-header-key-value.png differ diff --git a/docs-cn/20-third-party/emqx/run-mock.png b/docs-cn/20-third-party/emqx/run-mock.png new file mode 100644 index 0000000000000000000000000000000000000000..0da25818575247732d5d3a783aa52cf7ce24662c Binary files /dev/null and b/docs-cn/20-third-party/emqx/run-mock.png differ diff --git a/docs-cn/20-third-party/index.md b/docs-cn/20-third-party/index.md new file mode 100644 index 0000000000000000000000000000000000000000..b493203225c89944759a216f2b75e0afa6ad03ba --- /dev/null +++ b/docs-cn/20-third-party/index.md @@ -0,0 +1,14 @@ +--- +title: 第三方工具 +--- + +TDengine 通过对标准 SQL 命令、常用数据库连接器标准（例如 JDBC）、ORM 以及其他流行时序数据库写入协议（例如 InfluxDB Line Protocol、OpenTSDB JSON、OpenTSDB Telnet 等）的支持可以使 TDengine 非常容易和第三方工具共同使用。 + +对于支持的第三方工具，无需任何代码，你只需要做简单的配置，就可以将 TDengine 与第三方工具无缝集成起来。 + +```mdx-code-block +import DocCardList from '@theme/DocCardList'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + + +``` diff --git a/docs-cn/20-third-party/kafka/Kafka_Connect.png b/docs-cn/20-third-party/kafka/Kafka_Connect.png new file mode 100644 index 0000000000000000000000000000000000000000..f3dc02ea2a743c6e1ae5531e14f820e3adeca29a Binary files /dev/null and b/docs-cn/20-third-party/kafka/Kafka_Connect.png differ diff --git a/docs-cn/20-third-party/kafka/confluentPlatform.png b/docs-cn/20-third-party/kafka/confluentPlatform.png new file mode 100644 index 0000000000000000000000000000000000000000..f8e69f2c7f64d809996b2d1bf1370b67b8030850 Binary files /dev/null and b/docs-cn/20-third-party/kafka/confluentPlatform.png differ diff --git a/docs-cn/20-third-party/kafka/streaming-integration-with-kafka-connect.png b/docs-cn/20-third-party/kafka/streaming-integration-with-kafka-connect.png new file mode 100644 index 0000000000000000000000000000000000000000..26d8a866d706180c900d69bb6f57ca2dff0047dd Binary files /dev/null and b/docs-cn/20-third-party/kafka/streaming-integration-with-kafka-connect.png differ diff --git a/docs-cn/21-tdinternal/01-arch.md b/docs-cn/21-tdinternal/01-arch.md new file mode 100644 index 0000000000000000000000000000000000000000..6f479efc1ad13e27899e7819d194a2df59ed3ad1 --- /dev/null +++ b/docs-cn/21-tdinternal/01-arch.md @@ -0,0 +1,302 @@ +--- +sidebar_label: 整体架构 +title: 整体架构 +--- + +## 集群与基本逻辑单元 + +TDengine 的设计是基于单个硬件、软件系统不可靠，基于任何单台计算机都无法提供足够计算能力和存储能力处理海量数据的假设进行设计的。因此 TDengine 从研发的第一天起，就按照分布式高可靠架构进行设计，是支持水平扩展的，这样任何单台或多台服务器发生硬件故障或软件错误都不影响系统的可用性和可靠性。同时，通过节点虚拟化并辅以自动化负载均衡技术，TDengine 能最高效率地利用异构集群中的计算和存储资源降低硬件投资。 + +### 主要逻辑单元 + +TDengine 分布式架构的逻辑结构图如下： + +![TDengine架构示意图](/img/architecture/structure.png) + +
图 1 TDengine架构示意图
+ +一个完整的 TDengine 系统是运行在一到多个物理节点上的，逻辑上，它包含数据节点（dnode）、TDengine 应用驱动（taosc）以及应用（app）。系统中存在一到多个数据节点，这些数据节点组成一个集群（cluster）。应用通过 taosc 的 API 与 TDengine 集群进行互动。下面对每个逻辑单元进行简要介绍。 + +**物理节点（pnode）：** pnode 是一独立运行、拥有自己的计算、存储和网络能力的计算机，可以是安装有 OS 的物理机、虚拟机或 Docker 容器。物理节点由其配置的 FQDN（Fully Qualified Domain Name）来标识。TDengine 完全依赖 FQDN 来进行网络通讯，如果不了解 FQDN，请看博文[《一篇文章说清楚 TDengine 的 FQDN》](https://www.taosdata.com/blog/2020/09/11/1824.html)。 + +**数据节点（dnode）：** dnode 是 TDengine 服务器侧执行代码 taosd 在物理节点上的一个运行实例，一个工作的系统必须有至少一个数据节点。dnode 包含零到多个逻辑的虚拟节点（vnode），零或者至多一个逻辑的管理节点（mnode）。dnode 在系统中的唯一标识由实例的 End Point（EP）决定。EP 是 dnode 所在物理节点的 FQDN（Fully Qualified Domain Name）和系统所配置的网络端口号（Port）的组合。通过配置不同的端口，一个物理节点（一台物理机、虚拟机或容器）可以运行多个实例，或有多个数据节点。 + +**虚拟节点（vnode）：** 为更好的支持数据分片、负载均衡，防止数据过热或倾斜，数据节点被虚拟化成多个虚拟节点（vnode，图中 V2，V3，V4 等）。每个 vnode 都是一个相对独立的工作单元，是时序数据存储的基本单元，具有独立的运行线程、内存空间与持久化存储的路径。一个 vnode 包含一定数量的表（数据采集点）。当创建一张新表时，系统会检查是否需要创建新的 vnode。一个数据节点上能创建的 vnode 的数量取决于该数据节点所在物理节点的硬件资源。一个 vnode 只属于一个 DB，但一个 DB 可以有多个 vnode。一个 vnode 除存储的时序数据外，也保存有所包含的表的 schema、标签值等。一个虚拟节点由所属的数据节点的 EP，以及所属的 VGroup ID 在系统内唯一标识，由管理节点创建并管理。 + +**管理节点（mnode）：** 一个虚拟的逻辑单元，负责所有数据节点运行状态的监控和维护，以及节点之间的负载均衡（图中 M）。同时，管理节点也负责元数据（包括用户、数据库、表、静态标签等）的存储和管理，因此也称为 Meta Node。TDengine 集群中可配置多个（开源版最多不超过 3 个）mnode，它们自动构建成为一个虚拟管理节点组（图中 M0，M1，M2）。mnode 间采用 master/slave 的机制进行管理，而且采取强一致方式进行数据同步，任何数据更新操作只能在 Master 上进行。mnode 集群的创建由系统自动完成，无需人工干预。每个 dnode 上至多有一个 mnode，由所属的数据节点的 EP 来唯一标识。每个 dnode 通过内部消息交互自动获取整个集群中所有 mnode 所在的 dnode 的 EP。 + +**虚拟节点组（VGroup）：** 不同数据节点上的 vnode 可以组成一个虚拟节点组（vgroup）来保证系统的高可靠。虚拟节点组内采取 master/slave 的方式进行管理。写操作只能在 master vnode 上进行，系统采用异步复制的方式将数据同步到 slave vnode，这样确保了一份数据在多个物理节点上有拷贝。一个 vgroup 里虚拟节点个数就是数据的副本数。如果一个 DB 的副本数为 N，系统必须有至少 N 数据节点。副本数在创建 DB 时通过参数 replica 可以指定，缺省为 1。使用 TDengine 的多副本特性，可以不再需要昂贵的磁盘阵列等存储设备，就可以获得同样的数据高可靠性。虚拟节点组由管理节点创建、管理，并且由管理节点分配一个系统唯一的 ID，VGroup ID。如果两个虚拟节点的 VGroup ID 相同，说明他们属于同一个组，数据互为备份。虚拟节点组里虚拟节点的个数是可以动态改变的，容许只有一个，也就是没有数据复制。VGroup ID 是永远不变的，即使一个虚拟节点组被删除，它的 ID 也不会被收回重复利用。 + +**Taosc** taosc 是 TDengine 给应用提供的驱动程序（driver），负责处理应用与集群的接口交互，提供 C/C++ 语言原生接口，内嵌于 JDBC、C#、Python、Go、Node.js 语言连接库里。应用都是通过 taosc 而不是直接连接集群中的数据节点与整个集群进行交互的。这个模块负责获取并缓存元数据；将插入、查询等请求转发到正确的数据节点；在把结果返回给应用时，还需要负责最后一级的聚合、排序、过滤等操作。对于 JDBC、C/C++、C#、Python、Go、Node.js 接口而言，这个模块是在应用所处的物理节点上运行。同时，为支持全分布式的 RESTful 接口，taosc 在 TDengine 集群的每个 dnode 上都有一运行实例。 + +### 节点之间的通讯 + +**通讯方式：**TDengine 系统的各个数据节点之间，以及应用驱动与各数据节点之间的通讯是通过 TCP/UDP 进行的。因为考虑到物联网场景，数据写入的包一般不大，因此 TDengine 除采用 TCP 做传输之外，还采用 UDP 方式，因为 UDP 更加高效，而且不受连接数的限制。TDengine 实现了自己的超时、重传、确认等机制，以确保 UDP 的可靠传输。对于数据量不到 15K 的数据包，采取 UDP 的方式进行传输，超过 15K 的，或者是查询类的操作，自动采取 TCP 的方式进行传输。同时，TDengine 根据配置和数据包，会自动对数据进行压缩/解压缩，数字签名/认证等处理。对于数据节点之间的数据复制，只采用 TCP 方式进行数据传输。 + +**FQDN 配置：**一个数据节点有一个或多个 FQDN，可以在系统配置文件 taos.cfg 通过参数“fqdn”进行指定，如果没有指定，系统将自动获取计算机的 hostname 作为其 FQDN。如果节点没有配置 FQDN，可以直接将该节点的配置参数 fqdn 设置为它的 IP 地址。但不建议使用 IP，因为 IP 地址可变，一旦变化，将让集群无法正常工作。一个数据节点的 EP（End Point）由 FQDN + Port 组成。采用 FQDN，需要保证 DNS 服务正常工作，或者在节点以及应用所在的节点配置好 hosts 文件。另外，这个参数值的长度需要控制在 96 个字符以内。 + +**端口配置：**一个数据节点对外的端口由 TDengine 的系统配置参数 serverPort 决定，对集群内部通讯的端口是 serverPort+5。为支持多线程高效的处理 UDP 数据，每个对内和对外的 UDP 连接，都需要占用 5 个连续的端口。 + +- 集群内数据节点之间的数据复制操作占用一个 TCP 端口，是 serverPort+10。 +- 集群数据节点对外提供 RESTful 服务占用一个 TCP 端口，是 serverPort+11。 +- 集群内数据节点与 Arbitrator 节点之间通讯占用一个 TCP 端口，是 serverPort+12。 + +因此一个数据节点总的端口范围为 serverPort 到 serverPort+12，总共 13 个 TCP/UDP 端口。使用时，需要确保防火墙将这些端口打开。每个数据节点可以配置不同的 serverPort。详细的端口情况请参见 [TDengine 2.0 端口说明](/train-faq/faq#port) + +**集群对外连接：**TDengine 集群可以容纳单个、多个甚至几千个数据节点。应用只需要向集群中任何一个数据节点发起连接即可，连接需要提供的网络参数是一数据节点的 End Point（FQDN 加配置的端口号）。通过命令行 CLI 启动应用 taos 时，可以通过选项-h 来指定数据节点的 FQDN，-P 来指定其配置的端口号，如果端口不配置，将采用 TDengine 的系统配置参数 serverPort。 + +**集群内部通讯：**各个数据节点之间通过 TCP/UDP 进行连接。一个数据节点启动时，将获取 mnode 所在的 dnode 的 EP 信息，然后与系统中的 mnode 建立起连接，交换信息。获取 mnode 的 EP 信息有三步： + +1. 检查 mnodeEpSet.json 文件是否存在，如果不存在或不能正常打开获得 mnode EP 信息，进入第二步； +2. 检查系统配置文件 taos.cfg，获取节点配置参数 firstEp、secondEp（这两个参数指定的节点可以是不带 mnode 的普通节点，这样的话，节点被连接时会尝试重定向到 mnode 节点），如果不存在或者 taos.cfg 里没有这两个配置参数，或无效，进入第三步； +3. 将自己的 EP 设为 mnode EP，并独立运行起来。 + +获取 mnode EP 列表后，数据节点发起连接，如果连接成功，则成功加入进工作的集群，如果不成功，则尝试 mnode EP 列表中的下一个。如果都尝试了，但连接都仍然失败，则休眠几秒后，再进行尝试。 + +**Mnode 的选择：**TDengine 逻辑上有管理节点，但没有单独的执行代码，服务器侧只有一套执行代码 taosd。那么哪个数据节点会是管理节点呢？这是系统自动决定的，无需任何人工干预。原则如下：一个数据节点启动时，会检查自己的 End Point，并与获取的 mnode EP List 进行比对，如果在其中，该数据节点认为自己应该启动 mnode 模块，成为 mnode。如果自己的 EP 不在 mnode EP List 里，则不启动 mnode 模块。在系统的运行过程中，由于负载均衡、宕机等原因，mnode 有可能迁移至新的 dnode，但一切都是透明的，无需人工干预，配置参数的修改，是 mnode 自己根据资源做出的决定。 + +**新数据节点的加入：**系统有了一个数据节点后，就已经成为一个工作的系统。添加新的节点进集群时，有两个步骤，第一步：使用 TDengine CLI 连接到现有工作的数据节点，然后用命令“CREATE DNODE”将新的数据节点的 End Point 添加进去；第二步：在新的数据节点的系统配置参数文件 taos.cfg 里，将 firstEp，secondEp 参数设置为现有集群中任意两个数据节点的 EP 即可。具体添加的详细步骤请见详细的用户手册。这样就把集群一步一步的建立起来。 + +**重定向：**无论是 dnode 还是 taosc，最先都是要发起与 mnode 的连接，但 mnode 是系统自动创建并维护的，因此对于用户来说，并不知道哪个 dnode 在运行 mnode。TDengine 只要求向系统中任何一个工作的 dnode 发起连接即可。因为任何一个正在运行的 dnode，都维护有目前运行的 mnode EP List。当收到一个来自新启动的 dnode 或 taosc 的连接请求，如果自己不是 mnode，则将 mnode EP List 回复给对方，taosc 或新启动的 dnode 收到这个 list，就重新尝试建立连接。当 mnode EP List 发生改变，通过节点之间的消息交互，各个数据节点就很快获取最新列表，并通知 taosc。 + +### 一个典型的消息流程 + +为解释 vnode、mnode、taosc 和应用之间的关系以及各自扮演的角色，下面对写入数据这个典型操作的流程进行剖析。 + +![TDengine典型的操作流程](/img/architecture/message.png) + +
图 2 TDengine 典型的操作流程
+ +1. 应用通过 JDBC 或其他 API 接口发起插入数据的请求。 +2. taosc 会检查缓存，看是否保存有该表的 meta data。如果有，直接到第 4 步。如果没有，taosc 将向 mnode 发出 get meta-data 请求。 +3. mnode 将该表的 meta-data 返回给 taosc。Meta-data 包含有该表的 schema，而且还有该表所属的 vgroup 信息（vnode ID 以及所在的 dnode 的 End Point，如果副本数为 N，就有 N 组 End Point）。如果 taosc 迟迟得不到 mnode 回应，而且存在多个 mnode，taosc 将向下一个 mnode 发出请求。 +4. taosc 向 master vnode 发起插入请求。 +5. vnode 插入数据后，给 taosc 一个应答，表示插入成功。如果 taosc 迟迟得不到 vnode 的回应，taosc 会认为该节点已经离线。这种情况下，如果被插入的数据库有多个副本，taosc 将向 vgroup 里下一个 vnode 发出插入请求。 +6. taosc 通知 APP，写入成功。 + +对于第二和第三步，taosc 启动时，并不知道 mnode 的 End Point，因此会直接向配置的集群对外服务的 End Point 发起请求。如果接收到该请求的 dnode 并没有配置 mnode，该 dnode 会在回复的消息中告知 mnode EP 列表，这样 taosc 会重新向新的 mnode 的 EP 发出获取 meta-data 的请求。 + +对于第四和第五步，没有缓存的情况下，taosc 无法知道虚拟节点组里谁是 master，就假设第一个 vnodeID 就是 master，向它发出请求。如果接收到请求的 vnode 并不是 master，它会在回复中告知谁是 master，这样 taosc 就向建议的 master vnode 发出请求。一旦得到插入成功的回复，taosc 会缓存 master 节点的信息。 + +上述是插入数据的流程，查询、计算的流程也完全一致。taosc 把这些复杂的流程全部封装屏蔽了，对于应用来说无感知也无需任何特别处理。 + +通过 taosc 缓存机制，只有在第一次对一张表操作时，才需要访问 mnode，因此 mnode 不会成为系统瓶颈。但因为 schema 有可能变化，而且 vgroup 有可能发生改变（比如负载均衡发生），因此 taosc 会定时和 mnode 交互，自动更新缓存。 + +## 存储模型与数据分区、分片 + +### 存储模型 + +TDengine 存储的数据包括采集的时序数据以及库、表相关的元数据、标签数据等，这些数据具体分为三部分： + +- 时序数据：存放于 vnode 里，由 data、head 和 last 三个文件组成，数据量大，查询量取决于应用场景。容许乱序写入，但暂时不支持删除操作，并且仅在 update 参数设置为 1 时允许更新操作。通过采用一个采集点一张表的模型，一个时间段的数据是连续存储，对单张表的写入是简单的追加操作，一次读，可以读到多条记录，这样保证对单个采集点的插入和查询操作，性能达到最优。 +- 标签数据：存放于 vnode 里的 meta 文件，支持增删改查四个标准操作。数据量不大，有 N 张表，就有 N 条记录，因此可以全内存存储。如果标签过滤操作很多，查询将十分频繁，因此 TDengine 支持多核多线程并发查询。只要计算资源足够，即使有数千万张表，过滤结果能毫秒级返回。 +- 元数据：存放于 mnode 里，包含系统节点、用户、DB、Table Schema 等信息，支持增删改查四个标准操作。这部分数据的量不大，可以全内存保存，而且由于客户端有缓存，查询量也不大。因此目前的设计虽是集中式存储管理，但不会构成性能瓶颈。 + +与典型的 NoSQL 存储模型相比，TDengine 将标签数据与时序数据完全分离存储，它具有两大优势： + +- 能够极大地降低标签数据存储的冗余度：一般的 NoSQL 数据库或时序数据库，采用的 K-V 存储，其中的 Key 包含时间戳、设备 ID、各种标签。每条记录都带有这些重复的内容，浪费存储空间。而且如果应用要在历史数据上增加、修改或删除标签，需要遍历数据，重写一遍，操作成本极其昂贵。 +- 能够实现极为高效的多表之间的聚合查询：做多表之间聚合查询时，先把符合标签过滤条件的表查找出来，然后再查找这些表相应的数据块，这样大幅减少要扫描的数据集，从而大幅提高查询效率。而且标签数据采用全内存的结构进行管理和维护，千万级别规模的标签数据查询可以在毫秒级别返回。 + +### 数据分片 + +对于海量的数据管理，为实现水平扩展，一般都需要采取分片（Sharding）分区（Partitioning）策略。TDengine 是通过 vnode 来实现数据分片的，通过一个时间段一个数据文件来实现时序数据分区的。 + +vnode（虚拟数据节点）负责为采集的时序数据提供写入、查询和计算功能。为便于负载均衡、数据恢复、支持异构环境，TDengine 将一个数据节点根据其计算和存储资源切分为多个 vnode。这些 vnode 的管理是 TDengine 自动完成的，对应用完全透明。 + +对于单独一个数据采集点，无论其数据量多大，一个 vnode（或 vgroup，如果副本数大于 1）有足够的计算资源和存储资源来处理（如果每秒生成一条 16 字节的记录，一年产生的原始数据不到 0.5G），因此 TDengine 将一张表（一个数据采集点）的所有数据都存放在一个 vnode 里，而不会让同一个采集点的数据分布到两个或多个 dnode 上。而且一个 vnode 可存储多个数据采集点（表）的数据，一个 vnode 可容纳的表的数目的上限为一百万。设计上，一个 vnode 里所有的表都属于同一个 DB。一个数据节点上，除非特殊配置，一个 DB 拥有的 vnode 数目不会超过系统核的数目。 + +创建 DB 时，系统并不会马上分配资源。但当创建一张表时，系统将看是否有已经分配的 vnode，且该 vnode 是否有空余的表空间，如果有，立即在该有空位的 vnode 创建表。如果没有，系统将从集群中，根据当前的负载情况，在一个 dnode 上创建一新的 vnode，然后创建表。如果 DB 有多个副本，系统不是只创建一个 vnode，而是一个 vgroup（虚拟数据节点组）。系统对 vnode 的数目没有任何限制，仅仅受限于物理节点本身的计算和存储资源。 + +每张表的 meta data（包含 schema，标签等）也存放于 vnode 里，而不是集中存放于 mnode，实际上这是对 Meta 数据的分片，这样便于高效并行的进行标签过滤操作。 + +### 数据分区 + +TDengine 除 vnode 分片之外，还对时序数据按照时间段进行分区。每个数据文件只包含一个时间段的时序数据，时间段的长度由 DB 的配置参数 days 决定。这种按时间段分区的方法还便于高效实现数据的保留策略，只要数据文件超过规定的天数（系统配置参数 keep），将被自动删除。而且不同的时间段可以存放于不同的路径和存储介质，以便于大数据的冷热管理，实现多级存储。 + +总的来说，**TDengine 是通过 vnode 以及时间两个维度，对大数据进行切分**，便于并行高效的管理，实现水平扩展。 + +### 负载均衡 + +每个 dnode 都定时向 mnode（虚拟管理节点）报告其状态（包括硬盘空间、内存大小、CPU、网络、虚拟节点个数等），因此 mnode 了解整个集群的状态。基于整体状态，当 mnode 发现某个 dnode 负载过重，它会将 dnode 上的一个或多个 vnode 挪到其他 dnode。在挪动过程中，对外服务继续进行，数据插入、查询和计算操作都不受影响。 + +如果 mnode 一段时间没有收到 dnode 的状态报告，mnode 会认为这个 dnode 已经离线。如果离线时间超过一定时长（时长由配置参数 offlineThreshold 决定），该 dnode 将被 mnode 强制剔除出集群。该 dnode 上的 vnodes 如果副本数大于 1，系统将自动在其他 dnode 上创建新的副本，以保证数据的副本数。如果该 dnode 上还有 mnode，而且 mnode 的副本数大于 1，系统也将自动在其他 dnode 上创建新的 mnode，以保证 mnode 的副本数。 + +当新的数据节点被添加进集群，因为新的计算和存储被添加进来，系统也将自动启动负载均衡流程。 + +负载均衡过程无需任何人工干预，应用也无需重启，将自动连接新的节点，完全透明。 + +**提示：负载均衡由参数 balance 控制，决定开启/关闭自动负载均衡。** + +## 数据写入与复制流程 + +如果一个数据库有 N 个副本，那一个虚拟节点组就有 N 个虚拟节点，但是只有一个是 master，其他都是 slave。当应用将新的记录写入系统时，只有 master vnode 能接受写的请求。如果 slave vnode 收到写的请求，系统将通知 taosc 需要重新定向。 + +### Master Vnode 写入流程 + +Master Vnode 遵循下面的写入流程： + +![TDengine Master写入流程](/img/architecture/write_master.png) + +
图 3 TDengine Master 写入流程
+ +1. master vnode 收到应用的数据插入请求，验证 OK，进入下一步； +2. 如果系统配置参数 walLevel 大于 0，vnode 将把该请求的原始数据包写入数据库日志文件 WAL。如果 walLevel 设置为 2，而且 fsync 设置为 0，TDengine 还将 WAL 数据立即落盘，以保证即使宕机，也能从数据库日志文件中恢复数据，避免数据的丢失； +3. 如果有多个副本，vnode 将把数据包转发给同一虚拟节点组内的 slave vnodes，该转发包带有数据的版本号（version）； +4. 写入内存，并将记录加入到 skip list； +5. master vnode 返回确认信息给应用，表示写入成功； +6. 如果第 2、3、4 步中任何一步失败，将直接返回错误给应用。 + +### Slave Vnode 写入流程 + +对于 slave vnode，写入流程是： + +![TDengine Slave 写入流程](/img/architecture/write_slave.png) + +
图 4 TDengine Slave 写入流程
+ +1. slave vnode 收到 Master vnode 转发了的数据插入请求。检查 last version 是否与 master 一致，如果一致，进入下一步。如果不一致，需要进入同步状态。 +2. 如果系统配置参数 walLevel 大于 0，vnode 将把该请求的原始数据包写入数据库日志文件 WAL。如果 walLevel 设置为 2，而且 fsync 设置为 0，TDengine 还将 WAL 数据立即落盘，以保证即使宕机，也能从数据库日志文件中恢复数据，避免数据的丢失。 +3. 写入内存，更新内存中的 skip list。 + +与 master vnode 相比，slave vnode 不存在转发环节，也不存在回复确认环节，少了两步。但写内存与 WAL 是完全一样的。 + +### 主从选择 + +Vnode 会保持一个数据版本号（version），对内存数据进行持久化存储时，对该版本号也进行持久化存储。每个数据更新操作，无论是采集的时序数据还是元数据，这个版本号将增加 1。 + +一个 vnode 启动时，角色（master、slave）是不定的，数据是处于未同步状态，它需要与虚拟节点组内其他节点建立 TCP 连接，并互相交换 status，其中包括 version 和自己的角色。通过 status 的交换，系统进入选主流程，规则如下： + +1. 如果只有一个副本，该副本永远就是 master +2. 所有副本都在线时，版本最高的被选为 master +3. 在线的虚拟节点数过半，而且有虚拟节点是 slave 的话，该虚拟节点自动成为 master +4. 对于 2 和 3，如果多个虚拟节点满足成为 master 的要求，那么虚拟节点组的节点列表里，最前面的选为 master + +更多的关于数据复制的流程，请见[《TDengine 2.0 数据复制模块设计》](/tdinternal/replica/)。 + +### 同步复制 + +对于数据一致性要求更高的场景，异步数据复制无法满足要求，因为有极小的概率丢失数据，因此 TDengine 提供同步复制的机制供用户选择。在创建数据库时，除指定副本数 replica 之外，用户还需要指定新的参数 quorum。如果 quorum 大于 1，它表示每次 master 转发给副本时，需要等待 quorum-1 个回复确认，才能通知应用，数据在 slave 已经写入成功。如果在一定的时间内，得不到 quorum-1 个回复确认，master vnode 将返回错误给应用。 + +采用同步复制，系统的性能会有所下降，而且 latency 会增加。因为元数据要强一致，mnode 之间的数据同步缺省就是采用的同步复制。 + +## 缓存与持久化 + +### 缓存 + +TDengine 采用时间驱动缓存管理策略（First-In-First-Out，FIFO），又称为写驱动的缓存管理机制。这种策略有别于读驱动的数据缓存模式（Least-Recent-Used，LRU），直接将最近写入的数据保存在系统的缓存中。当缓存达到临界值的时候，将最早的数据批量写入磁盘。一般意义上来说，对于物联网数据的使用，用户最为关心的是刚产生的数据，即当前状态。TDengine 充分利用这一特性，将最近到达的（当前状态）数据保存在缓存中。 + +TDengine 通过查询函数向用户提供毫秒级的数据获取能力。直接将最近到达的数据保存在缓存中，可以更加快速地响应用户针对最近一条或一批数据的查询分析，整体上提供更快的数据库查询响应能力。从这个意义上来说，**可通过设置合适的配置参数将 TDengine 作为数据缓存来使用，而不需要再部署 Redis 或其他额外的缓存系统**，可有效地简化系统架构，降低运维的成本。需要注意的是，TDengine 重启以后系统的缓存将被清空，之前缓存的数据均会被批量写入磁盘，缓存的数据将不会像专门的 key-value 缓存系统再将之前缓存的数据重新加载到缓存中。 + +每个 vnode 有自己独立的内存，而且由多个固定大小的内存块组成，不同 vnode 之间完全隔离。数据写入时，类似于日志的写法，数据被顺序追加写入内存，但每个 vnode 维护有自己的 skip list，便于迅速查找。当三分之一以上的内存块写满时，启动落盘操作，而且后续写的操作在新的内存块进行。这样，一个 vnode 里有三分之一内存块是保留有最近的数据的，以达到缓存、快速查找的目的。一个 vnode 的内存块的个数由配置参数 blocks 决定，内存块的大小由配置参数 cache 决定。 + +### 持久化存储 + +TDengine 采用数据驱动的方式让缓存中的数据写入硬盘进行持久化存储。当 vnode 中缓存的数据达到一定规模时，为了不阻塞后续数据的写入，TDengine 也会拉起落盘线程将缓存的数据写入持久化存储。TDengine 在数据落盘时会打开新的数据库日志文件，在落盘成功后则会删除老的数据库日志文件，避免日志文件无限制地增长。 + +为充分利用时序数据特点，TDengine 将一个 vnode 保存在持久化存储的数据切分成多个文件，每个文件只保存固定天数的数据，这个天数由系统配置参数 days 决定。切分成多个文件后，给定查询的起止日期，无需任何索引，就可以立即定位需要打开哪些数据文件，大大加快读取速度。 + +对于采集的数据，一般有保留时长，这个时长由系统配置参数 keep 决定。超过这个设置天数的数据文件，将被系统自动删除，释放存储空间。 + +给定 days 与 keep 两个参数，一个典型工作状态的 vnode 中总的数据文件数为：向上取整 `(keep/days)+1` 个。总的数据文件个数不宜过大，也不宜过小。10 到 100 以内合适。基于这个原则，可以设置合理的 days。目前的版本，参数 keep 可以修改，但对于参数 days，一旦设置后，不可修改。 + +在每个数据文件里，一张表的数据是一块一块存储的。一张表可以有一到多个数据文件块。在一个文件块里，数据是列式存储的，占用的是一片连续的存储空间，这样大大提高读取速度。文件块的大小由系统参数 maxRows （每块最大记录条数）决定，缺省值为 4096。这个值不宜过大，也不宜过小。过大，定位具体时间段的数据的搜索时间会变长，影响读取速度；过小，数据块的索引太大，压缩效率偏低，也影响读取速度。 + +每个数据文件（.data 结尾）都有一个对应的索引文件（.head 结尾），该索引文件对每张表都有一数据块的摘要信息，记录了每个数据块在数据文件中的偏移量，数据的起止时间等信息，以帮助系统迅速定位需要查找的数据。每个数据文件还有一对应的 last 文件（.last 结尾），该文件是为防止落盘时数据块碎片化而设计的。如果一张表落盘的记录条数没有达到系统配置参数 minRows（每块最小记录条数），将被先存储到 last 文件，等下次落盘时，新落盘的记录将与 last 文件的记录进行合并，再写入数据文件。 + +数据写入磁盘时，根据系统配置参数 comp 决定是否压缩数据。TDengine 提供了三种压缩选项：无压缩、一阶段压缩和两阶段压缩，分别对应 comp 值为 0、1 和 2 的情况。一阶段压缩根据数据的类型进行了相应的压缩，压缩算法包括 delta-delta 编码、simple 8B 方法、zig-zag 编码、LZ4 等算法。二阶段压缩在一阶段压缩的基础上又用通用压缩算法进行了压缩，压缩率更高。 + +### 多级存储 + +说明：多级存储功能仅企业版支持，从 2.0.16.0 版本开始提供。 + +在默认配置下，TDengine 会将所有数据保存在 /var/lib/taos 目录下，而且每个 vnode 的数据文件保存在该目录下的不同目录。为扩大存储空间，尽量减少文件读取的瓶颈，提高数据吞吐率 TDengine 可通过配置系统参数 dataDir 让多个挂载的硬盘被系统同时使用。 + +除此之外，TDengine 也提供了数据分级存储的功能，将不同时间段的数据存储在挂载的不同介质上的目录里，从而实现不同“热度”的数据存储在不同的存储介质上，充分利用存储，节约成本。比如，最新采集的数据需要经常访问，对硬盘的读取性能要求高，那么用户可以配置将这些数据存储在 SSD 盘上。超过一定期限的数据，查询需求量没有那么高，那么可以存储在相对便宜的 HDD 盘上。 + +多级存储支持 3 级，每级最多可配置 16 个挂载点。 + +TDengine 多级存储配置方式如下（在配置文件/etc/taos/taos.cfg 中）： + +``` +dataDir [path] +``` + +- path: 挂载点的文件夹路径 +- level: 介质存储等级，取值为 0，1，2。 + 0 级存储最新的数据，1 级存储次新的数据，2 级存储最老的数据，省略默认为 0。 + 各级存储之间的数据流向：0 级存储 -> 1 级存储 -> 2 级存储。 + 同一存储等级可挂载多个硬盘，同一存储等级上的数据文件分布在该存储等级的所有硬盘上。 + 需要说明的是，数据在不同级别的存储介质上的移动，是由系统自动完成的，用户无需干预。 +- primary: 是否为主挂载点，0（否）或 1（是），省略默认为 1。 + +在配置中，只允许一个主挂载点的存在（level=0，primary=1），例如采用如下的配置方式： + +``` +dataDir /mnt/data1 0 1 +dataDir /mnt/data2 0 0 +dataDir /mnt/data3 1 0 +dataDir /mnt/data4 1 0 +dataDir /mnt/data5 2 0 +dataDir /mnt/data6 2 0 +``` + +:::note + +1. 多级存储不允许跨级配置，合法的配置方案有：仅 0 级，仅 0 级+ 1 级，以及 0 级+ 1 级+ 2 级。而不允许只配置 level=0 和 level=2，而不配置 level=1。 +2. 禁止手动移除使用中的挂载盘，挂载盘目前不支持非本地的网络盘。 +3. 多级存储目前不支持删除已经挂载的硬盘的功能。 + +::: + +## 数据查询 + +TDengine 提供了多种多样针对表和超级表的查询处理功能，除了常规的聚合查询之外，还提供针对时序数据的窗口查询、统计聚合等功能。TDengine 的查询处理需要客户端、vnode、mnode 节点协同完成。 + +### 单表查询 + +SQL 语句的解析和校验工作在客户端完成。解析 SQL 语句并生成抽象语法树（Abstract Syntax Tree，AST），然后对其进行校验和检查。以及向管理节点（mnode）请求查询中指定表的元数据信息（table metadata）。 + +根据元数据信息中的 End Point 信息，将查询请求序列化后发送到该表所在的数据节点（dnode）。dnode 接收到查询请求后，识别出该查询请求指向的虚拟节点（vnode），将消息转发到 vnode 的查询执行队列。vnode 的查询执行线程建立基础的查询执行环境，并立即返回该查询请求，同时开始执行该查询。 + +客户端在获取查询结果的时候，dnode 的查询执行队列中的工作线程会等待 vnode 执行线程执行完成，才能将查询结果返回到请求的客户端。 + +### 按时间轴聚合、降采样、插值 + +时序数据有别于普通数据的显著特征是每条记录均具有时间戳，因此针对具有时间戳的数据在时间轴上进行聚合是不同于普通数据库的重要功能。从这点上来看，与流计算引擎的窗口查询有相似的地方。 + +在 TDengine 中引入关键词 interval 来进行时间轴上固定长度时间窗口的切分，并按照时间窗口对数据进行聚合，对窗口范围内的数据按需进行聚合。例如： + +```sql +SELECT COUNT(*) FROM d1001 INTERVAL(1h); +``` + +针对 d1001 设备采集的数据，按照 1 小时的时间窗口返回每小时存储的记录数量。 + +在需要连续获得查询结果的应用场景下，如果给定的时间区间存在数据缺失，会导致该区间数据结果也丢失。TDengine 提供策略针对时间轴聚合计算的结果进行插值，通过使用关键词 fill 就能够对时间轴聚合结果进行插值。例如： + +```sql +SELECT COUNT(*) FROM d1001 WHERE ts >= '2017-7-14 00:00:00' AND ts < '2017-7-14 23:59:59' INTERVAL(1h) FILL(PREV); +``` + +针对 d1001 设备采集数据统计每小时记录数，如果某一个小时不存在数据，则返回之前一个小时的统计数据。TDengine 提供前向插值（prev）、线性插值（linear）、空值填充（NULL）、特定值填充（value）。 + +### 多表聚合查询 + +TDengine 对每个数据采集点单独建表，但在实际应用中经常需要对不同的采集点数据进行聚合。为高效的进行聚合操作，TDengine 引入超级表（STable）的概念。超级表用来代表一特定类型的数据采集点，它是包含多张表的表集合，集合里每张表的模式（schema）完全一致，但每张表都带有自己的静态标签，标签可以有多个，可以随时增加、删除和修改。应用可通过指定标签的过滤条件，对一个 STable 下的全部或部分表进行聚合或统计操作，这样大大简化应用的开发。其具体流程如下图所示： + +![多表聚合查询原理图](/img/architecture/multi_tables.png) + +
图 5 多表聚合查询原理图
+ +1. 应用将一个查询条件发往系统； +2. taosc 将超级表的名字发往 meta node（管理节点）； +3. 管理节点将超级表所拥有的 vnode 列表发回 taosc； +4. taosc 将计算的请求连同标签过滤条件发往这些 vnode 对应的多个数据节点； +5. 每个 vnode 先在内存里查找出自己节点里符合标签过滤条件的表的集合，然后扫描存储的时序数据，完成相应的聚合计算，将结果返回给 taosc； +6. taosc 将多个数据节点返回的结果做最后的聚合，将其返回给应用。 + +由于 TDengine 在 vnode 内将标签数据与时序数据分离存储，通过在内存里过滤标签数据，先找到需要参与聚合操作的表的集合，将需要扫描的数据集大幅减少，大幅提升聚合计算速度。同时，由于数据分布在多个 vnode/dnode，聚合计算操作在多个 vnode 里并发进行，又进一步提升了聚合的速度。 对普通表的聚合函数以及绝大部分操作都适用于超级表，语法完全一样，细节请看 TAOS SQL。 + +### 预计算 + +为有效提升查询处理的性能，针对物联网数据的不可更改的特点，在数据块头部记录该数据块中存储数据的统计信息：包括最大值、最小值、和。我们称之为预计算单元。如果查询处理涉及整个数据块的全部数据，直接使用预计算结果，完全不需要读取数据块的内容。由于预计算数据量远小于磁盘上存储的数据块数据的大小，对于磁盘 I/O 为瓶颈的查询处理，使用预计算结果可以极大地减小读取 I/O 压力，加速查询处理的流程。预计算机制与 PostgreSQL 的索引 BRIN（block range index）有异曲同工之妙。 diff --git a/docs-cn/21-tdinternal/02-replica.md b/docs-cn/21-tdinternal/02-replica.md new file mode 100644 index 0000000000000000000000000000000000000000..6a384b982d22956dd514d8df05dc827ca6f8b729 --- /dev/null +++ b/docs-cn/21-tdinternal/02-replica.md @@ -0,0 +1,256 @@ +--- +sidebar_label: 数据复制模块设计 +title: 数据复制模块设计 +--- + +## 数据复制概述 + +数据复制(Replication)是指同一份数据在多个物理地点保存。它的目的是防止数据丢失，提高系统的高可用性(High Availability)，而且通过应用访问多个副本，提升数据查询性能。 + +在高可靠的大数据系统里，数据复制是必不可少的一大功能。数据复制又分为实时复制与非实时复制。实时复制是指任何数据的更新(包括数据的增加、删除、修改）操作，会被实时的复制到所有副本，这样任何一台机器宕机或网络出现故障，整个系统还能提供最新的数据，保证系统的正常工作。而非实时复制，是指传统的数据备份操作，按照固定的时间周期，将一份数据全量或增量复制到其他地方。如果主节点宕机，副本是很大可能没有最新数据，因此在有些场景是无法满足要求的。 + +TDengine面向的是物联网场景，需要支持数据的实时复制，来最大程度保证系统的可靠性。实时复制有两种方式，一种是异步复制，一种是同步复制。异步复制(Asynchronous Replication)是指数据由Master转发给Slave后，Master并不需要等待Slave回复确认，这种方式效率高，但有极小的概率会丢失数据。同步复制是指Master将数据转发给Slave后，需要等待Slave的回复确认，才会通知应用写入成功，这种方式效率偏低，但能保证数据绝不丢失。 + +数据复制是与数据存储（写入、读取）密切相关的，但两者又是相对独立，可以完全脱耦的。在TDengine系统中，有两种不同类型的数据，一种是时序数据，由TSDB模块负责；一种是元数据(Meta Data), 由MNODE负责。这两种性质不同的数据都需要同步功能。数据复制模块通过不同的实例启动配置参数，为这两种类型数据都提供同步功能。 + +在阅读本文之前，请先阅读《[TDengine 2.0 整体架构](/tdinternal/arch/)》，了解TDengine的集群设计和基本概念 + +特别注明：本文中提到数据更新操作包括数据的增加、删除与修改。 + +## 基本概念和定义 + +TDengine里存在vnode, mnode, vnode用来存储时序数据，mnode用来存储元数据。但从同步数据复制的模块来看，两者没有本质的区别，因此本文里的虚拟节点不仅包括vnode, 也包括mnode, vgroup也指mnode group, 除非特别注明。 + +**版本(version)**： + +一个虚拟节点组里多个虚拟节点互为备份，来保证数据的有效与可靠，是依靠虚拟节点组的数据版本号来维持的。TDengine2.0设计里，对于版本的定义如下：客户端发起增加、删除、修改的流程，无论是一条记录还是多条，只要是在一个请求里，这个数据更新请求被TDengine的一个虚拟节点收到后，经过合法性检查后，可以被写入系统时，就会被分配一个版本号。这个版本号在一个虚拟节点里从1开始，是单调连续递增的。无论这条记录是采集的时序数据还是meta data, 一样处理。当Master转发一个写入请求到slave时，必须带上版本号。一个虚拟节点将一数据更新请求写入WAL时，需要带上版本号。 + +不同虚拟节点组的数据版本号是完全独立的，互不相干的。版本号本质上是数据更新记录的transaction ID，但用来标识数据集的版本。 + +**角色(role)：** + +一个虚拟节点可以是master, slave, unsynced或offline状态。 + +- master： 具有最新的数据，容许客户端往里写入数据，一个虚拟节点组，至多一个master. +- slave：与master是同步的，但不容许客户端往里写入数据，根据配置，可以容许客户端对其进行查询。 +- unsynced: 节点处于非同步状态，比如虚拟节点刚启动、或与其他虚拟节点的连接出现故障等。处于该状态时，该虚拟节点既不能提供写入，也不能提供查询服务。 +- offline: 由于宕机或网络原因，无法访问到某虚拟节点时，其他虚拟节点将该虚拟节点标为离线。但请注意，该虚拟节点本身的状态可能是unsynced或其他，但不会是离线。 + +**Quorum:** + +指数据写入成功所需要的确认数。对于异步复制，quorum设为1，具有master角色的虚拟节点自己确认即可。对于同步复制，需要至少大于等于2。原则上，Quorum >=1 并且 Quorum <= replication(副本数）。这个参数在启动一个同步模块实例时需要提供。 + +**WAL：** + +TDengine的WAL(Write Ahead Log)与cassandra的commit log, mySQL的bin log, Postgres的WAL没本质区别。没有写入数据库文件，还保存在内存的数据都会先存在WAL。当数据已经成功写入数据库数据文件，相应的WAL会被删除。但需要特别指明的是，在TDengine系统里，有几点： + +- 每个虚拟节点有自己独立的wal +- WAL里包含而且仅仅包含来自客户端的数据更新操作，每个更新操作都会被打上一个版本号 + +**复制实例：** + +复制模块只是一可执行的代码，复制实例是指正在运行的复制模块的一个实例，一个节点里，可以存在多个实例。原则上，一个节点有多少虚拟节点，就可以启动多少实例。对于副本数为1的场景，应用可以决定是否需要启动同步实例。应用启动一个同步模块的实例时，需要提供的就是虚拟节点组的配置信息，包括： + +- 虚拟节点个数，即replication number +- 各虚拟节点所在节点的信息，包括node的end point +- quorum, 需要的数据写入成功的确认数 +- 虚拟节点的初始版本号 + +## 数据复制模块的基本工作原理 + +TDengine采取的是Master-Slave模式进行同步，与流行的RAFT一致性算法比较一致。总结下来，有几点： + +1. 一个vgroup里有一到多个虚拟节点，每个虚拟节点都有自己的角色 +2. 客户端只能向角色是master的虚拟节点发起数据更新操作，因为master具有最新版本的数据，如果向非Master发起数据更新操作，会直接收到错误 +3. 客户端可以向master, 也可以向角色是Slave的虚拟节点发起查询操作，但不能对unsynced的虚拟节点发起任何操作 +4. 如果master不存在，这个vgroup是不能对外提供数据更新和查询服务的 +5. master收到客户端的数据更新操作时，会将其转发给slave节点 +6. 一个虚拟节点的版本号比master低的时候，会发起数据恢复流程，成功后，才会成为slave + +数据实时复制有三个主要流程：选主、数据转发、数据恢复。后续做详细讨论。 + +## 虚拟节点之间的网络连接 + +虚拟节点之间通过TCP进行连接，节点之间的状态交换、数据包的转发都是通过这个TCP连接(peerFd)进行。为避免竞争，两个虚拟节点之间的TCP连接，总是由IP地址(UINT32)小的节点作为TCP客户端发起。一旦TCP连接被中断，虚拟节点能通过TCP socket自动检测到，将对方标为offline。如果监测到任何错误（比如数据恢复流程），虚拟节点将主动重置该连接。 + +一旦作为客户端的节点连接不成或中断，它将周期性的每隔一秒钟去试图去连接一次。因为TCP本身有心跳机制，虚拟节点之间不再另行提供心跳。 + +如果一个unsynced节点要发起数据恢复流程，它与Master将建立起专有的TCP连接(syncFd)。数据恢复完成后，该连接会被关闭。而且为限制资源的使用，系统只容许一定数量(配置参数tsMaxSyncNum)的数据恢复的socket存在。如果超过这个数字，系统会将新的数据恢复请求延后处理。 + +任意一个节点，无论有多少虚拟节点，都会启动而且只会启动一个TCP server, 来接受来自其他虚拟节点的上述两类TCP的连接请求。当TCP socket建立起来，客户端侧发送的消息体里会带有vgId（全局唯一的vgroup ID), TCP 服务器侧会检查该vgId是否已经在该节点启动运行。如果已经启动运行，就接受其请求。如果不存在，就直接将连接请求关闭。在TDengine代码里，mnode group的vgId设置为1。 + +## 选主流程 + +当同一组的两个虚拟节点之间(vnode A, vnode B)建立连接后，他们互换status消息。status消息里包含本地存储的同一虚拟节点组内所有虚拟节点的role和version。 + +如果一个虚拟节点(vnode A)检测到与同一虚拟节点组内另外一虚拟节点（vnode B）的连接中断，vnode A将立即把vnode B的role设置为offline。无论是接收到另外一虚拟节点发来的status消息，还是检测与另外一虚拟节点的连接中断，该虚拟节点都将进入状态处理流程。状态处理流程的规则如下： + +1. 如果检测到在线的节点数没有超过一半，则将自己的状态设置为unsynced. +2. 如果在线的虚拟节点数超过一半，会检查master节点是否存在，如果存在，则会决定是否将自己状态改为slave或启动数据恢复流程。 +3. 如果master不存在，则会检查自己保存的各虚拟节点的状态信息与从另一节点接收到的是否一致，如果一致，说明节点组里状态已经稳定一致，则会触发选举流程。如果不一致，说明状态还没趋于一致，即使master不存在，也不进行选主。由于要求状态信息一致才进行选举，每个虚拟节点根据同样的信息，会选出同一个虚拟节点做master，无需投票表决。 +4. 自己的状态是根据规则自己决定并修改的，并不需要其他节点同意，包括成为master。一个节点无权修改其他节点的状态。 +5. 如果一个虚拟节点检测到自己或其他虚拟节点的role发生改变，该节点会广播它自己保存的各个虚拟节点的状态信息（role和version)。 + +具体的流程图如下： + +![replica-master.png](/img/architecture/replica-master.png) + +选择Master的具体规则如下： + +1. 如果只有一个副本，该副本永远就是master +2. 所有副本都在线时，版本最高的被选为master +3. 在线的虚拟节点数过半，而且有虚拟节点是slave的话，该虚拟节点自动成为master +4. 对于2和3，如果多个虚拟节点满足成为master的要求，那么虚拟节点组的节点列表里，最前面的选为master + +按照上面的规则，如果所有虚拟节点都是unsynced(比如全部重启），只有所有虚拟节点上线，才能选出master，该虚拟节点组才能开始对外提供服务。当一个虚拟节点的role发生改变时，sync模块回通过回调函数notifyRole通知应用。 + +## 数据转发流程 + +如果vnode A是master, vnode B是slave, vnode A能接受客户端的写请求，而vnode B不能。当vnode A收到写的请求后，遵循下面的流程： + +![replica-forward.png](/img/architecture/replica-forward.png) + +1. 应用对写请求做基本的合法性检查，通过，则给该请求包打上一个版本号(version, 单调递增） +2. 应用将打上版本号的写请求封装一个WAL Head, 写入WAL(Write Ahead Log) +3. 应用调用API syncForwardToPeer，如果vnode B是slave状态，sync模块将包含WAL Head的数据包通过Forward消息发送给vnode B，否则就不转发。 +4. vnode B收到Forward消息后，调用回调函数writeToCache, 交给应用处理 +5. vnode B应用在写入成功后，都需要调用syncConfirmForward通知sync模块已经写入成功。 +6. 如果quorum大于1，vnode B需要等待应用的回复确认，收到确认后，vnode B发送Forward Response消息给node A。 +7. 如果quorum大于1，vnode A需要等待vnode B或其他副本对Forward消息的确认。 +8. 如果quorum大于1，vnode A收到quorum-1条确认消息后，调用回调函数confirmForward，通知应用写入成功。 +9. 如果quorum为1，上述6，7，8步不会发生。 +10. 如果要等待slave的确认，master会启动2秒的定时器（可配置），如果超时，则认为失败。 + +对于回复确认，sync模块提供的是异步回调函数，因此APP在调用syncForwardToPeer之后，无需等待，可以处理下一个操作。在Master与Slave的TCP连接管道里，可能有多个Forward消息，这些消息是严格按照应用提供的顺序排好的。对于Forward Response也是一样，TCP管道里存在多个，但都是排序好的。这个顺序，SYNC模块并没有做特别的事情，是由APP单线程顺序写来保证的(TDengine里每个vnode的写数据，都是单线程）。 + +## 数据恢复流程 + +如果一虚拟节点(vnode B) 处于unsynced状态，master存在（vnode A)，而且其版本号比master的低，它将立即启动数据恢复流程。在理解恢复流程时，需要澄清几个关于文件的概念和处理规则。 + +1. 每个文件（无论是archived data的file还是wal)都有一个index, 这需要应用来维护(vnode里，该index就是fileId*3 + 0/1/2, 对应data, head与last三个文件）。如果index为0，表示系统里最老的数据文件。对于mode里的文件，数量是固定的，对应于acct, user, db, table等文件。 +2. 任何一个数据文件(file)有名字、大小，还有一个magic number。只有文件名、大小与magic number一致时，两个文件才判断是一样的，无需同步。Magic number可以是checksum, 也可以是简单的文件大小。怎么计算magic，换句话说，如何检测数据文件是否有效，完全由应用决定。 +3. 文件名的处理有点复杂，因为每台服务器的路径可能不一致。比如node A的TDengine的数据文件存放在 /etc/taos目录下，而node B的数据存放在 /home/jhtao目录下。因此同步模块需要应用在启动一个同步实例时提供一个path，这样两台服务器的绝对路径可以不一样，但仍然可以做对比，做同步。 +4. 当sync模块调用回调函数getFileInfo获得数据文件信息时，有如下的规则 + * index 为0，表示获取最老的文件，同时修改index返回给sync模块。如果index不为0，表示获取指定位置的文件。 + * 如果name为空，表示sync想获取位于index位置的文件信息，包括magic, size。Master节点会这么调用 + * 如果name不为空，表示sync想获取指定文件名和index的信息，slave节点会这么调用 + * 如果某个index的文件不存在，magic返回0，表示文件已经是最后一个。因此整个系统里，文件的index必须是连续的一段整数。 +5. 当sync模块调用回调函数getWalInfo获得wal信息时，有如下规则 + * index为0，表示获得最老的WAL文件, 返回时，index更新为具体的数字 + * 如果返回0，表示这是最新的一个WAL文件，如果返回值是1，表示后面还有更新的WAL文件 + * 返回的文件名为空，那表示没有WAL文件 +6. 无论是getFileInfo, 还是getWalInfo, 只要获取出错（不是文件不存在），返回-1即可，系统会报错，停止同步 + +整个数据恢复流程分为两大步骤，第一步，先恢复archived data(file), 然后恢复wal。具体流程如下： + +![replica-restore.png](/img/architecture/replica-restore.png) + +1. 通过已经建立的TCP连接，发送sync req给master节点 +2. master收到sync req后，以client的身份，向vnode B主动建立一新的专用于同步的TCP连接（syncFd) +3. 新的TCP连接建立成功后，master将开始retrieve流程，对应的，vnode B将同步启动restore流程 +4. Retrieve/Restore流程里，先处理所有archived data (vnode里的data, head, last文件），后处理WAL data。 +5. 对于archived data，master将通过回调函数getFileInfo获取数据文件的基本信息，包括文件名、magic以及文件大小。 +6. master 将获得的文件名、magic以及文件大小发给vnode B +7. vnode B将回调函数getFile获得magic和文件大小，如果两者一致，就认为无需同步，如果两者不一致 ，就认为需要同步。vnode B将结果通过消息FileAck发回master +8. 如果文件需要同步，master就调用sendfile把整个文件发往vnode B +9. 如果文件不需要同步，master(vnode A)就重复5，6，7，8，直到所有文件被处理完 + +对于WAL同步，流程如下： + +1. master节点调用回调函数getWalInfo，获取WAL的文件名。 +2. 如果getWalInfo返回值大于0，表示该文件还不是最后一个WAL，因此master调用sendfile一下把该文件发送给vnode B +3. 如果getWalInfo返回时为0，表示该文件是最后一个WAL，因为文件可能还处于写的状态中，sync模块要根据WAL Head的定义逐条读出记录，然后发往vnode B。 +4. vnode A读取TCP连接传来的数据，按照WAL Head，逐条读取，如果版本号比现有的大，调用回调函数writeToCache，交给应用处理。如果小，直接扔掉。 +5. 上述流程循环，直到所有WAL文件都被处理完。处理完后，master就会将新来的数据包通过Forward消息转发给slave。 + +从同步文件启动起，sync模块会通过inotify监控所有处理过的file以及wal。一旦发现被处理过的文件有更新变化，同步流程将中止，会重新启动。因为有可能落盘操作正在进行（比如历史数据导入，内存数据落盘），把已经处理过的文件进行了修改，需要重新同步才行。 + +对于最后一个WAL (LastWal)的处理逻辑有点复杂，因为这个文件往往是打开写的状态，有很多场景需要考虑，比如： + +- LastWal文件size在增长，需要重新读； +- LastWal文件虽然已经打开写，但内容为空； +- LastWal文件已经被关闭，应用生成了新的Last WAL文件; +- LastWal文件没有被关闭，但数据落盘的原因，没有读到完整的一条记录; +- LastWal文件没有被关闭，但数据落盘的原因，还有部分记录暂时读取不到； + +sync模块通过inotify监控LastWal文件的更新和关闭操作。而且在确认已经尽可能读完LastWal的数据后，会将对方同步状态设置为SYNC_CACHE。该状态下，master节点会将新的记录转发给vnode B，而此时vnode B并没有完成同步，需要把这些转发包先存在recv buffer里，等WAL处理完后，vnode A再把recv buffer里的数据包通过回调writeToCache交给应用处理。 + +等vnode B把这些buffered forwards处理完，同步流程才算结束，vnode B正式变为slave。 + +## Master分布均匀性问题 + +因为Master负责写、转发，消耗的资源会更多，因此Master在整个集群里分布均匀比较理想。 + +但在TDengine的设计里，如果多个虚拟节点都符合master条件，TDengine选在列表中最前面的做Master, 这样是否导致在集群里，Master数量的分布不均匀问题呢？这取决于应用的设计。 + +给一个具体例子，系统里仅仅有三个节点，IP地址分别为IP1, IP2, IP3. 在各个节点上，TDengine创建了多个虚拟节点组，每个虚拟节点组都有三个副本。如果三个副本的顺序在所有虚拟节点组里都是IP1, IP2, IP3, 那毫无疑问，master将集中在IP1这个节点，这是我们不想看到的。 + +但是，如果在创建虚拟节点组时，增加随机性，这个问题就不存在了。比如在vgroup 1, 顺序是IP1, IP2, IP3, 在vgroup 2里，顺序是IP2, IP3, IP1, 在vgroup 3里，顺序是IP3, IP1, IP2。最后master的分布会是均匀的。 + +因此在创建一个虚拟节点组时，应用需要保证节点的顺序是round robin或完全随机。 + +## 少数虚拟节点写入成功的问题 + +在某种情况下，写入成功的确认数大于0，但小于配置的Quorum, 虽然有虚拟节点数据更新成功，master仍然会认为数据更新失败，并通知客户端写入失败。 + +这个时候，系统存在数据不一致的问题，因为有的虚拟节点已经写入成功，而有的写入失败。一个处理方式是，Master重置(reset)与其他虚拟节点的连接，该虚拟节点组将自动进入选举流程。按照规则，已经成功写入数据的虚拟节点将成为新的master，组内的其他虚拟节点将从master那里恢复数据。 + +因为写入失败，客户端会重新写入数据。但对于TDengine而言，是OK的。因为时序数据都是有时间戳的，时间戳相同的数据更新操作，第一次会执行，但第二次会自动扔掉。对于Meta Data(增加、删除库、表等等）的操作，也是OK的。一张表、库已经被创建或删除，再创建或删除，不会被执行的。 + +在TDengine的设计里，虚拟节点与虚拟节点之间，是一个TCP连接，是一个pipeline，数据块一个接一个按顺序在这个pipeline里等待处理。一旦某个数据块的处理失败，这个连接会被重置，后续的数据块的处理都会失败。因此不会存在Pipeline里一个数据块更新失败，但下一个数据块成功的可能。 + +## Split Brain的问题 + +选举流程中，有个强制要求，那就是一定有超过半数的虚拟节点在线。但是如果replication正好是偶数，这个时候，完全可能存在splt brain问题。 + +为解决这个问题，TDengine提供Arbitrator的解决方法。Arbitrator是一个节点，它的任务就是接受任何虚拟节点的连接请求，并保持它。 + +在启动复制模块实例时，在配置参数中，应用可以提供Arbitrator的IP地址。如果是奇数个副本，复制模块不会与这个arbitrator去建立连接，但如果是偶数个副本，就会主动去建立连接。 + +Arbitrator的程序tarbitrator.c在复制模块的同一目录, 编译整个系统时，会在bin目录生成。命令行参数“-？”查看可以配置的参数，比如绑定的IP地址，监听的端口号。 + +## 与RAFT相比的异同 + +数据一致性协议流行的有两种，Paxos与Raft. 本设计的实现与Raft有很多类同之处，下面做一些比较 + +相同之处： + +- 三大流程一致：Raft里有Leader election, replication, safety，完全对应TDengine的选举、数据转发、数据恢复三个流程。 +- 节点状态定义一致：Raft里每个节点有Leader, Follower, Candidate三个状态，TDengine里是Master, Slave, Unsynced, Offline。多了一个offlince, 但本质上是一样的，因为offline是外界看一个节点的状态，但该节点本身是处于master, slave 或unsynced的。 +- 数据转发流程完全一样，Master(leader)需要等待回复确认。 +- 数据恢复流程几乎一样，Raft没有涉及历史数据同步问题，只考虑了WAL数据同步。 + +不同之处： + +- 选举流程不一样：Raft里任何一个节点是candidate时，主动向其他节点发出vote request，如果超过半数回答Yes，这个candidate就成为Leader，开始一个新的term。而TDengine的实现里，节点上线、离线或角色改变都会触发状态消息在节点组内传播，等节点组里状态稳定一致之后才触发选举流程，因为状态稳定一致，基于同样的状态信息，每个节点做出的决定会是一致的，一旦某个节点符合成为master的条件，无需其他节点认可，它会自动将自己设为master。TDengine里，任何一个节点检测到其他节点或自己的角色发生改变，就会向节点组内其他节点进行广播。Raft里不存在这样的机制，因此需要投票来解决。 +- 对WAL的一条记录，Raft用term + index来做唯一标识。但TDengine只用version（类似index)，在TDengine实现里，仅仅用version是完全可行的, 因为TDengine的选举机制，没有term的概念。 + +如果整个虚拟节点组全部宕机，重启，但不是所有虚拟节点都上线，这个时候TDengine是不会选出master的，因为未上线的节点有可能有最高version的数据。而RAFT协议，只要超过半数上线，就会选出Leader。 + +## Meta Data的数据复制 + +TDengine里存在时序数据，也存在Meta Data。Meta Data对数据的可靠性要求更高，那么TDengine设计能否满足要求呢？下面做个仔细分析。 + +TDengine里Meta Data包括以下： + +- account 信息 +- 一个account下面，可以有多个user, 多个DB +- 一个DB下面有多个vgroup +- 一个DB下面有多个stable +- 一个vgroup下面有多个table +- 整个系统有多个mnode, dnode +- 一个dnode可以有多个vnode + +上述的account, user, DB, vgroup, table, stable, mnode, dnode都有自己的属性，这些属性是TDengine自己定义的，不会开放给用户进行修改。这些Meta Data的查询都比较简单，都可以采用key-value模型进行存储。这些Meta Data还具有几个特点： + +1. 上述的Meta Data之间有一定的层级关系，比如必须先创建DB，才能创建table, stable。只有先创建dnode，才可能创建vnode, 才可能创建vgroup。因此他们创建的顺序是绝对不能错的。 +2. 在客户端应用的数据更新操作得到TDengine服务器侧确认后，所执行的数据更新操作绝对不能丢失。否则会造成客户端应用与服务器的数据不一致。 +3. 上述的Meta Data是容许重复操作的。比如插入新记录后，再插入一次，删除一次后，再删除一次，更新一次后，再更新一次，不会对系统产生任何影响，不会改变系统任何状态。 + +对于特点1，本设计里，数据的写入是单线程的，按照到达的先后顺序，给每个数据更新操作打上版本号，版本号大的记录一定是晚于版本号小的写入系统，数据写入顺序是100%保证的，绝对不会让版本号大的记录先写入。复制过程中，数据块的转发也是严格按照顺序进行的，因此TDengine的数据复制设计是能保证Meta Data的创建顺序的。 + +对于特点2，只要Quorum数设置等于replica，那么一定能保证回复确认过的数据更新操作不会在服务器侧丢失。即使某节点永不起来，只要超过一半的节点还是online, 查询服务不会受到任何影响。这时，如果某个节点离线超过一定时长，系统可以自动补充新的节点，以保证在线的节点数在绝大部分时间是100%的。 + +对于特点3，完全可能发生，服务器确实持久化存储了某一数据更新操作，但客户端应用出了问题，认为操作不成功，它会重新发起操作。但对于Meta Data而言，没有关系，客户端可以再次发起同样的操作，不会有任何影响。 + +总结来看，只要quorum设置大于一，本数据复制的设计是能满足Meta Data的需求的。目前，还没有发现漏洞。 diff --git a/docs-cn/21-tdinternal/03-taosd.md b/docs-cn/21-tdinternal/03-taosd.md new file mode 100644 index 0000000000000000000000000000000000000000..6a5734102c85db291339ce93a2231cb8196053f6 --- /dev/null +++ b/docs-cn/21-tdinternal/03-taosd.md @@ -0,0 +1,119 @@ +--- +sidebar_label: taosd 的设计 +title: taosd的设计 +--- + +逻辑上，TDengine 系统包含 dnode，taosc 和 App，dnode 是服务器侧执行代码 taosd 的一个运行实例，因此 taosd 是 TDengine 的核心，本文对 taosd 的设计做一简单的介绍，模块内的实现细节请见其他文档。 + +## 系统模块图 + +taosd 包含 rpc，dnode，vnode，tsdb，query，cq，sync，wal，mnode，http，monitor 等模块，具体如下图： + +![modules.png](/img/architecture/modules.png) + +taosd 的启动入口是 dnode 模块，dnode 然后启动其他模块，包括可选配置的 http，monitor 模块。taosc 或 dnode 之间交互的消息都是通过 rpc 模块进行，dnode 模块根据接收到的消息类型，将消息分发到 vnode 或 mnode 的消息队列，或由 dnode 模块自己消费。dnode 的工作线程（worker）消费消息队列里的消息，交给 mnode 或 vnode 进行处理。下面对各个模块做简要说明。 + +## RPC 模块 + +该模块负责 taosd 与 taosc，以及其他数据节点之间的通讯。TDengine 没有采取标准的 HTTP 或 gRPC 等第三方工具，而是实现了自己的通讯模块 RPC。 + +考虑到物联网场景下，数据写入的包一般不大，因此除支持 TCP 连接之外，RPC 还支持 UDP 连接。当数据包小于 15K 时，RPC 将采用 UDP 方式进行连接，否则将采用 TCP 连接。对于查询类的消息，RPC 不管包的大小，总是采取 TCP 连接。对于 UDP 连接，RPC 实现了自己的超时、重传、顺序检查等机制，以保证数据可靠传输。 + +RPC 模块还提供数据压缩功能，如果数据包的字节数超过系统配置参数 compressMsgSize，RPC 在传输中将自动压缩数据，以节省带宽。 + +为保证数据的安全和数据的 integrity，RPC 模块采用 MD5 做数字签名，对数据的真实性和完整性进行认证。 + +## DNODE 模块 + +该模块是整个 taosd 的入口，它具体负责如下任务： + +- 系统的初始化，包括 + - 从文件 taos.cfg 读取系统配置参数，从文件 dnodeCfg.json 读取数据节点的配置参数； + - 启动 RPC 模块，并建立起与 taosc 通讯的 server 连接，与其他数据节点通讯的 server 连接； + - 启动并初始化 dnode 的内部管理，该模块将扫描该数据节点已有的 vnode ，并打开它们； + - 初始化可配置的模块，如 mnode，http，monitor 等。 +- 数据节点的管理，包括 + - 定时的向 mnode 发送 status 消息，报告自己的状态； + - 根据 mnode 的指示，创建、改变、删除 vnode； + - 根据 mnode 的指示，修改自己的配置参数； +- 消息的分发、消费，包括 + - 为每一个 vnode 和 mnode 的创建并维护一个读队列、一个写队列； + - 将从 taosc 或其他数据节点来的消息，根据消息类型，将其直接分发到不同的消息队列，或由自己的管理模块直接消费； + - 维护一个读的线程池，消费读队列的消息，交给 vnode 或 mnode 处理。为支持高并发，一个读线程（worker）可以消费多个队列的消息，一个读队列可以由多个 worker 消费； + - 维护一个写的线程池，消费写队列的消息，交给 vnode 或 mnode 处理。为保证写操作的序列化，一个写队列只能由一个写线程负责，但一个写线程可以负责多个写队列。 + +taosd 的消息消费由 dnode 通过读写线程池进行控制，是系统的中枢。该模块内的结构体图如下： + +![dnode.png](/img/architecture/dnode.png) + +## VNODE 模块 + +vnode 是一独立的数据存储查询逻辑单元，但因为一个 vnode 只能容许一个 DB ，因此 vnode 内部没有 account，DB，user 等概念。为实现更好的模块化、封装以及未来的扩展，它有很多子模块，包括负责存储的 TSDB，负责查询的 query，负责数据复制的 sync，负责数据库日志的的 WAL，负责连续查询的 cq（continuous query），负责事件触发的流计算的 event 等模块，这些子模块只与 vnode 模块发生关系，与其他模块没有任何调用关系。模块图如下： + +![vnode.png](/img/architecture/vnode.png) + +vnode 模块向下，与 dnodeVRead，dnodeVWrite 发生互动，向上，与子模块发生互动。它主要的功能有： + +- 协调各个子模块的互动。各个子模块之间都不直接调用，都需要通过 vnode 模块进行； +- 对于来自 taosc 或 mnode 的写操作，vnode 模块将其分解为写日志（WAL），转发（sync），本地存储（TSDB）子模块的操作； +- 对于查询操作，分发到 query 模块进行。 + +一个数据节点里有多个 vnode，因此 vnode 模块是有多个运行实例的。每个运行实例是完全独立的。 + +vnode 与其子模块是通过 API 直接调用，而不是通过消息队列传递。而且各个子模块只与 vnode 模块有交互，不与 dnode，rpc 等模块发生任何直接关联。 + +## MNODE 模块 + +mnode 是整个系统的大脑，负责整个系统的资源调度，负责 meta data 的管理与存储。 + +一个运行的系统里，只有一个 mnode，但它有多个副本（由系统配置参数 numOfMnodes 控制）。这些副本分布在不同的 dnode 里，目的是保证系统的高可靠运行。副本之间的数据复制是采用同步而非异步的方式，以确保数据的一致性，确保数据不会丢失。这些副本会自动选举一个 Master，其他副本是 slave。所有数据更新类的操作，都只能在 master 上进行，而查询类的可以在 slave 节点上进行。代码实现上，同步模块与 vnode 共享，但 mnode 被分配一个特殊的 vgroup ID: 1，而且 quorum 大于 1。整个集群系统是由多个 dnode 组成的，运行的 mnode 的副本数不可能超过 dnode 的个数，但不会超过配置的副本数。如果某个 mnode 副本宕机一段时间，只要超过半数的 mnode 副本仍在运行，运行的 mnode 会自动根据整个系统的资源情况，在其他 dnode 里再启动一个 mnode，以保证运行的副本数。 + +各个 dnode 通过信息交换，保存有 mnode 各个副本的 End Point 列表，并向其中的 master 节点定时（间隔由系统配置参数 statusInterval 控制）发送 status 消息，消息体里包含该 dnode 的 CPU、内存、剩余存储空间、vnode 个数，以及各个 vnode 的状态（存储空间、原始数据大小、记录条数、角色等）。这样 mnode 就了解整个系统的资源情况，如果用户创建新的表，就可以决定需要在哪个 dnode 创建；如果增加或删除 dnode，或者监测到某 dnode 数据过热、或离线太长，就可以决定需要挪动那些 vnode，以实现负载均衡。 + +mnode 里还负责 account，user，DB，stable，table，vgroup，dnode 的创建、删除与更新。mnode 不仅把这些 entity 的 meta data 保存在内存，还做持久化存储。但为节省内存，各个表的标签值不保存在 mnode（保存在 vnode），而且子表不维护自己的 schema，而是与 stable 共享。为减小 mnode 的查询压力，taosc 会缓存 table、stable 的 schema。对于查询类的操作，各个 slave mnode 也可以提供，以减轻 master 压力。 + +## TSDB 模块 + +TSDB 模块是 vnode 中的负责快速高并发地存储和读取属于该 vnode 的表的元数据及采集的时序数据的引擎。除此之外，TSDB 还提供了表结构的修改、表标签值的修改等功能。TSDB 提供 API 供 vnode 和 query 等模块调用。TSDB 中存储了两类数据，1：元数据信息；2：时序数据 + +### 元数据信息 + +TSDB 中存储的元数据包含属于其所在的 vnode 中表的类型，schema 的定义等。对于超级表和超级表下的子表而言，又包含了 tag 的 schema 定义以及子表的 tag 值等。对于元数据信息而言，TSDB 就相当于一个全内存的 KV 型数据库，属于该 vnode 的表对象全部在内存中，方便快速查询表的信息。除此之外，TSDB 还对其中的子表，按照 tag 的第一列取值做了全内存的索引，大大加快了对于标签的过滤查询。TSDB 中的元数据的最新状态在落盘时，会以追加（append-only）的形式，写入到 meta 文件中。meta 文件只进行追加操作，即便是元数据的删除，也会以一条记录的形式写入到文件末尾。TSDB 也提供了对于元数据的修改操作，如表 schema 的修改，tag schema 的修改以及 tag 值的修改等。 + +### 时序数据 + +每个 TSDB 在创建时，都会事先分配一定量的内存缓冲区，且内存缓冲区的大小可配可修改。表采集的时序数据，在写入 TSDB 时，首先以追加的方式写入到分配的内存缓冲区中，同时建立基于时间戳的内存索引，方便快速查询。当内存缓冲区的数据积累到一定的程度时（达到内存缓冲区总大小的 1/3），则会触发落盘操作，将缓冲区中的数据持久化到硬盘文件上。时序数据在内存缓冲区中是以行（row）的形式存储的。 + +而时序数据在写入到 TSDB 的数据文件时，是以列（column）的形式存储的。TSDB 中的数据文件包含多个数据文件组，每个数据文件组中又包含 .head、.data 和 .last 三个文件，如（v2f1801.head、v2f1801.data、v2f1801.last）数据文件组。TSDB 中的数据文件组是按照时间跨度进行分片的，默认是 10 天一个文件组，且可通过配置文件及建库选项进行配置。分片的数据文件组又按照编号递增排列，方便快速定位某一时间段的时序数据，高效定位数据文件组。时序数据在 TSDB 的数据文件中是以块的形式进行列式存储的，每个块中只包含一张表的数据，且数据在一个块中是按照时间顺序递增排列的。在一个数据文件组中，.head 文件负责存储数据块的索引及统计信息，如每个块的位置，压缩算法，时间戳范围等。存储在 .head 文件中一张表的索引信息是按照数据块中存储的数据的时间递增排列的，方便进行折半查找等工作。.head 和 .last 文件是存储真实数据块的文件，若数据块中的数据累计到一定程度，则会写入 .data 文件中，否则，会写入 .last 文件中，等待下次落盘时合并数据写入 .data 文件中，从而大大减少文件中块的个数，避免数据的过度碎片化。 + +## Query 模块 + +该模块负责整体系统的查询处理。客户端调用该该模块进行 SQL 语法解析，并将查询或写入请求发送到 vnode ，同时负责针对超级表的查询进行二阶段的聚合操作。在 vnode 端，该模块调用 TSDB 模块读取系统中存储的数据进行查询处理。query 模块还定义了系统能够支持的全部查询函数，查询函数的实现机制与查询框架无耦合，可以在不修改查询流程的情况下动态增加查询函数。详细的设计请参见《TDengine 2.0 查询模块设计》。 + +## SYNC 模块 + +该模块实现数据的多副本复制，包括 vnode 与 mnode 的数据复制，支持异步和同步两种复制方式，以满足 meta data 与时序数据不同复制的需求。因为它为 mnode 与 vnode 共享，系统为 mnode 副本预留了一个特殊的 vgroup ID:1。因此 vnode group 的 ID 是从 2 开始的。 + +每个 vnode/mnode 模块实例会有一对应的 sync 模块实例，他们是一一对应的。详细设计请见[TDengine 2.0 数据复制模块设计](/tdinternal/replica/) + +## WAL 模块 + +该模块负责将新插入的数据写入 write ahead log（WAL），为 vnode，mnode 共享。以保证服务器 crash 或其他故障，能从 WAL 中恢复数据。 + +每个 vnode/mnode 模块实例会有一对应的 WAL 模块实例，是完全一一对应的。WAL 的落盘操作由两个参数 walLevel，fsync 控制。看具体场景，如果要 100% 保证数据不会丢失，需要将 walLevel 配置为 2，fsync 设置为 0，每条数据插入请求，都会实时落盘后，才会给应用确认 + +## HTTP 模块 + +该模块负责处理系统对外的 RESTful 接口，可以通过配置，由 dnode 启动或停止 。（仅 2.2 及之前的版本中存在） + +该模块将接收到的 RESTful 请求，做了各种合法性检查后，将其变成标准的 SQL 语句，通过 taosc 的异步接口，将请求发往整个系统中的任一 dnode 。收到处理后的结果后，再翻译成 HTTP 协议，返回给应用。 + +如果 HTTP 模块启动，就意味着启动了一个 taosc 的实例。任一一个 dnode 都可以启动该模块，以实现对 RESTful 请求的分布式处理。 + +## Monitor 模块 + +该模块负责检测一个 dnode 的运行状态，可以通过配置，由 dnode 启动或停止。原则上，每个 dnode 都应该启动一个 monitor 实例。 + +Monitor 采集 TDengine 里的关键操作，比如创建、删除、更新账号、表、库等，而且周期性的收集 CPU、内存、网络等资源的使用情况（采集周期由系统配置参数 monitorInterval 控制）。获得这些数据后，monitor 模块将采集的数据写入系统的日志库（DB 名字由系统配置参数 monitorDbName 控制）。 + +Monitor 模块使用 taosc 来将采集的数据写入系统，因此每个 monitor 实例，都有一个 taosc 运行实例。 diff --git a/docs-cn/21-tdinternal/12-tsz-compress.md b/docs-cn/21-tdinternal/12-tsz-compress.md new file mode 100644 index 0000000000000000000000000000000000000000..baf5df15db3b44edc9e0bd6909e46fa84b676a0b --- /dev/null +++ b/docs-cn/21-tdinternal/12-tsz-compress.md @@ -0,0 +1,44 @@ +--- +title: TSZ 压缩算法 +--- + +TSZ 压缩算法是 TDengine 为浮点数据类型提供更加丰富的压缩功能，可以实现浮点数的有损至无损全状态压缩，相比原来在 TDengine 中原有压缩算法，TSZ 压缩算法压缩选项更丰富，压缩率更高，即使切到无损状态下对浮点数压缩，压缩率也会比原来的压缩算法高一倍。 + +## 适合场景 + +TSZ 压缩算法压缩率比原来的要高，但压缩时间会更长，即开启 TSZ 压缩算法写入速度会有一些下降，通常情况下会有 20% 左右的下降。影响写入速度是因为需要更多的 CPU 计算，所以从原始数据到压缩好数据的交付时间变长，导致写入速度变慢。如果您的服务器 CPU 配置很高的话，这个影响会变小甚至没有。 + +另外如果设备产生了大量的高精度浮点数，存储占用的空间非常庞大，但实际使用并不需要那么高的精度时，可以通过 TSZ 压缩的有损压缩功能，把精度压缩至指定的长度，节约存储空间。 + +总结：采集到了大量浮点数，存储时占用空间过大或出有存储空间不足，需要超高压缩率的场景。 + +## 使用步骤 + +- 检查版本支持，2.4.0.10 及之后 TDengine 的版本都支持此功能 + +- 配置选项开启功能，在 TDengine 的配置文件 taos.cfg 增加一行以下内容，打开 TSZ 功能 + +```TSZ +lossyColumns float|double +``` + +- 根据自己需要配置其它选项，如果不配置都会按默认值处理。 + +- 重启服务，配置生效。 +- 确认功能已开启，在服务启动过程中输出的信息如果有前面配置的内容，表明功能已生效： + +```TSZ Test +02/22 10:49:27.607990 00002933 UTL lossyColumns float|double +``` + +## 注意事项 + +- 确认版本是否支持 + +- 除了服务器启动时的输出的配置成功信息外，不再会有其它的信息输出是使用的哪种压缩算法，可以通过配置前后数据库文件大小来比较效果 + +- 如果浮点数类型列较少，看整体数据文件大小效果会不太明显 + +- 此压缩产生的数据文件中浮点数据部分将不能被 2.4.0.10 以下的版本解析，即不向下兼容，使用时避免更换回旧版本，以免数据不能被读取出来。 + +- 在使用过程中允许反复开启和关闭 TSZ 压缩选项的操作，前后两种压缩算法产生的数据都能正常读取。 diff --git a/docs-cn/21-tdinternal/30-iot-big-data.md b/docs-cn/21-tdinternal/30-iot-big-data.md new file mode 100644 index 0000000000000000000000000000000000000000..a234713f883056e3d1a0dcbfe8e2e47a82865f81 --- /dev/null +++ b/docs-cn/21-tdinternal/30-iot-big-data.md @@ -0,0 +1,9 @@ +--- +title: 物联网大数据 +description: "物联网、工业互联网大数据的特点；物联网大数据平台应具备的功能和特点；通用大数据架构为什么不适合处理物联网数据；物联网、车联网、工业互联网大数据平台，为什么推荐使用 TDengine" +--- + +- [物联网、工业互联网大数据的特点](https://www.taosdata.com/blog/2019/07/09/105.html) +- [物联网大数据平台应具备的功能和特点](https://www.taosdata.com/blog/2019/07/29/542.html) +- [通用大数据架构为什么不适合处理物联网数据？](https://www.taosdata.com/blog/2019/07/09/107.html) +- [物联网、车联网、工业互联网大数据平台，为什么推荐使用 TDengine？](https://www.taosdata.com/blog/2019/07/09/109.html) diff --git a/docs-cn/21-tdinternal/_category_.yml b/docs-cn/21-tdinternal/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..c7509bf66224fa94759de9a2ae82955e2a7eb82f --- /dev/null +++ b/docs-cn/21-tdinternal/_category_.yml @@ -0,0 +1 @@ +label: 技术内幕 \ No newline at end of file diff --git a/docs-cn/21-tdinternal/index.md b/docs-cn/21-tdinternal/index.md new file mode 100644 index 0000000000000000000000000000000000000000..63a746623e0dd955f61ba887a76f8ecf7eb16972 --- /dev/null +++ b/docs-cn/21-tdinternal/index.md @@ -0,0 +1,10 @@ +--- +title: 技术内幕 +--- + +```mdx-code-block +import DocCardList from '@theme/DocCardList'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + + +``` \ No newline at end of file diff --git a/docs-cn/25-application/01-telegraf.md b/docs-cn/25-application/01-telegraf.md new file mode 100644 index 0000000000000000000000000000000000000000..f63a6701eed2b4c5b98f577d5b2867ae6dada387 --- /dev/null +++ b/docs-cn/25-application/01-telegraf.md @@ -0,0 +1,82 @@ +--- +sidebar_label: TDengine + Telegraf + Grafana +title: 使用 TDengine + Telegraf + Grafana 快速搭建 IT 运维展示系统 +--- + +## 背景介绍 + +TDengine 是涛思数据专为物联网、车联网、工业互联网、IT 运维等设计和优化的大数据平台。自从 2019 年 7 月开源以来，凭借创新的数据建模设计、快捷的安装方式、易用的编程接口和强大的数据写入查询性能博得了大量时序数据开发者的青睐。 + +IT 运维监测数据通常都是对时间特性比较敏感的数据，例如： + +- 系统资源指标：CPU、内存、IO、带宽等。 +- 软件系统指标：存活状态、连接数目、请求数目、超时数目、错误数目、响应时间、服务类型及其他与业务有关的指标。 + +当前主流的 IT 运维系统通常包含一个数据采集模块，一个数据存储模块，和一个可视化显示模块。Telegraf 和 Grafana 分别是当前最流行的数据采集模块和可视化显示模块之一。而数据存储模块可供选择的软件比较多，其中 OpenTSDB 或 InfluxDB 比较流行。而 TDengine 作为新兴的时序大数据平台，具备极强的高性能、高可靠、易管理、易维护的优势。 + +本文介绍不需要写一行代码，通过简单修改几行配置文件，就可以快速搭建一个基于 TDengine + Telegraf + Grafana 的 IT 运维系统。架构如下图： + +![IT-DevOps-Solutions-Telegraf.png](/img/IT-DevOps-Solutions-Telegraf.png) + +## 安装步骤 + +### 安装 Telegraf，Grafana 和 TDengine + +安装 Telegraf、Grafana 和 TDengine 请参考相关官方文档。 + +### Telegraf + +请参考[官方文档](https://portal.influxdata.com/downloads/)。 + +### Grafana + +请参考[官方文档](https://grafana.com/grafana/download)。 + +### TDengine + +从涛思数据官网[下载](http://taosdata.com/cn/all-downloads/)页面下载最新 TDengine-server 2.4.0.x 或以上版本安装。 + +## 数据链路设置 + +### 下载 TDengine 插件到 Grafana 插件目录 + +```bash +1. wget -c https://github.com/taosdata/grafanaplugin/releases/download/v3.1.3/tdengine-datasource-3.1.3.zip +2. sudo unzip tdengine-datasource-3.1.3.zip -d /var/lib/grafana/plugins/ +3. sudo chown grafana:grafana -R /var/lib/grafana/plugins/tdengine +4. echo -e "[plugins]\nallow_loading_unsigned_plugins = tdengine-datasource\n" | sudo tee -a /etc/grafana/grafana.ini +5. sudo systemctl restart grafana-server.service +``` + +### 修改 /etc/telegraf/telegraf.conf + +配置方法，在 `/etc/telegraf/telegraf.conf` 增加如下文字，其中 `database name` 请填写希望在 TDengine 保存 Telegraf 数据的数据库名，`TDengine server/cluster host`、`username` 和 `password` 填写 TDengine 实际值： + +``` +[[outputs.http]] + url = "http://:6041/influxdb/v1/write?db=" + method = "POST" + timeout = "5s" + username = "" + password = "" + data_format = "influx" + influx_max_line_bytes = 250 +``` + +然后重启 Telegraf： + +```bash +sudo systemctl start telegraf +``` + +### 导入 Dashboard + +使用 Web 浏览器访问 `IP:3000` 登录 Grafana 界面，系统初始用户名密码为 admin/admin。 +点击左侧齿轮图标并选择 `Plugins`，应该可以找到 TDengine data source 插件图标。 +点击左侧加号图标并选择 `Import`，从 `https://github.com/taosdata/grafanaplugin/blob/master/examples/telegraf/grafana/dashboards/telegraf-dashboard-v0.1.0.json` 下载 dashboard JSON 文件后导入。之后可以看到如下界面的仪表盘： + +![IT-DevOps-Solutions-telegraf-dashboard.png](/img/IT-DevOps-Solutions-telegraf-dashboard.png) + +## 总结 + +以上演示如何快速搭建一个完整的 IT 运维展示系统。得力于 TDengine 2.4.0.0 版本中新增的 schemaless 协议解析功能，以及强大的生态软件适配能力，用户可以短短数分钟就可以搭建一个高效易用的 IT 运维系统。TDengine 强大的数据写入查询性能和其他丰富功能请参考官方文档和产品落地案例。 diff --git a/docs-cn/25-application/02-collectd.md b/docs-cn/25-application/02-collectd.md new file mode 100644 index 0000000000000000000000000000000000000000..5e6bc6577b2f4c8564e4533ced745d0b214ec748 --- /dev/null +++ b/docs-cn/25-application/02-collectd.md @@ -0,0 +1,95 @@ +--- +sidebar_label: TDengine + collectd/StatsD + Grafana +title: 使用 TDengine + collectd/StatsD + Grafana 快速搭建 IT 运维监控系统 +--- + +## 背景介绍 + +TDengine 是涛思数据专为物联网、车联网、工业互联网、IT 运维等设计和优化的大数据平台。自从 2019 年 7 月开源以来，凭借创新的数据建模设计、快捷的安装方式、易用的编程接口和强大的数据写入查询性能博得了大量时序数据开发者的青睐。 + +IT 运维监测数据通常都是对时间特性比较敏感的数据，例如： + +- 系统资源指标：CPU、内存、IO、带宽等。 +- 软件系统指标：存活状态、连接数目、请求数目、超时数目、错误数目、响应时间、服务类型及其他与业务有关的指标。 + +当前主流的 IT 运维系统通常包含一个数据采集模块，一个数据存储模块，和一个可视化显示模块。collectd / statsD 作为老牌开源数据采集工具，具有广泛的用户群。但是 collectd / StatsD 自身功能有限，往往需要配合 Telegraf、Grafana 以及时序数据库组合搭建成为完整的监控系统。而 TDengine 新版本支持多种数据协议接入，可以直接接受 collectd 和 statsD 的数据写入，并提供 Grafana dashboard 进行图形化展示。 + +本文介绍不需要写一行代码，通过简单修改几行配置文件，就可以快速搭建一个基于 TDengine + collectd / statsD + Grafana 的 IT 运维系统。架构如下图： + +![IT-DevOps-Solutions-Collectd-StatsD.png](/img/IT-DevOps-Solutions-Collectd-StatsD.png) + +## 安装步骤 + +安装 collectd， StatsD， Grafana 和 TDengine 请参考相关官方文档。 + +### 安装 collectd + +请参考[官方文档](https://collectd.org/documentation.shtml)。 + +### 安装 StatsD + +请参考[官方文档](https://github.com/statsd/statsd)。 + +### 安装 Grafana + +请参考[官方文档](https://grafana.com/grafana/download)。 + +### 安装 TDengine + +从涛思数据官网[下载](http://taosdata.com/cn/all-downloads/)页面下载最新 TDengine-server 2.4.0.x 或以上版本安装。 + +## 数据链路设置 + +### 复制 TDengine 插件到 grafana 插件目录 + +```bash +1. wget -c https://github.com/taosdata/grafanaplugin/releases/download/v3.1.3/tdengine-datasource-3.1.3.zip +2. sudo unzip tdengine-datasource-3.1.3.zip -d /var/lib/grafana/plugins/ +3. sudo chown grafana:grafana -R /var/lib/grafana/plugins/tdengine +4. echo -e "[plugins]\nallow_loading_unsigned_plugins = tdengine-datasource\n" | sudo tee -a /etc/grafana/grafana.ini +5. sudo systemctl restart grafana-server.service +``` + +### 配置 collectd + +在 `/etc/collectd/collectd.conf` 文件中增加如下内容，其中 `host` 和 `port` 请填写 TDengine 和 taosAdapter 配置的实际值： + +``` +LoadPlugin network + + Server "" "" + + +sudo systemctl start collectd +``` + +### 配置 StatsD + +在 `config.js` 文件中增加如下内容后启动 StatsD，其中 `host` 和 `port` 请填写 TDengine 和 taosAdapter 配置的实际值： + +``` +backends 部分添加 "./backends/repeater" +repeater 部分添加 { host:'', port: } +``` + +### 导入 Dashboard + +使用 Web 浏览器访问运行 Grafana 的服务器的 3000 端口 `host:3000` 登录 Grafana 界面，系统初始用户名密码为 `admin/admin`。 +点击左侧齿轮图标并选择 `Plugins`，应该可以找到 TDengine data source 插件图标。 + +#### 导入 collectd 仪表盘 + +从 https://github.com/taosdata/grafanaplugin/blob/master/examples/collectd/grafana/dashboards/collect-metrics-with-tdengine-v0.1.0.json 下载 dashboard json 文件，点击左侧加号图标并选择 `Import`，按照界面提示选择 JSON 文件导入。之后可以看到如下界面的仪表盘： + +![IT-DevOps-Solutions-collectd-dashboard.png](/img/IT-DevOps-Solutions-collectd-dashboard.png) + +#### 导入 StatsD 仪表盘 + +从 `https://github.com/taosdata/grafanaplugin/blob/master/examples/statsd/dashboards/statsd-with-tdengine-v0.1.0.json` 下载 dashboard json 文件，点击左侧加号图标并选择 `Import`，按照界面提示导入 JSON 文件。之后可以看到如下界面的仪表盘： +![IT-DevOps-Solutions-statsd-dashboard.png](/img/IT-DevOps-Solutions-statsd-dashboard.png) + +## 总结 + +TDengine 作为新兴的时序大数据平台，具备极强的高性能、高可靠、易管理、易维护的优势。得力于 TDengine 2.4.0.0 版本中新增的 schemaless 协议解析功能，以及强大的生态软件适配能力，用户可以短短数分钟就可以搭建一个高效易用的 IT 运维系统或者适配一个已存在的系统。 + +TDengine 强大的数据写入查询性能和其他丰富功能请参考官方文档和产品成功落地案例。 diff --git a/docs-cn/25-application/03-immigrate.md b/docs-cn/25-application/03-immigrate.md new file mode 100644 index 0000000000000000000000000000000000000000..012fb2a73792f764c3a18e758ed18b4f956f7af8 --- /dev/null +++ b/docs-cn/25-application/03-immigrate.md @@ -0,0 +1,423 @@ +--- +sidebar_label: OpenTSDB 迁移到 TDengine +title: OpenTSDB 应用迁移到 TDengine 的最佳实践 +--- + +作为一个分布式、可伸缩、基于 HBase 的分布式时序数据库系统，得益于其先发优势，OpenTSDB 被 DevOps 领域的人员引入并广泛地应用在了运维监控领域。但最近几年，随着云计算、微服务、容器化等新技术快速落地发展，企业级服务种类变得越来越多，架构也越来越复杂，应用运行基础环境日益多样化，给系统和运行监控带来的压力也越来越大。从这一现状出发，使用 OpenTSDB 作为 DevOps 的监控后端存储，越来越受困于其性能问题以及迟缓的功能升级，以及由此而衍生出来的应用部署成本上升和运行效率降低等问题，这些问题随着系统规模的扩大日益严重。 + +在这一背景下，为满足高速增长的物联网大数据市场和技术需求，在吸取众多传统关系型数据库、NoSQL 数据库、流计算引擎、消息队列等软件的优点之后，涛思数据自主开发出创新型大数据处理产品 TDengine。在时序大数据处理上，TDengine 有着自己独特的优势。就 OpenTSDB 当前遇到的问题来说，TDengine 能够有效解决。 + +相对于 OpenTSDB，TDengine 具有如下显著特点： + +- 数据写入和查询的性能远超 OpenTSDB； +- 针对时序数据的高效压缩机制，压缩后在磁盘上的存储空间不到 1/5； +- 安装部署非常简单，单一安装包完成安装部署，不依赖其他的第三方软件，整个安装部署过程秒级搞定; +- 提供的内建函数覆盖 OpenTSDB 支持的全部查询函数，还支持更多的时序数据查询函数、标量函数及聚合函数，支持多种时间窗口聚合、连接查询、表达式运算、多种分组聚合、用户定义排序、以及用户定义函数等高级查询功能。采用类 SQL 的语法规则，更加简单易学，基本上没有学习成本。 +- 支持多达 128 个标签，标签总长度可达到 16 KB； +- 除 REST 接口之外，还提供 C/C++、Java、Python、Go、Rust、Node.js、C#、Lua（社区贡献）、PHP（社区贡献）等多种语言的接口，支持 JDBC 等多种企业级标准连接器协议。 + +如果我们将原本运行在 OpenTSDB 上的应用迁移到 TDengine 上，不仅可以有效地降低计算和存储资源的占用、减少部署服务器的规模，还能够极大减少运行维护的成本的输出，让运维管理工作更简单、更轻松，大幅降低总拥有成本。与 OpenTSDB 一样，TDengine 也已经进行了开源，不同的是，除了单机版，后者还实现了集群版开源，被厂商绑定的顾虑一扫而空。 + +在下文中我们将就“使用最典型并广泛应用的运维监控（DevOps）场景”来说明，如何在不编码的情况下将 OpenTSDB 的应用快速、安全、可靠地迁移到 TDengine 之上。后续的章节会做更深度的介绍，以便于进行非 DevOps 场景的迁移。 + +## DevOps 应用快速迁移 + +### 1、典型应用场景 + +一个典型的 DevOps 应用场景的系统整体的架构如下图（图 1） 所示。 + +**图 1. DevOps 场景中典型架构** +![IT-DevOps-Solutions-Immigrate-OpenTSDB-Arch](/img/IT-DevOps-Solutions-Immigrate-OpenTSDB-Arch.jpg "图1. DevOps 场景中典型架构") + +在该应用场景中，包含了部署在应用环境中负责收集机器度量（Metrics）、网络度量（Metrics）以及应用度量（Metrics）的 Agent 工具、汇聚 Agent 收集信息的数据收集器，数据持久化存储和管理的系统以及监控数据可视化工具（例如：Grafana 等）。 + +其中，部署在应用节点的 Agents 负责向 collectd/Statsd 提供不同来源的运行指标，collectd/StatsD 则负责将汇聚的数据推送到 OpenTSDB 集群系统，然后使用可视化看板 Grafana 将数据可视化呈现出来。 + +### 2、迁移服务 + +- **TDengine 安装部署** + +首先是 TDengine 的安装，从官网上下载 TDengine 最新稳定版进行安装。各种安装包的使用帮助请参见博客[《TDengine 多种安装包的安装和卸载》](https://www.taosdata.com/blog/2019/08/09/566.html)。 + +注意，安装完成以后，不要立即启动 `taosd` 服务，在正确配置完成参数以后再启动。 + +- **调整数据收集器配置** + +在 TDengine 2.4 版本中，包含一个组件 taosAdapter。taosAdapter 是一个无状态、可快速弹性伸缩的组件，它可以兼容 Influxdb 的 Line Protocol 和 OpenTSDB 的 telnet/JSON 写入协议规范，提供了丰富的数据接入能力，有效的节省用户迁移成本，降低用户应用迁移的难度。 + +用户可以根据需求弹性部署 taosAdapter 实例，结合场景的需要，快速提升数据写入的吞吐量，为不同应用场景下的数据写入提供保障。 + +通过 taosAdapter，用户可以将 collectd 或 StatsD 收集的数据直接推送到 TDengine ，实现应用场景的无缝迁移，非常的轻松便捷。taosAdapter 还支持 Telegraf、Icinga、TCollector 、node_exporter 的数据接入，使用详情参考[taosAdapter](/reference/taosadapter/)。 + +如果使用 collectd，修改其默认位置 `/etc/collectd/collectd.conf` 的配置文件为指向 taosAdapter 部署的节点 IP 地址和端口。假设 taosAdapter 的 IP 地址为 192.168.1.130，端口为 6046，配置如下： + +```html +LoadPlugin write_tsdb + + + Host "192.168.1.130" Port "6046" HostTags "status=production" StoreRates + false AlwaysAppendDS false + + +``` + +即可让 collectd 将数据使用推送到 OpenTSDB 的插件方式推送到 taosAdapter， taosAdapter 将调用 API 将数据写入到 TDengine 中，从而完成数据的写入工作。如果你使用的是 StatsD 相应地调整配置文件信息。 + +- **调整看板（Dashboard）系统** + +在数据能够正常写入 TDengine 后，可以调整适配 Grafana 将写入 TDengine 的数据可视化呈现出来。获取和使用 TDengine 提供的 Grafana 插件请参考[与其他工具的连接](/third-party/grafana)。 + +TDengine 提供了默认的两套 Dashboard 模板，用户只需要将 Grafana 目录下的模板导入到 Grafana 中即可激活使用。 + +**图 2. 导入 Grafana 模板** +![](/img/IT-DevOps-Solutions-Immigrate-OpenTSDB-Dashboard.jpg "图2. 导入 Grafana 模板") + +操作完以上步骤后，就完成了将 OpenTSDB 替换成为 TDengine 的迁移工作。可以看到整个流程非常简单，不需要写代码，只需要对某些配置文件进行调整即可完成全部的迁移工作。 + +### 3、迁移后架构 + +完成迁移以后，此时的系统整体的架构如下图（图 3）所示，而整个过程中采集端、数据写入端、以及监控呈现端均保持了稳定，除了极少的配置调整外，不涉及任何重要的更改和变动。OpenTSDB 大量的应用场景均为 DevOps ，这种场景下，简单的参数设置即可完成 OpenTSDB 到 TDengine 迁移动作，使用上 TDengine 更加强大的处理能力和查询性能。 + +在绝大多数的 DevOps 场景中，如果你拥有一个小规模的 OpenTSDB 集群（3 台及以下的节点）作为 DevOps 的存储端，依赖于 OpenTSDB 为系统持久化层提供数据存储和查询功能，那么你可以安全地将其替换为 TDengine，并节约更多的计算和存储资源。在同等计算资源配置情况下，单台 TDengine 即可满足 3 ~ 5 台 OpenTSDB 节点提供的服务能力。如果规模比较大，那便需要采用 TDengine 集群。 + +如果你的应用特别复杂，或者应用领域并不是 DevOps 场景，你可以继续阅读后续的章节，更加全面深入地了解将 OpenTSDB 的应用迁移到 TDengine 的高级话题。 + +**图 3. 迁移完成后的系统架构** +![IT-DevOps-Solutions-Immigrate-TDengine-Arch](/img/IT-DevOps-Solutions-Immigrate-TDengine-Arch.jpg "图 3. 迁移完成后的系统架构") + +## 其他场景的迁移评估与策略 + +### 1、TDengine 与 OpenTSDB 的差异 + +本章将详细介绍 OpenTSDB 与 TDengine 在系统功能层面上存在的差异。阅读完本章的内容，你可以全面地评估是否能够将某些基于 OpenTSDB 的复杂应用迁移到 TDengine 上，以及迁移之后应该注意的问题。 + +TDengine 当前只支持 Grafana 的可视化看板呈现，所以如果你的应用中使用了 Grafana 以外的前端看板（例如[TSDash](https://github.com/facebook/tsdash)、[Status Wolf](https://github.com/box/StatusWolf)等），那么前端看板将无法直接迁移到 TDengine，需要将前端看板重新适配到 Grafana 才可以正常运行。 + +在 2.3.0.x 版本中，TDengine 只能够支持 collectd 和 StatsD 作为数据收集汇聚软件，当然后面会陆续提供更多的数据收集聚合软件的接入支持。如果您的收集端使用了其他类型的数据汇聚器，您的应用需要适配到这两个数据汇聚端系统，才能够将数据正常写入。除了上述两个数据汇聚端软件协议以外，TDengine 还支持通过 InfluxDB 的行协议和 OpenTSDB 的数据写入协议、JSON 格式将数据直接写入，您可以重写数据推送端的逻辑，使用 TDengine 支持的行协议来写入数据。 + +此外，如果你的应用中使用了 OpenTSDB 以下特性，在将应用迁移到 TDengine 之前你还需要了解以下注意事项： + +1. `/api/stats`：如果你的应用中使用了该项特性来监控 OpenTSDB 的服务状态，并在应用中建立了相关的逻辑来联动处理，那么这部分状态读取和获取的逻辑需要重新适配到 TDengine。TDengine 提供了全新的处理集群状态监控机制，来满足你的应用对其进行的监控和维护的需求。 +2. `/api/tree`：如果你依赖于 OpenTSDB 的该项特性来进行时间线的层级化组织和维护，那么便无法将其直接迁移至 TDengine。TDengine 采用了数据库->超级表->子表这样的层级来组织和维护时间线，归属于同一个超级表的所有的时间线在系统中同一个层级，但是可以通过不同标签值的特殊构造来模拟应用逻辑上的多级结构。 +3. `Rollup And PreAggregates`：采用了 Rollup 和 PreAggregates 需要应用来决定在合适的地方访问 Rollup 的结果，在某些场景下又要访问原始的结果，这种结构的不透明性让应用处理逻辑变得极为复杂而且完全不具有移植性。我们认为这种策略是时序数据库无法提供高性能聚合情况下的妥协与折中。TDengine 暂不支持多个时间线的自动降采样和（时间段范围的）预聚合，由于 其拥有的高性能查询处理逻辑，即使不依赖于 Rollup 和 （时间段）预聚合计算结果，也能够提供很高性能的查询响应，而且让你的应用查询处理逻辑更加简单。 +4. `Rate`: TDengine 提供了两个计算数值变化率的函数，分别是 Derivative（其计算结果与 InfluxDB 的 Derivative 行为一致）和 IRate（其计算结果与 Prometheus 中的 IRate 函数计算结果一致）。但是这两个函数的计算结果与 Rate 有细微的差别，但整体上功能更强大。此外，**OpenTSDB 提供的所有计算函数，TDengine 均有对应的查询函数支持，并且 TDengine 的查询函数功能远超过 OpenTSDB 支持的查询函数，**可以极大地简化你的应用处理逻辑。 + +通过上面的介绍，相信你应该能够了解 OpenTSDB 迁移到 TDengine 带来的变化，这些信息也有助于你正确地判断是否可以接受将应用 迁移到 TDengine 之上，体验 TDengine 提供的强大的时序数据处理能力和便捷的使用体验。 + +### 2、迁移策略 + +首先将基于 OpenTSDB 的系统进行迁移涉及到的数据模式设计、系统规模估算、数据写入端改造，进行数据分流、应用适配工作；之后将两个系统并行运行一段时间，再将历史数据迁移到 TDengine 中。当然如果你的应用中有部分功能强依赖于上述 OpenTSDB 特性，同时又不希望停止使用，可以考虑保持原有的 OpenTSDB 系统运行，同时启动 TDengine 来提供主要的服务。 + +## 数据模型设计 + +一方面，TDengine 要求其入库的数据具有严格的模式定义。另一方面，TDengine 的数据模型相对于 OpenTSDB 来说又更加丰富，多值模型能够兼容全部的单值模型的建立需求。 + +现在让我们假设一个 DevOps 的场景，我们使用了 collectd 收集设备的基础度量（metrics），包含了 memory 、swap、disk 等几个度量，其在 OpenTSDB 中的模式如下： + +| 序号 | 测量（metric） | 值名称 | 类型 | tag1 | tag2 | tag3 | tag4 | tag5 | +| ---- | -------------- | ------ | ------ | ---- | ----------- | -------------------- | --------- | ------ | +| 1 | memory | value | double | host | memory_type | memory_type_instance | source | n/a | +| 2 | swap | value | double | host | swap_type | swap_type_instance | source | n/a | +| 3 | disk | value | double | host | disk_point | disk_instance | disk_type | source | + +TDengine 要求存储的数据具有数据模式，即写入数据之前需创建超级表并指定超级表的模式。对于数据模式的建立，你有两种方式来完成此项工作：1）充分利用 TDengine 对 OpenTSDB 的数据原生写入的支持，调用 TDengine 提供的 API 将（文本行或 JSON 格式）数据写入，并自动化地建立单值模型。采用这种方式不需要对数据写入应用进行较大的调整，也不需要对写入的数据格式进行转换。 + +在 C 语言层面，TDengine 提供了 `taos_schemaless_insert()` 函数来直接写入 OpenTSDB 格式的数据（在更早版本中该函数名称是 `taos_insert_lines()`）。其代码参考示例请参见安装包目录下示例代码 schemaless.c。 + +2）在充分理解 TDengine 的数据模型基础上，结合生成数据的特点，手动方式建立 OpenTSDB 到 TDengine 的数据模型调整的映射关系。TDengine 能够支持多值模型和单值模型，考虑到 OpenTSDB 均为单值映射模型，这里推荐使用单值模型在 TDengine 中进行建模。 + +- **单值模型**。 + +具体步骤如下：将度量（metrics）的名称作为 TDengine 超级表的名称，该超级表建成后具有两个基础的数据列—时间戳（timestamp）和值（value），超级表的标签等效于 度量 的标签信息，标签数量等同于度量 的标签的数量。子表的表名采用具有固定规则的方式进行命名：`metric + '_' + tags1_value + '_' + tag2_value + '_' + tag3_value ...`作为子表名称。 + +在 TDengine 中建立 3 个超级表： + +```sql +create stable memory(ts timestamp, val float) tags(host binary(12)，memory_type binary(20), memory_type_instance binary(20), source binary(20)); +create stable swap(ts timestamp, val double) tags(host binary(12), swap_type binary(20), swap_type_binary binary(20), source binary(20)); +create stable disk(ts timestamp, val double) tags(host binary(12), disk_point binary(20), disk_instance binary(20), disk_type binary(20), source binary(20)); +``` + +对于子表使用动态建表的方式创建如下所示： + +```sql +insert into memory_vm130_memory_buffered_collectd using memory tags(‘vm130’, ‘memory’, 'buffer', 'collectd') values(1632979445, 3.0656); +``` + +最终系统中会建立 340 个左右的子表，3 个超级表。需要注意的是，如果采用串联标签值的方式导致子表名称超过系统限制（191 字节），那么需要采用一定的编码方式（例如 MD5）将其转化为可接受长度。 + +- **多值模型** + +如果你想要利用 TDengine 的多值模型能力，需要首先满足以下要求：不同的采集量具有相同的采集频率，且能够通过消息队列**同时到达**数据写入端，从而确保使用 SQL 语句将多个指标一次性写入。将度量的名称作为超级表的名称，建立具有相同采集频率且能够同时到达的数据多列模型。子表的表名采用具有固定规则的方式进行命名。上述每个度量均只包含一个测量值，因此无法将其转化为多值模型。 + +## 数据分流与应用适配 + +从消息队列中订阅数据，并启动调整后的写入程序写入数据。 + +数据开始写入持续一段时间后，可以采用 SQL 语句检查写入的数据量是否符合预计的写入要求。统计数据量使用如下 SQL 语句： + +```sql +select count(*) from memory +``` + +完成查询后，如果写入的数据与预期的相比没有差别，同时写入程序本身没有异常的报错信息，那么可用确认数据写入是完整有效的。 + +TDengine 不支持采用 OpenTSDB 的查询语法进行查询或数据获取处理，但是针对 OpenTSDB 的每种查询都提供对应的支持。可以用检查附录 1 获取对应的查询处理的调整和应用使用的方式，如果需要全面了解 TDengine 支持的查询类型，请参阅 TDengine 的用户手册。 + +TDengine 支持标准的 JDBC 3.0 接口操纵数据库，你也可以使用其他类型的高级语言的连接器来查询读取数据，以适配你的应用。具体的操作和使用帮助也请参阅用户手册。 + +## 历史数据迁移 + +### 1、使用工具自动迁移数据 + +为了方便历史数据的迁移工作，我们为数据同步工具 DataX 提供了插件，能够将数据自动写入到 TDengine 中，需要注意的是 DataX 的自动化数据迁移只能够支持单值模型的数据迁移过程。 + +DataX 具体的使用方式及如何使用 DataX 将数据写入 TDengine 请参见[基于 DataX 的 TDengine 数据迁移工具](https://www.taosdata.com/blog/2021/10/26/3156.html)。 + +在对 DataX 进行迁移实践后，我们发现通过启动多个进程，同时迁移多个 metric 的方式，可以大幅度的提高迁移历史数据的效率，下面是迁移过程中的部分记录，希望这些能为应用迁移工作带来参考。 + +| DataX 实例个数 (并发进程个数) | 迁移记录速度 （条/秒) | +| ----------------------------- | --------------------- | +| 1 | 约 13.9 万 | +| 2 | 约 21.8 万 | +| 3 | 约 24.9 万 | +| 5 | 约 29.5 万 | +| 10 | 约 33 万 | + +
（注：测试数据源自 单节点 Intel(R) Core(TM) i7-10700 CPU@2.90GHz 16 核 64G 硬件设备，channel 和 batchSize 分别为 8 和 1000，每条记录包含 10 个 tag) + +### 2、手动迁移数据 + +如果你需要使用多值模型进行数据写入，就需要自行开发一个将数据从 OpenTSDB 导出的工具，然后确认哪些时间线能够合并导入到同一个时间线，再将可以同时导入的时间通过 SQL 语句的写入到数据库中。 + +手动迁移数据需要注意以下两个问题： + +1）在磁盘中存储导出数据时，磁盘需要有足够的存储空间以便能够充分容纳导出的数据文件。为了避免全量数据导出后导致磁盘文件存储紧张，可以采用部分导入的模式，对于归属于同一个超级表的时间线优先导出，然后将导出部分的数据文件导入到 TDengine 系统中。 + +2）在系统全负载运行下，如果有足够的剩余计算和 IO 资源，可以建立多线程的导入机制，最大限度地提升数据迁移的效率。考虑到数据解析对于 CPU 带来的巨大负载，需要控制最大的并行任务数量，以避免因导入历史数据而触发的系统整体过载。 + +由于 TDengine 本身操作简易性，所以不需要在整个过程中进行索引维护、数据格式的变化处理等工作，整个过程只需要顺序执行即可。 + +当历史数据完全导入到 TDengine 以后，此时两个系统处于同时运行的状态，之后便可以将查询请求切换到 TDengine 上，从而实现无缝的应用切换。 + +## 附录 1: OpenTSDB 查询函数对应表 + +### Avg + +等效函数：avg + +示例： + +```sql +SELECT avg(val) FROM (SELECT first(val) FROM super_table WHERE ts >= startTime and ts <= endTime INTERVAL(20s) Fill(linear)) INTERVAL(20s) +``` + +备注： + +1. Interval 内的数值与外层查询的 interval 数值需要相同。 +2. 在 TDengine 中插值处理需要使用子查询来协助完成，如上所示，在内层查询中指明插值类型即可，由于 OpenTSDB 中数值的插值使用了线性插值，因此在插值子句中使用 fill(linear) 来声明插值类型。以下有相同插值计算需求的函数，均采用该方法处理。 +3. Interval 中参数 20s 表示将内层查询按照 20 秒一个时间窗口生成结果。在真实的查询中，需要调整为不同的记录之间的时间间隔。这样可确保等效于原始数据生成了插值结果。 +4. 由于 OpenTSDB 特殊的插值策略和机制，聚合查询（Aggregate）中先插值再计算的方式导致其计算结果与 TDengine 不可能完全一致。但是在降采样（Downsample）的情况下，TDengine 和 OpenTSDB 能够获得一致的结果（由于 OpenTSDB 在聚合查询和降采样查询中采用了完全不同的插值策略）。 + +### Count + +等效函数：count + +示例： + +```sql +select count(\*) from super_table_name; +``` + +### Dev + +等效函数：stddev + +示例： + +```sql +Select stddev(val) from table_name +``` + +### Estimated percentiles + +等效函数：apercentile + +示例： + +```sql +Select apercentile(col1, 50, “t-digest”) from table_name +``` + +备注： + +1. 近似查询处理过程中，OpenTSDB 默认采用 t-digest 算法，所以为了获得相同的计算结果，需要在 apercentile 函数中指明使用的算法。TDengine 能够支持两种不同的近似处理算法，分别通过“default”和“t-digest”来声明。 +### First + +等效函数：first + +示例： + +```sql +Select first(col1) from table_name +``` + +### Last + +等效函数：last + +示例： + +```sql +Select last(col1) from table_name +``` + +### Max + +等效函数：max + +示例： + +```sql +Select max(value) from (select first(val) value from table_name interval(10s) fill(linear)) interval(10s) +``` + +备注：Max 函数需要插值，原因见上。 + +### Min + +等效函数：min + +示例： + +```sql +Select min(value) from (select first(val) value from table_name interval(10s) fill(linear)) interval(10s); +``` + +### MinMax + +等效函数：max + +```sql +Select max(val) from table_name +``` + +备注：该函数无插值需求，因此可用直接计算。 + +### MimMin + +等效函数：min + +```sql +Select min(val) from table_name +``` + +备注：该函数无插值需求，因此可用直接计算。 + +### Percentile + +等效函数：percentile + +备注： + +### Sum + +等效函数：sum + +```sql +Select max(value) from (select first(val) value from table_name interval(10s) fill(linear)) interval(10s) +``` + +备注：该函数无插值需求，因此可用直接计算。 + +### Zimsum + +等效函数：sum + +```sql +Select sum(val) from table_name +``` + +备注：该函数无插值需求，因此可用直接计算。 + +完整示例： + +```json +// OpenTSDB 查询 JSON +query = { +“start”:1510560000, +“end”: 1515000009, +“queries”:[{ +“aggregator”: “count”, +“metric”:”cpu.usage_user”, +}] +} + +//等效查询 SQL: +SELECT count(*) +FROM `cpu.usage_user` +WHERE ts>=1510560000 AND ts<=1515000009 +``` + +## 附录 2: 资源估算方法 + +### 数据生成环境 + +我们仍然使用第 4 章中的假设环境，3 个测量值。分别是：温度和湿度的数据写入的速率是每 5 秒一条记录，时间线 10 万个。空气质量的写入速率是 10 秒一条记录，时间线 1 万个，查询的请求频率 500 QPS。 + +### 存储资源估算 + +假设产生数据并需要存储的传感器设备数量为 `n`，数据生成的频率为`t`条/秒，每条记录的长度为 `L` bytes，则每天产生的数据规模为 `n×t×L` bytes。假设压缩比为 C，则每日产生数据规模为 `(n×t×L)/C` bytes。存储资源预估为能够容纳 1.5 年的数据规模，生产环境下 TDengine 的压缩比 C 一般在 5 ~ 7 之间，同时为最后结果增加 20% 的冗余，可计算得到需要存储资源： + +```matlab +(n×t×L)×(365×1.5)×(1+20%)/C +``` + +结合以上的计算公式，将参数带入计算公式，在不考虑标签信息的情况下，每年产生的原始数据规模是 11.8TB。需要注意的是，由于标签信息在 TDengine 中关联到每个时间线，并不是每条记录。所以需要记录的数据量规模相对于产生的数据有一定的降低，而这部分标签数据整体上可以忽略不记。假设压缩比为 5，则保留的数据规模最终为 2.56 TB。 + +### 存储设备选型考虑 + +硬盘应该选用具有较好随机读性能的硬盘设备，如果能够有 SSD，尽可能考虑使用 SSD。较好的随机读性能的磁盘对于提升系统查询性能具有极大的帮助，能够整体上提升系统的查询响应性能。为了获得较好的查询性能，硬盘设备的单线程随机读 IOPS 的性能指标不应该低于 1000，能够达到 5000 IOPS 以上为佳。为了获得当前的设备随机读取的 IO 性能的评估，建议使用 `fio` 软件对其进行运行性能评估（具体的使用方式请参阅附录 1），确认其是否能够满足大文件随机读性能要求。 + +硬盘写性能对于 TDengine 的影响不大。TDengine 写入过程采用了追加写的模式，所以只要有较好的顺序写性能即可，一般意义上的 SAS 硬盘和 SSD 均能够很好地满足 TDengine 对于磁盘写入性能的要求。 + +### 计算资源估算 + +由于物联网数据的特殊性，数据产生的频率固定以后，TDengine 写入的过程对于（计算和存储）资源消耗都保持一个相对固定的量。《[TDengine 运维指南](/operation/)》上的描述，该系统中每秒 22000 个写入，消耗 CPU 不到 1 个核。 + +在针对查询所需要消耗的 CPU 资源的估算上，假设应用要求数据库提供的 QPS 为 10000，每次查询消耗的 CPU 时间约 1 ms，那么每个核每秒提供的查询为 1000 QPS，满足 10000 QPS 的查询请求，至少需要 10 个核。为了让系统整体上 CPU 负载小于 50%，整个集群需要 10 个核的两倍，即 20 个核。 + +### 内存资源估算 + +数据库默认为每个 Vnode 分配内存 16MB\*3 缓冲区，集群系统包括 22 个 CPU 核，则默认会建立 22 个虚拟节点 Vnode，每个 Vnode 包含 1000 张表，则可以容纳所有的表。则约 1 个半小时写满一个 block，从而触发落盘，可以不做调整。22 个 Vnode 共计需要内存缓存约 1GB。考虑到查询所需要的内存，假设每次查询的内存开销约 50MB，则 500 个查询并发需要的内存约 25GB。 + +综上所述，可使用单台 16 核 32GB 的机器，或者使用 2 台 8 核 16GB 机器构成的集群。 + +## 附录 3: 集群部署及启动 + +TDengine 提供了丰富的帮助文档说明集群安装、部署的诸多方面的内容，这里提供相应的文档列表，供你参考。 + +### 集群部署 + +首先是安装 TDengine，从官网上下载 TDengine 最新稳定版，解压缩后运行 install.sh 进行安装。各种安装包的使用帮助请参见博客[《TDengine 多种安装包的安装和卸载》](https://www.taosdata.com/blog/2019/08/09/566.html)。 + +注意安装完成以后，不要立即启动 `taosd` 服务，在正确配置完成参数以后才启动 `taosd` 服务。 + +### 设置运行参数并启动服务 + +为确保系统能够正常获取运行的必要信息。请在服务端正确设置以下关键参数： + +FQDN、firstEp、secondEP、dataDir、logDir、tmpDir、serverPort。各参数的具体含义及设置的要求，可参见文档《[TDengine 集群安装、管理](/cluster/)》 + +按照相同的步骤，在需要运行的节点上设置参数，并启动 `taosd` 服务，然后添加 Dnode 到集群中。 + +最后启动 `taos` 命令行程序，执行命令 `show dnodes`，如果能看到所有的加入集群的节点，那么集群顺利搭建完成。具体的操作流程及注意事项，请参阅文档《[TDengine 集群安装、管理](/cluster/)》 + +## 附录 4: 超级表名称 + +由于 OpenTSDB 的 metric 名称中带有点号（“.”），例如“cpu.usage_user”这种名称的 metric。但是点号在 TDengine 中具有特殊含义，是用来分隔数据库和表名称的分隔符。TDengine 也提供转义符，以允许用户在（超级）表名称中使用关键词或特殊分隔符（如：点号）。为了使用特殊字符，需要采用转义字符将表的名称括起来，例如：`cpu.usage_user`这样就是合法的（超级）表名称。 + +## 附录 5：参考文章 + +1. [使用 TDengine + collectd/StatsD + Grafana 快速搭建 IT 运维监控系统](/application/collectd/) +2. [通过 collectd 将采集数据直接写入 TDengine](/third-party/collectd/) diff --git a/docs-cn/25-application/_category_.yml b/docs-cn/25-application/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..f43a4601b6c269822cbc0de1b7ed99dfdc70cfe5 --- /dev/null +++ b/docs-cn/25-application/_category_.yml @@ -0,0 +1 @@ +label: 应用实践 diff --git a/docs-cn/25-application/index.md b/docs-cn/25-application/index.md new file mode 100644 index 0000000000000000000000000000000000000000..1305cf230f78b68f988918921540a1df05f0931f --- /dev/null +++ b/docs-cn/25-application/index.md @@ -0,0 +1,10 @@ +--- +title: 应用实践 +--- + +```mdx-code-block +import DocCardList from '@theme/DocCardList'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + + +``` \ No newline at end of file diff --git a/docs-cn/27-train-faq/01-faq.md b/docs-cn/27-train-faq/01-faq.md new file mode 100644 index 0000000000000000000000000000000000000000..0ceae1fa490d99a1d9e55454d0c0c49ec1b384e6 --- /dev/null +++ b/docs-cn/27-train-faq/01-faq.md @@ -0,0 +1,195 @@ +--- +title: 常见问题及反馈 +--- + +## 问题反馈 + +如果 FAQ 中的信息不能够帮到您，需要 TDengine 技术团队的技术支持与协助，请将以下两个目录中内容打包： + +1. /var/log/taos （如果没有修改过默认路径） +2. /etc/taos + +附上必要的问题描述，包括使用的 TDengine 版本信息、平台环境信息、发生该问题的执行操作、出现问题的表征及大概的时间，在 [GitHub](https://github.com/taosdata/TDengine) 提交 issue。 + +为了保证有足够的 debug 信息，如果问题能够重复，请修改/etc/taos/taos.cfg 文件，最后面添加一行“debugFlag 135"(不带引号本身），然后重启 taosd, 重复问题，然后再递交。也可以通过如下 SQL 语句，临时设置 taosd 的日志级别。 + +``` + alter dnode debugFlag 135; +``` + +但系统正常运行时，请一定将 debugFlag 设置为 131，否则会产生大量的日志信息，降低系统效率。 + +## 常见问题列表 + +### 1. TDengine2.0 之前的版本升级到 2.0 及以上的版本应该注意什么？☆☆☆ + +2.0 版在之前版本的基础上，进行了完全的重构，配置文件和数据文件是不兼容的。在升级之前务必进行如下操作： + +1. 删除配置文件，执行 `sudo rm -rf /etc/taos/taos.cfg` +2. 删除日志文件，执行 `sudo rm -rf /var/log/taos/` +3. 确保数据已经不再需要的前提下，删除数据文件，执行 `sudo rm -rf /var/lib/taos/` +4. 安装最新稳定版本的 TDengine +5. 如果需要迁移数据或者数据文件损坏，请联系涛思数据官方技术支持团队，进行协助解决 + +### 2. Windows 平台下 JDBCDriver 找不到动态链接库，怎么办？ + +请看为此问题撰写的[技术博客](https://www.taosdata.com/blog/2019/12/03/950.html)。 + +### 3. 创建数据表时提示 more dnodes are needed + +请看为此问题撰写的[技术博客](https://www.taosdata.com/blog/2019/12/03/965.html)。 + +### 4. 如何让 TDengine crash 时生成 core 文件？ + +请看为此问题撰写的[技术博客](https://www.taosdata.com/blog/2019/12/06/974.html)。 + +### 5. 遇到错误“Unable to establish connection” 怎么办？ + +客户端遇到连接故障，请按照下面的步骤进行检查： + +1. 检查网络环境 + + - 云服务器：检查云服务器的安全组是否打开 TCP/UDP 端口 6030-6042 的访问权限 + - 本地虚拟机：检查网络能否 ping 通，尽量避免使用`localhost` 作为 hostname + - 公司服务器：如果为 NAT 网络环境，请务必检查服务器能否将消息返回值客户端 + +2. 确保客户端与服务端版本号是完全一致的，开源社区版和企业版也不能混用 + +3. 在服务器，执行 `systemctl status taosd` 检查*taosd*运行状态。如果没有运行，启动*taosd* + +4. 确认客户端连接时指定了正确的服务器 FQDN (Fully Qualified Domain Name —— 可在服务器上执行 Linux 命令 hostname -f 获得），FQDN 配置参考：[一篇文章说清楚 TDengine 的 FQDN](https://www.taosdata.com/blog/2020/09/11/1824.html)。 + +5. ping 服务器 FQDN，如果没有反应，请检查你的网络，DNS 设置，或客户端所在计算机的系统 hosts 文件。如果部署的是 TDengine 集群，客户端需要能 ping 通所有集群节点的 FQDN。 + +6. 检查防火墙设置（Ubuntu 使用 ufw status，CentOS 使用 firewall-cmd --list-port），确认 TCP/UDP 端口 6030-6042 是打开的 + +7. 对于 Linux 上的 JDBC（ODBC, Python, Go 等接口类似）连接, 确保*libtaos.so*在目录*/usr/local/taos/driver*里, 并且*/usr/local/taos/driver*在系统库函数搜索路径*LD_LIBRARY_PATH*里 + +8. 对于 Windows 上的 JDBC, ODBC, Python, Go 等连接，确保*C:\TDengine\driver\taos.dll*在你的系统库函数搜索目录里 (建议*taos.dll*放在目录 _C:\Windows\System32_) + +9. 如果仍不能排除连接故障 + + - Linux 系统请使用命令行工具 nc 来分别判断指定端口的 TCP 和 UDP 连接是否通畅 + 检查 UDP 端口连接是否工作：`nc -vuz {hostIP} {port} ` + 检查服务器侧 TCP 端口连接是否工作：`nc -l {port}` + 检查客户端侧 TCP 端口连接是否工作：`nc {hostIP} {port}` + + - Windows 系统请使用 PowerShell 命令 Net-TestConnection -ComputerName {fqdn} -Port {port} 检测服务段端口是否访问 + +10. 也可以使用 taos 程序内嵌的网络连通检测功能，来验证服务器和客户端之间指定的端口连接是否通畅（包括 TCP 和 UDP）：[TDengine 内嵌网络检测工具使用指南](https://www.taosdata.com/blog/2020/09/08/1816.html)。 + +### 6. 遇到错误 “Unexpected generic error in RPC”或者“Unable to resolve FQDN” 怎么办？ + +产生这个错误，是由于客户端或数据节点无法解析 FQDN(Fully Qualified Domain Name)导致。对于 TAOS Shell 或客户端应用，请做如下检查： + +1. 请检查连接的服务器的 FQDN 是否正确，FQDN 配置参考：[一篇文章说清楚 TDengine 的 FQDN](https://www.taosdata.com/blog/2020/09/11/1824.html) +2. 如果网络配置有 DNS server，请检查是否正常工作 +3. 如果网络没有配置 DNS server，请检查客户端所在机器的 hosts 文件，查看该 FQDN 是否配置，并是否有正确的 IP 地址 +4. 如果网络配置 OK，从客户端所在机器，你需要能 Ping 该连接的 FQDN，否则客户端是无法连接服务器的 +5. 如果服务器曾经使用过 TDengine，且更改过 hostname，建议检查 data 目录的 dnodeEps.json 是否符合当前配置的 EP，路径默认为/var/lib/taos/dnode。正常情况下，建议更换新的数据目录或者备份后删除以前的数据目录，这样可以避免该问题。 +6. 检查/etc/hosts 和/etc/hostname 是否是预配置的 FQDN + +### 7. 虽然语法正确，为什么我还是得到 "Invalid SQL" 错误？ + +如果你确认语法正确，2.0 之前版本，请检查 SQL 语句长度是否超过 64K。如果超过，也会返回这个错误。 + +### 8. 是否支持 validation queries？ + +TDengine 还没有一组专用的 validation queries。然而建议你使用系统监测的数据库”log"来做。 + + + +### 9. 我可以删除或更新一条记录吗？ + +TDengine 目前尚不支持删除功能，未来根据用户需求可能会支持。 + +从 2.0.8.0 开始，TDengine 支持更新已经写入数据的功能。使用更新功能需要在创建数据库时使用 UPDATE 1 参数，之后可以使用 INSERT INTO 命令更新已经写入的相同时间戳数据。UPDATE 参数不支持 ALTER DATABASE 命令修改。没有使用 UPDATE 1 参数创建的数据库，写入相同时间戳的数据不会修改之前的数据，也不会报错。 + +另需注意，在 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 列。） + +### 11. 最有效的写入数据的方法是什么？ + +批量插入。每条写入语句可以一张表同时插入多条记录，也可以同时插入多张表的多条记录。 + +### 12. Windows 系统下插入的 nchar 类数据中的汉字被解析成了乱码如何解决？ + +Windows 下插入 nchar 类的数据中如果有中文，请先确认系统的地区设置成了中国（在 Control Panel 里可以设置），这时 cmd 中的`taos`客户端应该已经可以正常工作了；如果是在 IDE 里开发 Java 应用，比如 Eclipse， IntelliJ，请确认 IDE 里的文件编码为 GBK（这是 Java 默认的编码类型），然后在生成 Connection 时，初始化客户端的配置，具体语句如下： + +```JAVA +Class.forName("com.taosdata.jdbc.TSDBDriver"); +Properties properties = new Properties(); +properties.setProperty(TSDBDriver.LOCALE_KEY, "UTF-8"); +Connection = DriverManager.getConnection(url, properties); +``` + +### 13.JDBC 报错： the executed SQL is not a DML or a DDL？ + +请更新至最新的 JDBC 驱动，参考 [Java 连接器](/reference/connector/java) + +### 14. taos connect failed, reason: invalid timestamp + +常见原因是服务器和客户端时间没有校准，可以通过和时间服务器同步的方式（Linux 下使用 ntpdate 命令，Windows 在系统时间设置中选择自动同步）校准。 + +### 15. 表名显示不全 + +由于 taos shell 在终端中显示宽度有限，有可能比较长的表名显示不全，如果按照显示的不全的表名进行相关操作会发生 Table does not exist 错误。解决方法可以是通过修改 taos.cfg 文件中的设置项 maxBinaryDisplayWidth， 或者直接输入命令 set max_binary_display_width 100。或者在命令结尾使用 \G 参数来调整结果的显示方式。 + +### 16. 如何进行数据迁移？ + +TDengine 是根据 hostname 唯一标志一台机器的，在数据文件从机器 A 移动机器 B 时，注意如下两件事： + + - 2.0.0.0 至 2.0.6.x 的版本，重新配置机器 B 的 hostname 为机器 A 的 hostname。 + - 2.0.7.0 及以后的版本，到/var/lib/taos/dnode 下，修复 dnodeEps.json 的 dnodeId 对应的 FQDN，重启。确保机器内所有机器的此文件是完全相同的。 + - 1.x 和 2.x 版本的存储结构不兼容，需要使用迁移工具或者自己开发应用导出导入数据。 + +### 17. 如何在命令行程序 taos 中临时调整日志级别 + +为了调试方便，从 2.0.16 版本开始，命令行程序 taos 新增了与日志记录相关的两条指令： + +```sql +ALTER LOCAL flag_name flag_value; +``` + +其含义是，在当前的命令行程序下，修改一个特定模块的日志记录级别（只对当前命令行程序有效，如果 taos 命令行程序重启，则需要重新设置）： + + - flag_name 的取值可以是：debugFlag，cDebugFlag，tmrDebugFlag，uDebugFlag，rpcDebugFlag + - flag_value 的取值可以是：131（输出错误和警告日志），135（ 输出错误、警告和调试日志），143（ 输出错误、警告、调试和跟踪日志） + +```sql +ALTER LOCAL RESETLOG; +``` + +其含义是，清空本机所有由客户端生成的日志文件。 + + + +### 18. go 语言编写组件编译失败怎样解决？ + +TDengine 2.3.0.0 及之后的版本包含一个使用 go 语言开发的 taosAdapter 独立组件，需要单独运行，取代之前 taosd 内置的 httpd ，提供包含原 httpd 功能以及支持多种其他软件（Prometheus、Telegraf、collectd、StatsD 等）的数据接入功能。 +使用最新 develop 分支代码编译需要先 `git submodule update --init --recursive` 下载 taosAdapter 仓库代码后再编译。 + +目前编译方式默认自动编译 taosAdapter。go 语言版本要求 1.14 以上，如果发生 go 编译错误，往往是国内访问 go mod 问题，可以通过设置 go 环境变量来解决： + +```sh +go env -w GO111MODULE=on +go env -w GOPROXY=https://goproxy.cn,direct +``` + +如果希望继续使用之前的内置 httpd，可以关闭 taosAdapter 编译，使用 +`cmake .. -DBUILD_HTTP=true` 使用原来内置的 httpd。 + +### 19. 如何查询数据占用的存储空间大小？ + +默认情况下，TDengine 的数据文件存储在 /var/lib/taos ，日志文件存储在 /var/log/taos 。 + +若想查看所有数据文件占用的具体大小，可以执行 Shell 指令：`du -sh /var/lib/taos/vnode --exclude='wal'` 来查看。此处排除了 WAL 目录，因为在持续写入的情况下，这里大小几乎是固定的，并且每当正常关闭 TDengine 让数据落盘后，WAL 目录都会清空。 + +若想查看单个数据库占用的大小，可在命令行程序 taos 内指定要查看的数据库后执行 `show vgroups;` ，通过得到的 VGroup id 去 /var/lib/taos/vnode 下查看包含的文件夹大小。 + +若仅仅想查看指定（超级）表的数据块分布及大小，可查看[_block_dist 函数](https://docs.taosdata.com/taos-sql/select/#_block_dist-%E5%87%BD%E6%95%B0) diff --git a/docs-cn/27-train-faq/02-video.mdx b/docs-cn/27-train-faq/02-video.mdx new file mode 100644 index 0000000000000000000000000000000000000000..b644412332fe817ea7fdc2c9ddc176ecc9858c56 --- /dev/null +++ b/docs-cn/27-train-faq/02-video.mdx @@ -0,0 +1,25 @@ +--- +title: 视频教程 +--- + +## 技术公开课 + +- [技术公开课：开源、高效的物联网大数据平台，TDengine 内核技术剖析](https://www.taosdata.com/blog/2020/12/25/2126.html) + +## 视频教程 + +- [TDengine 视频教程 - 快速上手](https://www.taosdata.com/blog/2020/11/11/1941.html) +- [TDengine 视频教程 - 数据建模](https://www.taosdata.com/blog/2020/11/11/1945.html) +- [TDengine 视频教程 - 集群搭建](https://www.taosdata.com/blog/2020/11/11/1961.html) +- [TDengine 视频教程 - Go Connector](https://www.taosdata.com/blog/2020/11/11/1951.html) +- [TDengine 视频教程 - JDBC Connector](https://www.taosdata.com/blog/2020/11/11/1955.html) +- [TDengine 视频教程 - Node.js Connector](https://www.taosdata.com/blog/2020/11/11/1957.html) +- [TDengine 视频教程 - Python Connector](https://www.taosdata.com/blog/2020/11/11/1963.html) +- [TDengine 视频教程 - RESTful Connector](https://www.taosdata.com/blog/2020/11/11/1965.html) +- [TDengine 视频教程 - “零”代码运维监控](https://www.taosdata.com/blog/2020/11/11/1959.html) + +## 微课堂 + +关注 TDengine 视频号， 有精心制作的微课堂。 + + diff --git a/docs-cn/27-train-faq/03-docker.md b/docs-cn/27-train-faq/03-docker.md new file mode 100644 index 0000000000000000000000000000000000000000..845a8751846c0995a43fb1c01e6ace3080176838 --- /dev/null +++ b/docs-cn/27-train-faq/03-docker.md @@ -0,0 +1,330 @@ +--- +title: 通过 Docker 快速体验 TDengine +--- + +虽然并不推荐在生产环境中通过 Docker 来部署 TDengine 服务，但 Docker 工具能够很好地屏蔽底层操作系统的环境差异，很适合在开发测试或初次体验时用于安装运行 TDengine 的工具集。特别是，借助 Docker，能够比较方便地在 macOS 和 Windows 系统上尝试 TDengine，而无需安装虚拟机或额外租用 Linux 服务器。另外，从 2.0.14.0 版本开始，TDengine 提供的镜像已经可以同时支持 X86-64、X86、arm64、arm32 平台，像 NAS、树莓派、嵌入式开发板之类可以运行 docker 的非主流计算机也可以基于本文档轻松体验 TDengine。 + +下文通过 Step by Step 风格的介绍，讲解如何通过 Docker 快速建立 TDengine 的单节点运行环境，以支持开发和测试。 + +## 下载 Docker + +Docker 工具自身的下载请参考 [Docker 官网文档](https://docs.docker.com/get-docker/)。 + +安装完毕后可以在命令行终端查看 Docker 版本。如果版本号正常输出，则说明 Docker 环境已经安装成功。 + +```bash +$ docker -v +Docker version 20.10.3, build 48d30b5 +``` + +## 使用 Docker 在容器中运行 TDengine + +### 在 Docker 容器中运行 TDengine server + +```bash +$ docker run -d -p 6030-6049:6030-6049 -p 6030-6049:6030-6049/udp tdengine/tdengine +526aa188da767ae94b244226a2b2eec2b5f17dd8eff592893d9ec0cd0f3a1ccd +``` + +这条命令，启动一个运行了 TDengine server 的 docker 容器，并且将容器的 6030 到 6049 端口映射到宿主机的 6030 到 6049 端口上。如果宿主机已经运行了 TDengine server 并占用了相同端口，需要映射容器的端口到不同的未使用端口段。（详情参见 [TDengine 2.0 端口说明](/train-faq/faq#port）。为了支持 TDengine 客户端操作 TDengine server 服务， TCP 和 UDP 端口都需要打开。 + +- **docker run**：通过 Docker 运行一个容器 +- **-d**：让容器在后台运行 +- **-p**：指定映射端口。注意：如果不是用端口映射，依然可以进入 Docker 容器内部使用 TDengine 服务或进行应用开发，只是不能对容器外部提供服务 +- **tdengine/tdengine**：拉取的 TDengine 官方发布的应用镜像 +- **526aa188da767ae94b244226a2b2eec2b5f17dd8eff592893d9ec0cd0f3a1ccd**：这个返回的长字符是容器 ID，我们也可以通过容器 ID 来查看对应的容器 + +进一步，还可以使用 docker run 命令启动运行 TDengine server 的 docker 容器，并使用 `--name` 命令行参数将容器命名为 `tdengine`，使用 `--hostname` 指定 hostname 为 `tdengine-server`，通过 `-v` 挂载本地目录到容器，实现宿主机与容器内部的数据同步，防止容器删除后，数据丢失。 + +```bash +docker run -d --name tdengine --hostname="tdengine-server" -v ~/work/taos/log:/var/log/taos -v ~/work/taos/data:/var/lib/taos -p 6030-6049:6030-6049 -p 6030-6049:6030-6049/udp tdengine/tdengine +``` + +- **--name tdengine**：设置容器名称，我们可以通过容器名称来访问对应的容器 +- **--hostname=tdengine-server**：设置容器内 Linux 系统的 hostname，我们可以通过映射 hostname 和 IP 来解决容器 IP 可能变化的问题。 +- **-v**：设置宿主机文件目录映射到容器内目录，避免容器删除后数据丢失。 + +### 使用 docker ps 命令确认容器是否已经正确运行 + +```bash +docker ps +``` + +输出示例如下： + +``` +CONTAINER ID IMAGE COMMAND CREATED STATUS ··· +c452519b0f9b tdengine/tdengine "taosd" 14 minutes ago Up 14 minutes ··· +``` + +- **docker ps**：列出所有正在运行状态的容器信息。 +- **CONTAINER ID**：容器 ID。 +- **IMAGE**：使用的镜像。 +- **COMMAND**：启动容器时运行的命令。 +- **CREATED**：容器创建时间。 +- **STATUS**：容器状态。UP 表示运行中。 + +### 通过 docker exec 命令，进入到 docker 容器中去做开发 + +```bash +$ docker exec -it tdengine /bin/bash +root@tdengine-server:~/TDengine-server-2.4.0.4# +``` + +- **docker exec**：通过 docker exec 命令进入容器，如果退出，容器不会停止。 +- **-i**：进入交互模式。 +- **-t**：指定一个终端。 +- **tdengine**：容器名称，需要根据 docker ps 指令返回的值进行修改。 +- **/bin/bash**：载入容器后运行 bash 来进行交互。 + +进入容器后，执行 taos shell 客户端程序。 + +```bash +root@tdengine-server:~/TDengine-server-2.4.0.4# taos + +Welcome to the TDengine shell from Linux, Client Version:2.4.0.4 +Copyright (c) 2020 by TAOS Data, Inc. All rights reserved. + +taos> +``` + +TDengine 终端成功连接服务端，打印出了欢迎消息和版本信息。如果失败，会有错误信息打印出来。 + +在 TDengine 终端中，可以通过 SQL 命令来创建/删除数据库、表、超级表等，并可以进行插入和查询操作。具体可以参考 [TAOS SQL 说明文档](/taos-sql/)。 + +### 在宿主机访问 Docker 容器中的 TDengine server + +在使用了 -p 命令行参数映射了正确的端口启动了 TDengine Docker 容器后，就在宿主机使用 taos shell 命令即可访问运行在 Docker 容器中的 TDengine。 + +``` +$ taos + +Welcome to the TDengine shell from Linux, Client Version:2.4.0.4 +Copyright (c) 2020 by TAOS Data, Inc. All rights reserved. + +taos> +``` + +也可以在宿主机使用 curl 通过 RESTful 端口访问 Docker 容器内的 TDengine server。 + +``` +curl -u root:taosdata -d 'show databases' 127.0.0.1:6041/rest/sql +``` + +输出示例如下： + +``` +{"status":"succ","head":["name","created_time","ntables","vgroups","replica","quorum","days","keep0,keep1,keep(D)","cache(MB)","blocks","minrows","maxrows","wallevel","fsync","comp","cachelast","precision","update","status"],"column_meta":[["name",8,32],["created_time",9,8],["ntables",4,4],["vgroups",4,4],["replica",3,2],["quorum",3,2],["days",3,2],["keep0,keep1,keep(D)",8,24],["cache(MB)",4,4],["blocks",4,4],["minrows",4,4],["maxrows",4,4],["wallevel",2,1],["fsync",4,4],["comp",2,1],["cachelast",2,1],["precision",8,3],["update",2,1],["status",8,10]],"data":[["test","2021-08-18 06:01:11.021",10000,4,1,1,10,"3650,3650,3650",16,6,100,4096,1,3000,2,0,"ms",0,"ready"],["log","2021-08-18 05:51:51.065",4,1,1,1,10,"30,30,30",1,3,100,4096,1,3000,2,0,"us",0,"ready"]],"rows":2} +``` + +这条命令，通过 REST API 访问 TDengine server，这时连接的是本机的 6041 端口，可见连接成功。 + +TDengine REST API 详情请参考[官方文档](/reference/rest-api/)。 + +### 使用 Docker 容器运行 TDengine server 和 taosAdapter + +在 TDengine 2.4.0.0 之后版本的 Docker 容器，开始提供一个独立运行的组件 taosAdapter，代替之前版本 TDengine 中 taosd 进程中内置的 http server。taosAdapter 支持通过 RESTful 接口对 TDengine server 的数据写入和查询能力，并提供和 InfluxDB/OpenTSDB 兼容的数据摄取接口，允许 InfluxDB/OpenTSDB 应用程序无缝移植到 TDengine。在新版本 Docker 镜像中，默认启用了 taosAdapter，也可以使用 docker run 命令中设置 TAOS_DISABLE_ADAPTER=true 来禁用 taosAdapter；也可以在 docker run 命令中单独使用 taosAdapter，而不运行 taosd 。 + +注意：如果容器中运行 taosAdapter，需要根据需要映射其他端口，具体端口默认配置和修改方法请参考[taosAdapter 文档](/reference/taosadapter/)。 + +使用 docker 运行 TDengine 2.4.0.4 版本镜像（taosd + taosAdapter）： + +```bash +docker run -d --name tdengine-all -p 6030-6049:6030-6049 -p 6030-6049:6030-6049/udp tdengine/tdengine:2.4.0.4 +``` + +使用 docker 运行 TDengine 2.4.0.4 版本镜像（仅 taosAdapter，需要设置 firstEp 配置项 或 TAOS_FIRST_EP 环境变量）： + +```bash +docker run -d --name tdengine-taosa -p 6041-6049:6041-6049 -p 6041-6049:6041-6049/udp -e TAOS_FIRST_EP=tdengine-all tdengine/tdengine:2.4.0.4 taosadapter +``` + +使用 docker 运行 TDengine 2.4.0.4 版本镜像（仅 taosd）： + +```bash +docker run -d --name tdengine-taosd -p 6030-6042:6030-6042 -p 6030-6042:6030-6042/udp -e TAOS_DISABLE_ADAPTER=true tdengine/tdengine:2.4.0.4 +``` + +使用 curl 命令验证 RESTful 接口可以正常工作： + +```bash +curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'show databases;' 127.0.0.1:6041/rest/sql +``` + +输出示例如下： + +``` +{"status":"succ","head":["name","created_time","ntables","vgroups","replica","quorum","days","keep","cache(MB)","blocks","minrows","maxrows","wallevel","fsync","comp","cachelast","precision","update","status"],"column_meta":[["name",8,32],["created_time",9,8],["ntables",4,4],["vgroups",4,4],["replica",3,2],["quorum",3,2],["days",3,2],["keep",8,24],["cache(MB)",4,4],["blocks",4,4],["minrows",4,4],["maxrows",4,4],["wallevel",2,1],["fsync",4,4],["comp",2,1],["cachelast",2,1],["precision",8,3],["update",2,1],["status",8,10]],"data":[["log","2021-12-28 09:18:55.765",10,1,1,1,10,"30",1,3,100,4096,1,3000,2,0,"us",0,"ready"]],"rows":1} +``` + +### 应用示例：在宿主机使用 taosBenchmark 写入数据到 Docker 容器中的 TDengine server + +1. 在宿主机命令行界面执行 taosBenchmark （曾命名为 taosdemo）写入数据到 Docker 容器中的 TDengine server + + ```bash + $ taosBenchmark + + taosBenchmark is simulating data generated by power equipments monitoring... + + host: 127.0.0.1:6030 + user: root + password: taosdata + configDir: + resultFile: ./output.txt + thread num of insert data: 10 + thread num of create table: 10 + top insert interval: 0 + number of records per req: 30000 + max sql length: 1048576 + database count: 1 + database[0]: + database[0] name: test + drop: yes + replica: 1 + precision: ms + super table count: 1 + super table[0]: + stbName: meters + autoCreateTable: no + childTblExists: no + childTblCount: 10000 + childTblPrefix: d + dataSource: rand + iface: taosc + insertRows: 10000 + interlaceRows: 0 + disorderRange: 1000 + disorderRatio: 0 + maxSqlLen: 1048576 + timeStampStep: 1 + startTimestamp: 2017-07-14 10:40:00.000 + sampleFormat: + sampleFile: + tagsFile: + columnCount: 3 + column[0]:FLOAT column[1]:INT column[2]:FLOAT + tagCount: 2 + tag[0]:INT tag[1]:BINARY(16) + + Press enter key to continue or Ctrl-C to stop + ``` + + 回车后，该命令将在数据库 test 下面自动创建一张超级表 meters，该超级表下有 1 万张表，表名为 "d0" 到 "d9999"，每张表有 1 万条记录，每条记录有 (ts, current, voltage, phase) 四个字段，时间戳从 "2017-07-14 10:40:00 000" 到 "2017-07-14 10:40:09 999"，每张表带有标签 location 和 groupId，groupId 被设置为 1 到 10， location 被设置为 "beijing" 或者 "shanghai"。 + + 最后共插入 1 亿条记录。 + +2. 进入 TDengine 终端，查看 taosBenchmark 生成的数据。 + + - **进入命令行。** + + ```bash + $ root@c452519b0f9b:~/TDengine-server-2.4.0.4# taos + + Welcome to the TDengine shell from Linux, Client Version:2.4.0.4 + Copyright (c) 2020 by TAOS Data, Inc. All rights reserved. + + taos> + ``` + + - **查看数据库。** + + ```bash + $ taos> show databases; + name | created_time | ntables | vgroups | ··· + test | 2021-08-18 06:01:11.021 | 10000 | 6 | ··· + log | 2021-08-18 05:51:51.065 | 4 | 1 | ··· + + ``` + + - **查看超级表。** + + ```bash + $ taos> use test; + Database changed. + + $ taos> show stables; + name | created_time | columns | tags | tables | + ============================================================================================ + meters | 2021-08-18 06:01:11.116 | 4 | 2 | 10000 | + Query OK, 1 row(s) in set (0.003259s) + + ``` + + - **查看表，限制输出十条。** + + ```bash + $ taos> select * from test.t0 limit 10; + + DB error: Table does not exist (0.002857s) + taos> select * from test.d0 limit 10; + ts | current | voltage | phase | + ====================================================================================== + 2017-07-14 10:40:00.000 | 10.12072 | 223 | 0.34167 | + 2017-07-14 10:40:00.001 | 10.16103 | 224 | 0.34445 | + 2017-07-14 10:40:00.002 | 10.00204 | 220 | 0.33334 | + 2017-07-14 10:40:00.003 | 10.00030 | 220 | 0.33333 | + 2017-07-14 10:40:00.004 | 9.84029 | 216 | 0.32222 | + 2017-07-14 10:40:00.005 | 9.88028 | 217 | 0.32500 | + 2017-07-14 10:40:00.006 | 9.88110 | 217 | 0.32500 | + 2017-07-14 10:40:00.007 | 10.08137 | 222 | 0.33889 | + 2017-07-14 10:40:00.008 | 10.12063 | 223 | 0.34167 | + 2017-07-14 10:40:00.009 | 10.16086 | 224 | 0.34445 | + Query OK, 10 row(s) in set (0.016791s) + + ``` + + - **查看 d0 表的标签值。** + + ```bash + $ taos> select groupid, location from test.d0; + groupid | location | + ================================= + 0 | shanghai | + Query OK, 1 row(s) in set (0.003490s) + ``` + +### 应用示例：使用数据收集代理软件写入 TDengine + +taosAdapter 支持多个数据收集代理软件（如 Telegraf、StatsD、collectd 等），这里仅模拟 StasD 写入数据，在宿主机执行命令如下： + +``` +echo "foo:1|c" | nc -u -w0 127.0.0.1 6044 +``` + +然后可以使用 taos shell 查询 taosAdapter 自动创建的数据库 statsd 和 超级表 foo 中的内容： + +``` +taos> show databases; + name | created_time | ntables | vgroups | replica | quorum | days | keep | cache(MB) | blocks | minrows | maxrows | wallevel | fsync | comp | cachelast | precision | update | status | +==================================================================================================================================================================================================================================================================================== + log | 2021-12-28 09:18:55.765 | 12 | 1 | 1 | 1 | 10 | 30 | 1 | 3 | 100 | 4096 | 1 | 3000 | 2 | 0 | us | 0 | ready | + statsd | 2021-12-28 09:21:48.841 | 1 | 1 | 1 | 1 | 10 | 3650 | 16 | 6 | 100 | 4096 | 1 | 3000 | 2 | 0 | ns | 2 | ready | +Query OK, 2 row(s) in set (0.002112s) + +taos> use statsd; +Database changed. + +taos> show stables; + name | created_time | columns | tags | tables | +============================================================================================ + foo | 2021-12-28 09:21:48.894 | 2 | 1 | 1 | +Query OK, 1 row(s) in set (0.001160s) + +taos> select * from foo; + ts | value | metric_type | +======================================================================================= + 2021-12-28 09:21:48.840820836 | 1 | counter | +Query OK, 1 row(s) in set (0.001639s) + +taos> +``` + +可以看到模拟数据已经被写入到 TDengine 中。 + +## 停止正在 Docker 中运行的 TDengine 服务 + +```bash +docker stop tdengine +``` + +- **docker stop**：通过 docker stop 停止指定的正在运行中的 docker 镜像。 diff --git a/docs-cn/27-train-faq/_category_.yml b/docs-cn/27-train-faq/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..16b32bc38fd3ef88313150cf89e32b15696fe7ff --- /dev/null +++ b/docs-cn/27-train-faq/_category_.yml @@ -0,0 +1 @@ +label: FAQ 及其他 diff --git a/docs-cn/27-train-faq/index.md b/docs-cn/27-train-faq/index.md new file mode 100644 index 0000000000000000000000000000000000000000..b42bff0288fc8ab59810a7d7121be28ddf781551 --- /dev/null +++ b/docs-cn/27-train-faq/index.md @@ -0,0 +1,10 @@ +--- +title: FAQ 及其他 +--- + +```mdx-code-block +import DocCardList from '@theme/DocCardList'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + + +``` \ No newline at end of file diff --git a/docs-cn/eco_system.png b/docs-cn/eco_system.png new file mode 100644 index 0000000000000000000000000000000000000000..bf8bf8f1e0a2311fc12202d712a8a2f9b8ce419b Binary files /dev/null and b/docs-cn/eco_system.png differ