diff --git a/.gitmodules b/.gitmodules index 5520c9b9188f0484ddc34eef630a86bca933a7a3..8179b9caa5701f7a94ed6c1dbda3ad75db1b866e 100644 --- a/.gitmodules +++ b/.gitmodules @@ -6,13 +6,13 @@ url = https://github.com/taosdata/hivemq-tdengine-extension.git [submodule "deps/jemalloc"] path = deps/jemalloc - url = https://github.com/jemalloc/jemalloc + url = https://github.com/jemalloc/jemalloc.git [submodule "src/kit/taos-tools"] path = src/kit/taos-tools - url = https://github.com/taosdata/taos-tools + url = https://github.com/taosdata/taos-tools.git [submodule "src/plugins/taosadapter"] path = src/plugins/taosadapter - url = https://github.com/taosdata/taosadapter + url = https://github.com/taosdata/taosadapter.git [submodule "examples/rust"] path = examples/rust url = https://github.com/songtianyi/tdengine-rust-bindings.git diff --git a/.mailmap b/.mailmap new file mode 100644 index 0000000000000000000000000000000000000000..9e5fb9468dbc65cd2bacb51b78a055998fad5bf6 --- /dev/null +++ b/.mailmap @@ -0,0 +1,16 @@ +# +# This list is used by git-shortlog to fix a few botched name translations +# in the git archive, either because the author's full name was messed up +# and/or not always written the same way, making contributions from the +# same person appearing not to be so or badly displayed. Also allows for +# old email addresses to map to new email addresses. +# +# For format details, see "MAPPING AUTHORS" in "man git-shortlog". +# +# Please keep this list dictionary sorted. +# + +Jeff Tao +Wade Zhang +Shuduo Sang +Pan Yang \ No newline at end of file diff --git a/Jenkinsfile2 b/Jenkinsfile2 index fceaa6554faa5bde7ae028ec9204627d505e8b95..f213afe3b9bd707c8488ae0f4431e56c01d30a4e 100644 --- a/Jenkinsfile2 +++ b/Jenkinsfile2 @@ -87,7 +87,9 @@ def sync_source() { cd ${WKC} git fetch origin +refs/pull/${CHANGE_ID}/merge git checkout -qf FETCH_HEAD - + ''' + sh ''' + cd ${WKC} if [ ! -d src/connector/python/.github ]; then rm -rf src/connector/python/* || : rm -rf src/connector/python/.* || : @@ -95,7 +97,6 @@ def sync_source() { else cd src/connector/python || echo "src/connector/python not exist" git pull || : - cd ${WKC} fi ''' } else if (env.CHANGE_URL =~ /\/TDinternal\//) { @@ -104,7 +105,9 @@ def sync_source() { cd ${WK} git fetch origin +refs/pull/${CHANGE_ID}/merge git checkout -qf FETCH_HEAD - + ''' + sh ''' + cd ${WKC} if [ ! -d community/src/connector/python/.github ]; then rm -rf community/src/connector/python/* || : rm -rf community/src/connector/python/.* || : @@ -112,7 +115,6 @@ def sync_source() { else cd community/src/connector/python || echo "community/src/connector/python not exist" git pull || : - cd ${WK} fi ''' } else { diff --git a/README-CN.md b/README-CN.md index e29495fdd0278ef4d1814a9f528cbed5fae1758b..eea73bde1b38ef7f7ddc5ca2458d7b81b55b80a8 100644 --- a/README-CN.md +++ b/README-CN.md @@ -11,7 +11,7 @@ # TDengine 简介 -TDengine 是一款高性能、分布式、支持 SQL 的时序数据库。而且除时序数据库功能外，它还提供缓存、数据订阅、流式计算等功能，最大程度减少研发和运维的复杂度，且核心代码，包括集群功能全部开源（开源协议，AGPL v3.0）。与其他时序数据数据库相比，TDengine 有以下特点： +TDengine 是一款高性能、分布式、支持 SQL 的时序数据库（Time-Series Database）。而且除时序数据库功能外，它还提供缓存、数据订阅、流式计算等功能，最大程度减少研发和运维的复杂度，且核心代码，包括集群功能全部开源（开源协议，AGPL v3.0）。与其他时序数据数据库相比，TDengine 有以下特点： - **高性能**：通过创新的存储引擎设计，无论是数据写入还是查询，TDengine 的性能比通用数据库快 10 倍以上，也远超其他时序数据库，而且存储空间也大为节省。 @@ -154,12 +154,23 @@ git submodule update --init --recursive ### Linux 系统 +可以运行代码仓库中的 `build.sh` 脚本编译出 TDengine 和 taosTools（包含 taosBenchmark 和 taosdump）。 + ```bash -mkdir debug && cd debug -cmake .. && cmake --build . +./build.sh +``` + +这个脚本等价于执行如下命令： + +```bash +git submodule update --init --recursive +mkdir debug +cd debug +cmake .. -DBUILD_TOOLS=true +make ``` -您可以选择使用 jemalloc 作为内存分配器，替代默认的 glibc： +您也可以选择使用 jemalloc 作为内存分配器，替代默认的 glibc： ```bash apt install autoconf diff --git a/README.md b/README.md index 07d70c2dd133f2864de7fab35eb0daaed20f38ce..aa944ef75dab53bcfec068a59285b561d064b429 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ We are hiring, check [here](https://www.taosdata.com/en/careers/) # What is TDengine？ -TDengine is a high-performance, scalable time-series database with SQL support. Its code including cluster feature is open source under [GNU AGPL v3.0](http://www.gnu.org/licenses/agpl-3.0.html). Besides the database, it provides caching, stream processing, data data subscription and other functionalities to reduce the complexity and cost of development and operation. TDengine differentiates itself from other TSDBs with the following advantages. +TDengine is a high-performance, scalable time-series database with SQL support. Its code including cluster feature is open source under [GNU AGPL v3.0](http://www.gnu.org/licenses/agpl-3.0.html). Besides the database, it provides caching, stream processing, data subscription and other functionalities to reduce the complexity and cost of development and operation. TDengine differentiates itself from other TSDBs with the following advantages. - **High Performance**: TDengine outperforms other time series databases in data ingestion and querying while significantly reducing storage cost and compute costs, with an innovatively designed and purpose-built storage engine. @@ -38,7 +38,7 @@ for details. The documentation from our website can also be downloaded locally f # Building -At the moment, TDengine only supports building and running on Linux systems. You can choose to [install from packages](https://www.taosdata.com/en/getting-started/#Install-from-Package) or from the source code. This quick guide is for installation from the source only. +At the moment, TDengine server only supports running on Linux systems. You can choose to [install from packages](https://www.taosdata.com/en/getting-started/#Install-from-Package) or build it from the source code. This quick guide is for installation from the source only. To build TDengine, use [CMake](https://cmake.org/) 3.0.2 or higher versions in the project directory. @@ -169,9 +169,20 @@ You can modify the file ~/.gitconfig to use ssh protocol instead of https for be ### On Linux platform +You can run the bash script `build.sh` to build both TDengine and taosTools including taosBenchmark and taosdump as below: + ```bash -mkdir debug && cd debug -cmake .. && cmake --build . +./build.sh +``` + +It equals to execute following commands: + +```bash +git submodule update --init --recursive +mkdir debug +cd debug +cmake .. -DBUILD_TOOLS=true +make ``` Note TDengine 2.3.x.0 and later use a component named 'taosAdapter' to play http daemon role by default instead of the http daemon embedded in the early version of TDengine. The taosAdapter is programmed by go language. If you pull TDengine source code to the latest from an existing codebase, please execute 'git submodule update --init --recursive' to pull taosAdapter source code. Please install go language version 1.14 or above for compiling taosAdapter. If you meet difficulties regarding 'go mod', especially you are from China, you can use a proxy to solve the problem. diff --git a/build.sh b/build.sh new file mode 100755 index 0000000000000000000000000000000000000000..d114c99e9ab862de19e21133bad661815f63929d --- /dev/null +++ b/build.sh @@ -0,0 +1,10 @@ +#!/bin/bash + +git submodule update --init --recursive > /dev/null || echo -e "failed to update git submodule" + +if [ ! -d debug ]; then + mkdir debug || echo -e "failed to make directory for build" +fi + +cd debug && cmake .. -DBUILD_TOOLS=true && make + diff --git a/cmake/define.inc b/cmake/define.inc index c1169b994804666c553b89300d140325341a14f0..5947472e2d04651a53421bfebacf5f7e23d8b268 100755 --- a/cmake/define.inc +++ b/cmake/define.inc @@ -242,8 +242,14 @@ IF (TD_WINDOWS) ADD_DEFINITIONS(-DPTW32_BUILD) ADD_DEFINITIONS(-D_MBCS -D_CRT_SECURE_NO_DEPRECATE -D_CRT_NONSTDC_NO_DEPRECATE) SET(CMAKE_GENERATOR "NMake Makefiles" CACHE INTERNAL "" FORCE) + IF (CMAKE_DEPFILE_FLAGS_C) + SET(CMAKE_DEPFILE_FLAGS_C "") + ENDIF () + IF (CMAKE_DEPFILE_FLAGS_CXX) + SET(CMAKE_DEPFILE_FLAGS_CXX "") + ENDIF () IF (NOT TD_GODLL) - SET(COMMON_FLAGS "/nologo /WX /wd4018 /wd4999 /Oi /Oy- /Gm- /EHsc /MT /GS /Gy /fp:precise /Zc:wchar_t /Zc:forScope /Gd /errorReport:prompt /analyze-") + SET(COMMON_FLAGS "/nologo /wd4018 /wd4999 /Oi /Oy- /Gm- /EHsc /MT /GS /Gy /fp:precise /Zc:wchar_t /Zc:forScope /Gd /errorReport:prompt /analyze- ") IF (MSVC AND (MSVC_VERSION GREATER_EQUAL 1900)) SET(COMMON_FLAGS "${COMMON_FLAGS} /Wv:18") ENDIF () diff --git a/cmake/env.inc b/cmake/env.inc index 69ff1ee7ae3134eb6b8116d0989bd61b43248172..1c594cd4be229cf259d76f9612b35fafde46221c 100755 --- a/cmake/env.inc +++ b/cmake/env.inc @@ -19,25 +19,6 @@ MESSAGE(STATUS "Project binary files output path: " ${PROJECT_BINARY_DIR}) MESSAGE(STATUS "Project executable files output path: " ${EXECUTABLE_OUTPUT_PATH}) MESSAGE(STATUS "Project library files output path: " ${LIBRARY_OUTPUT_PATH}) -find_package(Git QUIET) -if(GIT_FOUND AND EXISTS "${TD_COMMUNITY_DIR}/.git") -# Update submodules as needed - option(GIT_SUBMODULE "Check submodules during build" ON) - if(GIT_SUBMODULE) - message(STATUS "Submodule update") - execute_process(COMMAND ${GIT_EXECUTABLE} submodule update --init --recursive - WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} - RESULT_VARIABLE GIT_SUBMOD_RESULT) - if(NOT GIT_SUBMOD_RESULT EQUAL "0") - message(WARNING "git submodule update --init --recursive failed with ${GIT_SUBMOD_RESULT}, please checkout submodules") - endif() - endif() -endif() - -if(NOT EXISTS "${TD_COMMUNITY_DIR}/deps/jemalloc/Makefile.in") - message(WARNING "The submodules were not downloaded! GIT_SUBMODULE was turned off or failed. Please update submodules manually if you need build them.") -endif() - IF (TD_BUILD_JDBC) FIND_PROGRAM(TD_MVN_INSTALLED mvn) IF (TD_MVN_INSTALLED) diff --git a/cmake/version.inc b/cmake/version.inc index ae16262748653f7955a54cec0474f55611a7fd6d..dbd2277f9513d1698803e7316a51af588c3efda8 100755 --- a/cmake/version.inc +++ b/cmake/version.inc @@ -4,7 +4,7 @@ PROJECT(TDengine) IF (DEFINED VERNUMBER) SET(TD_VER_NUMBER ${VERNUMBER}) ELSE () - SET(TD_VER_NUMBER "2.4.0.0") + SET(TD_VER_NUMBER "2.7.0.0") ENDIF () IF (DEFINED VERCOMPATIBLE) diff --git a/docs-cn/01-intro/01-intro.md b/docs-cn/01-intro/01-intro.md deleted file mode 100644 index 492f729fb41626e28b85d48d19fbd8b1fc35daf5..0000000000000000000000000000000000000000 --- a/docs-cn/01-intro/01-intro.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -sidebar_label: 产品简介 -title: 产品简介 -toc_max_heading_level: 2 ---- - -## TDengine 主要功能 - -TDengine 是一款高性能、分布式、支持 SQL 的时序数据库，其核心代码，包括集群功能全部开源（开源协议，AGPL v3.0）。TDengine 能被广泛运用于物联网、工业互联网、车联网、IT 运维、金融等领域。除核心的时序数据库功能外，TDengine 还提供[缓存](/develop/cache/)、[数据订阅](/develop/subscribe)、[流式计算](/develop/continuous-query)等大数据平台所需要的系列功能，最大程度减少研发和运维的复杂度。主要功能如下： - -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. 支持[各种查询](/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 主要亮点 - -由于 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 在其中扮演的角色如下： - -
- -![TDengine技术生态图](eco_system.png) - -
-
图 1. TDengine技术生态图
- -上图中，左侧是各种数据采集或消息队列，包括 OPC-UA、MQTT、Telegraf、也包括 Kafaka, 他们的数据将被源源不断的写入到 TDengine。右侧则是可视化、BI 工具、组态软件、应用程序。下侧则是 TDengine 自身提供的命令行程序 (CLI) 以及可视化管理管理。 - -## TDengine 总体适用场景 - -作为一个高性能、分布式、支持 SQL 的时序数据库，TDengine 的典型适用场景包括但不限于 IoT、工业互联网、车联网、IT 运维、能源、金融证券等领域。需要指出的是，TDengine 是针对时序数据场景设计的专用数据库和专用大数据处理工具，因充分利用了时序大数据的特点，它无法用来处理网络爬虫、微博、微信、电商、ERP、CRM 等通用型数据。本文对适用场景做更多详细的分析。 - -### 数据源特点和需求 - -从数据源角度，设计人员可以从下面几个角度分析 TDengine 在目标应用系统里面的适用性。 - -| 数据源特点和需求 | 不适用 | 可能适用 | 非常适用 | 简单说明 | -| ---------------------------- | ------ | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- | -| 总体数据量巨大 | | | √ | TDengine 在容量方面提供出色的水平扩展功能，并且具备匹配高压缩的存储结构，达到业界最优的存储效率。 | -| 数据输入速度偶尔或者持续巨大 | | | √ | TDengine 的性能大大超过同类产品，可以在同样的硬件环境下持续处理大量的输入数据，并且提供很容易在用户环境里面运行的性能评估工具。 | -| 数据源数目巨大 | | | √ | TDengine 设计中包含专门针对大量数据源的优化，包括数据的写入和查询，尤其适合高效处理海量（千万或者更多量级）的数据源。 | - -### 系统架构要求 - -| 系统架构要求 | 不适用 | 可能适用 | 非常适用 | 简单说明 | -| ---------------------- | ------ | -------- | -------- | ----------------------------------------------------------------------------------------------------- | -| 要求简单可靠的系统架构 | | | √ | TDengine 的系统架构非常简单可靠，自带消息队列，缓存，流式计算，监控等功能，无需集成额外的第三方产品。 | -| 要求容错和高可靠 | | | √ | TDengine 的集群功能，自动提供容错灾备等高可靠功能。 | -| 标准化规范 | | | √ | TDengine 使用标准的 SQL 语言提供主要功能，遵守标准化规范。 | - -### 系统功能需求 - -| 系统功能需求 | 不适用 | 可能适用 | 非常适用 | 简单说明 | -| -------------------------- | ------ | -------- | -------- | --------------------------------------------------------------------------------------------------------------------- | -| 要求完整的内置数据处理算法 | | √ | | TDengine 的实现了通用的数据处理算法，但是还没有做到妥善处理各行各业的所有要求，因此特殊类型的处理还需要应用层面处理。 | -| 需要大量的交叉查询处理 | | √ | | 这种类型的处理更多应该用关系型数据系统处理，或者应该考虑 TDengine 和关系型数据系统配合实现系统功能。 | - -### 系统性能需求 - -| 系统性能需求 | 不适用 | 可能适用 | 非常适用 | 简单说明 | -| ---------------------- | ------ | -------- | -------- | ------------------------------------------------------------------------------------------------------ | -| 要求较大的总体处理能力 | | | √ | TDengine 的集群功能可以轻松地让多服务器配合达成处理能力的提升。 | -| 要求高速处理数据 | | | √ | TDengine 的专门为 IoT 优化的存储和数据处理的设计，一般可以让系统得到超出同类产品多倍数的处理速度提升。 | -| 要求快速处理小粒度数据 | | | √ | 这方面 TDengine 性能可以完全对标关系型和 NoSQL 型数据处理系统。 | - -### 系统维护需求 - -| 系统维护需求 | 不适用 | 可能适用 | 非常适用 | 简单说明 | -| ---------------------- | ------ | -------- | -------- | --------------------------------------------------------------------------------------------------------------------- | -| 要求系统可靠运行 | | | √ | TDengine 的系统架构非常稳定可靠，日常维护也简单便捷，对维护人员的要求简洁明了，最大程度上杜绝人为错误和事故。 | -| 要求运维学习成本可控 | | | √ | 同上。 | -| 要求市场有大量人才储备 | √ | | | 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/01-intro/_category_.yml b/docs-cn/01-intro/_category_.yml deleted file mode 100644 index 1fdaed6b943d4a0877325bf00005307fb2f19880..0000000000000000000000000000000000000000 --- a/docs-cn/01-intro/_category_.yml +++ /dev/null @@ -1 +0,0 @@ -label: TDengine 介绍 diff --git a/docs-cn/01-intro/eco_system.png b/docs-cn/01-intro/eco_system.png deleted file mode 100644 index bf8bf8f1e0a2311fc12202d712a8a2f9b8ce419b..0000000000000000000000000000000000000000 Binary files a/docs-cn/01-intro/eco_system.png and /dev/null differ diff --git a/docs-cn/02-concept/02-concept.md b/docs-cn/02-concept/02-concept.md deleted file mode 100644 index ec0a651c18a4af371278fb02108ebded737bddef..0000000000000000000000000000000000000000 --- a/docs-cn/02-concept/02-concept.md +++ /dev/null @@ -1,160 +0,0 @@ ---- -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）来做表名。每个数据采集点可能同时采集多个采集量（如上表中的 curent，voltage，phase），每个采集量对应一张表中的一列，数据类型可以是整型、浮点型、字符串等。除此之外，表的第一列必须是时间戳，即数据类型为 timestamp。对采集量，TDengine 将自动按照时间戳建立索引，但对采集量本身不建任何索引。数据用列式存储方式保存。 - -对于复杂的设备，比如汽车，它有多个数据采集点，那么就需要为一台汽车建立多张表。 - -## 超级表 (STable) - -由于一个数据采集点一张表，导致表的数量巨增，难以管理，而且应用经常需要做采集点之间的聚合操作，聚合的操作也变得复杂起来。为解决这个问题，TDengine 引入超级表（Super Table，简称为 STable）的概念。 - -超级表是指某一特定类型的数据采集点的集合。同一类型的数据采集点，其表的结构是完全一样的，但每个表（数据采集点）的静态属性（标签）是不一样的。描述一个超级表（某一特定类型的数据采集点的集合），除需要定义采集量的表结构之外，还需要定义其标签的 schema，标签的数据类型可以是整数、浮点数、字符串，标签可以有多个，可以事后增加、删除或修改。如果整个系统有 N 个不同类型的数据采集点，就需要建立 N 个超级表。 - -在 TDengine 的设计里，**表用来代表一个具体的数据采集点，超级表用来代表一组相同类型的数据采集点集合**。当为某个具体数据采集点创建表时，用户使用超级表的定义做模板，同时指定该具体采集点（表）的标签值。与传统的关系型数据库相比，表（一个数据采集点）是带有静态标签的，而且这些标签可以事后增加、删除、修改。超级表与与基于超级表建立的子表之间的关系表现在： - -1. 一张超级表包含有多张子表，这些子表具有相同的采集量 schema，但带有不同的标签值。 -2. 不能通过子表调整数据或标签的模式，对于超级表的数据模式修改立即对所有的子表生效。 -3. 超级表只定义一个模板，自身不存储任何数据或标签信息。因此，不能向一个超级表写入数据，只能将数据写入子表中。 - -查询既可以在表上进行，也可以在超级表上进行。针对超级表的查询，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/03-get-started/03-get-started.md b/docs-cn/03-get-started/03-get-started.md deleted file mode 100644 index 6776455c9dc3ab68d291488b7b3b0353967f0ac1..0000000000000000000000000000000000000000 --- a/docs-cn/03-get-started/03-get-started.md +++ /dev/null @@ -1,173 +0,0 @@ ---- -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 除 RESTful接口外，还提供一些列编程语言的连接器。2.4 之前的版本中，无 taosAdapter，RESTfule 接口均由 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 的状态，执行各种即席(Ad Hoc)查询，TDengine 提供一命令行应用程序(以下简称为 TDengine CLI) taos。要进入 TDengine 命令行，您只要在安装有 TDengine 的 Linux 终端执行 `taos` 即可。 - -```bash -taos -``` - -如果连接服务成功，将会打印出欢迎消息和版本信息。如果失败，则会打印错误消息出来（请参考 [FAQ](/train-faq/faq) 来解决终端连接服务端失败的问题）。 TDengine CLI 的提示符号如下： - -```cmd -taos> -``` - -在 TDengine CLI中，用户可以通过 SQL 命令来创建/删除数据库、表等，并进行插入查询操作。在终端中运行的 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/04-develop/01-connect/_connect_c.mdx b/docs-cn/04-develop/01-connect/_connect_c.mdx deleted file mode 100644 index 9cd8669561195b49e8428ed490ad97bb5653ae6a..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/01-connect/_connect_c.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```c title="原生连接" -{{#include docs-examples/c/connect_example.c}} -``` diff --git a/docs-cn/04-develop/01-connect/_connect_cs.mdx b/docs-cn/04-develop/01-connect/_connect_cs.mdx deleted file mode 100644 index 821820e8fe1d87a35e01943530179eeb6e0f48be..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/01-connect/_connect_cs.mdx +++ /dev/null @@ -1,8 +0,0 @@ -```csharp title="原生连接" -{{#include docs-examples/csharp/ConnectExample.cs}} -``` - -:::info -C# 连接器目前只支持原生连接。 - -::: diff --git a/docs-cn/04-develop/01-connect/_connect_go.mdx b/docs-cn/04-develop/01-connect/_connect_go.mdx deleted file mode 100644 index 478768caaacc8aceb9a3f5a85f008dde00125eb7..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/01-connect/_connect_go.mdx +++ /dev/null @@ -1,17 +0,0 @@ -#### 使用数据库访问统一接口 - -```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/04-develop/01-connect/_connect_java.mdx b/docs-cn/04-develop/01-connect/_connect_java.mdx deleted file mode 100644 index 635f39ceb28ffc3fd0b0d8edb057d9aa01c593de..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/01-connect/_connect_java.mdx +++ /dev/null @@ -1,15 +0,0 @@ -```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/04-develop/01-connect/_connect_node.mdx b/docs-cn/04-develop/01-connect/_connect_node.mdx deleted file mode 100644 index 199a6e3faa88fcb295379309a250990bf97fa973..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/01-connect/_connect_node.mdx +++ /dev/null @@ -1,7 +0,0 @@ -```js title="原生连接" -{{#include docs-examples/node/nativeexample/connect.js}} -``` - -```js title="REST 连接" -{{#include docs-examples/node/restexample/connect.js}} -``` diff --git a/docs-cn/04-develop/01-connect/_connect_php.mdx b/docs-cn/04-develop/01-connect/_connect_php.mdx deleted file mode 100644 index 2431df2a722659ae6e5962a955fba139be3e5f67..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/01-connect/_connect_php.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```php title="原生连接" -{{#include docs-examples/php/connect.php}} -``` diff --git a/docs-cn/04-develop/01-connect/_connect_python.mdx b/docs-cn/04-develop/01-connect/_connect_python.mdx deleted file mode 100644 index 43e13ab56eeada9d86eae057a1ab0eafcd5247de..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/01-connect/_connect_python.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```python title="原生连接" -{{#include docs-examples/python/connect_exmaple.py}} -``` diff --git a/docs-cn/04-develop/01-connect/_connect_r.mdx b/docs-cn/04-develop/01-connect/_connect_r.mdx deleted file mode 100644 index 8aab6121a66b38540bf1b8ebf5b48a513282ac7a..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/01-connect/_connect_r.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```r title="原生连接" -{{#include docs-examples/R/connect_native.r:demo}} -``` diff --git a/docs-cn/04-develop/01-connect/_connect_rust.mdx b/docs-cn/04-develop/01-connect/_connect_rust.mdx deleted file mode 100644 index 9e64724c178ba2c72e14fc9878bf9c3237bb50e7..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/01-connect/_connect_rust.mdx +++ /dev/null @@ -1,8 +0,0 @@ -```rust title="原生连接/REST 连接" -{{#include docs-examples/rust/nativeexample/examples/connect.rs}} -``` - -:::note -对于 Rust 连接器， 连接方式的不同只体现在使用的特性不同。如果启用了 "rest" 特性，那么只有 RESTful 的实现会被编译进来。 - -::: diff --git a/docs-cn/04-develop/01-connect/index.md b/docs-cn/04-develop/01-connect/index.md deleted file mode 100644 index e83e3451c2c7f39f38c57672e63234117b3ac4b7..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/01-connect/index.md +++ /dev/null @@ -1,284 +0,0 @@ ---- -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 -dextension=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/04-develop/02-model/index.mdx b/docs-cn/04-develop/02-model/index.mdx deleted file mode 100644 index 7cf03cee37a5ac681181b0982e98e48d139ddb83..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/02-model/index.mdx +++ /dev/null @@ -1,87 +0,0 @@ ---- -slug: /model -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/04-develop/03-insert-data/01-sql-writing.mdx b/docs-cn/04-develop/03-insert-data/01-sql-writing.mdx deleted file mode 100644 index e63ffce6dd07366da99fe1f41d0a2a8d7a623f31..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/01-sql-writing.mdx +++ /dev/null @@ -1,137 +0,0 @@ ---- -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/04-develop/03-insert-data/02-influxdb-line.mdx b/docs-cn/04-develop/03-insert-data/02-influxdb-line.mdx deleted file mode 100644 index dedd7f0e70834e21257bda78dd184f5ddc520160..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/02-influxdb-line.mdx +++ /dev/null @@ -1,70 +0,0 @@ ---- -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/04-develop/03-insert-data/03-opentsdb-telnet.mdx b/docs-cn/04-develop/03-insert-data/03-opentsdb-telnet.mdx deleted file mode 100644 index dfbe6efda67b6928999287900637e0a251b86562..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/03-opentsdb-telnet.mdx +++ /dev/null @@ -1,84 +0,0 @@ ---- -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/04-develop/03-insert-data/04-opentsdb-json.mdx b/docs-cn/04-develop/03-insert-data/04-opentsdb-json.mdx deleted file mode 100644 index 5d445997d061ca052e4f3673b8e881ea4acf0ade..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/04-opentsdb-json.mdx +++ /dev/null @@ -1,99 +0,0 @@ ---- -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/04-develop/03-insert-data/_c_line.mdx b/docs-cn/04-develop/03-insert-data/_c_line.mdx deleted file mode 100644 index 5ef2e9af774c54e9f090357286f83d2280c2ab11..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/_c_line.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```c -{{#include docs-examples/c/line_example.c:main}} -``` \ No newline at end of file diff --git a/docs-cn/04-develop/03-insert-data/_c_opts_json.mdx b/docs-cn/04-develop/03-insert-data/_c_opts_json.mdx deleted file mode 100644 index 22ad2e0122797248a372734aac0f3a16a1356530..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/_c_opts_json.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```c -{{#include docs-examples/c/json_protocol_example.c:main}} -``` \ No newline at end of file diff --git a/docs-cn/04-develop/03-insert-data/_c_opts_telnet.mdx b/docs-cn/04-develop/03-insert-data/_c_opts_telnet.mdx deleted file mode 100644 index 508d7bc98a149f49766bcd0a474ffe226cbe30bb..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/_c_opts_telnet.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```c -{{#include docs-examples/c/telnet_line_example.c:main}} -``` \ No newline at end of file diff --git a/docs-cn/04-develop/03-insert-data/_c_sql.mdx b/docs-cn/04-develop/03-insert-data/_c_sql.mdx deleted file mode 100644 index f4153fd2c427677a338d0c377663d0335f2672f0..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/_c_sql.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```c -{{#include docs-examples/c/insert_example.c}} -``` \ No newline at end of file diff --git a/docs-cn/04-develop/03-insert-data/_c_stmt.mdx b/docs-cn/04-develop/03-insert-data/_c_stmt.mdx deleted file mode 100644 index 01ac067519a2bd224e313fd70169722ba5f20413..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/_c_stmt.mdx +++ /dev/null @@ -1,6 +0,0 @@ -```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/04-develop/03-insert-data/_category_.yml b/docs-cn/04-develop/03-insert-data/_category_.yml deleted file mode 100644 index 9e76a57abd132b528bbd692f03439649ab83425d..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/_category_.yml +++ /dev/null @@ -1,5 +0,0 @@ -label: 写入数据 -link: - type: generated-index - slug: /insert-data/ - description: "TDengine 支持多种写入协议，包括 SQL，InfluxDB Line 协议, OpenTSDB Telnet 协议，OpenTSDB JSON 格式协议。数据可以单条插入，也可以批量插入，可以插入一个数据采集点的数据，也可以同时插入多个数据采集点的数据。同时，TDengine 支持多线程插入，支持时间乱序数据插入，也支持历史数据插入。InfluxDB Line 协议、OpenTSDB Telnet 协议和 OpenTSDB JSON 格式协议是 TDengine 支持的三种无模式写入协议。使用无模式方式写入无需提前创建超级表和子表，并且引擎能自适用数据对表结构做调整。" diff --git a/docs-cn/04-develop/03-insert-data/_cs_line.mdx b/docs-cn/04-develop/03-insert-data/_cs_line.mdx deleted file mode 100644 index 9c275ee3d7c7a1e52fbb34dbae922004543ee3ce..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/_cs_line.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```csharp -{{#include docs-examples/csharp/InfluxDBLineExample.cs}} -``` diff --git a/docs-cn/04-develop/03-insert-data/_cs_opts_json.mdx b/docs-cn/04-develop/03-insert-data/_cs_opts_json.mdx deleted file mode 100644 index 3d538b8506b298241faecd8098f89571359135c9..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/_cs_opts_json.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```csharp -{{#include docs-examples/csharp/OptsJsonExample.cs}} -``` diff --git a/docs-cn/04-develop/03-insert-data/_cs_opts_telnet.mdx b/docs-cn/04-develop/03-insert-data/_cs_opts_telnet.mdx deleted file mode 100644 index c53bf3d7233115351e5af03b7d9e6318aa4a0da6..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/_cs_opts_telnet.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```csharp -{{#include docs-examples/csharp/OptsTelnetExample.cs}} -``` diff --git a/docs-cn/04-develop/03-insert-data/_cs_sql.mdx b/docs-cn/04-develop/03-insert-data/_cs_sql.mdx deleted file mode 100644 index c7688bfbe77a1135424d829fe9b29fbb1bc93ae2..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/_cs_sql.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```csharp -{{#include docs-examples/csharp/SQLInsertExample.cs}} -``` diff --git a/docs-cn/04-develop/03-insert-data/_cs_stmt.mdx b/docs-cn/04-develop/03-insert-data/_cs_stmt.mdx deleted file mode 100644 index 97c3b910ffeb9e0c88fc143a02014115e819c147..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/_cs_stmt.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```csharp -{{#include docs-examples/csharp/StmtInsertExample.cs}} -``` diff --git a/docs-cn/04-develop/03-insert-data/_go_line.mdx b/docs-cn/04-develop/03-insert-data/_go_line.mdx deleted file mode 100644 index cd225945b70e28bef2ca7fdaf0d9be0ad7ffc18c..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/_go_line.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```go -{{#include docs-examples/go/insert/line/main.go}} -``` diff --git a/docs-cn/04-develop/03-insert-data/_go_opts_json.mdx b/docs-cn/04-develop/03-insert-data/_go_opts_json.mdx deleted file mode 100644 index 0c0d3e5b6330e046988cdd02234285ec67e92f01..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/_go_opts_json.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```go -{{#include docs-examples/go/insert/json/main.go}} -``` diff --git a/docs-cn/04-develop/03-insert-data/_go_opts_telnet.mdx b/docs-cn/04-develop/03-insert-data/_go_opts_telnet.mdx deleted file mode 100644 index d5ca40cc146e62412476289853e8e2739e0e9e4b..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/_go_opts_telnet.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```go -{{#include docs-examples/go/insert/telnet/main.go}} -``` diff --git a/docs-cn/04-develop/03-insert-data/_go_sql.mdx b/docs-cn/04-develop/03-insert-data/_go_sql.mdx deleted file mode 100644 index 613a65add1741eb763a4b24e65d180d05f7d670f..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/_go_sql.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```go -{{#include docs-examples/go/insert/sql/main.go}} -``` diff --git a/docs-cn/04-develop/03-insert-data/_go_stmt.mdx b/docs-cn/04-develop/03-insert-data/_go_stmt.mdx deleted file mode 100644 index 7bb6792d6df5b250850bd0a0021ecceba994aa09..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/_go_stmt.mdx +++ /dev/null @@ -1,8 +0,0 @@ -```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/04-develop/03-insert-data/_java_line.mdx b/docs-cn/04-develop/03-insert-data/_java_line.mdx deleted file mode 100644 index 2e59a5d4701b2a2ab04ec5711845dc5c80067a1e..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/_java_line.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```java -{{#include docs-examples/java/src/main/java/com/taos/example/LineProtocolExample.java}} -``` diff --git a/docs-cn/04-develop/03-insert-data/_java_opts_json.mdx b/docs-cn/04-develop/03-insert-data/_java_opts_json.mdx deleted file mode 100644 index 826a1a07d9405cb193849f9d21e5444f68517914..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/_java_opts_json.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```java -{{#include docs-examples/java/src/main/java/com/taos/example/JSONProtocolExample.java}} -``` diff --git a/docs-cn/04-develop/03-insert-data/_java_opts_telnet.mdx b/docs-cn/04-develop/03-insert-data/_java_opts_telnet.mdx deleted file mode 100644 index 954dcc1a482a150dea0b190e1e0593adbfbde796..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/_java_opts_telnet.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```java -{{#include docs-examples/java/src/main/java/com/taos/example/TelnetLineProtocolExample.java}} -``` diff --git a/docs-cn/04-develop/03-insert-data/_java_sql.mdx b/docs-cn/04-develop/03-insert-data/_java_sql.mdx deleted file mode 100644 index a863378defe43b1f22c1f98087a34f053a7d6619..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/_java_sql.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```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/04-develop/03-insert-data/_java_stmt.mdx b/docs-cn/04-develop/03-insert-data/_java_stmt.mdx deleted file mode 100644 index 54443e535fa84bdf8dc9161ed4ad00f50b26266c..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/_java_stmt.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```java -{{#include docs-examples/java/src/main/java/com/taos/example/StmtInsertExample.java}} -``` diff --git a/docs-cn/04-develop/03-insert-data/_js_line.mdx b/docs-cn/04-develop/03-insert-data/_js_line.mdx deleted file mode 100644 index 172c9bc17b8cff8b2620720b235a9c8e69bd4197..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/_js_line.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```js -{{#include docs-examples/node/nativeexample/influxdb_line_example.js}} -``` diff --git a/docs-cn/04-develop/03-insert-data/_js_opts_json.mdx b/docs-cn/04-develop/03-insert-data/_js_opts_json.mdx deleted file mode 100644 index 20ac9ec91e8dc6675828b16d7da0acb09afd3b5f..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/_js_opts_json.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```js -{{#include docs-examples/node/nativeexample/opentsdb_json_example.js}} -``` diff --git a/docs-cn/04-develop/03-insert-data/_js_opts_telnet.mdx b/docs-cn/04-develop/03-insert-data/_js_opts_telnet.mdx deleted file mode 100644 index c3c8c40bd642f4f443de88e3db006ad50724d514..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/_js_opts_telnet.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```js -{{#include docs-examples/node/nativeexample/opentsdb_telnet_example.js}} -``` diff --git a/docs-cn/04-develop/03-insert-data/_js_sql.mdx b/docs-cn/04-develop/03-insert-data/_js_sql.mdx deleted file mode 100644 index f5e17c76892a57a94192a95451b508b1c176c984..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/_js_sql.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```js -{{#include docs-examples/node/nativeexample/insert_example.js}} -``` diff --git a/docs-cn/04-develop/03-insert-data/_js_stmt.mdx b/docs-cn/04-develop/03-insert-data/_js_stmt.mdx deleted file mode 100644 index 17a6c9785c7dc1e3c3fa6a59982913f1f139f9c2..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/_js_stmt.mdx +++ /dev/null @@ -1,12 +0,0 @@ -```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/04-develop/03-insert-data/_php_sql.mdx b/docs-cn/04-develop/03-insert-data/_php_sql.mdx deleted file mode 100644 index 42d6a548479d526e7ecdba12807cf9cafb911ee5..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/_php_sql.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```php -{{#include docs-examples/php/insert.php}} -``` diff --git a/docs-cn/04-develop/03-insert-data/_php_stmt.mdx b/docs-cn/04-develop/03-insert-data/_php_stmt.mdx deleted file mode 100644 index c1ba4ed3b160514fafb50886d799fc27e60927ed..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/_php_stmt.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```php -{{#include docs-examples/php/insert_stmt.php}} -``` diff --git a/docs-cn/04-develop/03-insert-data/_py_line.mdx b/docs-cn/04-develop/03-insert-data/_py_line.mdx deleted file mode 100644 index d3bb1ebb3403b53fa43bfc9d5d1a0de9764d7583..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/_py_line.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```py -{{#include docs-examples/python/line_protocol_example.py}} -``` diff --git a/docs-cn/04-develop/03-insert-data/_py_opts_json.mdx b/docs-cn/04-develop/03-insert-data/_py_opts_json.mdx deleted file mode 100644 index cfbfe13ccfdb4f3f34b77300812863fdf70d0f59..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/_py_opts_json.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```py -{{#include docs-examples/python/json_protocol_example.py}} -``` diff --git a/docs-cn/04-develop/03-insert-data/_py_opts_telnet.mdx b/docs-cn/04-develop/03-insert-data/_py_opts_telnet.mdx deleted file mode 100644 index 14bc65a7a3da815abadf7f25c8deffeac666c8d7..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/_py_opts_telnet.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```py -{{#include docs-examples/python/telnet_line_protocol_example.py}} -``` diff --git a/docs-cn/04-develop/03-insert-data/_py_sql.mdx b/docs-cn/04-develop/03-insert-data/_py_sql.mdx deleted file mode 100644 index c0e15b8ec115b9244d50a47c9eafec04bcfdd70c..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/_py_sql.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```py -{{#include docs-examples/python/native_insert_example.py}} -``` diff --git a/docs-cn/04-develop/03-insert-data/_py_stmt.mdx b/docs-cn/04-develop/03-insert-data/_py_stmt.mdx deleted file mode 100644 index 8241ea86bc64ac64d842dc0a6cddc0eae0399503..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/_py_stmt.mdx +++ /dev/null @@ -1,12 +0,0 @@ -```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/04-develop/03-insert-data/_rust_line.mdx b/docs-cn/04-develop/03-insert-data/_rust_line.mdx deleted file mode 100644 index 696ddb7b854751b8dee01047066f97f74212933f..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/_rust_line.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```rust -{{#include docs-examples/rust/schemalessexample/examples/influxdb_line_example.rs}} -``` diff --git a/docs-cn/04-develop/03-insert-data/_rust_opts_json.mdx b/docs-cn/04-develop/03-insert-data/_rust_opts_json.mdx deleted file mode 100644 index 97d9052dacd1894cc7548a59951ecfaad9caee87..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/_rust_opts_json.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```rust -{{#include docs-examples/rust/schemalessexample/examples/opentsdb_json_example.rs}} -``` diff --git a/docs-cn/04-develop/03-insert-data/_rust_opts_telnet.mdx b/docs-cn/04-develop/03-insert-data/_rust_opts_telnet.mdx deleted file mode 100644 index 14021f43d8aff30c35dc30c5d278d4e51f375024..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/_rust_opts_telnet.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```rust -{{#include docs-examples/rust/schemalessexample/examples/opentsdb_telnet_example.rs}} -``` diff --git a/docs-cn/04-develop/03-insert-data/_rust_sql.mdx b/docs-cn/04-develop/03-insert-data/_rust_sql.mdx deleted file mode 100644 index 8e8013e4ad734efcc262ea2f750b82210a538e49..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/_rust_sql.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```rust -{{#include docs-examples/rust/restexample/examples/insert_example.rs}} -``` diff --git a/docs-cn/04-develop/03-insert-data/_rust_stmt.mdx b/docs-cn/04-develop/03-insert-data/_rust_stmt.mdx deleted file mode 100644 index 590a7a0e717426ed0235331c49dfc578bc55b2f7..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/03-insert-data/_rust_stmt.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```rust -{{#include docs-examples/rust/nativeexample/examples/stmt_example.rs}} -``` diff --git a/docs-cn/04-develop/04-query-data/_c.mdx b/docs-cn/04-develop/04-query-data/_c.mdx deleted file mode 100644 index 76c9067e2f6af19465cf7c52c3e9b48bb868547d..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/04-query-data/_c.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```c -{{#include docs-examples/c/query_example.c}} -``` \ No newline at end of file diff --git a/docs-cn/04-develop/04-query-data/_c_async.mdx b/docs-cn/04-develop/04-query-data/_c_async.mdx deleted file mode 100644 index 09f3d3b3ff6d6644f837642ef41db459ba7c5753..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/04-query-data/_c_async.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```c -{{#include docs-examples/c/async_query_example.c:demo}} -``` \ No newline at end of file diff --git a/docs-cn/04-develop/04-query-data/_cs.mdx b/docs-cn/04-develop/04-query-data/_cs.mdx deleted file mode 100644 index 2ab52feb564eff0fe251bc9900ea2539171e5dba..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/04-query-data/_cs.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```csharp -{{#include docs-examples/csharp/QueryExample.cs}} -``` diff --git a/docs-cn/04-develop/04-query-data/_cs_async.mdx b/docs-cn/04-develop/04-query-data/_cs_async.mdx deleted file mode 100644 index f868994b303e62016b5e2f9304275135855c6ae5..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/04-query-data/_cs_async.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```csharp -{{#include docs-examples/csharp/AsyncQueryExample.cs}} -``` diff --git a/docs-cn/04-develop/04-query-data/_go.mdx b/docs-cn/04-develop/04-query-data/_go.mdx deleted file mode 100644 index 417c12315c06517e2f3de850ac9a379b7714b519..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/04-query-data/_go.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```go -{{#include docs-examples/go/query/sync/main.go}} -``` diff --git a/docs-cn/04-develop/04-query-data/_go_async.mdx b/docs-cn/04-develop/04-query-data/_go_async.mdx deleted file mode 100644 index 72fff411b980a0dcbdcaf4274722c63e0351db6f..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/04-query-data/_go_async.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```go -{{#include docs-examples/go/query/async/main.go}} -``` diff --git a/docs-cn/04-develop/04-query-data/_java.mdx b/docs-cn/04-develop/04-query-data/_java.mdx deleted file mode 100644 index 519b9266144486231caf3ee593e973d438941ee4..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/04-query-data/_java.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```java -{{#include docs-examples/java/src/main/java/com/taos/example/RestQueryExample.java}} -``` diff --git a/docs-cn/04-develop/04-query-data/_js.mdx b/docs-cn/04-develop/04-query-data/_js.mdx deleted file mode 100644 index c5e4c4f3fc20d3940a2bc6e13e6a5dea8a15ff13..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/04-query-data/_js.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```js -{{#include docs-examples/node/nativeexample/query_example.js}} -``` diff --git a/docs-cn/04-develop/04-query-data/_js_async.mdx b/docs-cn/04-develop/04-query-data/_js_async.mdx deleted file mode 100644 index c65d54ed12f6c4bbeb333e0de0ba9ca4638bff84..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/04-query-data/_js_async.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```js -{{#include docs-examples/node/nativeexample/async_query_example.js}} -``` diff --git a/docs-cn/04-develop/04-query-data/_php.mdx b/docs-cn/04-develop/04-query-data/_php.mdx deleted file mode 100644 index 6264bd99f534fbd800f1f349d93ac69b31c77397..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/04-query-data/_php.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```go -{{#include docs-examples/php/query.php}} -``` diff --git a/docs-cn/04-develop/04-query-data/_py.mdx b/docs-cn/04-develop/04-query-data/_py.mdx deleted file mode 100644 index 6a1bacdd3ef91e9484c1d87d6a22de8b128e2144..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/04-query-data/_py.mdx +++ /dev/null @@ -1,11 +0,0 @@ -通过迭代逐行获取查询结果。 - -```py -{{#include docs-examples/python/query_example.py:iter}} -``` - -一次获取所有查询结果，并把每一行转化为一个字典返回。 - -```py -{{#include docs-examples/python/query_example.py:fetch_all}} -``` diff --git a/docs-cn/04-develop/04-query-data/_py_async.mdx b/docs-cn/04-develop/04-query-data/_py_async.mdx deleted file mode 100644 index 2399a50df645804788036e17bf223c53482d4eaf..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/04-query-data/_py_async.mdx +++ /dev/null @@ -1,8 +0,0 @@ -```py -{{#include docs-examples/python/async_query_example.py}} -``` - -:::note -这个示例程序，目前在 Windows 系统上还无法运行 - -::: diff --git a/docs-cn/04-develop/04-query-data/_rust.mdx b/docs-cn/04-develop/04-query-data/_rust.mdx deleted file mode 100644 index 742d70fd025ff44b573eedf78441c9d73defad45..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/04-query-data/_rust.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```rust -{{#include docs-examples/rust/restexample/examples/query_example.rs}} -``` diff --git a/docs-cn/04-develop/04-query-data/index.mdx b/docs-cn/04-develop/04-query-data/index.mdx deleted file mode 100644 index 6b7edc123097b48510d4debcd414fbad5e0c4987..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/04-query-data/index.mdx +++ /dev/null @@ -1,182 +0,0 @@ ---- -slug: /query-data -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/04-develop/05-continuous-query.mdx b/docs-cn/04-develop/05-continuous-query.mdx deleted file mode 100644 index 2fd1b3cc755188f513fe511541a84efa3558d3ea..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/05-continuous-query.mdx +++ /dev/null @@ -1,84 +0,0 @@ ---- -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/04-develop/06-subscribe.mdx b/docs-cn/04-develop/06-subscribe.mdx deleted file mode 100644 index d471c114e827d7c4b40195c2c1b3c8f6a9d26ed4..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/06-subscribe.mdx +++ /dev/null @@ -1,253 +0,0 @@ ---- -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/04-develop/07-cache.md b/docs-cn/04-develop/07-cache.md deleted file mode 100644 index fd31335310d62d792e5173e38a9aa778ee6c6c60..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/07-cache.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -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/04-develop/_category_.yml b/docs-cn/04-develop/_category_.yml deleted file mode 100644 index b17f078b9a42143b8eb42a04909d5c881dcaad9d..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/_category_.yml +++ /dev/null @@ -1,5 +0,0 @@ -label: 开发指南 -link: - type: generated-index - slug: /develop - description: "开始指南是对开发者友好的使用教程，既包括数据建模、写入、查询等基础功能的使用，也包括数据订阅、连续查询等高级功能的使用。对于每个主题，都配有各编程语言的连接器的示例代码，方便开发者快速上手。如果想更深入地了解各连接器的使用，请阅读连接器参考指南。" diff --git a/docs-cn/04-develop/_sub_c.mdx b/docs-cn/04-develop/_sub_c.mdx deleted file mode 100644 index 95fef0042d0a277f9136e6e6f8c15558487232f9..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/_sub_c.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```c -{{#include docs-examples/c/subscribe_demo.c}} -``` \ No newline at end of file diff --git a/docs-cn/04-develop/_sub_cs.mdx b/docs-cn/04-develop/_sub_cs.mdx deleted file mode 100644 index 80934aa4d014a076896dce7f41e520f06ffd735d..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/_sub_cs.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```csharp -{{#include docs-examples/csharp/SubscribeDemo.cs}} -``` \ No newline at end of file diff --git a/docs-cn/04-develop/_sub_go.mdx b/docs-cn/04-develop/_sub_go.mdx deleted file mode 100644 index cd908fc12c3a35f49ca108ee56c3951c5388a95f..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/_sub_go.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```go -{{#include docs-examples/go/sub/main.go}} -``` \ No newline at end of file diff --git a/docs-cn/04-develop/_sub_java.mdx b/docs-cn/04-develop/_sub_java.mdx deleted file mode 100644 index 1ee0cb1a21e35f6760f8680e2ba6dedee92201cd..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/_sub_java.mdx +++ /dev/null @@ -1,7 +0,0 @@ -```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/04-develop/_sub_node.mdx b/docs-cn/04-develop/_sub_node.mdx deleted file mode 100644 index c93ad627ce9a77ca71a014b41d571089e6c1727b..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/_sub_node.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```js -{{#include docs-examples/node/nativeexample/subscribe_demo.js}} -``` \ No newline at end of file diff --git a/docs-cn/04-develop/_sub_python.mdx b/docs-cn/04-develop/_sub_python.mdx deleted file mode 100644 index b817deeba6e283a3ba16fee0d580d3823c999536..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/_sub_python.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```py -{{#include docs-examples/python/subscribe_demo.py}} -``` \ No newline at end of file diff --git a/docs-cn/04-develop/_sub_rust.mdx b/docs-cn/04-develop/_sub_rust.mdx deleted file mode 100644 index 4750cf7a3b871db48c9e5a26b22ab4b8a03f11be..0000000000000000000000000000000000000000 --- a/docs-cn/04-develop/_sub_rust.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```rs -{{#include docs-examples/rust/nativeexample/examples/subscribe_demo.rs}} -``` \ No newline at end of file diff --git a/docs-cn/10-cluster/01-deploy.md b/docs-cn/10-cluster/01-deploy.md deleted file mode 100644 index cee140c0ec13bc9c8052a599a2147acc1aa15a8d..0000000000000000000000000000000000000000 --- a/docs-cn/10-cluster/01-deploy.md +++ /dev/null @@ -1,138 +0,0 @@ ---- -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/_category_.yml b/docs-cn/10-cluster/_category_.yml deleted file mode 100644 index df953cb6dd297c91f1e6d1e2d30690afab293982..0000000000000000000000000000000000000000 --- a/docs-cn/10-cluster/_category_.yml +++ /dev/null @@ -1,12 +0,0 @@ -label: 集群管理 -link: - type: generated-index - slug: /cluster/ - description: "TDengine支持以集群方式部署，以提升系统的处理能力和高可用性。TDengine集群支持任意数据的多副本从而提升高可用性，并自动实现负载均衡。同时TDengine集群具有很好的横向扩展能力以处理更多的数据采集点和更大的数据量。" - keywords: - [ - 集群， - 高可用， - 负载均衡， - 横向扩展 - ] diff --git a/docs-cn/12-taos-sql/02-database.md b/docs-cn/12-taos-sql/02-database.md deleted file mode 100644 index 5d358193f96b9c3258d1236f8d11341f8889b8e5..0000000000000000000000000000000000000000 --- a/docs-cn/12-taos-sql/02-database.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -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, blocks, days, keep, minRows, maxRows, wal, fsync, update, cacheLast, replica, quorum, maxVgroupsPerDb, ctime, comp, prec, 具体细节请参见 [配置参数](/reference/config/) 章节。 - -::: - -## 显示系统当前参数 - -``` -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 版本开始，修改这些参数后无需重启服务器即可生效。 -:::tip - -## 显示系统所有数据库 - -``` -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 deleted file mode 100644 index 330734f9bc46ffb09fc338997f37c0e05560a2d5..0000000000000000000000000000000000000000 --- a/docs-cn/12-taos-sql/03-table.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -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_wildcar]; -``` - -显示当前数据库下的所有数据表信息。 - -## 显示一个数据表的创建语句 - -``` -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 deleted file mode 100644 index a3c227317c85917b64b2477994d335710610ec70..0000000000000000000000000000000000000000 --- a/docs-cn/12-taos-sql/04-stable.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -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 deleted file mode 100644 index e542e442b78c9033ae37196f4913a7c67fb19d8b..0000000000000000000000000000000000000000 --- a/docs-cn/12-taos-sql/05-insert.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -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 deleted file mode 100644 index 6f0a0735135738c9502632387022cc94e9495375..0000000000000000000000000000000000000000 --- a/docs-cn/12-taos-sql/06-select.md +++ /dev/null @@ -1,463 +0,0 @@ ---- -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/testoutpu.csv`： - -``` -SELECT COUNT(*) FROM tb1 WHERE ts >= NOW - 10m AND col2 > 3.14 >> /home/testoutpu.csv; -``` - diff --git a/docs-cn/12-taos-sql/07-function.md b/docs-cn/12-taos-sql/07-function.md deleted file mode 100644 index f6e564419ddaa18931b0f0e0e4e7b5b3219a92f6..0000000000000000000000000000000000000000 --- a/docs-cn/12-taos-sql/07-function.md +++ /dev/null @@ -1,1794 +0,0 @@ ---- -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) -``` - -### MODE - -``` -SELECT MODE(field_name) FROM tb_name [WHERE clause]; -``` - -**功能说明**：返回出现频率最高的值，若存在多个频率相同的最高值，输出空。不能匹配标签、时间戳输出。 - -**返回数据类型**：同应用的字段。 - -**应用字段**：适合于除时间主列外的任何类型字段。 - -**使用说明**：由于返回数据量未知，考虑到内存因素，为了函数可以正常返回结果，建议不重复的数据量在 10 万级别，否则会报错。 - -**支持的版本**：2.6.0.0 及以后的版本。 - -**示例**： - -``` -taos> select voltage from d002; - voltage | -======================== - 1 | - 1 | - 2 | - 19 | -Query OK, 4 row(s) in set (0.003545s) - -taos> select mode(voltage) from d002; - mode(voltage) | -======================== - 1 | -Query OK, 1 row(s) in set (0.019393s) -``` - -### HYPERLOGLOG - -``` -SELECT HYPERLOGLOG(field_name) FROM { tb_name | stb_name } [WHERE clause]; -``` - -**功能说明**： - - 采用 hyperloglog 算法，返回某列的基数。该算法在数据量很大的情况下，可以明显降低内存的占用，但是求出来的基数是个估算值，标准误差（标准误差是多次实验，每次的平均数的标准差，不是与真实结果的误差）为 0.81%。 - - 在数据量较少的时候该算法不是很准确，可以使用 select count(data) from (select unique(col) as data from table) 的方法。 - -**返回结果类型**：整形。 - -**应用字段**：适合于任何类型字段。 - -**支持的版本**：2.6.0.0 及以后的版本。 - -**示例**： - -``` -taos> select dbig from shll; - dbig | -======================== - 1 | - 1 | - 1 | - NULL | - 2 | - 19 | - NULL | - 9 | -Query OK, 8 row(s) in set (0.003755s) - -taos> select hyperloglog(dbig) from shll; - hyperloglog(dbig)| -======================== - 4 | -Query OK, 1 row(s) in set (0.008388s) -``` - -## 选择函数 - -在使用所有的选择函数的时候，可以同时指定输出 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) -``` - -### TAIL - -``` -SELECT TAIL(field_name, k, offset_val) FROM {tb_name | stb_name} [WHERE clause]; -``` - -**功能说明**：返回跳过最后 offset_value 个，然后取连续 k 个记录，不忽略 NULL 值。offset_val 可以不输入。此时返回最后的 k 个记录。当有 offset_val 输入的情况下，该函数功能等效于 `order by ts desc LIMIT k OFFSET offset_val`。 - -**参数范围**：k: [1,100] offset_val: [0,100]。 - -**返回结果数据类型**：同应用的字段。 - -**应用字段**：适合于除时间主列外的任何类型字段。 - -**支持版本**：2.6.0.0 及之后的版本。 - -**示例**： - -``` -taos> select ts,dbig from tail2; - ts | dbig | -================================================== -2021-10-15 00:31:33.000 | 1 | -2021-10-17 00:31:31.000 | NULL | -2021-12-24 00:31:34.000 | 2 | -2022-01-01 08:00:05.000 | 19 | -2022-01-01 08:00:06.000 | NULL | -2022-01-01 08:00:07.000 | 9 | -Query OK, 6 row(s) in set (0.001952s) - -taos> select tail(dbig,2,2) from tail2; -ts | tail(dbig,2,2) | -================================================== -2021-12-24 00:31:34.000 | 2 | -2022-01-01 08:00:05.000 | 19 | -Query OK, 2 row(s) in set (0.002307s) -``` - -### UNIQUE - -``` -SELECT UNIQUE(field_name) FROM {tb_name | stb_name} [WHERE clause]; -``` - -**功能说明**：返回该列的数值首次出现的值。该函数功能与 distinct 相似，但是可以匹配标签和时间戳信息。可以针对除时间列以外的字段进行查询，可以匹配标签和时间戳，其中的标签和时间戳是第一次出现时刻的标签和时间戳。 - -**返回结果数据类型**：同应用的字段。 - -**应用字段**：适合于除时间类型以外的字段。 - -**支持版本**：2.6.0.0 及之后的版本。 - -**使用说明**: - -- 该函数可以应用在普通表和超级表上。不能和窗口操作一起使用，例如 interval/state_window/session_window 。 -- 由于返回数据量未知，考虑到内存因素，为了函数可以正常返回结果，建议不重复的数据量在 10 万级别，否则会报错。 - -**示例**： - -``` -taos> select ts,voltage from unique1; - ts | voltage | -================================================== -2021-10-17 00:31:31.000 | 1 | -2022-01-24 00:31:31.000 | 1 | -2021-10-17 00:31:31.000 | 1 | -2021-12-24 00:31:31.000 | 2 | -2022-01-01 08:00:01.000 | 19 | -2021-10-17 00:31:31.000 | NULL | -2022-01-01 08:00:02.000 | NULL | -2022-01-01 08:00:03.000 | 9 | -Query OK, 8 row(s) in set (0.003018s) - -taos> select unique(voltage) from unique1; -ts | unique(voltage) | -================================================== -2021-10-17 00:31:31.000 | 1 | -2021-10-17 00:31:31.000 | NULL | -2021-12-24 00:31:31.000 | 2 | -2022-01-01 08:00:01.000 | 19 | -2022-01-01 08:00:03.000 | 9 | -Query OK, 5 row(s) in set (0.108458s) -``` - -## 计算函数 - -### 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）。 -- 从 2.6.0 开始，DIFF 函数支持 ignore_negative 参数 - -**示例**： - - ```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开始支持 - -### ASIN - -```sql - SELECT ASIN(field_name) FROM { tb_name | stb_name } [WHERE clause] -``` - -**功能说明**：获得指定列的反正弦结果 - -**返回结果类型**：DOUBLE。如果输入值为 NULL，输出值也为 NULL - -**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**使用说明**： - -- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 -- 该函数可以应用在普通表和超级表上。 -- 版本2.6.0.x后支持 - -### ACOS - -```sql - SELECT ACOS(field_name) FROM { tb_name | stb_name } [WHERE clause] -``` - -**功能说明**：获得指定列的反余弦结果 - -**返回结果类型**：DOUBLE。如果输入值为 NULL，输出值也为 NULL - -**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**使用说明**： - -- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 -- 该函数可以应用在普通表和超级表上。 -- 版本2.6.0.x后支持 - -### ATAN - -```sql - SELECT ATAN(field_name) FROM { tb_name | stb_name } [WHERE clause] -``` - -**功能说明**：获得指定列的反正切结果 - -**返回结果类型**：DOUBLE。如果输入值为 NULL，输出值也为 NULL - -**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**使用说明**： - -- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 -- 该函数可以应用在普通表和超级表上。 -- 版本2.6.0.x后支持 - -### SIN - -```sql - SELECT SIN(field_name) FROM { tb_name | stb_name } [WHERE clause] -``` - -**功能说明**：获得指定列的正弦结果 - -**返回结果类型**：DOUBLE。如果输入值为 NULL，输出值也为 NULL - -**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**使用说明**： - -- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 -- 该函数可以应用在普通表和超级表上。 -- 版本2.6.0.x后支持 - -### COS - -```sql - SELECT COS(field_name) FROM { tb_name | stb_name } [WHERE clause] -``` - -**功能说明**：获得指定列的余弦结果 - -**返回结果类型**：DOUBLE。如果输入值为 NULL，输出值也为 NULL - -**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**使用说明**： - -- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 -- 该函数可以应用在普通表和超级表上。 -- 版本2.6.0.x后支持 - -### TAN - -```sql - SELECT TAN(field_name) FROM { tb_name | stb_name } [WHERE clause] -``` - -**功能说明**：获得指定列的正切结果 - -**返回结果类型**：DOUBLE。如果输入值为 NULL，输出值也为 NULL - -**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**使用说明**： - -- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 -- 该函数可以应用在普通表和超级表上。 -- 版本2.6.0.x后支持 - -### POW - -```sql - SELECT POW(field_name, power) FROM { tb_name | stb_name } [WHERE clause] -``` - -**功能说明**：获得指定列的指数为 power 的幂 - -**返回结果类型**：DOUBLE。如果输入值为 NULL，输出值也为 NULL - -**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**使用说明**： - -- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 -- 该函数可以应用在普通表和超级表上。 -- 版本2.6.0.x后支持 - -### LOG - -```sql - SELECT LOG(field_name, base) FROM { tb_name | stb_name } [WHERE clause] -``` - -**功能说明**：获得指定列对于底数 base 的对数 - -**返回结果类型**：DOUBLE。如果输入值为 NULL，输出值也为 NULL - -**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**使用说明**： - -- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 -- 该函数可以应用在普通表和超级表上。 -- 版本2.6.0.x后支持 - -### ABS - -```sql - SELECT ABS(field_name) FROM { tb_name | stb_name } [WHERE clause] -``` - -**功能说明**：获得指定列的绝对值 - -**返回结果类型**：如果输入值为整数，输出值是 UBIGINT 类型。如果输入值是 FLOAT/DOUBLE 数据类型，输出值是 DOUBLE 数据类型。 - -**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**使用说明**： - -- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 -- 该函数可以应用在普通表和超级表上。 -- 版本2.6.0.x后支持 - -### SQRT - -```sql - SELECT SQRT(field_name) FROM { tb_name | stb_name } [WHERE clause] -``` - -**功能说明**：获得指定列的平方根 - -**返回结果类型**：DOUBLE。如果输入值为 NULL，输出值也为 NULL - -**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 - -**嵌套子查询支持**：适用于内层查询和外层查询。 - -**使用说明**： - -- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 -- 该函数可以应用在普通表和超级表上。 -- 版本2.6.0.x后支持 - -### CAST - -```sql - SELECT CAST(expression AS type_name) FROM { tb_name | stb_name } [WHERE clause] -``` - -**功能说明**：数据类型转换函数，输入参数 expression 支持普通列、常量、标量函数及它们之间的四则运算，不支持 tag 列，只适用于 select 子句中。 - -**返回结果类型**：CAST 中指定的类型（type_name）。 - -**适用数据类型**： - -- 输入参数 expression 的类型可以是除 JSON 外目前所有类型字段（BOOL/TINYINT/SMALLINT/INT/BIGINT/FLOAT/DOUBLE/BINARY(M)/TIMESTAMP/NCHAR(M)/TINYINT UNSIGNED/SMALLINT UNSIGNED/INT UNSIGNED/BIGINT UNSIGNED）; -- 输出目标类型只支持 BIGINT/BINARY(N)/TIMESTAMP/NCHAR(N)/BIGINT UNSIGNED。 - -**使用说明**： - -- 对于不能支持的类型转换会直接报错。 -- 如果输入值为NULL则输出值也为NULL。 -- 对于类型支持但某些值无法正确转换的情况对应的转换后的值以转换函数输出为准。目前可能遇到的几种情况： - 1）BINARY/NCHAR转BIGINT/BIGINT UNSIGNED时可能出现的无效字符情况，例如"a"可能转为0。 - 2）有符号数或TIMESTAMP转BIGINT UNSIGNED可能遇到的溢出问题。 - 3）BIGINT UNSIGNED转BIGINT可能遇到的溢出问题。 - 4）FLOAT/DOUBLE转BIGINT/BIGINT UNSIGNED可能遇到的溢出问题。 -- 版本2.6.0.x后支持 - -### CONCAT - -```sql - SELECT CONCAT(str1|column1, str2|column2, ...) FROM { tb_name | stb_name } [WHERE clause] -``` - -**功能说明**：字符串连接函数。 - -**返回结果类型**：同输入参数类型，BINARY 或者 NCHAR。 - -**适用数据类型**：输入参数或者全部是 BINARY 格式的字符串或者列，或者全部是 NCHAR 格式的字符串或者列。不能应用在 TAG 列。 - -**使用说明**： - -- 如果输入值为NULL，输出值为NULL。 -- 该函数最小参数个数为2个，最大参数个数为8个。 -- 该函数可以应用在普通表和超级表上。 -- 该函数适用于内层查询和外层查询。 -- 版本2.6.0.x后支持 - -### CONCAT_WS - -``` - SELECT CONCAT_WS(separator, str1|column1, str2|column2, ...) FROM { tb_name | stb_name } [WHERE clause] -``` - -**功能说明**：带分隔符的字符串连接函数。 - -**返回结果类型**：同输入参数类型，BINARY 或者 NCHAR。 - -**适用数据类型**：输入参数或者全部是 BINARY 格式的字符串或者列，或者全部是 NCHAR 格式的字符串或者列。不能应用在 TAG 列。 - -**使用说明**： - -- 如果separator值为NULL，输出值为NULL。如果separator值不为NULL，其他输入为NULL，输出为空串 -- 该函数最小参数个数为3个，最大参数个数为9个。 -- 该函数可以应用在普通表和超级表上。 -- 该函数适用于内层查询和外层查询。 -- 版本2.6.0.x后支持 - -### LENGTH - -``` - SELECT LENGTH(str|column) FROM { tb_name | stb_name } [WHERE clause] -``` - -**功能说明**：以字节计数的字符串长度。 - -**返回结果类型**：INT。 - -**适用数据类型**：输入参数是 BINARY 类型或者 NCHAR 类型的字符串或者列。不能应用在 TAG 列。 - -**使用说明** - -- 如果输入值为NULL，输出值为NULL。 -- 该函数可以应用在普通表和超级表上。 -- 函数适用于内层查询和外层查询。 -- 版本2.6.0.x后支持 - -### CHAR_LENGTH - -``` - SELECT CHAR_LENGTH(str|column) FROM { tb_name | stb_name } [WHERE clause] -``` - -**功能说明**：以字符计数的字符串长度。 - -**返回结果类型**：INT。 - -**适用数据类型**：输入参数是 BINARY 类型或者 NCHAR 类型的字符串或者列。不能应用在 TAG 列。 - -**使用说明** - -- 如果输入值为NULL，输出值为NULL。 -- 该函数可以应用在普通表和超级表上。 -- 该函数适用于内层查询和外层查询。 -- 版本2.6.0.x后支持 - -### LOWER - -``` - SELECT LOWER(str|column) FROM { tb_name | stb_name } [WHERE clause] -``` - -**功能说明**：将字符串参数值转换为全小写字母。 - -**返回结果类型**：同输入类型。 - -**适用数据类型**：输入参数是 BINARY 类型或者 NCHAR 类型的字符串或者列。不能应用在 TAG 列。 - -**使用说明**： - -- 如果输入值为NULL，输出值为NULL。 -- 该函数可以应用在普通表和超级表上。 -- 该函数适用于内层查询和外层查询。 -- 版本2.6.0.x后支持 - -### UPPER - -``` - SELECT UPPER(str|column) FROM { tb_name | stb_name } [WHERE clause] -``` - -**功能说明**：将字符串参数值转换为全大写字母。 - -**返回结果类型**：同输入类型。 - -**适用数据类型**：输入参数是 BINARY 类型或者 NCHAR 类型的字符串或者列。不能应用在 TAG 列。 - -**使用说明**： - -- 如果输入值为NULL，输出值为NULL。 -- 该函数可以应用在普通表和超级表上。 -- 该函数适用于内层查询和外层查询。 -- 版本2.6.0.x后支持 - -### LTRIM - -``` - SELECT LTRIM(str|column) FROM { tb_name | stb_name } [WHERE clause] -``` - -**功能说明**：返回清除左边空格后的字符串。 - -**返回结果类型**：同输入类型。 - -**适用数据类型**：输入参数是 BINARY 类型或者 NCHAR 类型的字符串或者列。不能应用在 TAG 列。 - -**使用说明**： - -- 如果输入值为NULL，输出值为NULL。 -- 该函数可以应用在普通表和超级表上。 -- 该函数适用于内层查询和外层查询。 -- 版本2.6.0.x后支持 - -### RTRIM - -``` - SELECT RTRIM(str|column) FROM { tb_name | stb_name } [WHERE clause] -``` - -**功能说明**：返回清除右边空格后的字符串。 - -**返回结果类型**：同输入类型。 - -**适用数据类型**：输入参数是 BINARY 类型或者 NCHAR 类型的字符串或者列。不能应用在 TAG 列。 - -**使用说明**： - -- 如果输入值为NULL，输出值为NULL。 -- 该函数可以应用在普通表和超级表上。 -- 该函数适用于内层查询和外层查询。 -- 版本2.6.0.x后支持 - -### SUBSTR - -``` - SELECT SUBSTR(str,pos[,len]) FROM { tb_name | stb_name } [WHERE clause] -``` - -**功能说明**：从源字符串 str 中的指定位置 pos 开始取一个长度为 len 的子串并返回。 - -**返回结果类型**：同输入类型。 - -**适用数据类型**：输入参数是 BINARY 类型或者 NCHAR 类型的字符串或者列。不能应用在 TAG 列。 - -**使用说明**： - -- 如果输入值为NULL，输出值为NULL。 -- 输入参数pos可以为正数，也可以为负数。如果pos是正数，表示开始位置从字符串开头正数计算。如果pos为负数，表示开始位置从字符串结尾倒数计算。如果输入参数len被忽略，返回的子串包含从pos开始的整个字串。 -- 该函数可以应用在普通表和超级表上。 -- 该函数适用于内层查询和外层查询。 -- 版本2.6.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) -``` - -### STATECOUNT - -``` -SELECT STATECOUNT(field_name, oper, val) FROM { tb_name | stb_name } [WHERE clause]; -``` - -**功能说明**：返回满足某个条件的连续记录的个数，结果作为新的一列追加在每行后面。条件根据参数计算，如果条件为 true 则加 1，条件为 false 则重置为-1，如果数据为 NULL，跳过该条数据。 - -**参数范围**： - -- oper : LT (小于)、GT（大于）、LE（小于等于）、GE（大于等于）、NE（不等于）、EQ（等于），不区分大小写。 -- val : 数值型 - -**返回结果类型**：整形。 - -**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上。 - -**嵌套子查询支持**：不支持应用在子查询上。 - -**支持的版本**：2.6 开始的版本。 - -**使用说明**： - -- 该函数可以应用在普通表上，在由 GROUP BY 划分出单独时间线的情况下用于超级表（也即 GROUP BY tbname） -- 不能和窗口操作一起使用，例如 interval/state_window/session_window。 - -**示例**： - -``` -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) -``` - -### STATEDURATION - -```sql -SELECT stateDuration(field_name, oper, val, unit) FROM { tb_name | stb_name } [WHERE clause]; -``` - -**功能说明**：返回满足某个条件的连续记录的时间长度，结果作为新的一列追加在每行后面。条件根据参数计算，如果条件为 true 则加上两个记录之间的时间长度（第一个满足条件的记录时间长度记为 0），条件为 false 则重置为-1，如果数据为 NULL，跳过该条数据。 - -**参数范围**： - -- oper : LT (小于)、GT（大于）、LE（小于等于）、GE（大于等于）、NE（不等于）、EQ（等于），不区分大小写。 -- val : 数值型 -- unit : 时间长度的单位，范围[1s、1m、1h ]，不足一个单位舍去。默认为 1s。 - -**返回结果类型**：整形。 - -**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上。 - -**嵌套子查询支持**：不支持应用在子查询上。 - -**支持的版本**：2.6 开始的版本。 - -**使用说明**： - -- 该函数可以应用在普通表上，在由 GROUP BY 划分出单独时间线的情况下用于超级表（也即 GROUP BY tbname） -- 不能和窗口操作一起使用，例如 interval/state_window/session_window。 - -**示例**： - -``` -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.002407s) - -taos> select stateDuration(dbig,GT,2) from statef2; -ts | dbig | stateduration(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 | 0 | -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.002613s) -``` - -## 时间函数 - -从 2.6.0.0 版本开始，TDengine 查询引擎支持以下时间相关函数： - -### NOW - -```sql -SELECT NOW() FROM { tb_name | stb_name } [WHERE clause]; -SELECT select_expr FROM { tb_name | stb_name } WHERE ts_col cond_operatior NOW(); -INSERT INTO tb_name VALUES (NOW(), ...); -``` - -**功能说明**：返回客户端当前系统时间。 - -**返回结果数据类型**：TIMESTAMP 时间戳类型。 - -**应用字段**：在 WHERE 或 INSERT 语句中使用时只能作用于 TIMESTAMP 类型的字段。 - -**适用于**：表、超级表。 - -**使用说明**： - -- 支持时间加减操作，如 NOW() + 1s, 支持的时间单位如下： - b(纳秒)、u(微秒)、a(毫秒)、s(秒)、m(分)、h(小时)、d(天)、w(周)。 -- 返回的时间戳精度与当前 DATABASE 设置的时间精度一致。 - -**示例**： - -```sql -taos> SELECT NOW() FROM meters; - now() | -========================== - 2022-02-02 02:02:02.456 | -Query OK, 1 row(s) in set (0.002093s) - -taos> SELECT NOW() + 1h FROM meters; - now() + 1h | -========================== - 2022-02-02 03:02:02.456 | -Query OK, 1 row(s) in set (0.002093s) - -taos> SELECT COUNT(voltage) FROM d1001 WHERE ts < NOW(); - count(voltage) | -============================= - 5 | -Query OK, 5 row(s) in set (0.004475s) - -taos> INSERT INTO d1001 VALUES (NOW(), 10.2, 219, 0.32); -Query OK, 1 of 1 row(s) in database (0.002210s) -``` - -### TODAY - -```sql -SELECT TODAY() FROM { tb_name | stb_name } [WHERE clause]; -SELECT select_expr FROM { tb_name | stb_name } WHERE ts_col cond_operatior TODAY()]; -INSERT INTO tb_name VALUES (TODAY(), ...); -``` - -**功能说明**：返回客户端当日零时的系统时间。 - -**返回结果数据类型**：TIMESTAMP 时间戳类型。 - -**应用字段**：在 WHERE 或 INSERT 语句中使用时只能作用于 TIMESTAMP 类型的字段。 - -**适用于**：表、超级表。 - -**使用说明**： - -- 支持时间加减操作，如 TODAY() + 1s, 支持的时间单位如下： - b(纳秒)，u(微秒)，a(毫秒)，s(秒)，m(分)，h(小时)，d(天)，w(周)。 -- 返回的时间戳精度与当前 DATABASE 设置的时间精度一致。 - -**示例**： - -```sql -taos> SELECT TODAY() FROM meters; - today() | -========================== - 2022-02-02 00:00:00.000 | -Query OK, 1 row(s) in set (0.002093s) - -taos> SELECT TODAY() + 1h FROM meters; - today() + 1h | -========================== - 2022-02-02 01:00:00.000 | -Query OK, 1 row(s) in set (0.002093s) - -taos> SELECT COUNT(voltage) FROM d1001 WHERE ts < TODAY(); - count(voltage) | -============================= - 5 | -Query OK, 5 row(s) in set (0.004475s) - -taos> INSERT INTO d1001 VALUES (TODAY(), 10.2, 219, 0.32); -Query OK, 1 of 1 row(s) in database (0.002210s) -``` - -### TIMEZONE - -```sql -SELECT TIMEZONE() FROM { tb_name | stb_name } [WHERE clause]; -``` - -**功能说明**：返回客户端当前时区信息。 - -**返回结果数据类型**：BINARY 类型。 - -**应用字段**：无 - -**适用于**：表、超级表。 - -**示例**： - -```sql -taos> SELECT TIMEZONE() FROM meters; - timezone() | -================================= - UTC (UTC, +0000) | -Query OK, 1 row(s) in set (0.002093s) -``` - -### TO_ISO8601 - -```sql -SELECT TO_ISO8601(ts_val | ts_col) FROM { tb_name | stb_name } [WHERE clause]; -``` - -**功能说明**：将 UNIX 时间戳转换成为 ISO8601 标准的日期时间格式，并附加客户端时区信息。 - -**返回结果数据类型**：BINARY 类型。 - -**应用字段**：UNIX 时间戳常量或是 TIMESTAMP 类型的列 - -**适用于**：表、超级表。 - -**使用说明**： - -- 如果输入是 UNIX 时间戳常量，返回格式精度由时间戳的位数决定; -- 如果输入是 TIMSTAMP 类型的列，返回格式的时间戳精度与当前 DATABASE 设置的时间精度一致。 - -**示例**： - -```sql -taos> SELECT TO_ISO8601(1643738400) FROM meters; - to_iso8601(1643738400) | -============================== - 2022-02-02T02:00:00+0800 | - -taos> SELECT TO_ISO8601(ts) FROM meters; - to_iso8601(ts) | -============================== - 2022-02-02T02:00:00+0800 | - 2022-02-02T02:00:00+0800 | - 2022-02-02T02:00:00+0800 | -``` - -### TO_UNIXTIMESTAMP - -```sql -SELECT TO_UNIXTIMESTAMP(datetime_string | ts_col) FROM { tb_name | stb_name } [WHERE clause]; -``` - -**功能说明**：将日期时间格式的字符串转换成为 UNIX 时间戳。 - -**返回结果数据类型**：长整型 INT64。 - -**应用字段**：字符串常量或是 BINARY/NCHAR 类型的列。 - -**适用于**：表、超级表。 - -**使用说明**： - -- 输入的日期时间字符串须符合 ISO8601/RFC3339 标准，无法转换的字符串格式将返回 0。 -- 返回的时间戳精度与当前 DATABASE 设置的时间精度一致。 - -**示例**： - -```sql -taos> SELECT TO_UNIXTIMESTAMP("2022-02-02T02:00:00.000Z") FROM meters; -to_unixtimestamp("2022-02-02T02:00:00.000Z") | -============================================== - 1643767200000 | - -taos> SELECT TO_UNIXTIMESTAMP(col_binary) FROM meters; - to_unixtimestamp(col_binary) | -======================================== - 1643767200000 | - 1643767200000 | - 1643767200000 | -``` - -### TIMETRUNCATE - -```sql -SELECT TIMETRUNCATE(ts_val | datetime_string | ts_col, time_unit) FROM { tb_name | stb_name } [WHERE clause]; -``` - -**功能说明**：将时间戳按照指定时间单位 time_unit 进行截断。 - -**返回结果数据类型**：TIMESTAMP 时间戳类型。 - -**应用字段**：UNIX 时间戳，日期时间格式的字符串，或者 TIMESTAMP 类型的列。 - -**适用于**：表、超级表。 - -**使用说明**： -- 支持的时间单位 time_unit 如下： - 1u(微秒)，1a(毫秒)，1s(秒)，1m(分)，1h(小时)，1d(天)。 -- 返回的时间戳精度与当前 DATABASE 设置的时间精度一致。 - -**示例**： - -```sql -taos> SELECT TIMETRUNCATE(1643738522000, 1h) FROM meters; - timetruncate(1643738522000, 1h) | -=================================== - 2022-02-02 02:00:00.000 | -Query OK, 1 row(s) in set (0.001499s) - -taos> SELECT TIMETRUNCATE("2022-02-02 02:02:02", 1h) FROM meters; - timetruncate("2022-02-02 02:02:02", 1h) | -=========================================== - 2022-02-02 02:00:00.000 | -Query OK, 1 row(s) in set (0.003903s) - -taos> SELECT TIMETRUNCATE(ts, 1h) FROM meters; - timetruncate(ts, 1h) | -========================== - 2022-02-02 02:00:00.000 | - 2022-02-02 02:00:00.000 | - 2022-02-02 02:00:00.000 | -Query OK, 3 row(s) in set (0.003903s) -``` - -### TIMEDIFF - -```sql -SELECT TIMEDIFF(ts_val1 | datetime_string1 | ts_col1, ts_val2 | datetime_string2 | ts_col2 [, time_unit]) FROM { tb_name | stb_name } [WHERE clause]; -``` - -**功能说明**：计算两个时间戳之间的差值，并近似到时间单位 time_unit 指定的精度。 - -**返回结果数据类型**：长整型 INT64。 - -**应用字段**：UNIX 时间戳，日期时间格式的字符串，或者 TIMESTAMP 类型的列。 - -**适用于**：表、超级表。 - -**使用说明**： -- 支持的时间单位 time_unit 如下： - 1u(微秒)，1a(毫秒)，1s(秒)，1m(分)，1h(小时)，1d(天)。 -- 如果时间单位 time_unit 未指定， 返回的时间差值精度与当前 DATABASE 设置的时间精度一致。 - -**示例**： - -```sql -taos> SELECT TIMEDIFF(1643738400000, 1643742000000) FROM meters; - timediff(1643738400000, 1643742000000) | -========================================= - 3600000 | -Query OK, 1 row(s) in set (0.002553s) -taos> SELECT TIMEDIFF(1643738400000, 1643742000000, 1h) FROM meters; - timediff(1643738400000, 1643742000000, 1h) | -============================================= - 1 | -Query OK, 1 row(s) in set (0.003726s) - -taos> SELECT TIMEDIFF("2022-02-02 03:00:00", "2022-02-02 02:00:00", 1h) FROM meters; - timediff("2022-02-02 03:00:00", "2022-02-02 02:00:00", 1h) | -============================================================= - 1 | -Query OK, 1 row(s) in set (0.001937s) - -taos> SELECT TIMEDIFF(ts_col1, ts_col2, 1h) FROM meters; - timediff(ts_col1, ts_col2, 1h) | -=================================== - 1 | -Query OK, 1 row(s) in set (0.001937s) -``` diff --git a/docs-cn/12-taos-sql/08-interval.md b/docs-cn/12-taos-sql/08-interval.md deleted file mode 100644 index d62e11b0dbd0ba49ceedb3807e05361f060969b3..0000000000000000000000000000000000000000 --- a/docs-cn/12-taos-sql/08-interval.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -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 deleted file mode 100644 index 3c86a3862174377e6a00d046fb69627c773fe76e..0000000000000000000000000000000000000000 --- a/docs-cn/12-taos-sql/09-limit.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -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/12-keywords/_category_.yml b/docs-cn/12-taos-sql/12-keywords/_category_.yml deleted file mode 100644 index 67738650a4564477f017542aea81767b3de72922..0000000000000000000000000000000000000000 --- a/docs-cn/12-taos-sql/12-keywords/_category_.yml +++ /dev/null @@ -1 +0,0 @@ -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 deleted file mode 100644 index 608d4e080967cfd97072706cf0963ae669960be6..0000000000000000000000000000000000000000 --- a/docs-cn/12-taos-sql/12-keywords/index.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -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/index.md b/docs-cn/12-taos-sql/index.md deleted file mode 100644 index c34c1e5dc812ad589a0c4fdf89a8d02ff4fd18a4..0000000000000000000000000000000000000000 --- a/docs-cn/12-taos-sql/index.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -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。 \ No newline at end of file diff --git a/docs-cn/13-operation/03-tolerance.md b/docs-cn/13-operation/03-tolerance.md deleted file mode 100644 index 054e5c4cee07f7066038a6bfc5c4b25306b033ce..0000000000000000000000000000000000000000 --- a/docs-cn/13-operation/03-tolerance.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -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/11-optimize.md b/docs-cn/13-operation/11-optimize.md deleted file mode 100644 index 57411dbbb0705ae4c9c4568bb09909918bcee6a3..0000000000000000000000000000000000000000 --- a/docs-cn/13-operation/11-optimize.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -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: 系统中裁决器的 end point，缺省为空。 -- 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/_category_.yml b/docs-cn/13-operation/_category_.yml deleted file mode 100644 index 930e441defdc80215ce5d90375a9cbd2d4bad947..0000000000000000000000000000000000000000 --- a/docs-cn/13-operation/_category_.yml +++ /dev/null @@ -1,4 +0,0 @@ -label: 运维指南 -link: - slug: /operation/ - type: generated-index 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 deleted file mode 100644 index defa1e094c59622c437924af00ff80492ceda514..0000000000000000000000000000000000000000 --- a/docs-cn/14-reference/02-rest-api/02-rest-api.mdx +++ /dev/null @@ -1,307 +0,0 @@ ---- -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)。 - -注意：与原生连接器的一个区别是，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 语句中的数据表应提供数据库前缀，例如 \.\。如果表名不带数据库前缀，又没有在 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 采用 `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 采用 `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：非常详细的调试信息，默认 131。 -- httpDbNameMandatory: 是否必须在 RESTful url 中指定默认的数据库名。默认为 0，即关闭此检查。如果设置为 1，那么每个 RESTful url 中都必须设置一个默认数据库名，否则无论此时执行的 SQL 语句是否需要指定数据库，都会返回一个执行错误，拒绝执行此 SQL 语句。 - -:::note -如果使用 taosd 提供的 REST API, 那么以上配置需要写在 taosd 的配置文件 taos.cfg 中。如果使用 taosAdaper 提供的 REST API, 那么需要参考 taosAdaper [对应的配置方法](/reference/taosadapter/)。 - -::: diff --git a/docs-cn/14-reference/03-connector/03-connector.mdx b/docs-cn/14-reference/03-connector/03-connector.mdx deleted file mode 100644 index c0e714f148a7821e070be38a5484484fdd747e9a..0000000000000000000000000000000000000000 --- a/docs-cn/14-reference/03-connector/03-connector.mdx +++ /dev/null @@ -1,117 +0,0 @@ ---- -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/_verify_linux.mdx b/docs-cn/14-reference/03-connector/_verify_linux.mdx deleted file mode 100644 index af543108f88e1255ba700b8b70dbe838eb32f93d..0000000000000000000000000000000000000000 --- a/docs-cn/14-reference/03-connector/_verify_linux.mdx +++ /dev/null @@ -1,14 +0,0 @@ -在 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 deleted file mode 100644 index 19ac71ec310ea18eb8dacde6dfa34f3bcd57f560..0000000000000000000000000000000000000000 --- a/docs-cn/14-reference/03-connector/_verify_windows.mdx +++ /dev/null @@ -1,14 +0,0 @@ -在 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/cpp.mdx b/docs-cn/14-reference/03-connector/cpp.mdx deleted file mode 100644 index fb14609fb7ddd6b830c4e4369bdaa725a6b22658..0000000000000000000000000000000000000000 --- a/docs-cn/14-reference/03-connector/cpp.mdx +++ /dev/null @@ -1,450 +0,0 @@ ---- -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 返回错误（返回错误码或空指针）时获取错误信息。 - -### 无模式写入 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 deleted file mode 100644 index bbefaacb459153ab5116d557fdf1940d487b4bd3..0000000000000000000000000000000000000000 --- a/docs-cn/14-reference/03-connector/csharp.mdx +++ /dev/null @@ -1,189 +0,0 @@ ---- -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 "../../04-develop/03-insert-data/_cs_sql.mdx" -import CSInfluxLine from "../../04-develop/03-insert-data/_cs_line.mdx" -import CSOpenTSDBTelnet from "../../04-develop/03-insert-data/_cs_opts_telnet.mdx" -import CSOpenTSDBJson from "../../04-develop/03-insert-data/_cs_opts_json.mdx" -import CSQuery from "../../04-develop/04-query-data/_cs.mdx" -import CSAsyncQuery from "../../04-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 deleted file mode 100644 index 694dfc2510ca668391dc735bbe99812645c2d7b0..0000000000000000000000000000000000000000 --- a/docs-cn/14-reference/03-connector/go.mdx +++ /dev/null @@ -1,411 +0,0 @@ ---- -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 "../../04-develop/03-insert-data/_go_sql.mdx" -import GoInfluxLine from "../../04-develop/03-insert-data/_go_line.mdx" -import GoOpenTSDBTelnet from "../../04-develop/03-insert-data/_go_opts_telnet.mdx" -import GoOpenTSDBJson from "../../04-develop/03-insert-data/_go_opts_json.mdx" -import GoQuery from "../../04-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 deleted file mode 100644 index f80a019a4ab433cc66944c0ff6b6110d34571baf..0000000000000000000000000000000000000000 --- a/docs-cn/14-reference/03-connector/java.mdx +++ /dev/null @@ -1,839 +0,0 @@ ---- -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.0.18 及更高版本）。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 deleted file mode 100644 index 0afcf2457dfdb11c01657abd983601322899b8fb..0000000000000000000000000000000000000000 --- a/docs-cn/14-reference/03-connector/node.mdx +++ /dev/null @@ -1,259 +0,0 @@ ---- -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 "../../04-develop/03-insert-data/_js_sql.mdx"; -import NodeInfluxLine from "../../04-develop/03-insert-data/_js_line.mdx"; -import NodeOpenTSDBTelnet from "../../04-develop/03-insert-data/_js_opts_telnet.mdx"; -import NodeOpenTSDBJson from "../../04-develop/03-insert-data/_js_opts_json.mdx"; -import NodeQuery from "../../04-develop/04-query-data/_js.mdx"; -import NodeAsyncQuery from "../../04-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 deleted file mode 100644 index 5e6cdfba4fc3ee7fd6073b0264b54705c444bead..0000000000000000000000000000000000000000 --- a/docs-cn/14-reference/03-connector/python.mdx +++ /dev/null @@ -1,353 +0,0 @@ ---- -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`。 一般无需配置。 - -:::note - -::: - - - - -## 示例程序 - -### 基本使用 - - - - -##### 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 -查询结果只能获取一次。比如上面的示例中 `featch_all` 和 `fetch_all_into_dict` 只能用一个。重复获取得到的结果为空列表。 -::: - -##### TaosResult 类的使用 - -上面 `TaosConnection` 类的使用示例中，我们已经展示了两种获取查询结果的方法： `featch_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 deleted file mode 100644 index b6aac45c6ab30405190ab3ced39de017033e760a..0000000000000000000000000000000000000000 --- a/docs-cn/14-reference/03-connector/rust.mdx +++ /dev/null @@ -1,388 +0,0 @@ ---- -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 "../../04-develop/03-insert-data/_rust_sql.mdx" -import RustInfluxLine from "../../04-develop/03-insert-data/_rust_line.mdx" -import RustOpenTSDBTelnet from "../../04-develop/03-insert-data/_rust_opts_telnet.mdx" -import RustOpenTSDBJson from "../../04-develop/03-insert-data/_rust_opts_json.mdx" -import RustQuery from "../../04-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 deleted file mode 100644 index 1cb8401ea30b01d8db652ed4ea70ecc511de7461..0000000000000000000000000000000000000000 Binary files a/docs-cn/14-reference/03-connector/tdengine-jdbc-connector.png and /dev/null differ diff --git a/docs-cn/14-reference/04-taosadapter.md b/docs-cn/14-reference/04-taosadapter.md deleted file mode 100644 index 158d4ab008c3b3eca28cd469c38f451b22678518..0000000000000000000000000000000000000000 --- a/docs-cn/14-reference/04-taosadapter.md +++ /dev/null @@ -1,338 +0,0 @@ ---- -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 deleted file mode 100644 index dbf6847d514d70852204963c289d2bf901d7cbf0..0000000000000000000000000000000000000000 --- a/docs-cn/14-reference/05-taosbenchmark.md +++ /dev/null @@ -1,434 +0,0 @@ ---- -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` 必须设置为 `qeury`，该参数及其它通用参数详见[通用配置参数](#通用配置参数) - -#### 执行指定查询语句的配置参数 - -查询子表或者普通表的配置参数在 `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。 - -- **interva** : 执行订阅的时间间隔，单位为秒，默认为 0。 - -- **restart** : "yes" 表示开始新的订阅，"no" 表示继续之前的订阅，默认值为 "no"。 - -- **keepProgress** : "yes" 表示保留订阅进度，"no" 表示不保留，默认值为 "no"。 - -- **resubAfterConsume** : "yes" 表示取消之前的订阅然后再次订阅， "no" 表示继续之前的订阅，默认值为 "no"。 - -- **sqls** ： - - **sql** : 执行的 SQL 命令，必填。 - - **result** : 保存查询结果的文件，未指定则不保存。 - -#### 订阅超级表的配置参数 - -订阅超级表的配置参数在 `super_table_query` 中设置。 - -- **stblname** : 要订阅的超级表名称，必填。 - -- **threads** : 执行 SQL 的线程数，默认为 1。 - -- **interva** : 执行订阅的时间间隔，单位为秒，默认为 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 deleted file mode 100644 index 7131493ec9439225d8047288ed86026c887f0aac..0000000000000000000000000000000000000000 --- a/docs-cn/14-reference/06-taosdump.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -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/TDinsight-1-cluster-status.png b/docs-cn/14-reference/07-tdinsight/assets/TDinsight-1-cluster-status.png deleted file mode 100644 index 4708f836feb21980f2db7fed4a55f799b23a6ec1..0000000000000000000000000000000000000000 Binary files a/docs-cn/14-reference/07-tdinsight/assets/TDinsight-1-cluster-status.png and /dev/null 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 deleted file mode 100644 index f2684e6eed70e8f56697eae42b495d6bd62815e8..0000000000000000000000000000000000000000 Binary files a/docs-cn/14-reference/07-tdinsight/assets/TDinsight-2-dnodes.png and /dev/null 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 deleted file mode 100644 index 74686691e4106b8646c3deee1e0ce73b2f53f1ea..0000000000000000000000000000000000000000 Binary files a/docs-cn/14-reference/07-tdinsight/assets/TDinsight-3-mnodes.png and /dev/null 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 deleted file mode 100644 index 27964215567f9f961c0aeaf1b863188437008fb7..0000000000000000000000000000000000000000 Binary files a/docs-cn/14-reference/07-tdinsight/assets/TDinsight-4-requests.png and /dev/null 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 deleted file mode 100644 index b0d3abbf21ec4d4bd7bfb95fcc03a5f936b22665..0000000000000000000000000000000000000000 Binary files a/docs-cn/14-reference/07-tdinsight/assets/TDinsight-5-database.png and /dev/null 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 deleted file mode 100644 index 2b54cbeb83bcff12f20461a4f57f882e2073f231..0000000000000000000000000000000000000000 Binary files a/docs-cn/14-reference/07-tdinsight/assets/TDinsight-6-dnode-usage.png and /dev/null 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 deleted file mode 100644 index eb3848657f13900c856ac595c20766465157e9c4..0000000000000000000000000000000000000000 Binary files a/docs-cn/14-reference/07-tdinsight/assets/TDinsight-7-login-history.png and /dev/null differ diff --git a/docs-cn/14-reference/07-tdinsight/assets/TDinsight-8-taosadaper.png b/docs-cn/14-reference/07-tdinsight/assets/TDinsight-8-taosadaper.png deleted file mode 100644 index d94b2e02ac9855bb3d2f77d8902e068839db364f..0000000000000000000000000000000000000000 Binary files a/docs-cn/14-reference/07-tdinsight/assets/TDinsight-8-taosadaper.png and /dev/null 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 deleted file mode 100644 index 654df2934597ce600a1dc2dcd0cab7e29de7076d..0000000000000000000000000000000000000000 Binary files a/docs-cn/14-reference/07-tdinsight/assets/TDinsight-full.png and /dev/null 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 deleted file mode 100644 index e3afa22c0326d70567ec4529c83101c746daac87..0000000000000000000000000000000000000000 Binary files a/docs-cn/14-reference/07-tdinsight/assets/alert-manager-status.png and /dev/null 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 deleted file mode 100644 index 198bf37141c86a66cdd91b47a331bcdeb83daaf8..0000000000000000000000000000000000000000 Binary files a/docs-cn/14-reference/07-tdinsight/assets/alert-notification-channel.png and /dev/null 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 deleted file mode 100644 index ace3aa3c2f8f14fabdac54bc25ae2d9449445b69..0000000000000000000000000000000000000000 Binary files a/docs-cn/14-reference/07-tdinsight/assets/alert-query-demo.png and /dev/null 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 deleted file mode 100644 index 7082e49f6beb8690c36f98a3f4ff2befdb8fd014..0000000000000000000000000000000000000000 Binary files a/docs-cn/14-reference/07-tdinsight/assets/alert-rule-condition-notifications.png and /dev/null 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 deleted file mode 100644 index ffd4911b53854c42dbf0ff11838cb604fa694138..0000000000000000000000000000000000000000 Binary files a/docs-cn/14-reference/07-tdinsight/assets/alert-rule-test.png and /dev/null 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 deleted file mode 100644 index 802c7366f921301bd7fbc62458e56b2d1eaf195c..0000000000000000000000000000000000000000 Binary files a/docs-cn/14-reference/07-tdinsight/assets/howto-add-datasource-button.png and /dev/null 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 deleted file mode 100644 index 019ec921b6f808671f4f864ddf3380159d4a0dcc..0000000000000000000000000000000000000000 Binary files a/docs-cn/14-reference/07-tdinsight/assets/howto-add-datasource-tdengine.png and /dev/null 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 deleted file mode 100644 index 3963abb4ea8ae0e6f5557466f7a5b746c2d2ea3c..0000000000000000000000000000000000000000 Binary files a/docs-cn/14-reference/07-tdinsight/assets/howto-add-datasource-test.png and /dev/null 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 deleted file mode 100644 index 837100464b35a5cafac474723aef603f91945ebc..0000000000000000000000000000000000000000 Binary files a/docs-cn/14-reference/07-tdinsight/assets/howto-add-datasource.png and /dev/null 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 deleted file mode 100644 index 98223df25499effac343ff5723544a3c289f18fa..0000000000000000000000000000000000000000 Binary files a/docs-cn/14-reference/07-tdinsight/assets/howto-dashboard-display.png and /dev/null 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 deleted file mode 100644 index 07aba348f02b4fb8ef68e79664920c119b842d4c..0000000000000000000000000000000000000000 Binary files a/docs-cn/14-reference/07-tdinsight/assets/howto-dashboard-import-options.png and /dev/null 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 deleted file mode 100644 index 7e28939ead8bf3b6e2b4330e4f9b59c2e39b5c1c..0000000000000000000000000000000000000000 Binary files a/docs-cn/14-reference/07-tdinsight/assets/howto-import-dashboard.png and /dev/null 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 deleted file mode 100644 index 981f640b14d18aa6f0682768d8405a232df500f6..0000000000000000000000000000000000000000 Binary files a/docs-cn/14-reference/07-tdinsight/assets/import-dashboard-15167.png and /dev/null 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 deleted file mode 100644 index 94ef4fa5fe63e535118a81707b413c028ce01f70..0000000000000000000000000000000000000000 Binary files a/docs-cn/14-reference/07-tdinsight/assets/import-dashboard-for-tdengine.png and /dev/null 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 deleted file mode 100644 index 670cacc377c2801fa9437c3c132c5c7fbc361b0f..0000000000000000000000000000000000000000 Binary files a/docs-cn/14-reference/07-tdinsight/assets/import-via-grafana-dot-com.png and /dev/null 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 deleted file mode 100644 index d74cd36c96ee0fd24ddc6feae2da07824816f745..0000000000000000000000000000000000000000 Binary files a/docs-cn/14-reference/07-tdinsight/assets/import_dashboard.png and /dev/null differ diff --git a/docs-cn/14-reference/07-tdinsight/assets/tdengine_dashboard.png b/docs-cn/14-reference/07-tdinsight/assets/tdengine_dashboard.png deleted file mode 100644 index 0101e7430cb2ef673818de8bd3af53d0d082ad3f..0000000000000000000000000000000000000000 Binary files a/docs-cn/14-reference/07-tdinsight/assets/tdengine_dashboard.png and /dev/null differ diff --git a/docs-cn/14-reference/07-tdinsight/index.md b/docs-cn/14-reference/07-tdinsight/index.md deleted file mode 100644 index 553ae48b285f39a1fb29ebe946cb9b949adf9664..0000000000000000000000000000000000000000 --- a/docs-cn/14-reference/07-tdinsight/index.md +++ /dev/null @@ -1,427 +0,0 @@ ---- -title: TDinsight - 基于Grafana的TDengine零依赖监控解决方案 -sidebar_label: TDinsight ---- - -TDinsight 是使用 [TDengine] 原生监控数据库和 [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 -``` - -这个脚本会自动下载最新的[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 的用法说明： - -```bash -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 orgnization 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 -``` - -### 配置 Grafana - -将以下设置添加到配置文件 `/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, mdodes, 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%时触发。 -- **Messuring 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-taosadaper.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 deleted file mode 100644 index c9167fcf2643954981925fb5ef67a60cbad97a6d..0000000000000000000000000000000000000000 --- a/docs-cn/14-reference/08-taos-shell.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: TDengine 命令行(CLI) -sidebar_label: TDengine CLI -description: TDengine CLI 的使用说明和技巧 ---- - -TDengine 命令行程序（以下简称 TDengine CLI）是用户操作 TDengine 实例并与之交互的最简洁最常用的方式。 - -## 安装 - -如果在 TDengine 服务器端执行，无需任何安装，已经自动安装好。如果要在非 TDengine 服务器端运行，需要安装 TDengine 客户端驱动，具体安装，请参考 [连接器](/reference/connector/)。 - -## 执行 - -要进入 TDengine CLI，您只要在 Linux 终端或Windos 终端执行 `taos` 即可。 - -```bash -taos -``` -如果连接服务成功，将会打印出欢迎消息和版本信息。如果失败，则会打印错误消息出来（请参考 [FAQ](/train-faq/faq) 来解决终端连接服务端失败的问题）。TDengine CLI 的提示符号如下： - -```cmd -taos> -``` -进入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: 指定配置文件目录，默认为 `/etc/taos`，该目录下的配置文件默认名称为 taos.cfg -- -C, --dump-config: 打印 -c 指定的目录中 taos.cfg 的配置参数 -- -d, --database=DATABASE: 指定连接到服务端时使用的数据库 -- -D, --directory=DIRECTORY: 导入指定路径中的 SQL 脚本文件 -- -f, --file=FILE: 以非交互模式执行 SQL 脚本文件 -- -k, --check=CHECK: 指定要检查的表 -- -l, --pktlen=PKTLEN: 网络测试时使用的测试包大小 -- -n, --netrole=NETROLE: 网络连接测试时的测试范围，默认为 startup, 可选值为 client, server, rpc, startup, sync, speed, fqdn -- -r, --raw-time: 将时间输出出 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 小技巧 - -- 可以使用上下光标键查看历史输入的指令 -- 修改用户密码：在 shell 中使用 `alter user` 命令，缺省密码为 taosdata -- ctrl+c 中止正在进行中的查询 -- 执行 `RESET QUERY CACHE` 可清除本地缓存的表 schema -- 批量执行 SQL 语句。可以将一系列的 shell 命令（以英文 ; 结尾，每个 SQL 语句为一行）按行存放在文件里，在 shell 里执行命令 `source ` 自动执行该文件里所有的 SQL 语句 -- 输入 q 回车，退出 taos shell diff --git a/docs-cn/14-reference/11-docker/index.md b/docs-cn/14-reference/11-docker/index.md deleted file mode 100644 index daac309c2382d50f7afae68e5852cb0106ac7ff2..0000000000000000000000000000000000000000 --- a/docs-cn/14-reference/11-docker/index.md +++ /dev/null @@ -1,515 +0,0 @@ ---- -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 - ersion: "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/index.md b/docs-cn/14-reference/12-config/index.md deleted file mode 100644 index 9fff685ee6bfe9ef77b3a83d8b49ccc13216e0ce..0000000000000000000000000000000000000000 --- a/docs-cn/14-reference/12-config/index.md +++ /dev/null @@ -1,1126 +0,0 @@ ---- -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 的 end point | -| 缺省值 | localhost:6030 | - -### secondEp - -| 属性 | 说明 | -| -------- | ---------------------------------------------------------------------------- | -| 适用范围 | 服务端和客户端均适用 | -| 含义 | taosd 或者 taos 启动时，如果 firstEp 连接不上，尝试连接集群中第二个 dnode 的 end point | -| 缺省值 | 无 | - -### 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 级别 | -| 取值范围 | 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 - -| 属性 | 说明 | -| -------- | ------------------------ | -| 适用范围 | 仅服务端适用 | -| 含义 | 系统中裁决器的 end point，其格式如firstEp | -| 缺省值 | 空 | - -## 时间相关 - -### 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/13-schemaless/13-schemaless.md b/docs-cn/14-reference/13-schemaless/13-schemaless.md deleted file mode 100644 index d5ec8ddc44bcc73b189089856959b31ea27e3caf..0000000000000000000000000000000000000000 --- a/docs-cn/14-reference/13-schemaless/13-schemaless.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -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 中的每个数据项都需要对自身的数据类型进行描述。具体来说： - -- 如果两边有英文双引号，表示 BIANRY(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/_category_.yml b/docs-cn/14-reference/_category_.yml deleted file mode 100644 index 079c784e6512109661afe08c12b398e8c4fab720..0000000000000000000000000000000000000000 --- a/docs-cn/14-reference/_category_.yml +++ /dev/null @@ -1,5 +0,0 @@ -label: 参考指南 -link: - slug: /reference/ - type: generated-index - description: "参考指南是对 TDengine 本身、 TDengine 各语言连接器及自带的工具最详细的介绍。" diff --git a/docs-cn/14-reference/taosAdapter-architecture.png b/docs-cn/14-reference/taosAdapter-architecture.png deleted file mode 100644 index 08a9018553aae6f86b42d127b372d0cecfa9bdf8..0000000000000000000000000000000000000000 Binary files a/docs-cn/14-reference/taosAdapter-architecture.png and /dev/null differ diff --git a/docs-cn/20-third-party/01-grafana.mdx b/docs-cn/20-third-party/01-grafana.mdx deleted file mode 100644 index 39420a01a308d41924d189fce75e8a372e294eba..0000000000000000000000000000000000000000 --- a/docs-cn/20-third-party/01-grafana.mdx +++ /dev/null @@ -1,101 +0,0 @@ ---- -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.4/tdengine-datasource-3.1.4.zip \ - plugins install tdengine-datasource -``` - -或者下载到本地并解压到 Grafana 插件目录。 - -```bash -GF_VERSION=3.1.4 -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/ -``` - -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/08-tcollector.md b/docs-cn/20-third-party/08-tcollector.md deleted file mode 100644 index 5fbf001fa093f978dfdcd0f3f344a131d56ed9f9..0000000000000000000000000000000000000000 --- a/docs-cn/20-third-party/08-tcollector.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -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 deleted file mode 100644 index 52a6e79dfc6e562b7a11be525c65efc40cfc91cc..0000000000000000000000000000000000000000 --- a/docs-cn/20-third-party/09-emq-broker.md +++ /dev/null @@ -1,192 +0,0 @@ ---- -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); -``` - -注：表结构以博客[数据传输、存储、展现，EMQ X + 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 详细使用方法请参考 [EMQ 官方文档](https://www.emqx.io/docs/zh/v4.4/rule/rule-engine.html)。 - diff --git a/docs-cn/20-third-party/_category_.yml b/docs-cn/20-third-party/_category_.yml deleted file mode 100644 index cf9d95e5f9e0941f64159ffa17619839fdafbf05..0000000000000000000000000000000000000000 --- a/docs-cn/20-third-party/_category_.yml +++ /dev/null @@ -1,6 +0,0 @@ -label: 第三方工具 -link: - type: generated-index - slug: /third-party/ - description: TDengine 通过对标准 SQL 命令、常用数据库连接器标准（例如 JDBC）、ORM 以及其他流行时序数据库写入协议（例如 InfluxDB Line Protocol、OpenTSDB JSON、OpenTSDB Telnet 等）的支持可以使 TDengine 非常容易和第三方工具共同使用。 - diff --git a/docs-cn/20-third-party/emqx/add-action-handler.png b/docs-cn/20-third-party/emqx/add-action-handler.png deleted file mode 100644 index 97a1f933ecfadfcab399938806d73c5a5ecc6427..0000000000000000000000000000000000000000 Binary files a/docs-cn/20-third-party/emqx/add-action-handler.png and /dev/null 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 deleted file mode 100644 index c17a5c1ea2b9bbd49263056c8bf09c9aabab07d5..0000000000000000000000000000000000000000 Binary files a/docs-cn/20-third-party/emqx/check-result-in-taos.png and /dev/null 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 deleted file mode 100644 index 9e9a466946a1afa857e2bbc07b14956dd0f984b6..0000000000000000000000000000000000000000 Binary files a/docs-cn/20-third-party/emqx/check-rule-matched.png and /dev/null differ diff --git a/docs-cn/20-third-party/emqx/client-num.png b/docs-cn/20-third-party/emqx/client-num.png deleted file mode 100644 index fff48cbf3b271c367079ddde425b3f9b014062f7..0000000000000000000000000000000000000000 Binary files a/docs-cn/20-third-party/emqx/client-num.png and /dev/null differ diff --git a/docs-cn/20-third-party/emqx/create-resource.png b/docs-cn/20-third-party/emqx/create-resource.png deleted file mode 100644 index 58da4c391a3692b9f5fa348d952701eab8bcb746..0000000000000000000000000000000000000000 Binary files a/docs-cn/20-third-party/emqx/create-resource.png and /dev/null differ diff --git a/docs-cn/20-third-party/emqx/create-rule.png b/docs-cn/20-third-party/emqx/create-rule.png deleted file mode 100644 index 73b0b6ee3e6065a142df98abe8c0dbb32b34f89d..0000000000000000000000000000000000000000 Binary files a/docs-cn/20-third-party/emqx/create-rule.png and /dev/null differ diff --git a/docs-cn/20-third-party/emqx/edit-action.png b/docs-cn/20-third-party/emqx/edit-action.png deleted file mode 100644 index 2a43ee369a439cf11cee23c11f25d6a84b26d7dc..0000000000000000000000000000000000000000 Binary files a/docs-cn/20-third-party/emqx/edit-action.png and /dev/null differ diff --git a/docs-cn/20-third-party/emqx/edit-resource.png b/docs-cn/20-third-party/emqx/edit-resource.png deleted file mode 100644 index 0a0b3560044f4ed6e0a8f040b74085a7e8948b1f..0000000000000000000000000000000000000000 Binary files a/docs-cn/20-third-party/emqx/edit-resource.png and /dev/null differ diff --git a/docs-cn/20-third-party/emqx/login-dashboard.png b/docs-cn/20-third-party/emqx/login-dashboard.png deleted file mode 100644 index d6c5035c98d860faf639ef6611c6719adf80c47b..0000000000000000000000000000000000000000 Binary files a/docs-cn/20-third-party/emqx/login-dashboard.png and /dev/null differ diff --git a/docs-cn/20-third-party/emqx/rule-engine.png b/docs-cn/20-third-party/emqx/rule-engine.png deleted file mode 100644 index db110a837b024c82ee9d22f02dcd3a9d06abdd55..0000000000000000000000000000000000000000 Binary files a/docs-cn/20-third-party/emqx/rule-engine.png and /dev/null 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 deleted file mode 100644 index b81b9a9684aa2f98d00b7ec21e5de411fb450312..0000000000000000000000000000000000000000 Binary files a/docs-cn/20-third-party/emqx/rule-header-key-value.png and /dev/null differ diff --git a/docs-cn/20-third-party/emqx/run-mock.png b/docs-cn/20-third-party/emqx/run-mock.png deleted file mode 100644 index 0da25818575247732d5d3a783aa52cf7ce24662c..0000000000000000000000000000000000000000 Binary files a/docs-cn/20-third-party/emqx/run-mock.png and /dev/null differ diff --git a/docs-cn/21-tdinternal/01-arch.md b/docs-cn/21-tdinternal/01-arch.md deleted file mode 100644 index 84f6d239dd9fb347a4850966d391cb0b629a7944..0000000000000000000000000000000000000000 --- a/docs-cn/21-tdinternal/01-arch.md +++ /dev/null @@ -1,302 +0,0 @@ ---- -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 压力，加速查询处理的流程。预计算机制与 Postgre SQL 的索引 BRIN（block range index）有异曲同工之妙。 diff --git a/docs-cn/21-tdinternal/02-replica.md b/docs-cn/21-tdinternal/02-replica.md deleted file mode 100644 index 6a384b982d22956dd514d8df05dc827ca6f8b729..0000000000000000000000000000000000000000 --- a/docs-cn/21-tdinternal/02-replica.md +++ /dev/null @@ -1,256 +0,0 @@ ---- -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 deleted file mode 100644 index f0f50e03e277524fc37f44a2207b43e87898937e..0000000000000000000000000000000000000000 --- a/docs-cn/21-tdinternal/03-taosd.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -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/_category_.yml b/docs-cn/21-tdinternal/_category_.yml deleted file mode 100644 index 73c78f68a520fefecc145daaa24fe7e28c7c78e2..0000000000000000000000000000000000000000 --- a/docs-cn/21-tdinternal/_category_.yml +++ /dev/null @@ -1,4 +0,0 @@ -label: 技术内幕 -link: - slug: /tdinternal/ - type: generated-index \ No newline at end of file diff --git a/docs-cn/25-application/01-telegraf.md b/docs-cn/25-application/01-telegraf.md deleted file mode 100644 index f63a6701eed2b4c5b98f577d5b2867ae6dada387..0000000000000000000000000000000000000000 --- a/docs-cn/25-application/01-telegraf.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -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 deleted file mode 100644 index 5e6bc6577b2f4c8564e4533ced745d0b214ec748..0000000000000000000000000000000000000000 --- a/docs-cn/25-application/02-collectd.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -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 deleted file mode 100644 index 67882e623969070e3ced41b30e8e28969aae268c..0000000000000000000000000000000000000000 --- a/docs-cn/25-application/03-immigrate.md +++ /dev/null @@ -1,423 +0,0 @@ ---- -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 deleted file mode 100644 index 141c9269b50a2155391543ecea1dfe5c918e113c..0000000000000000000000000000000000000000 --- a/docs-cn/25-application/_category_.yml +++ /dev/null @@ -1,4 +0,0 @@ -label: 应用实践 -link: - slug: /application/ - type: generated-index diff --git a/docs-cn/27-train-faq/01-faq.md b/docs-cn/27-train-faq/01-faq.md deleted file mode 100644 index 80f66226b2171b1fcdf58ba18334f87868154ac6..0000000000000000000000000000000000000000 --- a/docs-cn/27-train-faq/01-faq.md +++ /dev/null @@ -1,204 +0,0 @@ ---- -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 excuted SQL is not a DML or a DDL？** - - 请更新至最新的 JDBC 驱动 - - ```xml - - com.taosdata.jdbc - taos-jdbcdriver - 2.0.27 - - ``` - -**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/03-docker.md b/docs-cn/27-train-faq/03-docker.md deleted file mode 100644 index 845a8751846c0995a43fb1c01e6ace3080176838..0000000000000000000000000000000000000000 --- a/docs-cn/27-train-faq/03-docker.md +++ /dev/null @@ -1,330 +0,0 @@ ---- -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 deleted file mode 100644 index 034d5894b9aea00e43caf4df21cb39487d8baf7b..0000000000000000000000000000000000000000 --- a/docs-cn/27-train-faq/_category_.yml +++ /dev/null @@ -1,4 +0,0 @@ -label: FAQ、教程及其它 -link: - slug: /train-faq/ - type: generated-index diff --git a/docs-en/01-intro/01-intro.md b/docs-en/01-intro/01-intro.md deleted file mode 100644 index 3fffcfb7da118a767b6736d1e32a3dad2f850c61..0000000000000000000000000000000000000000 --- a/docs-en/01-intro/01-intro.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: Introduction -toc_max_heading_level: 2 ---- - -## TDengine Major Features - -TDengine is a high-performance, scalable time-series database with SQL support. Its code, including its cluster feature is open source under GNU AGPL v3.0. Besides the database engine, it provides [caching](/develop/cache), [stream processing](/develop/continuous-query), [data subscription](/develop/subscribe) and other functionalities to reduce the complexity and cost of development and operation. The major features are listed below: - -1. Besides [using SQL to insert](/develop/insert-data/sql-writing)，supports [Schemaless writing](/reference/schemaless/)，and supports [InfluxDB LINE](/develop/insert-data/influxdb-line)，[OpenTSDB Telnet](/develop/insert-data/opentsdb-telnet), [OpenTSDB JSON ](/develop/insert-data/opentsdb-json) and other protocols. -2. Support seamless integration with third-party data collection agent like [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). Without a line of code, those agents can write data points into TDengine just by configuration. -3. Support [all kinds of queries](/query-data), including aggregation, nested query, downsampling, interpolation, etc. -4. Support [user defined functions](/develop/udf) -5. Support [caching](/develop/cache). TDengine always save the last data point in cache, so Redis is not needed in some scenarios. -6. Support [continuous query](/develop/continuous-query). -7. Support [data subscription](/develop/subscribe)，and the filter condition can be specified. -8. Support [cluster](/cluster/), so it can gain more processing power by adding more nodes. The high availability is supported by replication. -9. Provide interactive [command line intrerface](/reference/taos-shell) for management, maintainence and ad-hoc query. -10. Provide many ways to [import](/operation/import), [export](/operation/export) data. -11. Provide [monitoring](/operation/monitor) on TDengine running instances. -12. Provide [connectors](/reference/connector/) for [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) and other programming languages. -13. Provide [REST API](/reference/rest-api/). -14. Support the seamless integration with [Grafana](/third-party/grafana) for visualization. -15. Support seamless integration with Google Data Studio. - -For more detailed features, please read through the whole document. - -## TDenginge Highlights - -TDengine makes full use of [the characteristics of time series data](https://tdengine.com/2019/07/09/86.html), such as structured, no transaction, rarely delete or update, etc., and builds its own innovative storage engine and computing engine to differentiate itself from other TSDBs with the following advantages. - -- **High Performance**: TDengine outperforms other time series databases in data ingestion and querying while significantly reducing storage cost and compute costs, with an innovatively designed and purpose-built storage engine. - -- **Scalable**: TDengine provides out-of-box scalability and high-availability through its native distributed design. Nodes can be added through simple configuration to achieve greater data processing power. In addition, this feature is open source. - -- **SQL Support**: TDengine uses SQL as the query language, thereby reducing learning and migration costs, while adding SQL extensions to handle time-series data better, and supporting convenient and flexible schemaless data ingestion. - -- **All in One**: TDengine has built-in caching, stream processing and data subscription functions. It is no longer necessary to integrate Kafka/Redis/HBase/Spark or other software in some scenarios. It makes the system architecture much simpler, cost-effective and easier to maintain. - -- **Seamless Integration**: Without a single line of code, TDengine provide seamless, configurable integration with third-party tools such as Telegraf, Grafana, EMQX, Prometheus, StatsD, collectd, etc. More third-party tools are being integrated. - -- **Zero Management**: Installation and cluster setup can be done in seconds. Data partitioning and sharding are executed automatically. TDengine’s running status can be monitored via Grafana or other DevOps tools. - -- **Zero Learning Cost**: With SQL as the query language, support for ubiquitous tools like Python, Java, C/C++, Go, Rust, Node.js connectors, there is zero learning cost. - -- **Interactive Console**: TDengine provides convenient console access to the database to run ad hoc queries, maintain the database, or manage the cluster without any programming. - -With TDengine, the total cost of ownership of time-seriess data platform can be greatly reduced. Because 1: with its superior performance, the computing and storage resources are reduced significantly; 2：with SQL support, it can be seamlessly integrated with many third party tools, and learning cost/migration cost is reduced significantly; 3: with its simple architecture and zero management, the operation and maintainence cost is reduced. - -## TDengine Technical Ecosystem -In the time-series data processing platform, TDengine stands in a role like this diagram below: - -![TDengine Technical Ecosystem ](eco_system.png) - -
Figure 1. TDengine Technical Ecosystem
- -On the left side, there are data collection agents like OPC-UA, MQTT, Telegraf and Kafka. On the right side, visualization/BI tools, HMI, Python/R, IoT App can be connected. TDengine itself provides interactive command line interface and web interface for management and maintainence. - -## Suited Scenarios for TDengine - -As a high-performance, scalable and SQL supported time-series database, TDengine's typical application scenarios include but are not limited to IoT, Industrial Internet, Connected Vehicles, IT operation and maintenance, energy, financial market and other fields. But you shall note that TDengine is a purpose-built database and does tons of optimization based on the characteristics of time series data, it cannot be used to process data from web crawlers, social media, e-commerce, ERP, CRM, etc. This section makes a more detailed analysis of the applicable scenarios. - -### Characteristics and Requirements of Data Sources - -From the perspective of data sources, designers can analyze the applicability of TDengine in target application systems as follows. - -| **Data Source Characteristics and Requirements** | **Not Applicable** | **Might Be Applicable** | **Very Applicable** | **Description** | -| -------------------------------------------------------- | ------------------ | ----------------------- | ------------------- | :----------------------------------------------------------- | -| A massive amount of total data | | | √ | TDengine provides excellent scale-out functions in terms of capacity, and has a storage structure with matching high compression ratio to achieve the best storage efficiency in the industry.| -| Data input velocity is extremely high | | | √ | TDengine's performance is much higher than that of other similar products. It can continuously process larger amounts of input data in the same hardware environment, and provides a performance evaluation tool that can easily run in the user environment. | -| A huge number of data sources | | | √ | TDengine is optimized specifically for a huge number of data sources. It is especially suitable for efficiently ingesting, writing and querying data from billions of data sources. | - -### System Architecture Requirements - -| **System Architecture Requirements** | **Not Applicable** | **Might Be Applicable** | **Very Applicable** | **Description** | -| ------------------------------------------------- | ------------------ | ----------------------- | ------------------- | ------------------------------------------------------------ | -| A simple and reliable system architecture | | | √ | TDengine's system architecture is very simple and reliable, with its own message queue, cache, stream computing, monitoring and other functions. There is no need to integrate any additional third-party products. | -| Fault-tolerance and high-reliability | | | √ | TDengine has cluster functions to automatically provide high-reliability and high-availability functions such as fault tolerance and disaster recovery. | -| Standardization support | | | √ | TDengine supports standard SQL and also provides extensions specifically to analyze time-series data. | - -### System Function Requirements - -| **System Function Requirements** | **Not Applicable** | **Might Be Applicable** | **Very Applicable** | **Description** | -| ------------------------------------------------- | ------------------ | ----------------------- | ------------------- | ------------------------------------------------------------ | -| Complete data processing algorithms built-in | | √ | | While TDengine implements various general data processing algorithms, industry specific algorithms and special types of processing will need to be implemented at the application level.| -| A large number of crosstab queries | | √ | | This type of processing is better handled by general purpose relational database systems but TDengine can work in concert with relational database systems to provide more complete solutions. | - -### System Performance Requirements - -| **System Performance Requirements** | **Not Applicable** | **Might Be Applicable** | **Very Applicable** | **Description** | -| ------------------------------------------------- | ------------------ | ----------------------- | ------------------- | ------------------------------------------------------------ | -| Very large total processing capacity | | | √ | TDengine’s cluster functions can easily improve processing capacity via multi-server coordination. | -| Extremely high-speed data processing | | | √ | TDengine’s storage and data processing are optimized for IoT, and can process data many times faster than similar products.| -| Extremely fast processing of fine-grained data | | | √ | TDengine has achieved the same or better performance than other relational and NoSQL data processing systems. | - -### System Maintenance Requirements - -| **System Maintenance Requirements** | **Not Applicable** | **Might Be Applicable** | **Very Applicable** | **Description** | -| ------------------------------------------------- | ------------------ | ----------------------- | ------------------- | ------------------------------------------------------------ | -| Native high-reliability | | | √ | TDengine has a very robust, reliable and easily configurable system architecture to simplify routine operation. Human errors and accidents are eliminated to the greatest extent, with a streamlined experience for operators. | -| Minimize learning and maintenance costs | | | √ | In addition to being easily configurable, standard SQL support and the Taos shell for ad hoc queries makes maintenance simpler, allows reuse and reduces learning costs.| -| Abundant talent supply | √ | | | Given the above, and given the extensive training and professional services provided by TDengine, it is easy to migrate from existing solutions or create a new and lasting solution based on TDengine.| - -## Benchmark comparision between TDengine and other databases - -- [Writing Performance Comparison of TDengine and InfluxDB ](https://tdengine.com/2022/02/23/4975.html) -- [Query Performance Comparison of TDengine and InfluxDB](https://tdengine.com/2022/02/24/5120.html) -- [TDengine vs InfluxDB、OpenTSDB、Cassandra、MySQL、ClickHouse](https://www.tdengine.com/downloads/TDengine_Testing_Report_en.pdf) -- [TDengine vs OpenTSDB](https://tdengine.com/2019/09/12/710.html) -- [TDengine vs Cassandra](https://tdengine.com/2019/09/12/708.html) -- [TDengine vs InfluxDB](https://tdengine.com/2019/09/12/706.html) diff --git a/docs-en/01-intro/eco_system.png b/docs-en/01-intro/eco_system.png deleted file mode 100644 index bf8bf8f1e0a2311fc12202d712a8a2f9b8ce419b..0000000000000000000000000000000000000000 Binary files a/docs-en/01-intro/eco_system.png and /dev/null differ diff --git a/docs-en/02-concept/02-concept.md b/docs-en/02-concept/02-concept.md deleted file mode 100644 index 16242236e5fc1f3dddae9d065960539f8d4f4ab8..0000000000000000000000000000000000000000 --- a/docs-en/02-concept/02-concept.md +++ /dev/null @@ -1,158 +0,0 @@ ---- -title: Concepts ---- - -In order to explain the basic concepts and show sample code easily, the entire TDengine document takes smart meters as a typical time series data scenario. Assuming that each smart meter collects three metrics of current, voltage, and phase, there are multiple smart meters, and each meter has static attributes like location and group ID, the collected data shall be similar to the following table: - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
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
-Table 1: Smart meter example data -
- -Each row contains the device ID, timestamp, collected metrics (current, voltage, phase as above), and static tags (Location and groupId in Table 1) associated with the devices. Each smart meter generates a row (data point) in a pre-defined timer or triggered by an external event. It is a sequence of data points like a stream. - -## Metric - -Metric refers to the physical quantity collected by sensors, equipment or other types of data collection devices, such as current, voltage, temperature, pressure, GPS position, etc., which changes with time, and the data type can be integer, float, Boolean, or strings. As time goes by, the amount of collected metric data stored increases. - -## Label/Tag - -Label/Tag refers to the static properties of sensors, devices or other types of data collection devices, which do not change with time, such as device model, color, fixed location of the device, etc. The data type can be any type. Although static, TDengine allows users to add, delete or update tag values. Unlike the collected metric data, the amount of tag data stored does not change over time. - -## Data Collection Point - -Data Collection Point(DCP) refers to hardware or software that collects metrics based on preset time periods or triggered by events. A data collection point can collect one or multiple metrics, but these metrics are collected at the same time and have the same time stamp. For some complex equipments, there are often multiple data collection points, and the sampling rate of each collection point may be different, and fully independent. For example, for a car, there is a data collection point to collect GPS position metrics, a data collection point to collect engine status metrics, and a data collection point to collect the environment metrics inside the car, so a car has three data collection points. - -## Table - -Since time-series data is most likely to be structured data, TDengine adopts the traditional relational database model to process them with a short learning curve. You need to create a database, create tables, then insert data points and execute queries to explore the data. - -To make full use of time-series data characteristics, TDengine adopts a strategy "**One Table for One Data Collection Point**". TDengine requires the user to create a table for each data collection point (DCP) to store collected time-series data. For example, if there are over 10 million smart meters, it means 10 million tables shall be created. For the table above, 4 tables shall be created for devices D1001, D1002, D1003, and D1004 to store the data collected. This design has several benefits: - -1. Since the metric data from different DCP is fully independent, the data source of each DCP is unique, and a table has only one writer. In this way, data points can be written in a lock-free manner, and the writing speed can be greatly improved. -2. For a DCP, the metric data generated by DCP is ordered by timestamp, so the write operation can be implemented by simple appending, which further greatly improves the data writing speed. -3. The metric data from a DCP is continuously stored in block by block. If you read data for a period of time, it can greatly reduce random read operations and improve read and query performance by orders of magnitude. -4. Inside a data block for a DCP, columnar storage is used, and different compression algorithms are used for different data types. Because the change of the metrics from a DCP is not big in a time range, the compression rate is higher. - -If the metric data of multiple DPCs are traditionally written into a single table, due to the uncontrollable network delay, the timing of the data from different DCPs arriving at the server cannot be guaranteed, the writing operation must be protected by locks, and the metric data from one DCP cannot be guaranteed to be continuously stored together. **One table for one data collection point can ensure the best performance of insert and query of a single data collection point to the greatest extent.** - -TDengine suggests using DCP ID as the table name (like D1001 in the above table). Each DCP may collect one or multiple metrics (like the current, voltage, phase as above). Each metric has a corresponding column in the table. The data type for a column can be int, float, string and others. In addition, the first column in the table must be a timestamp. TDengine uses the time stamp as the index, and won’t build the index on any metrics stored. Column wise storage is used. - -## Super Table (STable) - -The design of one table for one data collection point will require a huge number of tables, which is difficult to manage. Furthermore, applications often need to take aggregation operations among DCPs, thus aggregation operations will become complicated. To support aggregation over multiple tables efficiently, the STable(Super Table) concept is introduced by TDengine. - -STable is an set for a type of data collection point. A STable contains a set of data collection points (tables) that have the same schema or data structure, but with different static attributes(tags). To describe a STable, in addition to defining the table structure of the metrics, it is also necessary to define the schema of its tags. The data type of tags can be int, float, string, and there can be multiple tags, which can be added, deleted, or modified afterward. If the whole system has N different types of data collection points, N STables need to be established. - -In the design of TDengine, **a table is used to represent a specific data collection point, and STable is used to represent a set of data collection points of the same type**. When creating a table for a specific data collection point, the user uses a STable as a template and specifies the tag value of the specific DCP (table). Compared with the traditional relational database, the table (a DCP) has static tags, and these tags can be added, deleted, and updated afterward. The relationship between the STable and the tables created based on the STable is as follows: - -1. A STable contains multiple tables with the same metric schema but with different tag values. -2. The schema of metrics or labels cannot be adjusted through tables, and it can only be changed via STable. Changes to the schema of a STable takes effect immediately for all belonged tables. -3. STable defines only one template and does not store any data or label information by itself. Therefore, data cannot be written to a STable, only to tables. - -Query can be executed on both table and STable. For a query on a STable, TDengine will treat the data in all belonged tables as a whole data set for processing. TDengine will first find out the tables that meet the tag filter conditions, then scan the time-series data of these tables to perform aggregation operation, which can greatly reduce the data sets to be scanned, thus greatly improving the performance of data aggregation across multiple DCPs. - -## Database - -A database is a collection of tables. TDengine allows a running instance to have multiple databases, and each database can be configured with different storage policies. Different types of DCPs often have different data characteristics, including the frequency of data collection, data retention time, the number of replications, the size of data blocks, whether data is allowed to be updated, and so on. In order for TDengine to work with maximum efficiency in various scenarios, TDengine recommends that STables with different data characteristics be created in different databases. - -In a database, there can be one or more STables, but a STable belongs to only one database. All tables owned by a STable are stored in only one database. - -## FQDN & End Point - -FQDN (Fully Qualified Domain Name) is the full domain name of a specific computer or host on the Internet. FQDN consists of two parts: hostname and domain name. For example, the FQDN of a mail server might be mail.tdengine.com. The hostname is mail, and the host is located in the domain name tdengine.com. DNS (Domain Name System) is responsible for translating FQDN into IP. For systems without DNS, it can be solved by configuring the hosts file. - -Each node of a TDengine cluster is uniquely identified by an End Point, which consists of an FQDN and a Port, such as h1.tdengine.com:6030. In this way, when the IP changes, we can still use the FQDN to dynamically find the node without changing any configuration of the cluster. In addition, FQDN is used to facilitate unified access to the same cluster from the Intranet and the Internet. - -TDengine does not recommend using IP address to access the cluster, which is not good for cluster management. diff --git a/docs-en/03-get-started/03-get-started.md b/docs-en/03-get-started/03-get-started.md deleted file mode 100644 index d0b6165c909e506fd4ac7452e824b00824c8bfda..0000000000000000000000000000000000000000 --- a/docs-en/03-get-started/03-get-started.md +++ /dev/null @@ -1,169 +0,0 @@ ---- -title: Get Started -description: "Install TDengine from Docker image, apt-get or package, and run TAOS CLI and taosBenchmark to experience the features" ---- - -import Tabs from "@theme/Tabs"; -import TabItem from "@theme/TabItem"; -import PkgInstall from "./\_pkg_install.mdx"; -import AptGetInstall from "./\_apt_get_install.mdx"; - -## Quick Install - -The full package of TDengine includes server(taosd), taosAdapter for connecting with third-party systems and providing RESTful interface, application driver(taosc), command line program(CLI, taos) and some tools. For current version, the server taosd and taosAdapter can only be installed and run on Linux systems, and will support Windows, macOS and other systems in the future. The application driver taosc and TDengine CLI can be installed and run on Windows or Linux. In addition to the RESTful interface, TDengine also provides connectors for a number of programming languages. In versions before 2.4, there is no taosAdapter, and the RESTfule interface is provided by the built-in http service of taosd. - -TDengine supports X64/ARM64/MIPS64/Alpha64 hardware platforms, and will support ARM32, RISC-V and other CPU architectures in the future. - - - -If docker is already installed on your computer, execute the following command: - -```shell -docker run -d -p 6030-6049:6030-6049 -p 6030-6049:6030-6049/udp tdengine/tdengine -``` - -Make sure the container is running - -```shell -docker ps -``` - -Enter into container and execute bash - -```shell -docker exec -it bash -``` - -Then you can execute the Linux commands and access TDengine. - -For detailed steps, please visit [Experience TDengine via Docker](/train-faq/docker)。 - -:::info -Starting from 2.4.0.10，besides taosd，TDengine docker image includes: taos，taosAdapter，taosdump，taosBenchmark，TDinsight, scripts and sample code. Once the TDengine container is started，it will start both taosAdapter and taosd automatically to support RESTful interface. - -::: - - - - - - - - - - -If you like to check the source code, build the package by youself or contribute to the project, please check [TDengine GitHub Repository](https://github.com/taosdata/TDengine) - - - - -## Quick Launch - -After installation, you can launch the TDengine service by the 'systemctl' command to start 'taosd'. - -```bash -systemctl start taosd -``` - -Check if taosd is running： - -```bash -systemctl status taosd -``` - -If everything is fine，you can run TDengine command line interface `taos` to access TDengine and play around it. - -:::info - -- systemctl requires _root_ privileges，if you are not _root_ ，please add sudo before the command. -- To get feedback and keep polishing the prodcut, TDengine is colleting some basic usage information, but you can turn it off by setting telemetryReporting to 0 in configuration file taos.cfg. -- TDengine uses FQDN (usually hostname）as the ID for a node. To make system work, you need to configure the FQDN for the server running taosd, and configure the DNS service or hosts file on the the machine where the application or TDengine CLI runs to ensure that the FQDN can be resolved. -- `systemctl stop taosd` won't stop the server right away, it will wait until all the data in memory are flushed to disk. It may takes time depending on the cache size. - -TDengine supports the installation on system which runs [`systemd`](https://en.wikipedia.org/wiki/Systemd) for process management，use `which systemctl` to check if the system has `systemd` installed: - -```bash -which systemctl -``` - -If the system does not have `systemd`，you can start TDengine manually by executing `/usr/local/taos/bin/taosd` - -:::note - -## Command Line Interface - -To manage the TDengine running instance，or execute ad-hoc queries, TDengine provides a Command Line Interface(hereinafter referred to as TDengine CLI) taos. To enter into the interactive CLI，execute `taos` on a Linux terminal where TDengine is installed. - -```bash -taos -``` - -If it connects to the TDengine server successfully, it will print out the version and welcome message. If it fails, it will print out the error message, please check [FAQ](/train-faq/faq) for trouble shooting connection issue. TDengine CLI's prompt is： - -```cmd -taos> -``` - -Inside TDengine CLI，you can execute SQL commands to create/drop database/table, and run queries. The SQL command must be eneded with a semicolon. For example: - -```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) -``` -Besides executing SQL commands, system administrator can check running status, add/drop user accounts and manage the running instances. TAOS CLI with application driver can be installed and run on either Linux or windows machine. For more details on CLI, please [check here](../reference/taos-shell/). - -## Experience the blazing fast speed - -After TDengine server is running，execute `taosBenchmark`(named as taosdemo before) from a Linux terminal： - -```bash -taosBenchmark -``` -This command will create a super table "meters" under database "test". Unde "meters", 10000 tables are created with name from "d0" to "d9999". Each table has 10000 rows and each row has four columns (ts, current, voltage, phase). Time stamp is starting from "2017-07-14 10:40:00 000" to "2017-07-14 10:40:09 999". Each table has tags "location" and "groupId". groupId is set 1 to 10 randomly, and location is set to "beijing" or "shanghai". - -This command will insert 100 million rows into database quickly. Depends on the hardware configuration, it only takes a dozen seconds for a regular PC server. - -taosBenchmark provides you command line options and confuguration file to customize the scenarios, like number of tables, number of rows per table, number of columns and more. Please execute `taosBenchmark --help` to list them. For details on running taosBenchmark, please check [reference for taosBenchmark](/reference/taosbenchmark) - -## Experience query speed - -After using taosBenchmark to insert a number of rows data, you can execute queries from TDengine CLI to experience the lightning query speed. - -query the total number of rows under super table "meters"： - -```sql -taos> select count(*) from test.meters; -``` - -query the average, maximum, minimum of 100 million rows: - -```sql -taos> select avg(current), max(voltage), min(phase) from test.meters; -``` - -query the total number of rows with location="beijing": - -```sql -taos> select count(*) from test.meters where location="beijing"; -``` - -query the average, maximum, minimum of all rows with groupId=10: - -```sql -taos> select avg(current), max(voltage), min(phase) from test.meters where groupId=10; -``` - -query the average, maximum, minimum for table d10 in 10 seconds time interal： - -```sql -taos> select avg(current), max(voltage), min(phase) from test.d10 interval(10s); -``` diff --git a/docs-en/03-get-started/_pkg_install.mdx b/docs-en/03-get-started/_pkg_install.mdx deleted file mode 100644 index 83c987af8bcf24a9593105b680d32a0421344d5f..0000000000000000000000000000000000000000 --- a/docs-en/03-get-started/_pkg_install.mdx +++ /dev/null @@ -1,17 +0,0 @@ -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-en/04-develop/01-connect/_connect_c.mdx b/docs-en/04-develop/01-connect/_connect_c.mdx deleted file mode 100644 index 174bf45c4e2f26bab8f57c098f9f8f00d2f5064d..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/01-connect/_connect_c.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```c title="Native Connection" -{{#include docs-examples/c/connect_example.c}} -``` diff --git a/docs-en/04-develop/01-connect/_connect_cs.mdx b/docs-en/04-develop/01-connect/_connect_cs.mdx deleted file mode 100644 index 52ea2d437123a26bd87e6f3fdc05a17141f9f835..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/01-connect/_connect_cs.mdx +++ /dev/null @@ -1,8 +0,0 @@ -```csharp title="Native Connection" -{{#include docs-examples/csharp/ConnectExample.cs}} -``` - -:::info -C# connector supports only native connection for now. - -::: diff --git a/docs-en/04-develop/01-connect/_connect_go.mdx b/docs-en/04-develop/01-connect/_connect_go.mdx deleted file mode 100644 index 1dd5d67e3533bba21960269e49e3d843b026efc8..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/01-connect/_connect_go.mdx +++ /dev/null @@ -1,17 +0,0 @@ -#### Unified Database Access Interface - -```go title="Native Connection" -{{#include docs-examples/go/connect/cgoexample/main.go}} -``` - -```go title="REST Connection" -{{#include docs-examples/go/connect/restexample/main.go}} -``` - -#### Advanced Features - -The af package of driver-go can also be used to establish connection, with this way some advanced features of TDengine, like parameter binding and subscription, can be used. - -```go title="Establish native connection using af package" -{{#include docs-examples/go/connect/afconn/main.go}} -``` diff --git a/docs-en/04-develop/01-connect/_connect_java.mdx b/docs-en/04-develop/01-connect/_connect_java.mdx deleted file mode 100644 index 1c3e9326bf2ae597ffba683250dd43986e670469..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/01-connect/_connect_java.mdx +++ /dev/null @@ -1,15 +0,0 @@ -```java title="Native Connection" -{{#include docs-examples/java/src/main/java/com/taos/example/JNIConnectExample.java}} -``` - -```java title="REST Connection" -{{#include docs-examples/java/src/main/java/com/taos/example/RESTConnectExample.java:main}} -``` - -When using REST connection, the feature of bulk pulling can be enabled if the size of resulting data set is huge. - -```java title="Enable Bulk Pulling" {4} -{{#include docs-examples/java/src/main/java/com/taos/example/WSConnectExample.java:main}} -``` - -More configuration about connection，please refer to [Java Connector](/reference/connector/java) diff --git a/docs-en/04-develop/01-connect/_connect_node.mdx b/docs-en/04-develop/01-connect/_connect_node.mdx deleted file mode 100644 index 489b0386e991ee1e8ddd173205637b75ae5a0c95..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/01-connect/_connect_node.mdx +++ /dev/null @@ -1,7 +0,0 @@ -```js title="Native Connection" -{{#include docs-examples/node/nativeexample/connect.js}} -``` - -```js title="REST Connection" -{{#include docs-examples/node/restexample/connect.js}} -``` diff --git a/docs-en/04-develop/01-connect/_connect_python.mdx b/docs-en/04-develop/01-connect/_connect_python.mdx deleted file mode 100644 index f6c8bcfee1d92fae2d1ad320002b805dd9951228..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/01-connect/_connect_python.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```python title="Native Connection" -{{#include docs-examples/python/connect_exmaple.py}} -``` diff --git a/docs-en/04-develop/01-connect/_connect_r.mdx b/docs-en/04-develop/01-connect/_connect_r.mdx deleted file mode 100644 index 09c3d71ac35b1134d3089247daea9a13db4129e2..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/01-connect/_connect_r.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```r title="Native Connection" -{{#include docs-examples/R/connect_native.r:demo}} -``` diff --git a/docs-en/04-develop/01-connect/_connect_rust.mdx b/docs-en/04-develop/01-connect/_connect_rust.mdx deleted file mode 100644 index aa19f58de6c9bab69df0663e5369402ab1a8f899..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/01-connect/_connect_rust.mdx +++ /dev/null @@ -1,8 +0,0 @@ -```rust title="Native Connection/REST Connection" -{{#include docs-examples/rust/nativeexample/examples/connect.rs}} -``` - -:::note -For Rust connector, the connection depends on the feature being used. If "rest" feature is enabled, then only the implementation for "rest" is compiled and packaged. - -::: diff --git a/docs-en/04-develop/01-connect/index.md b/docs-en/04-develop/01-connect/index.md deleted file mode 100644 index 6926170a7cad7e422c2268bfe81a8387e1e6d0c6..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/01-connect/index.md +++ /dev/null @@ -1,241 +0,0 @@ ---- -sidebar_label: Connect -title: Connect to TDengine -description: "This document explains how to establish connection to TDengine, and briefly introduce how to install and use TDengine connectors." ---- - -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 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"; - -Any application programs running on any kind of platforms can access TDengine through the REST API provided by TDengine. For the details please refer to [REST API](/reference/rest-api/). Besides, application programs can use the connectors of multiple languages to access TDengine, including C/C++, Java, Python, Go, Node.js, C#, and Rust. This chapter describes how to establish connection to TDengine and briefly introduce how to install and use connectors. For details about the connectors please refer to [Connectors](/reference/connector/) - -## Establish Connection - -There are two ways to establish connections to TDengine: - -1. Connection to taosd can be established through the REST API provided by taosAdapter component, this way is called "REST connection" hereinafter. -2. Connection to taosd can be established through the client side driver taosc, this way is called "Native connection" hereinafter. - -Either way, same or similar APIs are provided by connectors to access database or execute SQL statements, no obvious difference can be observed. - -Key differences： - -1. With REST connection, it's not necessary to install the client side driver taosc, it's more friendly for cross-platform with the cost of 30% performance downgrade. -2. With native connection, full compatibility of TDengine can be utilized, like [Parameter Binding](/reference/connector/cpp#Parameter Binding-api), [Subscription](reference/connector/cpp#Subscription), etc. - -## Install Client Driver taosc - -If choosing to use native connection and the client program is not on the same host as TDengine server, TDengine client driver needs to be installed on the host where the client program is. If choosing to use REST connection or the client is on the same host as server side, this step can be skipped. It's better to use same version of client as the server. - -### Install - - - - - - - - - - -### Verify - -After the above installation and configuration are done and making sure TDengine service is already started and in service, the Shell command `taos` can be launched to access TDengine.以 - - - - - - - - - - -## Install Connectors - - - - -If `maven` is used to manage the projects, what needs to be done is only adding below dependency in `pom.xml`. - -```xml - - com.taosdata.jdbc - taos-jdbcdriver - 2.0.38 - -``` - - - - -Install from PyPI using `pip`: - -``` -pip install taospy -``` - -Install from Git URL: - -``` -pip install git+https://github.com/taosdata/taos-connector-python.git -``` - - - - -Just need to add `driver-go` dependency in `go.mod` . - -```go-mod title=go.mod -module goexample - -go 1.17 - -require github.com/taosdata/driver-go/v2 develop -``` - -:::note -`driver-go` uses `cgo` to wrap the APIs provided by taosc, while `cgo` needs `gcc` to compile source code in C language, so please make sure you have proper `gcc` on your system. - -::: - - - - -Just need to add `libtaos` dependency in `Cargo.toml`. - -```toml title=Cargo.toml -[dependencies] -libtaos = { version = "0.4.2"} -``` - -:::info -Rust connector uses different features to distinguish the way to establish connection. To establish REST connection, please enable `rest` feature. - -```toml -libtaos = { version = "*", features = ["rest"] } -``` - -::: - - - - -Node.js connector provides different ways of establishing connections by providing different packages. - -1. Install Node.js Native Connector - -``` -npm i td2.0-connector -``` - -:::note -It's recommend to use Node whose version is between `node-v12.8.0` and `node-v13.0.0`. -::: - -2. Install Node.js REST Connector - -``` -npm i td2.0-rest-connector -``` - - - - -Just need to add the reference to [TDengine.Connector](https://www.nuget.org/packages/TDengine.Connector/) in the project configuration file. - -```xml title=csharp.csproj {12} - - - - Exe - net6.0 - enable - enable - TDengineExample.AsyncQueryExample - - - - - - - -``` - -Or add by `dotnet` command. - -``` -dotnet add package TDengine.Connector -``` - -:::note -The sample code below are based on dotnet6.0, they may need to be adjusted if your dotnet version is not exactly same. - -::: - - - - -1. Download [taos-jdbcdriver-version-dist.jar](https://repo1.maven.org/maven2/com/taosdata/jdbc/taos-jdbcdriver/2.0.38/). -2. Install the dependency package `RJDBC`： - -```R -install.packages("RJDBC") -``` - - - - -If the client driver taosc is already installed, then the C connector is already available. -
- - - - -## Establish Connection - -Prior to establishing connection, please make sure TDengine is already running and accessible. The following sample code assumes TDengine is running on the same host as the client program, with FQDN configured to "localhost" and serverPort configured to "6030". - - - - - - - - - - - - - - - - - - - - - - - - - - - - -:::tip -If the connection fails, in most cases it's caused by improper configuration for FQDN or firewall. Please refer to the section "Unable to establish connection" in [FAQ](https://docs.taosdata.com/train-faq/faq). - -::: diff --git a/docs-en/04-develop/02-model/index.mdx b/docs-en/04-develop/02-model/index.mdx deleted file mode 100644 index 0c2aab3cf9f86bc20f91d583b97bc5233826eeac..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/02-model/index.mdx +++ /dev/null @@ -1,86 +0,0 @@ ---- -sidebar_label: Data Model -slug: /model -title: Data Model ---- - -The data model employed by TDengine is similar to relational database, you need to create databases and tables. For a specific application, the design of databases, STables (abbreviated for super table), and tables need to be considered. This chapter will explain the big picture without syntax details. - -## Create Database - -The characteristics of data from different data collection points may be different, such as collection frequency, days to keep, number of replicas, data block size, whether it's allowed to update data, etc. For TDengine to operate with the best performance, it's strongly suggested to put the data with different characteristics into different databases because different storage policy can be set for each database. When creating a database, there are a lot of parameters that can be configured, such as the days to keep data, the number of replicas, the number of memory blocks, time precision, the minimum and maximum number of rows in each data block, compress or not, the time range of the data in single data file, etc. Below is an example of the SQL statement for creating a database. - -```sql -CREATE DATABASE power KEEP 365 DAYS 10 BLOCKS 6 UPDATE 1; -``` - -In the above SQL statement, a database named "power" will be created, the data in it will be kept for 365 days, which means the data older than 365 days will be deleted automatically, a new data file will be created every 10 days, the number of memory blocks is 6, data is allowed to be updated. For more details please refer to [Database](/taos-sql/database). - -After creating a database, the current database in use can be switched using SQL command `USE`, for example below SQL statement switches the current database to `power`. Without current database specified, table name must be preceded with the corresponding database name. - -```sql -USE power; -``` - -:::note - -- Any table or STable must belong to a database. To create a table or STable, the database it belongs to must be ready. -- JOIN operation can't be performed tables from two different databases. -- Timestamp needs to be specified when inserting rows or querying historical rows. - -::: - -## Create STable - -In a time-series application, there may be multiple kinds of data collection points. For example, in the electrical power system there are meters, transformers, bus bars, switches, etc. For easy and efficient aggregation of multiple tables, one STable needs to be created for each kind of data collection point. For example, for the meters in [table 1](/tdinternal/arch#model_table1), below SQL statement can be used to create the super table. - -```sql -CREATE STable meters (ts timestamp, current float, voltage int, phase float) TAGS (location binary(64), groupId int); -``` - -:::note -If you are using versions prior to 2.0.15, the `STable` keyword needs to be replaced with `TABLE`. - -::: - -Similar to creating a normal table, when creating a STable, name and schema need to be provided too. In the STable schema, the first column must be timestamp (like ts in the example), and other columns (like current, voltage and phase in the example) are the data collected. The type of a column can be integer, floating point number, string ,etc. Besides, the schema for tags need to be provided, like location and groupId in the example. The type of a tag can be integer, floating point number, string, etc. The static properties of a data collection point can be defined as tags, like the location, device type, device group ID, manager ID, etc. Tags in the schema can be added, removed or updated. Please refer to [STable](/taos-sql/stable) for more details. - -Each kind of data collection points needs a corresponding STable to be created, so there may be many STables in an application. For electrical power system, we need to create a STable respectively for meters, transformers, busbars, switches. There may be multiple kinds of data collection points on a single device, for example there may be one data collection point for electrical data like current and voltage and another point for environmental data like temperature, humidity and wind direction, multiple STables are required for such kind of device. - -At most 4096 (or 1024 prior to version 2.1.7.0) columns are allowed in a STable. If there are more than 4096 of metrics to bo collected for a data collection point, multiple STables are required for such kind of data collection point. There can be multiple databases in system, while one or more STables can exist in a database. - - -## Create Table - -A specific table needs to be created for each data collection point. Similar to RDBMS, table name and schema are required to create a table. Beside, one or more tags can be created for each table. To create a table, a STable needs to be used as template and the values need to be specified for the tags. For example, for the meters in [Table 1](/tdinternal/arch#model_table1), the table can be created using below SQL statement. - -```sql -CREATE TABLE d1001 USING meters TAGS ("Beijing.Chaoyang", 2); -``` - -In the above SQL statement, "d1001" is the table name, "meters" is the STable name, followed by the value of tag "Location" and the value of tag "groupId", which are "Beijing.Chaoyang" and "2" respectively in the example. The tag values can be updated after the table is created. Please refer to [Tables](/taos-sql/table) for details. - - -:::warning -It's not recommended to create a table in a database while using a STable from another database as template. - -:::tip -It's suggested to use the global unique ID of a data collection point as the table name, for example the device serial number. If there isn't such a unique ID, multiple IDs that are not global unique can be combined to form a global unique ID. It's not recommended to use a global unique ID as tag value. - -## Create Table Automatically - -In some circumstances, it's not sure whether the table already exists when inserting rows. The table can be created automatically using the SQL statement below, and nothing will happen if the table already exist. - -```sql -INSERT INTO d1001 USING meters TAGS ("Beijng.Chaoyang", 2) VALUES (now, 10.2, 219, 0.32); -``` - -In the above SQL statement, a row with value `(now, 10.2, 219, 0.32)` will be inserted into table "d1001". If table "d1001" doesn't exist, it will be created automatically using STable "meters" as template with tag value `"Beijing.Chaoyang", 2`. - -For more details please refer to [Create Table Automatically](/taos-sql/insert#automatically-create-table-when-inserting). - -## Single Column vs Multiple Column - -Multiple columns data model is supported in TDengine. As long as multiple metrics are collected by same data collection point at same time, i.e. the timestamp are identical, these metrics can be put in single stable as columns. However, there is another kind of design, i.e. single column data model, a table is created for each metric, which means a STable is required for each kind of metric. For example, 3 STables are required for current, voltage and phase. - -It's recommended to use multiple column data model as much as possible because it's better in the performance of inserting or querying rows. In some cases, however, the metrics to be collected vary frequently and correspondingly the STable schema needs to be changed frequently too. In such case, it's more convenient to use single column data model. diff --git a/docs-en/04-develop/03-insert-data/01-sql-writing.mdx b/docs-en/04-develop/03-insert-data/01-sql-writing.mdx deleted file mode 100644 index 64128d8c813278d2c7c45480a5134e77149d05fa..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/01-sql-writing.mdx +++ /dev/null @@ -1,130 +0,0 @@ ---- -sidebar_label: SQL -title: Insert Using 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"; - -## Introduction - -Application program can execute `INSERT` statement through connectors to insert rows. TAOS Shell can be launched manually to insert data too. - -### Insert Single Row - -Below SQL statement is used to insert one row into table "d1001". - -```sql -INSERT INTO d1001 VALUES (1538548685000, 10.3, 219, 0.31); -``` - -### Insert Multiple Rows - -Multiple rows can be inserted in single SQL statement. Below example inserts 2 rows into table "d1001". - -```sql -INSERT INTO d1001 VALUES (1538548684000, 10.2, 220, 0.23) (1538548696650, 10.3, 218, 0.25); -``` - -### Insert into Multiple Tables - -Data can be inserted into multiple tables in same SQL statement. Below example inserts 2 rows into table "d1001" and 1 row into table "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); -``` - -For more details about `INSERT` please refer to [INSERT](/taos-sql/insert). - -:::info - -- Inserting in batch can gain better performance. Normally, the higher the batch size, the better the performance. Please be noted each single row can't exceed 16K bytes and each single SQL statement can't exceed 1M bytes. -- Inserting with multiple threads can gain better performance too. However, depending on the system resources on the client side and the server side, with the number of inserting threads grows to a specific point, the performance may drop instead of growing. The proper number of threads need to be tested in a specific environment to find the best number. - -::: - -:::warning - -- If the timestamp for the row to be inserted already exists in the table, the behavior depends on the value of parameter `UPDATE`. If it's set to 0 (also the default value), the row will be discarded. If it's set to 1, the new values will override the old values for the same row. -- The timestamp to be inserted must be newer than the timestamp of subtracting current time by the parameter `KEEP`. If `KEEP` is set to 3650 days, then the data older than 3650 days ago can't be inserted. The timestamp to be inserted can't be newer than the timestamp of current time plus parameter `DAYS`. If `DAYS` is set to 2, the data newer than 2 days later can't be inserted. - -::: - -## Examples - -### Insert Using SQL - - - - - - - - - - - - - - - - - - - - - - - - - -:::note - -1. With either native connection or REST connection, the above samples can work well. -2. Please be noted that `use db` can't be used with REST connection because REST connection is stateless, so in the samples `dbName.tbName` is used to specify the table name. - -::: - -### Insert with Parameter Binding - -TDengine also provides Prepare API that support parameter binding. Similar to MySQL, only `?` can be used in these APIs to represent the parameters to bind. From version 2.1.1.0 and 2.1.2.0, parameter binding support for inserting data has been improved significantly to improve the insert performance by avoiding the cost of parsing SQL statements. - -Parameter binding is available only with native connection. - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs-en/04-develop/03-insert-data/02-influxdb-line.mdx b/docs-en/04-develop/03-insert-data/02-influxdb-line.mdx deleted file mode 100644 index 172003d203fa309ce51b3ecae9a7490a59f513d7..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/02-influxdb-line.mdx +++ /dev/null @@ -1,70 +0,0 @@ ---- -sidebar_label: InfluxDB Line Protocol -title: InfluxDB Line Protocol ---- - -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"; - -## Introduction - -A single line of text is used in InfluxDB Line protocol format represents one row of data, each line contains 4 parts as shown below. - -``` -measurement,tag_set field_set timestamp -``` - -- `measurement` will be used as the STable name -- `tag_set` will be used as tags, with format like `=,=` -- `field_set`will be used as data columns, with format like `=,=` -- `timestamp` is the primary key timestamp corresponding to this row of data - -For example: - -``` -meters,location=Beijing.Haidian,groupid=2 current=13.4,voltage=223,phase=0.29 1648432611249500 -``` - -:::note - -- All the data in `tag_set` will be converted to ncahr type automatically . -- Each data in `field_set` must be self-description for its data type. For example 1.2f32 means a value 1.2 of float type, it will be treated as double without the "f" type suffix. -- Multiple kinds of precision can be used for the `timestamp` field. Time precision can be from nanosecond (ns) to hour (h). - -::: - -For more details please refer to [InfluxDB Line Protocol](https://docs.influxdata.com/influxdb/v2.0/reference/syntax/line-protocol/) and [TDengine Schemaless](/reference/schemaless/#Schemaless-Line-Protocol) - - -## Examples - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs-en/04-develop/03-insert-data/03-opentsdb-telnet.mdx b/docs-en/04-develop/03-insert-data/03-opentsdb-telnet.mdx deleted file mode 100644 index 66bb67c25669b906183526377f60b969ea3d1e85..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/03-opentsdb-telnet.mdx +++ /dev/null @@ -1,84 +0,0 @@ ---- -sidebar_label: OpenTSDB Line Protocol -title: OpenTSDB Line Protocol ---- - -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"; - -## Introduction - -A single line of text is used in OpenTSDB line protocol to represent one row of data. OpenTSDB employs single column data model, so one line can only contains single data column. There can be multiple tags. Each line contains 4 parts as below: - -``` - =[ =] -``` - -- `metric` will be used as STable name. -- `timestamp` is the timestamp of current row of data. The time precision will be determined automatically based on the length of the timestamp. second and millisecond time precision are supported.\ -- `value` is a metric which must be a numeric value, the corresponding column name is "value". -- The last part is tag sets separated by space, all tags will be converted to nchar type automatically. - -For example: - -```txt -meters.current 1648432611250 11.3 location=Beijing.Haidian groupid=3 -``` - -Please refer to [OpenTSDB Telnet API](http://opentsdb.net/docs/build/html/api_telnet/put.html) for more details. - -## Examples - - - - - - - - - - - - - - - - - - - - - - - - - -2 STables will be crated automatically while each STable has 4 rows of data in the above sample code. - -```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-en/04-develop/03-insert-data/04-opentsdb-json.mdx b/docs-en/04-develop/03-insert-data/04-opentsdb-json.mdx deleted file mode 100644 index 8d9f150df3cdcf1930566714b5be32f739321468..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/04-opentsdb-json.mdx +++ /dev/null @@ -1,99 +0,0 @@ ---- -sidebar_label: OpenTSDB JSON Protocol -title: OpenTSDB JSON Protocol ---- - -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"; - -## Introduction - -A JSON string is sued in OpenTSDB JSON to represent one or more rows of data, for exmaple: - -```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" - } - } -] -``` - -Similar to OpenTSDB line protocol, `metric` will be used as the STable name, `timestamp` is the timestamp to be used, `value` represents the metric collected, `tags` are the tag sets. - - -Please refer to [OpenTSDB HTTP API](http://opentsdb.net/docs/build/html/api_http/put.html) for more details. - -:::note -- In JSON protocol, strings will be converted to nchar type and numeric values will be converted to double type. -- Only data in array format is accepted, array must be used even there is only one row. - -::: - -## Examples - - - - - - - - - - - - - - - - - - - - - - - - - -The above sample code will created 2 STables automatically while each STable has 2 rows of data. - -```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-en/04-develop/03-insert-data/_c_line.mdx b/docs-en/04-develop/03-insert-data/_c_line.mdx deleted file mode 100644 index 5ef2e9af774c54e9f090357286f83d2280c2ab11..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/_c_line.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```c -{{#include docs-examples/c/line_example.c:main}} -``` \ No newline at end of file diff --git a/docs-en/04-develop/03-insert-data/_c_opts_json.mdx b/docs-en/04-develop/03-insert-data/_c_opts_json.mdx deleted file mode 100644 index 22ad2e0122797248a372734aac0f3a16a1356530..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/_c_opts_json.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```c -{{#include docs-examples/c/json_protocol_example.c:main}} -``` \ No newline at end of file diff --git a/docs-en/04-develop/03-insert-data/_c_opts_telnet.mdx b/docs-en/04-develop/03-insert-data/_c_opts_telnet.mdx deleted file mode 100644 index 508d7bc98a149f49766bcd0a474ffe226cbe30bb..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/_c_opts_telnet.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```c -{{#include docs-examples/c/telnet_line_example.c:main}} -``` \ No newline at end of file diff --git a/docs-en/04-develop/03-insert-data/_c_sql.mdx b/docs-en/04-develop/03-insert-data/_c_sql.mdx deleted file mode 100644 index f4153fd2c427677a338d0c377663d0335f2672f0..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/_c_sql.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```c -{{#include docs-examples/c/insert_example.c}} -``` \ No newline at end of file diff --git a/docs-en/04-develop/03-insert-data/_c_stmt.mdx b/docs-en/04-develop/03-insert-data/_c_stmt.mdx deleted file mode 100644 index 7f5ef23a849689c36e732b6fd374a131695c9090..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/_c_stmt.mdx +++ /dev/null @@ -1,6 +0,0 @@ -```c title=Single Row Binding -{{#include docs-examples/c/stmt_example.c}} -``` -```c title=Multiple Row Binding 72:117 -{{#include docs-examples/c/multi_bind_example.c}} -``` \ No newline at end of file diff --git a/docs-en/04-develop/03-insert-data/_category_.yml b/docs-en/04-develop/03-insert-data/_category_.yml deleted file mode 100644 index 8f42ee1a417aaee469f8284f09df0f51c40fd1f7..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/_category_.yml +++ /dev/null @@ -1,5 +0,0 @@ -label: Insert -link: - type: generated-index - slug: /insert-data/ - description: "TDengine supports multiple protocols of inserting data, including SQL, InfluxDB Line protocol, OpenTSDB Telnet protocol, OpenTSDB JSON protocol. Data can be inserted row by row, or in batch. Data from one or more collecting points can be inserted simultaneously. In the meantime, data can be inserted with multiple threads, out of order data and historical data can be inserted too. InfluxDB Line protocol, OpenTSDB Telnet protocol and OpenTSDB JSON protocol are the 3 kinds of schemaless insert protocols supported by TDengine. It's not necessary to create stable and table in advance if using schemaless protocols, and the schemas can be adjusted automatically according to the data to be inserted." diff --git a/docs-en/04-develop/03-insert-data/_cs_line.mdx b/docs-en/04-develop/03-insert-data/_cs_line.mdx deleted file mode 100644 index 9c275ee3d7c7a1e52fbb34dbae922004543ee3ce..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/_cs_line.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```csharp -{{#include docs-examples/csharp/InfluxDBLineExample.cs}} -``` diff --git a/docs-en/04-develop/03-insert-data/_cs_opts_json.mdx b/docs-en/04-develop/03-insert-data/_cs_opts_json.mdx deleted file mode 100644 index 3d538b8506b298241faecd8098f89571359135c9..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/_cs_opts_json.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```csharp -{{#include docs-examples/csharp/OptsJsonExample.cs}} -``` diff --git a/docs-en/04-develop/03-insert-data/_cs_opts_telnet.mdx b/docs-en/04-develop/03-insert-data/_cs_opts_telnet.mdx deleted file mode 100644 index c53bf3d7233115351e5af03b7d9e6318aa4a0da6..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/_cs_opts_telnet.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```csharp -{{#include docs-examples/csharp/OptsTelnetExample.cs}} -``` diff --git a/docs-en/04-develop/03-insert-data/_cs_sql.mdx b/docs-en/04-develop/03-insert-data/_cs_sql.mdx deleted file mode 100644 index c7688bfbe77a1135424d829fe9b29fbb1bc93ae2..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/_cs_sql.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```csharp -{{#include docs-examples/csharp/SQLInsertExample.cs}} -``` diff --git a/docs-en/04-develop/03-insert-data/_cs_stmt.mdx b/docs-en/04-develop/03-insert-data/_cs_stmt.mdx deleted file mode 100644 index 97c3b910ffeb9e0c88fc143a02014115e819c147..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/_cs_stmt.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```csharp -{{#include docs-examples/csharp/StmtInsertExample.cs}} -``` diff --git a/docs-en/04-develop/03-insert-data/_go_line.mdx b/docs-en/04-develop/03-insert-data/_go_line.mdx deleted file mode 100644 index cd225945b70e28bef2ca7fdaf0d9be0ad7ffc18c..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/_go_line.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```go -{{#include docs-examples/go/insert/line/main.go}} -``` diff --git a/docs-en/04-develop/03-insert-data/_go_opts_json.mdx b/docs-en/04-develop/03-insert-data/_go_opts_json.mdx deleted file mode 100644 index 0c0d3e5b6330e046988cdd02234285ec67e92f01..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/_go_opts_json.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```go -{{#include docs-examples/go/insert/json/main.go}} -``` diff --git a/docs-en/04-develop/03-insert-data/_go_opts_telnet.mdx b/docs-en/04-develop/03-insert-data/_go_opts_telnet.mdx deleted file mode 100644 index d5ca40cc146e62412476289853e8e2739e0e9e4b..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/_go_opts_telnet.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```go -{{#include docs-examples/go/insert/telnet/main.go}} -``` diff --git a/docs-en/04-develop/03-insert-data/_go_sql.mdx b/docs-en/04-develop/03-insert-data/_go_sql.mdx deleted file mode 100644 index 613a65add1741eb763a4b24e65d180d05f7d670f..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/_go_sql.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```go -{{#include docs-examples/go/insert/sql/main.go}} -``` diff --git a/docs-en/04-develop/03-insert-data/_go_stmt.mdx b/docs-en/04-develop/03-insert-data/_go_stmt.mdx deleted file mode 100644 index c32bc21fb9bcaf45059e4f47df73fb57f047ed1c..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/_go_stmt.mdx +++ /dev/null @@ -1,8 +0,0 @@ -```go -{{#include docs-examples/go/insert/stmt/main.go}} -``` - -:::tip -`github.com/taosdata/driver-go/v2/wrapper` module in driver-go is the wrapper for C API, it can be used to insert data with parameter binding. - -::: diff --git a/docs-en/04-develop/03-insert-data/_java_line.mdx b/docs-en/04-develop/03-insert-data/_java_line.mdx deleted file mode 100644 index 2e59a5d4701b2a2ab04ec5711845dc5c80067a1e..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/_java_line.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```java -{{#include docs-examples/java/src/main/java/com/taos/example/LineProtocolExample.java}} -``` diff --git a/docs-en/04-develop/03-insert-data/_java_opts_json.mdx b/docs-en/04-develop/03-insert-data/_java_opts_json.mdx deleted file mode 100644 index 826a1a07d9405cb193849f9d21e5444f68517914..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/_java_opts_json.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```java -{{#include docs-examples/java/src/main/java/com/taos/example/JSONProtocolExample.java}} -``` diff --git a/docs-en/04-develop/03-insert-data/_java_opts_telnet.mdx b/docs-en/04-develop/03-insert-data/_java_opts_telnet.mdx deleted file mode 100644 index 954dcc1a482a150dea0b190e1e0593adbfbde796..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/_java_opts_telnet.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```java -{{#include docs-examples/java/src/main/java/com/taos/example/TelnetLineProtocolExample.java}} -``` diff --git a/docs-en/04-develop/03-insert-data/_java_sql.mdx b/docs-en/04-develop/03-insert-data/_java_sql.mdx deleted file mode 100644 index a863378defe43b1f22c1f98087a34f053a7d6619..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/_java_sql.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```java -{{#include docs-examples/java/src/main/java/com/taos/example/RestInsertExample.java:insert}} -``` \ No newline at end of file diff --git a/docs-en/04-develop/03-insert-data/_java_stmt.mdx b/docs-en/04-develop/03-insert-data/_java_stmt.mdx deleted file mode 100644 index 54443e535fa84bdf8dc9161ed4ad00f50b26266c..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/_java_stmt.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```java -{{#include docs-examples/java/src/main/java/com/taos/example/StmtInsertExample.java}} -``` diff --git a/docs-en/04-develop/03-insert-data/_js_line.mdx b/docs-en/04-develop/03-insert-data/_js_line.mdx deleted file mode 100644 index 172c9bc17b8cff8b2620720b235a9c8e69bd4197..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/_js_line.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```js -{{#include docs-examples/node/nativeexample/influxdb_line_example.js}} -``` diff --git a/docs-en/04-develop/03-insert-data/_js_opts_json.mdx b/docs-en/04-develop/03-insert-data/_js_opts_json.mdx deleted file mode 100644 index 20ac9ec91e8dc6675828b16d7da0acb09afd3b5f..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/_js_opts_json.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```js -{{#include docs-examples/node/nativeexample/opentsdb_json_example.js}} -``` diff --git a/docs-en/04-develop/03-insert-data/_js_opts_telnet.mdx b/docs-en/04-develop/03-insert-data/_js_opts_telnet.mdx deleted file mode 100644 index c3c8c40bd642f4f443de88e3db006ad50724d514..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/_js_opts_telnet.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```js -{{#include docs-examples/node/nativeexample/opentsdb_telnet_example.js}} -``` diff --git a/docs-en/04-develop/03-insert-data/_js_sql.mdx b/docs-en/04-develop/03-insert-data/_js_sql.mdx deleted file mode 100644 index f5e17c76892a57a94192a95451b508b1c176c984..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/_js_sql.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```js -{{#include docs-examples/node/nativeexample/insert_example.js}} -``` diff --git a/docs-en/04-develop/03-insert-data/_js_stmt.mdx b/docs-en/04-develop/03-insert-data/_js_stmt.mdx deleted file mode 100644 index 964d7ddc11b90031b70936efb85fbaabe873ddbb..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/_js_stmt.mdx +++ /dev/null @@ -1,12 +0,0 @@ -```js title=Single Row Binding -{{#include docs-examples/node/nativeexample/param_bind_example.js}} -``` - -```js title=Multiple Row Binding -{{#include docs-examples/node/nativeexample/multi_bind_example.js:insertData}} -``` - -:::info -Multiple row binding is better in performance than single row binding, but it can only be used with `INSERT` statement while single row binding can be used for other SQL statements besides `INSERT`. - -::: diff --git a/docs-en/04-develop/03-insert-data/_py_line.mdx b/docs-en/04-develop/03-insert-data/_py_line.mdx deleted file mode 100644 index d3bb1ebb3403b53fa43bfc9d5d1a0de9764d7583..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/_py_line.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```py -{{#include docs-examples/python/line_protocol_example.py}} -``` diff --git a/docs-en/04-develop/03-insert-data/_py_opts_json.mdx b/docs-en/04-develop/03-insert-data/_py_opts_json.mdx deleted file mode 100644 index cfbfe13ccfdb4f3f34b77300812863fdf70d0f59..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/_py_opts_json.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```py -{{#include docs-examples/python/json_protocol_example.py}} -``` diff --git a/docs-en/04-develop/03-insert-data/_py_opts_telnet.mdx b/docs-en/04-develop/03-insert-data/_py_opts_telnet.mdx deleted file mode 100644 index 14bc65a7a3da815abadf7f25c8deffeac666c8d7..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/_py_opts_telnet.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```py -{{#include docs-examples/python/telnet_line_protocol_example.py}} -``` diff --git a/docs-en/04-develop/03-insert-data/_py_sql.mdx b/docs-en/04-develop/03-insert-data/_py_sql.mdx deleted file mode 100644 index c0e15b8ec115b9244d50a47c9eafec04bcfdd70c..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/_py_sql.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```py -{{#include docs-examples/python/native_insert_example.py}} -``` diff --git a/docs-en/04-develop/03-insert-data/_py_stmt.mdx b/docs-en/04-develop/03-insert-data/_py_stmt.mdx deleted file mode 100644 index 16d98f54329ad0d3dfb463392f5c1d41c9aab25b..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/_py_stmt.mdx +++ /dev/null @@ -1,12 +0,0 @@ -```py title=Single Row Binding -{{#include docs-examples/python/bind_param_example.py}} -``` - -```py title=Multiple Row Binding -{{#include docs-examples/python/multi_bind_example.py:bind_batch}} -``` - -:::info -Multiple row binding is better in performance than single row binding, but it can only be used with `INSERT` statement while single row binding can be used for other SQL statements besides `INSERT`. - -::: \ No newline at end of file diff --git a/docs-en/04-develop/03-insert-data/_rust_line.mdx b/docs-en/04-develop/03-insert-data/_rust_line.mdx deleted file mode 100644 index 696ddb7b854751b8dee01047066f97f74212933f..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/_rust_line.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```rust -{{#include docs-examples/rust/schemalessexample/examples/influxdb_line_example.rs}} -``` diff --git a/docs-en/04-develop/03-insert-data/_rust_opts_json.mdx b/docs-en/04-develop/03-insert-data/_rust_opts_json.mdx deleted file mode 100644 index 97d9052dacd1894cc7548a59951ecfaad9caee87..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/_rust_opts_json.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```rust -{{#include docs-examples/rust/schemalessexample/examples/opentsdb_json_example.rs}} -``` diff --git a/docs-en/04-develop/03-insert-data/_rust_opts_telnet.mdx b/docs-en/04-develop/03-insert-data/_rust_opts_telnet.mdx deleted file mode 100644 index 14021f43d8aff30c35dc30c5d278d4e51f375024..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/_rust_opts_telnet.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```rust -{{#include docs-examples/rust/schemalessexample/examples/opentsdb_telnet_example.rs}} -``` diff --git a/docs-en/04-develop/03-insert-data/_rust_sql.mdx b/docs-en/04-develop/03-insert-data/_rust_sql.mdx deleted file mode 100644 index 8e8013e4ad734efcc262ea2f750b82210a538e49..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/_rust_sql.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```rust -{{#include docs-examples/rust/restexample/examples/insert_example.rs}} -``` diff --git a/docs-en/04-develop/03-insert-data/_rust_stmt.mdx b/docs-en/04-develop/03-insert-data/_rust_stmt.mdx deleted file mode 100644 index 590a7a0e717426ed0235331c49dfc578bc55b2f7..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/03-insert-data/_rust_stmt.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```rust -{{#include docs-examples/rust/nativeexample/examples/stmt_example.rs}} -``` diff --git a/docs-en/04-develop/04-query-data/_c.mdx b/docs-en/04-develop/04-query-data/_c.mdx deleted file mode 100644 index 76c9067e2f6af19465cf7c52c3e9b48bb868547d..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/04-query-data/_c.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```c -{{#include docs-examples/c/query_example.c}} -``` \ No newline at end of file diff --git a/docs-en/04-develop/04-query-data/_c_async.mdx b/docs-en/04-develop/04-query-data/_c_async.mdx deleted file mode 100644 index 09f3d3b3ff6d6644f837642ef41db459ba7c5753..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/04-query-data/_c_async.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```c -{{#include docs-examples/c/async_query_example.c:demo}} -``` \ No newline at end of file diff --git a/docs-en/04-develop/04-query-data/_category_.yml b/docs-en/04-develop/04-query-data/_category_.yml deleted file mode 100644 index 5507791d15e2c20c02e5528c94b0a0984a0e2fde..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/04-query-data/_category_.yml +++ /dev/null @@ -1 +0,0 @@ -label: Select diff --git a/docs-en/04-develop/04-query-data/_cs.mdx b/docs-en/04-develop/04-query-data/_cs.mdx deleted file mode 100644 index 2ab52feb564eff0fe251bc9900ea2539171e5dba..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/04-query-data/_cs.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```csharp -{{#include docs-examples/csharp/QueryExample.cs}} -``` diff --git a/docs-en/04-develop/04-query-data/_cs_async.mdx b/docs-en/04-develop/04-query-data/_cs_async.mdx deleted file mode 100644 index f868994b303e62016b5e2f9304275135855c6ae5..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/04-query-data/_cs_async.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```csharp -{{#include docs-examples/csharp/AsyncQueryExample.cs}} -``` diff --git a/docs-en/04-develop/04-query-data/_go.mdx b/docs-en/04-develop/04-query-data/_go.mdx deleted file mode 100644 index 417c12315c06517e2f3de850ac9a379b7714b519..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/04-query-data/_go.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```go -{{#include docs-examples/go/query/sync/main.go}} -``` diff --git a/docs-en/04-develop/04-query-data/_go_async.mdx b/docs-en/04-develop/04-query-data/_go_async.mdx deleted file mode 100644 index 72fff411b980a0dcbdcaf4274722c63e0351db6f..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/04-query-data/_go_async.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```go -{{#include docs-examples/go/query/async/main.go}} -``` diff --git a/docs-en/04-develop/04-query-data/_java.mdx b/docs-en/04-develop/04-query-data/_java.mdx deleted file mode 100644 index 519b9266144486231caf3ee593e973d438941ee4..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/04-query-data/_java.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```java -{{#include docs-examples/java/src/main/java/com/taos/example/RestQueryExample.java}} -``` diff --git a/docs-en/04-develop/04-query-data/_js.mdx b/docs-en/04-develop/04-query-data/_js.mdx deleted file mode 100644 index c5e4c4f3fc20d3940a2bc6e13e6a5dea8a15ff13..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/04-query-data/_js.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```js -{{#include docs-examples/node/nativeexample/query_example.js}} -``` diff --git a/docs-en/04-develop/04-query-data/_js_async.mdx b/docs-en/04-develop/04-query-data/_js_async.mdx deleted file mode 100644 index c65d54ed12f6c4bbeb333e0de0ba9ca4638bff84..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/04-query-data/_js_async.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```js -{{#include docs-examples/node/nativeexample/async_query_example.js}} -``` diff --git a/docs-en/04-develop/04-query-data/_py.mdx b/docs-en/04-develop/04-query-data/_py.mdx deleted file mode 100644 index aeae42a15e5c39b7e9d227afc424e77658109705..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/04-query-data/_py.mdx +++ /dev/null @@ -1,11 +0,0 @@ -Result set is iterated row by row. - -```py -{{#include docs-examples/python/query_example.py:iter}} -``` - -Result set is retrieved as a whole, each row is converted to a dict and returned. - -```py -{{#include docs-examples/python/query_example.py:fetch_all}} -``` \ No newline at end of file diff --git a/docs-en/04-develop/04-query-data/_py_async.mdx b/docs-en/04-develop/04-query-data/_py_async.mdx deleted file mode 100644 index ed6880ae64e59a860e7dc75a5d3c1ad5d2614d01..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/04-query-data/_py_async.mdx +++ /dev/null @@ -1,8 +0,0 @@ -```py -{{#include docs-examples/python/async_query_example.py}} -``` - -:::note -This sample code can't be run on Windows system for now. - -::: diff --git a/docs-en/04-develop/04-query-data/_rust.mdx b/docs-en/04-develop/04-query-data/_rust.mdx deleted file mode 100644 index 742d70fd025ff44b573eedf78441c9d73defad45..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/04-query-data/_rust.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```rust -{{#include docs-examples/rust/restexample/examples/query_example.rs}} -``` diff --git a/docs-en/04-develop/04-query-data/index.mdx b/docs-en/04-develop/04-query-data/index.mdx deleted file mode 100644 index eb31888e1002699d57ec195e9d12c0a44227ab01..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/04-query-data/index.mdx +++ /dev/null @@ -1,185 +0,0 @@ ---- -slug: /query-data -Sidebar_label: Select -title: Select -description: "This chapter introduces major query functionalities and how to perform sync and async query using connectors." ---- - -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 PyAsync from "./_py_async.mdx"; -import NodeAsync from "./_js_async.mdx"; -import CsAsync from "./_cs_async.mdx"; -import CAsync from "./_c_async.mdx"; - -## Introduction - -SQL is used by TDengine as the language for query. Application programs can send SQL statements to TDengine through REST API or connectors. TDengine CLI `taos` can also be used to execute SQL Ad-Hoc query. Here is the list of major query functionalities supported by TDengine： - -- Query on single column or multiple columns -- Filter on tags or data columns：>, <, =, <\>, like -- Grouping of results: `Group By` -- Sorting of results: `Order By` -- Limit the number of results: `Limit/Offset` -- Arithmetic on columns of numeric types or aggregate results -- Join query with timestamp alignment -- Aggregate functions: count, max, min, avg, sum, twa, stddev, leastsquares, top, bottom, first, last, percentile, apercentile, last_row, spread, diff - -For example, below SQL statement can be executed in TDengine CLI `taos` to select the rows whose voltage column is bigger than 215 and limit the output to only 2 rows. - -```sql -select * from d1001 where voltage > 215 order by ts desc limit 2; -``` - -```title=Output -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) -``` - -To meet the requirements in IoT use cases, some special functions have been added in TDengine, for example `twa` (Time Weighted Average), `spared` (The difference between the maximum and the minimum), `last_row` (the last row), more and more functions will be added to better perform in IoT use cases. Furthermore, continuous query is also supported in TDengine. - -For detailed query syntax please refer to [Select](/taos-sql/select). - -## Join Query - -In IoT use cases, there are always multiple data collection points of same kind. A new concept, called STable (abbreviated for super table), is used in TDengine to represent a kind of data collection points, and a table is used to represent a specific data collection point. Tags are used by TDengine to represent the static properties of data collection points. A specific data collection point has its own values for static properties. By specifying filter conditions on tags, join query can be performed efficiently between all the tables belonging to same STable, i.e. same kind of data collection points, can be. Aggregate functions applicable for tables can be used directly on STables, syntax is exactly same. - -### Example 1 - -In TDengine CLI `taos`, use below SQL to get the average voltage of all the meters in BeiJing grouped by 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) -``` - -### Example 2 - -In TDengine CLI `taos`, use below SQL to get the number of rows and the maximum current in the past 24 hours from meters whose groupId is 2. - -``` -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) -``` - -Join query is allowed between only the tables of same STable. In [Select](/taos-sql/select), all query operations are marked as whether it supports STable or not. - -## Down Sampling and Interpolation - -In IoT use cases, down sampling is widely used to aggregate the data by time range. `INTERVAL` keyword in TDengine can be used to simplify the query by time window. For example, below SQL statement can be used to get the sum of current every 10 seconds from meters table d1001. - -``` -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) -``` - -Down sampling can also be used for STable. For example, below SQL statement can be used to get the sum of current from all meters in BeiJing. - -``` -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) -``` - -Down sample also supports time offset. For example, below SQL statement can be used to get the sum of current from all meters but each time window must start at the boundary of 500 milliseconds. - -``` -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) -``` - -In IoT use cases, it's hard to align the timestamp of the data collected by each collection point. However, a lot of algorithms like FFT require the data to be aligned with same time interval and application programs have to handle by themselves in many systems. In TDengine, it's easy to achieve the alignment using down sampling. - -Interpolation can be performed in TDengine if there is no data in a time range. - -For more details please refer to [Aggregate by Window](/taos-sql/interval). - -## Examples - -### Query - -In the section describing [Insert](/develop/insert-data/sql-writing), a database named `power` is created and some data are inserted into STable `meters`. Below sample code demonstrates how to query the data in this STable. - - - - - - - - - - - - - - - - - - - - - - - - - -:::note - -1. With either REST connection or native connection, the above sample code work well. -2. Please be noted that `use db` can't be used in case of REST connection because it's stateless. - -::: - -### Asynchronous Query - -Besides synchronous query, asynchronous query API is also provided by TDengine to insert or query data more efficiently. With similar hardware and software environment, async API is 2~4 times faster than sync APIs. Async API works in non-blocking mode, which means an operation can be returned without finishing so that the calling thread can switch to other works to improve the performance of the whole application system. Async APIs perform especially better in case of poor network. - -Please be noted that async query can only be used with native connection. - - - - - - - - - - - - diff --git a/docs-en/04-develop/05-continuous-query.mdx b/docs-en/04-develop/05-continuous-query.mdx deleted file mode 100644 index 97e32a17ff325a9f67ac0a732be3dd72ccca8888..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/05-continuous-query.mdx +++ /dev/null @@ -1,83 +0,0 @@ ---- -sidebar_label: Continuous Query -description: "Continuous query is a query that's executed automatically according to predefined frequency to provide aggregate query capability by time window, it's actually a simplified time driven stream computing." -title: "Continuous Query" ---- - -Continuous query is a query that's executed automatically according to predefined frequency to provide aggregate query capability by time window, it's actually a simplified time driven stream computing. Continuous query can be performed on a table or STable in TDengine. The result of continuous query can be pushed to client or written back to TDengine. Each query is executed on a time window, which moves forward with time. The size of time window and the forward sliding time need to be specified with parameter `INTERVAL` and `SLIDING` respectively. - -Continuous query in TDengine is time driven, and can be defined using TAOS SQL directly without any extra operations. With continuous query, the result can be generated according to time window to achieve down sampling of original data. Once a continuous query is defined using TAOS SQL, the query is automatically executed at the end of each time window and the result is pushed back to client or written to TDengine. - -There are some differences between continuous query in TDengine and time window computation in stream computing： - -- The computation is performed and the result is returned in real time in stream computing, but the computation in continuous query is only started when a time window closes. For example, if the time window is 1 day, then the result will only be generated at 23:59:59. -- If a historical data row is written in to a time widow for which the computation has been finished, the computation will not be performed again and the result will not be pushed to client again either. If the result has been written into TDengine, there will be no update for the result. -- In continuous query, if the result is pushed to client, the client status is not cached on the server side and Exactly-once is not guaranteed by the server either. If the client program crashes, a new time window will be generated from the time where the continuous query is restarted. If the result is written into TDengine, the data written into TDengine can be guaranteed as valid and continuous. - -## Syntax - -```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: The time window for which continuous query is performed - -SLIDING: The time step for which the time window moves forward each time - -## How to Use - -In this section the use case of meters will be used to introduce how to use continuous query. Assume the STable and sub tables have been created using below SQL statement. - -```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); -``` - -The average voltage for each time window of one minute with 30 seconds as the length of moving forward can be retrieved using below SQL statement. - -```sql -select avg(voltage) from meters interval(1m) sliding(30s); -``` - -Whenever the above SQL statement is executed, all the existing data will be computed again. If the computation needs to be performed every 30 seconds automatically to compute on the data in the past one minute, the above SQL statement needs to be revised as below, in which `{startTime}` stands for the beginning timestamp in the latest time window. - -```sql -select avg(voltage) from meters where ts > {startTime} interval(1m) sliding(30s); -``` - -Another easier way for same purpose is prepend `create table {tableName} as` before the `select`. - -```sql -create table avg_vol as select avg(voltage) from meters interval(1m) sliding(30s); -``` - -A table named as `avg_vol` will be created automatically, then every 30 seconds the `select` statement will be executed automatically on the data in the past 1 minutes, i.e. the latest time window, and the result is written into table `avg_vol`. The client program just needs to query from table `avg_vol`. For example: - -```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 | -``` - -Please be noted that the minimum allowed time window is 10 milliseconds, and no upper limit. - -Besides, it's allowed to specify the start and end time of continuous query. If the start time is not specified, the timestamp of the first original row will be considered as the start time; if the end time is not specified, the continuous will be performed infinitely, otherwise it will be terminated once the end time is reached. For example, the continuous query in below SQL statement will be started from now and terminated one hour later. - -```sql -create table avg_vol as select avg(voltage) from meters where ts > now and ts <= now + 1h interval(1m) sliding(30s); -``` - -`now` in above SQL statement stands for the time when the continuous query is created, not the time when the computation is actually performed. Besides, to avoid the trouble caused by the delay of original data as much as possible, the actual computation in continuous query is also started with a little delay. That means, once a time window closes, the computation is not started immediately. Normally, the result can only be available a little time later, normally within one minute, after the time window closes. - -## How to Manage - -`show streams` command can be used in TDengine CLI `taos` to show all the continuous queries in the system, and `kill stream` can be used to terminate a continuous query. diff --git a/docs-en/04-develop/06-subscribe.mdx b/docs-en/04-develop/06-subscribe.mdx deleted file mode 100644 index 45b13d94c45e62ea8efb6e45e798a71e8cb16cba..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/06-subscribe.mdx +++ /dev/null @@ -1,257 +0,0 @@ ---- -sidebar_label: Subscription -description: "Lightweight service for data subscription and pushing, the time series data inserted into TDengine continuously can be pushed automatically to the subscribing clients." -title: Data Subscription ---- - -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"; - -## Introduction - -According to the time series nature of the data, data inserting in TDengine is similar to data publishing in message queues, they both can be considered as a new data record with timestamp is inserted into the system. Data is stored in ascending order of timestamp inside TDengine, so essentially each table in TDengine can be considered as a message queue. - -Lightweight service for data subscription and pushing is built in TDengine. With the API provided by TDengine, client programs can used `select` statement to subscribe the data from one or more tables. The subscription and and state maintenance is performed on the client side, the client programs polls the server to check whether there is new data, and if so the new data will be pushed back to the client side. If the client program is restarted, where to start for retrieving new data is up to the client side. - -There are 3 major APIs related to subscription provided in the TDengine client driver. - -```c -taos_subscribe -taos_consume -taos_unsubscribe -``` - -For more details about these API please refer to [C/C++ Connector](/reference/connector/cpp). Their usage will be introduced below using the use case of meters, in which the schema of STable and sub tables please refer to the previous section "continuous query". Full sample code can be found [here](https://github.com/taosdata/TDengine/blob/master/examples/c/subscribe.c). - -If we want to get notification and take some actions if the current exceeds a threshold, like 10A, from some meters, there are two ways: - -The first way is to query on each sub table and record the last timestamp matching the criteria, then after some time query on the data later than recorded timestamp and repeat this process. The SQL statements for this way are as below. - -```sql -select * from D1001 where ts > {last_timestamp1} and current > 10; -select * from D1002 where ts > {last_timestamp2} and current > 10; -... -``` - -The above way works, but the problem is that the number of `select` statements increases with the number of meters grows. Finally the performance of both client side and server side will be unacceptable once the number of meters grows to a big enough number. - -A better way is to query on the STable, only one `select` is enough regardless of the number of meters, like below: - -```sql -select * from meters where ts > {last_timestamp} and current > 10; -``` - -However, how to choose `last_timestamp` becomes a new problem if using this way. Firstly, the timestamp when the data is generated is different from the timestamp when the data is inserted into the database, sometimes the difference between them may be very big. Secondly, the time when the data from different meters may arrives at the database may be different too. If the timestamp of the "slowest" meter is used as `last_timestamp` in the query, the data from other meters may be selected repeatedly; but if the timestamp of the "fasted" meters is used as `last_timestamp`, some data from other meters may be missed. - -All the problems mentioned above can be resolved thoroughly using subscription provided by TDengine. - -The first step is to create subscription using `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); -} -``` - -The subscription in TDengine can be either synchronous or asynchronous. In the above sample code, the value of variable `async` is determined from the CLI input, then it's used to create either an async or sync subscription. Sync subscription means the client program needs to invoke `taos_consume` to retrieve data, and async subscription means another thread created by `taos_subscribe` internally invokes `taos_consume` to retrieve data and pass the data to `subscribe_callback` for processing, `subscribe_callback` is a call back function provided by the client program and it's suggested not to do time consuming operation in the call back function. - -The parameter `taos` is an established connection. There is nothing special in sync subscription mode. In async subscription, it should be exclusively by current thread, otherwise unpredictable error may occur. - -The parameter `sql` is a `select` statement in which `where` clause can be used to specify filter conditions. In our example, the data whose current exceeds 10A needs to be subscribed like below SQL statement: - -```sql -select * from meters where current > 10; -``` - -Please be noted that, all the data will be processed because no start time is specified. If only the data from one day ago needs to be processed, a time related condition can be added: - -```sql -select * from meters where ts > now - 1d and current > 10; -``` - -The parameter `topic` is the name of the subscription, it needs to be guaranteed unique in the client program, but it's not necessary to be globally unique because subscription is implemented in the APIs on client side. - -If the subscription named as `topic` doesn't exist, parameter `restart` would be ignored. If the subscription named as `topic` has been created before by the client program which then exited, when the client program is restarted to use this `topic`, parameter `restart` is used to determine retrieving data from beginning or from the last point where the subscription was broken. If the value of `restart` is **true** (i.e. a non-zero value), the data will be retrieved from beginning, or if it is **false** (i.e. zero), the data already consumed before will not be processed again. - -The last parameter of `taos_subscribe` is the polling interval in unit of millisecond. In sync mode, if the time difference between two continuous invocations to `taos_consume` is smaller than the interval specified by `taos_subscribe`, `taos_consume` would be blocked until the interval is reached. In async mode, this interval is the minimum interval between two invocations to the call back function. - -The last second parameter of `taos_subscribe` is used to pass arguments to the call back function. `taos_subscribe` doesn't process this parameter and simply passes it to the call back function. This parameter is simply ignored in sync mode. - -After a subscription is created, its data can be consumed and processed, below is the sample code of how to consume data in sync mode, in the else part if `if (async)`. - -```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(); -　　} -} -``` - -In the above sample code, there is an infinite loop, each time carriage return is entered `taos_consume` is invoked, the return value of `taos_consume` is the selected result set, exactly as the input of `taos_use_result`, in the above sample `print_result` is used instead to simplify the sample. Below is the implementation of `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); -} -``` - -In the above code `taos_print_row` is used to process the data consumed. All the matching rows will be printed. - -In async mode, the data consuming is simpler as below. - -```c -void subscribe_callback(TAOS_SUB* tsub, TAOS_RES *res, void* param, int code) { -　　print_result(res, *(int*)param); -} -``` - -`taos_unsubscribe` can be invoked to terminate a subscription. - -```c -taos_unsubscribe(tsub, keep); -``` - -The second parameter `keep` is used to specify whether to keep the subscription progress on the client sde. If it is **false**, i.e. **0**, then subscription will be restarted from beginning regardless of the `restart` parameter's value in when `taos_subscribe` is invoked again. The subscription progress information is stored in _{DataDir}/subscribe/_ , under which there is a file with same name as `topic` for each subscription, the subscription will be restarted from beginning if the corresponding progress file is removed. - -Now let's see the effect of the above sample code, assuming below prerequisites have been done. - -- The sample code has been downloaded to local system 示 -- TDengine has been installed and launched properly on same system -- The database, STable, sub tables required in the sample code have been ready - -It's ready to launch below command in the directory where the sample code resides to compile and start the program. - -```bash -make -./subscribe -sql='select * from meters where current > 10;' -``` - -After the program is started, open another terminal and launch TDengine CLI `taos`, then use below SQL commands to insert a row whose current is 12A into table **D1001**. - -```sql -use test; -insert into D1001 values(now, 12, 220, 1); -``` - -Then, this row of data will be shown by the example program on the first terminal because its current exceeds 10A. More data can be inserted for you to observe the output of the example program. - -## Examples - -Below example program demonstrates how to subscribe the data rows whose current exceeds 10A using connectors. - -### Prepare Data - -```bash -# 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) -``` - -### Example Programs - - - - - - - - - {/* - - */} - - - - {/* - - - - - */} - - - - - -### Run the Examples - -The example programs firstly consume all historical data matching the criteria. - -```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 -``` - -Next, use TDengine CLI to insert a new row. - -``` -# taos -taos> use power; -taos> insert into d1001 values(now, 12.4, 220, 1); -``` - -Because the current in inserted row exceeds 10A, it will be consumed by the example program. - -``` -ts: 1651146662805 current: 12.4 voltage: 220 phase: 1 location: Beijing.Chaoyang groupid: 2 -``` diff --git a/docs-en/04-develop/07-cache.md b/docs-en/04-develop/07-cache.md deleted file mode 100644 index 13db6c363802abed290cfc4d4466d40e48852f3d..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/07-cache.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -sidebar_label: Cache -title: Cache -description: "The latest row of each table is kept in cache to provide high performance query of latest state." ---- - -The cache management policy in TDengine is First-In-First-Out (FIFO), which is also known as insert driven cache management policy and different from read driven cache management, i.e. Least-Recent-Used (LRU). It simply stores the latest data in cache and flushes the oldest data in cache to disk when the cache usage reaches a threshold. In IoT use cases, the most cared about data is the latest data, i.e. current state. The cache policy in TDengine is based the nature of IoT data. - -Caching the latest data provides the capability of retrieving data in milliseconds. With this capability, TDengine can be configured properly to be used as caching system without deploying another separate caching system to simplify the system architecture and minimize the operation cost. The cache will be emptied after TDengine is restarted, TDengine doesn't reload data from disk into cache like a real key-value caching system. - -The memory space used by TDengine cache is fixed in size, according to the configuration based on application requirement and system resources. Independent memory pool is allocated for and managed by each vnode (virtual node) in TDengine, there is no sharing of memory pools between vnodes. All the tables belonging to a vnode share all the cache memory of the vnode. - -Memory pool is divided into blocks and data is stored in row format in memory and each block follows FIFO policy. The size of each block is determined by configuration parameter `cache`, the number of blocks for each vnode is determined by `blocks`. For each vnode, the total cache size is `cache * blocks`. It's better to set the size of each block to hold at least tends of rows. - -`last_row` function can be used to retrieve the last row of a table or a STable to quickly show the current state of devices on monitoring screen. For example below SQL statement retrieves the latest voltage of all meters in Chaoyang district of Beijing. - -```sql -select last_row(voltage) from meters where location='Beijing.Chaoyang'; -``` diff --git a/docs-en/04-develop/08-udf.md b/docs-en/04-develop/08-udf.md deleted file mode 100644 index e344e4024ca629607ff6c1a7be13186d548838c5..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/08-udf.md +++ /dev/null @@ -1,218 +0,0 @@ ---- -sidebar_label: UDF -title: User Defined Functions -description: "Scalar functions and aggregate functions developed by users can be utilized by the query framework to expand the query capability" ---- - -In some use cases, the query capability required by application programs can't be achieved directly by builtin functions. With UDF, the functions developed by users can be utilized by query framework to meet some special requirements. UDF normally takes one column of data as input, but can also support the result of sub query as input. - -From version 2.2.0.0, UDF programmed in C/C++ language can be supported by TDengine. - -Two kinds of functions can be implemented by UDF: scalar function and aggregate function. - -## Define UDF - -### Scalar Function - -Below function template can be used to define your own scalar function. - -`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` is the place holder of function name, a function implemented based on the above template can be used to perform scalar computation on data rows. The parameters are fixed to control the data exchange between UDF and TDengine. - -- Defintions of the parameters: - - - data：input data - - itype：the type of input data, for details please refer to [type definition in column_meta](/reference/rest-api/), for example 4 represents INT - - iBytes：the number of bytes consumed by each value in the input data - - oType：the type of output data, similar to iType - - oBytes：the number of bytes consumed by each value in the output data - - numOfRows：the number of rows in the input data - - ts: the column of timestamp corresponding to the input data - - dataOutput：the buffer for output data, total size is `oBytes * numberOfRows` - - interBuf：the buffer for intermediate result, its size is specified by `BUFSIZE` parameter when creating a UDF. It's normally used when the intermediate result is not same as the final result, it's allocated and freed by TDengine. - - tsOutput：the column of timestamps corresponding to the output data; it can be used to output timestamp together with the output data if it's not NULL - - numOfOutput：the number of rows in output data - - buf：for the state exchange between UDF and TDengine - - [add_one.c](https://github.com/taosdata/TDengine/blob/develop/tests/script/sh/add_one.c) is one example of the simplest UDF implementations, i.e. one instance of the above `udfNormalFunc` template. It adds one to each value of a column passed in which can be filtered using `where` clause and outputs the result. - -### Aggregate Function - -Below function template can be used to define your own aggregate function. - -`void abs_max_merge(char* data, int32_t numOfRows, char* dataOutput, int32_t* numOfOutput, SUdfInit* buf)` - -`udfMergeFunc` is the place holder of function name, the function implemented with the above template is used to aggregate the intermediate result, only can be used in the aggregate query for STable. - -Definitions of the parameters: - -- data：array of output data, if interBuf is used it's an array of interBuf -- numOfRows：number of rows in `data` -- dataOutput：the buffer for output data, the size is same as that of the final result; If the result is not final, it can be put in the interBuf, i.e. `data`. -- numOfOutput：number of rows in the output data -- buf：for the state exchange between UDF and TDengine - -[abs_max.c](https://github.com/taosdata/TDengine/blob/develop/tests/script/sh/abs_max.c) is an user defined aggregate function to get the maximum from the absolute value of a column. - -The internal processing is that the data affected by the select statement will be divided into multiple row blocks and `udfNormalFunc`, i.e. `abs_max` in this case, is performed on each row block to generate the intermediate of each sub table, then `udfMergeFunc`, i.e. `abs_max_merge` in this case, is performed on the intermediate result of sub tables to aggregate to generate the final or intermediate result of STable. The intermediate result of STable is finally processed by `udfFinalizeFunc` to generate the final result, which contain either 0 or 1 row. - -Other typical scenarios, like covariance, can also be achieved by aggregate UDF. - -### Finalize - -Below function template can be used to finalize the result of your own UDF, normally used when interBuf is used. - -`void abs_max_finalize(char* dataOutput, char* interBuf, int* numOfOutput, SUdfInit* buf)` - -`udfFinalizeFunc` is the place holder of function name, definitions of the parameter are as below: - -- dataOutput：buffer for output data -- interBuf：buffer for intermediate result, can be used as input for next processing step -- numOfOutput：number of output data, can only be 0 or 1 for aggregate function -- buf：for state exchange between UDF and TDengine - -## UDF Conventions - -The naming of 3 kinds of UDF, i.e. udfNormalFunc, udfMergeFunc, and udfFinalizeFunc is required to have same prefix, i.e. the actual name of udfNormalFunc, which means udfNormalFunc doesn't need a suffix following the function name. While udfMergeFunc should be udfNormalFunc followed by `_merge`, udfFinalizeFunc should be udfNormalFunc followed by `_finalize`. The naming convention is part of UDF framework, TDengine follows this convention to invoke corresponding actual functions.\ - -According to the kind of UDF to implement, the functions that need to be implemented are different. - -- Scalar function：udfNormalFunc is required -- Aggregate function：udfNormalFunc, udfMergeFunc (if query on STable) and udfFinalizeFunc are required - -To be more accurate, assuming we want to implement a UDF named "foo". If the function is a scalar function, what we really need to implement is `foo`; if the function is aggregate function, we need to implement `foo`, `foo_merge`, and `foo_finalize`. For aggregate UDF, even though one of the three functions is not necessary, there must be an empty implementation. - -## Compile UDF - -The source code of UDF in C can't be utilized by TDengine directly. UDF can only be loaded into TDengine after compiling to dynamically linked library. - -For example, the example UDF `add_one.c` mentioned in previous sections need to be compiled into DLL using below command on Linux Shell. - -```bash -gcc -g -O0 -fPIC -shared add_one.c -o add_one.so -``` - -The generated DLL file `dd_one.so` can be used later when creating UDF. It's recommended to use GCC not older than 7.5. - -## Create and Use UDF - -### Create UDF - -SQL command can be executed on the same hos where the generated UDF DLL resides to load the UDF DLL into TDengine, this operation can't be done through REST interface or web console. Once created, all the clients of the current TDengine can use these UDF functions in their SQL commands. UDF are stored in the management node of TDengine. The UDFs loaded in TDengine would be still available after TDengine is restarted. - -When creating UDF, it needs to be clarified as either scalar function or aggregate function. If the specified type is wrong, the SQL statements using the function would fail with error. Besides, the input type and output type don't need to be same in UDF, but the input data type and output data type need to be consistent with the UDF definition. - -- Create Scalar Function - -```sql -CREATE FUNCTION ids(X) AS ids(Y) OUTPUTTYPE typename(Z) [ BUFSIZE B ]; -``` - -- ids(X)：the function name to be sued in SQL statement, must be consistent with the function name defined by `udfNormalFunc` -- ids(Y)：the absolute path of the DLL file including the implementation of the UDF, the path needs to be quoted by single or double quotes -- typename(Z)：the output data type, the value is the literal string of the type -- B：the size of intermediate buffer, in bytes; it's an optional parameter and the range is [0,512] - -For example, below SQL statement can be used to create a UDF from `add_one.so`. - -```sql -CREATE FUNCTION add_one AS "/home/taos/udf_example/add_one.so" OUTPUTTYPE INT; -``` - -- Create Aggregate Function - -```sql -CREATE AGGREGATE FUNCTION ids(X) AS ids(Y) OUTPUTTYPE typename(Z) [ BUFSIZE B ]; -``` - -- ids(X)：the function name to be sued in SQL statement, must be consistent with the function name defined by `udfNormalFunc` -- ids(Y)：the absolute path of the DLL file including the implementation of the UDF, the path needs to be quoted by single or double quotes -- typename(Z)：the output data type, the value is the literal string of the type 此 -- B：the size of intermediate buffer, in bytes; it's an optional parameter and the range is [0,512] - -For details about how to use intermediate result, please refer to example program [demo.c](https://github.com/taosdata/TDengine/blob/develop/tests/script/sh/demo.c). - -For example, below SQL statement can be used to create a UDF rom `demo.so`. - -```sql -CREATE AGGREGATE FUNCTION demo AS "/home/taos/udf_example/demo.so" OUTPUTTYPE DOUBLE bufsize 14; -``` - -### Manage UDF - -- Delete UDF - -``` -DROP FUNCTION ids(X); -``` - -- ids(X)：same as that in `CREATE FUNCTION` statement - -```sql -DROP FUNCTION add_one; -``` - -- Show Available UDF - -```sql -SHOW FUNCTIONS; -``` - -### Use UDF - -The function name specified when creating UDF can be used directly in SQL statements, just like builtin functions. - -```sql -SELECT X(c) FROM table/STable; -``` - -The above SQL statement invokes function X for column c. - -## Restrictions for UDF - -In current version there are some restrictions for UDF - -1. Only Linux is supported when creating and invoking UDF for both client side and server side -2. UDF can't be mixed with builtin functions -3. Only one UDF can be used in a SQL statement -4. Single column is supported as input for UDF -5. Once created successfully, UDF is persisted in MNode of TDengineUDF -6. UDF can't be created through REST interface -7. The function name used when creating UDF in SQL must be consistent with the function name defined in the DLL, i.e. the name defined by `udfNormalFunc` -8. The name name of UDF name should not conflict with any of builtin functions - -## Examples - -### Scalar function example [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}} -``` - -
- -### Aggregate function example [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}} -``` - -
- -### Example for using intermediate result [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-en/04-develop/_category_.yml b/docs-en/04-develop/_category_.yml deleted file mode 100644 index e06175285245929dd46d19e59b4ca561957d0bcf..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/_category_.yml +++ /dev/null @@ -1,5 +0,0 @@ -label: Develop -link: - type: generated-index - slug: /develop - description: "The guide is for developers to quickly learn about the functionalities of TDengine, including fundamentals like data model, inserting data, query and advanced features like data subscription, continuous query. For each functionality, sample code of multiple programming languages are provided for developers to get started quickly." diff --git a/docs-en/04-develop/_sub_c.mdx b/docs-en/04-develop/_sub_c.mdx deleted file mode 100644 index 95fef0042d0a277f9136e6e6f8c15558487232f9..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/_sub_c.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```c -{{#include docs-examples/c/subscribe_demo.c}} -``` \ No newline at end of file diff --git a/docs-en/04-develop/_sub_cs.mdx b/docs-en/04-develop/_sub_cs.mdx deleted file mode 100644 index 80934aa4d014a076896dce7f41e520f06ffd735d..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/_sub_cs.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```csharp -{{#include docs-examples/csharp/SubscribeDemo.cs}} -``` \ No newline at end of file diff --git a/docs-en/04-develop/_sub_go.mdx b/docs-en/04-develop/_sub_go.mdx deleted file mode 100644 index cd908fc12c3a35f49ca108ee56c3951c5388a95f..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/_sub_go.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```go -{{#include docs-examples/go/sub/main.go}} -``` \ No newline at end of file diff --git a/docs-en/04-develop/_sub_java.mdx b/docs-en/04-develop/_sub_java.mdx deleted file mode 100644 index e65bc576ebed030d935ced6a4572289cd367ffac..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/_sub_java.mdx +++ /dev/null @@ -1,7 +0,0 @@ -```java -{{#include docs-examples/java/src/main/java/com/taos/example/SubscribeDemo.java}} -``` -:::note -For now Java connector doesn't provide asynchronous subscription, but `TimerTask` can be used to achieve similar purpose. - -::: \ No newline at end of file diff --git a/docs-en/04-develop/_sub_node.mdx b/docs-en/04-develop/_sub_node.mdx deleted file mode 100644 index c93ad627ce9a77ca71a014b41d571089e6c1727b..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/_sub_node.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```js -{{#include docs-examples/node/nativeexample/subscribe_demo.js}} -``` \ No newline at end of file diff --git a/docs-en/04-develop/_sub_python.mdx b/docs-en/04-develop/_sub_python.mdx deleted file mode 100644 index b817deeba6e283a3ba16fee0d580d3823c999536..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/_sub_python.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```py -{{#include docs-examples/python/subscribe_demo.py}} -``` \ No newline at end of file diff --git a/docs-en/04-develop/_sub_rust.mdx b/docs-en/04-develop/_sub_rust.mdx deleted file mode 100644 index 4750cf7a3b871db48c9e5a26b22ab4b8a03f11be..0000000000000000000000000000000000000000 --- a/docs-en/04-develop/_sub_rust.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```rs -{{#include docs-examples/rust/nativeexample/examples/subscribe_demo.rs}} -``` \ No newline at end of file diff --git a/docs-en/10-cluster/01-deploy.md b/docs-en/10-cluster/01-deploy.md deleted file mode 100644 index f434f7d2195ad37c0be95439120cfb75a3bee5f0..0000000000000000000000000000000000000000 --- a/docs-en/10-cluster/01-deploy.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: Deploy ---- - -## Prerequisites - -### Step 1 - -The FQDN of all hosts need to be setup properly, all the FQDNs need to be configured in the /etc/hosts of each host. It must be guaranteed that each FQDN can be accessed (by ping, for example) from any other hosts. - -On each host command `hostname -f` can be executed to get the hostname. `ping` command can be executed on each host to check whether any other host is accessible from it. If any host is not accessible, the network configuration, like /etc/hosts or DNS configuration, need to be checked and revised to make any two hosts accessible to each other. - -:::note - -- The host where the client program runs also needs to configured properly for FQDN, to make sure all hosts for client or server can be accessed from any other. In other words, the hosts where the client is running are also considered as a part of the cluster. - -- It's suggested to disable the firewall for all hosts in the cluster. At least TCP/UDP for port 6030~6042 need to be open if firewall is enabled. - -::: - -### Step 2 - -If any previous version of TDengine has been installed and configured on any host, the installation needs to be removed and the data needs to be cleaned up. For details about uninstalling please refer to [Install and Uninstall](/operation/pkg-install). To clean up the data, please use `rm -rf /var/lib/taos/\*` assuming the `dataDir` is configured as `/var/lib/taos`. - -### Step 3 - -Now it's time to install TDengine on all hosts without starting `taosd`, the versions on all hosts should be same. If it's prompted to input the existing TDengine cluster, simply press carriage return to ignore it. `install.sh -e no` can also be used to disable this prompt. For details please refer to [Install and Uninstall](/operation/pkg-install). - -### Step 4 - -Now each physical node (referred to as `dnode` hereinafter, it's abbreviation for "data node") of TDengine need to be configured properly. Please be noted that one dnode doesn't stand for one host, multiple TDengine nodes can be started on single host as long as they are configured properly without conflicting. More specifically each instance of the configuration file `taos.cfg` stands for a dnode. Assuming the first dnode of TDengine cluster is "h1.taosdata.com:6030", its `taos.cfg` is configured as following. - -```c -// firstEp is the end point to connect to when any dnode starts -firstEp h1.taosdata.com:6030 - -// must be configured to the FQDN of the host where the dnode is launched -fqdn h1.taosdata.com - -// the port used by the dnode, default is 6030 -serverPort 6030 - -// only necessary when replica is configured to an even number -#arbitrator ha.taosdata.com:6042 -``` - -`firstEp` and `fqdn` must be configured properly. In `taos.cfg` of all dnodes in TDengine cluster, `firstEp` must be configured to point to same address, i.e. the first dnode of the cluster. `fqdn` and `serverPort` compose the address of each node itself. If you want to start multiple TDengine dnodes on a single host, please also make sure all other configurations like `dataDir`, `logDir`, and other resources related parameters are not conflicting. - -For all the dnodes in a TDengine cluster, below parameters must be configured as exactly same, any node whose configuration is different from dnodes already in the cluster can't join the cluster. - -| **#** | **Parameter** | **Definition** | -| ----- | ------------------ | --------------------------------------------------------------------------------- | -| 1 | numOfMnodes | The number of management nodes in the cluster | -| 2 | mnodeEqualVnodeNum | The ratio of resource consuming of mnode to vnode | -| 3 | offlineThreshold | The threshold of dnode offline, once it's reached the dnode is considered as down | -| 4 | statusInterval | The interval by which dnode reports its status to mnode | -| 5 | arbitrator | End point of the arbitrator component in the cluster | -| 6 | timezone | Timezone | -| 7 | balance | Enable load balance automatically | -| 8 | maxTablesPerVnode | Maximum number of tables that can be created in each vnode | -| 9 | maxVgroupsPerDb | Maximum number vgroups that can be used by each DB | - -:::note -Prior to version 2.0.19.0, besides the above parameters, `locale` and `charset` must be configured as same too for each dnode. - -::: - -## Start Cluster - -### Start The First DNODE - -The first dnode can be started following the instructions in [Get Started](/get-started/), for example h1.taosdata.com. Then TDengine CLI `taos` can be launched to execute command `show dnodes`, the output is as following for example: - -``` -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> -``` - -From the above output, it is shown that the end point of the started dnode is "h1.taos.com:6030", which is the `firstEp` of the cluster. - -### Start Other DNODEs - -There are a few steps necessary to add other dnodes in the cluster. - -Firstly, start `taosd` as instructed in [Get Started](/get-started/), assuming it's for the second dnode. Before starting `taosd`, please making sure the configuration is correct, especially `firstEp`, `FQDN` and `serverPort`, `firstEp` must be same as the dnode shown in the section "Start First DNODE", i.e. "h1.taosdata.com" in this example. - -Then, on the first dnode, use TDengine CLI `taos` to execute below command to add the end point of the dnode in the cluster. In the command "fqdn:port" should be quoted using double quotes. - -```sql -CREATE DNODE "h2.taos.com:6030"; -``` - -Then on the first dnode, execute `show dnodes` in `taos` to show whether the second dnode has been added in the cluster successfully or not. - -```sql -SHOW DNODES; -``` - -If the status of the newly added dnode is offlie, please check: - -- Whether the `taosd` process is running properly or not -- In the log file `taosdlog.0` to see whether the fqdn and port are correct or not 查 - -The above process can be repeated to add more dnodes in the cluster. diff --git a/docs-en/10-cluster/02-cluster-mgmt.md b/docs-en/10-cluster/02-cluster-mgmt.md deleted file mode 100644 index 92e6d63428e177b243ccdbca0e44aad6fd940842..0000000000000000000000000000000000000000 --- a/docs-en/10-cluster/02-cluster-mgmt.md +++ /dev/null @@ -1,213 +0,0 @@ ---- -sidebar_label: Operation -title: Manage DNODEs ---- - -It has been introduced that how to deploy and start a cluster from scratch. Once a cluster is ready, the dnode status in the cluster can be shown at any time, new dnode can be added to scale out the cluster, an existing dnode can be removed, even load balance can be performed manually.\ - -:::note -All the commands to be introduced in this chapter need to be run after login TDengine, sometimes it's necessary to use root privilege. - -::: - -## Show DNODEs - -below command can be executed in TDengine CLI `taos` to list all dnodes in the cluster, including ID, end point (fqdn:port), status (ready, offline), number of vnodes, number of free vnodes, etc. It's suggested to execute this command to check after adding or removing a dnode. - -```sql -SHOW DNODES; -``` - -Below is the example output of this command. - -``` -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) -``` - -## Show VGROUPs - -To utilize system resources efficiently and provide scalability, data sharding is required. The data of each database is divided into multiple shards and stored in multiple vnodes. These vnodes may be located in different dnodes, scaling out can be achieved by adding more vnodes from more dnodes. Each vnode can only be used for a single DB, but one DB can have multiple vnodes. The allocation of vnode is scheduled automatically by mnode according to system resources of the dnodes. - -Launch TDengine CLI `taos` and execute below command: - -```sql -USE SOME_DATABASE; -SHOW VGROUPS; -``` - -The example output is as below: - -``` -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) -``` - -## Add DNODE - -Launch TDengine CLI `taos` and execute to add the end point of a new dnode into the EPI (end point) list of the cluster. "fqdn:port" must be quoted using double quotes. - -```sql -CREATE DNODE "fqdn:port"; -``` - -The example output is as below: - -``` -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) -``` - -It can be seen that the status of the new dnode is "offline", once the dnode is started and connects the firstEp of the cluster, execute the command again and get below example output, from which it can be seen that two dnodes are both in "ready" status. - -``` -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) -``` - -## Drop DNODE - -Launch TDengine CLI `taos` and execute command below to drop or remove a dndoe from the cluster. In the command, `dnodeId` can be gotten from `show dnodes`. - -```sql -DROP DNODE "fqdn:port"; -``` - -or - -```sql -DROP DNODE dnodeId; -``` - -The example output is as below： - -``` -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) -``` - -In the above example, when `show dnodes` is executed the first time, two dnodes are shown. Then `drop dnode 2` is executed, after that from the output of executing `show dnodes` again it can be seen that only the dnode with ID 1 is still in the cluster. - -:::note - -- Once a dnode is dropped, it can't rejoin the cluster. To rejoin, the dnode needs to deployed again after cleaning up the data directory. Normally, before dropping a dnode, the data belonging to the dnode needs to be migrated to other place. -- Please be noted that `drop dnode` is different from stopping `taosd` process. `drop dnode` just removes the dnode out of TDengine cluster. Only after a dnode is dropped, can the corresponding `taosd` process be stopped. -- Once a dnode is dropped, other dnodes in the cluster will be notified of the drop and will not accept the request from the dropped dnode. -- dnodeID is allocated automatically and can't be interfered manually. dnodeID is generated in ascending order without duplication. - -::: - -## Move VNODE - -A vnode can be manually moved from one dnode to another. - -Launch TDengine CLI `taos` and execute below command: - -```sql -ALTER DNODE BALANCE "VNODE:-DNODE:"; -``` - -In the above command, `source-dnodeId` is the original dnodeId where the vnode resides, `dest-dnodeId` specifies the target dnode. vgId (vgroup ID) can be shown by `SHOW VGROUPS `. - -Firstly `show vgroups` is executed to show the vgrup distribution. - -``` -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) -``` - -It can be seen that there are 5 vgroups in dnode 3 and 3 vgroups in node 1, now we want to move vgId 18 from dnode 3 to dnode 1. Execute below command in `taos` - -``` -taos> alter dnode 3 balance "vnode:18-dnode:1"; - -DB error: Balance already enabled (0.00755 -``` - -However, the operation fails with error message show above, which means automatic load balancing has been enabled in the current database so manual load balance can't be performed. - -Shutdown the cluster, configure `balance` parameter in all the dnodes to 0, then restart the cluster, and execute `alter dnode` and `show vgroups` as below. - -``` -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) -``` - -It can be seen from above output that vgId 18 has been moved from dndoe 3 to dnode 1. - -:::note - -- Manual load balancing can only be performed when the automatic load balancing is disabled, i.e. `balance` is set to 0 只. -- Only vnode in normal state, i.e. master or slave, can be moved. vnode can't moved when its in status offline, unsynced or syncing. -- Before moving a vnode, it's necessary to make sure the target dnode has enough resources: CPU, memory and disk. - -::: diff --git a/docs-en/10-cluster/03-ha-and-lb.md b/docs-en/10-cluster/03-ha-and-lb.md deleted file mode 100644 index 5ae76a0e8f75f45c33935056b5523ad8a528a8b9..0000000000000000000000000000000000000000 --- a/docs-en/10-cluster/03-ha-and-lb.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -sidebar_label: HA & LB -title: High Availability and Load Balancing ---- - -## High Availability of Vnode - -High availability of vnode and mnode can be achieved through replicas in TDengine. - -The number of vnodes is associated with each DB, there can be multiple DBs in a TDengine cluster. For the purpose of operation, different number of replicas can be configured properly for each DB. When creating a database, the parameter `replica` is used to specify the number of replicas, the default value is 1. With single replica, the reliability of the system can't be guaranteed. Whenever one node is down, data service would be unavailable. The number of dnodes in the cluster must NOT be lower than the number of replicas set for any DB, otherwise the `create table` operation would fail with error "more dnodes are needed". Below SQL statement is used to create a database named as "demo" with 3 replicas. - -```sql -CREATE DATABASE demo replica 3; -``` - -The data in a DB is divided into multiple shards and stored in multiple vgroups. The number of vnodes in each group is determined by the number of replicas set for the DB. The vnodes in each vgroups store exactly same data. For the purpose of high availability, the vnodes in a vgroup must be located in different dnodes on different hosts. As long as over half of the vnodes in a vgroup are in online state, the vgroup is able to serve data access. Otherwise the vgroup can't handle any data access for reading or inserting data. - -There may be data for multiple DBs in a dnode. Once a dnode is down, multiple DBs may be affected. However, it's hard to say the cluster is guaranteed to work properly as long as over half of dnodes are online because vnodes are introduced and there may be complex mapping between vnodes and dnodes. - -## High Availability of Mnode - -Each TDengine cluster is managed by `mnode`, which is a module of `taosd`. For the high availability of mnode, multiple mnodes can be configured using system parameter `numOfMNodes`, the valid time range is [1,3]. To make sure the data consistency between mnodes, the data replication between mnodes is performed in synchronous way. - -There may be multiple dnodes in a cluster, but only one mnode can be started in each dnode. Which one or ones of the dnodes will be designated as mnodes is automatically determined by TDengine according to the cluster configuration and system resources. Command `show mnodes` can be executed in TDengine `taos` to show the mnodes in the cluster. - -```sql -SHOW MNODES; -``` - -The end point and role/status (master, slave, unsynced, or offline) of all mnodes can be shown by the above command. When the first dnode is started in a cluster, there must be one mnode in this dnode, because there must be at least one mnode otherwise the cluster doesn't work. If `numOfMNodes` is configured to 2, another mnode will be started when the second dnode is launched. - -For the high availability of mnode, `numOfMnodes` needs to be configured to 2 or a higher value. Because the data consistency between mnodes must be guaranteed, the replica confirmation parameter `quorum` is set to 2 automatically if `numOfMNodes` is set to 2 or higher. - -:::note -If high availability is important for your system, both vnode and mnode must be configured to have multiple replicas. How to configure for them are different and have been described. - -::: - -## Load Balance - -Load balance will be triggered in 3 cades without manual intervention. - -- When a new dnode is joined in the cluster, automatic load balancing may be triggered, some data from some dnodes may be transferred to the new dnode automatically.当 -- When a dnode is removed from the cluster, the data from this dnode will be transferred to other dnodes automatically. -- When a dnode is too hot, i.e. too much data has been stored in it, automatic load balancing may be triggered to migrate some vnodes from this dnode to other dnodes. -- :::tip - Automatic load balancing is controlled by parameter `balance`, 0 means disabled and 1 means enabled. - -::: - -## Dnode Offline - -When a dnode is offline, it can be detected by the TDengine cluster. There are two cases: - -- The dnode becomes online again before the threshold configured in `offlineThreshold` is reached, it is still in the cluster and data replication is started automatically. The dnode can work properly after the data syncup is finished. - -- If the dnode has been offline over the threshold configured in `offlineThreshold` in `taos.cfg`, the dnode will be removed from the cluster automatically. System alert will be generated and automatic load balancing will be triggered too if `balance` is set to 1. When the removed dnode is restarted and becomes online, it will not be joined in the cluster automatically, it can only be joined manually by the system operator. - -:::note -If all the vnodes in a vgroup (or mnodes in mnode group) are in offline or unsynced status, the master node can only be voted after all the vnodes or mnodes in the group become online and can exchange status, then the vgroup (or mnode group) is able to provide service. - -::: - -## Arbitrator - -If the number of replicas is set to an even number like 2, when half of the vnodes in a vgroup don't work master node can't be voted. Similar case is also applicable to mnode if the number of mnodes is set to an even number like 2. - -To resolve this problem, a new arbitrator component named `tarbitrator`, abbreviated for TDengine Arbitrator, was introduced. Arbitrator simulates a vnode or mnode but it's only responsible for network communication and doesn't handle any actual data access. With Arbitrator, any vgroup or mnode group can be considered as having number of member nodes and master node can be selected. - -Normally, it's suggested to configure replica number of each DB or system parameter `numOfMNodes` to an odd number. However, if a user is very sensitive to storage space, replica number of 2 plus arbitrator component can be used to achieve both lower cost of storage space and high availability. - -Arbitrator component is installed with the server package. For details about how to install, please refer to [Install](/operation/pkg-install). The `-p` parameter of `tarbitrator` can be used to specify the port on which it provides service. - -In the configuration file `taos.cfg` of each dnode, parameter `arbitrator` needs to be configured to the end point of the `tarbitrator` process. arbitrator component will be used automatically if the replica is configured to an even number and will be ignored if the replica is configured to an odd number. - -Arbitrator can be shown by executing command in TDengine CLI `taos` with its role shown as "arb". - -```sql -SHOW DNODES; -``` diff --git a/docs-en/10-cluster/_category_.yml b/docs-en/10-cluster/_category_.yml deleted file mode 100644 index 2521c8a0368051f220accd45fb02308f89cf00dc..0000000000000000000000000000000000000000 --- a/docs-en/10-cluster/_category_.yml +++ /dev/null @@ -1,12 +0,0 @@ -label: Cluster -link: - type: generated-index - slug: /cluster/ - description: "TDengine can be deployed in cluster mode to increase the processing capability and high availability. In cluster mode, any data can have multiple replications for the purpose of high availability and load balance. TDengine cluster can be scaled out easily to support more data collecting points and more data." - keywords: - [ - cluster, - high availability, - load balance, - scale out - ] diff --git a/docs-en/12-taos-sql/01-data-type.md b/docs-en/12-taos-sql/01-data-type.md deleted file mode 100644 index ea09f8516cb76a02bcf6878ebdbf7910b00011da..0000000000000000000000000000000000000000 --- a/docs-en/12-taos-sql/01-data-type.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -sidebar_label: Data Types -title: Data Types -description: "The data types supported by TDengine include timestamp, float, JSON, etc" ---- - -When using TDengine to store and query data, the most important part of the data is timestamp. Timestamp must be specified when creating and inserting data rows or querying data, timestamp must follow below rules: - -- the format must be `YYYY-MM-DD HH:mm:ss.MS`, the default time precision is millisecond (ms), for example `2017-08-12 18:25:58.128` -- internal function `now` can be used to get the current timestamp of the client side -- the current timestamp of the client side is applied when `now` is used to insert data -- Epoch Time：timestamp can also be a long integer number, which means the number of seconds, milliseconds or nanoseconds, depending on the time precision, from 1970-01-01 00:00:00.000 (UTC/GMT) -- timestamp can be applied with add/substract operation, for example `now-2h` means 2 hours back from the time at which query is executed，the unit can be b(nanosecond), u(microsecond), a(millisecond), s(second), m(minute), h(hour), d(day), w(week.。 So `select * from t1 where ts > now-2w and ts <= now-1w` means the data between two weeks ago and one week ago. The time unit can also be n (calendar month) or y (calendar year) when specifying the time window for down sampling operation. - -Time precision in TDengine can be set by the `PRECISION` parameter when executing `CREATE DATABASE`, like below, the default time precision is millisecond. - -```sql -CREATE DATABASE db_name PRECISION 'ns'; -``` - -In TDengine, below data types can be used when specifying a column or tag. - -| # | **类型** | **Bytes** | **说明** | -| --- | :-------: | --------- | ------------------------- | -| 1 | TIMESTAMP | 8 | Default precision is millisecond, microsecond and nanosecond are also supported | -| 2 | INT | 4 | Integer, the value range is [-2^31+1, 2^31-1], while -2^31 is treated as NULL | -| 3 | BIGINT | 8 | Long integer, the value range is [-2^63+1, 2^63-1], while -2^63 is treated as NULL | -| 4 | FLOAT | 4 | Floating point number, the effective number of digits is 6-7, the value range is [-3.4E38, 3.4E38] | -| 5 | DOUBLE | 8 | double precision floating point number, the effective number of digits is 15-16, the value range is [-1.7E308, 1.7E308] | -| 6 | BINARY | User Defined | Single-byte string for ASCII visible characters. Length must be specified when defining a column or tag of binary type. The string length can be up to 16374 bytes. The string value must be quoted with single quotes. The literal single quote inside the string must be preceded with back slash like `\'` | -| 7 | SMALLINT | 2 | Short integer, the value range is [-32767, 32767], while -32768 is treated as NULL | -| 8 | TINYINT | 1 | Single-byte integer, the value range is [-127, 127], while -128 is treated as NLLL | -| 9 | BOOL | 1 | Bool, the value range is {true, false} | -| 10 | NCHAR | User Defined| Multiple-Byte string that can include like Chinese characters. Each character of NCHAR type consumes 4 bytes storage. The string value should be quoted with single quotes. Literal single quote inside the string must be preceded with backslash, like `\’`. The length must be specified when defining a column or tag of NCHAR type, for example nchar(10) means it can store at most 10 characters of nchar type and will consume fixed storage of 40 bytes. Error will be reported the string value exceeds the length defined. | -| 11 | JSON | | json type can only be used on tag, a tag of json type is excluded with any other tags of any other type | - -:::tip -TDengine is case insensitive and treats any characters in the sql command as lower case by default, case sensitive strings must be quoted with single quotes. - -::: - -:::note -Only ASCII visible characters are suggested to be used in a column or tag of BINARY type. Multiple-byte characters must be stored in NCHAR type. - -::: - -:::note -Numeric values in SQL statements will be determined as integer or float type according to whether there is decimal point or whether scientific notation is used, so attention must be paid to avoid overflow. For example, 9999999999999999999 will be considered as overflow because it exceeds the upper limit of long integer, but 9999999999999999999.0 will be considered as a legal float number. - -::: diff --git a/docs-en/12-taos-sql/02-database.md b/docs-en/12-taos-sql/02-database.md deleted file mode 100644 index 21cef3380cb161a10436df6f2bef679d2ee4aad8..0000000000000000000000000000000000000000 --- a/docs-en/12-taos-sql/02-database.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -sidebar_label: Database -title: Database -description: "create and drop database, show or change database parameters" ---- - -## Create Datable - -``` -CREATE DATABASE [IF NOT EXISTS] db_name [KEEP keep] [DAYS days] [UPDATE 1]; -``` - -:::info - -1. KEEP specifies the number of days for which the data in the database to be created will be kept, the default value is 3650 days, i.e. 10 years. The data will be deleted automatically once its age exceeds this threshold. -2. UPDATE specifies whether the data can be updated and how the data can be updated. - 1. UPDATE set to 0 means update operation is not allowed, the data with an existing timestamp will be dropped silently. - 2. UPDATE set to 1 means the whole row will be updated, the columns for which no value is specified will be set to NULL - 3. UPDATE set to 2 means updating a part of columns for a row is allowed, the columns for which no value is specified will be kept as no change -3. The maximum length of database name is 33 bytes. -4. The maximum length of a SQL statement is 65,480 bytes. -5. For more parameters that can be used when creating a database, like cache, blocks, days, keep, minRows, maxRows, wal, fsync, update, cacheLast, replica, quorum, maxVgroupsPerDb, ctime, comp, prec, Please refer to [Configuration Parameters](/reference/config/). - -::: - -## Show Current Configuration - -``` -SHOW VARIABLES; -``` - -## Specify The Database In Use - -``` -USE db_name; -``` - -:::note -This way is not applicable when using a REST connection - -::: - -## Drop Database - -``` -DROP DATABASE [IF EXISTS] db_name; -``` - -:::note -All data in the database will be deleted too. This command must be used with caution. - -::: - -## Change Database Configuration - -Some examples are shown below to demonstrate how to change the configuration of a database. Please be noted that some configuration parameters can be changed after the database is created, but some others can't, for details of the configuration parameters of database please refer to [Configuration Parameters](/reference/config/). - -``` -ALTER DATABASE db_name COMP 2; -``` - -COMP parameter specifies whether the data is compressed and how the data is compressed. - -``` -ALTER DATABASE db_name REPLICA 2; -``` - -REPLICA parameter specifies the number of replications of the database. - -``` -ALTER DATABASE db_name KEEP 365; -``` - -KEEP parameter specifies the number of days for which the data will be kept. - -``` -ALTER DATABASE db_name QUORUM 2; -``` - -QUORUM parameter specifies the necessary number of confirmations to determine whether the data is written successfully. - -``` -ALTER DATABASE db_name BLOCKS 100; -``` - -BLOCKS parameter specifies the number of memory blocks used by each VNODE. - -``` -ALTER DATABASE db_name CACHELAST 0; -``` - -CACHELAST parameter specifies whether and how the latest data of a sub table is cached. - -:::tip -The above parameters can be changed using `ALTER DATABASE` command without restarting. For more details of all configuration parameters please refer to [Configuration Parameters](/reference/config/). - -::: - -## Show All Databases - -``` -SHOW DATABASES; -``` - -## Show The Create Statement of A Database - -``` -SHOW CREATE DATABASE db_name; -``` - -This command is useful when migrating the data from one TDengine cluster to another one. Firstly this command can be used to get the CREATE statement, which in turn can be used in another TDengine to create an exactly same database. diff --git a/docs-en/12-taos-sql/03-table.md b/docs-en/12-taos-sql/03-table.md deleted file mode 100644 index b2e09929077b7222ade0656c432ce8c5f8b02d16..0000000000000000000000000000000000000000 --- a/docs-en/12-taos-sql/03-table.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -sidebar_label: Table -title: Table -description: create super table, normal table and sub table, drop tables and change tables ---- - -## Create Table - -``` -CREATE TABLE [IF NOT EXISTS] tb_name (timestamp_field_name TIMESTAMP, field1_name data_type1 [, field2_name data_type2 ...]); -``` - -:::info - -1. The first column of a table must be in TIMESTAMP type, and it will be set as primary key automatically -2. The maximum length of table name is 192 bytes. -3. The maximum length of each row is 16k bytes, please be notes that the extra 2 bytes used by each BINARY/NCHAR column are also counted in. -4. The name of sub-table can only be consisted of English characters, digits and underscore, and can't be started with digit. Table names are case insensitive. -5. The maximum length in bytes must be specified when using BINARY or NCHAR type. -6. Escape character "\`" can be used to avoid the conflict between table names and reserved keywords, above rules will be bypassed when using escape character on table names, but the upper limit for name length is still valid. The table names specified using escape character are case sensitive. Only ASCII visible characters can be used with escape character. - For example \`aBc\` and \`abc\` are different table names but `abc` and `aBc` are same table names because they are both converted to `abc` internally. - -::: - -### Create Table Using STable As Template - -``` -CREATE TABLE [IF NOT EXISTS] tb_name USING stb_name TAGS (tag_value1, ...); -``` - -The above command creates a sub table using the specified super table as template and the specified tab values. - -### Create Table Using STable As Template With A Part of Tags - -``` -CREATE TABLE [IF NOT EXISTS] tb_name USING stb_name (tag_name1, ...) TAGS (tag_value1, ...); -``` - -The tags for which no value is specified will be set to NULL. - -### Create Tables in Batch - -``` -CREATE TABLE [IF NOT EXISTS] tb_name1 USING stb_name TAGS (tag_value1, ...) [IF NOT EXISTS] tb_name2 USING stb_name TAGS (tag_value2, ...) ...; -``` - -This way can be used to create a lot of tables in a single SQL statement to accelerate the speed of the creating tables. - -:::info - -- Creating tables in batch must use super table as template. -- The length of single statement is suggested to be between 1,000 and 3,000 bytes for best performance. - -::: - -## Drop Tables - -``` -DROP TABLE [IF EXISTS] tb_name; -``` - -## Show All Tables In Current Database - -``` -SHOW TABLES [LIKE tb_name_wildcar]; -``` - -## Show Create Statement of A Table - -``` -SHOW CREATE TABLE tb_name; -``` - -This way is useful when migrating the data in one TDengine cluster to another one because it can be used to create exactly same tables in the target database. - -## Show Table Definition - -``` -DESCRIBE tb_name; -``` - -## Change Table Definition - -### Add A Column - -``` -ALTER TABLE tb_name ADD COLUMN field_name data_type; -``` - -:::info - -1. The maximum number of columns is 4096, the minimum number of columns is 2. -2. The maximum length of column name is 64 bytes. - -::: - -### Remove A Column - -``` -ALTER TABLE tb_name DROP COLUMN field_name; -``` - -:::note -If a table is created using a super table as template, the table definition can only be changed on the corresponding super table, but the change will be automatically applied to all the sub tables created using this super table as template. For tables created in normal way, the table definition can be changed directly on the table. - -::: - -### Change Column Length - -``` -ALTER TABLE tb_name MODIFY COLUMN field_name data_type(length); -``` - -The the type of a column is variable length, like BINARY or NCHAR, this way can be used to change (or increase) the length of the column. - -:::note -If a table is created using a super table as template, the table definition can only be changed on the corresponding super table, but the change will be automatically applied to all the sub tables created using this super table as template. For tables created in normal way, the table definition can be changed directly on the table. - -::: - -### Change Tag Value Of Sub Table - -``` -ALTER TABLE tb_name SET TAG tag_name=new_tag_value; -``` - -This command can be used to change the tag value if the table is created using a super table as template. diff --git a/docs-en/12-taos-sql/04-stable.md b/docs-en/12-taos-sql/04-stable.md deleted file mode 100644 index 8d763ac22f0c64ff898036653c1fd58c6df00298..0000000000000000000000000000000000000000 --- a/docs-en/12-taos-sql/04-stable.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -sidebar_label: STable -title: Super Table ---- - -:::note - -Keyword `STable`, abbreviated for super table, is supported since version 2.0.15. - -::: - -## Crate STable - -``` -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]); -``` - -The SQL statement of creating STable is similar to that of creating table, but a special column named as `TAGS` must be specified with the names and types of the tags. - -:::info - -1. The tag types specified in TAGS should NOT be timestamp. Since 2.1.3.0 timestamp type can be used in TAGS column, but its value must be fixed and arithmetic operation can't be applied on it. -2. The tag names specified in TAGS should NOT be same as other columns. -3. The tag names specified in TAGS should NOT be same as any reserved keywords.(Please refer to [keywords](/taos-sql/keywords/) -4. The maximum number of tags specified in TAGS is 128, but there must be at least one tag, and the total length of all tag columns should NOT exceed 16KB. - -::: - -## Drop STable - -``` -DROP STable [IF EXISTS] stb_name; -``` - -All the sub-tables created using the deleted STable will be deleted automatically. - -## Show All STables - -``` -SHOW STableS [LIKE tb_name_wildcard]; -``` - -This command can be used to display the information of all STables in the current database, including name, creation time, number of columns, number of tags, number of tables created using this STable. - -## Show The Create Statement of A STable - -``` -SHOW CREATE STable stb_name; -``` - -This command is useful in migrating data from one TDengine cluster to another one because it can be used to create an exactly same STable in the target database. - -## Get STable Definition - -``` -DESCRIBE stb_name; -``` - -## Change Columns Of STable - -### Add A Column - -``` -ALTER STable stb_name ADD COLUMN field_name data_type; -``` - -### Remove A Column - -``` -ALTER STable stb_name DROP COLUMN field_name; -``` - -### Change Column Length - -``` -ALTER STable stb_name MODIFY COLUMN field_name data_type(length); -``` - -This command can be used to change (or incerase, more specifically) the length of a column of variable length types, like BINARY or NCHAR. - -## Change Tags of A STable - -### Add A Tag - -``` -ALTER STable stb_name ADD TAG new_tag_name tag_type; -``` - -This command is used to add a new tag for a STable and specify the tag type. - -### Remove A Tag - -``` -ALTER STable stb_name DROP TAG tag_name; -``` - -The tag will be removed automatically from all the sub tables crated using the super table as template once a tag is removed from a super table. - -### Change A Tag - -``` -ALTER STable stb_name CHANGE TAG old_tag_name new_tag_name; -``` - -The tag name will be changed automatically from all the sub tables crated using the super table as template once a tag name is changed for a super table. - -### Change Tag Length - -``` -ALTER STable stb_name MODIFY TAG tag_name data_type(length); -``` - -This command can be used to change (or incerase, more specifically) the length of a tag of variable length types, like BINARY or NCHAR. - -:::note -Changing tag value can be applied to only sub tables. All other tag operations, like add tag, remove tag, however, can be applied to only STable. If a new tag is added for a STable, the tag will be added with NULL value for all its sub tables. - -::: diff --git a/docs-en/12-taos-sql/05-insert.md b/docs-en/12-taos-sql/05-insert.md deleted file mode 100644 index 36af96160b805b0221a95a318c9c6f7d6537d8aa..0000000000000000000000000000000000000000 --- a/docs-en/12-taos-sql/05-insert.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -sidebar_label: Insert -title: Insert ---- - -## Syntax - -```sql -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 - ...]; -``` - -## Insert Single or Multiple Rows - -Single row or multiple rows specified with VALUES can be inserted into a specific table. For example - -Single row is inserted using below statement. - -```sq; -INSERT INTO d1001 VALUES (NOW, 10.2, 219, 0.32); -``` - -Double rows can be inserted using below statement. - -```sql -INSERT INTO d1001 VALUES ('2021-07-13 14:06:32.272', 10.2, 219, 0.32) (1626164208000, 10.15, 217, 0.33); -``` - -:::note - -1. In the second example above, different formats are used in the two rows to be inserted. In the first row, the timestamp format is a date and time string, which is interpreted from the string value only. In the second row, the timestamp format is a long integer, which will be interpreted based on the database time precision. -2. When trying to insert multiple rows in single statement, only the timestamp of one row can be set as NOW, otherwise there will be duplicate timestamps among the rows and the result may be out of expectation because NOW will be interpreted as the time when the statement is executed. -3. The oldest timestamp that is allowed is subtracting the KEEP parameter from current time. -4. The newest timestamp that is allowed is adding the DAYS parameter to current time. - -::: - -## Insert Into Specific Columns - -Data can be inserted into specific columns, either single row or multiple row, while other columns will be inserted as NULL value. - -``` -INSERT INTO d1001 (ts, current, phase) VALUES ('2021-07-13 14:06:33.196', 10.27, 0.31); -``` - -:::info -If no columns are explicitly specified, all the columns must be provided with values, this is called "all column mode". The insert performance of all column mode is much better than specifying a part of columns, so it's encouraged to use "all column mode" while providing NULL value explicitly for the columns for which no actual value can be provided. - -::: - -## Insert Into Multiple Tables - -One or multiple rows can be inserted into multiple tables in single SQL statement, with or without specifying specific columns. - -```sql -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）; -``` - -## Automatically Create Table When Inserting - -If it's not sure whether the table already exists, the table can be created automatically while inserting using below SQL statement. To use this functionality, a STable must be used as template and tag values must be provided. - -```sql -INSERT INTO d21001 USING meters TAGS ('Beijing.Chaoyang', 2) VALUES ('2021-07-13 14:06:32.272', 10.2, 219, 0.32); -``` - -It's not necessary to provide values for all tag when creating tables automatically, the tags without values provided will be set to NULL. - -```sql -INSERT INTO d21001 USING meters (groupId) TAGS (2) VALUES ('2021-07-13 14:06:33.196', 10.15, 217, 0.33); -``` - -Multiple rows can also be inserted into same table in single SQL statement using this way.自 - -```sql -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 -Prior to version 2.0.20.5, when using `INSERT` to create table automatically and specify the columns, the column names must follow the table name immediately. From version 2.0.20.5, the column names can follow the table name immediately, also can be put between `TAGS` and `VALUES`. In same SQL statement, however, these two ways of specifying column names can't be mixed. -::: - -## Insert Rows From A File - -Besides using `VALUES` to insert one or multiple rows, the data to be inserted can also be prepared in a CSV file with comma as separator and each field value quoted by single quotes. Table definition is not required in the CSV file. For example, if file "/tmp/csvfile.csv" contains below data: - -``` -'2021-07-13 14:07:34.630', '10.2', '219', '0.32' -'2021-07-13 14:07:35.779', '10.15', '217', '0.33' -``` - -Then data in this file can be inserted by below SQL statement: - -```sql -INSERT INTO d1001 FILE '/tmp/csvfile.csv'; -``` - -## CreateTables Automatically and Insert Rows From File - -From version 2.1.5.0, tables can be automatically created using a super table as template when inserting data from a CSV file, Like below: - -```sql -INSERT INTO d21001 USING meters TAGS ('Beijing.Chaoyang', 2) FILE '/tmp/csvfile.csv'; -``` - -Multiple tables can be automatically created and inserted in single SQL statement, like below:也 - -```sql -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'; -``` - -## More About Insert - -For SQL statement like `insert`, stream parsing strategy is applied. That means before an error is found and the execution is aborted, the part prior to the error point has already been executed. Below is an experiment to help understand the behavior. - -Firstly, a super table is created. - -```sql -CREATE TABLE meters(ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS(location BINARY(30), groupId INT); -``` - -It can be proved that the super table has been created by `SHOW STableS`, but no table exists by `SHOW TABLES`. - -``` -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) -``` - -Then, try to create table d1001 automatically when inserting data into it. - -```sql -INSERT INTO d1001 USING meters TAGS('Beijing.Chaoyang', 2) VALUES('a'); -``` - -The output shows the value to be inserted is invalid. But `SHOW TABLES` proves that the table has been created automatically by the `INSERT` statement. - -``` -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) -``` - -From the above experiment, we can see that even though the value to be inserted is invalid but the table is still created. diff --git a/docs-en/12-taos-sql/06-select.md b/docs-en/12-taos-sql/06-select.md deleted file mode 100644 index f28c8dc2e641fd7be95a4199dad8981e5fbe68e3..0000000000000000000000000000000000000000 --- a/docs-en/12-taos-sql/06-select.md +++ /dev/null @@ -1,450 +0,0 @@ ---- -sidebar_label: Select -title: Select ---- - -## Syntax - -```SQL -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]; -``` - -## Wildcard - -Wilcard \* can be used to specify all columns. The result includes only data columns for normal tables. - -``` -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) -``` - -The result includes both data columns and tag columns for super table. - -``` -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) -``` - -Wildcard can be used with table name as prefix, both below SQL statements have same effects and return all columns. - -```SQL -SELECT * FROM d1001; -SELECT d1001.* FROM d1001; -``` - -In JOIN query, however, with or without table name prefix will return different results. \* without table prefix will return all the columns of both tables, but \* with table name as prefix will return only the columns of that table. - -``` -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) -``` - -Wilcard \* can be used with some functions, but the result may be different depending on the function being used. For example, `count(*)` returns only one column, i.e. the number of rows; `first`, `last` and `last_row` return all columns of the selected 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) -``` - -## Tags - -Starting from version 2.0.14, tag columns can be selected together with data columns when querying sub tables. Please be noted that, however, wildcard \* doesn't represent any tag column, that means tag columns must be specified explicitly like below example. - -``` -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) -``` - -## Get distinct values - -`DISTINCT` keyword can be used to get all the unique values of tag columns from a super table, it can also be used to get all the unique values of data columns from a table or sub table. - -```sql -SELECT DISTINCT tag_name [, tag_name ...] FROM stb_name; -SELECT DISTINCT col_name [, col_name ...] FROM tb_name; -``` - -:::info - -1. Configuration parameter `maxNumOfDistinctRes` in `taos.cfg` is used to control the number of rows to output. The minimum configurable value is 100,000, the maximum configurable value is 100,000,000, the default value is 1000,000. If the actual number of rows exceeds the value of this parameter, only the number of rows specified by this parameter will be output. -2. It can't be guaranteed that the results selected by using `DISTINCT` on columns of `FLOAT` or `DOUBLE` are exactly unique because of the precision nature of floating numbers. -3. `DISTINCT` can't be used in the sub-query of a nested query statement, and can't be used together with aggregate functions, `GROUP BY` or `JOIN` in same SQL statement. - -::: - -## Columns Names of Result Set - -When using `SELECT`, the column names in the result set will be same as that in the select clause if `AS` is not used. `AS` can be used to rename the column names in the result set. For example - -``` -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) -``` - -`AS` can't be used together with `first(*)`, `last(*)`, or `last_row(*)`. - -## Implicit Columns - -`Select_exprs` can be column names of a table, or function expression or arithmetic expression on columns. The maximum number of allowed column names and expressions is 256. Timestamp and the corresponding tag names will be returned in the result set if `interval` or `group by tags` are used, and timestamp will always be the first column in the result set. - -## Table List - -`FROM` can be followed by a number of tables or super tables, or can be followed by a sub-query. If no database is specified as current database in use, table names must be preceded with database name, like `power.d1001`. - -```SQL -SELECT * FROM power.d1001; -``` - -has same effect as - -```SQL -USE power; -SELECT * FROM d1001; -``` - -## Special Query - -Some special query functionalities can be performed without `FORM` sub-clause. For example, below statement can be used to get the current database in use. - -``` -taos> SELECT DATABASE(); - database() | -================================= - power | -Query OK, 1 row(s) in set (0.000079s) -``` - -If no database is specified upon logging in and no database is specified with `USE` after login, NULL will be returned by `select database()`. - -``` -taos> SELECT DATABASE(); - database() | -================================= - NULL | -Query OK, 1 row(s) in set (0.000184s) -``` - -Below statement can be used to get the version of client or server. - -``` -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) -``` - -Below statement is used to check the server status. One integer, like `1`, is returned if the server status is OK, otherwise an error code is returned. This way is compatible with the status check for TDengine from connection pool or 3rd party tools, and can avoid the problem of losing connection from connection pool when using wrong heartbeat checking SQL statement. - -``` -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 - -**Description**: Get the data block distribution of a table or STable. - -```SQL title="Syntax" -SELECT _block_dist() FROM { tb_name | stb_name } -``` - -**Restrictions**：No argument is allowed, where clause is not allowed - -**Sub Query**：Sub query or nested query are not supported - -**Return value**: A string which includes the data block distribution of the specified table or STable, i.e. the histogram of rows stored in the data blocks of the table or STable. - -```text title="Result" -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)] -``` - -**More explanation about above example**: - -- Histogram about the rows stored in the data blocks of the table or STable: the value of rows for 5%, 10%, 20%, 30%, 40%, 50%, 60%, 70%, 80%, 90%, 95%, and 99% -- Minimum number of rows stored in a data block, i.e. Min=[392(Rows)] -- Maximum number of rows stored in a data block, i.e. Max=[800(Rows)] -- Average number of rows stored in a data block, i.e. Avg=[666(Rows)] -- stddev of number of rows, i.e. Stddev=[2.17] -- Total number of rows, i.e. Rows[2000] -- Total number of data blocks, i.e. Blocks=[3] -- Total disk size consumed, i.e. Size=[5.440(Kb)] -- Compression ratio, which means the compressed size divided by original size, i.e. Comp=[0.23] -- Total number of rows in memory, i.e. RowsInMem=[0], which means no rows in memory -- The time spent on reading head file (to retrieve data block information), i.e. SeekHeaderTime=[1(us)], which means 1 microsecond. - -## Special Keywords in TAOS SQL - -- `TBNAME`： it is treated as a special tag when selecting on a super table, representing the name of sub-tables in that super table. -- `_c0`: represents the first column of a table or super table. - -## Tips - -To get all the sub tables and corresponding tag values from a super table: - -```SQL -SELECT TBNAME, location FROM meters; -``` - -To get the number of sub tables in a super table： - -```SQL -SELECT COUNT(TBNAME) FROM meters; -``` - -Only filter on `TAGS` are allowed in the `where` clause for above two query statements. For example: - -``` -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) -``` - -- Wildcard \* can be used to get all columns, or specific column names can be specified. Arithmetic operation can be performed on columns of number types, columns can be renamed in the result set. -- Arithmetic operation on columns can't be used in where clause. For example, `where a*2>6;` is not allowed but `where a>6/2;` can be used instead for same purpose. -- Arithmetic operation on columns can't be used as the objectives of select statement. For example, `select min(2*a) from t;` is not allowed but `select 2*min(a) from t;` can be used instead. -- Logical operation can be used in `WHERE` clause to filter numeric values, wildcard can be used to filter string values. -- Result set are arranged in ascending order of the first column, i.e. timestamp, but it can be controlled to output as descending order of timestamp. If `order by` is used on other columns, the result may be not as expected. By the way, \_c0 is used to represent the first column, i.e. timestamp. -- `LIMIT` parameter is used to control the number of rows to output. `OFFSET` parameter is used to specify from which row to output. `LIMIT` and `OFFSET` are executed after `ORDER BY` in the query execution. A simple tip is that `LIMIT 5 OFFSET 2` can be abbreviated as `LIMIT 2, 5`. -- What is controlled by `LIMIT` is the number of rows in each group when `GROUP BY` is used. -- `SLIMIT` parameter is used to control the number of groups when `GROUP BY` is used. Similar to `LIMIT`, `SLIMIT 5 OFFSET 2` can be abbreviated as `SLIMIT 2, 5`. -- ">>" can be used to output the result set of `select` statement to the specified file. - -## Where - -Logical operations in below table can be used in `where` clause to filter the resulting rows. - -| **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`** | - -**使用说明**: - -- Operator `<\>` is equal to `!=`, please be noted that this operator can't be used on the first column of any table, i.e.timestamp column. -- Operator `like` is used together with wildcards to match strings - - '%' matches 0 or any number of characters, '\_' matches any single ASCII character. - - `\_` is used to match the \_ in the string. - - The maximum length of wildcard string is 100 bytes from version 2.1.6.1 (before that the maximum length is 20 bytes). `maxWildCardsLength` in `taos.cfg` can be used to control this threshold. Too long wildcard string may slowdown the execution performance of `LIKE` operator. -- `AND` keyword can be used to filter multiple columns simultaneously. AND/OR operation can be performed on single or multiple columns from version 2.3.0.0. However, before 2.3.0.0 `OR` can't be used on multiple columns. -- For timestamp column, only one condition can be used; for other columns or tags, `OR` keyword can be used to combine multiple logical operators. For example, `((value > 20 AND value < 30) OR (value < 12))`. - - From version 2.3.0.0, multiple conditions can be used on timestamp column, but the result set can only contain single time range. -- From version 2.0.17.0, operator `BETWEEN AND` can be used in where clause, for example `WHERE col2 BETWEEN 1.5 AND 3.25` means the filter condition is equal to "1.5 ≤ col2 ≤ 3.25". -- From version 2.1.4.0, operator `IN` can be used in where clause. For example, `WHERE city IN ('Beijing', 'Shanghai')`. For bool type, both `{true, false}` and `{0, 1}` are allowed, but integers other than 0 or 1 are not allowed. FLOAT and DOUBLE types are impacted by floating precision, only values that match the condition within the tolerance will be selected. Non-primary key column of timestamp type can be used with `IN`. -- From version 2.3.0.0, regular expression is supported in where clause with keyword `match` or `nmatch`, the regular expression is case insensitive. - -## Regular Expression - -### Syntax - -```SQL -WHERE (column|tbname) **match/MATCH/nmatch/NMATCH** _regex_ -``` - -### Specification - -The regular expression being used must be compliant with POSIX specification, please refer to [Regular Expressions](https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html). - -### Restrictions - -Regular expression can be used against only table names, i.e. `tbname`, and tags of binary/nchar types, but can't be used against data columns. - -The maximum length of regular expression string is 128 bytes. Configuration parameter `maxRegexStringLen` can be used to set the maximum allowed regular expression. It's a configuration parameter on client side, and will take in effect after restarting the client. - -## JOIN - -From version 2.2.0.0, inner join is fully supported in TDengine. More specifically, the inner join between table and table, that between STable and STable, and that between sub query and sub query are supported. - -Only primary key, i.e. timestamp, can be used in the join operation between table and table. For example: - -```sql -SELECT * -FROM temp_tb_1 t1, pressure_tb_1 t2 -WHERE t1.ts = t2.ts -``` - -In the join operation between STable and STable, besides the primary key, i.e. timestamp, tags can also be used. For example: - -```sql -SELECT * -FROM temp_STable t1, temp_STable t2 -WHERE t1.ts = t2.ts AND t1.deviceid = t2.deviceid AND t1.status=0; -``` - -Similary, join operation can be performed on the result set of multiple sub queries. - -:::note -Restrictions on join operation: - -- The number of tables or STables in single join operation can't exceed 10. -- `FILL` is not allowed in the query statement that includes JOIN operation. -- Arithmetic operation is not allowed on the result set of join operation. -- `GROUP BY` is not allowed on a part of tables that participate in join operation. -- `OR` can't be used in the conditions for join operation -- join operation can't be performed on data columns, i.e. can only be performed on tags or primary key, i.e. timestamp - -::: - -## Nested Query - -Nested query is also called sub query, that means in a single SQL statement the result of inner query can be used as the data source of the outer query. - -From 2.2.0.0, unassociated sub query can be used in the `FROM` clause. unassociated means the sub query doesn't use the parameters in the parent query. More specifically, in the `tb_name_list` of `SELECT` statement, an independent SELECT statement can be used. So a complete nested query looks like: - -```SQL -SELECT ... FROM (SELECT ... FROM ...) ...; -``` - -:::info - -- Only one layer of nesting is allowed, that means no sub query is allowed in a sub query -- The result set returned by the inner query will be used as a "virtual table" by the outer query, the "virtual table" can be renamed using `AS` keyword for easy reference in the outer query. -- Sub query is not allowed in continuous query. -- JOIN operation is allowed between tables/STables inside both inner and outer queries. Join operation can be performed on the result set of the inner query. -- UNION operation is not allowed in either inner query or outer query. -- The functionalities that can be used in the inner query is same as non-nested query. - - `ORDER BY` inside the inner query doesn't make any sense but will slow down the query performance significantly, so please avoid such usage. -- Compared to the non-nested query, the functionalities that can be used in the outer query have such restrictions as: - - Functions - - If the result set returned by the inner query doesn't contain timestamp column, then functions relying on timestamp can't be used in the outer query, like `TOP`, `BOTTOM`, `FIRST`, `LAST`, `DIFF`. - - Functions that need to scan the data twice can't be used in the outer query, like `STDDEV`, `PERCENTILE`. - - `IN` operator is not allowed in the outer query but can be used in the inner query. - - `GROUP BY` is not supported in the outer query. - -::: - -## UNION ALL - -```SQL title=Syntax -SELECT ... -UNION ALL SELECT ... -[UNION ALL SELECT ...] -``` - -`UNION ALL` operator can be used to combine the result set from multiple select statements as long as the result set of these select statements have exactly same columns. `UNION ALL` doesn't remove redundant rows from multiple result sets. In single SQL statement, at most 100 `UNION ALL` can be supported. - -### Examples - -table `tb1` is created using below SQL statement: - -```SQL -CREATE TABLE tb1 (ts TIMESTAMP, col1 INT, col2 FLOAT, col3 BINARY(50)); -``` - -The rows in the past one hour in `tb1` can be selected using below SQL statement: - -```SQL -SELECT * FROM tb1 WHERE ts >= NOW - 1h; -``` - -The rows between 2018-06-01 08:00:00.000 and 2018-06-02 08:00:00.000 and col3 ends with 'nny' can be selected in the descending order of timestamp using below SQL statement: - -```SQL -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; -``` - -The sum of col1 and col2 for rows later than 2018-06-01 08:00:00.000 and whose col2 is bigger than 1.2 can be selected and renamed as "complex", while only 10 rows are output from the 5th row, by below SQL statement: - -```SQL -SELECT (col1 + col2) AS 'complex' FROM tb1 WHERE ts > '2018-06-01 08:00:00.000' AND col2 > 1.2 LIMIT 10 OFFSET 5; -``` - -The rows in the past 10 minutes and whose col2 is bigger than 3.14 are selected and output to the result file `/home/testoutpu.csv` with below SQL statement: - -```SQL -SELECT COUNT(*) FROM tb1 WHERE ts >= NOW - 10m AND col2 > 3.14 >> /home/testoutpu.csv; -``` diff --git a/docs-en/12-taos-sql/07-function.md b/docs-en/12-taos-sql/07-function.md deleted file mode 100644 index 1badb5915e01c172e7dccde686c652a6288ee69b..0000000000000000000000000000000000000000 --- a/docs-en/12-taos-sql/07-function.md +++ /dev/null @@ -1,1869 +0,0 @@ ---- -sidebar_label: Functions -title: Functions ---- - -## Aggregate Functions - -Aggregate query is supported in TDengine by following aggregate functions and selection functions. - -### COUNT - -``` -SELECT COUNT([*|field_name]) FROM tb_name [WHERE clause]; -``` - -**Description**:Get the number of rows or the number of non-null values in a table or a super table. - -**Return value type**:Long integer INT64 - -**Applicable column types**:All - -**Applicable table types**: table, super table, sub table - -**More explanation**: - -- Wildcard (\*) can be used to represent all columns, it's used to get the number of all rows -- The number of non-NULL values will be returned if this function is used on a specific column - -**Examples**: - -``` -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]; -``` - -**Description**:Get the average value of a column in a table or STable - -**Return value type**:Double precision floating number - -**Applicable column types**:Data types except for timestamp, binary, nchar and bool - -**Applicable table types**:table, STable - -**Examples**: - -``` -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; -``` - -**Description**:Time weighted average on a specific column within a time range - -**Return value type**:Double precision floating number - -**Applicable column types**:Data types except for timestamp, binary, nchar and bool - -**Applicable table types**:table, STable - -**More explanations**: - -- From version 2.1.3.0, function TWA can be used on stble with `GROUP BY`, i.e. timelines generated by `GROUP BY tbname` on a STable. - -### IRATE - -``` -SELECT IRATE(field_name) FROM tb_name WHERE clause; -``` - -**Description**:instantaneous rate on a specific column. The last two samples in the specified time range are used to calculate instantaneous rate. If the last sample value is smaller, then only the last sample value is used instead of the difference between the last two sample values. - -**Return value type**:Double precision floating number - -**Applicable column types**:Data types except for timestamp, binary, nchar and bool - -**Applicable table types**:table, STable - -**More explanations**: - -- From version 2.1.3.0, function IRATE can be used on stble with `GROUP BY`, i.e. timelines generated by `GROUP BY tbname` on a STable. - -### SUM - -``` -SELECT SUM(field_name) FROM tb_name [WHERE clause]; -``` - -**Description**:The sum of a specific column in a table or STable - -**Return value type**:Double precision floating number or long integer - -**Applicable column types**:Data types except for timestamp, binary, nchar and bool - -**Applicable table types**:table, STable - -**Examples**: - -``` -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]; -``` - -**Description**:Standard deviation of a specific column in a table or STable - -**Return value type**:Double precision floating number - -**Applicable column types**:Data types except for timestamp, binary, nchar and bool - -**Applicable table types**:table, STable (starting from version 2.0.15.1) - -**Examples**: - -``` -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]; -``` - -**Description**:统计表中某列的值是主键（时间戳）的拟合直线方程.start_val 是自变量初始值,step_val 是自变量的步长值. - -**Return value type**:A string in the format of "(slope, intercept)" - -**Applicable column types**:Data types except for timestamp, binary, nchar and bool - -**Applicable table types**:table only - -**Examples**: - -``` -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) -``` - -### MODE - -``` -SELECT MODE(field_name) FROM tb_name [WHERE clause]; -``` - -**Description**:The value which has the highest frequency of occurrence. NULL is returned if there are multiple values which have highest frequency of occurrence. It can't be used on timestamp column or tags. - -**Return value type**:Same as the data type of the column being operated - -**Applicable column types**:Data types except for timestamp - -**More explanations**:Considering the number of returned result set is unpredictable, it's suggested to limit the number of unique values to 100,000, otherwise error will be returned. - -**Applicable version**:From version 2.6.0.0 - -**Examples**: - -``` -taos> select voltage from d002; - voltage | -======================== - 1 | - 1 | - 2 | - 19 | -Query OK, 4 row(s) in set (0.003545s) - -taos> select mode(voltage) from d002; - mode(voltage) | -======================== - 1 | -Query OK, 1 row(s) in set (0.019393s) -``` - -### HYPERLOGLOG - -``` -SELECT HYPERLOGLOG(field_name) FROM { tb_name | stb_name } [WHERE clause]; -``` - -**Description**:The cardinal number of a specific column is returned by using hyperloglog algorithm. - -**Return value type**:Integer - -**Applicable column types**:Any data type - -**More explanations**: The benefit of using hyperloglog algorithm is that the memory usage is under control when the data volume is huge. However, when the data volume is very small, the result may be not accurate, it's recommented to use `select count(data) from (select unique(col) as data from table)` in this case. - -**Applicable versions**:From version 2.6.0.0 - -**Examples**: - -``` -taos> select dbig from shll; - dbig | -======================== - 1 | - 1 | - 1 | - NULL | - 2 | - 19 | - NULL | - 9 | -Query OK, 8 row(s) in set (0.003755s) - -taos> select hyperloglog(dbig) from shll; - hyperloglog(dbig)| -======================== - 4 | -Query OK, 1 row(s) in set (0.008388s) -``` - -## Selection Functions - -When any selective function is used, timestamp column or tag columns including `tbname` can be specified to show that the selected value are from which rows. - -### MIN - -``` -SELECT MIN(field_name) FROM {tb_name | stb_name} [WHERE clause]; -``` - -**Description**:The minimum value of a specific column in a table or STable - -**Return value type**:Same as the data type of the column being operated - -**Applicable column types**:Data types except for timestamp, binary, nchar and bool - -**Applicable table types**:table, STable - -**Examples**: - -``` -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]; -``` - -**Description**:The maximum value of a specific column of a table or STable - -**Return value type**:Same as the data type of the column being operated - -**Applicable column types**:Data types except for timestamp, binary, nchar and bool - -**Applicable table types**:table, STable - -**Examples**: - -``` -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]; -``` - -**Description**:The first non-null value of a specific column in a table or STable - -**Return value type**:Same as the column being operated - -**Applicable column types**:Any data type - -**Applicable table types**:table, STable - -**More explanations**: - -- FIRST(\*) can be used to get the first non-null value of all columns -- NULL will be returned if all the values of the specified column are all NULL -- No result will NOT be returned if all the columns in the result set are all NULL - -**Examples**: - -``` -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]; -``` - -**Description**:The last non-NULL value of a specific column in a table or STable - -**Return value type**:Same as the column being operated - -**Applicable column types**:Any data type - -**Applicable table types**:table, STable - -**More explanations**: - -- LAST(\*) can be used to get the last non-NULL value of all columns -- If the values of a column in the result set are all NULL, NULL is returned for that column; if all columns in the result are all NULL, no result will be returned. -- When it's used on a STable, if there are multiple values with the timestamp in the result set, one of them will be returned randomly and it's not guaranteed that the same value is returned if the same query is run multiple times. - -**Examples**: - -``` -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]; -``` - -**Description**: The greatest _k_ values of a specific column in a table or STable. If a value has multiple occurrences in the column but counting all of them in will exceed the upper limit _k_, then a part of them will be returned randomly. - -**Return value type**:Same as the column being operated - -**Applicable column types**:Data types except for timestamp, binary, nchar and bool - -**Applicable table types**:table, STable - -**More explanations**: - -- _k_ must be in range [1,100] -- The timestamp associated with the selected values are returned too -- Can't be used with `FILL` - -**Examples**: - -``` -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]; -``` - -**Description**:The least _k_ values of a specific column in a table or STable. If a value has multiple occurrences in the column but counting all of them in will exceed the upper limit _k_, then a part of them will be returned randomly. - -**Return value type**:Same as the column being operated - -**Applicable column types**: Data types except for timestamp, binary, nchar and bool - -**Applicable table types**: table, STable - -**More explanations**: - -- _k_ must be in range [1,100] -- The timestamp associated with the selected values are returned too -- Can't be used with `FILL` - -**Examples**: - -``` -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]; -``` - -**Description**: The value whose rank in a specific column matches the specified percentage. If such a value matching the specified percentage doesn't exist in the column, an interpolation value will be returned. - -**Return value type**: Double precision floating point - -**Applicable column types**: Data types except for timestamp, binary, nchar and bool - -**Applicable table types**: table - -**More explanations**: _P_ is in range [0,100], when _P_ is 0, the result is same as using function MIN; when _P_ is 100, the result is same as function MAX. - -**Examples**: - -``` -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] -``` - -**Description**: Similar to `PERCENTILE`, but a simulated result is returned - -**Return value type**: Double precision floating point - -**Applicable column types**: Data types except for timestamp, binary, nchar and bool - -**Applicable table types**: table, STable - -**More explanations** - -- _P_ is in range [0,100], when _P_ is 0, the result is same as using function MIN; when _P_ is 100, the result is same as function MAX. -- **algo_type** can only be input as `default` or `t-digest`, if it's not specified `default` will be used, i.e. `apercentile(column_name, 50)` is same as `apercentile(column_name, 50, "default")`. -- When `t-digest` is used, `t-digest` sampling is used to calculate. It can be used from version 2.2.0.0. - -**Nested query**: It can be used in both the outer query and inner query in a nested query. - -``` -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 }; -``` - -**Description**: The last row of a table or STable - -**Return value type**: Same as the column being operated - -**Applicable column types**: Any data type - -**Applicable table types**: table, STable - -**More explanations**: - -- When it's used against a STable, multiple rows with the same and largest timestamp may exist, in this case one of them is returned randomly and it's not guaranteed that the result is same if the query is run multiple times. -- Can't be used with `INTERVAL`. - -**Examples**: - -``` - 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 [From version 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})]; -``` - -**Description**: The value that matches the specified timestamp range is returned, if existing; or an interpolation value is returned. - -**Return value type**: same as the column being operated - -**Applicable column types**: Numeric data types - -**Applicable table types**: table, STable, nested query - -**More explanations** - -- `INTERP` is used to get the value that matches the specified time slice from a column. If no such value exists an interpolation value will be returned based on `FILL` parameter. -- The input data of `INTERP` is the value of the specified column, `where` can be used to filter the original data. If no `where` condition is specified then all original data is the input. -- The output time range of `INTERP` is specified by `RANGE(timestamp1,timestamp2)` parameter, with timestamp1<=timestamp2. timestamp1 is the starting point of the output time range and must be specified. timestamp2 is the ending point of the output time range and must be specified. If `RANGE` is not specified, then the timestamp of the first row that matches the filter condition is treated as timestamp1, the timestamp of the last row that matches the filter condition is treated as timestamp2. -- The number of rows in the result set of `INTERP` is determined by the parameter `EVERY`. Starting from timestamp1, one interpolation is performed for every time interval specified `EVERY` parameter. If `EVERY` parameter is not used, the time windows will be considered as no ending timestamp, i.e. there is only one time window from timestamp1. -- Interpolation is performed based on `FILL` parameter. No interpolation is performed if `FILL` is not used, that means either the original data that matches is returned or nothing is returned. -- `INTERP` can only be used to interpolate in single timeline. So it must be used with `group by tbname` when it's used on a STable. It can't be used with `GROUP BY` when it's used in the inner query of a nested query. -- The result of `INTERP` is not influenced by `ORDER BY TIMESTAMP`, which impacts the output order only.. - -**Examples**: Based on the `meters` schema used throughout the documents - -- Single point linear interpolation between "2017-07-14 18:40:00" and "2017-07-14 18:40:00: - -``` - taos> SELECT INTERP(current) FROM t1 RANGE('2017-7-14 18:40:00','2017-7-14 18:40:00') FILL(LINEAR); -``` - -- Get an original data every 5 seconds, no interpolation, between "2017-07-14 18:00:00" and "2017-07-14 19:00:00: - -``` - taos> SELECT INTERP(current) FROM t1 RANGE('2017-7-14 18:00:00','2017-7-14 19:00:00') EVERY(5s); -``` - -- Linear interpolation every 5 seconds between "2017-07-14 18:00:00" and "2017-07-14 19:00:00: - -``` - taos> SELECT INTERP(current) FROM t1 RANGE('2017-7-14 18:00:00','2017-7-14 19:00:00') EVERY(5s) FILL(LINEAR); -``` - -- Backward interpolation every 5 seconds - -``` - taos> SELECT INTERP(current) FROM t1 EVERY(5s) FILL(NEXT); -``` - -- Linear interpolation every 5 seconds between "2017-07-14 17:00:00" and "2017-07-14 20:00:00" - -``` - 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 [Prior to version 2.3.1] - -``` -SELECT INTERP(field_name) FROM { tb_name | stb_name } WHERE ts='timestamp' [FILL ({ VALUE | PREV | NULL | LINEAR | NEXT})]; -``` - -**Description**: The value of a specific column that matches the specified time slice - -**Return value type**: Same as the column being operated - -**Applicable column types**: Numeric data type - -**Applicable table types**: table, STable - -**More explanations**: - -- It can be used from version 2.0.15.0 -- Time slice must be specified. If there is no data matching the specified time slice, interpolation is performed based on `FILL` parameter. Conditions such as tags or `tbname` can be used `Where` clause can be used to filter data. -- The timestamp specified must be within the time range of the data rows of the table or STable. If it is beyond the valid time range, nothing is returned even with `FILL` parameter. -- `INTERP` can be used to query only single time point once. `INTERP` can be used with `EVERY` to get the interpolation value every time interval. -- **Examples**: - -``` - 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) -``` - -If there is not any data corresponding to the specified timestamp, an interpolation value is returned if interpolation policy is specified by `FILL` parameter; or nothing is returned\ - -``` - 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) -``` - -Interpolation is performed every 5 milliseconds between `['2017-7-14 18:40:00', '2017-7-14 18:40:00.014']` - -``` - 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) -``` - -### TAIL - -``` -SELECT TAIL(field_name, k, offset_val) FROM {tb_name | stb_name} [WHERE clause]; -``` - -**Description**: The next _k_ rows are returned after skipping the last `offset_val` rows, NULL values are not ignored. `offset_val` is optional parameter. When it's not specified, the last _k_ rows are returned. When `offset_val` is used, the effect is same as `order by ts desc LIMIT k OFFSET offset_val`. - -**Parameter value range**: k: [1,100] offset_val: [0,100] - -**Return value type**: Same as the column being operated - -**Applicable column types**: Any data type except form timestamp, i.e. the primary key - -**Applicable versions**: From version 2.6.0.0 - -**Examples**: - -``` -taos> select ts,dbig from tail2; - ts | dbig | -================================================== -2021-10-15 00:31:33.000 | 1 | -2021-10-17 00:31:31.000 | NULL | -2021-12-24 00:31:34.000 | 2 | -2022-01-01 08:00:05.000 | 19 | -2022-01-01 08:00:06.000 | NULL | -2022-01-01 08:00:07.000 | 9 | -Query OK, 6 row(s) in set (0.001952s) - -taos> select tail(dbig,2,2) from tail2; -ts | tail(dbig,2,2) | -================================================== -2021-12-24 00:31:34.000 | 2 | -2022-01-01 08:00:05.000 | 19 | -Query OK, 2 row(s) in set (0.002307s) -``` - -### UNIQUE - -``` -SELECT UNIQUE(field_name) FROM {tb_name | stb_name} [WHERE clause]; -``` - -**Description**: The values that occur the first time in the specified column. The effect is similar to `distinct` keyword, but it can also be used to match tags or timestamp. - -**Return value type**: Same as the column or tag being operated - -**Applicable column types**: Any data types except for timestamp - -**支持版本**: From version 2.6.0.0 - -**More explanations**: - -- It can be used against table or STable, but can't be used together with time window, like `interval`, `state_window` or `session_window` . -- Considering the number of result sets is unpredictable, it's suggested to limit the distinct values under 100,000 to control the memory usage, otherwise error will be returned. - -**Examples**: - -``` -taos> select ts,voltage from unique1; - ts | voltage | -================================================== -2021-10-17 00:31:31.000 | 1 | -2022-01-24 00:31:31.000 | 1 | -2021-10-17 00:31:31.000 | 1 | -2021-12-24 00:31:31.000 | 2 | -2022-01-01 08:00:01.000 | 19 | -2021-10-17 00:31:31.000 | NULL | -2022-01-01 08:00:02.000 | NULL | -2022-01-01 08:00:03.000 | 9 | -Query OK, 8 row(s) in set (0.003018s) - -taos> select unique(voltage) from unique1; -ts | unique(voltage) | -================================================== -2021-10-17 00:31:31.000 | 1 | -2021-10-17 00:31:31.000 | NULL | -2021-12-24 00:31:31.000 | 2 | -2022-01-01 08:00:01.000 | 19 | -2022-01-01 08:00:03.000 | 9 | -Query OK, 5 row(s) in set (0.108458s) -``` - -## Scalar functions - -### DIFF - -```sql -SELECT {DIFF(field_name, ignore_negative) | DIFF(field_name)} FROM tb_name [WHERE clause]; -``` - -**Description**: The different of each row with its previous row for a specific column. `ignore_negative` can be specified as 0 or 1, the default value is 1 if it's not specified. `1` means negative values are ignored. - -**Return value type**: Same as the column being operated - -**Applicable column types**: Data types except for timestamp, binary, nchar and bool - -**Applicable table types**: table, STable - -**More explanations**: - -- The number of result rows is the number of rows subtracted by one, no output for the first row -- From version 2.1.30, `DIFF` can be used on STable with `GROUP by tbname` -- From version 2.6.0, `ignore_negative` parameter is supported - -**Examples**: - -```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]; -``` - -**Description**: The derivative of a specific column. The time rage can be specified by parameter `time_interval` 参数指定, the minimum allowed time range is 1 second (1s); the value of `ignore_negative` can be 0 or 1, 1 means negative values are ignored. - -**Return value type**: Double precision floating point - -**Applicable column types**: Data types except for timestamp, binary, nchar and bool - -**Applicable table types**: table, STable - -**More explanations**: - -- It is available from version 2.1.3.0, the number of result rows is the number of total rows in the time range subtracted by one, no output for the first row.\ -- It can be used together with `GROUP BY tbname` against a STable. - -**Examples**: - -``` -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]; -``` - -**Description**: The difference between the max and the min of a specific column - -**Return value type**: Double precision floating point - -**Applicable column types**: Data types except for binary, nchar, and bool - -**Applicable table types**: table, STable - -**More explanations**: Can be used on a column of TIMESTAMP type, the result is the time range size.可 - -**Examples**: - -``` -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]; -``` - -**Description**: The round up value of a specific column - -**Return value type**: Same as the column being used - -**Applicable data types**: Data types except for timestamp, binary, nchar, bool - -**Applicable table types**: table, STable - -**Applicable nested query**: inner query and outer query - -**More explanations**: - -- Can't be used on any tags of any type -- Arithmetic operation can be performed on the result of `ceil` function -- Can't be used with aggregate functions - -### FLOOR - -``` -SELECT FLOOR(field_name) FROM { tb_name | stb_name } [WHERE clause]; -``` - -**Description**: The round down value of a specific column - -**More explanations**: The restrictions are same as `CEIL` function. - -### ROUND - -``` -SELECT ROUND(field_name) FROM { tb_name | stb_name } [WHERE clause]; -``` - -**Description**: The round value of a specific column. - -**More explanations**: The restrictions are same as `CEIL` function. - -### CSUM - -```sql - SELECT CSUM(field_name) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: The cumulative sum of each row for a specific column. The number of output rows is same as that of the input rows. - -**Return value type**: Long integer for integers; Double for floating points. Timestamp is returned for each row. - -**Applicable data types**: Data types except for timestamp, binary, nchar, and bool - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**More explanations**: - -- Can't be used on tags when it's used on STable -- Arithmetic operation can't be performed on the result of `csum` function -- Can only be used with aggregate functions -- `Group by tbname` must be used together on a STable to force the result on a single timeline - -**Applicable versions**: From 2.3.0.x - -### MAVG - -```sql - SELECT MAVG(field_name, K) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: The moving average of continuous _k_ values of a specific column. If the number of input rows is less than _k_, nothing is returned. The applicable range is _k_ is [1,1000]. - -**Return value type**: Double precision floating point - -**Applicable data types**: Data types except for timestamp, binary, nchar, and bool - -**Applicable nested query**: Inner query and Outer query - -**Applicable table types**: table, STable - -**More explanations**: - -- Arithmetic operation can't be performed on the result of `MAVG`. -- Can only be used with data columns, can't be used with tags. -- Can't be used with aggregate functions.\（Aggregation）函数一起使用； -- Must be used with `GROUP BY tbname` when it's used on a STable to force the result on each single timeline.该 - -**Applicable versions**: From 2.3.0.x - -### SAMPLE - -```sql - SELECT SAMPLE(field_name, K) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: _k_ sampling values of a specific column. The applicable range of _k_ is [1,10000] - -**Return value type**: Same as the column being operated plus the associated timestamp - -**Applicable data types**: Any data type except for tags of STable - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**More explanations**: - -- Arithmetic operation can't be operated on the result of `SAMPLE` function -- Must be used with `Group by tbname` when it's used on a STable to force the result on each single timeline - -**Applicable versions**: From 2.3.0.x - -### ASIN - -```sql -SELECT ASIN(field_name) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: The anti-sine of a specific column - -**Return value type**: Double if the input value is not NULL; or NULL if the input value is NULL - -**Applicable data types**: Data types except for timestamp, binary, nchar, bool - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**Applicable versions**: From 2.6.0.0 - -**More explanations**: - -- Can't be used with tags -- Can't be used with aggregate functions - -### ACOS - -```sql -SELECT ACOS(field_name) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: The anti-cosine of a specific column 获 - -**Return value type**: ouble if the input value is not NULL; or NULL if the input value is NULL - -**Applicable data types**: Data types except for timestamp, binary, nchar, bool - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**Applicable versions**: From 2.6.0.0 - -**More explanations**: - -- Can't be used with tags -- Can't be used with aggregate functions - -### ATAN - -```sql -SELECT ATAN(field_name) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: anti-tangent of a specific column - -**Description**: The anti-cosine of a specific column 获 - -**Return value type**: Double if the input value is not NULL; or NULL if the input value is NULL - -**Applicable data types**: Data types except for timestamp, binary, nchar, bool - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**Applicable versions**: From 2.6.0.0 - -**More explanations**: - -- Can't be used with tags -- Can't be used with aggregate functions - -### SIN - -```sql -SELECT SIN(field_name) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: The sine of a specific column - -**Description**: The anti-cosine of a specific column 获 - -**Return value type**: Double if the input value is not NULL; or NULL if the input value is NULL - -**Applicable data types**: Data types except for timestamp, binary, nchar, bool - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**Applicable versions**: From 2.6.0.0 - -**More explanations**: - -- Can't be used with tags -- Can't be used with aggregate functions - -### COS - -```sql -SELECT COS(field_name) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: The cosine of a specific column - -**Description**: The anti-cosine of a specific column 获 - -**Return value type**: Double if the input value is not NULL; or NULL if the input value is NULL - -**Applicable data types**: Data types except for timestamp, binary, nchar, bool - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**Applicable versions**: From 2.6.0.0 - -**More explanations**: - -- Can't be used with tags -- Can't be used with aggregate functions - -### TAN - -```sql -SELECT TAN(field_name) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: The tangent of a specific column - -**Description**: The anti-cosine of a specific column 获 - -**Return value type**: Double if the input value is not NULL; or NULL if the input value is NULL - -**Applicable data types**: Data types except for timestamp, binary, nchar, bool - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**Applicable versions**: From 2.6.0.0 - -**More explanations**: - -- Can't be used with tags -- Can't be used with aggregate functions - -### POW - -```sql -SELECT POW(field_name, power) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: The power of a specific column with `power` as the index - -**Return value type**: Double if the input value is not NULL; or NULL if the input value is NULL - -**Applicable data types**: Data types except for timestamp, binary, nchar, bool - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**Applicable versions**: From 2.6.0.0 - -**More explanations**: - -- Can't be used with tags -- Can't be used with aggregate functions - -### LOG - -```sql -SELECT LOG(field_name, base) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: The log of a specific with `base` as the radix - -**Return value type**: Double if the input value is not NULL; or NULL if the input value is NULL - -**Applicable data types**: Data types except for timestamp, binary, nchar, bool - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**Applicable versions**: From 2.6.0.0 - -**More explanations**: - -- Can't be used with tags -- Can't be used with aggregate functions - -### ABS - -```sql -SELECT ABS(field_name) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: The absolute of a specific column - -**Return value type**: UBIGINT if the input value is integer; DOUBLE if the input value is FLOAT/DOUBLE 如 - -**Applicable data types**: Data types except for timestamp, binary, nchar, bool - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**Applicable versions**: From 2.6.0.0 - -**More explanations**: - -- Can't be used with tags -- Can't be used with aggregate functions - -### SQRT - -```sql -SELECT SQRT(field_name) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: The square root of a specific column - -**Return value type**: Double if the input value is not NULL; or NULL if the input value is NULL - -**Applicable data types**: Data types except for timestamp, binary, nchar, bool - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**Applicable versions**: From 2.6.0.0 - -**More explanations**: - -- Can't be used with tags -- Can't be used with aggregate functions - -### CAST - -```sql -SELECT CAST(expression AS type_name) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: It's used for type casting. The input parameter `expression` can be data columns, constants, scalar functions or arithmetic between them. Can't be used with tags, and can only be used in `select` clause. - -**Return value type**: The type specified by parameter `type_name` - -**Applicable data types**: - -- Parameter `expression` can be any data type except for JSON, more specifically it can be any of BOOL/TINYINT/SMALLINT/INT/BIGINT/FLOAT/DOUBLE/BINARY(M)/TIMESTAMP/NCHAR(M)/TINYINT UNSIGNED/SMALLINT UNSIGNED/INT UNSIGNED/BIGINT UNSIGNED -- The output data type specified by `type_name` can only be one of BIGINT/BINARY(N)/TIMESTAMP/NCHAR(N)/BIGINT UNSIGNED - -**Applicable versions**: From 2.6.0.0 - -**More explanations**: - -- Error will be reported for unsupported type casting -- NULL will be returned if the input value is NULL -- Some values of some supported data types may not be casted, below are known issues: - 1）When casting BINARY/NCHAR to BIGINT/BIGINT UNSIGNED, some characters may be treated as illegal, for example "a" may be converted to 0. - 2）There may be overflow when casting singed integer or TIMESTAMP to unsigned BIGINT - 3）There may be overflow when casting unsigned BIGINT to BIGINT - 4）There may be overflow when casting FLOAT/DOUBLE to BIGINT or UNSIGNED BIGINT - -### CONCAT - -```sql -SELECT CONCAT(str1|column1, str2|column2, ...) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: The concatenation result of two or more strings, the number of strings to be concatenated is at least 2 and at most 8 - -**Return value type**: Same as the columns being operated, BINARY or NCHAR; or NULL if all the input are NULL - -**Applicable data types**: The input data must be in either all BINARY or in all NCHAR; can't be used on tag columns - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**Applicable versions**: From 2.6.0.0 - -### CONCAT_WS - -``` -SELECT CONCAT_WS(separator, str1|column1, str2|column2, ...) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: The concatenation result of two or more strings with separator, the number of strings to be concatenated is at least 3 and at most 9 - -**Return value type**: Same as the columns being operated, BINARY or NCHAR; or NULL if all the input are NULL - -**Applicable data types**: The input data must be in either all BINARY or in all NCHAR; can't be used on tag columns - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**Applicable versions**: From 2.6.0.0 - -**More explanations**: - -- If the value of `separator` is NULL, the output is NULL. If the value of `separator` is not NULL but other input are all NULL, the output is empty string. - -### LENGTH - -``` -SELECT LENGTH(str|column) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: The length in bytes of a string - -**Return value type**: Integer - -**Applicable data types**: BINARY or NCHAR, can't be used on tags - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**Applicable versions**: From 2.6.0.0 - -**More explanations** - -- If the input value is NULL, the output is NULL too - -### CHAR_LENGTH - -``` -SELECT CHAR_LENGTH(str|column) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: The length in number of characters of a string - -**Return value type**: Integer - -**Applicable data types**: BINARY or NCHAR, can't be used on tags - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**Applicable versions**: From 2.6.0.0 - -**More explanations** - -- If the input value is NULL, the output is NULL too - -### LOWER - -``` -SELECT LOWER(str|column) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: Convert the input string to lower case - -**Return value type**: Same as input - -**Applicable data types**: BINARY or NCHAR, can't be used on tags - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**Applicable versions**: From 2.6.0.0 - -**More explanations** - -- If the input value is NULL, the output is NULL too - -### UPPER - -``` -SELECT UPPER(str|column) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: Convert the input string to upper case - -**Return value type**: Same as input - -**Applicable data types**: BINARY or NCHAR, can't be used on tags - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**Applicable versions**: From 2.6.0.0 - -**More explanations** - -- If the input value is NULL, the output is NULL too - -### LTRIM - -``` -SELECT LTRIM(str|column) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: Remove the left leading blanks of a string - -**Return value type**: Same as input - -**Applicable data types**: BINARY or NCHAR, can't be used on tags - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**Applicable versions**: From 2.6.0.0 - -**More explanations** - -- If the input value is NULL, the output is NULL too - -### RTRIM - -``` -SELECT RTRIM(str|column) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: Remove the right tailing blanks of a string - -**Return value type**: Same as input - -**Applicable data types**: BINARY or NCHAR, can't be used on tags - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**Applicable versions**: From 2.6.0.0 - -**More explanations** - -- If the input value is NULL, the output is NULL too - -### SUBSTR - -``` -SELECT SUBSTR(str,pos[,len]) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: The sub-string starting from `pos` with length of `len` from the original string `str` - -**Return value type**: Same as input - -**Applicable data types**: BINARY or NCHAR, can't be used on tags - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**Applicable versions**: From 2.6.0.0 - -**More explanations**: - -- If the input is NULL, the output is NULL -- Parameter `pos` can be an positive or negative integer; If it's positive, the starting position will be counted from the beginning of the string; if it's negative, the starting position will be counted from the end of the string. -- If `len` is not specified, it means from `pos` to the end. - -### Arithmetic Operations - -``` -SELECT field_name [+|-|*|/|%][Value|field_name] FROM { tb_name | stb_name } [WHERE clause]; -``` - -**Description**: The sum, difference, product, quotient, or remainder between one or more columns - -**Return value type**: Double precision floating point - -**Applicable column types**: Data types except for timestamp, binary, nchar, bool - -**Applicable table types**: table, STable - -**More explanations**: - -- Arithmetic operations can be performed on two or more columns, `()` can be used to control the precedence -- NULL doesn't participate the operation, if one of the operands is NULL then result is NULL - -**Examples**: - -``` -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) -``` - -### STATECOUNT - -``` -SELECT STATECOUNT(field_name, oper, val) FROM { tb_name | stb_name } [WHERE clause]; -``` - -**Description**: The number of continuous rows satisfying the specified conditions for a specific column. The result is shown as an extra column for each row. If the specified condition is evaluated as true, the number is increased by 1; otherwise the number is reset to -1. If the input value is NULL, then the corresponding row is skipped. - -**Applicable parameter values**: - -- oper : Can be one of LT (lower than), GT (greater than), LE (lower than or euqal to), GE (greater than or equal to), NE (not equal to), EQ (equal to), the value is case insensitive -- val ： Numeric types - -**Return value type**: Integer - -**Applicable data types**: Data types excpet for timestamp, binary, nchar, bool - -**Applicable table types**: table, STable - -**Applicable nested query**: Outer query only - -**Applicable versions**: From 2.6.0.0 - -**More explanations**: - -- Must be used together with `GROUP BY tbname` when it's used on a STable to force the result into each single timeline] -- Can't be used with window operation, like interval/state_window/session_window - -**Examples**: - -``` -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) -``` - -### STATEDURATION - -``` -SELECT stateDuration(field_name, oper, val, unit) FROM { tb_name | stb_name } [WHERE clause]; -``` - -**Description**: The length of time range in which all rows satisfy the specified condition for a specific column. The result is shown as an extra column for each row. The length for the first row that satisfies the condition is 0. Next, if the condition is evaluated as true for a row, the time interval between current row and its previous row is added up to the time range; otherwise the time range length is reset to -1. If the value of the column is NULL, the corresponding row is skipped. - -**Applicable parameter values**: - -- oper : Can be one of LT (lower than), GT (greater than), LE (lower than or euqal to), GE (greater than or equal to), NE (not equal to), EQ (equal to), the value is case insensitive -- val ： Numeric types -- unit: The unit of time interval, can be [1s, 1m, 1h], default is 1s - -**Return value type**: Integer - -**Applicable data types**: Data types excpet for timestamp, binary, nchar, bool - -**Applicable table types**: table, STable - -**Applicable nested query**: Outer query only - -**Applicable versions**: From 2.6.0.0 - -**More explanations**: - -- Must be used together with `GROUP BY tbname` when it's used on a STable to force the result into each single timeline] -- Can't be used with window operation, like interval/state_window/session_window - -**Examples**: - -``` -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.002407s) - -taos> select stateDuration(dbig,GT,2) from statef2; -ts | dbig | stateduration(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 | 0 | -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.002613s) -``` - -## Time Functions - -From version 2.6.0.0, below time related functions can be used in TDengine. - -### NOW - -```sql -SELECT NOW() FROM { tb_name | stb_name } [WHERE clause]; -SELECT select_expr FROM { tb_name | stb_name } WHERE ts_col cond_operatior NOW(); -INSERT INTO tb_name VALUES (NOW(), ...); -``` - -**Description**: The current time of the client side system - -**Return value type**: TIMESTAMP - -**Applicable column types**: TIMESTAMP only - -**Applicable table types**: table, STable - -**More explanations**: - -- Add and Subtract operation can be performed, for example NOW() + 1s, the time unit can be: - b(nanosecond), u(microsecond), a(millisecond)), s(second), m(minute), h(hour), d(day), w(week) -- The precision of the returned timestamp is same as the precision set for the current data base in use - -**Examples**: - -```sql -taos> SELECT NOW() FROM meters; - now() | -========================== - 2022-02-02 02:02:02.456 | -Query OK, 1 row(s) in set (0.002093s) - -taos> SELECT NOW() + 1h FROM meters; - now() + 1h | -========================== - 2022-02-02 03:02:02.456 | -Query OK, 1 row(s) in set (0.002093s) - -taos> SELECT COUNT(voltage) FROM d1001 WHERE ts < NOW(); - count(voltage) | -============================= - 5 | -Query OK, 5 row(s) in set (0.004475s) - -taos> INSERT INTO d1001 VALUES (NOW(), 10.2, 219, 0.32); -Query OK, 1 of 1 row(s) in database (0.002210s) -``` - -### TODAY - -```sql -SELECT TODAY() FROM { tb_name | stb_name } [WHERE clause]; -SELECT select_expr FROM { tb_name | stb_name } WHERE ts_col cond_operatior TODAY()]; -INSERT INTO tb_name VALUES (TODAY(), ...); -``` - -**Description**: The timestamp of 00:00:00 of the client side system - -**Return value type**: TIMESTAMP - -**Applicable column types**: TIMESTAMP only - -**Applicable table types**: table, STable - -**More explanations**: - -- Add and Subtract operation can be performed, for example NOW() + 1s, the time unit can be: - b(nanosecond), u(microsecond), a(millisecond)), s(second), m(minute), h(hour), d(day), w(week) -- The precision of the returned timestamp is same as the precision set for the current data base in use - -**Examples**: - -```sql -taos> SELECT TODAY() FROM meters; - today() | -========================== - 2022-02-02 00:00:00.000 | -Query OK, 1 row(s) in set (0.002093s) - -taos> SELECT TODAY() + 1h FROM meters; - today() + 1h | -========================== - 2022-02-02 01:00:00.000 | -Query OK, 1 row(s) in set (0.002093s) - -taos> SELECT COUNT(voltage) FROM d1001 WHERE ts < TODAY(); - count(voltage) | -============================= - 5 | -Query OK, 5 row(s) in set (0.004475s) - -taos> INSERT INTO d1001 VALUES (TODAY(), 10.2, 219, 0.32); -Query OK, 1 of 1 row(s) in database (0.002210s) -``` - -### TIMEZONE - -```sql -SELECT TIMEZONE() FROM { tb_name | stb_name } [WHERE clause]; -``` - -**Description**: The timezone of the client side system - -**Return value type**: BINARY - -**Applicable column types**: None - -**Applicable table types**: table, STable - -**Examples**: - -```sql -taos> SELECT TIMEZONE() FROM meters; - timezone() | -================================= - UTC (UTC, +0000) | -Query OK, 1 row(s) in set (0.002093s) -``` - -### TO_ISO8601 - -```sql -SELECT TO_ISO8601(ts_val | ts_col) FROM { tb_name | stb_name } [WHERE clause]; -``` - -**Description**: The ISO8601 date/time format converted from a UNIX timestamp, plus the timezone of the client side system - -**Return value type**: BINARY - -**Applicable column types**: TIMESTAMP, constant or a column - -**Applicable table types**: table, STable - -**More explanations**: - -- If the input is UNIX timestamp constant, the precision of the returned value is determined by the digits of the input timestamp -- If the input is a column of TIMESTAMP type, The precision of the returned value is same as the precision set for the current data base in use - -**Examples**: - -```sql -taos> SELECT TO_ISO8601(1643738400) FROM meters; - to_iso8601(1643738400) | -============================== - 2022-02-02T02:00:00+0800 | - -taos> SELECT TO_ISO8601(ts) FROM meters; - to_iso8601(ts) | -============================== - 2022-02-02T02:00:00+0800 | - 2022-02-02T02:00:00+0800 | - 2022-02-02T02:00:00+0800 | -``` - -### TO_UNIXTIMESTAMP - -```sql -SELECT TO_UNIXTIMESTAMP(datetime_string | ts_col) FROM { tb_name | stb_name } [WHERE clause]; -``` - -**Description**: UNIX timestamp converted from a string of date/time format - -**Return value type**: Long integer - -**Applicable column types**: Constant or column of BINARY/NCHAR - -**Applicable table types**: table, STable - -**More explanations**: - -- The input string must be compatible with ISO8601/RFC3339 standard, 0 will be returned if the string can't be covnerted -- The precision of the returned timestamp is same as the precision set for the current data base in use - -**Examples**: - -```sql -taos> SELECT TO_UNIXTIMESTAMP("2022-02-02T02:00:00.000Z") FROM meters; -to_unixtimestamp("2022-02-02T02:00:00.000Z") | -============================================== - 1643767200000 | - -taos> SELECT TO_UNIXTIMESTAMP(col_binary) FROM meters; - to_unixtimestamp(col_binary) | -======================================== - 1643767200000 | - 1643767200000 | - 1643767200000 | -``` - -### TIMETRUNCATE - -```sql -SELECT TIMETRUNCATE(ts_val | datetime_string | ts_col, time_unit) FROM { tb_name | stb_name } [WHERE clause]; -``` - -**Description**: Truncate the input timestamp with unit specified by `time_unit`\ - -**Return value type**: TIMESTAMP\ - -**Applicable column types**: UNIX timestamp constant, string constant of date/time format, or a column of timestamp - -**Applicable table types**: table, STable - -**More explanations**: - -- Time unit specified by `time_unit` can be: - 1u(microsecond),1a(millisecond),1s(second),1m(minute),1h(hour),1d(day). -- The precision of the returned timestamp is same as the precision set for the current data base in use - -**Examples**: - -```sql -taos> SELECT TIMETRUNCATE(1643738522000, 1h) FROM meters; - timetruncate(1643738522000, 1h) | -=================================== - 2022-02-02 02:00:00.000 | -Query OK, 1 row(s) in set (0.001499s) - -taos> SELECT TIMETRUNCATE("2022-02-02 02:02:02", 1h) FROM meters; - timetruncate("2022-02-02 02:02:02", 1h) | -=========================================== - 2022-02-02 02:00:00.000 | -Query OK, 1 row(s) in set (0.003903s) - -taos> SELECT TIMETRUNCATE(ts, 1h) FROM meters; - timetruncate(ts, 1h) | -========================== - 2022-02-02 02:00:00.000 | - 2022-02-02 02:00:00.000 | - 2022-02-02 02:00:00.000 | -Query OK, 3 row(s) in set (0.003903s) -``` - -### TIMEDIFF - -```sql -SELECT TIMEDIFF(ts_val1 | datetime_string1 | ts_col1, ts_val2 | datetime_string2 | ts_col2 [, time_unit]) FROM { tb_name | stb_name } [WHERE clause]; -``` - -**Description**: The difference between two timestamps, and rounded to the time unit specified by `time_unit` - -**Return value type**: Long Integer - -**Applicable column types**: UNIX timestamp constant, string constant of date/time format, or a column of TIMESTAMP type - -**Applicable table types**: table, STable - -**More explanations**: - -- Time unit specified by `time_unit` can be: - 1u(microsecond),1a(millisecond),1s(second),1m(minute),1h(hour),1d(day). -- The precision of the returned timestamp is same as the precision set for the current data base in use - -**Examples**: - -```sql -taos> SELECT TIMEDIFF(1643738400000, 1643742000000) FROM meters; - timediff(1643738400000, 1643742000000) | -========================================= - 3600000 | -Query OK, 1 row(s) in set (0.002553s) -taos> SELECT TIMEDIFF(1643738400000, 1643742000000, 1h) FROM meters; - timediff(1643738400000, 1643742000000, 1h) | -============================================= - 1 | -Query OK, 1 row(s) in set (0.003726s) - -taos> SELECT TIMEDIFF("2022-02-02 03:00:00", "2022-02-02 02:00:00", 1h) FROM meters; - timediff("2022-02-02 03:00:00", "2022-02-02 02:00:00", 1h) | -============================================================= - 1 | -Query OK, 1 row(s) in set (0.001937s) - -taos> SELECT TIMEDIFF(ts_col1, ts_col2, 1h) FROM meters; - timediff(ts_col1, ts_col2, 1h) | -=================================== - 1 | -Query OK, 1 row(s) in set (0.001937s) -``` diff --git a/docs-en/12-taos-sql/08-interval.md b/docs-en/12-taos-sql/08-interval.md deleted file mode 100644 index 7bf2bd207e19dda1da3c97be64cd81e72db72c19..0000000000000000000000000000000000000000 --- a/docs-en/12-taos-sql/08-interval.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -sidebar_label: Window -title: Aggregate by Window ---- - -Aggregate by time window is supported in TDengine. For example, each temperature sensor reports the temperature every second, the average temperature every 10 minutes can be retrieved by query with time window. -Window related clauses are used to divide the data set to be queried into subsets and then aggregate. There are three kinds of windows, time window, status window, and session window. There are two kinds of time windows, sliding window and flip time window. - -## Time Window - -`INTERVAL` claused is used to generate time windows of same time interval, `SLIDING` is used to specify the time step for which the time window moves forward. The query is performed on one time window each time, and the time window moves forward with time. When defining continuous query both the size of time window and the step of forward sliding time need to be specified. As shown in the figure blow, [t0s, t0e] ，[t1s , t1e]， [t2s, t2e] are respectively the time range of three time windows on which continuous queries are executed. The time step for which time window moves forward is marked by `sliding time`. Query, filter and aggregate operations are executed on each time window respectively. When the time step specified by `SLIDING` is same as the time interval specified by `INTERVAL`, the sliding time window is actually a flip time window. - -![Time Window](/img/sql/timewindow-1.png) - -`INTERVAL` and `SLIDING` should be used with aggregate functions and selection functions. Below SQL statement is illegal because no aggregate or selection function is used with `INTERVAL`. - -``` -SELECT * FROM temp_tb_1 INTERVAL(1m); -``` - -The time step specified by `SLIDING` can't exceed the time interval specified by `INTERVAL`. Below SQL statement is illegal because the time length specified by `SLIDING` exceeds that specified by `INTERVAL`. - -``` -SELECT COUNT(*) FROM temp_tb_1 INTERVAL(1m) SLIDING(2m); -``` - -When the time length specified by `SLIDING` is same as that specified by `INTERVAL`, sliding window is actually flip window. The minimum time range specified by `INTERVAL` is 10 milliseconds (10a) prior to version 2.1.5.0. From version 2.1.5.0, the minimum time range by `INTERVAL` can be 1 microsecond (1u). However, if the DB precision is millisecond, the minimum time range is 1 millisecond (1a). Please be noted that the `timezone` parameter should be configured to same value in the `taos.cfg` configuration file on client side and server side. - -## Status Window - -In case of using integer, bool, or string to represent the device status at a moment, the continuous rows with same status belong to same status window. Once the status changes, the status window closes. As shown in the following figure，there are two status windows according to status, [2019-04-28 14:22:07，2019-04-28 14:22:10] and [2019-04-28 14:22:11，2019-04-28 14:22:12]. Status window is not applicable to STable for now. - -![Status Window](/img/sql/timewindow-3.png) - -`STATE_WINDOW` is used to specify the column based on which to define status window, for example： - -``` -SELECT COUNT(*), FIRST(ts), status FROM temp_tb_1 STATE_WINDOW(status); -``` - -## Session Window - -```sql -SELECT COUNT(*), FIRST(ts) FROM temp_tb_1 SESSION(ts, tol_val); -``` - -The primary key, i.e. timestamp, is used to determine which session window the row belongs to. If the time interval between two adjacent rows is within the time range specified by `tol_val`, they belong to same session window; otherwise they belong to two different time windows. As shown in the figure below, if the limit of time interval for session window is specified as 12 seconds, then the 6 rows in the figure constitutes 2 time windows, [2019-04-28 14:22:10，2019-04-28 14:22:30] and [2019-04-28 14:23:10，2019-04-28 14:23:30], because the time difference between 2019-04-28 14:22:30 and 2019-04-28 14:23:10 is 40 seconds, which exceeds the time interval limit of 12 seconds. - -![Session Window](/img/sql/timewindow-2.png) - -If the time interval between two continuous rows are withint the time interval specified by `tol_value` they belong to the same session window; otherwise a new session window is started automatically. Session window is not supported on STable for now. - -## More On Window Aggregate - -### Syntax - -The full syntax of aggregate by window is as following: - -```sql -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] -``` - -### Restrictions - -- Aggregate functions and selection functions can be used in `function_list`, with each function having only one output, for example COUNT, AVG, SUM, STDDEV, LEASTSQUARES, PERCENTILE, MIN, MAX, FIRST, LAST. Functions having multiple ouput can't be used, for example DIFF or arithmetic operations. -- `LAST_ROW` can't be used together with window aggregate. -- Scalar functions, like CEIL/FLOOR, can't be used with window aggregate. -- `WHERE` clause can be used to specify the starting and ending time and other filter conditions -- `FILL` clause is used to specify how to fill when there is data missing in any window, including: \ - 1. NONE: No fill (the default fill mode) - 2. VALUE：Fill with a fixed value, which should be specified together, for example `FILL(VALUE, 1.23)` - 3. PREV：Fill with the previous non-NULL value, `FILL(PREV)` - 4. NULL：Fill with NULL, `FILL(NULL)` - 5. LINEAR：Fill with the closest non-NULL value, `FILL(LINEAR)` - 6. NEXT：Fill with the next non-NULL value, `FILL(NEXT)` - -:::info - -1. Huge volume of interpolation output may be returned using `FILL`, so it's recommended to specify the time range when using `FILL`. The maximum interpolation values that can be returned in single query is 10,000,000. -2. The result set is in the ascending order of timestamp in aggregate by time window aggregate. -3. If aggregate by window is used on STable, the aggregate function is performed on all the rows matching the filter conditions. If `GROUP BY` is not used in the query, the result set will be returned in ascending order of timestamp; otherwise the result set is not exactly in the order of ascending timestamp in each group. - ::: - -Aggregate by time window is also used in continuous query, please refer to [Continuous Query](/develop/continuous-query). - -## Examples - -The table of intelligent meters can be created like below SQL statement： - -```sql -CREATE TABLE meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT); -``` - -The average current, maximum current and median of current in every 10 minutes of the past 24 hours can be calculated using below SQL statement, with missing value filled with the previous non-NULL value. - -``` -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-en/12-taos-sql/09-limit.md b/docs-en/12-taos-sql/09-limit.md deleted file mode 100644 index d695f9d99993baf243df805f936be2872faaad47..0000000000000000000000000000000000000000 --- a/docs-en/12-taos-sql/09-limit.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -sidebar_label: Limits -title: Limits and Restrictions ---- - -## Naming Rules - -1. Only English characters, digits and underscore are allowed -2. Can't be started with digits -3. Case Insensitive without escape character "\`" -4. Identifier with escape character "\`" - To support more flexible table or column names, a new escape character "\`" is introduced. For more details please refer to [escape](/taos-sql/escape). - -## Password Rule - -The legal character set is `[a-zA-Z0-9!?$%^&*()_–+={[}]:;@~#|<,>.?/]`. - -## General Limits - -- Maximum length of database name is 32 bytes -- Maximum length of table name is 192 bytes, excluding the database name prefix and the separator -- Maximum length of each data row is 48K bytes from version 2.1.7.0 , before which the limit is 16K bytes. Please be noted that the upper limit includes the extra 2 bytes consumed by each column of BINARY/NCHAR type. -- Maximum of column name is 64. -- Maximum number of columns is 4096. There must be at least 2 columns, and the first column must be timestamp. -- Maximum length of tag name is 64. -- Maximum number of tags is 128. There must be at least 1 tag. The total length of tag values should not exceed 16K bytes. -- Maximum length of singe SQL statement is 1048576, i.e. 1 MB bytes. It can be configured in the parameter `maxSQLLength` in the client side, the applicable range is [65480, 1048576]. -- At most 4096 columns (or 1024 prior to 2.1.7.0) can be returned by `SELECT`, functions in the query statement may constitute columns. Error will be returned if the limit is exceeded. -- Maximum numbers of databases, STables, tables are only depending on the system resources. -- Maximum of database name is 32 bytes, can't include "." and special characters. -- Maximum replica number of database is 3 -- Maximum length of user name is 23 bytes -- Maximum length of password is 15 bytes -- Maximum number of rows depends on the storage space only. -- Maximum number of tables depends on the number of nodes only. -- Maximum number of databases depends on the number of nodes only. -- Maximum number of vnodes for single database is 64. - -## Restrictions of `GROUP BY` - -`GROUP BY` can be performed on tags and `TBNAME`. It can be performed on data columns too, with one restriction that only one column and the number of unique values on that column is lower than 100,000. Please be noted that `GROUP BY` can't be performed on float or double type. - -## Restrictions of `IS NOT NULL` - -`IS NOT NULL` can be used on any data type of columns. The non-empty string evaluation expression, i.e. `<\>""` can only be used on non-numeric data types. - -## Restrictions of `ORDER BY` - -- Only one `order by` is allowed for normal table and sub table. -- At most two `order by` are allowed for STable, and the second one must be `ts`. -- `order by tag` must be used with `group by tag` on same tag, this rule is also applicable to `tbname`. -- `order by column` must be used with `group by column` or `top/bottom` on same column. This rule is applicable to table and STable. -- `order by ts` is applicable to table and STable. -- If `order by ts` is used with `group by`, the result set is sorted using `ts` in each group. - -## Restrictions of Table/Column Names - -### Name Restrictions of Table/Column - -The name of a table or column can only be composed of ASCII characters, digits and underscore, while digit can't be used as the beginning. The maximum length is 192 bytes. Names are case insensitive. The name mentioned in this rule doesn't include the database name prefix and the separator. - -### Name Restrictions After Escaping - -To support more flexible table or column names, new escape character "`" is introduced in TDengine to avoid the conflict between table name and keywords and break the above restrictions for table name. The escape character is not counted in the length of table name. - -With escaping, the string inside escape characters are case sensitive, i.e. will not be converted to lower case internally. - -For example: -\`aBc\` and \`abc\` are different table or column names, but "abc" and "aBc" are same names because internally they are all "abc". - -:::note -The characters inside escape characters must be printable characters. - -::: - -### Applicable Versions - -Escape character "\`" is available from version 2.3.0.1. diff --git a/docs-en/12-taos-sql/10-json.md b/docs-en/12-taos-sql/10-json.md deleted file mode 100644 index bd9606a84ec2ce0860203414e22d67cbb3330db6..0000000000000000000000000000000000000000 --- a/docs-en/12-taos-sql/10-json.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -sidebar_label: JSON -title: JSON Type ---- - -## Syntax - -1. Tag of JSON type - - ```sql - create STable s1 (ts timestamp, v1 int) tags (info json); - - create table s1_1 using s1 tags ('{"k1": "v1"}'); - ``` - -2. -> Operator of JSON - - ```sql - select * from s1 where info->'k1' = 'v1'; - - select info->'k1' from s1; - ``` - -3. contains Operator of JSON - - ```sql - select * from s1 where info contains 'k2'; - - select * from s1 where info contains 'k1'; - ``` - -## Applicable Operations - -1. When JSON data type is used in `where`, `match/nmatch/between and/like/and/or/is null/is no null` can be used but `in` can't be used. - - ```sql - 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. Tag of JSON type can be used in `group by`, `order by`, `join`, `union all` and sub query, for example `group by json->'key'` - -3. `Distinct` can be used with tag of JSON type - - ```sql - select distinct info->'k1' from s1; - ``` - -4. Tag Operations - - The value of JSON tag can be altered. Please be noted that the full JSON will be override when doing this. - - The name of JSON tag can be altered. A tag of JSON type can't be added or removed. The column length of a JSON tag can't be changed. - -## Other Restrictions - -- JSON type can only be used for tag. There can be only one tag of JSON type, and it's exclusive to any other types of tag. - -- The maximum length of keys in JSON is 256 bytes, and key must be printable ASCII characters. The maximum total length of a JSON is 4,096 bytes. - -- JSON format： - - - The input string for JSON can be empty, i.e. "", "\t", or NULL, but can't be non-NULL string, bool or array. - - object can be {}, and the whole JSON is empty if so. Key can be "", and it's ignored if so. - - value can be int, double, string, boll or NULL, can't be array. Nesting is not allowed, that means value can't be another JSON. - - If one key occurs twice in JSON, only the first one is valid. - - Escape characters are not allowed in JSON. - -- NULL is returned if querying a key that doesn't exist in JSON. - -- If a tag of JSON is the result of inner query, it can't be parsed and queried in the outer query. - -For example, below SQL statements are not supported. - -```sql; -select jtag->'key' from (select jtag from STable); -select jtag->'key' from (select jtag from STable) where jtag->'key'>0; -``` diff --git a/docs-en/12-taos-sql/11-escape.md b/docs-en/12-taos-sql/11-escape.md deleted file mode 100644 index 1b09a0416de28d0106e4bc2b0176c90260249e67..0000000000000000000000000000000000000000 --- a/docs-en/12-taos-sql/11-escape.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -sidebar-label: Escape -title: Escape ---- - -## Escape Characters - -| Escape Character | **Actual Meaning** | -| :--------------: | ------------------------ | -| `\'` | Single quote ' | -| `\"` | Double quote " | -| \n | Line Break | -| \r | Carriage Return | -| \t | tab | -| `\\` | Back Slash \ | -| `\%` | % see below for details | -| `\_` | \_ see below for details | - -:::note -Escape characters are available from version 2.4.0.4 . - -::: - -## Restrictions - -1. If there are escape characters in identifiers (database name, table name, column name) - - Identifier without ``: Error will be returned because identifier must be constituted of digits, ASCII characters or underscore and can't be started with digits - - Identifier quoted with ``： Original content is kept, no escaping -2. If there are escape characters in values - - The escape characters will be escaped as the above table. If the escape character doesn't match any supported one, the escape character "\" will be ignored. - - "%" and "\_" are used as wildcards in `like`. `\%` and `\_` should be used to represent literal "%" and "\_" in `like`,. If `\%` and `\_` are used out of `like` context, the evaluation result is "`\%`"and "`\_`", instead of "%" and "\_". diff --git a/docs-en/12-taos-sql/12-keywords.md b/docs-en/12-taos-sql/12-keywords.md deleted file mode 100644 index b124024feb9f7bd679e6d5185a8705c08b85f2f7..0000000000000000000000000000000000000000 --- a/docs-en/12-taos-sql/12-keywords.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -sidebar_label: Keywords -title: Reserved Keywords ---- - -## Reserved Keywords - -There are about 200 keywords reserved by TDengine, they can't be used as the name of database, STable or table with either upper case, lower case or mixed case. - -**Keywords List** - -| | | | | | -| ----------- | ---------- | --------- | ---------- | ------------ | -| 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-en/12-taos-sql/_category_.yml b/docs-en/12-taos-sql/_category_.yml deleted file mode 100644 index 0bfd46c860da0afdade1ad12e04f02737c39cedc..0000000000000000000000000000000000000000 --- a/docs-en/12-taos-sql/_category_.yml +++ /dev/null @@ -1 +0,0 @@ -label: SQL diff --git a/docs-en/12-taos-sql/index.md b/docs-en/12-taos-sql/index.md deleted file mode 100644 index 8b46a8a0bbb14449dec2dd88a718938d809b744c..0000000000000000000000000000000000000000 --- a/docs-en/12-taos-sql/index.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: TAOS SQL -description: "The syntax, select, functions and tips supported by TAOS SQL " ---- - -This document explains the syntax, select, functions and some tips that can be used in TAOS SQL. It would be easier to understand with some fundamental knowledge of SQL. - -TAOS SQL is the major interface for users to write data into or query from TDengine. For users to easily use, syntax similar to standard SQL is provided. However, please be noted that TAOS SQL is not standard SQL. Besides, because TDengine doesn't provide the functionality of deleting time series data, corresponding statements are not provided in TAOS SQL. - -TAOS SQL doesn't support abbreviation for keywords, for example `DESCRIBE` can't be abbreviated as `DESC`. - -Syntax Specifications used in this chapter: - -- The content inside <\> needs to be input by the user, excluding <\> itself. -- \[ \] means optional input, excluding [] itself. -- | means one of a few options, excluding | itself. -- … means the item prior to it can be repeated multiple times. - -To better demonstrate the syntax, usage and rules of TAOS SQL, hereinafter it's assumed that there is a data set of meters. Assuming each meter collects 3 data: current, voltage, phase. The data model is as below: - -```sql -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 | -``` - -The data set includes the data collected by 4 meters, the corresponding table name is d1001, d1002, d1003, d1004 respectively based on the data model of TDengine. diff --git a/docs-en/13-operation/01-pkg-install.md b/docs-en/13-operation/01-pkg-install.md deleted file mode 100644 index 00802506e681a9e27e338fef363e4157379c5a85..0000000000000000000000000000000000000000 --- a/docs-en/13-operation/01-pkg-install.md +++ /dev/null @@ -1,282 +0,0 @@ ---- -title: Install & Uninstall -description: Install, Uninstall, Start, Stop and Upgrade ---- - -import Tabs from "@theme/Tabs"; -import TabItem from "@theme/TabItem"; - -TDengine community version provides dev and rpm package for users to choose based on the system environment. deb supports Debian, Ubuntu and systems derived from them. rpm supports CentOS, RHEL, SUSE and systems derived from them. Furthermore, tar.gz package is provided for enterprise customers. - -## Install - - - - -1. Download deb package from official website, for example TDengine-server-2.4.0.7-Linux-x64.deb -2. In the directory where the package is located, execute below command - -```bash -$ 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. Download rpm package from official website, for example TDengine-server-2.4.0.7-Linux-x64.rpm； -2. In the directory where the package is located, execute below command - -``` -$ 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. Download the tar.gz package, for example TDengine-server-2.4.0.7-Linux-x64.tar.gz； - 2、In the directory where the package is located, firstly decompress the file, then switch to the sub-directory generated in decompressing, i.e. "TDengine-enterprise-server-2.4.0.7/" in this example, and execute the `install.sh` script. - -```bash -$ 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 -Some configuration will be prompted for users to provide when install.sh is executing, the interactive mode can be disabled by executing `./install.sh -e no`. `./install -h` can show all parameters and detailed explanation. - -::: - - - - -:::note -When installing on the first node in the cluster, when "Enter FQDN:" is prompted, nothing needs to be provided. When installing on following nodes, when "Enter FQDN:" is prompted, the end point of the first dnode in the cluster can be input if it has been already up; or just ignore it and configure later after installation is done. - -::: - -## Uninstall - - - - -Deb package of TDengine can be uninstalled as below: - -```bash -$ sudo dpkg -r tdengine -(Reading database ... 137504 files and directories currently installed.) -Removing tdengine (2.4.0.7) ... -TDengine is removed successfully! - -``` - - - - - -RPM package of TDengine can be uninstalled as below: - -``` -$ sudo rpm -e tdengine -TDengine is removed successfully! -``` - - - - - -tar.gz package of TDengine can be uninstalled as below: - -``` -$ rmtaos -Nginx for TDengine is running, stopping it... -TDengine is removed successfully! - -taosKeeper is removed successfully! -``` - - - - -:::note - -- It's strongly suggested not to use multiple kinds of installation packages on single host TDengine -- After deb package is installed, if the installation directory is removed manually so that uninstall or reinstall can't succeed, it can be resolved by cleaning up TDengine package information as below command and then reinstalling. - -```bash - $ sudo rm -f /var/lib/dpkg/info/tdengine* -``` - -- After rpm package is installed, if the installation directory is removed manually so that uninstall or reinstall can't succeed, it can be resolved by cleaning up TDengine package information as below command and then reinstalling. - -```bash - $ sudo rpm -e --noscripts tdengine -``` - -::: - -## Installation Directory - -TDengine is installed at /usr/local/taos if successful. - -```bash -$ 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/ -``` - -During the installation process: - -- Configuration directory, data directory, and log directory are created automatically if they don't exist -- The default configuration file is located at /etc/taos/taos.cfg, which is a copy of /usr/local/taos/cfg/taos.cfg if not existing -- The default data directory is /var/lib/taos, which is a soft link to /usr/local/taos/data -- The default log directory is /var/log/taos, which is a soft link to /usr/local/taos/log -- The executables at /usr/local/taos/bin are linked to /usr/bin -- The DLL files at /usr/local/taos/driver are linked to /usr/lib -- The header files at /usr/local/taos/include are linked to /usr/include - -:::note - -- When TDengine is uninstalled, the configuration /etc/taos/taos.cfg, data directory /var/lib/taos, log directory /var/log/taos are kept. They can be deleted manually with caution because data can't be recovered once -- When reinstalling TDengine, if the default configuration file /etc/taos/taos.cfg exists, it will be kept and the configuration file in the installation package will be renamed to taos.cfg.orig and stored at /usr/loca/taos/cfg to be used as configuration sample. Otherwise the configuration file in the installation package will be installed to /etc/taos/taos.cfg and used. - -## Start and Stop - -Linux system services `systemd`, `systemctl` or `service` is used to start, stop and restart TDengine. The server process of TDengine is `taosd`, which is started automatically after the Linux system is started. System operator can use `systemd`, `systemctl` or `service` to start, stop or restart TDengine server. - -For example, if using `systemctl` , the commands to start, stop, restart and check TDengine server are as below: - -- Start server：`systemctl start taosd` - -- Stop server：`systemctl stop taosd` - -- Restart server：`systemctl restart taosd` - -- Check server status：`systemctl status taosd` - -From version 2.4.0.0, a new independent component named as `taosAdapter` has been included in TDengine. `taosAdapter` should be started and stopped using `systemctl`. - -If the server process is OK, the output of `systemctl status` is like below: - -``` -Active: active (running) -``` - -Otherwise, the output is as below: - -``` -Active: inactive (dead) -``` - -## Upgrade - -There are two aspects in upgrade operation: upgrade installation package and upgrade a running server. - -Upgrading package should follow the steps mentioned previously to firstly uninstall old version then install new version. - -Upgrading a running server is much more complex. Firstly please check the version number of old version and new version. The version number of TDengine consists of 4 sections, only the first 3 section match can the old version be upgraded to the new version. The steps of upgrading a running server are as below: - -- Stop inserting data -- Make sure all data persisted into disk -- Stop the cluster of TDengine -- Uninstall old version and install new version -- Start the cluster of TDengine -- Make some simple queries to make sure no data loss -- Make some simple data insertion to make sure the cluster works well -- Restore business data - -:::warning -TDengine doesn't guarantee any lower version is compatible with the data generated by a higher version, so it's never recommended to downgrade the version. - -::: diff --git a/docs-en/13-operation/02-planning.mdx b/docs-en/13-operation/02-planning.mdx deleted file mode 100644 index 4f08695c1eb39266a9796ee42335fa653c76a0fa..0000000000000000000000000000000000000000 --- a/docs-en/13-operation/02-planning.mdx +++ /dev/null @@ -1,83 +0,0 @@ ---- -sidebar_label: Planning -title: Capacity Planning ---- - -The computing and storage resources need to be planned if using TDengine to build an IoT platform. How to plan the CPU, memory and disk required will be described in this chapter. - -## Memory Requirement of Server Side - -The number of vgroups created for each database is same as the number of CPU cores by default and can be configured by parameter `maxVgroupsPerDb`, each vnode in a vgroup stores one replica. Each vnode consumes fixed size of memory, i.e. `blocks` \* `cache`. Besides, some memory is required for tag values associated with each table. A fixed amount of memory is required for each cluster. So, the memory required for each DB can be calculated using below formula: - -``` -Database Memory Size = maxVgroupsPerDb * replica * (blocks * cache + 10MB) + numOfTables * (tagSizePerTable + 0.5KB) -``` - -For example, assuming the default value of `maxVgroupPerDB` is 64, the default value of `cache` 16M, the default value of `blocks` is 6, there are 100,000 tables in a DB, the replica number is 1, total length of tag values is 256 bytes, the total memory required for this DB is: 并且一个 DB 中有 10 万张表，单副本，标签总长度是 256 字节，则这个 DB 总的内存需求为：64 \* 1 \* (16 \* 6 + 10) + 100000 \* (0.25 + 0.5) / 1000 = 6792M. - -In real operation of TDengine, we are more concerned about the memory used by each TDengine server process `taosd`.在 - -``` - taosd_memory = vnode_memory + mnode_memory + query_memory -``` - -In the above formula: - -1. "vnode_memory" of a `taosd` process is the memory used by all vnodes hosted by this `taosd` process. It can be roughly calculated by firstly adding up the total memory of all DBs whose memory usage can be derived according to the formula mentioned previously then dividing by number of dnodes and multiplying the number of replicas. - -``` - vnode_memory = sum(Database memory) / number_of_dnodes \* replica -``` - -2. "mnode_memory" of a `taosd` process is the memory consumed by a mnode. If there is one (and only one) mnode hosted in a `taosd` process, the memory consumed by "mnode" is "0.2KB \* the total number of tables in the cluster". - -3. "query_memory" is the memory used when processing query requests. Each ongoing query consumes at least "0.2 KB \* total number of involved tables". - -Please be noted that the above formulas can only be used to estimate the minimum memory requirement, instead of maximum memory usage. In a real production environment, it's better to preserve some redundance beyond the estimated minimum memory requirement. If memory is abundant, it's suggested to increase the value of parameter `blocks` to speed up data insertion and data query. - -## Memory Requirement of Client Side - -The client programs use TDengine client driver `taosc` to connect to the server side, there is also memory requirement for a client program. - -The memory consumed by a client program is mainly about the SQL statements for data insertion, caching of table metadata, and some internal use. Assuming maximum number of tables is N (the memory consumed by the metadata of each table is 256 bytes), maximum number of threads for parallel insertion is T, maximum length of a SQL statement is S (normally 1 MB), the memory required by a client program can be estimated using below formula: - -``` -M = (T * S * 3 + (N / 4096) + 100) -``` - -For example, if the number of parallel data insertion threads is 100, total number of tables is 10,000,000, then minimum memory requirement of a client program is: - -``` -100 * 3 + (10000000 / 4096) + 100 = 2741 (MBytes) -``` - -So, at least 3GB needs to be reserved for such a client. - -## CPU Requirement - -The CPU resources required depend on two aspects: - -- **Data Insertion** Each dnode of TDengine can process at least 10,000 insertion requests in one second, while each insertion request can have multiple rows. The computing resource consumed between inserting 1 row one time and inserting 10 rows one time is very small. So, the more the rows to insert one time, the higher the efficiency. Inserting in bach also exposes requirement for the client side which needs to cache rows and insert in batch once the cached rows reaches a threshold. -- **Data Query** High efficiency query is provided in TDengine, but it's hard to estimate the CPU resource required because the queries used in different use cases and the frequency of queries vary significantly. It can only be verified with the query statements, query frequency, data size to be queried, etc provided by user. - -In short words, the CPU resource required for data insertion can be estimated but it's hard to do so for query use cases. In real operation, it's suggested to control CPU usage below 50%. If this threshold is exceeded, it's a reminder for system operator to add more nodes in the cluster to expand resources. - -## Disk Requirement - -The compression ratio in TDengine is much higher than that in RDBMS. In most cases, the compression ratio in TDengine is bigger than 5, or even 10 in some cases, depending on the characteristics of the original data. The data size before compression can be calculated based on below formula: - -``` -Raw DataSize = numOfTables * rowSizePerTable * rowsPerTable -``` - -For example, there are 10,000,000 meters, while each meter collects data every 15 minutes and the data size of each collection si 128 bytes, so the raw data size of one year is: 10000000 \* 128 \* 24 \* 60 / 15 \* 365 = 44.8512(TB). Assuming compression ratio is 5, the actual disk size is: 44.851 / 5 = 8.97024(TB). - -Parameter `keep` can be used to set how long the data will be kept on disk. To further reduce storage cost, multiple storage levels can be enabled in TDengine, with the coldest data stored on the cheapest storage device, and this is transparent to application programs. - -To increase the performance, multiple disks can be setup for parallel data reading or data inserting. Please be noted that expensive disk array is not necessary because replications are used in TDengine to provide high availability. - -## Number of Hosts - -A host can be either physical or virtual. The total memory, total CPU, total disk required can be estimated according to the formulas mentioned previously. Then, according to the system resources that a single host can provide, assuming all hosts are same in resources, the number of hosts can be derived easily. - -**Quick Estimation for CPU, Memory and Disk** Please refer to [Resource Estimate](https://www.taosdata.com/config/config.html). diff --git a/docs-en/13-operation/03-tolerance.md b/docs-en/13-operation/03-tolerance.md deleted file mode 100644 index 7293a45b4f9a1a5028c890553ba750617e77cebc..0000000000000000000000000000000000000000 --- a/docs-en/13-operation/03-tolerance.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -sidebar_label: Tolerance -title: Tolerance and Disaster Recovery ---- - -## Tolerance - -TDengine uses **WAL**, i.e. Write Ahead Log, to achieve fault tolerance and make sure high availability. - -When a data block is received by TDengine, the original data block is firstly written into WAL. The log in WAL will be deleted only after the data has been written into data files in the database. Data can be recovered from WAL in case the server is stopped abnormally due to any reason and then restarted. - -There are 2 configuration parameters related to WAL: - -- walLevel：0：wal is disabled; 1：wal is enabled without fsync; 2：wal is enabled with fsync. -- fsync：only valid when walLevel is set to 2, it specified the interval of invoking fsync. If set to 0, it means fsync is invoked immediately once WAL is written. - -To achieve absolutely no data loss, walLevel needs to be set to 2 and fsync needs to be set to 1. The penalty is the speed of data insertion downgrades. However, if the concurrent threads of data insertion on the client side can reach a big enough number, for example 50, the data insertion performance would be still good enough, our verification shows that the drop is only 30% compared to fsync is set to 3,000 milliseconds. - -## Disaster Recovery - -TDengine uses replications to provide high availability and disaster recovery capability. - -TDengine cluster is managed by mnode. To make sure the high availability of mnode, multiple replicas can be configured by system parameter `numOfMnodes`. The data replication between mnode replicas is in synchronous way to guarantee the metadata consistency. - -The number of replicas for time series data in TDengine is associated with each database, there can be a lot of databases in a cluster while each database can be configured with a different number of replicas. When creating a database, parameter `replica` is used to configure the number of replications. To achieve high availability, `replica` needs to be higher than 1. - -The number of dnodes in a TDengine cluster must NOT be lower than the number of replicas for any database, otherwise it would fail when trying to create table.集 - -As long as the dnodes of a TDengine cluster are deployed on different physical machines and replica number is set to bigger than 1, high availability can be achieved without any other assistance. If dnodes of TDengine cluster are deployed in geographically different data centers, disaster recovery can be achieved too. diff --git a/docs-en/13-operation/06-admin.md b/docs-en/13-operation/06-admin.md deleted file mode 100644 index 1ca0dfeaf4a4b0b4c597e1a5ec6ece20224e2dba..0000000000000000000000000000000000000000 --- a/docs-en/13-operation/06-admin.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: User Management ---- - -System operator can use TDengine CLI `taos` to create or remove user or change password. The SQL command is as low: - -## Create User - -```sql -CREATE USER PASS <'password'>; -``` - -When creating a user and specifying the user name and password, password needs to be quoted using single quotes. - -## Drop User - -```sql -DROP USER ; -``` - -Drop a user can only be performed by root. - -## Change Password - -```sql -ALTER USER PASS <'password'>; -``` - -To keep the case of the password when changing password, password needs to be quoted using single quotes. - -## Change Privilege - -```sql -ALTER USER PRIVILEGE ; -``` - -The privileges that can be changed to are `read` or `write` without single quotes. - -Note：there is another privilege `super`, which not allowed to be authorized to any user. - -## Show Users - -```sql -SHOW USERS; -``` - -:::note -In SQL syntax, `< >` means the part that needs to be input by user, excluding the `< >` itself. - -::: diff --git a/docs-en/13-operation/07-import.md b/docs-en/13-operation/07-import.md deleted file mode 100644 index 1577c17cc54a672948a7686c8f6303ee293f22b4..0000000000000000000000000000000000000000 --- a/docs-en/13-operation/07-import.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -sidebar_label: Import -title: Import Data ---- - -There are multiple ways of importing data provided byTDengine: import with script, import from data file, import using `taosdump`. - -## Import Using Script - -TDengine CLI `taos` supports `source ` command for executing the SQL statements in the file in batch. The SQL statements for creating databases, creating tables, and inserting rows can be written in single file with one statement on each line, then the file can be executed using `source` command in TDengine CLI `taos` to execute the SQL statements in order and in batch. In the script file, any line beginning with "#" is treated as comments and ignored silently. - -## Import from Data File - -In TDengine CLI, data can be imported from a CSV file into an existing table. The data in single CSV must belong to same table and must be consistent with the schema of that table. The SQL statement is as below:也 - -```sql -insert into tb1 file 'path/data.csv'; -``` - -:::note -If there is description in the first line of a CSV file, please remove it before importing. If there is no value for a column, please use `NULL` without quotes. - -::: - -For example, there is a sub table d1001 whose schema is as below: - -```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 | -``` - -The format of the CSV file to be imported, data.csv, is as below: - -```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 -``` - -Then, below SQL statement can be used to import data from file "data.csv", assuming the file is located under the home directory of current Linux user. - -```sql -taos> insert into d1001 file '~/data.csv'; -Query OK, 9 row(s) affected (0.004763s) -``` - -## Import using taosdump - -A convenient tool for importing and exporting data is provided by TDengine, `taosdump`, which can used to export data from one TDengine cluster and import into another one. For the details of using `taosdump` please refer to [Tool for exporting and importing data: taosdump](/reference/taosdump). diff --git a/docs-en/13-operation/08-export.md b/docs-en/13-operation/08-export.md deleted file mode 100644 index 0e84ee0d25ce539e9efe25d0956f950f9fd5f2aa..0000000000000000000000000000000000000000 --- a/docs-en/13-operation/08-export.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -sidebar_label: Export -title: Export Data ---- - -There are two ways of exporting data from a TDengine cluster, one is SQL statement in TDengine CLI, the other one is `taosdump`. - -## Export Using SQL - -If you want to export the data of a table or a STable, please execute below SQL statement in TDengine CLI. - -```sql -select * from >> data.csv; -``` - -The data of table or STable specified by `tb_name` will be exported into a file named `data.csv` in CSV format. - -## Export Using taosdump - -With `taosdump`, you can choose to export the data of all databases, a database, a table or a STable, you can also choose export the data within a time range, or even only export the schema definition of a table. For the details of using `taosdump` please refer to [Tool for exporting and importing data: taosdump](/reference/taosdump). diff --git a/docs-en/13-operation/09-status.md b/docs-en/13-operation/09-status.md deleted file mode 100644 index 3f3c6c9f1e86f9f33bafc7edfd79bebb175871cc..0000000000000000000000000000000000000000 --- a/docs-en/13-operation/09-status.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -sidebar_label: Connections & Tasks -title: Manage Connections and Query Tasks ---- - -System operator can use TDengine CLI to show the connections, ongoing queries, stream computing, and can close connection or stop ongoing query task or stream computing. - -## Show Connections - -```sql -SHOW CONNECTIONS; -``` - -One column of the output of the above SQL command is "ip:port", which is the end point of the client. - -## Close Connections Forcedly - -```sql -KILL CONNECTION ; -``` - -In the above SQL command, `connection-id` is from the first column of the output of `SHOW CONNECTIONS`. - -## Show Ongoing Queries - -```sql -SHOW QUERIES; -``` - -The first column of the output is query ID, which is composed of the corresponding connection ID and the sequence number of the current query task started on this connection, in format of "connection-id:query-no". - -## Close Queries Forcedly - -```sql -KILL QUERY ; -``` - -In the above SQL command, `query-id` is from the first column of the output of `SHOW QUERIES `. - -## Show Continuous Query - -```sql -SHOW STREAMS; -``` - -The first column of the output is stream ID, which is composed of the connection ID and the sequence number of the current stream started on this connection, in the format of "connection-id:stream-no". - -## Close Continuous Query Forcedly - -```sql -KILL STREAM ; -``` - -The the above SQL command, `stream-id` is from the first column of the output of `SHOW STREAMS`. diff --git a/docs-en/13-operation/10-monitor.md b/docs-en/13-operation/10-monitor.md deleted file mode 100644 index 738086ebe24026526713574a513342d615662e83..0000000000000000000000000000000000000000 --- a/docs-en/13-operation/10-monitor.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -sidebar_label: Monitor -title: Monitor TDengine ---- - -After TDengine is started, a database named `log` for monitoring is created automatically. The information about CPU, memory, disk, bandwidth, number of requests, disk I/O speed, slow query is written into `log` database on the basis of a predefined interval. Besides, some important system operations, like logon, create user, drop database, and alerts and warnings generated in TDengine are written into `log` database too. System operator can view the data in `log` database from TDengine CLI or from a web console. - -Collection of the monitoring information is enabled by default, but can be disabled by parameter `monitor` in configuration file. - -## TDinsight - -TDinsight is a total solution which uses the monitor database `log` mentioned previously and Grafana to monitor a TDengine cluster. - -From version 2.3.3.0, more monitoring data has been added in the `log` database. Please refer to [TDinsight Grafana Dashboard](https://grafana.com/grafana/dashboards/15167) to learn more details about using TDinsight to monitor TDengine. - -A script `TDinsight.sh` is provided to deploy TDinsight in automatic way. - -Download `TDinsight.sh` with below command: - -```bash -wget https://github.com/taosdata/grafanaplugin/raw/master/dashboards/TDinsight.sh -chmod +x TDinsight.sh -``` - -Prepare： - -1. TDengine Server - - - The URL of REST service：for example `http://localhost:6041` if TDengine is deployed locally - - User name and password - -2. Grafana Alert Notification - -There are two ways to setup Grafana alert notification. - -- An existing Grafana Notification Channel can be specified with parameter `-E`, the notifier uid of the channel can be obtained by `curl -u admin:admin localhost:3000/api/alert-notifications |jq` - - ```bash - sudo ./TDinsight.sh -a http://localhost:6041 -u root -p taosdata -E - ``` - -- The AliClund SMS alert built in TDengine data source plugin can be enabled with parameter `-s`, the parameters of this way are as follows: - - - `-I`: AliCloud SMS Key ID - - `-K`: AliCloud SMS Key Secret - - `-S`: AliCloud SMS Signature - - `-C`: SMS notification template - - `-T`: Input parameters in JSON format for the SMS notification template, for example`{"alarm_level":"%s","time":"%s","name":"%s","content":"%s"}` - - `-B`: List of mobile numbers to be notified - - Below is an example of the full command using this way. - - ```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"}' - ``` - -Launch `TDinsight.sh` as above command and restart Grafana, then open Dashboard `http://localhost:3000/d/tdinsight`. - -For more use cases and restrictions please refer to [TDinsight](/reference/tdinsight/). diff --git a/docs-en/13-operation/11-optimize.md b/docs-en/13-operation/11-optimize.md deleted file mode 100644 index a3c5df633b473fa24cedac2a28ebdf830e2ed34c..0000000000000000000000000000000000000000 --- a/docs-en/13-operation/11-optimize.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -sidebar_label: Optimize -title: Optimize Performance ---- - -After a TDengine cluster has been running for long enough time, because of updating data, deleting tables and deleting expired data, there may be fragments in data files and query performance may be impacted. To resolve the problem of fragments, from version 2.1.3.0 a new SQL command `COMPACT` can be used to defragment the data files. - -```sql -COMPACT VNODES IN (vg_id1, vg_id2, ...) -``` - -`COMPACT` can be used to defragment one or more vgroups. The defragmentation work will be put in task queue for scheduling execution by TDengine. `SHOW VGROUPS` command can be used to get the vgroup ids to be used in `COMPACT` command. There is a column `compacting` in the output of `SHOW GROUPS` to indicate the compacting status of the vgroup: 2 means the vgroup is waiting in task queue for compacting, 1 means compacting is in progress, and 0 means the vgroup has nothing to do with compacting. - -Please be noted that a lot of disk I/O is required for defragementation operation, during which the performance may be impacted significantly for data insertion and query, data insertion may be blocked shortly in extreme cases. - -## Optimize Storage Parameters - -The data in different use cases may have different characteristics, such as the days to keep, number of replicas, collection interval, record size, number of collection points, compression or not, etc. To achieve best efficiency in storage, the parameters in below table can be used, all of them can be either configured in `taos.cfg` as default configuration or in the command `create database`. For detailed definition of these parameters please refer to [Configuration Parameters](/reference/config/). - -| # | Parameter | Unit | Definition | **Value Range** | **Default Value** | -| --- | --------- | ---- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- | ----------------- | -| 1 | days | Day | The time range of the data stored in a single data file | 1-3650 | 10 | -| 2 | keep | Day | The number of days the data is kept in the database | 1-36500 | 3650 | -| 3 | cache | MB | The size of each memory block | 1-128 | 16 | -| 4 | blocks | None | The number of memory blocks used by each vnode | 3-10000 | 6 | -| 5 | quorum | None | The number of required confirmation in case of multiple replicas | 1-2 | 1 | -| 6 | minRows | None | The minimum number of rows in a data file | 10-1000 | 100 | -| 7 | maxRows | None | The maximum number of rows in a daa file | 200-10000 | 4096 | -| 8 | comp | None | Whether to compress the data | 0：uncompressed; 1: One Phase compression; 2: Two Phase compression | 2 | -| 9 | walLevel | None | wal sync level (named as "wal" in create database ) | 1：wal enabled without fsync; 2：wal enabled with fsync | 1 | -| 10 | fsync | ms | The time to wait for invoking fsync when walLevel is set to 2; 0 means no wait | 3000 | -| 11 | replica | none | The number of replications | 1-3 | 1 | -| 12 | precision | none | Time precision | ms: millisecond; us: microsecond;ns: nanosecond | ms | -| 13 | update | none | Whether to allow updating data | 0: not allowed; 1: a row must be updated as whole; 2: a part of columns in a row can be updated | 0 | -| 14 | cacheLast | none | Whether the latest data of a table is cached in memory | 0: not cached; 1: the last row is cached; 2: the latest non-NULL value of each column is cached | 0 | - -For a specific use case, there may be multiple kinds of data with different characteristics, it's best to put data with same characteristics in same database. So there may be multiple databases in a system while each database can be configured with different storage parameters to achieve best performance. The above parameters can be used when creating a database to override the default setting in configuration file. - -```sql - CREATE DATABASE demo DAYS 10 CACHE 32 BLOCKS 8 REPLICA 3 UPDATE 1; -``` - -The above SQL statement creates a database named as `demo`, in which each data file stores data across 10 days, the size of each memory block is 32 MB and each vnode is allocated with 8 blocks, the replica is set to 3, update operation is allowed, and all other parameters not specified in the command follow the default configuration in `taos.cfg`. - -Once a database is created, only some parameters can be changed and be effective immediately while others are can't. - -| **Parameter** | **Alterable** | **Value Range** | **Syntax** | -| ------------- | ------------- | ---------------- | -------------------------------------- | -| name | | | | -| create time | | | | -| ntables | | | | -| vgroups | | | | -| replica | **YES** | 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_ | - -**Explanation：** Prior to version 2.1.3.0, `taosd` server process needs to be restarted for these parameters to take in effect if they are changed using `ALTER DATABASE`. - -When trying to join a new dnode into a running TDengine cluster, all the parameters related to cluster in the new dnode configuration must be consistent with the cluster, otherwise it can't join the cluster. The parameters that are checked when joining a dnode are as below. For detailed definition of these parameters please refer to [Configuration Parameters](/reference/config/). - -- numOfMnodes -- mnodeEqualVnodeNum -- offlineThreshold -- statusInterval -- maxTablesPerVnode -- maxVgroupsPerDb -- arbitrator -- timezone -- balance -- flowctrl -- slaveQuery -- adjustMaster - -For the convenience of debugging, the log setting of a dnode can be changed temporarily. The temporary change will be lost once the server is restarted. - -```sql -ALTER DNODE -``` - -- dnode_id: from output of "SHOW DNODES" -- config: the parameter to be changed, as below - - resetlog: close the old log file and create the new on - - debugFlag: 131 (INFO/ERROR/WARNING), 135 (DEBUG), 143 (TRACE) - -For example - -``` -alter dnode 1 debugFlag 135; -``` diff --git a/docs-en/13-operation/17-diagnose.md b/docs-en/13-operation/17-diagnose.md deleted file mode 100644 index bbf6b55bf5eb1a685473c826ca789839014a3c9a..0000000000000000000000000000000000000000 --- a/docs-en/13-operation/17-diagnose.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -sidebar_label: Diagnose -title: Diagnose Problems ---- - -## Diagnose Network Connection - -When the client is unable to access the server, the network connection between the client side and the server side needs to be checked to find out the root cause and resolve problems. - -The diagnostic for network connection can be executed between Linux and Linux or between Linux and Windows. - -Diagnostic steps： - -1. If the port range to be diagnosed are being occupied by a `taosd` server process, please firstly stop `taosd. -2. On the server side, execute command `taos -n server -P -l ` to monitor the port range starting from the port specified by `-P` parameter with the role of "server. -3. On the client side, execute command `taos -n client -h -P -l ` to send testing package to the specified server and port. - --l ： The size of the testing package, in bytes. The value range is [11, 64,000] and default value is 1,000. Please be noted that the package length must be same in the above 2 commands executed on server side and client side respectively. - -Output of the server side is as below for example: - -```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 -``` - -Output of the client side is as below for example: - -```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 -``` - -The output needs to be checked carefully for the system operator to find out root cause and solve the problem. - -## Startup Status and RPC Diagnostic - -`taos -n startup -h ` can be used to check the startup status of a `taosd` process. This is a comman task for a system operator to do to determine whether `taosd` has been started successfully, especially in case of cluster. - -`taos -n rpc -h ` can be used to check whether the port of a started `taosd` can be accessed or not. If `taosd` process doesn't respond or work abnormally, this command can be used to initiate a rpc communication with the specified fqdn to determine whether it's network problem or `taosd` is abnormal. - -## Sync and Arbitrator Diagnostic - -```bash -taos -n sync -P 6040 -h -taos -n sync -P 6042 -h -``` - -The above commands can be executed on Linux Shell to check whether the port for sync works well and whether the sync module of the server side works well. Besides, `-P 6042` is used to check whether the arbitrator is configured properly and works well. - -## Network Speed Diagnostic - -`taos -n speed -h -P 6030 -N 10 -l 10000000 -S TCP` - -From version 2.2.0.0, the above command can be executed on Linux Shell to test the network speed, it sends uncompressed package to a running `taosd` server process or a simulated server process started by `taos -n server` to test the network speed. Parameters can be used when testing network speed are as below: - --n：When set to "speed", it means testing network speed --h：The FQDN or IP of the server process to be connected to; if not set, the FQDN configured in `taos.cfg` is used --P：The port of the server process to connect to, the default value is 6030 --N：The number of packages that will be sent in the test, range is [1,10000], default value is 100 --l：The size of each package in bytes, range is [1024, 1024 \* 1024 \* 1024], default value is 1024 --S：The type of network packages to send, can be either TCP or UDP, default value is - -## FQDN Resolution Diagnostic - -`taos -n fqdn -h ` - -From version 2.2.0.0, the above command can be executed on Linux Shell to test the resolution speed of FQDN. It can be used to try to resolve a FQDN to an IP address and record the time spent in this process. The parameters that can be used for this purpose are as below: - --n：When set to "fqdn", it means testing the speed of resolving FQDN --h：The FQDN to be resolved. If not set, the `FQDN` parameter in `taos.cfg` is used by default. - -## Server Log - -The parameter `debugFlag` is used to control the log level of `taosd` server process. The default value is 131, for debug purpose it needs to be escalated to 135 or 143. - -Once this parameter is set to 135 or 143, the log file grows very quickly especially when there is huge volume of data insertion and data query requests. If all the logs are stored together, some important information may be missed very easily, so on server side important information is stored at different place from other logs.一 - -- The log at level of INFO, WARNING and ERROR is stored in `taosinfo` so that it is easy to find important information -- The log at level of DEBUG (135) and TRACE (143) and other information not handled by `taosinfo` are stored in `taosdlog` - -## Client Log - -An independent log file, named as "taoslog+" is generated for each client program, i.e. a client process. The default value of `debugfalg` is also 131 and only log at level of INFO/ERROR/WARNING is recorded, it and needs to be changed to 135 or 143 so that log at DEBUG or TRACE level can be recorded for debugging purpose. - -The maximum length of a single log file is controlled by parameter `numOfLogLines` and only 2 log files are kept for each `taosd` server process. - -log file is written in async way to minimize the workload on disk, bu the penalty is that a few log lines may be lost in some extreme conditions. diff --git a/docs-en/13-operation/_category_.yml b/docs-en/13-operation/_category_.yml deleted file mode 100644 index 8d249261ca204200b184d356fa0cdac8d053f4d4..0000000000000000000000000000000000000000 --- a/docs-en/13-operation/_category_.yml +++ /dev/null @@ -1,4 +0,0 @@ -label: Administration -link: - slug: /operation/ - type: generated-index diff --git a/docs-en/14-reference/02-rest-api/02-rest-api.mdx b/docs-en/14-reference/02-rest-api/02-rest-api.mdx deleted file mode 100644 index defa1e094c59622c437924af00ff80492ceda514..0000000000000000000000000000000000000000 --- a/docs-en/14-reference/02-rest-api/02-rest-api.mdx +++ /dev/null @@ -1,307 +0,0 @@ ---- -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)。 - -注意：与原生连接器的一个区别是，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 语句中的数据表应提供数据库前缀，例如 \.\。如果表名不带数据库前缀，又没有在 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 采用 `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 采用 `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：非常详细的调试信息，默认 131。 -- httpDbNameMandatory: 是否必须在 RESTful url 中指定默认的数据库名。默认为 0，即关闭此检查。如果设置为 1，那么每个 RESTful url 中都必须设置一个默认数据库名，否则无论此时执行的 SQL 语句是否需要指定数据库，都会返回一个执行错误，拒绝执行此 SQL 语句。 - -:::note -如果使用 taosd 提供的 REST API, 那么以上配置需要写在 taosd 的配置文件 taos.cfg 中。如果使用 taosAdaper 提供的 REST API, 那么需要参考 taosAdaper [对应的配置方法](/reference/taosadapter/)。 - -::: diff --git a/docs-en/14-reference/03-connector/03-connector.mdx b/docs-en/14-reference/03-connector/03-connector.mdx deleted file mode 100644 index c0e714f148a7821e070be38a5484484fdd747e9a..0000000000000000000000000000000000000000 --- a/docs-en/14-reference/03-connector/03-connector.mdx +++ /dev/null @@ -1,117 +0,0 @@ ---- -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-en/14-reference/03-connector/_linux_install.mdx b/docs-en/14-reference/03-connector/_linux_install.mdx deleted file mode 100644 index 2f54aafafa009e43d3bea5e00d833ec80cc429d5..0000000000000000000000000000000000000000 --- a/docs-en/14-reference/03-connector/_linux_install.mdx +++ /dev/null @@ -1,32 +0,0 @@ -import PkgList from "/components/PkgList"; - -1. Download the TDengine client installation package - - - - [All Packages](https://www.taosdata.com/en/all-downloads/) - -2. Unzip - - Download the package to any directory the current user has read/write permission. Then execute `tar -xzvf TDengine-client-VERSION.tar.gz` command. - The VERSION should be the version of the package you just downloaded. - -3. Execute the install script - - Once the package is unzipped, you will see the following files in the directory: - - _ install_client.sh_: install script - - _ taos.tar.gz_: application driver package - - _ driver_: TDengine application driver - - _examples_: some example programs of different programming languages (C/C#/go/JDBC/MATLAB/python/R) - You can run `install_client.sh` to install it. -4. Edit taos.cfg - - Edit `taos.cfg` file (full path is `/etc/taos/taos.cfg` by default), modify `firstEP` with actual TDengine server's End Point, for example `h1.tdengine.com:6030` - -:::tip - -1. If the computer does not run the TDengine service but installs the TDengine application driver, then you need to config `firstEP` in `taos.cfg` only, and there is no need to configure `FQDN`; - -2. If you encounter the "Unable to resolve FQDN" error, please make sure the FQDN in the `/etc/hosts` file of the current computer is correctly configured or the DNS service is correctly configured. - -::: diff --git a/docs-en/14-reference/03-connector/_preparition.mdx b/docs-en/14-reference/03-connector/_preparition.mdx deleted file mode 100644 index 87538ebfd8c60507aec90ee86e427d85979dbc4a..0000000000000000000000000000000000000000 --- a/docs-en/14-reference/03-connector/_preparition.mdx +++ /dev/null @@ -1,10 +0,0 @@ -- 已安装客户端驱动（使用原生连接必须安装，使用 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-en/14-reference/03-connector/_verify_linux.mdx b/docs-en/14-reference/03-connector/_verify_linux.mdx deleted file mode 100644 index 120ef0e5a72c3e9486d56be282c51ad0d77fb69c..0000000000000000000000000000000000000000 --- a/docs-en/14-reference/03-connector/_verify_linux.mdx +++ /dev/null @@ -1,14 +0,0 @@ -在 Linux shell 下直接执行 `taos` 连接到 TDegine 服务，进入到 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-en/14-reference/03-connector/_windows_install.mdx b/docs-en/14-reference/03-connector/_windows_install.mdx deleted file mode 100644 index 755f96b2d728621de5752ce752e5d249cda0f6d9..0000000000000000000000000000000000000000 --- a/docs-en/14-reference/03-connector/_windows_install.mdx +++ /dev/null @@ -1,31 +0,0 @@ -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-en/14-reference/03-connector/cpp.mdx b/docs-en/14-reference/03-connector/cpp.mdx deleted file mode 100644 index 29aebaed3d8ca852950508ba751b8c86689724ca..0000000000000000000000000000000000000000 --- a/docs-en/14-reference/03-connector/cpp.mdx +++ /dev/null @@ -1,450 +0,0 @@ ---- -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()` - - 清理运行环境，应用退出前应调用此 API。 - -- `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：TDengine 管理主节点的端口号 - - 返回值为空表示失败。应用程序需要保存返回的参数，以便后续 API 调用。 - - :::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，都属于同步操作。应用调用 API 后，一直处于阻塞状态，直到服务端返回结果。 - -- `TAOS_RES* taos_query(TAOS *taos, const char *sql)` - - 该 API 用来执行 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 - -同步 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 返回错误（返回错误码或空指针）时获取错误信息。 - -### 无模式写入 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-en/14-reference/03-connector/csharp.mdx b/docs-en/14-reference/03-connector/csharp.mdx deleted file mode 100644 index bbefaacb459153ab5116d557fdf1940d487b4bd3..0000000000000000000000000000000000000000 --- a/docs-en/14-reference/03-connector/csharp.mdx +++ /dev/null @@ -1,189 +0,0 @@ ---- -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 "../../04-develop/03-insert-data/_cs_sql.mdx" -import CSInfluxLine from "../../04-develop/03-insert-data/_cs_line.mdx" -import CSOpenTSDBTelnet from "../../04-develop/03-insert-data/_cs_opts_telnet.mdx" -import CSOpenTSDBJson from "../../04-develop/03-insert-data/_cs_opts_json.mdx" -import CSQuery from "../../04-develop/04-query-data/_cs.mdx" -import CSAsyncQuery from "../../04-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-en/14-reference/03-connector/go.mdx b/docs-en/14-reference/03-connector/go.mdx deleted file mode 100644 index c5f448916a39acdf7f0ffff01bf431d93f2143b4..0000000000000000000000000000000000000000 --- a/docs-en/14-reference/03-connector/go.mdx +++ /dev/null @@ -1,411 +0,0 @@ ---- -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 "../../04-develop/03-insert-data/_go_sql.mdx" -import GoInfluxLine from "../../04-develop/03-insert-data/_go_line.mdx" -import GoOpenTSDBTelnet from "../../04-develop/03-insert-data/_go_opts_telnet.mdx" -import GoOpenTSDBJson from "../../04-develop/03-insert-data/_go_opts_json.mdx" -import GoQuery from "../../04-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-en/14-reference/03-connector/java.mdx b/docs-en/14-reference/03-connector/java.mdx deleted file mode 100644 index 7da90a4ebdc51db57c3acb6f2e247e867b203905..0000000000000000000000000000000000000000 --- a/docs-en/14-reference/03-connector/java.mdx +++ /dev/null @@ -1,839 +0,0 @@ ---- -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.0.18 及更高版本）。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-en/14-reference/03-connector/node.mdx b/docs-en/14-reference/03-connector/node.mdx deleted file mode 100644 index 0afcf2457dfdb11c01657abd983601322899b8fb..0000000000000000000000000000000000000000 --- a/docs-en/14-reference/03-connector/node.mdx +++ /dev/null @@ -1,259 +0,0 @@ ---- -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 "../../04-develop/03-insert-data/_js_sql.mdx"; -import NodeInfluxLine from "../../04-develop/03-insert-data/_js_line.mdx"; -import NodeOpenTSDBTelnet from "../../04-develop/03-insert-data/_js_opts_telnet.mdx"; -import NodeOpenTSDBJson from "../../04-develop/03-insert-data/_js_opts_json.mdx"; -import NodeQuery from "../../04-develop/04-query-data/_js.mdx"; -import NodeAsyncQuery from "../../04-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-en/14-reference/03-connector/python.mdx b/docs-en/14-reference/03-connector/python.mdx deleted file mode 100644 index 5e6cdfba4fc3ee7fd6073b0264b54705c444bead..0000000000000000000000000000000000000000 --- a/docs-en/14-reference/03-connector/python.mdx +++ /dev/null @@ -1,353 +0,0 @@ ---- -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`。 一般无需配置。 - -:::note - -::: - - - - -## 示例程序 - -### 基本使用 - - - - -##### 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 -查询结果只能获取一次。比如上面的示例中 `featch_all` 和 `fetch_all_into_dict` 只能用一个。重复获取得到的结果为空列表。 -::: - -##### TaosResult 类的使用 - -上面 `TaosConnection` 类的使用示例中，我们已经展示了两种获取查询结果的方法： `featch_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-en/14-reference/03-connector/rust.mdx b/docs-en/14-reference/03-connector/rust.mdx deleted file mode 100644 index b6aac45c6ab30405190ab3ced39de017033e760a..0000000000000000000000000000000000000000 --- a/docs-en/14-reference/03-connector/rust.mdx +++ /dev/null @@ -1,388 +0,0 @@ ---- -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 "../../04-develop/03-insert-data/_rust_sql.mdx" -import RustInfluxLine from "../../04-develop/03-insert-data/_rust_line.mdx" -import RustOpenTSDBTelnet from "../../04-develop/03-insert-data/_rust_opts_telnet.mdx" -import RustOpenTSDBJson from "../../04-develop/03-insert-data/_rust_opts_json.mdx" -import RustQuery from "../../04-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-en/14-reference/03-connector/tdengine-jdbc-connector.png b/docs-en/14-reference/03-connector/tdengine-jdbc-connector.png deleted file mode 100644 index 1cb8401ea30b01d8db652ed4ea70ecc511de7461..0000000000000000000000000000000000000000 Binary files a/docs-en/14-reference/03-connector/tdengine-jdbc-connector.png and /dev/null differ diff --git a/docs-en/14-reference/04-taosadapter.md b/docs-en/14-reference/04-taosadapter.md deleted file mode 100644 index 158d4ab008c3b3eca28cd469c38f451b22678518..0000000000000000000000000000000000000000 --- a/docs-en/14-reference/04-taosadapter.md +++ /dev/null @@ -1,338 +0,0 @@ ---- -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-en/14-reference/05-taosbenchmark.md b/docs-en/14-reference/05-taosbenchmark.md deleted file mode 100644 index 0ccd25cf3a93f0496458e061d095f58fe3eac4ca..0000000000000000000000000000000000000000 --- a/docs-en/14-reference/05-taosbenchmark.md +++ /dev/null @@ -1,434 +0,0 @@ ---- -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 只能选择其中之一。值得注意的是，所要测试的功能类型在使用命令行配置方式时是不可配置的，命令行配置方式只能测试写入性能。若要测试 TDegnine 的查询和订阅性能，必须使用配置文件的方式，通过配置文件中的参数 `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 ** : - 每次向 TDegnine 请求写入的数据行数，默认值为 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** : - 每次向 TDegnine 请求写入的数据行数，默认值为 30000 。当其设置过大时，TDegnine 客户端驱动会返回相应的错误信息，此时需要调低这个参数的设置以满足写入要求。 - -- **prepare_rand** : 生成的随机数据中唯一值的数量。若为 1 则表示所有数据都相同。默认值为 10000 。 - -### 查询场景配置参数 - -查询场景下 `filetype` 必须设置为 `qeury`，该参数及其它通用参数详见[通用配置参数](#通用配置参数) - -#### 执行指定查询语句的配置参数 - -查询子表或者普通表的配置参数在 `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。 - -- **interva** : 执行订阅的时间间隔，单位为秒，默认为 0。 - -- **restart** : "yes" 表示开始新的订阅，"no" 表示继续之前的订阅，默认值为 "no"。 - -- **keepProgress** : "yes" 表示保留订阅进度，"no" 表示不保留，默认值为 "no"。 - -- **resubAfterConsume** : "yes" 表示取消之前的订阅然后再次订阅， "no" 表示继续之前的订阅，默认值为 "no"。 - -- **sqls** ： - - **sql** : 执行的 SQL 命令，必填。 - - **result** : 保存查询结果的文件，未指定则不保存。 - -#### 订阅超级表的配置参数 - -订阅超级表的配置参数在 `super_table_query` 中设置。 - -- **stblname** : 要订阅的超级表名称，必填。 - -- **threads** : 执行 SQL 的线程数，默认为 1。 - -- **interva** : 执行订阅的时间间隔，单位为秒，默认为 0。 - -- **restart** : "yes" 表示开始新的订阅，"no" 表示继续之前的订阅，默认值为 "no"。 - -- **keepProgress** : "yes" 表示保留订阅进度，"no" 表示不保留，默认值为 "no"。 - -- **resubAfterConsume** : "yes" 表示取消之前的订阅然后再次订阅， "no" 表示继续之前的订阅，默认值为 "no"。 - -- **sqls** ： - - **sql** : 执行的 SQL 命令，必填；对于超级表的查询 SQL，在 SQL 命令中保留 "xxxx"，程序会自动将其替换为超级表的所有子表名。 - 替换为超级表中所有的子表名。 - - **result** : 保存查询结果的文件，未指定则不保存。 diff --git a/docs-en/14-reference/06-taosdump.md b/docs-en/14-reference/06-taosdump.md deleted file mode 100644 index 7131493ec9439225d8047288ed86026c887f0aac..0000000000000000000000000000000000000000 --- a/docs-en/14-reference/06-taosdump.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -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-en/14-reference/07-tdinsight/assets/TDinsight-1-cluster-status.png b/docs-en/14-reference/07-tdinsight/assets/TDinsight-1-cluster-status.png deleted file mode 100644 index 4708f836feb21980f2db7fed4a55f799b23a6ec1..0000000000000000000000000000000000000000 Binary files a/docs-en/14-reference/07-tdinsight/assets/TDinsight-1-cluster-status.png and /dev/null differ diff --git a/docs-en/14-reference/07-tdinsight/assets/TDinsight-2-dnodes.png b/docs-en/14-reference/07-tdinsight/assets/TDinsight-2-dnodes.png deleted file mode 100644 index f2684e6eed70e8f56697eae42b495d6bd62815e8..0000000000000000000000000000000000000000 Binary files a/docs-en/14-reference/07-tdinsight/assets/TDinsight-2-dnodes.png and /dev/null differ diff --git a/docs-en/14-reference/07-tdinsight/assets/TDinsight-3-mnodes.png b/docs-en/14-reference/07-tdinsight/assets/TDinsight-3-mnodes.png deleted file mode 100644 index 74686691e4106b8646c3deee1e0ce73b2f53f1ea..0000000000000000000000000000000000000000 Binary files a/docs-en/14-reference/07-tdinsight/assets/TDinsight-3-mnodes.png and /dev/null differ diff --git a/docs-en/14-reference/07-tdinsight/assets/TDinsight-4-requests.png b/docs-en/14-reference/07-tdinsight/assets/TDinsight-4-requests.png deleted file mode 100644 index 27964215567f9f961c0aeaf1b863188437008fb7..0000000000000000000000000000000000000000 Binary files a/docs-en/14-reference/07-tdinsight/assets/TDinsight-4-requests.png and /dev/null differ diff --git a/docs-en/14-reference/07-tdinsight/assets/TDinsight-5-database.png b/docs-en/14-reference/07-tdinsight/assets/TDinsight-5-database.png deleted file mode 100644 index b0d3abbf21ec4d4bd7bfb95fcc03a5f936b22665..0000000000000000000000000000000000000000 Binary files a/docs-en/14-reference/07-tdinsight/assets/TDinsight-5-database.png and /dev/null differ diff --git a/docs-en/14-reference/07-tdinsight/assets/TDinsight-6-dnode-usage.png b/docs-en/14-reference/07-tdinsight/assets/TDinsight-6-dnode-usage.png deleted file mode 100644 index 2b54cbeb83bcff12f20461a4f57f882e2073f231..0000000000000000000000000000000000000000 Binary files a/docs-en/14-reference/07-tdinsight/assets/TDinsight-6-dnode-usage.png and /dev/null differ diff --git a/docs-en/14-reference/07-tdinsight/assets/TDinsight-7-login-history.png b/docs-en/14-reference/07-tdinsight/assets/TDinsight-7-login-history.png deleted file mode 100644 index eb3848657f13900c856ac595c20766465157e9c4..0000000000000000000000000000000000000000 Binary files a/docs-en/14-reference/07-tdinsight/assets/TDinsight-7-login-history.png and /dev/null differ diff --git a/docs-en/14-reference/07-tdinsight/assets/TDinsight-8-taosadaper.png b/docs-en/14-reference/07-tdinsight/assets/TDinsight-8-taosadaper.png deleted file mode 100644 index d94b2e02ac9855bb3d2f77d8902e068839db364f..0000000000000000000000000000000000000000 Binary files a/docs-en/14-reference/07-tdinsight/assets/TDinsight-8-taosadaper.png and /dev/null differ diff --git a/docs-en/14-reference/07-tdinsight/assets/TDinsight-full.png b/docs-en/14-reference/07-tdinsight/assets/TDinsight-full.png deleted file mode 100644 index 654df2934597ce600a1dc2dcd0cab7e29de7076d..0000000000000000000000000000000000000000 Binary files a/docs-en/14-reference/07-tdinsight/assets/TDinsight-full.png and /dev/null differ diff --git a/docs-en/14-reference/07-tdinsight/assets/alert-manager-status.png b/docs-en/14-reference/07-tdinsight/assets/alert-manager-status.png deleted file mode 100644 index e3afa22c0326d70567ec4529c83101c746daac87..0000000000000000000000000000000000000000 Binary files a/docs-en/14-reference/07-tdinsight/assets/alert-manager-status.png and /dev/null differ diff --git a/docs-en/14-reference/07-tdinsight/assets/alert-notification-channel.png b/docs-en/14-reference/07-tdinsight/assets/alert-notification-channel.png deleted file mode 100644 index 198bf37141c86a66cdd91b47a331bcdeb83daaf8..0000000000000000000000000000000000000000 Binary files a/docs-en/14-reference/07-tdinsight/assets/alert-notification-channel.png and /dev/null differ diff --git a/docs-en/14-reference/07-tdinsight/assets/alert-query-demo.png b/docs-en/14-reference/07-tdinsight/assets/alert-query-demo.png deleted file mode 100644 index ace3aa3c2f8f14fabdac54bc25ae2d9449445b69..0000000000000000000000000000000000000000 Binary files a/docs-en/14-reference/07-tdinsight/assets/alert-query-demo.png and /dev/null differ diff --git a/docs-en/14-reference/07-tdinsight/assets/alert-rule-condition-notifications.png b/docs-en/14-reference/07-tdinsight/assets/alert-rule-condition-notifications.png deleted file mode 100644 index 7082e49f6beb8690c36f98a3f4ff2befdb8fd014..0000000000000000000000000000000000000000 Binary files a/docs-en/14-reference/07-tdinsight/assets/alert-rule-condition-notifications.png and /dev/null differ diff --git a/docs-en/14-reference/07-tdinsight/assets/alert-rule-test.png b/docs-en/14-reference/07-tdinsight/assets/alert-rule-test.png deleted file mode 100644 index ffd4911b53854c42dbf0ff11838cb604fa694138..0000000000000000000000000000000000000000 Binary files a/docs-en/14-reference/07-tdinsight/assets/alert-rule-test.png and /dev/null differ diff --git a/docs-en/14-reference/07-tdinsight/assets/howto-add-datasource-button.png b/docs-en/14-reference/07-tdinsight/assets/howto-add-datasource-button.png deleted file mode 100644 index 802c7366f921301bd7fbc62458e56b2d1eaf195c..0000000000000000000000000000000000000000 Binary files a/docs-en/14-reference/07-tdinsight/assets/howto-add-datasource-button.png and /dev/null differ diff --git a/docs-en/14-reference/07-tdinsight/assets/howto-add-datasource-tdengine.png b/docs-en/14-reference/07-tdinsight/assets/howto-add-datasource-tdengine.png deleted file mode 100644 index 019ec921b6f808671f4f864ddf3380159d4a0dcc..0000000000000000000000000000000000000000 Binary files a/docs-en/14-reference/07-tdinsight/assets/howto-add-datasource-tdengine.png and /dev/null differ diff --git a/docs-en/14-reference/07-tdinsight/assets/howto-add-datasource-test.png b/docs-en/14-reference/07-tdinsight/assets/howto-add-datasource-test.png deleted file mode 100644 index 3963abb4ea8ae0e6f5557466f7a5b746c2d2ea3c..0000000000000000000000000000000000000000 Binary files a/docs-en/14-reference/07-tdinsight/assets/howto-add-datasource-test.png and /dev/null differ diff --git a/docs-en/14-reference/07-tdinsight/assets/howto-add-datasource.png b/docs-en/14-reference/07-tdinsight/assets/howto-add-datasource.png deleted file mode 100644 index 837100464b35a5cafac474723aef603f91945ebc..0000000000000000000000000000000000000000 Binary files a/docs-en/14-reference/07-tdinsight/assets/howto-add-datasource.png and /dev/null differ diff --git a/docs-en/14-reference/07-tdinsight/assets/howto-dashboard-display.png b/docs-en/14-reference/07-tdinsight/assets/howto-dashboard-display.png deleted file mode 100644 index 98223df25499effac343ff5723544a3c289f18fa..0000000000000000000000000000000000000000 Binary files a/docs-en/14-reference/07-tdinsight/assets/howto-dashboard-display.png and /dev/null differ diff --git a/docs-en/14-reference/07-tdinsight/assets/howto-dashboard-import-options.png b/docs-en/14-reference/07-tdinsight/assets/howto-dashboard-import-options.png deleted file mode 100644 index 07aba348f02b4fb8ef68e79664920c119b842d4c..0000000000000000000000000000000000000000 Binary files a/docs-en/14-reference/07-tdinsight/assets/howto-dashboard-import-options.png and /dev/null differ diff --git a/docs-en/14-reference/07-tdinsight/assets/howto-import-dashboard.png b/docs-en/14-reference/07-tdinsight/assets/howto-import-dashboard.png deleted file mode 100644 index 7e28939ead8bf3b6e2b4330e4f9b59c2e39b5c1c..0000000000000000000000000000000000000000 Binary files a/docs-en/14-reference/07-tdinsight/assets/howto-import-dashboard.png and /dev/null differ diff --git a/docs-en/14-reference/07-tdinsight/assets/import-dashboard-15167.png b/docs-en/14-reference/07-tdinsight/assets/import-dashboard-15167.png deleted file mode 100644 index 981f640b14d18aa6f0682768d8405a232df500f6..0000000000000000000000000000000000000000 Binary files a/docs-en/14-reference/07-tdinsight/assets/import-dashboard-15167.png and /dev/null differ diff --git a/docs-en/14-reference/07-tdinsight/assets/import-dashboard-for-tdengine.png b/docs-en/14-reference/07-tdinsight/assets/import-dashboard-for-tdengine.png deleted file mode 100644 index 94ef4fa5fe63e535118a81707b413c028ce01f70..0000000000000000000000000000000000000000 Binary files a/docs-en/14-reference/07-tdinsight/assets/import-dashboard-for-tdengine.png and /dev/null differ diff --git a/docs-en/14-reference/07-tdinsight/assets/import-via-grafana-dot-com.png b/docs-en/14-reference/07-tdinsight/assets/import-via-grafana-dot-com.png deleted file mode 100644 index 670cacc377c2801fa9437c3c132c5c7fbc361b0f..0000000000000000000000000000000000000000 Binary files a/docs-en/14-reference/07-tdinsight/assets/import-via-grafana-dot-com.png and /dev/null differ diff --git a/docs-en/14-reference/07-tdinsight/assets/import_dashboard.png b/docs-en/14-reference/07-tdinsight/assets/import_dashboard.png deleted file mode 100644 index d74cd36c96ee0fd24ddc6feae2da07824816f745..0000000000000000000000000000000000000000 Binary files a/docs-en/14-reference/07-tdinsight/assets/import_dashboard.png and /dev/null differ diff --git a/docs-en/14-reference/07-tdinsight/assets/tdengine_dashboard.png b/docs-en/14-reference/07-tdinsight/assets/tdengine_dashboard.png deleted file mode 100644 index 0101e7430cb2ef673818de8bd3af53d0d082ad3f..0000000000000000000000000000000000000000 Binary files a/docs-en/14-reference/07-tdinsight/assets/tdengine_dashboard.png and /dev/null differ diff --git a/docs-en/14-reference/07-tdinsight/index.md b/docs-en/14-reference/07-tdinsight/index.md deleted file mode 100644 index 553ae48b285f39a1fb29ebe946cb9b949adf9664..0000000000000000000000000000000000000000 --- a/docs-en/14-reference/07-tdinsight/index.md +++ /dev/null @@ -1,427 +0,0 @@ ---- -title: TDinsight - 基于Grafana的TDengine零依赖监控解决方案 -sidebar_label: TDinsight ---- - -TDinsight 是使用 [TDengine] 原生监控数据库和 [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 -``` - -这个脚本会自动下载最新的[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 的用法说明： - -```bash -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 orgnization 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 -``` - -### 配置 Grafana - -将以下设置添加到配置文件 `/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, mdodes, 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%时触发。 -- **Messuring 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-taosadaper.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-en/14-reference/08-taos-shell.md b/docs-en/14-reference/08-taos-shell.md deleted file mode 100644 index c9167fcf2643954981925fb5ef67a60cbad97a6d..0000000000000000000000000000000000000000 --- a/docs-en/14-reference/08-taos-shell.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: TDengine 命令行(CLI) -sidebar_label: TDengine CLI -description: TDengine CLI 的使用说明和技巧 ---- - -TDengine 命令行程序（以下简称 TDengine CLI）是用户操作 TDengine 实例并与之交互的最简洁最常用的方式。 - -## 安装 - -如果在 TDengine 服务器端执行，无需任何安装，已经自动安装好。如果要在非 TDengine 服务器端运行，需要安装 TDengine 客户端驱动，具体安装，请参考 [连接器](/reference/connector/)。 - -## 执行 - -要进入 TDengine CLI，您只要在 Linux 终端或Windos 终端执行 `taos` 即可。 - -```bash -taos -``` -如果连接服务成功，将会打印出欢迎消息和版本信息。如果失败，则会打印错误消息出来（请参考 [FAQ](/train-faq/faq) 来解决终端连接服务端失败的问题）。TDengine CLI 的提示符号如下： - -```cmd -taos> -``` -进入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: 指定配置文件目录，默认为 `/etc/taos`，该目录下的配置文件默认名称为 taos.cfg -- -C, --dump-config: 打印 -c 指定的目录中 taos.cfg 的配置参数 -- -d, --database=DATABASE: 指定连接到服务端时使用的数据库 -- -D, --directory=DIRECTORY: 导入指定路径中的 SQL 脚本文件 -- -f, --file=FILE: 以非交互模式执行 SQL 脚本文件 -- -k, --check=CHECK: 指定要检查的表 -- -l, --pktlen=PKTLEN: 网络测试时使用的测试包大小 -- -n, --netrole=NETROLE: 网络连接测试时的测试范围，默认为 startup, 可选值为 client, server, rpc, startup, sync, speed, fqdn -- -r, --raw-time: 将时间输出出 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 小技巧 - -- 可以使用上下光标键查看历史输入的指令 -- 修改用户密码：在 shell 中使用 `alter user` 命令，缺省密码为 taosdata -- ctrl+c 中止正在进行中的查询 -- 执行 `RESET QUERY CACHE` 可清除本地缓存的表 schema -- 批量执行 SQL 语句。可以将一系列的 shell 命令（以英文 ; 结尾，每个 SQL 语句为一行）按行存放在文件里，在 shell 里执行命令 `source ` 自动执行该文件里所有的 SQL 语句 -- 输入 q 回车，退出 taos shell diff --git a/docs-en/14-reference/09-support-platform/_category_.yml b/docs-en/14-reference/09-support-platform/_category_.yml deleted file mode 100644 index ce2aa5213b1e85bbd07b7242d8bb1c1525e5c687..0000000000000000000000000000000000000000 --- a/docs-en/14-reference/09-support-platform/_category_.yml +++ /dev/null @@ -1 +0,0 @@ -label: 支持平台列表 diff --git a/docs-en/14-reference/09-support-platform/index.md b/docs-en/14-reference/09-support-platform/index.md deleted file mode 100644 index d396e4be1fed2e3ecdf202c6e57d509bc1941ecd..0000000000000000000000000000000000000000 --- a/docs-en/14-reference/09-support-platform/index.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -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-en/14-reference/11-docker/_category_.yml b/docs-en/14-reference/11-docker/_category_.yml deleted file mode 100644 index 68c16927f4a9098311dec116aab41e8faa07fe81..0000000000000000000000000000000000000000 --- a/docs-en/14-reference/11-docker/_category_.yml +++ /dev/null @@ -1 +0,0 @@ -label: TDengine Docker 镜像 \ No newline at end of file diff --git a/docs-en/14-reference/11-docker/index.md b/docs-en/14-reference/11-docker/index.md deleted file mode 100644 index daac309c2382d50f7afae68e5852cb0106ac7ff2..0000000000000000000000000000000000000000 --- a/docs-en/14-reference/11-docker/index.md +++ /dev/null @@ -1,515 +0,0 @@ ---- -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 - ersion: "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-en/14-reference/12-config/_category_.yml b/docs-en/14-reference/12-config/_category_.yml deleted file mode 100644 index 8d3cfcc8d0d8966bf1354f9ece83faea105f9c7a..0000000000000000000000000000000000000000 --- a/docs-en/14-reference/12-config/_category_.yml +++ /dev/null @@ -1 +0,0 @@ -label: 配置参数 \ No newline at end of file diff --git a/docs-en/14-reference/12-config/index.md b/docs-en/14-reference/12-config/index.md deleted file mode 100644 index 9fff685ee6bfe9ef77b3a83d8b49ccc13216e0ce..0000000000000000000000000000000000000000 --- a/docs-en/14-reference/12-config/index.md +++ /dev/null @@ -1,1126 +0,0 @@ ---- -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 的 end point | -| 缺省值 | localhost:6030 | - -### secondEp - -| 属性 | 说明 | -| -------- | ---------------------------------------------------------------------------- | -| 适用范围 | 服务端和客户端均适用 | -| 含义 | taosd 或者 taos 启动时，如果 firstEp 连接不上，尝试连接集群中第二个 dnode 的 end point | -| 缺省值 | 无 | - -### 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 级别 | -| 取值范围 | 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 - -| 属性 | 说明 | -| -------- | ------------------------ | -| 适用范围 | 仅服务端适用 | -| 含义 | 系统中裁决器的 end point，其格式如firstEp | -| 缺省值 | 空 | - -## 时间相关 - -### 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-en/14-reference/12-directory.md b/docs-en/14-reference/12-directory.md deleted file mode 100644 index f8c8cb4a082f691cf75db9bed3b42d0d6e1bc8a3..0000000000000000000000000000000000000000 --- a/docs-en/14-reference/12-directory.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -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-en/14-reference/13-schemaless/13-schemaless.md b/docs-en/14-reference/13-schemaless/13-schemaless.md deleted file mode 100644 index d5ec8ddc44bcc73b189089856959b31ea27e3caf..0000000000000000000000000000000000000000 --- a/docs-en/14-reference/13-schemaless/13-schemaless.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -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 中的每个数据项都需要对自身的数据类型进行描述。具体来说： - -- 如果两边有英文双引号，表示 BIANRY(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-en/14-reference/13-schemaless/_category_.yml b/docs-en/14-reference/13-schemaless/_category_.yml deleted file mode 100644 index 2e93df8b366a0d60d4af35ff35076b8345a1ad6a..0000000000000000000000000000000000000000 --- a/docs-en/14-reference/13-schemaless/_category_.yml +++ /dev/null @@ -1 +0,0 @@ -label: Schemaless 写入 diff --git a/docs-en/14-reference/_category_.yml b/docs-en/14-reference/_category_.yml deleted file mode 100644 index d4f07c2d4a3a214fed68d1be0d811aa163a2c766..0000000000000000000000000000000000000000 --- a/docs-en/14-reference/_category_.yml +++ /dev/null @@ -1,5 +0,0 @@ -label: Reference -link: - slug: /reference/ - type: generated-index - description: "参考指南是对 TDengine 本身、 TDengine 各语言连接器及自带的工具最详细的介绍。" diff --git a/docs-en/14-reference/_collectd.mdx b/docs-en/14-reference/_collectd.mdx deleted file mode 100644 index af3dd7564a58fb71f1a6c8a1cc6169ab6b3bb3a6..0000000000000000000000000000000000000000 --- a/docs-en/14-reference/_collectd.mdx +++ /dev/null @@ -1,84 +0,0 @@ -### Configuring taosAdapter - -To configure taosAdapter to receive collectd data. - -- Enable the configuration item in the taosAdapter configuration file (default location is /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" -... -``` - -The default database name written by taosAdapter is `collectd`. You can also modify the taosAdapter configuration file dbs entry to specify a different name. user and password are the values configured by the actual TDengine. After changing the configuration file, you need to restart the taosAdapter. - -- You can also enable the taosAdapter to receive collectd data by using the taosAdapter command line parameters or by setting environment variables. - -### Configure collectd -#collectd -collectd uses a plugin mechanism to write the collected monitoring data to different data storage software in various forms. tdengine supports both direct collection plugins and write_tsdb plugins. - -#### is configured to receive data from the direct collection plugin - -Modify the relevant configuration items in the collectd configuration file (default location /etc/collectd/collectd.conf). - -```text -LoadPlugin network - - Server "" "" - -``` - -where fills in the server's domain name or IP address running taosAdapter. fills in the port that taosAdapter uses to receive collectd data (default is 6045). - -An example is as follows. - -```text -LoadPlugin network - -``` - -#### Configure write_tsdb plugin data - -Modify the relevant configuration items in the collectd configuration file (default location /etc/collectd/collectd.conf). - -```text -LoadPlugin write_tsdb - - - Host "" - Port "" - ... - - -``` - -Where fills in the server's domain name or IP address running taosAdapter. Fill in the data that taosAdapter uses to receive the collectd write_tsdb plugin (default is 6047). - -```text -LoadPlugin write_tsdb - - - Host "127.0.0.1" - Port "6047" - HostTags "status=production" - StoreRates false - AlwaysAppendDS false - -``` - -Then restart collectd. - -``` -systemctl restart collectd -``` diff --git a/docs-en/14-reference/_icinga2.mdx b/docs-en/14-reference/_icinga2.mdx deleted file mode 100644 index a462a765e493acc1a276e99ee1c237a67bf4f5e2..0000000000000000000000000000000000000000 --- a/docs-en/14-reference/_icinga2.mdx +++ /dev/null @@ -1,46 +0,0 @@ - - -### Configuring taosAdapter - -To configure taosAdapter to receive icinga2 data. - -- Enable the configuration item in the taosAdapter configuration file (default location /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" -... -``` - -The default database name written by the taosAdapter is `icinga2`. You can also modify the taosAdapter configuration file dbs entry to specify a different name. user and password are the values configured by the actual TDengine. You need to restart the taosAdapter after modification. - -- You can also enable taosAdapter to receive icinga2 data by using the taosAdapter command line parameters or setting environment variables. - -### Configure icinga3 - -- Enable opentsdb-writer for icinga2 (refer to the link https://icinga.com/docs/icinga-2/latest/doc/14-features/#opentsdb-writer) -- Modify the configuration file `/etc/icinga2/features-enabled/opentsdb.conf` by filling in as the domain name or IP address of the server running taosAdapter and as the corresponding port on which taosAdapter supports receiving icinga2 data (default is 6048) - -``` -object OpenTsdbWriter "opentsdb" { - host = "" - port = -} -``` - -Example file: - -``` -object OpenTsdbWriter "opentsdb" { - host = "127.0.0.1" - port = 6048 -} -``` - diff --git a/docs-en/14-reference/_prometheus.mdx b/docs-en/14-reference/_prometheus.mdx deleted file mode 100644 index 0059fe53fcbb766f43d2f2580e2ab299f3a79cf8..0000000000000000000000000000000000000000 --- a/docs-en/14-reference/_prometheus.mdx +++ /dev/null @@ -1,31 +0,0 @@ -Configuring Prometheus is done by editing the Prometheus configuration file prometheus.yml (default location /etc/prometheus/prometheus.yml). - -### Configuring third-party database addresses - -Point the `remote_read url` and `remote_write url` to the domain name or IP address of the server running the taosAdapter service, the REST service port (taosAdapter uses 6041 by default), and the name of the database you want to write to TDengine, and ensure that the corresponding URL form as follows. - -- remote_read url : `http://:/prometheus/v1/remote_read/` -- remote_write url : `http://:/prometheus/v1/remote_write/` - -### Configure Basic authentication - -- username: -- password: - -### Example configuration of remote_write and remote_read related sections in prometheus.yml file - -```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-en/14-reference/_statsd.mdx b/docs-en/14-reference/_statsd.mdx deleted file mode 100644 index 403aff297c22958e0717381676f74ed8822c02ea..0000000000000000000000000000000000000000 --- a/docs-en/14-reference/_statsd.mdx +++ /dev/null @@ -1,55 +0,0 @@ -### Configuring taosAdapter - -To configure taosAdapter to receive StatsD data. - -- Enable the configuration item in the taosAdapter configuration file (default location /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 -... -``` - -The default database name written by taosAdapter is `statsd`. To specify a different name, you can also modify the taosAdapter configuration file db entry. user and password fill in the actual TDengine configuration values. After changing the configuration file, you need to restart the taosAdapter. - -- You can also enable taosAdapter to receive StatsD data by using the taosAdapter command line parameters or setting environment variables. - -### Configuring StatsD - -To use StatsD, you need to download its [source code](https://github.com/statsd/statsd). Please refer to the example file `exampleConfig.js` in the root directory of the source download to modify the configuration file. In , please fill in the domain name or IP address of the server running taosAdapter, and , please fill in the port where taosAdapter receives StatsD data (default is 6044). - -``` -backends section add ". /backends/repeater" -Add { host:'', port: } to repeater section -``` - -Example configuration file. - -``` -{ -port: 8125 -, backends: [". /backends/repeater"] -, repeater: [{ host: '127.0.0.1', port: 6044}] -} -``` - -Start StatsD after adding the following (assuming the config file is modified to config.js) - -``` -node stats.js config.js & -``` diff --git a/docs-en/14-reference/_tcollector.mdx b/docs-en/14-reference/_tcollector.mdx deleted file mode 100644 index b96c981b4294c15d3fe0afde9e0642f619413637..0000000000000000000000000000000000000000 --- a/docs-en/14-reference/_tcollector.mdx +++ /dev/null @@ -1,81 +0,0 @@ -### Configuring taosAdapter - -To configure taosAdapter to receive TCollector data. - -- Enable the configuration item in the taosAdapter configuration file (default location /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" -... -``` - -The taosAdapter writes to the database with the default name `tcollector`. You can also modify the taosAdapter configuration file dbs entry to specify a different name. user and password fill in the actual TDengine configuration values. After changing the configuration file, you need to restart the taosAdapter. - -- You can also enable taosAdapter to receive tcollector data by using the taosAdapter command line parameters or setting environment variables. - -### Configuring TCollector - -To use TCollector, you need to download its [source code](https://github.com/OpenTSDB/tcollector). Its configuration items are in its source code. Note: TCollector differs significantly from version to version, so here is an example of the latest code for the current master branch (git commit: 37ae920). - -Modify the contents of the `collectors/etc/config.py` and `tcollector.py` files. Change the address of the OpenTSDB host to the domain name or IP address of the server where taosAdapter is deployed, and change the port to the port that taosAdapter supports TCollector on (default is 6049). - -Example of git diff output of source code changes. - -``` -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-en/14-reference/_telegraf.mdx b/docs-en/14-reference/_telegraf.mdx deleted file mode 100644 index 423e9c6b835e99eb0582e82c5903b8eb399e0832..0000000000000000000000000000000000000000 --- a/docs-en/14-reference/_telegraf.mdx +++ /dev/null @@ -1,27 +0,0 @@ - -In the Telegraf configuration file (default location /etc/telegraf/telegraf.conf) add the outputs.http output module configuration. - -``` -[[outputs.http]] - url = "http://:/influxdb/v1/write?db=" - ... - username = "" - password = "" - ... -``` - -Where please fill in the server's domain name or IP address running the taosAdapter service. please fill in the port of the REST service (default is 6041). and please fill in the actual configuration of the currently running TDengine. And please fill in the database name where you want to store Telegraf data in TDengine. - -An example is as follows. - -``` -[[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-en/14-reference/taosAdapter-architecture.png b/docs-en/14-reference/taosAdapter-architecture.png deleted file mode 100644 index 08a9018553aae6f86b42d127b372d0cecfa9bdf8..0000000000000000000000000000000000000000 Binary files a/docs-en/14-reference/taosAdapter-architecture.png and /dev/null differ diff --git a/docs-en/20-third-party/01-grafana.mdx b/docs-en/20-third-party/01-grafana.mdx deleted file mode 100644 index f5cb9da9ddaaa60fd135b3ebefa76a8642ee3cb2..0000000000000000000000000000000000000000 --- a/docs-en/20-third-party/01-grafana.mdx +++ /dev/null @@ -1,97 +0,0 @@ ---- -sidebar_label: Grafana -title: Grafana ---- - -TDengine can be quickly integrated with the open-source data visualization system [Grafana](https://www.grafana.com/) to build a data monitoring and alerting system. The whole process does not require any code development. And you can visualize the contents of the data tables in TDengine on a DashBoard. - -You can learn more about using the TDengine plugin on [GitHub](https://github.com/taosdata/grafanaplugin/blob/master/README.md). - -## Installing Grafana - -TDengine currently supports Grafana versions 7.0 and above. Users can go to the Grafana official website to download the installation package and execute the installation according to the current operating system. The download address is as follows: . - -## Configuring Grafana - -You can download The Grafana plugin for TDengine from . The current latest version is 3.1.4. - -Recommend using the [``grafana-cli`` command-line tool](https://grafana.com/docs/grafana/latest/administration/cli/) for plugin installation. - -``bash -sudo -u grafana grafana-cli \ - --pluginUrl https://github.com/taosdata/grafanaplugin/releases/download/v3.1.4/tdengine-datasource-3.1.4.zip \ - plugins install tdengine-datasource -``` - -Or download it locally and extract it to the Grafana plugin directory. - -```bash -GF_VERSION=3.1.4 -wget https://github.com/taosdata/grafanaplugin/releases/download/v$GF_VERSION/tdengine-datasource-$GF_VERSION.zip -``` - -Take CentOS 7.2 for example, extract the plugin package to /var/lib/grafana/plugins directory, and restart grafana. - -```bash -sudo unzip tdengine-datasource-$GF_VERSION.zip -d /var/lib/grafana/plugins/ -``` - -Grafana versions 7.3+ / 8.x do signature checks on plugins, so you also need to add the following line to the grafana.ini file to use the plugin correctly. - -```ini -[plugins] -allow_loading_unsigned_plugins = tdengine-datasource -``` - -The TDengine plugin can be automatically installed and set up using the following environment variable settings in a Docker environment. - -```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 -``` - -## Using Grafana - -### Configuring Data Sources - -Users can log in to the Grafana server (username/password: admin/admin) directly through the URL `http://localhost:3000` and add a datasource through `Configuration -> Data Sources` on the left side, as shown in the following figure. - -![img](./grafana/add_datasource1.jpg) - -Click `Add data source` to enter the Add data source page, and enter TDengine in the query box to add it, as shown in the following figure. - -![img](./grafana/add_datasource2.jpg) - -Enter the datasource configuration page, and follow the default prompts to modify the corresponding configuration. - -![img](./grafana/add_datasource3.jpg) - -- Host: IP address of the server where the components of the TDengine cluster provide REST service (offered by taosd before 2.4 and by taosAdapter since 2.4) and the port number of the TDengine REST service (6041), by default use `http://localhost:6041`. -- User: TDengine user name. -- Password: TDengine user password. - -Click `Save & Test` to test. Follows are a success. - -![img](./grafana/add_datasource4.jpg) - -### Create Dashboard - -Go back to the main interface to create the Dashboard, click Add Query to enter the panel query page: - -![img](./grafana/create_dashboard1.jpg) - -As shown above, select the `TDengine` data source in the `Query` and enter the corresponding SQL in the query box below for query. - -- INPUT SQL: enter the statement to be queried (the result set of the SQL statement should be two columns and multiple rows), for example: `select avg(mem_system) from log.dn where ts >= $from and ts < $to interval($interval)`, where, from, to and interval are built-in variables of the TDengine plugin, indicating the range and time interval of queries fetched from the Grafana plugin panel. In addition to the built-in variables, ` custom template variables are also supported. -- ALIAS BY: This allows you to set the current query alias. -- GENERATE SQL: Clicking this button will automatically replace the corresponding variables and generate the final executed statement. - -Follow the default prompt to query the average system memory usage for the specified interval on the server where the current TDengine deployment is located as follows. - -![img](./grafana/create_dashboard2.jpg) - -> For more information on how to use Grafana to create the appropriate monitoring interface and for more details on using Grafana, refer to the official Grafana [documentation](https://grafana.com/docs/). - -### Importing the Dashboard - -In version 2.3.3.0 and above, you can import the TDinsight Dashboard (Grafana Dashboard ID: [15168](https://grafana.com/grafana/dashboards/15167)) as a monitoring visualization tool for TDengine clusters. You can find installation and usage instructions in the TDinsight User Manual (/reference/tdinsight/). diff --git a/docs-en/20-third-party/03-telegraf.md b/docs-en/20-third-party/03-telegraf.md deleted file mode 100644 index 0d563c9ff36268ac27e18e21fefed789789dc1a7..0000000000000000000000000000000000000000 --- a/docs-en/20-third-party/03-telegraf.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -sidebar_label: Telegraf -title: Telegraf writing ---- - -import Telegraf from "../14-reference/_telegraf.mdx" - -Telegraf is a viral metrics collection open-source software. Telegraf can collect the operation information of various components without writing any scripts to collect regularly, reducing the difficulty of data acquisition. - -Telegraf's data can be written to TDengine by simply adding the output configuration of Telegraf to the URL corresponding to taosAdapter and modifying several configuration items. The presence of Telegraf data in TDengine can take advantage of TDengine's efficient storage query performance and clustering capabilities for time-series data. - -## Prerequisites - -To write Telegraf data to TDengine requires the following preparations. -- The TDengine cluster is deployed and functioning properly -- taosAdapter is installed and running properly. Please refer to the [taosAdapter manual](/reference/taosadapter) for details. -- Telegraf has been installed. Please refer to the [official documentation](https://docs.influxdata.com/telegraf/v1.22/install/) for Telegraf installation. - -## Configuration steps - - -## Verification method - -Restart Telegraf service: - -``` -sudo systemctl restart telegraf -``` - -Use TDengine CLI to verify Telegraf correctly writing data to TDengine and read out: - -``` -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-en/20-third-party/05-collectd.md b/docs-en/20-third-party/05-collectd.md deleted file mode 100644 index 609e55842ab35cdc2d394663f5450f908e49f7f7..0000000000000000000000000000000000000000 --- a/docs-en/20-third-party/05-collectd.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -sidebar_label: collectd -title: collectd writing ---- - -import CollectD from "../14-reference/_collectd.mdx" - - -collectd is a daemon used to collect system performance metric data. collectd provides various storage mechanisms to store different values. It periodically counts system performance statistics number while the system is running and storing information. You can use this information to help identify current system performance bottlenecks and predict future system load. - -You can write the data collected by collectd to TDengine by simply modifying the configuration of collectd to the domain name (or IP address) and corresponding port of the server running taosAdapter. It can take full advantage of TDengine's efficient storage query performance and clustering capability for time-series data. - -## Prerequisites - -Writing collectd data to the TDengine requires several preparations. -- The TDengine cluster is deployed and running properly -- taosAdapter is installed and running, please refer to [taosAdapter's manual](/reference/taosadapter) for details -- collectd has been installed. Please refer to the [official documentation](https://collectd.org/download.shtml) to install collectd - -## Configuration steps - - -## Verification method - -Restart collectd - -``` -sudo systemctl restart collectd -``` - -Use the TDengine CLI to verify that collectd's data is written to TDengine and can read out correctly. - -``` -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-en/20-third-party/06-statsd.md b/docs-en/20-third-party/06-statsd.md deleted file mode 100644 index bf4b6c7ab5dac4114cad0d650b2aeb026a67581c..0000000000000000000000000000000000000000 --- a/docs-en/20-third-party/06-statsd.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -sidebar_label: StatsD -title: StatsD writing ---- - -import StatsD from "../14-reference/_statsd.mdx" - -StatsD is a simple daemon for aggregating application metrics, which has evolved rapidly in recent years into a unified protocol for collecting application performance metrics. - -You can write StatsD data to TDengine by simply modifying in the configuration file of StatsD with the domain name (or IP address) of the server running taosAdapter and the corresponding port. It can take full advantage of TDengine's efficient storage query performance and clustering capabilities for time-series data. - -## Prerequisites - -To write StatsD data to TDengine requires the following preparations. -- The TDengine cluster has been deployed and is working properly -- taosAdapter is installed and running properly. Please refer to the [taosAdapter manual](/reference/taosadapter) for details. -- StatsD has been installed. To install StatsD, please refer to [official documentation](https://github.com/statsd/statsd) - -## Configuration steps - - -## Verification method - -Start 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 -``` - -Using the utility software `nc` to write data for test: - -``` -$ echo "foo:1|c" | nc -u -w0 127.0.0.1 8125 -``` - -Use the TDengine CLI to verify that StatsD data is written to TDengine and can read out correctly. - -``` -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-en/20-third-party/07-icinga2.md b/docs-en/20-third-party/07-icinga2.md deleted file mode 100644 index ba9cde8cea7504ac9df871d5f6aa42cc5c94d895..0000000000000000000000000000000000000000 --- a/docs-en/20-third-party/07-icinga2.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -sidebar_label: icinga2 -title: icinga2 writing ---- - -import Icinga2 from "../14-reference/_icinga2.mdx" - -icinga2 is an open-source software monitoring host and network initially developed from the Nagios network monitoring application. Currently, icinga2 is distributed under the GNU GPL v2 license. - -You can write the data collected by icinga2 to TDengine by simply modifying the icinga2 configuration to point to the taosAdapter server and the corresponding port, taking advantage of TDengine's efficient storage and query performance and clustering capabilities for time-series data. - -## Prerequisites - -To write icinga2 data to TDengine requires the following preparations. -- The TDengine cluster is deployed and working properly -- taosAdapter is installed and running properly. Please refer to the [taosAdapter manual](/reference/taosadapter) for details. -- icinga2 has been installed. Please refer to the [official documentation](https://icinga.com/docs/icinga-2/latest/doc/02-installation/) for icinga2 installation - -## Configuration steps - - -## Verification method - -Restart taosAdapter: -``` -sudo systemctl restart taosadapter -``` - -Restart icinga2: - -``` -sudo systemctl restart icinga2 -``` - -After waiting about 10 seconds, use the TDengine CLI to query TDengine to verify that the appropriate database has been created and data are written. - -``` -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-en/20-third-party/08-tcollector.md b/docs-en/20-third-party/08-tcollector.md deleted file mode 100644 index dc14772c183c826297fed7997fd0aa88b4deaf48..0000000000000000000000000000000000000000 --- a/docs-en/20-third-party/08-tcollector.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -sidebar_label: TCollector -title: TCollector writing ---- - -import Tcollector from "../14-reference/_tcollector.mdx" - -TCollector is part of openTSDB and collects client computer's logs to send to the database. - -You can write the data collected by TCollector to TDengine by simply changing the configuration of TCollector to point to the domain name (or IP address) and corresponding port of the server running taosAdapter. It can take full advantage of TDengine's efficient storage query performance and clustering capability for time-series data. - -## Prerequisites - -To write data to the TDengine via TCollector requires the following preparations. -- The TDengine cluster has been deployed and is working properly -- taosAdapter is installed and running properly. Please refer to the [taosAdapter manual](/reference/taosadapter) for details. -- TCollector has been installed. Please refer to [official documentation](http://opentsdb.net/docs/build/html/user_guide/utilities/tcollector.html#installation-of-tcollector) for TCollector installation - -## Configuration steps - - -## Verification method - -Restart taosAdapter: - -``` -sudo systemctl restart taosadapter -``` - -Run `sudo ./tcollector.py`: - -Wait for a few seconds and then use the TDengine CLI to query whether the corresponding database has been created and data are written in 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-en/20-third-party/09-emq-broker.md b/docs-en/20-third-party/09-emq-broker.md deleted file mode 100644 index dc3ef4f43f4e153dbe3a729a36196509a6f7964c..0000000000000000000000000000000000000000 --- a/docs-en/20-third-party/09-emq-broker.md +++ /dev/null @@ -1,190 +0,0 @@ ---- -sidebar_label: EMQ Broker -title: EMQ Broker writing ---- - -MQTT is a popular IoT data transfer protocol, [EMQ](https://github.com/emqx/emqx) is an open-source MQTT Broker software, without any code, only need to use "rules" in EMQ Dashboard to do simple configuration. You can write MQTT data directly to TDengine. EMQ X supports saving data to TDengine by sending it to web services and provides a native TDengine driver for direct saving in the Enterprise Edition. Please refer to the [EMQ official documentation](https://www.emqx.io/docs/en/v4.4/rule/rule-engine.html) for details on how to use it. tdengine). - -## Prerequisites - -The following preparations are required for EMQX to add TDengine data sources correctly. -- The TDengine cluster is deployed and working properly -- taosAdapter is installed and running properly. Please refer to the [taosAdapter manual](/reference/taosadapter) for details. -- If you use the emulated writers described later, you need to install the appropriate version of Node.js. V12 is recommended. - -## Install and start EMQX - -Depending on the current operating system, users can download the installation package from the [EMQX official website](https://www.emqx.io/downloads) and execute the installation. After installation, use `sudo emqx start` or `sudo systemctl start emqx` to start the EMQX service. - -## Create the appropriate database and table schema in TDengine for receiving MQTT data - -### Take the Docker installation of TDengine as an example - -```bash - docker exec -it tdengine bash - taos -``` - -### Create Database and Table - -```sql - CREATE DATABASE test; - USE test; - - 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); -``` - -Note: The table schema is based on the blog [(In Chinese) Data Transfer, Storage, Presentation, EMQ X + TDengine Build MQTT IoT Data Visualization Platform](https://www.taosdata.com/blog/2020/08/04/1722.html) as an example. Subsequent operations are carried out with this blog scenario too. Please modify it according to your actual application scenario. - -## Configuring EMQX Rules - -Since the configuration interface of EMQX differs from version to version, here is v4.4.3 as an example. For other versions, please refer to the corresponding official documentation. - -### Login EMQX Dashboard - -Use your browser to open the URL `http://IP:18083` and log in to EMQX Dashboard. The initial installation username is `admin` and the password is: `public`. - -![img](./emqx/login-dashboard.png) - -### Creating Rule - -Select "Rule" in the "Rule Engine" on the left and click the "Create" button: ! - -![img](./emqx/rule-engine.png) - -### Edit SQL fields - -![img](./emqx/create-rule.png) - -### Add "action handler" - -![img](./emqx/add-action-handler.png) - -### Add "Resource" - -![img](./emqx/create-resource.png) - -Select "Data to Web Service" and click the "New Resource" button. - -### Edit "Resource" - -Select "Data to Web Service" and fill in the request URL as the address and port of the server running taosAdapter (default is 6041). Leave the other properties at their default values. - -![img](./emqx/edit-resource.png) - -### Edit "action" - -Edit the resource configuration to add the key/value pairing for Authorization. Please refer to the [ TDengine REST API documentation ](https://docs.taosdata.com/reference/rest-api/) for the authorization in details. Enter the rule engine replacement template in the message body. - -![img](./emqx/edit-action.png) - -## Compose program to mock data - -```javascript - // mock.js - const mqtt = require('mqtt') - const Mock = require('mockjs') - const EMQX_SERVER = 'mqtt://localhost:1883' - const CLIENT_NUM = 10 - const STEP = 5000 // Data interval in ms - const AWAIT = 5000 // Sleep time after data be written once to avoid data writing too fast - 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, - } - } -``` - -Note: `CLIENT_NUM` in the code can be set to a smaller value at the beginning of the test to avoid hardware performance be not capable to handle a more significant number of concurrent clients. - -![img](./emqx/client-num.png) - -## Execute tests to simulate sending MQTT data - -``` -npm install mqtt mockjs --save ---registry=https://registry.npm.taobao.org -node mock.js -``` - -![img](./emqx/run-mock.png) - -## Verify that EMQX is receiving data - -Refresh the EMQX Dashboard rules engine interface to see how many records were received correctly: - -![img](./emqx/check-rule-matched.png) - -## Verify that data writing to TDengine - -Use the TDengine CLI program to log in and query the appropriate databases and tables to verify that the data is being written to TDengine correctly: - -![img](./emqx/check-result-in-taos.png) - -Please refer to the [TDengine official documentation](https://docs.taosdata.com/) for more details on how to use TDengine. -EMQX Please refer to the [EMQ official documentation](https://www.emqx.io/docs/en/v4.4/rule/rule-engine.html) for details on how to use EMQX. diff --git a/docs-en/20-third-party/_category_.yml b/docs-en/20-third-party/_category_.yml deleted file mode 100644 index 63b9f353f8d021745c7b0a74ebebfda140c2d07c..0000000000000000000000000000000000000000 --- a/docs-en/20-third-party/_category_.yml +++ /dev/null @@ -1,6 +0,0 @@ -label: Third Party Tools -link: - type: generated-index - slug: /third-party/ - description: TDengine's support for standard SQL commands, common database connector standards (e.g., JDBC), ORM, and other popular time-series database writing protocols (e.g., InfluxDB Line Protocol, OpenTSDB JSON, OpenTSDB Telnet, etc.) makes TDengine very easy to use with third-party tools. - diff --git a/docs-en/20-third-party/emqx/add-action-handler.png b/docs-en/20-third-party/emqx/add-action-handler.png deleted file mode 100644 index 97a1f933ecfadfcab399938806d73c5a5ecc6427..0000000000000000000000000000000000000000 Binary files a/docs-en/20-third-party/emqx/add-action-handler.png and /dev/null differ diff --git a/docs-en/20-third-party/emqx/check-result-in-taos.png b/docs-en/20-third-party/emqx/check-result-in-taos.png deleted file mode 100644 index c17a5c1ea2b9bbd49263056c8bf09c9aabab07d5..0000000000000000000000000000000000000000 Binary files a/docs-en/20-third-party/emqx/check-result-in-taos.png and /dev/null differ diff --git a/docs-en/20-third-party/emqx/check-rule-matched.png b/docs-en/20-third-party/emqx/check-rule-matched.png deleted file mode 100644 index 9e9a466946a1afa857e2bbc07b14956dd0f984b6..0000000000000000000000000000000000000000 Binary files a/docs-en/20-third-party/emqx/check-rule-matched.png and /dev/null differ diff --git a/docs-en/20-third-party/emqx/client-num.png b/docs-en/20-third-party/emqx/client-num.png deleted file mode 100644 index fff48cbf3b271c367079ddde425b3f9b014062f7..0000000000000000000000000000000000000000 Binary files a/docs-en/20-third-party/emqx/client-num.png and /dev/null differ diff --git a/docs-en/20-third-party/emqx/create-resource.png b/docs-en/20-third-party/emqx/create-resource.png deleted file mode 100644 index 58da4c391a3692b9f5fa348d952701eab8bcb746..0000000000000000000000000000000000000000 Binary files a/docs-en/20-third-party/emqx/create-resource.png and /dev/null differ diff --git a/docs-en/20-third-party/emqx/create-rule.png b/docs-en/20-third-party/emqx/create-rule.png deleted file mode 100644 index 73b0b6ee3e6065a142df98abe8c0dbb32b34f89d..0000000000000000000000000000000000000000 Binary files a/docs-en/20-third-party/emqx/create-rule.png and /dev/null differ diff --git a/docs-en/20-third-party/emqx/edit-action.png b/docs-en/20-third-party/emqx/edit-action.png deleted file mode 100644 index 2a43ee369a439cf11cee23c11f25d6a84b26d7dc..0000000000000000000000000000000000000000 Binary files a/docs-en/20-third-party/emqx/edit-action.png and /dev/null differ diff --git a/docs-en/20-third-party/emqx/edit-resource.png b/docs-en/20-third-party/emqx/edit-resource.png deleted file mode 100644 index 0a0b3560044f4ed6e0a8f040b74085a7e8948b1f..0000000000000000000000000000000000000000 Binary files a/docs-en/20-third-party/emqx/edit-resource.png and /dev/null differ diff --git a/docs-en/20-third-party/emqx/login-dashboard.png b/docs-en/20-third-party/emqx/login-dashboard.png deleted file mode 100644 index d6c5035c98d860faf639ef6611c6719adf80c47b..0000000000000000000000000000000000000000 Binary files a/docs-en/20-third-party/emqx/login-dashboard.png and /dev/null differ diff --git a/docs-en/20-third-party/emqx/rule-engine.png b/docs-en/20-third-party/emqx/rule-engine.png deleted file mode 100644 index db110a837b024c82ee9d22f02dcd3a9d06abdd55..0000000000000000000000000000000000000000 Binary files a/docs-en/20-third-party/emqx/rule-engine.png and /dev/null differ diff --git a/docs-en/20-third-party/emqx/rule-header-key-value.png b/docs-en/20-third-party/emqx/rule-header-key-value.png deleted file mode 100644 index b81b9a9684aa2f98d00b7ec21e5de411fb450312..0000000000000000000000000000000000000000 Binary files a/docs-en/20-third-party/emqx/rule-header-key-value.png and /dev/null differ diff --git a/docs-en/20-third-party/emqx/run-mock.png b/docs-en/20-third-party/emqx/run-mock.png deleted file mode 100644 index 0da25818575247732d5d3a783aa52cf7ce24662c..0000000000000000000000000000000000000000 Binary files a/docs-en/20-third-party/emqx/run-mock.png and /dev/null differ diff --git a/docs-en/20-third-party/grafana/add_datasource1.jpg b/docs-en/20-third-party/grafana/add_datasource1.jpg deleted file mode 100644 index 1f0f5110f312c57f3ec1788bbc02f04fac6ac142..0000000000000000000000000000000000000000 Binary files a/docs-en/20-third-party/grafana/add_datasource1.jpg and /dev/null differ diff --git a/docs-en/20-third-party/grafana/add_datasource2.jpg b/docs-en/20-third-party/grafana/add_datasource2.jpg deleted file mode 100644 index fa7a83e00e96fae649910dff4edf5f5bdadd7850..0000000000000000000000000000000000000000 Binary files a/docs-en/20-third-party/grafana/add_datasource2.jpg and /dev/null differ diff --git a/docs-en/20-third-party/grafana/add_datasource3.jpg b/docs-en/20-third-party/grafana/add_datasource3.jpg deleted file mode 100644 index fc850ad08ff1174de972906842e0d5ee64e6e5cb..0000000000000000000000000000000000000000 Binary files a/docs-en/20-third-party/grafana/add_datasource3.jpg and /dev/null differ diff --git a/docs-en/20-third-party/grafana/add_datasource4.jpg b/docs-en/20-third-party/grafana/add_datasource4.jpg deleted file mode 100644 index 3ba73e50d455111f8621f4165746078554c2d790..0000000000000000000000000000000000000000 Binary files a/docs-en/20-third-party/grafana/add_datasource4.jpg and /dev/null differ diff --git a/docs-en/20-third-party/grafana/create_dashboard1.jpg b/docs-en/20-third-party/grafana/create_dashboard1.jpg deleted file mode 100644 index 3b83c3a1714e9e7540e0b06239ef7c1c4f63fe2c..0000000000000000000000000000000000000000 Binary files a/docs-en/20-third-party/grafana/create_dashboard1.jpg and /dev/null differ diff --git a/docs-en/20-third-party/grafana/create_dashboard2.jpg b/docs-en/20-third-party/grafana/create_dashboard2.jpg deleted file mode 100644 index fe5d768ac55254251e0290bf257178f5ff28f5a5..0000000000000000000000000000000000000000 Binary files a/docs-en/20-third-party/grafana/create_dashboard2.jpg and /dev/null differ diff --git a/docs-en/21-tdinternal/01-arch.md b/docs-en/21-tdinternal/01-arch.md deleted file mode 100644 index 2d4aa6c3dcc07e1d95c13560d04844eceb4b9dd8..0000000000000000000000000000000000000000 --- a/docs-en/21-tdinternal/01-arch.md +++ /dev/null @@ -1,285 +0,0 @@ ---- -sidebar_label: Architecture -title: Architecture ---- - -## Cluster and Primary Logic Unit - -The design of TDengine is based on the assumption that any hardware or software system is not 100% reliable and that no single node can provide sufficient computing and storage resources to process massive data. Therefore, TDengine has been designed in a distributed and high-reliability architecture since day one of the development, so that hardware failure or software failure of any single even multiple servers will not affect the availability and reliability of the system. At the same time, through node virtualization and automatic load-balancing technology, TDengine can make the most efficient use of computing and storage resources in heterogeneous clusters to reduce hardware resources significantly. - -### Primary Logic Unit - -Logical structure diagram of TDengine distributed architecture as following: - -![TDengine architecture diagram](structure.png) -
Figure 1: TDengine architecture diagram
- -A complete TDengine system runs on one or more physical nodes. Logically, it includes data node (dnode), TDengine application driver (TAOSC) and application (app). There are one or more data nodes in the system, which form a cluster. The application interacts with the TDengine cluster through TAOSC's API. The following is a brief introduction to each logical unit. - -**Physical node (pnode)**: A pnode is a computer that runs independently and has its own computing, storage and network capabilities. It can be a physical machine, virtual machine, or Docker container installed with OS. The physical node is identified by its configured FQDN (Fully Qualified Domain Name). TDengine relies entirely on FQDN for network communication. If you don't know about FQDN, please check [wikipedia](https://en.wikipedia.org/wiki/Fully_qualified_domain_name). - -**Data node (dnode):** A dnode is a running instance of the TDengine server-side execution code taosd on a physical node. A working system must have at least one data node. A dnode contains zero to multiple logical virtual nodes (VNODE), zero or at most one logical management node (mnode). The unique identification of a dnode in the system is determined by the instance's End Point (EP). EP is a combination of FQDN (Fully Qualified Domain Name) of the physical node where the dnode is located and the network port number (Port) configured by the system. By configuring different ports, a physical node (a physical machine, virtual machine or container) can run multiple instances or have multiple data nodes. - -**Virtual node (vnode)**: To better support data sharding, load balancing and prevent data from overheating or skewing, data nodes are virtualized into multiple virtual nodes (vnode, V2, V3, V4, etc. in the figure). Each vnode is a relatively independent work unit, which is the basic unit of time-series data storage and has independent running threads, memory space and persistent storage path. A vnode contains a certain number of tables (data collection points). When a new table is created, the system checks whether a new vnode needs to be created. The number of vnodes that can be created on a data node depends on the hardware capacities of the physical node where the data node is located. A vnode belongs to only one DB, but a DB can have multiple vnodes. In addition to the stored time-series data, a vnode also stores the schema and tag values of the included tables. A virtual node is uniquely identified in the system by the EP of the data node and the VGroup ID to which it belongs and is created and managed by the management node. - -**Management node (mnode)**: A virtual logical unit responsible for monitoring and maintaining the running status of all data nodes and load balancing among nodes (M in the figure). At the same time, the management node is also responsible for the storage and management of metadata (including users, databases, tables, static tags, etc.), so it is also called Meta Node. Multiple (up to 5) mnodes can be configured in a TDengine cluster, and they are automatically constructed into a virtual management node group (M0, M1, M2 in the figure). The master/slave mechanism is adopted for the mnode group and the data synchronization is carried out in a strongly consistent way. Any data update operation can only be executed on the master. The creation of mnode cluster is completed automatically by the system without manual intervention. There is at most one mnode on each dnode, which is uniquely identified by the EP of the data node to which it belongs. Each dnode automatically obtains the EP of the dnode where all mnodes in the whole cluster are located through internal messaging interaction. - -**Virtual node group (VGroup)**: Vnodes on different data nodes can form a virtual node group to ensure the high availability of the system. The virtual node group is managed in a master/slave mechanism. Write operations can only be performed on the master vnode, and then replicated to slave vnodes, thus ensuring that one single replica of data is copied on multiple physical nodes. The number of virtual nodes in a vgroup equals the number of data replicas. If the number of replicas of a DB is N, the system must have at least N data nodes. The number of replicas can be specified by the parameter `“replica”` when creating DB, and the default is 1. Using the multi-replication feature of TDengine, the same high data reliability can be achieved without the need for expensive storage devices such as disk arrays. Virtual node group is created and managed by the management node, and the management node assigns a system unique ID, aka VGroup ID. If two virtual nodes have the same vnode group ID, means that they belong to the same group and the data is backed up to each other. The number of virtual nodes in a virtual node group can be dynamically changed, allowing only one, that is, no data replication. VGroup ID is never changed. Even if a virtual node group is deleted, its ID will not be reused. - -**TAOSC**: TAOSC is the driver provided by TDengine to applications, which is responsible for dealing with the interaction between application and cluster, and provides the native interface of C/C++ language, which is embedded in JDBC, C #, Python, Go, Node.js language connection libraries. Applications interact with the whole cluster through TAOSC instead of directly connecting to data nodes in the cluster. This module is responsible for obtaining and caching metadata; forwarding requests for insertion, query, etc. to the correct data node; when returning the results to the application, TAOSC also needs to be responsible for the final level of aggregation, sorting, filtering and other operations. For JDBC, C/C++/C #/Python/Go/Node.js interfaces, this module runs on the physical node where the application is located. At the same time, in order to support the fully distributed RESTful interface, TAOSC has a running instance on each dnode of TDengine cluster. - -### Node Communication - -**Communication mode**: The communication among each data node of TDengine system, and among the application driver and each data node is carried out through TCP/UDP. Considering an IoT scenario, the data writing packets are generally not large, so TDengine uses UDP in addition to TCP for transmission, because UDP is more efficient and is not limited by the number of connections. TDengine implements its own timeout, retransmission, confirmation and other mechanisms to ensure reliable transmission of UDP. For packets with a data volume of less than 15K, UDP is adopted for transmission, and TCP is automatically adopted for transmission of packets with a data volume of more than 15K or query operations. At the same time, TDengine will automatically compress/decompress the data, digital sign/authenticate the data according to the configuration and data packet. For data replication among data nodes, only TCP is used for data transportation. - -**FQDN configuration:** A data node has one or more FQDNs, which can be specified in the system configuration file taos.cfg with the parameter “fqdn”. If it is not specified, the system will automatically use the hostname of the computer as its FQDN. If the node is not configured with FQDN, you can directly set the configuration parameter “fqdn” of the node to its IP address. However, IP is not recommended because IP address may be changed, and once it changes, the cluster will not work properly. The EP (End Point) of a data node consists of FQDN + Port. With FQDN, it is necessary to ensure the DNS service is running, or hosts files on nodes are configured properly. - -**Port configuration**: The external port of a data node is determined by the system configuration parameter “serverPort” in TDengine, and the port for internal communication of cluster is serverPort+5. The data replication operation among data nodes in the cluster also occupies a TCP port, which is serverPort+10. In order to support multithreading and efficient processing of UDP data, each internal and external UDP connection needs to occupy 5 consecutive ports. Therefore, the total port range of a data node will be serverPort to serverPort + 10, for a total of 11 TCP/UDP ports. To run the system, make sure that the firewall keeps these ports open. Each data node can be configured with a different serverPort. - -**Cluster external connection**: TDengine cluster can accommodate one single, multiple or even thousands of data nodes. The application only needs to initiate a connection to any data node in the cluster. The network parameter required for connection is the End Point (FQDN plus configured port number) of a data node. When starting the application taos through CLI, the FQDN of the data node can be specified through the option `-h`, and the configured port number can be specified through `-p`. If the port is not configured, the system configuration parameter “serverPort” of TDengine will be adopted. - -**Inter-cluster communication**: Data nodes connect with each other through TCP/UDP. When a data node starts, it will obtain the EP information of the dnode where the mnode is located, and then establish a connection with the mnode in the system to exchange information. There are three steps to obtain EP information of the mnode: - -1. Check whether the mnodeEpList file exists, if it does not exist or cannot be opened normally to obtain EP information of the mnode, skip to the second step; -2. Check the system configuration file taos.cfg to obtain node configuration parameters “firstEp” and “secondEp” (the node specified by these two parameters can be a normal node without mnode, in this case, the node will try to redirect to the mnode node when connected). If these two configuration parameters do not exist or do not exist in taos.cfg, or are invalid, skip to the third step; -3. Set your own EP as a mnode EP and run it independently. After obtaining the mnode EP list, the data node initiates the connection. It will successfully join the working cluster after connection. If not successful, it will try the next item in the mnode EP list. If all attempts are made, but the connection still fails, sleep for a few seconds before trying again. - -**The choice of MNODE**: TDengine logically has a management node, but there is no separated execution code. The server-side only has a set of execution code taosd. So which data node will be the management node? This is determined automatically by the system without any manual intervention. The principle is as follows: when a data node starts, it will check its End Point and compare it with the obtained mnode EP List. If its EP exists in it, the data node shall start the mnode module and become a mnode. If your own EP is not in the mnode EP List, the mnode module will not start. During the system operation, due to load balancing, downtime and other reasons, mnode may migrate to the new dnode, while totally transparent without manual intervention. The modification of configuration parameters is the decision made by mnode itself according to resources usage. - -**Add new data nodes:** After the system has a data node, it has become a working system. There are two steps to add a new node into the cluster. Step1: Connect to the existing working data node using TDengine CLI, and then add the End Point of the new data node with the command "create dnode"; Step 2: In the system configuration parameter file taos.cfg of the new data node, set the “firstEp” and “secondEp” parameters to the EP of any two data nodes in the existing cluster. Please refer to the detailed user tutorial for detailed steps. In this way, the cluster will be established step by step. - -**Redirection**: No matter about dnode or TAOSC, the connection to the mnode shall be initiated first, but the mnode is automatically created and maintained by the system, so the user does not know which dnode is running the mnode. TDengine only requires a connection to any working dnode in the system. Because any running dnode maintains the currently running mnode EP List, when receiving a connecting request from the newly started dnode or TAOSC, if it’s not a mnode by self, it will reply to the mnode EP List back. After receiving this list, TAOSC or the newly started dnode will try to establish the connection again. When the mnode EP List changes, each data node quickly obtains the latest list and notifies TAOSC through messaging interaction among nodes. - -### A Typical Data Writing Process - -To explain the relationship between vnode, mnode, TAOSC and application and their respective roles, the following is an analysis of a typical data writing process. - -![typical process of TDengine](message.png) -
Figure 2: Typical process of TDengine
- -1. Application initiates a request to insert data through JDBC, ODBC, or other APIs. -2. TAOSC checks if meta data existing for the table in the cache. If so, go straight to Step 4. If not, TAOSC sends a get meta-data request to mnode. -3. Mnode returns the meta-data of the table to TAOSC. Meta-data contains the schema of the table, and also the vgroup information to which the table belongs (the vnode ID and the End Point of the dnode where the table belongs. If the number of replicas is N, there will be N groups of End Points). If TAOSC does not receive a response from the mnode for a long time, and there are multiple mnodes, TAOSC will send a request to the next mnode. -4. TAOSC initiates an insert request to master vnode. -5. After vnode inserts the data, it gives a reply to TAOSC, indicating that the insertion is successful. If TAOSC doesn't get a response from vnode for a long time, TAOSC will treat this node as offline. In this case, if there are multiple replicas of the inserted database, TAOSC will issue an insert request to the next vnode in vgroup. -6. TAOSC notifies APP that writing is successful. - -For Step 2 and 3, when TAOSC starts, it does not know the End Point of mnode, so it will directly initiate a request to the configured serving End Point of the cluster. If the dnode that receives the request does not have a mnode configured, it will inform the mnode EP list in a reply message, so that TAOSC will re-issue a request to obtain meta-data to the EP of another new mnode. - -For Step 4 and 5, without caching, TAOSC can't recognize the master in the virtual node group, so assumes that the first vnode is the master and sends a request to it. If this vnode is not the master, it will reply to the actual master as a new target where TAOSC shall send a request to. Once the reply of successful insertion is obtained, TAOSC will cache the information of master node. - -The above is the process of inserting data, and the processes of querying and computing are the same. TAOSC encapsulates and hides all these complicated processes, and it is transparent to applications. - -Through TAOSC caching mechanism, mnode needs to be accessed only when a table is accessed for the first time, so mnode will not become a system bottleneck. However, because schema and vgroup may change (such as load balancing), TAOSC will interact with mnode regularly to automatically update the cache. - -## Storage Model and Data Partitioning/Sharding - -### Storage Model - -The data stored by TDengine include collected time-series data, metadata related to database and tables, tag data, etc. These data are specifically divided into three parts: - -- Time-series data: stored in vnode and composed of data, head and last files. The amount of data is large and query amount depends on the application scenario. Out-of-order writing is allowed, but delete operation is not supported for the time being, and update operation is only allowed when database “update” parameter is set to 1. By adopting the model with **one table for each data collection point**, the data of a given time period is continuously stored, and the writing against one single table is a simple appending operation. Multiple records can be read at one time, thus ensuring the insert and query operation of a single data collection point with the best performance. -- Tag data: meta files stored in vnode. Four standard operations of create, read, update and delete are supported. The amount of data is not large. If there are N tables, there are N records, so all can be stored in memory. To make tag filtering efficient, TDengine supports multi-core and multi-threaded concurrent queries. As long as the computing resources are sufficient, even in face of millions of tables, the tag filtering results will return in milliseconds. -- Metadata: stored in mnode, including system node, user, DB, Table Schema and other information. Four standard operations of create, delete, update and read are supported. The amount of these data are not large and can be stored in memory, moreover, the query amount is not large because of the client cache. Therefore, TDengine uses centralized storage management, however, there will be no performance bottleneck. - -Compared with the typical NoSQL storage model, TDengine stores tag data and time-series data completely separately, which has two major advantages: - -- Reduce the redundancy of tag data storage significantly: general NoSQL database or time-series database adopts K-V storage, in which Key includes a timestamp, a device ID and various tags. Each record carries these duplicated tags, so storage space is wasted. Moreover, if the application needs to add, modify or delete tags on historical data, it has to traverse the data and rewrite them again, which is extremely expensive to operate. -- Aggregate data efficiently between multiple tables: when aggregating data between multiple tables, it first finds out the tables which satisfy the filtering conditions, and then find out the corresponding data blocks of these tables to greatly reduce the data sets to be scanned, thus greatly improving the aggregation efficiency. Moreover, tag data is managed and maintained in a full-memory structure, and tag data queries in tens of millions can return in milliseconds. - -### Data Sharding - -For large-scale data management, to achieve scale-out, it is generally necessary to adopt the Partitioning or Sharding strategy. TDengine implements data sharding via vnode, and time-series data partitioning via one data file for a time range. - -VNode (Virtual Data Node) is responsible for providing writing, query and computing functions for collected time-series data. To facilitate load balancing, data recovery and support heterogeneous environments, TDengine splits a data node into multiple vnodes according to its computing and storage resources. The management of these vnodes is done automatically by TDengine and is completely transparent to the application. - -For a single data collection point, regardless of the amount of data, a vnode (or vnode group, if the number of replicas is greater than 1) has enough computing resource and storage resource to process (if a 16-byte record is generated per second, the original data generated in one year will be less than 0.5 G), so TDengine stores all the data of a table (a data collection point) in one vnode instead of distributing the data to two or more dnodes. Moreover, a vnode can store data from multiple data collection points (tables), and the upper limit of the tables’ quantity for a vnode is one million. By design, all tables in a vnode belong to the same DB. On a data node, unless specially configured, the number of vnodes owned by a DB will not exceed the number of system cores. - -When creating a DB, the system does not allocate resources immediately. However, when creating a table, the system will check if there is an allocated vnode with free tablespace. If so, the table will be created in the vacant vnode immediately. If not, the system will create a new vnode on a dnode from the cluster according to the current workload, and then a table. If there are multiple replicas of a DB, the system does not create only one vnode, but a vgroup (virtual data node group). The system has no limit on the number of vnodes, which is just limited by the computing and storage resources of physical nodes. - -The meta data of each table (including schema, tags, etc.) is also stored in vnode instead of centralized storage in mnode. In fact, this means sharding of meta data, which is good for efficient and parallel tag filtering operations. - -### Data Partitioning - -In addition to vnode sharding, TDengine partitions the time-series data by time range. Each data file contains only one time range of time-series data, and the length of the time range is determined by DB's configuration parameter `“days”`. This method of partitioning by time rang is also convenient to efficiently implement the data retention policy. As long as the data file exceeds the specified number of days (system configuration parameter `“keep”`), it will be automatically deleted. Moreover, different time ranges can be stored in different paths and storage media, so as to facilitate the tiered-storage. Cold/hot data can be stored in different storage media to reduce the storage cost. - -In general, **TDengine splits big data by vnode and time range in two dimensions** to manage the data efficiently with horizontal scalability. - -### Load Balancing - -Each dnode regularly reports its status (including hard disk space, memory size, CPU, network, number of virtual nodes, etc.) to the mnode (virtual management node), so mnode knows the status of the entire cluster. Based on the overall status, when the mnode finds a dnode is overloaded, it will migrate one or more vnodes to other dnodes. During the process, TDengine services keep running and the data insertion, query and computing operations are not affected. - -If the mnode has not received the dnode status for a period of time, the dnode will be treated as offline. When offline lasts a certain period of time (configured by parameter `“offlineThreshold”`), the dnode will be forcibly removed from the cluster by mnode. If the number of replicas of vnodes on this dnode is greater than one, the system will automatically create new replicas on other dnodes to ensure the replica number. If there are other mnodes on this dnode and the number of mnodes replicas is greater than one, the system will automatically create new mnodes on other dnodes to ensure the replica number. - -When new data nodes are added to the cluster, with new computing and storage resources are added, the system will automatically start the load balancing process. - -The load balancing process does not require any manual intervention, and it is transparent to the application. **Note: load balancing is controlled by parameter “balance”, which determines to turn on/off automatic load balancing.** - -## Data Writing and Replication Process - -If a database has N replicas, thus a virtual node group has N virtual nodes, but only one as Master and all others are slaves. When the application writes a new record to system, only the Master vnode can accept the writing request. If a slave vnode receives a writing request, the system will notifies TAOSC to redirect. - -### Master vnode Writing Process - -Master Vnode uses a writing process as follows: - -![TDengine Master Writing Process](write_master.png) -
Figure 3: TDengine Master writing process
- -1. Master vnode receives the application data insertion request, verifies, and moves to next step; -2. If the system configuration parameter `“walLevel”` is greater than 0, vnode will write the original request packet into database log file WAL. If walLevel is set to 2 and fsync is set to 0, TDengine will make WAL data written immediately to ensure that even system goes down, all data can be recovered from database log file; -3. If there are multiple replicas, vnode will forward data packet to slave vnodes in the same virtual node group, and the forwarded packet has a version number with data; -4. Write into memory and add the record to “skip list”; -5. Master vnode returns a confirmation message to the application, indicating a successful writing. -6. If any of Step 2, 3 or 4 fails, the error will directly return to the application. - -### Slave vnode Writing Process - -For a slave vnode, the write process as follows: - -![TDengine Slave Writing Process](write_slave.png) -
Figure 4: TDengine Slave Writing Process
- -1. Slave vnode receives a data insertion request forwarded by Master vnode; -2. If the system configuration parameter `“walLevel”` is greater than 0, vnode will write the original request packet into database log file WAL. If walLevel is set to 2 and fsync is set to 0, TDengine will make WAL data written immediately to ensure that even system goes down, all data can be recovered from database log file; -3. Write into memory and add the record to “skip list”. - -Compared with Master vnode, slave vnode has no forwarding or reply confirmation step, means two steps less. But writing into memory and WAL is exactly the same. - -### Remote Disaster Recovery and IDC Migration - -As above Master and Slave processes discussed, TDengine adopts asynchronous replication for data synchronization. This method can greatly improve the writing performance, with no obvious impact from network delay. By configuring IDC and rack number for each physical node, it can be ensured that for a virtual node group, virtual nodes are composed of physical nodes from different IDC and different racks, thus implementing remote disaster recovery without other tools. - -On the other hand, TDengine supports dynamic modification of the replicas number. Once the number of replicas increases, the newly added virtual nodes will immediately enter the data synchronization process. After synchronization completed, added virtual nodes can provide services. In the synchronization process, master and other synchronized virtual nodes keep serving. With this feature, TDengine can provide IDC migration without service interruption. It is only necessary to add new physical nodes to the existing IDC cluster, and then remove old physical nodes after the data synchronization is completed. - -However, the asynchronous replication has a tiny time window where data can be lost. The specific scenario is as follows: - -1. Master vnode has finished its 5-step operations, confirmed the success of writing to APP, and then went down; -2. Slave vnode receives the write request, then processing fails before writing to the log in Step 2; -3. Slave vnode will become the new master, thus losing one record. - -In theory, for asynchronous replication, there is no guarantee to prevent data loss. However, this window is extremely small, only if mater and slave fail at the same time, and just confirm the successful write to the application before. - -Note: Remote disaster recovery and no-downtime IDC migration are only supported by Enterprise Edition. **Hint: This function is not available yet** - -### Master/slave Selection - -Vnode maintains a version number. When memory data is persisted, the version number will also be persisted. For each data update operation, whether it is time-series data or metadata, this version number will be increased by one. - -When a vnode starts, the roles (master, slave) are uncertain, and the data is in an unsynchronized state. It’s necessary to establish TCP connections with other nodes in the virtual node group and exchange status, including version and its own roles. Through the exchange, the system implements a master-selection process. The rules are as follows: - -1. If there’s only one replica, it’s always master -2. When all replicas are online, the one with latest version is master -3. Over half of online nodes are virtual nodes, and some virtual node is slave, it will automatically become master -4. For 2 and 3, if multiple virtual nodes meet the requirement, the first vnode in virtual node group list will be selected as master - -### Synchronous Replication - -For scenarios with strong data consistency requirements, asynchronous data replication is not applicable, because there is a small probability of data loss. So, TDengine provides a synchronous replication mechanism for users. When creating a database, in addition to specifying the number of replicas, user also needs to specify a new parameter “quorum”. If quorum is greater than one, it means that every time the Master forwards a message to the replica, it needs to wait for “quorum-1” reply confirms before informing the application that data has been successfully written in slave. If “quorum-1” reply confirms are not received within a certain period of time, the master vnode will return an error to the application. - -With synchronous replication, performance of system will decrease and latency will increase. Because metadata needs strong consistent, the default for data synchronization between mnodes is synchronous replication. - -## Caching and Persistence - -### Caching - -TDengine adopts a time-driven cache management strategy (First-In-First-Out, FIFO), also known as a Write-driven Cache Management Mechanism. This strategy is different from the read-driven data caching mode (Least-Recent-Used, LRU), which directly put the most recently written data in the system buffer. When the buffer reaches a threshold, the earliest data are written to disk in batches. Generally speaking, for the use of IoT data, users are most concerned about the newly generated data, that is, the current status. TDengine takes full advantage of this feature to put the most recently arrived (current state) data in the buffer. - -TDengine provides millisecond-level data collecting capability to users through query functions. Putting the recently arrived data directly in the buffer can respond to users' analysis query for the latest piece or batch of data more quickly, and provide faster database query response capability as a whole. In this sense, **TDengine can be used as a data cache by setting appropriate configuration parameters without deploying Redis or other additional cache systems**, which can effectively simplify the system architecture and reduce the operation costs. It should be noted that after the TDengine is restarted, the buffer of the system will be emptied, the previously cached data will be written to disk in batches, and the previously cached data will not be reloaded into the buffer as so in a proprietary key-value cache system. - -Each vnode has its own independent memory, and it is composed of multiple memory blocks of fixed size, and different vnodes are completely isolated. When writing data, similar to the writing of logs, data is sequentially added to memory, but each vnode maintains its own skip list for quick search. When more than one third of the memory block are used, the disk writing operation will start, and the subsequent writing operation is carried out in a new memory block. By this design, one third of the memory blocks in a vnode keep the latest data, so as to achieve the purpose of caching and quick search. The number of memory blocks of a vnode is determined by the configuration parameter “blocks”, and the size of memory blocks is determined by the configuration parameter “cache”. - -### Persistent Storage - -TDengine uses a data-driven method to write the data from buffer into hard disk for persistent storage. When the cached data in vnode reaches a certain volume, TDengine will also pull up the disk-writing thread to write the cached data into persistent storage in order not to block subsequent data writing. TDengine will open a new database log file when the data is written, and delete the old database log file after written successfully to avoid unlimited log growth. - -To make full use of the characteristics of time-series data, TDengine splits the data stored in persistent storage by a vnode into multiple files, each file only saves data for a fixed number of days, which is determined by the system configuration parameter `“days”`. By so, for the given start and end date of a query, you can locate the data files to open immediately without any index, thus greatly speeding up reading operations. - -For time-series data, there is generally a retention policy, which is determined by the system configuration parameter `“keep”`. Data files exceeding this set number of days will be automatically deleted by the system to free up storage space. - -Given “days” and “keep” parameters, the total number of data files in a vnode is: keep/days. The total number of data files should not be too large or too small. 10 to 100 is appropriate. Based on this principle, reasonable days can be set. In the current version, parameter “keep” can be modified, but parameter “days” cannot be modified once it is set. - -In each data file, the data of a table is stored by blocks. A table can have one or more data file blocks. In a file block, data is stored in columns, occupying a continuous storage space, thus greatly improving the reading speed. The size of file block is determined by the system parameter `“maxRows”` (the maximum number of records per block), and the default value is 4096. This value should not be too large or too small. If it is too large, the data locating in search will cost longer; if too small, the index of data block is too large, and the compression efficiency will be low with slower reading speed. - -Each data file (with a .data postfix) has a corresponding index file (with a .head postfix). The index file has summary information of a data block for each table, recording the offset of each data block in the data file, start and end time of data and other information, so as to lead system quickly locate the data to be found. Each data file also has a corresponding last file (with a .last postfix), which is designed to prevent data block fragmentation when written in disk. If the number of written records from a table does not reach the system configuration parameter `“minRows”` (minimum number of records per block), it will be stored in the last file first. When write to disk next time, the newly written records will be merged with the records in last file and then written into data file. - -When data is written to disk, it is decided whether to compress the data according to system configuration parameter `“comp”`. TDengine provides three compression options: no compression, one-stage compression and two-stage compression, corresponding to comp values of 0, 1 and 2 respectively. One-stage compression is carried out according to the type of data. Compression algorithms include delta-delta coding, simple 8B method, zig-zag coding, LZ4 and other algorithms. Two-stage compression is based on one-stage compression and compressed by general compression algorithm, which has higher compression ratio. - -### Tiered Storage - -By default, TDengine saves all data in /var/lib/taos directory, and the data files of each vnode are saved in a different directory under this directory. In order to expand the storage space, minimize the bottleneck of file reading and improve the data throughput rate, TDengine can configure the system parameter “dataDir” to allow multiple mounted hard disks to be used by system at the same time. In addition, TDengine also provides the function of tiered data storage, i.e. storage on different storage media according to the time stamps of data files. For example, the latest data is stored on SSD, the data for more than one week is stored on local hard disk, and the data for more than four weeks is stored on network storage device, thus reducing the storage cost and ensuring efficient data access. The movement of data on different storage media is automatically done by the system and completely transparent to applications. Tiered storage of data is also configured through the system parameter “dataDir”. - -dataDir format is as follows: -``` -dataDir data_path [tier_level] -``` - -Where data_path is the folder path of mount point and tier_level is the media storage-tier. The higher the media storage-tier, means the older the data file. Multiple hard disks can be mounted at the same storage-tier, and data files on the same storage-tier are distributed on all hard disks within the tier. TDengine supports up to 3 tiers of storage, so tier_level values are 0, 1, and 2. When configuring dataDir, there must be only one mount path without specifying tier_level, which is called special mount disk (path). The mount path defaults to level 0 storage media and contains special file links, which cannot be removed, otherwise it will have a devastating impact on the written data. - -Suppose a physical node with six mountable hard disks/mnt/disk1,/mnt/disk2, …,/mnt/disk6, where disk1 and disk2 need to be designated as level 0 storage media, disk3 and disk4 are level 1 storage media, and disk5 and disk6 are level 2 storage media. Disk1 is a special mount disk, you can configure it in/etc/taos/taos.cfg as follows: - -``` -dataDir /mnt/disk1/taos -dataDir /mnt/disk2/taos 0 -dataDir /mnt/disk3/taos 1 -dataDir /mnt/disk4/taos 1 -dataDir /mnt/disk5/taos 2 -dataDir /mnt/disk6/taos 2 -``` - -Mounted disks can also be a non-local network disk, as long as the system can access it. - -Note: Tiered Storage is only supported in Enterprise Edition - -## Data Query - -TDengine provides a variety of query processing functions for tables and STables. In addition to common aggregation queries, TDengine also provides window queries and statistical aggregation functions for time-series data. The query processing of TDengine needs the collaboration of client, vnode and mnode. - -### Single Table Query - -The parsing and verification of SQL statements are completed on the client side. SQL statements are parsed and generate an Abstract Syntax Tree (AST), which is then checksummed. Then request metadata information (table metadata) for the table specified in the query from management node (mnode). - -According to the End Point information in metadata information, the query request is serialized and sent to the data node (dnode) where the table is located. After receiving the query, the dnode identifies the virtual node (vnode) pointed to and forwards the message to the query execution queue of the vnode. The query execution thread of vnode establishes the basic query execution environment, immediately returns the query request and starts executing the query at the same time. - -When client obtains query result, the worker thread in query execution queue of dnode will wait for the execution of vnode execution thread to complete before returning the query result to the requesting client. - -### Aggregation by Time Axis, Downsampling, Interpolation - -The remarkable feature that time-series data is different from ordinary data is that each record has a timestamp, so aggregating data with timestamps on the time axis is an important and distinct feature from common databases. From this point of view, it is similar to the window query of stream computing engine. - -The keyword `interval` is introduced into TDengine to split fixed length time windows on time axis, and the data are aggregated based on time windows, and the data within window range are aggregated as needed. For example: - -```mysql -select count(*) from d1001 interval(1h); -``` - -For the data collected by device D1001, the number of records stored per hour is returned by a 1-hour time window. - -In application scenarios where query results need to be obtained continuously, if there is data missing in a given time interval, the data results in this interval will also be lost. TDengine provides a strategy to interpolate the results of timeline aggregation calculation. The results of time axis aggregation can be interpolated by using keyword Fill. For example: - -```mysql -select count(*) from d1001 interval(1h) fill(prev); -``` - -For the data collected by device D1001, the number of records per hour is counted. If there is no data in a certain hour, statistical data of the previous hour is returned. TDengine provides forward interpolation (prev), linear interpolation (linear), NULL value populating (NULL), and specific value populating (value). - -### Multi-table Aggregation Query - -TDengine creates a separate table for each data collection point, but in practical applications, it is often necessary to aggregate data from different data collection points. In order to perform aggregation operations efficiently, TDengine introduces the concept of STable. STable is used to represent a specific type of data collection point. It is a table set containing multiple tables. The schema of each table in the set is the same, but each table has its own static tag. The tags can be multiple and be added, deleted and modified at any time. Applications can aggregate or statistically operate all or a subset of tables under a STABLE by specifying tag filters, thus greatly simplifying the development of applications. The process is shown in the following figure: - -![Diagram of multi-table aggregation query](multi_tables.png) -
Figure 5: Diagram of multi-table aggregation query
- -1. Application sends a query condition to system; -2. TAOSC sends the STable name to Meta Node(management node); -3. Management node sends the vnode list owned by the STable back to TAOSC; -4. TAOSC sends the computing request together with tag filters to multiple data nodes corresponding to these vnodes; -5. Each vnode first finds out the set of tables within its own node that meet the tag filters from memory, then scans the stored time-series data, completes corresponding aggregation calculations, and returns result to TAOSC; -6. TAOSC finally aggregates the results returned by multiple data nodes and send them back to application. - -Since TDengine stores tag data and time-series data separately in vnode, by filtering tag data in memory, the set of tables that need to participate in aggregation operation is first found, which greatly reduces the volume of data scanned and improves aggregation speed. At the same time, because the data is distributed in multiple vnodes/dnodes, the aggregation operation is carried out concurrently in multiple vnodes, which further improves the aggregation speed. Aggregation functions for ordinary tables and most operations are applicable to STables. The syntax is exactly the same. Please see TAOS SQL for details. - -### Precomputation - -In order to effectively improve the performance of query processing, based-on the unchangeable feature of IoT data, statistical information of data stored in data block is recorded in the head of data block, including max value, min value, and sum. We call it a precomputing unit. If the query processing involves all the data of a whole data block, the pre-calculated results are directly used, and no need to read the data block contents at all. Since the amount of pre-calculated data is much smaller than the actual size of data block stored on disk, for query processing with disk IO as bottleneck, the use of pre-calculated results can greatly reduce the pressure of reading IO and accelerate the query process. The precomputation mechanism is similar to the index BRIN (Block Range Index) of PostgreSQL. - diff --git a/docs-en/21-tdinternal/_category_.yml b/docs-en/21-tdinternal/_category_.yml deleted file mode 100644 index 254128aecebae304818125365822a7b08cdf7eab..0000000000000000000000000000000000000000 --- a/docs-en/21-tdinternal/_category_.yml +++ /dev/null @@ -1,4 +0,0 @@ -label: TDengine Inside -link: - slug: /tdinternal/ - type: generated-index \ No newline at end of file diff --git a/docs-en/21-tdinternal/dnode.png b/docs-en/21-tdinternal/dnode.png deleted file mode 100644 index cea87dcccba5d2761996e5dde998022d86487eb9..0000000000000000000000000000000000000000 Binary files a/docs-en/21-tdinternal/dnode.png and /dev/null differ diff --git a/docs-en/21-tdinternal/message.png b/docs-en/21-tdinternal/message.png deleted file mode 100644 index 715a8bd37ee9fe7e96eacce4e7ff563fedeefbee..0000000000000000000000000000000000000000 Binary files a/docs-en/21-tdinternal/message.png and /dev/null differ diff --git a/docs-en/21-tdinternal/modules.png b/docs-en/21-tdinternal/modules.png deleted file mode 100644 index 10ae4703a6cbbf66afea325ce4c0f919f7769a07..0000000000000000000000000000000000000000 Binary files a/docs-en/21-tdinternal/modules.png and /dev/null differ diff --git a/docs-en/21-tdinternal/multi_tables.png b/docs-en/21-tdinternal/multi_tables.png deleted file mode 100644 index 0cefaab6a9a4cdd671c671f7c6186dea41415ff0..0000000000000000000000000000000000000000 Binary files a/docs-en/21-tdinternal/multi_tables.png and /dev/null differ diff --git a/docs-en/21-tdinternal/replica-forward.png b/docs-en/21-tdinternal/replica-forward.png deleted file mode 100644 index bf616e030b130603eceb5dccfd30b4a1dfa68ea5..0000000000000000000000000000000000000000 Binary files a/docs-en/21-tdinternal/replica-forward.png and /dev/null differ diff --git a/docs-en/21-tdinternal/replica-master.png b/docs-en/21-tdinternal/replica-master.png deleted file mode 100644 index cb33f1ce98661563693215d8fc73b003235c7668..0000000000000000000000000000000000000000 Binary files a/docs-en/21-tdinternal/replica-master.png and /dev/null differ diff --git a/docs-en/21-tdinternal/replica-restore.png b/docs-en/21-tdinternal/replica-restore.png deleted file mode 100644 index 1558e5ed0108d23efdc6b5d9ea0e44a1dff45d28..0000000000000000000000000000000000000000 Binary files a/docs-en/21-tdinternal/replica-restore.png and /dev/null differ diff --git a/docs-en/21-tdinternal/structure.png b/docs-en/21-tdinternal/structure.png deleted file mode 100644 index 4fc8f47ab0a30d95b85ba1d85105726ed981e56e..0000000000000000000000000000000000000000 Binary files a/docs-en/21-tdinternal/structure.png and /dev/null differ diff --git a/docs-en/21-tdinternal/vnode.png b/docs-en/21-tdinternal/vnode.png deleted file mode 100644 index e6148d4907cf9a18bc52251f712d5c685651b7f5..0000000000000000000000000000000000000000 Binary files a/docs-en/21-tdinternal/vnode.png and /dev/null differ diff --git a/docs-en/21-tdinternal/write_master.png b/docs-en/21-tdinternal/write_master.png deleted file mode 100644 index ff2dfc20bfc2ecf956a2aab1a8965a7bbcae4387..0000000000000000000000000000000000000000 Binary files a/docs-en/21-tdinternal/write_master.png and /dev/null differ diff --git a/docs-en/21-tdinternal/write_slave.png b/docs-en/21-tdinternal/write_slave.png deleted file mode 100644 index cacb2cb6bcc4f4d934e979862387e1345bbac078..0000000000000000000000000000000000000000 Binary files a/docs-en/21-tdinternal/write_slave.png and /dev/null differ diff --git a/docs-en/25-application/01-telegraf.md b/docs-en/25-application/01-telegraf.md deleted file mode 100644 index e3d8b90eb20cdc06b222bf5ed2c016cddf359901..0000000000000000000000000000000000000000 --- a/docs-en/25-application/01-telegraf.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -sidebar_label: TDengine + Telegraf + Grafana -title: Quickly Build IT DevOps Visualization System with TDengine + Telegraf + Grafana ---- - -## Background - -TDengine is a big data platform designed and optimized for IoT (Internet of Things), Vehicle Telematics, Industrial Internet, IT DevOps, etc. by TAOSData. Since it opened its source code in July 2019, it has won the favor of a large number of time-series data developers with its innovative data modeling design, convenient installation, easy-to-use programming interface, and powerful data writing and query performance. - -IT DevOps metric data usually are time sensitive, for example: - -- System resource metrics: CPU, memory, IO, bandwidth, etc. -- Software system metrics: health status, number of connections, number of requests, number of timeouts, number of errors, response time, service type, and other business-related metrics. - -Current mainstream IT DevOps system usually include a data collection module, a data persistent module, and a visualization module; Telegraf and Grafana are one of the most popular data collection modules and visualization modules, respectively. The data persistent module is available in a wide range of options, with OpenTSDB or InfluxDB being the most popular. TDengine, as an emerging time-series big data platform, has the advantages of high performance, high reliability, easy management and easy maintenance. - -This article introduces how to quickly build a TDengine + Telegraf + Grafana based IT DevOps visualization system without writing even a single line of code and by simply modifying a few lines of configuration files. The architecture is as follows. - -![IT-DevOps-Solutions-Telegraf.png](/img/IT-DevOps-Solutions-Telegraf.png) - -## Installation steps - -### Installing Telegraf, Grafana and TDengine - -To install Telegraf, Grafana, and TDengine, please refer to the relevant official documentation. - -### Telegraf - -Please refer to the [official documentation](https://portal.influxdata.com/downloads/). - -### Grafana - -Please refer to the [official documentation](https://grafana.com/grafana/download). - -### TDengine - -Download the latest TDengine-server 2.4.0.x or above from the [Downloads](http://taosdata.com/cn/all-downloads/) page on the Taos Data website and install it. - -## Data Connection Setup - -### Download TDengine plug-in to grafana plug-in directory - -```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 -``` - -### Modify /etc/telegraf/telegraf.conf - -For the configuration method, add the following text to `/etc/telegraf/telegraf.conf`, where `database name` should be the name where you want to store Telegraf data in TDengine, `TDengine server/cluster host`, `username` and `password` please fill in the actual TDengine values. - -```text -[[outputs.http]] - url = "http://:6041/influxdb/v1/write?db=" - method = "POST" - timeout = "5s" - username = "" - password = "" - data_format = "influx" - influx_max_line_bytes = 250 -``` - -Then restart telegraf: - -```bash -sudo systemctl start telegraf -``` - -### Importing the Dashboard - -Log in to the Grafana interface using a web browser at `IP:3000`, with the system's initial username and password being `admin/admin`. -Click on the gear icon on the left and select `Plugins`, you should find the TDengine data source plugin icon. -Click on the plus icon on the left and select `Import` to get the data from `https://github.com/taosdata/grafanaplugin/blob/master/examples/telegraf/grafana/dashboards/telegraf-dashboard- v0.1.0.json`, download the dashboard JSON file and import it. You will then see the dashboard in the following screen. - -![IT-DevOps-Solutions-telegraf-dashboard.png](/img/IT-DevOps-Solutions-telegraf-dashboard.png) - -## Wrap-up - -The above demonstrates how to quickly build a IT DevOps visualization system. Thanks to the new schemaless protocol parsing feature in TDengine version 2.4.0.0 and the powerful ecological software adaptation capability, users can build an efficient and easy-to-use IT DevOps visualization system in just a few minutes. -Please refer to the official documentation and product implementation cases for other features. diff --git a/docs-en/25-application/02-collectd.md b/docs-en/25-application/02-collectd.md deleted file mode 100644 index 2ac37618fafe11e71b215313e53f89b6c302f7cb..0000000000000000000000000000000000000000 --- a/docs-en/25-application/02-collectd.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -sidebar_label: TDengine + collectd/StatsD + Grafana -title: Quickly build an IT DevOps visualization system using TDengine + collectd/StatsD + Grafana ---- - -## Background - -TDengine is a big data platform designed and optimized for IoT (Internet of Things), Vehicle Telematics, Industrial Internet, IT DevOps, etc. by TAOSData. Since it opened its source code in July 2019, it has won the favor of a large number of time-series data developers with its innovative data modeling design, convenient installation, easy-to-use programming interface, and powerful data writing and query performance. - -IT DevOps metric data usually are time sensitive, for example: - -- System resource metrics: CPU, memory, IO, bandwidth, etc. -- Software system metrics: health status, number of connections, number of requests, number of timeouts, number of errors, response time, service type, and other business-related metrics. - -The current mainstream IT DevOps visualization system usually contains a data collection module, a data persistent module, and a visual display module. collectd/StatsD, as an old-fashion open source data collection tool, has a wide user base. However, collectd/StatsD has limited functionality, and often needs to be combined with Telegraf, Grafana, and a time-series database to build a complete monitoring system. -The new version of TDengine supports multiple data protocols and can accept data from collectd and StatsD directly, and provides Grafana dashboard for graphical display. - -This article introduces how to quickly build an IT DevOps visualization system based on TDengine + collectd / StatsD + Grafana without writing even a single line of code but by simply modifying a few lines of configuration files. The architecture is shown in the following figure. - -![IT-DevOps-Solutions-Collectd-StatsD.png](/img/IT-DevOps-Solutions-Collectd-StatsD.png) - -## Installation Steps - -To install collectd, StatsD, Grafana, and TDengine, please refer to the official documentation. - -### Installing collectd - -Please refer to the [official documentation](https://collectd.org/documentation.shtml). - -### Installing StatsD - -Please refer to the [official documentation](https://github.com/statsd/statsd). - -### Install Grafana - -Please refer to the [official documentation](https://grafana.com/grafana/download). - -### Install TDengine - -Download the latest TDengine-server 2.4.0.x or above from the [Downloads](http://taosdata.com/cn/all-downloads/) page on the TAOSData website and install it. - -## Data Connection Setup - -### Copy the TDengine plugin to the grafana plugin directory - -```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 -``` - -### Configure collectd - -Add the following to the `/etc/collectd/collectd.conf` file, where the `host` and `port` should be the actual values of the TDengine and taosAdapter configurations. - -```text -LoadPlugin network - - Server "" "" - - -sudo systemctl start collectd -``` - -### Configure StatsD - -Start StatsD after adding the following to the `config.js` file, where the `host` and `port` are the actual values of the TDengine and taosAdapter configurations. - -```text -backends section add ". /backends/repeater" -Add { host:'', port: } to the repeater section -``` - -### Importing the Dashboard - -Use a web browser to access the server running Grafana on port 3000 `host:3000` to log into the Grafana interface with the initial system username and password of `admin/admin`. -Click on the gear icon on the left and select `Plugins`, you should find the TDengine data source plugin icon. - -#### Importing the collectd dashboard - -Download the dashboard json from `https://github.com/taosdata/grafanaplugin/blob/master/examples/collectd/grafana/dashboards/collect-metrics-with-tdengine-v0.1.0.json`, click the plus icon on the left and select Import, follow the instructions to import the JSON file. After that, you can see -The dashboard can be seen in the following screen. - -![IT-DevOps-Solutions-collectd-dashboard.png](/img/IT-DevOps-Solutions-collectd-dashboard.png) - -#### import collectd dashboard - -Download the dashboard json file from `https://github.com/taosdata/grafanaplugin/blob/master/examples/collectd/grafana/dashboards/collect-metrics-with-tdengine-v0.1.0.json`. Download the dashboard json file, click the plus icon on the left side and select `Import`, and follow the interface prompts to select the JSON file to import. After that, you can see -dashboard with the following interface. - -![IT-DevOps-Solutions-collectd-dashboard.png](/img/IT-DevOps-Solutions-collectd-dashboard.png) - -#### Importing the StatsD dashboard - -Download the dashboard json from `https://github.com/taosdata/grafanaplugin/blob/master/examples/statsd/dashboards/statsd-with-tdengine-v0.1.0.json`. Click on the plus icon on the left and select `Import`, and follow the interface prompts to import the JSON file. You will then see the dashboard in the following screen. -![IT-DevOps-Solutions-statsd-dashboard.png](/img/IT-DevOps-Solutions-statsd-dashboard.png) - -## Wrap-up - -TDengine, as an emerging time-series big data platform, has the advantages of high performance, high reliability, easy management and easy maintenance. Thanks to the new schemaless protocol parsing function in TDengine version 2.4.0.0 and the powerful ecological software adaptation capability, users can build an efficient and easy-to-use IT DevOps visualization system or adapt to an existing system in just a few minutes. - -For TDengine's powerful data writing and querying performance and other features, please refer to the official documentation and successful product implementation cases. diff --git a/docs-en/25-application/03-immigrate.md b/docs-en/25-application/03-immigrate.md deleted file mode 100644 index 585761b699f30cfcc8a8232466421f6db7b5eeb8..0000000000000000000000000000000000000000 --- a/docs-en/25-application/03-immigrate.md +++ /dev/null @@ -1,435 +0,0 @@ ---- -sidebar_label: OpenTSDB Migration to TDengine -title: Best Practices for Migrating OpenTSDB Applications to TDengine ---- - -As a distributed, scalable, HBase-based distributed time-series database software, thanks to its first-mover advantage, OpenTSDB has been introduced and widely used in DevOps by people. However, using new technologies like cloud computing, microservices, and containerization technology with rapid development. Enterprise-level services are becoming more and more diverse. The architecture is becoming more complex. - -From this situation, it increasingly plagues to use of OpenTSDB as a DevOps backend storage for monitoring by performance issues and delayed feature upgrades. The resulting increase in application deployment costs and reduced operational efficiency. -These problems are becoming increasingly severe as the system scales up. - -To meet the fast-growing IoT big data market and technical needs, TAOSData developed an innovative big-data processing product, **TDengine**. - -After learning the advantages of many traditional relational databases and NoSQL databases, stream computing engines, and message queues, TDengine has its unique benefits in time-series big data processing. TDengine can effectively solve the problems currently encountered by OpenTSDB. - -Compared with OpenTSDB, TDengine has the following distinctive features. - -- Performance of data writing and querying far exceeds that of OpenTSDB. -- Efficient compression mechanism for time-series data, which compresses less than 1/5 of the storage space on disk. -- The installation and deployment are straightforward. A single installation package can complete the installation and deployment and does not rely on other third-party software. The entire installation and deployment process in a few seconds; -- The built-in functions cover all of OpenTSDB's query functions. And support more time-series data query functions, scalar functions, and aggregation functions. And support advanced query functions such as multiple time-window aggregations, join query, expression operation, multiple group aggregation, user-defined sorting, and user-defined functions. Adopting SQL-like syntax rules is more straightforward and has no learning cost. -- Supports up to 128 tags, with a total tag length of 16 KB. -- In addition to the REST interface, it also provides interfaces to Java, Python, C, Rust, Go, C# and other languages. Its supports a variety of enterprise-class standard connector protocols such as JDBC. - -If we migrate the applications originally running on OpenTSDB to TDengine, we will effectively reduce the compute and storage resource consumption and the number of deployed servers. And will also significantly reduce the operation and maintenance costs, making operation and maintenance management more straightforward and more accessible, and considerably reducing the total cost of ownership. Like OpenTSDB, TDengine has also been open-sourced, including the stand-alone version and the cluster version source code. So there is no need to be concerned about the vendor-lock problem. - -We will explain how to migrate OpenTSDB applications to TDengine quickly, securely, and reliably without coding, using the most typical DevOps scenarios. Subsequent chapters will go into more depth to facilitate migration for non-DevOps systems. - -## DevOps Application Quick Migration - -### 1. Typical Application Scenarios - -The following figure (Figure 1) shows the system's overall architecture for a typical DevOps application scenario. - -**Figure 1. Typical architecture in a DevOps scenario** -Figure 1. [IT-DevOps-Solutions-Immigrate-OpenTSDB-Arch](/img/IT-DevOps-Solutions-Immigrate-OpenTSDB-Arch.jpg "Figure 1. Typical architecture in a DevOps scenario") - -In this application scenario, there are Agent tools deployed in the application environment to collect machine metrics, network metrics, and application metrics. Data collectors to aggregate information collected by agents, systems for persistent data storage and management, and tools for monitoring data visualization (e.g., Grafana, etc.). - -The agents deployed in the application nodes are responsible for providing operational metrics from different sources to collectd/Statsd. And collectd/StatsD is accountable for pushing the aggregated data to the OpenTSDB cluster system and then visualizing the data using the visualization kanban board software, Grafana. - -### 2. Migration Services - -- **TDengine installation and deployment** - -First of all, please install TDengine. Download the latest stable version of TDengine from the official website and install it. For help with using various installation packages, please refer to the blog ["Installation and Uninstallation of TDengine Multiple Installation Packages"](https://www.taosdata.com/blog/2019/08/09/566.html). - -Note that once the installation is complete, do not start the `taosd` service immediately, but after properly configuring the parameters. - -- **Adjusting the data collector configuration** - -TDengine version 2.4 and later version includes `taosAdapter`. taosAdapter is a stateless, rapidly elastic, and scalable component. taosAdapter supports Influxdb's Line Protocol and OpenTSDB's telnet/JSON writing protocol specification, providing rich data access capabilities, effectively saving user migration costs and reducing the difficulty of user migration. - -Users can flexibly deploy taosAdapter instances according to their requirements to rapidly improve the throughput of data writes in conjunction with the needs of scenarios and provide guarantees for data writes in different application scenarios. - -Through taosAdapter, users can directly push the data collected by `collectd` or `StatsD` to TDengine to achieve seamless migration of application scenarios, which is very easy and convenient. taosAdapter also supports Telegraf, Icinga, TCollector, and node_exporter data. For more details, please refer to [taosAdapter](/reference/taosadapter/). - -If using collectd, modify the configuration file in its default location `/etc/collectd/collectd.conf` to point to the IP address and port of the node where to deploy taosAdapter. For example, assuming the taosAdapter IP address is 192.168.1.130 and port 6046, configure it as follows. - -```html -LoadPlugin write_tsdb - - - Host "192.168.1.130" Port "6046" HostTags "status=production" StoreRates - false AlwaysAppendDS false - - -``` - -You can use collectd and push the data to taosAdapter utilizing the push to OpenTSDB plugin. taosAdapter will call the API to write the data to TDengine, thus completing the writing of the data. If you are using StatsD, adjust the profile information accordingly. - -- **Tuning the Dashboard system** - -After writing the data to TDengine properly, you can adapt Grafana to visualize the data written to TDengine. To obtain and use the Grafana plugin provided by TDengine, please refer to [Links to other tools](/third-party/grafana). - -TDengine provides two sets of Dashboard templates by default, and users only need to import the templates from the Grafana directory into Grafana to activate their use. - -**Importing Grafana Templates** Figure 2. -! [](/img/IT-DevOps-Solutions-Immigrate-OpenTSDB-Dashboard.jpg "Figure 2. Importing a Grafana Template") - -After the above steps, you completed the migration to replace OpenTSDB with TDengine. You can see that the whole process is straightforward, there is no need to write any code, and only some configuration files need to be adjusted to meet the migration work. - -### 3. Post-migration architecture - -After completing the migration, the figure below (Figure 3) shows the system's overall architecture. The whole process of the acquisition side, the data writing, and the monitoring and presentation side are all kept stable, except for a few configuration adjustments, which do not involve any critical changes or alterations. OpenTSDB to TDengine migration action, using TDengine more powerful processing power and query performance. - -In most DevOps scenarios, if you have a small OpenTSDB cluster (3 or fewer nodes) for providing the storage layer of DevOps and rely on OpenTSDB to give a data persistence layer and query capabilities, you can safely replace OpenTSDB with TDengine. TDengine will save more compute and storage resources. With the same compute resource allocation, a single TDengine can meet the service capacity provided by 3 to 5 OpenTSDB nodes. If the scale is more prominent, then TDengine clustering is required. - -Suppose your application is particularly complex, or the application domain is not a DevOps scenario. You can continue reading subsequent chapters for a more comprehensive and in-depth look at the advanced topics of migrating an OpenTSDB application to TDengine. - -**Figure 3. System architecture after migration** -! [IT-DevOps-Solutions-Immigrate-TDengine-Arch](/img/IT-DevOps-Solutions-Immigrate-TDengine-Arch.jpg "Figure 3. System architecture after migration completion") - -## Migration evaluation and strategy for other scenarios - -### 1. Differences between TDengine and OpenTSDB - -This chapter describes the differences between OpenTSDB and TDengine at the system functionality level. After reading this chapter, you can fully evaluate whether you can migrate some complex OpenTSDB-based applications to TDengine, and what you should pay attention to after migration. - -TDengine currently only supports Grafana for visual kanban rendering, so if your application uses front-end kanban boards other than Grafana (e.g., [TSDash](https://github.com/facebook/tsdash), [Status Wolf](https://github) .com/box/StatusWolf), etc.). You cannot directly migrate those front-end kanbans to TDengine, and the front-end kanban will need to be ported to Grafana to work correctly. - -TDengine version 2.3.0.x only supports collectd and StatsD as data collection aggregation software but will provide more data collection aggregation software in the future. If you use other data aggregators on the collection side, your application needs to be ported to these two data aggregation systems to write data correctly. -In addition to the two data aggregator software protocols mentioned above, TDengine also supports writing data directly via InfluxDB's row protocol and OpenTSDB's data writing protocol, JSON format. You can rewrite the logic on the data push side to write data using the row protocols supported by TDengine. - -In addition, if your application uses the following features of OpenTSDB, you need to understand the following considerations before migrating your application to TDengine. - -1. `/api/stats`: If your application uses this feature to monitor the service status of OpenTSDB, and you have built the relevant logic to link the processing in your application, then this part of the status reading and fetching logic needs to be re-adapted to TDengine. TDengine provides a new mechanism for handling cluster state monitoring to meet the monitoring and maintenance needs of your application. -2. `/api/tree`: If you rely on this feature of OpenTSDB for the hierarchical organization and maintenance of timelines, you cannot migrate it directly to TDengine, which uses a database -> super table -> sub-table hierarchy to organize and maintain timelines, with all timelines belonging to the same super table in the same system hierarchy, but it is possible to simulate a logical multi-level structure of the application through the unique construction of different tag values. -3. `Rollup And PreAggregates`: The use of Rollup and PreAggregates requires the application to decide where to access the Rollup results and, in some scenarios, to access the actual results. The opacity of this structure makes the application processing logic extraordinarily complex and not portable at all. We think this strategy is a compromise when the time-series database does not. -TDengine does not support automatic downsampling of multiple timelines and preaggregation (for a range of periods) for the time being. Still, thanks to its high-performance query processing logic can provide very high-performance query responses without relying on Rollup and preaggregation (for a range of periods), making your application query processing logic much more straightforward. -The logic is much simpler. -4. `Rate`: TDengine provides two functions to calculate the rate of change of values, namely `Derivative` (the result is consistent with the Derivative behavior of InfluxDB) and `IRate` (the result is compatible with the IRate function in Prometheus). However, the results of these two functions are slightly different from Rate, but the functions are more powerful overall. In addition, TDengine supports all the calculation functions provided by OpenTSDB, and TDengine's query functions are much more potent than those supported by OpenTSDB, which can significantly simplify the processing logic of your application. - -Through the above introduction, I believe you should be able to understand the changes brought about by the migration of OpenTSDB to TDengine. And this information will also help you correctly determine whether you would migrate your application to TDengine to experience the powerful and convenient time-series data processing capability provided by TDengine. - -### 2. Migration strategy suggestion - -First, the OpenTSDB-based system migration involves data schema design, system scale estimation, and data write end transformation, data streaming, and application adaptation; after that, the two systems will run in parallel for a while and then migrate the historical data to TDengine. Of course, if your application has some functions that strongly depend on the above OpenTSDB features and you do not want to stop using them, you can migrate the historical data to TDengine. -You can consider keeping the original OpenTSDB system running while starting TDengine to provide the primary services. - -## Data model design - -On the one hand, TDengine requires a strict schema definition for its incoming data. On the other hand, the data model of TDengine is richer than that of OpenTSDB, and the multi-valued model is compatible with all single-valued model building requirements. - -Let us now assume a DevOps scenario where we use collectd to collect the underlying metrics of the device, including memory, swap, disk, etc. The schema in OpenTSDB is as follows. - -| metric | value name | type | 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 requires the data stored to have a data schema, i.e., you need to create a super table and specify the schema of the super table before writing the data. For data schema creation, you have two ways to do this: 1) Take advantage of TDengine's native data writing support for OpenTSDB by calling the TDengine API to write (text line or JSON format) -and automate the creation of single-value models. This approach does not require significant adjustments to the data writing application, nor does it require converting the written data format. - -At the C level, TDengine provides the `taos_schemaless_insert()` function to write data in OpenTSDB format directly (in early version this function was named `taos_insert_lines()`). Please refer to the sample code `schemaless.c` in the installation package directory as reference. - -(2) based on a complete understanding of TDengine's data model, to establish the mapping relationship between OpenTSDB and TDengine's data model adjustment manually. Considering that OpenTSDB is a single-value mapping model, recommended using the single-value model in TDengine. TDengine can support both multi-value and single-value models. - -- **Single-valued model**. - -The steps are as follows: use the name of the metrics as the name of the TDengine super table, which build with two basic data columns - timestamp and value, and the label of the super table is equivalent to the label information of the metrics, and the number of labels is equal to the number of labels of the metrics. The names of sub-tables are named with fixed rules: `metric + '_' + tags1_value + '_' + tag2_value + '_' + tag3_value ...` as the sub-table name. - -Create 3 super tables in TDengine. - -```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)); -``` - -For sub-tables use dynamic table creation as shown below. - -```sql -insert into memory_vm130_memory_buffered_collectd using memory tags('vm130', 'memory', ' buffer', 'collectd') values(1632979445, 3.0656); -``` - -The final system will have about 340 sub-tables and three super-tables. Note that if the use of concatenated tagged values causes the sub-table names to exceed the system limit (191 bytes), then some encoding (e.g., MD5) needs to be used to convert them to an acceptable length. - -- **Multi-value model** - -Suppose you want to take advantage of TDengine's multi-value modeling capabilities. In that case, you need first to meet the requirements that different collection quantities have the same collection frequency and can reach the **data write side simultaneously via a message queue**, thus ensuring writing multiple metrics at once using SQL statements. The metric's name is used as the name of the super table to create a multi-column model of data that has the same collection frequency and can arrive simultaneously. The names of the sub-tables are named using a fixed rule. Each of the above metrics contains only one measurement value, so converting it into a multi-value model is impossible. - -## Data triage and application adaptation - -Subscribe data from the message queue and start the adapted writer to write the data. - -After writing the data starts for a while, you can use SQL statements to check whether the amount of data written meets the expected writing requirements. Use the following SQL statement to count the amount of data. - -```sql -select count(*) from memory -``` - -After completing the query, if the data written does not differ from what is expected and there are no abnormal error messages from the writing program itself, you can confirm that the written data is complete and valid. - -TDengine does not support querying, or data fetching using the OpenTSDB query syntax but does provide a counterpart for each of the OpenTSDB queries. The corresponding query processing can be adapted and applied in a manner obtained by examining Appendix 1. To fully understand the types of queries supported by TDengine, refer to the TDengine user manual. - -TDengine supports the standard JDBC 3.0 interface for manipulating databases, but you can also use other types of high-level language connectors for querying and reading data to suit your application. Please read the user manual for specific operations and usage. - -## Historical Data Migration - -### 1. Use the tool to migrate data automatically - -To facilitate historical data migration, we provide a plug-in for the data synchronization tool DataX, which can automatically write data into TDengine.The automatic data migration of DataX can only support the data migration process of a single value model. - -For the specific usage of DataX and how to use DataX to write data to TDengine, please refer to [DataX-based TDengine Data Migration Tool](https://www.taosdata.com/blog/2021/10/26/3156.html). - -After migrating via DataX, we found that we can significantly improve the efficiency of migrating historical data by starting multiple processes and migrating numerous metrics simultaneously. The following are some records of the migration process. I wish to use these for application migration as a reference. - -| Number of datax instances (number of concurrent processes) | Migration record speed (pieces/second) | -| ----------------------------- | ------------------- -- | -| 1 | About 139,000 | -| 2 | About 218,000 | -| 3 | About 249,000 | -| 5 | About 295,000 | -| 10 | About 330,000 | - -
(Note: The test data comes from a single-node Intel(R) Core(TM) i7-10700 CPU@2.90GHz 16-core 64G hardware device, the channel and batchSize are 8 and 1000 respectively, and each record contains 10 tags) - -### 2. Manual data migration - -Suppose you need to use the multi-value model for data writing. In that case, you need to develop a tool to export data from OpenTSDB, confirm which timelines can be merged and imported into the same timeline, and then pass the time to import simultaneously through the SQL statement—written to the database. - -Manual migration of data requires attention to the following two issues: - -1) When storing the exported data on the disk, the disk needs to have enough storage space to accommodate the exported data files fully. Adopting the partial import mode to avoid the shortage of disk file storage after the total amount of data is exported. Preferentially export the timelines belonging to the same super table. Then the exported data files are imported into the TDengine system. - -2) Under the full load of the system, if there are enough remaining computing and IO resources, establish a multi-threaded importing to maximize the efficiency of data migration. Considering the vast load that data parsing brings to the CPU, it is necessary to control the maximum number of parallel tasks to avoid the overall overload of the system triggered by importing historical data. - -Due to the ease of operation of TDengine itself, there is no need to perform index maintenance and data format change processing in the entire process. The whole process only needs to be executed sequentially. - -When wholly importing the historical data into TDengine, the two systems run simultaneously and then switch the query request to TDengine to achieve seamless application switching. - -## Appendix 1: OpenTSDB query function correspondence table - -### Avg - -Equivalent function: avg - -Example: - -```sql -SELECT avg(val) FROM (SELECT first(val) FROM super_table WHERE ts >= startTime and ts <= endTime INTERVAL(20s) Fill(linear)) INTERVAL(20s) -``` - -Remark: - -1. The value in Interval needs to be the same as the interval value in the outer query. -2. The interpolation processing in TDengine needs to use subqueries to assist in the completion. As shown above, it is enough to specify the interpolation type in the inner query. Since the interpolation of the values ​​in OpenTSDB uses linear interpolation, use fill( in the interpolation clause. linear) to declare the interpolation type. The following functions with the exact interpolation calculation requirements are processed by this method. -3. The parameter 20s in Interval indicates that the inner query will generate results according to a time window of 20 seconds. In an actual query, it needs to adjust to the time interval between different records. It ensures that producing interpolation results equivalent to the original data. -4. Due to the particular interpolation strategy and mechanism of OpenTSDB, the method of the first interpolation and then calculation in the aggregate query (Aggregate) makes the calculation results impossible to be utterly consistent with TDengine. But in the case of downsampling (Downsample), TDengine and OpenTSDB can obtain consistent results (since OpenTSDB performs aggregation and downsampling queries). - -### Count - -Equivalent function: count - -Example: - -```sql -select count(\*) from super_table_name; -``` - -### Dev - -Equivalent function: stddev - -Example: - -```sql -Select stddev(val) from table_name -``` - -### Estimated percentiles - -Equivalent function: apercentile - -Example: - -```sql -Select apercentile(col1, 50, “t-digest”) from table_name -``` - -Remark: - -1. During the approximate query processing, OpenTSDB uses the t-digest algorithm by default, so in order to obtain the same calculation result, the algorithm used needs to be specified in the `apercentile()` function. TDengine can support two different approximation processing algorithms, declared by "default" and "t-digest" respectively. - -### First - -Equivalent function: first - -Example: - -```sql -Select first(col1) from table_name -``` - -### Last - -Equivalent function: last - -Example: - -```sql -Select last(col1) from table_name -``` - -### Max - -Equivalent function: max - -Example: - -```sql -Select max(value) from (select first(val) value from table_name interval(10s) fill(linear)) interval(10s) -``` - -Note: The Max function requires interpolation for the reasons described above. - -### Min - -Equivalent function: min - -Example: - -```sql -Select min(value) from (select first(val) value from table_name interval(10s) fill(linear)) interval(10s); -``` - -### MinMax - -Equivalent function: max - -```sql -Select max(val) from table_name -``` - -Note: This function has no interpolation requirements, so it can be directly calculated. - -### MimMin - -Equivalent function: min - -```sql -Select min(val) from table_name -``` - -Note: This function has no interpolation requirements, so it can be directly calculated. - -### Percentile - -Equivalent function: percentile - -Remark: - -### Sum - -Equivalent function: sum - -```sql -Select max(value) from (select first(val) value from table_name interval(10s) fill(linear)) interval(10s) -``` - -Note: This function has no interpolation requirements, so it can be directly calculated. - -### Zimsum - -Equivalent function: sum - -```sql -Select sum(val) from table_name -``` - -Note: This function has no interpolation requirements, so it can be directly calculated. - -Complete example: - -````json -// OpenTSDB query JSON -query = { -"start": 1510560000, -"end": 1515000009, -"queries": [{ -"aggregator": "count", -"metric": "cpu.usage_user", -}] -} - -// Equivalent query SQL: -SELECT count(*) -FROM `cpu.usage_user` -WHERE ts>=1510560000 AND ts<=1515000009 -```` - -## Appendix 2: Resource Estimation Methodology - -### Data generation environment - -We still use the hypothetical environment from Chapter 4. There are three measurements. Respectively: the data writing rate of temperature and humidity is one record every 5 seconds, and the timeline is 100,000. The writing rate of air pollution is one record every 10 seconds, the timeline is 10,000, and the query request frequency is 500 QPS. - -### Storage resource estimation - -Assuming that the number of sensor devices that generate data and need to be stored is `n`, the frequency of data generation is `t` per second, and the length of each record is `L` bytes, the scale of data generated per day is `n * t * L` bytes. Assuming the compression ratio is `C`, the daily data size is `(n * t * L)/C` bytes. The storage resources are estimated to accommodate the data scale for 1.5 years. In the production environment, the compression ratio C of TDengine is generally between 5 and 7. -With additional 20% ​​redundancy, you can calculate the required storage resources: - -```matlab -(n * t * L) * (365 * 1.5) * (1+20%)/C -```` - -Combined with the above calculation formula, bring the parameters into the formula, and the raw data scale generated every year is 11.8TB without considering the label information. Note that since tag information is associated with each timeline in TDengine, not every record. The scale of the amount of data to be recorded is somewhat reduced relative to the generated data, and this part of label data can be ignored as a whole. Assuming a compression ratio of 5, the size of the retained data ends up being 2.56 TB. - -### Storage Device Selection Considerations - -The hard disk should be capable of better random read performance. Considering using an SSD as much as possible is a better choice. A disk with better random read performance is a great help to improve the system's query performance and improve the query response performance as a whole system. To obtain better query performance, the performance index of the single-threaded random read IOPS of the hard disk device should not be lower than 1000, and it is better to reach 5000 IOPS or more. Recommend to use `fio` utility software to evaluate the running performance (please refer to Appendix 1 for specific usage) for the random IO read of the current device to confirm whether it can meet the requirements of random read of large files. - -Hard disk writing performance has little effect on TDengine. The TDengine writing process adopts the append write mode, so as long as it has good sequential write performance, both SAS hard disks and SSDs in the general sense can well meet TDengine's requirements for disk write performance. - -### Computational resource estimates - -Due to the particularity of IoT data, after the frequency of data generation is consistent, the writing process of TDengine maintains a relatively fixed amount of resource consumption (computing and storage). According to the [TDengine Operation and Maintenance Guide](/operation/) description, the system consumes less than 1 CPU core at 22,000 writes per second. - -In estimating the CPU resources consumed by the query, assuming that the application requires the database to provide 10,000 QPS, the CPU time consumed by each query is about 1 ms. The query provided by each core per second is 1,000 QPS, which satisfies 10,000 QPS. The query request requires at least 10 cores. For the system as a whole system to have less than 50% CPU load, the entire cluster needs twice as many as 10 cores or 20 cores. - -### Memory resource estimation - -The database allocates 16MB\*3 buffer memory for each Vnode by default. If the cluster system includes 22 CPU cores, TDengine will create 22 Vnodes (virtual nodes) by default. Each Vnode contains 1000 tables, which can accommodate all the tables. Then it takes about 1.5 hours to write a block, which triggers the drop, and no adjustment is required. A total of 22 Vnodes require about 1GB of memory cache. Considering the memory needed for the query, assuming that the memory overhead of each query is about 50MB, the memory required for 500 queries concurrently is about 25GB. - -In summary, using a single 16-core 32GB machine or a cluster of 2 8-core 16GB machines is enough. - -## Appendix 3: Cluster Deployment and Startup - -TDengine provides a wealth of help documents to explain many aspects of cluster installation and deployment. Here is the list of corresponding document for your reference. - -### Cluster Deployment - -The first is TDengine installation. Download the latest stable version of TDengine from the official website, and install it. Please refer to the blog ["Installation and Uninstallation of Various Installation Packages of TDengine"](https://www.taosdata.com/blog/2019/08/09/566.html) for the various installation package formats. - -Note that once the installation is complete, do not immediately start the `taosd` service, but start it after correctly configuring the parameters. - -### Set running parameters and start the service - -To ensure that the system can obtain the necessary information for regular operation. Please set the following vital parameters correctly on the server: - -FQDN, firstEp, secondEP, dataDir, logDir, tmpDir, serverPort. For the specific meaning and setting requirements of each parameter, please refer to the document "[TDengine Cluster Installation and Management](/cluster/)" - -Follow the same steps to set parameters on the nodes that need running, start the taosd service, and then add Dnodes to the cluster. - -Finally, start `taos` and execute the `show dnodes` command. If you can see all the nodes that have joined the cluster, the cluster building process was successfully completed. For specific operation procedures and precautions, please refer to the document "[TDengine Cluster Installation and Management](/cluster/)". - -## Appendix 4: Super Table Names - -Since OpenTSDB's metric name has a dot (".") in it, for example, a metric with a name like "cpu.usage_user", the dot has a special meaning in TDengine and is a separator used to separate database and table names. TDengine also provides "escape" characters to allow users to use keywords or special separators (e.g., dots) in (super)table names. To use special characters, enclose the table name in escape characters, e.g.: `cpu.usage_user`. It is a valid (super) table name. - -## Appendix 5: Reference Articles - -1. [Using TDengine + collectd/StatsD + Grafana to quickly build an IT operation and maintenance monitoring system](/application/collectd/) -2. [Write collected data directly to TDengine through collectd](/third-party/collectd/) diff --git a/docs-en/25-application/_category_.yml b/docs-en/25-application/_category_.yml deleted file mode 100644 index 912a96126865fabc1eea24d8fc12e78b217b0527..0000000000000000000000000000000000000000 --- a/docs-en/25-application/_category_.yml +++ /dev/null @@ -1,4 +0,0 @@ -label: Application Practice -link: - slug: /application/ - type: generated-index diff --git a/docs-en/27-train-faq/01-faq.md b/docs-en/27-train-faq/01-faq.md deleted file mode 100644 index fac12cb44eaff68ec74d3019e537aecb0291410f..0000000000000000000000000000000000000000 --- a/docs-en/27-train-faq/01-faq.md +++ /dev/null @@ -1,224 +0,0 @@ ---- -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 excuted SQL is not a DML or a DDL？** - - 请更新至最新的 JDBC 驱动 - - ```xml - - com.taosdata.jdbc - taos-jdbcdriver - 2.0.27 - - ``` - -**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. 时间戳的时区信息是怎样处理的？** - - TDengine 中时间戳的时区总是由客户端进行处理，而与服务端无关。具体来说，客户端会对 SQL 语句中的时间戳进行时区转换，转为 UTC 时区（即 Unix 时间戳——Unix Timestamp）再交由服务端进行写入和查询；在读取数据时，服务端也是采用 UTC 时区提供原始数据，客户端收到后再根据本地设置，把时间戳转换为本地系统所要求的时区进行显示。 - - 客户端在处理时间戳字符串时，会采取如下逻辑： - - 1. 在未做特殊设置的情况下，客户端默认使用所在操作系统的时区设置。 - 2. 如果在 taos.cfg 中设置了 timezone 参数，则客户端会以这个配置文件中的设置为准。 - 3. 如果在 C/C++/Java/Python 等各种编程语言的 Connector Driver 中，在建立数据库连接时显式指定了 timezone，那么会以这个指定的时区设置为准。例如 Java Connector 的 JDBC URL 中就有 timezone 参数。 - 4. 在书写 SQL 语句时，也可以直接使用 Unix 时间戳（例如 `1554984068000`）或带有时区的时间戳字符串，也即以 RFC 3339 格式（例如 `2013-04-12T15:52:01.123+08:00`）或 ISO-8601 格式（例如 `2013-04-12T15:52:01.123+0800`）来书写时间戳，此时这些时间戳的取值将不再受其他时区设置的影响。 - - - -**19. TDengine 都会用到哪些网络端口？** - - 在 TDengine 2.0 版本中，会用到以下这些网络端口（以默认端口 6030 为前提进行说明，如果修改了配置文件中的设置，那么这里列举的端口都会出现变化），管理员可以参考这里的信息调整防火墙设置： - -| 协议 | 默认端口 | 用途说明 | 修改方法 | -| :--- | :-------- | :---------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------- | -| 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+以上版本）。 | -| TCP | 6045 | 支持 collectd 数据接入端口。 | 随 taosAdapter 启动参数设置变化（2.3.0.1+以上版本）。 | -| TCP | 6060 | 企业版内 Monitor 服务的网络端口。 | | -| UDP | 6030-6034 | 客户端与服务端之间通讯。 | 随 serverPort 端口变化。 | -| UDP | 6035-6039 | 多节点集群的节点间通讯。 | 随 serverPort 端口变化。 | - -**20. 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。 diff --git a/docs-en/27-train-faq/02-video.mdx b/docs-en/27-train-faq/02-video.mdx deleted file mode 100644 index b644412332fe817ea7fdc2c9ddc176ecc9858c56..0000000000000000000000000000000000000000 --- a/docs-en/27-train-faq/02-video.mdx +++ /dev/null @@ -1,25 +0,0 @@ ---- -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-en/27-train-faq/03-docker.md b/docs-en/27-train-faq/03-docker.md deleted file mode 100644 index a86b72a39e94c4db7d3b229fba2260df36ef2a88..0000000000000000000000000000000000000000 --- a/docs-en/27-train-faq/03-docker.md +++ /dev/null @@ -1,330 +0,0 @@ ---- -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 - -在 TDegnine 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-en/27-train-faq/_category_.yml b/docs-en/27-train-faq/_category_.yml deleted file mode 100644 index 0394904db35d58bd55d56aec79e68375d0717466..0000000000000000000000000000000000000000 --- a/docs-en/27-train-faq/_category_.yml +++ /dev/null @@ -1,4 +0,0 @@ -label: FAQ & Others -link: - slug: /train-faq/ - type: generated-index diff --git a/docs-examples/c/async_query_example.c b/docs-examples/c/async_query_example.c deleted file mode 100644 index 77002891bb4c03f7c7e32b329678e8a124f12a99..0000000000000000000000000000000000000000 --- a/docs-examples/c/async_query_example.c +++ /dev/null @@ -1,195 +0,0 @@ -// compile with: -// gcc -o async_query_example async_query_example.c -ltaos - -#include -#include -#include -#include -#include -#include - -typedef int16_t VarDataLenT; - -#define TSDB_NCHAR_SIZE sizeof(int32_t) -#define VARSTR_HEADER_SIZE sizeof(VarDataLenT) - -#define GET_FLOAT_VAL(x) (*(float *)(x)) -#define GET_DOUBLE_VAL(x) (*(double *)(x)) - -#define varDataLen(v) ((VarDataLenT *)(v))[0] - -int printRow(char *str, TAOS_ROW row, TAOS_FIELD *fields, int numFields) { - int len = 0; - char split = ' '; - - for (int i = 0; i < numFields; ++i) { - if (i > 0) { - str[len++] = split; - } - - if (row[i] == NULL) { - len += sprintf(str + len, "%s", "NULL"); - continue; - } - - switch (fields[i].type) { - case TSDB_DATA_TYPE_TINYINT: - len += sprintf(str + len, "%d", *((int8_t *)row[i])); - break; - - case TSDB_DATA_TYPE_UTINYINT: - len += sprintf(str + len, "%u", *((uint8_t *)row[i])); - break; - - case TSDB_DATA_TYPE_SMALLINT: - len += sprintf(str + len, "%d", *((int16_t *)row[i])); - break; - - case TSDB_DATA_TYPE_USMALLINT: - len += sprintf(str + len, "%u", *((uint16_t *)row[i])); - break; - - case TSDB_DATA_TYPE_INT: - len += sprintf(str + len, "%d", *((int32_t *)row[i])); - break; - - case TSDB_DATA_TYPE_UINT: - len += sprintf(str + len, "%u", *((uint32_t *)row[i])); - break; - - case TSDB_DATA_TYPE_BIGINT: - len += sprintf(str + len, "%" PRId64, *((int64_t *)row[i])); - break; - - case TSDB_DATA_TYPE_UBIGINT: - len += sprintf(str + len, "%" PRIu64, *((uint64_t *)row[i])); - break; - - case TSDB_DATA_TYPE_FLOAT: { - float fv = 0; - fv = GET_FLOAT_VAL(row[i]); - len += sprintf(str + len, "%f", fv); - } break; - - case TSDB_DATA_TYPE_DOUBLE: { - double dv = 0; - dv = GET_DOUBLE_VAL(row[i]); - len += sprintf(str + len, "%lf", dv); - } break; - - case TSDB_DATA_TYPE_BINARY: - case TSDB_DATA_TYPE_NCHAR: { - int32_t charLen = varDataLen((char *)row[i] - VARSTR_HEADER_SIZE); - memcpy(str + len, row[i], charLen); - len += charLen; - } break; - - case TSDB_DATA_TYPE_TIMESTAMP: - len += sprintf(str + len, "%" PRId64, *((int64_t *)row[i])); - break; - - case TSDB_DATA_TYPE_BOOL: - len += sprintf(str + len, "%d", *((int8_t *)row[i])); - default: - break; - } - } - - return len; -} - -void printHeader(TAOS_RES *res) { - int numFields = taos_num_fields(res); - TAOS_FIELD *fields = taos_fetch_fields(res); - char header[256] = {0}; - int len = 0; - for (int i = 0; i < numFields; ++i) { - len += sprintf(header + len, "%s ", fields[i].name); - } - puts(header); -} - -// ANCHOR: demo - -/** - * @brief call back function of taos_fetch_row_a - * - * @param param : the third parameter you passed to taos_fetch_row_a - * @param res : pointer of TAOS_RES - * @param numOfRow : number of rows fetched in this batch. will be 0 if there is no more data. - * @return void* - */ -void *fetch_row_callback(void *param, TAOS_RES *res, int numOfRow) { - printf("numOfRow = %d \n", numOfRow); - int numFields = taos_num_fields(res); - TAOS_FIELD *fields = taos_fetch_fields(res); - TAOS *_taos = (TAOS *)param; - if (numOfRow > 0) { - for (int i = 0; i < numOfRow; ++i) { - TAOS_ROW row = taos_fetch_row(res); - char temp[256] = {0}; - printRow(temp, row, fields, numFields); - puts(temp); - } - taos_fetch_rows_a(res, fetch_row_callback, _taos); - } else { - printf("no more data, close the connection.\n"); - taos_free_result(res); - taos_close(_taos); - taos_cleanup(); - } -} - -/** - * @brief callback function of taos_query_a - * - * @param param: the fourth parameter you passed to taos_query_a - * @param res : the result set - * @param code : status code - * @return void* - */ -void *select_callback(void *param, TAOS_RES *res, int code) { - printf("query callback ...\n"); - TAOS *_taos = (TAOS *)param; - if (code == 0 && res) { - printHeader(res); - taos_fetch_rows_a(res, fetch_row_callback, _taos); - } else { - printf("failed to exeuce taos_query. error: %s\n", taos_errstr(res)); - taos_free_result(res); - taos_close(_taos); - taos_cleanup(); - exit(EXIT_FAILURE); - } -} - -int main() { - TAOS *taos = taos_connect("localhost", "root", "taosdata", "power", 6030); - if (taos == NULL) { - puts("failed to connect to server"); - exit(EXIT_FAILURE); - } - // param one is the connection returned by taos_connect. - // param two is the SQL to execute. - // param three is the callback function. - // param four can be any pointer. It will be passed to your callback function as the first parameter. we use taos - // here, because we want to close it after getting data. - taos_query_a(taos, "SELECT * FROM meters", select_callback, taos); - sleep(1); -} - -// output: -// query callback ... -// ts current voltage phase location groupid -// numOfRow = 8 -// 1538548685000 10.300000 219 0.310000 beijing.chaoyang 2 -// 1538548695000 12.600000 218 0.330000 beijing.chaoyang 2 -// 1538548696800 12.300000 221 0.310000 beijing.chaoyang 2 -// 1538548696650 10.300000 218 0.250000 beijing.chaoyang 3 -// 1538548685500 11.800000 221 0.280000 beijing.haidian 2 -// 1538548696600 13.400000 223 0.290000 beijing.haidian 2 -// 1538548685000 10.800000 223 0.290000 beijing.haidian 3 -// 1538548686500 11.500000 221 0.350000 beijing.haidian 3 -// numOfRow = 0 -// no more data, close the connection. -// ANCHOR_END: demo \ No newline at end of file diff --git a/docs-examples/c/connect_example.c b/docs-examples/c/connect_example.c deleted file mode 100644 index ff0891e08267840fd5141d1b4271109d832c1c51..0000000000000000000000000000000000000000 --- a/docs-examples/c/connect_example.c +++ /dev/null @@ -1,24 +0,0 @@ -// compile with -// gcc connect_example.c -o connect_example -ltaos -#include -#include -#include "taos.h" - -int main() { - const char *host = "localhost"; - const char *user = "root"; - const char *passwd = "taosdata"; - // if don't want to connect to a default db, set it to NULL or "" - const char *db = NULL; - uint16_t port = 0; // 0 means use the default port - TAOS *taos = taos_connect(host, user, passwd, db, port); - if (taos == NULL) { - int errono = taos_errno(NULL); - char *msg = taos_errstr(NULL); - printf("%d, %s\n", errono, msg); - } else { - printf("connected\n"); - taos_close(taos); - } - taos_cleanup(); -} diff --git a/docs-examples/c/error_handle_example.c b/docs-examples/c/error_handle_example.c deleted file mode 100644 index 36bb7f12f77a46230add5af82b68e6fb86ddfe77..0000000000000000000000000000000000000000 --- a/docs-examples/c/error_handle_example.c +++ /dev/null @@ -1,24 +0,0 @@ -// compile with -// gcc error_handle_example.c -o error_handle_example -ltaos -#include -#include -#include "taos.h" - -int main() { - const char *host = "localhost"; - const char *user = "root"; - const char *passwd = "taosdata"; - // if don't want to connect to a default db, set it to NULL or "" - const char *db = "notexist"; - uint16_t port = 0; // 0 means use the default port - TAOS *taos = taos_connect(host, user, passwd, db, port); - if (taos == NULL) { - int errono = taos_errno(NULL); - char *msg = taos_errstr(NULL); - printf("%d, %s\n", errono, msg); - } else { - printf("connected\n"); - taos_close(taos); - } - taos_cleanup(); -} diff --git a/docs-examples/c/insert_example.c b/docs-examples/c/insert_example.c deleted file mode 100644 index ca12be9314efbda707dbd05449c746794c209743..0000000000000000000000000000000000000000 --- a/docs-examples/c/insert_example.c +++ /dev/null @@ -1,51 +0,0 @@ -// compile with -// gcc -o insert_example insert_example.c -ltaos -#include -#include -#include "taos.h" - - -/** - * @brief execute sql and print affected rows. - * - * @param taos - * @param sql - */ -void executeSQL(TAOS *taos, const char *sql) { - TAOS_RES *res = taos_query(taos, sql); - int code = taos_errno(res); - if (code != 0) { - printf("Error code: %d; Message: %s\n", code, taos_errstr(res)); - taos_free_result(res); - taos_close(taos); - exit(EXIT_FAILURE); - } - int affectedRows = taos_affected_rows(res); - printf("affected rows %d\n", affectedRows); - taos_free_result(res); -} - - - -int main() { - TAOS *taos = taos_connect("localhost", "root", "taosdata", NULL, 6030); - if (taos == NULL) { - printf("failed to connect to server\n"); - exit(EXIT_FAILURE); - } - executeSQL(taos, "CREATE DATABASE power"); - executeSQL(taos, "USE power"); - executeSQL(taos, "CREATE STABLE meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)"); - executeSQL(taos, "INSERT INTO d1001 USING meters TAGS(Beijing.Chaoyang, 2) VALUES ('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)" - "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) ('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) ('2018-10-03 14:38:06.500', 11.50000, 221, 0.35000)"); - taos_close(taos); - taos_cleanup(); -} - -// output: -// affected rows 0 -// affected rows 0 -// affected rows 0 -// affected rows 8 \ No newline at end of file diff --git a/docs-examples/c/json_protocol_example.c b/docs-examples/c/json_protocol_example.c deleted file mode 100644 index 182fd201308facc80c76f36cfa57580784d70413..0000000000000000000000000000000000000000 --- a/docs-examples/c/json_protocol_example.c +++ /dev/null @@ -1,52 +0,0 @@ -// compile with -// gcc -o json_protocol_example json_protocol_example.c -ltaos -#include -#include -#include -#include "taos.h" - -void executeSQL(TAOS *taos, const char *sql) { - TAOS_RES *res = taos_query(taos, sql); - int code = taos_errno(res); - if (code != 0) { - printf("%s\n", taos_errstr(res)); - taos_free_result(res); - taos_close(taos); - exit(EXIT_FAILURE); - } - taos_free_result(res); -} - -// ANCHOR: main -int main() { - TAOS *taos = taos_connect("localhost", "root", "taosdata", "", 6030); - if (taos == NULL) { - printf("failed to connect to server\n"); - exit(EXIT_FAILURE); - } - executeSQL(taos, "DROP DATABASE IF EXISTS test"); - executeSQL(taos, "CREATE DATABASE test"); - executeSQL(taos, "USE test"); - char *line = - "[{\"metric\": \"meters.current\", \"timestamp\": 1648432611249, \"value\": 10.3, \"tags\": {\"location\": " - "\"Beijing.Chaoyang\", \"groupid\": 2}},{\"metric\": \"meters.voltage\", \"timestamp\": 1648432611249, " - "\"value\": 219, \"tags\": {\"location\": \"Beijing.Haidian\", \"groupid\": 1}},{\"metric\": \"meters.current\", " - "\"timestamp\": 1648432611250, \"value\": 12.6, \"tags\": {\"location\": \"Beijing.Chaoyang\", \"groupid\": " - "2}},{\"metric\": \"meters.voltage\", \"timestamp\": 1648432611250, \"value\": 221, \"tags\": {\"location\": " - "\"Beijing.Haidian\", \"groupid\": 1}}]"; - - char *lines[] = {line}; - TAOS_RES *res = taos_schemaless_insert(taos, lines, 1, TSDB_SML_JSON_PROTOCOL, TSDB_SML_TIMESTAMP_NOT_CONFIGURED); - if (taos_errno(res) != 0) { - printf("failed to insert schema-less data, reason: %s\n", taos_errstr(res)); - } else { - int affectedRow = taos_affected_rows(res); - printf("successfully inserted %d rows\n", affectedRow); - } - taos_free_result(res); - taos_close(taos); - taos_cleanup(); -} -// output: -// successfully inserted 4 rows -// ANCHOR_END: main diff --git a/docs-examples/c/line_example.c b/docs-examples/c/line_example.c deleted file mode 100644 index 8dd4b1a5075369625645959da0476b76b9fbf290..0000000000000000000000000000000000000000 --- a/docs-examples/c/line_example.c +++ /dev/null @@ -1,47 +0,0 @@ -// compile with -// gcc -o line_example line_example.c -ltaos -#include -#include -#include -#include "taos.h" - -void executeSQL(TAOS *taos, const char *sql) { - TAOS_RES *res = taos_query(taos, sql); - int code = taos_errno(res); - if (code != 0) { - printf("%s\n", taos_errstr(res)); - taos_free_result(res); - taos_close(taos); - exit(EXIT_FAILURE); - } - taos_free_result(res); -} - -// ANCHOR: main -int main() { - TAOS *taos = taos_connect("localhost", "root", "taosdata", "", 0); - if (taos == NULL) { - printf("failed to connect to server\n"); - exit(EXIT_FAILURE); - } - executeSQL(taos, "DROP DATABASE IF EXISTS test"); - executeSQL(taos, "CREATE DATABASE test"); - executeSQL(taos, "USE test"); - char *lines[] = {"meters,location=Beijing.Haidian,groupid=2 current=11.8,voltage=221,phase=0.28 1648432611249", - "meters,location=Beijing.Haidian,groupid=2 current=13.4,voltage=223,phase=0.29 1648432611250", - "meters,location=Beijing.Haidian,groupid=3 current=10.8,voltage=223,phase=0.29 1648432611249", - "meters,location=Beijing.Haidian,groupid=3 current=11.3,voltage=221,phase=0.35 1648432611250"}; - TAOS_RES *res = taos_schemaless_insert(taos, lines, 4, TSDB_SML_LINE_PROTOCOL, TSDB_SML_TIMESTAMP_MILLI_SECONDS); - if (taos_errno(res) != 0) { - printf("failed to insert schema-less data, reason: %s\n", taos_errstr(res)); - } else { - int affectedRows = taos_affected_rows(res); - printf("successfully inserted %d rows\n", affectedRows); - } - taos_free_result(res); - taos_close(taos); - taos_cleanup(); -} -// output: -// successfully inserted 4 rows -// ANCHOR_END: main \ No newline at end of file diff --git a/docs-examples/c/multi_bind_example.c b/docs-examples/c/multi_bind_example.c deleted file mode 100644 index fe11df9caad3e216fbd0b1ff2f40a54fe3ba86e5..0000000000000000000000000000000000000000 --- a/docs-examples/c/multi_bind_example.c +++ /dev/null @@ -1,147 +0,0 @@ -// compile with -// gcc -o multi_bind_example multi_bind_example.c -ltaos -#include -#include -#include -#include "taos.h" - -/** - * @brief execute sql only and ignore result set - * - * @param taos - * @param sql - */ -void executeSQL(TAOS *taos, const char *sql) { - TAOS_RES *res = taos_query(taos, sql); - int code = taos_errno(res); - if (code != 0) { - printf("%s\n", taos_errstr(res)); - taos_free_result(res); - taos_close(taos); - exit(EXIT_FAILURE); - } - taos_free_result(res); -} - -/** - * @brief exit program when error occur. - * - * @param stmt - * @param code - * @param msg - */ -void checkErrorCode(TAOS_STMT *stmt, int code, const char *msg) { - if (code != 0) { - printf("%s. error: %s\n", msg, taos_stmt_errstr(stmt)); - taos_stmt_close(stmt); - exit(EXIT_FAILURE); - } -} - -/** - * @brief insert data using stmt API - * - * @param taos - */ -void insertData(TAOS *taos) { - // init - TAOS_STMT *stmt = taos_stmt_init(taos); - // prepare - const char *sql = "INSERT INTO ? USING meters TAGS(?, ?) values(?, ?, ?, ?)"; - int code = taos_stmt_prepare(stmt, sql, 0); - checkErrorCode(stmt, code, "failed to execute taos_stmt_prepare"); - // bind table name and tags - TAOS_BIND tags[2]; - char *location = "Beijing.Chaoyang"; - int groupId = 2; - tags[0].buffer_type = TSDB_DATA_TYPE_BINARY; - tags[0].buffer_length = strlen(location); - tags[0].length = &tags[0].buffer_length; - tags[0].buffer = location; - tags[0].is_null = NULL; - - tags[1].buffer_type = TSDB_DATA_TYPE_INT; - tags[1].buffer_length = sizeof(int); - tags[1].length = &tags[1].buffer_length; - tags[1].buffer = &groupId; - tags[1].is_null = NULL; - - code = taos_stmt_set_tbname_tags(stmt, "d1001", tags); - checkErrorCode(stmt, code, "failed to execute taos_stmt_set_tbname_tags"); - - // highlight-start - // insert two rows with multi binds - TAOS_MULTI_BIND params[4]; - // values to bind - int64_t ts[] = {1648432611249, 1648432611749}; - float current[] = {10.3, 12.6}; - int voltage[] = {219, 218}; - float phase[] = {0.31, 0.33}; - // is_null array - char is_null[2] = {0}; - // length array - int32_t int64Len[2] = {sizeof(int64_t)}; - int32_t floatLen[2] = {sizeof(float)}; - int32_t intLen[2] = {sizeof(int)}; - - params[0].buffer_type = TSDB_DATA_TYPE_TIMESTAMP; - params[0].buffer_length = sizeof(int64_t); - params[0].buffer = ts; - params[0].length = int64Len; - params[0].is_null = is_null; - params[0].num = 2; - - params[1].buffer_type = TSDB_DATA_TYPE_FLOAT; - params[1].buffer_length = sizeof(float); - params[1].buffer = current; - params[1].length = floatLen; - params[1].is_null = is_null; - params[1].num = 2; - - params[2].buffer_type = TSDB_DATA_TYPE_INT; - params[2].buffer_length = sizeof(int); - params[2].buffer = voltage; - params[2].length = intLen; - params[2].is_null = is_null; - params[2].num = 2; - - params[3].buffer_type = TSDB_DATA_TYPE_FLOAT; - params[3].buffer_length = sizeof(float); - params[3].buffer = phase; - params[3].length = floatLen; - params[3].is_null = is_null; - params[3].num = 2; - - code = taos_stmt_bind_param_batch(stmt, params); // bind batch - checkErrorCode(stmt, code, "failed to execute taos_stmt_bind_param_batch"); - code = taos_stmt_add_batch(stmt); // add batch - checkErrorCode(stmt, code, "failed to execute taos_stmt_add_batch"); - // highlight-end - // execute - code = taos_stmt_execute(stmt); - checkErrorCode(stmt, code, "failed to execute taos_stmt_execute"); - int affectedRows = taos_stmt_affected_rows(stmt); - printf("successfully inserted %d rows\n", affectedRows); - // close - taos_stmt_close(stmt); -} - -int main() { - TAOS *taos = taos_connect("localhost", "root", "taosdata", NULL, 6030); - if (taos == NULL) { - printf("failed to connect to server\n"); - exit(EXIT_FAILURE); - } - executeSQL(taos, "DROP DATABASE IF EXISTS power"); - executeSQL(taos, "CREATE DATABASE power"); - executeSQL(taos, "USE power"); - executeSQL(taos, - "CREATE STABLE meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), " - "groupId INT)"); - insertData(taos); - taos_close(taos); - taos_cleanup(); -} - -// output: -// successfully inserted 2 rows \ No newline at end of file diff --git a/docs-examples/c/query_example.c b/docs-examples/c/query_example.c deleted file mode 100644 index 4314ac4fe2f5b5251af2462bf0b20ebeed7cac5e..0000000000000000000000000000000000000000 --- a/docs-examples/c/query_example.c +++ /dev/null @@ -1,143 +0,0 @@ -// compile with: -// gcc -o query_example query_example.c -ltaos -#include -#include -#include -#include -#include - -typedef int16_t VarDataLenT; - -#define TSDB_NCHAR_SIZE sizeof(int32_t) -#define VARSTR_HEADER_SIZE sizeof(VarDataLenT) - -#define GET_FLOAT_VAL(x) (*(float *)(x)) -#define GET_DOUBLE_VAL(x) (*(double *)(x)) - -#define varDataLen(v) ((VarDataLenT *)(v))[0] - -int printRow(char *str, TAOS_ROW row, TAOS_FIELD *fields, int numFields) { - int len = 0; - char split = ' '; - - for (int i = 0; i < numFields; ++i) { - if (i > 0) { - str[len++] = split; - } - - if (row[i] == NULL) { - len += sprintf(str + len, "%s", "NULL"); - continue; - } - - switch (fields[i].type) { - case TSDB_DATA_TYPE_TINYINT: - len += sprintf(str + len, "%d", *((int8_t *)row[i])); - break; - - case TSDB_DATA_TYPE_UTINYINT: - len += sprintf(str + len, "%u", *((uint8_t *)row[i])); - break; - - case TSDB_DATA_TYPE_SMALLINT: - len += sprintf(str + len, "%d", *((int16_t *)row[i])); - break; - - case TSDB_DATA_TYPE_USMALLINT: - len += sprintf(str + len, "%u", *((uint16_t *)row[i])); - break; - - case TSDB_DATA_TYPE_INT: - len += sprintf(str + len, "%d", *((int32_t *)row[i])); - break; - - case TSDB_DATA_TYPE_UINT: - len += sprintf(str + len, "%u", *((uint32_t *)row[i])); - break; - - case TSDB_DATA_TYPE_BIGINT: - len += sprintf(str + len, "%" PRId64, *((int64_t *)row[i])); - break; - - case TSDB_DATA_TYPE_UBIGINT: - len += sprintf(str + len, "%" PRIu64, *((uint64_t *)row[i])); - break; - - case TSDB_DATA_TYPE_FLOAT: { - float fv = 0; - fv = GET_FLOAT_VAL(row[i]); - len += sprintf(str + len, "%f", fv); - } break; - - case TSDB_DATA_TYPE_DOUBLE: { - double dv = 0; - dv = GET_DOUBLE_VAL(row[i]); - len += sprintf(str + len, "%lf", dv); - } break; - - case TSDB_DATA_TYPE_BINARY: - case TSDB_DATA_TYPE_NCHAR: { - int32_t charLen = varDataLen((char *)row[i] - VARSTR_HEADER_SIZE); - memcpy(str + len, row[i], charLen); - len += charLen; - } break; - - case TSDB_DATA_TYPE_TIMESTAMP: - len += sprintf(str + len, "%" PRId64, *((int64_t *)row[i])); - break; - - case TSDB_DATA_TYPE_BOOL: - len += sprintf(str + len, "%d", *((int8_t *)row[i])); - default: - break; - } - } - - return len; -} - -/** - * @brief print column name and values of each row - * - * @param res - * @return int - */ -static int printResult(TAOS_RES *res) { - int numFields = taos_num_fields(res); - TAOS_FIELD *fields = taos_fetch_fields(res); - char header[256] = {0}; - int len = 0; - for (int i = 0; i < numFields; ++i) { - len += sprintf(header + len, "%s ", fields[i].name); - } - puts(header); - - TAOS_ROW row = NULL; - while ((row = taos_fetch_row(res))) { - char temp[256] = {0}; - printRow(temp, row, fields, numFields); - puts(temp); - } -} - -int main() { - TAOS *taos = taos_connect("localhost", "root", "taosdata", "power", 6030); - if (taos == NULL) { - puts("failed to connect to server"); - exit(EXIT_FAILURE); - } - TAOS_RES *res = taos_query(taos, "SELECT * FROM meters LIMIT 2"); - if (taos_errno(res) != 0) { - printf("failed to exeuce taos_query. error: %s\n", taos_errstr(res)); - exit(EXIT_FAILURE); - } - printResult(res); - taos_free_result(res); - taos_close(taos); - taos_cleanup(); -} - -// output: -// ts current voltage phase location groupid -// 1648432611249 10.300000 219 0.310000 Beijing.Chaoyang 2 -// 1648432611749 12.600000 218 0.330000 Beijing.Chaoyang 2 \ No newline at end of file diff --git a/docs-examples/c/stmt_example.c b/docs-examples/c/stmt_example.c deleted file mode 100644 index fab1506f953ef68050e4318406fa2ba1a0202929..0000000000000000000000000000000000000000 --- a/docs-examples/c/stmt_example.c +++ /dev/null @@ -1,141 +0,0 @@ -// compile with -// gcc -o stmt_example stmt_example.c -ltaos -#include -#include -#include -#include "taos.h" - -/** - * @brief execute sql only. - * - * @param taos - * @param sql - */ -void executeSQL(TAOS *taos, const char *sql) { - TAOS_RES *res = taos_query(taos, sql); - int code = taos_errno(res); - if (code != 0) { - printf("%s\n", taos_errstr(res)); - taos_free_result(res); - taos_close(taos); - exit(EXIT_FAILURE); - } - taos_free_result(res); -} - -/** - * @brief check return status and exit program when error occur. - * - * @param stmt - * @param code - * @param msg - */ -void checkErrorCode(TAOS_STMT *stmt, int code, const char* msg) { - if (code != 0) { - printf("%s. error: %s\n", msg, taos_stmt_errstr(stmt)); - taos_stmt_close(stmt); - exit(EXIT_FAILURE); - } -} - -typedef struct { - int64_t ts; - float current; - int voltage; - float phase; -} Row; - -/** - * @brief insert data using stmt API - * - * @param taos - */ -void insertData(TAOS *taos) { - // init - TAOS_STMT *stmt = taos_stmt_init(taos); - // prepare - const char *sql = "INSERT INTO ? USING meters TAGS(?, ?) VALUES(?, ?, ?, ?)"; - int code = taos_stmt_prepare(stmt, sql, 0); - checkErrorCode(stmt, code, "failed to execute taos_stmt_prepare"); - // bind table name and tags - TAOS_BIND tags[2]; - char* location = "Beijing.Chaoyang"; - int groupId = 2; - tags[0].buffer_type = TSDB_DATA_TYPE_BINARY; - tags[0].buffer_length = strlen(location); - tags[0].length = &tags[0].buffer_length; - tags[0].buffer = location; - tags[0].is_null = NULL; - - tags[1].buffer_type = TSDB_DATA_TYPE_INT; - tags[1].buffer_length = sizeof(int); - tags[1].length = &tags[1].buffer_length; - tags[1].buffer = &groupId; - tags[1].is_null = NULL; - - code = taos_stmt_set_tbname_tags(stmt, "d1001", tags); - checkErrorCode(stmt, code, "failed to execute taos_stmt_set_tbname_tags"); - - // insert two rows - Row rows[2] = { - {1648432611249, 10.3, 219, 0.31}, - {1648432611749, 12.6, 218, 0.33}, - }; - - TAOS_BIND values[4]; - values[0].buffer_type = TSDB_DATA_TYPE_TIMESTAMP; - values[0].buffer_length = sizeof(int64_t); - values[0].length = &values[0].buffer_length; - values[0].is_null = NULL; - - values[1].buffer_type = TSDB_DATA_TYPE_FLOAT; - values[1].buffer_length = sizeof(float); - values[1].length = &values[1].buffer_length; - values[1].is_null = NULL; - - values[2].buffer_type = TSDB_DATA_TYPE_INT; - values[2].buffer_length = sizeof(int); - values[2].length = &values[2].buffer_length; - values[2].is_null = NULL; - - values[3].buffer_type = TSDB_DATA_TYPE_FLOAT; - values[3].buffer_length = sizeof(float); - values[3].length = &values[3].buffer_length; - values[3].is_null = NULL; - - for (int i = 0; i < 2; ++i) { - values[0].buffer = &rows[i].ts; - values[1].buffer = &rows[i].current; - values[2].buffer = &rows[i].voltage; - values[3].buffer = &rows[i].phase; - code = taos_stmt_bind_param(stmt, values); // bind param - checkErrorCode(stmt, code, "failed to execute taos_stmt_bind_param"); - code = taos_stmt_add_batch(stmt); // add batch - checkErrorCode(stmt, code, "failed to execute taos_stmt_add_batch"); - } - // execute - code = taos_stmt_execute(stmt); - checkErrorCode(stmt, code, "failed to execute taos_stmt_execute"); - int affectedRows = taos_stmt_affected_rows(stmt); - printf("successfully inserted %d rows\n", affectedRows); - // close - taos_stmt_close(stmt); -} - -int main() { - TAOS *taos = taos_connect("localhost", "root", "taosdata", NULL, 6030); - if (taos == NULL) { - printf("failed to connect to server\n"); - exit(EXIT_FAILURE); - } - executeSQL(taos, "CREATE DATABASE power"); - executeSQL(taos, "USE power"); - executeSQL(taos, "CREATE STABLE meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)"); - insertData(taos); - taos_close(taos); - taos_cleanup(); -} - - -// output: -// successfully inserted 2 rows \ No newline at end of file diff --git a/docs-examples/c/subscribe_demo.c b/docs-examples/c/subscribe_demo.c deleted file mode 100644 index b523b4667e08ae8a02f4a470c939091f216d1dcb..0000000000000000000000000000000000000000 --- a/docs-examples/c/subscribe_demo.c +++ /dev/null @@ -1,66 +0,0 @@ -// A simple demo for asynchronous subscription. -// compile with: -// gcc -o subscribe_demo subscribe_demo.c -ltaos - -#include -#include -#include -#include - -int nTotalRows; - -/** - * @brief callback function of subscription. - * - * @param tsub - * @param res - * @param param. the additional parameter passed to taos_subscribe - * @param code. error code - */ -void subscribe_callback(TAOS_SUB* tsub, TAOS_RES* res, void* param, int code) { - if (code != 0) { - printf("error: %d\n", code); - exit(EXIT_FAILURE); - } - - TAOS_ROW row = NULL; - int num_fields = taos_num_fields(res); - TAOS_FIELD* fields = taos_fetch_fields(res); - int nRows = 0; - - while ((row = taos_fetch_row(res))) { - char buf[4096] = {0}; - taos_print_row(buf, row, fields, num_fields); - puts(buf); - nRows++; - } - - nTotalRows += nRows; - printf("%d rows consumed.\n", nRows); -} - -int main() { - TAOS* taos = taos_connect("localhost", "root", "taosdata", NULL, 6030); - if (taos == NULL) { - printf("failed to connect to server\n"); - exit(EXIT_FAILURE); - } - - int restart = 1; // if the topic already exists, where to subscribe from the begine. - const char* topic = "topic-meter-current-bg-10"; - const char* sql = "select * from power.meters where current > 10"; - void* param = NULL; // additional parameter. - int interval = 2000; // consumption interval in microseconds. - TAOS_SUB* tsub = taos_subscribe(taos, restart, topic, sql, subscribe_callback, NULL, interval); - - // wait for insert from others process. you can open TDengine CLI to insert some records for test. - - getchar(); // press Enter to stop - - printf("total rows consumed: %d\n", nTotalRows); - int keep = 0; // weather to keep subscribe process - taos_unsubscribe(tsub, keep); - - taos_close(taos); - taos_cleanup(); -} diff --git a/docs-examples/c/telnet_line_example.c b/docs-examples/c/telnet_line_example.c deleted file mode 100644 index 913d433f6aec07b3bce115d45536ffa4b45a0481..0000000000000000000000000000000000000000 --- a/docs-examples/c/telnet_line_example.c +++ /dev/null @@ -1,54 +0,0 @@ -// compile with -// gcc -o telnet_line_example telnet_line_example.c -ltaos -#include -#include -#include -#include "taos.h" - -void executeSQL(TAOS *taos, const char *sql) { - TAOS_RES *res = taos_query(taos, sql); - int code = taos_errno(res); - if (code != 0) { - printf("%s\n", taos_errstr(res)); - taos_free_result(res); - taos_close(taos); - exit(EXIT_FAILURE); - } - taos_free_result(res); -} - -// ANCHOR: main -int main() { - TAOS *taos = taos_connect("localhost", "root", "taosdata", "", 6030); - if (taos == NULL) { - printf("failed to connect to server\n"); - exit(EXIT_FAILURE); - } - executeSQL(taos, "DROP DATABASE IF EXISTS test"); - executeSQL(taos, "CREATE DATABASE test"); - executeSQL(taos, "USE test"); - char *lines[] = { - "meters.current 1648432611249 10.3 location=Beijing.Chaoyang groupid=2", - "meters.current 1648432611250 12.6 location=Beijing.Chaoyang groupid=2", - "meters.current 1648432611249 10.8 location=Beijing.Haidian groupid=3", - "meters.current 1648432611250 11.3 location=Beijing.Haidian groupid=3", - "meters.voltage 1648432611249 219 location=Beijing.Chaoyang groupid=2", - "meters.voltage 1648432611250 218 location=Beijing.Chaoyang groupid=2", - "meters.voltage 1648432611249 221 location=Beijing.Haidian groupid=3", - "meters.voltage 1648432611250 217 location=Beijing.Haidian groupid=3", - }; - TAOS_RES *res = taos_schemaless_insert(taos, lines, 8, TSDB_SML_TELNET_PROTOCOL, TSDB_SML_TIMESTAMP_NOT_CONFIGURED); - if (taos_errno(res) != 0) { - printf("failed to insert schema-less data, reason: %s\n", taos_errstr(res)); - } else { - int affectedRow = taos_affected_rows(res); - printf("successfully inserted %d rows\n", affectedRow); - } - - taos_free_result(res); - taos_close(taos); - taos_cleanup(); -} -// output: -// successfully inserted 8 rows -// ANCHOR_END: main diff --git a/docs-examples/csharp/AsyncQueryExample.cs b/docs-examples/csharp/AsyncQueryExample.cs deleted file mode 100644 index fe30d21efe82e8d1dc414bd4723227ca93bc944f..0000000000000000000000000000000000000000 --- a/docs-examples/csharp/AsyncQueryExample.cs +++ /dev/null @@ -1,238 +0,0 @@ -using TDengineDriver; -using System.Runtime.InteropServices; - -namespace TDengineExample -{ - public class AsyncQueryExample - { - static void Main() - { - IntPtr conn = GetConnection(); - QueryAsyncCallback queryAsyncCallback = new QueryAsyncCallback(QueryCallback); - TDengine.QueryAsync(conn, "select * from meters", queryAsyncCallback, IntPtr.Zero); - Thread.Sleep(2000); - TDengine.Close(conn); - TDengine.Cleanup(); - } - - static void QueryCallback(IntPtr param, IntPtr taosRes, int code) - { - if (code == 0 && taosRes != IntPtr.Zero) - { - FetchRowAsyncCallback fetchRowAsyncCallback = new FetchRowAsyncCallback(FetchRowCallback); - TDengine.FetchRowAsync(taosRes, fetchRowAsyncCallback, param); - } - else - { - Console.WriteLine($"async query data failed, failed code {code}"); - } - } - - static void FetchRowCallback(IntPtr param, IntPtr taosRes, int numOfRows) - { - if (numOfRows > 0) - { - Console.WriteLine($"{numOfRows} rows async retrieved"); - DisplayRes(taosRes); - TDengine.FetchRowAsync(taosRes, FetchRowCallback, param); - } - else - { - if (numOfRows == 0) - { - Console.WriteLine("async retrieve complete."); - - } - else - { - Console.WriteLine($"FetchRowAsync callback error, error code {numOfRows}"); - } - TDengine.FreeResult(taosRes); - } - } - - public static void DisplayRes(IntPtr res) - { - if (!IsValidResult(res)) - { - TDengine.Cleanup(); - System.Environment.Exit(1); - } - - List metaList = TDengine.FetchFields(res); - int fieldCount = metaList.Count; - // metaList.ForEach((item) => { Console.Write("{0} ({1}) \t|\t", item.name, item.size); }); - - List dataList = QueryRes(res, metaList); - for (int index = 0; index < dataList.Count; index++) - { - if (index % fieldCount == 0 && index != 0) - { - Console.WriteLine(""); - } - Console.Write("{0} \t|\t", dataList[index].ToString()); - - } - Console.WriteLine(""); - } - - public static bool IsValidResult(IntPtr res) - { - if ((res == IntPtr.Zero) || (TDengine.ErrorNo(res) != 0)) - { - if (res != IntPtr.Zero) - { - Console.Write("reason: " + TDengine.Error(res)); - return false; - } - Console.WriteLine(""); - return false; - } - return true; - } - - private static List QueryRes(IntPtr res, List meta) - { - IntPtr taosRow; - List dataRaw = new(); - while ((taosRow = TDengine.FetchRows(res)) != IntPtr.Zero) - { - dataRaw.AddRange(FetchRow(taosRow, res)); - } - if (TDengine.ErrorNo(res) != 0) - { - Console.Write("Query is not complete, Error {0} {1}", TDengine.ErrorNo(res), TDengine.Error(res)); - } - TDengine.FreeResult(res); - Console.WriteLine(""); - return dataRaw; - } - - public static List FetchRow(IntPtr taosRow, IntPtr taosRes)//, List metaList, int numOfFiled - { - List metaList = TDengine.FetchFields(taosRes); - int numOfFiled = TDengine.FieldCount(taosRes); - - - List dataRaw = new(); - - IntPtr colLengthPrt = TDengine.FetchLengths(taosRes); - int[] colLengthArr = new int[numOfFiled]; - Marshal.Copy(colLengthPrt, colLengthArr, 0, numOfFiled); - - for (int i = 0; i < numOfFiled; i++) - { - TDengineMeta meta = metaList[i]; - IntPtr data = Marshal.ReadIntPtr(taosRow, IntPtr.Size * i); - - if (data == IntPtr.Zero) - { - dataRaw.Add("NULL"); - continue; - } - switch ((TDengineDataType)meta.type) - { - case TDengineDataType.TSDB_DATA_TYPE_BOOL: - bool v1 = Marshal.ReadByte(data) != 0; - dataRaw.Add(v1); - break; - case TDengineDataType.TSDB_DATA_TYPE_TINYINT: - sbyte v2 = (sbyte)Marshal.ReadByte(data); - dataRaw.Add(v2); - break; - case TDengineDataType.TSDB_DATA_TYPE_SMALLINT: - short v3 = Marshal.ReadInt16(data); - dataRaw.Add(v3); - break; - case TDengineDataType.TSDB_DATA_TYPE_INT: - int v4 = Marshal.ReadInt32(data); - dataRaw.Add(v4); - break; - case TDengineDataType.TSDB_DATA_TYPE_BIGINT: - long v5 = Marshal.ReadInt64(data); - dataRaw.Add(v5); - break; - case TDengineDataType.TSDB_DATA_TYPE_FLOAT: - float v6 = (float)Marshal.PtrToStructure(data, typeof(float)); - dataRaw.Add(v6); - break; - case TDengineDataType.TSDB_DATA_TYPE_DOUBLE: - double v7 = (double)Marshal.PtrToStructure(data, typeof(double)); - dataRaw.Add(v7); - break; - case TDengineDataType.TSDB_DATA_TYPE_BINARY: - string v8 = Marshal.PtrToStringUTF8(data, colLengthArr[i]); - dataRaw.Add(v8); - break; - case TDengineDataType.TSDB_DATA_TYPE_TIMESTAMP: - long v9 = Marshal.ReadInt64(data); - dataRaw.Add(v9); - break; - case TDengineDataType.TSDB_DATA_TYPE_NCHAR: - string v10 = Marshal.PtrToStringUTF8(data, colLengthArr[i]); - dataRaw.Add(v10); - break; - case TDengineDataType.TSDB_DATA_TYPE_UTINYINT: - byte v12 = Marshal.ReadByte(data); - dataRaw.Add(v12.ToString()); - break; - case TDengineDataType.TSDB_DATA_TYPE_USMALLINT: - ushort v13 = (ushort)Marshal.ReadInt16(data); - dataRaw.Add(v13); - break; - case TDengineDataType.TSDB_DATA_TYPE_UINT: - uint v14 = (uint)Marshal.ReadInt32(data); - dataRaw.Add(v14); - break; - case TDengineDataType.TSDB_DATA_TYPE_UBIGINT: - ulong v15 = (ulong)Marshal.ReadInt64(data); - dataRaw.Add(v15); - break; - case TDengineDataType.TSDB_DATA_TYPE_JSONTAG: - string v16 = Marshal.PtrToStringUTF8(data, colLengthArr[i]); - dataRaw.Add(v16); - break; - default: - dataRaw.Add("nonsupport data type"); - break; - } - - } - return dataRaw; - } - - static IntPtr GetConnection() - { - string host = "localhost"; - short port = 6030; - string username = "root"; - string password = "taosdata"; - string dbname = "power"; - var conn = TDengine.Connect(host, username, password, dbname, port); - if (conn == IntPtr.Zero) - { - Console.WriteLine("Connect to TDengine failed"); - Environment.Exit(0); - } - else - { - Console.WriteLine("Connect to TDengine success"); - } - return conn; - } - } -} - -//output: -//Connect to TDengine success -//8 rows async retrieved - -//1538548685000 | 10.3 | 219 | 0.31 | beijing.chaoyang | 2 | -//1538548695000 | 12.6 | 218 | 0.33 | beijing.chaoyang | 2 | -//1538548696800 | 12.3 | 221 | 0.31 | beijing.chaoyang | 2 | -//1538548696650 | 10.3 | 218 | 0.25 | beijing.chaoyang | 3 | -//1538548685500 | 11.8 | 221 | 0.28 | beijing.haidian | 2 | -//1538548696600 | 13.4 | 223 | 0.29 | beijing.haidian | 2 | -//1538548685000 | 10.8 | 223 | 0.29 | beijing.haidian | 3 | -//1538548686500 | 11.5 | 221 | 0.35 | beijing.haidian | 3 | -//async retrieve complete. \ No newline at end of file diff --git a/docs-examples/csharp/InfluxDBLineExample.cs b/docs-examples/csharp/InfluxDBLineExample.cs deleted file mode 100644 index 7aad08825209db568d61e5963ec7a00034ab7ca7..0000000000000000000000000000000000000000 --- a/docs-examples/csharp/InfluxDBLineExample.cs +++ /dev/null @@ -1,77 +0,0 @@ -using TDengineDriver; - -namespace TDengineExample -{ - internal class InfluxDBLineExample - { - static void Main() - { - IntPtr conn = GetConnection(); - PrepareDatabase(conn); - string[] lines = { - "meters,location=Beijing.Haidian,groupid=2 current=11.8,voltage=221,phase=0.28 1648432611249", - "meters,location=Beijing.Haidian,groupid=2 current=13.4,voltage=223,phase=0.29 1648432611250", - "meters,location=Beijing.Haidian,groupid=3 current=10.8,voltage=223,phase=0.29 1648432611249", - "meters,location=Beijing.Haidian,groupid=3 current=11.3,voltage=221,phase=0.35 1648432611250" - }; - IntPtr res = TDengine.SchemalessInsert(conn, lines, lines.Length, (int)TDengineSchemalessProtocol.TSDB_SML_LINE_PROTOCOL, (int)TDengineSchemalessPrecision.TSDB_SML_TIMESTAMP_MILLI_SECONDS); - if (TDengine.ErrorNo(res) != 0) - { - Console.WriteLine("SchemalessInsert failed since " + TDengine.Error(res)); - ExitProgram(conn, 1); - } - else - { - int affectedRows = TDengine.AffectRows(res); - Console.WriteLine($"SchemalessInsert success, affected {affectedRows} rows"); - } - TDengine.FreeResult(res); - ExitProgram(conn, 0); - - } - static IntPtr GetConnection() - { - 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"); - TDengine.Cleanup(); - Environment.Exit(1); - } - else - { - Console.WriteLine("Connect to TDengine success"); - } - return conn; - } - - static void PrepareDatabase(IntPtr conn) - { - IntPtr res = TDengine.Query(conn, "CREATE DATABASE test"); - if (TDengine.ErrorNo(res) != 0) - { - Console.WriteLine("failed to create database, reason: " + TDengine.Error(res)); - ExitProgram(conn, 1); - } - res = TDengine.Query(conn, "USE test"); - if (TDengine.ErrorNo(res) != 0) - { - Console.WriteLine("failed to change database, reason: " + TDengine.Error(res)); - ExitProgram(conn, 1); - } - } - - static void ExitProgram(IntPtr conn, int exitCode) - { - TDengine.Close(conn); - TDengine.Cleanup(); - Environment.Exit(exitCode); - } - } - -} diff --git a/docs-examples/csharp/OptsJsonExample.cs b/docs-examples/csharp/OptsJsonExample.cs deleted file mode 100644 index d774a325afa1a8d93eb858f23dcd97dd29f8653d..0000000000000000000000000000000000000000 --- a/docs-examples/csharp/OptsJsonExample.cs +++ /dev/null @@ -1,76 +0,0 @@ -using TDengineDriver; - -namespace TDengineExample -{ - internal class OptsJsonExample - { - static void Main() - { - IntPtr conn = GetConnection(); - PrepareDatabase(conn); - string[] lines = { "[{\"metric\": \"meters.current\", \"timestamp\": 1648432611249, \"value\": 10.3, \"tags\": {\"location\": \"Beijing.Chaoyang\", \"groupid\": 2}}," + - " {\"metric\": \"meters.voltage\", \"timestamp\": 1648432611249, \"value\": 219, \"tags\": {\"location\": \"Beijing.Haidian\", \"groupid\": 1}}, " + - "{\"metric\": \"meters.current\", \"timestamp\": 1648432611250, \"value\": 12.6, \"tags\": {\"location\": \"Beijing.Chaoyang\", \"groupid\": 2}}," + - " {\"metric\": \"meters.voltage\", \"timestamp\": 1648432611250, \"value\": 221, \"tags\": {\"location\": \"Beijing.Haidian\", \"groupid\": 1}}]" - }; - - IntPtr res = TDengine.SchemalessInsert(conn, lines, 1, (int)TDengineSchemalessProtocol.TSDB_SML_JSON_PROTOCOL, (int)TDengineSchemalessPrecision.TSDB_SML_TIMESTAMP_NOT_CONFIGURED); - if (TDengine.ErrorNo(res) != 0) - { - Console.WriteLine("SchemalessInsert failed since " + TDengine.Error(res)); - ExitProgram(conn, 1); - } - else - { - int affectedRows = TDengine.AffectRows(res); - Console.WriteLine($"SchemalessInsert success, affected {affectedRows} rows"); - } - TDengine.FreeResult(res); - ExitProgram(conn, 0); - - } - static IntPtr GetConnection() - { - 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"); - TDengine.Cleanup(); - Environment.Exit(1); - } - else - { - Console.WriteLine("Connect to TDengine success"); - } - return conn; - } - - static void PrepareDatabase(IntPtr conn) - { - IntPtr res = TDengine.Query(conn, "CREATE DATABASE test"); - if (TDengine.ErrorNo(res) != 0) - { - Console.WriteLine("failed to create database, reason: " + TDengine.Error(res)); - ExitProgram(conn, 1); - } - res = TDengine.Query(conn, "USE test"); - if (TDengine.ErrorNo(res) != 0) - { - Console.WriteLine("failed to change database, reason: " + TDengine.Error(res)); - ExitProgram(conn, 1); - } - } - - static void ExitProgram(IntPtr conn, int exitCode) - { - TDengine.Close(conn); - TDengine.Cleanup(); - Environment.Exit(exitCode); - } - } -} diff --git a/docs-examples/csharp/OptsTelnetExample.cs b/docs-examples/csharp/OptsTelnetExample.cs deleted file mode 100644 index 81608c32213fa0618a2ca6e0769aacf8e9c8e64d..0000000000000000000000000000000000000000 --- a/docs-examples/csharp/OptsTelnetExample.cs +++ /dev/null @@ -1,80 +0,0 @@ -using TDengineDriver; - -namespace TDengineExample -{ - internal class OptsTelnetExample - { - static void Main() - { - IntPtr conn = GetConnection(); - PrepareDatabase(conn); - string[] lines = { - "meters.current 1648432611249 10.3 location=Beijing.Chaoyang groupid=2", - "meters.current 1648432611250 12.6 location=Beijing.Chaoyang groupid=2", - "meters.current 1648432611249 10.8 location=Beijing.Haidian groupid=3", - "meters.current 1648432611250 11.3 location=Beijing.Haidian groupid=3", - "meters.voltage 1648432611249 219 location=Beijing.Chaoyang groupid=2", - "meters.voltage 1648432611250 218 location=Beijing.Chaoyang groupid=2", - "meters.voltage 1648432611249 221 location=Beijing.Haidian groupid=3", - "meters.voltage 1648432611250 217 location=Beijing.Haidian groupid=3", - }; - IntPtr res = TDengine.SchemalessInsert(conn, lines, lines.Length, (int)TDengineSchemalessProtocol.TSDB_SML_TELNET_PROTOCOL, (int)TDengineSchemalessPrecision.TSDB_SML_TIMESTAMP_NOT_CONFIGURED); - if (TDengine.ErrorNo(res) != 0) - { - Console.WriteLine("SchemalessInsert failed since " + TDengine.Error(res)); - ExitProgram(conn, 1); - } - else - { - int affectedRows = TDengine.AffectRows(res); - Console.WriteLine($"SchemalessInsert success, affected {affectedRows} rows"); - } - TDengine.FreeResult(res); - ExitProgram(conn, 0); - - } - static IntPtr GetConnection() - { - 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"); - TDengine.Cleanup(); - Environment.Exit(1); - } - else - { - Console.WriteLine("Connect to TDengine success"); - } - return conn; - } - - static void PrepareDatabase(IntPtr conn) - { - IntPtr res = TDengine.Query(conn, "CREATE DATABASE test"); - if (TDengine.ErrorNo(res) != 0) - { - Console.WriteLine("failed to create database, reason: " + TDengine.Error(res)); - ExitProgram(conn, 1); - } - res = TDengine.Query(conn, "USE test"); - if (TDengine.ErrorNo(res) != 0) - { - Console.WriteLine("failed to change database, reason: " + TDengine.Error(res)); - ExitProgram(conn, 1); - } - } - - static void ExitProgram(IntPtr conn, int exitCode) - { - TDengine.Close(conn); - TDengine.Cleanup(); - Environment.Exit(exitCode); - } - } -} diff --git a/docs-examples/csharp/QueryExample.cs b/docs-examples/csharp/QueryExample.cs deleted file mode 100644 index f00e391100c7ce42177e2987f5b0b32dc02262c4..0000000000000000000000000000000000000000 --- a/docs-examples/csharp/QueryExample.cs +++ /dev/null @@ -1,162 +0,0 @@ -using TDengineDriver; -using System.Runtime.InteropServices; - -namespace TDengineExample -{ - internal class QueryExample - { - static void Main() - { - IntPtr conn = GetConnection(); - // run query - IntPtr res = TDengine.Query(conn, "SELECT * FROM test.meters LIMIT 2"); - if (TDengine.ErrorNo(res) != 0) - { - Console.WriteLine("Failed to query since: " + TDengine.Error(res)); - TDengine.Close(conn); - TDengine.Cleanup(); - return; - } - - // get filed count - int fieldCount = TDengine.FieldCount(res); - Console.WriteLine("fieldCount=" + fieldCount); - - // print column names - List metas = TDengine.FetchFields(res); - for (int i = 0; i < metas.Count; i++) - { - Console.Write(metas[i].name + "\t"); - } - Console.WriteLine(); - - // print values - IntPtr row; - while ((row = TDengine.FetchRows(res)) != IntPtr.Zero) - { - List metaList = TDengine.FetchFields(res); - int numOfFiled = TDengine.FieldCount(res); - - List dataRaw = new List(); - - IntPtr colLengthPrt = TDengine.FetchLengths(res); - int[] colLengthArr = new int[numOfFiled]; - Marshal.Copy(colLengthPrt, colLengthArr, 0, numOfFiled); - - for (int i = 0; i < numOfFiled; i++) - { - TDengineMeta meta = metaList[i]; - IntPtr data = Marshal.ReadIntPtr(row, IntPtr.Size * i); - - if (data == IntPtr.Zero) - { - Console.Write("NULL\t"); - continue; - } - switch ((TDengineDataType)meta.type) - { - case TDengineDataType.TSDB_DATA_TYPE_BOOL: - bool v1 = Marshal.ReadByte(data) == 0 ? false : true; - Console.Write(v1.ToString() + "\t"); - break; - case TDengineDataType.TSDB_DATA_TYPE_TINYINT: - sbyte v2 = (sbyte)Marshal.ReadByte(data); - Console.Write(v2.ToString() + "\t"); - break; - case TDengineDataType.TSDB_DATA_TYPE_SMALLINT: - short v3 = Marshal.ReadInt16(data); - Console.Write(v3.ToString() + "\t"); - break; - case TDengineDataType.TSDB_DATA_TYPE_INT: - int v4 = Marshal.ReadInt32(data); - Console.Write(v4.ToString() + "\t"); - break; - case TDengineDataType.TSDB_DATA_TYPE_BIGINT: - long v5 = Marshal.ReadInt64(data); - Console.Write(v5.ToString() + "\t"); - break; - case TDengineDataType.TSDB_DATA_TYPE_FLOAT: - float v6 = (float)Marshal.PtrToStructure(data, typeof(float)); - Console.Write(v6.ToString() + "\t"); - break; - case TDengineDataType.TSDB_DATA_TYPE_DOUBLE: - double v7 = (double)Marshal.PtrToStructure(data, typeof(double)); - Console.Write(v7.ToString() + "\t"); - break; - case TDengineDataType.TSDB_DATA_TYPE_BINARY: - string v8 = Marshal.PtrToStringUTF8(data, colLengthArr[i]); - Console.Write(v8 + "\t"); - break; - case TDengineDataType.TSDB_DATA_TYPE_TIMESTAMP: - long v9 = Marshal.ReadInt64(data); - Console.Write(v9.ToString() + "\t"); - break; - case TDengineDataType.TSDB_DATA_TYPE_NCHAR: - string v10 = Marshal.PtrToStringUTF8(data, colLengthArr[i]); - Console.Write(v10 + "\t"); - break; - case TDengineDataType.TSDB_DATA_TYPE_UTINYINT: - byte v12 = Marshal.ReadByte(data); - Console.Write(v12.ToString() + "\t"); - break; - case TDengineDataType.TSDB_DATA_TYPE_USMALLINT: - ushort v13 = (ushort)Marshal.ReadInt16(data); - Console.Write(v13.ToString() + "\t"); - break; - case TDengineDataType.TSDB_DATA_TYPE_UINT: - uint v14 = (uint)Marshal.ReadInt32(data); - Console.Write(v14.ToString() + "\t"); - break; - case TDengineDataType.TSDB_DATA_TYPE_UBIGINT: - ulong v15 = (ulong)Marshal.ReadInt64(data); - Console.Write(v15.ToString() + "\t"); - break; - case TDengineDataType.TSDB_DATA_TYPE_JSONTAG: - string v16 = Marshal.PtrToStringUTF8(data, colLengthArr[i]); - Console.Write(v16 + "\t"); - break; - default: - Console.Write("nonsupport data type value"); - break; - } - - } - Console.WriteLine(); - } - if (TDengine.ErrorNo(res) != 0) - { - Console.WriteLine($"Query is not complete, Error {TDengine.ErrorNo(res)} {TDengine.Error(res)}"); - } - // exit - TDengine.FreeResult(res); - TDengine.Close(conn); - TDengine.Cleanup(); - } - static IntPtr GetConnection() - { - string host = "localhost"; - short port = 6030; - string username = "root"; - string password = "taosdata"; - string dbname = "power"; - var conn = TDengine.Connect(host, username, password, dbname, port); - if (conn == IntPtr.Zero) - { - Console.WriteLine("Connect to TDengine failed"); - System.Environment.Exit(0); - } - else - { - Console.WriteLine("Connect to TDengine success"); - } - return conn; - } - } -} - -// output: -// Connect to TDengine success -// fieldCount=6 -// ts current voltage phase location groupid -// 1648432611249 10.3 219 0.31 Beijing.Chaoyang 2 -// 1648432611749 12.6 218 0.33 Beijing.Chaoyang 2 \ No newline at end of file diff --git a/docs-examples/csharp/SQLInsertExample.cs b/docs-examples/csharp/SQLInsertExample.cs deleted file mode 100644 index fa2e2a50daf06f4d948479e7f5b0df82c517f809..0000000000000000000000000000000000000000 --- a/docs-examples/csharp/SQLInsertExample.cs +++ /dev/null @@ -1,69 +0,0 @@ -using TDengineDriver; - - -namespace TDengineExample -{ - internal class SQLInsertExample - { - - static void Main() - { - IntPtr conn = GetConnection(); - IntPtr res = TDengine.Query(conn, "CREATE DATABASE power"); - CheckRes(conn, res, "failed to create database"); - res = TDengine.Query(conn, "USE power"); - CheckRes(conn, res, "failed to change database"); - res = TDengine.Query(conn, "CREATE STABLE power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)"); - CheckRes(conn, res, "failed to create stable"); - var sql = "INSERT INTO d1001 USING meters TAGS(Beijing.Chaoyang, 2) VALUES ('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) " + - "d1002 USING power.meters TAGS(Beijing.Chaoyang, 3) VALUES('2018-10-03 14:38:16.650', 10.30000, 218, 0.25000) " + - "d1003 USING power.meters TAGS(Beijing.Haidian, 2) VALUES('2018-10-03 14:38:05.500', 11.80000, 221, 0.28000)('2018-10-03 14:38:16.600', 13.40000, 223, 0.29000) " + - "d1004 USING power.meters TAGS(Beijing.Haidian, 3) VALUES('2018-10-03 14:38:05.000', 10.80000, 223, 0.29000)('2018-10-03 14:38:06.500', 11.50000, 221, 0.35000)"; - res = TDengine.Query(conn, sql); - CheckRes(conn, res, "failed to insert data"); - int affectedRows = TDengine.AffectRows(res); - Console.WriteLine("affectedRows " + affectedRows); - ExitProgram(conn, 0); - } - - static IntPtr GetConnection() - { - 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"); - Environment.Exit(0); - } - else - { - Console.WriteLine("Connect to TDengine success"); - } - return conn; - } - - static void CheckRes(IntPtr conn, IntPtr res, String errorMsg) - { - if (TDengine.ErrorNo(res) != 0) - { - Console.Write(errorMsg + " since: " + TDengine.Error(res)); - ExitProgram(conn, 1); - } - } - - static void ExitProgram(IntPtr conn, int exitCode) - { - TDengine.Close(conn); - TDengine.Cleanup(); - Environment.Exit(exitCode); - } - } -} - -// output: -// Connect to TDengine success -// affectedRows 8 diff --git a/docs-examples/csharp/StmtInsertExample.cs b/docs-examples/csharp/StmtInsertExample.cs deleted file mode 100644 index d6e00dd4ac54ab8dbfc33b93896d19fc585e7642..0000000000000000000000000000000000000000 --- a/docs-examples/csharp/StmtInsertExample.cs +++ /dev/null @@ -1,115 +0,0 @@ -using TDengineDriver; - -namespace TDengineExample -{ - internal class StmtInsertExample - { - private static IntPtr conn; - private static IntPtr stmt; - static void Main() - { - conn = GetConnection(); - PrepareSTable(); - // 1. init and prepare - stmt = TDengine.StmtInit(conn); - if (stmt == IntPtr.Zero) - { - Console.WriteLine("failed to init stmt, " + TDengine.Error(stmt)); - ExitProgram(); - } - int res = TDengine.StmtPrepare(stmt, "INSERT INTO ? USING meters TAGS(?, ?) VALUES(?, ?, ?, ?)"); - CheckStmtRes(res, "failed to prepare stmt"); - - // 2. bind table name and tags - TAOS_BIND[] tags = new TAOS_BIND[2] { TaosBind.BindBinary("Beijing.Chaoyang"), TaosBind.BindInt(2) }; - res = TDengine.StmtSetTbnameTags(stmt, "d1001", tags); - CheckStmtRes(res, "failed to bind table name and tags"); - - // 3. bind values - TAOS_MULTI_BIND[] values = new TAOS_MULTI_BIND[4] { - TaosMultiBind.MultiBindTimestamp(new long[2] { 1648432611249, 1648432611749}), - TaosMultiBind.MultiBindFloat(new float?[2] { 10.3f, 12.6f}), - TaosMultiBind.MultiBindInt(new int?[2] { 219, 218}), - TaosMultiBind.MultiBindFloat(new float?[2]{ 0.31f, 0.33f}) - }; - res = TDengine.StmtBindParamBatch(stmt, values); - CheckStmtRes(res, "failed to bind params"); - - // 4. add batch - res = TDengine.StmtAddBatch(stmt); - CheckStmtRes(res, "failed to add batch"); - - // 5. execute - res = TDengine.StmtExecute(stmt); - CheckStmtRes(res, "faild to execute"); - - // 6. free - TaosBind.FreeTaosBind(tags); - TaosMultiBind.FreeTaosBind(values); - TDengine.Close(conn); - TDengine.Cleanup(); - } - - static IntPtr GetConnection() - { - 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"); - Environment.Exit(0); - } - else - { - Console.WriteLine("Connect to TDengine success"); - } - return conn; - } - - - - static void PrepareSTable() - { - IntPtr res = TDengine.Query(conn, "CREATE DATABASE power"); - CheckResPtr(res, "failed to create database"); - res = TDengine.Query(conn, "USE power"); - CheckResPtr(res, "failed to change database"); - res = TDengine.Query(conn, "CREATE STABLE power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)"); - CheckResPtr(res, "failed to create stable"); - } - - static void CheckStmtRes(int res, string errorMsg) - { - if (res != 0) - { - Console.WriteLine(errorMsg + ", " + TDengine.StmtErrorStr(stmt)); - int code = TDengine.StmtClose(stmt); - if (code != 0) - { - Console.WriteLine($"falied to close stmt, {code} reason: {TDengine.StmtErrorStr(stmt)} "); - } - ExitProgram(); - } - } - - static void CheckResPtr(IntPtr res, string errorMsg) - { - if (TDengine.ErrorNo(res) != 0) - { - Console.WriteLine(errorMsg + " since:" + TDengine.Error(res)); - ExitProgram(); - } - } - - static void ExitProgram() - { - TDengine.Close(conn); - TDengine.Cleanup(); - Environment.Exit(1); - } - } -} diff --git a/docs-examples/go/connect/cgoexample/main.go b/docs-examples/go/connect/cgoexample/main.go deleted file mode 100644 index 8b9aba4ce4217c00605bc8796c788f3dd52805e6..0000000000000000000000000000000000000000 --- a/docs-examples/go/connect/cgoexample/main.go +++ /dev/null @@ -1,23 +0,0 @@ -package main - -import ( - "database/sql" - "fmt" - - _ "github.com/taosdata/driver-go/v2/taosSql" -) - -func main() { - var taosDSN = "root:taosdata@tcp(localhost:6030)/" - taos, err := sql.Open("taosSql", taosDSN) - if err != nil { - fmt.Println("failed to connect TDengine, err:", err) - return - } - fmt.Println("Connected") - defer taos.Close() -} - -// use -// var taosDSN = "root:taosdata@tcp(localhost:6030)/dbName" -// if you want to connect to a default database. diff --git a/docs-examples/go/connect/restexample/main.go b/docs-examples/go/connect/restexample/main.go deleted file mode 100644 index 9c05e7eed80dee4ae7e6b20637d265f388d7438d..0000000000000000000000000000000000000000 --- a/docs-examples/go/connect/restexample/main.go +++ /dev/null @@ -1,23 +0,0 @@ -package main - -import ( - "database/sql" - "fmt" - - _ "github.com/taosdata/driver-go/v2/taosRestful" -) - -func main() { - var taosDSN = "root:taosdata@http(localhost:6041)/" - taos, err := sql.Open("taosRestful", taosDSN) - if err != nil { - fmt.Println("failed to connect TDengine, err:", err) - return - } - fmt.Println("Connected") - defer taos.Close() -} - -// use -// var taosDSN = "root:taosdata@http(localhost:6041)/dbName" -// if you want to connect to a default database. diff --git a/docs-examples/go/insert/json/main.go b/docs-examples/go/insert/json/main.go deleted file mode 100644 index 47d9e9984adc05896fb9954ad3deffde3764b836..0000000000000000000000000000000000000000 --- a/docs-examples/go/insert/json/main.go +++ /dev/null @@ -1,37 +0,0 @@ -package main - -import ( - "fmt" - - "github.com/taosdata/driver-go/v2/af" -) - -func prepareDatabase(conn *af.Connector) { - _, err := conn.Exec("CREATE DATABASE test") - if err != nil { - panic(err) - } - _, err = conn.Exec("USE test") - if err != nil { - panic(err) - } -} - -func main() { - conn, err := af.Open("localhost", "root", "taosdata", "", 6030) - if err != nil { - fmt.Println("fail to connect, err:", err) - } - defer conn.Close() - prepareDatabase(conn) - - payload := `[{"metric": "meters.current", "timestamp": 1648432611249, "value": 10.3, "tags": {"location": "Beijing.Chaoyang", "groupid": 2}}, - {"metric": "meters.voltage", "timestamp": 1648432611249, "value": 219, "tags": {"location": "Beijing.Haidian", "groupid": 1}}, - {"metric": "meters.current", "timestamp": 1648432611250, "value": 12.6, "tags": {"location": "Beijing.Chaoyang", "groupid": 2}}, - {"metric": "meters.voltage", "timestamp": 1648432611250, "value": 221, "tags": {"location": "Beijing.Haidian", "groupid": 1}}]` - - err = conn.OpenTSDBInsertJsonPayload(payload) - if err != nil { - fmt.Println("insert error:", err) - } -} diff --git a/docs-examples/go/insert/line/main.go b/docs-examples/go/insert/line/main.go deleted file mode 100644 index bbc41468fe5f13d3e6f896445bb88f3eba584d0f..0000000000000000000000000000000000000000 --- a/docs-examples/go/insert/line/main.go +++ /dev/null @@ -1,38 +0,0 @@ -package main - -import ( - "fmt" - - "github.com/taosdata/driver-go/v2/af" -) - -func prepareDatabase(conn *af.Connector) { - _, err := conn.Exec("CREATE DATABASE test") - if err != nil { - panic(err) - } - _, err = conn.Exec("USE test") - if err != nil { - panic(err) - } -} - -func main() { - conn, err := af.Open("localhost", "root", "taosdata", "", 6030) - if err != nil { - fmt.Println("fail to connect, err:", err) - } - defer conn.Close() - prepareDatabase(conn) - var lines = []string{ - "meters,location=Beijing.Haidian,groupid=2 current=11.8,voltage=221,phase=0.28 1648432611249", - "meters,location=Beijing.Haidian,groupid=2 current=13.4,voltage=223,phase=0.29 1648432611250", - "meters,location=Beijing.Haidian,groupid=3 current=10.8,voltage=223,phase=0.29 1648432611249", - "meters,location=Beijing.Haidian,groupid=3 current=11.3,voltage=221,phase=0.35 1648432611250", - } - - err = conn.InfluxDBInsertLines(lines, "ms") - if err != nil { - fmt.Println("insert error:", err) - } -} diff --git a/docs-examples/go/insert/sql/main.go b/docs-examples/go/insert/sql/main.go deleted file mode 100644 index 91386855334c1930af721e0b4f43395c6a6d8e82..0000000000000000000000000000000000000000 --- a/docs-examples/go/insert/sql/main.go +++ /dev/null @@ -1,49 +0,0 @@ -package main - -import ( - "database/sql" - "fmt" - - _ "github.com/taosdata/driver-go/v2/taosRestful" -) - -func createStable(taos *sql.DB) { - _, err := taos.Exec("CREATE DATABASE power") - if err != nil { - fmt.Println("failed to create database, err:", err) - } - _, err = taos.Exec("CREATE STABLE power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)") - if err != nil { - fmt.Println("failed to create stable, err:", err) - } -} - -func insertData(taos *sql.DB) { - sql := `INSERT INTO power.d1001 USING power.meters TAGS(Beijing.Chaoyang, 2) VALUES ('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) - power.d1002 USING power.meters TAGS(Beijing.Chaoyang, 3) VALUES ('2018-10-03 14:38:16.650', 10.30000, 218, 0.25000) - power.d1003 USING power.meters TAGS(Beijing.Haidian, 2) VALUES ('2018-10-03 14:38:05.500', 11.80000, 221, 0.28000) ('2018-10-03 14:38:16.600', 13.40000, 223, 0.29000) - power.d1004 USING power.meters TAGS(Beijing.Haidian, 3) VALUES ('2018-10-03 14:38:05.000', 10.80000, 223, 0.29000) ('2018-10-03 14:38:06.500', 11.50000, 221, 0.35000)` - result, err := taos.Exec(sql) - if err != nil { - fmt.Println("failed to insert, err:", err) - return - } - rowsAffected, err := result.RowsAffected() - if err != nil { - fmt.Println("failed to get affected rows, err:", err) - return - } - fmt.Println("RowsAffected", rowsAffected) -} - -func main() { - var taosDSN = "root:taosdata@http(localhost:6041)/" - taos, err := sql.Open("taosRestful", taosDSN) - if err != nil { - fmt.Println("failed to connect TDengine, err:", err) - return - } - defer taos.Close() - createStable(taos) - insertData(taos) -} diff --git a/docs-examples/go/insert/stmt/main.go b/docs-examples/go/insert/stmt/main.go deleted file mode 100644 index c50200ebb427c4c64c2737cb8fe4c3d287551a34..0000000000000000000000000000000000000000 --- a/docs-examples/go/insert/stmt/main.go +++ /dev/null @@ -1,73 +0,0 @@ -package main - -import ( - "fmt" - "time" - - "github.com/taosdata/driver-go/v2/af" - "github.com/taosdata/driver-go/v2/af/param" - "github.com/taosdata/driver-go/v2/common" -) - -func checkErr(err error, prompt string) { - if err != nil { - fmt.Printf("%s\n", prompt) - panic(err) - } -} - -func prepareStable(conn *af.Connector) { - _, err := conn.Exec("CREATE DATABASE power") - checkErr(err, "failed to create database") - _, err = conn.Exec("CREATE STABLE power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)") - checkErr(err, "failed to create stable") - _, err = conn.Exec("USE power") - checkErr(err, "failed to change database") -} - -func main() { - conn, err := af.Open("localhost", "root", "taosdata", "", 6030) - checkErr(err, "fail to connect") - defer conn.Close() - prepareStable(conn) - // create stmt - stmt := conn.InsertStmt() - defer stmt.Close() - err = stmt.Prepare("INSERT INTO ? USING meters TAGS(?, ?) VALUES(?, ?, ?, ?)") - checkErr(err, "failed to create prepare statement") - - // bind table name and tags - tagParams := param.NewParam(2).AddBinary([]byte("Beijing.Chaoyang")).AddInt(2) - err = stmt.SetTableNameWithTags("d1001", tagParams) - checkErr(err, "failed to execute SetTableNameWithTags") - - // specify ColumnType - var bindType *param.ColumnType = param.NewColumnType(4).AddTimestamp().AddFloat().AddInt().AddFloat() - - // bind values. note: can only bind one row each time. - valueParams := []*param.Param{ - param.NewParam(1).AddTimestamp(time.Unix(1648432611, 249300000), common.PrecisionMilliSecond), - param.NewParam(1).AddFloat(10.3), - param.NewParam(1).AddInt(219), - param.NewParam(1).AddFloat(0.31), - } - err = stmt.BindParam(valueParams, bindType) - checkErr(err, "BindParam error") - err = stmt.AddBatch() - checkErr(err, "AddBatch error") - - // bind one more row - valueParams = []*param.Param{ - param.NewParam(1).AddTimestamp(time.Unix(1648432611, 749300000), common.PrecisionMilliSecond), - param.NewParam(1).AddFloat(12.6), - param.NewParam(1).AddInt(218), - param.NewParam(1).AddFloat(0.33), - } - err = stmt.BindParam(valueParams, bindType) - checkErr(err, "BindParam error") - err = stmt.AddBatch() - checkErr(err, "AddBatch error") - // execute - err = stmt.Execute() - checkErr(err, "Execute batch error") -} diff --git a/docs-examples/go/insert/telnet/main.go b/docs-examples/go/insert/telnet/main.go deleted file mode 100644 index 879e6d5cece74fd0b7c815dd34614dca3c9d4544..0000000000000000000000000000000000000000 --- a/docs-examples/go/insert/telnet/main.go +++ /dev/null @@ -1,42 +0,0 @@ -package main - -import ( - "fmt" - - "github.com/taosdata/driver-go/v2/af" -) - -func prepareDatabase(conn *af.Connector) { - _, err := conn.Exec("CREATE DATABASE test") - if err != nil { - panic(err) - } - _, err = conn.Exec("USE test") - if err != nil { - panic(err) - } -} - -func main() { - conn, err := af.Open("localhost", "root", "taosdata", "", 6030) - if err != nil { - fmt.Println("fail to connect, err:", err) - } - defer conn.Close() - prepareDatabase(conn) - var lines = []string{ - "meters.current 1648432611249 10.3 location=Beijing.Chaoyang groupid=2", - "meters.current 1648432611250 12.6 location=Beijing.Chaoyang groupid=2", - "meters.current 1648432611249 10.8 location=Beijing.Haidian groupid=3", - "meters.current 1648432611250 11.3 location=Beijing.Haidian groupid=3", - "meters.voltage 1648432611249 219 location=Beijing.Chaoyang groupid=2", - "meters.voltage 1648432611250 218 location=Beijing.Chaoyang groupid=2", - "meters.voltage 1648432611249 221 location=Beijing.Haidian groupid=3", - "meters.voltage 1648432611250 217 location=Beijing.Haidian groupid=3", - } - - err = conn.OpenTSDBInsertTelnetLines(lines) - if err != nil { - fmt.Println("insert error:", err) - } -} diff --git a/docs-examples/java/src/main/java/com/taos/example/JNIConnectExample.java b/docs-examples/java/src/main/java/com/taos/example/JNIConnectExample.java deleted file mode 100644 index c6ce2ef9785a010daa55ad29415f81711760cd57..0000000000000000000000000000000000000000 --- a/docs-examples/java/src/main/java/com/taos/example/JNIConnectExample.java +++ /dev/null @@ -1,25 +0,0 @@ -package com.taos.example; - -import java.sql.Connection; -import java.sql.DriverManager; -import java.sql.SQLException; -import java.util.Properties; - -import com.taosdata.jdbc.TSDBDriver; - -public class JNIConnectExample { - public static void main(String[] args) throws SQLException { - String jdbcUrl = "jdbc:TAOS://localhost:6030?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); - System.out.println("Connected"); - conn.close(); - } -} - -// use -// String jdbcUrl = "jdbc:TAOS://localhost:6030/dbName?user=root&password=taosdata"; -// if you want to connect to a default database. \ No newline at end of file diff --git a/docs-examples/java/src/main/java/com/taos/example/JSONProtocolExample.java b/docs-examples/java/src/main/java/com/taos/example/JSONProtocolExample.java deleted file mode 100644 index cb83424576a4fd7dfa09ea297294ed77b66bd12d..0000000000000000000000000000000000000000 --- a/docs-examples/java/src/main/java/com/taos/example/JSONProtocolExample.java +++ /dev/null @@ -1,40 +0,0 @@ -package com.taos.example; - -import com.taosdata.jdbc.SchemalessWriter; -import com.taosdata.jdbc.enums.SchemalessProtocolType; -import com.taosdata.jdbc.enums.SchemalessTimestampType; - -import java.sql.Connection; -import java.sql.DriverManager; -import java.sql.SQLException; -import java.sql.Statement; - -public class JSONProtocolExample { - private static Connection getConnection() throws SQLException { - String jdbcUrl = "jdbc:TAOS://localhost:6030?user=root&password=taosdata"; - return DriverManager.getConnection(jdbcUrl); - } - - private static void createDatabase(Connection conn) throws SQLException { - try (Statement stmt = conn.createStatement()) { - stmt.execute("CREATE DATABASE IF NOT EXISTS test"); - stmt.execute("USE test"); - } - } - - private static String getJSONData() { - return "[{\"metric\": \"meters.current\", \"timestamp\": 1648432611249, \"value\": 10.3, \"tags\": {\"location\": \"Beijing.Chaoyang\", \"groupid\": 2}}," + - " {\"metric\": \"meters.voltage\", \"timestamp\": 1648432611249, \"value\": 219, \"tags\": {\"location\": \"Beijing.Haidian\", \"groupid\": 1}}, " + - "{\"metric\": \"meters.current\", \"timestamp\": 1648432611250, \"value\": 12.6, \"tags\": {\"location\": \"Beijing.Chaoyang\", \"groupid\": 2}}," + - " {\"metric\": \"meters.voltage\", \"timestamp\": 1648432611250, \"value\": 221, \"tags\": {\"location\": \"Beijing.Haidian\", \"groupid\": 1}}]"; - } - - public static void main(String[] args) throws SQLException { - try (Connection conn = getConnection()) { - createDatabase(conn); - SchemalessWriter writer = new SchemalessWriter(conn); - String jsonData = getJSONData(); - writer.write(jsonData, SchemalessProtocolType.JSON, SchemalessTimestampType.NOT_CONFIGURED); - } - } -} diff --git a/docs-examples/java/src/main/java/com/taos/example/LineProtocolExample.java b/docs-examples/java/src/main/java/com/taos/example/LineProtocolExample.java deleted file mode 100644 index 8a2eabe0a91f7966cc3cc6b7dfeeb71b71b88d92..0000000000000000000000000000000000000000 --- a/docs-examples/java/src/main/java/com/taos/example/LineProtocolExample.java +++ /dev/null @@ -1,42 +0,0 @@ -package com.taos.example; - -import com.taosdata.jdbc.SchemalessWriter; -import com.taosdata.jdbc.enums.SchemalessProtocolType; -import com.taosdata.jdbc.enums.SchemalessTimestampType; - -import java.sql.Connection; -import java.sql.DriverManager; -import java.sql.SQLException; -import java.sql.Statement; - -public class LineProtocolExample { - // format: measurement,tag_set field_set timestamp - private static String[] lines = { - "meters,location=Beijing.Haidian,groupid=2 current=11.8,voltage=221,phase=0.28 1648432611249000", // micro - // seconds - "meters,location=Beijing.Haidian,groupid=2 current=13.4,voltage=223,phase=0.29 1648432611249500", - "meters,location=Beijing.Haidian,groupid=3 current=10.8,voltage=223,phase=0.29 1648432611249300", - "meters,location=Beijing.Haidian,groupid=3 current=11.3,voltage=221,phase=0.35 1648432611249800", - }; - - private static Connection getConnection() throws SQLException { - String jdbcUrl = "jdbc:TAOS://localhost:6030?user=root&password=taosdata"; - return DriverManager.getConnection(jdbcUrl); - } - - private static void createDatabase(Connection conn) throws SQLException { - try (Statement stmt = conn.createStatement()) { - // the default precision is ms (microsecond), but we use us(microsecond) here. - stmt.execute("CREATE DATABASE IF NOT EXISTS test PRECISION 'us'"); - stmt.execute("USE test"); - } - } - - public static void main(String[] args) throws SQLException { - try (Connection conn = getConnection()) { - createDatabase(conn); - SchemalessWriter writer = new SchemalessWriter(conn); - writer.write(lines, SchemalessProtocolType.LINE, SchemalessTimestampType.MICRO_SECONDS); - } - } -} diff --git a/docs-examples/java/src/main/java/com/taos/example/RestInsertExample.java b/docs-examples/java/src/main/java/com/taos/example/RestInsertExample.java deleted file mode 100644 index de89f26cbe38f9343d60aeb8d3e9ce7f67c2e764..0000000000000000000000000000000000000000 --- a/docs-examples/java/src/main/java/com/taos/example/RestInsertExample.java +++ /dev/null @@ -1,74 +0,0 @@ -package com.taos.example; - -import java.sql.Connection; -import java.sql.DriverManager; -import java.sql.SQLException; -import java.sql.Statement; -import java.util.Arrays; -import java.util.List; - - -public class RestInsertExample { - private static Connection getConnection() throws SQLException { - String jdbcUrl = "jdbc:TAOS-RS://localhost:6041?user=root&password=taosdata"; - return DriverManager.getConnection(jdbcUrl); - } - - private static List getRawData() { - return Arrays.asList( - "d1001,2018-10-03 14:38:05.000,10.30000,219,0.31000,Beijing.Chaoyang,2", - "d1001,2018-10-03 14:38:15.000,12.60000,218,0.33000,Beijing.Chaoyang,2", - "d1001,2018-10-03 14:38:16.800,12.30000,221,0.31000,Beijing.Chaoyang,2", - "d1002,2018-10-03 14:38:16.650,10.30000,218,0.25000,Beijing.Chaoyang,3", - "d1003,2018-10-03 14:38:05.500,11.80000,221,0.28000,Beijing.Haidian,2", - "d1003,2018-10-03 14:38:16.600,13.40000,223,0.29000,Beijing.Haidian,2", - "d1004,2018-10-03 14:38:05.000,10.80000,223,0.29000,Beijing.Haidian,3", - "d1004,2018-10-03 14:38:06.500,11.50000,221,0.35000,Beijing.Haidian,3" - ); - } - - - /** - * The generated SQL is: - * INSERT INTO power.d1001 USING power.meters TAGS(Beijing.Chaoyang, 2) VALUES('2018-10-03 14:38:05.000',10.30000,219,0.31000) - * power.d1001 USING power.meters TAGS(Beijing.Chaoyang, 2) VALUES('2018-10-03 14:38:15.000',12.60000,218,0.33000) - * power.d1001 USING power.meters TAGS(Beijing.Chaoyang, 2) VALUES('2018-10-03 14:38:16.800',12.30000,221,0.31000) - * power.d1002 USING power.meters TAGS(Beijing.Chaoyang, 3) VALUES('2018-10-03 14:38:16.650',10.30000,218,0.25000) - * power.d1003 USING power.meters TAGS(Beijing.Haidian, 2) VALUES('2018-10-03 14:38:05.500',11.80000,221,0.28000) - * power.d1003 USING power.meters TAGS(Beijing.Haidian, 2) VALUES('2018-10-03 14:38:16.600',13.40000,223,0.29000) - * power.d1004 USING power.meters TAGS(Beijing.Haidian, 3) VALUES('2018-10-03 14:38:05.000',10.80000,223,0.29000) - * power.d1004 USING power.meters TAGS(Beijing.Haidian, 3) VALUES('2018-10-03 14:38:06.500',11.50000,221,0.35000) - */ - private static String getSQL() { - StringBuilder sb = new StringBuilder("INSERT INTO "); - for (String line : getRawData()) { - String[] ps = line.split(","); - sb.append("power." + ps[0]).append(" USING power.meters TAGS(") - .append(ps[5]).append(", ") // tag: location - .append(ps[6]) // tag: groupId - .append(") VALUES(") - .append('\'').append(ps[1]).append('\'').append(",") // ts - .append(ps[2]).append(",") // current - .append(ps[3]).append(",") // voltage - .append(ps[4]).append(") "); // phase - } - return sb.toString(); - } - - public static void insertData() throws SQLException { - try (Connection conn = getConnection()) { - try (Statement stmt = conn.createStatement()) { - stmt.execute("CREATE DATABASE power KEEP 3650"); - stmt.execute("CREATE STABLE power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) " + - "TAGS (location BINARY(64), groupId INT)"); - String sql = getSQL(); - int rowCount = stmt.executeUpdate(sql); - System.out.println("rowCount=" + rowCount); // rowCount=8 - } - } - } - - public static void main(String[] args) throws SQLException { - insertData(); - } -} diff --git a/docs-examples/java/src/main/java/com/taos/example/RestQueryExample.java b/docs-examples/java/src/main/java/com/taos/example/RestQueryExample.java deleted file mode 100644 index b1a1d224c6d9af2b83ac039726dcdb49a33ec2b0..0000000000000000000000000000000000000000 --- a/docs-examples/java/src/main/java/com/taos/example/RestQueryExample.java +++ /dev/null @@ -1,55 +0,0 @@ -package com.taos.example; - -import java.sql.*; - -public class RestQueryExample { - private static Connection getConnection() throws SQLException { - String jdbcUrl = "jdbc:TAOS-RS://localhost:6041/power?user=root&password=taosdata"; - return DriverManager.getConnection(jdbcUrl); - } - - private static void printRow(ResultSet rs) throws SQLException { - ResultSetMetaData meta = rs.getMetaData(); - for (int i = 1; i <= meta.getColumnCount(); i++) { - String value = rs.getString(i); - System.out.print(value); - System.out.print("\t"); - } - System.out.println(); - } - - private static void printColName(ResultSet rs) throws SQLException { - ResultSetMetaData meta = rs.getMetaData(); - for (int i = 1; i <= meta.getColumnCount(); i++) { - String colLabel = meta.getColumnLabel(i); - System.out.print(colLabel); - System.out.print("\t"); - } - System.out.println(); - } - - private static void processResult(ResultSet rs) throws SQLException { - printColName(rs); - while (rs.next()) { - printRow(rs); - } - } - - private static void queryData() throws SQLException { - try (Connection conn = getConnection()) { - try (Statement stmt = conn.createStatement()) { - ResultSet rs = stmt.executeQuery("SELECT AVG(voltage) FROM meters GROUP BY location"); - processResult(rs); - } - } - } - - public static void main(String[] args) throws SQLException { - queryData(); - } -} - -// possible output: -// avg(voltage) location -// 222.0 Beijing.Haidian -// 219.0 Beijing.Chaoyang diff --git a/docs-examples/java/src/main/java/com/taos/example/StmtInsertExample.java b/docs-examples/java/src/main/java/com/taos/example/StmtInsertExample.java deleted file mode 100644 index 2a7ccebf41cae1a22d7516966e2c6ffb10011b64..0000000000000000000000000000000000000000 --- a/docs-examples/java/src/main/java/com/taos/example/StmtInsertExample.java +++ /dev/null @@ -1,84 +0,0 @@ -package com.taos.example; - -import com.taosdata.jdbc.TSDBPreparedStatement; - -import java.sql.Connection; -import java.sql.DriverManager; -import java.sql.SQLException; -import java.sql.Statement; -import java.time.LocalDateTime; -import java.time.ZoneOffset; -import java.time.format.DateTimeFormatter; -import java.util.ArrayList; -import java.util.Arrays; -import java.util.List; - -public class StmtInsertExample { - private static ArrayList tsToLongArray(String ts) { - ArrayList result = new ArrayList<>(); - DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss.SSS"); - LocalDateTime localDateTime = LocalDateTime.parse(ts, formatter); - result.add(localDateTime.toInstant(ZoneOffset.of("+8")).toEpochMilli()); - return result; - } - - private static ArrayList toArray(T v) { - ArrayList result = new ArrayList<>(); - result.add(v); - return result; - } - - private static List getRawData() { - return Arrays.asList( - "d1001,2018-10-03 14:38:05.000,10.30000,219,0.31000,Beijing.Chaoyang,2", - "d1001,2018-10-03 14:38:15.000,12.60000,218,0.33000,Beijing.Chaoyang,2", - "d1001,2018-10-03 14:38:16.800,12.30000,221,0.31000,Beijing.Chaoyang,2", - "d1002,2018-10-03 14:38:16.650,10.30000,218,0.25000,Beijing.Chaoyang,3", - "d1003,2018-10-03 14:38:05.500,11.80000,221,0.28000,Beijing.Haidian,2", - "d1003,2018-10-03 14:38:16.600,13.40000,223,0.29000,Beijing.Haidian,2", - "d1004,2018-10-03 14:38:05.000,10.80000,223,0.29000,Beijing.Haidian,3", - "d1004,2018-10-03 14:38:06.500,11.50000,221,0.35000,Beijing.Haidian,3" - ); - } - - private static Connection getConnection() throws SQLException { - String jdbcUrl = "jdbc:TAOS://localhost:6030?user=root&password=taosdata"; - return DriverManager.getConnection(jdbcUrl); - } - - private static void createTable(Connection conn) throws SQLException { - try (Statement stmt = conn.createStatement()) { - stmt.execute("CREATE DATABASE power KEEP 3650"); - stmt.executeUpdate("USE power"); - stmt.execute("CREATE STABLE meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) " + - "TAGS (location BINARY(64), groupId INT)"); - } - } - - private static void insertData() throws SQLException { - try (Connection conn = getConnection()) { - createTable(conn); - String psql = "INSERT INTO ? USING meters TAGS(?, ?) VALUES(?, ?, ?, ?)"; - try (TSDBPreparedStatement pst = (TSDBPreparedStatement) conn.prepareStatement(psql)) { - for (String line : getRawData()) { - String[] ps = line.split(","); - // bind table name and tags - pst.setTableName(ps[0]); - pst.setTagString(0, ps[5]); - pst.setTagInt(1, Integer.valueOf(ps[6])); - // bind values - pst.setTimestamp(0, tsToLongArray(ps[1])); //ps[1] looks like: 2018-10-03 14:38:05.000 - pst.setFloat(1, toArray(Float.valueOf(ps[2]))); - pst.setInt(2, toArray(Integer.valueOf(ps[3]))); - pst.setFloat(3, toArray(Float.valueOf(ps[4]))); - pst.columnDataAddBatch(); - } - pst.columnDataExecuteBatch(); - } - } - } - - public static void main(String[] args) throws SQLException { - insertData(); - } -} diff --git a/docs-examples/java/src/main/java/com/taos/example/TelnetLineProtocolExample.java b/docs-examples/java/src/main/java/com/taos/example/TelnetLineProtocolExample.java deleted file mode 100644 index 1431eccf16dabaac20f60ae7e971ef49707ba509..0000000000000000000000000000000000000000 --- a/docs-examples/java/src/main/java/com/taos/example/TelnetLineProtocolExample.java +++ /dev/null @@ -1,45 +0,0 @@ -package com.taos.example; - -import com.taosdata.jdbc.SchemalessWriter; -import com.taosdata.jdbc.enums.SchemalessProtocolType; -import com.taosdata.jdbc.enums.SchemalessTimestampType; - -import java.sql.Connection; -import java.sql.DriverManager; -import java.sql.SQLException; -import java.sql.Statement; - -public class TelnetLineProtocolExample { - // format: =[ =] - private static String[] lines = { "meters.current 1648432611249 10.3 location=Beijing.Chaoyang groupid=2", - "meters.current 1648432611250 12.6 location=Beijing.Chaoyang groupid=2", - "meters.current 1648432611249 10.8 location=Beijing.Haidian groupid=3", - "meters.current 1648432611250 11.3 location=Beijing.Haidian groupid=3", - "meters.voltage 1648432611249 219 location=Beijing.Chaoyang groupid=2", - "meters.voltage 1648432611250 218 location=Beijing.Chaoyang groupid=2", - "meters.voltage 1648432611249 221 location=Beijing.Haidian groupid=3", - "meters.voltage 1648432611250 217 location=Beijing.Haidian groupid=3", - }; - - private static Connection getConnection() throws SQLException { - String jdbcUrl = "jdbc:TAOS://localhost:6030?user=root&password=taosdata"; - return DriverManager.getConnection(jdbcUrl); - } - - private static void createDatabase(Connection conn) throws SQLException { - try (Statement stmt = conn.createStatement()) { - // the default precision is ms (microsecond), but we use us(microsecond) here. - stmt.execute("CREATE DATABASE IF NOT EXISTS test precision 'us'"); - stmt.execute("USE test"); - } - } - - public static void main(String[] args) throws SQLException { - try (Connection conn = getConnection()) { - createDatabase(conn); - SchemalessWriter writer = new SchemalessWriter(conn); - writer.write(lines, SchemalessProtocolType.TELNET, SchemalessTimestampType.NOT_CONFIGURED); - } - } - -} diff --git a/docs-examples/java/src/test/java/com/taos/test/TestAll.java b/docs-examples/java/src/test/java/com/taos/test/TestAll.java deleted file mode 100644 index 92fe14a49d5f5ea5d7ea5f1d809867b3de0cc9d2..0000000000000000000000000000000000000000 --- a/docs-examples/java/src/test/java/com/taos/test/TestAll.java +++ /dev/null @@ -1,91 +0,0 @@ -package com.taos.test; - -import com.taos.example.*; -import org.junit.FixMethodOrder; -import org.junit.Test; - -import java.sql.*; - -@FixMethodOrder -public class TestAll { - private String[] args = new String[]{}; - - public void dropDB(String dbName) throws SQLException { - String jdbcUrl = "jdbc:TAOS://localhost:6030?user=root&password=taosdata"; - try (Connection conn = DriverManager.getConnection(jdbcUrl)) { - try (Statement stmt = conn.createStatement()) { - stmt.execute("drop database if exists " + dbName); - } - } - } - - public void insertData() throws SQLException { - String jdbcUrl = "jdbc:TAOS://localhost:6030?user=root&password=taosdata"; - try (Connection conn = DriverManager.getConnection(jdbcUrl)) { - try (Statement stmt = conn.createStatement()) { - String sql = "INSERT INTO power.d1001 USING power.meters TAGS(Beijing.Chaoyang, 2) VALUES('2018-10-03 14:38:05.000',10.30000,219,0.31000)\n" + - " power.d1001 USING power.meters TAGS(Beijing.Chaoyang, 2) VALUES('2018-10-03 15:38:15.000',12.60000,218,0.33000)\n" + - " power.d1001 USING power.meters TAGS(Beijing.Chaoyang, 2) VALUES('2018-10-03 15:38:16.800',12.30000,221,0.31000)\n" + - " power.d1002 USING power.meters TAGS(Beijing.Chaoyang, 3) VALUES('2018-10-03 15:38:16.650',10.30000,218,0.25000)\n" + - " power.d1003 USING power.meters TAGS(Beijing.Haidian, 2) VALUES('2018-10-03 15:38:05.500',11.80000,221,0.28000)\n" + - " power.d1003 USING power.meters TAGS(Beijing.Haidian, 2) VALUES('2018-10-03 15:38:16.600',13.40000,223,0.29000)\n" + - " power.d1004 USING power.meters TAGS(Beijing.Haidian, 3) VALUES('2018-10-03 15:38:05.000',10.80000,223,0.29000)\n" + - " power.d1004 USING power.meters TAGS(Beijing.Haidian, 3) VALUES('2018-10-03 15:38:06.000',10.80000,223,0.29000)\n" + - " power.d1004 USING power.meters TAGS(Beijing.Haidian, 3) VALUES('2018-10-03 15:38:07.000',10.80000,223,0.29000)\n" + - " power.d1004 USING power.meters TAGS(Beijing.Haidian, 3) VALUES('2018-10-03 15:38:08.500',11.50000,221,0.35000)"; - - stmt.execute(sql); - } - } - } - - @Test - public void testJNIConnect() throws SQLException { - JNIConnectExample.main(args); - } - - @Test - public void testRestConnect() throws SQLException { - RESTConnectExample.main(args); - } - - @Test - public void testRestInsert() throws SQLException { - dropDB("power"); - RestInsertExample.main(args); - RestQueryExample.main(args); - } - - @Test - public void testStmtInsert() throws SQLException { - dropDB("power"); - StmtInsertExample.main(args); - } - - @Test - public void testSubscribe() { - - Thread thread = new Thread(() -> { - try { - Thread.sleep(1000); - insertData(); - } catch (SQLException e) { - e.printStackTrace(); - } catch (InterruptedException e) { - e.printStackTrace(); - } - }); - thread.start(); - SubscribeDemo.main(args); - } - - @Test - public void testSchemaless() throws SQLException { - LineProtocolExample.main(args); - TelnetLineProtocolExample.main(args); - // for json protocol, tags may be double type. but for telnet protocol tag must be nchar type. - // To avoid type mismatch, we delete database test. - dropDB("test"); - JSONProtocolExample.main(args); - } -} diff --git a/docs-examples/node/nativeexample/influxdb_line_example.js b/docs-examples/node/nativeexample/influxdb_line_example.js deleted file mode 100644 index a9fc6d11df0b335b92bb3292baaa017cb4bc42ea..0000000000000000000000000000000000000000 --- a/docs-examples/node/nativeexample/influxdb_line_example.js +++ /dev/null @@ -1,34 +0,0 @@ -const taos = require("td2.0-connector"); - -const conn = taos.connect({ - host: "localhost", -}); - -const cursor = conn.cursor(); - -function createDatabase() { - cursor.execute("CREATE DATABASE test"); - cursor.execute("USE test"); -} - -function insertData() { - const lines = [ - "meters,location=Beijing.Haidian,groupid=2 current=11.8,voltage=221,phase=0.28 1648432611249", - "meters,location=Beijing.Haidian,groupid=2 current=13.4,voltage=223,phase=0.29 1648432611250", - "meters,location=Beijing.Haidian,groupid=3 current=10.8,voltage=223,phase=0.29 1648432611249", - "meters,location=Beijing.Haidian,groupid=3 current=11.3,voltage=221,phase=0.35 1648432611250", - ]; - cursor.schemalessInsert( - lines, - taos.SCHEMALESS_PROTOCOL.TSDB_SML_LINE_PROTOCOL, - taos.SCHEMALESS_PRECISION.TSDB_SML_TIMESTAMP_MILLI_SECONDS - ); -} - -try { - createDatabase(); - insertData(); -} finally { - cursor.close(); - conn.close(); -} diff --git a/docs-examples/node/nativeexample/insert_example.js b/docs-examples/node/nativeexample/insert_example.js deleted file mode 100644 index 85a353f889176655654d8c39c9a905054d3b6622..0000000000000000000000000000000000000000 --- a/docs-examples/node/nativeexample/insert_example.js +++ /dev/null @@ -1,31 +0,0 @@ -const taos = require("td2.0-connector"); - -const conn = taos.connect({ - host: "localhost", -}); - -const cursor = conn.cursor(); -try { - cursor.execute("CREATE DATABASE power"); - cursor.execute("USE power"); - cursor.execute( - "CREATE STABLE meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)" - ); - var sql = `INSERT INTO power.d1001 USING power.meters TAGS(Beijing.Chaoyang, 2) VALUES ('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) -power.d1002 USING power.meters TAGS(Beijing.Chaoyang, 3) VALUES ('2018-10-03 14:38:16.650', 10.30000, 218, 0.25000) -power.d1003 USING power.meters TAGS(Beijing.Haidian, 2) VALUES ('2018-10-03 14:38:05.500', 11.80000, 221, 0.28000) ('2018-10-03 14:38:16.600', 13.40000, 223, 0.29000) -power.d1004 USING power.meters TAGS(Beijing.Haidian, 3) VALUES ('2018-10-03 14:38:05.000', 10.80000, 223, 0.29000) ('2018-10-03 14:38:06.500', 11.50000, 221, 0.35000)`; - cursor.execute(sql); -} finally { - cursor.close(); - conn.close(); -} - -// run with: node insert_example.js -// output: -// Successfully connected to TDengine -// Query OK, 0 row(s) affected (0.00509570s) -// Query OK, 0 row(s) affected (0.00130880s) -// Query OK, 0 row(s) affected (0.00467900s) -// Query OK, 8 row(s) affected (0.04043550s) -// Connection is closed diff --git a/docs-examples/node/nativeexample/multi_bind_example.js b/docs-examples/node/nativeexample/multi_bind_example.js deleted file mode 100644 index d52581ec8e10c6edfbc8fc8f7ca78512b5c93d74..0000000000000000000000000000000000000000 --- a/docs-examples/node/nativeexample/multi_bind_example.js +++ /dev/null @@ -1,53 +0,0 @@ -const taos = require("td2.0-connector"); - -const conn = taos.connect({ - host: "localhost", -}); - -const cursor = conn.cursor(); - -function prepareSTable() { - cursor.execute("CREATE DATABASE power"); - cursor.execute("USE power"); - cursor.execute( - "CREATE STABLE meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)" - ); -} - -//ANCHOR: insertData -function insertData() { - // init - cursor.stmtInit(); - // prepare - cursor.stmtPrepare( - "INSERT INTO ? USING meters TAGS(?, ?) VALUES(?, ?, ?, ?)" - ); - - // bind table name and tags - let tagBind = new taos.TaosBind(2); - tagBind.bindBinary("Beijing.Chaoyang"); - tagBind.bindInt(2); - cursor.stmtSetTbnameTags("d1001", tagBind.getBind()); - - // bind values - let valueBind = new taos.TaosMultiBindArr(4); - valueBind.multiBindTimestamp([1648432611249, 1648432611749]); - valueBind.multiBindFloat([10.3, 12.6]); - valueBind.multiBindInt([219, 218]); - valueBind.multiBindFloat([0.31, 0.33]); - cursor.stmtBindParamBatch(valueBind.getMultiBindArr()); - cursor.stmtAddBatch(); - - // execute - cursor.stmtExecute(); - cursor.stmtClose(); -} -//ANCHOR_END: insertData - -try { - prepareSTable(); - insertData(); -} finally { - cursor.close(); - conn.close(); -} diff --git a/docs-examples/node/nativeexample/opentsdb_json_example.js b/docs-examples/node/nativeexample/opentsdb_json_example.js deleted file mode 100644 index 6d436a8e9ebe0230bba22064e8fb6c180c14b5d1..0000000000000000000000000000000000000000 --- a/docs-examples/node/nativeexample/opentsdb_json_example.js +++ /dev/null @@ -1,55 +0,0 @@ -const taos = require("td2.0-connector"); - -const conn = taos.connect({ - host: "localhost", -}); - -const cursor = conn.cursor(); - -function createDatabase() { - cursor.execute("CREATE DATABASE test"); - cursor.execute("USE test"); -} - -function insertData() { - const lines = [ - { - metric: "meters.current", - timestamp: 1648432611249, - value: 10.3, - tags: { location: "Beijing.Chaoyang", groupid: 2 }, - }, - { - metric: "meters.voltage", - timestamp: 1648432611249, - value: 219, - tags: { location: "Beijing.Haidian", groupid: 1 }, - }, - { - metric: "meters.current", - timestamp: 1648432611250, - value: 12.6, - tags: { location: "Beijing.Chaoyang", groupid: 2 }, - }, - { - metric: "meters.voltage", - timestamp: 1648432611250, - value: 221, - tags: { location: "Beijing.Haidian", groupid: 1 }, - }, - ]; - - cursor.schemalessInsert( - [JSON.stringify(lines)], - taos.SCHEMALESS_PROTOCOL.TSDB_SML_JSON_PROTOCOL, - taos.SCHEMALESS_PRECISION.TSDB_SML_TIMESTAMP_NOT_CONFIGURED - ); -} - -try { - createDatabase(); - insertData(); -} finally { - cursor.close(); - conn.close(); -} diff --git a/docs-examples/node/nativeexample/opentsdb_telnet_example.js b/docs-examples/node/nativeexample/opentsdb_telnet_example.js deleted file mode 100644 index 01e79c2dcacd923cd708d1d228959a628d0ff26a..0000000000000000000000000000000000000000 --- a/docs-examples/node/nativeexample/opentsdb_telnet_example.js +++ /dev/null @@ -1,38 +0,0 @@ -const taos = require("td2.0-connector"); - -const conn = taos.connect({ - host: "localhost", -}); - -const cursor = conn.cursor(); - -function createDatabase() { - cursor.execute("CREATE DATABASE test"); - cursor.execute("USE test"); -} - -function insertData() { - const lines = [ - "meters.current 1648432611249 10.3 location=Beijing.Chaoyang groupid=2", - "meters.current 1648432611250 12.6 location=Beijing.Chaoyang groupid=2", - "meters.current 1648432611249 10.8 location=Beijing.Haidian groupid=3", - "meters.current 1648432611250 11.3 location=Beijing.Haidian groupid=3", - "meters.voltage 1648432611249 219 location=Beijing.Chaoyang groupid=2", - "meters.voltage 1648432611250 218 location=Beijing.Chaoyang groupid=2", - "meters.voltage 1648432611249 221 location=Beijing.Haidian groupid=3", - "meters.voltage 1648432611250 217 location=Beijing.Haidian groupid=3", - ]; - cursor.schemalessInsert( - lines, - taos.SCHEMALESS_PROTOCOL.TSDB_SML_TELNET_PROTOCOL, - taos.SCHEMALESS_PRECISION.TSDB_SML_TIMESTAMP_NOT_CONFIGURED - ); -} - -try { - createDatabase(); - insertData(); -} finally { - cursor.close(); - conn.close(); -} diff --git a/docs-examples/node/nativeexample/param_bind_example.js b/docs-examples/node/nativeexample/param_bind_example.js deleted file mode 100644 index 9117f46c3eeabd9009b72fa9d4a8503e65884242..0000000000000000000000000000000000000000 --- a/docs-examples/node/nativeexample/param_bind_example.js +++ /dev/null @@ -1,57 +0,0 @@ -const taos = require("td2.0-connector"); - -const conn = taos.connect({ - host: "localhost", -}); - -const cursor = conn.cursor(); - -function prepareSTable() { - cursor.execute("CREATE DATABASE power"); - cursor.execute("USE power"); - cursor.execute( - "CREATE STABLE meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)" - ); -} - -function insertData() { - // init - cursor.stmtInit(); - // prepare - cursor.stmtPrepare( - "INSERT INTO ? USING meters TAGS(?, ?) VALUES(?, ?, ?, ?)" - ); - - // bind table name and tags - let tagBind = new taos.TaosBind(2); - tagBind.bindBinary("Beijing.Chaoyang"); - tagBind.bindInt(2); - cursor.stmtSetTbnameTags("d1001", tagBind.getBind()); - - // bind values - let rows = [ - [1648432611249, 10.3, 219, 0.31], - [1648432611749, 12.6, 218, 0.33], - ]; - for (let row of rows) { - let valueBind = new taos.TaosBind(4); - valueBind.bindTimestamp(row[0]); - valueBind.bindFloat(row[1]); - valueBind.bindInt(row[2]); - valueBind.bindFloat(row[3]); - cursor.stmtBindParam(valueBind.getBind()); - cursor.stmtAddBatch(); - } - - // execute - cursor.stmtExecute(); - cursor.stmtClose(); -} - -try { - prepareSTable(); - insertData(); -} finally { - cursor.close(); - conn.close(); -} diff --git a/docs-examples/php/connect.php b/docs-examples/php/connect.php deleted file mode 100644 index 5af77b9768e5c5ac4b774b433479a4ac8902beda..0000000000000000000000000000000000000000 --- a/docs-examples/php/connect.php +++ /dev/null @@ -1,20 +0,0 @@ -connect(); -} catch (TDengineException $e) { - // 连接失败捕获异常 - throw $e; -} diff --git a/docs-examples/php/insert.php b/docs-examples/php/insert.php deleted file mode 100644 index 0d9cfc4843a2ec3e72d0ad128fa4c2650d6b9cf6..0000000000000000000000000000000000000000 --- a/docs-examples/php/insert.php +++ /dev/null @@ -1,33 +0,0 @@ -connect(); - - // 插入 - $connection->query('CREATE DATABASE if not exists power'); - $connection->query('CREATE STABLE if not exists meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)'); - $resource = $connection->query(<<<'SQL' - INSERT INTO power.d1001 USING power.meters TAGS(Beijing.Chaoyang, 2) VALUES ('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) - power.d1002 USING power.meters TAGS(Beijing.Chaoyang, 3) VALUES ('2018-10-03 14:38:16.650', 10.30000, 218, 0.25000) - power.d1003 USING power.meters TAGS(Beijing.Haidian, 2) VALUES ('2018-10-03 14:38:05.500', 11.80000, 221, 0.28000) ('2018-10-03 14:38:16.600', 13.40000, 223, 0.29000) - power.d1004 USING power.meters TAGS(Beijing.Haidian, 3) VALUES ('2018-10-03 14:38:05.000', 10.80000, 223, 0.29000) ('2018-10-03 14:38:06.500', 11.50000, 221, 0.35000) - SQL); - - // 影响行数 - var_dump($resource->affectedRows()); -} catch (TDengineException $e) { - // 捕获异常 - throw $e; -} diff --git a/docs-examples/php/insert_stmt.php b/docs-examples/php/insert_stmt.php deleted file mode 100644 index 5d4b4809d215d781807c21172982feff2171fe07..0000000000000000000000000000000000000000 --- a/docs-examples/php/insert_stmt.php +++ /dev/null @@ -1,49 +0,0 @@ -connect(); - - // 插入 - $connection->query('CREATE DATABASE if not exists power'); - $connection->query('CREATE STABLE if not exists meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)'); - $stmt = $connection->prepare('INSERT INTO ? USING meters TAGS(?, ?) VALUES(?, ?, ?, ?)'); - - // 设置表名和标签 - $stmt->setTableNameTags('d1001', [ - // 支持格式同参数绑定 - [TDengine\TSDB_DATA_TYPE_BINARY, 'Beijing.Chaoyang'], - [TDengine\TSDB_DATA_TYPE_INT, 2], - ]); - - $stmt->bindParams([ - [TDengine\TSDB_DATA_TYPE_TIMESTAMP, 1648432611249], - [TDengine\TSDB_DATA_TYPE_FLOAT, 10.3], - [TDengine\TSDB_DATA_TYPE_INT, 219], - [TDengine\TSDB_DATA_TYPE_FLOAT, 0.31], - ]); - $stmt->bindParams([ - [TDengine\TSDB_DATA_TYPE_TIMESTAMP, 1648432611749], - [TDengine\TSDB_DATA_TYPE_FLOAT, 12.6], - [TDengine\TSDB_DATA_TYPE_INT, 218], - [TDengine\TSDB_DATA_TYPE_FLOAT, 0.33], - ]); - $resource = $stmt->execute(); - - // 影响行数 - var_dump($resource->affectedRows()); -} catch (TDengineException $e) { - // 捕获异常 - throw $e; -} diff --git a/docs-examples/php/query.php b/docs-examples/php/query.php deleted file mode 100644 index 4e86a2cec7426887686049977a8647e786ac2744..0000000000000000000000000000000000000000 --- a/docs-examples/php/query.php +++ /dev/null @@ -1,23 +0,0 @@ -connect(); - - $resource = $connection->query('SELECT ts, current FROM meters LIMIT 2'); - var_dump($resource->fetch()); -} catch (TDengineException $e) { - // 捕获异常 - throw $e; -} diff --git a/docs-examples/python/bind_param_example.py b/docs-examples/python/bind_param_example.py deleted file mode 100644 index 503a2eb5dd91a3516f87a4d3c1c3218cb6505236..0000000000000000000000000000000000000000 --- a/docs-examples/python/bind_param_example.py +++ /dev/null @@ -1,60 +0,0 @@ -import taos -from datetime import datetime - -# note: lines have already been sorted by table name -lines = [('d1001', '2018-10-03 14:38:05.000', 10.30000, 219, 0.31000, 'Beijing.Chaoyang', 2), - ('d1001', '2018-10-03 14:38:15.000', 12.60000, 218, 0.33000, 'Beijing.Chaoyang', 2), - ('d1001', '2018-10-03 14:38:16.800', 12.30000, 221, 0.31000, 'Beijing.Chaoyang', 2), - ('d1002', '2018-10-03 14:38:16.650', 10.30000, 218, 0.25000, 'Beijing.Chaoyang', 3), - ('d1003', '2018-10-03 14:38:05.500', 11.80000, 221, 0.28000, 'Beijing.Haidian', 2), - ('d1003', '2018-10-03 14:38:16.600', 13.40000, 223, 0.29000, 'Beijing.Haidian', 2), - ('d1004', '2018-10-03 14:38:05.000', 10.80000, 223, 0.29000, 'Beijing.Haidian', 3), - ('d1004', '2018-10-03 14:38:06.500', 11.50000, 221, 0.35000, 'Beijing.Haidian', 3)] - - -def get_ts(ts: str): - dt = datetime.strptime(ts, '%Y-%m-%d %H:%M:%S.%f') - return int(dt.timestamp() * 1000) - - -def create_stable(): - conn = taos.connect() - try: - conn.execute("CREATE DATABASE power") - conn.execute("CREATE STABLE power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) " - "TAGS (location BINARY(64), groupId INT)") - finally: - conn.close() - - -def bind_row_by_row(stmt: taos.TaosStmt): - tb_name = None - for row in lines: - if tb_name != row[0]: - tb_name = row[0] - tags: taos.TaosBind = taos.new_bind_params(2) # 2 is count of tags - tags[0].binary(row[5]) # location - tags[1].int(row[6]) # groupId - stmt.set_tbname_tags(tb_name, tags) - values: taos.TaosBind = taos.new_bind_params(4) # 4 is count of columns - values[0].timestamp(get_ts(row[1])) - values[1].float(row[2]) - values[2].int(row[3]) - values[3].float(row[4]) - stmt.bind_param(values) - - -def insert_data(): - conn = taos.connect(database="power") - try: - stmt = conn.statement("INSERT INTO ? USING meters TAGS(?, ?) VALUES(?, ?, ?, ?)") - bind_row_by_row(stmt) - stmt.execute() - stmt.close() - finally: - conn.close() - - -if __name__ == '__main__': - create_stable() - insert_data() diff --git a/docs-examples/python/conn_native_pandas.py b/docs-examples/python/conn_native_pandas.py deleted file mode 100644 index 314759f7662c7bf4c9df2c8b3396ad3101c91cd4..0000000000000000000000000000000000000000 --- a/docs-examples/python/conn_native_pandas.py +++ /dev/null @@ -1,19 +0,0 @@ -import pandas -from sqlalchemy import create_engine - -engine = create_engine("taos://root:taosdata@localhost:6030/power") -df = pandas.read_sql("SELECT * FROM meters", engine) - -# print index -print(df.index) -# print data type of element in ts column -print(type(df.ts[0])) -print(df.head(3)) - -# output: -# RangeIndex(start=0, stop=8, step=1) -# -# ts current voltage phase location groupid -# 0 2018-10-03 14:38:05.000 10.3 219 0.31 beijing.chaoyang 2 -# 1 2018-10-03 14:38:15.000 12.6 218 0.33 beijing.chaoyang 2 -# 2 2018-10-03 14:38:16.800 12.3 221 0.31 beijing.chaoyang 2 diff --git a/docs-examples/python/conn_rest_pandas.py b/docs-examples/python/conn_rest_pandas.py deleted file mode 100644 index 143e4275fa4eda685766297e4b90cba3935a574d..0000000000000000000000000000000000000000 --- a/docs-examples/python/conn_rest_pandas.py +++ /dev/null @@ -1,19 +0,0 @@ -import pandas -from sqlalchemy import create_engine - -engine = create_engine("taosrest://root:taosdata@localhost:6041") -df: pandas.DataFrame = pandas.read_sql("SELECT * FROM power.meters", engine) - -# print index -print(df.index) -# print data type of element in ts column -print(type(df.ts[0])) -print(df.head(3)) - -# output: -# -# RangeIndex(start=0, stop=8, step=1) -# ts current ... location groupid -# 0 2018-10-03 14:38:05+08:00 10.3 ... beijing.chaoyang 2 -# 1 2018-10-03 14:38:15+08:00 12.6 ... beijing.chaoyang 2 -# 2 2018-10-03 14:38:16.800000+08:00 12.3 ... beijing.chaoyang 2 diff --git a/docs-examples/python/connect_rest_examples.py b/docs-examples/python/connect_rest_examples.py deleted file mode 100644 index a043d506b965bc31179dbb6f38749d196ab338ff..0000000000000000000000000000000000000000 --- a/docs-examples/python/connect_rest_examples.py +++ /dev/null @@ -1,45 +0,0 @@ -# ANCHOR: connect -from taosrest import connect, TaosRestConnection, TaosRestCursor - -conn: TaosRestConnection = connect(host="localhost", - user="root", - password="taosdata", - port=6041, - timeout=30) - -# ANCHOR_END: connect -# ANCHOR: basic -# create STable -cursor: TaosRestCursor = conn.cursor() -cursor.execute("DROP DATABASE IF EXISTS power") -cursor.execute("CREATE DATABASE power") -cursor.execute("CREATE STABLE power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)") - -# insert data -cursor.execute("""INSERT INTO power.d1001 USING power.meters TAGS(Beijing.Chaoyang, 2) VALUES ('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) - power.d1002 USING power.meters TAGS(Beijing.Chaoyang, 3) VALUES ('2018-10-03 14:38:16.650', 10.30000, 218, 0.25000) - power.d1003 USING power.meters TAGS(Beijing.Haidian, 2) VALUES ('2018-10-03 14:38:05.500', 11.80000, 221, 0.28000) ('2018-10-03 14:38:16.600', 13.40000, 223, 0.29000) - power.d1004 USING power.meters TAGS(Beijing.Haidian, 3) VALUES ('2018-10-03 14:38:05.000', 10.80000, 223, 0.29000) ('2018-10-03 14:38:06.500', 11.50000, 221, 0.35000)""") -print("inserted row count:", cursor.rowcount) - -# query data -cursor.execute("SELECT * FROM power.meters LIMIT 3") -# get total rows -print("queried row count:", cursor.rowcount) -# get column names from cursor -column_names = [meta[0] for meta in cursor.description] -# get rows -data: list[tuple] = cursor.fetchall() -print(column_names) -for row in data: - print(row) - -# output: -# inserted row count: 8 -# queried row count: 3 -# ['ts', 'current', 'voltage', 'phase', 'location', 'groupid'] -# [datetime.datetime(2018, 10, 3, 14, 38, 5, tzinfo=datetime.timezone(datetime.timedelta(seconds=28800), '+08:00')), 10.3, 219, 0.31, 'beijing.chaoyang', 2] -# [datetime.datetime(2018, 10, 3, 14, 38, 15, tzinfo=datetime.timezone(datetime.timedelta(seconds=28800), '+08:00')), 12.6, 218, 0.33, 'beijing.chaoyang', 2] -# [datetime.datetime(2018, 10, 3, 14, 38, 16, 800000, tzinfo=datetime.timezone(datetime.timedelta(seconds=28800), '+08:00')), 12.3, 221, 0.31, 'beijing.chaoyang', 2] - -# ANCHOR_END: basic diff --git a/docs-examples/python/json_protocol_example.py b/docs-examples/python/json_protocol_example.py deleted file mode 100644 index 5bb4d629bccf3d79e74b381d6259de86d6522315..0000000000000000000000000000000000000000 --- a/docs-examples/python/json_protocol_example.py +++ /dev/null @@ -1,38 +0,0 @@ -import json - -import taos -from taos import SmlProtocol, SmlPrecision - -lines = [{"metric": "meters.current", "timestamp": 1648432611249, "value": 10.3, "tags": {"location": "Beijing.Chaoyang", "groupid": 2}}, - {"metric": "meters.voltage", "timestamp": 1648432611249, "value": 219, - "tags": {"location": "Beijing.Haidian", "groupid": 1}}, - {"metric": "meters.current", "timestamp": 1648432611250, "value": 12.6, - "tags": {"location": "Beijing.Chaoyang", "groupid": 2}}, - {"metric": "meters.voltage", "timestamp": 1648432611250, "value": 221, "tags": {"location": "Beijing.Haidian", "groupid": 1}}] - - -def get_connection(): - return taos.connect() - - -def create_database(conn): - conn.execute("CREATE DATABASE test") - conn.execute("USE test") - - -def insert_lines(conn): - global lines - lines = json.dumps(lines) - # note: the first parameter must be a list with only one element. - affected_rows = conn.schemaless_insert( - [lines], SmlProtocol.JSON_PROTOCOL, SmlPrecision.NOT_CONFIGURED) - print(affected_rows) # 4 - - -if __name__ == '__main__': - connection = get_connection() - try: - create_database(connection) - insert_lines(connection) - finally: - connection.close() diff --git a/docs-examples/python/line_protocol_example.py b/docs-examples/python/line_protocol_example.py deleted file mode 100644 index 02baeb2104f9f48984b4d34afb5e67af641d4e32..0000000000000000000000000000000000000000 --- a/docs-examples/python/line_protocol_example.py +++ /dev/null @@ -1,34 +0,0 @@ -import taos -from taos import SmlProtocol, SmlPrecision - -lines = ["meters,location=Beijing.Haidian,groupid=2 current=11.8,voltage=221,phase=0.28 1648432611249000", - "meters,location=Beijing.Haidian,groupid=2 current=13.4,voltage=223,phase=0.29 1648432611249500", - "meters,location=Beijing.Haidian,groupid=3 current=10.8,voltage=223,phase=0.29 1648432611249300", - "meters,location=Beijing.Haidian,groupid=3 current=11.3,voltage=221,phase=0.35 1648432611249800", - ] - - -def get_connection(): - # create connection use firstEP in taos.cfg. - return taos.connect() - - -def create_database(conn): - # the default precision is ms (microsecond), but we use us(microsecond) here. - conn.execute("CREATE DATABASE test precision 'us'") - conn.execute("USE test") - - -def insert_lines(conn): - affected_rows = conn.schemaless_insert( - lines, SmlProtocol.LINE_PROTOCOL, SmlPrecision.MICRO_SECONDS) - print(affected_rows) # 8 - - -if __name__ == '__main__': - connection = get_connection() - try: - create_database(connection) - insert_lines(connection) - finally: - connection.close() diff --git a/docs-examples/python/multi_bind_example.py b/docs-examples/python/multi_bind_example.py deleted file mode 100644 index 1714121d72705ab8d619a41f3463af4aa3193871..0000000000000000000000000000000000000000 --- a/docs-examples/python/multi_bind_example.py +++ /dev/null @@ -1,88 +0,0 @@ -import taos -from datetime import datetime - -# ANCHOR: bind_batch -table_tags = { - "d1001": ('Beijing.Chaoyang', 2), - "d1002": ('Beijing.Chaoyang', 3), - "d1003": ('Beijing.Haidian', 2), - "d1004": ('Beijing.Haidian', 3) -} - -table_values = { - "d1001": [ - ['2018-10-03 14:38:05.000', '2018-10-03 14:38:15.000', '2018-10-03 14:38:16.800'], - [10.3, 12.6, 12.3], - [219, 218, 221], - [0.31, 0.33, 0.32] - ], - "d1002": [ - ['2018-10-03 14:38:16.650'], [10.3], [218], [0.25] - ], - "d1003": [ - ['2018-10-03 14:38:05.500', '2018-10-03 14:38:16.600'], - [11.8, 13.4], - [221, 223], - [0.28, 0.29] - ], - "d1004": [ - ['2018-10-03 14:38:05.500', '2018-10-03 14:38:06.500'], - [10.8, 11.5], - [223, 221], - [0.29, 0.35] - ] -} - - -def bind_multi_rows(stmt: taos.TaosStmt): - """ - batch bind example - """ - for tb_name in table_values.keys(): - tags = table_tags[tb_name] - tag_params = taos.new_bind_params(2) - tag_params[0].binary(tags[0]) - tag_params[1].int(tags[1]) - stmt.set_tbname_tags(tb_name, tag_params) - - values = table_values[tb_name] - value_params = taos.new_multi_binds(4) - value_params[0].timestamp([get_ts(t) for t in values[0]]) - value_params[1].float(values[1]) - value_params[2].int(values[2]) - value_params[3].float(values[3]) - stmt.bind_param_batch(value_params) - - -def insert_data(): - conn = taos.connect(database="power") - try: - stmt = conn.statement("INSERT INTO ? USING meters TAGS(?, ?) VALUES(?, ?, ?, ?)") - bind_multi_rows(stmt) - stmt.execute() - stmt.close() - finally: - conn.close() - - -# ANCHOR_END: bind_batch - - -def create_stable(): - conn = taos.connect() - try: - conn.execute("CREATE DATABASE power") - conn.execute("CREATE STABLE power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) " - "TAGS (location BINARY(64), groupId INT)") - finally: - conn.close() - - -def get_ts(ts: str): - dt = datetime.strptime(ts, '%Y-%m-%d %H:%M:%S.%f') - return int(dt.timestamp() * 1000) - - -if __name__ == '__main__': - create_stable() - insert_data() diff --git a/docs-examples/python/native_insert_example.py b/docs-examples/python/native_insert_example.py deleted file mode 100644 index 94d4888a8f5330b9e39d5ae051fcb68f9825505f..0000000000000000000000000000000000000000 --- a/docs-examples/python/native_insert_example.py +++ /dev/null @@ -1,60 +0,0 @@ -import taos - -lines = ["d1001,2018-10-03 14:38:05.000,10.30000,219,0.31000,Beijing.Chaoyang,2", - "d1004,2018-10-03 14:38:05.000,10.80000,223,0.29000,Beijing.Haidian,3", - "d1003,2018-10-03 14:38:05.500,11.80000,221,0.28000,Beijing.Haidian,2", - "d1004,2018-10-03 14:38:06.500,11.50000,221,0.35000,Beijing.Haidian,3", - "d1002,2018-10-03 14:38:16.650,10.30000,218,0.25000,Beijing.Chaoyang,3", - "d1001,2018-10-03 14:38:15.000,12.60000,218,0.33000,Beijing.Chaoyang,2", - "d1001,2018-10-03 14:38:16.800,12.30000,221,0.31000,Beijing.Chaoyang,2", - "d1003,2018-10-03 14:38:16.600,13.40000,223,0.29000,Beijing.Haidian,2"] - - -def get_connection() -> taos.TaosConnection: - """ - create connection use firstEp in taos.cfg and use default user and password. - """ - return taos.connect() - - -def create_stable(conn: taos.TaosConnection): - conn.execute("CREATE DATABASE power") - conn.execute("USE power") - conn.execute("CREATE STABLE meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) " - "TAGS (location BINARY(64), groupId INT)") - - -# The generated SQL is: -# INSERT INTO d1001 USING meters TAGS(Beijing.Chaoyang, 2) VALUES ('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) -# 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) ('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) ('2018-10-03 14:38:06.500', 11.50000, 221, 0.35000) - -def get_sql(): - global lines - lines = map(lambda line: line.split(','), lines) # [['d1001', ...]...] - lines = sorted(lines, key=lambda ls: ls[0]) # sort by table name - sql = "INSERT INTO " - tb_name = None - for ps in lines: - tmp_tb_name = ps[0] - if tb_name != tmp_tb_name: - tb_name = tmp_tb_name - sql += f"{tb_name} USING meters TAGS({ps[5]}, {ps[6]}) VALUES " - sql += f"('{ps[1]}', {ps[2]}, {ps[3]}, {ps[4]}) " - return sql - - -def insert_data(conn: taos.TaosConnection): - sql = get_sql() - affected_rows = conn.execute(sql) - print("affected_rows", affected_rows) # 8 - - -if __name__ == '__main__': - connection = get_connection() - try: - create_stable(connection) - insert_data(connection) - finally: - connection.close() diff --git a/docs-examples/python/query_example.py b/docs-examples/python/query_example.py deleted file mode 100644 index 6d33c49c968d9210b475931b5d8cecca0ceff3e3..0000000000000000000000000000000000000000 --- a/docs-examples/python/query_example.py +++ /dev/null @@ -1,42 +0,0 @@ -import taos - - -# ANCHOR: iter -def query_api_demo(conn: taos.TaosConnection): - result: taos.TaosResult = conn.query("SELECT tbname, * FROM meters LIMIT 2") - print("field count:", result.field_count) - print("meta of fields[1]:", result.fields[1]) - print("======================Iterate on result=========================") - for row in result: - print(row) - - -# field count: 7 -# meta of files[1]: {name: ts, type: 9, bytes: 8} -# ======================Iterate on result========================= -# ('d1001', datetime.datetime(2018, 10, 3, 14, 38, 5), 10.300000190734863, 219, 0.3100000023841858, 'Beijing.Chaoyang', 2) -# ('d1001', datetime.datetime(2018, 10, 3, 14, 38, 15), 12.600000381469727, 218, 0.33000001311302185, 'Beijing.Chaoyang', 2) -# ANCHOR_END: iter - -# ANCHOR: fetch_all -def fetch_all_demo(conn: taos.TaosConnection): - result: taos.TaosResult = conn.query("SELECT ts, current FROM meters LIMIT 2") - rows = result.fetch_all_into_dict() - print("row count:", result.row_count) - print("===============all data===================") - print(rows) - - -# row count: 2 -# ===============all data=================== -# [{'ts': datetime.datetime(2018, 10, 3, 14, 38, 5), 'current': 10.300000190734863}, -# {'ts': datetime.datetime(2018, 10, 3, 14, 38, 15), 'current': 12.600000381469727}] -# ANCHOR_END: fetch_all - -if __name__ == '__main__': - connection = taos.connect(database="power") - try: - query_api_demo(connection) - fetch_all_demo(connection) - finally: - connection.close() diff --git a/docs-examples/python/rest_client_example.py b/docs-examples/python/rest_client_example.py deleted file mode 100644 index 46d33a1d795f8c8dbb0b830061d43ed4510046ba..0000000000000000000000000000000000000000 --- a/docs-examples/python/rest_client_example.py +++ /dev/null @@ -1,9 +0,0 @@ -from taosrest import RestClient - -client = RestClient("localhost", 6041, "root", "taosdata") -res: dict = client.sql("SELECT ts, current FROM power.meters LIMIT 1") -print(res) - -# output: -# {'status': 'succ', 'head': ['ts', 'current'], 'column_meta': [['ts', 9, 8], ['current', 6, 4]], 'data': [[datetime.datetime(2018, 10, 3, 14, 38, 5, tzinfo=datetime.timezone(datetime.timedelta(seconds=28800), '+08:00')), 10.3]], 'rows': 1} - diff --git a/docs-examples/python/telnet_line_protocol_example.py b/docs-examples/python/telnet_line_protocol_example.py deleted file mode 100644 index 072835109ee238940e6fe5880b72b2b04e0157fa..0000000000000000000000000000000000000000 --- a/docs-examples/python/telnet_line_protocol_example.py +++ /dev/null @@ -1,38 +0,0 @@ -import taos -from taos import SmlProtocol, SmlPrecision - -# format: =[ =] -lines = ["meters.current 1648432611249 10.3 location=Beijing.Chaoyang groupid=2", - "meters.current 1648432611250 12.6 location=Beijing.Chaoyang groupid=2", - "meters.current 1648432611249 10.8 location=Beijing.Haidian groupid=3", - "meters.current 1648432611250 11.3 location=Beijing.Haidian groupid=3", - "meters.voltage 1648432611249 219 location=Beijing.Chaoyang groupid=2", - "meters.voltage 1648432611250 218 location=Beijing.Chaoyang groupid=2", - "meters.voltage 1648432611249 221 location=Beijing.Haidian groupid=3", - "meters.voltage 1648432611250 217 location=Beijing.Haidian groupid=3", - ] - - -# create connection use firstEp in taos.cfg. -def get_connection(): - return taos.connect() - - -def create_database(conn): - conn.execute("CREATE DATABASE test") - conn.execute("USE test") - - -def insert_lines(conn): - affected_rows = conn.schemaless_insert( - lines, SmlProtocol.TELNET_PROTOCOL, SmlPrecision.NOT_CONFIGURED) - print(affected_rows) # 8 - - -if __name__ == '__main__': - connection = get_connection() - try: - create_database(connection) - insert_lines(connection) - finally: - connection.close() diff --git a/docs-examples/rust/nativeexample/examples/stmt_example.rs b/docs-examples/rust/nativeexample/examples/stmt_example.rs deleted file mode 100644 index a791a4135984a33dded145e8175d7ade57de8d77..0000000000000000000000000000000000000000 --- a/docs-examples/rust/nativeexample/examples/stmt_example.rs +++ /dev/null @@ -1,38 +0,0 @@ -use bstr::BString; -use libtaos::*; - -#[tokio::main] -async fn main() -> Result<(), Error> { - let taos = TaosCfg::default().connect().expect("fail to connect"); - taos.create_database("power").await?; - taos.use_database("power").await?; - taos.exec("CREATE STABLE meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)").await?; - let mut stmt = taos.stmt("INSERT INTO ? USING meters TAGS(?, ?) VALUES(?, ?, ?, ?)")?; - // bind table name and tags - stmt.set_tbname_tags( - "d1001", - [ - Field::Binary(BString::from("Beijing.Chaoyang")), - Field::Int(2), - ], - )?; - // bind values. - let values = vec![ - Field::Timestamp(Timestamp::new(1648432611249, TimestampPrecision::Milli)), - Field::Float(10.3), - Field::Int(219), - Field::Float(0.31), - ]; - stmt.bind(&values)?; - // bind one more row - let values2 = vec![ - Field::Timestamp(Timestamp::new(1648432611749, TimestampPrecision::Milli)), - Field::Float(12.6), - Field::Int(218), - Field::Float(0.33), - ]; - stmt.bind(&values2)?; - // execute - stmt.execute()?; - Ok(()) -} diff --git a/docs-examples/rust/restexample/examples/insert_example.rs b/docs-examples/rust/restexample/examples/insert_example.rs deleted file mode 100644 index d7acc98d096fb3cd6bea22d6c5f6f0f5caea50af..0000000000000000000000000000000000000000 --- a/docs-examples/rust/restexample/examples/insert_example.rs +++ /dev/null @@ -1,18 +0,0 @@ -use libtaos::*; - -#[tokio::main] -async fn main() -> Result<(), Error> { - let taos = TaosCfg::default().connect().expect("fail to connect"); - taos.create_database("power").await?; - taos.exec("CREATE STABLE power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)").await?; - let sql = "INSERT INTO power.d1001 USING power.meters TAGS(Beijing.Chaoyang, 2) VALUES ('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) - power.d1002 USING power.meters TAGS(Beijing.Chaoyang, 3) VALUES ('2018-10-03 14:38:16.650', 10.30000, 218, 0.25000) - power.d1003 USING power.meters TAGS(Beijing.Haidian, 2) VALUES ('2018-10-03 14:38:05.500', 11.80000, 221, 0.28000) ('2018-10-03 14:38:16.600', 13.40000, 223, 0.29000) - power.d1004 USING power.meters TAGS(Beijing.Haidian, 3) VALUES ('2018-10-03 14:38:05.000', 10.80000, 223, 0.29000) ('2018-10-03 14:38:06.500', 11.50000, 221, 0.35000)"; - let result = taos.query(sql).await?; - println!("{:?}", result); - Ok(()) -} - -// output: -// TaosQueryData { column_meta: [ColumnMeta { name: "affected_rows", type_: Int, bytes: 4 }], rows: [[Int(8)]] } diff --git a/docs-examples/rust/schemalessexample/examples/influxdb_line_example.rs b/docs-examples/rust/schemalessexample/examples/influxdb_line_example.rs deleted file mode 100644 index e93888cc83d12f3bec7370a66e8a85d38cec42ad..0000000000000000000000000000000000000000 --- a/docs-examples/rust/schemalessexample/examples/influxdb_line_example.rs +++ /dev/null @@ -1,22 +0,0 @@ -use libtaos::schemaless::*; -use libtaos::*; - -fn main() { - let taos = TaosCfg::default().connect().expect("fail to connect"); - taos.raw_query("CREATE DATABASE test").unwrap(); - taos.raw_query("USE test").unwrap(); - let lines = ["meters,location=Beijing.Haidian,groupid=2 current=11.8,voltage=221,phase=0.28 1648432611249", - "meters,location=Beijing.Haidian,groupid=2 current=13.4,voltage=223,phase=0.29 1648432611250", - "meters,location=Beijing.Haidian,groupid=3 current=10.8,voltage=223,phase=0.29 1648432611249", - "meters,location=Beijing.Haidian,groupid=3 current=11.3,voltage=221,phase=0.35 1648432611250"]; - let affected_rows = taos - .schemaless_insert( - &lines, - TSDB_SML_LINE_PROTOCOL, - TSDB_SML_TIMESTAMP_MILLISECONDS, - ) - .unwrap(); - println!("affected_rows={}", affected_rows); -} - -// run with: cargo run --example influxdb_line_example diff --git a/docs-examples/rust/schemalessexample/examples/opentsdb_json_example.rs b/docs-examples/rust/schemalessexample/examples/opentsdb_json_example.rs deleted file mode 100644 index 1d66bd1f2b1bcbe82dc3ee3e8e25ea4c521c81f0..0000000000000000000000000000000000000000 --- a/docs-examples/rust/schemalessexample/examples/opentsdb_json_example.rs +++ /dev/null @@ -1,25 +0,0 @@ -use libtaos::schemaless::*; -use libtaos::*; - -fn main() { - let taos = TaosCfg::default().connect().expect("fail to connect"); - taos.raw_query("CREATE DATABASE test").unwrap(); - taos.raw_query("USE test").unwrap(); - let lines = [ - r#"[{"metric": "meters.current", "timestamp": 1648432611249, "value": 10.3, "tags": {"location": "Beijing.Chaoyang", "groupid": 2}}, - {"metric": "meters.voltage", "timestamp": 1648432611249, "value": 219, "tags": {"location": "Beijing.Haidian", "groupid": 1}}, - {"metric": "meters.current", "timestamp": 1648432611250, "value": 12.6, "tags": {"location": "Beijing.Chaoyang", "groupid": 2}}, - {"metric": "meters.voltage", "timestamp": 1648432611250, "value": 221, "tags": {"location": "Beijing.Haidian", "groupid": 1}}]"#, - ]; - - let affected_rows = taos - .schemaless_insert( - &lines, - TSDB_SML_JSON_PROTOCOL, - TSDB_SML_TIMESTAMP_NOT_CONFIGURED, - ) - .unwrap(); - println!("affected_rows={}", affected_rows); // affected_rows=4 -} - -// run with: cargo run --example opentsdb_json_example diff --git a/docs-examples/rust/schemalessexample/examples/opentsdb_telnet_example.rs b/docs-examples/rust/schemalessexample/examples/opentsdb_telnet_example.rs deleted file mode 100644 index 18d7500714d9e41b1bebd490199d296ead3dc7c4..0000000000000000000000000000000000000000 --- a/docs-examples/rust/schemalessexample/examples/opentsdb_telnet_example.rs +++ /dev/null @@ -1,28 +0,0 @@ -use libtaos::schemaless::*; -use libtaos::*; - -fn main() { - let taos = TaosCfg::default().connect().expect("fail to connect"); - taos.raw_query("CREATE DATABASE test").unwrap(); - taos.raw_query("USE test").unwrap(); - let lines = [ - "meters.current 1648432611249 10.3 location=Beijing.Chaoyang groupid=2", - "meters.current 1648432611250 12.6 location=Beijing.Chaoyang groupid=2", - "meters.current 1648432611249 10.8 location=Beijing.Haidian groupid=3", - "meters.current 1648432611250 11.3 location=Beijing.Haidian groupid=3", - "meters.voltage 1648432611249 219 location=Beijing.Chaoyang groupid=2", - "meters.voltage 1648432611250 218 location=Beijing.Chaoyang groupid=2", - "meters.voltage 1648432611249 221 location=Beijing.Haidian groupid=3", - "meters.voltage 1648432611250 217 location=Beijing.Haidian groupid=3", - ]; - let affected_rows = taos - .schemaless_insert( - &lines, - TSDB_SML_TELNET_PROTOCOL, - TSDB_SML_TIMESTAMP_NOT_CONFIGURED, - ) - .unwrap(); - println!("affected_rows={}", affected_rows); // affected_rows=8 -} - -// run with: cargo run --example opentsdb_telnet_example diff --git a/docs/en/01-index.md b/docs/en/01-index.md new file mode 100644 index 0000000000000000000000000000000000000000..d76c12e10fce24dff9f916945f5b6236857ebb8d --- /dev/null +++ b/docs/en/01-index.md @@ -0,0 +1,27 @@ +--- +title: TDengine Documentation +sidebar_label: Documentation Home +slug: / +--- + +TDengine is a [high-performance](https://tdengine.com/fast), [scalable](https://tdengine.com/scalable) time series database with [SQL support](https://tdengine.com/sql-support). This document is the TDengine user manual. It introduces the basic, as well as novel concepts, in TDengine, and also talks in detail about installation, features, SQL, APIs, operation, maintenance, kernel design and other topics. It’s written mainly for architects, developers and system administrators. + +To get a global view about TDengine, like feature list, benchmarks, and competitive advantages, please browse through section [Introduction](./intro). + +TDengine greatly improves the efficiency of data ingestion, querying and storage by exploiting the characteristics of time series data, introducing the novel concepts of "one table for one data collection point" and "super table", and designing an innovative storage engine. To understand the new concepts in TDengine and make full use of the features and capabilities of TDengine, please read [“Concepts”](./concept) thoroughly. + +If you are a developer, please read the [“Developer Guide”](./develop) carefully. This section introduces the database connection, data modeling, data ingestion, query, continuous query, cache, data subscription, user-defined functions, and other functionality in detail. Sample code is provided for a variety of programming languages. In most cases, you can just copy and paste the sample code, make a few changes to accommodate your application, and it will work. + +We live in the era of big data, and scale-up is unable to meet the growing business needs. Any modern data system must have the ability to scale out, and clustering has become an indispensable feature of big data systems. Not only did the TDengine team develop the cluster feature, but also decided to open source this important feature. To learn how to deploy, manage and maintain a TDengine cluster please refer to ["cluster"](./cluster). + +TDengine uses ubiquitious SQL as its query language, which greatly reduces learning costs and migration costs. In addition to the standard SQL, TDengine has extensions to better support time series data analysis. These extensions include functions such as roll up, interpolation and time weighted average, among many others. The ["SQL Reference"](./taos-sql) chapter describes the SQL syntax in detail, and lists the various supported commands and functions. + +If you are a system administrator who cares about installation, upgrade, fault tolerance, disaster recovery, data import, data export, system configuration, how to monitor whether TDengine is running healthily, and how to improve system performance, please refer to, and thoroughly read the ["Administration"](./operation) section. + +If you want to know more about TDengine tools, the REST API, and connectors for various programming languages, please see the ["Reference"](./reference) chapter. + +If you are very interested in the internal design of TDengine, please read the chapter ["Inside TDengine”](./tdinternal), which introduces the cluster design, data partitioning, sharding, writing, and reading processes in detail. If you want to study TDengine code or even contribute code, please read this chapter carefully. + +TDengine is an open source database, and we would love for you to be a part of TDengine. If you find any errors in the documentation, or see parts where more clarity or elaboration is needed, please click "Edit this page" at the bottom of each page to edit it directly. + +Together, we make a difference. diff --git a/docs-en/01-intro/_category_.yml b/docs/en/02-intro/_category_.yml similarity index 100% rename from docs-en/01-intro/_category_.yml rename to docs/en/02-intro/_category_.yml diff --git a/docs/en/02-intro/eco_system.webp b/docs/en/02-intro/eco_system.webp new file mode 100644 index 0000000000000000000000000000000000000000..d60c38e97c67fa7b2acc703b2ba777d19ae5be13 Binary files /dev/null and b/docs/en/02-intro/eco_system.webp differ diff --git a/docs/en/02-intro/index.md b/docs/en/02-intro/index.md new file mode 100644 index 0000000000000000000000000000000000000000..f6766f910f4d7560b782bf02ffa97922523e6167 --- /dev/null +++ b/docs/en/02-intro/index.md @@ -0,0 +1,113 @@ +--- +title: Introduction +toc_max_heading_level: 2 +--- + +TDengine is a high-performance, scalable time-series database with SQL support. Its code, including its cluster feature is open source under GNU AGPL v3.0. Besides the database engine, it provides [caching](/develop/cache), [stream processing](/develop/continuous-query), [data subscription](/develop/subscribe) and other functionalities to reduce the complexity and cost of development and operation. + +This section introduces the major features, competitive advantages, typical use-cases and benchmarks to help you get a high level overview of TDengine. + +## Major Features + +The major features are listed below: + +1. While TDengine supports [using SQL to insert](/develop/insert-data/sql-writing), it also supports [Schemaless writing](/reference/schemaless/) just like NoSQL databases. TDengine also supports standard protocols like [InfluxDB LINE](/develop/insert-data/influxdb-line)，[OpenTSDB Telnet](/develop/insert-data/opentsdb-telnet), [OpenTSDB JSON ](/develop/insert-data/opentsdb-json) among others. +2. TDengine supports seamless integration with third-party data collection agents like [Telegraf](/third-party/telegraf)，[Prometheus](/third-party/prometheus)，[StatsD](/third-party/statsd)，[collectd](/third-party/collectd)，[icinga2](/third-party/icinga2), [TCollector](/third-party/tcollector), [EMQX](/third-party/emq-broker), [HiveMQ](/third-party/hive-mq-broker). These agents can write data into TDengine with simple configuration and without a single line of code. +3. Support for [all kinds of queries](/develop/query-data), including aggregation, nested query, downsampling, interpolation and others. +4. Support for [user defined functions](/develop/udf). +5. Support for [caching](/develop/cache). TDengine always saves the last data point in cache, so Redis is not needed in some scenarios. +6. Support for [continuous query](/develop/continuous-query). +7. Support for [data subscription](/develop/subscribe) with the capability to specify filter conditions. +8. Support for [cluster](/cluster/), with the capability of increasing processing power by adding more nodes. High availability is supported by replication. +9. Provides an interactive [command-line interface](/reference/taos-shell) for management, maintenance and ad-hoc queries. +10. Provides many ways to [import](/operation/import) and [export](/operation/export) data. +11. Provides [monitoring](/operation/monitor) on running instances of TDengine. +12. Provides [connectors](/reference/connector/) for [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) and other programming languages. +13. Provides a [REST API](/reference/rest-api/). +14. Supports seamless integration with [Grafana](/third-party/grafana) for visualization. +15. Supports seamless integration with Google Data Studio. + +For more details on features, please read through the entire documentation. + +## Competitive Advantages + +Time-series data is structured, not transactional, and is rarely deleted or updated. TDengine makes full use of [these characteristics of time series data](https://tdengine.com/2019/07/09/86.html) to build its own innovative storage engine and computing engine to differentiate itself from other time series databases, with the following advantages. + +- **[High Performance](https://tdengine.com/fast)**: With an innovatively designed and purpose-built storage engine, TDengine outperforms other time series databases in data ingestion and querying while significantly reducing storage costs and compute costs. + +- **[Scalable](https://tdengine.com/scalable)**: TDengine provides out-of-box scalability and high-availability through its native distributed design. Nodes can be added through simple configuration to achieve greater data processing power. In addition, this feature is open source. + +- **[SQL Support](https://tdengine.com/sql-support)**: TDengine uses SQL as the query language, thereby reducing learning and migration costs, while adding SQL extensions to better handle time-series. Keeping NoSQL developers in mind, TDengine also supports convenient and flexible, schemaless data ingestion. + +- **All in One**: TDengine has built-in caching, stream processing and data subscription functions. It is no longer necessary to integrate Kafka/Redis/HBase/Spark or other software in some scenarios. It makes the system architecture much simpler, cost-effective and easier to maintain. + +- **Seamless Integration**: Without a single line of code, TDengine provide seamless, configurable integration with third-party tools such as Telegraf, Grafana, EMQX, Prometheus, StatsD, collectd, etc. More third-party tools are being integrated. + +- **Zero Management**: Installation and cluster setup can be done in seconds. Data partitioning and sharding are executed automatically. TDengine’s running status can be monitored via Grafana or other DevOps tools. + +- **Zero Learning Costs**: With SQL as the query language and support for ubiquitous tools like Python, Java, C/C++, Go, Rust, and Node.js connectors, and a REST API, there are zero learning costs. + +- **Interactive Console**: TDengine provides convenient console access to the database, through a CLI, to run ad hoc queries, maintain the database, or manage the cluster, without any programming. + +With TDengine, the total cost of ownership of your time-series data platform can be greatly reduced. 1: With its superior performance, the computing and storage resources are reduced significantly 2: With SQL support, it can be seamlessly integrated with many third party tools, and learning costs/migration costs are reduced significantly 3: With its simple architecture and zero management, the operation and maintenance costs are reduced. + +## Technical Ecosystem +This is how TDengine would be situated, in a typical time-series data processing platform: + +![TDengine Database Technical Ecosystem ](eco_system.webp) + +
Figure 1. TDengine Technical Ecosystem
+ +On the left-hand side, there are data collection agents like OPC-UA, MQTT, Telegraf and Kafka. On the right-hand side, visualization/BI tools, HMI, Python/R, and IoT Apps can be connected. TDengine itself provides an interactive command-line interface and a web interface for management and maintenance. + +## Typical Use Cases + +As a high-performance, scalable and SQL supported time-series database, TDengine's typical use case include but are not limited to IoT, Industrial Internet, Connected Vehicles, IT operation and maintenance, energy, financial markets and other fields. TDengine is a purpose-built database optimized for the characteristics of time series data. As such, it cannot be used to process data from web crawlers, social media, e-commerce, ERP, CRM and so on. More generally TDengine is not a suitable storage engine for non-time-series data. This section makes a more detailed analysis of the applicable scenarios. + +### Characteristics and Requirements of Data Sources + +| **Data Source Characteristics and Requirements** | **Not Applicable** | **Might Be Applicable** | **Very Applicable** | **Description** | +| -------------------------------------------------------- | ------------------ | ----------------------- | ------------------- | :----------------------------------------------------------- | +| A massive amount of total data | | | √ | TDengine provides excellent scale-out functions in terms of capacity, and has a storage structure with matching high compression ratio to achieve the best storage efficiency in the industry.| +| Data input velocity is extremely high | | | √ | TDengine's performance is much higher than that of other similar products. It can continuously process larger amounts of input data in the same hardware environment, and provides a performance evaluation tool that can easily run in the user environment. | +| A huge number of data sources | | | √ | TDengine is optimized specifically for a huge number of data sources. It is especially suitable for efficiently ingesting, writing and querying data from billions of data sources. | + +### System Architecture Requirements + +| **System Architecture Requirements** | **Not Applicable** | **Might Be Applicable** | **Very Applicable** | **Description** | +| ------------------------------------------------- | ------------------ | ----------------------- | ------------------- | ------------------------------------------------------------ | +| A simple and reliable system architecture | | | √ | TDengine's system architecture is very simple and reliable, with its own message queue, cache, stream computing, monitoring and other functions. There is no need to integrate any additional third-party products. | +| Fault-tolerance and high-reliability | | | √ | TDengine has cluster functions to automatically provide high-reliability and high-availability functions such as fault tolerance and disaster recovery. | +| Standardization support | | | √ | TDengine supports standard SQL and provides SQL extensions for time-series data analysis. | + +### System Function Requirements + +| **System Function Requirements** | **Not Applicable** | **Might Be Applicable** | **Very Applicable** | **Description** | +| ------------------------------------------------- | ------------------ | ----------------------- | ------------------- | ------------------------------------------------------------ | +| Complete data processing algorithms built-in | | √ | | While TDengine implements various general data processing algorithms, industry specific algorithms and special types of processing will need to be implemented at the application level.| +| A large number of crosstab queries | | √ | | This type of processing is better handled by general purpose relational database systems but TDengine can work in concert with relational database systems to provide more complete solutions. | + +### System Performance Requirements + +| **System Performance Requirements** | **Not Applicable** | **Might Be Applicable** | **Very Applicable** | **Description** | +| ------------------------------------------------- | ------------------ | ----------------------- | ------------------- | ------------------------------------------------------------ | +| Very large total processing capacity | | | √ | TDengine’s cluster functions can easily improve processing capacity via multi-server coordination. | +| Extremely high-speed data processing | | | √ | TDengine’s storage and data processing are optimized for IoT, and can process data many times faster than similar products.| +| Extremely fast processing of high resolution data | | | √ | TDengine has achieved the same or better performance than other relational and NoSQL data processing systems. | + +### System Maintenance Requirements + +| **System Maintenance Requirements** | **Not Applicable** | **Might Be Applicable** | **Very Applicable** | **Description** | +| ------------------------------------------------- | ------------------ | ----------------------- | ------------------- | ------------------------------------------------------------ | +| Native high-reliability | | | √ | TDengine has a very robust, reliable and easily configurable system architecture to simplify routine operation. Human errors and accidents are eliminated to the greatest extent, with a streamlined experience for operators. | +| Minimize learning and maintenance costs | | | √ | In addition to being easily configurable, standard SQL support and the Taos shell for ad hoc queries makes maintenance simpler, allows reuse and reduces learning costs.| +| Abundant talent supply | √ | | | Given the above, and given the extensive training and professional services provided by TDengine, it is easy to migrate from existing solutions or create a new and lasting solution based on TDengine.| + +## Comparison with other databases + +- [Writing Performance Comparison of TDengine and InfluxDB ](https://tdengine.com/2022/02/23/4975.html) +- [Query Performance Comparison of TDengine and InfluxDB](https://tdengine.com/2022/02/24/5120.html) +- [TDengine vs InfluxDB、OpenTSDB、Cassandra、MySQL、ClickHouse](https://www.tdengine.com/downloads/TDengine_Testing_Report_en.pdf) +- [TDengine vs OpenTSDB](https://tdengine.com/2019/09/12/710.html) +- [TDengine vs Cassandra](https://tdengine.com/2019/09/12/708.html) +- [TDengine vs InfluxDB](https://tdengine.com/2019/09/12/706.html) diff --git a/docs-en/02-concept/_category_.yml b/docs/en/04-concept/_category_.yml similarity index 100% rename from docs-en/02-concept/_category_.yml rename to docs/en/04-concept/_category_.yml diff --git a/docs/en/04-concept/index.md b/docs/en/04-concept/index.md new file mode 100644 index 0000000000000000000000000000000000000000..850f705146c4829db579f14be1a686ef9052f678 --- /dev/null +++ b/docs/en/04-concept/index.md @@ -0,0 +1,170 @@ +--- +title: Concepts +--- + +In order to explain the basic concepts and provide some sample code, the TDengine documentation smart meters as a typical time series use case. We assume the following: 1. Each smart meter collects three metrics i.e. current, voltage, and phase 2. There are multiple smart meters, and 3. Each meter has static attributes like location and group ID. Based on this, collected data will look similar to the following table: + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Device IDTime StampCollected MetricsTags
Device IDTime StampcurrentvoltagephaselocationgroupId
d1001153854868500010.32190.31California.SanFrancisco2
d1002153854868400010.22200.23California.SanFrancisco3
d1003153854868650011.52210.35California.LosAngeles3
d1004153854868550013.42230.29California.LosAngeles2
d1001153854869500012.62180.33California.SanFrancisco2
d1004153854869660011.82210.28California.LosAngeles2
d1002153854869665010.32180.25California.SanFrancisco3
d1001153854869680012.32210.31California.SanFrancisco2
+Table 1: Smart meter example data +
+ +Each row contains the device ID, time stamp, collected metrics (current, voltage, phase as above), and static tags (location and groupId in Table 1) associated with the devices. Each smart meter generates a row (measurement) in a pre-defined time interval or triggered by an external event. The device produces a sequence of measurements with associated time stamps. + +## Metric + +Metric refers to the physical quantity collected by sensors, equipment or other types of data collection devices, such as current, voltage, temperature, pressure, GPS position, etc., which change with time, and the data type can be integer, float, Boolean, or strings. As time goes by, the amount of collected metric data stored increases. + +## Label/Tag + +Label/Tag refers to the static properties of sensors, equipment or other types of data collection devices, which do not change with time, such as device model, color, fixed location of the device, etc. The data type can be any type. Although static, TDengine allows users to add, delete or update tag values at any time. Unlike the collected metric data, the amount of tag data stored does not change over time. + +## Data Collection Point + +Data Collection Point (DCP) refers to hardware or software that collects metrics based on preset time periods or triggered by events. A data collection point can collect one or multiple metrics, but these metrics are collected at the same time and have the same time stamp. For some complex equipment, there are often multiple data collection points, and the sampling rate of each collection point may be different, and fully independent. For example, for a car, there could be a data collection point to collect GPS position metrics, a data collection point to collect engine status metrics, and a data collection point to collect the environment metrics inside the car. So in this example the car would have three data collection points. + +## Table + +Since time-series data is most likely to be structured data, TDengine adopts the traditional relational database model to process them with a short learning curve. You need to create a database, create tables, then insert data points and execute queries to explore the data. + +To make full use of time-series data characteristics, TDengine adopts a strategy of "**One Table for One Data Collection Point**". TDengine requires the user to create a table for each data collection point (DCP) to store collected time-series data. For example, if there are over 10 million smart meters, it means 10 million tables should be created. For the table above, 4 tables should be created for devices D1001, D1002, D1003, and D1004 to store the data collected. This design has several benefits: + +1. Since the metric data from different DCP are fully independent, the data source of each DCP is unique, and a table has only one writer. In this way, data points can be written in a lock-free manner, and the writing speed can be greatly improved. +2. For a DCP, the metric data generated by DCP is ordered by timestamp, so the write operation can be implemented by simple appending, which further greatly improves the data writing speed. +3. The metric data from a DCP is continuously stored, block by block. If you read data for a period of time, it can greatly reduce random read operations and improve read and query performance by orders of magnitude. +4. Inside a data block for a DCP, columnar storage is used, and different compression algorithms are used for different data types. Metrics generally don't vary as significantly between themselves over a time range as compared to other metrics, which allows for a higher compression rate. + +If the metric data of multiple DCPs are traditionally written into a single table, due to uncontrollable network delays, the timing of the data from different DCPs arriving at the server cannot be guaranteed, write operations must be protected by locks, and metric data from one DCP cannot be guaranteed to be continuously stored together. **One table for one data collection point can ensure the best performance of insert and query of a single data collection point to the greatest possible extent.** + +TDengine suggests using DCP ID as the table name (like D1001 in the above table). Each DCP may collect one or multiple metrics (like the current, voltage, phase as above). Each metric has a corresponding column in the table. The data type for a column can be int, float, string and others. In addition, the first column in the table must be a timestamp. TDengine uses the time stamp as the index, and won’t build the index on any metrics stored. Column wise storage is used. + +## Super Table (STable) + +The design of one table for one data collection point will require a huge number of tables, which is difficult to manage. Furthermore, applications often need to take aggregation operations among DCPs, thus aggregation operations will become complicated. To support aggregation over multiple tables efficiently, the STable(Super Table) concept is introduced by TDengine. + +STable is a template for a type of data collection point. A STable contains a set of data collection points (tables) that have the same schema or data structure, but with different static attributes (tags). To describe a STable, in addition to defining the table structure of the metrics, it is also necessary to define the schema of its tags. The data type of tags can be int, float, string, and there can be multiple tags, which can be added, deleted, or modified afterward. If the whole system has N different types of data collection points, N STables need to be established. + +In the design of TDengine, **a table is used to represent a specific data collection point, and STable is used to represent a set of data collection points of the same type**. + +## Subtable + +When creating a table for a specific data collection point, the user can use a STable as a template and specify the tag values of this specific DCP to create it. **The table created by using a STable as the template is called subtable** in TDengine. The difference between regular table and subtable is: +1. Subtable is a table, all SQL commands applied on a regular table can be applied on subtable. +2. Subtable is a table with extensions, it has static tags (labels), and these tags can be added, deleted, and updated after it is created. But a regular table does not have tags. +3. A subtable belongs to only one STable, but a STable may have many subtables. Regular tables do not belong to a STable. +4. A regular table can not be converted into a subtable, and vice versa. + +The relationship between a STable and the subtables created based on this STable is as follows: + +1. A STable contains multiple subtables with the same metric schema but with different tag values. +2. The schema of metrics or labels cannot be adjusted through subtables, and it can only be changed via STable. Changes to the schema of a STable takes effect immediately for all associated subtables. +3. STable defines only one template and does not store any data or label information by itself. Therefore, data cannot be written to a STable, only to subtables. + +Queries can be executed on both a table (subtable) and a STable. For a query on a STable, TDengine will treat the data in all its subtables as a whole data set for processing. TDengine will first find the subtables that meet the tag filter conditions, then scan the time-series data of these subtables to perform aggregation operation, which reduces the number of data sets to be scanned which in turn greatly improves the performance of data aggregation across multiple DCPs. + +In TDengine, it is recommended to use a subtable instead of a regular table for a DCP. + +## Database + +A database is a collection of tables. TDengine allows a running instance to have multiple databases, and each database can be configured with different storage policies. Different types of DCPs often have different data characteristics, including the frequency of data collection, data retention time, the number of replications, the size of data blocks, whether data is allowed to be updated, and so on. In order for TDengine to work with maximum efficiency in various scenarios, TDengine recommends that STables with different data characteristics be created in different databases. + +In a database, there can be one or more STables, but a STable belongs to only one database. All tables owned by a STable are stored in only one database. + +## FQDN & End Point + +FQDN (Fully Qualified Domain Name) is the full domain name of a specific computer or host on the Internet. FQDN consists of two parts: hostname and domain name. For example, the FQDN of a mail server might be mail.tdengine.com. The hostname is mail, and the host is located in the domain name tdengine.com. DNS (Domain Name System) is responsible for translating FQDN into IP. For systems without DNS, it can be solved by configuring the hosts file. + +Each node of a TDengine cluster is uniquely identified by an End Point, which consists of an FQDN and a Port, such as h1.tdengine.com:6030. In this way, when the IP changes, we can still use the FQDN to dynamically find the node without changing any configuration of the cluster. In addition, FQDN is used to facilitate unified access to the same cluster from the Intranet and the Internet. + +TDengine does not recommend using an IP address to access the cluster. FQDN is recommended for cluster management. diff --git a/docs-en/03-get-started/_apt_get_install.mdx b/docs/en/05-get-started/_apt_get_install.mdx similarity index 100% rename from docs-en/03-get-started/_apt_get_install.mdx rename to docs/en/05-get-started/_apt_get_install.mdx diff --git a/docs-en/03-get-started/_category_.yml b/docs/en/05-get-started/_category_.yml similarity index 100% rename from docs-en/03-get-started/_category_.yml rename to docs/en/05-get-started/_category_.yml diff --git a/docs/en/05-get-started/_pkg_install.mdx b/docs/en/05-get-started/_pkg_install.mdx new file mode 100644 index 0000000000000000000000000000000000000000..cf10497c96ba1d777e45340b0312d97c127b6fcb --- /dev/null +++ b/docs/en/05-get-started/_pkg_install.mdx @@ -0,0 +1,17 @@ +import PkgList from "/components/PkgList"; + +It's very easy to install TDengine and would take you only a few minutes from downloading to finishing installation. + +For the convenience of users, from version 2.4.0.10, the standard server side installation package includes `taos`, `taosd`, `taosAdapter`, `taosBenchmark` and sample code. If only the `taosd` server and C/C++ connector are required, you can also choose to download the lite package. + +Three kinds of packages are provided, tar.gz, rpm and deb. Especially the tar.gz package is provided for the convenience of enterprise customers on different kinds of operating systems, it includes `taosdump` and TDinsight installation script which are normally only provided in taos-tools rpm and deb packages. + +Between two major release versions, some beta versions may be delivered for users to try some new features. + + + +For the details please refer to [Install and Uninstall](/operation/pkg-install)。 + +To see the details of versions, please refer to [Download List](https://tdengine.com/all-downloads) and [Release Notes](https://github.com/taosdata/TDengine/releases). + + diff --git a/docs/en/05-get-started/index.md b/docs/en/05-get-started/index.md new file mode 100644 index 0000000000000000000000000000000000000000..9c5a853820487c87a0c9691bb295e5c1aabe3b12 --- /dev/null +++ b/docs/en/05-get-started/index.md @@ -0,0 +1,171 @@ +--- +title: Get Started +description: 'Install TDengine from Docker image, apt-get or package, and run TDengine CLI and taosBenchmark to experience the features' +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import PkgInstall from "./\_pkg_install.mdx"; +import AptGetInstall from "./\_apt_get_install.mdx"; + +## Quick Install + +The full package of TDengine includes the server(taosd), taosAdapter for connecting with third-party systems and providing a RESTful interface, client driver(taosc), command-line program(CLI, taos) and some tools. For the current version, the server taosd and taosAdapter can only be installed and run on Linux systems. In the future taosd and taosAdapter will also be supported on Windows, macOS and other systems. The client driver taosc and TDengine CLI can be installed and run on Windows or Linux. In addition to connectors for multiple languages, TDengine also provides a [RESTful interface](/reference/rest-api) through [taosAdapter](/reference/taosadapter). Prior to version 2.4.0.0, taosAdapter did not exist and the RESTful interface was provided by the built-in HTTP service of taosd. + +TDengine supports X64/ARM64/MIPS64/Alpha64 hardware platforms, and will support ARM32, RISC-V and other CPU architectures in the future. + + + +If docker is already installed on your computer, execute the following command: + +```shell +docker run -d -p 6030-6049:6030-6049 -p 6030-6049:6030-6049/udp tdengine/tdengine +``` + +Make sure the container is running + +```shell +docker ps +``` + +Enter into container and execute bash + +```shell +docker exec -it bash +``` + +Then you can execute the Linux commands and access TDengine. + +For detailed steps, please visit [Experience TDengine via Docker](/train-faq/docker)。 + +:::info +Starting from 2.4.0.10，besides taosd，TDengine docker image includes: taos，taosAdapter，taosdump，taosBenchmark，TDinsight, scripts and sample code. Once the TDengine container is started，it will start both taosAdapter and taosd automatically to support RESTful interface. + +::: + + + + + + + + + + +If you like to check the source code, build the package by yourself or contribute to the project, please check [TDengine GitHub Repository](https://github.com/taosdata/TDengine) + + + + +## Quick Launch + +After installation, you can launch the TDengine service by the 'systemctl' command to start 'taosd'. + +```bash +systemctl start taosd +``` + +Check if taosd is running： + +```bash +systemctl status taosd +``` + +If everything is fine, you can run TDengine command-line interface `taos` to access TDengine and test it out yourself. + +:::info + +- systemctl requires _root_ privileges，if you are not _root_ ，please add sudo before the command. +- To get feedback and keep improving the product, TDengine is collecting some basic usage information, but you can turn it off by setting telemetryReporting to 0 in configuration file taos.cfg. +- TDengine uses FQDN (usually hostname）as the ID for a node. To make the system work, you need to configure the FQDN for the server running taosd, and configure the DNS service or hosts file on the the machine where the application or TDengine CLI runs to ensure that the FQDN can be resolved. +- `systemctl stop taosd` won't stop the server right away, it will wait until all the data in memory are flushed to disk. It may takes time depending on the cache size. + +TDengine supports the installation on system which runs [`systemd`](https://en.wikipedia.org/wiki/Systemd) for process management，use `which systemctl` to check if the system has `systemd` installed: + +```bash +which systemctl +``` + +If the system does not have `systemd`，you can start TDengine manually by executing `/usr/local/taos/bin/taosd` + +:::note + +## Command Line Interface + +To manage the TDengine running instance，or execute ad-hoc queries, TDengine provides a Command Line Interface (hereinafter referred to as TDengine CLI) taos. To enter into the interactive CLI，execute `taos` on a Linux terminal where TDengine is installed. + +```bash +taos +``` + +If it connects to the TDengine server successfully, it will print out the version and welcome message. If it fails, it will print out the error message, please check [FAQ](/train-faq/faq) for trouble shooting connection issue. TDengine CLI's prompt is： + +```cmd +taos> +``` + +Inside TDengine CLI，you can execute SQL commands to create/drop database/table, and run queries. The SQL command must be ended with a semicolon. For example: + +```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) +``` + +Besides executing SQL commands, system administrators can check running status, add/drop user accounts and manage the running instances. TDengine CLI with client driver can be installed and run on either Linux or Windows machines. For more details on CLI, please [check here](../reference/taos-shell/). + +## Experience the blazing fast speed + +After TDengine server is running，execute `taosBenchmark` (previously named taosdemo) from a Linux terminal： + +```bash +taosBenchmark +``` + +This command will create a super table "meters" under database "test". Under "meters", 10000 tables are created with names from "d0" to "d9999". Each table has 10000 rows and each row has four columns (ts, current, voltage, phase). Time stamp is starting from "2017-07-14 10:40:00 000" to "2017-07-14 10:40:09 999". Each table has tags "location" and "groupId". groupId is set 1 to 10 randomly, and location is set to "California.SanFrancisco" or "California.SanDiego". + +This command will insert 100 million rows into the database quickly. Time to insert depends on the hardware configuration, it only takes a dozen seconds for a regular PC server. + +taosBenchmark provides command-line options and a configuration file to customize the scenarios, like number of tables, number of rows per table, number of columns and more. Please execute `taosBenchmark --help` to list them. For details on running taosBenchmark, please check [reference for taosBenchmark](/reference/taosbenchmark) + +## Experience query speed + +After using taosBenchmark to insert a number of rows data, you can execute queries from TDengine CLI to experience the lightning fast query speed. + +query the total number of rows under super table "meters"： + +```sql +taos> select count(*) from test.meters; +``` + +query the average, maximum, minimum of 100 million rows: + +```sql +taos> select avg(current), max(voltage), min(phase) from test.meters; +``` + +query the total number of rows with location="California.SanFrancisco": + +```sql +taos> select count(*) from test.meters where location="California.SanFrancisco"; +``` + +query the average, maximum, minimum of all rows with groupId=10: + +```sql +taos> select avg(current), max(voltage), min(phase) from test.meters where groupId=10; +``` + +query the average, maximum, minimum for table d10 in 10 seconds time interval： + +```sql +taos> select avg(current), max(voltage), min(phase) from test.d10 interval(10s); +``` diff --git a/docs-en/04-develop/01-connect/_category_.yml b/docs/en/07-develop/01-connect/_category_.yml similarity index 100% rename from docs-en/04-develop/01-connect/_category_.yml rename to docs/en/07-develop/01-connect/_category_.yml diff --git a/docs/en/07-develop/01-connect/_connect_c.mdx b/docs/en/07-develop/01-connect/_connect_c.mdx new file mode 100644 index 0000000000000000000000000000000000000000..4d13d80e085956a7ceccdc404b7106620b22c25e --- /dev/null +++ b/docs/en/07-develop/01-connect/_connect_c.mdx @@ -0,0 +1,3 @@ +```c title="Native Connection" +{{#include docs/examples/c/connect_example.c}} +``` diff --git a/docs/en/07-develop/01-connect/_connect_cs.mdx b/docs/en/07-develop/01-connect/_connect_cs.mdx new file mode 100644 index 0000000000000000000000000000000000000000..f8d8e519fde7fc6d0954bbfe865155221c0b0595 --- /dev/null +++ b/docs/en/07-develop/01-connect/_connect_cs.mdx @@ -0,0 +1,8 @@ +```csharp title="Native Connection" +{{#include docs/examples/csharp/ConnectExample.cs}} +``` + +:::info +C# connector supports only native connection for now. + +::: diff --git a/docs/en/07-develop/01-connect/_connect_go.mdx b/docs/en/07-develop/01-connect/_connect_go.mdx new file mode 100644 index 0000000000000000000000000000000000000000..6f742ea0bcf027de6c97132167d4de65e2cbee8a --- /dev/null +++ b/docs/en/07-develop/01-connect/_connect_go.mdx @@ -0,0 +1,17 @@ +#### Unified Database Access Interface + +```go title="Native Connection" +{{#include docs/examples/go/connect/cgoexample/main.go}} +``` + +```go title="REST Connection" +{{#include docs/examples/go/connect/restexample/main.go}} +``` + +#### Advanced Features + +The af package of driver-go can also be used to establish connection, with this way some advanced features of TDengine, like parameter binding and subscription, can be used. + +```go title="Establish native connection using af package" +{{#include docs/examples/go/connect/afconn/main.go}} +``` diff --git a/docs/en/07-develop/01-connect/_connect_java.mdx b/docs/en/07-develop/01-connect/_connect_java.mdx new file mode 100644 index 0000000000000000000000000000000000000000..880d2aa3e489566203fa0f4b8379feb653a98f73 --- /dev/null +++ b/docs/en/07-develop/01-connect/_connect_java.mdx @@ -0,0 +1,15 @@ +```java title="Native Connection" +{{#include docs/examples/java/src/main/java/com/taos/example/JNIConnectExample.java}} +``` + +```java title="REST Connection" +{{#include docs/examples/java/src/main/java/com/taos/example/RESTConnectExample.java:main}} +``` + +When using REST connection, the feature of bulk pulling can be enabled if the size of resulting data set is huge. + +```java title="Enable Bulk Pulling" {4} +{{#include docs/examples/java/src/main/java/com/taos/example/WSConnectExample.java:main}} +``` + +More configuration about connection，please refer to [Java Connector](/reference/connector/java) diff --git a/docs/en/07-develop/01-connect/_connect_node.mdx b/docs/en/07-develop/01-connect/_connect_node.mdx new file mode 100644 index 0000000000000000000000000000000000000000..943677b36be22f73c970d5b1f4228ff757b0a62e --- /dev/null +++ b/docs/en/07-develop/01-connect/_connect_node.mdx @@ -0,0 +1,7 @@ +```js title="Native Connection" +{{#include docs/examples/node/nativeexample/connect.js}} +``` + +```js title="REST Connection" +{{#include docs/examples/node/restexample/connect.js}} +``` diff --git a/docs/en/07-develop/01-connect/_connect_python.mdx b/docs/en/07-develop/01-connect/_connect_python.mdx new file mode 100644 index 0000000000000000000000000000000000000000..60b454d52f3977d1feac9e745da984db83a38668 --- /dev/null +++ b/docs/en/07-develop/01-connect/_connect_python.mdx @@ -0,0 +1,3 @@ +```python title="Native Connection" +{{#include docs/examples/python/connect_example.py}} +``` diff --git a/docs/en/07-develop/01-connect/_connect_r.mdx b/docs/en/07-develop/01-connect/_connect_r.mdx new file mode 100644 index 0000000000000000000000000000000000000000..e2d7f631d2c467937589bd00271a7decd036506d --- /dev/null +++ b/docs/en/07-develop/01-connect/_connect_r.mdx @@ -0,0 +1,3 @@ +```r title="Native Connection" +{{#include docs/examples/R/connect_native.r:demo}} +``` diff --git a/docs/en/07-develop/01-connect/_connect_rust.mdx b/docs/en/07-develop/01-connect/_connect_rust.mdx new file mode 100644 index 0000000000000000000000000000000000000000..80ac1f4ff4a8174acc4c2f6af11b31f027ece602 --- /dev/null +++ b/docs/en/07-develop/01-connect/_connect_rust.mdx @@ -0,0 +1,8 @@ +```rust title="Native Connection/REST Connection" +{{#include docs/examples/rust/nativeexample/examples/connect.rs}} +``` + +:::note +For Rust connector, the connection depends on the feature being used. If "rest" feature is enabled, then only the implementation for "rest" is compiled and packaged. + +::: diff --git a/docs/en/07-develop/01-connect/index.md b/docs/en/07-develop/01-connect/index.md new file mode 100644 index 0000000000000000000000000000000000000000..720f8e2384c565d5494ce7d84d531188dae96fe0 --- /dev/null +++ b/docs/en/07-develop/01-connect/index.md @@ -0,0 +1,280 @@ +--- +sidebar_label: Connect +title: Connect +description: "This document explains how to establish connections to TDengine, and briefly introduces how to install and use TDengine connectors." +--- + +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 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"; + +Any application programs running on any kind of platform can access TDengine through the REST API provided by TDengine. For details, please refer to [REST API](/reference/rest-api/). Additionally, application programs can use the connectors of multiple programming languages including C/C++, Java, Python, Go, Node.js, C#, Rust to access TDengine. This chapter describes how to establish a connection to TDengine and briefly introduces how to install and use connectors. TDengine community also provides connectors in LUA and PHP languages. For details about the connectors, please refer to [Connectors](/reference/connector/). + +## Establish Connection + +There are two ways for a connector to establish connections to TDengine: + +1. Connection through the REST API provided by the taosAdapter component, this way is called "REST connection" hereinafter. +2. Connection through the TDengine client driver (taosc), this way is called "Native connection" hereinafter. + +Key differences： + +1. The TDengine client driver (taosc) has the highest performance with all the features of TDengine like [Parameter Binding](/reference/connector/cpp#parameter-binding-api), [Subscription](/reference/connector/cpp#subscription-and-consumption-api), etc. +2. The TDengine client driver (taosc) is not supported across all platforms, and applications built on taosc may need to be modified when updating taosc to newer versions. +3. The REST connection is more accessible with cross-platform support, however it results in a 30% performance downgrade. + +## Install Client Driver taosc + +If you are choosing to use the native connection and the the application is not on the same host as TDengine server, the TDengine client driver taosc needs to be installed on the application host. If choosing to use the REST connection or the application is on the same host as TDengine server, this step can be skipped. It's better to use same version of taosc as the TDengine server. + +### Install + + + + + + + + + + +### Verify + +After the above installation and configuration are done and making sure TDengine service is already started and in service, the TDengine command-line interface `taos` can be launched to access TDengine. + + + + + + + + + + +## Install Connectors + + + + +If `maven` is used to manage the projects, what needs to be done is only adding below dependency in `pom.xml`. + +```xml + + com.taosdata.jdbc + taos-jdbcdriver + 2.0.38 + +``` + + + + +Install from PyPI using `pip`: + +``` +pip install taospy +``` + +Install from Git URL: + +``` +pip install git+https://github.com/taosdata/taos-connector-python.git +``` + + + + +Just need to add `driver-go` dependency in `go.mod` . + +```go-mod title=go.mod +module goexample + +go 1.17 + +require github.com/taosdata/driver-go/v2 develop +``` + +:::note +`driver-go` uses `cgo` to wrap the APIs provided by taosc, while `cgo` needs `gcc` to compile source code in C language, so please make sure you have proper `gcc` on your system. + +::: + + + + +Just need to add `libtaos` dependency in `Cargo.toml`. + +```toml title=Cargo.toml +[dependencies] +libtaos = { version = "0.4.2"} +``` + +:::info +Rust connector uses different features to distinguish the way to establish connection. To establish REST connection, please enable `rest` feature. + +```toml +libtaos = { version = "*", features = ["rest"] } +``` + +::: + + + + +Node.js connector provides different ways of establishing connections by providing different packages. + +1. Install Node.js Native Connector + +``` +npm i td2.0-connector +``` + +:::note +It's recommend to use Node whose version is between `node-v12.8.0` and `node-v13.0.0`. +::: + +2. Install Node.js REST Connector + +``` +npm i td2.0-rest-connector +``` + + + + +Just need to add the reference to [TDengine.Connector](https://www.nuget.org/packages/TDengine.Connector/) in the project configuration file. + +```xml title=csharp.csproj {12} + + + + Exe + net6.0 + enable + enable + TDengineExample.AsyncQueryExample + + + + + + + +``` + +Or add by `dotnet` command. + +``` +dotnet add package TDengine.Connector +``` + +:::note +The sample code below are based on dotnet6.0, they may need to be adjusted if your dotnet version is not exactly same. + +::: + + + + +1. Download [taos-jdbcdriver-version-dist.jar](https://repo1.maven.org/maven2/com/taosdata/jdbc/taos-jdbcdriver/2.0.38/). +2. Install the dependency package `RJDBC`： + +```R +install.packages("RJDBC") +``` + + + + +If the client driver (taosc) is already installed, then the C connector is already available. +
+ + + + +**Download Source Code Package and Unzip：** + +```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 +``` + +> Version number `v1.0.2` is only for example, it can be replaced to any newer version, please check available version from [TDengine PHP Connector Releases](https://github.com/Yurunsoft/php-tdengine/releases). + +**Non-Swoole Environment：** + +```shell +phpize && ./configure && make -j && make install +``` + +**Specify TDengine Location：** + +```shell +phpize && ./configure --with-tdengine-dir=/usr/local/Cellar/tdengine/2.4.0.0 && make -j && make install +``` + +> `--with-tdengine-dir=` is followed by the TDengine installation location. +> This way is useful in case TDengine location can't be found automatically or macOS. + +**Swoole Environment：** + +```shell +phpize && ./configure --enable-swoole && make -j && make install +``` + +**Enable The Extension:** + +Option One: Add `extension=tdengine` in `php.ini` + +Option Two: Specify the extension on CLI `php -d extension=tdengine test.php` + + + + +## Establish Connection + +Prior to establishing connection, please make sure TDengine is already running and accessible. The following sample code assumes TDengine is running on the same host as the client program, with FQDN configured to "localhost" and serverPort configured to "6030". + + + + + + + + + + + + + + + + + + + + + + + + + + + + +:::tip +If the connection fails, in most cases it's caused by improper configuration for FQDN or firewall. Please refer to the section "Unable to establish connection" in [FAQ](https://docs.taosdata.com/train-faq/faq). + +::: diff --git a/docs-en/04-develop/02-model/_category_.yml b/docs/en/07-develop/02-model/_category_.yml similarity index 100% rename from docs-en/04-develop/02-model/_category_.yml rename to docs/en/07-develop/02-model/_category_.yml diff --git a/docs/en/07-develop/02-model/index.mdx b/docs/en/07-develop/02-model/index.mdx new file mode 100644 index 0000000000000000000000000000000000000000..e0378cc77ca28a1a82ef6a52fa1f74d6cd580a01 --- /dev/null +++ b/docs/en/07-develop/02-model/index.mdx @@ -0,0 +1,93 @@ +--- +title: Data Model +--- + +The data model employed by TDengine is similar to that of a relational database. You have to create databases and tables. You must design the data model based on your own business and application requirements. You should design the STable (an abbreviation for super table) schema to fit your data. This chapter will explain the big picture without getting into syntactical details. + +## Create Database + +The [characteristics of time-series data](https://www.taosdata.com/blog/2019/07/09/86.html) from different data collection points may be different. Characteristics include collection frequency, retention policy and others which determine how you create and configure the database. For e.g. days to keep, number of replicas, data block size, whether data updates are allowed and other configurable parameters would be determined by the characteristics of your data and your business requirements. For TDengine to operate with the best performance, we strongly recommend that you create and configure different databases for data with different characteristics. This allows you, for example, to set up different storage and retention policies. When creating a database, there are a lot of parameters that can be configured such as, the days to keep data, the number of replicas, the number of memory blocks, time precision, the minimum and maximum number of rows in each data block, whether compression is enabled, the time range of the data in single data file and so on. Below is an example of the SQL statement to create a database. + +```sql +CREATE DATABASE power KEEP 365 DAYS 10 BLOCKS 6 UPDATE 1; +``` + +In the above SQL statement: +- a database named "power" will be created +- the data in it will be kept for 365 days, which means that data older than 365 days will be deleted automatically +- a new data file will be created every 10 days +- the number of memory blocks is 6 +- data is allowed to be updated + +For more details please refer to [Database](/taos-sql/database). + +After creating a database, the current database in use can be switched using SQL command `USE`. For example the SQL statement below switches the current database to `power`. Without the current database specified, table name must be preceded with the corresponding database name. + +```sql +USE power; +``` + +:::note + +- Any table or STable must belong to a database. To create a table or STable, the database it belongs to must be ready. +- JOIN operations can't be performed on tables from two different databases. +- Timestamp needs to be specified when inserting rows or querying historical rows. + +::: + +## Create STable + +In a time-series application, there may be multiple kinds of data collection points. For example, in the electrical power system there are meters, transformers, bus bars, switches, etc. For easy and efficient aggregation of multiple tables, one STable needs to be created for each kind of data collection point. For example, for the meters in [table 1](/concept/#model_table1), the SQL statement below can be used to create the super table. + +```sql +CREATE STable meters (ts timestamp, current float, voltage int, phase float) TAGS (location binary(64), groupId int); +``` + +:::note +If you are using versions prior to 2.0.15, the `STable` keyword needs to be replaced with `TABLE`. + +::: + +Similar to creating a regular table, when creating a STable, the name and schema need to be provided. In the STable schema, the first column must always be a timestamp (like ts in the example), and the other columns (like current, voltage and phase in the example) are the data collected. The remaining columns can [contain data of type](/taos-sql/data-type/) integer, float, double, string etc. In addition, the schema for tags, like location and groupId in the example, must be provided. The tag type can be integer, float, string, etc. Tags are essentially the static properties of a data collection point. For example, properties like the location, device type, device group ID, manager ID are tags. Tags in the schema can be added, removed or updated. Please refer to [STable](/taos-sql/stable) for more details. + +For each kind of data collection point, a corresponding STable must be created. There may be many STables in an application. For electrical power system, we need to create a STable respectively for meters, transformers, busbars, switches. There may be multiple kinds of data collection points on a single device, for example there may be one data collection point for electrical data like current and voltage and another data collection point for environmental data like temperature, humidity and wind direction. Multiple STables are required for these kinds of devices. + +At most 4096 (or 1024 prior to version 2.1.7.0) columns are allowed in a STable. If there are more than 4096 of metrics to be collected for a data collection point, multiple STables are required. There can be multiple databases in a system, while one or more STables can exist in a database. + +## Create Table + +A specific table needs to be created for each data collection point. Similar to RDBMS, table name and schema are required to create a table. Additionally, one or more tags can be created for each table. To create a table, a STable needs to be used as template and the values need to be specified for the tags. For example, for the meters in [Table 1](/tdinternal/arch#model_table1), the table can be created using below SQL statement. + +```sql +CREATE TABLE d1001 USING meters TAGS ("California.SanFrancisco", 2); +``` + +In the above SQL statement, "d1001" is the table name, "meters" is the STable name, followed by the value of tag "Location" and the value of tag "groupId", which are "California.SanFrancisco" and "2" respectively in the example. The tag values can be updated after the table is created. Please refer to [Tables](/taos-sql/table) for details. + +In the TDengine system, it's recommended to create a table for a data collection point via STable. A table created via STable is called subtable in some parts of the TDengine documentation. All SQL commands applied on regular tables can be applied on subtables. + +:::warning +It's not recommended to create a table in a database while using a STable from another database as template. + +:::tip +It's suggested to use the globally unique ID of a data collection point as the table name. For example the device serial number could be used as a unique ID. If a unique ID doesn't exist, multiple IDs that are not globally unique can be combined to form a globally unique ID. It's not recommended to use a globally unique ID as tag value. + +## Create Table Automatically + +In some circumstances, it's unknown whether the table already exists when inserting rows. The table can be created automatically using the SQL statement below, and nothing will happen if the table already exists. + +```sql +INSERT INTO d1001 USING meters TAGS ("California.SanFrancisco", 2) VALUES (now, 10.2, 219, 0.32); +``` + +In the above SQL statement, a row with value `(now, 10.2, 219, 0.32)` will be inserted into table "d1001". If table "d1001" doesn't exist, it will be created automatically using STable "meters" as template with tag value `"California.SanFrancisco", 2`. + +For more details please refer to [Create Table Automatically](/taos-sql/insert#automatically-create-table-when-inserting). + +## Single Column vs Multiple Column + +A multiple columns data model is supported in TDengine. As long as multiple metrics are collected by the same data collection point at the same time, i.e. the timestamps are identical, these metrics can be put in a single STable as columns. + +However, there is another kind of design, i.e. single column data model in which a table is created for each metric. This means that a STable is required for each kind of metric. For example in a single column model, 3 STables would be required for current, voltage and phase. + +It's recommended to use a multiple column data model as much as possible because insert and query performance is higher. In some cases, however, the collected metrics may vary frequently and so the corresponding STable schema needs to be changed frequently too. In such cases, it's more convenient to use single column data model. diff --git a/docs/en/07-develop/03-insert-data/01-sql-writing.mdx b/docs/en/07-develop/03-insert-data/01-sql-writing.mdx new file mode 100644 index 0000000000000000000000000000000000000000..d8c4453f409dfaf1db1ec154e9ba35f8db74862e --- /dev/null +++ b/docs/en/07-develop/03-insert-data/01-sql-writing.mdx @@ -0,0 +1,130 @@ +--- +sidebar_label: Insert Using SQL +title: Insert Using 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"; + +## Introduction + +Application programs can execute `INSERT` statement through connectors to insert rows. The TDengine CLI can also be used to manually insert data. + +### Insert Single Row + +The below SQL statement is used to insert one row into table "d1001". + +```sql +INSERT INTO d1001 VALUES (1538548685000, 10.3, 219, 0.31); +``` + +### Insert Multiple Rows + +Multiple rows can be inserted in a single SQL statement. The example below inserts 2 rows into table "d1001". + +```sql +INSERT INTO d1001 VALUES (1538548684000, 10.2, 220, 0.23) (1538548696650, 10.3, 218, 0.25); +``` + +### Insert into Multiple Tables + +Data can be inserted into multiple tables in the same SQL statement. The example below inserts 2 rows into table "d1001" and 1 row into table "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); +``` + +For more details about `INSERT` please refer to [INSERT](/taos-sql/insert). + +:::info + +- Inserting in batches can improve performance. Normally, the higher the batch size, the better the performance. Please note that a single row can't exceed 48K bytes and each SQL statement can't exceed 1MB. +- Inserting with multiple threads can also improve performance. However, depending on the system resources on the application side and the server side, when the number of inserting threads grows beyond a specific point the performance may drop instead of improving. The proper number of threads needs to be tested in a specific environment to find the best number. + +::: + +:::warning + +- If the timestamp for the row to be inserted already exists in the table, the behavior depends on the value of parameter `UPDATE`. If it's set to 0 (the default value), the row will be discarded. If it's set to 1, the new values will override the old values for the same row. +- The timestamp to be inserted must be newer than the timestamp of subtracting current time by the parameter `KEEP`. If `KEEP` is set to 3650 days, then the data older than 3650 days ago can't be inserted. The timestamp to be inserted can't be newer than the timestamp of current time plus parameter `DAYS`. If `DAYS` is set to 2, the data newer than 2 days later can't be inserted. + +::: + +## Examples + +### Insert Using SQL + + + + + + + + + + + + + + + + + + + + + + + + + +:::note + +1. With either native connection or REST connection, the above samples can work well. +2. Please note that `use db` can't be used with a REST connection because REST connections are stateless, so in the samples `dbName.tbName` is used to specify the table name. + +::: + +### Insert with Parameter Binding + +TDengine also provides API support for parameter binding. Similar to MySQL, only `?` can be used in these APIs to represent the parameters to bind. From version 2.1.1.0 and 2.1.2.0, parameter binding support for inserting data has improved significantly to improve the insert performance by avoiding the cost of parsing SQL statements. + +Parameter binding is available only with native connection. + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/07-develop/03-insert-data/02-influxdb-line.mdx b/docs/en/07-develop/03-insert-data/02-influxdb-line.mdx new file mode 100644 index 0000000000000000000000000000000000000000..be46ebf0c97a29b57c1b57eb8ea5c9394f85b93a --- /dev/null +++ b/docs/en/07-develop/03-insert-data/02-influxdb-line.mdx @@ -0,0 +1,70 @@ +--- +sidebar_label: InfluxDB Line Protocol +title: InfluxDB Line Protocol +--- + +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"; + +## Introduction + +In the InfluxDB Line protocol format, a single line of text is used to represent one row of data. Each line contains 4 parts as shown below. + +``` +measurement,tag_set field_set timestamp +``` + +- `measurement` will be used as the name of the STable +- `tag_set` will be used as tags, with format like `=,=` +- `field_set`will be used as data columns, with format like `=,=` +- `timestamp` is the primary key timestamp corresponding to this row of data + +For example: + +``` +meters,location=California.LoSangeles,groupid=2 current=13.4,voltage=223,phase=0.29 1648432611249500 +``` + +:::note + +- All the data in `tag_set` will be converted to nchar type automatically . +- Each data in `field_set` must be self-descriptive for its data type. For example 1.2f32 means a value 1.2 of float type. Without the "f" type suffix, it will be treated as type double. +- Multiple kinds of precision can be used for the `timestamp` field. Time precision can be from nanosecond (ns) to hour (h). + +::: + +For more details please refer to [InfluxDB Line Protocol](https://docs.influxdata.com/influxdb/v2.0/reference/syntax/line-protocol/) and [TDengine Schemaless](/reference/schemaless/#Schemaless-Line-Protocol) + + +## Examples + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/07-develop/03-insert-data/03-opentsdb-telnet.mdx b/docs/en/07-develop/03-insert-data/03-opentsdb-telnet.mdx new file mode 100644 index 0000000000000000000000000000000000000000..18a695cda8efbef075451ff53e542d9e69c58e0b --- /dev/null +++ b/docs/en/07-develop/03-insert-data/03-opentsdb-telnet.mdx @@ -0,0 +1,84 @@ +--- +sidebar_label: OpenTSDB Line Protocol +title: OpenTSDB Line Protocol +--- + +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"; + +## Introduction + +A single line of text is used in OpenTSDB line protocol to represent one row of data. OpenTSDB employs a single column data model, so each line can only contain a single data column. There can be multiple tags. Each line contains 4 parts as below: + +``` + =[ =] +``` + +- `metric` will be used as the STable name. +- `timestamp` is the timestamp of current row of data. The time precision will be determined automatically based on the length of the timestamp. Second and millisecond time precision are supported. +- `value` is a metric which must be a numeric value, the corresponding column name is "value". +- The last part is the tag set separated by spaces, all tags will be converted to nchar type automatically. + +For example: + +```txt +meters.current 1648432611250 11.3 location=California.LoSangeles groupid=3 +``` + +Please refer to [OpenTSDB Telnet API](http://opentsdb.net/docs/build/html/api_telnet/put.html) for more details. + +## Examples + + + + + + + + + + + + + + + + + + + + + + + + + +2 STables will be created automatically and each STable has 4 rows of data in the above sample code. + +```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 | California.LoSangeles | + t_0e7bcfa21a02331c06764f275... | 2022-03-28 09:56:51.250 | 11.300000000 | 3 | California.LoSangeles | + t_7e7b26dd860280242c6492a16... | 2022-03-28 09:56:51.249 | 10.300000000 | 2 | California.SanFrancisco | + t_7e7b26dd860280242c6492a16... | 2022-03-28 09:56:51.250 | 12.600000000 | 2 | California.SanFrancisco | +Query OK, 4 row(s) in set (0.005399s) +``` diff --git a/docs/en/07-develop/03-insert-data/04-opentsdb-json.mdx b/docs/en/07-develop/03-insert-data/04-opentsdb-json.mdx new file mode 100644 index 0000000000000000000000000000000000000000..3a239440311c736159d6060db5e730c5e5665bcb --- /dev/null +++ b/docs/en/07-develop/03-insert-data/04-opentsdb-json.mdx @@ -0,0 +1,99 @@ +--- +sidebar_label: OpenTSDB JSON Protocol +title: OpenTSDB JSON Protocol +--- + +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"; + +## Introduction + +A JSON string is used in OpenTSDB JSON to represent one or more rows of data, for example: + +```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" + } + } +] +``` + +Similar to OpenTSDB line protocol, `metric` will be used as the STable name, `timestamp` is the timestamp to be used, `value` represents the metric collected, `tags` are the tag sets. + + +Please refer to [OpenTSDB HTTP API](http://opentsdb.net/docs/build/html/api_http/put.html) for more details. + +:::note +- In JSON protocol, strings will be converted to nchar type and numeric values will be converted to double type. +- Only data in array format is accepted and so an array must be used even if there is only one row. + +::: + +## Examples + + + + + + + + + + + + + + + + + + + + + + + + + +The above sample code will created 2 STables automatically while each STable has 2 rows of data. + +```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 | California.SanFrancisco | + 2022-03-28 09:56:51.250 | 12.600000000 | 2.000000000 | California.SanFrancisco | +Query OK, 2 row(s) in set (0.004076s) +``` diff --git a/docs/en/07-develop/03-insert-data/_c_line.mdx b/docs/en/07-develop/03-insert-data/_c_line.mdx new file mode 100644 index 0000000000000000000000000000000000000000..7f2f0d5dd8198d52dda1da34256e54a1bbb4c967 --- /dev/null +++ b/docs/en/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/en/07-develop/03-insert-data/_c_opts_json.mdx b/docs/en/07-develop/03-insert-data/_c_opts_json.mdx new file mode 100644 index 0000000000000000000000000000000000000000..34b1d8ab3c1e299c2ab2a1ad6d47f81dfaa364cc --- /dev/null +++ b/docs/en/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/en/07-develop/03-insert-data/_c_opts_telnet.mdx b/docs/en/07-develop/03-insert-data/_c_opts_telnet.mdx new file mode 100644 index 0000000000000000000000000000000000000000..6bda068d12fd0b379a5af96438029c9ae476a753 --- /dev/null +++ b/docs/en/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/en/07-develop/03-insert-data/_c_sql.mdx b/docs/en/07-develop/03-insert-data/_c_sql.mdx new file mode 100644 index 0000000000000000000000000000000000000000..4e55c3387ee1c6fe860f312afdbdad65142bf7fb --- /dev/null +++ b/docs/en/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/en/07-develop/03-insert-data/_c_stmt.mdx b/docs/en/07-develop/03-insert-data/_c_stmt.mdx new file mode 100644 index 0000000000000000000000000000000000000000..4b609efe5e942c7ecb8296e8fdbd0607f1421229 --- /dev/null +++ b/docs/en/07-develop/03-insert-data/_c_stmt.mdx @@ -0,0 +1,6 @@ +```c title=Single Row Binding +{{#include docs/examples/c/stmt_example.c}} +``` +```c title=Multiple Row Binding 72:117 +{{#include docs/examples/c/multi_bind_example.c}} +``` \ No newline at end of file diff --git a/docs/en/07-develop/03-insert-data/_category_.yml b/docs/en/07-develop/03-insert-data/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..e515d60e09ec44894e2c42f38fee74fe4286e17f --- /dev/null +++ b/docs/en/07-develop/03-insert-data/_category_.yml @@ -0,0 +1 @@ +label: Insert Data diff --git a/docs/en/07-develop/03-insert-data/_cs_line.mdx b/docs/en/07-develop/03-insert-data/_cs_line.mdx new file mode 100644 index 0000000000000000000000000000000000000000..71f46c62be3dfe7d771a35b2298e476bed353aba --- /dev/null +++ b/docs/en/07-develop/03-insert-data/_cs_line.mdx @@ -0,0 +1,3 @@ +```csharp +{{#include docs/examples/csharp/InfluxDBLineExample.cs}} +``` diff --git a/docs/en/07-develop/03-insert-data/_cs_opts_json.mdx b/docs/en/07-develop/03-insert-data/_cs_opts_json.mdx new file mode 100644 index 0000000000000000000000000000000000000000..8d80d042c984c513df5ca91813c0cd0a17b58eb5 --- /dev/null +++ b/docs/en/07-develop/03-insert-data/_cs_opts_json.mdx @@ -0,0 +1,3 @@ +```csharp +{{#include docs/examples/csharp/OptsJsonExample.cs}} +``` diff --git a/docs/en/07-develop/03-insert-data/_cs_opts_telnet.mdx b/docs/en/07-develop/03-insert-data/_cs_opts_telnet.mdx new file mode 100644 index 0000000000000000000000000000000000000000..cff32abf1feaf703971111542749fbe40152bc33 --- /dev/null +++ b/docs/en/07-develop/03-insert-data/_cs_opts_telnet.mdx @@ -0,0 +1,3 @@ +```csharp +{{#include docs/examples/csharp/OptsTelnetExample.cs}} +``` diff --git a/docs/en/07-develop/03-insert-data/_cs_sql.mdx b/docs/en/07-develop/03-insert-data/_cs_sql.mdx new file mode 100644 index 0000000000000000000000000000000000000000..1dc7bb3d1366aa3000212786756506eb5eb280e6 --- /dev/null +++ b/docs/en/07-develop/03-insert-data/_cs_sql.mdx @@ -0,0 +1,3 @@ +```csharp +{{#include docs/examples/csharp/SQLInsertExample.cs}} +``` diff --git a/docs/en/07-develop/03-insert-data/_cs_stmt.mdx b/docs/en/07-develop/03-insert-data/_cs_stmt.mdx new file mode 100644 index 0000000000000000000000000000000000000000..229c874ab9f515e7eae66890a3dfe2e59c129e86 --- /dev/null +++ b/docs/en/07-develop/03-insert-data/_cs_stmt.mdx @@ -0,0 +1,3 @@ +```csharp +{{#include docs/examples/csharp/StmtInsertExample.cs}} +``` diff --git a/docs/en/07-develop/03-insert-data/_go_line.mdx b/docs/en/07-develop/03-insert-data/_go_line.mdx new file mode 100644 index 0000000000000000000000000000000000000000..df2afc0e8720ca14e42e0e4bd7e50276cecace43 --- /dev/null +++ b/docs/en/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/en/07-develop/03-insert-data/_go_opts_json.mdx b/docs/en/07-develop/03-insert-data/_go_opts_json.mdx new file mode 100644 index 0000000000000000000000000000000000000000..362ce430515c70a3ac502e646630025d7f950612 --- /dev/null +++ b/docs/en/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/en/07-develop/03-insert-data/_go_opts_telnet.mdx b/docs/en/07-develop/03-insert-data/_go_opts_telnet.mdx new file mode 100644 index 0000000000000000000000000000000000000000..518ea4c8164ab148afff9e21b03d892cbc1bfaf8 --- /dev/null +++ b/docs/en/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/en/07-develop/03-insert-data/_go_sql.mdx b/docs/en/07-develop/03-insert-data/_go_sql.mdx new file mode 100644 index 0000000000000000000000000000000000000000..02f4d4e2ba21bc14dd67cb0443a1631b06750923 --- /dev/null +++ b/docs/en/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/en/07-develop/03-insert-data/_go_stmt.mdx b/docs/en/07-develop/03-insert-data/_go_stmt.mdx new file mode 100644 index 0000000000000000000000000000000000000000..ab519c9a806345c2f14337f62c74728da955d2e0 --- /dev/null +++ b/docs/en/07-develop/03-insert-data/_go_stmt.mdx @@ -0,0 +1,8 @@ +```go +{{#include docs/examples/go/insert/stmt/main.go}} +``` + +:::tip +`github.com/taosdata/driver-go/v2/wrapper` module in driver-go is the wrapper for C API, it can be used to insert data with parameter binding. + +::: diff --git a/docs/en/07-develop/03-insert-data/_java_line.mdx b/docs/en/07-develop/03-insert-data/_java_line.mdx new file mode 100644 index 0000000000000000000000000000000000000000..17f759d30fdb76744dc032be60ee91b6dd9f1540 --- /dev/null +++ b/docs/en/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/en/07-develop/03-insert-data/_java_opts_json.mdx b/docs/en/07-develop/03-insert-data/_java_opts_json.mdx new file mode 100644 index 0000000000000000000000000000000000000000..1fc0adc202f26c73e64da09456e7e42bdc6367f6 --- /dev/null +++ b/docs/en/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/en/07-develop/03-insert-data/_java_opts_telnet.mdx b/docs/en/07-develop/03-insert-data/_java_opts_telnet.mdx new file mode 100644 index 0000000000000000000000000000000000000000..b68f54b4e872a57f34ae6d5c3651a70812b71154 --- /dev/null +++ b/docs/en/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/en/07-develop/03-insert-data/_java_sql.mdx b/docs/en/07-develop/03-insert-data/_java_sql.mdx new file mode 100644 index 0000000000000000000000000000000000000000..636c7e00eb8846704678ef3cdd8394a99a4528f8 --- /dev/null +++ b/docs/en/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/en/07-develop/03-insert-data/_java_stmt.mdx b/docs/en/07-develop/03-insert-data/_java_stmt.mdx new file mode 100644 index 0000000000000000000000000000000000000000..2f6a33769044ef5052e633e28a9b60fdab130e88 --- /dev/null +++ b/docs/en/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/en/07-develop/03-insert-data/_js_line.mdx b/docs/en/07-develop/03-insert-data/_js_line.mdx new file mode 100644 index 0000000000000000000000000000000000000000..cc138a76bde76e779eaa1fe554ecc82c1f564e24 --- /dev/null +++ b/docs/en/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/en/07-develop/03-insert-data/_js_opts_json.mdx b/docs/en/07-develop/03-insert-data/_js_opts_json.mdx new file mode 100644 index 0000000000000000000000000000000000000000..cb3c275ce8140ed58d668bf03972a1f960bb6564 --- /dev/null +++ b/docs/en/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/en/07-develop/03-insert-data/_js_opts_telnet.mdx b/docs/en/07-develop/03-insert-data/_js_opts_telnet.mdx new file mode 100644 index 0000000000000000000000000000000000000000..db96742f31440342516134636db998af987af9fb --- /dev/null +++ b/docs/en/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/en/07-develop/03-insert-data/_js_sql.mdx b/docs/en/07-develop/03-insert-data/_js_sql.mdx new file mode 100644 index 0000000000000000000000000000000000000000..a9a12f5d2cfb31bcaefba25a82846b455dbc8671 --- /dev/null +++ b/docs/en/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/en/07-develop/03-insert-data/_js_stmt.mdx b/docs/en/07-develop/03-insert-data/_js_stmt.mdx new file mode 100644 index 0000000000000000000000000000000000000000..8df1065c4a42537c2e4c61087ad77cdde9e24a77 --- /dev/null +++ b/docs/en/07-develop/03-insert-data/_js_stmt.mdx @@ -0,0 +1,12 @@ +```js title=Single Row Binding +{{#include docs/examples/node/nativeexample/param_bind_example.js}} +``` + +```js title=Multiple Row Binding +{{#include docs/examples/node/nativeexample/multi_bind_example.js:insertData}} +``` + +:::info +Multiple row binding is better in performance than single row binding, but it can only be used with `INSERT` statement while single row binding can be used for other SQL statements besides `INSERT`. + +::: diff --git a/docs/en/07-develop/03-insert-data/_py_line.mdx b/docs/en/07-develop/03-insert-data/_py_line.mdx new file mode 100644 index 0000000000000000000000000000000000000000..85f7e32e6681c6d428a2332220194c169c421f2f --- /dev/null +++ b/docs/en/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/en/07-develop/03-insert-data/_py_opts_json.mdx b/docs/en/07-develop/03-insert-data/_py_opts_json.mdx new file mode 100644 index 0000000000000000000000000000000000000000..195c7090c02e03131c4261c57f1414a5ab1ba6b6 --- /dev/null +++ b/docs/en/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/en/07-develop/03-insert-data/_py_opts_telnet.mdx b/docs/en/07-develop/03-insert-data/_py_opts_telnet.mdx new file mode 100644 index 0000000000000000000000000000000000000000..3bae1ea57bcffe50be5b4e96a7ae8f83faed2087 --- /dev/null +++ b/docs/en/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/en/07-develop/03-insert-data/_py_sql.mdx b/docs/en/07-develop/03-insert-data/_py_sql.mdx new file mode 100644 index 0000000000000000000000000000000000000000..1557e3994b04e64c596918ee67c63e7765ebaa07 --- /dev/null +++ b/docs/en/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/en/07-develop/03-insert-data/_py_stmt.mdx b/docs/en/07-develop/03-insert-data/_py_stmt.mdx new file mode 100644 index 0000000000000000000000000000000000000000..4f7636bfb8ea920e1e879b8e59083543cf798d01 --- /dev/null +++ b/docs/en/07-develop/03-insert-data/_py_stmt.mdx @@ -0,0 +1,12 @@ +```py title=Single Row Binding +{{#include docs/examples/python/bind_param_example.py}} +``` + +```py title=Multiple Row Binding +{{#include docs/examples/python/multi_bind_example.py:bind_batch}} +``` + +:::info +Multiple row binding is better in performance than single row binding, but it can only be used with `INSERT` statement while single row binding can be used for other SQL statements besides `INSERT`. + +::: \ No newline at end of file diff --git a/docs/en/07-develop/03-insert-data/_rust_line.mdx b/docs/en/07-develop/03-insert-data/_rust_line.mdx new file mode 100644 index 0000000000000000000000000000000000000000..dbb35d76bc3517463902b642ce4a3861ae42b2f8 --- /dev/null +++ b/docs/en/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/en/07-develop/03-insert-data/_rust_opts_json.mdx b/docs/en/07-develop/03-insert-data/_rust_opts_json.mdx new file mode 100644 index 0000000000000000000000000000000000000000..cc2055510bce006491ed277a8e884b9958a5a993 --- /dev/null +++ b/docs/en/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/en/07-develop/03-insert-data/_rust_opts_telnet.mdx b/docs/en/07-develop/03-insert-data/_rust_opts_telnet.mdx new file mode 100644 index 0000000000000000000000000000000000000000..109c0c5d019e250b87e12c535e4f55c69924b4af --- /dev/null +++ b/docs/en/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/en/07-develop/03-insert-data/_rust_sql.mdx b/docs/en/07-develop/03-insert-data/_rust_sql.mdx new file mode 100644 index 0000000000000000000000000000000000000000..fb59a4826510e666457ac592328cc5ba17412c79 --- /dev/null +++ b/docs/en/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/en/07-develop/03-insert-data/_rust_stmt.mdx b/docs/en/07-develop/03-insert-data/_rust_stmt.mdx new file mode 100644 index 0000000000000000000000000000000000000000..a889b56745601158489037a590b6cf5bd80da543 --- /dev/null +++ b/docs/en/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/en/07-develop/03-insert-data/index.md b/docs/en/07-develop/03-insert-data/index.md new file mode 100644 index 0000000000000000000000000000000000000000..1a71e719a56448e4b535632e570ce8a04d2282bb --- /dev/null +++ b/docs/en/07-develop/03-insert-data/index.md @@ -0,0 +1,12 @@ +--- +title: Insert Data +--- + +TDengine supports multiple protocols of inserting data, including SQL, InfluxDB Line protocol, OpenTSDB Telnet protocol, and OpenTSDB JSON protocol. Data can be inserted row by row, or in batches. Data from one or more collection points can be inserted simultaneously. Data can be inserted with multiple threads, and out of order data and historical data can be inserted as well. InfluxDB Line protocol, OpenTSDB Telnet protocol and OpenTSDB JSON protocol are the 3 kinds of schemaless insert protocols supported by TDengine. It's not necessary to create STables and tables in advance if using schemaless protocols, and the schemas can be adjusted automatically based on the data being inserted. + +```mdx-code-block +import DocCardList from '@theme/DocCardList'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + + +``` diff --git a/docs/en/07-develop/04-query-data/_c.mdx b/docs/en/07-develop/04-query-data/_c.mdx new file mode 100644 index 0000000000000000000000000000000000000000..c51557ef2918dd9152e329c6e1937109d286b11c --- /dev/null +++ b/docs/en/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/en/07-develop/04-query-data/_c_async.mdx b/docs/en/07-develop/04-query-data/_c_async.mdx new file mode 100644 index 0000000000000000000000000000000000000000..641a53e82ddb252e1b3255799bd922158a08f229 --- /dev/null +++ b/docs/en/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/en/07-develop/04-query-data/_category_.yml b/docs/en/07-develop/04-query-data/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..809db34621a63505ceace7ba182e07c698bdbddb --- /dev/null +++ b/docs/en/07-develop/04-query-data/_category_.yml @@ -0,0 +1 @@ +label: Query Data diff --git a/docs/en/07-develop/04-query-data/_cs.mdx b/docs/en/07-develop/04-query-data/_cs.mdx new file mode 100644 index 0000000000000000000000000000000000000000..4bb582ecbfaeceac679af975e7752d1caeacb018 --- /dev/null +++ b/docs/en/07-develop/04-query-data/_cs.mdx @@ -0,0 +1,3 @@ +```csharp +{{#include docs/examples/csharp/QueryExample.cs}} +``` diff --git a/docs/en/07-develop/04-query-data/_cs_async.mdx b/docs/en/07-develop/04-query-data/_cs_async.mdx new file mode 100644 index 0000000000000000000000000000000000000000..3ecf635fd39db402d1db68de6d7336b7b2d9d8e8 --- /dev/null +++ b/docs/en/07-develop/04-query-data/_cs_async.mdx @@ -0,0 +1,3 @@ +```csharp +{{#include docs/examples/csharp/AsyncQueryExample.cs}} +``` diff --git a/docs/en/07-develop/04-query-data/_go.mdx b/docs/en/07-develop/04-query-data/_go.mdx new file mode 100644 index 0000000000000000000000000000000000000000..b43894a1ebe8aa0a261cce5f2469f2b3f8449fc4 --- /dev/null +++ b/docs/en/07-develop/04-query-data/_go.mdx @@ -0,0 +1,3 @@ +```go +{{#include docs/examples/go/query/sync/main.go}} +``` diff --git a/docs/en/07-develop/04-query-data/_go_async.mdx b/docs/en/07-develop/04-query-data/_go_async.mdx new file mode 100644 index 0000000000000000000000000000000000000000..3fbc6f5b6dac9d3987678e64d7268eed200ce513 --- /dev/null +++ b/docs/en/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/en/07-develop/04-query-data/_java.mdx b/docs/en/07-develop/04-query-data/_java.mdx new file mode 100644 index 0000000000000000000000000000000000000000..74de32658c658fb81c29349a1997e32ed512db1b --- /dev/null +++ b/docs/en/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/en/07-develop/04-query-data/_js.mdx b/docs/en/07-develop/04-query-data/_js.mdx new file mode 100644 index 0000000000000000000000000000000000000000..5883d378e7c7acab033bffb2018f00f1ab5a48d5 --- /dev/null +++ b/docs/en/07-develop/04-query-data/_js.mdx @@ -0,0 +1,3 @@ +```js +{{#include docs/examples/node/nativeexample/query_example.js}} +``` diff --git a/docs/en/07-develop/04-query-data/_js_async.mdx b/docs/en/07-develop/04-query-data/_js_async.mdx new file mode 100644 index 0000000000000000000000000000000000000000..4b0f54a0342e62da1e5050d49546ca605ae1d729 --- /dev/null +++ b/docs/en/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/en/07-develop/04-query-data/_py.mdx b/docs/en/07-develop/04-query-data/_py.mdx new file mode 100644 index 0000000000000000000000000000000000000000..8ebeca450bd611913874b606b73e65f1e484d239 --- /dev/null +++ b/docs/en/07-develop/04-query-data/_py.mdx @@ -0,0 +1,11 @@ +Result set is iterated row by row. + +```py +{{#include docs/examples/python/query_example.py:iter}} +``` + +Result set is retrieved as a whole, each row is converted to a dict and returned. + +```py +{{#include docs/examples/python/query_example.py:fetch_all}} +``` \ No newline at end of file diff --git a/docs/en/07-develop/04-query-data/_py_async.mdx b/docs/en/07-develop/04-query-data/_py_async.mdx new file mode 100644 index 0000000000000000000000000000000000000000..393a5b173351bafcbdb469ac7d00db0a6b22dbc1 --- /dev/null +++ b/docs/en/07-develop/04-query-data/_py_async.mdx @@ -0,0 +1,8 @@ +```py +{{#include docs/examples/python/async_query_example.py}} +``` + +:::note +This sample code can't be run on Windows system for now. + +::: diff --git a/docs/en/07-develop/04-query-data/_rust.mdx b/docs/en/07-develop/04-query-data/_rust.mdx new file mode 100644 index 0000000000000000000000000000000000000000..cab1b403fbba0cb432ecb9cb280a0fa7582c5be1 --- /dev/null +++ b/docs/en/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/en/07-develop/04-query-data/index.mdx b/docs/en/07-develop/04-query-data/index.mdx new file mode 100644 index 0000000000000000000000000000000000000000..a212fa9529215fc24c55c95a166cfc1a407359b2 --- /dev/null +++ b/docs/en/07-develop/04-query-data/index.mdx @@ -0,0 +1,186 @@ +--- +Sidebar_label: Query data +title: Query data +description: "This chapter introduces major query functionalities and how to perform sync and async query using connectors." +--- + +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 PyAsync from "./_py_async.mdx"; +import NodeAsync from "./_js_async.mdx"; +import CsAsync from "./_cs_async.mdx"; +import CAsync from "./_c_async.mdx"; + +## Introduction + +SQL is used by TDengine as its query language. Application programs can send SQL statements to TDengine through REST API or connectors. TDengine's CLI `taos` can also be used to execute ad hoc SQL queries. Here is the list of major query functionalities supported by TDengine： + +- Query on single column or multiple columns +- Filter on tags or data columns：>, <, =, <\>, like +- Grouping of results: `Group By` +- Sorting of results: `Order By` +- Limit the number of results: `Limit/Offset` +- Arithmetic on columns of numeric types or aggregate results +- Join query with timestamp alignment +- Aggregate functions: count, max, min, avg, sum, twa, stddev, leastsquares, top, bottom, first, last, percentile, apercentile, last_row, spread, diff + +For example, the SQL statement below can be executed in TDengine CLI `taos` to select records with voltage greater than 215 and limit the output to only 2 rows. + +```sql +select * from d1001 where voltage > 215 order by ts desc limit 2; +``` + +```title=Output +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) +``` + +To meet the requirements of varied use cases, some special functions have been added in TDengine. Some examples are `twa` (Time Weighted Average), `spread` (The difference between the maximum and the minimum), and `last_row` (the last row). Furthermore, continuous query is also supported in TDengine. + +For detailed query syntax please refer to [Select](/taos-sql/select). + +## Aggregation among Tables + +In most use cases, there are always multiple kinds of data collection points. A new concept, called STable (abbreviation for super table), is used in TDengine to represent one type of data collection point, and a subtable is used to represent a specific data collection point of that type. Tags are used by TDengine to represent the static properties of data collection points. A specific data collection point has its own values for static properties. By specifying filter conditions on tags, aggregation can be performed efficiently among all the subtables created via the same STable, i.e. same type of data collection points. Aggregate functions applicable for tables can be used directly on STables; the syntax is exactly the same. + +In summary, records across subtables can be aggregated by a simple query on their STable. It is like a join operation. However, tables belonging to different STables can not be aggregated. + +### Example 1 + +In TDengine CLI `taos`, use the SQL below to get the average voltage of all the meters in California grouped by location. + +``` +taos> SELECT AVG(voltage) FROM meters GROUP BY location; + avg(voltage) | location | +============================================================= + 222.000000000 | California.LosAngeles | + 219.200000000 | California.SanFrancisco | +Query OK, 2 row(s) in set (0.002136s) +``` + +### Example 2 + +In TDengine CLI `taos`, use the SQL below to get the number of rows and the maximum current in the past 24 hours from meters whose groupId is 2. + +``` +taos> SELECT count(*), max(current) FROM meters where groupId = 2 and ts > now - 24h; + count(*) | max(current) | +================================== + 5 | 13.4 | +Query OK, 1 row(s) in set (0.002136s) +``` + +Join queries are only allowed between subtables of the same STable. In [Select](/taos-sql/select), all query operations are marked as to whether they support STables or not. + +## Down Sampling and Interpolation + +In IoT use cases, down sampling is widely used to aggregate data by time range. The `INTERVAL` keyword in TDengine can be used to simplify the query by time window. For example, the SQL statement below can be used to get the sum of current every 10 seconds from meters table d1001. + +``` +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) +``` + +Down sampling can also be used for STable. For example, the below SQL statement can be used to get the sum of current from all meters in California. + +``` +taos> SELECT SUM(current) FROM meters where location like "California%" 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) +``` + +Down sampling also supports time offset. For example, the below SQL statement can be used to get the sum of current from all meters but each time window must start at the boundary of 500 milliseconds. + +``` +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) +``` + +In many use cases, it's hard to align the timestamp of the data collected by each collection point. However, a lot of algorithms like FFT require the data to be aligned with same time interval and application programs have to handle this by themselves. In TDengine, it's easy to achieve the alignment using down sampling. + +Interpolation can be performed in TDengine if there is no data in a time range. + +For more details please refer to [Aggregate by Window](/taos-sql/interval). + +## Examples + +### Query + +In the section describing [Insert](/develop/insert-data/sql-writing), a database named `power` is created and some data are inserted into STable `meters`. Below sample code demonstrates how to query the data in this STable. + + + + + + + + + + + + + + + + + + + + + + + + + +:::note + +1. With either REST connection or native connection, the above sample code works well. +2. Please note that `use db` can't be used in case of REST connection because it's stateless. + +::: + +### Asynchronous Query + +Besides synchronous queries, an asynchronous query API is also provided by TDengine to insert or query data more efficiently. With a similar hardware and software environment, the async API is 2~4 times faster than sync APIs. Async API works in non-blocking mode, which means an operation can be returned without finishing so that the calling thread can switch to other work to improve the performance of the whole application system. Async APIs perform especially better in the case of poor networks. + +Please note that async query can only be used with a native connection. + + + + + + + + + + + + diff --git a/docs/en/07-develop/06-continuous-query.mdx b/docs/en/07-develop/06-continuous-query.mdx new file mode 100644 index 0000000000000000000000000000000000000000..1aea5783fc8116a4e02a4b5345d341707cd399ea --- /dev/null +++ b/docs/en/07-develop/06-continuous-query.mdx @@ -0,0 +1,83 @@ +--- +sidebar_label: Continuous Query +description: "Continuous query is a query that's executed automatically at a predefined frequency to provide aggregate query capability by time window. It is essentially simplified, time driven, stream computing." +title: "Continuous Query" +--- + +A continuous query is a query that's executed automatically at a predefined frequency to provide aggregate query capability by time window. It is essentially simplified, time driven, stream computing. A continuous query can be performed on a table or STable in TDengine. The results of a continuous query can be pushed to clients or written back to TDengine. Each query is executed on a time window, which moves forward with time. The size of time window and the forward sliding time need to be specified with parameter `INTERVAL` and `SLIDING` respectively. + +A continuous query in TDengine is time driven, and can be defined using TAOS SQL directly without any extra operations. With a continuous query, the result can be generated based on a time window to achieve down sampling of the original data. Once a continuous query is defined using TAOS SQL, the query is automatically executed at the end of each time window and the result is pushed back to clients or written to TDengine. + +There are some differences between continuous query in TDengine and time window computation in stream computing： + +- The computation is performed and the result is returned in real time in stream computing, but the computation in continuous query is only started when a time window closes. For example, if the time window is 1 day, then the result will only be generated at 23:59:59. +- If a historical data row is written in to a time window for which the computation has already finished, the computation will not be performed again and the result will not be pushed to client applications again. If the results have already been written into TDengine, they will not be updated. +- In continuous query, if the result is pushed to a client, the client status is not cached on the server side and Exactly-once is not guaranteed by the server. If the client program crashes, a new time window will be generated from the time where the continuous query is restarted. If the result is written into TDengine, the data written into TDengine can be guaranteed as valid and continuous. + +## Syntax + +```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: The time window for which continuous query is performed + +SLIDING: The time step for which the time window moves forward each time + +## How to Use + +In this section the use case of meters will be used to introduce how to use continuous query. Assume the STable and subtables have been created using the SQL statements below. + +```sql +create table meters (ts timestamp, current float, voltage int, phase float) tags (location binary(64), groupId int); +create table D1001 using meters tags ("California.SanFrancisco", 2); +create table D1002 using meters tags ("California.LosAngeles", 2); +``` + +The SQL statement below retrieves the average voltage for a one minute time window, with each time window moving forward by 30 seconds. + +```sql +select avg(voltage) from meters interval(1m) sliding(30s); +``` + +Whenever the above SQL statement is executed, all the existing data will be computed again. If the computation needs to be performed every 30 seconds automatically to compute on the data in the past one minute, the above SQL statement needs to be revised as below, in which `{startTime}` stands for the beginning timestamp in the latest time window. + +```sql +select avg(voltage) from meters where ts > {startTime} interval(1m) sliding(30s); +``` + +An easier way to achieve this is to prepend `create table {tableName} as` before the `select`. + +```sql +create table avg_vol as select avg(voltage) from meters interval(1m) sliding(30s); +``` + +A table named as `avg_vol` will be created automatically, then every 30 seconds the `select` statement will be executed automatically on the data in the past 1 minute, i.e. the latest time window, and the result is written into table `avg_vol`. The client program just needs to query from table `avg_vol`. For example: + +```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 | +``` + +Please note that the minimum allowed time window is 10 milliseconds, and there is no upper limit. + +It's possible to specify the start and end time of a continuous query. If the start time is not specified, the timestamp of the first row will be considered as the start time; if the end time is not specified, the continuous query will be performed indefinitely, otherwise it will be terminated once the end time is reached. For example, the continuous query in the SQL statement below will be started from now and terminated one hour later. + +```sql +create table avg_vol as select avg(voltage) from meters where ts > now and ts <= now + 1h interval(1m) sliding(30s); +``` + +`now` in the above SQL statement stands for the time when the continuous query is created, not the time when the computation is actually performed. To avoid the trouble caused by a delay in receiving data as much as possible, the actual computation in a continuous query is started after a little delay. That means, once a time window closes, the computation is not started immediately. Normally, the result are available after a little time, normally within one minute, after the time window closes. + +## How to Manage + +`show streams` command can be used in the TDengine CLI `taos` to show all the continuous queries in the system, and `kill stream` can be used to terminate a continuous query. diff --git a/docs/en/07-develop/07-subscribe.mdx b/docs/en/07-develop/07-subscribe.mdx new file mode 100644 index 0000000000000000000000000000000000000000..782fcdbaf221419dd231bd10958e26b8f4f856e5 --- /dev/null +++ b/docs/en/07-develop/07-subscribe.mdx @@ -0,0 +1,259 @@ +--- +sidebar_label: Data Subscription +description: "Lightweight service for data subscription and publishing. Time series data inserted into TDengine continuously can be pushed automatically to subscribing clients." +title: Data Subscription +--- + +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"; + +## Introduction + +Due to the nature of time series data, data insertion into TDengine is similar to data publishing in message queues. Data is stored in ascending order of timestamp inside TDengine, and so each table in TDengine can essentially be considered as a message queue. + +A lightweight service for data subscription and publishing is built into TDengine. With the API provided by TDengine, client programs can use `select` statements to subscribe to data from one or more tables. The subscription and state maintenance is performed on the client side. The client programs poll the server to check whether there is new data, and if so the new data will be pushed back to the client side. If the client program is restarted, where to start retrieving new data is up to the client side. + +There are 3 major APIs related to subscription provided in the TDengine client driver. + +```c +taos_subscribe +taos_consume +taos_unsubscribe +``` + +For more details about these APIs please refer to [C/C++ Connector](/reference/connector/cpp). Their usage will be introduced below using the use case of meters, in which the schema of STable and subtables from the previous section [Continuous Query](/develop/continuous-query) are used. Full sample code can be found [here](https://github.com/taosdata/TDengine/blob/master/examples/c/subscribe.c). + +If we want to get a notification and take some actions if the current exceeds a threshold, like 10A, from some meters, there are two ways: + +The first way is to query each sub table and record the last timestamp matching the criteria. Then after some time, query the data later than the recorded timestamp, and repeat this process. The SQL statements for this way are as below. + +```sql +select * from D1001 where ts > {last_timestamp1} and current > 10; +select * from D1002 where ts > {last_timestamp2} and current > 10; +... +``` + +The above way works, but the problem is that the number of `select` statements increases with the number of meters. Additionally, the performance of both client side and server side will be unacceptable once the number of meters grows to a big enough number. + +A better way is to query on the STable, only one `select` is enough regardless of the number of meters, like below: + +```sql +select * from meters where ts > {last_timestamp} and current > 10; +``` + +However, this presents a new problem in how to choose `last_timestamp`. First, the timestamp when the data is generated is different from the timestamp when the data is inserted into the database, sometimes the difference between them may be very big. Second, the time when the data from different meters arrives at the database may be different too. If the timestamp of the "slowest" meter is used as `last_timestamp` in the query, the data from other meters may be selected repeatedly; but if the timestamp of the "fastest" meter is used as `last_timestamp`, some data from other meters may be missed. + +All the problems mentioned above can be resolved easily using the subscription functionality provided by TDengine. + +The first step is to create subscription using `taos_subscribe`. + +```c +TAOS_SUB* tsub = NULL; +if (async) { +　　// create an asynchronous subscription, the callback function will be called every 1s +　　tsub = taos_subscribe(taos, restart, topic, sql, subscribe_callback, &blockFetch, 1000); +} else { +　　// create an synchronous subscription, need to call 'taos_consume' manually +　　tsub = taos_subscribe(taos, restart, topic, sql, NULL, NULL, 0); +} +``` + +The subscription in TDengine can be either synchronous or asynchronous. In the above sample code, the value of variable `async` is determined from the CLI input, then it's used to create either an async or sync subscription. Sync subscription means the client program needs to invoke `taos_consume` to retrieve data, and async subscription means another thread created by `taos_subscribe` internally invokes `taos_consume` to retrieve data and pass the data to `subscribe_callback` for processing. `subscribe_callback` is a callback function provided by the client program. You should not perform time consuming operations in the callback function. + +The parameter `taos` is an established connection. Nothing special needs to be done for thread safety for synchronous subscription. For asynchronous subscription, the taos_subscribe function should be called exclusively by the current thread, to avoid unpredictable errors. + +The parameter `sql` is a `select` statement in which the `where` clause can be used to specify filter conditions. In our example, we can subscribe to the records in which the current exceeds 10A, with the following SQL statement: + +```sql +select * from meters where current > 10; +``` + +Please note that, all the data will be processed because no start time is specified. If we only want to process data for the past day, a time related condition can be added: + +```sql +select * from meters where ts > now - 1d and current > 10; +``` + +The parameter `topic` is the name of the subscription. The client application must guarantee that the name is unique. However, it doesn't have to be globally unique because subscription is implemented in the APIs on the client side. + +If the subscription named as `topic` doesn't exist, the parameter `restart` will be ignored. If the subscription named as `topic` has been created before by the client program, when the client program is restarted with the subscription named `topic`, parameter `restart` is used to determine whether to retrieve data from the beginning or from the last point where the subscription was broken. + +If the value of `restart` is **true** (i.e. a non-zero value), data will be retrieved from the beginning. If it is **false** (i.e. zero), the data already consumed before will not be processed again. + +The last parameter of `taos_subscribe` is the polling interval in units of millisecond. In sync mode, if the time difference between two continuous invocations to `taos_consume` is smaller than the interval specified by `taos_subscribe`, `taos_consume` will be blocked until the interval is reached. In async mode, this interval is the minimum interval between two invocations to the call back function. + +The second to last parameter of `taos_subscribe` is used to pass arguments to the call back function. `taos_subscribe` doesn't process this parameter and simply passes it to the call back function. This parameter is simply ignored in sync mode. + +After a subscription is created, its data can be consumed and processed. Shown below is the sample code to consume data in sync mode, in the else condition of `if (async)`. + +```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(); +　　} +} +``` + +In the above sample code in the else condition, there is an infinite loop. Each time carriage return is entered `taos_consume` is invoked. The return value of `taos_consume` is the selected result set. In the above sample, `print_result` is used to simplify the printing of the result set. It is similar to `taos_use_result`. Below is the implementation of `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); +} +``` + +In the above code `taos_print_row` is used to process the data consumed. All matching rows are printed. + +In async mode, consuming data is simpler as shown below. + +```c +void subscribe_callback(TAOS_SUB* tsub, TAOS_RES *res, void* param, int code) { +　　print_result(res, *(int*)param); +} +``` + +`taos_unsubscribe` can be invoked to terminate a subscription. + +```c +taos_unsubscribe(tsub, keep); +``` + +The second parameter `keep` is used to specify whether to keep the subscription progress on the client sde. If it is **false**, i.e. **0**, then subscription will be restarted from beginning regardless of the `restart` parameter's value when `taos_subscribe` is invoked again. The subscription progress information is stored in _{DataDir}/subscribe/_ , under which there is a file with the same name as `topic` for each subscription(Note: The default value of `DataDir` in the `taos.cfg` file is **/var/lib/taos/**. However, **/var/lib/taos/** does not exist on the Windows server. So you need to change the `DataDir` value to the corresponding existing directory."), the subscription will be restarted from the beginning if the corresponding progress file is removed. + +Now let's see the effect of the above sample code, assuming below prerequisites have been done. + +- The sample code has been downloaded to local system +- TDengine has been installed and launched properly on same system +- The database, STable, and subtables required in the sample code are ready + +Launch the command below in the directory where the sample code resides to compile and start the program. + +```bash +make +./subscribe -sql='select * from meters where current > 10;' +``` + +After the program is started, open another terminal and launch TDengine CLI `taos`, then use the below SQL commands to insert a row whose current is 12A into table **D1001**. + +```sql +use test; +insert into D1001 values(now, 12, 220, 1); +``` + +Then, this row of data will be shown by the example program on the first terminal because its current exceeds 10A. More data can be inserted for you to observe the output of the example program. + +## Examples + +The example program below demonstrates how to subscribe, using connectors, to data rows in which current exceeds 10A. + +### Prepare Data + +```bash +# 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 ("California.SanFrancisco", 2); +taos> create table d1002 using meters tags ("California.LoSangeles", 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 | California.LoSangeles | 2 | + 2020-08-15 12:20:00.000 | 11.20000 | 220 | 1 | California.LoSangeles | 2 | + 2020-08-15 12:00:00.000 | 12.00000 | 220 | 1 | California.SanFrancisco | 2 | + 2020-08-15 12:10:00.000 | 12.30000 | 220 | 2 | California.SanFrancisco | 2 | + 2020-08-15 12:20:00.000 | 12.20000 | 220 | 1 | California.SanFrancisco | 2 | +Query OK, 5 row(s) in set (0.004896s) +``` + +### Example Programs + + + + + + + + + {/* + + */} + + + + {/* + + + + + */} + + + + + +### Run the Examples + +The example programs first consume all historical data matching the criteria. + +```bash +ts: 1597464000000 current: 12.0 voltage: 220 phase: 1 location: California.SanFrancisco groupid : 2 +ts: 1597464600000 current: 12.3 voltage: 220 phase: 2 location: California.SanFrancisco groupid : 2 +ts: 1597465200000 current: 12.2 voltage: 220 phase: 1 location: California.SanFrancisco groupid : 2 +ts: 1597464600000 current: 10.3 voltage: 220 phase: 1 location: California.LoSangeles groupid : 2 +ts: 1597465200000 current: 11.2 voltage: 220 phase: 1 location: California.LoSangeles groupid : 2 +``` + +Next, use TDengine CLI to insert a new row. + +``` +# taos +taos> use power; +taos> insert into d1001 values(now, 12.4, 220, 1); +``` + +Because the current in the inserted row exceeds 10A, it will be consumed by the example program. + +``` +ts: 1651146662805 current: 12.4 voltage: 220 phase: 1 location: California.SanFrancisco groupid: 2 +``` diff --git a/docs/en/07-develop/08-cache.md b/docs/en/07-develop/08-cache.md new file mode 100644 index 0000000000000000000000000000000000000000..743452faff6a2be8466318a7dab61a44e33c3664 --- /dev/null +++ b/docs/en/07-develop/08-cache.md @@ -0,0 +1,19 @@ +--- +sidebar_label: Cache +title: Cache +description: "The latest row of each table is kept in cache to provide high performance query of latest state." +--- + +The cache management policy in TDengine is First-In-First-Out (FIFO). FIFO is also known as insert driven cache management policy and it is different from read driven cache management, which is more commonly known as Least-Recently-Used (LRU). FIFO simply stores the latest data in cache and flushes the oldest data in cache to disk, when the cache usage reaches a threshold. In IoT use cases, it is the current state i.e. the latest or most recent data that is important. The cache policy in TDengine, like much of the design and architecture of TDengine, is based on the nature of IoT data. + +Caching the latest data provides the capability of retrieving data in milliseconds. With this capability, TDengine can be configured properly to be used as a caching system without deploying another separate caching system. This simplifies the system architecture and minimizes operational costs. The cache is emptied after TDengine is restarted. TDengine does not reload data from disk into cache, like a key-value caching system. + +The memory space used by the TDengine cache is fixed in size and configurable. It should be allocated based on application requirements and system resources. An independent memory pool is allocated for and managed by each vnode (virtual node) in TDengine. There is no sharing of memory pools between vnodes. All the tables belonging to a vnode share all the cache memory of the vnode. + +The memory pool is divided into blocks and data is stored in row format in memory and each block follows FIFO policy. The size of each block is determined by configuration parameter `cache` and the number of blocks for each vnode is determined by the parameter `blocks`. For each vnode, the total cache size is `cache * blocks`. A cache block needs to ensure that each table can store at least dozens of records, to be efficient. + +`last_row` function can be used to retrieve the last row of a table or a STable to quickly show the current state of devices on monitoring screen. For example the below SQL statement retrieves the latest voltage of all meters in San Francisco, California. + +```sql +select last_row(voltage) from meters where location='California.SanFrancisco'; +``` diff --git a/docs/en/07-develop/09-udf.md b/docs/en/07-develop/09-udf.md new file mode 100644 index 0000000000000000000000000000000000000000..49bc95bd91a4c31d42d2b21ef05d69225f1bd963 --- /dev/null +++ b/docs/en/07-develop/09-udf.md @@ -0,0 +1,240 @@ +--- +sidebar_label: UDF +title: User Defined Functions(UDF) +description: "Scalar functions and aggregate functions developed by users can be utilized by the query framework to expand query capability" +--- + +In some use cases, built-in functions are not adequate for the query capability required by application programs. With UDF, the functions developed by users can be utilized by the query framework to meet business and application requirements. UDF normally takes one column of data as input, but can also support the result of a sub-query as input. + +From version 2.2.0.0, UDF written in C/C++ are supported by TDengine. + + +## Types of UDF + +Two kinds of functions can be implemented by UDF: scalar functions and aggregate functions. + +Scalar functions return multiple rows and aggregate functions return either 0 or 1 row. + +In the case of a scalar function you only have to implement the "normal" function template. + +In the case of an aggregate function, in addition to the "normal" function, you also need to implement the "merge" and "finalize" function templates even if the implementation is empty. This will become clear in the sections below. + +### Scalar Function + +As mentioned earlier, a scalar UDF only has to implement the "normal" function template. The function template below can be used to define your own scalar function. + +`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` is the place holder for a function name. A function implemented based on the above template can be used to perform scalar computation on data rows. The parameters are fixed to control the data exchange between UDF and TDengine. + +- Definitions of the parameters: + + - data：input data + - itype：the type of input data, for details please refer to [type definition in column_meta](/reference/rest-api/), for example 4 represents INT + - iBytes：the number of bytes consumed by each value in the input data + - oType：the type of output data, similar to iType + - oBytes：the number of bytes consumed by each value in the output data + - numOfRows：the number of rows in the input data + - ts: the column of timestamp corresponding to the input data + - dataOutput：the buffer for output data, total size is `oBytes * numberOfRows` + - interBuf：the buffer for an intermediate result. Its size is specified by the `BUFSIZE` parameter when creating a UDF. It's normally used when the intermediate result is not same as the final result. This buffer is allocated and freed by TDengine. + - tsOutput：the column of timestamps corresponding to the output data; it can be used to output timestamp together with the output data if it's not NULL + - numOfOutput：the number of rows in output data + - buf：for the state exchange between UDF and TDengine + + [add_one.c](https://github.com/taosdata/TDengine/blob/develop/tests/script/sh/add_one.c) is one example of a very simple UDF implementation, i.e. one instance of the above `udfNormalFunc` template. It adds one to each value of a passed in column, which can be filtered using the `where` clause, and outputs the result. + +### Aggregate Function + +For aggregate UDF, as mentioned earlier you must implement a "normal" function template (described above) and also implement the "merge" and "finalize" templates. + +#### Merge Function Template + +The function template below can be used to define your own merge function for an aggregate UDF. + +`void udfMergeFunc(char* data, int32_t numOfRows, char* dataOutput, int32_t* numOfOutput, SUdfInit* buf)` + +`udfMergeFunc` is the place holder for a function name. The function implemented with the above template is used to aggregate intermediate results and can only be used in the aggregate query for STable. + +Definitions of the parameters: + +- data：array of output data, if interBuf is used it's an array of interBuf +- numOfRows：number of rows in `data` +- dataOutput：the buffer for output data, the size is same as that of the final result; If the result is not final, it can be put in the interBuf, i.e. `data`. +- numOfOutput：number of rows in the output data +- buf：for the state exchange between UDF and TDengine + +#### Finalize Function Template + +The function template below can be used to finalize the result of your own UDF, normally used when interBuf is used. + +`void udfFinalizeFunc(char* dataOutput, char* interBuf, int* numOfOutput, SUdfInit* buf)` + +`udfFinalizeFunc` is the place holder of function name, definitions of the parameter are as below: + +- dataOutput：buffer for output data +- interBuf：buffer for intermediate result, can be used as input for next processing step +- numOfOutput：number of output data, can only be 0 or 1 for aggregate function +- buf：for state exchange between UDF and TDengine + +### Example abs_max.c + +[abs_max.c](https://github.com/taosdata/TDengine/blob/develop/tests/script/sh/abs_max.c) is an example of a user defined aggregate function to get the maximum from the absolute values of a column. + +The internal processing happens as follows. The results of the select statement are divided into multiple row blocks and `udfNormalFunc`, i.e. `abs_max` in this case, is performed on each row block to generate the intermediate results for each sub table. Then `udfMergeFunc`, i.e. `abs_max_merge` in this case, is performed on the intermediate result of sub tables to aggregate and generate the final or intermediate result of STable. The intermediate result of STable is finally processed by `udfFinalizeFunc`, i.e. `abs_max_finalize` in this example, to generate the final result, which contains either 0 or 1 row. + +Other typical aggregation functions such as covariance, can also be implemented using aggregate UDF. + +## UDF Naming Conventions + +The naming convention for the 3 kinds of function templates required by UDF is as follows: + - udfNormalFunc, udfMergeFunc, and udfFinalizeFunc are required to have same prefix, i.e. the actual name of udfNormalFunc. The udfNormalFunc doesn't need a suffix following the function name. + - udfMergeFunc should be udfNormalFunc followed by `_merge` + - udfFinalizeFunc should be udfNormalFunc followed by `_finalize`. + +The naming convention is part of TDengine's UDF framework. TDengine follows this convention to invoke the corresponding actual functions. + +Depending on whether you are creating a scalar UDF or aggregate UDF, the functions that you need to implement are different. + +- Scalar function：udfNormalFunc is required. +- Aggregate function：udfNormalFunc, udfMergeFunc (if query on STable) and udfFinalizeFunc are required. + +For clarity, assuming we want to implement a UDF named "foo": +- If the function is a scalar function, we only need to implement the "normal" function template and it should be named simply `foo`. +- If the function is an aggregate function, we need to implement `foo`, `foo_merge`, and `foo_finalize`. Note that for aggregate UDF, even though one of the three functions is not necessary, there must be an empty implementation. + +## Compile UDF + +The source code of UDF in C can't be utilized by TDengine directly. UDF can only be loaded into TDengine after compiling to dynamically linked library (DLL). + +For example, the example UDF `add_one.c` mentioned earlier, can be compiled into DLL using the command below, in a Linux Shell. + +```bash +gcc -g -O0 -fPIC -shared add_one.c -o add_one.so +``` + +The generated DLL file `add_one.so` can be used later when creating a UDF. It's recommended to use GCC not older than 7.5. + +## Create and Use UDF + +When a UDF is created in a TDengine instance, it is available across the databases in that instance. + +### Create UDF + +SQL command can be executed on the host where the generated UDF DLL resides to load the UDF DLL into TDengine. This operation cannot be done through REST interface or web console. Once created, any client of the current TDengine can use these UDF functions in their SQL commands. UDF are stored in the management node of TDengine. The UDFs loaded in TDengine would be still available after TDengine is restarted. + +When creating UDF, the type of UDF, i.e. a scalar function or aggregate function must be specified. If the specified type is wrong, the SQL statements using the function would fail with errors. The input type and output type don't need to be the same in UDF, but the input data type and output data type must be consistent with the UDF definition. + +- Create Scalar Function + +```sql +CREATE FUNCTION userDefinedFunctionName AS "/absolute/path/to/userDefinedFunctionName.so" OUTPUTTYPE [BUFSIZE B]; +``` + +- userDefinedFunctionName：The function name to be used in SQL statement which must be consistent with the function name defined by `udfNormalFunc` and is also the name of the compiled DLL (.so file). +- path：The absolute path of the DLL file including the name of the shared object file (.so). The path must be quoted with single or double quotes. +- outputtype：The output data type, the value is the literal string of the supported TDengine data type. +- B：the size of intermediate buffer, in bytes; it is an optional parameter and the range is [0,512]. + +For example, below SQL statement can be used to create a UDF from `add_one.so`. + +```sql +CREATE FUNCTION add_one AS "/home/taos/udf_example/add_one.so" OUTPUTTYPE INT; +``` + +- Create Aggregate Function + +```sql +CREATE AGGREGATE FUNCTION userDefinedFunctionName AS "/absolute/path/to/userDefinedFunctionName.so" OUTPUTTYPE [ BUFSIZE B ]; +``` + +- userDefinedFunctionName：the function name to be used in SQL statement which must be consistent with the function name defined by `udfNormalFunc` and is also the name of the compiled DLL (.so file). +- path：the absolute path of the DLL file including the name of the shared object file (.so). The path needs to be quoted by single or double quotes. +- OUTPUTTYPE：the output data type, the value is the literal string of the type +- B：the size of intermediate buffer, in bytes; it's an optional parameter and the range is [0,512] + +For details about how to use intermediate result, please refer to example program [demo.c](https://github.com/taosdata/TDengine/blob/develop/tests/script/sh/demo.c). + +For example, below SQL statement can be used to create a UDF from `demo.so`. + +```sql +CREATE AGGREGATE FUNCTION demo AS "/home/taos/udf_example/demo.so" OUTPUTTYPE DOUBLE bufsize 14; +``` + +### Manage UDF + +- Delete UDF + +``` +DROP FUNCTION ids(X); +``` + +- ids(X)：same as that in `CREATE FUNCTION` statement + +```sql +DROP FUNCTION add_one; +``` + +- Show Available UDF + +```sql +SHOW FUNCTIONS; +``` + +### Use UDF + +The function name specified when creating UDF can be used directly in SQL statements, just like builtin functions. + +```sql +SELECT X(c) FROM table/STable; +``` + +The above SQL statement invokes function X for column c. + +## Restrictions for UDF + +In current version there are some restrictions for UDF + +1. Only Linux is supported when creating and invoking UDF for both client side and server side +2. UDF can't be mixed with builtin functions +3. Only one UDF can be used in a SQL statement +4. Only a single column is supported as input for UDF +5. Once created successfully, UDF is persisted in MNode of TDengineUDF +6. UDF can't be created through REST interface +7. The function name used when creating UDF in SQL must be consistent with the function name defined in the DLL, i.e. the name defined by `udfNormalFunc` +8. The name of a UDF should not conflict with any of TDengine's built-in functions + +## Examples + +### Scalar function example [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}} +``` + +
+ +### Aggregate function example [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}} +``` + +
+ +### Example for using intermediate result [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/en/07-develop/_category_.yml b/docs/en/07-develop/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..6f0d66351a5c326eb2dced998e29e668d11cd1ca --- /dev/null +++ b/docs/en/07-develop/_category_.yml @@ -0,0 +1 @@ +label: Developer Guide \ No newline at end of file diff --git a/docs/en/07-develop/_sub_c.mdx b/docs/en/07-develop/_sub_c.mdx new file mode 100644 index 0000000000000000000000000000000000000000..da492a0269f064d8cdf9dfb80969894131d94015 --- /dev/null +++ b/docs/en/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/en/07-develop/_sub_cs.mdx b/docs/en/07-develop/_sub_cs.mdx new file mode 100644 index 0000000000000000000000000000000000000000..a435ea0273c94cbe75eaf7431e1a9c39d49d92e3 --- /dev/null +++ b/docs/en/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/en/07-develop/_sub_go.mdx b/docs/en/07-develop/_sub_go.mdx new file mode 100644 index 0000000000000000000000000000000000000000..34b2aefd92c5eef75b59fbbba96b83da091722a7 --- /dev/null +++ b/docs/en/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/en/07-develop/_sub_java.mdx b/docs/en/07-develop/_sub_java.mdx new file mode 100644 index 0000000000000000000000000000000000000000..ab77f61348c115d3fe3336df47d467c5525f41b8 --- /dev/null +++ b/docs/en/07-develop/_sub_java.mdx @@ -0,0 +1,7 @@ +```java +{{#include docs/examples/java/src/main/java/com/taos/example/SubscribeDemo.java}} +``` +:::note +For now Java connector doesn't provide asynchronous subscription, but `TimerTask` can be used to achieve similar purpose. + +::: \ No newline at end of file diff --git a/docs/en/07-develop/_sub_node.mdx b/docs/en/07-develop/_sub_node.mdx new file mode 100644 index 0000000000000000000000000000000000000000..3eeff0922a31a478dd34a77c6cb6471f51a57a8c --- /dev/null +++ b/docs/en/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/en/07-develop/_sub_python.mdx b/docs/en/07-develop/_sub_python.mdx new file mode 100644 index 0000000000000000000000000000000000000000..490b76fca6deb61e61dc59c2096b30742a7d25f7 --- /dev/null +++ b/docs/en/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/en/07-develop/_sub_rust.mdx b/docs/en/07-develop/_sub_rust.mdx new file mode 100644 index 0000000000000000000000000000000000000000..afb8d79daa3bbd72d72795cb4425f12277d710fc --- /dev/null +++ b/docs/en/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/en/07-develop/index.md b/docs/en/07-develop/index.md new file mode 100644 index 0000000000000000000000000000000000000000..e3f55f290753f79ac1708337082ce90bb050b21f --- /dev/null +++ b/docs/en/07-develop/index.md @@ -0,0 +1,25 @@ +--- +title: Developer Guide +--- + +To develop an application to process time-series data using TDengine, we recommend taking the following steps: + +1. Choose the method to connect to TDengine. No matter what programming language you use, you can always use the REST interface to access TDengine, but you can also use connectors unique to each programming language. +2. Design the data model based on your own use cases. Learn the [concepts](/concept/) of TDengine including "one table for one data collection point" and the "super table" (STable) concept; learn about static labels, collected metrics, and subtables. Depending on the characteristics of your data and your requirements, you may decide to create one or more databases, and you should design the STable schema to fit your data. +3. Decide how you will insert data. TDengine supports writing using standard SQL, but also supports schemaless writing, so that data can be written directly without creating tables manually. +4. Based on business requirements, find out what SQL query statements need to be written. You may be able to repurpose any existing SQL. +5. If you want to run real-time analysis based on time series data, including various dashboards, it is recommended that you use the TDengine continuous query feature instead of deploying complex streaming processing systems such as Spark or Flink. +6. If your application has modules that need to consume inserted data, and they need to be notified when new data is inserted, it is recommended that you use the data subscription function provided by TDengine without the need to deploy Kafka. +7. In many use cases (such as fleet management), the application needs to obtain the latest status of each data collection point. It is recommended that you use the cache function of TDengine instead of deploying Redis separately. +8. If you find that the SQL functions of TDengine cannot meet your requirements, then you can use user-defined functions to solve the problem. + +This section is organized in the order described above. For ease of understanding, TDengine provides sample code for each supported programming language for each function. If you want to learn more about the use of SQL, please read the [SQL manual](/taos-sql/). For a more in-depth understanding of the use of each connector, please read the [Connector Reference Guide](/reference/connector/). If you also want to integrate TDengine with third-party systems, such as Grafana, please refer to the [third-party tools](/third-party/). + +If you encounter any problems during the development process, please click ["Submit an issue"](https://github.com/taosdata/TDengine/issues/new/choose) at the bottom of each page and submit it on GitHub right away. + +```mdx-code-block +import DocCardList from '@theme/DocCardList'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + + +``` diff --git a/docs/en/10-cluster/01-deploy.md b/docs/en/10-cluster/01-deploy.md new file mode 100644 index 0000000000000000000000000000000000000000..200da1be3f8185818bd21dd3fcdc78c124a36831 --- /dev/null +++ b/docs/en/10-cluster/01-deploy.md @@ -0,0 +1,136 @@ +--- +title: Deployment +--- + +## Prerequisites + +### Step 1 + +The FQDN of all hosts must be setup properly. For e.g. FQDNs may have to be configured in the /etc/hosts file on each host. You must confirm that each FQDN can be accessed from any other host. For e.g. you can do this by using the `ping` command. + +To get the hostname on any host, the command `hostname -f` can be executed. `ping ` command can be executed on each host to check whether any other host is accessible from it. If any host is not accessible, the network configuration, like /etc/hosts or DNS configuration, needs to be checked and revised, to make any two hosts accessible to each other. + +:::note + +- The host where the client program runs also needs to be configured properly for FQDN, to make sure all hosts for client or server can be accessed from any other. In other words, the hosts where the client is running are also considered as a part of the cluster. + +- Please ensure that your firewall rules do not block TCP/UDP on ports 6030-6042 on all hosts in the cluster. + +::: + +### Step 2 + +If any previous version of TDengine has been installed and configured on any host, the installation needs to be removed and the data needs to be cleaned up. For details about uninstalling please refer to [Install and Uninstall](/operation/pkg-install). To clean up the data, please use `rm -rf /var/lib/taos/\*` assuming the `dataDir` is configured as `/var/lib/taos`. + +:::note + +As a best practice, before cleaning up any data files or directories, please ensure that your data has been backed up correctly, if required by your data integrity, backup, security, or other standard operating protocols (SOP). + +::: + +### Step 3 + +Now it's time to install TDengine on all hosts but without starting `taosd`. Note that the versions on all hosts should be same. If you are prompted to input the existing TDengine cluster, simply press carriage return to ignore the prompt. `install.sh -e no` can also be used to disable this prompt. For details please refer to [Install and Uninstall](/operation/pkg-install). + +### Step 4 + +Now each physical node (referred to, hereinafter, as `dnode` which is an abbreviation for "data node") of TDengine needs to be configured properly. Please note that one dnode doesn't stand for one host. Multiple TDengine dnodes can be started on a single host as long as they are configured properly without conflicting. More specifically each instance of the configuration file `taos.cfg` stands for a dnode. Assuming the first dnode of TDengine cluster is "h1.taosdata.com:6030", its `taos.cfg` is configured as following. + +```c +// firstEp is the end point to connect to when any dnode starts +firstEp h1.taosdata.com:6030 + +// must be configured to the FQDN of the host where the dnode is launched +fqdn h1.taosdata.com + +// the port used by the dnode, default is 6030 +serverPort 6030 + +// only necessary when replica is configured to an even number +#arbitrator ha.taosdata.com:6042 +``` + +`firstEp` and `fqdn` must be configured properly. In `taos.cfg` of all dnodes in TDengine cluster, `firstEp` must be configured to point to same address, i.e. the first dnode of the cluster. `fqdn` and `serverPort` compose the address of each node itself. If you want to start multiple TDengine dnodes on a single host, please make sure all other configurations like `dataDir`, `logDir`, and other resources related parameters are not conflicting. + +For all the dnodes in a TDengine cluster, the below parameters must be configured exactly the same, any node whose configuration is different from dnodes already in the cluster can't join the cluster. + +| **#** | **Parameter** | **Definition** | +| ----- | ------------------ | --------------------------------------------------------------------------------- | +| 1 | numOfMnodes | The number of management nodes in the cluster | +| 2 | mnodeEqualVnodeNum | The ratio of resource consuming of mnode to vnode | +| 3 | offlineThreshold | The threshold of dnode offline, once it's reached the dnode is considered as down | +| 4 | statusInterval | The interval by which dnode reports its status to mnode | +| 5 | arbitrator | End point of the arbitrator component in the cluster | +| 6 | timezone | Timezone | +| 7 | balance | Enable load balance automatically | +| 8 | maxTablesPerVnode | Maximum number of tables that can be created in each vnode | +| 9 | maxVgroupsPerDb | Maximum number vgroups that can be used by each DB | + +:::note +Prior to version 2.0.19.0, besides the above parameters, `locale` and `charset` must also be configured the same for each dnode. + +::: + +## Start Cluster + +In the following example we assume that first dnode has FQDN h1.taosdata.com and the second dnode has FQDN h2.taosdata.com. + +### Start The First DNODE + +The first dnode can be started following the instructions in [Get Started](/get-started/). Then TDengine CLI `taos` can be launched to execute command `show dnodes`, the output is as following for example: + +``` +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.taosdata.com:6030 | 0 | 2 | ready | any | 2020-07-31 03:49:29.202 | +Query OK, 1 row(s) in set (0.006385s) + +taos> +``` + +From the above output, it is shown that the end point of the started dnode is "h1.taosdata.com:6030", which is the `firstEp` of the cluster. + +### Start Other DNODEs + +There are a few steps necessary to add other dnodes in the cluster. + +Let's assume we are starting the second dnode with FQDN, h2.taosdata.com. First we make sure the configuration is correct. + +```c +// firstEp is the end point to connect to when any dnode starts +firstEp h1.taosdata.com:6030 + +// must be configured to the FQDN of the host where the dnode is launched +fqdn h2.taosdata.com + +// the port used by the dnode, default is 6030 +serverPort 6030 + +``` + +Second, we can start `taosd` as instructed in [Get Started](/get-started/). + +Then, on the first dnode i.e. h1.taosdata.com in our example, use TDengine CLI `taos` to execute the following command to add the end point of the dnode in the cluster. In the command "fqdn:port" should be quoted using double quotes. + +```sql +CREATE DNODE "h2.taos.com:6030"; +``` + +Then on the first dnode h1.taosdata.com, execute `show dnodes` in `taos` to show whether the second dnode has been added in the cluster successfully or not. + +```sql +SHOW DNODES; +``` + +If the status of the newly added dnode is offline, please check: + +- Whether the `taosd` process is running properly or not +- In the log file `taosdlog.0` to see whether the fqdn and port are correct + +The above process can be repeated to add more dnodes in the cluster. diff --git a/docs/en/10-cluster/02-cluster-mgmt.md b/docs/en/10-cluster/02-cluster-mgmt.md new file mode 100644 index 0000000000000000000000000000000000000000..674c92e2766a4eb304079140af19c8efea72d55e --- /dev/null +++ b/docs/en/10-cluster/02-cluster-mgmt.md @@ -0,0 +1,213 @@ +--- +sidebar_label: Operation +title: Manage DNODEs +--- + +The previous section, [Deployment],(/cluster/deploy) showed you how to deploy and start a cluster from scratch. Once a cluster is ready, the status of dnode(s) in the cluster can be shown at any time. Dnodes can be managed from the TDengine CLI. New dnode(s) can be added to scale out the cluster, an existing dnode can be removed and you can even perform load balancing manually, if necessary. + +:::note +All the commands introduced in this chapter must be run in the TDengine CLI - `taos`. Note that sometimes it is necessary to use root privilege. + +::: + +## Show DNODEs + +The below command can be executed in TDengine CLI `taos` to list all dnodes in the cluster, including ID, end point (fqdn:port), status (ready, offline), number of vnodes, number of free vnodes and so on. We recommend executing this command after adding or removing a dnode. + +```sql +SHOW DNODES; +``` + +Below is the example output of this command. + +``` +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) +``` + +## Show VGROUPs + +To utilize system resources efficiently and provide scalability, data sharding is required. The data of each database is divided into multiple shards and stored in multiple vnodes. These vnodes may be located on different dnodes. One way of scaling out is to add more vnodes on dnodes. Each vnode can only be used for a single DB, but one DB can have multiple vnodes. The allocation of vnode is scheduled automatically by mnode based on system resources of the dnodes. + +Launch TDengine CLI `taos` and execute below command: + +```sql +USE SOME_DATABASE; +SHOW VGROUPS; +``` + +The example output is below: + +``` +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) +``` + +## Add DNODE + +Launch TDengine CLI `taos` and execute the command below to add the end point of a new dnode into the EPI (end point) list of the cluster. "fqdn:port" must be quoted using double quotes. + +```sql +CREATE DNODE "fqdn:port"; +``` + +The example output is as below: + +``` +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) +``` + +It can be seen that the status of the new dnode is "offline". Once the dnode is started and connects to the firstEp of the cluster, you can execute the command again and get the example output below. As can be seen, both dnodes are in "ready" status. + +``` +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) +``` + +## Drop DNODE + +Launch TDengine CLI `taos` and execute the command below to drop or remove a dnode from the cluster. In the command, you can get `dnodeId` from `show dnodes`. + +```sql +DROP DNODE "fqdn:port"; +``` + +or + +```sql +DROP DNODE dnodeId; +``` + +The example output is below： + +``` +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) +``` + +In the above example, when `show dnodes` is executed the first time, two dnodes are shown. After `drop dnode 2` is executed, you can execute `show dnodes` again and it can be seen that only the dnode with ID 1 is still in the cluster. + +:::note + +- Once a dnode is dropped, it can't rejoin the cluster. To rejoin, the dnode needs to deployed again after cleaning up the data directory. Before dropping a dnode, the data belonging to the dnode MUST be migrated/backed up according to your data retention, data security or other SOPs. +- Please note that `drop dnode` is different from stopping `taosd` process. `drop dnode` just removes the dnode out of TDengine cluster. Only after a dnode is dropped, can the corresponding `taosd` process be stopped. +- Once a dnode is dropped, other dnodes in the cluster will be notified of the drop and will not accept the request from the dropped dnode. +- dnodeID is allocated automatically and can't be manually modified. dnodeID is generated in ascending order without duplication. + +::: + +## Move VNODE + +A vnode can be manually moved from one dnode to another. + +Launch TDengine CLI `taos` and execute below command: + +```sql +ALTER DNODE BALANCE "VNODE:-DNODE:"; +``` + +In the above command, `source-dnodeId` is the original dnodeId where the vnode resides, `dest-dnodeId` specifies the target dnode. vgId (vgroup ID) can be shown by `SHOW VGROUPS `. + +First `show vgroups` is executed to show the vgroup distribution. + +``` +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) +``` + +It can be seen that there are 5 vgroups in dnode 3 and 3 vgroups in node 1, now we want to move vgId 18 from dnode 3 to dnode 1. Execute the below command in `taos` + +``` +taos> alter dnode 3 balance "vnode:18-dnode:1"; + +DB error: Balance already enabled (0.00755 +``` + +However, the operation fails with error message show above, which means automatic load balancing has been enabled in the current database so manual load balance can't be performed. + +Shutdown the cluster, configure `balance` parameter in all the dnodes to 0, then restart the cluster, and execute `alter dnode` and `show vgroups` as below. + +``` +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) +``` + +It can be seen from above output that vgId 18 has been moved from dnode 3 to dnode 1. + +:::note + +- Manual load balancing can only be performed when the automatic load balancing is disabled, i.e. `balance` is set to 0. +- Only a vnode in normal state, i.e. master or slave, can be moved. vnode can't be moved when its in status offline, unsynced or syncing. +- Before moving a vnode, it's necessary to make sure the target dnode has enough resources: CPU, memory and disk. + +::: diff --git a/docs/en/10-cluster/03-ha-and-lb.md b/docs/en/10-cluster/03-ha-and-lb.md new file mode 100644 index 0000000000000000000000000000000000000000..bd718eef9f8dc181628132de831dbca2af59d158 --- /dev/null +++ b/docs/en/10-cluster/03-ha-and-lb.md @@ -0,0 +1,81 @@ +--- +sidebar_label: HA & LB +title: High Availability and Load Balancing +--- + +## High Availability of Vnode + +High availability of vnode and mnode can be achieved through replicas in TDengine. + +A TDengine cluster can have multiple databases. Each database has a number of vnodes associated with it. A different number of replicas can be configured for each DB. When creating a database, the parameter `replica` is used to specify the number of replicas. The default value for `replica` is 1. Naturally, a single replica cannot guarantee high availability since if one node is down, the data service is unavailable. Note that the number of dnodes in the cluster must NOT be lower than the number of replicas set for any DB, otherwise the `create table` operation will fail with error "more dnodes are needed". The SQL statement below is used to create a database named "demo" with 3 replicas. + +```sql +CREATE DATABASE demo replica 3; +``` + +The data in a DB is divided into multiple shards and stored in multiple vgroups. The number of vnodes in each vgroup is determined by the number of replicas set for the DB. The vnodes in each vgroup store exactly the same data. For the purpose of high availability, the vnodes in a vgroup must be located in different dnodes on different hosts. As long as over half of the vnodes in a vgroup are in an online state, the vgroup is able to provide data access. Otherwise the vgroup can't provide data access for reading or inserting data. + +There may be data for multiple DBs in a dnode. When a dnode is down, multiple DBs may be affected. While in theory, the cluster will provide data access for reading or inserting data if over half the vnodes in vgroups are online, because of the possibly complex mapping between vnodes and dnodes, it is difficult to guarantee that the cluster will work properly if over half of the dnodes are online. + +## High Availability of Mnode + +Each TDengine cluster is managed by `mnode`, which is a module of `taosd`. For the high availability of mnode, multiple mnodes can be configured using system parameter `numOfMNodes`. The valid range for `numOfMnodes` is [1,3]. To ensure data consistency between mnodes, data replication between mnodes is performed synchronously. + +There may be multiple dnodes in a cluster, but only one mnode can be started in each dnode. Which one or ones of the dnodes will be designated as mnodes is automatically determined by TDengine according to the cluster configuration and system resources. The command `show mnodes` can be executed in TDengine `taos` to show the mnodes in the cluster. + +```sql +SHOW MNODES; +``` + +The end point and role/status (master, slave, unsynced, or offline) of all mnodes can be shown by the above command. When the first dnode is started in a cluster, there must be one mnode in this dnode. Without at least one mnode, the cluster cannot work. If `numOfMNodes` is configured to 2, another mnode will be started when the second dnode is launched. + +For the high availability of mnode, `numOfMnodes` needs to be configured to 2 or a higher value. Because the data consistency between mnodes must be guaranteed, the replica confirmation parameter `quorum` is set to 2 automatically if `numOfMNodes` is set to 2 or higher. + +:::note +If high availability is important for your system, both vnode and mnode must be configured to have multiple replicas. + +::: + +## Load Balancing + +Load balancing will be triggered in 3 cases without manual intervention. + +- When a new dnode joins the cluster, automatic load balancing may be triggered. Some data from other dnodes may be transferred to the new dnode automatically. +- When a dnode is removed from the cluster, the data from this dnode will be transferred to other dnodes automatically. +- When a dnode is too hot, i.e. too much data has been stored in it, automatic load balancing may be triggered to migrate some vnodes from this dnode to other dnodes. + +:::tip +Automatic load balancing is controlled by the parameter `balance`, 0 means disabled and 1 means enabled. This is set in the file [taos.cfg](https://docs.tdengine.com/reference/config/#balance). + +::: + +## Dnode Offline + +When a dnode is offline, it can be detected by the TDengine cluster. There are two cases: + +- The dnode comes online before the threshold configured in `offlineThreshold` is reached. The dnode is still in the cluster and data replication is started automatically. The dnode can work properly after the data sync is finished. + +- If the dnode has been offline over the threshold configured in `offlineThreshold` in `taos.cfg`, the dnode will be removed from the cluster automatically. A system alert will be generated and automatic load balancing will be triggered if `balance` is set to 1. When the removed dnode is restarted and becomes online, it will not join the cluster automatically. The system administrator has to manually join the dnode to the cluster. + +:::note +If all the vnodes in a vgroup (or mnodes in mnode group) are in offline or unsynced status, the master node can only be voted on, after all the vnodes or mnodes in the group become online and can exchange status. Following this, the vgroup (or mnode group) is able to provide service. + +::: + +## Arbitrator + +The "arbitrator" component is used to address the special case when the number of replicas is set to an even number like 2,4 etc. If half of the vnodes in a vgroup don't work, it is impossible to vote and select a master node. This situation also applies to mnodes if the number of mnodes is set to an even number like 2,4 etc. + +To resolve this problem, a new arbitrator component named `tarbitrator`, an abbreviation of TDengine Arbitrator, was introduced. The `tarbitrator` simulates a vnode or mnode but it's only responsible for network communication and doesn't handle any actual data access. As long as more than half of the vnode or mnode, including Arbitrator, are available the vnode group or mnode group can provide data insertion or query services normally. + +Normally, it's prudent to configure the replica number for each DB or system parameter `numOfMNodes` to be an odd number. However, if a user is very sensitive to storage space, a replica number of 2 plus arbitrator component can be used to achieve both lower cost of storage space and high availability. + +Arbitrator component is installed with the server package. For details about how to install, please refer to [Install](/operation/pkg-install). The `-p` parameter of `tarbitrator` can be used to specify the port on which it provides service. + +In the configuration file `taos.cfg` of each dnode, parameter `arbitrator` needs to be configured to the end point of the `tarbitrator` process. Arbitrator component will be used automatically if the replica is configured to an even number and will be ignored if the replica is configured to an odd number. + +Arbitrator can be shown by executing command in TDengine CLI `taos` with its role shown as "arb". + +```sql +SHOW DNODES; +``` diff --git a/docs/en/10-cluster/_category_.yml b/docs/en/10-cluster/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..141fd7832631d69efed214293c69cee336bc854d --- /dev/null +++ b/docs/en/10-cluster/_category_.yml @@ -0,0 +1 @@ +label: Cluster diff --git a/docs/en/10-cluster/index.md b/docs/en/10-cluster/index.md new file mode 100644 index 0000000000000000000000000000000000000000..5a45a2ce7b08c67322265cf1bbd54ef66cbfc027 --- /dev/null +++ b/docs/en/10-cluster/index.md @@ -0,0 +1,15 @@ +--- +title: Cluster +keywords: ["cluster", "high availability", "load balance", "scale out"] +--- + +TDengine has a native distributed design and provides the ability to scale out. A few nodes can form a TDengine cluster. If you need higher processing power, you just need to add more nodes into the cluster. TDengine uses virtual node technology to virtualize a node into multiple virtual nodes to achieve load balancing. At the same time, TDengine can group virtual nodes on different nodes into virtual node groups, and use the replication mechanism to ensure the high availability of the system. The cluster feature of TDengine is completely open source. + +This chapter mainly introduces cluster deployment, maintenance, and how to achieve high availability and load balancing. + +```mdx-code-block +import DocCardList from '@theme/DocCardList'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + + +``` diff --git a/docs/en/12-taos-sql/01-data-type.md b/docs/en/12-taos-sql/01-data-type.md new file mode 100644 index 0000000000000000000000000000000000000000..3f5a49e3135771c6c1e62bcf158a99ee30f1ed9d --- /dev/null +++ b/docs/en/12-taos-sql/01-data-type.md @@ -0,0 +1,49 @@ +--- +title: Data Types +description: "TDengine supports a variety of data types including timestamp, float, JSON and many others." +--- + +When using TDengine to store and query data, the most important part of the data is timestamp. Timestamp must be specified when creating and inserting data rows. Timestamp must follow the rules below: + +- The format must be `YYYY-MM-DD HH:mm:ss.MS`, the default time precision is millisecond (ms), for example `2017-08-12 18:25:58.128` +- Internal function `now` can be used to get the current timestamp on the client side +- The current timestamp of the client side is applied when `now` is used to insert data +- Epoch Time：timestamp can also be a long integer number, which means the number of seconds, milliseconds or nanoseconds, depending on the time precision, from 1970-01-01 00:00:00.000 (UTC/GMT) +- Add/subtract operations can be carried out on timestamps. For example `now-2h` means 2 hours prior to the time at which query is executed. The units of time in operations can be b(nanosecond), u(microsecond), a(millisecond), s(second), m(minute), h(hour), d(day), or w(week). So `select * from t1 where ts > now-2w and ts <= now-1w` means the data between two weeks ago and one week ago. The time unit can also be n (calendar month) or y (calendar year) when specifying the time window for down sampling operations. + +Time precision in TDengine can be set by the `PRECISION` parameter when executing `CREATE DATABASE`. The default time precision is millisecond. In the statement below, the precision is set to nanonseconds. + +```sql +CREATE DATABASE db_name PRECISION 'ns'; +``` + +In TDengine, the data types below can be used when specifying a column or tag. + +| # | **type** | **Bytes** | **Description** | +| --- | :-------: | --------- | ------------------------- | +| 1 | TIMESTAMP | 8 | Default precision is millisecond, microsecond and nanosecond are also supported | +| 2 | INT | 4 | Integer, the value range is [-2^31+1, 2^31-1], while -2^31 is treated as NULL | +| 3 | BIGINT | 8 | Long integer, the value range is [-2^63+1, 2^63-1], while -2^63 is treated as NULL | +| 4 | FLOAT | 4 | Floating point number, the effective number of digits is 6-7, the value range is [-3.4E38, 3.4E38] | +| 5 | DOUBLE | 8 | Double precision floating point number, the effective number of digits is 15-16, the value range is [-1.7E308, 1.7E308] | +| 6 | BINARY | User Defined | Single-byte string for ASCII visible characters. Length must be specified when defining a column or tag of binary type. The string length can be up to 16374 bytes. The string value must be quoted with single quotes. The literal single quote inside the string must be preceded with back slash like `\'` | +| 7 | SMALLINT | 2 | Short integer, the value range is [-32767, 32767], while -32768 is treated as NULL | +| 8 | TINYINT | 1 | Single-byte integer, the value range is [-127, 127], while -128 is treated as NULL | +| 9 | BOOL | 1 | Bool, the value range is {true, false} | +| 10 | NCHAR | User Defined| Multi-Byte string that can include multi byte characters like Chinese characters. Each character of NCHAR type consumes 4 bytes storage. The string value should be quoted with single quotes. Literal single quote inside the string must be preceded with backslash, like `\’`. The length must be specified when defining a column or tag of NCHAR type, for example nchar(10) means it can store at most 10 characters of nchar type and will consume fixed storage of 40 bytes. An error will be reported if the string value exceeds the length defined. | +| 11 | JSON | | JSON type can only be used on tags. A tag of json type is excluded with any other tags of any other type | + +:::tip +TDengine is case insensitive and treats any characters in the sql command as lower case by default, case sensitive strings must be quoted with single quotes. + +::: + +:::note +Only ASCII visible characters are suggested to be used in a column or tag of BINARY type. Multi-byte characters must be stored in NCHAR type. + +::: + +:::note +Numeric values in SQL statements will be determined as integer or float type according to whether there is decimal point or whether scientific notation is used, so attention must be paid to avoid overflow. For example, 9999999999999999999 will be considered as overflow because it exceeds the upper limit of long integer, but 9999999999999999999.0 will be considered as a legal float number. + +::: diff --git a/docs/en/12-taos-sql/02-database.md b/docs/en/12-taos-sql/02-database.md new file mode 100644 index 0000000000000000000000000000000000000000..80581b2f1bc7ce9cd046c18873d3f22b6804d8cf --- /dev/null +++ b/docs/en/12-taos-sql/02-database.md @@ -0,0 +1,127 @@ +--- +sidebar_label: Database +title: Database +description: "create and drop database, show or change database parameters" +--- + +## Create Database + +``` +CREATE DATABASE [IF NOT EXISTS] db_name [KEEP keep] [DAYS days] [UPDATE 1]; +``` + +:::info + +1. KEEP specifies the number of days for which the data in the database will be retained. The default value is 3650 days, i.e. 10 years. The data will be deleted automatically once its age exceeds this threshold. +2. UPDATE specifies whether the data can be updated and how the data can be updated. + 1. UPDATE set to 0 means update operation is not allowed. The update for data with an existing timestamp will be discarded silently and the original record in the database will be preserved as is. + 2. UPDATE set to 1 means the whole row will be updated. The columns for which no value is specified will be set to NULL. + 3. UPDATE set to 2 means updating a subset of columns for a row is allowed. The columns for which no value is specified will be kept unchanged. +3. The maximum length of database name is 33 bytes. +4. The maximum length of a SQL statement is 65,480 bytes. +5. Below are the parameters that can be used when creating a database + - 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. Please note that all of the parameters mentioned in this section are configured in configuration file `taos.cfg` on the TDengine server. If not specified in the `create database` statement, the values from taos.cfg are used by default. To override default parameters, they must be specified in the `create database` statement. + +::: + +## Show Current Configuration + +``` +SHOW VARIABLES; +``` + +## Specify The Database In Use + +``` +USE db_name; +``` + +:::note +This way is not applicable when using a REST connection. In a REST connection the database name must be specified before a table or stable name. For e.g. to query the stable "meters" in database "test" the query would be "SELECT count(*) from test.meters" + +::: + +## Drop Database + +``` +DROP DATABASE [IF EXISTS] db_name; +``` + +:::note +All data in the database will be deleted too. This command must be used with extreme caution. Please follow your organization's data integrity, data backup, data security or any other applicable SOPs before using this command. + +::: + +## Change Database Configuration + +Some examples are shown below to demonstrate how to change the configuration of a database. Please note that some configuration parameters can be changed after the database is created, but some cannot. For details of the configuration parameters of database please refer to [Configuration Parameters](/reference/config/). + +``` +ALTER DATABASE db_name COMP 2; +``` + +COMP parameter specifies whether the data is compressed and how the data is compressed. + +``` +ALTER DATABASE db_name REPLICA 2; +``` + +REPLICA parameter specifies the number of replicas of the database. + +``` +ALTER DATABASE db_name KEEP 365; +``` + +KEEP parameter specifies the number of days for which the data will be kept. + +``` +ALTER DATABASE db_name QUORUM 2; +``` + +QUORUM parameter specifies the necessary number of confirmations to determine whether the data is written successfully. + +``` +ALTER DATABASE db_name BLOCKS 100; +``` + +BLOCKS parameter specifies the number of memory blocks used by each VNODE. + +``` +ALTER DATABASE db_name CACHELAST 0; +``` + +CACHELAST parameter specifies whether and how the latest data of a sub table is cached. + +:::tip +The above parameters can be changed using `ALTER DATABASE` command without restarting. For more details of all configuration parameters please refer to [Configuration Parameters](/reference/config/). + +::: + +## Show All Databases + +``` +SHOW DATABASES; +``` + +## Show The Create Statement of A Database + +``` +SHOW CREATE DATABASE db_name; +``` + +This command is useful when migrating the data from one TDengine cluster to another. This command can be used to get the CREATE statement, which can be used in another TDengine instance to create the exact same database. diff --git a/docs/en/12-taos-sql/03-table.md b/docs/en/12-taos-sql/03-table.md new file mode 100644 index 0000000000000000000000000000000000000000..f065a8e2396583bb7a512446b513ed60056ad55e --- /dev/null +++ b/docs/en/12-taos-sql/03-table.md @@ -0,0 +1,127 @@ +--- +sidebar_label: Table +title: Table +description: create super table, normal table and sub table, drop tables and change tables +--- + +## Create Table + +``` +CREATE TABLE [IF NOT EXISTS] tb_name (timestamp_field_name TIMESTAMP, field1_name data_type1 [, field2_name data_type2 ...]); +``` + +:::info + +1. The first column of a table MUST be of type TIMESTAMP. It is automatically set as the primary key. +2. The maximum length of the table name is 192 bytes. +3. The maximum length of each row is 48k bytes, please note that the extra 2 bytes used by each BINARY/NCHAR column are also counted. +4. The name of the subtable can only consist of characters from the English alphabet, digits and underscore. Table names can't start with a digit. Table names are case insensitive. +5. The maximum length in bytes must be specified when using BINARY or NCHAR types. +6. Escape character "\`" can be used to avoid the conflict between table names and reserved keywords, above rules will be bypassed when using escape character on table names, but the upper limit for the name length is still valid. The table names specified using escape character are case sensitive. Only ASCII visible characters can be used with escape character. + For example \`aBc\` and \`abc\` are different table names but `abc` and `aBc` are same table names because they are both converted to `abc` internally. + +::: + +### Create Subtable Using STable As Template + +``` +CREATE TABLE [IF NOT EXISTS] tb_name USING stb_name TAGS (tag_value1, ...); +``` + +The above command creates a subtable using the specified super table as a template and the specified tag values. + +### Create Subtable Using STable As Template With A Subset of Tags + +``` +CREATE TABLE [IF NOT EXISTS] tb_name USING stb_name (tag_name1, ...) TAGS (tag_value1, ...); +``` + +The tags for which no value is specified will be set to NULL. + +### Create Tables in Batch + +``` +CREATE TABLE [IF NOT EXISTS] tb_name1 USING stb_name TAGS (tag_value1, ...) [IF NOT EXISTS] tb_name2 USING stb_name TAGS (tag_value2, ...) ...; +``` + +This can be used to create a lot of tables in a single SQL statement while making table creation much faster. + +:::info + +- Creating tables in batch must use a super table as a template. +- The length of single statement is suggested to be between 1,000 and 3,000 bytes for best performance. + +::: + +## Drop Tables + +``` +DROP TABLE [IF EXISTS] tb_name; +``` + +## Show All Tables In Current Database + +``` +SHOW TABLES [LIKE tb_name_wildcard]; +``` + +## Show Create Statement of A Table + +``` +SHOW CREATE TABLE tb_name; +``` + +This is useful when migrating the data in one TDengine cluster to another one because it can be used to create the exact same tables in the target database. + +## Show Table Definition + +``` +DESCRIBE tb_name; +``` + +## Change Table Definition + +### Add A Column + +``` +ALTER TABLE tb_name ADD COLUMN field_name data_type; +``` + +:::info + +1. The maximum number of columns is 4096, the minimum number of columns is 2. +2. The maximum length of a column name is 64 bytes. + +::: + +### Remove A Column + +``` +ALTER TABLE tb_name DROP COLUMN field_name; +``` + +:::note +If a table is created using a super table as template, the table definition can only be changed on the corresponding super table, and the change will be automatically applied to all the subtables created using this super table as template. For tables created in the normal way, the table definition can be changed directly on the table. + +::: + +### Change Column Length + +``` +ALTER TABLE tb_name MODIFY COLUMN field_name data_type(length); +``` + +If the type of a column is variable length, like BINARY or NCHAR, this command can be used to change the length of the column. + +:::note +If a table is created using a super table as template, the table definition can only be changed on the corresponding super table, and the change will be automatically applied to all the subtables created using this super table as template. For tables created in the normal way, the table definition can be changed directly on the table. + +::: + +### Change Tag Value Of Sub Table + +``` +ALTER TABLE tb_name SET TAG tag_name=new_tag_value; +``` + +This command can be used to change the tag value if the table is created using a super table as template. diff --git a/docs/en/12-taos-sql/04-stable.md b/docs/en/12-taos-sql/04-stable.md new file mode 100644 index 0000000000000000000000000000000000000000..b8a608792ab327a81129d29ddd0ff44d7af6e6c5 --- /dev/null +++ b/docs/en/12-taos-sql/04-stable.md @@ -0,0 +1,118 @@ +--- +sidebar_label: STable +title: Super Table +--- + +:::note + +Keyword `STable`, abbreviated for super table, is supported since version 2.0.15. + +::: + +## Create STable + +``` +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]); +``` + +The SQL statement of creating a STable is similar to that of creating a table, but a special column set named `TAGS` must be specified with the names and types of the tags. + +:::info + +1. A tag can be of type timestamp, since version 2.1.3.0, but its value must be fixed and arithmetic operations cannot be performed on it. Prior to version 2.1.3.0, tag types specified in TAGS could not be of type timestamp. +2. The tag names specified in TAGS should NOT be the same as other columns. +3. The tag names specified in TAGS should NOT be the same as any reserved keywords.(Please refer to [keywords](/taos-sql/keywords/) +4. The maximum number of tags specified in TAGS is 128, there must be at least one tag, and the total length of all tag columns should NOT exceed 16KB. + +::: + +## Drop STable + +``` +DROP STable [IF EXISTS] stb_name; +``` + +All the subtables created using the deleted STable will be deleted automatically. + +## Show All STables + +``` +SHOW STableS [LIKE tb_name_wildcard]; +``` + +This command can be used to display the information of all STables in the current database, including name, creation time, number of columns, number of tags, and number of tables created using this STable. + +## Show The Create Statement of A STable + +``` +SHOW CREATE STable stb_name; +``` + +This command is useful in migrating data from one TDengine cluster to another because it can be used to create the exact same STable in the target database. + +## Get STable Definition + +``` +DESCRIBE stb_name; +``` + +## Change Columns Of STable + +### Add A Column + +``` +ALTER STable stb_name ADD COLUMN field_name data_type; +``` + +### Remove A Column + +``` +ALTER STable stb_name DROP COLUMN field_name; +``` + +### Change Column Length + +``` +ALTER STable stb_name MODIFY COLUMN field_name data_type(length); +``` + +This command can be used to change (or more specifically, increase) the length of a column of variable length types, like BINARY or NCHAR. + +## Change Tags of A STable + +### Add A Tag + +``` +ALTER STable stb_name ADD TAG new_tag_name tag_type; +``` + +This command is used to add a new tag for a STable and specify the tag type. + +### Remove A Tag + +``` +ALTER STable stb_name DROP TAG tag_name; +``` + +The tag will be removed automatically from all the subtables, created using the super table as template, once a tag is removed from a super table. + +### Change A Tag + +``` +ALTER STable stb_name CHANGE TAG old_tag_name new_tag_name; +``` + +The tag name will be changed automatically for all the subtables, created using the super table as template, once a tag name is changed for a super table. + +### Change Tag Length + +``` +ALTER STable stb_name MODIFY TAG tag_name data_type(length); +``` + +This command can be used to change (or more specifically, increase) the length of a tag of variable length types, like BINARY or NCHAR. + +:::note +Changing tag values can be applied to only subtables. All other tag operations, like add tag, remove tag, however, can be applied to only STable. If a new tag is added for a STable, the tag will be added with NULL value for all its subtables. + +::: diff --git a/docs/en/12-taos-sql/05-insert.md b/docs/en/12-taos-sql/05-insert.md new file mode 100644 index 0000000000000000000000000000000000000000..1336cd7238a19190583ea9d268a64df242ffd3c9 --- /dev/null +++ b/docs/en/12-taos-sql/05-insert.md @@ -0,0 +1,164 @@ +--- +title: Insert +--- + +## Syntax + +```sql +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 + ...]; +``` + +## Insert Single or Multiple Rows + +Single row or multiple rows specified with VALUES can be inserted into a specific table. For example: + +A single row is inserted using the below statement. + +```sq; +INSERT INTO d1001 VALUES (NOW, 10.2, 219, 0.32); +``` + +Double rows are inserted using the below statement. + +```sql +INSERT INTO d1001 VALUES ('2021-07-13 14:06:32.272', 10.2, 219, 0.32) (1626164208000, 10.15, 217, 0.33); +``` + +:::note + +1. In the second example above, different formats are used in the two rows to be inserted. In the first row, the timestamp format is a date and time string, which is interpreted from the string value only. In the second row, the timestamp format is a long integer, which will be interpreted based on the database time precision. +2. When trying to insert multiple rows in a single statement, only the timestamp of one row can be set as NOW, otherwise there will be duplicate timestamps among the rows and the result may be out of expectation because NOW will be interpreted as the time when the statement is executed. +3. The oldest timestamp that is allowed is subtracting the KEEP parameter from current time. +4. The newest timestamp that is allowed is adding the DAYS parameter to current time. + +::: + +## Insert Into Specific Columns + +Data can be inserted into specific columns, either single row or multiple row, while other columns will be inserted as NULL value. + +``` +INSERT INTO d1001 (ts, current, phase) VALUES ('2021-07-13 14:06:33.196', 10.27, 0.31); +``` + +:::info +If no columns are explicitly specified, all the columns must be provided with values, this is called "all column mode". The insert performance of all column mode is much better than specifying a subset of columns, so it's encouraged to use "all column mode" while providing NULL value explicitly for the columns for which no actual value can be provided. + +::: + +## Insert Into Multiple Tables + +One or multiple rows can be inserted into multiple tables in a single SQL statement, with or without specifying specific columns. + +```sql +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）; +``` + +## Automatically Create Table When Inserting + +If it's unknown whether the table already exists, the table can be created automatically while inserting using the SQL statement below. To use this functionality, a STable must be used as template and tag values must be provided. + +```sql +INSERT INTO d21001 USING meters TAGS ('California.SanFrancisco', 2) VALUES ('2021-07-13 14:06:32.272', 10.2, 219, 0.32); +``` + +It's not necessary to provide values for all tags when creating tables automatically, the tags without values provided will be set to NULL. + +```sql +INSERT INTO d21001 USING meters (groupId) TAGS (2) VALUES ('2021-07-13 14:06:33.196', 10.15, 217, 0.33); +``` + +Multiple rows can also be inserted into the same table in a single SQL statement. + +```sql +INSERT INTO d21001 USING meters TAGS ('California.SanFrancisco', 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 +Prior to version 2.0.20.5, when using `INSERT` to create tables automatically and specifying the columns, the column names must follow the table name immediately. From version 2.0.20.5, the column names can follow the table name immediately, also can be put between `TAGS` and `VALUES`. In the same SQL statement, however, these two ways of specifying column names can't be mixed. +::: + +## Insert Rows From A File + +Besides using `VALUES` to insert one or multiple rows, the data to be inserted can also be prepared in a CSV file with comma as separator and each field value quoted by single quotes. Table definition is not required in the CSV file. For example, if file "/tmp/csvfile.csv" contains the below data: + +``` +'2021-07-13 14:07:34.630', '10.2', '219', '0.32' +'2021-07-13 14:07:35.779', '10.15', '217', '0.33' +``` + +Then data in this file can be inserted by the SQL statement below: + +```sql +INSERT INTO d1001 FILE '/tmp/csvfile.csv'; +``` + +## Create Tables Automatically and Insert Rows From File + +From version 2.1.5.0, tables can be automatically created using a super table as template when inserting data from a CSV file, like below: + +```sql +INSERT INTO d21001 USING meters TAGS ('California.SanFrancisco', 2) FILE '/tmp/csvfile.csv'; +``` + +Multiple tables can be automatically created and inserted in a single SQL statement, like below: + +```sql +INSERT INTO d21001 USING meters TAGS ('California.SanFrancisco', 2) FILE '/tmp/csvfile_21001.csv' + d21002 USING meters (groupId) TAGS (2) FILE '/tmp/csvfile_21002.csv'; +``` + +## More About Insert + +For SQL statement like `insert`, a stream parsing strategy is applied. That means before an error is found and the execution is aborted, the part prior to the error point has already been executed. Below is an experiment to help understand the behavior. + +First, a super table is created. + +```sql +CREATE TABLE meters(ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS(location BINARY(30), groupId INT); +``` + +It can be proven that the super table has been created by `SHOW STableS`, but no table exists using `SHOW TABLES`. + +``` +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) +``` + +Then, try to create table d1001 automatically when inserting data into it. + +```sql +INSERT INTO d1001 USING meters TAGS('California.SanFrancisco', 2) VALUES('a'); +``` + +The output shows the value to be inserted is invalid. But `SHOW TABLES` proves that the table has been created automatically by the `INSERT` statement. + +``` +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) +``` + +From the above experiment, we can see that while the value to be inserted is invalid the table is still created. diff --git a/docs/en/12-taos-sql/06-select.md b/docs/en/12-taos-sql/06-select.md new file mode 100644 index 0000000000000000000000000000000000000000..8a017cf92e40aa4a854dcd531b7df291a9243515 --- /dev/null +++ b/docs/en/12-taos-sql/06-select.md @@ -0,0 +1,449 @@ +--- +title: Select +--- + +## Syntax + +```SQL +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]; +``` + +## Wildcard + +Wildcard \* can be used to specify all columns. The result includes only data columns for normal tables. + +``` +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) +``` + +The result includes both data columns and tag columns for super table. + +``` +taos> SELECT * FROM meters; + ts | current | voltage | phase | location | groupid | +===================================================================================================================================== + 2018-10-03 14:38:05.500 | 11.80000 | 221 | 0.28000 | California.LoSangeles | 2 | + 2018-10-03 14:38:16.600 | 13.40000 | 223 | 0.29000 | California.LoSangeles | 2 | + 2018-10-03 14:38:05.000 | 10.80000 | 223 | 0.29000 | California.LoSangeles | 3 | + 2018-10-03 14:38:06.500 | 11.50000 | 221 | 0.35000 | California.LoSangeles | 3 | + 2018-10-03 14:38:04.000 | 10.20000 | 220 | 0.23000 | California.SanFrancisco | 3 | + 2018-10-03 14:38:16.650 | 10.30000 | 218 | 0.25000 | California.SanFrancisco | 3 | + 2018-10-03 14:38:05.000 | 10.30000 | 219 | 0.31000 | California.SanFrancisco | 2 | + 2018-10-03 14:38:15.000 | 12.60000 | 218 | 0.33000 | California.SanFrancisco | 2 | + 2018-10-03 14:38:16.800 | 12.30000 | 221 | 0.31000 | California.SanFrancisco | 2 | +Query OK, 9 row(s) in set (0.002022s) +``` + +Wildcard can be used with table name as prefix. Both SQL statements below have the same effect and return all columns. + +```SQL +SELECT * FROM d1001; +SELECT d1001.* FROM d1001; +``` + +In a JOIN query, however, the results are different with or without a table name prefix. \* without table prefix will return all the columns of both tables, but \* with table name as prefix will return only the columns of that table. + +``` +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) +``` + +Wildcard \* can be used with some functions, but the result may be different depending on the function being used. For example, `count(*)` returns only one column, i.e. the number of rows; `first`, `last` and `last_row` return all columns of the selected 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) +``` + +## Tags + +Starting from version 2.0.14, tag columns can be selected together with data columns when querying sub tables. Please note however, that, wildcard \* cannot be used to represent any tag column. This means that tag columns must be specified explicitly like the example below. + +``` +taos> SELECT location, groupid, current FROM d1001 LIMIT 2; + location | groupid | current | +====================================================================== + California.SanFrancisco | 2 | 10.30000 | + California.SanFrancisco | 2 | 12.60000 | +Query OK, 2 row(s) in set (0.003112s) +``` + +## Get distinct values + +`DISTINCT` keyword can be used to get all the unique values of tag columns from a super table. It can also be used to get all the unique values of data columns from a table or subtable. + +```sql +SELECT DISTINCT tag_name [, tag_name ...] FROM stb_name; +SELECT DISTINCT col_name [, col_name ...] FROM tb_name; +``` + +:::info + +1. Configuration parameter `maxNumOfDistinctRes` in `taos.cfg` is used to control the number of rows to output. The minimum configurable value is 100,000, the maximum configurable value is 100,000,000, the default value is 1,000,000. If the actual number of rows exceeds the value of this parameter, only the number of rows specified by this parameter will be output. +2. It can't be guaranteed that the results selected by using `DISTINCT` on columns of `FLOAT` or `DOUBLE` are exactly unique because of the precision errors in floating point numbers. +3. `DISTINCT` can't be used in the sub-query of a nested query statement, and can't be used together with aggregate functions, `GROUP BY` or `JOIN` in the same SQL statement. + +::: + +## Columns Names of Result Set + +When using `SELECT`, the column names in the result set will be the same as that in the select clause if `AS` is not used. `AS` can be used to rename the column names in the result set. For example + +``` +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) +``` + +`AS` can't be used together with `first(*)`, `last(*)`, or `last_row(*)`. + +## Implicit Columns + +`Select_exprs` can be column names of a table, or function expression or arithmetic expression on columns. The maximum number of allowed column names and expressions is 256. Timestamp and the corresponding tag names will be returned in the result set if `interval` or `group by tags` are used, and timestamp will always be the first column in the result set. + +## Table List + +`FROM` can be followed by a number of tables or super tables, or can be followed by a sub-query. If no database is specified as current database in use, table names must be preceded with database name, like `power.d1001`. + +```SQL +SELECT * FROM power.d1001; +``` + +has same effect as + +```SQL +USE power; +SELECT * FROM d1001; +``` + +## Special Query + +Some special query functions can be invoked without `FROM` sub-clause. For example, the statement below can be used to get the current database in use. + +``` +taos> SELECT DATABASE(); + database() | +================================= + power | +Query OK, 1 row(s) in set (0.000079s) +``` + +If no database is specified upon logging in and no database is specified with `USE` after login, NULL will be returned by `select database()`. + +``` +taos> SELECT DATABASE(); + database() | +================================= + NULL | +Query OK, 1 row(s) in set (0.000184s) +``` + +The statement below can be used to get the version of client or server. + +``` +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) +``` + +The statement below is used to check the server status. An integer, like `1`, is returned if the server status is OK, otherwise an error code is returned. This is compatible with the status check for TDengine from connection pool or 3rd party tools, and can avoid the problem of losing the connection from a connection pool when using the wrong heartbeat checking SQL statement. + +``` +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 + +**Description**: Get the data block distribution of a table or STable. + +```SQL title="Syntax" +SELECT _block_dist() FROM { tb_name | stb_name } +``` + +**Restrictions**：No argument is allowed, where clause is not allowed + +**Sub Query**：Sub query or nested query are not supported + +**Return value**: A string which includes the data block distribution of the specified table or STable, i.e. the histogram of rows stored in the data blocks of the table or STable. + +```text title="Result" +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)] +``` + +**More explanation about above example**: + +- Histogram about the rows stored in the data blocks of the table or STable: the value of rows for 5%, 10%, 20%, 30%, 40%, 50%, 60%, 70%, 80%, 90%, 95%, and 99% +- Minimum number of rows stored in a data block, i.e. Min=[392(Rows)] +- Maximum number of rows stored in a data block, i.e. Max=[800(Rows)] +- Average number of rows stored in a data block, i.e. Avg=[666(Rows)] +- stddev of number of rows, i.e. Stddev=[2.17] +- Total number of rows, i.e. Rows[2000] +- Total number of data blocks, i.e. Blocks=[3] +- Total disk size consumed, i.e. Size=[5.440(Kb)] +- Compression ratio, which means the compressed size divided by original size, i.e. Comp=[0.23] +- Total number of rows in memory, i.e. RowsInMem=[0], which means no rows in memory +- The time spent on reading head file (to retrieve data block information), i.e. SeekHeaderTime=[1(us)], which means 1 microsecond. + +## Special Keywords in TAOS SQL + +- `TBNAME`： it is treated as a special tag when selecting on a super table, representing the name of subtables in that super table. +- `_c0`: represents the first column of a table or super table. + +## Tips + +To get all the subtables and corresponding tag values from a super table: + +```SQL +SELECT TBNAME, location FROM meters; +``` + +To get the number of sub tables in a super table： + +```SQL +SELECT COUNT(TBNAME) FROM meters; +``` + +Only filter on `TAGS` are allowed in the `where` clause for above two query statements. For example: + +``` +taos> SELECT TBNAME, location FROM meters; + tbname | location | +================================================================== + d1004 | California.LosAngeles | + d1003 | California.LosAngeles | + d1002 | California.SanFrancisco | + d1001 | California.SanFrancisco | +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) +``` + +- Wildcard \* can be used to get all columns, or specific column names can be specified. Arithmetic operation can be performed on columns of numerical types, columns can be renamed in the result set. +- Arithmetic operation on columns can't be used in where clause. For example, `where a*2>6;` is not allowed but `where a>6/2;` can be used instead for the same purpose. +- Arithmetic operation on columns can't be used as the objectives of select statement. For example, `select min(2*a) from t;` is not allowed but `select 2*min(a) from t;` can be used instead. +- Logical operation can be used in `WHERE` clause to filter numeric values, wildcard can be used to filter string values. +- Result sets are arranged in ascending order of the first column, i.e. timestamp, but it can be controlled to output as descending order of timestamp. If `order by` is used on other columns, the result may not be as expected. By the way, \_c0 is used to represent the first column, i.e. timestamp. +- `LIMIT` parameter is used to control the number of rows to output. `OFFSET` parameter is used to specify from which row to output. `LIMIT` and `OFFSET` are executed after `ORDER BY` in the query execution. A simple tip is that `LIMIT 5 OFFSET 2` can be abbreviated as `LIMIT 2, 5`. +- What is controlled by `LIMIT` is the number of rows in each group when `GROUP BY` is used. +- `SLIMIT` parameter is used to control the number of groups when `GROUP BY` is used. Similar to `LIMIT`, `SLIMIT 5 OFFSET 2` can be abbreviated as `SLIMIT 2, 5`. +- ">>" can be used to output the result set of `select` statement to the specified file. + +## Where + +Logical operations in below table can be used in the `where` clause to filter the resulting rows. + +| **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`** | + +**Explanations**: + +- Operator `<\>` is equal to `!=`, please note that this operator can't be used on the first column of any table, i.e.timestamp column. +- Operator `like` is used together with wildcards to match strings + - '%' matches 0 or any number of characters, '\_' matches any single ASCII character. + - `\_` is used to match the \_ in the string. + - The maximum length of wildcard string is 100 bytes from version 2.1.6.1 (before that the maximum length is 20 bytes). `maxWildCardsLength` in `taos.cfg` can be used to control this threshold. A very long wildcard string may slowdown the execution performance of `LIKE` operator. +- `AND` keyword can be used to filter multiple columns simultaneously. AND/OR operation can be performed on single or multiple columns from version 2.3.0.0. However, before 2.3.0.0 `OR` can't be used on multiple columns. +- For timestamp column, only one condition can be used; for other columns or tags, `OR` keyword can be used to combine multiple logical operators. For example, `((value > 20 AND value < 30) OR (value < 12))`. + - From version 2.3.0.0, multiple conditions can be used on timestamp column, but the result set can only contain single time range. +- From version 2.0.17.0, operator `BETWEEN AND` can be used in where clause, for example `WHERE col2 BETWEEN 1.5 AND 3.25` means the filter condition is equal to "1.5 ≤ col2 ≤ 3.25". +- From version 2.1.4.0, operator `IN` can be used in the where clause. For example, `WHERE city IN ('California.SanFrancisco', 'California.SanDiego')`. For bool type, both `{true, false}` and `{0, 1}` are allowed, but integers other than 0 or 1 are not allowed. FLOAT and DOUBLE types are impacted by floating point precision errors. Only values that match the condition within the tolerance will be selected. Non-primary key column of timestamp type can be used with `IN`. +- From version 2.3.0.0, regular expression is supported in the where clause with keyword `match` or `nmatch`. The regular expression is case insensitive. + +## Regular Expression + +### Syntax + +```SQL +WHERE (column|tbname) **match/MATCH/nmatch/NMATCH** _regex_ +``` + +### Specification + +The regular expression being used must be compliant with POSIX specification, please refer to [Regular Expressions](https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html). + +### Restrictions + +Regular expression can be used against only table names, i.e. `tbname`, and tags of binary/nchar types, but can't be used against data columns. + +The maximum length of regular expression string is 128 bytes. Configuration parameter `maxRegexStringLen` can be used to set the maximum allowed regular expression. It's a configuration parameter on the client side, and will take effect after restarting the client. + +## JOIN + +From version 2.2.0.0, inner join is fully supported in TDengine. More specifically, the inner join between table and table, between STable and STable, and between sub query and sub query are supported. + +Only primary key, i.e. timestamp, can be used in the join operation between table and table. For example: + +```sql +SELECT * +FROM temp_tb_1 t1, pressure_tb_1 t2 +WHERE t1.ts = t2.ts +``` + +In the join operation between STable and STable, besides the primary key, i.e. timestamp, tags can also be used. For example: + +```sql +SELECT * +FROM temp_STable t1, temp_STable t2 +WHERE t1.ts = t2.ts AND t1.deviceid = t2.deviceid AND t1.status=0; +``` + +Similarly, join operations can be performed on the result set of multiple sub queries. + +:::note +Restrictions on join operation: + +- The number of tables or STables in a single join operation can't exceed 10. +- `FILL` is not allowed in the query statement that includes JOIN operation. +- Arithmetic operation is not allowed on the result set of join operation. +- `GROUP BY` is not allowed on a part of tables that participate in join operation. +- `OR` can't be used in the conditions for join operation +- join operation can't be performed on data columns, i.e. can only be performed on tags or primary key, i.e. timestamp + +::: + +## Nested Query + +Nested query is also called sub query. This means that in a single SQL statement the result of inner query can be used as the data source of the outer query. + +From 2.2.0.0, unassociated sub query can be used in the `FROM` clause. Unassociated means the sub query doesn't use the parameters in the parent query. More specifically, in the `tb_name_list` of `SELECT` statement, an independent SELECT statement can be used. So a complete nested query looks like: + +```SQL +SELECT ... FROM (SELECT ... FROM ...) ...; +``` + +:::info + +- Only one layer of nesting is allowed, that means no sub query is allowed within a sub query +- The result set returned by the inner query will be used as a "virtual table" by the outer query. The "virtual table" can be renamed using `AS` keyword for easy reference in the outer query. +- Sub query is not allowed in continuous query. +- JOIN operation is allowed between tables/STables inside both inner and outer queries. Join operation can be performed on the result set of the inner query. +- UNION operation is not allowed in either inner query or outer query. +- The functions that can be used in the inner query are the same as those that can be used in a non-nested query. + - `ORDER BY` inside the inner query is unnecessary and will slow down the query performance significantly. It is best to avoid the use of `ORDER BY` inside the inner query. +- Compared to the non-nested query, the functionality that can be used in the outer query has the following restrictions: + - Functions + - If the result set returned by the inner query doesn't contain timestamp column, then functions relying on timestamp can't be used in the outer query, like `TOP`, `BOTTOM`, `FIRST`, `LAST`, `DIFF`. + - Functions that need to scan the data twice can't be used in the outer query, like `STDDEV`, `PERCENTILE`. + - `IN` operator is not allowed in the outer query but can be used in the inner query. + - `GROUP BY` is not supported in the outer query. + +::: + +## UNION ALL + +```SQL title=Syntax +SELECT ... +UNION ALL SELECT ... +[UNION ALL SELECT ...] +``` + +`UNION ALL` operator can be used to combine the result set from multiple select statements as long as the result set of these select statements have exactly the same columns. `UNION ALL` doesn't remove redundant rows from multiple result sets. In a single SQL statement, at most 100 `UNION ALL` can be supported. + +### Examples + +table `tb1` is created using below SQL statement: + +```SQL +CREATE TABLE tb1 (ts TIMESTAMP, col1 INT, col2 FLOAT, col3 BINARY(50)); +``` + +The rows in the past one hour in `tb1` can be selected using below SQL statement: + +```SQL +SELECT * FROM tb1 WHERE ts >= NOW - 1h; +``` + +The rows between 2018-06-01 08:00:00.000 and 2018-06-02 08:00:00.000 and col3 ends with 'nny' can be selected in the descending order of timestamp using below SQL statement: + +```SQL +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; +``` + +The sum of col1 and col2 for rows later than 2018-06-01 08:00:00.000 and whose col2 is bigger than 1.2 can be selected and renamed as "complex", while only 10 rows are output from the 5th row, by below SQL statement: + +```SQL +SELECT (col1 + col2) AS 'complex' FROM tb1 WHERE ts > '2018-06-01 08:00:00.000' AND col2 > 1.2 LIMIT 10 OFFSET 5; +``` + +The rows in the past 10 minutes and whose col2 is bigger than 3.14 are selected and output to the result file `/home/testoutput.csv` with below SQL statement: + +```SQL +SELECT COUNT(*) FROM tb1 WHERE ts >= NOW - 10m AND col2 > 3.14 >> /home/testoutput.csv; +``` diff --git a/docs/en/12-taos-sql/08-delete-data.mdx b/docs/en/12-taos-sql/08-delete-data.mdx new file mode 100644 index 0000000000000000000000000000000000000000..86443dca53b08f5f5c489d40f4a2ea8afc8081fb --- /dev/null +++ b/docs/en/12-taos-sql/08-delete-data.mdx @@ -0,0 +1,42 @@ +--- +sidebar_label: Delete Data +description: "Delete data from table or Stable" +title: Delete Data +--- + +TDengine provides the functionality of deleting data from a table or STable according to specified time range, it can be used to cleanup abnormal data generated due to device failure. Please be noted that this functionality is only available in Enterprise version, please refer to [TDengine Enterprise Edition](https://tdengine.com/products#enterprise-edition-link) + + +**Syntax:** + +```sql +DELETE FROM [ db_name. ] tb_name [WHERE condition]; +``` + +**Description:** Delete data from a table or STable + +**Parameters:** + +- `db_name`: Optional parameter, specifies the database in which the table exists; if not specified, the current database will be used. +- `tb_name`: Mandatory parameter, specifies the table name from which data will be deleted, it can be normal table, subtable or STable. +- `condition`: Optional parameter, specifies the data filter condition. If no condition is specified all data will be deleted, so please be cautions to delete data without any condition. The condition used here is only applicable to the first column, i.e. the timestamp column. If the table is a STable, the condition is also applicable to tag columns. + +**More Explanations:** + +The data can't be recovered once deleted, so please be cautious to use the functionality of deleting data. It's better to firstly make sure the data to be deleted using `select` then execute `delete`. + +**Example:** + +`meters` is a STable, in which `groupid` is a tag column of int type. Now we want to delete the data older than 2021-10-01 10:40:00.100 and `groupid` is 1. The SQL for this purpose is like below: + +```sql +delete from meters where ts < '2021-10-01 10:40:00.100' and groupid=1 ; +``` + +The output is: + +``` +Deleted 102000 row(s) from 1020 table(s) (0.421950s) +``` + +It means totally 102,000 rows of data have been deleted from 1,020 sub tables. diff --git a/docs/en/12-taos-sql/10-function.md b/docs/en/12-taos-sql/10-function.md new file mode 100644 index 0000000000000000000000000000000000000000..86ff5a58ce31a357d6e247294ffdac791cb0c032 --- /dev/null +++ b/docs/en/12-taos-sql/10-function.md @@ -0,0 +1,1963 @@ +--- +title: Functions +--- + +## Aggregate Functions + +Aggregate queries are supported in TDengine by the following aggregate functions and selection functions. + +### COUNT + +``` +SELECT COUNT([*|field_name]) FROM tb_name [WHERE clause]; +``` + +**Description**: Get the number of rows or the number of non-null values in a table or a super table. + +**Return value type**: Long integer INT64 + +**Applicable column types**: All + +**Applicable table types**: table, super table, sub table + +**More explanation**: + +- Wildcard (\*) is used to represent all columns. The `COUNT` function is used to get the total number of all rows. +- The number of non-NULL values will be returned if this function is used on a specific column. + +**Examples**: + +``` +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]; +``` + +**Description**: Get the average value of a column in a table or STable + +**Return value type**: Double precision floating number + +**Applicable column types**: Data types except for timestamp, binary, nchar and bool + +**Applicable table types**: table, STable + +**Examples**: + +``` +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; +``` + +**Description**: Time weighted average on a specific column within a time range + +**Return value type**: Double precision floating number + +**Applicable column types**: Data types except for timestamp, binary, nchar and bool + +**Applicable table types**: table, STable + +**More explanations**: + +- Since version 2.1.3.0, function TWA can be used on stable with `GROUP BY`, i.e. timelines generated by `GROUP BY tbname` on a STable. + +### IRATE + +``` +SELECT IRATE(field_name) FROM tb_name WHERE clause; +``` + +**Description**: instantaneous rate on a specific column. The last two samples in the specified time range are used to calculate instantaneous rate. If the last sample value is smaller, then only the last sample value is used instead of the difference between the last two sample values. + +**Return value type**: Double precision floating number + +**Applicable column types**: Data types except for timestamp, binary, nchar and bool + +**Applicable table types**: table, STable + +**More explanations**: + +- Since version 2.1.3.0, function IRATE can be used on stble with `GROUP BY`, i.e. timelines generated by `GROUP BY tbname` on a STable. + +### SUM + +``` +SELECT SUM(field_name) FROM tb_name [WHERE clause]; +``` + +**Description**: The sum of a specific column in a table or STable + +**Return value type**: Double precision floating number or long integer + +**Applicable column types**: Data types except for timestamp, binary, nchar and bool + +**Applicable table types**: table, STable + +**Examples**: + +``` +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]; +``` + +**Description**: Standard deviation of a specific column in a table or STable + +**Return value type**: Double precision floating number + +**Applicable column types**: Data types except for timestamp, binary, nchar and bool + +**Applicable table types**: table, STable (since version 2.0.15.1) + +**Examples**: + +``` +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]; +``` + +**Description**: The linear regression function of the specified column and the timestamp column (primary key), `start_val` is the initial value and `step_val` is the step value. + +**Return value type**: A string in the format of "(slope, intercept)" + +**Applicable column types**: Data types except for timestamp, binary, nchar and bool + +**Applicable table types**: table only + +**Examples**: + +``` +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) +``` + +### MODE + +``` +SELECT MODE(field_name) FROM tb_name [WHERE clause]; +``` + +**Description**:The value which has the highest frequency of occurrence. NULL is returned if there are multiple values which have highest frequency of occurrence. It can't be used on timestamp column or tags. + +**Return value type**:Same as the data type of the column being operated upon + +**Applicable column types**:Data types except for timestamp + +**More explanations**:Considering the number of returned result set is unpredictable, it's suggested to limit the number of unique values to 100,000, otherwise error will be returned. + +**Applicable version**:Since version 2.6.0.0 + +**Examples**: + +``` +taos> select voltage from d002; + voltage | +======================== + 1 | + 1 | + 2 | + 19 | +Query OK, 4 row(s) in set (0.003545s) + +taos> select mode(voltage) from d002; + mode(voltage) | +======================== + 1 | +Query OK, 1 row(s) in set (0.019393s) +``` + +### HYPERLOGLOG + +``` +SELECT HYPERLOGLOG(field_name) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**Description**:The cardinal number of a specific column is returned by using hyperloglog algorithm. + +**Return value type**:Integer + +**Applicable column types**:Any data type + +**More explanations**: The benefit of using hyperloglog algorithm is that the memory usage is under control when the data volume is huge. However, when the data volume is very small, the result may be not accurate, it's recommented to use `select count(data) from (select unique(col) as data from table)` in this case. + +**Applicable versions**:Since version 2.6.0.0 + +**Examples**: + +``` +taos> select dbig from shll; + dbig | +======================== + 1 | + 1 | + 1 | + NULL | + 2 | + 19 | + NULL | + 9 | +Query OK, 8 row(s) in set (0.003755s) + +taos> select hyperloglog(dbig) from shll; + hyperloglog(dbig)| +======================== + 4 | +Query OK, 1 row(s) in set (0.008388s) +``` + +### HISTOGRAM + +``` +SELECT HISTOGRAM(field_name，bin_type, bin_description, normalized) FROM tb_name [WHERE clause]; +``` + +**Description**：Returns count of data points in user-specified ranges. + +**Return value type**：Double or INT64, depends on normalized parameter settings. + +**Applicable column type**：Numerical types. + +**Applicable versions**：Since version 2.6.0.0. + +**Applicable table types**: table, STable + +**Explanations**： + +1. bin_type: parameter to indicate the bucket type, valid inputs are: "user_input", "linear_bin", "log_bin"。 +2. bin_description: parameter to describe how to generate buckets，can be in the following JSON formats for each bin_type respectively: + + - "user_input": "[1, 3, 5, 7]": User specified bin values. + + - "linear_bin": "{"start": 0.0, "width": 5.0, "count": 5, "infinity": true}" + "start" - bin starting point. + "width" - bin offset. + "count" - number of bins generated. + "infinity" - whether to add（-inf, inf）as start/end point in generated set of bins. + The above "linear_bin" descriptor generates a set of bins: [-inf, 0.0, 5.0, 10.0, 15.0, 20.0, +inf]. + + - "log_bin": "{"start":1.0, "factor": 2.0, "count": 5, "infinity": true}" + "start" - bin starting point. + "factor" - exponential factor of bin offset. + "count" - number of bins generated. + "infinity" - whether to add（-inf, inf）as start/end point in generated range of bins. + The above "log_bin" descriptor generates a set of bins:[-inf, 1.0, 2.0, 4.0, 8.0, 16.0, +inf]. + +3. normalized: setting to 1/0 to turn on/off result normalization. + +**Example**： + +```mysql +taos> SELECT HISTOGRAM(voltage, "user_input", "[1,3,5,7]", 1) FROM meters; + histogram(voltage, "user_input", "[1,3,5,7]", 1) | + ======================================================= + {"lower_bin":1, "upper_bin":3, "count":0.333333} | + {"lower_bin":3, "upper_bin":5, "count":0.333333} | + {"lower_bin":5, "upper_bin":7, "count":0.333333} | + Query OK, 3 row(s) in set (0.004273s) + +taos> SELECT HISTOGRAM(voltage, 'linear_bin', '{"start": 1, "width": 3, "count": 3, "infinity": false}', 0) FROM meters; + histogram(voltage, 'linear_bin', '{"start": 1, "width": 3, " | + =================================================================== + {"lower_bin":1, "upper_bin":4, "count":3} | + {"lower_bin":4, "upper_bin":7, "count":3} | + {"lower_bin":7, "upper_bin":10, "count":3} | + Query OK, 3 row(s) in set (0.004887s) + +taos> SELECT HISTOGRAM(voltage, 'log_bin', '{"start": 1, "factor": 3, "count": 3, "infinity": true}', 0) FROM meters; + histogram(voltage, 'log_bin', '{"start": 1, "factor": 3, "count" | + =================================================================== + {"lower_bin":-inf, "upper_bin":1, "count":3} | + {"lower_bin":1, "upper_bin":3, "count":2} | + {"lower_bin":3, "upper_bin":9, "count":6} | + {"lower_bin":9, "upper_bin":27, "count":3} | + {"lower_bin":27, "upper_bin":inf, "count":1} | +``` + +### ELAPSED + +```mysql +SELECT ELAPSED(field_name[, time_unit]) FROM { tb_name | stb_name } [WHERE clause] [INTERVAL(interval [, offset]) [SLIDING sliding]]; +``` + +**Description**：`elapsed` function can be used to calculate the continuous time length in which there is valid data. If it's used with `INTERVAL` clause, the returned result is the calcualted time length within each time window. If it's used without `INTERVAL` caluse, the returned result is the calculated time length within the specified time range. Please be noted that the return value of `elapsed` is the number of `time_unit` in the calculated time length. + +**Return value type**：Double + +**Applicable Column type**：Timestamp + +**Applicable versions**：Sicne version 2.6.0.0 + +**Applicable tables**: table, STable, outter in nested query + +**Explanations**： +- `field_name` parameter can only be the first column of a table, i.e. timestamp primary key. +- The minimum value of `time_unit` is the time precision of the database. If `time_unit` is not specified, the time precision of the database is used as the default ime unit. +- It can be used with `INTERVAL` to get the time valid time length of each time window. Please be noted that the return value is same as the time window for all time windows except for the first and the last time window. +- `order by asc/desc` has no effect on the result. +- `group by tbname` must be used together when `elapsed` is used against a STable. +- `group by` must NOT be used together when `elapsed` is used against a table or sub table. +- When used in nested query, it's only applicable when the inner query outputs an implicit timestamp column as the primary key. For example, `select elapsed(ts) from (select diff(value) from sub1)` is legal usage while `select elapsed(ts) from (select * from sub1)` is not. +- It can't be used with `leastsquares`, `diff`, `derivative`, `top`, `bottom`, `last_row`, `interp`. + +## Selection Functions + +When any select function is used, timestamp column or tag columns including `tbname` can be specified to show that the selected value are from which rows. + +### MIN + +``` +SELECT MIN(field_name) FROM {tb_name | stb_name} [WHERE clause]; +``` + +**Description**: The minimum value of a specific column in a table or STable + +**Return value type**: Same as the data type of the column being operated upon + +**Applicable column types**: Data types except for timestamp, binary, nchar and bool + +**Applicable table types**: table, STable + +**Examples**: + +``` +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]; +``` + +**Description**: The maximum value of a specific column of a table or STable + +**Return value type**: Same as the data type of the column being operated upon + +**Applicable column types**: Data types except for timestamp, binary, nchar and bool + +**Applicable table types**: table, STable + +**Examples**: + +``` +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]; +``` + +**Description**: The first non-null value of a specific column in a table or STable + +**Return value type**: Same as the column being operated upon + +**Applicable column types**: Any data type + +**Applicable table types**: table, STable + +**More explanations**: + +- FIRST(\*) can be used to get the first non-null value of all columns +- NULL will be returned if all the values of the specified column are all NULL +- A result will NOT be returned if all the columns in the result set are all NULL + +**Examples**: + +``` +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]; +``` + +**Description**: The last non-NULL value of a specific column in a table or STable + +**Return value type**: Same as the column being operated upon + +**Applicable column types**: Any data type + +**Applicable table types**: table, STable + +**More explanations**: + +- LAST(\*) can be used to get the last non-NULL value of all columns +- If the values of a column in the result set are all NULL, NULL is returned for that column; if all columns in the result are all NULL, no result will be returned. +- When it's used on a STable, if there are multiple values with the timestamp in the result set, one of them will be returned randomly and it's not guaranteed that the same value is returned if the same query is run multiple times. + +**Examples**: + +``` +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]; +``` + +**Description**: The greatest _k_ values of a specific column in a table or STable. If a value has multiple occurrences in the column but counting all of them in will exceed the upper limit _k_, then a part of them will be returned randomly. + +**Return value type**: Same as the column being operated upon + +**Applicable column types**: Data types except for timestamp, binary, nchar and bool + +**Applicable table types**: table, STable + +**More explanations**: + +- _k_ must be in range [1,100] +- The timestamp associated with the selected values are returned too +- Can't be used with `FILL` + +**Examples**: + +``` +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]; +``` + +**Description**: The least _k_ values of a specific column in a table or STable. If a value has multiple occurrences in the column but counting all of them in will exceed the upper limit _k_, then a part of them will be returned randomly. + +**Return value type**: Same as the column being operated upon + +**Applicable column types**: Data types except for timestamp, binary, nchar and bool + +**Applicable table types**: table, STable + +**More explanations**: + +- _k_ must be in range [1,100] +- The timestamp associated with the selected values are returned too +- Can't be used with `FILL` + +**Examples**: + +``` +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]; +``` + +**Description**: The value whose rank in a specific column matches the specified percentage. If such a value matching the specified percentage doesn't exist in the column, an interpolation value will be returned. + +**Return value type**: Double precision floating point + +**Applicable column types**: Data types except for timestamp, binary, nchar and bool + +**Applicable table types**: table + +**More explanations**: _P_ is in range [0,100], when _P_ is 0, the result is same as using function MIN; when _P_ is 100, the result is same as function MAX. + +**Examples**: + +``` +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] +``` + +**Description**: Similar to `PERCENTILE`, but a simulated result is returned + +**Return value type**: Double precision floating point + +**Applicable column types**: Data types except for timestamp, binary, nchar and bool + +**Applicable table types**: table, STable + +**More explanations** + +- _P_ is in range [0,100], when _P_ is 0, the result is same as using function MIN; when _P_ is 100, the result is same as function MAX. +- **algo_type** can only be input as `default` or `t-digest`, if it's not specified `default` will be used, i.e. `apercentile(column_name, 50)` is same as `apercentile(column_name, 50, "default")`. +- When `t-digest` is used, `t-digest` sampling is used to calculate. It can be used from version 2.2.0.0. + +**Nested query**: It can be used in both the outer query and inner query in a nested query. + +``` +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 }; +``` + +**Description**: The last row of a table or STable + +**Return value type**: Same as the column being operated upon + +**Applicable column types**: Any data type + +**Applicable table types**: table, STable + +**More explanations**: + +- When it's used against a STable, multiple rows with the same and largest timestamp may exist, in this case one of them is returned randomly and it's not guaranteed that the result is same if the query is run multiple times. +- Can't be used with `INTERVAL`. + +**Examples**: + +``` + 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 [Since version 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})]; +``` + +**Description**: The value that matches the specified timestamp range is returned, if existing; or an interpolation value is returned. + +**Return value type**: Same as the column being operated upon + +**Applicable column types**: Numeric data types + +**Applicable table types**: table, STable, nested query + +**More explanations** + +- `INTERP` is used to get the value that matches the specified time slice from a column. If no such value exists an interpolation value will be returned based on `FILL` parameter. +- The input data of `INTERP` is the value of the specified column and a `where` clause can be used to filter the original data. If no `where` condition is specified then all original data is the input. +- The output time range of `INTERP` is specified by `RANGE(timestamp1,timestamp2)` parameter, with timestamp1<=timestamp2. timestamp1 is the starting point of the output time range and must be specified. timestamp2 is the ending point of the output time range and must be specified. If `RANGE` is not specified, then the timestamp of the first row that matches the filter condition is treated as timestamp1, the timestamp of the last row that matches the filter condition is treated as timestamp2. +- The number of rows in the result set of `INTERP` is determined by the parameter `EVERY`. Starting from timestamp1, one interpolation is performed for every time interval specified `EVERY` parameter. If `EVERY` parameter is not used, the time windows will be considered as no ending timestamp, i.e. there is only one time window from timestamp1. +- Interpolation is performed based on `FILL` parameter. No interpolation is performed if `FILL` is not used, that means either the original data that matches is returned or nothing is returned. +- `INTERP` can only be used to interpolate in single timeline. So it must be used with `group by tbname` when it's used on a STable. It can't be used with `GROUP BY` when it's used in the inner query of a nested query. +- The result of `INTERP` is not influenced by `ORDER BY TIMESTAMP`, which impacts the output order only.. + +**Examples**: Based on the `meters` schema used throughout the documents + +- Single point linear interpolation between "2017-07-14 18:40:00" and "2017-07-14 18:40:00: + +``` + taos> SELECT INTERP(current) FROM t1 RANGE('2017-7-14 18:40:00','2017-7-14 18:40:00') FILL(LINEAR); +``` + +- Get original data every 5 seconds, no interpolation, between "2017-07-14 18:00:00" and "2017-07-14 19:00:00: + +``` + taos> SELECT INTERP(current) FROM t1 RANGE('2017-7-14 18:00:00','2017-7-14 19:00:00') EVERY(5s); +``` + +- Linear interpolation every 5 seconds between "2017-07-14 18:00:00" and "2017-07-14 19:00:00: + +``` + taos> SELECT INTERP(current) FROM t1 RANGE('2017-7-14 18:00:00','2017-7-14 19:00:00') EVERY(5s) FILL(LINEAR); +``` + +- Backward interpolation every 5 seconds + +``` + taos> SELECT INTERP(current) FROM t1 EVERY(5s) FILL(NEXT); +``` + +- Linear interpolation every 5 seconds between "2017-07-14 17:00:00" and "2017-07-14 20:00:00" + +``` + 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 [Since version 2.0.15.0] + +``` +SELECT INTERP(field_name) FROM { tb_name | stb_name } WHERE ts='timestamp' [FILL ({ VALUE | PREV | NULL | LINEAR | NEXT})]; +``` + +**Description**: The value of a specific column that matches the specified time slice + +**Return value type**: Same as the column being operated upon + +**Applicable column types**: Numeric data type + +**Applicable table types**: table, STable + +**More explanations**: + +- Time slice must be specified. If there is no data matching the specified time slice, interpolation is performed based on `FILL` parameter. Conditions such as tags or `tbname` can be used `Where` clause can be used to filter data. +- The timestamp specified must be within the time range of the data rows of the table or STable. If it is beyond the valid time range, nothing is returned even with `FILL` parameter. +- `INTERP` can be used to query only single time point once. `INTERP` can be used with `EVERY` to get the interpolation value every time interval. +- **Examples**: + +``` + 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) +``` + +If there is no data corresponding to the specified timestamp, an interpolation value is returned if interpolation policy is specified by `FILL` parameter; or nothing is returned. + +``` + 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) +``` + +Interpolation is performed every 5 milliseconds between `['2017-7-14 18:40:00', '2017-7-14 18:40:00.014']` + +``` + 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) +``` + +### TAIL + +``` +SELECT TAIL(field_name, k, offset_val) FROM {tb_name | stb_name} [WHERE clause]; +``` + +**Description**: The next _k_ rows are returned after skipping the last `offset_val` rows, NULL values are not ignored. `offset_val` is optional parameter. When it's not specified, the last _k_ rows are returned. When `offset_val` is used, the effect is same as `order by ts desc LIMIT k OFFSET offset_val`. + +**Parameter value range**: k: [1,100] offset_val: [0,100] + +**Return value type**: Same as the column being operated upon + +**Applicable column types**: Any data type except form timestamp, i.e. the primary key + +**Applicable versions**: Since version 2.6.0.0 + +**Examples**: + +``` +taos> select ts,dbig from tail2; + ts | dbig | +================================================== +2021-10-15 00:31:33.000 | 1 | +2021-10-17 00:31:31.000 | NULL | +2021-12-24 00:31:34.000 | 2 | +2022-01-01 08:00:05.000 | 19 | +2022-01-01 08:00:06.000 | NULL | +2022-01-01 08:00:07.000 | 9 | +Query OK, 6 row(s) in set (0.001952s) + +taos> select tail(dbig,2,2) from tail2; +ts | tail(dbig,2,2) | +================================================== +2021-12-24 00:31:34.000 | 2 | +2022-01-01 08:00:05.000 | 19 | +Query OK, 2 row(s) in set (0.002307s) +``` + +### UNIQUE + +``` +SELECT UNIQUE(field_name) FROM {tb_name | stb_name} [WHERE clause]; +``` + +**Description**: The values that occur the first time in the specified column. The effect is similar to `distinct` keyword, but it can also be used to match tags or timestamp. + +**Return value type**: Same as the column or tag being operated upon + +**Applicable column types**: Any data types except for timestamp + +**Applicable versions**: Since version 2.6.0.0 + +**More explanations**: + +- It can be used against table or STable, but can't be used together with time window, like `interval`, `state_window` or `session_window` . +- Considering the number of result sets is unpredictable, it's suggested to limit the distinct values under 100,000 to control the memory usage, otherwise error will be returned. + +**Examples**: + +``` +taos> select ts,voltage from unique1; + ts | voltage | +================================================== +2021-10-17 00:31:31.000 | 1 | +2022-01-24 00:31:31.000 | 1 | +2021-10-17 00:31:31.000 | 1 | +2021-12-24 00:31:31.000 | 2 | +2022-01-01 08:00:01.000 | 19 | +2021-10-17 00:31:31.000 | NULL | +2022-01-01 08:00:02.000 | NULL | +2022-01-01 08:00:03.000 | 9 | +Query OK, 8 row(s) in set (0.003018s) + +taos> select unique(voltage) from unique1; +ts | unique(voltage) | +================================================== +2021-10-17 00:31:31.000 | 1 | +2021-10-17 00:31:31.000 | NULL | +2021-12-24 00:31:31.000 | 2 | +2022-01-01 08:00:01.000 | 19 | +2022-01-01 08:00:03.000 | 9 | +Query OK, 5 row(s) in set (0.108458s) +``` + +## Scalar functions + +### DIFF + +```sql +SELECT {DIFF(field_name, ignore_negative) | DIFF(field_name)} FROM tb_name [WHERE clause]; +``` + +**Description**: The different of each row with its previous row for a specific column. `ignore_negative` can be specified as 0 or 1, the default value is 1 if it's not specified. `1` means negative values are ignored. + +**Return value type**: Same as the column being operated upon + +**Applicable column types**: Data types except for timestamp, binary, nchar and bool + +**Applicable table types**: table, STable + +**More explanations**: + +- The number of result rows is the number of rows subtracted by one, no output for the first row +- Since version 2.1.30, `DIFF` can be used on STable with `GROUP by tbname` +- Since version 2.6.0, `ignore_negative` parameter is supported + +**Examples**: + +```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]; +``` + +**Description**: The derivative of a specific column. The time rage can be specified by parameter `time_interval`, the minimum allowed time range is 1 second (1s); the value of `ignore_negative` can be 0 or 1, 1 means negative values are ignored. + +**Return value type**: Double precision floating point + +**Applicable column types**: Data types except for timestamp, binary, nchar and bool + +**Applicable table types**: table, STable + +**More explanations**: + +- It is available from version 2.1.3.0, the number of result rows is the number of total rows in the time range subtracted by one, no output for the first row. +- It can be used together with `GROUP BY tbname` against a STable. + +**Examples**: + +``` +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]; +``` + +**Description**: The difference between the max and the min of a specific column + +**Return value type**: Double precision floating point + +**Applicable column types**: Data types except for binary, nchar, and bool + +**Applicable table types**: table, STable + +**More explanations**: Can be used on a column of TIMESTAMP type, the result is the time range size. + +**Examples**: + +``` +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]; +``` + +**Description**: The rounded up value of a specific column + +**Return value type**: Same as the column being used + +**Applicable data types**: Data types except for timestamp, binary, nchar, bool + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and outer query + +**More explanations**: + +- Can't be used on any tags of any type +- Arithmetic operation can be performed on the result of `ceil` function +- Can't be used with aggregate functions + +### FLOOR + +``` +SELECT FLOOR(field_name) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**Description**: The rounded down value of a specific column + +**More explanations**: The restrictions are same as those of the `CEIL` function. + +### ROUND + +``` +SELECT ROUND(field_name) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**Description**: The rounded value of a specific column. + +**More explanations**: The restrictions are same as `CEIL` function. + +### CSUM + +```sql + SELECT CSUM(field_name) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: The cumulative sum of each row for a specific column. The number of output rows is same as that of the input rows. + +**Return value type**: Long integer for integers; Double for floating points. Timestamp is returned for each row. + +**Applicable data types**: Data types except for timestamp, binary, nchar, and bool + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and Outer query + +**More explanations**: + +- Can't be used on tags when it's used on STable +- Arithmetic operation can't be performed on the result of `csum` function +- Can only be used with aggregate functions +- `Group by tbname` must be used together on a STable to force the result on a single timeline + +**Applicable versions**: Since 2.3.0.x + +### MAVG + +```sql + SELECT MAVG(field_name, K) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: The moving average of continuous _k_ values of a specific column. If the number of input rows is less than _k_, nothing is returned. The applicable range of _k_ is [1,1000]. + +**Return value type**: Double precision floating point + +**Applicable data types**: Data types except for timestamp, binary, nchar, and bool + +**Applicable nested query**: Inner query and Outer query + +**Applicable table types**: table, STable + +**More explanations**: + +- Arithmetic operation can't be performed on the result of `MAVG`. +- Can only be used with data columns, can't be used with tags. +- Can't be used with aggregate functions. +- Must be used with `GROUP BY tbname` when it's used on a STable to force the result on each single timeline. + +**Applicable versions**: Since 2.3.0.x + +### SAMPLE + +```sql + SELECT SAMPLE(field_name, K) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: _k_ sampling values of a specific column. The applicable range of _k_ is [1,10000] + +**Return value type**: Same as the column being operated plus the associated timestamp + +**Applicable data types**: Any data type except for tags of STable + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and Outer query + +**More explanations**: + +- Arithmetic operation can't be operated on the result of `SAMPLE` function +- Must be used with `Group by tbname` when it's used on a STable to force the result on each single timeline + +**Applicable versions**: Since 2.3.0.x + +### ASIN + +```sql +SELECT ASIN(field_name) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: The anti-sine of a specific column + +**Return value type**: Double if the input value is not NULL; or NULL if the input value is NULL + +**Applicable data types**: Data types except for timestamp, binary, nchar, bool + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and Outer query + +**Applicable versions**: From 2.6.0.0 + +**More explanations**: + +- Can't be used with tags +- Can't be used with aggregate functions + +### ACOS + +```sql +SELECT ACOS(field_name) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: The anti-cosine of a specific column + +**Return value type**: Double if the input value is not NULL; or NULL if the input value is NULL + +**Applicable data types**: Data types except for timestamp, binary, nchar, bool + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and Outer query + +**Applicable versions**: From 2.6.0.0 + +**More explanations**: + +- Can't be used with tags +- Can't be used with aggregate functions + +### ATAN + +```sql +SELECT ATAN(field_name) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: anti-tangent of a specific column + +**Description**: The anti-cosine of a specific column + +**Return value type**: Double if the input value is not NULL; or NULL if the input value is NULL + +**Applicable data types**: Data types except for timestamp, binary, nchar, bool + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and Outer query + +**Applicable versions**: From 2.6.0.0 + +**More explanations**: + +- Can't be used with tags +- Can't be used with aggregate functions + +### SIN + +```sql +SELECT SIN(field_name) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: The sine of a specific column + +**Description**: The anti-cosine of a specific column + +**Return value type**: Double if the input value is not NULL; or NULL if the input value is NULL + +**Applicable data types**: Data types except for timestamp, binary, nchar, bool + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and Outer query + +**Applicable versions**: From 2.6.0.0 + +**More explanations**: + +- Can't be used with tags +- Can't be used with aggregate functions + +### COS + +```sql +SELECT COS(field_name) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: The cosine of a specific column + +**Description**: The anti-cosine of a specific column + +**Return value type**: Double if the input value is not NULL; or NULL if the input value is NULL + +**Applicable data types**: Data types except for timestamp, binary, nchar, bool + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and Outer query + +**Applicable versions**: From 2.6.0.0 + +**More explanations**: + +- Can't be used with tags +- Can't be used with aggregate functions + +### TAN + +```sql +SELECT TAN(field_name) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: The tangent of a specific column + +**Description**: The anti-cosine of a specific column + +**Return value type**: Double if the input value is not NULL; or NULL if the input value is NULL + +**Applicable data types**: Data types except for timestamp, binary, nchar, bool + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and Outer query + +**Applicable versions**: From 2.6.0.0 + +**More explanations**: + +- Can't be used with tags +- Can't be used with aggregate functions + +### POW + +```sql +SELECT POW(field_name, power) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: The power of a specific column with `power` as the index + +**Return value type**: Double if the input value is not NULL; or NULL if the input value is NULL + +**Applicable data types**: Data types except for timestamp, binary, nchar, bool + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and Outer query + +**Applicable versions**: From 2.6.0.0 + +**More explanations**: + +- Can't be used with tags +- Can't be used with aggregate functions + +### LOG + +```sql +SELECT LOG(field_name, base) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: The log of a specific with `base` as the radix + +**Return value type**: Double if the input value is not NULL; or NULL if the input value is NULL + +**Applicable data types**: Data types except for timestamp, binary, nchar, bool + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and Outer query + +**Applicable versions**: From 2.6.0.0 + +**More explanations**: + +- Can't be used with tags +- Can't be used with aggregate functions + +### ABS + +```sql +SELECT ABS(field_name) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: The absolute of a specific column + +**Return value type**: UBIGINT if the input value is integer; DOUBLE if the input value is FLOAT/DOUBLE + +**Applicable data types**: Data types except for timestamp, binary, nchar, bool + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and Outer query + +**Applicable versions**: From 2.6.0.0 + +**More explanations**: + +- Can't be used with tags +- Can't be used with aggregate functions + +### SQRT + +```sql +SELECT SQRT(field_name) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: The square root of a specific column + +**Return value type**: Double if the input value is not NULL; or NULL if the input value is NULL + +**Applicable data types**: Data types except for timestamp, binary, nchar, bool + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and Outer query + +**Applicable versions**: From 2.6.0.0 + +**More explanations**: + +- Can't be used with tags +- Can't be used with aggregate functions + +### CAST + +```sql +SELECT CAST(expression AS type_name) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: It's used for type casting. The input parameter `expression` can be data columns, constants, scalar functions or arithmetic between them. Can't be used with tags, and can only be used in `select` clause. + +**Return value type**: The type specified by parameter `type_name` + +**Applicable data types**: + +- Parameter `expression` can be any data type except for JSON, more specifically it can be any of BOOL/TINYINT/SMALLINT/INT/BIGINT/FLOAT/DOUBLE/BINARY(M)/TIMESTAMP/NCHAR(M)/TINYINT UNSIGNED/SMALLINT UNSIGNED/INT UNSIGNED/BIGINT UNSIGNED +- The output data type specified by `type_name` can only be one of BIGINT/BINARY(N)/TIMESTAMP/NCHAR(N)/BIGINT UNSIGNED + +**Applicable versions**: From 2.6.0.0 + +**More explanations**: + +- Error will be reported for unsupported type casting +- NULL will be returned if the input value is NULL +- Some values of some supported data types may not be casted, below are known issues: + 1）When casting BINARY/NCHAR to BIGINT/BIGINT UNSIGNED, some characters may be treated as illegal, for example "a" may be converted to 0. + 2）There may be overflow when casting singed integer or TIMESTAMP to unsigned BIGINT + 3）There may be overflow when casting unsigned BIGINT to BIGINT + 4）There may be overflow when casting FLOAT/DOUBLE to BIGINT or UNSIGNED BIGINT + +### CONCAT + +```sql +SELECT CONCAT(str1|column1, str2|column2, ...) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: The concatenation result of two or more strings, the number of strings to be concatenated is at least 2 and at most 8 + +**Return value type**: Same as the columns being operated, BINARY or NCHAR; or NULL if all the input are NULL + +**Applicable data types**: The input data must be in either all BINARY or in all NCHAR; can't be used on tag columns + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and Outer query + +**Applicable versions**: From 2.6.0.0 + +### CONCAT_WS + +``` +SELECT CONCAT_WS(separator, str1|column1, str2|column2, ...) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: The concatenation result of two or more strings with separator, the number of strings to be concatenated is at least 3 and at most 9 + +**Return value type**: Same as the columns being operated, BINARY or NCHAR; or NULL if all the input are NULL + +**Applicable data types**: The input data must be in either all BINARY or in all NCHAR; can't be used on tag columns + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and Outer query + +**Applicable versions**: From 2.6.0.0 + +**More explanations**: + +- If the value of `separator` is NULL, the output is NULL. If the value of `separator` is not NULL but other input are all NULL, the output is empty string. + +### LENGTH + +``` +SELECT LENGTH(str|column) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: The length in bytes of a string + +**Return value type**: Integer + +**Applicable data types**: BINARY or NCHAR, can't be used on tags + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and Outer query + +**Applicable versions**: From 2.6.0.0 + +**More explanations** + +- If the input value is NULL, the output is NULL too + +### CHAR_LENGTH + +``` +SELECT CHAR_LENGTH(str|column) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: The length in number of characters of a string + +**Return value type**: Integer + +**Applicable data types**: BINARY or NCHAR, can't be used on tags + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and Outer query + +**Applicable versions**: From 2.6.0.0 + +**More explanations** + +- If the input value is NULL, the output is NULL too + +### LOWER + +``` +SELECT LOWER(str|column) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: Convert the input string to lower case + +**Return value type**: Same as input + +**Applicable data types**: BINARY or NCHAR, can't be used on tags + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and Outer query + +**Applicable versions**: From 2.6.0.0 + +**More explanations** + +- If the input value is NULL, the output is NULL too + +### UPPER + +``` +SELECT UPPER(str|column) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: Convert the input string to upper case + +**Return value type**: Same as input + +**Applicable data types**: BINARY or NCHAR, can't be used on tags + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and Outer query + +**Applicable versions**: From 2.6.0.0 + +**More explanations** + +- If the input value is NULL, the output is NULL too + +### LTRIM + +``` +SELECT LTRIM(str|column) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: Remove the left leading blanks of a string + +**Return value type**: Same as input + +**Applicable data types**: BINARY or NCHAR, can't be used on tags + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and Outer query + +**Applicable versions**: From 2.6.0.0 + +**More explanations** + +- If the input value is NULL, the output is NULL too + +### RTRIM + +``` +SELECT RTRIM(str|column) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: Remove the right tailing blanks of a string + +**Return value type**: Same as input + +**Applicable data types**: BINARY or NCHAR, can't be used on tags + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and Outer query + +**Applicable versions**: From 2.6.0.0 + +**More explanations** + +- If the input value is NULL, the output is NULL too + +### SUBSTR + +``` +SELECT SUBSTR(str,pos[,len]) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: The sub-string starting from `pos` with length of `len` from the original string `str` + +**Return value type**: Same as input + +**Applicable data types**: BINARY or NCHAR, can't be used on tags + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and Outer query + +**Applicable versions**: From 2.6.0.0 + +**More explanations**: + +- If the input is NULL, the output is NULL +- Parameter `pos` can be an positive or negative integer; If it's positive, the starting position will be counted from the beginning of the string; if it's negative, the starting position will be counted from the end of the string. +- If `len` is not specified, it means from `pos` to the end. + +### Arithmetic Operations + +``` +SELECT field_name [+|-|*|/|%][Value|field_name] FROM { tb_name | stb_name } [WHERE clause]; +``` + +**Description**: The sum, difference, product, quotient, or remainder between one or more columns + +**Return value type**: Double precision floating point + +**Applicable column types**: Data types except for timestamp, binary, nchar, bool + +**Applicable table types**: table, STable + +**More explanations**: + +- Arithmetic operations can be performed on two or more columns, Parentheses `()` can be used to control the order of precedence. +- NULL doesn't participate in the operation i.e. if one of the operands is NULL then result is NULL. + +**Examples**: + +``` +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) +``` + +### STATECOUNT + +``` +SELECT STATECOUNT(field_name, oper, val) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**Description**: The number of continuous rows satisfying the specified conditions for a specific column. The result is shown as an extra column for each row. If the specified condition is evaluated as true, the number is increased by 1; otherwise the number is reset to -1. If the input value is NULL, then the corresponding row is skipped. + +**Applicable parameter values**: + +- oper : Can be one of LT (lower than), GT (greater than), LE (lower than or euqal to), GE (greater than or equal to), NE (not equal to), EQ (equal to), the value is case insensitive +- val ： Numeric types + +**Return value type**: Integer + +**Applicable data types**: Data types excpet for timestamp, binary, nchar, bool + +**Applicable table types**: table, STable + +**Applicable nested query**: Outer query only + +**Applicable versions**: From 2.6.0.0 + +**More explanations**: + +- Must be used together with `GROUP BY tbname` when it's used on a STable to force the result into each single timeline] +- Can't be used with window operation, like interval/state_window/session_window + +**Examples**: + +``` +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) +``` + +### STATEDURATION + +``` +SELECT stateDuration(field_name, oper, val, unit) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**Description**: The length of time range in which all rows satisfy the specified condition for a specific column. The result is shown as an extra column for each row. The length for the first row that satisfies the condition is 0. Next, if the condition is evaluated as true for a row, the time interval between current row and its previous row is added up to the time range; otherwise the time range length is reset to -1. If the value of the column is NULL, the corresponding row is skipped. + +**Applicable parameter values**: + +- oper : Can be one of LT (lower than), GT (greater than), LE (lower than or euqal to), GE (greater than or equal to), NE (not equal to), EQ (equal to), the value is case insensitive +- val ： Numeric types +- unit: The unit of time interval, can be [1s, 1m, 1h], default is 1s + +**Return value type**: Integer + +**Applicable data types**: Data types excpet for timestamp, binary, nchar, bool + +**Applicable table types**: table, STable + +**Applicable nested query**: Outer query only + +**Applicable versions**: From 2.6.0.0 + +**More explanations**: + +- Must be used together with `GROUP BY tbname` when it's used on a STable to force the result into each single timeline] +- Can't be used with window operation, like interval/state_window/session_window + +**Examples**: + +``` +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.002407s) + +taos> select stateDuration(dbig,GT,2) from statef2; +ts | dbig | stateduration(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 | 0 | +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.002613s) +``` + +## Time Functions + +Since version 2.6.0.0, below time related functions can be used in TDengine. + +### NOW + +```sql +SELECT NOW() FROM { tb_name | stb_name } [WHERE clause]; +SELECT select_expr FROM { tb_name | stb_name } WHERE ts_col cond_operatior NOW(); +INSERT INTO tb_name VALUES (NOW(), ...); +``` + +**Description**: The current time of the client side system + +**Return value type**: TIMESTAMP + +**Applicable column types**: TIMESTAMP only + +**Applicable table types**: table, STable + +**More explanations**: + +- Add and Subtract operation can be performed, for example NOW() + 1s, the time unit can be: + b(nanosecond), u(microsecond), a(millisecond)), s(second), m(minute), h(hour), d(day), w(week) +- The precision of the returned timestamp is same as the precision set for the current data base in use + +**Examples**: + +```sql +taos> SELECT NOW() FROM meters; + now() | +========================== + 2022-02-02 02:02:02.456 | +Query OK, 1 row(s) in set (0.002093s) + +taos> SELECT NOW() + 1h FROM meters; + now() + 1h | +========================== + 2022-02-02 03:02:02.456 | +Query OK, 1 row(s) in set (0.002093s) + +taos> SELECT COUNT(voltage) FROM d1001 WHERE ts < NOW(); + count(voltage) | +============================= + 5 | +Query OK, 5 row(s) in set (0.004475s) + +taos> INSERT INTO d1001 VALUES (NOW(), 10.2, 219, 0.32); +Query OK, 1 of 1 row(s) in database (0.002210s) +``` + +### TODAY + +```sql +SELECT TODAY() FROM { tb_name | stb_name } [WHERE clause]; +SELECT select_expr FROM { tb_name | stb_name } WHERE ts_col cond_operatior TODAY()]; +INSERT INTO tb_name VALUES (TODAY(), ...); +``` + +**Description**: The timestamp of 00:00:00 of the client side system + +**Return value type**: TIMESTAMP + +**Applicable column types**: TIMESTAMP only + +**Applicable table types**: table, STable + +**More explanations**: + +- Add and Subtract operation can be performed, for example NOW() + 1s, the time unit can be: + b(nanosecond), u(microsecond), a(millisecond)), s(second), m(minute), h(hour), d(day), w(week) +- The precision of the returned timestamp is same as the precision set for the current data base in use + +**Examples**: + +```sql +taos> SELECT TODAY() FROM meters; + today() | +========================== + 2022-02-02 00:00:00.000 | +Query OK, 1 row(s) in set (0.002093s) + +taos> SELECT TODAY() + 1h FROM meters; + today() + 1h | +========================== + 2022-02-02 01:00:00.000 | +Query OK, 1 row(s) in set (0.002093s) + +taos> SELECT COUNT(voltage) FROM d1001 WHERE ts < TODAY(); + count(voltage) | +============================= + 5 | +Query OK, 5 row(s) in set (0.004475s) + +taos> INSERT INTO d1001 VALUES (TODAY(), 10.2, 219, 0.32); +Query OK, 1 of 1 row(s) in database (0.002210s) +``` + +### TIMEZONE + +```sql +SELECT TIMEZONE() FROM { tb_name | stb_name } [WHERE clause]; +``` + +**Description**: The timezone of the client side system + +**Return value type**: BINARY + +**Applicable column types**: None + +**Applicable table types**: table, STable + +**Examples**: + +```sql +taos> SELECT TIMEZONE() FROM meters; + timezone() | +================================= + UTC (UTC, +0000) | +Query OK, 1 row(s) in set (0.002093s) +``` + +### TO_ISO8601 + +```sql +SELECT TO_ISO8601(ts_val | ts_col) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**Description**: The ISO8601 date/time format converted from a UNIX timestamp, plus the timezone of the client side system + +**Return value type**: BINARY + +**Applicable column types**: TIMESTAMP, constant or a column + +**Applicable table types**: table, STable + +**More explanations**: + +- If the input is UNIX timestamp constant, the precision of the returned value is determined by the digits of the input timestamp +- If the input is a column of TIMESTAMP type, The precision of the returned value is same as the precision set for the current data base in use + +**Examples**: + +```sql +taos> SELECT TO_ISO8601(1643738400) FROM meters; + to_iso8601(1643738400) | +============================== + 2022-02-02T02:00:00+0800 | + +taos> SELECT TO_ISO8601(ts) FROM meters; + to_iso8601(ts) | +============================== + 2022-02-02T02:00:00+0800 | + 2022-02-02T02:00:00+0800 | + 2022-02-02T02:00:00+0800 | +``` + +### TO_UNIXTIMESTAMP + +```sql +SELECT TO_UNIXTIMESTAMP(datetime_string | ts_col) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**Description**: UNIX timestamp converted from a string of date/time format + +**Return value type**: Long integer + +**Applicable column types**: Constant or column of BINARY/NCHAR + +**Applicable table types**: table, STable + +**More explanations**: + +- The input string must be compatible with ISO8601/RFC3339 standard, 0 will be returned if the string can't be converted +- The precision of the returned timestamp is same as the precision set for the current data base in use + +**Examples**: + +```sql +taos> SELECT TO_UNIXTIMESTAMP("2022-02-02T02:00:00.000Z") FROM meters; +to_unixtimestamp("2022-02-02T02:00:00.000Z") | +============================================== + 1643767200000 | + +taos> SELECT TO_UNIXTIMESTAMP(col_binary) FROM meters; + to_unixtimestamp(col_binary) | +======================================== + 1643767200000 | + 1643767200000 | + 1643767200000 | +``` + +### TIMETRUNCATE + +```sql +SELECT TIMETRUNCATE(ts_val | datetime_string | ts_col, time_unit) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**Description**: Truncate the input timestamp with unit specified by `time_unit` + +**Return value type**: TIMESTAMP + +**Applicable column types**: UNIX timestamp constant, string constant of date/time format, or a column of timestamp + +**Applicable table types**: table, STable + +**More explanations**: + +- Time unit specified by `time_unit` can be: + 1u(microsecond),1a(millisecond),1s(second),1m(minute),1h(hour),1d(day). +- The precision of the returned timestamp is same as the precision set for the current data base in use + +**Examples**: + +```sql +taos> SELECT TIMETRUNCATE(1643738522000, 1h) FROM meters; + timetruncate(1643738522000, 1h) | +=================================== + 2022-02-02 02:00:00.000 | +Query OK, 1 row(s) in set (0.001499s) + +taos> SELECT TIMETRUNCATE("2022-02-02 02:02:02", 1h) FROM meters; + timetruncate("2022-02-02 02:02:02", 1h) | +=========================================== + 2022-02-02 02:00:00.000 | +Query OK, 1 row(s) in set (0.003903s) + +taos> SELECT TIMETRUNCATE(ts, 1h) FROM meters; + timetruncate(ts, 1h) | +========================== + 2022-02-02 02:00:00.000 | + 2022-02-02 02:00:00.000 | + 2022-02-02 02:00:00.000 | +Query OK, 3 row(s) in set (0.003903s) +``` + +### TIMEDIFF + +```sql +SELECT TIMEDIFF(ts_val1 | datetime_string1 | ts_col1, ts_val2 | datetime_string2 | ts_col2 [, time_unit]) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**Description**: The difference between two timestamps, and rounded to the time unit specified by `time_unit` + +**Return value type**: Long Integer + +**Applicable column types**: UNIX timestamp constant, string constant of date/time format, or a column of TIMESTAMP type + +**Applicable table types**: table, STable + +**More explanations**: + +- Time unit specified by `time_unit` can be: + 1u(microsecond),1a(millisecond),1s(second),1m(minute),1h(hour),1d(day). +- The precision of the returned timestamp is same as the precision set for the current data base in use + +**Applicable versions**:Since version 2.6.0.0 + +**Examples**: + +```sql +taos> SELECT TIMEDIFF(1643738400000, 1643742000000) FROM meters; + timediff(1643738400000, 1643742000000) | +========================================= + 3600000 | +Query OK, 1 row(s) in set (0.002553s) +taos> SELECT TIMEDIFF(1643738400000, 1643742000000, 1h) FROM meters; + timediff(1643738400000, 1643742000000, 1h) | +============================================= + 1 | +Query OK, 1 row(s) in set (0.003726s) + +taos> SELECT TIMEDIFF("2022-02-02 03:00:00", "2022-02-02 02:00:00", 1h) FROM meters; + timediff("2022-02-02 03:00:00", "2022-02-02 02:00:00", 1h) | +============================================================= + 1 | +Query OK, 1 row(s) in set (0.001937s) + +taos> SELECT TIMEDIFF(ts_col1, ts_col2, 1h) FROM meters; + timediff(ts_col1, ts_col2, 1h) | +=================================== + 1 | +Query OK, 1 row(s) in set (0.001937s) +``` diff --git a/docs/en/12-taos-sql/12-interval.md b/docs/en/12-taos-sql/12-interval.md new file mode 100644 index 0000000000000000000000000000000000000000..acfb0de0e1521fd8c6a068497a3df7a17941524c --- /dev/null +++ b/docs/en/12-taos-sql/12-interval.md @@ -0,0 +1,113 @@ +--- +sidebar_label: Interval +title: Aggregate by Time Window +--- + +Aggregation by time window is supported in TDengine. For example, in the case where temperature sensors report the temperature every seconds, the average temperature for every 10 minutes can be retrieved by performing a query with a time window. +Window related clauses are used to divide the data set to be queried into subsets and then aggregation is performed across the subsets. There are three kinds of windows: time window, status window, and session window. There are two kinds of time windows: sliding window and flip time/tumbling window. + +## Time Window + +The `INTERVAL` clause is used to generate time windows of the same time interval. The `SLIDING` parameter is used to specify the time step for which the time window moves forward. The query is performed on one time window each time, and the time window moves forward with time. When defining a continuous query, both the size of the time window and the step of forward sliding time need to be specified. As shown in the figure blow, [t0s, t0e] ，[t1s , t1e]， [t2s, t2e] are respectively the time ranges of three time windows on which continuous queries are executed. The time step for which time window moves forward is marked by `sliding time`. Query, filter and aggregate operations are executed on each time window respectively. When the time step specified by `SLIDING` is same as the time interval specified by `INTERVAL`, the sliding time window is actually a flip time/tumbling window. + +![TDengine Database Time Window](./timewindow-1.webp) + +`INTERVAL` and `SLIDING` should be used with aggregate functions and select functions. The SQL statement below is illegal because no aggregate or selection function is used with `INTERVAL`. + +``` +SELECT * FROM temp_tb_1 INTERVAL(1m); +``` + +The time step specified by `SLIDING` cannot exceed the time interval specified by `INTERVAL`. The SQL statement below is illegal because the time length specified by `SLIDING` exceeds that specified by `INTERVAL`. + +``` +SELECT COUNT(*) FROM temp_tb_1 INTERVAL(1m) SLIDING(2m); +``` + +When the time length specified by `SLIDING` is the same as that specified by `INTERVAL`, the sliding window is actually a flip/tumbling window. The minimum time range specified by `INTERVAL` is 10 milliseconds (10a) prior to version 2.1.5.0. Since version 2.1.5.0, the minimum time range by `INTERVAL` can be 1 microsecond (1u). However, if the DB precision is millisecond, the minimum time range is 1 millisecond (1a). Please note that the `timezone` parameter should be configured to be the same value in the `taos.cfg` configuration file on client side and server side. + +## Status Window + +In case of using integer, bool, or string to represent the status of a device at any given moment, continuous rows with the same status belong to a status window. Once the status changes, the status window closes. As shown in the following figure, there are two status windows according to status, [2019-04-28 14:22:07，2019-04-28 14:22:10] and [2019-04-28 14:22:11，2019-04-28 14:22:12]. Status window is not applicable to STable for now. + +![TDengine Database Status Window](./timewindow-3.webp) + +`STATE_WINDOW` is used to specify the column on which the status window will be based. For example： + +``` +SELECT COUNT(*), FIRST(ts), status FROM temp_tb_1 STATE_WINDOW(status); +``` + +## Session Window + +```sql +SELECT COUNT(*), FIRST(ts) FROM temp_tb_1 SESSION(ts, tol_val); +``` + +The primary key, i.e. timestamp, is used to determine which session window a row belongs to. If the time interval between two adjacent rows is within the time range specified by `tol_val`, they belong to the same session window; otherwise they belong to two different session windows. As shown in the figure below, if the limit of time interval for the session window is specified as 12 seconds, then the 6 rows in the figure constitutes 2 time windows, [2019-04-28 14:22:10，2019-04-28 14:22:30] and [2019-04-28 14:23:10，2019-04-28 14:23:30], because the time difference between 2019-04-28 14:22:30 and 2019-04-28 14:23:10 is 40 seconds, which exceeds the time interval limit of 12 seconds. + +![TDengine Database Session Window](./timewindow-2.webp) + +If the time interval between two continuous rows are within the time interval specified by `tol_value` they belong to the same session window; otherwise a new session window is started automatically. Session window is not supported on STable for now. + +## More On Window Aggregate + +### Syntax + +The full syntax of aggregate by window is as follows: + +```sql +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] +``` + +### Restrictions + +- Aggregate functions and select functions can be used in `function_list`, with each function having only one output. For example COUNT, AVG, SUM, STDDEV, LEASTSQUARES, PERCENTILE, MIN, MAX, FIRST, LAST. Functions having multiple outputs, such as DIFF or arithmetic operations can't be used. +- `LAST_ROW` can't be used together with window aggregate. +- Scalar functions, like CEIL/FLOOR, can't be used with window aggregate. +- `WHERE` clause can be used to specify the starting and ending time and other filter conditions +- `FILL` clause is used to specify how to fill when there is data missing in any window, including: + 1. NONE: No fill (the default fill mode) + 2. VALUE：Fill with a fixed value, which should be specified together, for example `FILL(VALUE, 1.23)` + 3. PREV：Fill with the previous non-NULL value, `FILL(PREV)` + 4. NULL：Fill with NULL, `FILL(NULL)` + 5. LINEAR：Fill with the closest non-NULL value, `FILL(LINEAR)` + 6. NEXT：Fill with the next non-NULL value, `FILL(NEXT)` + +:::info + +1. A huge volume of interpolation output may be returned using `FILL`, so it's recommended to specify the time range when using `FILL`. The maximum number of interpolation values that can be returned in a single query is 10,000,000. +2. The result set is in ascending order of timestamp when you aggregate by time window. +3. If aggregate by window is used on STable, the aggregate function is performed on all the rows matching the filter conditions. If `GROUP BY` is not used in the query, the result set will be returned in ascending order of timestamp; otherwise the result set is not exactly in the order of ascending timestamp in each group. + +::: + +Aggregate by time window is also used in continuous query, please refer to [Continuous Query](/develop/continuous-query). + +## Examples + +A table of intelligent meters can be created by the SQL statement below： + +```sql +CREATE TABLE meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT); +``` + +The average current, maximum current and median of current in every 10 minutes for the past 24 hours can be calculated using the SQL statement below, with missing values filled with the previous non-NULL values. + +``` +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/en/12-taos-sql/14-limit.md b/docs/en/12-taos-sql/14-limit.md new file mode 100644 index 0000000000000000000000000000000000000000..db55cdd69e7bd29ca66ee15b61f28991568d9556 --- /dev/null +++ b/docs/en/12-taos-sql/14-limit.md @@ -0,0 +1,77 @@ +--- +title: Limits & Restrictions +--- + +## Naming Rules + +1. Only characters from the English alphabet, digits and underscore are allowed +2. Names cannot start with a digit +3. Case insensitive without escape character "\`" +4. Identifier with escape character "\`" + To support more flexible table or column names, a new escape character "\`" is introduced. For more details please refer to [escape](/taos-sql/escape). + +## Password Rule + +The legal character set is `[a-zA-Z0-9!?$%^&*()_–+={[}]:;@~#|<,>.?/]`. + +## General Limits + +- Maximum length of database name is 32 bytes. +- Maximum length of table name is 192 bytes, excluding the database name prefix and the separator. +- Maximum length of each data row is 48K bytes since version 2.1.7.0 , before which the limit was 16K bytes. Please note that the upper limit includes the extra 2 bytes consumed by each column of BINARY/NCHAR type. +- Maximum length of column name is 64. +- Maximum number of columns is 4096. There must be at least 2 columns, and the first column must be timestamp. +- Maximum length of tag name is 64. +- Maximum number of tags is 128. There must be at least 1 tag. The total length of tag values should not exceed 16K bytes. +- Maximum length of singe SQL statement is 1048576, i.e. 1 MB. It can be configured in the parameter `maxSQLLength` in the client side, the applicable range is [65480, 1048576]. +- At most 4096 columns (or 1024 prior to 2.1.7.0) can be returned by `SELECT`. Functions in the query statement constitute columns. An error is returned if the limit is exceeded. +- Maximum numbers of databases, STables, tables are dependent only on the system resources. +- Maximum of database name is 32 bytes, and it can't include "." or special characters. +- Maximum number of replicas for a database is 3. +- Maximum length of user name is 23 bytes. +- Maximum length of password is 15 bytes. +- Maximum number of rows depends only on the storage space. +- Maximum number of tables depends only on the number of nodes. +- Maximum number of databases depends only on the number of nodes. +- Maximum number of vnodes for a single database is 64. + +## Restrictions of `GROUP BY` + +`GROUP BY` can be performed on tags and `TBNAME`. It can be performed on data columns too, with the only restriction being it can only be performed on one data column and the number of unique values in that column is lower than 100,000. Please note that `GROUP BY` cannot be performed on float or double types. + +## Restrictions of `IS NOT NULL` + +`IS NOT NULL` can be used on any data type of columns. The non-empty string evaluation expression, i.e. `< > ""` can only be used on non-numeric data types. + +## Restrictions of `ORDER BY` + +- Only one `order by` is allowed for normal table and subtable. +- At most two `order by` are allowed for STable, and the second one must be `ts`. +- `order by tag` must be used with `group by tag` on same tag. This rule is also applicable to `tbname`. +- `order by column` must be used with `group by column` or `top/bottom` on same column. This rule is applicable to table and STable. +- `order by ts` is applicable to table and STable. +- If `order by ts` is used with `group by`, the result set is sorted using `ts` in each group. + +## Restrictions of Table/Column Names + +### Name Restrictions of Table/Column + +The name of a table or column can only be composed of ASCII characters, digits and underscore and it cannot start with a digit. The maximum length is 192 bytes. Names are case insensitive. The name mentioned in this rule doesn't include the database name prefix and the separator. + +### Name Restrictions After Escaping + +To support more flexible table or column names, new escape character "\`" is introduced in TDengine to avoid the conflict between table name and keywords and break the above restrictions for table names. The escape character is not counted in the length of table name. + +With escaping, the string inside escape characters are case sensitive, i.e. will not be converted to lower case internally. + +For example: +\`aBc\` and \`abc\` are different table or column names, but "abc" and "aBc" are same names because internally they are all "abc". + +:::note +The characters inside escape characters must be printable characters. + +::: + +### Applicable Versions + +Escape character "\`" is available from version 2.3.0.1. diff --git a/docs/en/12-taos-sql/16-json.md b/docs/en/12-taos-sql/16-json.md new file mode 100644 index 0000000000000000000000000000000000000000..7460a5e0ba3ce78ee7744569cda460c477cac19c --- /dev/null +++ b/docs/en/12-taos-sql/16-json.md @@ -0,0 +1,82 @@ +--- +title: JSON Type +--- + +## Syntax + +1. Tag of type JSON + + ```sql + create STable s1 (ts timestamp, v1 int) tags (info json); + + create table s1_1 using s1 tags ('{"k1": "v1"}'); + ``` + +2. "->" Operator of JSON + + ```sql + select * from s1 where info->'k1' = 'v1'; + + select info->'k1' from s1; + ``` + +3. "contains" Operator of JSON + + ```sql + select * from s1 where info contains 'k2'; + + select * from s1 where info contains 'k1'; + ``` + +## Applicable Operations + +1. When a JSON data type is used in `where`, `match/nmatch/between and/like/and/or/is null/is no null` can be used but `in` can't be used. + + ```sql + 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. A tag of JSON type can be used in `group by`, `order by`, `join`, `union all` and sub query; for example `group by json->'key'` + +3. `Distinct` can be used with a tag of type JSON + + ```sql + select distinct info->'k1' from s1; + ``` + +4. Tag Operations + + The value of a JSON tag can be altered. Please note that the full JSON will be overriden when doing this. + + The name of a JSON tag can be altered. A tag of JSON type can't be added or removed. The column length of a JSON tag can't be changed. + +## Other Restrictions + +- JSON type can only be used for a tag. There can be only one tag of JSON type, and it's exclusive to any other types of tags. + +- The maximum length of keys in JSON is 256 bytes, and key must be printable ASCII characters. The maximum total length of a JSON is 4,096 bytes. + +- JSON format： + + - The input string for JSON can be empty, i.e. "", "\t", or NULL, but it can't be non-NULL string, bool or array. + - object can be {}, and the entire JSON is empty if so. Key can be "", and it's ignored if so. + - value can be int, double, string, bool or NULL, and it can't be an array. Nesting is not allowed which means that the value of a key can't be JSON. + - If one key occurs twice in JSON, only the first one is valid. + - Escape characters are not allowed in JSON. + +- NULL is returned when querying a key that doesn't exist in JSON. + +- If a tag of JSON is the result of inner query, it can't be parsed and queried in the outer query. + +For example, the SQL statements below are not supported. + +```sql; +select jtag->'key' from (select jtag from STable); +select jtag->'key' from (select jtag from STable) where jtag->'key'>0; +``` diff --git a/docs/en/12-taos-sql/18-escape.md b/docs/en/12-taos-sql/18-escape.md new file mode 100644 index 0000000000000000000000000000000000000000..34ce9f7848a9d60811a23286a6675e8afa4f04fe --- /dev/null +++ b/docs/en/12-taos-sql/18-escape.md @@ -0,0 +1,30 @@ +--- +title: Escape Characters +--- + +Below table is the list of escape characters used in TDengine. + +| Escape Character | **Actual Meaning** | +| :--------------: | ------------------------ | +| `\'` | Single quote ' | +| `\"` | Double quote " | +| \n | Line Break | +| \r | Carriage Return | +| \t | tab | +| `\\` | Back Slash \ | +| `\%` | % see below for details | +| `\_` | \_ see below for details | + +:::note +Escape characters are available from version 2.4.0.4 . + +::: + +## Restrictions + +1. If there are escape characters in identifiers (database name, table name, column name) + - Identifier without ``: Error will be returned because identifier must be constituted of digits, ASCII characters or underscore and can't be started with digits + - Identifier quoted with ``： Original content is kept, no escaping +2. If there are escape characters in values + - The escape characters will be escaped as the above table. If the escape character doesn't match any supported one, the escape character "\" will be ignored. + - "%" and "\_" are used as wildcards in `like`. `\%` and `\_` should be used to represent literal "%" and "\_" in `like`,. If `\%` and `\_` are used out of `like` context, the evaluation result is "`\%`"and "`\_`", instead of "%" and "\_". diff --git a/docs/en/12-taos-sql/20-keywords.md b/docs/en/12-taos-sql/20-keywords.md new file mode 100644 index 0000000000000000000000000000000000000000..b01ff4c64847107063287508b4daf320d0f62072 --- /dev/null +++ b/docs/en/12-taos-sql/20-keywords.md @@ -0,0 +1,314 @@ +--- +title: Keywords +--- + +There are about 200 keywords reserved by TDengine, they can't be used as the name of database, STable or table with either upper case, lower case or mixed case. + +## Keyword List + +### A + +- ABORT +- ACCOUNT +- ACCOUNTS +- ADD +- AFTER +- ALL +- ALTER +- AND +- AS +- ASC +- ATTACH + +### B + +- BEFORE +- BEGIN +- BETWEEN +- BIGINT +- BINARY +- BITAND +- BITNOT +- BITOR +- BLOCKS +- BOOL +- BY + +### C + +- CACHE +- CACHELAST +- CASCADE +- CHANGE +- CLUSTER +- COLON +- COLUMN +- COMMA +- COMP +- COMPACT +- CONCAT +- CONFLICT +- CONNECTION +- CONNECTIONS +- CONNS +- COPY +- CREATE +- CTIME + +### D + +- DATABASE +- DATABASES +- DAYS +- DBS +- DEFERRED +- DELETE +- DELIMITERS +- DESC +- DESCRIBE +- DETACH +- DISTINCT +- DIVIDE +- DNODE +- DNODES +- DOT +- DOUBLE +- DROP + +### E + +- END +- EQ +- EXISTS +- EXPLAIN + +### F + +- FAIL +- FILE +- FILL +- FLOAT +- FOR +- FROM +- FSYNC + +### G + +- GE +- GLOB +- GRANTS +- GROUP +- GT + +### H + +- HAVING + +### I + +- ID +- IF +- IGNORE +- IMMEDIA +- IMPORT +- IN +- INITIAL +- INSERT +- INSTEAD +- INT +- INTEGER +- INTERVA +- INTO +- IS +- ISNULL + +### J + +- JOIN + +### K + +- KEEP +- KEY +- KILL + +### L + +- LE +- LIKE +- LIMIT +- LINEAR +- LOCAL +- LP +- LSHIFT +- LT + +### M + +- MATCH +- MAXROWS +- MINROWS +- MINUS +- MNODES +- MODIFY +- MODULES + +### N + +- NE +- NONE +- NOT +- NOTNULL +- NOW +- NULL + +### O + +- OF +- OFFSET +- OR +- ORDER + +### P + +- PARTITION +- PASS +- PLUS +- PPS +- PRECISION +- PREV +- PRIVILEGE + +### Q + +- QTIME +- QUERIE +- QUERY +- QUORUM + +### R + +- RAISE +- REM +- REPLACE +- REPLICA +- RESET +- RESTRIC +- ROW +- RP +- RSHIFT + +### S + +- SCORES +- SELECT +- SEMI +- SESSION +- SET +- SHOW +- SLASH +- SLIDING +- SLIMIT +- SMALLIN +- SOFFSET +- STable +- STableS +- STAR +- STATE +- STATEMEN +- STATE_WI +- STORAGE +- STREAM +- STREAMS +- STRING +- SYNCDB + +### T + +- TABLE +- TABLES +- TAG +- TAGS +- TBNAME +- TIMES +- TIMESTAMP +- TINYINT +- TOPIC +- TOPICS +- TRIGGER +- TSERIES + +### U + +- UMINUS +- UNION +- UNSIGNED +- UPDATE +- UPLUS +- USE +- USER +- USERS +- USING + +### V + +- VALUES +- VARIABLE +- VARIABLES +- VGROUPS +- VIEW +- VNODES + +### W + +- WAL +- WHERE + +### _ + +- _C0 +- _QSTART +- _QSTOP +- _QDURATION +- _WSTART +- _WSTOP +- _WDURATION + +## Explanations +### TBNAME +`TBNAME` can be considered as a special tag, which represents the name of the subtable, in STable. + +Get the table name and tag values of all subtables in a STable. +```mysql +SELECT TBNAME, location FROM meters; + +Count the number of subtables in a STable. +```mysql +SELECT COUNT(TBNAME) FROM meters; +``` + +Only filter on TAGS can be used in WHERE clause in the above two query statements. +```mysql +taos> SELECT TBNAME, location FROM meters; + tbname | location | +================================================================== + d1004 | California.SanFrancisco | + d1003 | California.SanFrancisco | + d1002 | California.LosAngeles | + d1001 | California.LosAngeles | +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) +``` +### _QSTART/_QSTOP/_QDURATION +The start, stop and duration of a query time window (Since version 2.6.0.0). + +### _WSTART/_WSTOP/_WDURATION +The start, stop and duration of aggegate query by time window, like interval, session window, state window (Since version 2.6.0.0). + +### _c0 +The first column of a table or STable. diff --git a/docs/en/12-taos-sql/_category_.yml b/docs/en/12-taos-sql/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..74a3b6309e0a4ad35feb674f544c689ae1992299 --- /dev/null +++ b/docs/en/12-taos-sql/_category_.yml @@ -0,0 +1 @@ +label: TDengine SQL diff --git a/docs/en/12-taos-sql/index.md b/docs/en/12-taos-sql/index.md new file mode 100644 index 0000000000000000000000000000000000000000..33656338a7bba38dc55cf536bdba8e95309c5acf --- /dev/null +++ b/docs/en/12-taos-sql/index.md @@ -0,0 +1,31 @@ +--- +title: TDengine SQL +description: "The syntax supported by TDengine SQL " +--- + +This section explains the syntax of SQL to perform operations on databases, tables and STables, insert data, select data and use functions. We also provide some tips that can be used in TDengine SQL. If you have previous experience with SQL this section will be fairly easy to understand. If you do not have previous experience with SQL, you'll come to appreciate the simplicity and power of SQL. + +TDengine SQL is the major interface for users to write data into or query from TDengine. For ease of use, the syntax is similar to that of standard SQL. However, please note that TDengine SQL is not standard SQL. For instance, TDengine doesn't provide a delete function for time series data and so corresponding statements are not provided in TDengine SQL. + +Syntax Specifications used in this chapter: + +- The content inside <\> needs to be input by the user, excluding <\> itself. +- \[ \] means optional input, excluding [] itself. +- | means one of a few options, excluding | itself. +- … means the item prior to it can be repeated multiple times. + +To better demonstrate the syntax, usage and rules of TAOS SQL, hereinafter it's assumed that there is a data set of data from electric meters. Each meter collects 3 data measurements: current, voltage, phase. The data model is shown below: + +```sql +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 | +``` + +The data set includes the data collected by 4 meters, the corresponding table name is d1001, d1002, d1003 and d1004 based on the data model of TDengine. diff --git a/docs/en/12-taos-sql/timewindow-1.webp b/docs/en/12-taos-sql/timewindow-1.webp new file mode 100644 index 0000000000000000000000000000000000000000..82747558e96df752a0010d85be79a4af07e4a1df Binary files /dev/null and b/docs/en/12-taos-sql/timewindow-1.webp differ diff --git a/docs/en/12-taos-sql/timewindow-2.webp b/docs/en/12-taos-sql/timewindow-2.webp new file mode 100644 index 0000000000000000000000000000000000000000..8f1314ae34f7f5c5cca1d3cb80455f555fad38c3 Binary files /dev/null and b/docs/en/12-taos-sql/timewindow-2.webp differ diff --git a/docs/en/12-taos-sql/timewindow-3.webp b/docs/en/12-taos-sql/timewindow-3.webp new file mode 100644 index 0000000000000000000000000000000000000000..5bd16e68e7fd5da6805551e9765975277cd5d4d9 Binary files /dev/null and b/docs/en/12-taos-sql/timewindow-3.webp differ diff --git a/docs/en/13-operation/01-pkg-install.md b/docs/en/13-operation/01-pkg-install.md new file mode 100644 index 0000000000000000000000000000000000000000..c098002962d62aa0acc7a94462c052303cb2ed90 --- /dev/null +++ b/docs/en/13-operation/01-pkg-install.md @@ -0,0 +1,284 @@ +--- +title: Install & Uninstall +description: Install, Uninstall, Start, Stop and Upgrade +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +TDengine community version provides deb and rpm packages for users to choose from, based on their system environment. The deb package supports Debian, Ubuntu and derivative systems. The rpm package supports CentOS, RHEL, SUSE and derivative systems. Furthermore, a tar.gz package is provided for TDengine Enterprise customers. + +## Install + + + + +1. Download deb package from official website, for example TDengine-server-2.4.0.7-Linux-x64.deb +2. In the directory where the package is located, execute the command below + +```bash +$ 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. Download rpm package from official website, for example TDengine-server-2.4.0.7-Linux-x64.rpm； +2. In the directory where the package is located, execute the command below + +``` +$ 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. Download the tar.gz package, for example TDengine-server-2.4.0.7-Linux-x64.tar.gz； +2. In the directory where the package is located, first decompress the file, then switch to the sub-directory generated in decompressing, i.e. "TDengine-enterprise-server-2.4.0.7/" in this example, and execute the `install.sh` script. + +```bash +$ 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 +Users will be prompted to enter some configuration information when install.sh is executing. The interactive mode can be disabled by executing `./install.sh -e no`. `./install.sh -h` can show all parameters with detailed explanation. + +::: + + + + +:::note +When installing on the first node in the cluster, at the "Enter FQDN:" prompt, nothing needs to be provided. When installing on subsequent nodes, at the "Enter FQDN:" prompt, you must enter the end point of the first dnode in the cluster if it is already up. You can also just ignore it and configure it later after installation is finished. + +::: + +## Uninstall + + + + +Deb package of TDengine can be uninstalled as below: + +```bash +$ sudo dpkg -r tdengine +(Reading database ... 137504 files and directories currently installed.) +Removing tdengine (2.4.0.7) ... +TDengine is removed successfully! + +``` + + + + + +RPM package of TDengine can be uninstalled as below: + +``` +$ sudo rpm -e tdengine +TDengine is removed successfully! +``` + + + + + +tar.gz package of TDengine can be uninstalled as below: + +``` +$ rmtaos +Nginx for TDengine is running, stopping it... +TDengine is removed successfully! + +taosKeeper is removed successfully! +``` + + + + +:::note + +- We strongly recommend not to use multiple kinds of installation packages on a single host TDengine. +- After deb package is installed, if the installation directory is removed manually, uninstall or reinstall will not work. This issue can be resolved by using the command below which cleans up TDengine package information. You can then reinstall if needed. + +```bash + $ sudo rm -f /var/lib/dpkg/info/tdengine* +``` + +- After rpm package is installed, if the installation directory is removed manually, uninstall or reinstall will not work. This issue can be resolved by using the command below which cleans up TDengine package information. You can then reinstall if needed. + +```bash + $ sudo rpm -e --noscripts tdengine +``` + +::: + +## Installation Directory + +TDengine is installed at /usr/local/taos if successful. + +```bash +$ 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/ +``` + +During the installation process: + +- Configuration directory, data directory, and log directory are created automatically if they don't exist +- The default configuration file is located at /etc/taos/taos.cfg, which is a copy of /usr/local/taos/cfg/taos.cfg +- The default data directory is /var/lib/taos, which is a soft link to /usr/local/taos/data +- The default log directory is /var/log/taos, which is a soft link to /usr/local/taos/log +- The executables at /usr/local/taos/bin are linked to /usr/bin +- The DLL files at /usr/local/taos/driver are linked to /usr/lib +- The header files at /usr/local/taos/include are linked to /usr/include + +:::note + +- When TDengine is uninstalled, the configuration /etc/taos/taos.cfg, data directory /var/lib/taos, log directory /var/log/taos are kept. They can be deleted manually with caution, because data can't be recovered. Please follow data integrity, security, backup or relevant SOPs before deleting any data. +- When reinstalling TDengine, if the default configuration file /etc/taos/taos.cfg exists, it will be kept and the configuration file in the installation package will be renamed to taos.cfg.orig and stored at /usr/local/taos/cfg to be used as configuration sample. Otherwise the configuration file in the installation package will be installed to /etc/taos/taos.cfg and used. + +## Start and Stop + +Linux system services `systemd`, `systemctl` or `service` are used to start, stop and restart TDengine. The server process of TDengine is `taosd`, which is started automatically after the Linux system is started. System operators can use `systemd`, `systemctl` or `service` to start, stop or restart TDengine server. + +For example, if using `systemctl` , the commands to start, stop, restart and check TDengine server are below: + +- Start server：`systemctl start taosd` + +- Stop server：`systemctl stop taosd` + +- Restart server：`systemctl restart taosd` + +- Check server status：`systemctl status taosd` + +From version 2.4.0.0, a new independent component named as `taosAdapter` has been included in TDengine. `taosAdapter` should be started and stopped using `systemctl`. + +If the server process is OK, the output of `systemctl status` is like below: + +``` +Active: active (running) +``` + +Otherwise, the output is as below: + +``` +Active: inactive (dead) +``` + +## Upgrade + +There are two aspects in upgrade operation: upgrade installation package and upgrade a running server. + +To upgrade a package, follow the steps mentioned previously to first uninstall the old version then install the new version. + +Upgrading a running server is much more complex. First please check the version number of the old version and the new version. The version number of TDengine consists of 4 sections, only if the first 3 sections match can the old version be upgraded to the new version. The steps of upgrading a running server are as below: + +- Stop inserting data +- Make sure all data is persisted to disk +- Make some simple queries (Such as total rows in stables, tables and so on. Note down the values. Follow best practices and relevant SOPs.) +- Stop the cluster of TDengine +- Uninstall old version and install new version +- Start the cluster of TDengine +- Execute simple queries, such as the ones executed prior to installing the new package, to make sure there is no data loss +- Run some simple data insertion statements to make sure the cluster works well +- Restore business services + +:::warning + +TDengine doesn't guarantee any lower version is compatible with the data generated by a higher version, so it's never recommended to downgrade the version. + +::: diff --git a/docs/en/13-operation/02-planning.mdx b/docs/en/13-operation/02-planning.mdx new file mode 100644 index 0000000000000000000000000000000000000000..c1baf92dbfa8d93f83174c05c2ea631d1a469739 --- /dev/null +++ b/docs/en/13-operation/02-planning.mdx @@ -0,0 +1,82 @@ +--- +title: Resource Planning +--- + +It is important to plan computing and storage resources if using TDengine to build an IoT, time-series or Big Data platform. How to plan the CPU, memory and disk resources required, will be described in this chapter. + +## Memory Requirement of Server Side + +By default, the number of vgroups created for each database is the same as the number of CPU cores. This can be configured by the parameter `maxVgroupsPerDb`. Each vnode in a vgroup stores one replica. Each vnode consumes a fixed amount of memory, i.e. `blocks` \* `cache`. In addition, some memory is required for tag values associated with each table. A fixed amount of memory is required for each cluster. So, the memory required for each DB can be calculated using the formula below: + +``` +Database Memory Size = maxVgroupsPerDb * replica * (blocks * cache + 10MB) + numOfTables * (tagSizePerTable + 0.5KB) +``` + +For example, assuming the default value of `maxVgroupPerDB` is 64, the default value of `cache` is 16M, the default value of `blocks` is 6, there are 100,000 tables in a DB, the replica number is 1, total length of tag values is 256 bytes, the total memory required for this DB is: 64 \* 1 \* (16 \* 6 + 10) + 100000 \* (0.25 + 0.5) / 1000 = 6792M. + +In the real operation of TDengine, we are more concerned about the memory used by each TDengine server process `taosd`. + +``` + taosd_memory = vnode_memory + mnode_memory + query_memory +``` + +In the above formula: + +1. "vnode_memory" of a `taosd` process is the memory used by all vnodes hosted by this `taosd` process. It can be roughly calculated by firstly adding up the total memory of all DBs whose memory usage can be derived according to the formula for Database Memory Size, mentioned above, then dividing by number of dnodes and multiplying the number of replicas. + +``` + vnode_memory = (sum(Database Memory Size) / number_of_dnodes) * replica +``` + +2. "mnode_memory" of a `taosd` process is the memory consumed by a mnode. If there is one (and only one) mnode hosted in a `taosd` process, the memory consumed by "mnode" is "0.2KB \* the total number of tables in the cluster". + +3. "query_memory" is the memory used when processing query requests. Each ongoing query consumes at least "0.2 KB \* total number of involved tables". + +Please note that the above formulas can only be used to estimate the minimum memory requirement, instead of maximum memory usage. In a real production environment, it's better to reserve some redundance beyond the estimated minimum memory requirement. If memory is abundant, it's suggested to increase the value of parameter `blocks` to speed up data insertion and data query. + +## Memory Requirement of Client Side + +For the client programs using TDengine client driver `taosc` to connect to the server side there is a memory requirement as well. + +The memory consumed by a client program is mainly about the SQL statements for data insertion, caching of table metadata, and some internal use. Assuming maximum number of tables is N (the memory consumed by the metadata of each table is 256 bytes), maximum number of threads for parallel insertion is T, maximum length of a SQL statement is S (normally 1 MB), the memory required by a client program can be estimated using the below formula: + +``` +M = (T * S * 3 + (N / 4096) + 100) +``` + +For example, if the number of parallel data insertion threads is 100, total number of tables is 10,000,000, then the minimum memory requirement of a client program is: + +``` +100 * 3 + (10000000 / 4096) + 100 = 2741 (MBytes) +``` + +So, at least 3GB needs to be reserved for such a client. + +## CPU Requirement + +The CPU resources required depend on two aspects: + +- **Data Insertion** Each dnode of TDengine can process at least 10,000 insertion requests in one second, while each insertion request can have multiple rows. The difference in computing resource consumed, between inserting 1 row at a time, and inserting 10 rows at a time is very small. So, the more the number of rows that can be inserted one time, the higher the efficiency. Inserting in batch also imposes requirements on the client side which needs to cache rows to insert in batch once the number of cached rows reaches a threshold. +- **Data Query** High efficiency query is provided in TDengine, but it's hard to estimate the CPU resource required because the queries used in different use cases and the frequency of queries vary significantly. It can only be verified with the query statements, query frequency, data size to be queried, and other requirements provided by users. + +In short, the CPU resource required for data insertion can be estimated but it's hard to do so for query use cases. In real operation, it's suggested to control CPU usage below 50%. If this threshold is exceeded, it's a reminder for system operator to add more nodes in the cluster to expand resources. + +## Disk Requirement + +The compression ratio in TDengine is much higher than that in RDBMS. In most cases, the compression ratio in TDengine is bigger than 5, or even 10 in some cases, depending on the characteristics of the original data. The data size before compression can be calculated based on below formula: + +``` +Raw DataSize = numOfTables * rowSizePerTable * rowsPerTable +``` + +For example, there are 10,000,000 meters, while each meter collects data every 15 minutes and the data size of each collection is 128 bytes, so the raw data size of one year is: 10000000 \* 128 \* 24 \* 60 / 15 \* 365 = 44.8512(TB). Assuming compression ratio is 5, the actual disk size is: 44.851 / 5 = 8.97024(TB). + +Parameter `keep` can be used to set how long the data will be kept on disk. To further reduce storage cost, multiple storage levels can be enabled in TDengine, with the coldest data stored on the cheapest storage device. This is completely transparent to application programs. + +To increase performance, multiple disks can be setup for parallel data reading or data inserting. Please note that an expensive disk array is not necessary because replications are used in TDengine to provide high availability. + +## Number of Hosts + +A host can be either physical or virtual. The total memory, total CPU, total disk required can be estimated according to the formulae mentioned previously. Then, according to the system resources that a single host can provide, assuming all hosts have the same resources, the number of hosts can be derived easily. + +**Quick Estimation for CPU, Memory and Disk** Please refer to [Resource Estimate](https://www.taosdata.com/config/config.html). diff --git a/docs/en/13-operation/03-tolerance.md b/docs/en/13-operation/03-tolerance.md new file mode 100644 index 0000000000000000000000000000000000000000..d4d48d7fcdc2c990b6ea0821e2347c70a809ed79 --- /dev/null +++ b/docs/en/13-operation/03-tolerance.md @@ -0,0 +1,32 @@ +--- +sidebar_label: Fault Tolerance +title: Fault Tolerance & Disaster Recovery +--- + +## Fault Tolerance + +TDengine uses **WAL**, i.e. Write Ahead Log, to achieve fault tolerance and high reliability. + +When a data block is received by TDengine, the original data block is first written into WAL. The log in WAL will be deleted only after the data has been written into data files in the database. Data can be recovered from WAL in case the server is stopped abnormally for any reason and then restarted. + +There are 2 configuration parameters related to WAL: + +- walLevel： + - 0：wal is disabled + - 1：wal is enabled without fsync + - 2：wal is enabled with fsync +- fsync：This parameter is only valid when walLevel is set to 2. It specifies the interval, in milliseconds, of invoking fsync. If set to 0, it means fsync is invoked immediately once WAL is written. + +To achieve absolutely no data loss, walLevel should be set to 2 and fsync should be set to 1. There is a performance penalty to the data ingestion rate. However, if the concurrent data insertion threads on the client side can reach a big enough number, for example 50, the data ingestion performance will be still good enough. Our verification shows that the drop is only 30% when fsync is set to 3,000 milliseconds. + +## Disaster Recovery + +TDengine uses replication to provide high availability and disaster recovery capability. + +A TDengine cluster is managed by mnode. To ensure the high availability of mnode, multiple replicas can be configured by the system parameter `numOfMnodes`. The data replication between mnode replicas is performed in a synchronous way to guarantee metadata consistency. + +The number of replicas for time series data in TDengine is associated with each database. There can be many databases in a cluster and each database can be configured with a different number of replicas. When creating a database, parameter `replica` is used to configure the number of replications. To achieve high availability, `replica` needs to be higher than 1. + +The number of dnodes in a TDengine cluster must NOT be lower than the number of replicas for any database, otherwise it would fail when trying to create a table. + +As long as the dnodes of a TDengine cluster are deployed on different physical machines and the replica number is higher than 1, high availability can be achieved without any other assistance. For disaster recovery, dnodes of a TDengine cluster should be deployed in geographically different data centers. diff --git a/docs/en/13-operation/06-admin.md b/docs/en/13-operation/06-admin.md new file mode 100644 index 0000000000000000000000000000000000000000..458a91b88c6d8319fe8b84c2b34d8ff968957910 --- /dev/null +++ b/docs/en/13-operation/06-admin.md @@ -0,0 +1,50 @@ +--- +title: User Management +--- + +A system operator can use TDengine CLI `taos` to create or remove users or change passwords. The SQL commands are documented below: + +## Create User + +```sql +CREATE USER PASS <'password'>; +``` + +When creating a user and specifying the user name and password, the password needs to be quoted using single quotes. + +## Drop User + +```sql +DROP USER ; +``` + +Dropping a user can only be performed by root. + +## Change Password + +```sql +ALTER USER PASS <'password'>; +``` + +To keep the case of the password when changing password, the password needs to be quoted using single quotes. + +## Change Privilege + +```sql +ALTER USER PRIVILEGE ; +``` + +The privileges that can be changed to are `read` or `write` without single quotes. + +Note：there is another privilege `super`, which is not allowed to be authorized to any user. + +## Show Users + +```sql +SHOW USERS; +``` + +:::note +In SQL syntax, `< >` means the part that needs to be input by the user, excluding the `< >` itself. + +::: diff --git a/docs/en/13-operation/07-import.md b/docs/en/13-operation/07-import.md new file mode 100644 index 0000000000000000000000000000000000000000..8362cec1ab3072866018678b42a679d0c19b49de --- /dev/null +++ b/docs/en/13-operation/07-import.md @@ -0,0 +1,61 @@ +--- +title: Data Import +--- + +There are multiple ways of importing data provided by TDengine: import with script, import from data file, import using `taosdump`. + +## Import Using Script + +TDengine CLI `taos` supports `source ` command for executing the SQL statements in the file in batch. The SQL statements for creating databases, creating tables, and inserting rows can be written in a single file with one statement on each line, then the file can be executed using the `source` command in TDengine CLI `taos` to execute the SQL statements in order and in batch. In the script file, any line beginning with "#" is treated as comments and ignored silently. + +## Import from Data File + +In TDengine CLI, data can be imported from a CSV file into an existing table. The data in a single CSV must belong to the same table and must be consistent with the schema of that table. The SQL statement is as below: + +```sql +insert into tb1 file 'path/data.csv'; +``` + +:::note +If there is a description in the first line of the CSV file, please remove it before importing. If there is no value for a column, please use `NULL` without quotes. + +::: + +For example, there is a subtable d1001 whose schema is as below: + +```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 | +``` + +The format of the CSV file to be imported, data.csv, is as below: + +```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 +``` + +Then, the below SQL statement can be used to import data from file "data.csv", assuming the file is located under the home directory of the current Linux user. + +```sql +taos> insert into d1001 file '~/data.csv'; +Query OK, 9 row(s) affected (0.004763s) +``` + +## Import using taosdump + +A convenient tool for importing and exporting data is provided by TDengine, `taosdump`, which can be used to export data from one TDengine cluster and import into another one. For the details of using `taosdump` please refer to [Tool for exporting and importing data: taosdump](/reference/taosdump). diff --git a/docs/en/13-operation/08-export.md b/docs/en/13-operation/08-export.md new file mode 100644 index 0000000000000000000000000000000000000000..5780de42faeaedbc1c985ad2aa2f52fe56c76971 --- /dev/null +++ b/docs/en/13-operation/08-export.md @@ -0,0 +1,21 @@ +--- +title: Data Export +--- + +There are two ways of exporting data from a TDengine cluster: +- Using a SQL statement in TDengine CLI +- Using the `taosdump` tool + +## Export Using SQL + +If you want to export the data of a table or a STable, please execute the SQL statement below, in the TDengine CLI. + +```sql +select * from >> data.csv; +``` + +The data of table or STable specified by `tb_name` will be exported into a file named `data.csv` in CSV format. + +## Export Using taosdump + +With `taosdump`, you can choose to export the data of all databases, a database, a table or a STable, you can also choose to export the data within a time range, or even only export the schema definition of a table. For the details of using `taosdump` please refer to [Tool for exporting and importing data: taosdump](/reference/taosdump). diff --git a/docs/en/13-operation/09-status.md b/docs/en/13-operation/09-status.md new file mode 100644 index 0000000000000000000000000000000000000000..51396524ea281ae665c9fdf61d2e6e6202995537 --- /dev/null +++ b/docs/en/13-operation/09-status.md @@ -0,0 +1,54 @@ +--- +sidebar_label: Connections & Tasks +title: Manage Connections and Query Tasks +--- + +A system operator can use the TDengine CLI to show connections, ongoing queries, stream computing, and can close connections or stop ongoing query tasks or stream computing. + +## Show Connections + +```sql +SHOW CONNECTIONS; +``` + +One column of the output of the above SQL command is "ip:port", which is the end point of the client. + +## Force Close Connections + +```sql +KILL CONNECTION ; +``` + +In the above SQL command, `connection-id` is from the first column of the output of `SHOW CONNECTIONS`. + +## Show Ongoing Queries + +```sql +SHOW QUERIES; +``` + +The first column of the output is query ID, which is composed of the corresponding connection ID and the sequence number of the current query task started on this connection. The format is "connection-id:query-no". + +## Force Close Queries + +```sql +KILL QUERY ; +``` + +In the above SQL command, `query-id` is from the first column of the output of `SHOW QUERIES `. + +## Show Continuous Query + +```sql +SHOW STREAMS; +``` + +The first column of the output is stream ID, which is composed of the connection ID and the sequence number of the current stream started on this connection. The format is "connection-id:stream-no". + +## Force Close Continuous Query + +```sql +KILL STREAM ; +``` + +The above SQL command, `stream-id` is from the first column of the output of `SHOW STREAMS`. diff --git a/docs/en/13-operation/10-monitor.md b/docs/en/13-operation/10-monitor.md new file mode 100644 index 0000000000000000000000000000000000000000..a4679983f2bc77bb4e438f5d43fa1b8beb39b120 --- /dev/null +++ b/docs/en/13-operation/10-monitor.md @@ -0,0 +1,60 @@ +--- +title: TDengine Monitoring +--- + +After TDengine is started, a database named `log` is created automatically to help with monitoring. Information that includes CPU, memory and disk usage, bandwidth, number of requests, disk I/O speed, slow queries, is written into the `log` database at a predefined interval. Additionally, some important system operations, like logon, create user, drop database, and alerts and warnings generated in TDengine are written into the `log` database too. A system operator can view the data in `log` database from TDengine CLI or from a web console. + +The collection of the monitoring information is enabled by default, but can be disabled by parameter `monitor` in the configuration file. + +## TDinsight + +TDinsight is a complete solution which uses the monitoring database `log` mentioned previously, and Grafana, to monitor a TDengine cluster. + +From version 2.3.3.0, more monitoring data has been added in the `log` database. Please refer to [TDinsight Grafana Dashboard](https://grafana.com/grafana/dashboards/15167) to learn more details about using TDinsight to monitor TDengine. + +A script `TDinsight.sh` is provided to deploy TDinsight automatically. + +Download `TDinsight.sh` with the below command: + +```bash +wget https://github.com/taosdata/grafanaplugin/raw/master/dashboards/TDinsight.sh +chmod +x TDinsight.sh +``` + +Prepare： + +1. TDengine Server + + - The URL of REST service：for example `http://localhost:6041` if TDengine is deployed locally + - User name and password + +2. Grafana Alert Notification + +There are two ways to setup Grafana alert notification. + +- An existing Grafana Notification Channel can be specified with parameter `-E`, the notifier uid of the channel can be obtained by `curl -u admin:admin localhost:3000/api/alert-notifications |jq` + + ```bash + sudo ./TDinsight.sh -a http://localhost:6041 -u root -p taosdata -E + ``` + +- The AliCloud SMS alert built in TDengine data source plugin can be enabled with parameter `-s`, the parameters of enabling this plugin are listed below: + + - `-I`: AliCloud SMS Key ID + - `-K`: AliCloud SMS Key Secret + - `-S`: AliCloud SMS Signature + - `-C`: SMS notification template + - `-T`: Input parameters in JSON format for the SMS notification template, for example`{"alarm_level":"%s","time":"%s","name":"%s","content":"%s"}` + - `-B`: List of mobile numbers to be notified + + Below is an example of the full command using the AliCloud SMS alert. + + ```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"}' + ``` + +Launch `TDinsight.sh` with the command above and restart Grafana, then open Dashboard `http://localhost:3000/d/tdinsight`. + +For more use cases and restrictions please refer to [TDinsight](/reference/tdinsight/). diff --git a/docs/en/13-operation/11-optimize.md b/docs/en/13-operation/11-optimize.md new file mode 100644 index 0000000000000000000000000000000000000000..69f8a49e4cf950fdf1e363e7a51aa9d888e22e04 --- /dev/null +++ b/docs/en/13-operation/11-optimize.md @@ -0,0 +1,100 @@ +--- +title: Performance Optimization +--- + +After a TDengine cluster has been running for a long enough time, because of data insertion, table deletion and deletion of expired data, there may be fragments in data files and query performance may be impacted. To resolve the problem of fragments, since version 2.1.3.0 a new SQL command `COMPACT` can be used to defragment data files. + +```sql +COMPACT VNODES IN (vg_id1, vg_id2, ...) +``` + +`COMPACT` can be used to defragment one or more vgroups. The defragmentation work will be scheduled in the task queue for execution by TDengine. `SHOW VGROUPS` command can be used to get the vgroup ids to be used in `COMPACT` command. There is a column `compacting` in the output of `SHOW GROUPS` to indicate the compaction status of the vgroup: 2 means the vgroup is waiting in task queue for compaction, 1 means compaction is in progress, and 0 means the vgroup has not been scheduled for compaction. + +Please note that a lot of disk I/O is required for defragementation operations. During defragmentation the performance may be impacted significantly for data insertion and query. Data insertion may even be blocked for very short periods, in extreme cases. + +## Optimize Storage Parameters + +The data in different use cases may have different characteristics, such as the days to keep, number of replicas, collection interval, record size, number of collection points, compression or not, etc. To achieve best efficiency in storage, the parameters in the table below can be used. All of them can either be configured in `taos.cfg`, as default parameters, or can be set in the command `create database`. For detailed definition of these parameters please refer to [Configuration Parameters](/reference/config/). + +| # | Parameter | Unit | Definition | **Value Range** | **Default Value** | +| --- | --------- | ---- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- | ----------------- | +| 1 | days | Day | The time range of the data stored in a single data file | 1-3650 | 10 | +| 2 | keep | Day | The number of days the data is kept in the database | 1-36500 | 3650 | +| 3 | cache | MB | The size of each memory block | 1-128 | 16 | +| 4 | blocks | None | The number of memory blocks used by each vnode | 3-10000 | 6 | +| 5 | quorum | None | The number of required confirmations in case of multiple replicas | 1-2 | 1 | +| 6 | minRows | None | The minimum number of rows in a data file | 10-1000 | 100 | +| 7 | maxRows | None | The maximum number of rows in a data file | 200-10000 | 4096 | +| 8 | comp | None | Whether to compress the data | 0：uncompressed; 1: One Phase compression; 2: Two Phase compression | 2 | +| 9 | walLevel | None | wal sync level (named as "wal" in create database ) | 1：wal enabled without fsync; 2：wal enabled with fsync | 1 | +| 10 | fsync | ms | The time to wait for invoking fsync when walLevel is set to 2; 0 means no wait | 0-3000 | +| 11 | replica | none | The number of replications | 1-3 | 1 | +| 12 | precision | none | Time precision | ms: millisecond; us: microsecond;ns: nanosecond | ms | +| 13 | update | none | Whether to allow updating data | 0: not allowed; 1: a whole row must be updated; 2: a portion of columns in a row can be updated | 0 | +| 14 | cacheLast | none | Whether the latest data of a table is cached in memory | 0: not cached; 1: the last row is cached; 2: the latest non-NULL value of each column is cached | 0 | + +Even for a specific use case, there may be multiple kinds of data with different characteristics. In this case it's best to put data with the same characteristics in the same database. There may be multiple databases in a system and each database can be configured with different storage parameters to achieve the best performance. The above parameters can be used when creating a database to override the default setting in the configuration file. + +```sql + CREATE DATABASE demo DAYS 10 CACHE 32 BLOCKS 8 REPLICA 3 UPDATE 1; +``` + +The above SQL statement creates a database named `demo`, in which each data file stores 10 days of data, the size of each memory block is 32 MB and 8 blocks are allocated to each vnode, there are 3 replicas and update operations are allowed. All other parameters not specified in the command, will default to the values in the configuration file `taos.cfg`. + +Once a database is created, only some parameters can be changed and be effective immediately while others are can't. + +| **Parameter** | **Alterable** | **Value Range** | **Syntax** | +| ------------- | ------------- | ---------------- | -------------------------------------- | +| name | | | | +| create time | | | | +| ntables | | | | +| vgroups | | | | +| replica | **YES** | 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_ | + +**Explanation：** Prior to version 2.1.3.0, `taosd` server process needs to be restarted for these parameters to take in effect if they are changed using `ALTER DATABASE`. + +When trying to join a new dnode into a running TDengine cluster, all the parameters related to the cluster in the new dnode configuration must be consistent with the cluster, otherwise it can't join the cluster. The parameters that are checked when joining a dnode are listed below. For detailed definition of these parameters please refer to [Configuration Parameters](/reference/config/). + +- numOfMnodes +- mnodeEqualVnodeNum +- offlineThreshold +- statusInterval +- maxTablesPerVnode +- maxVgroupsPerDb +- arbitrator +- timezone +- balance +- flowctrl +- slaveQuery +- adjustMaster + +For the convenience of debugging, the log setting of a dnode can be changed temporarily. The temporary change will be lost once the server is restarted. + +```sql +ALTER DNODE +``` + +- dnode_id: from output of "SHOW DNODES" +- config: the parameter to be changed, as below + - resetlog: close the old log file and create the new one + - debugFlag: 131 (INFO/ERROR/WARNING), 135 (DEBUG), 143 (TRACE) + +For example: + +``` +alter dnode 1 debugFlag 135; +``` diff --git a/docs/en/13-operation/17-diagnose.md b/docs/en/13-operation/17-diagnose.md new file mode 100644 index 0000000000000000000000000000000000000000..2b474fddba4af5ba0c29103cd8ab1249d10d055b --- /dev/null +++ b/docs/en/13-operation/17-diagnose.md @@ -0,0 +1,122 @@ +--- +title: Problem Diagnostics +--- + +## Network Connection Diagnostics + +When a TDengine client is unable to access a TDengine server, the network connection between the client side and the server side must be checked to find the root cause and resolve problems. + +Diagnostics for network connections can be executed between Linux and Linux or between Linux and Windows. + +Diagnostic steps： + +1. If the port range to be diagnosed is being occupied by a `taosd` server process, please first stop `taosd. +2. On the server side, execute command `taos -n server -P -l ` to monitor the port range starting from the port specified by `-P` parameter with the role of "server". +3. On the client side, execute command `taos -n client -h -P -l ` to send a testing package to the specified server and port. + +-l ： The size of the testing package, in bytes. The value range is [11, 64,000] and default value is 1,000. Please note that the package length must be same in the above 2 commands executed on server side and client side respectively. + +Output of the server side for the example is below: + +```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 +``` + +Output of the client side for the example is below: + +```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 +``` + +The output needs to be checked carefully for the system operator to find the root cause and resolve the problem. + +## Startup Status and RPC Diagnostic + +`taos -n startup -h ` can be used to check the startup status of a `taosd` process. This is a common task which should be performed by a system operator, especially in the case of a cluster, to determine whether `taosd` has been started successfully. + +`taos -n rpc -h ` can be used to check whether the port of a started `taosd` can be accessed or not. If `taosd` process doesn't respond or is working abnormally, this command can be used to initiate a rpc communication with the specified fqdn to determine whether it's a network problem or whether `taosd` is abnormal. + +## Sync and Arbitrator Diagnostic + +```bash +taos -n sync -P 6040 -h +taos -n sync -P 6042 -h +``` + +The above commands can be executed in a Linux shell to check whether the port for sync is working well and whether the sync module on the server side is working well. Additionally, `-P 6042` is used to check whether the arbitrator is configured properly and is working well. + +## Network Speed Diagnostic + +`taos -n speed -h -P 6030 -N 10 -l 10000000 -S TCP` + +From version 2.2.0.0 onwards, the above command can be executed in a Linux shell to test network speed. The command sends uncompressed packages to a running `taosd` server process or a simulated server process started by `taos -n server` to test the network speed. Parameters can be used when testing network speed are as below: + +-n：When set to "speed", it means testing network speed. +-h：The FQDN or IP of the server process to be connected to; if not set, the FQDN configured in `taos.cfg` is used. +-P：The port of the server process to connect to, the default value is 6030. +-N：The number of packages that will be sent in the test, range is [1,10000], default value is 100. +-l：The size of each package in bytes, range is [1024, 1024 \* 1024 \* 1024], default value is 1024. +-S：The type of network packages to send, can be either TCP or UDP, default value is TCP. + +## FQDN Resolution Diagnostic + +`taos -n fqdn -h ` + +From version 2.2.0.0 onward, the above command can be executed in a Linux shell to test the resolution speed of FQDN. It can be used to try to resolve a FQDN to an IP address and record the time spent in this process. The parameters that can be used for this purpose are as below: + +-n：When set to "fqdn", it means testing the speed of resolving FQDN. +-h：The FQDN to be resolved. If not set, the `FQDN` parameter in `taos.cfg` is used by default. + +## Server Log + +The parameter `debugFlag` is used to control the log level of the `taosd` server process. The default value is 131. For debugging and tracing, it needs to be set to either 135 or 143 respectively. + +Once this parameter is set to 135 or 143, the log file grows very quickly especially when there is a huge volume of data insertion and data query requests. If all the logs are stored together, some important information may be missed very easily and so on the server side, important information is stored in a different place from other logs. + +- The log at level of INFO, WARNING and ERROR is stored in `taosinfo` so that it is easy to find important information +- The log at level of DEBUG (135) and TRACE (143) and other information not handled by `taosinfo` are stored in `taosdlog` + +## Client Log + +An independent log file, named as "taoslog+" is generated for each client program, i.e. a client process. The default value of `debugFlag` is also 131 and only logs at level of INFO/ERROR/WARNING are recorded. As stated above, for debugging and tracing, it needs to be changed to 135 or 143 respectively, so that logs at DEBUG or TRACE level can be recorded. + +The maximum length of a single log file is controlled by parameter `numOfLogLines` and only 2 log files are kept for each `taosd` server process. + +Log files are written in an async way to minimize the workload on disk, but the trade off for performance is that a few log lines may be lost in some extreme conditions. diff --git a/docs/en/13-operation/_category_.yml b/docs/en/13-operation/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..3231ce910dc959a0700eb3bd4dbf8c2a727dd09b --- /dev/null +++ b/docs/en/13-operation/_category_.yml @@ -0,0 +1 @@ +label: Administration diff --git a/docs/en/13-operation/index.md b/docs/en/13-operation/index.md new file mode 100644 index 0000000000000000000000000000000000000000..c64749c40e26f091e4a25e0238827ebceff4b069 --- /dev/null +++ b/docs/en/13-operation/index.md @@ -0,0 +1,12 @@ +--- +title: Administration +--- + +This chapter is mainly written for system administrators. It covers download, install/uninstall, data import/export, system monitoring, user management, connection management, capacity planning and system optimization. + +```mdx-code-block +import DocCardList from '@theme/DocCardList'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + + +``` diff --git a/docs/en/14-reference/02-rest-api/02-rest-api.mdx b/docs/en/14-reference/02-rest-api/02-rest-api.mdx new file mode 100644 index 0000000000000000000000000000000000000000..990af861961e9daf4ac775462e21d6d9852d17c1 --- /dev/null +++ b/docs/en/14-reference/02-rest-api/02-rest-api.mdx @@ -0,0 +1,307 @@ +--- +title: REST API +--- + +To support the development of various types of applications and platforms, TDengine provides an API that conforms to REST principles; namely REST API. To minimize the learning cost, unlike REST APIs for other database engines, TDengine allows insertion of SQL commands in the BODY of an HTTP POST request, to operate the database. + +:::note +One difference from the native connector is that the REST interface is stateless and so the `USE db_name` command has no effect. All references to table names and super table names need to specify the database name in the prefix. (Since version 2.2.0.0, TDengine supports specification of the db_name in RESTful URL. If the database name prefix is not specified in the SQL command, the `db_name` specified in the URL will be used. Since version 2.4.0.0, REST service is provided by taosAdapter by default and it requires that the `db_name` must be specified in the URL.) +::: + +## Installation + +The REST interface does not rely on any TDengine native library, so the client application does not need to install any TDengine libraries. The client application's development language only needs to support the HTTP protocol. + +## Verification + +If the TDengine server is already installed, it can be verified as follows: + +The following example is in an Ubuntu environment and uses the `curl` tool to verify that the REST interface is working. Note that the `curl` tool may need to be installed in your environment. + +The following example lists all databases on the host h1.taosdata.com. To use it in your environment, replace `h1.taosdata.com` and `6041` (the default port) with the actual running TDengine service FQDN and port number. + +```html +curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'show databases;' h1.taosdata.com:6041/rest/sql +``` + +The following return value results indicate that the verification passed. + +```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 request URL format + +``` +http://:/rest/sql/[db_name] +``` + +Parameter Description: + +- fqnd: FQDN or IP address of any host in the cluster +- port: httpPort configuration item in the configuration file, default is 6041 +- db_name: Optional parameter that specifies the default database name for the executed SQL command. (supported since version 2.2.0.0) + +For example, `http://h1.taos.com:6041/rest/sql/test` is a URL to `h1.taos.com:6041` and sets the default database name to `test`. + +TDengine supports both Basic authentication and custom authentication mechanisms, and subsequent versions will provide a standard secure digital signature mechanism for authentication. + +- The custom authentication information is as follows. More details about "token" later. + + ``` + Authorization: Taosd + ``` + +- Basic authentication information is shown below + + ``` + Authorization: Basic + ``` + +The HTTP request's BODY is a complete SQL command, and the data table in the SQL statement should be provided with a database prefix, e.g., `db_name.tb_name`. If the table name does not have a database prefix and the database name is not specified in the URL, the system will response an error because the HTTP module is a simple forwarder and has no awareness of the current DB. + +Use `curl` to initiate an HTTP request with a custom authentication method, with the following syntax. + +```bash +curl -H 'Authorization: Basic ' -d '' :/rest/sql/[db_name] +``` + +Or + +```bash +curl -u username:password -d '' :/rest/sql/[db_name] +``` + +where `TOKEN` is the string after Base64 encoding of `{username}:{password}`, e.g. `root:taosdata` is encoded as `cm9vdDp0YW9zZGF0YQ==`. + +## HTTP Return Format + +The return result is in JSON format, as follows: + +```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 +} +``` + +Description: + +- status: tells you whethre the operation result is success or failure. +- head: the definition of the table, or just one column "affected_rows" if no result set is returned. (As of version 2.0.17.0, it is recommended not to rely on the head return value to determine the data column type but rather use column_meta. In later versions, the head item may be removed from the return value.) +- column_meta: this item is added to the return value to indicate the data type of each column in the data with version 2.0.17.0 and later versions. Each column is described by three values: column name, column type, and type length. For example, `["current",6,4]` means that the column name is "current", the column type is 6, which is the float type, and the type length is 4, which is the float type with 4 bytes. If the column type is binary or nchar, the type length indicates the maximum length of content stored in the column, not the length of the specific data in this return value. When the column type is nchar, the type length indicates the number of Unicode characters that can be saved, not bytes. +- data: The exact data returned, presented row by row, or just [[affected_rows]] if no result set is returned. The order of the data columns in each row of data is the same as that of the data columns described in column_meta. +- rows: Indicates how many rows of data there are. + +The column types in column_meta are described as follows: + +- 1:BOOL +- 2:TINYINT +- 3:SMALLINT +- 4:INT +- 5:BIGINT +- 6:FLOAT +- 7:DOUBLE +- 8:BINARY +- 9:TIMESTAMP +- 10:NCHAR + +## Custom Authorization Code + +HTTP requests require an authorization code `` for identification purposes. The administrator usually provides the authorization code, and it can be obtained simply by sending an ``HTTP GET`` request as follows: + +```bash +curl http://:/rest/login// +``` + +Where `fqdn` is the FQDN or IP address of the TDengine database. `port` is the port number of the TDengine service. `username` is the database username. `password` is the database password. The return value is in `JSON` format, and the meaning of each field is as follows. + +- status: flag bit of the request result + +- code: return value code + +- desc: authorization code + +Example of getting authorization code. + +```bash +curl http://192.168.0.1:6041/rest/login/root/taosdata +``` + +Response body: + +```json +{ + "status": "succ", + "code": 0, + "desc": "/KfeAzX/f9na8qdtNZmtONryp201ma04bEl8LcvLUd7a8qdtNZmtONryp201ma04" +} +``` + +## For example + +- query all records from table d1001 of database demo + + ```bash + curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.d1001' 192.168.0.1:6041/rest/sql + ``` + + Response body: + + ```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 + } + ``` + +- Create database demo: + + ```bash + curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'create database demo' 192.168.0.1:6041/rest/sql + ``` + + Response body: + + ```json + { + "status": "succ", + "head": ["affected_rows"], + "column_meta": [["affected_rows", 4, 4]], + "data": [[1]], + "rows": 1 + } + ``` + +## Other Uses + +### Unix timestamps for result sets + +When the HTTP request URL uses `/rest/sqlt`, the returned result set's timestamp value will be in Unix timestamp format, for example: + +```bash +curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.d1001' 192.168.0.1:6041/rest/sqlt +``` + +Response body: + +```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 format for the result set + +When the HTTP request URL uses `/rest/sqlutc`, the timestamp of the returned result set will be expressed as a UTC format, for example: + +```bash + curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.t1' 192.168.0.1:6041/rest/sqlutc +``` + +Response body: + +```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 +} +``` + +## Important configuration items + +Only some configuration parameters related to the RESTful interface are listed below. Please see the description in the configuration file for other system parameters. + +- The port number of the external RESTful service is bound to 6041 by default (the actual value is serverPort + 11, so it can be changed by modifying the setting of the serverPort parameter). +- httpMaxThreads: the number of threads to start, default is 2 (the default value is rounded down to half of the CPU cores with version 2.0.17.0 and later versions). +- restfulRowLimit: the maximum number of result sets (in JSON format) to return. The default value is 10240. +- httpEnableCompress: whether to support compression, the default is not supported. Currently, TDengine only supports the gzip compression format. +- httpDebugFlag: logging switch, default is 131. 131: error and alarm messages only, 135: debug messages, 143: very detailed debug messages. +- httpDbNameMandatory: users must specify the default database name in the RESTful URL. The default is 0, which turns off this check. If set to 1, users must put a default database name in every RESTful URL. Otherwise, it will return an execution error and reject this SQL statement, regardless of whether the SQL statement executed at this time requires a specified database. + +:::note +If you are using the REST API provided by taosd, you should write the above configuration in taosd's configuration file taos.cfg. If you use the REST API of taosAdapter, you need to refer to taosAdapter [corresponding configuration method](/reference/taosadapter/). +::: diff --git a/docs-cn/14-reference/02-rest-api/_category_.yml b/docs/en/14-reference/02-rest-api/_category_.yml similarity index 100% rename from docs-cn/14-reference/02-rest-api/_category_.yml rename to docs/en/14-reference/02-rest-api/_category_.yml diff --git a/docs/en/14-reference/03-connector/03-connector.mdx b/docs/en/14-reference/03-connector/03-connector.mdx new file mode 100644 index 0000000000000000000000000000000000000000..44685579005c2cebd5e0194a10d457cd1199051e --- /dev/null +++ b/docs/en/14-reference/03-connector/03-connector.mdx @@ -0,0 +1,115 @@ +--- +title: Connector +--- + +TDengine provides a rich set of APIs (application development interface). To facilitate users to develop their applications quickly, TDengine supports connectors for multiple programming languages, including official connectors for C/C++, Java, Python, Go, Node.js, C#, and Rust. These connectors support connecting to TDengine clusters using both native interfaces (taosc) and REST interfaces (not supported in a few languages yet). Community developers have also contributed several unofficial connectors, such as the ADO.NET connector, the Lua connector, and the PHP connector. + +![TDengine Database image-connector](./connector.webp) + +## Supported platforms + +Currently, TDengine's native interface connectors can support platforms such as X64/X86/ARM64/ARM32/MIPS/Alpha hardware platforms and Linux/Win64/Win32 development environments. The comparison matrix is as follows. + +| **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** | ○ | ○ | ○ | ○ | ○ | ○ | ○ | + +Where ● means the official test verification passed, ○ means the unofficial test verification passed, -- means no assurance. + +Using REST connection can support a broader range of operating systems as it does not rely on client drivers. + +## Version support + +TDengine version updates often add new features, and the connector versions in the list are the best-fit versions of the connector. + +| **TDengine Versions** | **Java** | **Python** | **Go** | **C#** | **Node.js** | **Rust** | +| --------------------- | -------- | ---------- | ------------ | ------------- | --------------- | -------- | +| **2.4.0.14 and up** | 2.0.38 | current version | develop branch | 1.0.2 - 1.0.6 | 2.0.10 - 2.0.12 | current version | +| **2.4.0.6 and up** | 2.0.37 | current version | develop branch | 1.0.2 - 1.0.6 | 2.0.10 - 2.0.12 | current version | +| **2.4.0.4 - 2.4.0.5** | 2.0.37 | current version | develop branch | 1.0.2 - 1.0.6 | 2.0.10 - 2.0.12 | current version | +| **2.2.x.x ** | 2.0.36 | current version | master branch | n/a | 2.0.7 - 2.0.9 | current version | +| **2.0.x.x ** | 2.0.34 | current version | master branch | n/a | 2.0.1 - 2.0.6 | current version | + +## Functional Features + +Comparing the connector support for TDengine functional features as follows. + +### Using the native interface (taosc) + +| **Functional Features** | **Java** | **Python** | **Go** | **C#** | **Node.js** | **Rust** | +| -------------- | -------- | ---------- | ------ | ------ | ----------- | -------- | +| **Connection Management** | Support | Support | Support | Support | Support | Support | +| **Regular Query** | Support | Support | Support | Support | Support | Support | +| **Continuous Query** | Support | Support | Support | Support | Support | Support | +| **Parameter Binding** | Support | Support | Support | Support | Support | Support | +| **Subscription** | Support | Support | Support | Support | Support | Not Supported | +| **Schemaless** | Support | Support | Support | Support | Support | Support | +| **DataFrame** | Not Supported | Support | Not Supported | Not Supported | Not Supported | Not Supported | + +:::info +The different database framework specifications for various programming languages do not mean that all C/C++ interfaces need a wrapper. +::: + +### Using the REST interface + +| **Functional Features** | **Java** | **Python** | **Go** | **C# (not supported yet)** | **Node.js** | **Rust** | +| ------------------------------ | -------- | ---------- | -------- | ------------------ | ----------- | -------- | +| **Connection Management** | Support | Support | Support | N/A | Support | Support | +| **Regular Query** | Support | Support | Support | N/A | Support | Support | +| **Continous Query ** | Support | Support | Support | N/A | Support | Support | +| **Parameter Binding** | Not Supported | Not Supported | Not Supported | N/A | Not Supported | Not Supported | +| **Subscription** | Not Supported | Not Supported | Not Supported | N/A | Not Supported | Not Supported | +| **Schemaless** | Not supported | Not Supported | Not Supported | N/A | Not Supported | Not supported | +| **Bulk Pulling (based on WebSocket) **| Support | Not Supported | Not Supported | N/A | Not Supported | Not Supported | +| **DataFrame** | Not supported | Support | Not supported | N/A | Not supported | Not supported | + +:::warning + +- Regardless of the programming language chosen for the connector, TDengine versions 2.0 and above recommend that each thread of a database application create a separate connection. Or create a connection pool based on threads to avoid interference between threads with the "USE statement" state within a connection (but the connection's query and write operations are thread-safe). + +::: + +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"; + +## Install Client Driver + +:::info +The client driver needs to be installed if you use the native interface connector on a system that does not have the TDengine server software installed. + +::: + +### Installation steps + + + + + + + + + + +### Installation Verification + +After completing the above installation and configuration and you have confirmed that the TDengine service is up and running, you can execute the TDengine CLI tool to log in. + + + + + + + + + + diff --git a/docs-en/14-reference/03-connector/_category_.yml b/docs/en/14-reference/03-connector/_category_.yml similarity index 100% rename from docs-en/14-reference/03-connector/_category_.yml rename to docs/en/14-reference/03-connector/_category_.yml diff --git a/docs/en/14-reference/03-connector/_linux_install.mdx b/docs/en/14-reference/03-connector/_linux_install.mdx new file mode 100644 index 0000000000000000000000000000000000000000..3fa123794cd8ff304a1bc13449591194e7320aa9 --- /dev/null +++ b/docs/en/14-reference/03-connector/_linux_install.mdx @@ -0,0 +1,34 @@ +import PkgList from "/components/PkgList"; + +1. Download the TDengine client installation package + + + + [All Packages](https://www.taosdata.com/en/all-downloads/) + +2. Unzip + + Download the package to any directory the current user has read/write permission. Then execute `tar -xzvf TDengine-client-VERSION.tar.gz` command. + The VERSION should be the version of the package you just downloaded. + +3. Execute the install script + + Once the package is unzipped, you will see the following files in the directory: + - _ install_client.sh_: install script + - _ taos.tar.gz_: client driver package + - _ driver_: TDengine client driver + - _examples_: some example programs of different programming languages (C/C#/go/JDBC/MATLAB/python/R) + + You can run `install_client.sh` to install it. + +4. Edit taos.cfg + + Edit `taos.cfg` file (full path is `/etc/taos/taos.cfg` by default), modify `firstEP` with actual TDengine server's End Point, for example `h1.tdengine.com:6030` + +:::tip + +1. If the computer does not run the TDengine service but installs the TDengine client driver, then you need to config `firstEP` in `taos.cfg` only, and there is no need to configure `FQDN`; + +2. If you encounter the "Unable to resolve FQDN" error, please make sure the FQDN in the `/etc/hosts` file of the current computer is correctly configured, or the DNS service is correctly configured. + +::: diff --git a/docs/en/14-reference/03-connector/_preparation.mdx b/docs/en/14-reference/03-connector/_preparation.mdx new file mode 100644 index 0000000000000000000000000000000000000000..07ebdbca3d891ff51a254bc1b83016f1404bb47e --- /dev/null +++ b/docs/en/14-reference/03-connector/_preparation.mdx @@ -0,0 +1,10 @@ +- Client driver installed (mandatory for native connections, not required for REST connections) + +:::info + +Since the TDengine client driver is written in C, using the native connection requires loading the client driver shared library file, which is usually included in the TDengine installer. You can install either standard TDengine server installation package or [TDengine client installation package](/get-started/). For Windows development, you need to install the corresponding [Windows client](https://www.taosdata.com/cn/all-downloads/#TDengine-Windows-Client) for TDengine. + +- libtaos.so: After successful installation of TDengine on a Linux system, the dependent Linux version of the client driver `libtaos.so` file will be automatically linked to `/usr/lib/libtaos.so`, which is included in the Linux scannable path and does not need to be specified separately. +- taos.dll: After installing the client on Windows, the dependent Windows version of the client driver taos.dll file will be automatically copied to the system default search path C:/Windows/System32, again without the need to specify it separately. + +::: diff --git a/docs/en/14-reference/03-connector/_verify_linux.mdx b/docs/en/14-reference/03-connector/_verify_linux.mdx new file mode 100644 index 0000000000000000000000000000000000000000..a6e5455224bc19167d79c045f79365b452a57892 --- /dev/null +++ b/docs/en/14-reference/03-connector/_verify_linux.mdx @@ -0,0 +1,14 @@ +Execute TDengine CLI program `taos` directly from the Linux shell to connect to the TDengine service and enter the TDengine CLI interface, as shown in the following example. + +```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/en/14-reference/03-connector/_verify_windows.mdx b/docs/en/14-reference/03-connector/_verify_windows.mdx new file mode 100644 index 0000000000000000000000000000000000000000..daeb151bb1252436c0ef16eab1d50a64d664e437 --- /dev/null +++ b/docs/en/14-reference/03-connector/_verify_windows.mdx @@ -0,0 +1,14 @@ +Go to the `C:\TDengine` directory from `cmd` and execute TDengine CLI program `taos.exe` directly to connect to the TDengine service and enter the TDengine CLI interface, for example, as follows: + +```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/en/14-reference/03-connector/_windows_install.mdx b/docs/en/14-reference/03-connector/_windows_install.mdx new file mode 100644 index 0000000000000000000000000000000000000000..2819be615ee0a80da9f0324d8d41e9b247e8a7f6 --- /dev/null +++ b/docs/en/14-reference/03-connector/_windows_install.mdx @@ -0,0 +1,31 @@ +import PkgList from "/components/PkgList"; + +1. Download the client installation package + + + + [All downloads](https://www.taosdata.com/cn/all-downloads/) + +2. Execute the installer, select the default value as prompted, and complete the installation +3. Installation path + + The default installation path is C:\TDengine, including the following files (directories). + + - _taos.exe_ : TDengine CLI command-line program + - _cfg_ : configuration file directory + - _driver_: client driver dynamic link library + - _examples_: sample programs bash/C/C#/go/JDBC/Python/Node.js + - _include_: header files + - _log_ : log file + - _unins000.exe_: uninstaller + +4. configure taos.cfg + + Edit the taos.cfg file (default path C:\TDengine\cfg\taos.cfg) and change the firstEP to the End Point of the TDengine server, for example: `h1.tdengine.com:6030`. + +:::tip + +1. If you use FQDN to connect to the server, you must ensure the local network environment DNS is configured, or add FQDN addressing records in the `hosts` file, e.g., edit C:\Windows\system32\drivers\etc\hosts and add a record like the following: `192.168.1.99 h1.taosd.com`.. +2. Uninstall: Run unins000.exe to uninstall the TDengine client driver. + +::: diff --git a/docs/en/14-reference/03-connector/connector.webp b/docs/en/14-reference/03-connector/connector.webp new file mode 100644 index 0000000000000000000000000000000000000000..040cf5c26c726b345b2e0e5363dd3c677bec61be Binary files /dev/null and b/docs/en/14-reference/03-connector/connector.webp differ diff --git a/docs/en/14-reference/03-connector/cpp.mdx b/docs/en/14-reference/03-connector/cpp.mdx new file mode 100644 index 0000000000000000000000000000000000000000..17d864dd7268537a21b4d77fd2d4805fee14d063 --- /dev/null +++ b/docs/en/14-reference/03-connector/cpp.mdx @@ -0,0 +1,451 @@ +--- +sidebar_position: 1 +sidebar_label: C/C++ +title: C/C++ Connector +--- + +C/C++ developers can use TDengine's client driver and the C/C++ connector, to develop their applications to connect to TDengine clusters for data writing, querying, and other functions. To use the C/C++ connector you must include the TDengine header file _taos.h_, which lists the function prototypes of the provided APIs. The application also needs to link to the corresponding dynamic libraries on the platform where it is located. + +```c +#include +``` + +After TDengine server or client installation, `taos.h` is located at + +- Linux: `/usr/local/taos/include` +- Windows: `C:\TDengine\include` + +The dynamic libraries for the TDengine client driver are located in. + +- Linux: `/usr/local/taos/driver/libtaos.so` +- Windows: `C:\TDengine\taos.dll` + +## Supported platforms + +Please refer to [list of supported platforms](/reference/connector#supported-platforms) + +## Supported versions + +The version number of the TDengine client driver and the version number of the TDengine server should be same. A lower version of the client driver is compatible with a higher version of the server, if the first three version numbers are the same (i.e., only the fourth version number is different). For e.g. if the client version is x.y.z.1 and the server version is x.y.z.2 the client and server are compatible. But in general we do not recommend using a lower client version with a newer server version. It is also strongly discouraged to use a higher version of the client driver to access a lower version of the TDengine server. + +## Installation steps + +Please refer to the [Installation Steps](/reference/connector#installation-steps) for TDengine client driver installation + +## Establishing a connection + +The basic process of accessing a TDengine cluster using the client driver is to establish a connection, query and write data, close the connection, and clear the resource. + +The following is sample code for establishing a connection, which omits the query and writing sections and shows how to establish a connection, close a connection, and clear a resource. + +```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 query and writing */ + + taos_close(taos); + taos_cleanup(); +``` + +In the above example code, `taos_connect()` establishes a connection to port 6030 on the host where the client application is located, `taos_close()` closes the current connection, and `taos_cleanup()` clears the resources requested and used by the client driver. + +:::note + +- If not specified, when the return value of the API is an integer, _0_ means success. All others are error codes representing the reason for failure. When the return value is a pointer, _NULL_ means failure. +- All error codes and their corresponding causes are described in the `taoserror.h` file. + +::: + +## Example program + +This section shows sample code for standard access methods to TDengine clusters using the client driver. + +### Synchronous query example + +
+Synchronous query + +```c +{{#include examples/c/demo.c}} +``` + +
+ +### Asynchronous query example + +
+Asynchronous queries + +```c +{{#include examples/c/asyncdemo.c}} +``` + +
+ +### Parameter binding example + +
+Parameter Binding + +```c +{{#include examples/c/prepare.c}} +``` + +
+ +### Pattern-free writing example + +
+Mode free write + +```c +{{#include examples/c/schemaless.c}} +``` + +
+ +### Subscription and consumption example + +
+Subscribe and consume + +```c +{{#include examples/c/subscribe.c}} +``` + +
+ +:::info +More example code and downloads are available at [GitHub](https://github.com/taosdata/TDengine/tree/develop/examples/c). +You can find it in the installation directory under the `examples/c` path. This directory has a makefile and can be compiled under Linux by executing `make` directly. +**Hint:** When compiling in an ARM environment, please remove `-msse4.2` from the makefile. This option is only supported on the x64/x86 hardware platforms. + +::: + +## API reference + +The following describes the basic API, synchronous API, asynchronous API, subscription API, and schemaless write API of TDengine client driver, respectively. + +### Basic API + +The base API is used to do things like create database connections and provide a runtime environment for the execution of other APIs. + +- `void taos_init()` + + Initializes the runtime environment. If the API is not actively called, the driver will automatically call the API when `taos_connect()` is called, so the program generally does not need to call it manually. + +- `void taos_cleanup()` + + Cleans up the runtime environment and should be called before the application exits. + +- ` int taos_options(TSDB_OPTION option, const void * arg, ...) ` + + Set client options, currently supports region setting (`TSDB_OPTION_LOCALE`), character set +(`TSDB_OPTION_CHARSET`), time zone (`TSDB_OPTION_TIMEZONE`), configuration file path (`TSDB_OPTION_CONFIGDIR`). The region setting, character set, and time zone default to the current settings of the operating system. + +- `char *taos_get_client_info()` + + Get client version information. + +- `TAOS *taos_connect(const char *host, const char *user, const char *pass, const char *db, int port)` + + Creates a database connection and initializes the connection context. Among the parameters required from the user are: + + - host: FQDN of any node in the TDengine cluster + - user: user name + - pass: password + - db: the database name. Even if the user does not provide this, the connection will still work correctly. The user can create a new database through this connection. If the user provides the database name, it means that the database has already been created and the connection can be used for regular operations on the database. + - port: the port the taosd program is listening on + + NULL indicates a failure. The application needs to save the returned parameters for subsequent use. + + :::info + The same process can connect to multiple TDengine clusters according to different host/port + + ::: + +- `char *taos_get_server_info(TAOS *taos)` + + Get server-side version information. + +- ` int taos_select_db(TAOS *taos, const char *db)` + + Set the current default database to `db`. + +- `void taos_close(TAOS *taos)` + + Closes the connection, where `taos` is the handle returned by `taos_connect()`. + +### Synchronous query APIs + +The APIs described in this subsection are all synchronous interfaces. After being called by the application, it blocks and waits for a response until it gets a return result or an error message. + +- `TAOS_RES* taos_query(TAOS *taos, const char *sql)` + + Executes an SQL command, either a DQL, DML, or DDL statement. The `taos` parameter is a handle obtained with `taos_connect()`. If the return value is `NULL` this does not necessarily indicate a failure. You can get the error code, if any, by parsing the error code in the result set with the `taos_errno()` function. + +- `int taos_result_precision(TAOS_RES *res)` + + Returns the precision of the result set timestamp field, `0` for milliseconds, `1` for microseconds, and `2` for nanoseconds. + +- `TAOS_ROW taos_fetch_row(TAOS_RES *res)` + + Fetch the data in the query result set by row. + +- ` int taos_fetch_block(TAOS_RES *res, TAOS_ROW *rows)` + + Batch fetches the data in the query result set. The return value is the number of rows of the fetched data. + +- `int taos_num_fields(TAOS_RES *res)` and `int taos_field_count(TAOS_RES *res)` + + These two APIs are equivalent and are used to get the number of columns in the query result set. + +- `int* taos_fetch_lengths(TAOS_RES *res)` + + Gets the lengths of each field in the result set. The return value is an array whose length is the number of columns in the result set. + +- `int taos_affected_rows(TAOS_RES *res)` + + Get the number of rows affected by the executed SQL statement. + +- ` TAOS_FIELD *taos_fetch_fields(TAOS_RES *res)` + + Gets the properties of each column of the query result set (column name, column data type, column length), used in conjunction with `taos_num_fields()` to parse a tuple (one row) of data returned by `taos_fetch_row()`. The structure of `TAOS_FIELD` is as follows. + +```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)` + + Stops the execution of the current query. + +- ` void taos_free_result(TAOS_RES *res)` + + Frees the query result set and the associated resources. Be sure to call this API to free the resources after the query is completed. Failing to call this, may lead to a memory leak in the application. However, note that the application will crash if you call a function like `taos_consume()` to get the query results after freeing the resources. + +- `char *taos_errstr(TAOS_RES *res)` + + Get the reason for the failure of the last API call. The return value is an error message identified by a string. + +- 'int taos_errno(TAOS_RES *res)` + + Get the reason for the last API call failure. The return value is the error code. + +:::note +TDengine version 2.0 and above recommends that each thread of a database application create a separate connection or a connection pool based on threads. It is not recommended to pass the connection (TAOS\*) structure to different threads for shared use in the application. Queries, writes, and other operations issued that are based on TAOS structures are multi-thread safe, but state quantities such as the "USE statement" may interfere between threads. In addition, the C connector can dynamically create new database-oriented connections on demand (this procedure is not visible to the user), and it is recommended that `taos_close()` be called only at the final exit of the program to close the connection. + +::: + +### Asynchronous query API + +TDengine also provides a set of asynchronous API to handle data insertion and query operations with a higher performance. Given the same hardware and software environment, the asynchronous API can run data insertion 2 to 4 times faster than the synchronous API. The asynchronous API is called non-blocking and returns immediately before the system completes a specific database operation. The calling thread can go to work on other tasks, which can improve the performance of the whole application. Asynchronous APIs are particularly advantageous in the case of severe network latency. + +The asynchronous APIs require the application to provide a callback function with the following parameters: the first two parameters are consistent, and the third parameter depends on the API. The first parameter, `param`, is provided to the system when the application calls the asynchronous API. It is used for the callback so that the application can retrieve the context of the specific operation, depending on the implementation. The second parameter is the result set of the SQL operation. If it is NULL, such as insert operation, it means that there are no records returned, and if it is not NULL, such as select operation, it means that there are records returned. + +The asynchronous API has relatively high user requirements, so users can use it selectively according to specific application scenarios. The following are two important asynchronous APIs. + +- `void taos_query_a(TAOS *taos, const char *sql, void (*fp)(void *param, TAOS_RES *, int code), void *param);` + + Execute SQL command asynchronously. + + - taos: the database connection returned by calling `taos_connect()` + - sql: the SQL statement to be executed + - fp: user-defined callback function whose third parameter `code` is used to indicate whether the operation was successful or not, `0` means success, a negative number means failure (call `taos_errstr()` to get the reason for failure). When defining the callback function, the application mainly handles the second parameter `TAOS_RES *`, which is the result set returned by the query + - param: the application provides a parameter for the callback + +- `void taos_fetch_rows_a(TAOS_RES *res, void (*fp)(void *param, TAOS_RES *, int numOfRows), void *param);` + + Batch get the result set of an asynchronous query, which can only be used with `taos_query_a()`. The parameters are: + + - res: the result set returned by the `taos_query_a()` callback + - fp: callback function. Its parameter `param` is a user-definable parameter structure passed to the callback function; `numOfRows` is the number of rows of the fetched data (not a function of the entire query result set). In the callback function, the application can iterate forward to fetch each row of records in the batch by calling `taos_fetch_row()`. After reading all the rows in a block, the application needs to continue calling `taos_fetch_rows_a()` in the callback function to get the next batch of rows for processing until the number of rows returned, `numOfRows`, is zero (result return complete) or the number of rows is negative (query error). + +All TDengine's asynchronous APIs use a non-blocking call pattern. Applications can open multiple tables simultaneously using multiple threads and perform queries or inserts on each open table at the same time. It is important to note that **client applications must ensure that operations on the same table are fully serialized**. i.e., no second insert or query operation can be performed while an insert or query operation on the same table is incomplete (not returned). + +### Parameter Binding API + +In addition to direct calls to `taos_query()` to perform queries, TDengine also provides a set of `bind` APIs that supports parameter binding, similar in style to MySQL. TDengine currently only supports using a question mark `? ` to represent the parameter to be bound. + +Starting with versions 2.1.1.0 and 2.1.2.0, TDengine has significantly improved the bind APIs to support data writing (INSERT) scenarios. This avoids the resource consumption of SQL syntax parsing when writing data through the parameter binding interface, thus significantly improving write performance in most cases. A typical operation, in this case, is as follows. + +1. call `taos_stmt_init()` to create the parameter binding object. +2. call `taos_stmt_prepare()` to parse the INSERT statement. +3. call `taos_stmt_set_tbname()` to set the table name if it is reserved in the INSERT statement but not the TAGS. +4. call `taos_stmt_set_tbname_tags()` to set the table name and TAGS values if the table name and TAGS are reserved in the INSERT statement (for example, if the INSERT statement takes an automatic table build). +5. call `taos_stmt_bind_param_batch()` to set the value of VALUES in multiple columns, or call `taos_stmt_bind_param()` to set the value of VALUES in a single row. +6. call `taos_stmt_add_batch()` to add the currently bound parameters to the batch. +7. you can repeat steps 3 to 6 to add more rows of data to the batch. +8. call `taos_stmt_execute()` to execute the prepared batch instructions. +9. When execution is complete, call `taos_stmt_close()` to release all resources. + +Note: If `taos_stmt_execute()` succeeds, you can reuse the parsed result of `taos_stmt_prepare()` to bind new data in steps 3 to 6 if you don't need to change the SQL command. However, if there is an execution error, it is not recommended to continue working in the current context but release the resources and start again with `taos_stmt_init()` steps. + +The specific functions related to the interface are as follows (see also the [prepare.c](https://github.com/taosdata/TDengine/blob/develop/examples/c/prepare.c) file for the way to use the corresponding functions) + +- `TAOS_STMT* taos_stmt_init(TAOS *taos)` + + Creates a TAOS_STMT object for subsequent calls. + +- ` int taos_stmt_prepare(TAOS_STMT *stmt, const char *sql, unsigned long length)` + + Parse a SQL command, and bind the parsed result and parameter information to `stmt`. If the parameter length is greater than 0, use this parameter as the length of the SQL command. If it is equal to 0, the length of the SQL command will be determined automatically. + +- `int taos_stmt_bind_param(TAOS_STMT *stmt, TAOS_BIND *bind)` + + Not as efficient as `taos_stmt_bind_param_batch()`, but can support non-INSERT type SQL statements. + To bind parameters, bind points to an array (representing the row of data to be bound), making sure that the number and order of the elements in this array are the same as the parameters in the SQL statement. taos_bind is used similarly to MYSQL_BIND in MySQL, as defined below. + + ```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)` + + (Available in 2.1.1.0 and later versions, only supported for replacing parameter values in INSERT statements) + When the table name in the SQL command uses `? ` placeholder, you can use this function to bind a specific table name. + +- `int taos_stmt_set_tbname_tags(TAOS_STMT* stmt, const char* name, TAOS_BIND* tags)` + + (Available in 2.1.2.0 and later versions, only supported for replacing parameter values in INSERT statements) + When the table name and TAGS in the SQL command both use `? `, you can use this function to bind the specific table name and the specific TAGS value. The most typical usage scenario is an INSERT statement that uses the automatic table building function (the current version does not support specifying specific TAGS columns.) The number of columns in the TAGS parameter needs to be the same as the number of TAGS requested in the SQL command. + +- `int taos_stmt_bind_param_batch(TAOS_STMT* stmt, TAOS_MULTI_BIND* bind)` + + (Available in 2.1.1.0 and later versions, only supported for replacing parameter values in INSERT statements) + To pass the data to be bound in a multi-column manner, it is necessary to ensure that the order of the data columns and the number of columns given here are the same as the VALUES parameter in the SQL statement. The specific definition of TAOS_MULTI_BIND is as follows. + + ```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)` + + Adds the currently bound parameter to the batch. After calling this function, you can call `taos_stmt_bind_param()` or `taos_stmt_bind_param_batch()` again to bind a new parameter. Note that this function only supports INSERT/IMPORT statements. Other SQL command such as SELECT will return an error. + +- `int taos_stmt_execute(TAOS_STMT *stmt)` + + Execute the prepared statement. Currently, a statement can only be executed once. + +- ` TAOS_RES* taos_stmt_use_result(TAOS_STMT *stmt)` + + Gets the result set of a statement. Use the result set in the same way as in the non-parametric call. When finished, `taos_free_result()` should be called on this result set to free resources. + +- `int taos_stmt_close(TAOS_STMT *stmt)` + + Finish execution and release all resources. + +- ` char * taos_stmt_errstr(TAOS_STMT *stmt)` + + (Available in 2.1.3.0 and later versions) + Used to get error information if other STMT APIs return errors (return error codes or null pointers). + +### Schemaless Writing API + +In addition to writing data using the SQL method or the parameter binding API, writing can also be done using schemaless writing, which eliminates the need to create a super table/data sub-table structure in advance and writes the data directly. The TDengine system automatically creates and maintains the required table structure based on the written data content. The use of schemaless writing is described in the chapter [Schemaless Writing](/reference/schemaless/), and the C/C++ API used with it is described here. + +- `TAOS_RES* taos_schemaless_insert(TAOS* taos, const char* lines[], int numLines, int protocol, int precision)` + + **Function description** + This interface writes the text data of the line protocol to TDengine. + + **Parameter description** + - taos: database connection, established by the `taos_connect()` function. + - lines: text data. A pattern-free text string that meets the parsing format requirements. + - numLines: the number of lines of text data, cannot be 0. + - protocol: the protocol type of the lines, used to identify the text data format. + - precision: precision string for the timestamp in the text data. + + **return value** + TAOS_RES structure, application can get error message by using `taos_errstr()` and also error code by using `taos_errno()`. + In some cases, the returned TAOS_RES is `NULL`, and it is still possible to call `taos_errno()` to safely get the error code information. + The returned TAOS_RES needs to be freed by the caller in order to avoid memory leaks. + + **Description** + The protocol type is enumerated and contains the following three formats. + + - TSDB_SML_LINE_PROTOCOL: InfluxDB line protocol (Line Protocol) + - TSDB_SML_TELNET_PROTOCOL: OpenTSDB Telnet Text Line Protocol + - TSDB_SML_JSON_PROTOCOL: OpenTSDB Json protocol format + + The timestamp resolution definitions are in the taos.h file, as follows + + - 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 + + Note that the timestamp resolution parameter only takes effect when the protocol type is `SML_LINE_PROTOCOL`. + For OpenTSDB's text protocol, timestamp resolution follows its official resolution rules - time precision is confirmed by the number of characters contained in the timestamp. + + **Supported Versions** + This feature interface is supported from version 2.3.0.0. + +### Subscription and Consumption API + +The Subscription API currently supports subscribing to one or more tables and continuously fetching the latest data written to them by polling periodically. + +- `TAOS_SUB *taos_subscribe(TAOS* taos, int restart, const char* topic, const char *sql, TAOS_SUBSCRIBE_CALLBACK fp, void *param, int interval)` + + This function is responsible for starting the subscription service, returning the subscription object on success and `NULL` on failure, with the following parameters. + + - taos: the database connection that has been established. + - restart: if the subscription already exists, whether to restart or continue the previous subscription. + - topic: the topic of the subscription (i.e., the name). This parameter is the unique identifier of the subscription. + - sql: the query statement of the subscription which can only be a _select_ statement. Only the original data should be queried, and data can only be queried in temporal order. + - fp: the callback function when the query result is received only used when called asynchronously. This parameter should be passed `NULL` when called synchronously. The function prototype is described below. + - param: additional parameter when calling the callback function. The system API will pass it to the callback function as is, without any processing. + - interval: polling period in milliseconds. The callback function will be called periodically according to this parameter when called asynchronously. The interval should not be too small to avoid impact on system performance when called synchronously. If the interval between two calls to `taos_consume()` is less than this period, the API will block until the interval exceeds this period. + +- ` typedef void (*TAOS_SUBSCRIBE_CALLBACK)(TAOS_SUB* tsub, TAOS_RES *res, void* param, int code)` + + The prototype of the callback function in asynchronous mode with the following parameters + + - tsub: subscription object + - res: query result set, note that there may be no records in the result set + - param: additional parameters provided by the client program when calling `taos_subscribe()` + - code: error code + + :::note + The callback function should not take too long to process, especially if the returned result set has a lot of data. Otherwise, it may lead to an abnormal state, such as client blocking. If you must perform complex calculations, we recommend handling them in a separate thread. + + ::: + +- `TAOS_RES *taos_consume(TAOS_SUB *tsub)` + + In synchronous mode, this function is used to fetch the results of a subscription. The user application places it in a loop. If the interval between two calls to `taos_consume()` is less than the polling period of the subscription, the API will block until the interval exceeds this period. If a new record arrives in the database, the API returns that latest record. Otherwise, it returns an empty result set with no records. If the return value is `NULL`, there is a system error. This API should not be called by user programs in asynchronous mode. + + :::note + After calling `taos_consume()`, the user application should make sure to call `taos_fetch_row()` or `taos_fetch_block()` to process the subscription results as soon as possible. Otherwise, the server-side will keep caching the query result data waiting to be read by the client, which in extreme cases will cause the server side to run out of memory and affect the stability of the service. + + ::: + +- `void taos_unsubscribe(TAOS_SUB *tsub, int keepProgress)` + + Unsubscribe. If the parameter `keepProgress` is not 0, the API will keep the progress information of the subscription, and subsequent calls to `taos_subscribe()` will continue based on this progress; otherwise, the progress information will be deleted, and subsequent readings will have to be restarted. diff --git a/docs/en/14-reference/03-connector/csharp.mdx b/docs/en/14-reference/03-connector/csharp.mdx new file mode 100644 index 0000000000000000000000000000000000000000..2d1b62fe89c542280c4264dd478538fa00634c79 --- /dev/null +++ b/docs/en/14-reference/03-connector/csharp.mdx @@ -0,0 +1,190 @@ +--- +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 Preparation from "./_preparation.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` is a C# language connector provided by TDengine that allows C# developers to develop C# applications that access TDengine cluster data. + +The `TDengine.Connector` connector supports connect to TDengine instances via the TDengine client driver (taosc), providing data writing, querying, subscription, schemaless writing, bind interface, etc. The `TDengine.Connector` currently does not provide a REST connection interface. Developers can write their RESTful application by referring to the [REST API](/reference/rest-api/) documentation. + +This article describes how to install `TDengine.Connector` in a Linux or Windows environment and connect to TDengine clusters via `TDengine.Connector` to perform basic operations such as data writing and querying. + +The source code of `TDengine.Connector` is hosted on [GitHub](https://github.com/taosdata/taos-connector-dotnet). + +## Supported Platforms + +The supported platforms are the same as those supported by the TDengine client driver. + +## Version support + +Please refer to [version support list](/reference/connector#version-support) + +## Supported features + +1. Connection Management +2. General Query +3. Continuous Query +4. Parameter Binding +5. Subscription +6. Schemaless + +## Installation Steps + +### Pre-installation preparation + +* Install the [.NET SDK](https://dotnet.microsoft.com/download) +* [Nuget Client](https://docs.microsoft.com/en-us/nuget/install-nuget-client-tools) (optional installation) +* Install TDengine client driver, please refer to [Install client driver](/reference/connector/#install-client-driver) for details + +### Install via dotnet CLI + + + + +You can reference the `TDengine.Connector` published in Nuget to the current project via the `dotnet` command under the path of the existing .NET project. + +``` +dotnet add package TDengine.Connector +``` + + + + +You can download TDengine's source code and directly reference the latest version of the TDengine.Connector library + +``` +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 +``` + + + +## Create a connection + +```csharp +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(); + } + } +} + +``` + +## Usage examples + +### Write data + +#### SQL Write + + + +#### InfluxDB line protocol write + + + +#### OpenTSDB Telnet line protocol write + + + +#### OpenTSDB JSON line protocol write + + + +### Query data + +#### Synchronous Query + + + +#### Asynchronous query + + + +### More sample programs + +|Sample program |Sample program description | +|--------------------------------------------------------------------------------------------------------------------|------------ --------------------------------| +| [C#checker](https://github.com/taosdata/TDengine/tree/develop/examples/C%23/C%23checker) | Using TDengine.Connector, you can test C# Driver's synchronous writes and queries | +| [TDengineTest](https://github.com/taosdata/TDengine/tree/develop/examples/C%23/TDengineTest) | A simple example of writing and querying using TDengine. +| [insertCn](https://github.com/taosdata/TDengine/tree/develop/examples/C%23/insertCn) | Example of writing and querying Chinese characters using TDengine. +| [jsonTag](https://github.com/taosdata/TDengine/tree/develop/examples/C%23/jsonTag) | Example of writing and querying JSON tag type data using TDengine. +| [stmt](https://github.com/taosdata/TDengine/tree/develop/examples/C%23/stmt) | Example of parameter binding using TDengine. +| [schemaless](https://github.com/taosdata/TDengine/tree/develop/examples/C%23/schemaless) | Example of writing with schemaless implemented using TDengine. |schemaless +| [benchmark](https://github.com/taosdata/TDengine/tree/develop/examples/C%23/taosdemo) | A simple benchmark implemented using TDengine. +| [async query](https://github.com/taosdata/taos-connector-dotnet/blob/develop/examples/QueryAsyncSample.cs) | Example of an asynchronous query implemented using TDengine. Example of an asynchronous query +| [subscribe](https://github.com/taosdata/taos-connector-dotnet/blob/develop/examples/SubscribeSample.cs) | Example of subscribing to data using TDengine. Data example + +## Important update records + +| TDengine.Connector | Description | +|--------------------|--------------------------------| +| 1.0.6 | Fix schemaless bug in 1.0.4 and 1.0.5. | +| 1.0.5 | Fix Windows sync query Chinese error bug. | 1.0.4 | Fix schemaless bug. +| 1.0.4 | Add asynchronous query, subscription, and other functions. Fix the binding parameter bug. +| 1.0.3 | Add parameter binding, schemaless, JSON tag, etc. | new +| 1.0.2 | Add connection management, synchronous query, error messages, etc. ## Other + +## Other descriptions + +### Third-party driver + +`Taos` is an ADO.NET connector for TDengine, supporting Linux and Windows platforms. Community contributor `Maikebing@@maikebing contributes the connector`. Please refer to: + +* Interface download: +* Usage notes: + +## Frequently Asked Questions + +1. "Unable to establish connection", "Unable to resolve FQDN" + + Usually, it's caused by an incorrect FQDN configuration. Please refer to this section in the [FAQ](https://docs.tdengine.com/2.4/train-faq/faq/#2-how-to-handle-unable-to-establish-connection) to troubleshoot. + +2. Unhandled exception. System.DllNotFoundException: Unable to load DLL 'taos' or one of its dependencies: The specified module cannot be found. + + This is usually because the program did not find the dependent client driver. The solution is to copy `C:\TDengine\driver\taos.dll` to the `C:\Windows\System32\` directory on Windows, and create the following soft link on Linux `ln -s /usr/local/taos/driver/libtaos.so.x.x .x.x /usr/lib/libtaos.so` will work. + +## API Reference + +[API Reference](https://docs.taosdata.com/api/connector-csharp/html/860d2ac1-dd52-39c9-e460-0829c4e5a40b.htm) diff --git a/docs/en/14-reference/03-connector/go.mdx b/docs/en/14-reference/03-connector/go.mdx new file mode 100644 index 0000000000000000000000000000000000000000..8a05f2d841bbcdbab2bdb7471691ca0ae49a4f6b --- /dev/null +++ b/docs/en/14-reference/03-connector/go.mdx @@ -0,0 +1,415 @@ +--- +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 Preparation from "./_preparation.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` is the official Go language connector for TDengine. It implements the [database/sql](https://golang.org/pkg/database/sql/) package, the generic Go language interface to SQL databases. Go developers can use it to develop applications that access TDengine cluster data. + +`driver-go` provides two ways to establish connections. One is **native connection**, which connects to TDengine instances natively through the TDengine client driver (taosc), supporting data writing, querying, subscriptions, schemaless writing, and bind interface. The other is the **REST connection**, which connects to TDengine instances via the REST interface provided by taosAdapter. The set of features implemented by the REST connection differs slightly from those implemented by the native connection. + +This article describes how to install `driver-go` and connect to TDengine clusters and perform basic operations such as data query and data writing through `driver-go`. + +The source code of `driver-go` is hosted on [GitHub](https://github.com/taosdata/driver-go). + +## Supported Platforms + +Native connections are supported on the same platforms as the TDengine client driver. +REST connections are supported on all platforms that can run Go. + +## Version support + +Please refer to [version support list](/reference/connector#version-support) + +## Supported features + +### Native connections + +A "native connection" is established by the connector directly to the TDengine instance via the TDengine client driver (taosc). The supported functional features are: + +* Normal queries +* Continuous queries +* Subscriptions +* schemaless interface +* parameter binding interface + +### REST connection + +A "REST connection" is a connection between the application and the TDengine instance via the REST API provided by the taosAdapter component. The following features are supported: + +* General queries +* Continuous queries + +## Installation steps + +### Pre-installation + +- Install Go development environment (Go 1.14 and above, GCC 4.8.5 and above) +- If you use the native connector, please install the TDengine client driver. Please refer to [Install Client Driver](/reference/connector/#install-client-driver) for specific steps + +Configure the environment variables and check the command. + +* `go env` +* `gcc -v` + +### Use go get to install + +``` +go get -u github.com/taosdata/driver-go/v2@develop +``` + +### Manage with go mod + +1. Initialize the project with the `go mod` command. + + ```text + go mod init taos-demo + ``` + +2. Introduce taosSql + + ```go + import ( + "database/sql" + _ "github.com/taosdata/driver-go/v2/taosSql" + ) + ``` + +3. Update the dependency packages with `go mod tidy`. + + ```text + go mod tidy + ``` + +4. Run the program with `go run taos-demo` or compile the binary with the `go build` command. + + ```text + go run taos-demo + go build + ``` + +## Create a connection + +### Data source name (DSN) + +Data source names have a standard format, e.g. [PEAR DB](http://pear.php.net/manual/en/package.database.db.intro-dsn.php), but no type prefix (square brackets indicate optionally): + +``` text +[username[:password]@][protocol[(address)]]/[dbname][?param1=value1&... ¶mN=valueN] +``` + +DSN in full form. + +```text +username:password@protocol(address)/dbname?param=value +``` + +### Connecting via connector + + + + +_taosSql_ implements Go's `database/sql/driver` interface via cgo. You can use the [`database/sql`](https://golang.org/pkg/database/sql/) interface by simply introducing the driver. + +Use `taosSql` as `driverName` and use a correct [DSN](#DSN) as `dataSourceName`, DSN supports the following parameters. + +* configPath specifies the `taos.cfg` directory + +Example. + +```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_ implements Go's `database/sql/driver` interface via `http client`. You can use the [`database/sql`](https://golang.org/pkg/database/sql/) interface by simply introducing the driver. + +Use `taosRestful` as `driverName` and use a correct [DSN](#DSN) as `dataSourceName` with the following parameters supported by the DSN. + +* `disableCompression` whether to accept compressed data, default is true do not accept compressed data, set to false if transferring data using gzip compression. +* `readBufferSize` The default size of the buffer for reading data is 4K (4096), which can be adjusted upwards when the query result has a lot of data. + +Example. + +```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 + } +} +``` + + + +## Usage examples + +### Write data + +#### SQL Write + + + +#### InfluxDB line protocol write + + + +#### OpenTSDB Telnet line protocol write + + + +#### OpenTSDB JSON line protocol write + + + +### Query data + + + +### More sample programs + +* [sample program](https://github.com/taosdata/TDengine/tree/develop/examples/go) +* [Video tutorial](https://www.taosdata.com/blog/2020/11/11/1951.html). + +## Usage limitations + +Since the REST interface is stateless, the `use db` syntax will not work. You need to put the db name into the SQL command, e.g. `create table if not exists tb1 (ts timestamp, a int)` to `create table if not exists test.tb1 (ts timestamp, a int)` otherwise it will report the error `[0x217] Database not specified or available`. + +You can also put the db name in the DSN by changing `root:taosdata@http(localhost:6041)/` to `root:taosdata@http(localhost:6041)/test`. This method is supported by taosAdapter since TDengine 2.4.0.5. Executing the `create database` statement when the specified db does not exist will not report an error while executing other queries or writing against that db will report an error. + +The complete example is as follows. + +```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) + } +} +``` + +## Frequently Asked Questions + +1. Cannot find the package `github.com/taosdata/driver-go/v2/taosRestful` + + Change the `github.com/taosdata/driver-go/v2` line in the require block of the `go.mod` file to `github.com/taosdata/driver-go/v2 develop`, then execute `go mod tidy`. + +2. bind interface in database/sql crashes + + REST does not support parameter binding related interface. It is recommended to use `db.Exec` and `db.Query`. + +3. error `[0x217] Database not specified or available` after executing other statements with `use db` statement + + The execution of SQL command in the REST interface is not contextual, so using `use db` statement will not work, see the usage restrictions section above. + +4. use `taosSql` without error but use `taosRestful` with error `[0x217] Database not specified or available` + + Because the REST interface is stateless, using the `use db` statement will not take effect. See the usage restrictions section above. + +5. Upgrade `github.com/taosdata/driver-go/v2/taosRestful` + + Change the `github.com/taosdata/driver-go/v2` line in the `go.mod` file to `github.com/taosdata/driver-go/v2 develop`, then execute `go mod tidy`. + +6. `readBufferSize` parameter has no significant effect after being increased + + Increasing `readBufferSize` will reduce the number of `syscall` calls when fetching results. If the query result is smaller, modifying this parameter will not improve performance significantly. If you increase the parameter value too much, the bottleneck will be parsing JSON data. If you need to optimize the query speed, you must adjust the value based on the actual situation to achieve the best query performance. + +7. `disableCompression` parameter is set to `false` when the query efficiency is reduced + + When set `disableCompression` parameter to `false`, the query result will be compressed by `gzip` and then transmitted, so you have to decompress the data by `gzip` after getting it. + +8. `go get` command can't get the package, or timeout to get the package + + Set Go proxy `go env -w GOPROXY=https://goproxy.cn,direct`. + +## Common APIs + +### database/sql API + +* `sql.Open(DRIVER_NAME string, dataSourceName string) *DB` + + Use This API to open a DB, returning an object of type \*DB. + +:::info +This API is created successfully without checking permissions, but only when you execute a Query or Exec, and check if user/password/host/port is legal. + +::: + +* `func (db *DB) Exec(query string, args . .interface{}) (Result, error)` + + `sql.Open` built-in method to execute non-query related SQL. + +* `func (db *DB) Query(query string, args ... . interface{}) (*Rows, error)` + + `sql.Open` Built-in method to execute query statements. + +### Advanced functions (af) API + +The `af` package encapsulates TDengine advanced functions such as connection management, subscriptions, schemaless, parameter binding, etc. + +#### Connection management + +* `af.Open(host, user, pass, db string, port int) (*Connector, error)` + + This API creates a connection to taosd via cgo. + +* `func (conn *Connector) Close() error` + + Closes the connection. + +#### Subscribe to + +* `func (conn *Connector) Subscribe(restart bool, topic string, sql string, interval time.Duration) (Subscriber, error)` + + Subscribe to data. + +* `func (s *taosSubscriber) Consume() (driver.Rows, error)` + + Consume the subscription data, returning the `Rows` structure of the `database/sql/driver` package. + +* `func (s *taosSubscriber) Unsubscribe(keepProgress bool)` + + Unsubscribe from data. + +#### schemaless + +* `func (conn *Connector) InfluxDBInsertLines(lines []string, precision string) error` + + Write to influxDB line protocol. + +* `func (conn *Connector) OpenTSDBInsertTelnetLines(lines []string) error` + + Write OpenTDSB telnet protocol data. + +* `func (conn *Connector) OpenTSDBInsertJsonPayload(payload string) error` + + Writes OpenTSDB JSON protocol data. + +#### parameter binding + +* `func (conn *Connector) StmtExecute(sql string, params *param.Param) (res driver.Result, err error)` + + Parameter bound single row insert. + +* `func (conn *Connector) StmtQuery(sql string, params *param.Param) (rows driver.Rows, err error)` + + Parameter bound query that returns the `Rows` structure of the `database/sql/driver` package. + +* `func (conn *Connector) InsertStmt() *insertstmt. + + Initialize the parameters. + +* `func (stmt *InsertStmt) Prepare(sql string) error` + + Parameter binding preprocessing SQL statement. + +* `func (stmt *InsertStmt) SetTableName(name string) error` + + Bind the set table name parameter. + +* `func (stmt *InsertStmt) SetSubTableName(name string) error` + + Parameter binding to set the sub table name. + +* `func (stmt *InsertStmt) BindParam(params []*param.Param, bindType *param.ColumnType) error` + + Parameter bind multiple rows of data. + +* `func (stmt *InsertStmt) AddBatch() error` + + Add to a parameter-bound batch. + +* `func (stmt *InsertStmt) Execute() error` + + Execute a parameter binding. + +* `func (stmt *InsertStmt) GetAffectedRows() int` + + Gets the number of affected rows inserted by the parameter binding. + +* `func (stmt *InsertStmt) Close() error` + + Closes the parameter binding. + +## API Reference + +Full API see [driver-go documentation](https://pkg.go.dev/github.com/taosdata/driver-go/v2) diff --git a/docs/en/14-reference/03-connector/java.mdx b/docs/en/14-reference/03-connector/java.mdx new file mode 100644 index 0000000000000000000000000000000000000000..ff15acf1a9c5dbfd74e6f3101459cfc7bdeda515 --- /dev/null +++ b/docs/en/14-reference/03-connector/java.mdx @@ -0,0 +1,845 @@ +--- +toc_max_heading_level: 4 +sidebar_position: 2 +sidebar_label: Java +title: TDengine Java Connector +description: TDengine Java based on JDBC API and provide both native and REST connections +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +'taos-jdbcdriver' is TDengine's official Java language connector, which allows Java developers to develop applications that access the TDengine database. 'taos-jdbcdriver' implements the interface of the JDBC driver standard and provides two forms of connectors. One is to connect to a TDengine instance natively through the TDengine client driver (taosc), which supports functions including data writing, querying, subscription, schemaless writing, and bind interface. And the other is to connect to a TDengine instance through the REST interface provided by taosAdapter (2.4.0.0 and later). The implementation of the REST connection and those of the native connections have slight differences in features. + +![TDengine Database tdengine-connector](tdengine-jdbc-connector.webp) + +The preceding diagram shows two ways for a Java app to access TDengine via connector: + +- JDBC native connection: Java applications use TSDBDriver on physical node 1 (pnode1) to call client-driven directly (`libtaos.so` or `taos.dll`) APIs to send writing and query requests to taosd instances located on physical node 2 (pnode2). +- JDBC REST connection: The Java application encapsulates the SQL as a REST request via RestfulDriver, sends it to the REST server (taosAdapter) on physical node 2. taosAdapter forwards the request to TDengine server and returns the result. + +The REST connection, which does not rely on TDengine client drivers, is more convenient and flexible, in addition to being cross-platform. However the performance is about 30% lower than that of the native connection. + +:::info +TDengine's JDBC driver implementation is as consistent as possible with the relational database driver. Still, there are differences in the use scenarios and technical characteristics of TDengine and relational object databases. So 'taos-jdbcdriver' also has some differences from traditional JDBC drivers. It is important to keep the following points in mind: + +- TDengine does not currently support delete operations for individual data records. +- Transactional operations are not currently supported. + +::: + +## Supported platforms + +Native connection supports the same platform as TDengine client-driven support. +REST connection supports all platforms that can run Java. + +## Version support + +Please refer to [Version Support List](/reference/connector#version-support). + +## TDengine DataType vs. Java DataType + +TDengine currently supports timestamp, number, character, Boolean type, and the corresponding type conversion with Java is as follows: + +| TDengine DataType | JDBCType (driver version < 2.0.24) | JDBCType (driver version > = 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 | + +**Note**: Only TAG supports JSON types + +## Installation steps + +### Pre-installation preparation + +Before using Java Connector to connect to the database, the following conditions are required. + +- Java 1.8 or above runtime environment and Maven 3.6 or above installed +- TDengine client driver installed (required for native connections, not required for REST connections), please refer to [Installing Client Driver](/reference/connector#Install-Client-Driver) + +### Install the connectors + + + + +- [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) + +Add following dependency in the `pom.xml` file of your Maven project: + +```xml + + com.taosdata.jdbc + taos-jdbcdriver + 2.0.** + +``` + + + + +You can build Java connector from source code after cloning the TDengine project: + +``` +git clone https://github.com/taosdata/taos-connector-jdbc.git +cd taos-connector-jdbc +mvn clean install -Dmaven.test.skip=true +``` + +After compilation, a jar package named taos-jdbcdriver-2.0.XX-dist.jar is generated in the target directory, and the compiled jar file is automatically placed in the local Maven repository. + + + + +## Establish a connection + +TDengine's JDBC URL specification format is: +`jdbc:[TAOS| TAOS-RS]://[host_name]:[port]/[database_name]? [user={user}|&password={password}|&charset={charset}|&cfgdir={config_dir}|&locale={locale}|&timezone={timezone}]` + +For establishing connections, native connections differ slightly from REST connections. + + + + +```java +Class.forName("com.taosdata.jdbc.TSDBDriver"); +String jdbcUrl = "jdbc:TAOS://taosdemo.com:6030/test?user=root&password=taosdata"; +Connection conn = DriverManager.getConnection(jdbcUrl); +``` + +In the above example, TSDBDriver, which uses a JDBC native connection, establishes a connection to a hostname `taosdemo.com`, port `6030` (the default port for TDengine), and a database named `test`. In this URL, the user name `user` is specified as `root`, and the `password` is `taosdata`. + +Note: With JDBC native connections, taos-jdbcdriver relies on the client driver (`libtaos.so` on Linux; `taos.dll` on Windows). + +The configuration parameters in the URL are as follows: + +- user: Log in to the TDengine username. The default value is 'root'. +- password: User login password, the default value is 'taosdata'. +- cfgdir: client configuration file directory path, default '/etc/taos' on Linux OS, 'C:/TDengine/cfg' on Windows OS. +- charset: The character set used by the client, the default value is the system character set. +- locale: Client locale, by default, use the system's current locale. +- timezone: The time zone used by the client, the default value is the system's current time zone. +- batchfetch: true: pulls result sets in batches when executing queries; false: pulls result sets row by row. The default value is: false. Enabling batch pulling and obtaining a batch of data can improve query performance when the query data volume is large. +- batchErrorIgnore:true: When executing statement executeBatch, if there is a SQL execution failure in the middle, the following SQL will continue to be executed. false: No more statements after the failed SQL are executed. The default value is: false. + +For more information about JDBC native connections, see [Video Tutorial](https://www.taosdata.com/blog/2020/11/11/1955.html). + +**Connect using the TDengine client-driven configuration file ** + +When you use a JDBC native connection to connect to a TDengine cluster, you can use the TDengine client driver configuration file to specify parameters such as `firstEp` and `secondEp` of the cluster in the configuration file as below: + +1. Do not specify hostname and port in Java applications. + + ```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. specify the firstEp and the secondEp in the configuration file taos.cfg + + ```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 + ``` + +In the above example, JDBC uses the client's configuration file to establish a connection to a hostname `cluster_node1`, port 6030, and a database named `test`. When the firstEp node in the cluster fails, JDBC attempts to connect to the cluster using secondEp. + +In TDengine, as long as one node in firstEp and secondEp is valid, the connection to the cluster can be established normally. + +:::note +The configuration file here refers to the configuration file on the machine where the application that calls the JDBC Connector is located, the default path is `/etc/taos/taos.cfg` on Linux, and the default path is `C://TDengine/cfg/taos.cfg` on Windows. + +::: + + + + +```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); +``` + +In the above example, a RestfulDriver with a JDBC REST connection is used to establish a connection to a database named `test` with hostname `taosdemo.com` on port `6041`. The URL specifies the user name as `root` and the password as `taosdata`. + +There is no dependency on the client driver when Using a JDBC REST connection. Compared to a JDBC native connection, only the following are required: + +1. driverClass specified as "com.taosdata.jdbc.rs.RestfulDriver". +2. jdbcUrl starting with "jdbc:TAOS-RS://". +3. use 6041 as the connection port. + +The configuration parameters in the URL are as follows. + +- user: Login TDengine user name, default value 'root'. +- password: user login password, default value 'taosdata'. +- batchfetch: true: pull the result set in batch when executing the query; false: pull the result set row by row. The default value is false. batchfetch uses HTTP for data transfer. The JDBC REST connection supports bulk data pulling function in taos-jdbcdriver-2.0.38 and TDengine 2.4.0.12 and later versions. taos-jdbcdriver and TDengine transfer data via WebSocket connection. Compared with HTTP, WebSocket enables JDBC REST connection to support large data volume querying and improve query performance. +- charset: specify the charset to parse the string, this parameter is valid only when set batchfetch to true. +- batchErrorIgnore: true: when executing executeBatch of Statement, if one SQL execution fails in the middle, continue to execute the following SQL. false: no longer execute any statement after the failed SQL. The default value is: false. + +**Note**: Some configuration items (e.g., locale, timezone) do not work in the REST connection. + +:::note + +- Unlike the native connection method, the REST interface is stateless. When using the JDBC REST connection, you need to specify the database name of the table and super table in SQL. For example. + +```sql +INSERT INTO test.t1 USING test.weather (ts, temperature) TAGS('California.SanFrancisco') VALUES(now, 24.6); +``` + +- Starting from taos-jdbcdriver-2.0.36 and TDengine 2.2.0.0, if dbname is specified in the URL, JDBC REST connections will use `/rest/sql/dbname` as the URL for REST requests by default, and there is no need to specify dbname in SQL. For example, if the URL is `jdbc:TAOS-RS://127.0.0.1:6041/test`, then the SQL can be executed: insert into test using weather(ts, temperature) tags('California.SanFrancisco') values(now, 24.6); + +::: + + + + +### Specify the URL and Properties to get the connection + +In addition to getting the connection from the specified URL, you can use Properties to specify parameters when the connection is established. + +**Note**: + +- The client parameter set in the application is process-level. If you want to update the parameters of the client, you need to restart the application. This is because the client parameter is a global parameter that takes effect only the first time the application is set. +- The following sample code is based on 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; +} +``` + +In the above example, a connection is established to `taosdemo.com`, port is 6030/6041, and database named `test`. The connection specifies the user name as `root` and the password as `taosdata` in the URL and specifies the character set, language environment, time zone, and whether to enable bulk fetching in the connProps. + +The configuration parameters in properties are as follows. + +- TSDBDriver.PROPERTY_KEY_USER: Login TDengine user name, default value 'root'. +- TSDBDriver.PROPERTY_KEY_PASSWORD: user login password, default value 'taosdata'. +- TSDBDriver.PROPERTY_KEY_BATCH_LOAD: true: pull the result set in batch when executing query; false: pull the result set row by row. The default value is: false. +- TSDBDriver.PROPERTY_KEY_BATCH_ERROR_IGNORE: true: when executing executeBatch of Statement, if there is a SQL execution failure in the middle, continue to execute the following sq. false: no longer execute any statement after the failed SQL. The default value is: false. +- TSDBDriver.PROPERTY_KEY_CONFIG_DIR: Only works when using JDBC native connection. Client configuration file directory path, default value `/etc/taos` on Linux OS, default value `C:/TDengine/cfg` on Windows OS. +- TSDBDriver.PROPERTY_KEY_CHARSET: In the character set used by the client, the default value is the system character set. +- TSDBDriver.PROPERTY_KEY_LOCALE: this only takes effect when using JDBC native connection. Client language environment, the default value is system current locale. +- TSDBDriver.PROPERTY_KEY_TIME_ZONE: only takes effect when using JDBC native connection. In the time zone used by the client, the default value is the system's current time zone. + For JDBC native connections, you can specify other parameters, such as log level, SQL length, etc., by specifying URL and Properties. For more detailed configuration, please refer to [Client Configuration](/reference/config/#Client-Only). + +### Priority of configuration parameters + +If the configuration parameters are duplicated in the URL, Properties, or client configuration file, the `priority` of the parameters, from highest to lowest, are as follows: + +1. JDBC URL parameters, as described above, can be specified in the parameters of the JDBC URL. +2. Properties connProps +3. the configuration file taos.cfg of the TDengine client driver when using a native connection + +For example, if you specify the password as `taosdata` in the URL and specify the password as `taosdemo` in the Properties simultaneously, JDBC will use the password in the URL to establish the connection. + +## Usage examples + +### Create database and tables + +```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)"); +``` + +> **Note**: If you do not use `use db` to specify the database, all subsequent operations on the table need to add the database name as a prefix, such as db.tb. + +### Insert data + +```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 is an internal function. The default is the current time of the client's computer. +> `now + 1s` represents the current time of the client plus 1 second, followed by the number representing the unit of time: a (milliseconds), s (seconds), m (minutes), h (hours), d (days), w (weeks), n (months), y (years). + +### Querying data + +```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); +} +``` + +> The query is consistent with operating a relational database. When using subscripts to get the contents of the returned fields, you have to start from 1. However, we recommend using the field names to get the values of the fields in the result set. + +### Handling exceptions + +After an error is reported, the error message and error code can be obtained through 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(); +} +``` + +There are three types of error codes that the JDBC connector can report: + +- Error code of the JDBC driver itself (error code between 0x2301 and 0x2350) +- Error code of the native connection method (error code between 0x2351 and 0x2400) +- Error code of other TDengine function modules + +For specific error codes, please refer to. + +- [TDengine Java Connector](https://github.com/taosdata/taos-connector-jdbc/blob/main/src/main/java/com/taosdata/jdbc/TSDBErrorNumbers.java) +- [TDengine_ERROR_CODE](https://github.com/taosdata/TDengine/blob/develop/src/inc/taoserror.h) + +### Writing data via parameter binding + +TDengine's native JDBC connection implementation has significantly improved its support for data writing (INSERT) scenarios via bind interface with version 2.1.2.0 and later versions. Writing data in this way avoids the resource consumption of SQL syntax parsing, resulting in significant write performance improvements in many cases. + +**Note**. + +- JDBC REST connections do not currently support bind interface +- The following sample code is based on taos-jdbcdriver-2.0.36 +- The setString method should be called for binary type data, and the setNString method should be called for nchar type data +- both setString and setNString require the user to declare the width of the corresponding column in the size parameter of the table definition + +```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, "California-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("California-abc"); + } + pstmt.setNString(1, f1List, BINARY_COLUMN_SIZE); + + // add column + pstmt.columnDataAddBatch(); + } + // execute + pstmt.columnDataExecuteBatch(); + } + } +} +``` + +The methods to set TAGS values: + +```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) +``` + +The methods to set VALUES columns: + +```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 +``` + +### Schemaless Writing + +Starting with version 2.2.0.0, TDengine has added the ability to perform schemaless writing. It is compatible with InfluxDB's Line Protocol, OpenTSDB's telnet line protocol, and OpenTSDB's JSON format protocol. See [schemaless writing](/reference/schemaless/) for details. + +**Note**. + +- JDBC REST connections do not currently support schemaless writes +- The following sample code is based on 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\": \"California.SanFrancisco\", \"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"); + } + } +} +``` + +### Subscriptions + +The TDengine Java Connector supports subscription functionality with the following application API. + +#### Create subscriptions + +```java +TSDBSubscribe sub = ((TSDBConnection)conn).subscribe("topicname", "select * from meters", false); +``` + +The three parameters of the `subscribe()` method have the following meanings. + +- topicname: the name of the subscribed topic. This parameter is the unique identifier of the subscription. +- sql: the query statement of the subscription. This statement can only be a `select` statement. Only original data can be queried, and you can query the data only temporal order. +- restart: if the subscription already exists, whether to restart or continue the previous subscription + +The above example will use the SQL command `select * from meters` to create a subscription named `topicname`. If the subscription exists, it will continue the progress of the previous query instead of consuming all the data from the beginning. + +#### Subscribe to consume data + +```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); +} +``` + +The `consume()` method returns a result set containing all new data from the last `consume()`. Be sure to choose a reasonable frequency for calling `consume()` as needed (e.g. `Thread.sleep(1000)` in the example). Otherwise, it will cause unnecessary stress on the server-side. + +#### Close subscriptions + +```java +sub.close(true); +``` + +The `close()` method closes a subscription. If its argument is `true` it means that the subscription progress information is retained, and the subscription with the same name can be created to continue consuming data; if it is `false` it does not retain the subscription progress. + +### Closing resources + +```java +resultSet.close(); +stmt.close(); +conn.close(); +``` + +> **Be sure to close the connection**, otherwise, there will be a connection leak. + +### Use with connection pool + +#### HikariCP + +Example usage is as follows. + +```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 connection pool +} +``` + +> getConnection(), you need to call the close() method after you finish using it. It doesn't close the connection. It just puts it back into the connection pool. +> For more questions about using HikariCP, please see the [official instructions](https://github.com/brettwooldridge/HikariCP). + +#### Druid + +Example usage is as follows. + +```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 connection pool +} +``` + +> For more questions about using druid, please see [Official Instructions](https://github.com/alibaba/druid). + +**Caution:** + +- TDengine `v1.6.4.1` provides a special function `select server_status()` for heartbeat detection, so it is recommended to use `select server_status()` for Validation Query when using connection pooling. + +As you can see below, `select server_status()` returns `1` on successful execution. + +```sql +taos> select server_status(); +server_status()| +================ +1 | +Query OK, 1 row(s) in set (0.000141s) +``` + +### More sample programs + +The source code of the sample application is under `TDengine/examples/JDBC`: + +- JDBCDemo: JDBC sample source code. +- JDBCConnectorChecker: JDBC installation checker source and jar package. +- connectionPools: using taos-jdbcdriver in connection pools such as HikariCP, Druid, dbcp, c3p0, etc. +- SpringJdbcTemplate: using taos-jdbcdriver in Spring JdbcTemplate. +- mybatisplus-demo: using taos-jdbcdriver in Springboot + Mybatis. + +Please refer to: [JDBC example](https://github.com/taosdata/TDengine/tree/develop/examples/JDBC) + +## Recent update logs + +| taos-jdbcdriver version | major changes | +| :---------------------: | :------------------------------------------: | +| 2.0.38 | JDBC REST connections add bulk pull function | +| 2.0.37 | Added support for json tags | +| 2.0.36 | Add support for schemaless writing | + +## Frequently Asked Questions + +1. Why is there no performance improvement when using Statement's `addBatch()` and `executeBatch()` to perform `batch data writing/update`? + + **Cause**: In TDengine's JDBC implementation, SQL statements submitted by `addBatch()` method are executed sequentially in the order they are added, which does not reduce the number of interactions with the server and does not bring performance improvement. + + **Solution**: 1. splice multiple values in a single insert statement; 2. use multi-threaded concurrent insertion; 3. use parameter-bound writing + +2. java.lang.UnsatisfiedLinkError: no taos in java.library.path + + **Cause**: The program did not find the dependent native library `taos`. + + **Solution**: On Windows you can copy `C:\TDengine\driver\taos.dll` to the `C:\Windows\System32` directory, on Linux the following soft link will be created `ln -s /usr/local/taos/driver/libtaos.so.x.x.x.x /usr/lib/libtaos.so` will work. + +3. java.lang.UnsatisfiedLinkError: taos.dll Can't load AMD 64 bit on an IA 32-bit platform + + **Cause**: Currently, TDengine only supports 64-bit JDK. + + **Solution**: Reinstall the 64-bit JDK. 4. + +For other questions, please refer to [FAQ](/train-faq/faq) + +## API Reference + +[taos-jdbcdriver doc](https://docs.taosdata.com/api/taos-jdbcdriver) diff --git a/docs/en/14-reference/03-connector/node.mdx b/docs/en/14-reference/03-connector/node.mdx new file mode 100644 index 0000000000000000000000000000000000000000..8f586acde4848af71efcb23358be1f8486cedb8e --- /dev/null +++ b/docs/en/14-reference/03-connector/node.mdx @@ -0,0 +1,248 @@ +--- +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 Preparation from "./_preparation.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"; + +`td2.0-connector` and `td2.0-rest-connector` are the official Node.js language connectors for TDengine. Node.js developers can develop applications to access TDengine instance data. + +`td2.0-connector` is a **native connector** that connects to TDengine instances via the TDengine client driver (taosc) and supports data writing, querying, subscriptions, schemaless writing, and bind interface. The `td2.0-rest-connector` is a **REST connector** that connects to TDengine instances via the REST interface provided by taosAdapter. The REST connector can run on any platform, but performance is slightly degraded, and the interface implements a somewhat different set of functional features than the native interface. + +The Node.js connector source code is hosted on [GitHub](https://github.com/taosdata/taos-connector-node). + +## Supported Platforms + +The platforms supported by the native connector are the same as those supported by the TDengine client driver. +The REST connector supports all platforms that can run Node.js. + +## Version support + +Please refer to [version support list](/reference/connector#version-support) + +## Supported features + +### Native connectors + +1. connection management +2. general query +3. continuous query +4. parameter binding +5. subscription function +6. Schemaless + +### REST Connector + +1. connection management +2. general queries +3. Continuous query + +## Installation steps + +### Pre-installation + +- Install the Node.js development environment +- If you are using the REST connector, skip this step. However, if you use the native connector, please install the TDengine client driver. Please refer to [Install Client Driver](/reference/connector#Install-Client-Driver) for more details. We use [node-gyp](https://github.com/nodejs/node-gyp) to interact with TDengine instances and also need to install some dependencies mentioned below depending on the specific OS. + + + + +- `python` (recommended for `v2.7` , `v3.x.x` currently not supported) +- `td2.0-connector` 2.0.6 supports Node.js LTS v10.9.0 or later, Node.js LTS v12.8.0 or later; 2.0.5 and earlier support Node.js LTS v10.x versions. Other versions may have package compatibility issues +- `make` +- C compiler, [GCC](https://gcc.gnu.org) v4.8.5 or higher + + + + +- Installation method 1 + +Use Microsoft's [windows-build-tools](https://github.com/felixrieseberg/windows-build-tools) to execute `npm install --global --production` from the `cmd` command-line interface to install all the necessary tools. + +- Installation method 2 + +Manually install the following tools. + +- Install Visual Studio related: [Visual Studio Build Tools](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=BuildTools) or [Visual Studio 2017 Community](https://visualstudio.microsoft.com/pl/thank-you-downloading-visual-studio/?sku=Community) +- Install [Python](https://www.python.org/downloads/) 2.7 (`v3.x.x` is not supported) and execute `npm config set python python2.7`. +- Go to the `cmd` command-line interface, `npm config set msvs_version 2017` + +Refer to Microsoft's Node.js User Manual [Microsoft's Node.js Guidelines for Windows](https://github.com/Microsoft/nodejs-guidelines/blob/master/windows-environment.md#compiling-native-addon-modules). + +If using ARM64 Node.js on Windows 10 ARM, you must add "Visual C++ compilers and libraries for ARM64" and "Visual C++ ATL for ARM64". + + + + +### Install via npm + + + + +```bash +npm install td2.0-connector +``` + + + + +```bash +npm i td2.0-rest-connector +``` + + + + +### Installation verification + +After installing the TDengine client, use the `nodejsChecker.js` program to verify that the current environment supports Node.js access to TDengine. + +Verification in details: + +- Create a new installation verification directory, e.g. `~/tdengine-test`, and download the [nodejsChecker.js source code](https://github.com/taosdata/TDengine/tree/develop/examples/nodejs/) from GitHub. to the work directory. + +- Execute the following command from the command-line. + +```bash +npm init -y +npm install td2.0-connector +node nodejsChecker.js host=localhost +``` + +- After executing the above steps, the command-line will output the result of `nodejsChecker.js` connecting to the TDengine instance and performing a simple insert and query. + +## Establishing a connection + +Please choose to use one of the connectors. + + + + +Install and refer to `td2.0-connector` package: + +```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(); +``` + + + + +Install and refer to `td2.0-rest-connector`package: + +```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(); +``` + + + + +## Usage examples + +### Write data + +#### SQL Writing + + + +#### InfluxDB line protocol writing + + + +#### OpenTSDB Telnet line protocol writing + + + +#### OpenTSDB JSON line protocol writing + + + +### Query data + + + +## More Sample Programs + +| Sample Programs | Sample Program Description | +| --------------------------------------------------------------------------------------------------------------------------------- --------- | -------------------------------------- | +| [connection](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/cursorClose.js) | Example of establishing a connection. | +| [stmtBindBatch](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/stmtBindParamBatchSample.js) | Example of binding a multi-line parameter Example of inserting. | +| [stmtBind](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/stmtBindParamSample.js) | Example of a line-by-line bind parameter insertion. | +| [stmtBindSingleParamBatch](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/) stmtBindSingleParamBatchSample.js) | Example of binding parameters by column. | +| [stmtUseResult](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/stmtUseResultSample.js) | Example of a bound parameter query. | +| [json tag](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/testJsonTag.js) | Example of using Json tag. | +| [Nanosecond](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/testNanoseconds.js) | An example of using timestamps with nanosecond precision. | +| [Microsecond](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/testMicroseconds.js) | Example of using microsecond timestamp. | +| [schemless insert](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/testSchemalessInsert.js) | schemless Example of a schemless insert. | +| [subscribe](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/testSubscribe.js) | Example of using subscribe. | +| [asyncQuery](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/tset.js) | An example of using asynchronous queries. | +| [REST](https://github.com/taosdata/taos-connector-node/blob/develop/typescript-rest/example/example.ts) | An example of using TypeScript with REST connections. | + +## Usage restrictions + +Node.js Connector >= v2.0.6 currently supports node versions >=v12.8.0 <= v12.9.1 || >=v10.20.0 <= v10.9.0; v10.x versions are supported in 2.0.5 and earlier, other versions may have package compatibility issues. + +## Other notes + +See [video tutorial](https://www.taosdata.com/blog/2020/11/11/1957.html) for the Node.js connector usage. + +## Frequently Asked Questions + +1. Using REST connections requires starting taosadapter. + + ```bash + sudo systemctl start taosadapter + ``` + +2. "Unable to establish connection", "Unable to resolve FQDN" + + Usually, the root cause is an incorrect FQDN configuration. You can refer to this section in the [FAQ](https://docs.tdengine.com/2.4/train-faq/faq/#2-how-to-handle-unable-to-establish-connection) to troubleshoot. + +## Important Updates + +### Native connectors + +| td2.0-connector version | description | +| -------------------- | ---------------------------------------------------------------- | +| 2.0.12 | Fix bug with cursor.close() error. | 2.0.12 | Fix bug with cursor.close() error. +| 2.0.11 | Support for binding parameters, json tag, schemaless interface, etc. | +| 2.0.10 | Support connection management, general query, continuous query, get system information, subscribe function, etc. | ### REST Connector + +### REST Connector + +| td2.0-rest-connector version | Description | +| ------------------------- | ---------------------------------------------------------------- | +| 1.0.3 | Support connection management, general query, get system information, error message, continuous query, etc. |# API Reference + +## API Reference + +[API Reference](https://docs.taosdata.com/api/td2.0-connector/) diff --git a/docs/en/14-reference/03-connector/php.mdx b/docs/en/14-reference/03-connector/php.mdx new file mode 100644 index 0000000000000000000000000000000000000000..69dcce91e80fa05face1ffb35effe1ce1efa2631 --- /dev/null +++ b/docs/en/14-reference/03-connector/php.mdx @@ -0,0 +1,150 @@ +--- +sidebar_position: 1 +sidebar_label: PHP +title: PHP Connector +--- + +`php-tdengine` is the TDengine PHP connector provided by TDengine community. In particular, it supports Swoole coroutine. + +PHP Connector relies on TDengine client driver. + +Project Repository： + +After TDengine client or server is installed, `taos.h` is located at: + +- Linux：`/usr/local/taos/include` +- Windows：`C:\TDengine\include` + +TDengine client driver is located at: + +- Linux: `/usr/local/taos/driver/libtaos.so` +- Windows: `C:\TDengine\taos.dll` + +## Supported Platforms + +- Windows、Linux、MacOS + +- PHP >= 7.4 + +- TDengine >= 2.0 + +- Swoole >= 4.8 (Optional) + +## Supported Versions + +Because the version of TDengine client driver is tightly associated with that of TDengine server, it's strongly suggested to use the client driver of same version as TDengine server, even though the client driver can work with TDengine server if the first 3 sections of the versions are same. + +## Installation + +### Install TDengine Client Driver + +Regarding how to install TDengine client driver please refer to [Install Client Driver](/reference/connector#installation-steps) + +### Install php-tdengine + +**Download Source Code Package and Unzip：** + +```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 +``` + +> Version number `v1.0.2` is only for example, it can be replaced to any newer version, please find available versions in [TDengine PHP Connector Releases](https://github.com/Yurunsoft/php-tdengine/releases). + +**Non-Swoole Environment：** + +```shell +phpize && ./configure && make -j && make install +``` + +**Specify TDengine location：** + +```shell +phpize && ./configure --with-tdengine-dir=/usr/local/Cellar/tdengine/2.4.0.0 && make -j && make install +``` + +> `--with-tdengine-dir=` is followed by TDengine location. +> It's useful in case TDengine installatio location can't be found automatically or MacOS. + +**Swoole Environment：** + +```shell +phpize && ./configure --enable-swoole && make -j && make install +``` + +**Enable Extension:** + +Option One: Add `extension=tdengine` in `php.ini`. + +Option Two: Use CLI `php -dextension=tdengine test.php`. + +## Sample Programs + +In this section a few sample programs which use TDengine PHP connector to access TDengine cluster are demonstrated. + +> Any error would throw exception: `TDengine\Exception\TDengineException` + +### Establish Conection + +
+Establish Connection + +```c +{{#include docs/examples/php/connect.php}} +``` + +
+ +### Insert Data + +
+Insert Data + +```c +{{#include docs/examples/php/insert.php}} +``` + +
+ +### Synchronous Query + +
+Synchronous Query + +```c +{{#include docs/examples/php/query.php}} +``` + +
+ +### Parameter Binding + +
+Parameter Binding + +```c +{{#include docs/examples/php/insert_stmt.php}} +``` + +
+ +## Constants + +| Constant | Description | +| ----------------------------------- | ----------- | +| `TDengine\TSDB_DATA_TYPE_NULL` | null | +| `TDengine\TSDB_DATA_TYPE_BOOL` | bool | +| `TDengine\TSDB_DATA_TYPE_TINYINT` | tinyint | +| `TDengine\TSDB_DATA_TYPE_SMALLINT` | smallint | +| `TDengine\TSDB_DATA_TYPE_INT` | int | +| `TDengine\TSDB_DATA_TYPE_BIGINT` | bigint | +| `TDengine\TSDB_DATA_TYPE_FLOAT` | float | +| `TDengine\TSDB_DATA_TYPE_DOUBLE` | double | +| `TDengine\TSDB_DATA_TYPE_BINARY` | binary | +| `TDengine\TSDB_DATA_TYPE_TIMESTAMP` | timestamp | +| `TDengine\TSDB_DATA_TYPE_NCHAR` | nchar | +| `TDengine\TSDB_DATA_TYPE_UTINYINT` | utinyint | +| `TDengine\TSDB_DATA_TYPE_USMALLINT` | usmallint | +| `TDengine\TSDB_DATA_TYPE_UINT` | uint | +| `TDengine\TSDB_DATA_TYPE_UBIGINT` | ubigint | diff --git a/docs/en/14-reference/03-connector/python.mdx b/docs/en/14-reference/03-connector/python.mdx new file mode 100644 index 0000000000000000000000000000000000000000..04eb2e57d4455a83b62633ecb988cb64bf837fea --- /dev/null +++ b/docs/en/14-reference/03-connector/python.mdx @@ -0,0 +1,345 @@ +--- +sidebar_position: 3 +sidebar_label: Python +title: TDengine Python Connector +description: "taospy is the official Python connector for TDengine. taospy provides a rich API that makes it easy for Python applications to use TDengine. tasopy wraps both the native and REST interfaces of TDengine, corresponding to the two submodules of tasopy: taos and taosrest. In addition to wrapping the native and REST interfaces, taospy also provides a programming interface that conforms to the Python Data Access Specification (PEP 249), making it easy to integrate taospy with many third-party tools, such as SQLAlchemy and pandas." +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +`taospy` is the official Python connector for TDengine. `taospy` provides a rich set of APIs that makes it easy for Python applications to access TDengine. `taospy` wraps both the [native interface](/reference/connector/cpp) and [REST interface](/reference/rest-api) of TDengine, which correspond to the `taos` and `taosrest` modules of the `taospy` package, respectively. +In addition to wrapping the native and REST interfaces, `taospy` also provides a set of programming interfaces that conforms to the [Python Data Access Specification (PEP 249)](https://peps.python.org/pep-0249/). It is easy to integrate `taospy` with many third-party tools, such as [SQLAlchemy](https://www.sqlalchemy.org/) and [pandas](https://pandas.pydata.org/). + +The direct connection to the server using the native interface provided by the client driver is referred to hereinafter as a "native connection"; the connection to the server using the REST interface provided by taosAdapter is referred to hereinafter as a "REST connection". + +The source code for the Python connector is hosted on [GitHub](https://github.com/taosdata/taos-connector-python). + +## Supported Platforms + +- The [supported platforms](/reference/connector/#supported-platforms) for the native connection are the same as the ones supported by the TDengine client. +- REST connections are supported on all platforms that can run Python. + +## Version selection + +We recommend using the latest version of `taospy`, regardless of the version of TDengine. + +## Supported features + +- Native connections support all the core features of TDengine, including connection management, SQL execution, bind interface, subscriptions, and schemaless writing. +- REST connections support features such as connection management and SQL execution. (SQL execution allows you to: manage databases, tables, and supertables, write data, query data, create continuous queries, etc.). + +## Installation + +### Preparation + +1. Install Python. Python >= 3.6 is recommended. If Python is not available on your system, refer to the [Python BeginnersGuide](https://wiki.python.org/moin/BeginnersGuide/Download) to install it. +2. Install [pip](https://pypi.org/project/pip/). In most cases, the Python installer comes with the pip utility. If not, please refer to [pip documentation](https://pip.pypa.io/en/stable/installation/) to install it. + +If you use a native connection, you will also need to [Install Client Driver](/reference/connector#Install-Client-Driver). The client install package includes the TDengine client dynamic link library (`libtaos.so` or `taos.dll`) and the TDengine CLI. + +### Install via pip + +#### Uninstalling an older version + +If you have installed an older version of the Python Connector, please uninstall it beforehand. + +``` +pip3 uninstall taos taospy +``` + +:::note +Earlier TDengine client software includes the Python connector. If the Python connector is installed from the client package's installation directory, the corresponding Python package name is `taos`. So the above uninstall command includes `taos`, and it doesn't matter if it doesn't exist. + +::: + +#### To install `taospy` + + + + +Install the latest version of: + +``` +pip3 install taospy +``` + +You can also specify a specific version to install: + +``` +pip3 install taospy==2.3.0 +``` + + + + +``` +pip3 install git+https://github.com/taosdata/taos-connector-python.git +``` + + + + +### Installation verification + + + + +For native connection, you need to verify that both the client driver and the Python connector itself are installed correctly. The client driver and Python connector have been installed properly if you can successfully import the `taos` module. In the Python Interactive Shell, you can type. + +```python +import taos +``` + + + + +For REST connections, verifying that the `taosrest` module can be imported successfully can be done in the Python Interactive Shell by typing. + +```python +import taosrest +``` + + + + +:::tip +If you have multiple versions of Python on your system, you may have various `pip` commands. Be sure to use the correct path for the `pip` command. Above, we installed the `pip3` command, which rules out the possibility of using the `pip` corresponding to Python 2.x versions. However, if you have more than one version of Python 3.x on your system, you still need to check that the installation path is correct. The easiest way to verify this is to type `pip3 install taospy` again in the command, and it will print out the exact location of `taospy`, for example, on 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) + +::: + +## Establish connection + +### Connectivity testing + +Before establishing a connection with the connector, we recommend testing the connectivity of the local TDengine CLI to the TDengine cluster. + + + + +Ensure that the TDengine instance is up and that the FQDN of the machines in the cluster (the FQDN defaults to hostname if you are starting a standalone version) can be resolved locally, by testing with the `ping` command. + +``` +ping +``` + +Then test if the cluster can be appropriately connected with TDengine CLI: + +``` +taos -h -p +``` + +The FQDN above can be the FQDN of any dnode in the cluster, and the PORT is the serverPort corresponding to this dnode. + + + + +For REST connections, make sure the cluster and taosAdapter component, are running. This can be tested using the following `curl ` command. + +``` +curl -u root:taosdata http://:/rest/sql -d "select server_version()" +``` + +The FQDN above is the FQDN of the machine running taosAdapter, PORT is the port taosAdapter listening, default is `6041`. +If the test is successful, it will output the server version information, e.g. + +```json +{ + "status": "succ", + "head": ["server_version()"], + "column_meta": [["server_version()", 8, 8]], + "data": [["2.4.0.16"]], + "rows": 1 +} +``` + + + + +### Using connectors to establish connections + +The following example code assumes that TDengine is installed locally and that the default configuration is used for both FQDN and serverPort. + + + + +```python +{{#include docs/examples/python/connect_native_reference.py}} +``` + +All arguments of the `connect()` function are optional keyword arguments. The following are the connection parameters specified. + +- `host` : The FQDN of the node to connect to. There is no default value. If this parameter is not provided, the firstEP in the client configuration file will be connected. +- `user` : The TDengine user name. The default value is `root`. +- `password` : TDengine user password. The default value is `taosdata`. +- `port` : The starting port of the data node to connect to, i.e., the serverPort configuration. The default value is 6030, which will only take effect if the host parameter is provided. +- `config` : The path to the client configuration file. On Windows systems, the default is `C:\TDengine\cfg`. The default is `/etc/taos/` on Linux systems. +- `timezone` : The timezone used to convert the TIMESTAMP data in the query results to python `datetime` objects. The default is the local timezone. + +:::warning +`config` and `timezone` are both process-level configurations. We recommend that all connections made by a process use the same parameter values. Otherwise, unpredictable errors may occur. +::: + +:::tip +The `connect()` function returns a `taos.TaosConnection` instance. In client-side multi-threaded scenarios, we recommend that each thread request a separate connection instance rather than sharing a connection between multiple threads. + +::: + + + + +```python +{{#include docs/examples/python/connect_rest_examples.py:connect}} +``` + +All arguments to the `connect()` function are optional keyword arguments. The following are the connection parameters specified. + +- `url`： The URL of taosAdapter REST service. The default is . +- `user`: TDengine user name. The default is `root`. +- `password`: TDengine user password. The default is `taosdata`. +- `timeout`: HTTP request timeout in seconds. The default is `socket._GLOBAL_DEFAULT_TIMEOUT`. Usually, no configuration is needed. + + + + +## Sample program + +### Basic Usage + + + + +##### TaosConnection class + +The `TaosConnection` class contains both an implementation of the PEP249 Connection interface (e.g., the `cursor()` method and the `close()` method) and many extensions (e.g., the `execute()`, `query()`, `schemaless_insert()`, and `subscribe()` methods). + +```python title="execute method" +{{#include docs/examples/python/connection_usage_native_reference.py:insert}} +``` + +```python title="query method" +{{#include docs/examples/python/connection_usage_native_reference.py:query}} +``` + +:::tip +The queried results can only be fetched once. For example, only one of `fetch_all()` and `fetch_all_into_dict()` can be used in the example above. Repeated fetches will result in an empty list. +::: + +##### Use of TaosResult class + +In the above example of using the `TaosConnection` class, we have shown two ways to get the result of a query: `fetch_all()` and `fetch_all_into_dict()`. In addition, `TaosResult` also provides methods to iterate through the result set by rows (`rows_iter`) or by data blocks (`blocks_iter`). Using these two methods will be more efficient in scenarios where the query has a large amount of data. + +```python title="blocks_iter method" +{{#include docs/examples/python/result_set_examples.py}} +``` +##### Use of the TaosCursor class + +The `TaosConnection` class and the `TaosResult` class already implement all the functionality of the native interface. If you are familiar with the interfaces in the PEP249 specification, you can also use the methods provided by the `TaosCursor` class. + +```python title="Use of TaosCursor" +{{#include docs/examples/python/cursor_usage_native_reference.py}} +``` + +:::note +The TaosCursor class uses native connections for write and query operations. In a client-side multi-threaded scenario, this cursor instance must remain thread exclusive and cannot be shared across threads for use, otherwise, it will result in errors in the returned results. + +::: + + + + +##### Use of TaosRestCursor class + +The ``TaosRestCursor`` class is an implementation of the PEP249 Cursor interface. + +```python title="Use of TaosRestCursor" +{{#include docs/examples/python/connect_rest_examples.py:basic}} +``` +- `cursor.execute` : Used to execute arbitrary SQL statements. +- `cursor.rowcount` : For write operations, returns the number of successful rows written. For query operations, returns the number of rows in the result set. +- `cursor.description` : Returns the description of the field. Please refer to [TaosRestCursor](https://docs.taosdata.com/api/taospy/taosrest/cursor.html) for the specific format of the description information. + +##### Use of the RestClient class + +The `RestClient` class is a direct wrapper for the [REST API](/reference/rest-api). It contains only a `sql()` method for executing arbitrary SQL statements and returning the result. + +```python title="Use of RestClient" +{{#include docs/examples/python/rest_client_example.py}} +``` + +For a more detailed description of the `sql()` method, please refer to [RestClient](https://docs.taosdata.com/api/taospy/taosrest/restclient.html). + + + + +### Used with pandas + + + + +```python +{{#include docs/examples/python/conn_native_pandas.py}} +``` + + + + +```python +{{#include docs/examples/python/conn_rest_pandas.py}} +``` + + + + +### Other sample programs + +| Example program links | Example program content | +| ------------------------------------------------------------------------------------------------------------- | ------------------- ---- | +| [bind_multi.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/bind-multi.py) | parameter binding, bind multiple rows at once | +| [bind_row.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/bind-row.py) | bind_row.py +| [insert_lines.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/insert-lines.py) | InfluxDB line protocol writing | +| [json_tag.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/json-tag.py) | Use JSON type tags | +| [subscribe-async.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/subscribe-async.py) | Asynchronous subscription | +| [subscribe-sync.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/subscribe-sync.py) | synchronous-subscribe | + +## Other notes + +### Exception handling + +All errors from database operations are thrown directly as exceptions and the error message from the database is passed up the exception stack. The application is responsible for exception handling. For example: + +```python +{{#include docs/examples/python/handle_exception.py}} +``` + +### About nanoseconds + +Due to the current imperfection of Python's nanosecond support (see link below), the current implementation returns integers at nanosecond precision instead of the `datetime` type produced by `ms` and `us`, which application developers will need to handle on their own. And it is recommended to use pandas' to_datetime(). The Python Connector may modify the interface in the future if Python officially supports nanoseconds in full. + +1. https://stackoverflow.com/questions/10611328/parsing-datetime-strings-containing-nanoseconds +2. https://www.python.org/dev/peps/pep-0564/ + + +## Frequently Asked Questions + +Welcome to [ask questions or report questions](https://github.com/taosdata/taos-connector-python/issues). + +## Important Update + +| Connector version | Important Update | Release date | +| ---------- | --------------------------------------------------------------------------------- | ---------- | +| 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 Reference + +- [taos](https://docs.taosdata.com/api/taospy/taos/) +- [taosrest](https://docs.taosdata.com/api/taospy/taosrest) diff --git a/docs/en/14-reference/03-connector/rust.mdx b/docs/en/14-reference/03-connector/rust.mdx new file mode 100644 index 0000000000000000000000000000000000000000..a5cbaeac8077cda42690d9cc232062a685a51f41 --- /dev/null +++ b/docs/en/14-reference/03-connector/rust.mdx @@ -0,0 +1,384 @@ +--- +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 Preparation from "./_preparation.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" + +`libtaos` is the official Rust language connector for TDengine. Rust developers can develop applications to access the TDengine instance data. + +`libtaos` provides two ways to establish connections. One is the **Native Connection**, which connects to TDengine instances via the TDengine client driver (taosc). The other is **REST connection**, which connects to TDengine instances via taosAdapter's REST interface. + +The source code for `libtaos` is hosted on [GitHub](https://github.com/taosdata/libtaos-rs). + +## Supported platforms + +The platforms supported by native connections are the same as those supported by the TDengine client driver. +REST connections are supported on all platforms that can run Rust. + +## Version support + +Please refer to [version support list](/reference/connector#version-support). + +The Rust Connector is still under rapid development and is not guaranteed to be backward compatible before 1.0. We recommend using TDengine version 2.4 or higher to avoid known issues. + +## Installation + +### Pre-installation +* Install the Rust development toolchain +* If using the native connection, please install the TDengine client driver. Please refer to [install client driver](/reference/connector#install-client-driver) + +### Adding libtaos dependencies + +Add the [libtaos][libtaos] dependency to the [Rust](https://rust-lang.org) project as follows, depending on the connection method selected. + + + + +Add [libtaos][libtaos] to the `Cargo.toml` file. + +```toml +[dependencies] +# use default feature +libtaos = "*" +``` + + + + +Add [libtaos][libtaos] to the `Cargo.toml` file and enable the `rest` feature. + +```toml +[dependencies] +# use rest feature +libtaos = { version = "*", features = ["rest"]} +``` + + + + + +### Using connection pools + +Please enable the `r2d2` feature in `Cargo.toml`. + +```toml +[dependencies] +# with taosc +libtaos = { version = "*", features = ["r2d2"] } +# or rest +libtaos = { version = "*", features = ["rest", "r2d2"] } +``` + +## Create a connection + +The [TaosCfgBuilder] provides the user with an API in the form of a constructor for the subsequent creation of connections or use of connection pools. + +```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"); +} +``` + +You can now use this object to create the connection. + +```rust +let conn = cfg.connect()? ; +``` + +The connection object can create more than one. + +```rust +let conn = cfg.connect()? ; +let conn2 = cfg.connect()? ; +``` + +You can use connection pools in applications. + +```rust +let pool = r2d2::Pool::builder() + .max_size(10000) // max connections + .build(cfg)? ; + +// ... +// Use pool to get connection +let conn = pool.get()? ; +``` + +After that, you can perform the following operations on the database. + +```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(",")); + } +} +``` + +## Usage examples + +### Write data + +#### SQL Write + + + +#### InfluxDB line protocol write + + + +#### OpenTSDB Telnet line protocol write + + + +#### OpenTSDB JSON line protocol write + + + +### Query data + + + +### More sample programs + +| Program Path | Program Description | +| -------------- | ----------------------------------------------------------------------------- | +| [demo.rs] | Basic API Usage Examples | +| [bailongma-rs] | Using TDengine as the Prometheus remote storage API adapter for the storage backend, using the r2d2 connection pool | + +## API Reference + +### Connection constructor API + +The [Builder Pattern](https://doc.rust-lang.org/1.0.0/style/ownership/builders.html) constructor pattern is Rust's solution for handling complex data types or optional configuration types. The [libtaos] implementation uses the connection constructor [TaosCfgBuilder] as the entry point for the TDengine Rust connector. The [TaosCfgBuilder] provides optional configuration of servers, ports, databases, usernames, passwords, etc. + +Using the `default()` method, you can construct a [TaosCfg] with default parameters for subsequent connections to the database or establishing connection pools. + +```rust +let cfg = TaosCfgBuilder::default().build()? ; +``` + +Using the constructor pattern, the user can set on-demand. + +```rust +let cfg = TaosCfgBuilder::default() + .ip("127.0.0.1") + .user("root") + .pass("taosdata") + .db("log") + .port(6030u16) + .build()? ; +``` + +Create TDengine connection using [TaosCfg] object. + +```rust +let conn: Taos = cfg.connect(); +``` + +### Connection pooling + +In complex applications, we recommend enabling connection pools. Connection pool for [libtaos] is implemented using [r2d2]. + +As follows, a connection pool with default parameters can be generated. + +```rust +let pool = r2d2::Pool::new(cfg)? ; +``` + +You can set the same connection pool parameters using the connection pool's constructor. + +```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); +``` + +In the application code, use `pool.get()? ` to get a connection object [Taos]. + +```rust +let taos = pool.get()? ; +``` + +The [Taos] structure is the connection manager in [libtaos] and provides two main APIs. + +1. `exec`: Execute some non-query SQL statements, such as `CREATE`, `ALTER`, `INSERT`, etc. + + ```rust + taos.exec().await? + ``` + +2. `query`: Execute the query statement and return the [TaosQueryData] object. + + ```rust + let q = taos.query("select * from log.logs").await? + ``` + + The [TaosQueryData] object stores the query result data and basic information about the returned columns (column name, type, length). + + Column information is stored using [ColumnMeta]. + + ``rust + let cols = &q.column_meta; + for col in cols { + println!("name: {}, type: {:?} , bytes: {}", col.name, col.type_, col.bytes); + } + ``` + + It fetches data line by line. + + ```rust + for (i, row) in q.rows.iter().enumerate() { + for (j, cell) in row.iter().enumerate() { + println!("cell({}, {}) data: {}", i, j, cell); + } + } + ``` + +Note that Rust asynchronous functions and an asynchronous runtime are required. + +[Taos] provides a few Rust methods that encapsulate SQL to reduce the frequency of `format!` code blocks. + +- `.describe(table: &str)`: Executes `DESCRIBE` and returns a Rust data structure. +- `.create_database(database: &str)`: Executes the `CREATE DATABASE` statement. +- `.use_database(database: &str)`: Executes the `USE` statement. + +In addition, this structure is also the entry point for [Parameter Binding](#Parameter Binding Interface) and [Line Protocol Interface](#Line Protocol Interface). Please refer to the specific API descriptions for usage. + +### Bind Interface + +Similar to the C interface, Rust provides the bind interface's wrapping. First, create a bind object [Stmt] for a SQL command from the [Taos] object. + +```rust +let mut stmt: Stmt = taos.stmt("insert into ? values(? ,?)") ? ; +``` + +The bind object provides a set of interfaces for implementing parameter binding. + +##### `.set_tbname(tbname: impl ToCString)` + +To bind table names. + +##### `.set_tbname_tags(tbname: impl ToCString, tags: impl IntoParams)` + +Bind sub-table table names and tag values when the SQL statement uses a super table. + +```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\":\"one, two, three, four, five, six, seven, eight, nine, ten\"}").unwrap()); +stmt.set_tbname_tags("tb0", [&tag])? ; +``` + +##### `.bind(params: impl IntoParams)` + +Bind value types. Use the [Field] structure to construct the desired type and bind. + +```rust +let ts = Field::Timestamp(Timestamp::now()); +let value = Field::Float(0.0); +stmt.bind(vec![ts, value].iter())? ; +``` + +##### `.execute()` + +Execute SQL.[Stmt] objects can be reused, re-binded, and executed after execution. + +```rust +stmt.execute()? ; + +// next bind cycle. +// stmt.set_tbname()? ; +//stmt.bind()? ; +//stmt.execute()? ; +``` + +### Line protocol interface + +The line protocol interface supports multiple modes and different precision and requires the introduction of constants in the schemaless module to set. + +```rust +use libtaos::*; +use libtaos::schemaless::*; +``` + +- InfluxDB line protocol + + ```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 Protocol + + ```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 protocol + + ```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)? ; + ``` + +Please move to the Rust documentation hosting page for other related structure API usage instructions: . + +[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/en/14-reference/03-connector/tdengine-jdbc-connector.webp b/docs/en/14-reference/03-connector/tdengine-jdbc-connector.webp new file mode 100644 index 0000000000000000000000000000000000000000..37cf6d90a528e320d5cb7d6da502d3a5b10aa4ee Binary files /dev/null and b/docs/en/14-reference/03-connector/tdengine-jdbc-connector.webp differ diff --git a/docs/en/14-reference/04-taosadapter.md b/docs/en/14-reference/04-taosadapter.md new file mode 100644 index 0000000000000000000000000000000000000000..3264124655e7040e1d94b43500a0b582d95cb5a1 --- /dev/null +++ b/docs/en/14-reference/04-taosadapter.md @@ -0,0 +1,337 @@ +--- +title: "taosAdapter" +description: "taosAdapter is a TDengine companion tool that acts as a bridge and adapter between TDengine clusters and applications. It provides an easy-to-use and efficient way to ingest data directly from data collection agent software such as Telegraf, StatsD, collectd, etc. It also provides an InfluxDB/OpenTSDB compatible data ingestion interface, allowing InfluxDB/OpenTSDB applications to be seamlessly ported to 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 is a TDengine companion tool that acts as a bridge and adapter between TDengine clusters and applications. It provides an easy-to-use and efficient way to ingest data directly from data collection agent software such as Telegraf, StatsD, collectd, etc. It also provides an InfluxDB/OpenTSDB compatible data ingestion interface that allows InfluxDB/OpenTSDB applications to be seamlessly ported to TDengine. + +taosAdapter provides the following features. + +- RESTful interface +- InfluxDB v1 compliant write interface +- OpenTSDB JSON and telnet format writes compatible +- Seamless connection to Telegraf +- Seamless connection to collectd +- Seamless connection to StatsD +- Supports Prometheus remote_read and remote_write + +## taosAdapter architecture diagram + +![TDengine Database taosAdapter Architecture](taosAdapter-architecture.webp) + +## taosAdapter Deployment Method + +### Install taosAdapter + +taosAdapter has been part of TDengine server software since TDengine v2.4.0.0. If you use the TDengine server, you don't need additional steps to install taosAdapter. You can download taosAdapter from [TDengine official website](https://tdengine.com/all-downloads/) to download the TDengine server installation package (taosAdapter is included in v2.4.0.0 and later version). If you need to deploy taosAdapter separately on another server other than the TDengine server, you should install the full TDengine server package on that server to install taosAdapter. If you need to build taosAdapter from source code, you can refer to the [Building taosAdapter]( https://github.com/taosdata/taosadapter/blob/develop/BUILD.md) documentation. + +### Start/Stop taosAdapter + +On Linux systems, the taosAdapter service is managed by `systemd` by default. You can use the command `systemctl start taosadapter` to start the taosAdapter service and use the command `systemctl stop taosadapter` to stop the taosAdapter service. + +### Remove taosAdapter + +Use the command `rmtaos` to remove the TDengine server software if you use tar.gz package. If you installed using a .deb or .rpm package, use the corresponding command, for your package manager, like apt or rpm to remove the TDengine server, including taosAdapter. + +### Upgrade taosAdapter + +taosAdapter and TDengine server need to use the same version. Please upgrade the taosAdapter by upgrading the TDengine server. +You need to upgrade the taosAdapter deployed separately from TDengine server by upgrading the TDengine server on the deployed server. + +## taosAdapter parameter list + +taosAdapter is configurable via command-line arguments, environment variables and configuration files. The default configuration file is /etc/taos/taosadapter.toml on Linux. + +Command-line arguments take precedence over environment variables over configuration files. The command-line usage is arg=val, e.g., taosadapter -p=30000 --debug=true. The detailed list is as follows: + +```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 +``` + +Note: +Please set the following Cross-Origin Resource Sharing (CORS) parameters according to the actual situation when using a browser for interface calls. + +```text +AllowAllOrigins +AllowOrigins +AllowHeaders +ExposeHeaders +AllowCredentials +AllowWebSockets +``` + +You do not need to care about these configurations if you do not make interface calls through the browser. + +For details on the CORS protocol, please refer to: [https://www.w3.org/wiki/CORS_Enabled](https://www.w3.org/wiki/CORS_Enabled) or [https://developer.mozilla.org/zh-CN/docs/Web/HTTP/CORS](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/CORS). + +See [example/config/taosadapter.toml](https://github.com/taosdata/taosadapter/blob/develop/example/config/taosadapter.toml) for sample configuration files. + +## Feature List + +- Compatible with RESTful interfaces [REST API](/reference/rest-api/) +- Compatible with InfluxDB v1 write interface + [https://docs.influxdata.com/influxdb/v2.0/reference/api/influxdb-1x/write/](https://docs.influxdata.com/influxdb/v2.0/reference/api/influxdb-1x/write/) +- Compatible with OpenTSDB JSON and telnet format writes + - + - +- Seamless connection to collectd + collectd is a system statistics collection daemon, please visit [https://collectd.org/](https://collectd.org/) for more information. +- Seamless connection with StatsD + StatsD is a simple yet powerful daemon for aggregating statistical information. Please visit [https://github.com/statsd/statsd](https://github.com/statsd/statsd) for more information. +- Seamless connection with icinga2 + icinga2 is a software that collects inspection result metrics and performance data. Please visit [https://icinga.com/docs/icinga-2/latest/doc/14-features/#opentsdb-writer](https://icinga.com/docs/icinga-2/latest/doc/14-features/#opentsdb-writer) for more information. +- Seamless connection to TCollector + TCollector is a client process that collects data from a local collector and pushes the data to OpenTSDB. Please visit [http://opentsdb.net/docs/build/html/user_guide/utilities/tcollector.html](http://opentsdb.net/docs/build/html/user_guide/utilities/tcollector.html) for more information. +- Seamless connection to node_exporter + node_export is an exporter for machine metrics. Please visit [https://github.com/prometheus/node_exporter](https://github.com/prometheus/node_exporter) for more information. +- Support for Prometheus remote_read and remote_write + remote_read and remote_write are interfaces for Prometheus data read and write from/to other data storage solution. Please visit [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) for more information. + +## Interfaces + +### TDengine RESTful interface + +You can use any client that supports the http protocol to write data to or query data from TDengine by accessing the REST interface address `http://:6041/`. See the [official documentation](/reference/connector#restful) for details. The following EndPoint is supported. + +```text +/rest/sql +/rest/sqlt +/rest/sqlutc +``` + +### InfluxDB + +You can use any client that supports the http protocol to access the RESTful interface address `http://:6041/` to write data in InfluxDB compatible format to TDengine. The EndPoint is as follows: + +```text +/influxdb/v1/write +``` + +Support InfluxDB query parameters as follows. + +- `db` Specifies the database name used by TDengine +- `precision` The time precision used by TDengine +- `u` TDengine user name +- `p` TDengine password + +Note: InfluxDB token authorization is not supported at present. Only Basic authorization and query parameter validation are supported. + +### OpenTSDB + +You can use any client that supports the http protocol to access the RESTful interface address `http://:6041/` to write data in OpenTSDB compatible format to TDengine. + +```text +/opentsdb/v1/put/json/:db +/opentsdb/v1/put/telnet/:db +``` + +### collectd + + + +### StatsD + + + +### icinga2 OpenTSDB writer + + + +### TCollector + + + +### node_exporter + +node_export is an exporter of hardware and OS metrics exposed by the \*NIX kernel used by Prometheus + +- Enable the taosAdapter configuration `node_exporter.enable` +- Set the configuration of the node_exporter +- Restart taosAdapter + +### Prometheus + + + +## Memory usage optimization methods + +taosAdapter will monitor its memory usage during operation and adjust it with two thresholds. Valid values are integers between 1 to 100, and represent a percentage of the system's physical memory. + +- pauseQueryMemoryThreshold +- pauseAllMemoryThreshold + +Stops processing query requests when the `pauseQueryMemoryThreshold` threshold is exceeded. + +HTTP response content. + +- code 503 +- body "query memory exceeds threshold" + +Stops processing all write and query requests when the `pauseAllMemoryThreshold` threshold is exceeded. + +HTTP response: code 503 + +- code 503 +- body "memory exceeds threshold" + +Resume the corresponding function when the memory falls back below the threshold. + +Status check interface `http://:6041/-/ping` + +- Normal returns `code 200` +- No parameter If memory exceeds pauseAllMemoryThreshold returns `code 503` +- Request parameter `action=query` returns `code 503` if memory exceeds `pauseQueryMemoryThreshold` or `pauseAllMemoryThreshold` + +Corresponding configuration parameter + +``text + monitor.collectDuration monitoring interval environment variable `TAOS_MONITOR_COLLECT_DURATION` (default value 3s) + monitor.incgroup whether to run in cgroup (set to true for running in container) environment variable `TAOS_MONITOR_INCGROUP` + monitor.pauseAllMemoryThreshold memory threshold for no more inserts and queries environment variable `TAOS_MONITOR_PAUSE_ALL_MEMORY_THRESHOLD` (default 80) + monitor.pauseQueryMemoryThreshold memory threshold for no more queries Environment variable `TAOS_MONITOR_PAUSE_QUERY_MEMORY_THRESHOLD` (default 70) +``` + +You should adjust this parameter based on your specific application scenario and operation strategy. We recommend using monitoring software to monitor system memory status. The load balancer can also check the taosAdapter running status through this interface. + +## taosAdapter Monitoring Metrics + +taosAdapter collects HTTP-related metrics, CPU percentage, and memory percentage. + +### HTTP interface + +Provides an interface conforming to [OpenMetrics](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md). + +```text +http://:6041/metrics +``` + +### Write to TDengine + +taosAdapter supports writing the metrics of HTTP monitoring, CPU percentage, and memory percentage to TDengine. + +For configuration parameters + +| **Configuration items** | **Description** | **Default values** | +| ----------------------- | --------------------------------------------------------- | ---------- | +| monitor.collectDuration | CPU and memory collection interval | 3s | +| monitor.identity | The current taosadapter identifier will be used if not set to `hostname:port` | | +| monitor.incgroup | whether it is running in a cgroup (set to true for running in a container) | false | +| monitor.writeToTD | Whether to write to TDengine | true | +| monitor.user | TDengine connection username | root | +| monitor.password | TDengine connection password | taosdata | +| monitor.writeInterval | Write to TDengine interval | 30s | + +## Limit the number of results returned + +taosAdapter controls the number of results returned by the parameter `restfulRowLimit`, -1 means no limit, default is no limit. + +This parameter controls the number of results returned by the following interfaces: + +- `http://:6041/rest/sql` +- `http://:6041/rest/sqlt` +- `http://:6041/rest/sqlutc` +- ` http://:6041/prometheus/v1/remote_read/:db` + +## Troubleshooting + +You can check the taosAdapter running status with the `systemctl status taosadapter` command. + +You can also adjust the level of the taosAdapter log output by setting the `--logLevel` parameter or the environment variable `TAOS_ADAPTER_LOG_LEVEL`. Valid values are: panic, fatal, error, warn, warning, info, debug and trace. + +## How to migrate from older TDengine versions to taosAdapter + +In TDengine server 2.2.x.x or earlier, the TDengine server process (taosd) contains an embedded HTTP service. As mentioned earlier, taosAdapter is a standalone software managed using `systemd` and has its own process ID. There are some configuration parameters and behaviors that are different between the two. See the following table for details. + +| **#** | **embedded httpd** | **taosAdapter** | **comment** | +| ----- | ------------------- | ------------------------------------ | ------------------------------------------------------------------ ------------------------------------------------------------------------ | +| 1 | httpEnableRecordSql | --logLevel=debug | | +| 2 | httpMaxThreads | n/a | taosAdapter Automatically manages thread pools without this parameter | +| 3 | telegrafUseFieldNum | See the taosAdapter telegraf configuration method | | +| 4 | restfulRowLimit | restfulRowLimit | Embedded httpd outputs 10240 rows of data by default, the maximum allowed is 102400. taosAdapter also provides restfulRowLimit but it is not limited by default. You can configure it according to the actual scenario. +| 5 | httpDebugFlag | Not applicable | httpdDebugFlag does not work for taosAdapter | +| 6 | httpDBNameMandatory | N/A | taosAdapter requires the database name to be specified in the URL | diff --git a/docs/en/14-reference/05-taosbenchmark.md b/docs/en/14-reference/05-taosbenchmark.md new file mode 100644 index 0000000000000000000000000000000000000000..0f250f0767601a1825f9eda2eac75a5f9b532fdc --- /dev/null +++ b/docs/en/14-reference/05-taosbenchmark.md @@ -0,0 +1,434 @@ +--- +title: taosBenchmark +sidebar_label: taosBenchmark +toc_max_heading_level: 4 +description: "taosBenchmark (once called taosdemo ) is a tool for testing the performance of TDengine." +--- + +## Introduction + +taosBenchmark (formerly taosdemo ) is a tool for testing the performance of TDengine products. taosBenchmark can test the performance of TDengine's insert, query, and subscription functions and simulate large amounts of data generated by many devices. taosBenchmark can be configured to generate user defined databases, supertables, subtables, and the time series data to populate these for performance benchmarking. taosBenchark is highly configurable and some of the configurations include the time interval for inserting data, the number of working threads and the capability to insert disordered data. The installer provides taosdemo as a soft link to taosBenchmark for compatibility with past users. + +## Installation + +There are two ways to install taosBenchmark: + +- Installing the official TDengine installer will automatically install taosBenchmark. Please refer to [TDengine installation](/operation/pkg-install) for details. + +- Compile taos-tools separately and install them. Please refer to the [taos-tools](https://github.com/taosdata/taos-tools) repository for details. + +## Run + +### Configuration and running methods + +TaosBenchmark needs to be executed on the terminal of the operating system, it supports two configuration methods: [Command-line arguments](#Command-line arguments in detailed) and [JSON configuration file](#Configuration file arguments in detailed). These two methods are mutually exclusive. Users can use `-f ` to specify a configuration file. When running taosBenchmark with command-line arguments to control its behavior, users should use other parameters for configuration, but not the `-f` parameter. In addition, taosBenchmark offers a special way of running without parameters. + +taosBenchmark supports the complete performance testing of TDengine by providing functionaly to write, query, and subscribe. These three functions are mutually exclusive, users can only select one of them each time taosBenchmark runs. The query and subscribe functionalities are only configurable using a json configuration file by specifying the parameter `filetype`, while write can be performed through both the command-line and a configuration file. + +**Make sure that the TDengine cluster is running correctly before running taosBenchmark. ** + +### Run without command-line arguments + +Execute the following commands to quickly experience taosBenchmark's default configuration-based write performance testing of TDengine. + +```bash +taosBenchmark +``` + +When run without parameters, taosBenchmark connects to the TDengine cluster specified in `/etc/taos` by default and creates a database named test in TDengine, a super table named `meters` under the test database, and 10,000 tables under the super table with 10,000 records written to each table. Note that if there is already a test database, this command will delete it first and create a new test database. + +### Run with command-line configuration parameters + +The `-f ` argument cannot be used when running taosBenchmark with command-line parameters. Users must specify all configuration parameters from the command-line. The following is an example of testing taosBenchmark writing performance using the command-line approach. + +```bash +taosBenchmark -I stmt -n 200 -t 100 +``` + +In the above command, `taosBenchmark` will create the default database named `test`, create the default super table named `meters`, create 100 subtables in the super table and insert 200 records for each subtable using parameter binding. + +### Run with the configuration file + +A sample configuration file is provided in the taosBenchmark installation package under `/examples/taosbenchmark-json`. + +Use the following command-line to run taosBenchmark and control its behavior via a configuration file. + +```bash +taosBenchmark -f +``` + +**Here are a few examples of configuration files:** + +#### Example of inserting a scenario JSON configuration file + +
+insert.json + +```json +{{#include /taos-tools/example/insert.json}} +``` + +
+ +#### Query Scenario JSON Profile Example + +
+query.json + +```json +{{#include /taos-tools/example/query.json}} +``` + +
+ +#### Subscription JSON configuration example + +
+subscribe.json + +```json +{{#include /taos-tools/example/subscribe.json}} +``` + +
+ +## Command-line arguments in detail + +- **-f/--file ** : + specify the configuration file to use. This file includes All parameters. Users should not use this parameter with other parameters on the command-line. There is no default value. + +- **-c/--config-dir ** : + specify the directory of the TDengine cluster configuration file. the default path is `/etc/taos`. + +- **-h/--host ** : + specify the FQDN of the TDengine server to connect to. The default value is localhost. + +- **-P/--port ** : + specify the port number of the TDengine server to connect to, the default value is 6030. + +- **-I/--interface ** : + specify the insert mode. Options are taosc, rest, stmt, sml, sml-rest, corresponding to normal write, restful interface writing, parameter binding interface writing, schemaless interface writing, RESTful schemaless interface writing (provided by taosAdapter). The default value is taosc. + +- **-u/--user ** : + specify the user name to connect to the TDengine server, the default is root. + +- **-p/--password ** : + specify the password to connect to the TDengine server, the default is `taosdata`. + +- **-o/--output ** : + specify the path of the result output file, the default value is `. /output.txt`. + +- **-T/--thread ** : + specify the number of threads to insert data, the default value is 8. + +- **-B/--interlace-rows ** : + enables interleaved insertion mode and specifies the number of rows of data to be inserted into each child table. Interleaved insertion mode means inserting the number of rows specified by this parameter into each sub-table and repeating the process until all sub-tables have been inserted. The default value is 0, i.e., data is inserted into one sub-table before the next sub-table is inserted. + +- **-i/--insert-interval ** : + specify the insert interval in `ms` for interleaved insert mode. The default value is 0. It only works if `-B/--interlace-rows` is greater than 0. That means that after inserting interlaced rows for each child table, the data insertion with multiple threads will wait for the interval specified by this value before proceeding to the next round of writes. + +- **-r/--rec-per-req ** : + specify the number of rows to write per request, the default value is 30000. + +- **-t/--tables ** : + specify the number of subtables to create, the default value is 10000. + +- **-S/--timestampstep ** : + specify the timestamp step between records when inserting data in each child table in ms, the default value is 1. + +- **-n/--records ** : + specify the number of records inserted into each sub-table, the default value is 10000. + +- **-d/--database ** : + specify the name of the database used, the default value is `test`. + +- **-b/--data-type ** : + specify the data column types of the super table. The default values are three columns of type FLOAT, INT, and FLOAT. + +- **-l/--columns ** : + specify the number of columns in the super table. If both this parameter and `-b/--data-type` are set, the resulting number of columns is the greater of the two. If the number specified by this parameter is greater than the number of columns specified by `-b/--data-type`, the unspecified column types default to INT, for example: `-l 5 -b float,double`, then the column types are `FLOAT,DOUBLE,INT,INT,INT`. If the number of columns specified is less than or equal to the number of columns specified by `-b/--data-type`, then the columns specified by `-b/--data-type` will be used. e.g.: `-l 3 -b float,double,float,bigint` will result in the column types `FLOAT,DOUBLE,FLOAT,BIGINT`. + +- **-A/--tag-type ** : + specify the tag column types of the super table. nchar and binary types can both set the length, for example: + +``` +taosBenchmark -A INT,DOUBLE,NCHAR,BINARY(16) +``` + +If the user does not set the tag type, the default is two tags, whose types are INT and BINARY(16). +Note: In some shells, such as bash, "()" needs to be escaped, so the above command should be + +``` +taosBenchmark -A INT,DOUBLE,NCHAR,BINARY\(16\) +``` + +- **-w/--binwidth **: + specify the default length for nchar and binary types, the default value is 64. + +- **-m/--table-prefix ** : + specify the prefix of the sub-table names, the default value is "d". + +- **-E/--escape-character** : + specify whether to use escape characters in the super table and sub-table names, the default is no. + +- **-C/--chinese** : + specify whether to use Unicode Chinese characters in nchar and binary, the deault is no. + +- **-N/--normal-table** : + specify whether taosBenchmark will create only normal tables instead of super tables. The default value is false. It can be used if the insert mode is taosc, stmt, and rest. + +- **-M/--random** : + specify whether taosBenchmark will generate random values. The default is false. When true, for tag/data columns of numeric type, the value is a random value within the range of values of that type. For NCHAR and BINARY type tag/data columns, the value is a random string within the specified length range. + +- **-x/--aggr-func** : + specify whether to query aggregation function after insertion. The default value is false. + +- **-y/--answer-yes** : + specify whether to require the user to confirm at the prompt to continue. The default value is false. + +- **-O/--disorder ** : + specify the percentage probability of disordered data, with a value range of [0,50]. The default value is 0, i.e., there is no disordered data. + +- **-R/--disorder-range ** : + specify the timestamp range for the disordered data. The disordered timestamp data will be out of order by the ordered timestamp minus a random value in this range. Valid only if the percentage of disordered data specified by `-O/--disorder` is greater than 0. + +- **-F/--prepare_rand ** : + specify the number of unique values in the generated random data. A value of 1 means that all data are equal. The default value is 10000. + +- **-a/--replica ** : + specify the number of replicas when creating the database. The default value is 1. + +- **-V/--version** : + Show version information only. Users should not use this with other parameters. + +- **-? /--help** : + Show help information and exit. Users should not use it with other parameters. + +## Configuration file parameters in detail + +### General configuration parameters + +The parameters listed in this section apply to all function modes. + +- **filetype** : The function to be tested, with optional values `insert`, `query` and `subscribe`. These correspond to the insert, query, and subscribe functions, respectively. Users can specify only one of these in each configuration file. +**cfgdir**: specify the TDengine cluster configuration file's directory. The default path is /etc/taos. + +- **host**: specify the FQDN of the TDengine server to connect to. The default value is `localhost`. + +- **port**: specify the port number of the TDengine server to connect to, the default value is `6030`. + +- **user**: specify the user name to connect to the TDengine server, the default is `root`. + +- **password**: specify the password to connect to the TDengine server, the default value is `taosdata`. + +### Insert scenario configuration parameters + +`filetype` must be set to `insert` in the insertion scenario. See [General Configuration Parameters](#general-configuration-parameters) + +#### Database related configuration parameters + +The parameters related to database creation are configured in `dbinfo` in the json configuration file, as follows. These parameters correspond to the database parameters specified when `create database` in TDengine. + +- **name**: specify the name of the database. + +- **drop**: indicate whether to delete the database before inserting. The default is true. + +- **replica**: specify the number of replicas when creating the database. + +- **days**: specify the time span for storing data in a single data file. The default is 10. + +- **cache**: specify the size of the cache blocks in MB. The default value is 16. + +- **blocks**: specify the number of cache blocks in each vnode. The default is 6. + +- **precision**: specify the database time precision. The default value is "ms". + +- **keep**: specify the number of days to keep the data. The default value is 3650. + +- **minRows**: specify the minimum number of records in the file block. The default value is 100. + +- **maxRows**: specify the maximum number of records in the file block. The default value is 4096. + +- **comp**: specify the file compression level. The default value is 2. + +- **walLevel** : specify WAL level, default is 1. + +- **cacheLast**: indicate whether to allow the last record of each table to be kept in memory. The default value is 0. The value can be 0, 1, 2, or 3. + +- **quorum**: specify the number of writing acknowledgments in multi-replica mode. The default value is 1. + +- **fsync**: specify the interval of fsync in ms when users set WAL to 2. The default value is 3000. + +- **update** : indicate whether to support data update, default value is 0, values can be 0, 1, 2. + +#### Super table related configuration parameters + +The parameters for creating super tables are configured in `super_tables` in the json configuration file, as shown below. + +- **name**: Super table name, mandatory, no default value. +- **child_table_exists** : whether the child table already exists, default value is "no", values can be "yes" or "no". + +- **child_table_count** : The number of child tables, the default value is 10. + +- **child_table_prefix** : The prefix of the child table name, mandatory configuration item, no default value. + +- **escape_character**: specify whether the super table and child table names containing escape characters. By default is "no". The value can be "yes" or "no". + +- **auto_create_table**: only when insert_mode is taosc, rest, stmt, and childtable_exists is "no". "yes" means taosBenchmark will automatically create non-existent tables when inserting data; "no" means that taosBenchmark will create all tables before inserting. + +- **batch_create_tbl_num** : the number of tables per batch when creating sub-tables, default is 10. Note: the actual number of batches may not be the same as this value. If the executed SQL statement is larger than the maximum length supported, it will be automatically truncated and re-executed to continue creating. + +- **data_source**: specify the source of data-generation. Default is taosBenchmark randomly generated. Users can configure it as "rand" and "sample". When "sample" is used, taosBenchmark will use the data in the file specified by the `sample_file` parameter. + +- **insert_mode**: insertion mode with options taosc, rest, stmt, sml, sml-rest, corresponding to normal write, restful interface write, parameter binding interface write, schemaless interface write, restful schemaless interface write (provided by taosAdapter). The default value is taosc. + +- **non_stop_mode**: Specify whether to keep writing. If "yes", insert_rows will be disabled, and writing will not stop until Ctrl + C stops the program. The default value is "no", i.e., taosBenchmark will stop the writing after the specified number of rows are written. Note: insert_rows must be configured as a non-zero positive integer even if it is disabled in continuous write mode. + +- **line_protocol**: Insert data using line protocol. Only works when insert_mode is sml or sml-rest. The value can be `line`, `telnet`, or `json`. + +- **tcp_transfer**: Communication protocol in telnet mode only takes effect when insert_mode is sml-rest, and line_protocol is telnet. If not configured, the default protocol is http. + +- **insert_rows** : The number of inserted rows per child table, default is 0. + +- **childtable_offset**: Effective only if childtable_exists is yes, specifies the offset when fetching the list of child tables from the super table, i.e., starting from the first child table. + +- **childtable_limit**: Effective only when childtable_exists is yes, specifies the upper limit for fetching the list of child tables from the super table. + +- **interlace_rows**: Enables interleaved insertion mode and specifies the number of rows of data to be inserted into each child table at a time. Staggered insertion mode means inserting the number of rows specified by this parameter into each sub-table and repeating the process until all sub-tables have been inserted. The default value is 0, i.e., data is inserted into one sub-table before the next sub-table is inserted. + +- **insert_interval** : Specifies the insertion interval in ms for interleaved insertion mode. The default value is 0. It only works if `-B/--interlace-rows` is greater than 0. After inserting interlaced rows for each child table, the data insertion thread will wait for the interval specified by this value before proceeding to the next round of writes. + +- **partial_col_num**: If this value is a positive number n, only the first n columns are written to, only if insert_mode is taosc and rest, or all columns if n is 0. + +- **disorder_ratio** : Specifies the percentage probability of disordered (i.e. out-of-order) data in the value range [0,50]. The default is 0, which means there is no disorder data. + +- **disorder_range** : Specifies the timestamp fallback range for the disordered data. The disordered timestamp is generated by subtracting a random value in this range, from the timestamp that would be used in the non-disorder case. Valid only if the percentage of disordered data specified by `-O/--disorder` is greater than 0. + +- **timestamp_step**: The timestamp step for inserting data in each child table, in units consistent with the `precision` of the database. For e.g. if the `precision` is milliseconds, the timestamp step will be in milliseconds. The default value is 1. + +- **start_timestamp** : The timestamp start value of each sub-table, the default value is now. + +- **sample_format**: The type of the sample data file; for now only "csv" is supported. + +- **sample_file**: Specify a CSV format file as the data source. It only works when data_source is a sample. If the number of rows in the CSV file is less than or equal to prepared_rand, then taosBenchmark will read the CSV file data cyclically until it is the same as prepared_rand; otherwise, taosBenchmark will read only the rows with the number of prepared_rand. The final number of rows of data generated is the smaller of the two. + +- **use_sample_ts**: effective only when data_source is `sample`, indicates whether the CSV file specified by sample_file contains the first timestamp column. Default is no. If set to yes, the first column of the CSV file is used as `timestamp`. Since the timestamp of the same sub-table cannot be repeated, the amount of data generated depends on the same number of rows of data in the CSV file, and insert_rows will be invalidated. + +- **tags_file** : only works when insert_mode is taosc, rest. The final tag value is related to the childtable_count. Suppose the tag data rows in the CSV file are smaller than the given number of child tables. In that case, taosBenchmark will read the CSV file data cyclically until the number of child tables specified by childtable_count is generated. Otherwise, taosBenchmark will read the childtable_count rows of tag data only. The final number of child tables generated is the smaller of the two. + +#### Tag and Data Column Configuration Parameters + +The configuration parameters for specifying super table tag columns and data columns are in `columns` and `tag` in `super_tables`, respectively. + +- **type**: Specify the column type. For optional values, please refer to the data types supported by TDengine. + Note: JSON data type is unique and can only be used for tags. When using JSON type as a tag, there is and can only be this one tag. At this time, `count` and `len` represent the meaning of the number of key-value pairs within the JSON tag and the length of the value of each KV pair. Respectively, the value is a string by default. + +- **len**: Specifies the length of this data type, valid for NCHAR, BINARY, and JSON data types. If this parameter is configured for other data types, a value of 0 means that the column is always written with a null value; if it is not 0, it is ignored. + +- **count**: Specifies the number of consecutive occurrences of the column type, e.g., "count": 4096 generates 4096 columns of the specified type. + +- **name** : The name of the column, if used together with count, e.g. "name": "current", "count":3, then the names of the 3 columns are current, current_2. current_3. + +- **min**: The minimum value of the column/label of the data type. + +- **max**: The maximum value of the column/label of the data type. + +- **values**: The value field of the nchar/binary column/label, which will be chosen randomly from the values. + +#### insertion behavior configuration parameters + +- **thread_count**: specify the number of threads to insert data. Default is 8. + +- **create_table_thread_count** : The number of threads to build the table, default is 8. + +- **connection_pool_size** : The number of pre-established connections to the TDengine server. If not configured, it is the same as number of threads specified. + +- **result_file** : The path to the result output file, the default value is . /output.txt. + +- **confirm_parameter_prompt**: The switch parameter requires the user to confirm after the prompt to continue. The default value is false. + +- **interlace_rows**: Enables interleaved insertion mode and specifies the number of rows of data to be inserted into each child table at a time. Interleaved insertion mode means inserting the number of rows specified by this parameter into each sub-table and repeating the process until all sub-tables are inserted. The default value is 0, which means that data will be inserted into the following child table only after data is inserted into one child table. + This parameter can also be configured in `super_tables`, and if so, the configuration in `super_tables` takes precedence and overrides the global setting. + +- **insert_interval** : + Specifies the insertion interval in ms for interleaved insertion mode. The default value is 0. Only works if `-B/--interlace-rows` is greater than 0. It means that after inserting interlace rows for each child table, the data insertion thread will wait for the interval specified by this value before proceeding to the next round of writes. + This parameter can also be configured in `super_tables`, and if configured, the configuration in `super_tables` takes high priority, overriding the global setting. + +- **num_of_records_per_req** : + The number of rows of data to be written per request to TDengine, the default value is 30000. When it is set too large, the TDengine client driver will return the corresponding error message, so you need to lower the setting of this parameter to meet the writing requirements. + +- **prepare_rand**: The number of unique values in the generated random data. A value of 1 means that all data are the same. The default value is 10000. + +### Query scenario configuration parameters + +`filetype` must be set to `query` in the query scenario. See [General Configuration Parameters](#general-configuration-parameters) for details of this parameter and other general parameters + +#### Configuration parameters for executing the specified query statement + +The configuration parameters for querying the sub-tables or the normal tables are set in `specified_table_query`. + +- **query_interval** : The query interval in seconds, the default value is 0. + +- **threads**: The number of threads to execute the query SQL, the default value is 1. + +- **sqls**. + - **sql**: the SQL command to be executed. + - **result**: the file to save the query result. If it is unspecified, taosBenchark will not save the result. + +#### Configuration parameters of query super table + +The configuration parameters of the super table query are set in `super_table_query`. + +- **stblname**: Specify the name of the super table to be queried, required. + +- **query_interval** : The query interval in seconds, the default value is 0. + +- **threads**: The number of threads to execute the query SQL, the default value is 1. + +- **sqls** : The default value is 1. + - **sql**: The SQL command to be executed. For the query SQL of super table, keep "xxxx" in the SQL command. The program will automatically replace it with all the sub-table names of the super table. + Replace it with all the sub-table names in the super table. + - **result**: The file to save the query result. If not specified, taosBenchmark will not save result. + +### Subscription scenario configuration parameters + +`filetype` must be set to `subscribe` in the subscription scenario. See [General Configuration Parameters](#genera-configuration-parameters) for details of this and other general parameters + +#### Configuration parameters for executing the specified subscription statement + +The configuration parameters for subscribing to a sub-table or a generic table are set in `specified_table_query`. + +- **threads**: The number of threads to execute SQL, default is 1. + +- **interval**: The time interval to execute the subscription, in seconds, default is 0. + +- **restart** : "yes" means start a new subscription, "no" means continue the previous subscription, the default value is "no". + +- **keepProgress**: "yes" means keep the progress of the subscription, "no" means don't keep it, and the default value is "no". + +- **resubAfterConsume**: "yes" means cancel the previous subscription and then subscribe again, "no" means continue the previous subscription, and the default value is "no". + +- **sqls** : The default value is "no". + - **sql** : The SQL command to be executed, required. + - **result** : The file to save the query result, unspecified is not saved. + +#### Configuration parameters for subscribing to supertables + +The configuration parameters for subscribing to a super table are set in `super_table_query`. + +- **stblname**: The name of the super table to subscribe. + +- **threads**: The number of threads to execute SQL, default is 1. + +- **interval**: The time interval to execute the subscription, in seconds, default is 0. + +- **restart** : "yes" means start a new subscription, "no" means continue the previous subscription, the default value is "no". + +- **keepProgress**: "yes" means keep the progress of the subscription, "no" means don't keep it, and the default value is "no". + +- **resubAfterConsume**: "yes" means cancel the previous subscription and then subscribe again, "no" means continue the previous subscription, and the default value is "no". + +- **sqls** : The default value is "no". + - **sql**: SQL command to be executed, required; for the query SQL of the super table, keep "xxxx" in the SQL command, and the program will replace it with all the sub-table names of the super table automatically. + Replace it with all the sub-table names in the super table. + - **result**: The file to save the query result, if not specified, it will not be saved. diff --git a/docs/en/14-reference/06-taosdump.md b/docs/en/14-reference/06-taosdump.md new file mode 100644 index 0000000000000000000000000000000000000000..5403e40925f633ce62795cc6037fc8c8f7aad07a --- /dev/null +++ b/docs/en/14-reference/06-taosdump.md @@ -0,0 +1,115 @@ +--- +title: taosdump +description: "taosdump is a tool that supports backing up data from a running TDengine cluster and restoring the backed up data to the same, or another running TDengine cluster." +--- + +## Introduction + +taosdump is a tool that supports backing up data from a running TDengine cluster and restoring the backed up data to the same, or another running TDengine cluster. + +taosdump can back up a database, a super table, or a normal table as a logical data unit or backup data records in the database, super tables, and normal tables. When using taosdump, you can specify the directory path for data backup. If you do not specify a directory, taosdump will back up the data to the current directory by default. + +If the specified location already has data files, taosdump will prompt the user and exit immediately to avoid data overwriting. This means that the same path can only be used for one backup. + +Please be careful if you see a prompt for this and please ensure that you follow best practices and relevant SOPs for data integrity, backup and data security. + +Users should not use taosdump to back up raw data, environment settings, hardware information, server configuration, or cluster topology. taosdump uses [Apache AVRO](https://avro.apache.org/) as the data file format to store backup data. + +## Installation + +There are two ways to install taosdump: + +- Install the taosTools official installer. Please find taosTools from [All download links](https://www.tdengine.com/all-downloads) page and download and install it. + +- Compile taos-tools separately and install it. Please refer to the [taos-tools](https://github.com/taosdata/taos-tools) repository for details. + +## Common usage scenarios + +### taosdump backup data + +1. backing up all databases: specify `-A` or `-all-databases` parameter. +2. backup multiple specified databases: use `-D db1,db2,... ` parameters; +3. back up some super or normal tables in the specified database: use `-dbname stbname1 stbname2 tbname1 tbname2 ... ` parameters. Note that the first parameter of this input sequence is the database name, and only one database is supported. The second and subsequent parameters are the names of super or normal tables in that database, separated by spaces. +4. back up the system log database: TDengine clusters usually contain a system database named `log`. The data in this database is the data that TDengine runs itself, and the taosdump will not back up the log database by default. If users need to back up the log database, users can use the `-a` or `-allow-sys` command-line parameter. +5. Loose mode backup: taosdump version 1.4.1 onwards provides `-n` and `-L` parameters for backing up data without using escape characters and "loose" mode, which can reduce the number of backups if table names, column names, tag names do not use escape characters. This can also reduce the backup data time and backup data footprint. If you are unsure about using `-n` and `-L` conditions, please use the default parameters for "strict" mode backup. See the [official documentation](/taos-sql/escape) for a description of escaped characters. + +:::tip +- taosdump versions after 1.4.1 provide the `-I` argument for parsing Avro file schema and data. If users specify `-s` then only taosdump will parse schema. +- Backups after taosdump 1.4.2 use the batch count specified by the `-B` parameter. The default value is 16384. If, in some environments, low network speed or disk performance causes "Error actual dump ... batch ...", then try changing the `-B` parameter to a smaller value. + +::: + +### taosdump recover data + +Restore the data file in the specified path: use the `-i` parameter plus the path to the data file. You should not use the same directory to backup different data sets, and you should not backup the same data set multiple times in the same path. Otherwise, the backup data will cause overwriting or multiple backups. + +:::tip +taosdump internally uses TDengine stmt binding API for writing recovery data with a default batch size of 16384 for better data recovery performance. If there are more columns in the backup data, it may cause a "WAL size exceeds limit" error. You can try to adjust the batch size to a smaller value by using the `-B` parameter. + +::: + +## Detailed command-line parameter list + +The following is a detailed list of taosdump command-line arguments. + +``` +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 from which to dump data. 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 listed databases. Use comma to separate + database names. + -N, --without-property Dump database without its properties. + -s, --schemaonly Only dump table schemas. + -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 Use 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/en/14-reference/07-tdinsight/assets/15146-tdengine-monitor-dashboard.json similarity index 100% rename from docs-cn/14-reference/07-tdinsight/assets/15146-tdengine-monitor-dashboard.json rename to docs/en/14-reference/07-tdinsight/assets/15146-tdengine-monitor-dashboard.json diff --git a/docs-cn/14-reference/07-tdinsight/assets/15155-tdengine-alert-demo.json b/docs/en/14-reference/07-tdinsight/assets/15155-tdengine-alert-demo.json similarity index 100% rename from docs-cn/14-reference/07-tdinsight/assets/15155-tdengine-alert-demo.json rename to docs/en/14-reference/07-tdinsight/assets/15155-tdengine-alert-demo.json diff --git a/docs/en/14-reference/07-tdinsight/assets/TDinsight-1-cluster-status.webp b/docs/en/14-reference/07-tdinsight/assets/TDinsight-1-cluster-status.webp new file mode 100644 index 0000000000000000000000000000000000000000..a78e18028a94c2f6a783b08d992a25c791527407 Binary files /dev/null and b/docs/en/14-reference/07-tdinsight/assets/TDinsight-1-cluster-status.webp differ diff --git a/docs/en/14-reference/07-tdinsight/assets/TDinsight-2-dnodes.webp b/docs/en/14-reference/07-tdinsight/assets/TDinsight-2-dnodes.webp new file mode 100644 index 0000000000000000000000000000000000000000..b152418d0902b8ebdf62ebce6705c10dd5ab4fbf Binary files /dev/null and b/docs/en/14-reference/07-tdinsight/assets/TDinsight-2-dnodes.webp differ diff --git a/docs/en/14-reference/07-tdinsight/assets/TDinsight-3-mnodes.webp b/docs/en/14-reference/07-tdinsight/assets/TDinsight-3-mnodes.webp new file mode 100644 index 0000000000000000000000000000000000000000..f58f48b7f17375cb8e62e7c0126ca3aea56a13f6 Binary files /dev/null and b/docs/en/14-reference/07-tdinsight/assets/TDinsight-3-mnodes.webp differ diff --git a/docs/en/14-reference/07-tdinsight/assets/TDinsight-4-requests.webp b/docs/en/14-reference/07-tdinsight/assets/TDinsight-4-requests.webp new file mode 100644 index 0000000000000000000000000000000000000000..00afcce013602dce0da17bfd033f65aaa8e43bb7 Binary files /dev/null and b/docs/en/14-reference/07-tdinsight/assets/TDinsight-4-requests.webp differ diff --git a/docs/en/14-reference/07-tdinsight/assets/TDinsight-5-database.webp b/docs/en/14-reference/07-tdinsight/assets/TDinsight-5-database.webp new file mode 100644 index 0000000000000000000000000000000000000000..567e5694f9d7a035a3eb354493d3df8ed64db251 Binary files /dev/null and b/docs/en/14-reference/07-tdinsight/assets/TDinsight-5-database.webp differ diff --git a/docs/en/14-reference/07-tdinsight/assets/TDinsight-6-dnode-usage.webp b/docs/en/14-reference/07-tdinsight/assets/TDinsight-6-dnode-usage.webp new file mode 100644 index 0000000000000000000000000000000000000000..cc8a912810f35e53a6e5fa96ea0c81e334ffc0df Binary files /dev/null and b/docs/en/14-reference/07-tdinsight/assets/TDinsight-6-dnode-usage.webp differ diff --git a/docs/en/14-reference/07-tdinsight/assets/TDinsight-7-login-history.webp b/docs/en/14-reference/07-tdinsight/assets/TDinsight-7-login-history.webp new file mode 100644 index 0000000000000000000000000000000000000000..651b716bc511ba2ed5db5e6fc6b0591ef150cbf6 Binary files /dev/null and b/docs/en/14-reference/07-tdinsight/assets/TDinsight-7-login-history.webp differ diff --git a/docs/en/14-reference/07-tdinsight/assets/TDinsight-8-taosadapter.webp b/docs/en/14-reference/07-tdinsight/assets/TDinsight-8-taosadapter.webp new file mode 100644 index 0000000000000000000000000000000000000000..8666193f59497180574fd2786266e5baabbe9761 Binary files /dev/null and b/docs/en/14-reference/07-tdinsight/assets/TDinsight-8-taosadapter.webp differ diff --git a/docs/en/14-reference/07-tdinsight/assets/TDinsight-full.webp b/docs/en/14-reference/07-tdinsight/assets/TDinsight-full.webp new file mode 100644 index 0000000000000000000000000000000000000000..7f38a76a2b899ffebc7aecd39c8ec4fd0b2da778 Binary files /dev/null and b/docs/en/14-reference/07-tdinsight/assets/TDinsight-full.webp differ diff --git a/docs/en/14-reference/07-tdinsight/assets/alert-manager-status.webp b/docs/en/14-reference/07-tdinsight/assets/alert-manager-status.webp new file mode 100644 index 0000000000000000000000000000000000000000..3d7fe932a23f3720e76e4217a7b5d1868d81fac8 Binary files /dev/null and b/docs/en/14-reference/07-tdinsight/assets/alert-manager-status.webp differ diff --git a/docs/en/14-reference/07-tdinsight/assets/alert-notification-channel.webp b/docs/en/14-reference/07-tdinsight/assets/alert-notification-channel.webp new file mode 100644 index 0000000000000000000000000000000000000000..517123954efe4b94485fdab2e07be0d765f5daa2 Binary files /dev/null and b/docs/en/14-reference/07-tdinsight/assets/alert-notification-channel.webp differ diff --git a/docs/en/14-reference/07-tdinsight/assets/alert-query-demo.webp b/docs/en/14-reference/07-tdinsight/assets/alert-query-demo.webp new file mode 100644 index 0000000000000000000000000000000000000000..6666296ac16e7a0c0ab3db23f0517f2089d09035 Binary files /dev/null and b/docs/en/14-reference/07-tdinsight/assets/alert-query-demo.webp differ diff --git a/docs/en/14-reference/07-tdinsight/assets/alert-rule-condition-notifications.webp b/docs/en/14-reference/07-tdinsight/assets/alert-rule-condition-notifications.webp new file mode 100644 index 0000000000000000000000000000000000000000..6f74bc3a47a32de661ef25f787a947d823715810 Binary files /dev/null and b/docs/en/14-reference/07-tdinsight/assets/alert-rule-condition-notifications.webp differ diff --git a/docs/en/14-reference/07-tdinsight/assets/alert-rule-test.webp b/docs/en/14-reference/07-tdinsight/assets/alert-rule-test.webp new file mode 100644 index 0000000000000000000000000000000000000000..acda3b24a6263815ac8b658709d2172300ca3b00 Binary files /dev/null and b/docs/en/14-reference/07-tdinsight/assets/alert-rule-test.webp differ diff --git a/docs/en/14-reference/07-tdinsight/assets/howto-add-datasource-button.webp b/docs/en/14-reference/07-tdinsight/assets/howto-add-datasource-button.webp new file mode 100644 index 0000000000000000000000000000000000000000..903e236e2a776dfef7f85c014662e8913a9033a5 Binary files /dev/null and b/docs/en/14-reference/07-tdinsight/assets/howto-add-datasource-button.webp differ diff --git a/docs/en/14-reference/07-tdinsight/assets/howto-add-datasource-tdengine.webp b/docs/en/14-reference/07-tdinsight/assets/howto-add-datasource-tdengine.webp new file mode 100644 index 0000000000000000000000000000000000000000..14fcfe9d183e8804199708ae4492d0904a7c9d62 Binary files /dev/null and b/docs/en/14-reference/07-tdinsight/assets/howto-add-datasource-tdengine.webp differ diff --git a/docs/en/14-reference/07-tdinsight/assets/howto-add-datasource-test.webp b/docs/en/14-reference/07-tdinsight/assets/howto-add-datasource-test.webp new file mode 100644 index 0000000000000000000000000000000000000000..00b50cc619b030d1fb2be3a367183901d5c833e8 Binary files /dev/null and b/docs/en/14-reference/07-tdinsight/assets/howto-add-datasource-test.webp differ diff --git a/docs/en/14-reference/07-tdinsight/assets/howto-add-datasource.webp b/docs/en/14-reference/07-tdinsight/assets/howto-add-datasource.webp new file mode 100644 index 0000000000000000000000000000000000000000..06d0ff6ed50091a6340508bc5b2b3f78b65dcb18 Binary files /dev/null and b/docs/en/14-reference/07-tdinsight/assets/howto-add-datasource.webp differ diff --git a/docs/en/14-reference/07-tdinsight/assets/howto-dashboard-display.webp b/docs/en/14-reference/07-tdinsight/assets/howto-dashboard-display.webp new file mode 100644 index 0000000000000000000000000000000000000000..e2ec052b91e439a817f6e88b8afd0fcb4dcb7ef8 Binary files /dev/null and b/docs/en/14-reference/07-tdinsight/assets/howto-dashboard-display.webp differ diff --git a/docs/en/14-reference/07-tdinsight/assets/howto-dashboard-import-options.webp b/docs/en/14-reference/07-tdinsight/assets/howto-dashboard-import-options.webp new file mode 100644 index 0000000000000000000000000000000000000000..665c035f9755b9472aee33cd61d3ab52831194b5 Binary files /dev/null and b/docs/en/14-reference/07-tdinsight/assets/howto-dashboard-import-options.webp differ diff --git a/docs/en/14-reference/07-tdinsight/assets/howto-import-dashboard.webp b/docs/en/14-reference/07-tdinsight/assets/howto-import-dashboard.webp new file mode 100644 index 0000000000000000000000000000000000000000..7dc42eeba919fee7b438a453c00bb9fd0ac2d274 Binary files /dev/null and b/docs/en/14-reference/07-tdinsight/assets/howto-import-dashboard.webp differ diff --git a/docs/en/14-reference/07-tdinsight/assets/import-dashboard-15167.webp b/docs/en/14-reference/07-tdinsight/assets/import-dashboard-15167.webp new file mode 100644 index 0000000000000000000000000000000000000000..7ef081900f8de99c859193b69d49b3d6bc187909 Binary files /dev/null and b/docs/en/14-reference/07-tdinsight/assets/import-dashboard-15167.webp differ diff --git a/docs/en/14-reference/07-tdinsight/assets/import-dashboard-for-tdengine.webp b/docs/en/14-reference/07-tdinsight/assets/import-dashboard-for-tdengine.webp new file mode 100644 index 0000000000000000000000000000000000000000..602452fc4c89424d8e17d46d74949b69be84dbe8 Binary files /dev/null and b/docs/en/14-reference/07-tdinsight/assets/import-dashboard-for-tdengine.webp differ diff --git a/docs/en/14-reference/07-tdinsight/assets/import-via-grafana-dot-com.webp b/docs/en/14-reference/07-tdinsight/assets/import-via-grafana-dot-com.webp new file mode 100644 index 0000000000000000000000000000000000000000..35a3ebba781f24dbb0066993d1ca2f02659997d2 Binary files /dev/null and b/docs/en/14-reference/07-tdinsight/assets/import-via-grafana-dot-com.webp differ diff --git a/docs/en/14-reference/07-tdinsight/assets/import_dashboard.webp b/docs/en/14-reference/07-tdinsight/assets/import_dashboard.webp new file mode 100644 index 0000000000000000000000000000000000000000..fb7958f1b9fbd43c8f63136024842790e711c490 Binary files /dev/null and b/docs/en/14-reference/07-tdinsight/assets/import_dashboard.webp differ diff --git a/docs-cn/14-reference/07-tdinsight/assets/tdengine-grafana-7.x.json b/docs/en/14-reference/07-tdinsight/assets/tdengine-grafana-7.x.json similarity index 100% rename from docs-cn/14-reference/07-tdinsight/assets/tdengine-grafana-7.x.json rename to docs/en/14-reference/07-tdinsight/assets/tdengine-grafana-7.x.json diff --git a/docs-cn/14-reference/07-tdinsight/assets/tdengine-grafana.json b/docs/en/14-reference/07-tdinsight/assets/tdengine-grafana.json similarity index 100% rename from docs-cn/14-reference/07-tdinsight/assets/tdengine-grafana.json rename to docs/en/14-reference/07-tdinsight/assets/tdengine-grafana.json diff --git a/docs/en/14-reference/07-tdinsight/assets/tdengine_dashboard.webp b/docs/en/14-reference/07-tdinsight/assets/tdengine_dashboard.webp new file mode 100644 index 0000000000000000000000000000000000000000..49f1d88f4ad93286cd8582536e82b4dcc4ff271b Binary files /dev/null and b/docs/en/14-reference/07-tdinsight/assets/tdengine_dashboard.webp differ diff --git a/docs/en/14-reference/07-tdinsight/index.md b/docs/en/14-reference/07-tdinsight/index.md new file mode 100644 index 0000000000000000000000000000000000000000..cebfafa225e6e8de75ff84bb51fa664784177910 --- /dev/null +++ b/docs/en/14-reference/07-tdinsight/index.md @@ -0,0 +1,428 @@ +--- +title: TDinsight - Grafana-based Zero-Dependency Monitoring Solution for TDengine +sidebar_label: TDinsight +--- + +TDinsight is a solution for monitoring TDengine using the builtin native monitoring database and [Grafana]. + +After TDengine starts, it will automatically create a monitoring database `log`. TDengine will automatically write many metrics in specific intervals into the `log` database. The metrics may include the server's CPU, memory, hard disk space, network bandwidth, number of requests, disk read/write speed, slow queries, other information like important system operations (user login, database creation, database deletion, etc.), and error alarms. With [Grafana] and [TDengine Data Source Plugin](https://github.com/taosdata/grafanaplugin/releases), TDinsight can visualize cluster status, node information, insertion and query requests, resource usage, vnode, dnode, and mnode status, exception alerts and many other metrics. This is very convenient for developers who want to monitor TDengine cluster status in real-time. This article will guide users to install the Grafana server, automatically install the TDengine data source plug-in, and deploy the TDinsight visualization panel using the `TDinsight.sh` installation script. + +## System Requirements + +To deploy TDinsight, a single-node TDengine server or a multi-node TDengine cluster and a [Grafana] server are required. This dashboard requires TDengine 2.3.3.0 and above, with the `log` database enabled (`monitor = 1`). + +## Installing Grafana + +We recommend using the latest [Grafana] version 7 or 8 here. You can install Grafana on any [supported operating system](https://grafana.com/docs/grafana/latest/installation/requirements/#supported-operating-systems) by following the [official Grafana documentation Instructions](https://grafana.com/docs/grafana/latest/installation/) to install [Grafana]. + +### Installing Grafana on Debian or Ubuntu + +For Debian or Ubuntu operating systems, we recommend the Grafana image repository and using the following command to install from scratch. + +```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 +``` + +### Install Grafana on CentOS / RHEL + +You can install it from its official YUM repository. + +```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 +``` + +Or install it with RPM package. + +```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 +``` + +## Automated deployment of TDinsight + +We provide an installation script [`TDinsight.sh`](https://github.com/taosdata/grafanaplugin/releases/latest/download/TDinsight.sh) to allow users to configure the installation automatically and quickly. + +You can download the script via `wget` or other tools: + +```bash +wget https://github.com/taosdata/grafanaplugin/releases/latest/download/TDinsight.sh +chmod +x TDinsight.sh +./TDinsight.sh +``` + +This script will automatically download the latest [Grafana TDengine data source plugin](https://github.com/taosdata/grafanaplugin/releases/latest) and [TDinsight dashboard](https://grafana.com/grafana/dashboards/15167) with configurable parameters for command-line options to the [Grafana Provisioning](https://grafana.com/docs/grafana/latest/administration/provisioning/) configuration file to automate deployment and updates, etc. With the alert setting options provided by this script, you can also get built-in support for AliCloud SMS alert notifications. + +Assume you use TDengine and Grafana's default services on the same host. Run `. /TDinsight.sh` and open the Grafana browser window to see the TDinsight dashboard. + +The following is a description of TDinsight.sh usage. + +```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. + +Alibaba Cloud SMS as Notifier: +-s, --sms-enabled To enable tdengine-datasource plugin builtin Alibaba Cloud 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 Alibaba Cloud SMS access key id +-K, --sms-access-key-secret Alibaba Cloud 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] +``` + +Most command-line options can take effect the same as environment variables. + +| Short Options | Long Options | Environment Variables | Description | +| ------ | -------------------------- | ---------------------------- | ------------------------------------------------------------------ --------- | +| -v | --plugin-version | TDENGINE_PLUGIN_VERSION | The TDengine data source plugin version, the latest version is used by default. | -P +| -P | --grafana-provisioning-dir | GF_PROVISIONING_DIR | The Grafana configuration directory, defaults to `/etc/grafana/provisioning/` | +| -G | --grafana-plugins-dir | GF_PLUGINS_DIR | The Grafana plugin directory, defaults to `/var/lib/grafana/plugins`. | -O +| -O | --grafana-org-id | GF_ORG_ID | The Grafana organization ID, default is 1. | +| -n | --tdengine-ds-name | TDENGINE_DS_NAME | The name of the TDengine data source, defaults to TDengine. | -a | --tdengine-ds-name | The name of the TDengine data source, defaults to TDengine. +| -a | --tdengine-api | TDENGINE_API | The TDengine REST API endpoint. Defaults to `http://127.0.0.1:6041`. | -u +| -u | --tdengine-user | TDENGINE_USER | TDengine username. [default: root] | +| -p | --tdengine-password | TDENGINE_PASSWORD | TDengine password. [default: tadosdata] | -i | --tdengine-password +| -i | --tdinsight-uid | TDINSIGHT_DASHBOARD_UID | TDinsight `uid` of the dashboard. [default: tdinsight] | +| -t | --tdinsight-title | TDINSIGHT_DASHBOARD_TITLE | TDinsight dashboard title. [Default: TDinsight] | -e | -tdinsight-title +| -e | --tdinsight-editable | TDINSIGHT_DASHBOARD_EDITABLE | If the dashboard is configured to be editable. [Default: false] | -e | --external +| -E | --external-notifier | EXTERNAL_NOTIFIER | Apply the external notifier uid to the TDinsight dashboard. | -s +| -s | --sms-enabled | SMS_ENABLED | Enable the tdengine-datasource plugin built into Alibaba Cloud SMS webhook. | -s +| -N | --sms-notifier-name | SMS_NOTIFIER_NAME | The name of the provisioning notifier. [Default: `TDinsight Builtin SMS`] | -U +| -U | --sms-notifier-uid | SMS_NOTIFIER_UID | "Notification Channel" `uid`, lowercase of the program name is used by default, other characters are replaced by "-". |-sms +| -D | --sms-notifier-is-default | SMS_NOTIFIER_IS_DEFAULT | Set built-in SMS notification to default value. |-sms-notifier-is-default +| -I | --sms-access-key-id | SMS_ACCESS_KEY_ID | Alibaba Cloud SMS access key id | +| -K | --sms-access-key-secret | SMS_ACCESS_KEY_SECRET | AliCloud SMS-access-secret-key | +| -S | --sms-sign-name | SMS_SIGN_NAME | Signature | +| -C | --sms-template-code | SMS_TEMPLATE_CODE | Template code | +| -T | --sms-template-param | SMS_TEMPLATE_PARAM | JSON template for template parameters | +| -B | --sms-phone-numbers | SMS_PHONE_NUMBERS | A comma-separated list of phone numbers, e.g. `"189xxxxxxxx,132xxxxxxxx"` | +| -L | --sms-listen-addr | SMS_LISTEN_ADDR | Built-in SMS webhook listener address, default is `127.0.0.1:9100` | + +Suppose you start a TDengine database on host `tdengine` with HTTP API port `6041`, user `root1`, and password `pass5ord`. Execute the script. + +```bash +sudo . /TDinsight.sh -a http://tdengine:6041 -u root1 -p pass5ord +``` + +We provide a "-E" option to configure TDinsight to use the existing Notification Channel from the command line. Assuming your Grafana user and password is `admin:admin`, use the following command to get the `uid` of an existing notification channel. + +```bash +curl --no-progress-meter -u admin:admin http://localhost:3000/api/alert-notifications | jq +``` + +Use the `uid` value obtained above as `-E` input. + +```bash +sudo ./TDinsight.sh -a http://tdengine:6041 -u root1 -p pass5ord -E existing-notifier +``` + +If you want to use the [Alibaba Cloud SMS](https://www.aliyun.com/product/sms) service as a notification channel, you should enable it with the `-s` flag add the following parameters. + +- `-N`: Notification Channel name, default is `TDinsight Builtin SMS`. +- `-U`: Channel uid, default is lowercase of `name`, any other character is replaced with -, for the default `-N`, its uid is `tdinsight-builtin-sms`. +- `-I`: Alibaba Cloud SMS access key id. +- `-K`: Alibaba Cloud SMS access secret key. +- `-S`: Alibaba Cloud SMS signature. +- `-C`: Alibaba Cloud SMS template id. +- `-T`: Alibaba Cloud SMS template parameters, for JSON format template, example is as follows `'{"alarm_level":"%s", "time":"%s", "name":"%s", "content":"%s"}'`. There are four parameters: alarm level, time, name and alarm content. +- `-B`: a list of phone numbers, separated by a comma `,`. + +If you want to monitor multiple TDengine clusters, you need to set up numerous TDinsight dashboards. Setting up non-default TDinsight requires some changes: the `-n` `-i` `-t` options need to be changed to non-default names, and `-N` and `-L` should also be changed if using the built-in SMS alerting feature. + +```bash +sudo . /TDengine.sh -n TDengine-Env1 -a http://another:6041 -u root -p taosdata -i tdinsight-env1 -t 'TDinsight Env1' +# If using built-in SMS notifications +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 +``` + +Please note that the configuration data source, notification channel, and dashboard are not changeable on the front end. You should update the configuration again via this script or manually change the configuration file in the `/etc/grafana/provisioning` directory (this is the default directory for Grafana, use the `-P` option to change it as needed). + +Specifically, `-O` can be used to set the organization ID when you are using Grafana Cloud or another organization. `-G` specifies the Grafana plugin installation directory. The `-e` parameter sets the dashboard to be editable. + +## Set up TDinsight manually + +### Install the TDengine data source plugin + +Install the latest version of the TDengine Data Source plugin from GitHub. + +```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 +The 3.1.6 and earlier version plugins require the following setting in the configuration file `/etc/grafana/grafana.ini` to enable unsigned plugins. + +```ini +[plugins] +allow_loading_unsigned_plugins = tdengine-datasource +``` +::: + +### Start the Grafana service + +```bash +sudo systemctl start grafana-server +sudo systemctl enable grafana-server +``` + +### Logging into Grafana + +Open the default Grafana URL in a web browser: ``http://localhost:3000``. +The default username/password is `admin`. Grafana will require a password change after the first login. + +### Adding a TDengine Data Source + +Point to the **Configurations** -> **Data Sources** menu, and click the **Add data source** button. + +![TDengine Database TDinsight Add data source button](./assets/howto-add-datasource-button.webp) + +Search for and select **TDengine**. + +![TDengine Database TDinsight Add datasource](./assets/howto-add-datasource-tdengine.webp) + +Configure the TDengine datasource. + +![TDengine Database TDinsight Datasource Configuration](./assets/howto-add-datasource.webp) + +Save and test. It will report 'TDengine Data source is working' under normal circumstances. + +![TDengine Database TDinsight datasource test](./assets/howto-add-datasource-test.webp) + +### Importing dashboards + +Point to **+** / **Create** - **import** (or `/dashboard/import` url). + +![TDengine Database TDinsight Import Dashboard and Configuration](./assets/import_dashboard.webp) + +Type the dashboard ID `15167` in the **Import via grafana.com** location and **Load**. + +![TDengine Database TDinsight Import via grafana.com](./assets/import-dashboard-15167.webp) + +Once the import is complete, the full page view of TDinsight is shown below. + +![TDengine Database TDinsight show](./assets/TDinsight-full.webp) + +## TDinsight dashboard details + +The TDinsight dashboard is designed to provide the usage and status of TDengine-related resources [dnodes, mnodes, vnodes](https://www.taosdata.com/cn/documentation/architecture#cluster) or databases. + +Details of the metrics are as follows. + +### Cluster Status + +![TDengine Database TDinsight mnodes overview](./assets/TDinsight-1-cluster-status.webp) + +This section contains the current information and status of the cluster, the alert information is also here (from left to right, top to bottom). + +- **First EP**: the `firstEp` setting in the current TDengine cluster. +- **Version**: TDengine server version (master mnode). +- **Master Uptime**: The time elapsed since the current Master MNode was elected as Master. +- **Expire Time** - Enterprise version expiration time. +- **Used Measuring Points** - The number of measuring points used by the Enterprise Edition. +- **Databases** - The number of databases. +- **Connections** - The number of current connections. +- **DNodes/MNodes/VGroups/VNodes** - Total number of each resource and the number of survivors. +- **DNodes/MNodes/VGroups/VNodes Alive Percent**: The ratio of the number of alive/total for each resource, enabling the alert rule and triggering it when the resource liveness rate (the average percentage of healthy resources in 1 minute) is less than 100%. +- **Measuring Points Used**: The number of measuring points used to enable the alert rule (no data available in the community version, healthy by default). +- **Grants Expire Time**: the expiration time of the enterprise version of the enabled alert rule (no data available for the community version, healthy by default). +- **Error Rate**: Aggregate error rate (average number of errors per second) for alert-enabled clusters. +- **Variables**: `show variables` table display. + +### DNodes Status + +![TDengine Database TDinsight mnodes overview](./assets/TDinsight-2-dnodes.webp) + +- **DNodes Status**: simple table view of `show dnodes`. +- **DNodes Lifetime**: the time elapsed since the dnode was created. +- **DNodes Number**: the number of DNodes changes. +- **Offline Reason**: if any dnode status is offline, the reason for offline is shown as a pie chart. + +### MNode Overview + +![TDengine Database TDinsight mnodes overview](./assets/TDinsight-3-mnodes.webp) + +1. **MNodes Status**: a simple table view of `show mnodes`. +2. **MNodes Number**: similar to `DNodes Number`, the number of MNodes changes. + +### Request + +![TDengine Database TDinsight tdinsight requests](./assets/TDinsight-4-requests.webp) + +1. **Requests Rate(Inserts per Second)**: average number of inserts per second. +2. **Requests (Selects)**: number of query requests and change rate (count of second). +3. **Requests (HTTP)**: number of HTTP requests and request rate (count of second). + +### Database + +![TDengine Database TDinsight database](./assets/TDinsight-5-database.webp) + +Database usage, repeated for each value of the variable `$database` i.e. multiple rows per database. + +1. **STables**: number of super tables. +2. **Total Tables**: number of all tables. +3. **Sub Tables**: the number of all super table subtables. +4. **Tables**: graph of all normal table numbers over time. +5. **Tables Number Foreach VGroups**: The number of tables contained in each VGroups. + +### DNode Resource Usage + +![TDengine Database TDinsight dnode usage](./assets/TDinsight-6-dnode-usage.webp) + +Data node resource usage display with repeated multiple rows for the variable `$fqdn` i.e., each data node. Includes. + +1. **Uptime**: the time elapsed since the dnode was created. +2. **Has MNodes?**: whether the current dnode is a mnode. +3. **CPU Cores**: the number of CPU cores. +4. **VNodes Number**: the number of VNodes in the current dnode. +5. **VNodes Masters**: the number of vnodes in the master role. +6. **Current CPU Usage of taosd**: CPU usage rate of taosd processes. +7. **Current Memory Usage of taosd**: memory usage of taosd processes. +8. **Disk Used**: The total disk usage percentage of the taosd data directory. +9. **CPU Usage**: Process and system CPU usage. +10. **RAM Usage**: Time series view of RAM usage metrics. +11. **Disk Used**: Disks used at each level of multi-level storage (default is level0). +12. **Disk Increasing Rate per Minute**: Percentage increase or decrease in disk usage per minute. +13. **Disk IO**: Disk IO rate. +14. **Net IO**: Network IO, the aggregate network IO rate in addition to the local network. + +### Login History + +![TDengine Database TDinsight Login History](./assets/TDinsight-7-login-history.webp) + +Currently, only the number of logins per minute is reported. + +### Monitoring taosAdapter + +![TDengine Database TDinsight monitor taosadapter](./assets/TDinsight-8-taosadapter.webp) + +Support monitoring taosAdapter request statistics and status details. Includes. + +1. **http_request**: contains the total number of requests, the number of failed requests, and the number of requests being processed +2. **top 3 request endpoint**: data of the top 3 requests by endpoint group +3. **Memory Used**: taosAdapter memory usage +4. **latency_quantile(ms)**: quantile of (1, 2, 5, 9, 99) stages +5. **top 3 failed request endpoint**: data of the top 3 failed requests by endpoint grouping +6. **CPU Used**: taosAdapter CPU usage + +## Upgrade + +TDinsight installed via the `TDinsight.sh` script can be upgraded to the latest Grafana plugin and TDinsight Dashboard by re-running the script. + +In the case of a manual installation, follow the steps above to install the new Grafana plugin and Dashboard yourself. + +## Uninstall + +TDinsight installed via the `TDinsight.sh` script can be cleaned up using the command line `TDinsight.sh -R` to clean up the associated resources. + +To completely uninstall TDinsight during a manual installation, you need to clean up the following. + +1. the TDinsight Dashboard in Grafana. +2. the Data Source in Grafana. +3. remove the `tdengine-datasource` plugin from the plugin installation directory. + +## Integrated Docker Example + +```bash +git clone --depth 1 https://github.com/taosdata/grafanaplugin.git +cd grafanaplugin +``` + +Change as needed in the ``docker-compose.yml`` file to + +```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: +``` + +Replace the environment variables in `docker-compose.yml` or save the environment variables to the `.env` file, then start Grafana with `docker-compose up`. See [Docker Compose Reference](https://docs.docker.com/compose/) + +```bash +docker-compose up -d +``` + +Then the TDinsight was deployed via Provisioning. Go to http://localhost:3000/d/tdinsight/ to view the dashboard. + +[grafana]: https://grafana.com +[tdengine]: https://tdengine.com diff --git a/docs/en/14-reference/08-taos-shell.md b/docs/en/14-reference/08-taos-shell.md new file mode 100644 index 0000000000000000000000000000000000000000..9e077a3b11f2c373cd409f54401cbdb6350df6a8 --- /dev/null +++ b/docs/en/14-reference/08-taos-shell.md @@ -0,0 +1,86 @@ +--- +title: TDengine Command Line Interface (CLI) +sidebar_label: Command Line Interface +description: Instructions and tips for using the TDengine CLI +--- + +The TDengine command-line interface (hereafter referred to as `TDengine CLI`) is the simplest way for users to manipulate and interact with TDengine instances. + +## Installation + +If executed on the TDengine server-side, there is no need for additional installation steps to install TDengine CLI as it is already included and installed automatically. To run TDengine CLI in an environment where no TDengine server is running, the TDengine client installation package needs to be installed first. For details, please refer to [Install Client Driver](/reference/connector/#install-client-driver). + +## Execution + +To access the TDengine CLI, you can execute `taos` command-line utility from a Linux terminal or Windows terminal. + +```bash +taos +``` + +TDengine CLI will display a welcome message and version information if it successfully connected to the TDengine service. If it fails, TDengine CLI will print an error message. See [FAQ](/train-faq/faq) to solve the problem of terminal connection failure to the server. The TDengine CLI prompts as follows: + +```cmd +taos> +``` +After entering the TDengine CLI, you can execute various SQL commands, including inserts, queries, or administrative commands. + +## Execute SQL script file + +Run SQL command script file in the TDengine CLI via the `source` command. + +```sql +taos> source ; +``` + +## Adjust display width to show more characters + +Users can adjust the display width in TDengine CLI to show more characters with the following command: + +```sql +taos> SET MAX_BINARY_DISPLAY_WIDTH ; +``` + +If the displayed content is followed by `...` you can use this command to change the display width to display the full content. + +## Command Line Parameters + +You can change the behavior of TDengine CLI by specifying command-line parameters. The following parameters are commonly used. + +- -h, --host=HOST: FQDN of the server where the TDengine server is to be connected. Default is to connect to the local service +- -P, --port=PORT: Specify the port number to be used by the server. Default is `6030` +- -u, --user=USER: the user name to use when connecting. Default is `root` +- -p, --password=PASSWORD: the password to use when connecting to the server. Default is `taosdata` +- -?, --help: print out all command-line arguments + +And many more parameters. + +- -c, --config-dir: Specify the directory where configuration file exists. The default is `/etc/taos`, and the default name of the configuration file in this directory is `taos.cfg` +- -C, --dump-config: Print the configuration parameters of `taos.cfg` in the default directory or specified by -c +- -d, --database=DATABASE: Specify the database to use when connecting to the server +- -D, --directory=DIRECTORY: Import the SQL script file in the specified path +- -f, --file=FILE: Execute the SQL script file in non-interactive mode +- -k, --check=CHECK: Specify the table to be checked +- -l, --pktlen=PKTLEN: Test package size to be used for network testing +- -n, --netrole=NETROLE: test scope for network connection test, default is `startup`. The value can be `client`, `server`, `rpc`, `startup`, `sync`, `speed`, or `fqdn`. +- -r, --raw-time: output the timestamp format as unsigned 64-bits integer (uint64_t in C language) +- -s, --commands=COMMAND: execute SQL commands in non-interactive mode +- -S, --pkttype=PKTTYPE: Specify the packet type used for network testing. The default is TCP, can be specified as either TCP or UDP when `speed` is specified to `netrole` parameter +- -T, --thread=THREADNUM: The number of threads to import data in multi-threaded mode +- -s, --commands: Run TDengine CLI commands without entering the terminal +- -z, --timezone=TIMEZONE: Specify time zone. Default is the value of current configuration file +- -V, --version: Print out the current version number + +Example. + +```bash +taos -h h1.taos.com -s "use db; show tables;" +``` +## TDengine CLI tips + +- You can use the up and down keys to iterate the history of commands entered +- Change user password: use `alter user` command in TDengine CLI to change user's password. The default password is `taosdata`. +- use Ctrl+C to stop a query in progress +- Execute `RESET QUERY CACHE` to clear the local cache of the table schema +- Execute SQL statements in batches. You can store a series of shell commands (ending with ;, one line for each SQL command) in a script file and execute the command `source ` in the TDengine CLI to execute all SQL commands in that file automatically +- Enter `q` to exit TDengine CLI diff --git a/docs/en/14-reference/09-support-platform/_category_.yml b/docs/en/14-reference/09-support-platform/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..fabf2fef69fbde25266d18df92efffb52ed8a923 --- /dev/null +++ b/docs/en/14-reference/09-support-platform/_category_.yml @@ -0,0 +1 @@ +label: supported platforms diff --git a/docs/en/14-reference/09-support-platform/index.md b/docs/en/14-reference/09-support-platform/index.md new file mode 100644 index 0000000000000000000000000000000000000000..af15758225198a55765a20d232098165a1e3c7c4 --- /dev/null +++ b/docs/en/14-reference/09-support-platform/index.md @@ -0,0 +1,34 @@ +--- +title: List of supported platforms +description: "List of platforms supported by TDengine server, client, and connector" +--- + +## List of supported platforms for TDengine server + +| | **CentOS 7/8** | **Ubuntu 16/18/20** | **Other Linux** | +| ------------ | -------------- | ------------------- | --------------- | +| X64 | ● | ● | | +| MIPS64 | | | ● | +| ARM64 | | ○ | ○ | +| Alpha64 | | | ○ | + +Note: ● means officially tested and verified, ○ means unofficially tested and verified. + +## List of supported platforms for TDengine clients and connectors + +TDengine's connector can support a wide range of platforms, including X64/X86/ARM64/ARM32/MIPS/Alpha hardware platforms and Linux/Win64/Win32 development environments. + +The comparison matrix is as follows. + +| **CPU** | **X64 64bit** | | | **X86 32bit** | **ARM64** | **ARM32** | **MIPS** | **Alpha** | +| ----------- | ------------- | --------- | --------- | ------------- | --------- | --------- | --------- | --------- | +| **OS** | **Linux** | **Win64** | **Win32** | **Win32** | **Linux** | **Linux** | **Linux** | **Linux** | +| **C/C++** | ● | ● | ● | ○ | ● | ● | ● | ● | +| **JDBC** | ● | ● | ● | ○ | ● | ● | ● | ● | +| **Python** | ● | ● | ● | ○ | ● | ● | ● | -- | +| **Go** | ● | ● | ● | ○ | ● | ● | ○ | -- | +| **NodeJs** | ● | ● | ○ | ○ | ● | ● | ○ | -- | +| **C#** | ● | ● | ○ | ○ | ○ | ○ | ○ | -- | +| **RESTful** | ● | ● | ● | ● | ● | ● | ● | ● | + +Note: ● means the official test is verified, ○ means the unofficial test is verified, -- means not verified. diff --git a/docs/en/14-reference/11-docker/_category_.yml b/docs/en/14-reference/11-docker/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..f89ef7112c6d850726e5bcf20f1d1bd9f65d02fd --- /dev/null +++ b/docs/en/14-reference/11-docker/_category_.yml @@ -0,0 +1 @@ +label: TDengine Docker images \ No newline at end of file diff --git a/docs/en/14-reference/11-docker/index.md b/docs/en/14-reference/11-docker/index.md new file mode 100644 index 0000000000000000000000000000000000000000..b7e60ab3e7f04a6078950977a563382a3524ebaa --- /dev/null +++ b/docs/en/14-reference/11-docker/index.md @@ -0,0 +1,515 @@ +--- +title: Deploying TDengine with Docker +Description: "This chapter focuses on starting the TDengine service in a container and accessing it." +--- + +This chapter describes how to start the TDengine service in a container and access it. Users can control the behavior of the service in the container by using environment variables on the docker run command-line or in the docker-compose file. + +## Starting TDengine + +The TDengine image starts with the HTTP service activated by default, using the following command: + +```shell +docker run -d --name tdengine -p 6041:6041 tdengine/tdengine +``` + +The above command starts a container named "tdengine" and maps the HTTP service port 6041 to the host port 6041. You can verify that the HTTP service provided in this container is available using the following command. + +```shell +curl -u root:taosdata -d "show databases" localhost:6041/rest/sql +``` + +The TDengine client taos can be executed in this container to access TDengine using the following command. + +```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. + +taos> show databases; + name | created_time | ntables | vgroups | replica | quorum | days | keep | cache(MB) | blocks | minrows | maxrows | wallevel | fsync | comp | cachelast | precision | update | status | status 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) +``` + +The TDengine server running in the container uses the container's hostname to establish a connection. Using TDengine CLI or various connectors (such as JDBC-JNI) to access the TDengine inside the container from outside the container is more complicated. So the above is the simplest way to access the TDengine service in the container and is suitable for some simple scenarios. Please refer to the next section if you want to access the TDengine service in the container from outside the container using TDengine CLI or various connectors for complex scenarios. + +## Start TDengine on the host network + +```shell +docker run -d --name tdengine --network host tdengine/tdengine +``` + +The above command starts TDengine on the host network and uses the host's FQDN to establish a connection instead of the container's hostname. It is the equivalent of using `systemctl` to start TDengine on the host. If the TDengine client is already installed on the host, you can access it directly with the following command. + +```shell +$ taos + +Welcome to the TDengine shell from Linux, Client Version:2.4.0.0 +Copyright (c) 2020 by TAOS Data, Inc. + +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) +``` + +## Start TDengine with the specified hostname and port + +The `TAOS_FQDN` environment variable or the `fqdn` configuration item in `taos.cfg` allows TDengine to establish a connection at the specified hostname. This approach provides greater flexibility for deployment. + +```shell +docker run -d \ + --name tdengine \ + -e TAOS_FQDN=tdengine \ + -p 6030-6049:6030-6049 \ + -p 6030-6049:6030-6049/udp \ + tdengine/tdengine +``` + +The above command starts a TDengine service in the container, which listens to the hostname tdengine, and maps the container's port segment 6030 to 6049 to the host's port segment 6030 to 6049 (both TCP and UDP ports need to be mapped). If the port segment is already occupied on the host, you can modify the above command to specify a free port segment on the host. If `rpcForceTcp` is set to `1`, you can map only the TCP protocol. + +Next, ensure the hostname "tdengine" is resolvable in `/etc/hosts`. + +```shell +echo 127.0.0.1 tdengine |sudo tee -a /etc/hosts +``` + +Finally, the TDengine service can be accessed from the taos shell or any connector with "tdengine" as the server address. + +```shell +taos -h tdengine -P 6030 +``` + +If set `TAOS_FQDN` to the same hostname, the effect is the same as "Start TDengine on host network". + +## Start TDengine on the specified network + +You can also start TDengine on a specific network. + +1. First, create a docker network named `td-net` + + ```shell + docker network create td-net + ``` Create td-net + +2. Start TDengine + + Start the TDengine service on the `td-net` network with the following command: + + ```shell + docker run -d --name tdengine --network td-net \ + -e TAOS_FQDN=tdengine \ + tdengine/tdengine + ``` + +3. Start the TDengine client in another container on the same network + + ```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 + ``` + +## Launching a client application in a container + +If you want to start your application in a container, you need to add the corresponding dependencies on TDengine to the image as well, e.g. + +```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"] +``` + +Here is an example GO program: + +```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) + } +} +``` + +Here is the full 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"] +``` + +Now that we have `main.go`, `go.mod`, `go.sum`, `app.dockerfile`, we can build the application and start it on the `td-net` network. + +```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 +``` + +## Start the TDengine cluster with docker-compose + +1. The following docker-compose file starts a TDengine cluster with two replicas, two management nodes, two data nodes, and one arbitrator. + + ```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 +- The `VERSION` environment variable is used to set the tdengine image tag + - `TAOS_FIRST_EP` must be set on the newly created instance so that it can join the TDengine cluster; if there is a high availability requirement, `TAOS_SECOND_EP` needs to be used at the same time + - `TAOS_REPLICA` is used to set the default number of database replicas. Its value range is [1,3] + We recommend setting it with `TAOS_ARBITRATOR` to use arbitrator in a two-nodes environment. + + ::: + +2. Start the cluster + + ```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. Check the status of each node + + ```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. Show dnodes via TDengine CLI + + ```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 is enabled by default in the TDengine container. If you want to disable it, specify the environment variable `TAOS_DISABLE_ADAPTER=true` at startup + +2. At the same time, for flexible deployment, taosAdapter can be started in a separate container + + ```docker + services: + # ... + adapter: + image: tdengine/tdengine:$VERSION + command: taosadapter + ```` + + Suppose you want to deploy multiple taosAdapters to improve throughput and provide high availability. In that case, the recommended configuration method uses a reverse proxy such as Nginx to offer a unified access entry. For specific configuration methods, please refer to the official documentation of Nginx. Here is an example: + + ```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: + ``` + +## Deploy with docker swarm + +If you want to deploy a container-based TDengine cluster on multiple hosts, you can use docker swarm. First, to establish a docker swarm cluster on these hosts, please refer to the official docker documentation. + +The docker-compose file can refer to the previous section. Here is the command to start TDengine with docker swarm: + +```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 +``` + +Checking status: + +```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 +``` + +From the above output, you can see two dnodes, two taosAdapters, and one Nginx reverse proxy service. + +Next, we can reduce the number of taosAdapter services. + +```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/en/14-reference/12-config/_category_.yml b/docs/en/14-reference/12-config/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..94aa9438729449e6e0d13b20019514dbbbc3a384 --- /dev/null +++ b/docs/en/14-reference/12-config/_category_.yml @@ -0,0 +1 @@ +label: Configuration \ No newline at end of file diff --git a/docs/en/14-reference/12-config/index.md b/docs/en/14-reference/12-config/index.md new file mode 100644 index 0000000000000000000000000000000000000000..b6b535429b00796b5d2636c467153415a4281e59 --- /dev/null +++ b/docs/en/14-reference/12-config/index.md @@ -0,0 +1,1120 @@ +--- +sidebar_label: Configuration +title: Configuration Parameters +description: "Configuration parameters for client and server in TDengine" +--- + +In this chapter, all the configuration parameters on both server and client side are described thoroughly. + +## Configuration File on Server Side + +On the server side, the actual service of TDengine is provided by an executable `taosd` whose parameters can be configured in file `taos.cfg` to meet the requirements of different use cases. The default location of `taos.cfg` is `/etc/taos`, but can be changed by using `-c` parameter on the CLI of `taosd`. For example, the configuration file can be put under `/home/user` and used like below + +```bash +taosd -c /home/user +``` + +Parameter `-C` can be used on the CLI of `taosd` to show its configuration, like below: + +``` +taosd -C +``` + +## Configuration File on Client Side + +TDengine CLI `taos` is the tool for users to interact with TDengine. It can share same configuration file as `taosd` or use a separate configuration file. When launching `taos`, parameter `-c` can be used to specify the location where its configuration file is. For example `taos -c /home/cfg` means `/home/cfg/taos.cfg` will be used. If `-c` is not used, the default location of the configuration file is `/etc/taos`. For more details please use `taos --help` to get. + +From version 2.0.10.0 below commands can be used to show the configuration parameters of the client side. + +```bash +taos -C +``` + +```bash +taos --dump-config +``` + +# Configuration Parameters + +:::note +`taosd` needs to be restarted for the parameters changed in the configuration file to take effect. + +::: + +## Connection Parameters + +### firstEp + +| Attribute | Description | +| ------------- | ---------------------------------------------------------------------------------------------------- | +| Applicable | Server and Client | +| Meaning | The end point of the first dnode in the cluster to be connected to when `taosd` or `taos` is started | +| Default Value | localhost:6030 | + +### secondEp + +| Attribute | Description | +| ------------- | ---------------------------------------------------------------------------------------------------------------------- | +| Applicable | Server and Client | +| Meaning | The end point of the second dnode to be connected to if the firstEp is not available when `taosd` or `taos` is started | +| Default Value | None | + +### fqdn + +| Attribute | Description | +| ------------- | ------------------------------------------------------------------------ | +| Applicable | Server Only | +| Meaning | The FQDN of the host where `taosd` will be started. It can be IP address | +| Default Value | The first hostname configured for the host | +| Note | It should be within 96 bytes | + +### serverPort + +| Attribute | Description | +| ------------- | ------------------------------------------------------------------------------------------------------------------------------- | +| Applicable | Server Only | +| Meaning | The port for external access after `taosd` is started | +| Default Value | 6030 | +| Note | REST service is provided by `taosd` before 2.4.0.0 but by `taosAdapter` after 2.4.0.0, the default port of REST service is 6041 | + +:::note +TDengine uses 13 continuous ports, both TCP and UDP, starting with the port specified by `serverPort`. You should ensure, in your firewall rules, that these ports are kept open. Below table describes the ports used by TDengine in details. + +::: + +| Protocol | Default Port | Description | How to configure | +| :------- | :----------- | :----------------------------------------------- | :--------------------------------------------------------------------------------------------- | +| TCP | 6030 | Communication between client and server | serverPort | +| TCP | 6035 | Communication among server nodes in cluster | serverPort+5 | +| TCP | 6040 | Data syncup among server nodes in cluster | serverPort+10 | +| TCP | 6041 | REST connection between client and server | Prior to 2.4.0.0: serverPort+11; After 2.4.0.0 refer to [taosAdapter](/reference/taosadapter/) | +| TCP | 6042 | Service Port of Arbitrator | The parameter of Arbitrator | +| TCP | 6043 | Service Port of TaosKeeper | The parameter of TaosKeeper | +| TCP | 6044 | Data access port for StatsD | refer to [taosAdapter](/reference/taosadapter/) | +| UDP | 6045 | Data access for statsd | refer to [taosAdapter](/reference/taosadapter/) | +| TCP | 6060 | Port of Monitoring Service in Enterprise version | | +| UDP | 6030-6034 | Communication between client and server | serverPort | +| UDP | 6035-6039 | Communication among server nodes in cluster | serverPort | + +### maxShellConns + +| Attribute | Description | +| ------------- | ---------------------------------------------------- | +| Applicable | Server Only | +| Meaning | The maximum number of connections a dnode can accept | +| Value Range | 10-50000000 | +| Default Value | 5000 | + +### maxConnections + +| Attribute | Description | +| ------------- | ----------------------------------------------------------------------------- | +| Applicable | Server Only | +| Meaning | The maximum number of connections allowed by a database | +| Value Range | 1-100000 | +| Default Value | 5000 | +| Note | The maximum number of worker threads on the client side is maxConnections/100 | + +### rpcForceTcp + +| Attribute | Description | +| ------------- | ------------------------------------------------------------------- | +| Applicable | Server and Client | +| Meaning | TCP is used by force | +| Value Range | 0: disabled 1: enabled | +| Default Value | 0 | +| Note | It's suggested to configure to enable if network is not good enough | + +## Monitoring Parameters + +### monitor + +| Attribute | Description | +| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Applicable | Server Only | +| Meaning | The switch for monitoring inside server. The workload of the hosts, including CPU, memory, disk, network, TTP requests, are collected and stored in a system builtin database `LOG` | +| Value Range | 0: monitoring disabled, 1: monitoring enabled | +| Default Value | 1 | + +### monitorInterval + +| Attribute | Description | +| ------------- | ------------------------------------------ | +| Applicable | Server Only | +| Meaning | The interval of collecting system workload | +| Unit | second | +| Value Range | 1-600 | +| Default Value | 30 | + +### telemetryReporting + +| Attribute | Description | +| ------------- | ---------------------------------------------------------------------------- | +| Applicable | Server Only | +| Meaning | Switch for allowing TDengine to collect and report service usage information | +| Value Range | 0: Not allowed; 1: Allowed | +| Default Value | 1 | + +## Query Parameters + +### queryBufferSize + +| Attribute | Description | +| ------------- | ---------------------------------------------------------------------------------------- | +| Applicable | Server Only | +| Meaning | The total memory size reserved for all queries | +| Unit | MB | +| Default Value | None | +| Note | It can be estimated by "maximum number of concurrent queries" _ "number of tables" _ 170 | + +### ratioOfQueryCores + +| Attribute | Description | +| ------------- | ----------------------------------------------------------------------------------------------------- | +| Applicable | Server Only | +| Meaning | Maximum number of query threads | +| Default Value | 1 | +| Note | value range: float number between [0, 2] 0: only 1 query thread; >0: the times of the number of cores | + +### maxNumOfDistinctRes + +| Attribute | Description | +| ------------- | -------------------------------------------- | +| Applicable | Server Only | +| Meaning | The maximum number of distinct rows returned | +| Value Range | [100,000 - 100,000,000] | +| Default Value | 100,000 | +| Note | After version 2.3.0.0 | + +## Locale Parameters + +### timezone + +| Attribute | Description | +| ------------- | ------------------------------- | +| Applicable | Server and Client | +| Meaning | TimeZone | +| Default Value | TimeZone configured in the host | + +:::info +To handle the data insertion and data query from multiple timezones, Unix Timestamp is used and stored in TDengine. The timestamp generated from any timezones at same time is same in Unix timestamp. To make sure the time on client side can be converted to Unix timestamp correctly, the timezone must be set properly. + +On Linux system, TDengine clients automatically obtain timezone from the host. Alternatively, the timezone can be configured explicitly in configuration file `taos.cfg` like below. + +``` +timezone UTC-7 +timezone GMT-8 +timezone Asia/Shanghai +``` + +The above examples are all proper configuration for the timezone of UTC+8. On Windows system, however, `timezone Asia/Shanghai` is not supported, it must be set as `timezone UTC-8`. + +The setting for timezone impacts strings that are not in Unix timestamp format and keywords or functions related to date/time. For example: + +```sql +SELECT count(*) FROM table_name WHERE TS<'2019-04-11 12:01:08'; +``` + +If the timezone is UTC+8, the above SQL statement is equal to: + +```sql +SELECT count(*) FROM table_name WHERE TS<1554955268000; +``` + +If the timezone is UTC, it's equal to + +```sql +SELECT count(*) FROM table_name WHERE TS<1554984068000; +``` + +To avoid the problems of using time strings, Unix timestamp can be used directly. Furthermore, time strings with timezone can be used in SQL statements. For example "2013-04-12T15:52:01.123+08:00" in RFC3339 format or "2013-04-12T15:52:01.123+0800" in ISO-8601 format are not influenced by timezone setting when converted to Unix timestamp. + +::: + +### locale + +| Attribute | Description | +| ------------- | ------------------------- | +| Applicable | Server and Client | +| Meaning | Location code | +| Default Value | Locale configured in host | + +:::info +A specific type "nchar" is provided in TDengine to store non-ASCII characters such as Chinese, Japanese, and Korean. The characters to be stored in nchar type are firstly encoded in UCS4-LE before sending to server side. To store non-ASCII characters correctly, the encoding format of the client side needs to be set properly. + +The characters input on the client side are encoded using the default system encoding, which is UTF-8 on Linux, or GB18030 or GBK on some systems in Chinese, POSIX in docker, CP936 on Windows in Chinese. The encoding of the operating system in use must be set correctly so that the characters in nchar type can be converted to UCS4-LE. + +The locale definition standard on Linux is: \_., for example, in "zh_CN.UTF-8", "zh" means Chinese, "CN" means China mainland, "UTF-8" means charset. On Linux and Mac OSX, the charset can be set by locale in the system. On Windows system another configuration parameter `charset` must be used to configure charset because the locale used on Windows is not POSIX standard. Of course, `charset` can also be used on Linux to specify the charset. + +::: + +### charset + +| Attribute | Description | +| ------------- | ------------------------- | +| Applicable | Server and Client | +| Meaning | Character | +| Default Value | charset set in the system | + +:::info +On Linux, if `charset` is not set in `taos.cfg`, when `taos` is started, the charset is obtained from system locale. If obtaining charset from system locale fails, `taos` would fail to start. So on Linux system, if system locale is set properly, it's not necessary to set `charset` in `taos.cfg`. For example: + +``` +locale zh_CN.UTF-8 +``` + +On a Linux system, if the charset contained in `locale` is not consistent with that set by `charset`, the later setting in the configuration file takes precedence. + +```title="Effective charset is GBK" +locale zh_CN.UTF-8 +charset GBK +``` + +```title="Effective charset is UTF-8" +charset GBK +locale zh_CN.UTF-8 +``` + +On Windows system, it's not possible to obtain charset from system locale. If it's not set in configuration file `taos.cfg`, it would be default to CP936, same as set as below in `taos.cfg`. For example + +``` +charset CP936 +``` + +::: + +## Storage Parameters + +### dataDir + +| Attribute | Description | +| ------------- | ------------------------------------------- | +| Applicable | Server Only | +| Meaning | All data files are stored in this directory | +| Default Value | /var/lib/taos | + +### cache + +| Attribute | Description | +| ------------- | ----------------------------- | +| Applicable | Server Only | +| Meaning | The size of each memory block | +| Unit | MB | +| Default Value | 16 | + +### blocks + +| Attribute | Description | +| ------------- | -------------------------------------------------------------- | +| Applicable | Server Only | +| Meaning | The number of memory blocks of size `cache` used by each vnode | +| Default Value | 6 | + +### days + +| Attribute | Description | +| ------------- | ----------------------------------------------------- | +| Applicable | Server Only | +| Meaning | The time range of the data stored in single data file | +| Unit | day | +| Default Value | 10 | + +### keep + +| Attribute | Description | +| ------------- | -------------------------------------- | +| Applicable | Server Only | +| Meaning | The number of days for data to be kept | +| Unit | day | +| Default Value | 3650 | + +### minRows + +| Attribute | Description | +| ------------- | ------------------------------------------ | +| Applicable | Server Only | +| Meaning | minimum number of rows in single data file | +| Default Value | 100 | + +### maxRows + +| Attribute | Description | +| ------------- | ------------------------------------------ | +| Applicable | Server Only | +| Meaning | maximum number of rows in single data file | +| Default Value | 4096 | + +### walLevel + +| Attribute | Description | +| ------------- | ---------------------------------------------------------------------------------- | +| Applicable | Server Only | +| Meaning | WAL level | +| Value Range | 0: wal disabled
1: wal enabled without fsync
2: wal enabled with fsync | +| Default Value | 1 | + +### fsync + +| Attribute | Description | +| ------------- | --------------------------------------------------------------------------------------------------------------------- | +| Applicable | Server Only | +| Meaning | The waiting time for invoking fsync when walLevel is 2 | +| Unit | millisecond | +| Value Range | 0: no waiting time, fsync is performed immediately once WAL is written;
maximum value is 180000, i.e. 3 minutes | +| Default Value | 3000 | + +### update + +| Attribute | Description | +| ------------- | ------------------------------------------------------------------------------------------------------ | +| Applicable | Server Only | +| Meaning | If it's allowed to update existing data | +| Value Range | 0: not allowed
1: a row can only be updated as a whole
2: a part of columns can be updated | +| Default Value | 0 | +| Note | Not available from version 2.0.8.0 | + +### cacheLast + +| Attribute | Description | +| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Applicable | Server Only | +| Meaning | Whether to cache the latest rows of each sub table in memory | +| Value Range | 0: not cached
1: the last row of each sub table is cached
2: the last non-null value of each column is cached
3: identical to both 1 and 2 are set | +| Default Value | 0 | + +### minimalTmpDirGB + +| Attribute | Description | +| ------------- | ----------------------------------------------------------------------------------------------- | +| Applicable | Server and Client | +| Meaning | When the available disk space in tmpDir is below this threshold, writing to tmpDir is suspended | +| Unit | GB | +| Default Value | 1.0 | + +### minimalDataDirGB + +| Attribute | Description | +| ------------- | ------------------------------------------------------------------------------------------------ | +| Applicable | Server Only | +| Meaning | hen the available disk space in dataDir is below this threshold, writing to dataDir is suspended | +| Unit | GB | +| Default Value | 2.0 | + +### vnodeBak + +| Attribute | Description | +| ------------- | --------------------------------------------------------------------------- | +| Applicable | Server Only | +| Meaning | Whether to backup the corresponding vnode directory when a vnode is deleted | +| Value Range | 0: not backed up, 1: backup | +| Default Value | 1 | + +## Cluster Parameters + +### numOfMnodes + +| Attribute | Description | +| ------------- | ------------------------------ | +| Applicable | Server Only | +| Meaning | The number of management nodes | +| Default Value | 3 | + +### replica + +| Attribute | Description | +| ------------- | -------------------------- | +| Applicable | Server Only | +| Meaning | The number of replications | +| Value Range | 1-3 | +| Default Value | 1 | + +### quorum + +| Attribute | Description | +| ------------- | ------------------------------------------------------------------------------------------ | +| Applicable | Server Only | +| Meaning | The number of required confirmations for data replication in case of multiple replications | +| Value Range | 1,2 | +| Default Value | 1 | + +### role + +| Attribute | Description | +| ------------- | --------------------------------------------------------------- | +| Applicable | Server Only | +| Meaning | The role of the dnode | +| Value Range | 0: both mnode and vnode
1: mnode only
2: dnode only | +| Default Value | 0 | + +### balance + +| Attribute | Description | +| ------------- | ------------------------ | +| Applicable | Server Only | +| Meaning | Automatic load balancing | +| Value Range | 0: disabled, 1: enabled | +| Default Value | 1 | + +### balanceInterval + +| Attribute | Description | +| ------------- | ----------------------------------------------- | +| Applicable | Server Only | +| Meaning | The interval for checking load balance by mnode | +| Unit | second | +| Value Range | 1-30000 | +| Default Value | 300 | + +### arbitrator + +| Attribute | Description | +| ------------- | -------------------------------------------------- | +| Applicable | Server Only | +| Meaning | End point of arbitrator, format is same as firstEp | +| Default Value | None | + +## Time Parameters + +### precision + +| Attribute | Description | +| ------------- | ------------------------------------------------- | +| Applicable | Server only | +| Meaning | Time precision used for each database | +| Value Range | ms: millisecond; us: microsecond ; ns: nanosecond | +| Default Value | ms | + +### rpcTimer + +| Attribute | Description | +| ------------- | ------------------ | +| Applicable | Server and Client | +| Meaning | rpc retry interval | +| Unit | milliseconds | +| Value Range | 100-3000 | +| Default Value | 300 | + +### rpcMaxTime + +| Attribute | Description | +| ------------- | ---------------------------------- | +| Applicable | Server and Client | +| Meaning | maximum wait time for rpc response | +| Unit | second | +| Value Range | 100-7200 | +| Default Value | 600 | + +### statusInterval + +| Attribute | Description | +| ------------- | ----------------------------------------------- | +| Applicable | Server Only | +| Meaning | the interval of dnode reporting status to mnode | +| Unit | second | +| Value Range | 1-10 | +| Default Value | 1 | + +### shellActivityTimer + +| Attribute | Description | +| ------------- | ------------------------------------------------------ | +| Applicable | Server and Client | +| Meaning | The interval for taos shell to send heartbeat to mnode | +| Unit | second | +| Value Range | 1-120 | +| Default Value | 3 | + +### tableMetaKeepTimer + +| Attribute | Description | +| ------------- | -------------------------------------------------------------------------------------------------- | +| Applicable | Server Only | +| Meaning | The expiration time for metadata in cache, once it's reached the client would refresh the metadata | +| Unit | second | +| Value Range | 1-8640000 | +| Default Value | 7200 | + +### maxTmrCtrl + +| Attribute | Description | +| ------------- | ------------------------ | +| Applicable | Server and Client | +| Meaning | Maximum number of timers | +| Unit | None | +| Value Range | 8-2048 | +| Default Value | 512 | + +### offlineThreshold + +| Attribute | Description | +| ------------- | ----------------------------------------------------------------------------------------------------------------------------- | +| Applicable | Server Only | +| Meaning | The expiration time for dnode online status, once it's reached before receiving status from a node, the dnode becomes offline | +| Unit | second | +| Value Range | 5-7200000 | +| Default Value | 86400\*10 (i.e. 10 days) | + +## Performance Optimization Parameters + +### numOfThreadsPerCore + +| Attribute | Description | +| ------------- | ------------------------------------------- | +| Applicable | Server and Client | +| Meaning | The number of consumer threads per CPU core | +| Default Value | 1.0 | + +### ratioOfQueryThreads + +| Attribute | Description | +| ------------- | --------------------------------------------------------------------------------------------- | +| Applicable | Server Only | +| Meaning | Maximum number of query threads | +| Value Range | 0: Only one query thread
1: Same as number of CPU cores
2: two times of CPU cores | +| Default Value | 1 | +| Note | This value can be a float number, 0.5 means half of the CPU cores | + +### maxVgroupsPerDb + +| Attribute | Description | +| ------------- | ------------------------------------ | +| Applicable | Server Only | +| Meaning | Maximum number of vnodes for each DB | +| Value Range | 0-8192 | +| Default Value | | + +### maxTablesPerVnode + +| Attribute | Description | +| ------------- | -------------------------------------- | +| Applicable | Server Only | +| Meaning | Maximum number of tables in each vnode | +| Default Value | 1000000 | + +### minTablesPerVnode + +| Attribute | Description | +| ------------- | -------------------------------------- | +| Applicable | Server Only | +| Meaning | Minimum number of tables in each vnode | +| Default Value | 1000 | + +### tableIncStepPerVnode + +| Attribute | Description | +| ------------- | ------------------------------------------------------------------------------------------- | +| Applicable | Server Only | +| Meaning | When minTablesPerVnode is reached, the number of tables are allocated for a vnode each time | +| Default Value | 1000 | + +### maxNumOfOrderedRes + +| Attribute | Description | +| ------------- | ------------------------------------------- | +| Applicable | Server and Client | +| Meaning | Maximum number of rows ordered for a STable | +| Default Value | 100,000 | + +### mnodeEqualVnodeNum + +| Attribute | Description | +| ------------- | ----------------------------------------------------------------------------------------------- | +| Applicable | Server Only | +| Meaning | The number of vnodes whose system resources consumption are considered as equal to single mnode | +| Default Value | 4 | + +### numOfCommitThreads + +| Attribute | Description | +| ------------- | ----------------------------------------- | +| Applicable | Server Only | +| Meaning | Maximum of threads for committing to disk | +| Default Value | | + +## Compression Parameters + +### comp + +| Attribute | Description | +| ------------- | ------------------------------------------------------------------- | +| Applicable | Server Only | +| Meaning | Whether data is compressed | +| Value Range | 0: uncompressed, 1: One phase compression, 2: Two phase compression | +| Default Value | 2 | + +### tsdbMetaCompactRatio + +| Attribute | Description | +| ------------- | ------------------------------------------------------------------------------------------- | +| Meaning | The threshold for percentage of redundant in meta file to trigger compression for meta file | +| Value Range | 0: no compression forever, [1-100]: The threshold percentage | +| Default Value | 0 | + +### compressMsgSize + +| Attribute | Description | +| ------------- | -------------------------------------------------------------------------------- | +| Applicable | Server Only | +| Meaning | The threshold for message size to compress the message.. | +| Unit | bytes | +| Value Range | 0: already compress; >0: compress when message exceeds it; -1: always uncompress | +| Default Value | -1 | + +### compressColData + +| Attribute | Description | +| ------------- | ------------------------------------------------------------------------------------------------------------------- | +| Applicable | Server Only | +| Meaning | The threshold for size of column data to trigger compression for the query result | +| Unit | bytes | +| Value Range | 0: always compress; >0: only compress when the size of any column data exceeds the threshold; -1: always uncompress | +| Default Value | -1 | +| Note | available from version 2.3.0.0 | + +### lossyColumns + +| Attribute | Description | +| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| Applicable | Server Only | +| Meaning | The floating number types for lossy compression | +| Value Range | "": lossy compression is disabled
float: only for float
double: only for double
float \| double: for both float and double | +| Default Value | "" , i.e. disabled | + +### fPrecision + +| Attribute | Description | +| ------------- | ----------------------------------------------------------- | +| Applicable | Server Only | +| Meaning | Compression precision for float type | +| Value Range | 0.1 ~ 0.00000001 | +| Default Value | 0.00000001 | +| Note | The fractional part lower than this value will be discarded | + +### dPrecision + +| Attribute | Description | +| ------------- | ----------------------------------------------------------- | +| Applicable | Server Only | +| Meaning | Compression precision for double type | +| Value Range | 0.1 ~ 0.0000000000000001 | +| Default Value | 0.0000000000000001 | +| Note | The fractional part lower than this value will be discarded | + +## Continuous Query Parameters + +### stream + +| Attribute | Description | +| ------------- | ---------------------------------- | +| Applicable | Server Only | +| Meaning | Whether to enable continuous query | +| Value Range | 0: disabled
1: enabled | +| Default Value | 1 | + +### minSlidingTime + +| Attribute | Description | +| ------------- | -------------------------------------------------------- | +| Applicable | Server Only | +| Meaning | Minimum sliding time of time window | +| Unit | millisecond or microsecond , depending on time precision | +| Value Range | 10-1000000 | +| Default Value | 10 | + +### minIntervalTime + +| Attribute | Description | +| ------------- | --------------------------- | +| Applicable | Server Only | +| Meaning | Minimum size of time window | +| Unit | millisecond | +| Value Range | 1-1000000 | +| Default Value | 10 | + +### maxStreamCompDelay + +| Attribute | Description | +| ------------- | ------------------------------------------------ | +| Applicable | Server Only | +| Meaning | Maximum delay before starting a continuous query | +| Unit | millisecond | +| Value Range | 10-1000000000 | +| Default Value | 20000 | + +### maxFirstStreamCompDelay + +| Attribute | Description | +| ------------- | -------------------------------------------------------------------- | +| Applicable | Server Only | +| Meaning | Maximum delay time before starting a continuous query the first time | +| Unit | millisecond | +| Value Range | 10-1000000000 | +| Default Value | 10000 | + +### retryStreamCompDelay + +| Attribute | Description | +| ------------- | --------------------------------------------- | +| Applicable | Server Only | +| Meaning | Delay time before retrying a continuous query | +| Unit | millisecond | +| Value Range | 10-1000000000 | +| Default Value | 10 | + +### streamCompDelayRatio + +| Attribute | Description | +| ------------- | ------------------------------------------------------------------------ | +| Applicable | Server Only | +| Meaning | The delay ratio, with time window size as the base, for continuous query | +| Value Range | 0.1-0.9 | +| Default Value | 0.1 | + +:::info +To prevent system resource from being exhausted by multiple concurrent streams, a random delay is applied on each stream automatically. `maxFirstStreamCompDelay` is the maximum delay time before a continuous query is started the first time. `streamCompDelayRatio` is the ratio for calculating delay time, with the size of the time window as base. `maxStreamCompDelay` is the maximum delay time. The actual delay time is a random time not bigger than `maxStreamCompDelay`. If a continuous query fails, `retryStreamComDelay` is the delay time before retrying it, also not bigger than `maxStreamCompDelay`. + +::: + +## HTTP Parameters + +:::note +HTTP service was provided by `taosd` prior to version 2.4.0.0 and is provided by `taosAdapter` after version 2.4.0.0. +The parameters described in this section are only application in versions prior to 2.4.0.0. If you are using any version from 2.4.0.0, please refer to [taosAdapter](/reference/taosadapter/). + +::: + +### http + +| Attribute | Description | +| ------------- | ------------------------------ | +| Applicable | Server Only | +| Meaning | Whether to enable http service | +| Value Range | 0: disabled, 1: enabled | +| Default Value | 1 | + +### httpEnableRecordSql + +| Attribute | Description | +| ------------- | ------------------------------------------------------------------------- | +| Applicable | Server Only | +| Meaning | Whether to record the SQL invocation through REST interface | +| Default Value | 0: false; 1: true | +| Note | The resulting files, i.e. httpnote.0/httpnote.1, are located under logDir | + +### httpMaxThreads + +| Attribute | Description | +| ------------- | -------------------------------------------- | +| Applicable | Server Only | +| Meaning | The number of threads for RESTFul interface. | +| Default Value | 2 | + +### restfulRowLimit + +| Attribute | Description | +| ------------- | ------------------------------------------------------------ | +| Applicable | Server Only | +| Meaning | Maximum number of rows returned each time by REST interface. | +| Default Value | 10240 | +| Note | Maximum value is 10,000,000 | + +### httpDBNameMandatory + +| Attribute | Description | +| ------------- | ---------------------------------------- | +| Applicable | Server Only | +| Meaning | Whether database name is required in URL | +| Value Range | 0:not required, 1: required | +| Default Value | 0 | +| Note | From version 2.3.0.0 | + +## Log Parameters + +### logDir + +| Attribute | Description | +| ------------- | ----------------------------------- | +| Applicable | Server and Client | +| Meaning | The directory for writing log files | +| Default Value | /var/log/taos | + +### minimalLogDirGB + +| Attribute | Description | +| ------------- | -------------------------------------------------------------------------------------------------- | +| Applicable | Server and Client | +| Meaning | When the available disk space in logDir is below this threshold, writing to log files is suspended | +| Unit | GB | +| Default Value | 1.0 | + +### numOfLogLines + +| Attribute | Description | +| ------------- | ------------------------------------------ | +| Applicable | Server and Client | +| Meaning | Maximum number of lines in single log file | +| Default Value | 10,000,000 | + +### asyncLog + +| Attribute | Description | +| ------------- | ---------------------------- | +| Applicable | Server and Client | +| Meaning | The mode of writing log file | +| Value Range | 0: sync way; 1: async way | +| Default Value | 1 | + +### logKeepDays + +| Attribute | Description | +| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| Applicable | Server and Client | +| Meaning | The number of days for log files to be kept | +| Unit | day | +| Default Value | 0 | +| Note | When it's bigger than 0, the log file would be renamed to "taosdlog.xxx" in which "xxx" is the timestamp when the file is changed last time | + +### debugFlag + +| Attribute | Description | +| ------------- | --------------------------------------------------------- | +| Applicable | Server and Client | +| Meaning | Log level | +| Value Range | 131: INFO/WARNING/ERROR; 135: plus DEBUG; 143: plus TRACE | +| Default Value | 131 or 135, depending on the module | + +### mDebugFlag + +| Attribute | Description | +| ------------- | ------------------ | +| Applicable | Server Only | +| Meaning | Log level of mnode | +| Value Range | same as debugFlag | +| Default Value | 135 | + +### dDebugFlag + +| Attribute | Description | +| ------------- | ------------------ | +| Applicable | Server and Client | +| Meaning | Log level of dnode | +| Value Range | same as debugFlag | +| Default Value | 135 | + +### sDebugFlag + +| Attribute | Description | +| ------------- | ------------------------ | +| Applicable | Server and Client | +| Meaning | Log level of sync module | +| Value Range | same as debugFlag | +| Default Value | 135 | + +### wDebugFlag + +| Attribute | Description | +| ------------- | ----------------------- | +| Applicable | Server and Client | +| Meaning | Log level of WAL module | +| Value Range | same as debugFlag | +| Default Value | 135 | + +### sdbDebugFlag + +| Attribute | Description | +| ------------- | ---------------------- | +| Applicable | Server and Client | +| Meaning | logLevel of sdb module | +| Value Range | same as debugFlag | +| Default Value | 135 | + +### rpcDebugFlag + +| Attribute | Description | +| ------------- | ----------------------- | +| Applicable | Server and Client | +| Meaning | Log level of rpc module | +| Value Range | Same as debugFlag | +| Default Value | | + +### tmrDebugFlag + +| Attribute | Description | +| ------------- | ------------------------- | +| Applicable | Server and Client | +| Meaning | Log level of timer module | +| Value Range | Same as debugFlag | +| Default Value | | + +### cDebugFlag + +| Attribute | Description | +| ------------- | ------------------- | +| Applicable | Client Only | +| Meaning | Log level of Client | +| Value Range | Same as debugFlag | +| Default Value | | + +### jniDebugFlag + +| Attribute | Description | +| ------------- | ----------------------- | +| Applicable | Client Only | +| Meaning | Log level of jni module | +| Value Range | Same as debugFlag | +| Default Value | | + +### odbcDebugFlag + +| Attribute | Description | +| ------------- | ------------------------ | +| Applicable | Client Only | +| Meaning | Log level of odbc module | +| Value Range | Same as debugFlag | +| Default Value | | + +### uDebugFlag + +| Attribute | Description | +| ------------- | -------------------------- | +| Applicable | Server and Client | +| Meaning | Log level of common module | +| Value Range | Same as debugFlag | +| Default Value | | + +### httpDebugFlag + +| Attribute | Description | +| ------------- | ------------------------------------------- | +| Applicable | Server Only | +| Meaning | Log level of http module (prior to 2.4.0.0) | +| Value Range | Same as debugFlag | +| Default Value | | + +### mqttDebugFlag + +| Attribute | Description | +| ------------- | ------------------------ | +| Applicable | Server Only | +| Meaning | Log level of mqtt module | +| Value Range | Same as debugFlag | +| Default Value | | + +### monitorDebugFlag + +| Attribute | Description | +| ------------- | ------------------------------ | +| Applicable | Server Only | +| Meaning | Log level of monitoring module | +| Value Range | Same as debugFlag | +| Default Value | | + +### qDebugFlag + +| Attribute | Description | +| ------------- | ------------------------- | +| Applicable | Server and Client | +| Meaning | Log level of query module | +| Value Range | Same as debugFlag | +| Default Value | | + +### vDebugFlag + +| Attribute | Description | +| ------------- | ------------------ | +| Applicable | Server and Client | +| Meaning | Log level of vnode | +| Value Range | Same as debugFlag | +| Default Value | | + +### tsdbDebugFlag + +| Attribute | Description | +| ------------- | ------------------------ | +| Applicable | Server Only | +| Meaning | Log level of TSDB module | +| Value Range | Same as debugFlag | +| Default Value | | + +### cqDebugFlag + +| Attribute | Description | +| ------------- | ------------------------------------ | +| Applicable | Server and Client | +| Meaning | Log level of continuous query module | +| Value Range | Same as debugFlag | +| Default Value | | + +## Client Only + +### maxSQLLength + +| Attribute | Description | +| ------------- | -------------------------------------- | +| Applicable | Client Only | +| Meaning | Maximum length of single SQL statement | +| Unit | bytes | +| Value Range | 65480-1048576 | +| Default Value | 1048576 | + +### tscEnableRecordSql + +| Attribute | Description | +| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| Meaning | Whether to record SQL statements in file | +| Value Range | 0: false, 1: true | +| Default Value | 0 | +| Note | The generated files are named as "tscnote-xxxx.0/tscnote-xxx.1" in which "xxxx" is the pid of the client, and located at same place as client log | + +### maxBinaryDisplayWidth + +| Attribute | Description | +| ------------- | --------------------------------------------------------------------------------------------------- | +| Meaning | Maximum display width of binary and nchar in taos shell. Anything beyond this limit would be hidden | +| Value Range | 5 - | +| Default Value | 30 | + +:::info +If the length of value exceeds `maxBinaryDisplayWidth`, then the actual display width is max(column name, maxBinaryDisplayLength); otherwise the actual display width is max(length of column name, length of column value). This parameter can also be changed dynamically using `set max_binary_display_width ` in TDengine CLI `taos`. + +::: + +### maxWildCardsLength + +| Attribute | Description | +| ------------- | ----------------------------------------------------- | +| Meaning | The maximum length for wildcard string used with LIKE | +| Unit | bytes | +| Value Range | 0-16384 | +| Default Value | 100 | +| Note | From version 2.1.6.1 | + +### clientMerge + +| Attribute | Description | +| ------------- | --------------------------------------------------- | +| Meaning | Whether to filter out duplicate data on client side | +| Value Range | 0: false; 1: true | +| Default Value | 0 | +| Note | From version 2.3.0.0 | + +### maxRegexStringLen + +| Attribute | Description | +| ------------- | ------------------------------------ | +| Meaning | Maximum length of regular expression | +| Value Range | [128, 16384] | +| Default Value | 128 | +| Note | From version 2.3.0.0 | + +## Other Parameters + +### enableCoreFile + +| Attribute | Description | +| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Applicable | Server and Client | +| Meaning | Whether to generate core file when server crashes | +| Value Range | 0: false, 1: true | +| Default Value | 1 | +| Note | The core file is generated under root directory `systemctl start taosd` is used to start, or under the working directory if `taosd` is started directly on Linux Shell. | diff --git a/docs/en/14-reference/12-directory.md b/docs/en/14-reference/12-directory.md new file mode 100644 index 0000000000000000000000000000000000000000..304e3bcb434ee9a6ba338577a4d1ba546b548e3f --- /dev/null +++ b/docs/en/14-reference/12-directory.md @@ -0,0 +1,40 @@ +--- +title: File directory structure +description: "TDengine installation directory description" +--- + +After TDengine is installed, the following directories or files will be created in the system by default. + +| directory/file | description | +| ------------------------- | -------------------------------------------------------------------- | +| /usr/local/taos/bin | The TDengine executable directory. The executable files are soft-linked to the /usr/bin directory. | +| /usr/local/taos/driver | The TDengine dynamic link library directory. It is soft-linked to the /usr/lib directory. | +| /usr/local/taos/examples | The TDengine various language application examples directory. | +| /usr/local/taos/include | The header files for TDengine's external C interface. | +| /etc/taos/taos.cfg | TDengine default [configuration file] | +| /var/lib/taos | TDengine's default data file directory. The location can be changed via [configuration file]. | +| /var/log/taos | TDengine default log file directory. The location can be changed via [configure file]. | + +## Executable files + +All executable files of TDengine are in the _/usr/local/taos/bin_ directory by default. These include. + +- _taosd_: TDengine server-side executable files +- _taos_: TDengine CLI executable +- _taosdump_: data import and export tool +- _taosBenchmark_: TDengine testing tool +- _remove.sh_: script to uninstall TDengine, please execute it carefully, link to the **rmtaos** command in the /usr/bin directory. Will remove the TDengine installation directory `/usr/local/taos`, but will keep `/etc/taos`, `/var/lib/taos`, `/var/log/taos` +- _taosadapter_: server-side executable that provides RESTful services and accepts writing requests from a variety of other softwares +- _tarbitrator_: provides arbitration for two-node cluster deployments +- _run_taosd_and_taosadapter.sh_: script to start both taosd and taosAdapter +- _TDinsight.sh_: script to download TDinsight and install it +- _set_core.sh_: script for setting up the system to generate core dump files for easy debugging +- _taosd-dump-cfg.gdb_: script to facilitate debugging of taosd's gdb execution. + +:::note +taosdump after version 2.4.0.0 require taosTools as a standalone installation. A new version of taosBenchmark is include in taosTools too. +::: + +:::tip +You can configure different data directories and log directories by modifying the system configuration file `taos.cfg`. +::: diff --git a/docs/en/14-reference/13-schemaless/13-schemaless.md b/docs/en/14-reference/13-schemaless/13-schemaless.md new file mode 100644 index 0000000000000000000000000000000000000000..acbbb1cd3c5a7c50e226644f2de9e0e77274c6dd --- /dev/null +++ b/docs/en/14-reference/13-schemaless/13-schemaless.md @@ -0,0 +1,159 @@ +--- +title: Schemaless Writing +description: "The Schemaless write method eliminates the need to create super tables/sub tables in advance and automatically creates the storage structure corresponding to the data, as it is written to the interface." +--- + +In IoT applications, data is collected for many purposes such as intelligent control, business analysis, device monitoring and so on. Due to changes in business or functional requirements or changes in device hardware, the application logic and even the data collected may change. To provide the flexibility needed in such cases and in a rapidly changing IoT landscape, TDengine starting from version 2.2.0.0, provides a series of interfaces for the schemaless writing method. These interfaces eliminate the need to create super tables and subtables in advance by automatically creating the storage structure corresponding to the data as the data is written to the interface. When necessary, schemaless writing will automatically add the required columns to ensure that the data written by the user is stored correctly. + +The schemaless writing method creates super tables and their corresponding subtables. These are completely indistinguishable from the super tables and subtables created directly via SQL. You can write data directly to them via SQL statements. Note that the names of tables created by schemaless writing are based on fixed mapping rules for tag values, so they are not explicitly ideographic and they lack readability. + +## Schemaless Writing Line Protocol + +TDengine's schemaless writing line protocol supports InfluxDB's Line Protocol, OpenTSDB's telnet line protocol, and OpenTSDB's JSON format protocol. However, when using these three protocols, you need to specify in the API the standard of the parsing protocol to be used for the input content. + +For the standard writing protocols of InfluxDB and OpenTSDB, please refer to the documentation of each protocol. The following is a description of TDengine's extended protocol, based on InfluxDB's line protocol first. They allow users to control the (super table) schema more granularly. + +With the following formatting conventions, schemaless writing uses a single string to express a data row (multiple rows can be passed into the writing API at once to enable bulk writing). + +```json +measurement,tag_set field_set timestamp +``` + +where : + +- measurement will be used as the data table name. It will be separated from tag_set by a comma. +- tag_set will be used as tag data in the format `=,=`, i.e. multiple tags' data can be separated by a comma. It is separated from field_set by space. +- field_set will be used as normal column data in the format of `=,=`, again using a comma to separate multiple normal columns of data. It is separated from the timestamp by a space. +- The timestamp is the primary key corresponding to the data in this row. + +All data in tag_set is automatically converted to the NCHAR data type and does not require double quotes ("). + +In the schemaless writing data line protocol, each data item in the field_set needs to be described with its data type. Let's explain in detail: + +- If there are English double quotes on both sides, it indicates the BINARY(32) type. For example, `"abc"`. +- If there are double quotes on both sides and an L prefix, it means NCHAR(32) type. For example, `L"error message"`. +- Spaces, equal signs (=), commas (,), and double quotes (") need to be escaped with a backslash (\\) in front. (All refer to the ASCII character) +- Numeric types will be distinguished from data types by the suffix. + +| **Serial number** | **Postfix** | **Mapping type** | **Size (bytes)** | +| -------- | -------- | ------------ | -------------- | +| 1 | none or f64 | double | 8 | +| 2 | f32 | float | 4 | +| 3 | i8 | TinyInt | 1 | +| 4 | i16 | SmallInt | 2 | +| 5 | i32 | Int | 4 | +| 6 | i64 or i | Bigint | 8 | + +- `t`, `T`, `true`, `True`, `TRUE`, `f`, `F`, `false`, and `False` will be handled directly as BOOL types. + +For example, the following data rows indicate that the t1 label is "3" (NCHAR), the t2 label is "4" (NCHAR), and the t3 label is "t3" to the super table named `st` labeled "t3" (NCHAR), write c1 column as 3 (BIGINT), c2 column as false (BOOL), c3 column is "passit" (BINARY), c4 column is 4 (DOUBLE), and the primary key timestamp is 1626006833639000000 in one row. + +```json +st,t1=3,t2=4,t3=t3 c1=3i64,c3="passit",c2=false,c4=4f64 1626006833639000000 +``` + +Note that if the wrong case is used when describing the data type suffix, or if the wrong data type is specified for the data, it may cause an error message and cause the data to fail to be written. + +## Main processing logic for schemaless writing + +Schemaless writes process row data according to the following principles. + +1. You can use the following rules to generate the subtable names: first, combine the measurement name and the key and value of the label into the next string: + +```json +"measurement,tag_key1=tag_value1,tag_key2=tag_value2" +``` + +Note that tag_key1, tag_key2 are not the original order of the tags entered by the user but the result of using the tag names in ascending order of the strings. Therefore, tag_key1 is not the first tag entered in the line protocol. +The string's MD5 hash value "md5_val" is calculated after the ranking is completed. The calculation result is then combined with the string to generate the table name: "t_md5_val". "t*" is a fixed prefix that every table generated by this mapping relationship has. + +2. If the super table obtained by parsing the line protocol does not exist, this super table is created. +If the subtable obtained by the parse line protocol does not exist, Schemaless creates the sub-table according to the subtable name determined in steps 1 or 2. +4. If the specified tag or regular column in the data row does not exist, the corresponding tag or regular column is added to the super table (only incremental). +5. If there are some tag columns or regular columns in the super table that are not specified to take values in a data row, then the values of these columns are set to NULL. +6. For BINARY or NCHAR columns, if the length of the value provided in a data row exceeds the column type limit, the maximum length of characters allowed to be stored in the column is automatically increased (only incremented and not decremented) to ensure complete preservation of the data. +7. If the specified data subtable already exists, and the specified tag column takes a value different from the saved value this time, the value in the latest data row overwrites the old tag column take value. +8. Errors encountered throughout the processing will interrupt the writing process and return an error code. + +:::tip +All processing logic of schemaless will still follow TDengine's underlying restrictions on data structures, such as the total length of each row of data cannot exceed 48k bytes. See [TAOS SQL Boundary Limits](/taos-sql/limit) for specific constraints in this area. +::: + +## Time resolution recognition + +Three specified modes are supported in the schemaless writing process, as follows: + +| **Serial** | **Value** | **Description** | +| -------- | ------------------- | ------------------------------- | +| 1 | SML_LINE_PROTOCOL | InfluxDB Line Protocol | +| 2 | SML_TELNET_PROTOCOL | OpenTSDB Text Line Protocol | +| 3 | SML_JSON_PROTOCOL | JSON protocol format | + +In the SML_LINE_PROTOCOL parsing mode, the user is required to specify the time resolution of the input timestamp. The available time resolutions are shown in the following table. + +| **Serial Number** | **Time Resolution Definition** | **Meaning** | +| -------- | --------------------------------- | -------------- | +| 1 | TSDB_SML_TIMESTAMP_NOT_CONFIGURED | Not defined (invalid) | +| 2 | TSDB_SML_TIMESTAMP_HOURS | hour | +| 3 | TSDB_SML_TIMESTAMP_MINUTES | MINUTES +| 4 | TSDB_SML_TIMESTAMP_SECONDS | SECONDS +| 5 | TSDB_SML_TIMESTAMP_MILLI_SECONDS | milliseconds +| 6 | TSDB_SML_TIMESTAMP_MICRO_SECONDS | microseconds +| 7 | TSDB_SML_TIMESTAMP_NANO_SECONDS | nanoseconds | + +In SML_TELNET_PROTOCOL and SML_JSON_PROTOCOL modes, the time precision is determined based on the length of the timestamp (in the same way as the OpenTSDB standard operation), and the user-specified time resolution is ignored at this point. + +## Data schema mapping rules + +This section describes how data for line protocols are mapped to data with a schema. The data measurement in each line protocol is mapped as follows: +- The tag name in tag_set is the name of the tag in the data schema +- The name in field_set is the column's name. + +The following data is used as an example to illustrate the mapping rules. + +```json +st,t1=3,t2=4,t3=t3 c1=3i64,c3="passit",c2=false,c4=4f64 1626006833639000000 +``` + +The row data mapping generates a super table: `st`, which contains three labels of type NCHAR: t1, t2, t3. Five data columns are ts (timestamp), c1 (bigint), c3 (binary), c2 (bool), c4 (bigint). The mapping becomes the following SQL statement. + +```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)) +``` + +## Data schema change handling + +This section describes the impact on the data schema for different line protocol data writing cases. + +When writing to an explicitly identified field type using the line protocol, subsequent changes to the field's type definition will result in an explicit data schema error, i.e., will trigger a write API report error. As shown below, the + +```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 +``` + +The data type mapping in the first row defines column c4 as DOUBLE, but the data in the second row is declared as BIGINT by the numeric suffix, which triggers a parsing error with schemaless writing. + +If the line protocol before the column declares the data column as BINARY, the subsequent one requires a longer binary length, which triggers a super table schema change. + +```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 +``` + +The first line of the line protocol parsing will declare column c5 is a BINARY(4) field. The second line data write will parse column c5 as a BINARY column. But in the second line, c5's width is 6 so you need to increase the width of the BINARY field to be able to accommodate the new string. + +```json +st,t1=3,t2=4,t3=t3 c1=3i64 1626006833639000000 +st,t1=3,t2=4,t3=t3 c1=3i64,c6="passit" 1626006833640000000 +``` + +The second line of data has an additional column c6 of type BINARY(6) compared to the first row. Then a column c6 of type BINARY(6) is automatically added at this point. + +## Write integrity + +TDengine provides idempotency guarantees for data writing, i.e., you can repeatedly call the API to write data with errors. However, it does not give atomicity guarantees for writing multiple rows of data. During the process of writing numerous rows of data in one batch, some data will be written successfully, and some data will fail. + +## Error code + +If it is an error in the data itself during the schemaless writing process, the application will get `TSDB_CODE_TSC_LINE_SYNTAX_ERROR` error message, which indicates that the error occurred in writing. The other error codes are consistent with the TDengine and can be obtained via the `taos_errstr()` to get the specific cause of the error. diff --git a/docs/en/14-reference/13-schemaless/_category_.yml b/docs/en/14-reference/13-schemaless/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..416b41f73cb3884421c911189a15e522493c70e7 --- /dev/null +++ b/docs/en/14-reference/13-schemaless/_category_.yml @@ -0,0 +1 @@ +label: Schemaless writing diff --git a/docs/en/14-reference/_category_.yml b/docs/en/14-reference/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..5f5466532be79153d42da0907df6336439593601 --- /dev/null +++ b/docs/en/14-reference/_category_.yml @@ -0,0 +1 @@ +label: Reference diff --git a/docs/en/14-reference/_collectd.mdx b/docs/en/14-reference/_collectd.mdx new file mode 100644 index 0000000000000000000000000000000000000000..ce88328098a181de48dcaa080ef45f228b20bf1c --- /dev/null +++ b/docs/en/14-reference/_collectd.mdx @@ -0,0 +1,84 @@ +### Configuring taosAdapter + +To configure taosAdapter to receive collectd data. + +- Enable the configuration item in the taosAdapter configuration file (default location is /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" +... +``` + +The default database name written by taosAdapter is `collectd`. You can also modify the taosAdapter configuration file dbs entry to specify a different name. user and password are the values configured by the actual TDengine. After changing the configuration file, you need to restart the taosAdapter. + +- You can also enable the taosAdapter to receive collectd data by using the taosAdapter command-line parameters or by setting environment variables. + +### Configure collectd +#collectd +collectd uses a plugin mechanism to write the collected monitoring data to different data storage software in various forms. tdengine supports both direct collection plugins and write_tsdb plugins. + +#### Configure the direct collection plugin + +Modify the relevant configuration items in the collectd configuration file (default location /etc/collectd/collectd.conf). + +```text +LoadPlugin network + + Server "" "" + +``` + +where fills in the server's domain name or IP address running taosAdapter. fills in the port that taosAdapter uses to receive collectd data (default is 6045). + +An example is as follows. + +```text +LoadPlugin network + +``` + +#### Configure write_tsdb plugin data + +Modify the relevant configuration items in the collectd configuration file (default location /etc/collectd/collectd.conf). + +```text +LoadPlugin write_tsdb + + + Host "" + Port "" + ... + + +``` + +Where is the domain name or IP address of the server running taosAdapter. Fill in the data that taosAdapter uses to receive the collectd write_tsdb plugin (default is 6047). + +```text +LoadPlugin write_tsdb + + + Host "127.0.0.1" + Port "6047" + HostTags "status=production" + StoreRates false + AlwaysAppendDS false + +``` + +Then restart collectd. + +``` +systemctl restart collectd +``` diff --git a/docs/en/14-reference/_icinga2.mdx b/docs/en/14-reference/_icinga2.mdx new file mode 100644 index 0000000000000000000000000000000000000000..0a2bf52c2796717e9fd7afcccc7cd8f75626fdd9 --- /dev/null +++ b/docs/en/14-reference/_icinga2.mdx @@ -0,0 +1,46 @@ + + +### Configuring taosAdapter + +To configure taosAdapter to receive icinga2 data. + +- Enable the configuration item in the taosAdapter configuration file (default location /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" +... +``` + +The default database name written by the taosAdapter is `icinga2`. You can also modify the taosAdapter configuration file dbs entry to specify a different name. user and password are the values configured by the actual TDengine. You need to restart the taosAdapter after modification. + +- You can also enable taosAdapter to receive icinga2 data by using the taosAdapter command-line parameters or setting environment variables. + +### Configure icinga3 + +- Enable opentsdb-writer for icinga2 (refer to the link https://icinga.com/docs/icinga-2/latest/doc/14-features/#opentsdb-writer) +- Modify the configuration file `/etc/icinga2/features-enabled/opentsdb.conf` by filling in as the domain name or IP address of the server running taosAdapter and as the corresponding port on which taosAdapter supports receiving icinga2 data (default is 6048) + +``` +object OpenTsdbWriter "opentsdb" { + host = "" + port = +} +``` + +Example file: + +``` +object OpenTsdbWriter "opentsdb" { + host = "127.0.0.1" + port = 6048 +} +``` + diff --git a/docs/en/14-reference/_prometheus.mdx b/docs/en/14-reference/_prometheus.mdx new file mode 100644 index 0000000000000000000000000000000000000000..0940e4adb20f008ac190c3ea105466236889fec8 --- /dev/null +++ b/docs/en/14-reference/_prometheus.mdx @@ -0,0 +1,31 @@ +Configuring Prometheus is done by editing the Prometheus configuration file prometheus.yml (default location `/etc/prometheus/prometheus.yml`). + +### Configuring third-party database addresses + +Point the `remote_read url` and `remote_write url` to the domain name or IP address of the server running the taosAdapter service, the REST service port (taosAdapter uses 6041 by default), and the name of the database you want to write to TDengine, and ensure that the corresponding URL form as follows. + +- remote_read url : `http://:/prometheus/v1/remote_read/` +- remote_write url : `http://:/prometheus/v1/remote_write/` + +### Configure Basic authentication + +- username: +- password: + +### Example configuration of remote_write and remote_read related sections in prometheus.yml file + +```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/en/14-reference/_statsd.mdx b/docs/en/14-reference/_statsd.mdx new file mode 100644 index 0000000000000000000000000000000000000000..d0721a16fb575ef22f04ad6cb416a31851d6cff5 --- /dev/null +++ b/docs/en/14-reference/_statsd.mdx @@ -0,0 +1,55 @@ +### Configuring taosAdapter + +To configure taosAdapter to receive StatsD data. + +- Enable the configuration item in the taosAdapter configuration file (default location /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 +... +``` + +The default database name written by taosAdapter is `statsd`. To specify a different name, you can also modify the taosAdapter configuration file db entry. user and password fill in the actual TDengine configuration values. After changing the configuration file, you need to restart the taosAdapter. + +- You can also enable taosAdapter to receive StatsD data by using the taosAdapter command-line parameters or setting environment variables. + +### Configuring StatsD + +To use StatsD, you need to download its [source code](https://github.com/statsd/statsd). Please refer to the example file `exampleConfig.js` in the root directory of the source download to modify the configuration file. In , please fill in the domain name or IP address of the server running taosAdapter, and , please fill in the port where taosAdapter receives StatsD data (default is 6044). + +``` +backends section add ". /backends/repeater" +Add { host:'', port: } to repeater section +``` + +Example configuration file. + +``` +{ +port: 8125 +, backends: [". /backends/repeater"] +, repeater: [{ host: '127.0.0.1', port: 6044}] +} +``` + +Start StatsD after adding the following (assuming the config file is modified to config.js) + +``` +node stats.js config.js & +``` diff --git a/docs/en/14-reference/_tcollector.mdx b/docs/en/14-reference/_tcollector.mdx new file mode 100644 index 0000000000000000000000000000000000000000..42b021410e3862c4fa328d8dae40dcac1456e929 --- /dev/null +++ b/docs/en/14-reference/_tcollector.mdx @@ -0,0 +1,81 @@ +### Configuring taosAdapter + +To configure taosAdapter to receive TCollector data. + +- Enable the configuration item in the taosAdapter configuration file (default location /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" +... +``` + +The taosAdapter writes to the database with the default name `tcollector`. You can also modify the taosAdapter configuration file dbs entry to specify a different name. Fill in the actual user and password for TDengine. After changing the configuration file, you need to restart the taosAdapter. + +- You can also enable taosAdapter to receive tcollector data by using the taosAdapter command-line parameters or setting environment variables. + +### Configuring TCollector + +To use TCollector, you need to download its [source code](https://github.com/OpenTSDB/tcollector). Its configuration items are in its source code. Note: TCollector differs significantly from version to version, so here is an example of the latest code for the current master branch (git commit: 37ae920). + +Modify the contents of the `collectors/etc/config.py` and `tcollector.py` files. Change the address of the OpenTSDB host to the domain name or IP address of the server where taosAdapter is deployed, and change the port to the port on which taosAdapter supports TCollector (default is 6049). + +Example of git diff output of source code changes. + +``` +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/en/14-reference/_telegraf.mdx b/docs/en/14-reference/_telegraf.mdx new file mode 100644 index 0000000000000000000000000000000000000000..e32fb256936a5f2c00bbb3f37529e895d260fc5c --- /dev/null +++ b/docs/en/14-reference/_telegraf.mdx @@ -0,0 +1,26 @@ + +In the Telegraf configuration file (default location `/etc/telegraf/telegraf.conf`) add an `outputs.http` section. + +``` +[[outputs.http]] + url = "http://:/influxdb/v1/write?db=" + ... + username = "" + password = "" + ... +``` + +Where please fill in the server's domain name or IP address running the taosAdapter service. please fill in the port of the REST service (default is 6041). and please fill in the actual configuration of the currently running TDengine. And please fill in the database name where you want to store Telegraf data in TDengine. + +An example is as follows. + +``` +[[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/en/14-reference/index.md b/docs/en/14-reference/index.md new file mode 100644 index 0000000000000000000000000000000000000000..f350eebfc1a1ca2feaedc18c4b4fa798742e31b4 --- /dev/null +++ b/docs/en/14-reference/index.md @@ -0,0 +1,12 @@ +--- +title: Reference +--- + +The reference guide is a detailed introduction to TDengine including various TDengine connectors in different languages, and the tools that come with TDengine. + +```mdx-code-block +import DocCardList from '@theme/DocCardList'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + + +``` diff --git a/docs/en/14-reference/taosAdapter-architecture.webp b/docs/en/14-reference/taosAdapter-architecture.webp new file mode 100644 index 0000000000000000000000000000000000000000..a4162b0a037c06d34191784716c51080b9f8a570 Binary files /dev/null and b/docs/en/14-reference/taosAdapter-architecture.webp differ diff --git a/docs/en/20-third-party/01-grafana.mdx b/docs/en/20-third-party/01-grafana.mdx new file mode 100644 index 0000000000000000000000000000000000000000..b51d5a8d904601802efec0db5847203b72fa2668 --- /dev/null +++ b/docs/en/20-third-party/01-grafana.mdx @@ -0,0 +1,148 @@ +--- +sidebar_label: Grafana +title: Grafana +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +TDengine can be quickly integrated with the open-source data visualization system [Grafana](https://www.grafana.com/) to build a data monitoring and alerting system. The whole process does not require any code development. And you can visualize the contents of the data tables in TDengine on a dashboard. + +You can learn more about using the TDengine plugin on [GitHub](https://github.com/taosdata/grafanaplugin/blob/master/README.md). + +## Prerequisites + +In order for Grafana to add the TDengine data source successfully, the following preparations are required: + +1. The TDengine cluster is deployed and functioning properly +2. taosAdapter is installed and running properly. Please refer to the taosAdapter manual for details. + +Record these values: + +- TDengine REST API url: `http://tdengine.local:6041`. +- TDengine cluster authorization, with user + password. + +## Installing Grafana + +TDengine currently supports Grafana versions 7.5 and above. Users can go to the Grafana official website to download the installation package and execute the installation according to the current operating system. The download address is as follows: . + +## Configuring Grafana + +### Install Grafana Plugin and Configure Data Source + + + + +Set the url and authorization environment variables by `export` or a [`.env`(dotenv) file](https://hexdocs.pm/dotenvy/dotenv-file-format.html): + +```sh +export TDENGINE_API=http://tdengine.local:6041 +# user + password +export TDENGINE_USER=user +export TDENGINE_PASSWORD=password + +# Other useful variables +# - If to install TDengine data source, default is true +export TDENGINE_DS_ENABLED=false +# - Data source name to be created, default is TDengine +export TDENGINE_DS_NAME=TDengine +# - Data source organization id, default is 1 +export GF_ORG_ID=1 +# - Data source is editable in admin ui or not, default is 0 (false) +export TDENGINE_EDITABLE=1 +``` + +Run `install.sh`: + +```sh +bash -c "$(curl -fsSL https://raw.githubusercontent.com/taosdata/grafanaplugin/master/install.sh)" +``` + +With this script, TDengine data source plugin and the Grafana data source will be installed and created automatically with Grafana provisioning configurations. Save the script and type `./install.sh --help` for the full usage of the script. + +And then, restart Grafana service and open Grafana in web-browser, usually . + + + + +Follow the installation steps in [Grafana](https://grafana.com/grafana/plugins/tdengine-datasource/?tab=installation) with the [``grafana-cli`` command-line tool](https://grafana.com/docs/grafana/latest/administration/cli/) for plugin installation. + +```bash +grafana-cli plugins install tdengine-datasource +# with sudo +sudo -u grafana grafana-cli plugins install tdengine-datasource +``` + +Alternatively, you can manually download the .zip file from [GitHub](https://github.com/taosdata/grafanaplugin/tags) or [Grafana](https://grafana.com/grafana/plugins/tdengine-datasource/?tab=installation) and unpack it into your grafana plugins directory. + +```bash +GF_VERSION=3.2.2 +# from GitHub +wget https://github.com/taosdata/grafanaplugin/releases/download/v$GF_VERSION/tdengine-datasource-$GF_VERSION.zip +# from Grafana +wget -O tdengine-datasource-$GF_VERSION.zip https://grafana.com/api/plugins/tdengine-datasource/versions/$GF_VERSION/download +``` + +Take CentOS 7.2 for example, extract the plugin package to /var/lib/grafana/plugins directory, and restart grafana. + +```bash +sudo unzip tdengine-datasource-$GF_VERSION.zip -d /var/lib/grafana/plugins/ +``` + +If Grafana is running in a Docker environment, the TDengine plugin can be automatically installed and set up using the following environment variable settings: + +```bash +GF_INSTALL_PLUGINS=tdengine-datasource +``` + +Now users can log in to the Grafana server (username/password: admin/admin) directly through the URL `http://localhost:3000` and add a datasource through `Configuration -> Data Sources` on the left side, as shown in the following figure. + +![TDengine Database TDinsight plugin add datasource 1](./grafana/add_datasource1.webp) + +Click `Add data source` to enter the Add data source page, and enter TDengine in the query box to add it, as shown in the following figure. + +![TDengine Database TDinsight plugin add datasource 2](./grafana/add_datasource2.webp) + +Enter the datasource configuration page, and follow the default prompts to modify the corresponding configuration. + +![TDengine Database TDinsight plugin add database 3](./grafana/add_datasource3.webp) + +- Host: IP address of the server where the components of the TDengine cluster provide REST service (offered by taosd before 2.4 and by taosAdapter since 2.4) and the port number of the TDengine REST service (6041), by default use `http://localhost:6041`. +- User: TDengine user name. +- Password: TDengine user password. + +Click `Save & Test` to test. You should see a success message if the test worked. + +![TDengine Database TDinsight plugin add database 4](./grafana/add_datasource4.webp) + + + + +### Create Dashboard + +Go back to the main interface to create a dashboard and click Add Query to enter the panel query page: + +![TDengine Database TDinsight plugin create dashboard 1](./grafana/create_dashboard1.webp) + +As shown above, select the `TDengine` data source in the `Query` and enter the corresponding SQL in the query box below for query. + +- INPUT SQL: enter the statement to be queried (the result set of the SQL statement should be two columns and multiple rows), for example: `select avg(mem_system) from log.dn where ts >= $from and ts < $to interval($interval)`, where, from, to and interval are built-in variables of the TDengine plugin, indicating the range and time interval of queries fetched from the Grafana plugin panel. In addition to the built-in variables, custom template variables are also supported. +- ALIAS BY: This allows you to set the current query alias. +- GENERATE SQL: Clicking this button will automatically replace the corresponding variables and generate the final executed statement. + +Follow the default prompt to query the average system memory usage for the specified interval on the server where the current TDengine deployment is located as follows. + +![TDengine Database TDinsight plugin create dashboard 2](./grafana/create_dashboard2.webp) + +> For more information on how to use Grafana to create the appropriate monitoring interface and for more details on using Grafana, refer to the official Grafana [documentation](https://grafana.com/docs/). + +### Importing the Dashboard + +You can install TDinsight dashboard in data source configuration page (like `http://localhost:3000/datasources/edit/1/dashboards`) as a monitoring visualization tool for TDengine cluster. The dashboard is published in Grafana as [Dashboard 15167 - TDinsight](https://grafana.com/grafana/dashboards/15167). Check the [TDinsight User Manual](/reference/tdinsight/) for the details. + +For more dashboards using TDengine data source, [search here in Grafana](https://grafana.com/grafana/dashboards/?dataSource=tdengine-datasource). Here is a sub list: + +- [15146](https://grafana.com/grafana/dashboards/15146): Monitor multiple TDengine clusters. +- [15155](https://grafana.com/grafana/dashboards/15155): TDengine alert demo. +- [15167](https://grafana.com/grafana/dashboards/15167): TDinsight. +- [16388](https://grafana.com/grafana/dashboards/16388): Telegraf node metrics dashboard using TDengine data source. diff --git a/docs-en/20-third-party/02-prometheus.md b/docs/en/20-third-party/02-prometheus.md similarity index 100% rename from docs-en/20-third-party/02-prometheus.md rename to docs/en/20-third-party/02-prometheus.md diff --git a/docs/en/20-third-party/03-telegraf.md b/docs/en/20-third-party/03-telegraf.md new file mode 100644 index 0000000000000000000000000000000000000000..6a7aac322f9def880f58d7ed0adcc4a8f3687ed1 --- /dev/null +++ b/docs/en/20-third-party/03-telegraf.md @@ -0,0 +1,67 @@ +--- +sidebar_label: Telegraf +title: Telegraf writing +--- + +import Telegraf from "../14-reference/_telegraf.mdx" + +Telegraf is a viral, open-source, metrics collection software. Telegraf can collect the operation information of various components without having to write any scripts to collect regularly, reducing the difficulty of data acquisition. + +Telegraf's data can be written to TDengine by simply adding the output configuration of Telegraf to the URL corresponding to taosAdapter and modifying several configuration items. The presence of Telegraf data in TDengine can take advantage of TDengine's efficient storage query performance and clustering capabilities for time-series data. + +## Prerequisites + +To write Telegraf data to TDengine requires the following preparations. +- The TDengine cluster is deployed and functioning properly +- taosAdapter is installed and running properly. Please refer to the [taosAdapter manual](/reference/taosadapter) for details. +- Telegraf has been installed. Please refer to the [official documentation](https://docs.influxdata.com/telegraf/v1.22/install/) for Telegraf installation. + +## Configuration steps + + +## Verification method + +Restart Telegraf service: + +``` +sudo systemctl restart telegraf +``` + +Use TDengine CLI to verify Telegraf correctly writing data to TDengine and read out: + +``` +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/en/20-third-party/05-collectd.md b/docs/en/20-third-party/05-collectd.md new file mode 100644 index 0000000000000000000000000000000000000000..db62f2ecd1afb4936466ca0243a7e14ff294f8b6 --- /dev/null +++ b/docs/en/20-third-party/05-collectd.md @@ -0,0 +1,74 @@ +--- +sidebar_label: collectd +title: collectd writing +--- + +import CollectD from "../14-reference/_collectd.mdx" + + +collectd is a daemon used to collect system performance metric data. collectd provides various storage mechanisms to store different values. It periodically counts system performance statistics while the system is running and storing information. You can use this information to help identify current system performance bottlenecks and predict future system load. + +You can write the data collected by collectd to TDengine by simply modifying the configuration of collectd to the domain name (or IP address) and corresponding port of the server running taosAdapter. It can take full advantage of TDengine's efficient storage query performance and clustering capability for time-series data. + +## Prerequisites + +Writing collectd data to the TDengine requires several preparations. +- The TDengine cluster is deployed and running properly +- taosAdapter is installed and running, please refer to [taosAdapter's manual](/reference/taosadapter) for details +- collectd has been installed. Please refer to the [official documentation](https://collectd.org/download.shtml) to install collectd + +## Configuration steps + + +## Verification method + +Restart collectd + +``` +sudo systemctl restart collectd +``` + +Use the TDengine CLI to verify that collectd's data is written to TDengine and can read out correctly. + +``` +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/en/20-third-party/06-statsd.md b/docs/en/20-third-party/06-statsd.md new file mode 100644 index 0000000000000000000000000000000000000000..40e927b9fd1d2eca9d454a987ac51d533eb75005 --- /dev/null +++ b/docs/en/20-third-party/06-statsd.md @@ -0,0 +1,68 @@ +--- +sidebar_label: StatsD +title: StatsD writing +--- + +import StatsD from "../14-reference/_statsd.mdx" + +StatsD is a simple daemon for aggregating application metrics, which has evolved rapidly in recent years into a unified protocol for collecting application performance metrics. + +You can write StatsD data to TDengine by simply modifying the configuration file of StatsD with the domain name (or IP address) of the server running taosAdapter and the corresponding port. It can take full advantage of TDengine's efficient storage query performance and clustering capabilities for time-series data. + +## Prerequisites + +To write StatsD data to TDengine requires the following preparations. +- The TDengine cluster has been deployed and is working properly +- taosAdapter is installed and running properly. Please refer to the [taosAdapter manual](/reference/taosadapter) for details. +- StatsD has been installed. To install StatsD, please refer to [official documentation](https://github.com/statsd/statsd) + +## Configuration steps + + +## Verification method + +Start 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 +``` + +Using the utility software `nc` to write data for test: + +``` +$ echo "foo:1|c" | nc -u -w0 127.0.0.1 8125 +``` + +Use the TDengine CLI to verify that StatsD data is written to TDengine and can read out correctly. + +``` +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/en/20-third-party/07-icinga2.md b/docs/en/20-third-party/07-icinga2.md new file mode 100644 index 0000000000000000000000000000000000000000..b27196dfe313b468eeb73ff4b114d9d955618c3e --- /dev/null +++ b/docs/en/20-third-party/07-icinga2.md @@ -0,0 +1,74 @@ +--- +sidebar_label: icinga2 +title: icinga2 writing +--- + +import Icinga2 from "../14-reference/_icinga2.mdx" + +icinga2 is an open-source, host and network monitoring software initially developed from the Nagios network monitoring application. Currently, icinga2 is distributed under the GNU GPL v2 license. + +You can write the data collected by icinga2 to TDengine by simply modifying the icinga2 configuration to point to the taosAdapter server and the corresponding port, taking advantage of TDengine's efficient storage and query performance and clustering capabilities for time-series data. + +## Prerequisites + +To write icinga2 data to TDengine requires the following preparations. +- The TDengine cluster is deployed and working properly +- taosAdapter is installed and running properly. Please refer to the [taosAdapter manual](/reference/taosadapter) for details. +- icinga2 has been installed. Please refer to the [official documentation](https://icinga.com/docs/icinga-2/latest/doc/02-installation/) for icinga2 installation + +## Configuration steps + + +## Verification method + +Restart taosAdapter: +``` +sudo systemctl restart taosadapter +``` + +Restart icinga2: + +``` +sudo systemctl restart icinga2 +``` + +After waiting about 10 seconds, use the TDengine CLI to query TDengine to verify that the appropriate database has been created and data are written. + +``` +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/en/20-third-party/08-tcollector.md b/docs/en/20-third-party/08-tcollector.md new file mode 100644 index 0000000000000000000000000000000000000000..16b73c23948ff001bab9c756c50b0fcb2cd44810 --- /dev/null +++ b/docs/en/20-third-party/08-tcollector.md @@ -0,0 +1,67 @@ +--- +sidebar_label: TCollector +title: TCollector writing +--- + +import TCollector from "../14-reference/_tcollector.mdx" + +TCollector is part of openTSDB and collects client computer's logs to send to the database. + +You can write the data collected by TCollector to TDengine by simply changing the configuration of TCollector to point to the domain name (or IP address) and corresponding port of the server running taosAdapter. It can take full advantage of TDengine's efficient storage query performance and clustering capability for time-series data. + +## Prerequisites + +To write data to the TDengine via TCollector requires the following preparations. +- The TDengine cluster has been deployed and is working properly +- taosAdapter is installed and running properly. Please refer to the [taosAdapter manual](/reference/taosadapter) for details. +- TCollector has been installed. Please refer to [official documentation](http://opentsdb.net/docs/build/html/user_guide/utilities/tcollector.html#installation-of-tcollector) for TCollector installation + +## Configuration steps + + +## Verification method + +Restart taosAdapter: + +``` +sudo systemctl restart taosadapter +``` + +Run `sudo ./tcollector.py`: + +Wait for a few seconds and then use the TDengine CLI to query whether the corresponding database has been created and data are written in 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/en/20-third-party/09-emq-broker.md b/docs/en/20-third-party/09-emq-broker.md new file mode 100644 index 0000000000000000000000000000000000000000..8dfa09e6c7d1615ea3a1145428efe920588b687e --- /dev/null +++ b/docs/en/20-third-party/09-emq-broker.md @@ -0,0 +1,140 @@ +--- +sidebar_label: EMQX Broker +title: EMQX Broker writing +--- + +MQTT is a popular IoT data transfer protocol. [EMQX](https://github.com/emqx/emqx) is an open-source MQTT Broker software. You can write MQTT data directly to TDengine without any code. You only need to setup "rules" in EMQX Dashboard to create a simple configuration. EMQX supports saving data to TDengine by sending data to a web service and provides a native TDengine driver for direct saving in the Enterprise Edition. Please refer to the [EMQX official documentation](https://www.emqx.io/docs/en/v4.4/rule/rule-engine.html) for details on how to use it.). + +## Prerequisites + +The following preparations are required for EMQX to add TDengine data sources correctly. +- The TDengine cluster is deployed and working properly +- taosAdapter is installed and running properly. Please refer to the [taosAdapter manual](/reference/taosadapter) for details. +- If you use the emulated writers described later, you need to install the appropriate version of Node.js. V12 is recommended. + +## Install and start EMQX + +Depending on the current operating system, users can download the installation package from the [EMQX official website](https://www.emqx.io/downloads) and execute the installation. After installation, use `sudo emqx start` or `sudo systemctl start emqx` to start the EMQX service. + + +## Create Database and Table + +In this step we create the appropriate database and table schema in TDengine for receiving MQTT data. Open TDengine CLI and execute SQL bellow: + +```sql +CREATE DATABASE test; +USE test; +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); +``` + +Note: The table schema is based on the blog [(In Chinese) Data Transfer, Storage, Presentation, EMQX + TDengine Build MQTT IoT Data Visualization Platform](https://www.taosdata.com/blog/2020/08/04/1722.html) as an example. Subsequent operations are carried out with this blog scenario too. Please modify it according to your actual application scenario. + +## Configuring EMQX Rules + +Since the configuration interface of EMQX differs from version to version, here is v4.4.3 as an example. For other versions, please refer to the corresponding official documentation. + +### Login EMQX Dashboard + +Use your browser to open the URL `http://IP:18083` and log in to EMQX Dashboard. The initial installation username is `admin` and the password is: `public`. + +![TDengine Database EMQX login dashboard](./emqx/login-dashboard.webp) + +### Creating Rule + +Select "Rule" in the "Rule Engine" on the left and click the "Create" button: ! + +![TDengine Database EMQX rule engine](./emqx/rule-engine.webp) + +### Edit SQL fields + +Copy SQL bellow and paste it to the SQL edit area： + +```sql +SELECT + payload +FROM + "sensor/data" +``` + +![TDengine Database EMQX create rule](./emqx/create-rule.webp) + +### Add "action handler" + +![TDengine Database EMQX add action handler](./emqx/add-action-handler.webp) + +### Add "Resource" + +![TDengine Database EMQX create resource](./emqx/create-resource.webp) + +Select "Data to Web Service" and click the "New Resource" button. + +### Edit "Resource" + +Select "WebHook" and fill in the request URL as the address and port of the server running taosAdapter (default is 6041). Leave the other properties at their default values. + +![TDengine Database EMQX edit resource](./emqx/edit-resource.webp) + +### Edit "action" + +Edit the resource configuration to add the key/value pairing for Authorization. If you use the default TDengine username and password then the value of key Authorization is： +``` +Basic cm9vdDp0YW9zZGF0YQ== +``` + +Please refer to the [ TDengine REST API documentation ](/reference/rest-api/) for the authorization in details. + +Enter the rule engine replacement template in the message body: + +```sql +INSERT INTO test.sensor_data VALUES( + now, + ${payload.temperature}, + ${payload.humidity}, + ${payload.volume}, + ${payload.PM10}, + ${payload.pm25}, + ${payload.SO2}, + ${payload.NO2}, + ${payload.CO}, + '${payload.id}', + ${payload.area}, + ${payload.ts} +) +``` + +![TDengine Database EMQX edit action](./emqx/edit-action.webp) + +Finally, click the "Create" button at bottom left corner saving the rule. +## Compose program to mock data + +```javascript +{{#include docs/examples/other/mock.js}} +``` + +Note: `CLIENT_NUM` in the code can be set to a smaller value at the beginning of the test to avoid hardware performance be not capable to handle a more significant number of concurrent clients. + +![TDengine Database EMQX client num](./emqx/client-num.webp) + +## Execute tests to simulate sending MQTT data + +``` +npm install mqtt mockjs --save ---registry=https://registry.npm.taobao.org +node mock.js +``` + +![TDengine Database EMQX run mock](./emqx/run-mock.webp) + +## Verify that EMQX is receiving data + +Refresh the EMQX Dashboard rules engine interface to see how many records were received correctly: + +![TDengine Database EMQX rule matched](./emqx/check-rule-matched.webp) + +## Verify that data writing to TDengine + +Use the TDengine CLI program to log in and query the appropriate databases and tables to verify that the data is being written to TDengine correctly: + +![TDengine Database EMQX result in taos](./emqx/check-result-in-taos.webp) + +Please refer to the [TDengine official documentation](https://docs.taosdata.com/) for more details on how to use TDengine. +EMQX Please refer to the [EMQX official documentation](https://www.emqx.io/docs/en/v4.4/rule/rule-engine.html) for details on how to use EMQX. diff --git a/docs-en/20-third-party/10-hive-mq-broker.md b/docs/en/20-third-party/10-hive-mq-broker.md similarity index 100% rename from docs-en/20-third-party/10-hive-mq-broker.md rename to docs/en/20-third-party/10-hive-mq-broker.md diff --git a/docs/en/20-third-party/11-kafka.md b/docs/en/20-third-party/11-kafka.md new file mode 100644 index 0000000000000000000000000000000000000000..6720af8bf81ea2f4fce415a54847453f578ababf --- /dev/null +++ b/docs/en/20-third-party/11-kafka.md @@ -0,0 +1,439 @@ +--- +sidebar_label: Kafka +title: TDengine Kafka Connector Tutorial +--- + +TDengine Kafka Connector contains two plugins: TDengine Source Connector and TDengine Sink Connector. Users only need to provide a simple configuration file to synchronize the data of the specified topic in Kafka (batch or real-time) to TDengine or synchronize the data (batch or real-time) of the specified database in TDengine to Kafka. + +## What is Kafka Connect? + +Kafka Connect is a component of [Apache Kafka](https://kafka.apache.org/) that enables other systems, such as databases, cloud services, file systems, etc., to connect to Kafka easily. Data can flow from other software to Kafka via Kafka Connect and Kafka to other systems via Kafka Connect. Plugins that read data from other software are called Source Connectors, and plugins that write data to other software are called Sink Connectors. Neither Source Connector nor Sink Connector will directly connect to Kafka Broker, and Source Connector transfers data to Kafka Connect. Sink Connector receives data from Kafka Connect. + +![TDengine Database Kafka Connector -- Kafka Connect](kafka/Kafka_Connect.webp) + +TDengine Source Connector is used to read data from TDengine in real-time and send it to Kafka Connect. Users can use The TDengine Sink Connector to receive data from Kafka Connect and write it to TDengine. + +![TDengine Database Kafka Connector -- streaming integration with kafka connect](kafka/streaming-integration-with-kafka-connect.webp) + +## What is Confluent? + +[Confluent](https://www.confluent.io/) adds many extensions to Kafka. include: + +1. Schema Registry +2. REST Proxy +3. Non-Java Clients +4. Many packaged Kafka Connect plugins +5. GUI for managing and monitoring Kafka - Confluent Control Center + +Some of these extensions are available in the community version of Confluent. Some are only available in the enterprise version. +![TDengine Database Kafka Connector -- Confluent platform](kafka/confluentPlatform.webp) + +Confluent Enterprise Edition provides the `confluent` command-line tool to manage various components. + +## Prerequisites + +1. Linux operating system +2. Java 8 and Maven installed +3. Git is installed +4. TDengine is installed and started. If not, please refer to [Installation and Uninstallation](/operation/pkg-install) + +## Install Confluent + +Confluent provides two installation methods: Docker and binary packages. This article only introduces binary package installation. + +Execute in any directory: + +```` +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 +```` + +Then you need to add the `$CONFLUENT_HOME/bin` directory to the PATH. + +```title=".profile" +export CONFLUENT_HOME=/opt/confluent-7.1.1 +PATH=$CONFLUENT_HOME/bin +export PATH +``` + +Users can append the above script to the current user's profile file (~/.profile or ~/.bash_profile) + +After the installation is complete, you can enter `confluent version` for simple verification: + +``` +# 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 +``` + +## Install TDengine Connector plugin + +### Install from source code + +``` +git clone https://github.com:taosdata/kafka-connect-tdengine.git +cd kafka-connect-tdengine +mvn clean package +unzip -d $CONFLUENT_HOME/share/java/ target/components/packages/taosdata-kafka-connect-tdengine-*.zip +``` + +The above script first clones the project source code and then compiles and packages it with Maven. After the package is complete, the zip package of the plugin is generated in the `target/components/packages/` directory. Unzip this zip package to plugin path. We used `$CONFLUENT_HOME/share/java/` above because it's a build in plugin path. + +### Install with confluent-hub + +[Confluent Hub](https://www.confluent.io/hub) provides a service to download Kafka Connect plugins. After TDengine Kafka Connector is published to Confluent Hub, it can be installed using the command tool `confluent-hub`. +**TDengine Kafka Connector is currently not officially released and cannot be installed in this way**. + +## Start Confluent + +``` +confluent local services start +``` + +:::note +Be sure to install the plugin before starting Confluent. Otherwise, Kafka Connect will fail to discover the plugins. +::: + +:::tip +If a component fails to start, try clearing the data and restarting. The data directory will be printed to the console at startup, e.g.: + +```title="Console output log" {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] +``` + +To clear data, execute `rm -rf /tmp/confluent.106668`. +::: + +### Check Confluent Services Status + +Use command bellow to check the status of all service: + +``` +confluent local services status +``` + +The expected output is: +``` +Connect is [UP] +Control Center is [UP] +Kafka is [UP] +Kafka REST is [UP] +ksqlDB Server is [UP] +Schema Registry is [UP] +ZooKeeper is [UP] +``` + +### Check Successfully Loaded Plugin + +After Kafka Connect was completely started, you can use bellow command to check if our plugins are installed successfully: +``` +confluent local services connect plugin list +``` + +The output should contains `TDengineSinkConnector` and `TDengineSourceConnector` as bellow: + +``` +Available Connect Plugins: +[ + { + "class": "com.taosdata.kafka.connect.sink.TDengineSinkConnector", + "type": "sink", + "version": "1.0.0" + }, + { + "class": "com.taosdata.kafka.connect.source.TDengineSourceConnector", + "type": "source", + "version": "1.0.0" + }, +...... +``` + +If not, please check the log file of Kafka Connect. To view the log file path, please execute: + +``` +echo `cat /tmp/confluent.current`/connect/connect.stdout +``` +It should produce a path like:`/tmp/confluent.104086/connect/connect.stdout` + +Besides log file `connect.stdout` there is a file named `connect.properties`. At the end of this file you can see the effective `plugin.path` which is a series of paths joined by comma. If Kafka Connect not found our plugins, it's probably because the installed path is not included in `plugin.path`. + +## The use of TDengine Sink Connector + +The role of the TDengine Sink Connector is to synchronize the data of the specified topic to TDengine. Users do not need to create databases and super tables in advance. The name of the target database can be specified manually (see the configuration parameter connection.database), or it can be generated according to specific rules (see the configuration parameter connection.database.prefix). + +TDengine Sink Connector internally uses TDengine [modeless write interface](/reference/connector/cpp#modeless write-api) to write data to TDengine, currently supports data in three formats: [InfluxDB line protocol format](/develop /insert-data/influxdb-line), [OpenTSDB Telnet protocol format](/develop/insert-data/opentsdb-telnet), and [OpenTSDB JSON protocol format](/develop/insert-data/opentsdb-json). + +The following example synchronizes the data of the topic meters to the target database power. The data format is the InfluxDB Line protocol format. + +### Add configuration file + +``` +mkdir ~/test +cd ~/test +vi sink-demo.properties +``` + +sink-demo.properties' content is following: + +```ini title="sink-demo.properties" +name=TDengineSinkConnector +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 +data.precision=ns +key.converter=org.apache.kafka.connect.storage.StringConverter +value.converter=org.apache.kafka.connect.storage.StringConverter +``` + +Key configuration instructions: + +1. `topics=meters` and `connection.database=power` means to subscribe to the data of the topic meters and write to the database power. +2. `db.schemaless=line` means the data in the InfluxDB Line protocol format. + +### Create Connector instance + +```` +confluent local services connect connector load TDengineSinkConnector --config ./sink-demo.properties +```` + +If the above command is executed successfully, the output is as follows: + +```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", + "data.precision": "ns", + "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" +} +``` + +### Write test data + +Prepare text file as test data, its content is following: + +```txt title="test-data.txt" +meters,location=California.LoSangeles,groupid=2 current=11.8,voltage=221,phase=0.28 1648432611249000000 +meters,location=California.LoSangeles,groupid=2 current=13.4,voltage=223,phase=0.29 1648432611250000000 +meters,location=California.LoSangeles,groupid=3 current=10.8,voltage=223,phase=0.29 1648432611249000000 +meters,location=California.LoSangeles,groupid=3 current=11.3,voltage=221,phase=0.35 1648432611250000000 +``` + +Use kafka-console-producer to write test data to the topic `meters`. + +``` +cat test-data.txt | kafka-console-producer --broker-list localhost:9092 --topic meters +``` + +:::note +TDengine Sink Connector will automatically create the database if the target database does not exist. The time precision used to create the database automatically is nanoseconds, which requires that the timestamp precision of the written data is also nanoseconds. An exception will be thrown if the timestamp precision of the written data is not nanoseconds. +::: + +### Verify that the sync was successful + +Use the TDengine CLI to verify that the sync was successful. + +``` +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 | California.LosAngeles | + 2022-03-28 09:56:51.250000000 | 13.400000000 | 223.000000000 | 0.290000000 | 2 | California.LosAngeles | + 2022-03-28 09:56:51.249000000 | 10.800000000 | 223.000000000 | 0.290000000 | 3 | California.LosAngeles | + 2022-03-28 09:56:51.250000000 | 11.300000000 | 221.000000000 | 0.350000000 | 3 | California.LosAngeles | +Query OK, 4 row(s) in set (0.004208s) +``` + +If you see the above data, the synchronization is successful. If not, check the logs of Kafka Connect. For detailed description of configuration parameters, see [Configuration Reference](#configuration-reference). + +## The use of TDengine Source Connector + +The role of the TDengine Source Connector is to push all the data of a specific TDengine database after a particular time to Kafka. The implementation principle of TDengine Source Connector is to first pull historical data in batches and then synchronize incremental data with the strategy of the regular query. At the same time, the changes in the table will be monitored, and the newly added table can be automatically synchronized. If Kafka Connect is restarted, synchronization will resume where it left off. + +TDengine Source Connector will convert the data in TDengine data table into [InfluxDB Line protocol format](/develop/insert-data/influxdb-line/) or [OpenTSDB JSON protocol format](/develop/insert-data/opentsdb-json ) and then write to Kafka. + +The following sample program synchronizes the data in the database test to the topic tdengine-source-test. + +### Add configuration file + +``` +vi source-demo.properties +``` + +Input following content: + +```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 +``` + +### Prepare test data + +Prepare SQL script file to generate test data + +```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(California.SanFrancisco, 2) VALUES('2018-10-03 14:38:05.000',10.30000,219,0.31000) d1001 USING meters TAGS(California.SanFrancisco, 2) VALUES('2018-10-03 14:38:15.000',12.60000,218,0.33000) d1001 USING meters TAGS(California.SanFrancisco, 2) VALUES('2018-10-03 14:38:16.800',12.30000,221,0.31000) d1002 USING meters TAGS(California.SanFrancisco, 3) VALUES('2018-10-03 14:38:16.650',10.30000,218,0.25000) d1003 USING meters TAGS(California.LoSangeles, 2) VALUES('2018-10-03 14:38:05.500',11.80000,221,0.28000) d1003 USING meters TAGS(California.LoSangeles, 2) VALUES('2018-10-03 14:38:16.600',13.40000,223,0.29000) d1004 USING meters TAGS(California.LoSangeles, 3) VALUES('2018-10-03 14:38:05.000',10.80000,223,0.29000) d1004 USING meters TAGS(California.LoSangeles, 3) VALUES('2018-10-03 14:38:06.500',11.50000,221,0.35000); +``` + +Use TDengine CLI to execute SQL script + +``` +taos -f prepare-source-data.sql +``` + +### Create Connector instance + +```` +confluent local services connect connector load TDengineSourceConnector --config source-demo.properties +```` + +### View topic data + +Use the kafka-console-consumer command-line tool to monitor data in the topic tdengine-source-test. In the beginning, all historical data will be output. After inserting two new data into TDengine, kafka-console-consumer immediately outputs the two new data. + +```` +kafka-console-consumer --bootstrap-server localhost:9092 --from-beginning --topic tdengine-source-test +```` + +output: + +```` +...... +meters,location="California.SanFrancisco",groupid=2i32 current=10.3f32,voltage=219i32,phase=0.31f32 1538548685000000000 +meters,location="California.SanFrancisco",groupid=2i32 current=12.6f32,voltage=218i32,phase=0.33f32 1538548695000000000 +...... +```` + +All historical data is displayed. Switch to the TDengine CLI and insert two new pieces of data: + +```` +USE test; +INSERT INTO d1001 VALUES (now, 13.3, 229, 0.38); +INSERT INTO d1002 VALUES (now, 16.3, 233, 0.22); +```` + +Switch back to kafka-console-consumer, and the command line window has printed out the two pieces of data just inserted. + +### unload plugin + +After testing, use the unload command to stop the loaded connector. + +View currently active connectors: + +```` +confluent local services connect connector status +```` + +You should now have two active connectors if you followed the previous steps. Use the following command to unload: + +```` +confluent local services connect connector unload TDengineSourceConnector +confluent local services connect connector unload TDengineSourceConnector +```` + +## Configuration reference + +### General configuration + +The following configuration items apply to TDengine Sink Connector and TDengine Source Connector. + +1. `name`: The name of the connector. +2. `connector.class`: The full class name of the connector, for example: com.taosdata.kafka.connect.sink.TDengineSinkConnector. +3. `tasks.max`: The maximum number of tasks, the default is 1. +4. `topics`: A list of topics to be synchronized, separated by commas, such as `topic1,topic2`. +5. `connection.url`: TDengine JDBC connection string, such as `jdbc:TAOS://127.0.0.1:6030`. +6. `connection.user`: TDengine username, default root. +7. `connection.password`: TDengine user password, default taosdata. +8. `connection.attempts` : The maximum number of connection attempts. Default 3. +9. `connection.backoff.ms`: The retry interval for connection creation failure, the unit is ms. Default is 5000. + +### TDengine Sink Connector specific configuration + +1. `connection.database`: The name of the target database. If the specified database does not exist, it will be created automatically. The time precision used for automatic library building is nanoseconds. The default value is null. When it is NULL, refer to the description of the `connection.database.prefix` parameter for the naming rules of the target database +2. `connection.database.prefix`: When `connection.database` is null, the prefix of the target database. Can contain placeholder '${topic}'. For example, kafka_${topic}, for topic 'orders' will be written to database 'kafka_orders'. Default null. When null, the name of the target database is the same as the name of the topic. +3. `batch.size`: Write the number of records in each batch in batches. When the data received by the sink connector at one time is larger than this value, it will be written in some batches. +4. `max.retries`: The maximum number of retries when an error occurs. Defaults to 1. +5. `retry.backoff.ms`: The time interval for retry when sending an error. The unit is milliseconds. The default is 3000. +6. `db.schemaless`: Data format, could be one of `line`, `json`, and `telnet`. Represent InfluxDB line protocol format, OpenTSDB JSON format, and OpenTSDB Telnet line protocol format. +7. `data.precision`: The time precision when use InfluxDB line protocol format data, could be one of `ms`, `us` and `ns`. The default is `ns`. + +### TDengine Source Connector specific configuration + +1. `connection.database`: source database name, no default value. +2. `topic.prefix`: topic name prefix after data is imported into kafka. Use `topic.prefix` + `connection.database` name as the full topic name. Defaults to the empty string "". +3. `timestamp.initial`: Data synchronization start time. The format is 'yyyy-MM-dd HH:mm:ss'. Default "1970-01-01 00:00:00". +4. `poll.interval.ms`: Pull data interval, the unit is ms. Default is 1000. +5. `fetch.max.rows`: The maximum number of rows retrieved when retrieving the database. Default is 100. +6. `out.format`: The data format. The value could be line or json. The line represents the InfluxDB Line protocol format, and json represents the OpenTSDB JSON format. Default is `line`. + + +## Other notes + +1. To install plugin to a customized location, refer to https://docs.confluent.io/home/connect/self-managed/install.html#install-connector-manually. +2. To use Kafka Connect without confluent, refer to https://kafka.apache.org/documentation/#connect. + +## Feedback + +https://github.com/taosdata/kafka-connect-tdengine/issues + +## Reference + +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/en/20-third-party/_category_.yml b/docs/en/20-third-party/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..e71e65a6a365df63603c3878375c034b4b24db77 --- /dev/null +++ b/docs/en/20-third-party/_category_.yml @@ -0,0 +1,2 @@ +label: Third Party Tools + diff --git a/docs-en/20-third-party/_deploytaosadapter.mdx b/docs/en/20-third-party/_deploytaosadapter.mdx similarity index 100% rename from docs-en/20-third-party/_deploytaosadapter.mdx rename to docs/en/20-third-party/_deploytaosadapter.mdx diff --git a/docs/en/20-third-party/emqx/add-action-handler.webp b/docs/en/20-third-party/emqx/add-action-handler.webp new file mode 100644 index 0000000000000000000000000000000000000000..4a8d105f711991226cfbd43b6e9ab07d7ccc686a Binary files /dev/null and b/docs/en/20-third-party/emqx/add-action-handler.webp differ diff --git a/docs/en/20-third-party/emqx/check-result-in-taos.webp b/docs/en/20-third-party/emqx/check-result-in-taos.webp new file mode 100644 index 0000000000000000000000000000000000000000..8fa040a86104fece02ddaf8986f0a67de316143d Binary files /dev/null and b/docs/en/20-third-party/emqx/check-result-in-taos.webp differ diff --git a/docs/en/20-third-party/emqx/check-rule-matched.webp b/docs/en/20-third-party/emqx/check-rule-matched.webp new file mode 100644 index 0000000000000000000000000000000000000000..e5a614035739df859b27c817f3b9f41be444b513 Binary files /dev/null and b/docs/en/20-third-party/emqx/check-rule-matched.webp differ diff --git a/docs/en/20-third-party/emqx/client-num.webp b/docs/en/20-third-party/emqx/client-num.webp new file mode 100644 index 0000000000000000000000000000000000000000..a151b184843607d67b649babb3145bfb3e329cda Binary files /dev/null and b/docs/en/20-third-party/emqx/client-num.webp differ diff --git a/docs/en/20-third-party/emqx/create-resource.webp b/docs/en/20-third-party/emqx/create-resource.webp new file mode 100644 index 0000000000000000000000000000000000000000..bf9cccbe49c57f925c5e6b094a4c0d88a64242cb Binary files /dev/null and b/docs/en/20-third-party/emqx/create-resource.webp differ diff --git a/docs/en/20-third-party/emqx/create-rule.webp b/docs/en/20-third-party/emqx/create-rule.webp new file mode 100644 index 0000000000000000000000000000000000000000..13e8fc83d48d2fd9d0a303c707ef3024d3ee5203 Binary files /dev/null and b/docs/en/20-third-party/emqx/create-rule.webp differ diff --git a/docs/en/20-third-party/emqx/edit-action.webp b/docs/en/20-third-party/emqx/edit-action.webp new file mode 100644 index 0000000000000000000000000000000000000000..7f6d2e36a82b1917930e5d3969115db9359674a0 Binary files /dev/null and b/docs/en/20-third-party/emqx/edit-action.webp differ diff --git a/docs/en/20-third-party/emqx/edit-resource.webp b/docs/en/20-third-party/emqx/edit-resource.webp new file mode 100644 index 0000000000000000000000000000000000000000..fd5d278fab16bba4e04e1c348d4086dce77abb98 Binary files /dev/null and b/docs/en/20-third-party/emqx/edit-resource.webp differ diff --git a/docs/en/20-third-party/emqx/login-dashboard.webp b/docs/en/20-third-party/emqx/login-dashboard.webp new file mode 100644 index 0000000000000000000000000000000000000000..f84cee668fb6efe1586515ba0dee3ae2f10a5b30 Binary files /dev/null and b/docs/en/20-third-party/emqx/login-dashboard.webp differ diff --git a/docs/en/20-third-party/emqx/rule-engine.webp b/docs/en/20-third-party/emqx/rule-engine.webp new file mode 100644 index 0000000000000000000000000000000000000000..c1711c8cc757cd73fef5cb941a1818756241f7f0 Binary files /dev/null and b/docs/en/20-third-party/emqx/rule-engine.webp differ diff --git a/docs/en/20-third-party/emqx/rule-header-key-value.webp b/docs/en/20-third-party/emqx/rule-header-key-value.webp new file mode 100644 index 0000000000000000000000000000000000000000..e645b3822dffec86f4926e78a57eaffa1e7f4d8d Binary files /dev/null and b/docs/en/20-third-party/emqx/rule-header-key-value.webp differ diff --git a/docs/en/20-third-party/emqx/run-mock.webp b/docs/en/20-third-party/emqx/run-mock.webp new file mode 100644 index 0000000000000000000000000000000000000000..ed33f1666d456f1ab40ed6830af4550d4c7ca037 Binary files /dev/null and b/docs/en/20-third-party/emqx/run-mock.webp differ diff --git a/docs/en/20-third-party/grafana/add_datasource1.webp b/docs/en/20-third-party/grafana/add_datasource1.webp new file mode 100644 index 0000000000000000000000000000000000000000..211edc4457abd0db6b0ef64636d61d65b5f43db6 Binary files /dev/null and b/docs/en/20-third-party/grafana/add_datasource1.webp differ diff --git a/docs/en/20-third-party/grafana/add_datasource2.webp b/docs/en/20-third-party/grafana/add_datasource2.webp new file mode 100644 index 0000000000000000000000000000000000000000..8ab547231fee4d3b0874fcfe08c0ce152b0c53a1 Binary files /dev/null and b/docs/en/20-third-party/grafana/add_datasource2.webp differ diff --git a/docs/en/20-third-party/grafana/add_datasource3.webp b/docs/en/20-third-party/grafana/add_datasource3.webp new file mode 100644 index 0000000000000000000000000000000000000000..d8a733360a09b4425c571f254a9ecb298c04b72f Binary files /dev/null and b/docs/en/20-third-party/grafana/add_datasource3.webp differ diff --git a/docs/en/20-third-party/grafana/add_datasource4.webp b/docs/en/20-third-party/grafana/add_datasource4.webp new file mode 100644 index 0000000000000000000000000000000000000000..b1e0fc6e2b27df4af1bb5ad92756bcb5d4fda63e Binary files /dev/null and b/docs/en/20-third-party/grafana/add_datasource4.webp differ diff --git a/docs/en/20-third-party/grafana/create_dashboard1.webp b/docs/en/20-third-party/grafana/create_dashboard1.webp new file mode 100644 index 0000000000000000000000000000000000000000..55eb388833e4df2a46f4d1cf6d346aa11429385d Binary files /dev/null and b/docs/en/20-third-party/grafana/create_dashboard1.webp differ diff --git a/docs/en/20-third-party/grafana/create_dashboard2.webp b/docs/en/20-third-party/grafana/create_dashboard2.webp new file mode 100644 index 0000000000000000000000000000000000000000..bb40e407187718c52e9f617d8ebd3d25fd14b56b Binary files /dev/null and b/docs/en/20-third-party/grafana/create_dashboard2.webp differ diff --git a/docs/en/20-third-party/index.md b/docs/en/20-third-party/index.md new file mode 100644 index 0000000000000000000000000000000000000000..87bd9e075133d1182ee93d1c1c43617c766755b9 --- /dev/null +++ b/docs/en/20-third-party/index.md @@ -0,0 +1,12 @@ +--- +title: Third Party Tools +--- + +Since TDengine supports standard SQL commands, common database connector standards (e.g., JDBC), ORM, and other popular time-series database writing protocols (e.g., InfluxDB Line Protocol, OpenTSDB JSON, OpenTSDB Telnet, etc.), it is very easy to integrate TDengine with other third party tools. You only need to provide simple configuration, the integration can be done without a line of code. + +```mdx-code-block +import DocCardList from '@theme/DocCardList'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + + +``` diff --git a/docs/en/20-third-party/kafka/Kafka_Connect.webp b/docs/en/20-third-party/kafka/Kafka_Connect.webp new file mode 100644 index 0000000000000000000000000000000000000000..8f2000a749b0a2ccec9939abd144c53c44fbe171 Binary files /dev/null and b/docs/en/20-third-party/kafka/Kafka_Connect.webp differ diff --git a/docs/en/20-third-party/kafka/confluentPlatform.webp b/docs/en/20-third-party/kafka/confluentPlatform.webp new file mode 100644 index 0000000000000000000000000000000000000000..ff03d4e51aaaec85f07ff41ecda0fb9bd6cb2847 Binary files /dev/null and b/docs/en/20-third-party/kafka/confluentPlatform.webp differ diff --git a/docs/en/20-third-party/kafka/streaming-integration-with-kafka-connect.webp b/docs/en/20-third-party/kafka/streaming-integration-with-kafka-connect.webp new file mode 100644 index 0000000000000000000000000000000000000000..120d534ec132cea2ccef6cf87a3ce680a5ac6e9c Binary files /dev/null and b/docs/en/20-third-party/kafka/streaming-integration-with-kafka-connect.webp differ diff --git a/docs/en/21-tdinternal/01-arch.md b/docs/en/21-tdinternal/01-arch.md new file mode 100644 index 0000000000000000000000000000000000000000..4d8bed4d2d6b3a0404e10213aeab599767325cc2 --- /dev/null +++ b/docs/en/21-tdinternal/01-arch.md @@ -0,0 +1,287 @@ +--- +sidebar_label: Architecture +title: Architecture +--- + +## Cluster and Primary Logic Unit + +The design of TDengine is based on the assumption that any hardware or software system is not 100% reliable and that no single node can provide sufficient computing and storage resources to process massive data. Therefore, since day one, TDengine has been designed as a natively distributed system, with high-reliability architecture. Hardware failure or software failure of a single, or even multiple servers will not affect the availability and reliability of the system. At the same time, through node virtualization and automatic load-balancing technology, TDengine can make the most efficient use of computing and storage resources in heterogeneous clusters to reduce hardware resource needs, significantly. + +### Primary Logic Unit + +Logical structure diagram of TDengine's distributed architecture is as follows: + +![TDengine Database architecture diagram](structure.webp) +
Figure 1: TDengine architecture diagram
+ +A complete TDengine system runs on one or more physical nodes. Logically, it includes data node (dnode), TDengine client driver (TAOSC) and application (app). There are one or more data nodes in the system, which form a cluster. The application interacts with the TDengine cluster through TAOSC's API. The following is a brief introduction to each logical unit. + +**Physical node (pnode)**: A pnode is a computer that runs independently and has its own computing, storage and network capabilities. It can be a physical machine, virtual machine, or Docker container installed with OS. The physical node is identified by its configured FQDN (Fully Qualified Domain Name). TDengine relies entirely on FQDN for network communication. If you don't know about FQDN, please check [wikipedia](https://en.wikipedia.org/wiki/Fully_qualified_domain_name). + +**Data node (dnode):** A dnode is a running instance of the TDengine server-side execution code taosd on a physical node (pnode). A working system must have at least one data node. A dnode contains zero to multiple logical virtual nodes (VNODE) and zero or at most one logical management node (mnode). The unique identification of a dnode in the system is determined by the instance's End Point (EP). EP is a combination of FQDN (Fully Qualified Domain Name) of the physical node where the dnode is located and the network port number (Port) configured by the system. By configuring different ports, a physical node (a physical machine, virtual machine or container) can run multiple instances or have multiple data nodes. + +**Virtual node (vnode)**: To better support data sharding, load balancing and prevent data from overheating or skewing, data nodes are virtualized into multiple virtual nodes (vnode, V2, V3, V4, etc. in the figure). Each vnode is a relatively independent work unit, which is the basic unit of time-series data storage and has independent running threads, memory space and persistent storage path. A vnode contains a certain number of tables (data collection points). When a new table is created, the system checks whether a new vnode needs to be created. The number of vnodes that can be created on a data node depends on the capacity of the hardware of the physical node where the data node is located. A vnode belongs to only one DB, but a DB can have multiple vnodes. In addition to the stored time-series data, a vnode also stores the schema and tag values of the included tables. A virtual node is uniquely identified in the system by the EP of the data node and the VGroup ID to which it belongs and is created and managed by the management node. + +**Management node (mnode)**: A virtual logical unit responsible for monitoring and maintaining the running status of all data nodes and load balancing among nodes (M in the figure). At the same time, the management node is also responsible for the storage and management of metadata (including users, databases, tables, static tags, etc.), so it is also called Meta Node. Multiple (up to 5) mnodes can be configured in a TDengine cluster, and they are automatically constructed into a virtual management node group (M0, M1, M2 in the figure). The master/slave mechanism is adopted for the mnode group and the data synchronization is carried out in a strongly consistent way. Any data update operation can only be executed on the master. The creation of mnode cluster is completed automatically by the system without manual intervention. There is at most one mnode on each dnode, which is uniquely identified by the EP of the data node to which it belongs. Each dnode automatically obtains the EP of the dnode where all mnodes in the whole cluster are located, through internal messaging interaction. + +**Virtual node group (VGroup)**: Vnodes on different data nodes can form a virtual node group to ensure the high availability of the system. The virtual node group is managed in a master/slave mechanism. Write operations can only be performed on the master vnode, and then replicated to slave vnodes, thus ensuring that one single replica of data is copied on multiple physical nodes. The number of virtual nodes in a vgroup equals the number of data replicas. If the number of replicas of a DB is N, the system must have at least N data nodes. The number of replicas can be specified by the parameter `“replica”` when creating a DB, and the default is 1. Using the multi-replication feature of TDengine, the same high data reliability can be achieved without the need for expensive storage devices such as disk arrays. Virtual node groups are created and managed by the management node, and the management node assigns a system unique ID, aka VGroup ID. If two virtual nodes have the same vnode group ID, it means that they belong to the same group and the data is backed up to each other. The number of virtual nodes in a virtual node group can be dynamically changed, allowing only one, that is, no data replication. VGroup ID is never changed. Even if a virtual node group is deleted, its ID will not be reused. + +**TAOSC**: TAOSC is the driver provided by TDengine to applications. It is responsible for dealing with the interaction between application and cluster, and provides the native interface for the C/C++ language. It is also embedded in the JDBC, C #, Python, Go, Node.js language connection libraries. Applications interact with the whole cluster through TAOSC instead of directly connecting to data nodes in the cluster. This module is responsible for obtaining and caching metadata; forwarding requests for insertion, query, etc. to the correct data node; when returning the results to the application, TAOSC also needs to be responsible for the final level of aggregation, sorting, filtering and other operations. For JDBC, C/C++/C#/Python/Go/Node.js interfaces, this module runs on the physical node where the application is located. At the same time, in order to support the fully distributed RESTful interface, TAOSC has a running instance on each dnode of TDengine cluster. + +### Node Communication + +**Communication mode**: The communication among each data node of TDengine system, and among the client driver and each data node is carried out through TCP/UDP. Considering an IoT scenario, the data writing packets are generally not large, so TDengine uses UDP in addition to TCP for transmission, because UDP is more efficient and is not limited by the number of connections. TDengine implements its own timeout, retransmission, confirmation and other mechanisms to ensure reliable transmission of UDP. For packets with a data volume of less than 15K, UDP is adopted for transmission, and TCP is automatically adopted for transmission of packets with a data volume of more than 15K or query operations. At the same time, TDengine will automatically compress/decompress the data, digitally sign/authenticate the data according to the configuration and data packet. For data replication among data nodes, only TCP is used for data transportation. + +**FQDN configuration:** A data node has one or more FQDNs, which can be specified in the system configuration file taos.cfg with the parameter “fqdn”. If it is not specified, the system will automatically use the hostname of the computer as its FQDN. If the node is not configured with FQDN, you can directly set the configuration parameter “fqdn” of the node to its IP address. However, IP is not recommended because IP address may be changed, and once it changes, the cluster will not work properly. The EP (End Point) of a data node consists of FQDN + Port. With FQDN, it is necessary to ensure the DNS service is running, or hosts files on nodes are configured properly. + +**Port configuration**: The external port of a data node is determined by the system configuration parameter “serverPort” in TDengine, and the port for internal communication of cluster is serverPort+5. The data replication operation among data nodes in the cluster also occupies a TCP port, which is serverPort+10. In order to support multithreading and efficient processing of UDP data, each internal and external UDP connection needs to occupy 5 consecutive ports. Therefore, the total port range of a data node will be serverPort to serverPort + 10, for a total of 11 TCP/UDP ports. To run the system, make sure that the firewall keeps these ports open. Each data node can be configured with a different serverPort. + +**Cluster external connection**: TDengine cluster can accommodate a single, multiple or even thousands of data nodes. The application only needs to initiate a connection to any data node in the cluster. The network parameter required for connection is the End Point (FQDN plus configured port number) of a data node. When starting the application taos through CLI, the FQDN of the data node can be specified through the option `-h`, and the configured port number can be specified through `-p`. If the port is not configured, the system configuration parameter “serverPort” of TDengine will be adopted. + +**Inter-cluster communication**: Data nodes connect with each other through TCP/UDP. When a data node starts, it will obtain the EP information of the dnode where the mnode is located, and then establish a connection with the mnode in the system to exchange information. There are three steps to obtain EP information of the mnode: + +1. Check whether the mnodeEpList file exists, if it does not exist or cannot be opened normally to obtain EP information of the mnode, skip to the second step; +2. Check the system configuration file taos.cfg to obtain node configuration parameters “firstEp” and “secondEp” (the node specified by these two parameters can be a normal node without mnode, in this case, the node will try to redirect to the mnode node when connected). If these two configuration parameters do not exist or do not exist in taos.cfg, or are invalid, skip to the third step; +3. Set your own EP as a mnode EP and run it independently. After obtaining the mnode EP list, the data node initiates the connection. It will successfully join the working cluster after connection. If not successful, it will try the next item in the mnode EP list. If all attempts are made, but the connection still fails, sleep for a few seconds before trying again. + +**The choice of MNODE**: TDengine logically has a management node, but there is no separate execution code. The server-side only has one set of execution code, taosd. So which data node will be the management node? This is determined automatically by the system without any manual intervention. The principle is as follows: when a data node starts, it will check its End Point and compare it with the obtained mnode EP List. If its EP exists in it, the data node shall start the mnode module and become a mnode. If your own EP is not in the mnode EP List, the mnode module will not start. During the system operation, due to load balancing, downtime and other reasons, mnode may migrate to the new dnode, totally transparently and without manual intervention. The modification of configuration parameters is the decision made by mnode itself according to resources usage. + +**Add new data nodes:** After the system has a data node, it has become a working system. There are two steps to add a new node into the cluster. +- Step1: Connect to the existing working data node using TDengine CLI, and then add the End Point of the new data node with the command "create dnode" +- Step 2: In the system configuration parameter file taos.cfg of the new data node, set the “firstEp” and “secondEp” parameters to the EP of any two data nodes in the existing cluster. Please refer to the user tutorial for detailed steps. In this way, the cluster will be established step by step. + +**Redirection**: Regardless of dnode or TAOSC, the connection to the mnode is initiated first. The mnode is automatically created and maintained by the system, so the user does not know which dnode is running the mnode. TDengine only requires a connection to any working dnode in the system. Because any running dnode maintains the currently running mnode EP List, when receiving a connecting request from the newly started dnode or TAOSC, if it’s not an mnode itself, it will reply to the mnode with the EP List. After receiving this list, TAOSC or the newly started dnode will try to establish the connection again. When the mnode EP List changes, each data node quickly obtains the latest list and notifies TAOSC through messaging interaction among nodes. + +### A Typical Data Writing Process + +To explain the relationship between vnode, mnode, TAOSC and application and their respective roles, the following is an analysis of a typical data writing process. + +![typical process of TDengine Database](message.webp) +
Figure 2: Typical process of TDengine
+ +1. Application initiates a request to insert data through JDBC, ODBC, or other APIs. +2. TAOSC checks the cache to see if meta data exists for the table. If it does, it goes straight to Step 4. If not, TAOSC sends a get meta-data request to mnode. +3. Mnode returns the meta-data of the table to TAOSC. Meta-data contains the schema of the table, and also the vgroup information to which the table belongs (the vnode ID and the End Point of the dnode where the table belongs. If the number of replicas is N, there will be N groups of End Points). If TAOSC does not receive a response from the mnode for a long time, and there are multiple mnodes, TAOSC will send a request to the next mnode. +4. TAOSC initiates an insert request to master vnode. +5. After vnode inserts the data, it gives a reply to TAOSC, indicating that the insertion is successful. If TAOSC doesn't get a response from vnode for a long time, TAOSC will treat this node as offline. In this case, if there are multiple replicas of the inserted database, TAOSC will issue an insert request to the next vnode in vgroup. +6. TAOSC notifies APP that writing is successful. + +For Step 2 and 3, when TAOSC starts, it does not know the End Point of mnode, so it will directly initiate a request to the configured serving End Point of the cluster. If the dnode that receives the request does not have a mnode configured, it will reply with the mnode EP list, so that TAOSC will re-issue a request to obtain meta-data to the EP of another mnode. + +For Step 4 and 5, without caching, TAOSC can't recognize the master in the virtual node group, so assumes that the first vnode is the master and sends a request to it. If this vnode is not the master, it will reply to the actual master as a new target to which TAOSC shall send a request. Once a response of successful insertion is obtained, TAOSC will cache the information of master node. + +The above describes the process of inserting data. The processes of querying and computing are the same. TAOSC encapsulates and hides all these complicated processes, and it is transparent to applications. + +Through TAOSC caching mechanism, mnode needs to be accessed only when a table is accessed for the first time, so mnode will not become a system bottleneck. However, because schema and vgroup may change (such as load balancing), TAOSC will interact with mnode regularly to automatically update the cache. + +## Storage Model and Data Partitioning/Sharding + +### Storage Model + +The data stored by TDengine includes collected time-series data, metadata related to database and tables, tag data, etc. All of the data is specifically divided into three parts: + +- Time-series data: stored in vnode and composed of data, head and last files. The amount of data is large and query amount depends on the application scenario. Out-of-order writing is allowed, but delete operation is not supported for the time being, and update operation is only allowed when database “update” parameter is set to 1. By adopting the model with **one table for each data collection point**, the data of a given time period is continuously stored, and the writing against one single table is a simple appending operation. Multiple records can be read at one time, thus ensuring the best performance for both insert and query operations of a single data collection point. +- Tag data: meta files stored in vnode. Four standard operations of create, read, update and delete are supported. The amount of data is not large. If there are N tables, there are N records, so all can be stored in memory. To make tag filtering efficient, TDengine supports multi-core and multi-threaded concurrent queries. As long as the computing resources are sufficient, even with millions of tables, the tag filtering results will return in milliseconds. +- Metadata: stored in mnode and includes system node, user, DB, table schema and other information. Four standard operations of create, delete, update and read are supported. The amount of this data is not large and can be stored in memory. Moreover, the number of queries is not large because of client cache. Even though TDengine uses centralized storage management, because of the architecture, there is no performance bottleneck. + +Compared with the typical NoSQL storage model, TDengine stores tag data and time-series data completely separately. This has two major advantages: + +- Reduces the redundancy of tag data storage significantly. General NoSQL database or time-series database adopts K-V (key-value) storage, in which the key includes a timestamp, a device ID and various tags. Each record carries these duplicated tags, so storage space is wasted. Moreover, if the application needs to add, modify or delete tags on historical data, it has to traverse the data and rewrite them again, which is an extremely expensive operation. +- Aggregate data efficiently between multiple tables: when aggregating data between multiple tables, it first finds the tables which satisfy the filtering conditions, and then finds the corresponding data blocks of these tables. This greatly reduces the data sets to be scanned which in turn improves the aggregation efficiency. Moreover, tag data is managed and maintained in a full-memory structure, and tag data queries in tens of millions can return in milliseconds. + +### Data Sharding + +For large-scale data management, to achieve scale-out, it is generally necessary to adopt a Partitioning or Sharding strategy. TDengine implements data sharding via vnode, and time-series data partitioning via one data file for a time range. + +VNode (Virtual Data Node) is responsible for providing writing, query and computing functions for collected time-series data. To facilitate load balancing, data recovery and support heterogeneous environments, TDengine splits a data node into multiple vnodes according to its computing and storage resources. The management of these vnodes is done automatically by TDengine and is completely transparent to the application. + +For a single data collection point, regardless of the amount of data, a vnode (or vnode group, if the number of replicas is greater than 1) has enough computing resource and storage resource to process (if a 16-byte record is generated per second, the original data generated in one year will be less than 0.5 G). So TDengine stores all the data of a table (a data collection point) in one vnode instead of distributing the data to two or more dnodes. Moreover, a vnode can store data from multiple data collection points (tables), and the upper limit of the tables’ quantity for a vnode is one million. By design, all tables in a vnode belong to the same DB. On a data node, unless specially configured, the number of vnodes owned by a DB will not exceed the number of system cores. + +When creating a DB, the system does not allocate resources immediately. However, when creating a table, the system will check if there is an allocated vnode with free tablespace. If so, the table will be created in the vacant vnode immediately. If not, the system will create a new vnode on a dnode from the cluster according to the current workload, and then a table. If there are multiple replicas of a DB, the system does not create only one vnode, but a vgroup (virtual data node group). The system has no limit on the number of vnodes, which is just limited by the computing and storage resources of physical nodes. + +The meta data of each table (including schema, tags, etc.) is also stored in vnode instead of centralized storage in mnode. In fact, this means sharding of meta data, which is good for efficient and parallel tag filtering operations. + +### Data Partitioning + +In addition to vnode sharding, TDengine partitions the time-series data by time range. Each data file contains only one time range of time-series data, and the length of the time range is determined by the database configuration parameter `“days”`. This method of partitioning by time range is also convenient to efficiently implement data retention policies. As long as the data file exceeds the specified number of days (system configuration parameter `“keep”`), it will be automatically deleted. Moreover, different time ranges can be stored in different paths and storage media, so as to facilitate tiered-storage. Cold/hot data can be stored in different storage media to significantly reduce storage costs. + +In general, **TDengine splits big data by vnode and time range in two dimensions** to manage the data efficiently with horizontal scalability. + +### Load Balancing + +Each dnode regularly reports its status (including hard disk space, memory size, CPU, network, number of virtual nodes, etc.) to the mnode (virtual management node) so that the mnode knows the status of the entire cluster. Based on the overall status, when the mnode finds a dnode is overloaded, it will migrate one or more vnodes to other dnodes. During the process, TDengine services keep running and the data insertion, query and computing operations are not affected. + +If the mnode has not received the dnode status for a period of time, the dnode will be treated as offline. If the dnode stays offline beyond the time configured by parameter `“offlineThreshold”`, the dnode will be forcibly removed from the cluster by mnode. If the number of replicas of vnodes on this dnode is greater than one, the system will automatically create new replicas on other dnodes to ensure the replica number. If there are other mnodes on this dnode and the number of mnodes replicas is greater than one, the system will automatically create new mnodes on other dnodes to ensure the replica number. + +When new data nodes are added to the cluster, with new computing and storage resources, the system will automatically start the load balancing process. + +The load balancing process does not require any manual intervention, and it is transparent to the application. **Note: load balancing is controlled by parameter “balance”, which determines to turn on/off automatic load balancing.** + +## Data Writing and Replication Process + +If a database has N replicas, a virtual node group has N virtual nodes. But only one is the Master and all others are slaves. When the application writes a new record to system, only the Master vnode can accept the writing request. If a slave vnode receives a writing request, the system will notifies TAOSC to redirect. + +### Master vnode Writing Process + +Master Vnode uses a writing process as follows: + +![TDengine Database Master Writing Process](write_master.webp) +
Figure 3: TDengine Master writing process
+ +1. Master vnode receives the application data insertion request, verifies, and moves to next step; +2. If the system configuration parameter `“walLevel”` is greater than 0, vnode will write the original request packet into database log file WAL. If walLevel is set to 2 and fsync is set to 0, TDengine will make WAL data written immediately to ensure that even system goes down, all data can be recovered from database log file; +3. If there are multiple replicas, vnode will forward data packet to slave vnodes in the same virtual node group, and the forwarded packet has a version number with data; +4. Write into memory and add the record to “skip list”; +5. Master vnode returns a confirmation message to the application, indicating a successful write. +6. If any of Step 2, 3 or 4 fails, the error will directly return to the application. + +### Slave vnode Writing Process + +For a slave vnode, the write process as follows: + +![TDengine Database Slave Writing Process](write_slave.webp) +
Figure 4: TDengine Slave Writing Process
+ +1. Slave vnode receives a data insertion request forwarded by Master vnode; +2. If the system configuration parameter `“walLevel”` is greater than 0, vnode will write the original request packet into database log file WAL. If walLevel is set to 2 and fsync is set to 0, TDengine will make WAL data written immediately to ensure that even system goes down, all data can be recovered from database log file; +3. Write into memory and add the record to “skip list”. + +Compared with Master vnode, slave vnode has no forwarding or reply confirmation step, means two steps less. But writing into memory and WAL is exactly the same. + +### Remote Disaster Recovery and IDC (Internet Data Center) Migration + +As discussed above, TDengine writes using Master and Slave processes. TDengine adopts asynchronous replication for data synchronization. This method can greatly improve write performance, with no obvious impact from network delay. By configuring IDC and rack number for each physical node, it can be ensured that for a virtual node group, virtual nodes are composed of physical nodes from different IDC and different racks, thus implementing remote disaster recovery without other tools. + +On the other hand, TDengine supports dynamic modification of the replica number. Once the number of replicas increases, the newly added virtual nodes will immediately enter the data synchronization process. After synchronization is complete, added virtual nodes can provide services. In the synchronization process, master and other synchronized virtual nodes keep serving. With this feature, TDengine can provide IDC migration without service interruption. It is only necessary to add new physical nodes to the existing IDC cluster, and then remove old physical nodes after the data synchronization is completed. + +However, the asynchronous replication has a very low probability scenario where data may be lost. The specific scenario is as follows: + +1. Master vnode has finished its 5-step operations, confirmed the success of writing to APP, and then goes down; +2. Slave vnode receives the write request, then processing fails before writing to the log in Step 2; +3. Slave vnode will become the new master, thus losing one record. + +In theory, for asynchronous replication, there is no guarantee to prevent data loss. However, this is an extremely low probability scenario as described above. + +Note: Remote disaster recovery and no-downtime IDC migration are only supported by Enterprise Edition. **Hint: This function is not available yet** + +### Master/slave Selection + +Vnode maintains a version number. When memory data is persisted, the version number will also be persisted. For each data update operation, whether it is time-series data or metadata, this version number will be increased by one. + +When a vnode starts, the roles (master, slave) are uncertain, and the data is in an unsynchronized state. It’s necessary to establish TCP connections with other nodes in the virtual node group and exchange status, including version and its own roles. Through the exchange, the system implements a master-selection process. The rules are as follows: + +1. If there’s only one replica, it’s always master +2. When all replicas are online, the one with latest version is master +3. Over half of online nodes are virtual nodes, and some virtual node is slave, it will automatically become master +4. For 2 and 3, if multiple virtual nodes meet the requirement, the first vnode in virtual node group list will be selected as master. + +### Synchronous Replication + +For scenarios with strong data consistency requirements, asynchronous data replication is not applicable, because there is a small probability of data loss. So, TDengine provides a synchronous replication mechanism for users. When creating a database, in addition to specifying the number of replicas, user also needs to specify a new parameter “quorum”. If quorum is greater than one, it means that every time the Master forwards a message to the replica, it needs to wait for “quorum-1” reply confirms before informing the application that data has been successfully written in slave. If “quorum-1” reply confirms are not received within a certain period of time, the master vnode will return an error to the application. + +With synchronous replication, performance of system will decrease and latency will increase. Because metadata needs strong consistency, the default for data synchronization between mnodes is synchronous replication. + +## Caching and Persistence + +### Caching + +TDengine adopts a time-driven cache management strategy (First-In-First-Out, FIFO), also known as a Write-driven Cache Management Mechanism. This strategy is different from the read-driven data caching mode (Least-Recent-Used, LRU), which directly puts the most recently written data in the system buffer. When the buffer reaches a threshold, the earliest data are written to disk in batches. Generally speaking, for the use of IoT data, users are most concerned about the most recently generated data, that is, the current status. TDengine takes full advantage of this feature to put the most recently arrived (current state) data in the buffer. + +TDengine provides millisecond-level data collecting capability to users through query functions. Putting the recently arrived data directly in the buffer can respond to users' analysis query for the latest piece or batch of data more quickly, and provide faster database query response capability as a whole. In this sense, **TDengine can be used as a data cache by setting appropriate configuration parameters without deploying Redis or other additional cache systems**. This can effectively simplify the system architecture and reduce operational costs. It should be noted that after TDengine is restarted, the buffer of the system will be emptied, the previously cached data will be written to disk in batches, and the previously cached data will not be reloaded into the buffer. In this sense, TDengine's cache differs from proprietary key-value cache systems. + +Each vnode has its own independent memory, and it is composed of multiple memory blocks of fixed size, and different vnodes are completely isolated. When writing data, similar to the writing of logs, data is sequentially added to memory, but each vnode maintains its own skip list for quick search. When more than one third of the memory block are used, the disk writing operation will start, and the subsequent writing operation is carried out in a new memory block. By this design, one third of the memory blocks in a vnode keep the latest data, so as to achieve the purpose of caching and quick search. The number of memory blocks of a vnode is determined by the configuration parameter “blocks”, and the size of memory blocks is determined by the configuration parameter “cache”. + +### Persistent Storage + +TDengine uses a data-driven method to write the data from buffer into hard disk for persistent storage. When the cached data in vnode reaches a certain volume, TDengine will pull up the disk-writing thread to write the cached data into persistent storage so that subsequent data writing is not blocked. TDengine will open a new database log file when the data is written, and delete the old database log file after successfull persistence, to avoid unlimited log growth. + +To make full use of the characteristics of time-series data, TDengine splits the data stored in persistent storage by a vnode into multiple files, each file only saves data for a fixed number of days, which is determined by the system configuration parameter `“days”`. Thus for given start and end dates of a query, you can locate the data files to open immediately without any index. This greatly speeds up read operations. + +For time-series data, there is generally a retention policy, which is determined by the system configuration parameter `“keep”`. Data files exceeding this set number of days will be automatically deleted by the system to free up storage space. + +Given “days” and “keep” parameters, the total number of data files in a vnode is: keep/days. The total number of data files should not be too large or too small. 10 to 100 is appropriate. Based on this principle, reasonable days can be set. In the current version, parameter “keep” can be modified, but parameter “days” cannot be modified once it is set. + +In each data file, the data of a table is stored in blocks. A table can have one or more data file blocks. In a file block, data is stored in columns, occupying a continuous storage space, thus greatly improving the reading speed. The size of file block is determined by the system parameter `“maxRows”` (the maximum number of records per block), and the default value is 4096. This value should not be too large or too small. If it is too large, data location for queries will take a longer tim. If it is too small, the index of data block is too large, and the compression efficiency will be low with slower reading speed. + +Each data file (with a .data postfix) has a corresponding index file (with a .head postfix). The index file has summary information of a data block for each table, recording the offset of each data block in the data file, start and end time of data and other information which allows the system to locate the data to be found very quickly. Each data file also has a corresponding last file (with a .last postfix), which is designed to prevent data block fragmentation when written in disk. If the number of written records from a table does not reach the system configuration parameter `“minRows”` (minimum number of records per block), it will be stored in the last file first. At the next write operation to the disk, the newly written records will be merged with the records in last file and then written into data file. + +When data is written to disk, the system decideswhether to compress the data based on the system configuration parameter `“comp”`. TDengine provides three compression options: no compression, one-stage compression and two-stage compression, corresponding to comp values of 0, 1 and 2 respectively. One-stage compression is carried out according to the type of data. Compression algorithms include delta-delta coding, simple 8B method, zig-zag coding, LZ4 and other algorithms. Two-stage compression is based on one-stage compression and compressed by general compression algorithm, which has higher compression ratio. + +### Tiered Storage + +By default, TDengine saves all data in /var/lib/taos directory, and the data files of each vnode are saved in a different directory under this directory. In order to expand the storage space, minimize the bottleneck of file reading and improve the data throughput rate, TDengine can configure the system parameter “dataDir” to allow multiple mounted hard disks to be used by system at the same time. In addition, TDengine also provides the function of tiered data storage, i.e. storage on different storage media according to the time stamps of data files. For example, the latest data is stored on SSD, the data older than a week is stored on local hard disk, and data older than four weeks is stored on network storage device. This reduces storage costs and ensures efficient data access. The movement of data on different storage media is automatically done by the system and is completely transparent to applications. Tiered storage of data is also configured through the system parameter “dataDir”. + +dataDir format is as follows: +``` +dataDir data_path [tier_level] +``` + +Where data_path is the folder path of mount point and tier_level is the media storage-tier. The higher the media storage-tier, means the older the data file. Multiple hard disks can be mounted at the same storage-tier, and data files on the same storage-tier are distributed on all hard disks within the tier. TDengine supports up to 3 tiers of storage, so tier_level values are 0, 1, and 2. When configuring dataDir, there must be only one mount path without specifying tier_level, which is called special mount disk (path). The mount path defaults to level 0 storage media and contains special file links, which cannot be removed, otherwise it will have a devastating impact on the written data. + +Suppose there is a physical node with six mountable hard disks/mnt/disk1,/mnt/disk2, …,/mnt/disk6, where disk1 and disk2 need to be designated as level 0 storage media, disk3 and disk4 are level 1 storage media, and disk5 and disk6 are level 2 storage media. Disk1 is a special mount disk, you can configure it in/etc/taos/taos.cfg as follows: + +``` +dataDir /mnt/disk1/taos +dataDir /mnt/disk2/taos 0 +dataDir /mnt/disk3/taos 1 +dataDir /mnt/disk4/taos 1 +dataDir /mnt/disk5/taos 2 +dataDir /mnt/disk6/taos 2 +``` + +Mounted disks can also be a non-local network disk, as long as the system can access it. + +Note: Tiered Storage is only supported in Enterprise Edition + +## Data Query + +TDengine provides a variety of query processing functions for tables and STables. In addition to common aggregation queries, TDengine also provides window queries and statistical aggregation functions for time-series data. Query processing in TDengine needs the collaboration of client, vnode and mnode. + +### Single Table Query + +The parsing and verification of SQL statements are completed on the client side. SQL statements are parsed and generate an Abstract Syntax Tree (AST), which is then checksummed. Then metadata information (table metadata) for the table specified is requested in the query from management node (mnode). + +According to the End Point information in metadata information, the query request is serialized and sent to the data node (dnode) where the table is located. After receiving the query, the dnode identifies the virtual node (vnode) pointed to and forwards the message to the query execution queue of the vnode. The query execution thread of vnode establishes the basic query execution environment, immediately returns the query request and starts executing the query at the same time. + +When client obtains query result, the worker thread in query execution queue of dnode will wait for the execution of vnode execution thread to complete before returning the query result to the requesting client. + +### Aggregation by Time Axis, Downsampling, Interpolation + +Time-series data is different from ordinary data in that each record has a timestamp. So aggregating data by timestamps on the time axis is an important and distinct feature of time-series databases which is different from that of common databases. It is similar to the window query of stream computing engines. + +The keyword `interval` is introduced into TDengine to split fixed length time windows on the time axis. The data is aggregated based on time windows, and the data within time window ranges is aggregated as needed. For example: + +```mysql +select count(*) from d1001 interval(1h); +``` + +For the data collected by device D1001, the number of records stored per hour is returned by a 1-hour time window. + +In application scenarios where query results need to be obtained continuously, if there is data missing in a given time interval, the data results in this interval will also be lost. TDengine provides a strategy to interpolate the results of timeline aggregation calculation. The results of time axis aggregation can be interpolated by using keyword Fill. For example: + +```mysql +select count(*) from d1001 interval(1h) fill(prev); +``` + +For the data collected by device D1001, the number of records per hour is counted. If there is no data in a certain hour, statistical data of the previous hour is returned. TDengine provides forward interpolation (prev), linear interpolation (linear), NULL value populating (NULL), and specific value populating (value). + +### Multi-table Aggregation Query + +TDengine creates a separate table for each data collection point, but in practical applications, it is often necessary to aggregate data from different data collection points. In order to perform aggregation operations efficiently, TDengine introduces the concept of STable (super table). STable is used to represent a specific type of data collection point. It is a table set containing multiple tables. The schema of each table in the set is the same, but each table has its own static tag. There can be multiple tags which can be added, deleted and modified at any time. Applications can aggregate or statistically operate on all or a subset of tables under a STABLE by specifying tag filters. This greatly simplifies the development of applications. The process is shown in the following figure: + +![TDengine Database Diagram of multi-table aggregation query](multi_tables.webp) +
Figure 5: Diagram of multi-table aggregation query
+ +1. Application sends a query condition to system; +2. TAOSC sends the STable name to Meta Node(management node); +3. Management node sends the vnode list owned by the STable back to TAOSC; +4. TAOSC sends the computing request together with tag filters to multiple data nodes corresponding to these vnodes; +5. Each vnode first finds the set of tables within its own node that meet the tag filters from memory, then scans the stored time-series data, completes corresponding aggregation calculations, and returns result to TAOSC; +6. TAOSC finally aggregates the results returned by multiple data nodes and send them back to application. + +Since TDengine stores tag data and time-series data separately in vnode, by filtering tag data in memory, the set of tables that need to participate in aggregation operation is first found, which reduces the volume of data to be scanned and improves aggregation speed. At the same time, because the data is distributed in multiple vnodes/dnodes, the aggregation operation is carried out concurrently in multiple vnodes, which further improves the aggregation speed. Aggregation functions for ordinary tables and most operations are applicable to STables. The syntax is exactly the same. Please see TAOS SQL for details. + +### Precomputation + +In order to effectively improve the performance of query processing, based-on the unchangeable feature of IoT data, statistical information of data stored in data block is recorded in the head of data block, including max value, min value, and sum. We call it a precomputing unit. If the query processing involves all the data of a whole data block, the pre-calculated results are directly used, and no need to read the data block contents at all. Since the amount of pre-calculated data is much smaller than the actual size of data block stored on disk, for query processing with disk IO as bottleneck, the use of pre-calculated results can greatly reduce the pressure of reading IO and accelerate the query process. The precomputation mechanism is similar to the BRIN (Block Range Index) of PostgreSQL. + diff --git a/docs-en/21-tdinternal/30-iot-big-data.md b/docs/en/21-tdinternal/30-iot-big-data.md similarity index 100% rename from docs-en/21-tdinternal/30-iot-big-data.md rename to docs/en/21-tdinternal/30-iot-big-data.md diff --git a/docs/en/21-tdinternal/_category_.yml b/docs/en/21-tdinternal/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..38a7f9a7641200e47868a693f3935216a333f44d --- /dev/null +++ b/docs/en/21-tdinternal/_category_.yml @@ -0,0 +1 @@ +label: Inside TDengine diff --git a/docs/en/21-tdinternal/dnode.webp b/docs/en/21-tdinternal/dnode.webp new file mode 100644 index 0000000000000000000000000000000000000000..a56c7e4594df00a721cb48381d68ca3bc813cdc8 Binary files /dev/null and b/docs/en/21-tdinternal/dnode.webp differ diff --git a/docs/en/21-tdinternal/index.md b/docs/en/21-tdinternal/index.md new file mode 100644 index 0000000000000000000000000000000000000000..999d6f89ff57164d6e0372620504c8ecc9de7c9b --- /dev/null +++ b/docs/en/21-tdinternal/index.md @@ -0,0 +1,10 @@ +--- +title: TDengine Inside +--- + +```mdx-code-block +import DocCardList from '@theme/DocCardList'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + + +``` \ No newline at end of file diff --git a/docs/en/21-tdinternal/message.webp b/docs/en/21-tdinternal/message.webp new file mode 100644 index 0000000000000000000000000000000000000000..a2a42abff3d6e932b41a3abe9feae4a5cc13c9e5 Binary files /dev/null and b/docs/en/21-tdinternal/message.webp differ diff --git a/docs/en/21-tdinternal/modules.webp b/docs/en/21-tdinternal/modules.webp new file mode 100644 index 0000000000000000000000000000000000000000..718a6abccdbe40d4a0df5e3812fe0ab943a7c523 Binary files /dev/null and b/docs/en/21-tdinternal/modules.webp differ diff --git a/docs/en/21-tdinternal/multi_tables.webp b/docs/en/21-tdinternal/multi_tables.webp new file mode 100644 index 0000000000000000000000000000000000000000..8f649e34a3a62d1b11b4403b2e743ff6b5e47be2 Binary files /dev/null and b/docs/en/21-tdinternal/multi_tables.webp differ diff --git a/docs/en/21-tdinternal/replica-forward.webp b/docs/en/21-tdinternal/replica-forward.webp new file mode 100644 index 0000000000000000000000000000000000000000..512efd4eba8f23ad0f8607eaaf5525f51ecdcf0e Binary files /dev/null and b/docs/en/21-tdinternal/replica-forward.webp differ diff --git a/docs/en/21-tdinternal/replica-master.webp b/docs/en/21-tdinternal/replica-master.webp new file mode 100644 index 0000000000000000000000000000000000000000..57030a11f563af2689dbcfd206183f410b121aee Binary files /dev/null and b/docs/en/21-tdinternal/replica-master.webp differ diff --git a/docs/en/21-tdinternal/replica-restore.webp b/docs/en/21-tdinternal/replica-restore.webp new file mode 100644 index 0000000000000000000000000000000000000000..f282c2d4d23f517e3ef08e906cea7e9c5edc0b2a Binary files /dev/null and b/docs/en/21-tdinternal/replica-restore.webp differ diff --git a/docs/en/21-tdinternal/structure.webp b/docs/en/21-tdinternal/structure.webp new file mode 100644 index 0000000000000000000000000000000000000000..b77a42c074b15302b5c3ab889fb550a46dd549b3 Binary files /dev/null and b/docs/en/21-tdinternal/structure.webp differ diff --git a/docs/en/21-tdinternal/vnode.webp b/docs/en/21-tdinternal/vnode.webp new file mode 100644 index 0000000000000000000000000000000000000000..fae3104c89c542c26790b509d12ad56661082c32 Binary files /dev/null and b/docs/en/21-tdinternal/vnode.webp differ diff --git a/docs/en/21-tdinternal/write_master.webp b/docs/en/21-tdinternal/write_master.webp new file mode 100644 index 0000000000000000000000000000000000000000..9624036ed3d46ed60924ead9ce5c61acee0f4652 Binary files /dev/null and b/docs/en/21-tdinternal/write_master.webp differ diff --git a/docs/en/21-tdinternal/write_slave.webp b/docs/en/21-tdinternal/write_slave.webp new file mode 100644 index 0000000000000000000000000000000000000000..7c45dec11b00e6a738de458f9e1bedacfad75a96 Binary files /dev/null and b/docs/en/21-tdinternal/write_slave.webp differ diff --git a/docs/en/25-application/01-telegraf.md b/docs/en/25-application/01-telegraf.md new file mode 100644 index 0000000000000000000000000000000000000000..d30a23fe1b942e1411e8b5f1320e1c54ae2b407f --- /dev/null +++ b/docs/en/25-application/01-telegraf.md @@ -0,0 +1,83 @@ +--- +sidebar_label: TDengine + Telegraf + Grafana +title: Quickly Build IT DevOps Visualization System with TDengine + Telegraf + Grafana +--- + +## Background + +TDengine is a big data platform designed and optimized for IoT (Internet of Things), Vehicle Telemetry, Industrial Internet, IT DevOps and other applications. Since it was open-sourced in July 2019, it has won the favor of a large number of time-series data developers with its innovative data modeling design, convenient installation, easy-to-use programming interface, and powerful data writing and query performance. + +IT DevOps metric data usually are time sensitive, for example: + +- System resource metrics: CPU, memory, IO, bandwidth, etc. +- Software system metrics: health status, number of connections, number of requests, number of timeouts, number of errors, response time, service type, and other business-related metrics. + +Current mainstream IT DevOps system usually include a data collection module, a data persistent module, and a visualization module; Telegraf and Grafana are one of the most popular data collection modules and visualization modules, respectively. The data persistence module is available in a wide range of options, with OpenTSDB or InfluxDB being the most popular. TDengine, as an emerging time-series big data platform, has the advantages of high performance, high reliability, easy management and easy maintenance. + +This article introduces how to quickly build a TDengine + Telegraf + Grafana based IT DevOps visualization system without writing even a single line of code and by simply modifying a few lines in configuration files. The architecture is as follows. + +![TDengine Database IT-DevOps-Solutions-Telegraf](./IT-DevOps-Solutions-Telegraf.webp) + +## Installation steps + +### Installing Telegraf, Grafana and TDengine + +To install Telegraf, Grafana, and TDengine, please refer to the relevant official documentation. + +### Telegraf + +Please refer to the [official documentation](https://portal.influxdata.com/downloads/). + +### Grafana + +Please refer to the [official documentation](https://grafana.com/grafana/download). + +### TDengine + +Download the latest TDengine-server 2.4.0.x or above from the [Downloads](http://taosdata.com/cn/all-downloads/) page on the TAOSData website and install it. + +## Data Connection Setup + +### Download TDengine plug-in to grafana plug-in directory + +```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 +``` + +### Modify /etc/telegraf/telegraf.conf + +For the configuration method, add the following text to `/etc/telegraf/telegraf.conf`, where `database name` should be the name where you want to store Telegraf data in TDengine, `TDengine server/cluster host`, `username` and `password` please fill in the actual TDengine values. + +```text +[[outputs.http]] + url = "http://:6041/influxdb/v1/write?db=" + method = "POST" + timeout = "5s" + username = "" + password = "" + data_format = "influx" + influx_max_line_bytes = 250 +``` + +Then restart telegraf: + +```bash +sudo systemctl start telegraf +``` + +### Importing the Dashboard + +Log in to the Grafana interface using a web browser at `IP:3000`, with the system's initial username and password being `admin/admin`. +Click on the gear icon on the left and select `Plugins`, you should find the TDengine data source plugin icon. +Click on the plus icon on the left and select `Import` to get the data from `https://github.com/taosdata/grafanaplugin/blob/master/examples/telegraf/grafana/dashboards/telegraf-dashboard-v0.1.0.json`, download the dashboard JSON file and import it. You will then see the dashboard in the following screen. + +![TDengine Database IT-DevOps-Solutions-telegraf-dashboard](./IT-DevOps-Solutions-telegraf-dashboard.webp) + +## Wrap-up + +The above demonstrates how to quickly build a IT DevOps visualization system. Thanks to the new schemaless protocol parsing feature in TDengine version 2.4.0.0 and ability to integrate easily with a large software ecosystem, users can build an efficient and easy-to-use IT DevOps visualization system in just a few minutes. +Please refer to the official documentation and product implementation cases for other features. diff --git a/docs/en/25-application/02-collectd.md b/docs/en/25-application/02-collectd.md new file mode 100644 index 0000000000000000000000000000000000000000..1733ed1b1af8c9375c3773d1ca86831396499a78 --- /dev/null +++ b/docs/en/25-application/02-collectd.md @@ -0,0 +1,104 @@ +--- +sidebar_label: TDengine + collectd/StatsD + Grafana +title: Quickly build an IT DevOps visualization system using TDengine + collectd/StatsD + Grafana +--- + +## Background + +TDengine is a big data platform designed and optimized for IoT (Internet of Things), Vehicle Telemetry, Industrial Internet, IT DevOps and other applications. Since it was open-sourced in July 2019, it has won the favor of a large number of time-series data developers with its innovative data modeling design, convenient installation, easy-to-use programming interface, and powerful data writing and query performance. + +IT DevOps metric data usually are time sensitive, for example: + +- System resource metrics: CPU, memory, IO, bandwidth, etc. +- Software system metrics: health status, number of connections, number of requests, number of timeouts, number of errors, response time, service type, and other business-related metrics. + +The current mainstream IT DevOps visualization system usually contains a data collection module, a data persistence module, and a visual display module. collectd/StatsD, as an old-fashion open source data collection tool, has a wide user base. However, collectd/StatsD has limited functionality, and often needs to be combined with Telegraf, Grafana, and a time-series database to build a complete monitoring system. +The new version of TDengine supports multiple data protocols and can accept data from collectd and StatsD directly, and provides Grafana dashboard for graphical display. + +This article introduces how to quickly build an IT DevOps visualization system based on TDengine + collectd / StatsD + Grafana without writing even a single line of code but by simply modifying a few lines in configuration files. The architecture is shown in the following figure. + +![TDengine Database IT-DevOps-Solutions-Collectd-StatsD](./IT-DevOps-Solutions-Collectd-StatsD.webp) + +## Installation Steps + +To install collectd, StatsD, Grafana, and TDengine, please refer to the official documentation. + +### Installing collectd + +Please refer to the [official documentation](https://collectd.org/documentation.shtml). + +### Installing StatsD + +Please refer to the [official documentation](https://github.com/statsd/statsd). + +### Install Grafana + +Please refer to the [official documentation](https://grafana.com/grafana/download). + +### Install TDengine + +Download the latest TDengine-server 2.4.0.x or above from the [Downloads](http://taosdata.com/cn/all-downloads/) page on the TAOSData website and install it. + +## Data Connection Setup + +### Copy the TDengine plugin to the grafana plugin directory + +```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 +``` + +### Configure collectd + +Add the following to the `/etc/collectd/collectd.conf` file, where the `host` and `port` should be the actual values of the TDengine and taosAdapter configurations. + +```text +LoadPlugin network + + Server "" "" + + +sudo systemctl start collectd +``` + +### Configure StatsD + +Start StatsD after adding the following to the `config.js` file, where the `host` and `port` are the actual values of the TDengine and taosAdapter configurations. + +```text +backends section add ". /backends/repeater" +Add { host:'', port: } to the repeater section +``` + +### Importing the Dashboard + +Use a web browser to access the server running Grafana on port 3000 `host:3000` to log into the Grafana interface with the initial system username and password of `admin/admin`. +Click on the gear icon on the left and select `Plugins`, you should find the TDengine data source plugin icon. + +#### Importing the collectd dashboard + +Download the dashboard json from `https://github.com/taosdata/grafanaplugin/blob/master/examples/collectd/grafana/dashboards/collect-metrics-with-tdengine-v0.1.0.json`, click the plus icon on the left and select Import, follow the instructions to import the JSON file. After that, you can see +The dashboard can be seen in the following screen. + +![TDengine Database IT-DevOps-Solutions-collectd-dashboard](./IT-DevOps-Solutions-collectd-dashboard.webp) + +#### import collectd dashboard + +Download the dashboard json file from `https://github.com/taosdata/grafanaplugin/blob/master/examples/collectd/grafana/dashboards/collect-metrics-with-tdengine-v0.1.0.json`. Download the dashboard json file, click the plus icon on the left side and select `Import`, and follow the interface prompts to select the JSON file to import. After that, you can see +dashboard with the following interface. + +![IT-DevOps-Solutions-collectd-dashboard](./IT-DevOps-Solutions-collectd-dashboard.webp) + +#### Importing the StatsD dashboard + +Download the dashboard json from `https://github.com/taosdata/grafanaplugin/blob/master/examples/statsd/dashboards/statsd-with-tdengine-v0.1.0.json`. Click on the plus icon on the left and select `Import`, and follow the interface prompts to import the JSON file. You will then see the dashboard in the following screen. +![TDengine Database IT-DevOps-Solutions-statsd-dashboard](./IT-DevOps-Solutions-statsd-dashboard.webp) + +## Wrap-up + +TDengine, as an emerging time-series big data platform, has the advantages of high performance, high reliability, easy management and easy maintenance. Thanks to the new schemaless protocol parsing feature in TDengine version 2.4.0.0 and ability to integrate easily with a large software ecosystem, users can build an efficient and easy-to-use IT DevOps visualization system, or adapt an existing system, in just a few minutes. + +For TDengine's powerful data writing and querying performance and other features, please refer to the official documentation and successful product implementation cases. diff --git a/docs/en/25-application/03-immigrate.md b/docs/en/25-application/03-immigrate.md new file mode 100644 index 0000000000000000000000000000000000000000..4d47aec1d76014ba63f6be91004abcc3934769f7 --- /dev/null +++ b/docs/en/25-application/03-immigrate.md @@ -0,0 +1,435 @@ +--- +sidebar_label: OpenTSDB Migration to TDengine +title: Best Practices for Migrating OpenTSDB Applications to TDengine +--- + +As a distributed, scalable, distributed time-series database platform based on HBase, and thanks to its first-mover advantage, OpenTSDB is widely used for monitoring in DevOps. However, as new technologies like cloud computing, microservices, and containerization technology has developed rapidly, Enterprise-level services are becoming more and more diverse and the architecture is becoming more complex. + +As a result, as a DevOps backend for monitoring, OpenTSDB is plagued by performance issues and delayed feature upgrades. This has resulted in increased application deployment costs and reduced operational efficiency. These problems become increasingly severe as the system tries to scale up. + +To meet the fast-growing IoT big data market and technical needs, TAOSData developed an innovative big-data processing product, **TDengine**. + +After learning the advantages of many traditional relational databases and NoSQL databases, stream computing engines, and message queues, TDengine has its unique benefits in time-series big data processing. TDengine can effectively solve the problems currently encountered by OpenTSDB. + +Compared with OpenTSDB, TDengine has the following distinctive features. + +- Data writing and querying performance far exceeds that of OpenTSDB. +- Efficient compression mechanism for time-series data, which compresses to less than 1/5 of the storage space, on disk. +- The installation and deployment are straightforward. A single installation package can complete the installation and deployment and does not rely on other third-party software. The entire installation and deployment process takes a few seconds. +- The built-in functions cover all of OpenTSDB's query functions and TDengine supports more time-series data query functions, scalar functions, and aggregation functions. TDengine also supports advanced query functions such as multiple time-window aggregations, join query, expression operation, multiple group aggregation, user-defined sorting, and user-defined functions. With a SQL-like query language, querying is more straightforward and has no learning cost. +- Supports up to 128 tags, with a total tag length of 16 KB. +- In addition to the REST interface, it also provides interfaces to Java, Python, C, Rust, Go, C# and other languages. Its supports a variety of enterprise-class standard connector protocols such as JDBC. + +Migrating applications originally running on OpenTSDB to TDengine, effectively reduces compute and storage resource consumption and the number of deployed servers. It also significantly reduces operation and maintenance costs, makes operation and maintenance management more straightforward and more accessible, and considerably reduces the total cost of ownership. Like OpenTSDB, TDengine has also been open-sourced. Both the stand-alone version and the cluster version are open-sourced and there is no need to be concerned about the vendor-lock problem. + +We will explain how to migrate OpenTSDB applications to TDengine quickly, securely, and reliably without coding, using the most typical DevOps scenarios. Subsequent chapters will go into more depth to facilitate migration for non-DevOps systems. + +## DevOps Application Quick Migration + +### 1. Typical Application Scenarios + +The following figure (Figure 1) shows the system's overall architecture for a typical DevOps application scenario. + +**Figure 1. Typical architecture in a DevOps scenario** +![TDengine Database IT-DevOps-Solutions-Immigrate-OpenTSDB-Arch](./IT-DevOps-Solutions-Immigrate-OpenTSDB-Arch.webp "Figure 1. Typical architecture in a DevOps scenario") + +In this application scenario, there are Agent tools deployed in the application environment to collect machine metrics, network metrics, and application metrics. There are also data collectors to aggregate information collected by agents, systems for persistent data storage and management, and tools for data visualization (e.g., Grafana, etc.). + +The agents deployed in the application nodes are responsible for providing operational metrics from different sources to collectd/Statsd. And collectd/StatsD is accountable for pushing the aggregated data to the OpenTSDB cluster system and then visualizing the data using the visualization kanban board software, Grafana. + +### 2. Migration Services + +- **TDengine installation and deployment** + +First of all, please install TDengine. Download the latest stable version of TDengine from the official website and install it. For help with using various installation packages, please refer to the blog ["Installation and Uninstallation of TDengine Multiple Installation Packages"](https://www.taosdata.com/blog/2019/08/09/566.html). + +Note that once the installation is complete, do not start the `taosd` service before properly configuring the parameters. + +- **Adjusting the data collector configuration** + +TDengine version 2.4 and later version includes `taosAdapter`. taosAdapter is a stateless, rapidly elastic, and scalable component. taosAdapter supports Influxdb's Line Protocol and OpenTSDB's telnet/JSON writing protocol specification, providing rich data access capabilities, effectively saving user migration costs and reducing the difficulty of user migration. + +Users can flexibly deploy taosAdapter instances, based on their requirements, to improve data writing throughput and provide guarantees for data writes in different application scenarios. + +Through taosAdapter, users can directly write the data collected by `collectd` or `StatsD` to TDengine to achieve easy, convenient and seamless migration in application scenarios. taosAdapter also supports Telegraf, Icinga, TCollector, and node_exporter data. For more details, please refer to [taosAdapter](/reference/taosadapter/). + +If using collectd, modify the configuration file in its default location `/etc/collectd/collectd.conf` to point to the IP address and port of the node where to deploy taosAdapter. For example, assuming the taosAdapter IP address is 192.168.1.130 and port 6046, configure it as follows. + +```html +LoadPlugin write_tsdb + + + Host "192.168.1.130" Port "6046" HostTags "status=production" StoreRates + false AlwaysAppendDS false + + +``` + +You can use collectd and push the data to taosAdapter utilizing the write_tsdb plugin. taosAdapter will call the API to write the data to TDengine. If you are using StatsD, adjust the profile information accordingly. + +- **Tuning the Dashboard system** + +After writing the data to TDengine, you can configure Grafana to visualize the data written to TDengine. To obtain and use the Grafana plugin provided by TDengine, please refer to [Links to other tools](/third-party/grafana). + +TDengine provides two sets of Dashboard templates by default, and users only need to import the templates from the Grafana directory into Grafana to activate their use. + +**Importing Grafana Templates** Figure 2. +![TDengine Database IT-DevOps-Solutions-Immigrate-OpenTSDB-Dashboard](./IT-DevOps-Solutions-Immigrate-OpenTSDB-Dashboard.webp "Figure 2. Importing a Grafana Template") + +With the above steps completed, you have finished replacing OpenTSDB with TDengine. You can see that the whole process is straightforward, there is no need to write any code, and only some configuration files need to be changed. + +### 3. Post-migration architecture + +After completing the migration, the figure below (Figure 3) shows the system's overall architecture. The whole process of the acquisition side, the data writing, and the monitoring and presentation side are all kept stable. There are a few configuration adjustments, which do not involve any critical changes or alterations. Migrating to TDengine from OpenTSDB leads to powerful processing power and query performance. + +In most DevOps scenarios, if you have a small OpenTSDB cluster (3 or fewer nodes) which provides storage and data persistence layer in addition to query capability, you can safely replace OpenTSDB with TDengine. TDengine will save compute and storage resources. With the same compute resource allocation, a single TDengine can meet the service capacity provided by 3 to 5 OpenTSDB nodes. TDengine clustering may be required depending on the scale of the application. + +**Figure 3. System architecture after migration** +![TDengine Database IT-DevOps-Solutions-Immigrate-TDengine-Arch](./IT-DevOps-Solutions-Immigrate-TDengine-Arch.webp "Figure 3. System architecture after migration completion") + +The following chapters provide a more comprehensive and in-depth look at the advanced topics of migrating an OpenTSDB application to TDengine. This will be useful if your application is particularly complex and is not a DevOps application. + +## Migration evaluation and strategy for other scenarios + +### 1. Differences between TDengine and OpenTSDB + +This chapter describes the differences between OpenTSDB and TDengine at the system functionality level. After reading this chapter, you can fully evaluate whether you can migrate some complex OpenTSDB-based applications to TDengine, and what you should pay attention to after migration. + +TDengine currently only supports Grafana for visual kanban rendering, so if your application uses front-end kanban boards other than Grafana (e.g., [TSDash](https://github.com/facebook/tsdash), [Status Wolf](https://github.com/box/StatusWolf), etc.) you cannot directly migrate those front-end kanbans to TDengine. The front-end kanban will need to be ported to Grafana to work correctly. + +TDengine version 2.3.0.x only supports collectd and StatsD as data collection and aggregation software but future versions will provide support for more data collection and aggregation software in the future. If you use other data aggregators on the collection side, your application needs to be ported to these two data aggregation systems to write data correctly. +In addition to the two data aggregator software protocols mentioned above, TDengine also supports writing data directly via InfluxDB's line protocol and OpenTSDB's data writing protocol, JSON format. You can rewrite the logic on the data push side to write data using the line protocols supported by TDengine. + +In addition, if your application uses the following features of OpenTSDB, you need to take into account the following considerations before migrating your application to TDengine. + +1. `/api/stats`: If your application uses this feature to monitor the service status of OpenTSDB, and you have built the relevant logic to link the processing in your application, then this part of the status reading and fetching logic needs to be re-adapted to TDengine. TDengine provides a new mechanism for handling cluster state monitoring to meet the monitoring and maintenance needs of your application. +2. `/api/tree`: If you rely on this feature of OpenTSDB for the hierarchical organization and maintenance of timelines, you cannot migrate it directly to TDengine, which uses a database -> super table -> sub-table hierarchy to organize and maintain timelines, with all timelines belonging to the same super table in the same system hierarchy. But it is possible to simulate a logical multi-level structure of the application through the unique construction of different tag values. +3. `Rollup And PreAggregates`: The use of Rollup and PreAggregates requires the application to decide where to access the Rollup results and, in some scenarios, to access the actual results. The opacity of this structure makes the application processing logic extraordinarily complex and not portable at all. +While TDengine does not currently support automatic downsampling of multiple timelines and preaggregation (for a range of periods), thanks to its high-performance query processing logic, it can provide very high-performance query responses without relying on Rollup and preaggregation (for a range of periods). This makes your application query processing logic straightforward and simple. +4. `Rate`: TDengine provides two functions to calculate the rate of change of values, namely `Derivative` (the result is consistent with the Derivative behavior of InfluxDB) and `IRate` (the result is compatible with the IRate function in Prometheus). However, the results of these two functions are slightly different from that of Rate. But the TDengine functions are more powerful. In addition, TDengine supports all the calculation functions provided by OpenTSDB. TDengine's query functions are much more powerful than those supported by OpenTSDB, which can significantly simplify the processing logic of your application. + +With the above introduction, we believe you should be able to understand the changes brought about by the migration of OpenTSDB to TDengine. And this information will also help you correctly determine whether you should migrate your application to TDengine to experience the powerful and convenient time-series data processing capability provided by TDengine. + +### 2. Migration strategy suggestion + +OpenTSDB-based system migration involves data schema design, system scale estimation, data write transformation, data streaming, and application changes. The two systems should run in parallel for a while and then the historical data should be migrated to TDengine if your application has some functions that strongly depend on the above OpenTSDB features and you do not want to stop using them. +You can also consider keeping the original OpenTSDB system running while using TDengine to provide the primary services. + +## Data model design + +On the one hand, TDengine requires a strict schema definition for its incoming data. On the other hand, the data model of TDengine is richer than that of OpenTSDB, and the multi-valued model is compatible with all single-valued model building requirements. + +Let us now assume a DevOps scenario where we use collectd to collect the underlying metrics of the device, including memory, swap, disk, etc. The schema in OpenTSDB is as follows. + +| metric | value name | type | 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 requires the data stored to have a data schema, i.e., you need to create a super table and specify the schema of the super table before writing the data. For data schema creation, you have two ways to do this: +1) Take advantage of TDengine's native data writing support for OpenTSDB by calling the TDengine API to write (text line or JSON format) and automate the creation of single-value models. This approach does not require significant adjustments to the data writing application, nor does it require converting the written data format. + +At the C level, TDengine provides the `taos_schemaless_insert()` function to write data in OpenTSDB format directly (in early version this function was named `taos_insert_lines()`). Please refer to the sample code `schemaless.c` in the installation package directory as reference. + +(2) Based on a thorough understanding of TDengine's data model, establish a mapping between OpenTSDB and TDengine's data model. Considering that OpenTSDB is a single-value mapping model, we recommended using the single-value model in TDengine for simplicity. But keep in mind that TDengine supports both multi-value and single-value models. + +- **Single-valued model**. + +The steps are as follows: +- Use the name of the metrics as the name of the TDengine super table +- Build with two basic data columns - timestamp and value. The label of the super table is equivalent to the label information of the metrics, and the number of labels is equal to the number of labels of the metrics. +- The names of sub-tables are named with fixed rules: `metric + '_' + tags1_value + '_' + tag2_value + '_' + tag3_value ...` as the sub-table name. + +Create 3 super tables in TDengine. + +```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)); +``` + +For sub-tables use dynamic table creation as shown below. + +```sql +insert into memory_vm130_memory_buffered_collectd using memory tags('vm130', 'memory', ' buffer', 'collectd') values(1632979445, 3.0656); +``` + +The final system will have about 340 sub-tables and three super-tables. Note that if the use of concatenated tagged values causes the sub-table names to exceed the system limit (191 bytes), then some encoding (e.g., MD5) needs to be used to convert them to an acceptable length. + +- **Multi-value model** + +Ideally you should take advantage of TDengine's multi-value modeling capabilities. In that case, you first need to meet the requirement that different collection quantities have the same collection frequency and can reach the **data write side simultaneously via a message queue**, thus ensuring writing multiple metrics at once, using SQL statements. The metric's name is used as the name of the super table to create a multi-column model of data that has the same collection frequency and can arrive simultaneously. The sub-tables are named using a fixed rule. Each of the above metrics contains only one measurement value, so converting it into a multi-value model is impossible. + +## Data triage and application adaptation + +Subscribe to the message queue and start writing data to TDengine. + +After data has been written for a while, you can use SQL statements to check whether the amount of data written meets the expected writing requirements. Use the following SQL statement to count the amount of data. + +```sql +select count(*) from memory +``` + +After completing the query, if the data written does not differ from what is expected and there are no abnormal error messages from the writing program itself, you can confirm that the written data is complete and valid. + +TDengine does not support querying, or data fetching using the OpenTSDB query syntax but does provide a counterpart for each of the OpenTSDB queries. The corresponding query processing can be adapted and applied in a manner obtained by examining Appendix 1. To fully understand the types of queries supported by TDengine, refer to the TDengine user manual. + +TDengine supports the standard JDBC 3.0 interface for manipulating databases, but you can also use other types of high-level language connectors for querying and reading data to suit your application. Please read the user manual for specific operations and usage. + +## Historical Data Migration + +### 1. Use the tool to migrate data automatically + +To facilitate historical data migration, we provide a plug-in for the data synchronization tool DataX, which can automatically write data into TDengine.The automatic data migration of DataX can only support the data migration process of a single value model. + +For the specific usage of DataX and how to use DataX to write data to TDengine, please refer to [DataX-based TDengine Data Migration Tool](https://www.taosdata.com/blog/2021/10/26/3156.html). + +After migrating via DataX, we found that we can significantly improve the efficiency of migrating historical data by starting multiple processes and migrating numerous metrics simultaneously. The following are some records of the migration process. We provide these as a reference for application migration. + +| Number of datax instances (number of concurrent processes) | Migration record speed (pieces/second) | +| ----------------------------- | ------------------- -- | +| 1 | About 139,000 | +| 2 | About 218,000 | +| 3 | About 249,000 | +| 5 | About 295,000 | +| 10 | About 330,000 | + +
(Note: The test data comes from a single-node Intel(R) Core(TM) i7-10700 CPU@2.90GHz 16-core 64G hardware device, the channel and batchSize are 8 and 1000 respectively, and each record contains 10 tags) + +### 2. Manual data migration + +Suppose you need to use the multi-value model for data writing. In that case, you need to develop a tool to export data from OpenTSDB, confirm which timelines can be merged and imported into the same timeline, and then pass the time to import simultaneously through the SQL statement—written to the database. + +Manual migration of data requires attention to the following two issues: + +1) When storing the exported data on the disk, the disk needs to have enough storage space to accommodate the exported data files fully. To avoid running out of disk space, you can adopt a partial import mode in which you preferentially export the timelines belonging to the same super table and then only those files are imported into TDengine. + +2) Under the full load of the system, if there are enough remaining computing and IO resources, establish a multi-threaded import to maximize the efficiency of data migration. Considering the vast load that data parsing brings to the CPU, it is necessary to control the maximum number of parallel tasks to avoid overloading the system when importing historical data. + +Due to the ease of operation of TDengine itself, there is no need to perform index maintenance and data format change processing in the entire process. The whole process only needs to be executed sequentially. + +While importing historical data into TDengine, the two systems should run simultaneously. Once all the data is migrated, switch the query request to TDengine to achieve seamless application switching. + +## Appendix 1: OpenTSDB query function correspondence table + +### Avg + +Equivalent function: avg + +Example: + +```sql +SELECT avg(val) FROM (SELECT first(val) FROM super_table WHERE ts >= startTime and ts <= endTime INTERVAL(20s) Fill(linear)) INTERVAL(20s) +``` + +Remarks: + +1. The value in Interval needs to be the same as the interval value in the outer query. +2. Interpolation processing in TDengine uses subqueries to assist in completion. As shown above, it is enough to specify the interpolation type in the inner query. Since OpenTSDB uses linear interpolation, use `fill(linear)` to declare the interpolation type in TDengine. Some of the functions mentioned below have exactly the same interpolation calculation requirements. +3. The parameter 20s in Interval indicates that the inner query will generate results according to a time window of 20 seconds. In an actual query, it needs to adjust to the time interval between different records. It ensures that interpolation results are equivalent to the original data. +4. Due to the particular interpolation strategy and mechanism of OpenTSDB i.e. interpolation followed by aggregate calculation, it is impossible for the results to be completely consistent with those of TDengine. But in the case of downsampling (Downsample), TDengine and OpenTSDB can obtain consistent results (since OpenTSDB performs aggregation and downsampling queries). + +### Count + +Equivalent function: count + +Example: + +```sql +select count(\*) from super_table_name; +``` + +### Dev + +Equivalent function: stddev + +Example: + +```sql +Select stddev(val) from table_name +``` + +### Estimated percentiles + +Equivalent function: apercentile + +Example: + +```sql +Select apercentile(col1, 50, “t-digest”) from table_name +``` + +Remark: + +1. When calculating estimate percentiles, OpenTSDB uses the t-digest algorithm by default. In order to obtain the same calculation results in TDengine, the algorithm used needs to be specified in the `apercentile()` function. TDengine can support two different percentile calculation algorithms named "default" and "t-digest" respectively. + +### First + +Equivalent function: first + +Example: + +```sql +Select first(col1) from table_name +``` + +### Last + +Equivalent function: last + +Example: + +```sql +Select last(col1) from table_name +``` + +### Max + +Equivalent function: max + +Example: + +```sql +Select max(value) from (select first(val) value from table_name interval(10s) fill(linear)) interval(10s) +``` + +Note: The Max function requires interpolation for the reasons described above. + +### Min + +Equivalent function: min + +Example: + +```sql +Select min(value) from (select first(val) value from table_name interval(10s) fill(linear)) interval(10s); +``` + +### MinMax + +Equivalent function: max + +```sql +Select max(val) from table_name +``` + +Note: This function has no interpolation requirements, so it can be directly calculated. + +### MimMin + +Equivalent function: min + +```sql +Select min(val) from table_name +``` + +Note: This function has no interpolation requirements, so it can be directly calculated. + +### Percentile + +Equivalent function: percentile + +Remark: + +### Sum + +Equivalent function: sum + +```sql +Select max(value) from (select first(val) value from table_name interval(10s) fill(linear)) interval(10s) +``` + +Note: This function has no interpolation requirements, so it can be directly calculated. + +### Zimsum + +Equivalent function: sum + +```sql +Select sum(val) from table_name +``` + +Note: This function has no interpolation requirements, so it can be directly calculated. + +Complete example: + +````json +// OpenTSDB query JSON +query = { +"start": 1510560000, +"end": 1515000009, +"queries": [{ +"aggregator": "count", +"metric": "cpu.usage_user", +}] +} + +// Equivalent query SQL: +SELECT count(*) +FROM `cpu.usage_user` +WHERE ts>=1510560000 AND ts<=1515000009 +```` + +## Appendix 2: Resource Estimation Methodology + +### Data generation environment + +We still use the hypothetical environment from Chapter 4. There are three measurements. Respectively: the data writing rate of temperature and humidity is one record every 5 seconds, and the timeline is 100,000. The writing rate of air pollution is one record every 10 seconds, the timeline is 10,000, and the query request frequency is 500 QPS. + +### Storage resource estimation + +Assuming that the number of sensor devices that generate data and need to be stored is `n`, the frequency of data generation is `t` per second, and the length of each record is `L` bytes, the scale of data generated per day is `n * t * L` bytes. Assuming the compression ratio is `C`, the daily data size is `(n * t * L)/C` bytes. The storage resources are estimated to accommodate the data scale for 1.5 years. In the production environment, the compression ratio C of TDengine is generally between 5 and 7. +With additional 20% redundancy, you can calculate the required storage resources: + +```matlab +(n * t * L) * (365 * 1.5) * (1+20%)/C +```` +Substituting in the above formula, the raw data generated every year is 11.8TB without considering the label information. Note that tag information is associated with each timeline in TDengine, not every record. The amount of data to be recorded is somewhat reduced relative to the generated data, and label data can be ignored as a whole. Assuming a compression ratio of 5, the size of the retained data ends up being 2.56 TB. + +### Storage Device Selection Considerations + +A disk with better random read performance, such as an SSD, improves the system's query performance and improves the query response performance of the whole system. To obtain better query performance, the performance index of the single-threaded random read IOPS of the hard disk device should not be lower than 1000, and it is better to reach 5000 IOPS or more. We recommend using `fio` utility software to evaluate the running performance (please refer to Appendix 1 for specific usage) for the random IO read of the current device to confirm whether it can meet the requirements of random read of large files. + +Hard disk writing performance has little effect on TDengine. The TDengine writing process adopts the append write mode, so as long as it has good sequential write performance, both SAS hard disks and SSDs in the general sense can well meet TDengine's requirements for disk write performance. + +### Computational resource estimates + +Due to the characteristics of IoT data, when the frequency of data generation is consistent, the writing process of TDengine maintains a relatively fixed amount of resource consumption (computing and storage). According to the [TDengine Operation and Maintenance Guide](/operation/) description, the system consumes less than 1 CPU core at 22,000 writes per second. + +In estimating the CPU resources consumed by the query, assuming that the application requires the database to provide 10,000 QPS, the CPU time consumed by each query is about 1 ms. The query provided by each core per second is 1,000 QPS, which satisfies 10,000 QPS. The query request requires at least 10 cores. For the system as a whole system to have less than 50% CPU load, the entire cluster needs twice as many cores i.e. 20 cores. + +### Memory resource estimation + +The database allocates 16MB\*3 buffer memory for each Vnode by default. If the cluster system includes 22 CPU cores, TDengine will create 22 Vnodes (virtual nodes) by default. Each Vnode contains 1000 tables, which is more than enough to accommodate all the tables in our hypothetical scenario. Then it takes about 1.5 hours to write a block, which triggers persistence to disk without requiring any adjustment. A total of 22 Vnodes require about 1GB of memory cache. Considering the memory needed for the query, assuming that the memory overhead of each query is about 50MB, the memory required for 500 queries concurrently is about 25GB. + +In summary, using a single 16-core 32GB machine or a cluster of 2 8-core 16GB machines is enough. + +## Appendix 3: Cluster Deployment and Startup + +TDengine provides a wealth of help documents to explain many aspects of cluster installation and deployment. Here is the list of documents for your reference. + +### Cluster Deployment + +The first is TDengine installation. Download the latest stable version of TDengine from the official website, and install it. Please refer to the blog ["Installation and Uninstallation of Various Installation Packages of TDengine"](https://www.taosdata.com/blog/2019/08/09/566.html) for the various installation package formats. + +Note that once the installation is complete, do not immediately start the `taosd` service, but start it after correctly configuring the parameters. + +### Set running parameters and start the service + +To ensure that the system can obtain the necessary information for regular operation. Please set the following vital parameters correctly on the server: + +FQDN, firstEp, secondEP, dataDir, logDir, tmpDir, serverPort. For the specific meaning and setting requirements of each parameter, please refer to the document "[TDengine Cluster Installation and Management](/cluster/)" + +Follow the same steps to set parameters on the other nodes, start the taosd service, and then add Dnodes to the cluster. + +Finally, start `taos` and execute the `show dnodes` command. If you can see all the nodes that have joined the cluster, the cluster building process was successfully completed. For specific operation procedures and precautions, please refer to the document "[TDengine Cluster Installation and Management](/cluster/)". + +## Appendix 4: Super Table Names + +Since OpenTSDB's metric name has a dot (".") in it, for example, a metric with a name like "cpu.usage_user", the dot has a special meaning in TDengine and is a separator used to separate database and table names. TDengine also provides "escape" characters to allow users to use keywords or special separators (e.g., dots) in (super)table names. To use special characters, enclose the table name in escape characters, e.g.: `cpu.usage_user`. It is a valid (super) table name. + +## Appendix 5: Reference Articles + +1. [Using TDengine + collectd/StatsD + Grafana to quickly build an IT operation and maintenance monitoring system](/application/collectd/) +2. [Write collected data directly to TDengine through collectd](/third-party/collectd/) diff --git a/docs/en/25-application/IT-DevOps-Solutions-Collectd-StatsD.webp b/docs/en/25-application/IT-DevOps-Solutions-Collectd-StatsD.webp new file mode 100644 index 0000000000000000000000000000000000000000..147a65b17bff2aa0e44faa206618bdce5664e1ca Binary files /dev/null and b/docs/en/25-application/IT-DevOps-Solutions-Collectd-StatsD.webp differ diff --git a/docs/en/25-application/IT-DevOps-Solutions-Immigrate-OpenTSDB-Arch.webp b/docs/en/25-application/IT-DevOps-Solutions-Immigrate-OpenTSDB-Arch.webp new file mode 100644 index 0000000000000000000000000000000000000000..3ca99c835b33df8845adf1b52d8fb8eb63076e82 Binary files /dev/null and b/docs/en/25-application/IT-DevOps-Solutions-Immigrate-OpenTSDB-Arch.webp differ diff --git a/docs/en/25-application/IT-DevOps-Solutions-Immigrate-OpenTSDB-Dashboard.webp b/docs/en/25-application/IT-DevOps-Solutions-Immigrate-OpenTSDB-Dashboard.webp new file mode 100644 index 0000000000000000000000000000000000000000..04811f61b9b318e129552d87cd48eabf6e99feab Binary files /dev/null and b/docs/en/25-application/IT-DevOps-Solutions-Immigrate-OpenTSDB-Dashboard.webp differ diff --git a/docs/en/25-application/IT-DevOps-Solutions-Immigrate-TDengine-Arch.webp b/docs/en/25-application/IT-DevOps-Solutions-Immigrate-TDengine-Arch.webp new file mode 100644 index 0000000000000000000000000000000000000000..36930068758556f4de5b58321804a96401c64b22 Binary files /dev/null and b/docs/en/25-application/IT-DevOps-Solutions-Immigrate-TDengine-Arch.webp differ diff --git a/docs/en/25-application/IT-DevOps-Solutions-Telegraf.webp b/docs/en/25-application/IT-DevOps-Solutions-Telegraf.webp new file mode 100644 index 0000000000000000000000000000000000000000..fd5461ec9b37be66cac4c17fb1f81fec76158330 Binary files /dev/null and b/docs/en/25-application/IT-DevOps-Solutions-Telegraf.webp differ diff --git a/docs/en/25-application/IT-DevOps-Solutions-collectd-dashboard.webp b/docs/en/25-application/IT-DevOps-Solutions-collectd-dashboard.webp new file mode 100644 index 0000000000000000000000000000000000000000..879c27a1a5843c714ff3c33c1dccfa32a2154b82 Binary files /dev/null and b/docs/en/25-application/IT-DevOps-Solutions-collectd-dashboard.webp differ diff --git a/docs/en/25-application/IT-DevOps-Solutions-statsd-dashboard.webp b/docs/en/25-application/IT-DevOps-Solutions-statsd-dashboard.webp new file mode 100644 index 0000000000000000000000000000000000000000..1d4c655970b5f3fcb3be2d65d67eb42f08f35862 Binary files /dev/null and b/docs/en/25-application/IT-DevOps-Solutions-statsd-dashboard.webp differ diff --git a/docs/en/25-application/IT-DevOps-Solutions-telegraf-dashboard.webp b/docs/en/25-application/IT-DevOps-Solutions-telegraf-dashboard.webp new file mode 100644 index 0000000000000000000000000000000000000000..105afcdb8312b23675f62ff6339d5e737b5cd958 Binary files /dev/null and b/docs/en/25-application/IT-DevOps-Solutions-telegraf-dashboard.webp differ diff --git a/docs/en/25-application/_category_.yml b/docs/en/25-application/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..772d45e6cf7042e701968fe658b53ef53bd91c62 --- /dev/null +++ b/docs/en/25-application/_category_.yml @@ -0,0 +1 @@ +label: Application Practice diff --git a/docs/en/25-application/index.md b/docs/en/25-application/index.md new file mode 100644 index 0000000000000000000000000000000000000000..5383a00c67c515dc65fd2ed1cac4b218710288b5 --- /dev/null +++ b/docs/en/25-application/index.md @@ -0,0 +1,10 @@ +--- +title: Application Practice +--- + +```mdx-code-block +import DocCardList from '@theme/DocCardList'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + + +``` \ No newline at end of file diff --git a/docs/en/27-train-faq/01-faq.md b/docs/en/27-train-faq/01-faq.md new file mode 100644 index 0000000000000000000000000000000000000000..c10bca1d05edd8cebe451901b3abb91923618a26 --- /dev/null +++ b/docs/en/27-train-faq/01-faq.md @@ -0,0 +1,114 @@ +--- +sidebar_label: FAQ +title: Frequently Asked Questions +--- + +## Submit an Issue + +If the tips in FAQ don't help much, please submit an issue on [GitHub](https://github.com/taosdata/TDengine) to describe your problem. In your description please include the TDengine version, hardware and OS information, the steps to reproduce the problem and any other relevant information. It would be very helpful if you can package the contents in `/var/log/taos` and `/etc/taos` and upload. These two are the default directories used by TDengine. If you have changed the default directories in your configuration, please package the files in your configured directories. We recommended setting `debugFlag` to 135 in `taos.cfg`, restarting `taosd`, then reproducing the problem and collecting the logs. If you don't want to restart, an alternative way of setting `debugFlag` is executing `alter dnode debugFlag 135` command in TDengine CLI `taos`. During normal running, however, please make sure `debugFlag` is set to 131. + +## Frequently Asked Questions + +### 1. How to upgrade to TDengine 2.0 from older version? + +version 2.x is not compatible with version 1.x. With regard to the configuration and data files, please perform the following steps before upgrading. Please follow data integrity, security, backup and other relevant SOPs, best practices before removing/deleting any data. + +1. Delete configuration files: `sudo rm -rf /etc/taos/taos.cfg` +2. Delete log files: `sudo rm -rf /var/log/taos/` +3. Delete data files if the data doesn't need to be kept: `sudo rm -rf /var/lib/taos/` +4. Install latest 2.x version +5. If the data needs to be kept and migrated to newer version, please contact professional service at TDengine for assistance. + +### 2. How to handle "Unable to establish connection"？ + +When the client is unable to connect to the server, you can try the following ways to troubleshoot and resolve the problem. + +1. Check the network + + - Check if the hosts where the client and server are running are accessible to each other, for example by `ping` command. + - Check if the TCP/UDP on port 6030-6042 are open for access if firewall is enabled. If possible, disable the firewall for diagnostics, but please ensure that you are following security and other relevant protocols. + - Check if the FQDN and serverPort are configured correctly in `taos.cfg` used by the server side. + - Check if the `firstEp` is set properly in the `taos.cfg` used by the client side. + +2. Make sure the client version and server version are same. + +3. On server side, check the running status of `taosd` by executing `systemctl status taosd` . If your server is started using another way instead of `systemctl`, use the proper method to check whether the server process is running normally. + +4. If using connector of Python, Java, Go, Rust, C#, node.JS on Linux to connect to the server, please make sure `libtaos.so` is in directory `/usr/local/taos/driver` and `/usr/local/taos/driver` is in system lib search environment variable `LD_LIBRARY_PATH`. + +5. If using connector on Windows, please make sure `C:\TDengine\driver\taos.dll` is in your system lib search path. We recommend putting `taos.dll` under `C:\Windows\System32`. + +6. Some advanced network diagnostics tools + + - On Linux system tool `nc` can be used to check whether the TCP/UDP can be accessible on a specified port + Check whether a UDP port is open: `nc -vuz {hostIP} {port} ` + Check whether a TCP port on server side is open: `nc -l {port}` + Check whether a TCP port on client side is open: `nc {hostIP} {port}` + + - On Windows system `Test-NetConnection -ComputerName {fqdn} -Port {port}` on PowerShell can be used to check whether the port on server side is open for access. + +7. TDengine CLI `taos` can also be used to check network, please refer to [TDengine CLI](/reference/taos-shell). + +### 3. How to handle "Unexpected generic error in RPC" or "Unable to resolve FQDN" ? + +This error is caused because the FQDN can't be resolved. Please try following ways: + +1. Check whether the FQDN is configured properly on the server side +2. If DSN server is configured in the network, please check whether it works; otherwise, check `/etc/hosts` to see whether the FQDN is configured with correct IP +3. If the network configuration on the server side is OK, try to ping the server from the client side. +4. If TDengine has been used before with an old hostname then the hostname has been changed, please check `/var/lib/taos/taos/dnode/dnodeEps.json`. Before setting up a new TDengine cluster, it's better to cleanup the directories configured. + +### 4. "Invalid SQL" is returned even though the Syntax is correct + +"Invalid SQL" is returned when the length of SQL statement exceeds maximum allowed length or the syntax is not correct. + +### 5. Whether validation queries are supported? + +It's suggested to use a builtin database named as `log` to monitor. + + + +### 6. Can I delete a record? + +From version 2.6.0.0 Enterprise version, deleting data can be supported. + +### 7. How to create a table of over 1024 columns? + +From version 2.1.7.0, at most 4096 columns can be defined for a table. + +### 8. How to improve the efficiency of inserting data? + +Inserting data in batch is a good practice. Single SQL statement can insert data for one or multiple tables in batch. + +### 9. JDBC Error： the executed SQL is not a DML or a DDL？ + +Please upgrade to latest JDBC driver, for details please refer to [Java Connector](/reference/connector/java) + +### 10. Failed to connect with error "invalid timestamp" + +The most common reason is that the time setting is not aligned on the client side and the server side. On Linux system, please use `ntpdate` command. On Windows system, please enable automatic sync in system time setting. + +### 11. Table name is not shown in full + +There is a display width setting in TDengine CLI `taos`. It can be controlled by configuration parameter `maxBinaryDisplayWidth`, or can be set using SQL command `set max_binary_display_width`. A more convenient way is to append `\G` in a SQL command to bypass this limitation. + +### 12. How to change log level temporarily? + +Below SQL command can be used to adjust log level temporarily + +```sql +ALTER LOCAL flag_name flag_value; +``` + - flag_name can be: debugFlag，cDebugFlag，tmrDebugFlag，uDebugFlag，rpcDebugFlag + - flag_value can be: 131 (INFO/WARNING/ERROR), 135 (plus DEBUG), 143 (plus TRACE) + + + +### 13. What to do if go compilation fails? + +From version 2.3.0.0, a new component named `taosAdapter` is introduced. Its' developed in Go. If you want to compile from source code and meet go compilation problems, try to do below steps to resolve Go environment problems. + +```sh +go env -w GO111MODULE=on +go env -w GOPROXY=https://goproxy.cn,direct +``` diff --git a/docs/en/27-train-faq/03-docker.md b/docs/en/27-train-faq/03-docker.md new file mode 100644 index 0000000000000000000000000000000000000000..afee13c1377b0b4331d6f7ec20251d1aa2db81a1 --- /dev/null +++ b/docs/en/27-train-faq/03-docker.md @@ -0,0 +1,285 @@ +--- +sidebar_label: TDengine in Docker +title: Deploy TDengine in Docker +--- + +We do not recommend deploying TDengine using Docker in a production system. However, Docker is still very useful in a development environment, especially when your host is not Linux. From version 2.0.14.0, the official image of TDengine can support X86-64, X86, arm64, and rm32 . + +In this chapter we introduce a simple step by step guide to use TDengine in Docker. + +## Install Docker + +To install Docker please refer to [Get Docker](https://docs.docker.com/get-docker/). + +After Docker is installed, you can check whether Docker is installed properly by displaying Docker version. + +```bash +$ docker -v +Docker version 20.10.3, build 48d30b5 +``` + +## Launch TDengine in Docker + +### Launch TDengine Server + +```bash +$ docker run -d -p 6030-6049:6030-6049 -p 6030-6049:6030-6049/udp tdengine/tdengine +526aa188da767ae94b244226a2b2eec2b5f17dd8eff592893d9ec0cd0f3a1ccd +``` + +In the above command, a docker container is started to run TDengine server, the port range 6030-6049 of the container is mapped to host port range 6030-6049. If port range 6030-6049 has been occupied on the host, please change to an available host port range. For port requirements on the host, please refer to [Port Configuration](/reference/config/#serverport). + +- **docker run**: Launch a docker container +- **-d**: the container will run in background mode +- **-p**: port mapping +- **tdengine/tdengine**: The image from which to launch the container +- **526aa188da767ae94b244226a2b2eec2b5f17dd8eff592893d9ec0cd0f3a1ccd**: the container ID if successfully launched. + +Furthermore, `--name` can be used with `docker run` to specify name for the container, `--hostname` can be used to specify hostname for the container, `-v` can be used to mount local volumes to the container so that the data generated inside the container can be persisted to disk on the host. + +```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**: specify the name of the container, the name can be used to specify the container later +- **--hostname=tdengine-server**: specify the hostname inside the container, the hostname can be used inside the container without worrying the container IP may vary +- **-v**: volume mapping between host and container + +### Check the container + +```bash +docker ps +``` + +The output is like below: + +``` +CONTAINER ID IMAGE COMMAND CREATED STATUS ··· +c452519b0f9b tdengine/tdengine "taosd" 14 minutes ago Up 14 minutes ··· +``` + +- **docker ps**: List all the containers +- **CONTAINER ID**: Container ID +- **IMAGE**: The image used for the container +- **COMMAND**: The command used when launching the container +- **CREATED**: When the container was created +- **STATUS**: Status of the container + +### Access TDengine inside container + +```bash +$ docker exec -it tdengine /bin/bash +root@tdengine-server:~/TDengine-server-2.4.0.4# +``` + +- **docker exec**: Attach to the container +- **-i**: Interactive mode +- **-t**: Use terminal +- **tdengine**: Container name, up to the output of `docker ps` +- **/bin/bash**: The command to execute once the container is attached + +Inside the container, start TDengine CLI `taos` + +```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> +``` + +The above example is for a successful connection. If `taos` fails to connect to the server side, error information would be shown. + +In TDengine CLI, SQL commands can be executed to create/drop databases, tables, STables, and insert or query data. For details please refer to [TAOS SQL](/taos-sql/). + +### Access TDengine from host + +If option `-p` used to map ports properly between host and container, it's also able to access TDengine in container from the host as long as `firstEp` is configured correctly for the client on host. + +``` +$ 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> +``` + +It's also able to access the REST interface provided by TDengine in container from the host. + +``` +curl -u root:taosdata -d 'show databases' 127.0.0.1:6041/rest/sql +``` + +Output is like below: + +``` +{"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} +``` + +For details of REST API please refer to [REST API](/reference/rest-api/). + +### Run TDengine server and taosAdapter inside container + +From version 2.4.0.0, in the TDengine Docker image, `taosAdapter` is enabled by default, but can be disabled using environment variable `TAOS_DISABLE_ADAPTER=true` . `taosAdapter` can also be run alone without `taosd` when launching a container. + +For the port mapping of `taosAdapter`, please refer to [taosAdapter](/reference/taosadapter/). + +- Run both `taosd` and `taosAdapter` (by default) in docker container: + +```bash +docker run -d --name tdengine-all -p 6030-6049:6030-6049 -p 6030-6049:6030-6049/udp tdengine/tdengine:2.4.0.4 +``` + +- Run `taosAdapter` only in docker container, `TAOS_FIRST_EP` environment variable needs to be used to specify the container name in which `taosd` is running: + +```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 +``` + +- Run `taosd` only in docker container: + +```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 +``` + +- Verify the REST interface: + +```bash +curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'show databases;' 127.0.0.1:6041/rest/sql +``` + +Below is an example output: + +``` +{"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} +``` + +### Use taosBenchmark on host to access TDengine server in container + +1. Run `taosBenchmark`, named as `taosdemo` previously, on the host: + + ```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 + ``` + + Once the execution is finished, a database `test` is created, a STable `meters` is created in database `test`, 10,000 sub tables are created using `meters` as template, named as "d0" to "d9999", while 10,000 rows are inserted into each table, so totally 100,000,000 rows are inserted. + +2. Check the data + + - **Check database** + + ```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 | ··· + + ``` + + - **Check STable** + + ```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) + + ``` + + - **Check Tables** + + ```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) + + ``` + + - **Check tag values of table d0** + + ```bash + $ taos> select groupid, location from test.d0; + groupid | location | + ================================= + 0 | California.SanDiego | + Query OK, 1 row(s) in set (0.003490s) + ``` + +### Access TDengine from 3rd party tools + +A lot of 3rd party tools can be used to write data into TDengine through `taosAdapter`, for details please refer to [3rd party tools](/third-party/). + +There is nothing different from the 3rd party side to access TDengine server inside a container, as long as the end point is specified correctly, the end point should be the FQDN and the mapped port of the host. + +## Stop TDengine inside container + +```bash +docker stop tdengine +``` + +- **docker stop**: stop a container +- **tdengine**: container name diff --git a/docs/en/27-train-faq/_category_.yml b/docs/en/27-train-faq/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..7a8530c129b90c4ac382168a55c339bbd627cd05 --- /dev/null +++ b/docs/en/27-train-faq/_category_.yml @@ -0,0 +1 @@ +label: FAQ & Others diff --git a/docs/en/27-train-faq/index.md b/docs/en/27-train-faq/index.md new file mode 100644 index 0000000000000000000000000000000000000000..2cb87aab005b0ecc9275b6fe10e267487d38c336 --- /dev/null +++ b/docs/en/27-train-faq/index.md @@ -0,0 +1,10 @@ +--- +title: FAQ & Others +--- + +```mdx-code-block +import DocCardList from '@theme/DocCardList'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + + +``` \ No newline at end of file diff --git a/docs/en/30-release/02-2.6.md b/docs/en/30-release/02-2.6.md new file mode 100644 index 0000000000000000000000000000000000000000..85b76d9999e211336b5859beab3fdfc7988f4fda --- /dev/null +++ b/docs/en/30-release/02-2.6.md @@ -0,0 +1,9 @@ +--- +title: 2.6 +--- + +[2.6.0.4](https://github.com/taosdata/TDengine/releases/tag/ver-2.6.0.4) + +[2.6.0.1](https://github.com/taosdata/TDengine/releases/tag/ver-2.6.0.1) + +[2.6.0.0](https://github.com/taosdata/TDengine/releases/tag/ver-2.6.0.0) diff --git a/docs/en/30-release/03-2.4.md b/docs/en/30-release/03-2.4.md new file mode 100644 index 0000000000000000000000000000000000000000..62580b327a3bd5098e1b7f1162a1c398ac2a5eff --- /dev/null +++ b/docs/en/30-release/03-2.4.md @@ -0,0 +1,29 @@ +--- +title: 2.4 +--- + +[2.4.0.26](https://github.com/taosdata/TDengine/releases/tag/ver-2.4.0.26) + +[2.4.0.25](https://github.com/taosdata/TDengine/releases/tag/ver-2.4.0.25) + +[2.4.0.24](https://github.com/taosdata/TDengine/releases/tag/ver-2.4.0.24) + +[2.4.0.20](https://github.com/taosdata/TDengine/releases/tag/ver-2.4.0.20) + +[2.4.0.18](https://github.com/taosdata/TDengine/releases/tag/ver-2.4.0.18) + +[2.4.0.16](https://github.com/taosdata/TDengine/releases/tag/ver-2.4.0.16) + +[2.4.0.14](https://github.com/taosdata/TDengine/releases/tag/ver-2.4.0.14) + +[2.4.0.12](https://github.com/taosdata/TDengine/releases/tag/ver-2.4.0.12) + +[2.4.0.10](https://github.com/taosdata/TDengine/releases/tag/ver-2.4.0.10) + +[2.4.0.7](https://github.com/taosdata/TDengine/releases/tag/ver-2.4.0.7) + +[2.4.0.5](https://github.com/taosdata/TDengine/releases/tag/ver-2.4.0.5) + +[2.4.0.4](https://github.com/taosdata/TDengine/releases/tag/ver-2.4.0.4) + +[2.4.0.0](https://github.com/taosdata/TDengine/releases/tag/ver-2.4.0.0) diff --git a/docs/en/30-release/_category_.yml b/docs/en/30-release/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..4672fec6fd11d6e06b61e58ebdeb2cfb100ccc5e --- /dev/null +++ b/docs/en/30-release/_category_.yml @@ -0,0 +1 @@ +label: Releases diff --git a/docs/en/30-release/index.md b/docs/en/30-release/index.md new file mode 100644 index 0000000000000000000000000000000000000000..c01c99cdce0190fb04f88d55a09e8cc406d4d8b0 --- /dev/null +++ b/docs/en/30-release/index.md @@ -0,0 +1,10 @@ +--- +title: Releases +--- + +```mdx-code-block +import DocCardList from '@theme/DocCardList'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + + +``` \ No newline at end of file diff --git a/docs-examples/.gitignore b/docs/examples/.gitignore similarity index 100% rename from docs-examples/.gitignore rename to docs/examples/.gitignore diff --git a/docs-examples/.gitignre b/docs/examples/.gitignre similarity index 100% rename from docs-examples/.gitignre rename to docs/examples/.gitignre diff --git a/docs-examples/R/connect_native.r b/docs/examples/R/connect_native.r similarity index 100% rename from docs-examples/R/connect_native.r rename to docs/examples/R/connect_native.r diff --git a/docs-examples/R/connect_rest.r b/docs/examples/R/connect_rest.r similarity index 100% rename from docs-examples/R/connect_rest.r rename to docs/examples/R/connect_rest.r diff --git a/docs-examples/c/.gitignore b/docs/examples/c/.gitignore similarity index 100% rename from docs-examples/c/.gitignore rename to docs/examples/c/.gitignore diff --git a/docs/examples/c/async_query_example.c b/docs/examples/c/async_query_example.c new file mode 100644 index 0000000000000000000000000000000000000000..b370420b124a21b05f8e0b4041fb1461b1e2478a --- /dev/null +++ b/docs/examples/c/async_query_example.c @@ -0,0 +1,195 @@ +// compile with: +// gcc -o async_query_example async_query_example.c -ltaos + +#include +#include +#include +#include +#include +#include + +typedef int16_t VarDataLenT; + +#define TSDB_NCHAR_SIZE sizeof(int32_t) +#define VARSTR_HEADER_SIZE sizeof(VarDataLenT) + +#define GET_FLOAT_VAL(x) (*(float *)(x)) +#define GET_DOUBLE_VAL(x) (*(double *)(x)) + +#define varDataLen(v) ((VarDataLenT *)(v))[0] + +int printRow(char *str, TAOS_ROW row, TAOS_FIELD *fields, int numFields) { + int len = 0; + char split = ' '; + + for (int i = 0; i < numFields; ++i) { + if (i > 0) { + str[len++] = split; + } + + if (row[i] == NULL) { + len += sprintf(str + len, "%s", "NULL"); + continue; + } + + switch (fields[i].type) { + case TSDB_DATA_TYPE_TINYINT: + len += sprintf(str + len, "%d", *((int8_t *)row[i])); + break; + + case TSDB_DATA_TYPE_UTINYINT: + len += sprintf(str + len, "%u", *((uint8_t *)row[i])); + break; + + case TSDB_DATA_TYPE_SMALLINT: + len += sprintf(str + len, "%d", *((int16_t *)row[i])); + break; + + case TSDB_DATA_TYPE_USMALLINT: + len += sprintf(str + len, "%u", *((uint16_t *)row[i])); + break; + + case TSDB_DATA_TYPE_INT: + len += sprintf(str + len, "%d", *((int32_t *)row[i])); + break; + + case TSDB_DATA_TYPE_UINT: + len += sprintf(str + len, "%u", *((uint32_t *)row[i])); + break; + + case TSDB_DATA_TYPE_BIGINT: + len += sprintf(str + len, "%" PRId64, *((int64_t *)row[i])); + break; + + case TSDB_DATA_TYPE_UBIGINT: + len += sprintf(str + len, "%" PRIu64, *((uint64_t *)row[i])); + break; + + case TSDB_DATA_TYPE_FLOAT: { + float fv = 0; + fv = GET_FLOAT_VAL(row[i]); + len += sprintf(str + len, "%f", fv); + } break; + + case TSDB_DATA_TYPE_DOUBLE: { + double dv = 0; + dv = GET_DOUBLE_VAL(row[i]); + len += sprintf(str + len, "%lf", dv); + } break; + + case TSDB_DATA_TYPE_BINARY: + case TSDB_DATA_TYPE_NCHAR: { + int32_t charLen = varDataLen((char *)row[i] - VARSTR_HEADER_SIZE); + memcpy(str + len, row[i], charLen); + len += charLen; + } break; + + case TSDB_DATA_TYPE_TIMESTAMP: + len += sprintf(str + len, "%" PRId64, *((int64_t *)row[i])); + break; + + case TSDB_DATA_TYPE_BOOL: + len += sprintf(str + len, "%d", *((int8_t *)row[i])); + default: + break; + } + } + + return len; +} + +void printHeader(TAOS_RES *res) { + int numFields = taos_num_fields(res); + TAOS_FIELD *fields = taos_fetch_fields(res); + char header[256] = {0}; + int len = 0; + for (int i = 0; i < numFields; ++i) { + len += sprintf(header + len, "%s ", fields[i].name); + } + puts(header); +} + +// ANCHOR: demo + +/** + * @brief call back function of taos_fetch_row_a + * + * @param param : the third parameter you passed to taos_fetch_row_a + * @param res : pointer of TAOS_RES + * @param numOfRow : number of rows fetched in this batch. will be 0 if there is no more data. + * @return void* + */ +void *fetch_row_callback(void *param, TAOS_RES *res, int numOfRow) { + printf("numOfRow = %d \n", numOfRow); + int numFields = taos_num_fields(res); + TAOS_FIELD *fields = taos_fetch_fields(res); + TAOS *_taos = (TAOS *)param; + if (numOfRow > 0) { + for (int i = 0; i < numOfRow; ++i) { + TAOS_ROW row = taos_fetch_row(res); + char temp[256] = {0}; + printRow(temp, row, fields, numFields); + puts(temp); + } + taos_fetch_rows_a(res, fetch_row_callback, _taos); + } else { + printf("no more data, close the connection.\n"); + taos_free_result(res); + taos_close(_taos); + taos_cleanup(); + } +} + +/** + * @brief callback function of taos_query_a + * + * @param param: the fourth parameter you passed to taos_query_a + * @param res : the result set + * @param code : status code + * @return void* + */ +void *select_callback(void *param, TAOS_RES *res, int code) { + printf("query callback ...\n"); + TAOS *_taos = (TAOS *)param; + if (code == 0 && res) { + printHeader(res); + taos_fetch_rows_a(res, fetch_row_callback, _taos); + } else { + printf("failed to execute taos_query. error: %s\n", taos_errstr(res)); + taos_free_result(res); + taos_close(_taos); + taos_cleanup(); + exit(EXIT_FAILURE); + } +} + +int main() { + TAOS *taos = taos_connect("localhost", "root", "taosdata", "power", 6030); + if (taos == NULL) { + puts("failed to connect to server"); + exit(EXIT_FAILURE); + } + // param one is the connection returned by taos_connect. + // param two is the SQL to execute. + // param three is the callback function. + // param four can be any pointer. It will be passed to your callback function as the first parameter. we use taos + // here, because we want to close it after getting data. + taos_query_a(taos, "SELECT * FROM meters", select_callback, taos); + sleep(1); +} + +// output: +// query callback ... +// ts current voltage phase location groupid +// numOfRow = 8 +// 1538548685500 11.800000 221 0.280000 california.losangeles 2 +// 1538548696600 13.400000 223 0.290000 california.losangeles 2 +// 1538548685000 10.800000 223 0.290000 california.losangeles 3 +// 1538548686500 11.500000 221 0.350000 california.losangeles 3 +// 1538548685000 10.300000 219 0.310000 california.sanfrancisco 2 +// 1538548695000 12.600000 218 0.330000 california.sanfrancisco 2 +// 1538548696800 12.300000 221 0.310000 california.sanfrancisco 2 +// 1538548696650 10.300000 218 0.250000 california.sanfrancisco 3 +// numOfRow = 0 +// no more data, close the connection. +// ANCHOR_END: demo \ No newline at end of file diff --git a/docs/examples/c/connect_example.c b/docs/examples/c/connect_example.c new file mode 100644 index 0000000000000000000000000000000000000000..1a23df4806d7ff986898734e1971f6e0cd7c5360 --- /dev/null +++ b/docs/examples/c/connect_example.c @@ -0,0 +1,24 @@ +// compile with +// gcc connect_example.c -o connect_example -ltaos +#include +#include +#include "taos.h" + +int main() { + const char *host = "localhost"; + const char *user = "root"; + const char *passwd = "taosdata"; + // if don't want to connect to a default db, set it to NULL or "" + const char *db = NULL; + uint16_t port = 0; // 0 means use the default port + TAOS *taos = taos_connect(host, user, passwd, db, port); + if (taos == NULL) { + int errno = taos_errno(NULL); + char *msg = taos_errstr(NULL); + printf("%d, %s\n", errno, msg); + } else { + printf("connected\n"); + taos_close(taos); + } + taos_cleanup(); +} diff --git a/docs/examples/c/error_handle_example.c b/docs/examples/c/error_handle_example.c new file mode 100644 index 0000000000000000000000000000000000000000..e7dedb263df250f6634aa15fab2729cbaf4e5972 --- /dev/null +++ b/docs/examples/c/error_handle_example.c @@ -0,0 +1,24 @@ +// compile with +// gcc error_handle_example.c -o error_handle_example -ltaos +#include +#include +#include "taos.h" + +int main() { + const char *host = "localhost"; + const char *user = "root"; + const char *passwd = "taosdata"; + // if don't want to connect to a default db, set it to NULL or "" + const char *db = "notexist"; + uint16_t port = 0; // 0 means use the default port + TAOS *taos = taos_connect(host, user, passwd, db, port); + if (taos == NULL) { + int errno = taos_errno(NULL); + char *msg = taos_errstr(NULL); + printf("%d, %s\n", errno, msg); + } else { + printf("connected\n"); + taos_close(taos); + } + taos_cleanup(); +} diff --git a/docs/examples/c/insert_example.c b/docs/examples/c/insert_example.c new file mode 100644 index 0000000000000000000000000000000000000000..ce8fdc5b9372aec7b02d3c9254ec25c4c4f62adc --- /dev/null +++ b/docs/examples/c/insert_example.c @@ -0,0 +1,51 @@ +// compile with +// gcc -o insert_example insert_example.c -ltaos +#include +#include +#include "taos.h" + + +/** + * @brief execute sql and print affected rows. + * + * @param taos + * @param sql + */ +void executeSQL(TAOS *taos, const char *sql) { + TAOS_RES *res = taos_query(taos, sql); + int code = taos_errno(res); + if (code != 0) { + printf("Error code: %d; Message: %s\n", code, taos_errstr(res)); + taos_free_result(res); + taos_close(taos); + exit(EXIT_FAILURE); + } + int affectedRows = taos_affected_rows(res); + printf("affected rows %d\n", affectedRows); + taos_free_result(res); +} + + + +int main() { + TAOS *taos = taos_connect("localhost", "root", "taosdata", NULL, 6030); + if (taos == NULL) { + printf("failed to connect to server\n"); + exit(EXIT_FAILURE); + } + executeSQL(taos, "CREATE DATABASE power"); + executeSQL(taos, "USE power"); + executeSQL(taos, "CREATE STABLE meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)"); + executeSQL(taos, "INSERT INTO d1001 USING meters TAGS(California.SanFrancisco, 2) VALUES ('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)" + "d1002 USING meters TAGS(California.SanFrancisco, 3) VALUES ('2018-10-03 14:38:16.650', 10.30000, 218, 0.25000)" + "d1003 USING meters TAGS(California.LosAngeles, 2) VALUES ('2018-10-03 14:38:05.500', 11.80000, 221, 0.28000) ('2018-10-03 14:38:16.600', 13.40000, 223, 0.29000)" + "d1004 USING meters TAGS(California.LosAngeles, 3) VALUES ('2018-10-03 14:38:05.000', 10.80000, 223, 0.29000) ('2018-10-03 14:38:06.500', 11.50000, 221, 0.35000)"); + taos_close(taos); + taos_cleanup(); +} + +// output: +// affected rows 0 +// affected rows 0 +// affected rows 0 +// affected rows 8 \ No newline at end of file diff --git a/docs/examples/c/json_protocol_example.c b/docs/examples/c/json_protocol_example.c new file mode 100644 index 0000000000000000000000000000000000000000..9d276127a64c3d74322e30587ab2e319c29cbf65 --- /dev/null +++ b/docs/examples/c/json_protocol_example.c @@ -0,0 +1,52 @@ +// compile with +// gcc -o json_protocol_example json_protocol_example.c -ltaos +#include +#include +#include +#include "taos.h" + +void executeSQL(TAOS *taos, const char *sql) { + TAOS_RES *res = taos_query(taos, sql); + int code = taos_errno(res); + if (code != 0) { + printf("%s\n", taos_errstr(res)); + taos_free_result(res); + taos_close(taos); + exit(EXIT_FAILURE); + } + taos_free_result(res); +} + +// ANCHOR: main +int main() { + TAOS *taos = taos_connect("localhost", "root", "taosdata", "", 6030); + if (taos == NULL) { + printf("failed to connect to server\n"); + exit(EXIT_FAILURE); + } + executeSQL(taos, "DROP DATABASE IF EXISTS test"); + executeSQL(taos, "CREATE DATABASE test"); + executeSQL(taos, "USE test"); + char *line = + "[{\"metric\": \"meters.current\", \"timestamp\": 1648432611249, \"value\": 10.3, \"tags\": {\"location\": " + "\"California.SanFrancisco\", \"groupid\": 2}},{\"metric\": \"meters.voltage\", \"timestamp\": 1648432611249, " + "\"value\": 219, \"tags\": {\"location\": \"California.LosAngeles\", \"groupid\": 1}},{\"metric\": \"meters.current\", " + "\"timestamp\": 1648432611250, \"value\": 12.6, \"tags\": {\"location\": \"California.SanFrancisco\", \"groupid\": " + "2}},{\"metric\": \"meters.voltage\", \"timestamp\": 1648432611250, \"value\": 221, \"tags\": {\"location\": " + "\"California.LosAngeles\", \"groupid\": 1}}]"; + + char *lines[] = {line}; + TAOS_RES *res = taos_schemaless_insert(taos, lines, 1, TSDB_SML_JSON_PROTOCOL, TSDB_SML_TIMESTAMP_NOT_CONFIGURED); + if (taos_errno(res) != 0) { + printf("failed to insert schema-less data, reason: %s\n", taos_errstr(res)); + } else { + int affectedRow = taos_affected_rows(res); + printf("successfully inserted %d rows\n", affectedRow); + } + taos_free_result(res); + taos_close(taos); + taos_cleanup(); +} +// output: +// successfully inserted 4 rows +// ANCHOR_END: main diff --git a/docs/examples/c/line_example.c b/docs/examples/c/line_example.c new file mode 100644 index 0000000000000000000000000000000000000000..ce39f8d9df744082a450ce246529bf56adebd1e0 --- /dev/null +++ b/docs/examples/c/line_example.c @@ -0,0 +1,47 @@ +// compile with +// gcc -o line_example line_example.c -ltaos +#include +#include +#include +#include "taos.h" + +void executeSQL(TAOS *taos, const char *sql) { + TAOS_RES *res = taos_query(taos, sql); + int code = taos_errno(res); + if (code != 0) { + printf("%s\n", taos_errstr(res)); + taos_free_result(res); + taos_close(taos); + exit(EXIT_FAILURE); + } + taos_free_result(res); +} + +// ANCHOR: main +int main() { + TAOS *taos = taos_connect("localhost", "root", "taosdata", "", 0); + if (taos == NULL) { + printf("failed to connect to server\n"); + exit(EXIT_FAILURE); + } + executeSQL(taos, "DROP DATABASE IF EXISTS test"); + executeSQL(taos, "CREATE DATABASE test"); + executeSQL(taos, "USE test"); + char *lines[] = {"meters,location=California.LosAngeles,groupid=2 current=11.8,voltage=221,phase=0.28 1648432611249", + "meters,location=California.LosAngeles,groupid=2 current=13.4,voltage=223,phase=0.29 1648432611250", + "meters,location=California.LosAngeles,groupid=3 current=10.8,voltage=223,phase=0.29 1648432611249", + "meters,location=California.LosAngeles,groupid=3 current=11.3,voltage=221,phase=0.35 1648432611250"}; + TAOS_RES *res = taos_schemaless_insert(taos, lines, 4, TSDB_SML_LINE_PROTOCOL, TSDB_SML_TIMESTAMP_MILLI_SECONDS); + if (taos_errno(res) != 0) { + printf("failed to insert schema-less data, reason: %s\n", taos_errstr(res)); + } else { + int affectedRows = taos_affected_rows(res); + printf("successfully inserted %d rows\n", affectedRows); + } + taos_free_result(res); + taos_close(taos); + taos_cleanup(); +} +// output: +// successfully inserted 4 rows +// ANCHOR_END: main \ No newline at end of file diff --git a/docs/examples/c/multi_bind_example.c b/docs/examples/c/multi_bind_example.c new file mode 100644 index 0000000000000000000000000000000000000000..02e6568e9e88ac8703a4993ed406e770d23c2438 --- /dev/null +++ b/docs/examples/c/multi_bind_example.c @@ -0,0 +1,147 @@ +// compile with +// gcc -o multi_bind_example multi_bind_example.c -ltaos +#include +#include +#include +#include "taos.h" + +/** + * @brief execute sql only and ignore result set + * + * @param taos + * @param sql + */ +void executeSQL(TAOS *taos, const char *sql) { + TAOS_RES *res = taos_query(taos, sql); + int code = taos_errno(res); + if (code != 0) { + printf("%s\n", taos_errstr(res)); + taos_free_result(res); + taos_close(taos); + exit(EXIT_FAILURE); + } + taos_free_result(res); +} + +/** + * @brief exit program when error occur. + * + * @param stmt + * @param code + * @param msg + */ +void checkErrorCode(TAOS_STMT *stmt, int code, const char *msg) { + if (code != 0) { + printf("%s. error: %s\n", msg, taos_stmt_errstr(stmt)); + taos_stmt_close(stmt); + exit(EXIT_FAILURE); + } +} + +/** + * @brief insert data using stmt API + * + * @param taos + */ +void insertData(TAOS *taos) { + // init + TAOS_STMT *stmt = taos_stmt_init(taos); + // prepare + const char *sql = "INSERT INTO ? USING meters TAGS(?, ?) values(?, ?, ?, ?)"; + int code = taos_stmt_prepare(stmt, sql, 0); + checkErrorCode(stmt, code, "failed to execute taos_stmt_prepare"); + // bind table name and tags + TAOS_BIND tags[2]; + char *location = "California.SanFrancisco"; + int groupId = 2; + tags[0].buffer_type = TSDB_DATA_TYPE_BINARY; + tags[0].buffer_length = strlen(location); + tags[0].length = &tags[0].buffer_length; + tags[0].buffer = location; + tags[0].is_null = NULL; + + tags[1].buffer_type = TSDB_DATA_TYPE_INT; + tags[1].buffer_length = sizeof(int); + tags[1].length = &tags[1].buffer_length; + tags[1].buffer = &groupId; + tags[1].is_null = NULL; + + code = taos_stmt_set_tbname_tags(stmt, "d1001", tags); + checkErrorCode(stmt, code, "failed to execute taos_stmt_set_tbname_tags"); + + // highlight-start + // insert two rows with multi binds + TAOS_MULTI_BIND params[4]; + // values to bind + int64_t ts[] = {1648432611249, 1648432611749}; + float current[] = {10.3, 12.6}; + int voltage[] = {219, 218}; + float phase[] = {0.31, 0.33}; + // is_null array + char is_null[2] = {0}; + // length array + int32_t int64Len[2] = {sizeof(int64_t)}; + int32_t floatLen[2] = {sizeof(float)}; + int32_t intLen[2] = {sizeof(int)}; + + params[0].buffer_type = TSDB_DATA_TYPE_TIMESTAMP; + params[0].buffer_length = sizeof(int64_t); + params[0].buffer = ts; + params[0].length = int64Len; + params[0].is_null = is_null; + params[0].num = 2; + + params[1].buffer_type = TSDB_DATA_TYPE_FLOAT; + params[1].buffer_length = sizeof(float); + params[1].buffer = current; + params[1].length = floatLen; + params[1].is_null = is_null; + params[1].num = 2; + + params[2].buffer_type = TSDB_DATA_TYPE_INT; + params[2].buffer_length = sizeof(int); + params[2].buffer = voltage; + params[2].length = intLen; + params[2].is_null = is_null; + params[2].num = 2; + + params[3].buffer_type = TSDB_DATA_TYPE_FLOAT; + params[3].buffer_length = sizeof(float); + params[3].buffer = phase; + params[3].length = floatLen; + params[3].is_null = is_null; + params[3].num = 2; + + code = taos_stmt_bind_param_batch(stmt, params); // bind batch + checkErrorCode(stmt, code, "failed to execute taos_stmt_bind_param_batch"); + code = taos_stmt_add_batch(stmt); // add batch + checkErrorCode(stmt, code, "failed to execute taos_stmt_add_batch"); + // highlight-end + // execute + code = taos_stmt_execute(stmt); + checkErrorCode(stmt, code, "failed to execute taos_stmt_execute"); + int affectedRows = taos_stmt_affected_rows(stmt); + printf("successfully inserted %d rows\n", affectedRows); + // close + taos_stmt_close(stmt); +} + +int main() { + TAOS *taos = taos_connect("localhost", "root", "taosdata", NULL, 6030); + if (taos == NULL) { + printf("failed to connect to server\n"); + exit(EXIT_FAILURE); + } + executeSQL(taos, "DROP DATABASE IF EXISTS power"); + executeSQL(taos, "CREATE DATABASE power"); + executeSQL(taos, "USE power"); + executeSQL(taos, + "CREATE STABLE meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), " + "groupId INT)"); + insertData(taos); + taos_close(taos); + taos_cleanup(); +} + +// output: +// successfully inserted 2 rows \ No newline at end of file diff --git a/docs/examples/c/query_example.c b/docs/examples/c/query_example.c new file mode 100644 index 0000000000000000000000000000000000000000..fcae95bcd45a282eaa3ae911b4115e6300c6af8e --- /dev/null +++ b/docs/examples/c/query_example.c @@ -0,0 +1,143 @@ +// compile with: +// gcc -o query_example query_example.c -ltaos +#include +#include +#include +#include +#include + +typedef int16_t VarDataLenT; + +#define TSDB_NCHAR_SIZE sizeof(int32_t) +#define VARSTR_HEADER_SIZE sizeof(VarDataLenT) + +#define GET_FLOAT_VAL(x) (*(float *)(x)) +#define GET_DOUBLE_VAL(x) (*(double *)(x)) + +#define varDataLen(v) ((VarDataLenT *)(v))[0] + +int printRow(char *str, TAOS_ROW row, TAOS_FIELD *fields, int numFields) { + int len = 0; + char split = ' '; + + for (int i = 0; i < numFields; ++i) { + if (i > 0) { + str[len++] = split; + } + + if (row[i] == NULL) { + len += sprintf(str + len, "%s", "NULL"); + continue; + } + + switch (fields[i].type) { + case TSDB_DATA_TYPE_TINYINT: + len += sprintf(str + len, "%d", *((int8_t *)row[i])); + break; + + case TSDB_DATA_TYPE_UTINYINT: + len += sprintf(str + len, "%u", *((uint8_t *)row[i])); + break; + + case TSDB_DATA_TYPE_SMALLINT: + len += sprintf(str + len, "%d", *((int16_t *)row[i])); + break; + + case TSDB_DATA_TYPE_USMALLINT: + len += sprintf(str + len, "%u", *((uint16_t *)row[i])); + break; + + case TSDB_DATA_TYPE_INT: + len += sprintf(str + len, "%d", *((int32_t *)row[i])); + break; + + case TSDB_DATA_TYPE_UINT: + len += sprintf(str + len, "%u", *((uint32_t *)row[i])); + break; + + case TSDB_DATA_TYPE_BIGINT: + len += sprintf(str + len, "%" PRId64, *((int64_t *)row[i])); + break; + + case TSDB_DATA_TYPE_UBIGINT: + len += sprintf(str + len, "%" PRIu64, *((uint64_t *)row[i])); + break; + + case TSDB_DATA_TYPE_FLOAT: { + float fv = 0; + fv = GET_FLOAT_VAL(row[i]); + len += sprintf(str + len, "%f", fv); + } break; + + case TSDB_DATA_TYPE_DOUBLE: { + double dv = 0; + dv = GET_DOUBLE_VAL(row[i]); + len += sprintf(str + len, "%lf", dv); + } break; + + case TSDB_DATA_TYPE_BINARY: + case TSDB_DATA_TYPE_NCHAR: { + int32_t charLen = varDataLen((char *)row[i] - VARSTR_HEADER_SIZE); + memcpy(str + len, row[i], charLen); + len += charLen; + } break; + + case TSDB_DATA_TYPE_TIMESTAMP: + len += sprintf(str + len, "%" PRId64, *((int64_t *)row[i])); + break; + + case TSDB_DATA_TYPE_BOOL: + len += sprintf(str + len, "%d", *((int8_t *)row[i])); + default: + break; + } + } + + return len; +} + +/** + * @brief print column name and values of each row + * + * @param res + * @return int + */ +static int printResult(TAOS_RES *res) { + int numFields = taos_num_fields(res); + TAOS_FIELD *fields = taos_fetch_fields(res); + char header[256] = {0}; + int len = 0; + for (int i = 0; i < numFields; ++i) { + len += sprintf(header + len, "%s ", fields[i].name); + } + puts(header); + + TAOS_ROW row = NULL; + while ((row = taos_fetch_row(res))) { + char temp[256] = {0}; + printRow(temp, row, fields, numFields); + puts(temp); + } +} + +int main() { + TAOS *taos = taos_connect("localhost", "root", "taosdata", "power", 6030); + if (taos == NULL) { + puts("failed to connect to server"); + exit(EXIT_FAILURE); + } + TAOS_RES *res = taos_query(taos, "SELECT * FROM meters LIMIT 2"); + if (taos_errno(res) != 0) { + printf("failed to execute taos_query. error: %s\n", taos_errstr(res)); + exit(EXIT_FAILURE); + } + printResult(res); + taos_free_result(res); + taos_close(taos); + taos_cleanup(); +} + +// output: +// ts current voltage phase location groupid +// 1648432611249 10.300000 219 0.310000 California.SanFrancisco 2 +// 1648432611749 12.600000 218 0.330000 California.SanFrancisco 2 \ No newline at end of file diff --git a/docs/examples/c/stmt_example.c b/docs/examples/c/stmt_example.c new file mode 100644 index 0000000000000000000000000000000000000000..28dae5f9d5ea2faec0aa3c0a784d39e252651c65 --- /dev/null +++ b/docs/examples/c/stmt_example.c @@ -0,0 +1,141 @@ +// compile with +// gcc -o stmt_example stmt_example.c -ltaos +#include +#include +#include +#include "taos.h" + +/** + * @brief execute sql only. + * + * @param taos + * @param sql + */ +void executeSQL(TAOS *taos, const char *sql) { + TAOS_RES *res = taos_query(taos, sql); + int code = taos_errno(res); + if (code != 0) { + printf("%s\n", taos_errstr(res)); + taos_free_result(res); + taos_close(taos); + exit(EXIT_FAILURE); + } + taos_free_result(res); +} + +/** + * @brief check return status and exit program when error occur. + * + * @param stmt + * @param code + * @param msg + */ +void checkErrorCode(TAOS_STMT *stmt, int code, const char* msg) { + if (code != 0) { + printf("%s. error: %s\n", msg, taos_stmt_errstr(stmt)); + taos_stmt_close(stmt); + exit(EXIT_FAILURE); + } +} + +typedef struct { + int64_t ts; + float current; + int voltage; + float phase; +} Row; + +/** + * @brief insert data using stmt API + * + * @param taos + */ +void insertData(TAOS *taos) { + // init + TAOS_STMT *stmt = taos_stmt_init(taos); + // prepare + const char *sql = "INSERT INTO ? USING meters TAGS(?, ?) VALUES(?, ?, ?, ?)"; + int code = taos_stmt_prepare(stmt, sql, 0); + checkErrorCode(stmt, code, "failed to execute taos_stmt_prepare"); + // bind table name and tags + TAOS_BIND tags[2]; + char* location = "California.SanFrancisco"; + int groupId = 2; + tags[0].buffer_type = TSDB_DATA_TYPE_BINARY; + tags[0].buffer_length = strlen(location); + tags[0].length = &tags[0].buffer_length; + tags[0].buffer = location; + tags[0].is_null = NULL; + + tags[1].buffer_type = TSDB_DATA_TYPE_INT; + tags[1].buffer_length = sizeof(int); + tags[1].length = &tags[1].buffer_length; + tags[1].buffer = &groupId; + tags[1].is_null = NULL; + + code = taos_stmt_set_tbname_tags(stmt, "d1001", tags); + checkErrorCode(stmt, code, "failed to execute taos_stmt_set_tbname_tags"); + + // insert two rows + Row rows[2] = { + {1648432611249, 10.3, 219, 0.31}, + {1648432611749, 12.6, 218, 0.33}, + }; + + TAOS_BIND values[4]; + values[0].buffer_type = TSDB_DATA_TYPE_TIMESTAMP; + values[0].buffer_length = sizeof(int64_t); + values[0].length = &values[0].buffer_length; + values[0].is_null = NULL; + + values[1].buffer_type = TSDB_DATA_TYPE_FLOAT; + values[1].buffer_length = sizeof(float); + values[1].length = &values[1].buffer_length; + values[1].is_null = NULL; + + values[2].buffer_type = TSDB_DATA_TYPE_INT; + values[2].buffer_length = sizeof(int); + values[2].length = &values[2].buffer_length; + values[2].is_null = NULL; + + values[3].buffer_type = TSDB_DATA_TYPE_FLOAT; + values[3].buffer_length = sizeof(float); + values[3].length = &values[3].buffer_length; + values[3].is_null = NULL; + + for (int i = 0; i < 2; ++i) { + values[0].buffer = &rows[i].ts; + values[1].buffer = &rows[i].current; + values[2].buffer = &rows[i].voltage; + values[3].buffer = &rows[i].phase; + code = taos_stmt_bind_param(stmt, values); // bind param + checkErrorCode(stmt, code, "failed to execute taos_stmt_bind_param"); + code = taos_stmt_add_batch(stmt); // add batch + checkErrorCode(stmt, code, "failed to execute taos_stmt_add_batch"); + } + // execute + code = taos_stmt_execute(stmt); + checkErrorCode(stmt, code, "failed to execute taos_stmt_execute"); + int affectedRows = taos_stmt_affected_rows(stmt); + printf("successfully inserted %d rows\n", affectedRows); + // close + taos_stmt_close(stmt); +} + +int main() { + TAOS *taos = taos_connect("localhost", "root", "taosdata", NULL, 6030); + if (taos == NULL) { + printf("failed to connect to server\n"); + exit(EXIT_FAILURE); + } + executeSQL(taos, "CREATE DATABASE power"); + executeSQL(taos, "USE power"); + executeSQL(taos, "CREATE STABLE meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)"); + insertData(taos); + taos_close(taos); + taos_cleanup(); +} + + +// output: +// successfully inserted 2 rows \ No newline at end of file diff --git a/docs/examples/c/subscribe_demo.c b/docs/examples/c/subscribe_demo.c new file mode 100644 index 0000000000000000000000000000000000000000..2fe62c24eb92d2f57c24b40fc16f47d62ea5e378 --- /dev/null +++ b/docs/examples/c/subscribe_demo.c @@ -0,0 +1,66 @@ +// A simple demo for asynchronous subscription. +// compile with: +// gcc -o subscribe_demo subscribe_demo.c -ltaos + +#include +#include +#include +#include + +int nTotalRows; + +/** + * @brief callback function of subscription. + * + * @param tsub + * @param res + * @param param. the additional parameter passed to taos_subscribe + * @param code. error code + */ +void subscribe_callback(TAOS_SUB* tsub, TAOS_RES* res, void* param, int code) { + if (code != 0) { + printf("error: %d\n", code); + exit(EXIT_FAILURE); + } + + TAOS_ROW row = NULL; + int num_fields = taos_num_fields(res); + TAOS_FIELD* fields = taos_fetch_fields(res); + int nRows = 0; + + while ((row = taos_fetch_row(res))) { + char buf[4096] = {0}; + taos_print_row(buf, row, fields, num_fields); + puts(buf); + nRows++; + } + + nTotalRows += nRows; + printf("%d rows consumed.\n", nRows); +} + +int main() { + TAOS* taos = taos_connect("localhost", "root", "taosdata", NULL, 6030); + if (taos == NULL) { + printf("failed to connect to server\n"); + exit(EXIT_FAILURE); + } + + int restart = 1; // if the topic already exists, where to subscribe from the begin. + const char* topic = "topic-meter-current-bg-10"; + const char* sql = "select * from power.meters where current > 10"; + void* param = NULL; // additional parameter. + int interval = 2000; // consumption interval in microseconds. + TAOS_SUB* tsub = taos_subscribe(taos, restart, topic, sql, subscribe_callback, NULL, interval); + + // wait for insert from others process. you can open TDengine CLI to insert some records for test. + + getchar(); // press Enter to stop + + printf("total rows consumed: %d\n", nTotalRows); + int keep = 0; // whether to keep subscribe process + taos_unsubscribe(tsub, keep); + + taos_close(taos); + taos_cleanup(); +} diff --git a/docs/examples/c/telnet_line_example.c b/docs/examples/c/telnet_line_example.c new file mode 100644 index 0000000000000000000000000000000000000000..da62da4ba492856b0d73a564c1bf9cdd60b5b742 --- /dev/null +++ b/docs/examples/c/telnet_line_example.c @@ -0,0 +1,54 @@ +// compile with +// gcc -o telnet_line_example telnet_line_example.c -ltaos +#include +#include +#include +#include "taos.h" + +void executeSQL(TAOS *taos, const char *sql) { + TAOS_RES *res = taos_query(taos, sql); + int code = taos_errno(res); + if (code != 0) { + printf("%s\n", taos_errstr(res)); + taos_free_result(res); + taos_close(taos); + exit(EXIT_FAILURE); + } + taos_free_result(res); +} + +// ANCHOR: main +int main() { + TAOS *taos = taos_connect("localhost", "root", "taosdata", "", 6030); + if (taos == NULL) { + printf("failed to connect to server\n"); + exit(EXIT_FAILURE); + } + executeSQL(taos, "DROP DATABASE IF EXISTS test"); + executeSQL(taos, "CREATE DATABASE test"); + executeSQL(taos, "USE test"); + char *lines[] = { + "meters.current 1648432611249 10.3 location=California.SanFrancisco groupid=2", + "meters.current 1648432611250 12.6 location=California.SanFrancisco groupid=2", + "meters.current 1648432611249 10.8 location=California.LosAngeles groupid=3", + "meters.current 1648432611250 11.3 location=California.LosAngeles groupid=3", + "meters.voltage 1648432611249 219 location=California.SanFrancisco groupid=2", + "meters.voltage 1648432611250 218 location=California.SanFrancisco groupid=2", + "meters.voltage 1648432611249 221 location=California.LosAngeles groupid=3", + "meters.voltage 1648432611250 217 location=California.LosAngeles groupid=3", + }; + TAOS_RES *res = taos_schemaless_insert(taos, lines, 8, TSDB_SML_TELNET_PROTOCOL, TSDB_SML_TIMESTAMP_NOT_CONFIGURED); + if (taos_errno(res) != 0) { + printf("failed to insert schema-less data, reason: %s\n", taos_errstr(res)); + } else { + int affectedRow = taos_affected_rows(res); + printf("successfully inserted %d rows\n", affectedRow); + } + + taos_free_result(res); + taos_close(taos); + taos_cleanup(); +} +// output: +// successfully inserted 8 rows +// ANCHOR_END: main diff --git a/docs-examples/csharp/.gitignore b/docs/examples/csharp/.gitignore similarity index 100% rename from docs-examples/csharp/.gitignore rename to docs/examples/csharp/.gitignore diff --git a/docs/examples/csharp/AsyncQueryExample.cs b/docs/examples/csharp/AsyncQueryExample.cs new file mode 100644 index 0000000000000000000000000000000000000000..3dabbebd1630a207af2e1b1b11cc4ba15bdd94a9 --- /dev/null +++ b/docs/examples/csharp/AsyncQueryExample.cs @@ -0,0 +1,238 @@ +using TDengineDriver; +using System.Runtime.InteropServices; + +namespace TDengineExample +{ + public class AsyncQueryExample + { + static void Main() + { + IntPtr conn = GetConnection(); + QueryAsyncCallback queryAsyncCallback = new QueryAsyncCallback(QueryCallback); + TDengine.QueryAsync(conn, "select * from meters", queryAsyncCallback, IntPtr.Zero); + Thread.Sleep(2000); + TDengine.Close(conn); + TDengine.Cleanup(); + } + + static void QueryCallback(IntPtr param, IntPtr taosRes, int code) + { + if (code == 0 && taosRes != IntPtr.Zero) + { + FetchRowAsyncCallback fetchRowAsyncCallback = new FetchRowAsyncCallback(FetchRowCallback); + TDengine.FetchRowAsync(taosRes, fetchRowAsyncCallback, param); + } + else + { + Console.WriteLine($"async query data failed, failed code {code}"); + } + } + + static void FetchRowCallback(IntPtr param, IntPtr taosRes, int numOfRows) + { + if (numOfRows > 0) + { + Console.WriteLine($"{numOfRows} rows async retrieved"); + DisplayRes(taosRes); + TDengine.FetchRowAsync(taosRes, FetchRowCallback, param); + } + else + { + if (numOfRows == 0) + { + Console.WriteLine("async retrieve complete."); + + } + else + { + Console.WriteLine($"FetchRowAsync callback error, error code {numOfRows}"); + } + TDengine.FreeResult(taosRes); + } + } + + public static void DisplayRes(IntPtr res) + { + if (!IsValidResult(res)) + { + TDengine.Cleanup(); + System.Environment.Exit(1); + } + + List metaList = TDengine.FetchFields(res); + int fieldCount = metaList.Count; + // metaList.ForEach((item) => { Console.Write("{0} ({1}) \t|\t", item.name, item.size); }); + + List dataList = QueryRes(res, metaList); + for (int index = 0; index < dataList.Count; index++) + { + if (index % fieldCount == 0 && index != 0) + { + Console.WriteLine(""); + } + Console.Write("{0} \t|\t", dataList[index].ToString()); + + } + Console.WriteLine(""); + } + + public static bool IsValidResult(IntPtr res) + { + if ((res == IntPtr.Zero) || (TDengine.ErrorNo(res) != 0)) + { + if (res != IntPtr.Zero) + { + Console.Write("reason: " + TDengine.Error(res)); + return false; + } + Console.WriteLine(""); + return false; + } + return true; + } + + private static List QueryRes(IntPtr res, List meta) + { + IntPtr taosRow; + List dataRaw = new(); + while ((taosRow = TDengine.FetchRows(res)) != IntPtr.Zero) + { + dataRaw.AddRange(FetchRow(taosRow, res)); + } + if (TDengine.ErrorNo(res) != 0) + { + Console.Write("Query is not complete, Error {0} {1}", TDengine.ErrorNo(res), TDengine.Error(res)); + } + TDengine.FreeResult(res); + Console.WriteLine(""); + return dataRaw; + } + + public static List FetchRow(IntPtr taosRow, IntPtr taosRes)//, List metaList, int numOfFiled + { + List metaList = TDengine.FetchFields(taosRes); + int numOfFiled = TDengine.FieldCount(taosRes); + + + List dataRaw = new(); + + IntPtr colLengthPrt = TDengine.FetchLengths(taosRes); + int[] colLengthArr = new int[numOfFiled]; + Marshal.Copy(colLengthPrt, colLengthArr, 0, numOfFiled); + + for (int i = 0; i < numOfFiled; i++) + { + TDengineMeta meta = metaList[i]; + IntPtr data = Marshal.ReadIntPtr(taosRow, IntPtr.Size * i); + + if (data == IntPtr.Zero) + { + dataRaw.Add("NULL"); + continue; + } + switch ((TDengineDataType)meta.type) + { + case TDengineDataType.TSDB_DATA_TYPE_BOOL: + bool v1 = Marshal.ReadByte(data) != 0; + dataRaw.Add(v1); + break; + case TDengineDataType.TSDB_DATA_TYPE_TINYINT: + sbyte v2 = (sbyte)Marshal.ReadByte(data); + dataRaw.Add(v2); + break; + case TDengineDataType.TSDB_DATA_TYPE_SMALLINT: + short v3 = Marshal.ReadInt16(data); + dataRaw.Add(v3); + break; + case TDengineDataType.TSDB_DATA_TYPE_INT: + int v4 = Marshal.ReadInt32(data); + dataRaw.Add(v4); + break; + case TDengineDataType.TSDB_DATA_TYPE_BIGINT: + long v5 = Marshal.ReadInt64(data); + dataRaw.Add(v5); + break; + case TDengineDataType.TSDB_DATA_TYPE_FLOAT: + float v6 = (float)Marshal.PtrToStructure(data, typeof(float)); + dataRaw.Add(v6); + break; + case TDengineDataType.TSDB_DATA_TYPE_DOUBLE: + double v7 = (double)Marshal.PtrToStructure(data, typeof(double)); + dataRaw.Add(v7); + break; + case TDengineDataType.TSDB_DATA_TYPE_BINARY: + string v8 = Marshal.PtrToStringUTF8(data, colLengthArr[i]); + dataRaw.Add(v8); + break; + case TDengineDataType.TSDB_DATA_TYPE_TIMESTAMP: + long v9 = Marshal.ReadInt64(data); + dataRaw.Add(v9); + break; + case TDengineDataType.TSDB_DATA_TYPE_NCHAR: + string v10 = Marshal.PtrToStringUTF8(data, colLengthArr[i]); + dataRaw.Add(v10); + break; + case TDengineDataType.TSDB_DATA_TYPE_UTINYINT: + byte v12 = Marshal.ReadByte(data); + dataRaw.Add(v12.ToString()); + break; + case TDengineDataType.TSDB_DATA_TYPE_USMALLINT: + ushort v13 = (ushort)Marshal.ReadInt16(data); + dataRaw.Add(v13); + break; + case TDengineDataType.TSDB_DATA_TYPE_UINT: + uint v14 = (uint)Marshal.ReadInt32(data); + dataRaw.Add(v14); + break; + case TDengineDataType.TSDB_DATA_TYPE_UBIGINT: + ulong v15 = (ulong)Marshal.ReadInt64(data); + dataRaw.Add(v15); + break; + case TDengineDataType.TSDB_DATA_TYPE_JSONTAG: + string v16 = Marshal.PtrToStringUTF8(data, colLengthArr[i]); + dataRaw.Add(v16); + break; + default: + dataRaw.Add("nonsupport data type"); + break; + } + + } + return dataRaw; + } + + static IntPtr GetConnection() + { + string host = "localhost"; + short port = 6030; + string username = "root"; + string password = "taosdata"; + string dbname = "power"; + var conn = TDengine.Connect(host, username, password, dbname, port); + if (conn == IntPtr.Zero) + { + Console.WriteLine("Connect to TDengine failed"); + Environment.Exit(0); + } + else + { + Console.WriteLine("Connect to TDengine success"); + } + return conn; + } + } +} + +//output: +// Connect to TDengine success +// 8 rows async retrieved + +// 1538548685500 | 11.8 | 221 | 0.28 | california.losangeles | 2 | +// 1538548696600 | 13.4 | 223 | 0.29 | california.losangeles | 2 | +// 1538548685000 | 10.8 | 223 | 0.29 | california.losangeles | 3 | +// 1538548686500 | 11.5 | 221 | 0.35 | california.losangeles | 3 | +// 1538548685000 | 10.3 | 219 | 0.31 | california.sanfrancisco | 2 | +// 1538548695000 | 12.6 | 218 | 0.33 | california.sanfrancisco | 2 | +// 1538548696800 | 12.3 | 221 | 0.31 | california.sanfrancisco | 2 | +// 1538548696650 | 10.3 | 218 | 0.25 | california.sanfrancisco | 3 | +// async retrieve complete. \ No newline at end of file diff --git a/docs-examples/csharp/ConnectExample.cs b/docs/examples/csharp/ConnectExample.cs similarity index 100% rename from docs-examples/csharp/ConnectExample.cs rename to docs/examples/csharp/ConnectExample.cs diff --git a/docs/examples/csharp/InfluxDBLineExample.cs b/docs/examples/csharp/InfluxDBLineExample.cs new file mode 100644 index 0000000000000000000000000000000000000000..7b4453f4ac0b14dd76d166e395bdacb46a5d3fbc --- /dev/null +++ b/docs/examples/csharp/InfluxDBLineExample.cs @@ -0,0 +1,77 @@ +using TDengineDriver; + +namespace TDengineExample +{ + internal class InfluxDBLineExample + { + static void Main() + { + IntPtr conn = GetConnection(); + PrepareDatabase(conn); + string[] lines = { + "meters,location=California.LosAngeles,groupid=2 current=11.8,voltage=221,phase=0.28 1648432611249", + "meters,location=California.LosAngeles,groupid=2 current=13.4,voltage=223,phase=0.29 1648432611250", + "meters,location=California.LosAngeles,groupid=3 current=10.8,voltage=223,phase=0.29 1648432611249", + "meters,location=California.LosAngeles,groupid=3 current=11.3,voltage=221,phase=0.35 1648432611250" + }; + IntPtr res = TDengine.SchemalessInsert(conn, lines, lines.Length, (int)TDengineSchemalessProtocol.TSDB_SML_LINE_PROTOCOL, (int)TDengineSchemalessPrecision.TSDB_SML_TIMESTAMP_MILLI_SECONDS); + if (TDengine.ErrorNo(res) != 0) + { + Console.WriteLine("SchemalessInsert failed since " + TDengine.Error(res)); + ExitProgram(conn, 1); + } + else + { + int affectedRows = TDengine.AffectRows(res); + Console.WriteLine($"SchemalessInsert success, affected {affectedRows} rows"); + } + TDengine.FreeResult(res); + ExitProgram(conn, 0); + + } + static IntPtr GetConnection() + { + 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"); + TDengine.Cleanup(); + Environment.Exit(1); + } + else + { + Console.WriteLine("Connect to TDengine success"); + } + return conn; + } + + static void PrepareDatabase(IntPtr conn) + { + IntPtr res = TDengine.Query(conn, "CREATE DATABASE test"); + if (TDengine.ErrorNo(res) != 0) + { + Console.WriteLine("failed to create database, reason: " + TDengine.Error(res)); + ExitProgram(conn, 1); + } + res = TDengine.Query(conn, "USE test"); + if (TDengine.ErrorNo(res) != 0) + { + Console.WriteLine("failed to change database, reason: " + TDengine.Error(res)); + ExitProgram(conn, 1); + } + } + + static void ExitProgram(IntPtr conn, int exitCode) + { + TDengine.Close(conn); + TDengine.Cleanup(); + Environment.Exit(exitCode); + } + } + +} diff --git a/docs/examples/csharp/OptsJsonExample.cs b/docs/examples/csharp/OptsJsonExample.cs new file mode 100644 index 0000000000000000000000000000000000000000..2c41acc5c9628befda7eb4ad5c30af5b921de948 --- /dev/null +++ b/docs/examples/csharp/OptsJsonExample.cs @@ -0,0 +1,76 @@ +using TDengineDriver; + +namespace TDengineExample +{ + internal class OptsJsonExample + { + static void Main() + { + IntPtr conn = GetConnection(); + PrepareDatabase(conn); + string[] lines = { "[{\"metric\": \"meters.current\", \"timestamp\": 1648432611249, \"value\": 10.3, \"tags\": {\"location\": \"California.SanFrancisco\", \"groupid\": 2}}," + + " {\"metric\": \"meters.voltage\", \"timestamp\": 1648432611249, \"value\": 219, \"tags\": {\"location\": \"California.LosAngeles\", \"groupid\": 1}}, " + + "{\"metric\": \"meters.current\", \"timestamp\": 1648432611250, \"value\": 12.6, \"tags\": {\"location\": \"California.SanFrancisco\", \"groupid\": 2}}," + + " {\"metric\": \"meters.voltage\", \"timestamp\": 1648432611250, \"value\": 221, \"tags\": {\"location\": \"California.LosAngeles\", \"groupid\": 1}}]" + }; + + IntPtr res = TDengine.SchemalessInsert(conn, lines, 1, (int)TDengineSchemalessProtocol.TSDB_SML_JSON_PROTOCOL, (int)TDengineSchemalessPrecision.TSDB_SML_TIMESTAMP_NOT_CONFIGURED); + if (TDengine.ErrorNo(res) != 0) + { + Console.WriteLine("SchemalessInsert failed since " + TDengine.Error(res)); + ExitProgram(conn, 1); + } + else + { + int affectedRows = TDengine.AffectRows(res); + Console.WriteLine($"SchemalessInsert success, affected {affectedRows} rows"); + } + TDengine.FreeResult(res); + ExitProgram(conn, 0); + + } + static IntPtr GetConnection() + { + 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"); + TDengine.Cleanup(); + Environment.Exit(1); + } + else + { + Console.WriteLine("Connect to TDengine success"); + } + return conn; + } + + static void PrepareDatabase(IntPtr conn) + { + IntPtr res = TDengine.Query(conn, "CREATE DATABASE test"); + if (TDengine.ErrorNo(res) != 0) + { + Console.WriteLine("failed to create database, reason: " + TDengine.Error(res)); + ExitProgram(conn, 1); + } + res = TDengine.Query(conn, "USE test"); + if (TDengine.ErrorNo(res) != 0) + { + Console.WriteLine("failed to change database, reason: " + TDengine.Error(res)); + ExitProgram(conn, 1); + } + } + + static void ExitProgram(IntPtr conn, int exitCode) + { + TDengine.Close(conn); + TDengine.Cleanup(); + Environment.Exit(exitCode); + } + } +} diff --git a/docs/examples/csharp/OptsTelnetExample.cs b/docs/examples/csharp/OptsTelnetExample.cs new file mode 100644 index 0000000000000000000000000000000000000000..bb752db1afbbb2ef68df9ca25314c8b91cd9a266 --- /dev/null +++ b/docs/examples/csharp/OptsTelnetExample.cs @@ -0,0 +1,80 @@ +using TDengineDriver; + +namespace TDengineExample +{ + internal class OptsTelnetExample + { + static void Main() + { + IntPtr conn = GetConnection(); + PrepareDatabase(conn); + string[] lines = { + "meters.current 1648432611249 10.3 location=California.SanFrancisco groupid=2", + "meters.current 1648432611250 12.6 location=California.SanFrancisco groupid=2", + "meters.current 1648432611249 10.8 location=California.LosAngeles groupid=3", + "meters.current 1648432611250 11.3 location=California.LosAngeles groupid=3", + "meters.voltage 1648432611249 219 location=California.SanFrancisco groupid=2", + "meters.voltage 1648432611250 218 location=California.SanFrancisco groupid=2", + "meters.voltage 1648432611249 221 location=California.LosAngeles groupid=3", + "meters.voltage 1648432611250 217 location=California.LosAngeles groupid=3", + }; + IntPtr res = TDengine.SchemalessInsert(conn, lines, lines.Length, (int)TDengineSchemalessProtocol.TSDB_SML_TELNET_PROTOCOL, (int)TDengineSchemalessPrecision.TSDB_SML_TIMESTAMP_NOT_CONFIGURED); + if (TDengine.ErrorNo(res) != 0) + { + Console.WriteLine("SchemalessInsert failed since " + TDengine.Error(res)); + ExitProgram(conn, 1); + } + else + { + int affectedRows = TDengine.AffectRows(res); + Console.WriteLine($"SchemalessInsert success, affected {affectedRows} rows"); + } + TDengine.FreeResult(res); + ExitProgram(conn, 0); + + } + static IntPtr GetConnection() + { + 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"); + TDengine.Cleanup(); + Environment.Exit(1); + } + else + { + Console.WriteLine("Connect to TDengine success"); + } + return conn; + } + + static void PrepareDatabase(IntPtr conn) + { + IntPtr res = TDengine.Query(conn, "CREATE DATABASE test"); + if (TDengine.ErrorNo(res) != 0) + { + Console.WriteLine("failed to create database, reason: " + TDengine.Error(res)); + ExitProgram(conn, 1); + } + res = TDengine.Query(conn, "USE test"); + if (TDengine.ErrorNo(res) != 0) + { + Console.WriteLine("failed to change database, reason: " + TDengine.Error(res)); + ExitProgram(conn, 1); + } + } + + static void ExitProgram(IntPtr conn, int exitCode) + { + TDengine.Close(conn); + TDengine.Cleanup(); + Environment.Exit(exitCode); + } + } +} diff --git a/docs/examples/csharp/QueryExample.cs b/docs/examples/csharp/QueryExample.cs new file mode 100644 index 0000000000000000000000000000000000000000..97f0c456d412e2ed608c345ba87469d3f5ccfc15 --- /dev/null +++ b/docs/examples/csharp/QueryExample.cs @@ -0,0 +1,162 @@ +using TDengineDriver; +using System.Runtime.InteropServices; + +namespace TDengineExample +{ + internal class QueryExample + { + static void Main() + { + IntPtr conn = GetConnection(); + // run query + IntPtr res = TDengine.Query(conn, "SELECT * FROM test.meters LIMIT 2"); + if (TDengine.ErrorNo(res) != 0) + { + Console.WriteLine("Failed to query since: " + TDengine.Error(res)); + TDengine.Close(conn); + TDengine.Cleanup(); + return; + } + + // get filed count + int fieldCount = TDengine.FieldCount(res); + Console.WriteLine("fieldCount=" + fieldCount); + + // print column names + List metas = TDengine.FetchFields(res); + for (int i = 0; i < metas.Count; i++) + { + Console.Write(metas[i].name + "\t"); + } + Console.WriteLine(); + + // print values + IntPtr row; + while ((row = TDengine.FetchRows(res)) != IntPtr.Zero) + { + List metaList = TDengine.FetchFields(res); + int numOfFiled = TDengine.FieldCount(res); + + List dataRaw = new List(); + + IntPtr colLengthPrt = TDengine.FetchLengths(res); + int[] colLengthArr = new int[numOfFiled]; + Marshal.Copy(colLengthPrt, colLengthArr, 0, numOfFiled); + + for (int i = 0; i < numOfFiled; i++) + { + TDengineMeta meta = metaList[i]; + IntPtr data = Marshal.ReadIntPtr(row, IntPtr.Size * i); + + if (data == IntPtr.Zero) + { + Console.Write("NULL\t"); + continue; + } + switch ((TDengineDataType)meta.type) + { + case TDengineDataType.TSDB_DATA_TYPE_BOOL: + bool v1 = Marshal.ReadByte(data) == 0 ? false : true; + Console.Write(v1.ToString() + "\t"); + break; + case TDengineDataType.TSDB_DATA_TYPE_TINYINT: + sbyte v2 = (sbyte)Marshal.ReadByte(data); + Console.Write(v2.ToString() + "\t"); + break; + case TDengineDataType.TSDB_DATA_TYPE_SMALLINT: + short v3 = Marshal.ReadInt16(data); + Console.Write(v3.ToString() + "\t"); + break; + case TDengineDataType.TSDB_DATA_TYPE_INT: + int v4 = Marshal.ReadInt32(data); + Console.Write(v4.ToString() + "\t"); + break; + case TDengineDataType.TSDB_DATA_TYPE_BIGINT: + long v5 = Marshal.ReadInt64(data); + Console.Write(v5.ToString() + "\t"); + break; + case TDengineDataType.TSDB_DATA_TYPE_FLOAT: + float v6 = (float)Marshal.PtrToStructure(data, typeof(float)); + Console.Write(v6.ToString() + "\t"); + break; + case TDengineDataType.TSDB_DATA_TYPE_DOUBLE: + double v7 = (double)Marshal.PtrToStructure(data, typeof(double)); + Console.Write(v7.ToString() + "\t"); + break; + case TDengineDataType.TSDB_DATA_TYPE_BINARY: + string v8 = Marshal.PtrToStringUTF8(data, colLengthArr[i]); + Console.Write(v8 + "\t"); + break; + case TDengineDataType.TSDB_DATA_TYPE_TIMESTAMP: + long v9 = Marshal.ReadInt64(data); + Console.Write(v9.ToString() + "\t"); + break; + case TDengineDataType.TSDB_DATA_TYPE_NCHAR: + string v10 = Marshal.PtrToStringUTF8(data, colLengthArr[i]); + Console.Write(v10 + "\t"); + break; + case TDengineDataType.TSDB_DATA_TYPE_UTINYINT: + byte v12 = Marshal.ReadByte(data); + Console.Write(v12.ToString() + "\t"); + break; + case TDengineDataType.TSDB_DATA_TYPE_USMALLINT: + ushort v13 = (ushort)Marshal.ReadInt16(data); + Console.Write(v13.ToString() + "\t"); + break; + case TDengineDataType.TSDB_DATA_TYPE_UINT: + uint v14 = (uint)Marshal.ReadInt32(data); + Console.Write(v14.ToString() + "\t"); + break; + case TDengineDataType.TSDB_DATA_TYPE_UBIGINT: + ulong v15 = (ulong)Marshal.ReadInt64(data); + Console.Write(v15.ToString() + "\t"); + break; + case TDengineDataType.TSDB_DATA_TYPE_JSONTAG: + string v16 = Marshal.PtrToStringUTF8(data, colLengthArr[i]); + Console.Write(v16 + "\t"); + break; + default: + Console.Write("nonsupport data type value"); + break; + } + + } + Console.WriteLine(); + } + if (TDengine.ErrorNo(res) != 0) + { + Console.WriteLine($"Query is not complete, Error {TDengine.ErrorNo(res)} {TDengine.Error(res)}"); + } + // exit + TDengine.FreeResult(res); + TDengine.Close(conn); + TDengine.Cleanup(); + } + static IntPtr GetConnection() + { + string host = "localhost"; + short port = 6030; + string username = "root"; + string password = "taosdata"; + string dbname = "power"; + var conn = TDengine.Connect(host, username, password, dbname, port); + if (conn == IntPtr.Zero) + { + Console.WriteLine("Connect to TDengine failed"); + System.Environment.Exit(0); + } + else + { + Console.WriteLine("Connect to TDengine success"); + } + return conn; + } + } +} + +// output: +// Connect to TDengine success +// fieldCount=6 +// ts current voltage phase location groupid +// 1648432611249 10.3 219 0.31 California.SanFrancisco 2 +// 1648432611749 12.6 218 0.33 California.SanFrancisco 2 \ No newline at end of file diff --git a/docs/examples/csharp/SQLInsertExample.cs b/docs/examples/csharp/SQLInsertExample.cs new file mode 100644 index 0000000000000000000000000000000000000000..d5462c1062e01fd5c93bac983696d0350117ad92 --- /dev/null +++ b/docs/examples/csharp/SQLInsertExample.cs @@ -0,0 +1,69 @@ +using TDengineDriver; + + +namespace TDengineExample +{ + internal class SQLInsertExample + { + + static void Main() + { + IntPtr conn = GetConnection(); + IntPtr res = TDengine.Query(conn, "CREATE DATABASE power"); + CheckRes(conn, res, "failed to create database"); + res = TDengine.Query(conn, "USE power"); + CheckRes(conn, res, "failed to change database"); + res = TDengine.Query(conn, "CREATE STABLE power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)"); + CheckRes(conn, res, "failed to create stable"); + var sql = "INSERT INTO d1001 USING meters TAGS(California.SanFrancisco, 2) VALUES ('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) " + + "d1002 USING power.meters TAGS(California.SanFrancisco, 3) VALUES('2018-10-03 14:38:16.650', 10.30000, 218, 0.25000) " + + "d1003 USING power.meters TAGS(California.LosAngeles, 2) VALUES('2018-10-03 14:38:05.500', 11.80000, 221, 0.28000)('2018-10-03 14:38:16.600', 13.40000, 223, 0.29000) " + + "d1004 USING power.meters TAGS(California.LosAngeles, 3) VALUES('2018-10-03 14:38:05.000', 10.80000, 223, 0.29000)('2018-10-03 14:38:06.500', 11.50000, 221, 0.35000)"; + res = TDengine.Query(conn, sql); + CheckRes(conn, res, "failed to insert data"); + int affectedRows = TDengine.AffectRows(res); + Console.WriteLine("affectedRows " + affectedRows); + ExitProgram(conn, 0); + } + + static IntPtr GetConnection() + { + 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"); + Environment.Exit(0); + } + else + { + Console.WriteLine("Connect to TDengine success"); + } + return conn; + } + + static void CheckRes(IntPtr conn, IntPtr res, String errorMsg) + { + if (TDengine.ErrorNo(res) != 0) + { + Console.Write(errorMsg + " since: " + TDengine.Error(res)); + ExitProgram(conn, 1); + } + } + + static void ExitProgram(IntPtr conn, int exitCode) + { + TDengine.Close(conn); + TDengine.Cleanup(); + Environment.Exit(exitCode); + } + } +} + +// output: +// Connect to TDengine success +// affectedRows 8 diff --git a/docs/examples/csharp/StmtInsertExample.cs b/docs/examples/csharp/StmtInsertExample.cs new file mode 100644 index 0000000000000000000000000000000000000000..6ade424b95d64529b7a40a782de13e3106d0c78a --- /dev/null +++ b/docs/examples/csharp/StmtInsertExample.cs @@ -0,0 +1,115 @@ +using TDengineDriver; + +namespace TDengineExample +{ + internal class StmtInsertExample + { + private static IntPtr conn; + private static IntPtr stmt; + static void Main() + { + conn = GetConnection(); + PrepareSTable(); + // 1. init and prepare + stmt = TDengine.StmtInit(conn); + if (stmt == IntPtr.Zero) + { + Console.WriteLine("failed to init stmt, " + TDengine.Error(stmt)); + ExitProgram(); + } + int res = TDengine.StmtPrepare(stmt, "INSERT INTO ? USING meters TAGS(?, ?) VALUES(?, ?, ?, ?)"); + CheckStmtRes(res, "failed to prepare stmt"); + + // 2. bind table name and tags + TAOS_BIND[] tags = new TAOS_BIND[2] { TaosBind.BindBinary("California.SanFrancisco"), TaosBind.BindInt(2) }; + res = TDengine.StmtSetTbnameTags(stmt, "d1001", tags); + CheckStmtRes(res, "failed to bind table name and tags"); + + // 3. bind values + TAOS_MULTI_BIND[] values = new TAOS_MULTI_BIND[4] { + TaosMultiBind.MultiBindTimestamp(new long[2] { 1648432611249, 1648432611749}), + TaosMultiBind.MultiBindFloat(new float?[2] { 10.3f, 12.6f}), + TaosMultiBind.MultiBindInt(new int?[2] { 219, 218}), + TaosMultiBind.MultiBindFloat(new float?[2]{ 0.31f, 0.33f}) + }; + res = TDengine.StmtBindParamBatch(stmt, values); + CheckStmtRes(res, "failed to bind params"); + + // 4. add batch + res = TDengine.StmtAddBatch(stmt); + CheckStmtRes(res, "failed to add batch"); + + // 5. execute + res = TDengine.StmtExecute(stmt); + CheckStmtRes(res, "faild to execute"); + + // 6. free + TaosBind.FreeTaosBind(tags); + TaosMultiBind.FreeTaosBind(values); + TDengine.Close(conn); + TDengine.Cleanup(); + } + + static IntPtr GetConnection() + { + 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"); + Environment.Exit(0); + } + else + { + Console.WriteLine("Connect to TDengine success"); + } + return conn; + } + + + + static void PrepareSTable() + { + IntPtr res = TDengine.Query(conn, "CREATE DATABASE power"); + CheckResPtr(res, "failed to create database"); + res = TDengine.Query(conn, "USE power"); + CheckResPtr(res, "failed to change database"); + res = TDengine.Query(conn, "CREATE STABLE power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)"); + CheckResPtr(res, "failed to create stable"); + } + + static void CheckStmtRes(int res, string errorMsg) + { + if (res != 0) + { + Console.WriteLine(errorMsg + ", " + TDengine.StmtErrorStr(stmt)); + int code = TDengine.StmtClose(stmt); + if (code != 0) + { + Console.WriteLine($"falied to close stmt, {code} reason: {TDengine.StmtErrorStr(stmt)} "); + } + ExitProgram(); + } + } + + static void CheckResPtr(IntPtr res, string errorMsg) + { + if (TDengine.ErrorNo(res) != 0) + { + Console.WriteLine(errorMsg + " since:" + TDengine.Error(res)); + ExitProgram(); + } + } + + static void ExitProgram() + { + TDengine.Close(conn); + TDengine.Cleanup(); + Environment.Exit(1); + } + } +} diff --git a/docs-examples/csharp/SubscribeDemo.cs b/docs/examples/csharp/SubscribeDemo.cs similarity index 100% rename from docs-examples/csharp/SubscribeDemo.cs rename to docs/examples/csharp/SubscribeDemo.cs diff --git a/docs-examples/csharp/asyncquery.csproj b/docs/examples/csharp/asyncquery.csproj similarity index 100% rename from docs-examples/csharp/asyncquery.csproj rename to docs/examples/csharp/asyncquery.csproj diff --git a/docs-examples/csharp/connect.csproj b/docs/examples/csharp/connect.csproj similarity index 100% rename from docs-examples/csharp/connect.csproj rename to docs/examples/csharp/connect.csproj diff --git a/docs-examples/csharp/influxdbline.csproj b/docs/examples/csharp/influxdbline.csproj similarity index 100% rename from docs-examples/csharp/influxdbline.csproj rename to docs/examples/csharp/influxdbline.csproj diff --git a/docs-examples/csharp/optsjson.csproj b/docs/examples/csharp/optsjson.csproj similarity index 100% rename from docs-examples/csharp/optsjson.csproj rename to docs/examples/csharp/optsjson.csproj diff --git a/docs-examples/csharp/optstelnet.csproj b/docs/examples/csharp/optstelnet.csproj similarity index 100% rename from docs-examples/csharp/optstelnet.csproj rename to docs/examples/csharp/optstelnet.csproj diff --git a/docs-examples/csharp/query.csproj b/docs/examples/csharp/query.csproj similarity index 100% rename from docs-examples/csharp/query.csproj rename to docs/examples/csharp/query.csproj diff --git a/docs-examples/csharp/sqlinsert.csproj b/docs/examples/csharp/sqlinsert.csproj similarity index 100% rename from docs-examples/csharp/sqlinsert.csproj rename to docs/examples/csharp/sqlinsert.csproj diff --git a/docs-examples/csharp/stmtinsert.csproj b/docs/examples/csharp/stmtinsert.csproj similarity index 100% rename from docs-examples/csharp/stmtinsert.csproj rename to docs/examples/csharp/stmtinsert.csproj diff --git a/docs-examples/csharp/subscribe.csproj b/docs/examples/csharp/subscribe.csproj similarity index 100% rename from docs-examples/csharp/subscribe.csproj rename to docs/examples/csharp/subscribe.csproj diff --git a/docs-examples/go/.gitignore b/docs/examples/go/.gitignore similarity index 100% rename from docs-examples/go/.gitignore rename to docs/examples/go/.gitignore diff --git a/docs-examples/go/connect/afconn/main.go b/docs/examples/go/connect/afconn/main.go similarity index 100% rename from docs-examples/go/connect/afconn/main.go rename to docs/examples/go/connect/afconn/main.go diff --git a/docs/examples/go/connect/cgoexample/main.go b/docs/examples/go/connect/cgoexample/main.go new file mode 100644 index 0000000000000000000000000000000000000000..ba7ed0f728a1cd546dbc3199ce4c0dc854ebee91 --- /dev/null +++ b/docs/examples/go/connect/cgoexample/main.go @@ -0,0 +1,23 @@ +package main + +import ( + "database/sql" + "fmt" + + _ "github.com/taosdata/driver-go/v2/taosSql" +) + +func main() { + var taosDSN = "root:taosdata@tcp(localhost:6030)/" + taos, err := sql.Open("taosSql", taosDSN) + if err != nil { + fmt.Println("failed to connect TDengine, err:", err) + return + } + fmt.Println("Connected") + defer taos.Close() +} + +// use +// var taosDSN = "root:taosdata@tcp(localhost:6030)/dbName" +// if you want to connect a specified database named "dbName". diff --git a/docs/examples/go/connect/restexample/main.go b/docs/examples/go/connect/restexample/main.go new file mode 100644 index 0000000000000000000000000000000000000000..1efc98b988c183c4c680884057bf2a72a9dd19e9 --- /dev/null +++ b/docs/examples/go/connect/restexample/main.go @@ -0,0 +1,23 @@ +package main + +import ( + "database/sql" + "fmt" + + _ "github.com/taosdata/driver-go/v2/taosRestful" +) + +func main() { + var taosDSN = "root:taosdata@http(localhost:6041)/" + taos, err := sql.Open("taosRestful", taosDSN) + if err != nil { + fmt.Println("failed to connect TDengine, err:", err) + return + } + fmt.Println("Connected") + defer taos.Close() +} + +// use +// var taosDSN = "root:taosdata@http(localhost:6041)/dbName" +// if you want to connect a specified database named "dbName". diff --git a/docs-examples/go/connect/wrapper/main.go b/docs/examples/go/connect/wrapper/main.go similarity index 100% rename from docs-examples/go/connect/wrapper/main.go rename to docs/examples/go/connect/wrapper/main.go diff --git a/docs-examples/go/go.mod b/docs/examples/go/go.mod similarity index 100% rename from docs-examples/go/go.mod rename to docs/examples/go/go.mod diff --git a/docs/examples/go/insert/json/main.go b/docs/examples/go/insert/json/main.go new file mode 100644 index 0000000000000000000000000000000000000000..6be375270e32a5091c015f88de52c9dda2246b59 --- /dev/null +++ b/docs/examples/go/insert/json/main.go @@ -0,0 +1,37 @@ +package main + +import ( + "fmt" + + "github.com/taosdata/driver-go/v2/af" +) + +func prepareDatabase(conn *af.Connector) { + _, err := conn.Exec("CREATE DATABASE test") + if err != nil { + panic(err) + } + _, err = conn.Exec("USE test") + if err != nil { + panic(err) + } +} + +func main() { + conn, err := af.Open("localhost", "root", "taosdata", "", 6030) + if err != nil { + fmt.Println("fail to connect, err:", err) + } + defer conn.Close() + prepareDatabase(conn) + + payload := `[{"metric": "meters.current", "timestamp": 1648432611249, "value": 10.3, "tags": {"location": "California.SanFrancisco", "groupid": 2}}, + {"metric": "meters.voltage", "timestamp": 1648432611249, "value": 219, "tags": {"location": "California.LosAngeles", "groupid": 1}}, + {"metric": "meters.current", "timestamp": 1648432611250, "value": 12.6, "tags": {"location": "California.SanFrancisco", "groupid": 2}}, + {"metric": "meters.voltage", "timestamp": 1648432611250, "value": 221, "tags": {"location": "California.LosAngeles", "groupid": 1}}]` + + err = conn.OpenTSDBInsertJsonPayload(payload) + if err != nil { + fmt.Println("insert error:", err) + } +} diff --git a/docs/examples/go/insert/line/main.go b/docs/examples/go/insert/line/main.go new file mode 100644 index 0000000000000000000000000000000000000000..c17e1a5270850e6a8b497e0dbec4ae714ee1e2d6 --- /dev/null +++ b/docs/examples/go/insert/line/main.go @@ -0,0 +1,38 @@ +package main + +import ( + "fmt" + + "github.com/taosdata/driver-go/v2/af" +) + +func prepareDatabase(conn *af.Connector) { + _, err := conn.Exec("CREATE DATABASE test") + if err != nil { + panic(err) + } + _, err = conn.Exec("USE test") + if err != nil { + panic(err) + } +} + +func main() { + conn, err := af.Open("localhost", "root", "taosdata", "", 6030) + if err != nil { + fmt.Println("fail to connect, err:", err) + } + defer conn.Close() + prepareDatabase(conn) + var lines = []string{ + "meters,location=California.LosAngeles,groupid=2 current=11.8,voltage=221,phase=0.28 1648432611249", + "meters,location=California.LosAngeles,groupid=2 current=13.4,voltage=223,phase=0.29 1648432611250", + "meters,location=California.LosAngeles,groupid=3 current=10.8,voltage=223,phase=0.29 1648432611249", + "meters,location=California.LosAngeles,groupid=3 current=11.3,voltage=221,phase=0.35 1648432611250", + } + + err = conn.InfluxDBInsertLines(lines, "ms") + if err != nil { + fmt.Println("insert error:", err) + } +} diff --git a/docs/examples/go/insert/sql/main.go b/docs/examples/go/insert/sql/main.go new file mode 100644 index 0000000000000000000000000000000000000000..6cd5f860e65f4fffd139668f69cc1772f5310eae --- /dev/null +++ b/docs/examples/go/insert/sql/main.go @@ -0,0 +1,49 @@ +package main + +import ( + "database/sql" + "fmt" + + _ "github.com/taosdata/driver-go/v2/taosRestful" +) + +func createStable(taos *sql.DB) { + _, err := taos.Exec("CREATE DATABASE power") + if err != nil { + fmt.Println("failed to create database, err:", err) + } + _, err = taos.Exec("CREATE STABLE power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)") + if err != nil { + fmt.Println("failed to create stable, err:", err) + } +} + +func insertData(taos *sql.DB) { + sql := `INSERT INTO power.d1001 USING power.meters TAGS(California.SanFrancisco, 2) VALUES ('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) + power.d1002 USING power.meters TAGS(California.SanFrancisco, 3) VALUES ('2018-10-03 14:38:16.650', 10.30000, 218, 0.25000) + power.d1003 USING power.meters TAGS(California.LosAngeles, 2) VALUES ('2018-10-03 14:38:05.500', 11.80000, 221, 0.28000) ('2018-10-03 14:38:16.600', 13.40000, 223, 0.29000) + power.d1004 USING power.meters TAGS(California.LosAngeles, 3) VALUES ('2018-10-03 14:38:05.000', 10.80000, 223, 0.29000) ('2018-10-03 14:38:06.500', 11.50000, 221, 0.35000)` + result, err := taos.Exec(sql) + if err != nil { + fmt.Println("failed to insert, err:", err) + return + } + rowsAffected, err := result.RowsAffected() + if err != nil { + fmt.Println("failed to get affected rows, err:", err) + return + } + fmt.Println("RowsAffected", rowsAffected) +} + +func main() { + var taosDSN = "root:taosdata@http(localhost:6041)/" + taos, err := sql.Open("taosRestful", taosDSN) + if err != nil { + fmt.Println("failed to connect TDengine, err:", err) + return + } + defer taos.Close() + createStable(taos) + insertData(taos) +} diff --git a/docs/examples/go/insert/stmt/main.go b/docs/examples/go/insert/stmt/main.go new file mode 100644 index 0000000000000000000000000000000000000000..7093fdf1e52bc5a14fc92cec995fd81e70717d9f --- /dev/null +++ b/docs/examples/go/insert/stmt/main.go @@ -0,0 +1,73 @@ +package main + +import ( + "fmt" + "time" + + "github.com/taosdata/driver-go/v2/af" + "github.com/taosdata/driver-go/v2/af/param" + "github.com/taosdata/driver-go/v2/common" +) + +func checkErr(err error, prompt string) { + if err != nil { + fmt.Printf("%s\n", prompt) + panic(err) + } +} + +func prepareStable(conn *af.Connector) { + _, err := conn.Exec("CREATE DATABASE power") + checkErr(err, "failed to create database") + _, err = conn.Exec("CREATE STABLE power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)") + checkErr(err, "failed to create stable") + _, err = conn.Exec("USE power") + checkErr(err, "failed to change database") +} + +func main() { + conn, err := af.Open("localhost", "root", "taosdata", "", 6030) + checkErr(err, "fail to connect") + defer conn.Close() + prepareStable(conn) + // create stmt + stmt := conn.InsertStmt() + defer stmt.Close() + err = stmt.Prepare("INSERT INTO ? USING meters TAGS(?, ?) VALUES(?, ?, ?, ?)") + checkErr(err, "failed to create prepare statement") + + // bind table name and tags + tagParams := param.NewParam(2).AddBinary([]byte("California.SanFrancisco")).AddInt(2) + err = stmt.SetTableNameWithTags("d1001", tagParams) + checkErr(err, "failed to execute SetTableNameWithTags") + + // specify ColumnType + var bindType *param.ColumnType = param.NewColumnType(4).AddTimestamp().AddFloat().AddInt().AddFloat() + + // bind values. note: can only bind one row each time. + valueParams := []*param.Param{ + param.NewParam(1).AddTimestamp(time.Unix(1648432611, 249300000), common.PrecisionMilliSecond), + param.NewParam(1).AddFloat(10.3), + param.NewParam(1).AddInt(219), + param.NewParam(1).AddFloat(0.31), + } + err = stmt.BindParam(valueParams, bindType) + checkErr(err, "BindParam error") + err = stmt.AddBatch() + checkErr(err, "AddBatch error") + + // bind one more row + valueParams = []*param.Param{ + param.NewParam(1).AddTimestamp(time.Unix(1648432611, 749300000), common.PrecisionMilliSecond), + param.NewParam(1).AddFloat(12.6), + param.NewParam(1).AddInt(218), + param.NewParam(1).AddFloat(0.33), + } + err = stmt.BindParam(valueParams, bindType) + checkErr(err, "BindParam error") + err = stmt.AddBatch() + checkErr(err, "AddBatch error") + // execute + err = stmt.Execute() + checkErr(err, "Execute batch error") +} diff --git a/docs/examples/go/insert/telnet/main.go b/docs/examples/go/insert/telnet/main.go new file mode 100644 index 0000000000000000000000000000000000000000..91fafbe71adbf60d9341b903f5a25708b7011852 --- /dev/null +++ b/docs/examples/go/insert/telnet/main.go @@ -0,0 +1,42 @@ +package main + +import ( + "fmt" + + "github.com/taosdata/driver-go/v2/af" +) + +func prepareDatabase(conn *af.Connector) { + _, err := conn.Exec("CREATE DATABASE test") + if err != nil { + panic(err) + } + _, err = conn.Exec("USE test") + if err != nil { + panic(err) + } +} + +func main() { + conn, err := af.Open("localhost", "root", "taosdata", "", 6030) + if err != nil { + fmt.Println("fail to connect, err:", err) + } + defer conn.Close() + prepareDatabase(conn) + var lines = []string{ + "meters.current 1648432611249 10.3 location=California.SanFrancisco groupid=2", + "meters.current 1648432611250 12.6 location=California.SanFrancisco groupid=2", + "meters.current 1648432611249 10.8 location=California.LosAngeles groupid=3", + "meters.current 1648432611250 11.3 location=California.LosAngeles groupid=3", + "meters.voltage 1648432611249 219 location=California.SanFrancisco groupid=2", + "meters.voltage 1648432611250 218 location=California.SanFrancisco groupid=2", + "meters.voltage 1648432611249 221 location=California.LosAngeles groupid=3", + "meters.voltage 1648432611250 217 location=California.LosAngeles groupid=3", + } + + err = conn.OpenTSDBInsertTelnetLines(lines) + if err != nil { + fmt.Println("insert error:", err) + } +} diff --git a/docs-examples/go/query/async/main.go b/docs/examples/go/query/async/main.go similarity index 100% rename from docs-examples/go/query/async/main.go rename to docs/examples/go/query/async/main.go diff --git a/docs-examples/go/query/sync/main.go b/docs/examples/go/query/sync/main.go similarity index 100% rename from docs-examples/go/query/sync/main.go rename to docs/examples/go/query/sync/main.go diff --git a/docs-examples/go/rest/opentsdbjson/main.go b/docs/examples/go/rest/opentsdbjson/main.go similarity index 100% rename from docs-examples/go/rest/opentsdbjson/main.go rename to docs/examples/go/rest/opentsdbjson/main.go diff --git a/docs-examples/go/sub/main.go b/docs/examples/go/sub/main.go similarity index 100% rename from docs-examples/go/sub/main.go rename to docs/examples/go/sub/main.go diff --git a/docs-examples/java/.gitignore b/docs/examples/java/.gitignore similarity index 100% rename from docs-examples/java/.gitignore rename to docs/examples/java/.gitignore diff --git a/docs-examples/java/pom.xml b/docs/examples/java/pom.xml similarity index 100% rename from docs-examples/java/pom.xml rename to docs/examples/java/pom.xml diff --git a/docs/examples/java/src/main/java/com/taos/example/JNIConnectExample.java b/docs/examples/java/src/main/java/com/taos/example/JNIConnectExample.java new file mode 100644 index 0000000000000000000000000000000000000000..84292f7e8682dbb8171c807da74a603f4ae8256e --- /dev/null +++ b/docs/examples/java/src/main/java/com/taos/example/JNIConnectExample.java @@ -0,0 +1,25 @@ +package com.taos.example; + +import java.sql.Connection; +import java.sql.DriverManager; +import java.sql.SQLException; +import java.util.Properties; + +import com.taosdata.jdbc.TSDBDriver; + +public class JNIConnectExample { + public static void main(String[] args) throws SQLException { + String jdbcUrl = "jdbc:TAOS://localhost:6030?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); + System.out.println("Connected"); + conn.close(); + } +} + +// use +// String jdbcUrl = "jdbc:TAOS://localhost:6030/dbName?user=root&password=taosdata"; +// if you want to connect a specified database named "dbName". \ No newline at end of file diff --git a/docs/examples/java/src/main/java/com/taos/example/JSONProtocolExample.java b/docs/examples/java/src/main/java/com/taos/example/JSONProtocolExample.java new file mode 100644 index 0000000000000000000000000000000000000000..c8e649482fbd747cdc238daa9e7a237cf63295b6 --- /dev/null +++ b/docs/examples/java/src/main/java/com/taos/example/JSONProtocolExample.java @@ -0,0 +1,40 @@ +package com.taos.example; + +import com.taosdata.jdbc.SchemalessWriter; +import com.taosdata.jdbc.enums.SchemalessProtocolType; +import com.taosdata.jdbc.enums.SchemalessTimestampType; + +import java.sql.Connection; +import java.sql.DriverManager; +import java.sql.SQLException; +import java.sql.Statement; + +public class JSONProtocolExample { + private static Connection getConnection() throws SQLException { + String jdbcUrl = "jdbc:TAOS://localhost:6030?user=root&password=taosdata"; + return DriverManager.getConnection(jdbcUrl); + } + + private static void createDatabase(Connection conn) throws SQLException { + try (Statement stmt = conn.createStatement()) { + stmt.execute("CREATE DATABASE IF NOT EXISTS test"); + stmt.execute("USE test"); + } + } + + private static String getJSONData() { + return "[{\"metric\": \"meters.current\", \"timestamp\": 1648432611249, \"value\": 10.3, \"tags\": {\"location\": \"California.SanFrancisco\", \"groupid\": 2}}," + + " {\"metric\": \"meters.voltage\", \"timestamp\": 1648432611249, \"value\": 219, \"tags\": {\"location\": \"California.LosAngeles\", \"groupid\": 1}}, " + + "{\"metric\": \"meters.current\", \"timestamp\": 1648432611250, \"value\": 12.6, \"tags\": {\"location\": \"California.SanFrancisco\", \"groupid\": 2}}," + + " {\"metric\": \"meters.voltage\", \"timestamp\": 1648432611250, \"value\": 221, \"tags\": {\"location\": \"California.LosAngeles\", \"groupid\": 1}}]"; + } + + public static void main(String[] args) throws SQLException { + try (Connection conn = getConnection()) { + createDatabase(conn); + SchemalessWriter writer = new SchemalessWriter(conn); + String jsonData = getJSONData(); + writer.write(jsonData, SchemalessProtocolType.JSON, SchemalessTimestampType.NOT_CONFIGURED); + } + } +} diff --git a/docs/examples/java/src/main/java/com/taos/example/LineProtocolExample.java b/docs/examples/java/src/main/java/com/taos/example/LineProtocolExample.java new file mode 100644 index 0000000000000000000000000000000000000000..990922b7a516bd32a7e299f5743bd1b5e321868a --- /dev/null +++ b/docs/examples/java/src/main/java/com/taos/example/LineProtocolExample.java @@ -0,0 +1,42 @@ +package com.taos.example; + +import com.taosdata.jdbc.SchemalessWriter; +import com.taosdata.jdbc.enums.SchemalessProtocolType; +import com.taosdata.jdbc.enums.SchemalessTimestampType; + +import java.sql.Connection; +import java.sql.DriverManager; +import java.sql.SQLException; +import java.sql.Statement; + +public class LineProtocolExample { + // format: measurement,tag_set field_set timestamp + private static String[] lines = { + "meters,location=California.LosAngeles,groupid=2 current=11.8,voltage=221,phase=0.28 1648432611249000", // micro + // seconds + "meters,location=California.LosAngeles,groupid=2 current=13.4,voltage=223,phase=0.29 1648432611249500", + "meters,location=California.LosAngeles,groupid=3 current=10.8,voltage=223,phase=0.29 1648432611249300", + "meters,location=California.LosAngeles,groupid=3 current=11.3,voltage=221,phase=0.35 1648432611249800", + }; + + private static Connection getConnection() throws SQLException { + String jdbcUrl = "jdbc:TAOS://localhost:6030?user=root&password=taosdata"; + return DriverManager.getConnection(jdbcUrl); + } + + private static void createDatabase(Connection conn) throws SQLException { + try (Statement stmt = conn.createStatement()) { + // the default precision is ms (microsecond), but we use us(microsecond) here. + stmt.execute("CREATE DATABASE IF NOT EXISTS test PRECISION 'us'"); + stmt.execute("USE test"); + } + } + + public static void main(String[] args) throws SQLException { + try (Connection conn = getConnection()) { + createDatabase(conn); + SchemalessWriter writer = new SchemalessWriter(conn); + writer.write(lines, SchemalessProtocolType.LINE, SchemalessTimestampType.MICRO_SECONDS); + } + } +} diff --git a/docs-examples/java/src/main/java/com/taos/example/RESTConnectExample.java b/docs/examples/java/src/main/java/com/taos/example/RESTConnectExample.java similarity index 100% rename from docs-examples/java/src/main/java/com/taos/example/RESTConnectExample.java rename to docs/examples/java/src/main/java/com/taos/example/RESTConnectExample.java diff --git a/docs/examples/java/src/main/java/com/taos/example/RestInsertExample.java b/docs/examples/java/src/main/java/com/taos/example/RestInsertExample.java new file mode 100644 index 0000000000000000000000000000000000000000..af97fe4373ca964260e5614f133f359e229b0e15 --- /dev/null +++ b/docs/examples/java/src/main/java/com/taos/example/RestInsertExample.java @@ -0,0 +1,74 @@ +package com.taos.example; + +import java.sql.Connection; +import java.sql.DriverManager; +import java.sql.SQLException; +import java.sql.Statement; +import java.util.Arrays; +import java.util.List; + + +public class RestInsertExample { + private static Connection getConnection() throws SQLException { + String jdbcUrl = "jdbc:TAOS-RS://localhost:6041?user=root&password=taosdata"; + return DriverManager.getConnection(jdbcUrl); + } + + private static List getRawData() { + return Arrays.asList( + "d1001,2018-10-03 14:38:05.000,10.30000,219,0.31000,California.SanFrancisco,2", + "d1001,2018-10-03 14:38:15.000,12.60000,218,0.33000,California.SanFrancisco,2", + "d1001,2018-10-03 14:38:16.800,12.30000,221,0.31000,California.SanFrancisco,2", + "d1002,2018-10-03 14:38:16.650,10.30000,218,0.25000,California.SanFrancisco,3", + "d1003,2018-10-03 14:38:05.500,11.80000,221,0.28000,California.LosAngeles,2", + "d1003,2018-10-03 14:38:16.600,13.40000,223,0.29000,California.LosAngeles,2", + "d1004,2018-10-03 14:38:05.000,10.80000,223,0.29000,California.LosAngeles,3", + "d1004,2018-10-03 14:38:06.500,11.50000,221,0.35000,California.LosAngeles,3" + ); + } + + + /** + * The generated SQL is: + * INSERT INTO power.d1001 USING power.meters TAGS(California.SanFrancisco, 2) VALUES('2018-10-03 14:38:05.000',10.30000,219,0.31000) + * power.d1001 USING power.meters TAGS(California.SanFrancisco, 2) VALUES('2018-10-03 14:38:15.000',12.60000,218,0.33000) + * power.d1001 USING power.meters TAGS(California.SanFrancisco, 2) VALUES('2018-10-03 14:38:16.800',12.30000,221,0.31000) + * power.d1002 USING power.meters TAGS(California.SanFrancisco, 3) VALUES('2018-10-03 14:38:16.650',10.30000,218,0.25000) + * power.d1003 USING power.meters TAGS(California.LosAngeles, 2) VALUES('2018-10-03 14:38:05.500',11.80000,221,0.28000) + * power.d1003 USING power.meters TAGS(California.LosAngeles, 2) VALUES('2018-10-03 14:38:16.600',13.40000,223,0.29000) + * power.d1004 USING power.meters TAGS(California.LosAngeles, 3) VALUES('2018-10-03 14:38:05.000',10.80000,223,0.29000) + * power.d1004 USING power.meters TAGS(California.LosAngeles, 3) VALUES('2018-10-03 14:38:06.500',11.50000,221,0.35000) + */ + private static String getSQL() { + StringBuilder sb = new StringBuilder("INSERT INTO "); + for (String line : getRawData()) { + String[] ps = line.split(","); + sb.append("power." + ps[0]).append(" USING power.meters TAGS(") + .append(ps[5]).append(", ") // tag: location + .append(ps[6]) // tag: groupId + .append(") VALUES(") + .append('\'').append(ps[1]).append('\'').append(",") // ts + .append(ps[2]).append(",") // current + .append(ps[3]).append(",") // voltage + .append(ps[4]).append(") "); // phase + } + return sb.toString(); + } + + public static void insertData() throws SQLException { + try (Connection conn = getConnection()) { + try (Statement stmt = conn.createStatement()) { + stmt.execute("CREATE DATABASE power KEEP 3650"); + stmt.execute("CREATE STABLE power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) " + + "TAGS (location BINARY(64), groupId INT)"); + String sql = getSQL(); + int rowCount = stmt.executeUpdate(sql); + System.out.println("rowCount=" + rowCount); // rowCount=8 + } + } + } + + public static void main(String[] args) throws SQLException { + insertData(); + } +} diff --git a/docs/examples/java/src/main/java/com/taos/example/RestQueryExample.java b/docs/examples/java/src/main/java/com/taos/example/RestQueryExample.java new file mode 100644 index 0000000000000000000000000000000000000000..a3581a1f4733e8bf3e3f561bb6cab5a725d8a1c0 --- /dev/null +++ b/docs/examples/java/src/main/java/com/taos/example/RestQueryExample.java @@ -0,0 +1,55 @@ +package com.taos.example; + +import java.sql.*; + +public class RestQueryExample { + private static Connection getConnection() throws SQLException { + String jdbcUrl = "jdbc:TAOS-RS://localhost:6041/power?user=root&password=taosdata"; + return DriverManager.getConnection(jdbcUrl); + } + + private static void printRow(ResultSet rs) throws SQLException { + ResultSetMetaData meta = rs.getMetaData(); + for (int i = 1; i <= meta.getColumnCount(); i++) { + String value = rs.getString(i); + System.out.print(value); + System.out.print("\t"); + } + System.out.println(); + } + + private static void printColName(ResultSet rs) throws SQLException { + ResultSetMetaData meta = rs.getMetaData(); + for (int i = 1; i <= meta.getColumnCount(); i++) { + String colLabel = meta.getColumnLabel(i); + System.out.print(colLabel); + System.out.print("\t"); + } + System.out.println(); + } + + private static void processResult(ResultSet rs) throws SQLException { + printColName(rs); + while (rs.next()) { + printRow(rs); + } + } + + private static void queryData() throws SQLException { + try (Connection conn = getConnection()) { + try (Statement stmt = conn.createStatement()) { + ResultSet rs = stmt.executeQuery("SELECT AVG(voltage) FROM meters GROUP BY location"); + processResult(rs); + } + } + } + + public static void main(String[] args) throws SQLException { + queryData(); + } +} + +// possible output: +// avg(voltage) location +// 222.0 California.LosAngeles +// 219.0 California.SanFrancisco diff --git a/docs/examples/java/src/main/java/com/taos/example/StmtInsertExample.java b/docs/examples/java/src/main/java/com/taos/example/StmtInsertExample.java new file mode 100644 index 0000000000000000000000000000000000000000..bbcc92b22f67c31384b0fb7a082975eaac2ff2bc --- /dev/null +++ b/docs/examples/java/src/main/java/com/taos/example/StmtInsertExample.java @@ -0,0 +1,84 @@ +package com.taos.example; + +import com.taosdata.jdbc.TSDBPreparedStatement; + +import java.sql.Connection; +import java.sql.DriverManager; +import java.sql.SQLException; +import java.sql.Statement; +import java.time.LocalDateTime; +import java.time.ZoneOffset; +import java.time.format.DateTimeFormatter; +import java.util.ArrayList; +import java.util.Arrays; +import java.util.List; + +public class StmtInsertExample { + private static ArrayList tsToLongArray(String ts) { + ArrayList result = new ArrayList<>(); + DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss.SSS"); + LocalDateTime localDateTime = LocalDateTime.parse(ts, formatter); + result.add(localDateTime.toInstant(ZoneOffset.of("+8")).toEpochMilli()); + return result; + } + + private static ArrayList toArray(T v) { + ArrayList result = new ArrayList<>(); + result.add(v); + return result; + } + + private static List getRawData() { + return Arrays.asList( + "d1001,2018-10-03 14:38:05.000,10.30000,219,0.31000,California.SanFrancisco,2", + "d1001,2018-10-03 14:38:15.000,12.60000,218,0.33000,California.SanFrancisco,2", + "d1001,2018-10-03 14:38:16.800,12.30000,221,0.31000,California.SanFrancisco,2", + "d1002,2018-10-03 14:38:16.650,10.30000,218,0.25000,California.SanFrancisco,3", + "d1003,2018-10-03 14:38:05.500,11.80000,221,0.28000,California.LosAngeles,2", + "d1003,2018-10-03 14:38:16.600,13.40000,223,0.29000,California.LosAngeles,2", + "d1004,2018-10-03 14:38:05.000,10.80000,223,0.29000,California.LosAngeles,3", + "d1004,2018-10-03 14:38:06.500,11.50000,221,0.35000,California.LosAngeles,3" + ); + } + + private static Connection getConnection() throws SQLException { + String jdbcUrl = "jdbc:TAOS://localhost:6030?user=root&password=taosdata"; + return DriverManager.getConnection(jdbcUrl); + } + + private static void createTable(Connection conn) throws SQLException { + try (Statement stmt = conn.createStatement()) { + stmt.execute("CREATE DATABASE power KEEP 3650"); + stmt.executeUpdate("USE power"); + stmt.execute("CREATE STABLE meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) " + + "TAGS (location BINARY(64), groupId INT)"); + } + } + + private static void insertData() throws SQLException { + try (Connection conn = getConnection()) { + createTable(conn); + String psql = "INSERT INTO ? USING meters TAGS(?, ?) VALUES(?, ?, ?, ?)"; + try (TSDBPreparedStatement pst = (TSDBPreparedStatement) conn.prepareStatement(psql)) { + for (String line : getRawData()) { + String[] ps = line.split(","); + // bind table name and tags + pst.setTableName(ps[0]); + pst.setTagString(0, ps[5]); + pst.setTagInt(1, Integer.valueOf(ps[6])); + // bind values + pst.setTimestamp(0, tsToLongArray(ps[1])); //ps[1] looks like: 2018-10-03 14:38:05.000 + pst.setFloat(1, toArray(Float.valueOf(ps[2]))); + pst.setInt(2, toArray(Integer.valueOf(ps[3]))); + pst.setFloat(3, toArray(Float.valueOf(ps[4]))); + pst.columnDataAddBatch(); + } + pst.columnDataExecuteBatch(); + } + } + } + + public static void main(String[] args) throws SQLException { + insertData(); + } +} diff --git a/docs-examples/java/src/main/java/com/taos/example/SubscribeDemo.java b/docs/examples/java/src/main/java/com/taos/example/SubscribeDemo.java similarity index 100% rename from docs-examples/java/src/main/java/com/taos/example/SubscribeDemo.java rename to docs/examples/java/src/main/java/com/taos/example/SubscribeDemo.java diff --git a/docs/examples/java/src/main/java/com/taos/example/TelnetLineProtocolExample.java b/docs/examples/java/src/main/java/com/taos/example/TelnetLineProtocolExample.java new file mode 100644 index 0000000000000000000000000000000000000000..4c9368288df74f829121aeab5b925d1d083d29f0 --- /dev/null +++ b/docs/examples/java/src/main/java/com/taos/example/TelnetLineProtocolExample.java @@ -0,0 +1,45 @@ +package com.taos.example; + +import com.taosdata.jdbc.SchemalessWriter; +import com.taosdata.jdbc.enums.SchemalessProtocolType; +import com.taosdata.jdbc.enums.SchemalessTimestampType; + +import java.sql.Connection; +import java.sql.DriverManager; +import java.sql.SQLException; +import java.sql.Statement; + +public class TelnetLineProtocolExample { + // format: =[ =] + private static String[] lines = { "meters.current 1648432611249 10.3 location=California.SanFrancisco groupid=2", + "meters.current 1648432611250 12.6 location=California.SanFrancisco groupid=2", + "meters.current 1648432611249 10.8 location=California.LosAngeles groupid=3", + "meters.current 1648432611250 11.3 location=California.LosAngeles groupid=3", + "meters.voltage 1648432611249 219 location=California.SanFrancisco groupid=2", + "meters.voltage 1648432611250 218 location=California.SanFrancisco groupid=2", + "meters.voltage 1648432611249 221 location=California.LosAngeles groupid=3", + "meters.voltage 1648432611250 217 location=California.LosAngeles groupid=3", + }; + + private static Connection getConnection() throws SQLException { + String jdbcUrl = "jdbc:TAOS://localhost:6030?user=root&password=taosdata"; + return DriverManager.getConnection(jdbcUrl); + } + + private static void createDatabase(Connection conn) throws SQLException { + try (Statement stmt = conn.createStatement()) { + // the default precision is ms (microsecond), but we use us(microsecond) here. + stmt.execute("CREATE DATABASE IF NOT EXISTS test precision 'us'"); + stmt.execute("USE test"); + } + } + + public static void main(String[] args) throws SQLException { + try (Connection conn = getConnection()) { + createDatabase(conn); + SchemalessWriter writer = new SchemalessWriter(conn); + writer.write(lines, SchemalessProtocolType.TELNET, SchemalessTimestampType.NOT_CONFIGURED); + } + } + +} diff --git a/docs-examples/java/src/main/java/com/taos/example/WSConnectExample.java b/docs/examples/java/src/main/java/com/taos/example/WSConnectExample.java similarity index 100% rename from docs-examples/java/src/main/java/com/taos/example/WSConnectExample.java rename to docs/examples/java/src/main/java/com/taos/example/WSConnectExample.java diff --git a/docs/examples/java/src/test/java/com/taos/test/TestAll.java b/docs/examples/java/src/test/java/com/taos/test/TestAll.java new file mode 100644 index 0000000000000000000000000000000000000000..42db24485afec05298159f7b0c3a4e15835d98ed --- /dev/null +++ b/docs/examples/java/src/test/java/com/taos/test/TestAll.java @@ -0,0 +1,91 @@ +package com.taos.test; + +import com.taos.example.*; +import org.junit.FixMethodOrder; +import org.junit.Test; + +import java.sql.*; + +@FixMethodOrder +public class TestAll { + private String[] args = new String[]{}; + + public void dropDB(String dbName) throws SQLException { + String jdbcUrl = "jdbc:TAOS://localhost:6030?user=root&password=taosdata"; + try (Connection conn = DriverManager.getConnection(jdbcUrl)) { + try (Statement stmt = conn.createStatement()) { + stmt.execute("drop database if exists " + dbName); + } + } + } + + public void insertData() throws SQLException { + String jdbcUrl = "jdbc:TAOS://localhost:6030?user=root&password=taosdata"; + try (Connection conn = DriverManager.getConnection(jdbcUrl)) { + try (Statement stmt = conn.createStatement()) { + String sql = "INSERT INTO power.d1001 USING power.meters TAGS(California.SanFrancisco, 2) VALUES('2018-10-03 14:38:05.000',10.30000,219,0.31000)\n" + + " power.d1001 USING power.meters TAGS(California.SanFrancisco, 2) VALUES('2018-10-03 15:38:15.000',12.60000,218,0.33000)\n" + + " power.d1001 USING power.meters TAGS(California.SanFrancisco, 2) VALUES('2018-10-03 15:38:16.800',12.30000,221,0.31000)\n" + + " power.d1002 USING power.meters TAGS(California.SanFrancisco, 3) VALUES('2018-10-03 15:38:16.650',10.30000,218,0.25000)\n" + + " power.d1003 USING power.meters TAGS(California.LosAngeles, 2) VALUES('2018-10-03 15:38:05.500',11.80000,221,0.28000)\n" + + " power.d1003 USING power.meters TAGS(California.LosAngeles, 2) VALUES('2018-10-03 15:38:16.600',13.40000,223,0.29000)\n" + + " power.d1004 USING power.meters TAGS(California.LosAngeles, 3) VALUES('2018-10-03 15:38:05.000',10.80000,223,0.29000)\n" + + " power.d1004 USING power.meters TAGS(California.LosAngeles, 3) VALUES('2018-10-03 15:38:06.000',10.80000,223,0.29000)\n" + + " power.d1004 USING power.meters TAGS(California.LosAngeles, 3) VALUES('2018-10-03 15:38:07.000',10.80000,223,0.29000)\n" + + " power.d1004 USING power.meters TAGS(California.LosAngeles, 3) VALUES('2018-10-03 15:38:08.500',11.50000,221,0.35000)"; + + stmt.execute(sql); + } + } + } + + @Test + public void testJNIConnect() throws SQLException { + JNIConnectExample.main(args); + } + + @Test + public void testRestConnect() throws SQLException { + RESTConnectExample.main(args); + } + + @Test + public void testRestInsert() throws SQLException { + dropDB("power"); + RestInsertExample.main(args); + RestQueryExample.main(args); + } + + @Test + public void testStmtInsert() throws SQLException { + dropDB("power"); + StmtInsertExample.main(args); + } + + @Test + public void testSubscribe() { + + Thread thread = new Thread(() -> { + try { + Thread.sleep(1000); + insertData(); + } catch (SQLException e) { + e.printStackTrace(); + } catch (InterruptedException e) { + e.printStackTrace(); + } + }); + thread.start(); + SubscribeDemo.main(args); + } + + @Test + public void testSchemaless() throws SQLException { + LineProtocolExample.main(args); + TelnetLineProtocolExample.main(args); + // for json protocol, tags may be double type. but for telnet protocol tag must be nchar type. + // To avoid type mismatch, we delete database test. + dropDB("test"); + JSONProtocolExample.main(args); + } +} diff --git a/docs-examples/node/.gitignore b/docs/examples/node/.gitignore similarity index 100% rename from docs-examples/node/.gitignore rename to docs/examples/node/.gitignore diff --git a/docs-examples/node/nativeexample/async_query_example.js b/docs/examples/node/nativeexample/async_query_example.js similarity index 100% rename from docs-examples/node/nativeexample/async_query_example.js rename to docs/examples/node/nativeexample/async_query_example.js diff --git a/docs-examples/node/nativeexample/connect.js b/docs/examples/node/nativeexample/connect.js similarity index 100% rename from docs-examples/node/nativeexample/connect.js rename to docs/examples/node/nativeexample/connect.js diff --git a/docs/examples/node/nativeexample/influxdb_line_example.js b/docs/examples/node/nativeexample/influxdb_line_example.js new file mode 100644 index 0000000000000000000000000000000000000000..2050bee54506a3ee6fe7d89de97b3b41334dd4a6 --- /dev/null +++ b/docs/examples/node/nativeexample/influxdb_line_example.js @@ -0,0 +1,34 @@ +const taos = require("td2.0-connector"); + +const conn = taos.connect({ + host: "localhost", +}); + +const cursor = conn.cursor(); + +function createDatabase() { + cursor.execute("CREATE DATABASE test"); + cursor.execute("USE test"); +} + +function insertData() { + const lines = [ + "meters,location=California.LosAngeles,groupid=2 current=11.8,voltage=221,phase=0.28 1648432611249", + "meters,location=California.LosAngeles,groupid=2 current=13.4,voltage=223,phase=0.29 1648432611250", + "meters,location=California.LosAngeles,groupid=3 current=10.8,voltage=223,phase=0.29 1648432611249", + "meters,location=California.LosAngeles,groupid=3 current=11.3,voltage=221,phase=0.35 1648432611250", + ]; + cursor.schemalessInsert( + lines, + taos.SCHEMALESS_PROTOCOL.TSDB_SML_LINE_PROTOCOL, + taos.SCHEMALESS_PRECISION.TSDB_SML_TIMESTAMP_MILLI_SECONDS + ); +} + +try { + createDatabase(); + insertData(); +} finally { + cursor.close(); + conn.close(); +} diff --git a/docs/examples/node/nativeexample/insert_example.js b/docs/examples/node/nativeexample/insert_example.js new file mode 100644 index 0000000000000000000000000000000000000000..ade9d83158362cbf00a856b43a973de31def7601 --- /dev/null +++ b/docs/examples/node/nativeexample/insert_example.js @@ -0,0 +1,31 @@ +const taos = require("td2.0-connector"); + +const conn = taos.connect({ + host: "localhost", +}); + +const cursor = conn.cursor(); +try { + cursor.execute("CREATE DATABASE power"); + cursor.execute("USE power"); + cursor.execute( + "CREATE STABLE meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)" + ); + var sql = `INSERT INTO power.d1001 USING power.meters TAGS(California.SanFrancisco, 2) VALUES ('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) +power.d1002 USING power.meters TAGS(California.SanFrancisco, 3) VALUES ('2018-10-03 14:38:16.650', 10.30000, 218, 0.25000) +power.d1003 USING power.meters TAGS(California.LosAngeles, 2) VALUES ('2018-10-03 14:38:05.500', 11.80000, 221, 0.28000) ('2018-10-03 14:38:16.600', 13.40000, 223, 0.29000) +power.d1004 USING power.meters TAGS(California.LosAngeles, 3) VALUES ('2018-10-03 14:38:05.000', 10.80000, 223, 0.29000) ('2018-10-03 14:38:06.500', 11.50000, 221, 0.35000)`; + cursor.execute(sql); +} finally { + cursor.close(); + conn.close(); +} + +// run with: node insert_example.js +// output: +// Successfully connected to TDengine +// Query OK, 0 row(s) affected (0.00509570s) +// Query OK, 0 row(s) affected (0.00130880s) +// Query OK, 0 row(s) affected (0.00467900s) +// Query OK, 8 row(s) affected (0.04043550s) +// Connection is closed diff --git a/docs/examples/node/nativeexample/multi_bind_example.js b/docs/examples/node/nativeexample/multi_bind_example.js new file mode 100644 index 0000000000000000000000000000000000000000..6ef8b30c097393fef8c6a2837f8683c736b363f1 --- /dev/null +++ b/docs/examples/node/nativeexample/multi_bind_example.js @@ -0,0 +1,53 @@ +const taos = require("td2.0-connector"); + +const conn = taos.connect({ + host: "localhost", +}); + +const cursor = conn.cursor(); + +function prepareSTable() { + cursor.execute("CREATE DATABASE power"); + cursor.execute("USE power"); + cursor.execute( + "CREATE STABLE meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)" + ); +} + +//ANCHOR: insertData +function insertData() { + // init + cursor.stmtInit(); + // prepare + cursor.stmtPrepare( + "INSERT INTO ? USING meters TAGS(?, ?) VALUES(?, ?, ?, ?)" + ); + + // bind table name and tags + let tagBind = new taos.TaosBind(2); + tagBind.bindBinary("California.SanFrancisco"); + tagBind.bindInt(2); + cursor.stmtSetTbnameTags("d1001", tagBind.getBind()); + + // bind values + let valueBind = new taos.TaosMultiBindArr(4); + valueBind.multiBindTimestamp([1648432611249, 1648432611749]); + valueBind.multiBindFloat([10.3, 12.6]); + valueBind.multiBindInt([219, 218]); + valueBind.multiBindFloat([0.31, 0.33]); + cursor.stmtBindParamBatch(valueBind.getMultiBindArr()); + cursor.stmtAddBatch(); + + // execute + cursor.stmtExecute(); + cursor.stmtClose(); +} +//ANCHOR_END: insertData + +try { + prepareSTable(); + insertData(); +} finally { + cursor.close(); + conn.close(); +} diff --git a/docs/examples/node/nativeexample/opentsdb_json_example.js b/docs/examples/node/nativeexample/opentsdb_json_example.js new file mode 100644 index 0000000000000000000000000000000000000000..2d78444a3f805bc77ab5e11925a28dd18fe221fe --- /dev/null +++ b/docs/examples/node/nativeexample/opentsdb_json_example.js @@ -0,0 +1,55 @@ +const taos = require("td2.0-connector"); + +const conn = taos.connect({ + host: "localhost", +}); + +const cursor = conn.cursor(); + +function createDatabase() { + cursor.execute("CREATE DATABASE test"); + cursor.execute("USE test"); +} + +function insertData() { + const lines = [ + { + metric: "meters.current", + timestamp: 1648432611249, + value: 10.3, + tags: { location: "California.SanFrancisco", groupid: 2 }, + }, + { + metric: "meters.voltage", + timestamp: 1648432611249, + value: 219, + tags: { location: "California.LosAngeles", groupid: 1 }, + }, + { + metric: "meters.current", + timestamp: 1648432611250, + value: 12.6, + tags: { location: "California.SanFrancisco", groupid: 2 }, + }, + { + metric: "meters.voltage", + timestamp: 1648432611250, + value: 221, + tags: { location: "California.LosAngeles", groupid: 1 }, + }, + ]; + + cursor.schemalessInsert( + [JSON.stringify(lines)], + taos.SCHEMALESS_PROTOCOL.TSDB_SML_JSON_PROTOCOL, + taos.SCHEMALESS_PRECISION.TSDB_SML_TIMESTAMP_NOT_CONFIGURED + ); +} + +try { + createDatabase(); + insertData(); +} finally { + cursor.close(); + conn.close(); +} diff --git a/docs/examples/node/nativeexample/opentsdb_telnet_example.js b/docs/examples/node/nativeexample/opentsdb_telnet_example.js new file mode 100644 index 0000000000000000000000000000000000000000..7f80f558838e18f07ad79e580e7d08638b74e940 --- /dev/null +++ b/docs/examples/node/nativeexample/opentsdb_telnet_example.js @@ -0,0 +1,38 @@ +const taos = require("td2.0-connector"); + +const conn = taos.connect({ + host: "localhost", +}); + +const cursor = conn.cursor(); + +function createDatabase() { + cursor.execute("CREATE DATABASE test"); + cursor.execute("USE test"); +} + +function insertData() { + const lines = [ + "meters.current 1648432611249 10.3 location=California.SanFrancisco groupid=2", + "meters.current 1648432611250 12.6 location=California.SanFrancisco groupid=2", + "meters.current 1648432611249 10.8 location=California.LosAngeles groupid=3", + "meters.current 1648432611250 11.3 location=California.LosAngeles groupid=3", + "meters.voltage 1648432611249 219 location=California.SanFrancisco groupid=2", + "meters.voltage 1648432611250 218 location=California.SanFrancisco groupid=2", + "meters.voltage 1648432611249 221 location=California.LosAngeles groupid=3", + "meters.voltage 1648432611250 217 location=California.LosAngeles groupid=3", + ]; + cursor.schemalessInsert( + lines, + taos.SCHEMALESS_PROTOCOL.TSDB_SML_TELNET_PROTOCOL, + taos.SCHEMALESS_PRECISION.TSDB_SML_TIMESTAMP_NOT_CONFIGURED + ); +} + +try { + createDatabase(); + insertData(); +} finally { + cursor.close(); + conn.close(); +} diff --git a/docs/examples/node/nativeexample/param_bind_example.js b/docs/examples/node/nativeexample/param_bind_example.js new file mode 100644 index 0000000000000000000000000000000000000000..c7e04c71a0d19ff8666f3d43fe09109009741266 --- /dev/null +++ b/docs/examples/node/nativeexample/param_bind_example.js @@ -0,0 +1,57 @@ +const taos = require("td2.0-connector"); + +const conn = taos.connect({ + host: "localhost", +}); + +const cursor = conn.cursor(); + +function prepareSTable() { + cursor.execute("CREATE DATABASE power"); + cursor.execute("USE power"); + cursor.execute( + "CREATE STABLE meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)" + ); +} + +function insertData() { + // init + cursor.stmtInit(); + // prepare + cursor.stmtPrepare( + "INSERT INTO ? USING meters TAGS(?, ?) VALUES(?, ?, ?, ?)" + ); + + // bind table name and tags + let tagBind = new taos.TaosBind(2); + tagBind.bindBinary("California.SanFrancisco"); + tagBind.bindInt(2); + cursor.stmtSetTbnameTags("d1001", tagBind.getBind()); + + // bind values + let rows = [ + [1648432611249, 10.3, 219, 0.31], + [1648432611749, 12.6, 218, 0.33], + ]; + for (let row of rows) { + let valueBind = new taos.TaosBind(4); + valueBind.bindTimestamp(row[0]); + valueBind.bindFloat(row[1]); + valueBind.bindInt(row[2]); + valueBind.bindFloat(row[3]); + cursor.stmtBindParam(valueBind.getBind()); + cursor.stmtAddBatch(); + } + + // execute + cursor.stmtExecute(); + cursor.stmtClose(); +} + +try { + prepareSTable(); + insertData(); +} finally { + cursor.close(); + conn.close(); +} diff --git a/docs-examples/node/nativeexample/query_example.js b/docs/examples/node/nativeexample/query_example.js similarity index 100% rename from docs-examples/node/nativeexample/query_example.js rename to docs/examples/node/nativeexample/query_example.js diff --git a/docs-examples/node/nativeexample/subscribe_demo.js b/docs/examples/node/nativeexample/subscribe_demo.js similarity index 100% rename from docs-examples/node/nativeexample/subscribe_demo.js rename to docs/examples/node/nativeexample/subscribe_demo.js diff --git a/docs-examples/node/package.json b/docs/examples/node/package.json similarity index 100% rename from docs-examples/node/package.json rename to docs/examples/node/package.json diff --git a/docs-examples/node/restexample/connect.js b/docs/examples/node/restexample/connect.js similarity index 100% rename from docs-examples/node/restexample/connect.js rename to docs/examples/node/restexample/connect.js diff --git a/docs/examples/other/mock.js b/docs/examples/other/mock.js new file mode 100644 index 0000000000000000000000000000000000000000..136c5afa96425073fc29854708495e98d0b2e743 --- /dev/null +++ b/docs/examples/other/mock.js @@ -0,0 +1,78 @@ +// mock.js +const mqtt = require('mqtt') +const Mock = require('mockjs') +const EMQX_SERVER = 'mqtt://localhost:1883' +const CLIENT_NUM = 10 +const STEP = 5000 // Data interval in ms +const AWAIT = 5000 // Sleep time after data be written once to avoid data writing too fast +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, + } +} \ No newline at end of file diff --git a/docs/examples/php/connect.php b/docs/examples/php/connect.php new file mode 100644 index 0000000000000000000000000000000000000000..b825b447805a3923248042d2cdff79c51bdcdbe3 --- /dev/null +++ b/docs/examples/php/connect.php @@ -0,0 +1,20 @@ +connect(); +} catch (TDengineException $e) { + // throw exception + throw $e; +} diff --git a/docs/examples/php/insert.php b/docs/examples/php/insert.php new file mode 100644 index 0000000000000000000000000000000000000000..6e38fa0c46d31aa0a939d471ccbd255cfa453a16 --- /dev/null +++ b/docs/examples/php/insert.php @@ -0,0 +1,33 @@ +connect(); + + // insert + $connection->query('CREATE DATABASE if not exists power'); + $connection->query('CREATE STABLE if not exists meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)'); + $resource = $connection->query(<<<'SQL' + INSERT INTO power.d1001 USING power.meters TAGS(California.SanFrancisco, 2) VALUES ('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) + power.d1002 USING power.meters TAGS(California.SanFrancisco, 3) VALUES ('2018-10-03 14:38:16.650', 10.30000, 218, 0.25000) + power.d1003 USING power.meters TAGS(California.LosAngeles, 2) VALUES ('2018-10-03 14:38:05.500', 11.80000, 221, 0.28000) ('2018-10-03 14:38:16.600', 13.40000, 223, 0.29000) + power.d1004 USING power.meters TAGS(California.LosAngeles, 3) VALUES ('2018-10-03 14:38:05.000', 10.80000, 223, 0.29000) ('2018-10-03 14:38:06.500', 11.50000, 221, 0.35000) + SQL); + + // get affected rows + var_dump($resource->affectedRows()); +} catch (TDengineException $e) { + // throw exception + throw $e; +} diff --git a/docs/examples/php/insert_stmt.php b/docs/examples/php/insert_stmt.php new file mode 100644 index 0000000000000000000000000000000000000000..c927a9b0ced46461daeda0f53b27e2f9d67d5860 --- /dev/null +++ b/docs/examples/php/insert_stmt.php @@ -0,0 +1,49 @@ +connect(); + + // insert + $connection->query('CREATE DATABASE if not exists power'); + $connection->query('CREATE STABLE if not exists meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)'); + $stmt = $connection->prepare('INSERT INTO ? USING meters TAGS(?, ?) VALUES(?, ?, ?, ?)'); + + // set table name and tags + $stmt->setTableNameTags('d1001', [ + // same format as parameter binding + [TDengine\TSDB_DATA_TYPE_BINARY, 'California.SanFrancisco'], + [TDengine\TSDB_DATA_TYPE_INT, 2], + ]); + + $stmt->bindParams([ + [TDengine\TSDB_DATA_TYPE_TIMESTAMP, 1648432611249], + [TDengine\TSDB_DATA_TYPE_FLOAT, 10.3], + [TDengine\TSDB_DATA_TYPE_INT, 219], + [TDengine\TSDB_DATA_TYPE_FLOAT, 0.31], + ]); + $stmt->bindParams([ + [TDengine\TSDB_DATA_TYPE_TIMESTAMP, 1648432611749], + [TDengine\TSDB_DATA_TYPE_FLOAT, 12.6], + [TDengine\TSDB_DATA_TYPE_INT, 218], + [TDengine\TSDB_DATA_TYPE_FLOAT, 0.33], + ]); + $resource = $stmt->execute(); + + // get affected rows + var_dump($resource->affectedRows()); +} catch (TDengineException $e) { + // throw exception + throw $e; +} diff --git a/docs/examples/php/query.php b/docs/examples/php/query.php new file mode 100644 index 0000000000000000000000000000000000000000..2607940ea06a70eaa30e4c165c05bd72aa89857c --- /dev/null +++ b/docs/examples/php/query.php @@ -0,0 +1,23 @@ +connect(); + + $resource = $connection->query('SELECT ts, current FROM meters LIMIT 2'); + var_dump($resource->fetch()); +} catch (TDengineException $e) { + // throw exception + throw $e; +} diff --git a/docs-examples/python/.gitignore b/docs/examples/python/.gitignore similarity index 100% rename from docs-examples/python/.gitignore rename to docs/examples/python/.gitignore diff --git a/docs-examples/python/.gitkeep b/docs/examples/python/.gitkeep similarity index 100% rename from docs-examples/python/.gitkeep rename to docs/examples/python/.gitkeep diff --git a/docs-examples/python/async_query_example.py b/docs/examples/python/async_query_example.py similarity index 100% rename from docs-examples/python/async_query_example.py rename to docs/examples/python/async_query_example.py diff --git a/docs/examples/python/bind_param_example.py b/docs/examples/python/bind_param_example.py new file mode 100644 index 0000000000000000000000000000000000000000..6a67434f876f159cf32069a55e9527ca19034640 --- /dev/null +++ b/docs/examples/python/bind_param_example.py @@ -0,0 +1,60 @@ +import taos +from datetime import datetime + +# note: lines have already been sorted by table name +lines = [('d1001', '2018-10-03 14:38:05.000', 10.30000, 219, 0.31000, 'California.SanFrancisco', 2), + ('d1001', '2018-10-03 14:38:15.000', 12.60000, 218, 0.33000, 'California.SanFrancisco', 2), + ('d1001', '2018-10-03 14:38:16.800', 12.30000, 221, 0.31000, 'California.SanFrancisco', 2), + ('d1002', '2018-10-03 14:38:16.650', 10.30000, 218, 0.25000, 'California.SanFrancisco', 3), + ('d1003', '2018-10-03 14:38:05.500', 11.80000, 221, 0.28000, 'California.LosAngeles', 2), + ('d1003', '2018-10-03 14:38:16.600', 13.40000, 223, 0.29000, 'California.LosAngeles', 2), + ('d1004', '2018-10-03 14:38:05.000', 10.80000, 223, 0.29000, 'California.LosAngeles', 3), + ('d1004', '2018-10-03 14:38:06.500', 11.50000, 221, 0.35000, 'California.LosAngeles', 3)] + + +def get_ts(ts: str): + dt = datetime.strptime(ts, '%Y-%m-%d %H:%M:%S.%f') + return int(dt.timestamp() * 1000) + + +def create_stable(): + conn = taos.connect() + try: + conn.execute("CREATE DATABASE power") + conn.execute("CREATE STABLE power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) " + "TAGS (location BINARY(64), groupId INT)") + finally: + conn.close() + + +def bind_row_by_row(stmt: taos.TaosStmt): + tb_name = None + for row in lines: + if tb_name != row[0]: + tb_name = row[0] + tags: taos.TaosBind = taos.new_bind_params(2) # 2 is count of tags + tags[0].binary(row[5]) # location + tags[1].int(row[6]) # groupId + stmt.set_tbname_tags(tb_name, tags) + values: taos.TaosBind = taos.new_bind_params(4) # 4 is count of columns + values[0].timestamp(get_ts(row[1])) + values[1].float(row[2]) + values[2].int(row[3]) + values[3].float(row[4]) + stmt.bind_param(values) + + +def insert_data(): + conn = taos.connect(database="power") + try: + stmt = conn.statement("INSERT INTO ? USING meters TAGS(?, ?) VALUES(?, ?, ?, ?)") + bind_row_by_row(stmt) + stmt.execute() + stmt.close() + finally: + conn.close() + + +if __name__ == '__main__': + create_stable() + insert_data() diff --git a/docs/examples/python/conn_native_pandas.py b/docs/examples/python/conn_native_pandas.py new file mode 100644 index 0000000000000000000000000000000000000000..56942ef57085766cd128b03cabb7a357587eab16 --- /dev/null +++ b/docs/examples/python/conn_native_pandas.py @@ -0,0 +1,19 @@ +import pandas +from sqlalchemy import create_engine + +engine = create_engine("taos://root:taosdata@localhost:6030/power") +df = pandas.read_sql("SELECT * FROM meters", engine) + +# print index +print(df.index) +# print data type of element in ts column +print(type(df.ts[0])) +print(df.head(3)) + +# output: +# RangeIndex(start=0, stop=8, step=1) +# +# ts current ... location groupid +# 0 2018-10-03 14:38:05.500 11.8 ... california.losangeles 2 +# 1 2018-10-03 14:38:16.600 13.4 ... california.losangeles 2 +# 2 2018-10-03 14:38:05.000 10.8 ... california.losangeles 3 diff --git a/docs/examples/python/conn_rest_pandas.py b/docs/examples/python/conn_rest_pandas.py new file mode 100644 index 0000000000000000000000000000000000000000..0164080cd5a05e72dce40b1d111ea423623ff9b2 --- /dev/null +++ b/docs/examples/python/conn_rest_pandas.py @@ -0,0 +1,19 @@ +import pandas +from sqlalchemy import create_engine + +engine = create_engine("taosrest://root:taosdata@localhost:6041") +df: pandas.DataFrame = pandas.read_sql("SELECT * FROM power.meters", engine) + +# print index +print(df.index) +# print data type of element in ts column +print(type(df.ts[0])) +print(df.head(3)) + +# output: +# RangeIndex(start=0, stop=8, step=1) +# +# ts current ... location groupid +# 0 2018-10-03 06:38:05.500000+00:00 11.8 ... california.losangeles 2 +# 1 2018-10-03 06:38:16.600000+00:00 13.4 ... california.losangeles 2 +# 2 2018-10-03 06:38:05+00:00 10.8 ... california.losangeles 3 diff --git a/docs-examples/python/connect_exmaple.py b/docs/examples/python/connect_example.py similarity index 100% rename from docs-examples/python/connect_exmaple.py rename to docs/examples/python/connect_example.py diff --git a/docs-examples/python/connect_native_reference.py b/docs/examples/python/connect_native_reference.py similarity index 100% rename from docs-examples/python/connect_native_reference.py rename to docs/examples/python/connect_native_reference.py diff --git a/docs/examples/python/connect_rest_examples.py b/docs/examples/python/connect_rest_examples.py new file mode 100644 index 0000000000000000000000000000000000000000..900ec1022ec81ac2db761d918d1ec11c9bb26852 --- /dev/null +++ b/docs/examples/python/connect_rest_examples.py @@ -0,0 +1,43 @@ +# ANCHOR: connect +from taosrest import connect, TaosRestConnection, TaosRestCursor + +conn: TaosRestConnection = connect(url="http://localhost:6041", + user="root", + password="taosdata", + timeout=30) + +# ANCHOR_END: connect +# ANCHOR: basic +# create STable +cursor: TaosRestCursor = conn.cursor() +cursor.execute("DROP DATABASE IF EXISTS power") +cursor.execute("CREATE DATABASE power") +cursor.execute("CREATE STABLE power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)") + +# insert data +cursor.execute("""INSERT INTO power.d1001 USING power.meters TAGS(California.SanFrancisco, 2) VALUES ('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) + power.d1002 USING power.meters TAGS(California.SanFrancisco, 3) VALUES ('2018-10-03 14:38:16.650', 10.30000, 218, 0.25000) + power.d1003 USING power.meters TAGS(California.LosAngeles, 2) VALUES ('2018-10-03 14:38:05.500', 11.80000, 221, 0.28000) ('2018-10-03 14:38:16.600', 13.40000, 223, 0.29000) + power.d1004 USING power.meters TAGS(California.LosAngeles, 3) VALUES ('2018-10-03 14:38:05.000', 10.80000, 223, 0.29000) ('2018-10-03 14:38:06.500', 11.50000, 221, 0.35000)""") +print("inserted row count:", cursor.rowcount) + +# query data +cursor.execute("SELECT * FROM power.meters LIMIT 3") +# get total rows +print("queried row count:", cursor.rowcount) +# get column names from cursor +column_names = [meta[0] for meta in cursor.description] +# get rows +data: list[tuple] = cursor.fetchall() +print(column_names) +for row in data: + print(row) + +# output: +# inserted row count: 8 +# queried row count: 3 +# ['ts', 'current', 'voltage', 'phase', 'location', 'groupid'] +# [datetime.datetime(2018, 10, 3, 14, 38, 5, 500000, tzinfo=datetime.timezone(datetime.timedelta(seconds=28800), '+08:00')), 11.8, 221, 0.28, 'california.losangeles', 2] +# [datetime.datetime(2018, 10, 3, 14, 38, 16, 600000, tzinfo=datetime.timezone(datetime.timedelta(seconds=28800), '+08:00')), 13.4, 223, 0.29, 'california.losangeles', 2] +# [datetime.datetime(2018, 10, 3, 14, 38, 5, tzinfo=datetime.timezone(datetime.timedelta(seconds=28800), '+08:00')), 10.8, 223, 0.29, 'california.losangeles', 3] +# ANCHOR_END: basic diff --git a/docs-examples/python/connection_usage_native_reference.py b/docs/examples/python/connection_usage_native_reference.py similarity index 100% rename from docs-examples/python/connection_usage_native_reference.py rename to docs/examples/python/connection_usage_native_reference.py diff --git a/docs-examples/python/cursor_usage_native_reference.py b/docs/examples/python/cursor_usage_native_reference.py similarity index 100% rename from docs-examples/python/cursor_usage_native_reference.py rename to docs/examples/python/cursor_usage_native_reference.py diff --git a/docs-examples/python/handle_exception.py b/docs/examples/python/handle_exception.py similarity index 100% rename from docs-examples/python/handle_exception.py rename to docs/examples/python/handle_exception.py diff --git a/docs/examples/python/json_protocol_example.py b/docs/examples/python/json_protocol_example.py new file mode 100644 index 0000000000000000000000000000000000000000..58b38f3ff667bcbbd902434d3409441a4d2c5b45 --- /dev/null +++ b/docs/examples/python/json_protocol_example.py @@ -0,0 +1,38 @@ +import json + +import taos +from taos import SmlProtocol, SmlPrecision + +lines = [{"metric": "meters.current", "timestamp": 1648432611249, "value": 10.3, "tags": {"location": "California.SanFrancisco", "groupid": 2}}, + {"metric": "meters.voltage", "timestamp": 1648432611249, "value": 219, + "tags": {"location": "California.LosAngeles", "groupid": 1}}, + {"metric": "meters.current", "timestamp": 1648432611250, "value": 12.6, + "tags": {"location": "California.SanFrancisco", "groupid": 2}}, + {"metric": "meters.voltage", "timestamp": 1648432611250, "value": 221, "tags": {"location": "California.LosAngeles", "groupid": 1}}] + + +def get_connection(): + return taos.connect() + + +def create_database(conn): + conn.execute("CREATE DATABASE test") + conn.execute("USE test") + + +def insert_lines(conn): + global lines + lines = json.dumps(lines) + # note: the first parameter must be a list with only one element. + affected_rows = conn.schemaless_insert( + [lines], SmlProtocol.JSON_PROTOCOL, SmlPrecision.NOT_CONFIGURED) + print(affected_rows) # 4 + + +if __name__ == '__main__': + connection = get_connection() + try: + create_database(connection) + insert_lines(connection) + finally: + connection.close() diff --git a/docs/examples/python/line_protocol_example.py b/docs/examples/python/line_protocol_example.py new file mode 100644 index 0000000000000000000000000000000000000000..735e8e7eb8aed1a8133de7a6de50bd50d076c472 --- /dev/null +++ b/docs/examples/python/line_protocol_example.py @@ -0,0 +1,34 @@ +import taos +from taos import SmlProtocol, SmlPrecision + +lines = ["meters,location=California.LosAngeles,groupid=2 current=11.8,voltage=221,phase=0.28 1648432611249000", + "meters,location=California.LosAngeles,groupid=2 current=13.4,voltage=223,phase=0.29 1648432611249500", + "meters,location=California.LosAngeles,groupid=3 current=10.8,voltage=223,phase=0.29 1648432611249300", + "meters,location=California.LosAngeles,groupid=3 current=11.3,voltage=221,phase=0.35 1648432611249800", + ] + + +def get_connection(): + # create connection use firstEP in taos.cfg. + return taos.connect() + + +def create_database(conn): + # the default precision is ms (microsecond), but we use us(microsecond) here. + conn.execute("CREATE DATABASE test precision 'us'") + conn.execute("USE test") + + +def insert_lines(conn): + affected_rows = conn.schemaless_insert( + lines, SmlProtocol.LINE_PROTOCOL, SmlPrecision.MICRO_SECONDS) + print(affected_rows) # 8 + + +if __name__ == '__main__': + connection = get_connection() + try: + create_database(connection) + insert_lines(connection) + finally: + connection.close() diff --git a/docs/examples/python/multi_bind_example.py b/docs/examples/python/multi_bind_example.py new file mode 100644 index 0000000000000000000000000000000000000000..205ba69fb267ae1781415e4f0995b41f908ceb17 --- /dev/null +++ b/docs/examples/python/multi_bind_example.py @@ -0,0 +1,88 @@ +import taos +from datetime import datetime + +# ANCHOR: bind_batch +table_tags = { + "d1001": ('California.SanFrancisco', 2), + "d1002": ('California.SanFrancisco', 3), + "d1003": ('California.LosAngeles', 2), + "d1004": ('California.LosAngeles', 3) +} + +table_values = { + "d1001": [ + ['2018-10-03 14:38:05.000', '2018-10-03 14:38:15.000', '2018-10-03 14:38:16.800'], + [10.3, 12.6, 12.3], + [219, 218, 221], + [0.31, 0.33, 0.32] + ], + "d1002": [ + ['2018-10-03 14:38:16.650'], [10.3], [218], [0.25] + ], + "d1003": [ + ['2018-10-03 14:38:05.500', '2018-10-03 14:38:16.600'], + [11.8, 13.4], + [221, 223], + [0.28, 0.29] + ], + "d1004": [ + ['2018-10-03 14:38:05.500', '2018-10-03 14:38:06.500'], + [10.8, 11.5], + [223, 221], + [0.29, 0.35] + ] +} + + +def bind_multi_rows(stmt: taos.TaosStmt): + """ + batch bind example + """ + for tb_name in table_values.keys(): + tags = table_tags[tb_name] + tag_params = taos.new_bind_params(2) + tag_params[0].binary(tags[0]) + tag_params[1].int(tags[1]) + stmt.set_tbname_tags(tb_name, tag_params) + + values = table_values[tb_name] + value_params = taos.new_multi_binds(4) + value_params[0].timestamp([get_ts(t) for t in values[0]]) + value_params[1].float(values[1]) + value_params[2].int(values[2]) + value_params[3].float(values[3]) + stmt.bind_param_batch(value_params) + + +def insert_data(): + conn = taos.connect(database="power") + try: + stmt = conn.statement("INSERT INTO ? USING meters TAGS(?, ?) VALUES(?, ?, ?, ?)") + bind_multi_rows(stmt) + stmt.execute() + stmt.close() + finally: + conn.close() + + +# ANCHOR_END: bind_batch + + +def create_stable(): + conn = taos.connect() + try: + conn.execute("CREATE DATABASE power") + conn.execute("CREATE STABLE power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) " + "TAGS (location BINARY(64), groupId INT)") + finally: + conn.close() + + +def get_ts(ts: str): + dt = datetime.strptime(ts, '%Y-%m-%d %H:%M:%S.%f') + return int(dt.timestamp() * 1000) + + +if __name__ == '__main__': + create_stable() + insert_data() diff --git a/docs/examples/python/native_insert_example.py b/docs/examples/python/native_insert_example.py new file mode 100644 index 0000000000000000000000000000000000000000..3b6b73cb2236c8d9d11019349f99f79135a5c1d6 --- /dev/null +++ b/docs/examples/python/native_insert_example.py @@ -0,0 +1,60 @@ +import taos + +lines = ["d1001,2018-10-03 14:38:05.000,10.30000,219,0.31000,California.SanFrancisco,2", + "d1004,2018-10-03 14:38:05.000,10.80000,223,0.29000,California.LosAngeles,3", + "d1003,2018-10-03 14:38:05.500,11.80000,221,0.28000,California.LosAngeles,2", + "d1004,2018-10-03 14:38:06.500,11.50000,221,0.35000,California.LosAngeles,3", + "d1002,2018-10-03 14:38:16.650,10.30000,218,0.25000,California.SanFrancisco,3", + "d1001,2018-10-03 14:38:15.000,12.60000,218,0.33000,California.SanFrancisco,2", + "d1001,2018-10-03 14:38:16.800,12.30000,221,0.31000,California.SanFrancisco,2", + "d1003,2018-10-03 14:38:16.600,13.40000,223,0.29000,California.LosAngeles,2"] + + +def get_connection() -> taos.TaosConnection: + """ + create connection use firstEp in taos.cfg and use default user and password. + """ + return taos.connect() + + +def create_stable(conn: taos.TaosConnection): + conn.execute("CREATE DATABASE power") + conn.execute("USE power") + conn.execute("CREATE STABLE meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) " + "TAGS (location BINARY(64), groupId INT)") + + +# The generated SQL is: +# INSERT INTO d1001 USING meters TAGS(California.SanFrancisco, 2) VALUES ('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) +# d1002 USING meters TAGS(California.SanFrancisco, 3) VALUES ('2018-10-03 14:38:16.650', 10.30000, 218, 0.25000) +# d1003 USING meters TAGS(California.LosAngeles, 2) VALUES ('2018-10-03 14:38:05.500', 11.80000, 221, 0.28000) ('2018-10-03 14:38:16.600', 13.40000, 223, 0.29000) +# d1004 USING meters TAGS(California.LosAngeles, 3) VALUES ('2018-10-03 14:38:05.000', 10.80000, 223, 0.29000) ('2018-10-03 14:38:06.500', 11.50000, 221, 0.35000) + +def get_sql(): + global lines + lines = map(lambda line: line.split(','), lines) # [['d1001', ...]...] + lines = sorted(lines, key=lambda ls: ls[0]) # sort by table name + sql = "INSERT INTO " + tb_name = None + for ps in lines: + tmp_tb_name = ps[0] + if tb_name != tmp_tb_name: + tb_name = tmp_tb_name + sql += f"{tb_name} USING meters TAGS({ps[5]}, {ps[6]}) VALUES " + sql += f"('{ps[1]}', {ps[2]}, {ps[3]}, {ps[4]}) " + return sql + + +def insert_data(conn: taos.TaosConnection): + sql = get_sql() + affected_rows = conn.execute(sql) + print("affected_rows", affected_rows) # 8 + + +if __name__ == '__main__': + connection = get_connection() + try: + create_stable(connection) + insert_data(connection) + finally: + connection.close() diff --git a/docs/examples/python/query_example.py b/docs/examples/python/query_example.py new file mode 100644 index 0000000000000000000000000000000000000000..8afd7f07358d7e9c9a3677ee04f8eb92aae6856b --- /dev/null +++ b/docs/examples/python/query_example.py @@ -0,0 +1,42 @@ +import taos + + +# ANCHOR: iter +def query_api_demo(conn: taos.TaosConnection): + result: taos.TaosResult = conn.query("SELECT tbname, * FROM meters LIMIT 2") + print("field count:", result.field_count) + print("meta of fields[1]:", result.fields[1]) + print("======================Iterate on result=========================") + for row in result: + print(row) + + +# field count: 7 +# meta of fields[1]: {name: ts, type: 9, bytes: 8} +# ======================Iterate on result========================= +# ('d1003', datetime.datetime(2018, 10, 3, 14, 38, 5, 500000), 11.800000190734863, 221, 0.2800000011920929, 'california.losangeles', 2) +# ('d1003', datetime.datetime(2018, 10, 3, 14, 38, 16, 600000), 13.399999618530273, 223, 0.28999999165534973, 'california.losangeles', 2) +# ANCHOR_END: iter + +# ANCHOR: fetch_all +def fetch_all_demo(conn: taos.TaosConnection): + result: taos.TaosResult = conn.query("SELECT ts, current FROM meters LIMIT 2") + rows = result.fetch_all_into_dict() + print("row count:", result.row_count) + print("===============all data===================") + print(rows) + + +# row count: 2 +# ===============all data=================== +# [{'ts': datetime.datetime(2018, 10, 3, 14, 38, 5, 500000), 'current': 11.800000190734863}, +# {'ts': datetime.datetime(2018, 10, 3, 14, 38, 16, 600000), 'current': 13.399999618530273}] +# ANCHOR_END: fetch_all + +if __name__ == '__main__': + connection = taos.connect(database="power") + try: + query_api_demo(connection) + fetch_all_demo(connection) + finally: + connection.close() diff --git a/docs/examples/python/rest_client_example.py b/docs/examples/python/rest_client_example.py new file mode 100644 index 0000000000000000000000000000000000000000..59c629df95fdc7dcee8d764d061afeb360b51dfc --- /dev/null +++ b/docs/examples/python/rest_client_example.py @@ -0,0 +1,9 @@ +from taosrest import RestClient + +client = RestClient("http://localhost:6041", user="root", password="taosdata") +res: dict = client.sql("SELECT ts, current FROM power.meters LIMIT 1") +print(res) + +# output: +# {'status': 'succ', 'head': ['ts', 'current'], 'column_meta': [['ts', 9, 8], ['current', 6, 4]], 'data': [[datetime.datetime(2018, 10, 3, 14, 38, 5, tzinfo=datetime.timezone(datetime.timedelta(seconds=28800), '+08:00')), 10.3]], 'rows': 1} + diff --git a/docs-examples/python/result_set_examples.py b/docs/examples/python/result_set_examples.py similarity index 100% rename from docs-examples/python/result_set_examples.py rename to docs/examples/python/result_set_examples.py diff --git a/docs-examples/python/subscribe_demo.py b/docs/examples/python/subscribe_demo.py similarity index 100% rename from docs-examples/python/subscribe_demo.py rename to docs/examples/python/subscribe_demo.py diff --git a/docs/examples/python/telnet_line_protocol_example.py b/docs/examples/python/telnet_line_protocol_example.py new file mode 100644 index 0000000000000000000000000000000000000000..d812e186af86be6811ee7774f10458e46df1f39f --- /dev/null +++ b/docs/examples/python/telnet_line_protocol_example.py @@ -0,0 +1,38 @@ +import taos +from taos import SmlProtocol, SmlPrecision + +# format: =[ =] +lines = ["meters.current 1648432611249 10.3 location=California.SanFrancisco groupid=2", + "meters.current 1648432611250 12.6 location=California.SanFrancisco groupid=2", + "meters.current 1648432611249 10.8 location=California.LosAngeles groupid=3", + "meters.current 1648432611250 11.3 location=California.LosAngeles groupid=3", + "meters.voltage 1648432611249 219 location=California.SanFrancisco groupid=2", + "meters.voltage 1648432611250 218 location=California.SanFrancisco groupid=2", + "meters.voltage 1648432611249 221 location=California.LosAngeles groupid=3", + "meters.voltage 1648432611250 217 location=California.LosAngeles groupid=3", + ] + + +# create connection use firstEp in taos.cfg. +def get_connection(): + return taos.connect() + + +def create_database(conn): + conn.execute("CREATE DATABASE test") + conn.execute("USE test") + + +def insert_lines(conn): + affected_rows = conn.schemaless_insert( + lines, SmlProtocol.TELNET_PROTOCOL, SmlPrecision.NOT_CONFIGURED) + print(affected_rows) # 8 + + +if __name__ == '__main__': + connection = get_connection() + try: + create_database(connection) + insert_lines(connection) + finally: + connection.close() diff --git a/docs-examples/rust/Cargo.toml b/docs/examples/rust/Cargo.toml similarity index 100% rename from docs-examples/rust/Cargo.toml rename to docs/examples/rust/Cargo.toml diff --git a/docs-examples/rust/nativeexample/Cargo.toml b/docs/examples/rust/nativeexample/Cargo.toml similarity index 100% rename from docs-examples/rust/nativeexample/Cargo.toml rename to docs/examples/rust/nativeexample/Cargo.toml diff --git a/docs-examples/rust/nativeexample/examples/connect.rs b/docs/examples/rust/nativeexample/examples/connect.rs similarity index 100% rename from docs-examples/rust/nativeexample/examples/connect.rs rename to docs/examples/rust/nativeexample/examples/connect.rs diff --git a/docs/examples/rust/nativeexample/examples/stmt_example.rs b/docs/examples/rust/nativeexample/examples/stmt_example.rs new file mode 100644 index 0000000000000000000000000000000000000000..190f8c1ef6d50a8e9c925178c1a9d31c22e3d4df --- /dev/null +++ b/docs/examples/rust/nativeexample/examples/stmt_example.rs @@ -0,0 +1,38 @@ +use bstr::BString; +use libtaos::*; + +#[tokio::main] +async fn main() -> Result<(), Error> { + let taos = TaosCfg::default().connect().expect("fail to connect"); + taos.create_database("power").await?; + taos.use_database("power").await?; + taos.exec("CREATE STABLE meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)").await?; + let mut stmt = taos.stmt("INSERT INTO ? USING meters TAGS(?, ?) VALUES(?, ?, ?, ?)")?; + // bind table name and tags + stmt.set_tbname_tags( + "d1001", + [ + Field::Binary(BString::from("California.SanFrancisco")), + Field::Int(2), + ], + )?; + // bind values. + let values = vec![ + Field::Timestamp(Timestamp::new(1648432611249, TimestampPrecision::Milli)), + Field::Float(10.3), + Field::Int(219), + Field::Float(0.31), + ]; + stmt.bind(&values)?; + // bind one more row + let values2 = vec![ + Field::Timestamp(Timestamp::new(1648432611749, TimestampPrecision::Milli)), + Field::Float(12.6), + Field::Int(218), + Field::Float(0.33), + ]; + stmt.bind(&values2)?; + // execute + stmt.execute()?; + Ok(()) +} diff --git a/docs-examples/rust/nativeexample/examples/subscribe_demo.rs b/docs/examples/rust/nativeexample/examples/subscribe_demo.rs similarity index 100% rename from docs-examples/rust/nativeexample/examples/subscribe_demo.rs rename to docs/examples/rust/nativeexample/examples/subscribe_demo.rs diff --git a/docs-examples/rust/nativeexample/src/main.rs b/docs/examples/rust/nativeexample/src/main.rs similarity index 100% rename from docs-examples/rust/nativeexample/src/main.rs rename to docs/examples/rust/nativeexample/src/main.rs diff --git a/docs-examples/rust/restexample/Cargo.toml b/docs/examples/rust/restexample/Cargo.toml similarity index 100% rename from docs-examples/rust/restexample/Cargo.toml rename to docs/examples/rust/restexample/Cargo.toml diff --git a/docs-examples/rust/restexample/examples/connect.rs b/docs/examples/rust/restexample/examples/connect.rs similarity index 100% rename from docs-examples/rust/restexample/examples/connect.rs rename to docs/examples/rust/restexample/examples/connect.rs diff --git a/docs/examples/rust/restexample/examples/insert_example.rs b/docs/examples/rust/restexample/examples/insert_example.rs new file mode 100644 index 0000000000000000000000000000000000000000..9261536f627c297fc707708f88f57eed647dbf3e --- /dev/null +++ b/docs/examples/rust/restexample/examples/insert_example.rs @@ -0,0 +1,18 @@ +use libtaos::*; + +#[tokio::main] +async fn main() -> Result<(), Error> { + let taos = TaosCfg::default().connect().expect("fail to connect"); + taos.create_database("power").await?; + taos.exec("CREATE STABLE power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)").await?; + let sql = "INSERT INTO power.d1001 USING power.meters TAGS(California.SanFrancisco, 2) VALUES ('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) + power.d1002 USING power.meters TAGS(California.SanFrancisco, 3) VALUES ('2018-10-03 14:38:16.650', 10.30000, 218, 0.25000) + power.d1003 USING power.meters TAGS(California.LosAngeles, 2) VALUES ('2018-10-03 14:38:05.500', 11.80000, 221, 0.28000) ('2018-10-03 14:38:16.600', 13.40000, 223, 0.29000) + power.d1004 USING power.meters TAGS(California.LosAngeles, 3) VALUES ('2018-10-03 14:38:05.000', 10.80000, 223, 0.29000) ('2018-10-03 14:38:06.500', 11.50000, 221, 0.35000)"; + let result = taos.query(sql).await?; + println!("{:?}", result); + Ok(()) +} + +// output: +// TaosQueryData { column_meta: [ColumnMeta { name: "affected_rows", type_: Int, bytes: 4 }], rows: [[Int(8)]] } diff --git a/docs-examples/rust/restexample/examples/query_example.rs b/docs/examples/rust/restexample/examples/query_example.rs similarity index 100% rename from docs-examples/rust/restexample/examples/query_example.rs rename to docs/examples/rust/restexample/examples/query_example.rs diff --git a/docs-examples/rust/restexample/src/main.rs b/docs/examples/rust/restexample/src/main.rs similarity index 100% rename from docs-examples/rust/restexample/src/main.rs rename to docs/examples/rust/restexample/src/main.rs diff --git a/docs-examples/rust/schemalessexample/Cargo.toml b/docs/examples/rust/schemalessexample/Cargo.toml similarity index 100% rename from docs-examples/rust/schemalessexample/Cargo.toml rename to docs/examples/rust/schemalessexample/Cargo.toml diff --git a/docs/examples/rust/schemalessexample/examples/influxdb_line_example.rs b/docs/examples/rust/schemalessexample/examples/influxdb_line_example.rs new file mode 100644 index 0000000000000000000000000000000000000000..64d1a3c9ac6037c16e3e1c3be0258e19cce632a0 --- /dev/null +++ b/docs/examples/rust/schemalessexample/examples/influxdb_line_example.rs @@ -0,0 +1,22 @@ +use libtaos::schemaless::*; +use libtaos::*; + +fn main() { + let taos = TaosCfg::default().connect().expect("fail to connect"); + taos.raw_query("CREATE DATABASE test").unwrap(); + taos.raw_query("USE test").unwrap(); + let lines = ["meters,location=California.LosAngeles,groupid=2 current=11.8,voltage=221,phase=0.28 1648432611249", + "meters,location=California.LosAngeles,groupid=2 current=13.4,voltage=223,phase=0.29 1648432611250", + "meters,location=California.LosAngeles,groupid=3 current=10.8,voltage=223,phase=0.29 1648432611249", + "meters,location=California.LosAngeles,groupid=3 current=11.3,voltage=221,phase=0.35 1648432611250"]; + let affected_rows = taos + .schemaless_insert( + &lines, + TSDB_SML_LINE_PROTOCOL, + TSDB_SML_TIMESTAMP_MILLISECONDS, + ) + .unwrap(); + println!("affected_rows={}", affected_rows); +} + +// run with: cargo run --example influxdb_line_example diff --git a/docs/examples/rust/schemalessexample/examples/opentsdb_json_example.rs b/docs/examples/rust/schemalessexample/examples/opentsdb_json_example.rs new file mode 100644 index 0000000000000000000000000000000000000000..e61691596704c8aaf979081429802df6e5aa86f9 --- /dev/null +++ b/docs/examples/rust/schemalessexample/examples/opentsdb_json_example.rs @@ -0,0 +1,25 @@ +use libtaos::schemaless::*; +use libtaos::*; + +fn main() { + let taos = TaosCfg::default().connect().expect("fail to connect"); + taos.raw_query("CREATE DATABASE test").unwrap(); + taos.raw_query("USE test").unwrap(); + let lines = [ + r#"[{"metric": "meters.current", "timestamp": 1648432611249, "value": 10.3, "tags": {"location": "California.SanFrancisco", "groupid": 2}}, + {"metric": "meters.voltage", "timestamp": 1648432611249, "value": 219, "tags": {"location": "California.LosAngeles", "groupid": 1}}, + {"metric": "meters.current", "timestamp": 1648432611250, "value": 12.6, "tags": {"location": "California.SanFrancisco", "groupid": 2}}, + {"metric": "meters.voltage", "timestamp": 1648432611250, "value": 221, "tags": {"location": "California.LosAngeles", "groupid": 1}}]"#, + ]; + + let affected_rows = taos + .schemaless_insert( + &lines, + TSDB_SML_JSON_PROTOCOL, + TSDB_SML_TIMESTAMP_NOT_CONFIGURED, + ) + .unwrap(); + println!("affected_rows={}", affected_rows); // affected_rows=4 +} + +// run with: cargo run --example opentsdb_json_example diff --git a/docs/examples/rust/schemalessexample/examples/opentsdb_telnet_example.rs b/docs/examples/rust/schemalessexample/examples/opentsdb_telnet_example.rs new file mode 100644 index 0000000000000000000000000000000000000000..c8cab7655a24806e5c7659af80e83da383539c55 --- /dev/null +++ b/docs/examples/rust/schemalessexample/examples/opentsdb_telnet_example.rs @@ -0,0 +1,28 @@ +use libtaos::schemaless::*; +use libtaos::*; + +fn main() { + let taos = TaosCfg::default().connect().expect("fail to connect"); + taos.raw_query("CREATE DATABASE test").unwrap(); + taos.raw_query("USE test").unwrap(); + let lines = [ + "meters.current 1648432611249 10.3 location=California.SanFrancisco groupid=2", + "meters.current 1648432611250 12.6 location=California.SanFrancisco groupid=2", + "meters.current 1648432611249 10.8 location=California.LosAngeles groupid=3", + "meters.current 1648432611250 11.3 location=California.LosAngeles groupid=3", + "meters.voltage 1648432611249 219 location=California.SanFrancisco groupid=2", + "meters.voltage 1648432611250 218 location=California.SanFrancisco groupid=2", + "meters.voltage 1648432611249 221 location=California.LosAngeles groupid=3", + "meters.voltage 1648432611250 217 location=California.LosAngeles groupid=3", + ]; + let affected_rows = taos + .schemaless_insert( + &lines, + TSDB_SML_TELNET_PROTOCOL, + TSDB_SML_TIMESTAMP_NOT_CONFIGURED, + ) + .unwrap(); + println!("affected_rows={}", affected_rows); // affected_rows=8 +} + +// run with: cargo run --example opentsdb_telnet_example diff --git a/docs-examples/rust/schemalessexample/src/main.rs b/docs/examples/rust/schemalessexample/src/main.rs similarity index 100% rename from docs-examples/rust/schemalessexample/src/main.rs rename to docs/examples/rust/schemalessexample/src/main.rs diff --git a/docs/zh/01-index.md b/docs/zh/01-index.md new file mode 100644 index 0000000000000000000000000000000000000000..d2e6706892f3997af115e71d1da455ebce2ecbec --- /dev/null +++ b/docs/zh/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/zh/02-intro.md b/docs/zh/02-intro.md new file mode 100644 index 0000000000000000000000000000000000000000..673c2e96b65814fc1cd572d54f948793ed6fa521 --- /dev/null +++ b/docs/zh/02-intro.md @@ -0,0 +1,124 @@ +--- +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 Database 技术生态图](eco_system.webp) + +
+
图 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 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/02-concept/_category_.yml b/docs/zh/04-concept/_category_.yml similarity index 100% rename from docs-cn/02-concept/_category_.yml rename to docs/zh/04-concept/_category_.yml diff --git a/docs/zh/04-concept/index.md b/docs/zh/04-concept/index.md new file mode 100644 index 0000000000000000000000000000000000000000..8e97d4a2f43537c1229c8e8ea092ddfc1257dde7 --- /dev/null +++ b/docs/zh/04-concept/index.md @@ -0,0 +1,173 @@ +--- +title: 数据模型和基本概念 +--- + +为了便于解释基本概念，便于撰写示例程序，整个 TDengine 文档以智能电表作为典型时序数据场景。假设每个智能电表采集电流、电压、相位三个量，有多个智能电表，每个电表有位置 location 和分组 group ID 的静态属性. 其采集的数据类似如下的表格： + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Device IDTime StampCollected MetricsTags
Device IDTime StampcurrentvoltagephaselocationgroupId
d1001153854868500010.32190.31California.SanFrancisco2
d1002153854868400010.22200.23California.SanFrancisco3
d1003153854868650011.52210.35California.LosAngeles3
d1004153854868550013.42230.29California.LosAngeles2
d1001153854869500012.62180.33California.SanFrancisco2
d1004153854869660011.82210.28California.LosAngeles2
d1002153854869665010.32180.25California.SanFrancisco3
d1001153854869680012.32210.31California.SanFrancisco2
+表 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/03-get-started/_apt_get_install.mdx b/docs/zh/05-get-started/_apt_get_install.mdx similarity index 100% rename from docs-cn/03-get-started/_apt_get_install.mdx rename to docs/zh/05-get-started/_apt_get_install.mdx diff --git a/docs-cn/03-get-started/_category_.yml b/docs/zh/05-get-started/_category_.yml similarity index 100% rename from docs-cn/03-get-started/_category_.yml rename to docs/zh/05-get-started/_category_.yml diff --git a/docs-cn/03-get-started/_pkg_install.mdx b/docs/zh/05-get-started/_pkg_install.mdx similarity index 100% rename from docs-cn/03-get-started/_pkg_install.mdx rename to docs/zh/05-get-started/_pkg_install.mdx diff --git a/docs/zh/05-get-started/index.md b/docs/zh/05-get-started/index.md new file mode 100644 index 0000000000000000000000000000000000000000..818027174e4b398f919a36c536ab8c07a6b1b868 --- /dev/null +++ b/docs/zh/05-get-started/index.md @@ -0,0 +1,173 @@ +--- +title: 立即开始 +description: '从 Docker，安装包或使用 apt-get 快速安装 TDengine, 通过命令行程序TDengine 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 进行检查系统运行状态、添加删除用户账号等操作。TDengine 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 被设置为 "California.SanFrancisco" 或者 "California.LosAngeles"。 + +这条命令很快完成 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="California.SanFrancisco" 的记录总条数： + +```sql +taos> select count(*) from test.meters where location="California.SanFrancisco"; +``` + +查询 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/04-develop/01-connect/_category_.yml b/docs/zh/07-develop/01-connect/_category_.yml similarity index 100% rename from docs-cn/04-develop/01-connect/_category_.yml rename to docs/zh/07-develop/01-connect/_category_.yml diff --git a/docs/zh/07-develop/01-connect/_connect_c.mdx b/docs/zh/07-develop/01-connect/_connect_c.mdx new file mode 100644 index 0000000000000000000000000000000000000000..1b145538dc9ec77a91d3a20786521a8922cafc66 --- /dev/null +++ b/docs/zh/07-develop/01-connect/_connect_c.mdx @@ -0,0 +1,3 @@ +```c title="原生连接" +{{#include docs/examples/c/connect_example.c}} +``` diff --git a/docs/zh/07-develop/01-connect/_connect_cs.mdx b/docs/zh/07-develop/01-connect/_connect_cs.mdx new file mode 100644 index 0000000000000000000000000000000000000000..13b8a5dff250e6143fbed3090ba1f35e74adb9a0 --- /dev/null +++ b/docs/zh/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/zh/07-develop/01-connect/_connect_go.mdx b/docs/zh/07-develop/01-connect/_connect_go.mdx new file mode 100644 index 0000000000000000000000000000000000000000..d69720496df86436153a7b969c0125235b2d93b0 --- /dev/null +++ b/docs/zh/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/zh/07-develop/01-connect/_connect_java.mdx b/docs/zh/07-develop/01-connect/_connect_java.mdx new file mode 100644 index 0000000000000000000000000000000000000000..f5b8ea1cc2bf309bbb182be6ae06100102328a16 --- /dev/null +++ b/docs/zh/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/zh/07-develop/01-connect/_connect_node.mdx b/docs/zh/07-develop/01-connect/_connect_node.mdx new file mode 100644 index 0000000000000000000000000000000000000000..3a856d40229513c8fc890aab4abe36dfdf15382e --- /dev/null +++ b/docs/zh/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/zh/07-develop/01-connect/_connect_php.mdx b/docs/zh/07-develop/01-connect/_connect_php.mdx new file mode 100644 index 0000000000000000000000000000000000000000..dbad72bc1988bd5336f1da132dd9e6ba9b8020e6 --- /dev/null +++ b/docs/zh/07-develop/01-connect/_connect_php.mdx @@ -0,0 +1,3 @@ +```php title="原生连接" +{{#include docs/examples/php/connect.php}} +``` diff --git a/docs/zh/07-develop/01-connect/_connect_python.mdx b/docs/zh/07-develop/01-connect/_connect_python.mdx new file mode 100644 index 0000000000000000000000000000000000000000..b331f4648c60fdcf354ea6e4440c9d716040a609 --- /dev/null +++ b/docs/zh/07-develop/01-connect/_connect_python.mdx @@ -0,0 +1,3 @@ +```python title="原生连接" +{{#include docs/examples/python/connect_example.py}} +``` diff --git a/docs/zh/07-develop/01-connect/_connect_r.mdx b/docs/zh/07-develop/01-connect/_connect_r.mdx new file mode 100644 index 0000000000000000000000000000000000000000..ba72dc848c5393340f1041c83f2fe3581db5a5d3 --- /dev/null +++ b/docs/zh/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/zh/07-develop/01-connect/_connect_rust.mdx b/docs/zh/07-develop/01-connect/_connect_rust.mdx new file mode 100644 index 0000000000000000000000000000000000000000..25f178a285f63230ad4e0af4c5de1bae638e77da --- /dev/null +++ b/docs/zh/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/zh/07-develop/01-connect/index.md b/docs/zh/07-develop/01-connect/index.md new file mode 100644 index 0000000000000000000000000000000000000000..b1857b973932b4f9cfd1564b709dd79f26701951 --- /dev/null +++ b/docs/zh/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#订阅和消费-api)等等。 + +## 安装客户端驱动 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.2` 只是示例，可替换为任意更新的版本，可在 [TDengine PHP Connector 发布历史](https://github.com/Yurunsoft/php-tdengine/releases) 中查看可用版本。 + +**非 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/04-develop/02-model/_category_.yml b/docs/zh/07-develop/02-model/_category_.yml similarity index 100% rename from docs-cn/04-develop/02-model/_category_.yml rename to docs/zh/07-develop/02-model/_category_.yml diff --git a/docs/zh/07-develop/02-model/index.mdx b/docs/zh/07-develop/02-model/index.mdx new file mode 100644 index 0000000000000000000000000000000000000000..7e2762b6e78393493c2c5b61959e9a6ff57a7b13 --- /dev/null +++ b/docs/zh/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 ("California.SanFrancisco", 2); +``` + +其中 d1001 是表名，meters 是超级表的表名，后面紧跟标签 Location 的具体标签值 "California.SanFrancisco"，标签 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 ("California.SanFrancisco", 2) VALUES (now, 10.2, 219, 0.32); +``` + +上述 SQL 语句将记录`(now, 10.2, 219, 0.32)`插入表 d1001。如果表 d1001 还未创建，则使用超级表 meters 做模板自动创建，同时打上标签值 `"California.SanFrancisco", 2`。 + +关于自动建表的详细语法请参见 [插入记录时自动建表](/taos-sql/insert#插入记录时自动建表) 章节。 + +## 多列模型 vs 单列模型 + +TDengine 支持多列模型，只要物理量是一个数据采集点同时采集的（时间戳一致），这些量就可以作为不同列放在一张超级表里。但还有一种极限的设计，单列模型，每个采集的物理量都单独建表，因此每种类型的物理量都单独建立一超级表。比如电流、电压、相位，就建三张超级表。 + +TDengine 建议尽可能采用多列模型，因为插入效率以及存储效率更高。但对于有些场景，一个采集点的采集量的种类经常变化，这个时候，如果采用多列模型，就需要频繁修改超级表的结构定义，让应用变的复杂，这个时候，采用单列模型会显得更简单。 diff --git a/docs/zh/07-develop/03-insert-data/01-sql-writing.mdx b/docs/zh/07-develop/03-insert-data/01-sql-writing.mdx new file mode 100644 index 0000000000000000000000000000000000000000..99a92573c87d0f90f699a8d1352619f4df4aef39 --- /dev/null +++ b/docs/zh/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 + +- 要提高写入效率，需要批量写入。一批写入的记录条数越多，插入效率就越高。但一条记录不能超过 48K，一条 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/zh/07-develop/03-insert-data/02-influxdb-line.mdx b/docs/zh/07-develop/03-insert-data/02-influxdb-line.mdx new file mode 100644 index 0000000000000000000000000000000000000000..54f02c91475bb5524e259a0aa890363603a86fba --- /dev/null +++ b/docs/zh/07-develop/03-insert-data/02-influxdb-line.mdx @@ -0,0 +1,69 @@ +--- +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=California.LosAngeles,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/zh/07-develop/03-insert-data/03-opentsdb-telnet.mdx b/docs/zh/07-develop/03-insert-data/03-opentsdb-telnet.mdx new file mode 100644 index 0000000000000000000000000000000000000000..2b397e1bdc7a4c76686cd4b6d457a25dbcc2c950 --- /dev/null +++ b/docs/zh/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=California.LosAngeles 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 | California.LosAngeles | + t_0e7bcfa21a02331c06764f275... | 2022-03-28 09:56:51.250 | 11.300000000 | 3 | California.LosAngeles | + t_7e7b26dd860280242c6492a16... | 2022-03-28 09:56:51.249 | 10.300000000 | 2 | California.SanFrancisco | + t_7e7b26dd860280242c6492a16... | 2022-03-28 09:56:51.250 | 12.600000000 | 2 | California.SanFrancisco | +Query OK, 4 row(s) in set (0.005399s) +``` diff --git a/docs/zh/07-develop/03-insert-data/04-opentsdb-json.mdx b/docs/zh/07-develop/03-insert-data/04-opentsdb-json.mdx new file mode 100644 index 0000000000000000000000000000000000000000..a15f80a5851ad29605e871f16aed60b68109038a --- /dev/null +++ b/docs/zh/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 | California.SanFrancisco | + 2022-03-28 09:56:51.250 | 12.600000000 | 2.000000000 | California.SanFrancisco | +Query OK, 2 row(s) in set (0.004076s) +``` diff --git a/docs/zh/07-develop/03-insert-data/_c_line.mdx b/docs/zh/07-develop/03-insert-data/_c_line.mdx new file mode 100644 index 0000000000000000000000000000000000000000..7f2f0d5dd8198d52dda1da34256e54a1bbb4c967 --- /dev/null +++ b/docs/zh/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/zh/07-develop/03-insert-data/_c_opts_json.mdx b/docs/zh/07-develop/03-insert-data/_c_opts_json.mdx new file mode 100644 index 0000000000000000000000000000000000000000..34b1d8ab3c1e299c2ab2a1ad6d47f81dfaa364cc --- /dev/null +++ b/docs/zh/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/zh/07-develop/03-insert-data/_c_opts_telnet.mdx b/docs/zh/07-develop/03-insert-data/_c_opts_telnet.mdx new file mode 100644 index 0000000000000000000000000000000000000000..6bda068d12fd0b379a5af96438029c9ae476a753 --- /dev/null +++ b/docs/zh/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/zh/07-develop/03-insert-data/_c_sql.mdx b/docs/zh/07-develop/03-insert-data/_c_sql.mdx new file mode 100644 index 0000000000000000000000000000000000000000..4e55c3387ee1c6fe860f312afdbdad65142bf7fb --- /dev/null +++ b/docs/zh/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/zh/07-develop/03-insert-data/_c_stmt.mdx b/docs/zh/07-develop/03-insert-data/_c_stmt.mdx new file mode 100644 index 0000000000000000000000000000000000000000..78f2d20dfb95859448e998bc41dc815efc4d9bd0 --- /dev/null +++ b/docs/zh/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/zh/07-develop/03-insert-data/_category_.yml b/docs/zh/07-develop/03-insert-data/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..430b3e4209ec12c6abdbfa825c9a95582376d058 --- /dev/null +++ b/docs/zh/07-develop/03-insert-data/_category_.yml @@ -0,0 +1 @@ +label: 写入数据 \ No newline at end of file diff --git a/docs/zh/07-develop/03-insert-data/_cs_line.mdx b/docs/zh/07-develop/03-insert-data/_cs_line.mdx new file mode 100644 index 0000000000000000000000000000000000000000..71f46c62be3dfe7d771a35b2298e476bed353aba --- /dev/null +++ b/docs/zh/07-develop/03-insert-data/_cs_line.mdx @@ -0,0 +1,3 @@ +```csharp +{{#include docs/examples/csharp/InfluxDBLineExample.cs}} +``` diff --git a/docs/zh/07-develop/03-insert-data/_cs_opts_json.mdx b/docs/zh/07-develop/03-insert-data/_cs_opts_json.mdx new file mode 100644 index 0000000000000000000000000000000000000000..8d80d042c984c513df5ca91813c0cd0a17b58eb5 --- /dev/null +++ b/docs/zh/07-develop/03-insert-data/_cs_opts_json.mdx @@ -0,0 +1,3 @@ +```csharp +{{#include docs/examples/csharp/OptsJsonExample.cs}} +``` diff --git a/docs/zh/07-develop/03-insert-data/_cs_opts_telnet.mdx b/docs/zh/07-develop/03-insert-data/_cs_opts_telnet.mdx new file mode 100644 index 0000000000000000000000000000000000000000..cff32abf1feaf703971111542749fbe40152bc33 --- /dev/null +++ b/docs/zh/07-develop/03-insert-data/_cs_opts_telnet.mdx @@ -0,0 +1,3 @@ +```csharp +{{#include docs/examples/csharp/OptsTelnetExample.cs}} +``` diff --git a/docs/zh/07-develop/03-insert-data/_cs_sql.mdx b/docs/zh/07-develop/03-insert-data/_cs_sql.mdx new file mode 100644 index 0000000000000000000000000000000000000000..1dc7bb3d1366aa3000212786756506eb5eb280e6 --- /dev/null +++ b/docs/zh/07-develop/03-insert-data/_cs_sql.mdx @@ -0,0 +1,3 @@ +```csharp +{{#include docs/examples/csharp/SQLInsertExample.cs}} +``` diff --git a/docs/zh/07-develop/03-insert-data/_cs_stmt.mdx b/docs/zh/07-develop/03-insert-data/_cs_stmt.mdx new file mode 100644 index 0000000000000000000000000000000000000000..229c874ab9f515e7eae66890a3dfe2e59c129e86 --- /dev/null +++ b/docs/zh/07-develop/03-insert-data/_cs_stmt.mdx @@ -0,0 +1,3 @@ +```csharp +{{#include docs/examples/csharp/StmtInsertExample.cs}} +``` diff --git a/docs/zh/07-develop/03-insert-data/_go_line.mdx b/docs/zh/07-develop/03-insert-data/_go_line.mdx new file mode 100644 index 0000000000000000000000000000000000000000..df2afc0e8720ca14e42e0e4bd7e50276cecace43 --- /dev/null +++ b/docs/zh/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/zh/07-develop/03-insert-data/_go_opts_json.mdx b/docs/zh/07-develop/03-insert-data/_go_opts_json.mdx new file mode 100644 index 0000000000000000000000000000000000000000..362ce430515c70a3ac502e646630025d7f950612 --- /dev/null +++ b/docs/zh/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/zh/07-develop/03-insert-data/_go_opts_telnet.mdx b/docs/zh/07-develop/03-insert-data/_go_opts_telnet.mdx new file mode 100644 index 0000000000000000000000000000000000000000..518ea4c8164ab148afff9e21b03d892cbc1bfaf8 --- /dev/null +++ b/docs/zh/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/zh/07-develop/03-insert-data/_go_sql.mdx b/docs/zh/07-develop/03-insert-data/_go_sql.mdx new file mode 100644 index 0000000000000000000000000000000000000000..02f4d4e2ba21bc14dd67cb0443a1631b06750923 --- /dev/null +++ b/docs/zh/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/zh/07-develop/03-insert-data/_go_stmt.mdx b/docs/zh/07-develop/03-insert-data/_go_stmt.mdx new file mode 100644 index 0000000000000000000000000000000000000000..d65a96549fbef3cd14b47853f765d557447dde1d --- /dev/null +++ b/docs/zh/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/zh/07-develop/03-insert-data/_java_line.mdx b/docs/zh/07-develop/03-insert-data/_java_line.mdx new file mode 100644 index 0000000000000000000000000000000000000000..17f759d30fdb76744dc032be60ee91b6dd9f1540 --- /dev/null +++ b/docs/zh/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/zh/07-develop/03-insert-data/_java_opts_json.mdx b/docs/zh/07-develop/03-insert-data/_java_opts_json.mdx new file mode 100644 index 0000000000000000000000000000000000000000..1fc0adc202f26c73e64da09456e7e42bdc6367f6 --- /dev/null +++ b/docs/zh/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/zh/07-develop/03-insert-data/_java_opts_telnet.mdx b/docs/zh/07-develop/03-insert-data/_java_opts_telnet.mdx new file mode 100644 index 0000000000000000000000000000000000000000..b68f54b4e872a57f34ae6d5c3651a70812b71154 --- /dev/null +++ b/docs/zh/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/zh/07-develop/03-insert-data/_java_sql.mdx b/docs/zh/07-develop/03-insert-data/_java_sql.mdx new file mode 100644 index 0000000000000000000000000000000000000000..636c7e00eb8846704678ef3cdd8394a99a4528f8 --- /dev/null +++ b/docs/zh/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/zh/07-develop/03-insert-data/_java_stmt.mdx b/docs/zh/07-develop/03-insert-data/_java_stmt.mdx new file mode 100644 index 0000000000000000000000000000000000000000..2f6a33769044ef5052e633e28a9b60fdab130e88 --- /dev/null +++ b/docs/zh/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/zh/07-develop/03-insert-data/_js_line.mdx b/docs/zh/07-develop/03-insert-data/_js_line.mdx new file mode 100644 index 0000000000000000000000000000000000000000..cc138a76bde76e779eaa1fe554ecc82c1f564e24 --- /dev/null +++ b/docs/zh/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/zh/07-develop/03-insert-data/_js_opts_json.mdx b/docs/zh/07-develop/03-insert-data/_js_opts_json.mdx new file mode 100644 index 0000000000000000000000000000000000000000..cb3c275ce8140ed58d668bf03972a1f960bb6564 --- /dev/null +++ b/docs/zh/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/zh/07-develop/03-insert-data/_js_opts_telnet.mdx b/docs/zh/07-develop/03-insert-data/_js_opts_telnet.mdx new file mode 100644 index 0000000000000000000000000000000000000000..db96742f31440342516134636db998af987af9fb --- /dev/null +++ b/docs/zh/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/zh/07-develop/03-insert-data/_js_sql.mdx b/docs/zh/07-develop/03-insert-data/_js_sql.mdx new file mode 100644 index 0000000000000000000000000000000000000000..a9a12f5d2cfb31bcaefba25a82846b455dbc8671 --- /dev/null +++ b/docs/zh/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/zh/07-develop/03-insert-data/_js_stmt.mdx b/docs/zh/07-develop/03-insert-data/_js_stmt.mdx new file mode 100644 index 0000000000000000000000000000000000000000..b94ae121c50387c899336fc6f09348f48483bf58 --- /dev/null +++ b/docs/zh/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/zh/07-develop/03-insert-data/_php_sql.mdx b/docs/zh/07-develop/03-insert-data/_php_sql.mdx new file mode 100644 index 0000000000000000000000000000000000000000..78cd663ec219dabc2eeb81c7e67426eda41d7762 --- /dev/null +++ b/docs/zh/07-develop/03-insert-data/_php_sql.mdx @@ -0,0 +1,3 @@ +```php +{{#include docs/examples/php/insert.php}} +``` diff --git a/docs/zh/07-develop/03-insert-data/_php_stmt.mdx b/docs/zh/07-develop/03-insert-data/_php_stmt.mdx new file mode 100644 index 0000000000000000000000000000000000000000..3bb7b2f8da9887c1063822e69bfdff599aa50b7b --- /dev/null +++ b/docs/zh/07-develop/03-insert-data/_php_stmt.mdx @@ -0,0 +1,3 @@ +```php +{{#include docs/examples/php/insert_stmt.php}} +``` diff --git a/docs/zh/07-develop/03-insert-data/_py_line.mdx b/docs/zh/07-develop/03-insert-data/_py_line.mdx new file mode 100644 index 0000000000000000000000000000000000000000..85f7e32e6681c6d428a2332220194c169c421f2f --- /dev/null +++ b/docs/zh/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/zh/07-develop/03-insert-data/_py_opts_json.mdx b/docs/zh/07-develop/03-insert-data/_py_opts_json.mdx new file mode 100644 index 0000000000000000000000000000000000000000..195c7090c02e03131c4261c57f1414a5ab1ba6b6 --- /dev/null +++ b/docs/zh/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/zh/07-develop/03-insert-data/_py_opts_telnet.mdx b/docs/zh/07-develop/03-insert-data/_py_opts_telnet.mdx new file mode 100644 index 0000000000000000000000000000000000000000..3bae1ea57bcffe50be5b4e96a7ae8f83faed2087 --- /dev/null +++ b/docs/zh/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/zh/07-develop/03-insert-data/_py_sql.mdx b/docs/zh/07-develop/03-insert-data/_py_sql.mdx new file mode 100644 index 0000000000000000000000000000000000000000..1557e3994b04e64c596918ee67c63e7765ebaa07 --- /dev/null +++ b/docs/zh/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/zh/07-develop/03-insert-data/_py_stmt.mdx b/docs/zh/07-develop/03-insert-data/_py_stmt.mdx new file mode 100644 index 0000000000000000000000000000000000000000..e244288401ae99228701fc3b965389f4c3a362b4 --- /dev/null +++ b/docs/zh/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/zh/07-develop/03-insert-data/_rust_line.mdx b/docs/zh/07-develop/03-insert-data/_rust_line.mdx new file mode 100644 index 0000000000000000000000000000000000000000..dbb35d76bc3517463902b642ce4a3861ae42b2f8 --- /dev/null +++ b/docs/zh/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/zh/07-develop/03-insert-data/_rust_opts_json.mdx b/docs/zh/07-develop/03-insert-data/_rust_opts_json.mdx new file mode 100644 index 0000000000000000000000000000000000000000..cc2055510bce006491ed277a8e884b9958a5a993 --- /dev/null +++ b/docs/zh/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/zh/07-develop/03-insert-data/_rust_opts_telnet.mdx b/docs/zh/07-develop/03-insert-data/_rust_opts_telnet.mdx new file mode 100644 index 0000000000000000000000000000000000000000..109c0c5d019e250b87e12c535e4f55c69924b4af --- /dev/null +++ b/docs/zh/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/zh/07-develop/03-insert-data/_rust_sql.mdx b/docs/zh/07-develop/03-insert-data/_rust_sql.mdx new file mode 100644 index 0000000000000000000000000000000000000000..fb59a4826510e666457ac592328cc5ba17412c79 --- /dev/null +++ b/docs/zh/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/zh/07-develop/03-insert-data/_rust_stmt.mdx b/docs/zh/07-develop/03-insert-data/_rust_stmt.mdx new file mode 100644 index 0000000000000000000000000000000000000000..a889b56745601158489037a590b6cf5bd80da543 --- /dev/null +++ b/docs/zh/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/zh/07-develop/03-insert-data/index.md b/docs/zh/07-develop/03-insert-data/index.md new file mode 100644 index 0000000000000000000000000000000000000000..55a28e4a8ba13501e2f481c9aba67b7300da98d0 --- /dev/null +++ b/docs/zh/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/zh/07-develop/04-query-data/_c.mdx b/docs/zh/07-develop/04-query-data/_c.mdx new file mode 100644 index 0000000000000000000000000000000000000000..c51557ef2918dd9152e329c6e1937109d286b11c --- /dev/null +++ b/docs/zh/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/zh/07-develop/04-query-data/_c_async.mdx b/docs/zh/07-develop/04-query-data/_c_async.mdx new file mode 100644 index 0000000000000000000000000000000000000000..641a53e82ddb252e1b3255799bd922158a08f229 --- /dev/null +++ b/docs/zh/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/04-develop/04-query-data/_category_.yml b/docs/zh/07-develop/04-query-data/_category_.yml similarity index 100% rename from docs-cn/04-develop/04-query-data/_category_.yml rename to docs/zh/07-develop/04-query-data/_category_.yml diff --git a/docs/zh/07-develop/04-query-data/_cs.mdx b/docs/zh/07-develop/04-query-data/_cs.mdx new file mode 100644 index 0000000000000000000000000000000000000000..4bb582ecbfaeceac679af975e7752d1caeacb018 --- /dev/null +++ b/docs/zh/07-develop/04-query-data/_cs.mdx @@ -0,0 +1,3 @@ +```csharp +{{#include docs/examples/csharp/QueryExample.cs}} +``` diff --git a/docs/zh/07-develop/04-query-data/_cs_async.mdx b/docs/zh/07-develop/04-query-data/_cs_async.mdx new file mode 100644 index 0000000000000000000000000000000000000000..3ecf635fd39db402d1db68de6d7336b7b2d9d8e8 --- /dev/null +++ b/docs/zh/07-develop/04-query-data/_cs_async.mdx @@ -0,0 +1,3 @@ +```csharp +{{#include docs/examples/csharp/AsyncQueryExample.cs}} +``` diff --git a/docs/zh/07-develop/04-query-data/_go.mdx b/docs/zh/07-develop/04-query-data/_go.mdx new file mode 100644 index 0000000000000000000000000000000000000000..b43894a1ebe8aa0a261cce5f2469f2b3f8449fc4 --- /dev/null +++ b/docs/zh/07-develop/04-query-data/_go.mdx @@ -0,0 +1,3 @@ +```go +{{#include docs/examples/go/query/sync/main.go}} +``` diff --git a/docs/zh/07-develop/04-query-data/_go_async.mdx b/docs/zh/07-develop/04-query-data/_go_async.mdx new file mode 100644 index 0000000000000000000000000000000000000000..3fbc6f5b6dac9d3987678e64d7268eed200ce513 --- /dev/null +++ b/docs/zh/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/zh/07-develop/04-query-data/_java.mdx b/docs/zh/07-develop/04-query-data/_java.mdx new file mode 100644 index 0000000000000000000000000000000000000000..74de32658c658fb81c29349a1997e32ed512db1b --- /dev/null +++ b/docs/zh/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/zh/07-develop/04-query-data/_js.mdx b/docs/zh/07-develop/04-query-data/_js.mdx new file mode 100644 index 0000000000000000000000000000000000000000..5883d378e7c7acab033bffb2018f00f1ab5a48d5 --- /dev/null +++ b/docs/zh/07-develop/04-query-data/_js.mdx @@ -0,0 +1,3 @@ +```js +{{#include docs/examples/node/nativeexample/query_example.js}} +``` diff --git a/docs/zh/07-develop/04-query-data/_js_async.mdx b/docs/zh/07-develop/04-query-data/_js_async.mdx new file mode 100644 index 0000000000000000000000000000000000000000..4b0f54a0342e62da1e5050d49546ca605ae1d729 --- /dev/null +++ b/docs/zh/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/zh/07-develop/04-query-data/_php.mdx b/docs/zh/07-develop/04-query-data/_php.mdx new file mode 100644 index 0000000000000000000000000000000000000000..bcafd1cfbcb1bbb55b03f6fe198e6fa1b5251b19 --- /dev/null +++ b/docs/zh/07-develop/04-query-data/_php.mdx @@ -0,0 +1,3 @@ +```go +{{#include docs/examples/php/query.php}} +``` diff --git a/docs/zh/07-develop/04-query-data/_py.mdx b/docs/zh/07-develop/04-query-data/_py.mdx new file mode 100644 index 0000000000000000000000000000000000000000..7184c66b8ea35a72309246aefc737d430434bb54 --- /dev/null +++ b/docs/zh/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/zh/07-develop/04-query-data/_py_async.mdx b/docs/zh/07-develop/04-query-data/_py_async.mdx new file mode 100644 index 0000000000000000000000000000000000000000..dd323ef364d67fc5d37c6c094433e0c9d14d5b08 --- /dev/null +++ b/docs/zh/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/zh/07-develop/04-query-data/_rust.mdx b/docs/zh/07-develop/04-query-data/_rust.mdx new file mode 100644 index 0000000000000000000000000000000000000000..cab1b403fbba0cb432ecb9cb280a0fa7582c5be1 --- /dev/null +++ b/docs/zh/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/zh/07-develop/04-query-data/index.mdx b/docs/zh/07-develop/04-query-data/index.mdx new file mode 100644 index 0000000000000000000000000000000000000000..824f36ef2f98aac227bdcaf2016d7be0a2e59328 --- /dev/null +++ b/docs/zh/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 | California.LosAngeles | + 219.200000000 | California.SanFrancisco | +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 "California%" 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/zh/07-develop/06-continuous-query.mdx b/docs/zh/07-develop/06-continuous-query.mdx new file mode 100644 index 0000000000000000000000000000000000000000..b2223d15e33114d263b9833df51e4201bc01c772 --- /dev/null +++ b/docs/zh/07-develop/06-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 ("California.SanFrancisco", 2); +create table D1002 using meters tags ("California.LosAngeles", 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/zh/07-develop/07-subscribe.md b/docs/zh/07-develop/07-subscribe.md new file mode 100644 index 0000000000000000000000000000000000000000..0f531e07c9dce7dbb03bacebf8e5cbefae82671f --- /dev/null +++ b/docs/zh/07-develop/07-subscribe.md @@ -0,0 +1,254 @@ +--- +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/_ 这个目录下（注：`taos.cfg` 配置文件中 `DataDir` 参数值默认为 **/var/lib/taos/**,但是 Windows 服务器上本身不存在该目录，所以需要在 Windows 的配置文件中修改 `DataDir` 参数值为相应的已存在目录"），每个订阅有一个与其 `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 ("California.SanFrancisco", 2); +taos> create table d1002 using meters tags ("California.LosAngeles", 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 | California.LosAngeles | 2 | + 2020-08-15 12:20:00.000 | 11.20000 | 220 | 1 | California.LosAngeles | 2 | + 2020-08-15 12:00:00.000 | 12.00000 | 220 | 1 | California.SanFrancisco | 2 | + 2020-08-15 12:10:00.000 | 12.30000 | 220 | 2 | California.SanFrancisco | 2 | + 2020-08-15 12:20:00.000 | 12.20000 | 220 | 1 | California.SanFrancisco | 2 | +Query OK, 5 row(s) in set (0.004896s) +``` + +### 示例代码 + + + + + + + + + {/* + + */} + + + + {/* + + + + + */} + + + + + +### 运行示例程序 + +示例程序会先消费符合查询条件的所有历史数据： + +```bash +ts: 1597464000000 current: 12.0 voltage: 220 phase: 1 location: California.SanFrancisco groupid : 2 +ts: 1597464600000 current: 12.3 voltage: 220 phase: 2 location: California.SanFrancisco groupid : 2 +ts: 1597465200000 current: 12.2 voltage: 220 phase: 1 location: California.SanFrancisco groupid : 2 +ts: 1597464600000 current: 10.3 voltage: 220 phase: 1 location: California.LosAngeles groupid : 2 +ts: 1597465200000 current: 11.2 voltage: 220 phase: 1 location: California.LosAngeles 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: California.SanFrancisco groupid: 2 +``` diff --git a/docs/zh/07-develop/08-cache.md b/docs/zh/07-develop/08-cache.md new file mode 100644 index 0000000000000000000000000000000000000000..cc59c0353c0d12fb7a8f0f20254087d741361031 --- /dev/null +++ b/docs/zh/07-develop/08-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='California.SanFrancisco'; +``` + +该 SQL 语句将获取所有位于加利福尼亚州旧金山市的电表最后记录的电压值。 diff --git a/docs-cn/04-develop/08-udf.md b/docs/zh/07-develop/09-udf.md similarity index 100% rename from docs-cn/04-develop/08-udf.md rename to docs/zh/07-develop/09-udf.md diff --git a/docs/zh/07-develop/_category_.yml b/docs/zh/07-develop/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..509a9405c42939a4819b87669a4c5b244bd29a8b --- /dev/null +++ b/docs/zh/07-develop/_category_.yml @@ -0,0 +1 @@ +label: 开发指南 \ No newline at end of file diff --git a/docs/zh/07-develop/_sub_c.mdx b/docs/zh/07-develop/_sub_c.mdx new file mode 100644 index 0000000000000000000000000000000000000000..da492a0269f064d8cdf9dfb80969894131d94015 --- /dev/null +++ b/docs/zh/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/zh/07-develop/_sub_cs.mdx b/docs/zh/07-develop/_sub_cs.mdx new file mode 100644 index 0000000000000000000000000000000000000000..a435ea0273c94cbe75eaf7431e1a9c39d49d92e3 --- /dev/null +++ b/docs/zh/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/zh/07-develop/_sub_go.mdx b/docs/zh/07-develop/_sub_go.mdx new file mode 100644 index 0000000000000000000000000000000000000000..34b2aefd92c5eef75b59fbbba96b83da091722a7 --- /dev/null +++ b/docs/zh/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/zh/07-develop/_sub_java.mdx b/docs/zh/07-develop/_sub_java.mdx new file mode 100644 index 0000000000000000000000000000000000000000..52df23f7dd0dbdc9810b1e53d66c4fcfd610759e --- /dev/null +++ b/docs/zh/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/zh/07-develop/_sub_node.mdx b/docs/zh/07-develop/_sub_node.mdx new file mode 100644 index 0000000000000000000000000000000000000000..3eeff0922a31a478dd34a77c6cb6471f51a57a8c --- /dev/null +++ b/docs/zh/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/zh/07-develop/_sub_python.mdx b/docs/zh/07-develop/_sub_python.mdx new file mode 100644 index 0000000000000000000000000000000000000000..490b76fca6deb61e61dc59c2096b30742a7d25f7 --- /dev/null +++ b/docs/zh/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/zh/07-develop/_sub_rust.mdx b/docs/zh/07-develop/_sub_rust.mdx new file mode 100644 index 0000000000000000000000000000000000000000..afb8d79daa3bbd72d72795cb4425f12277d710fc --- /dev/null +++ b/docs/zh/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/zh/07-develop/index.md b/docs/zh/07-develop/index.md new file mode 100644 index 0000000000000000000000000000000000000000..0393a87ab2ae7a5b08eea75d7a0bea95614b8131 --- /dev/null +++ b/docs/zh/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/zh/10-cluster/01-deploy.md b/docs/zh/10-cluster/01-deploy.md new file mode 100644 index 0000000000000000000000000000000000000000..b44d2942f2e4672ef6060aa9d084db1d3342e1c8 --- /dev/null +++ b/docs/zh/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/zh/10-cluster/02-cluster-mgmt.md similarity index 100% rename from docs-cn/10-cluster/02-cluster-mgmt.md rename to docs/zh/10-cluster/02-cluster-mgmt.md diff --git a/docs-cn/10-cluster/03-ha-and-lb.md b/docs/zh/10-cluster/03-ha-and-lb.md similarity index 100% rename from docs-cn/10-cluster/03-ha-and-lb.md rename to docs/zh/10-cluster/03-ha-and-lb.md diff --git a/docs/zh/10-cluster/_category_.yml b/docs/zh/10-cluster/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..3cee5ce4cdc29e7febf456e567ba08cf2753d305 --- /dev/null +++ b/docs/zh/10-cluster/_category_.yml @@ -0,0 +1 @@ +label: 集群管理 diff --git a/docs/zh/10-cluster/index.md b/docs/zh/10-cluster/index.md new file mode 100644 index 0000000000000000000000000000000000000000..ef2a7253c977cbdbd101ba6af5d7e1584aaf34bd --- /dev/null +++ b/docs/zh/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/zh/12-taos-sql/01-data-type.md similarity index 100% rename from docs-cn/12-taos-sql/01-data-type.md rename to docs/zh/12-taos-sql/01-data-type.md diff --git a/docs/zh/12-taos-sql/02-database.md b/docs/zh/12-taos-sql/02-database.md new file mode 100644 index 0000000000000000000000000000000000000000..566fec324148fede8d897869656b83e657569f59 --- /dev/null +++ b/docs/zh/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: [详细说明](/reference/config/#cache) + - blocks: [详细说明](/reference/config/#blocks) + - days: [详细说明](/reference/config/#days) + - keep: [详细说明](/reference/config/#keep) + - minRows: [详细说明](/reference/config/#minrows) + - maxRows: [详细说明](/reference/config/#maxrows) + - wal: [详细说明](/reference/config/#wallevel) + - fsync: [详细说明](/reference/config/#fsync) + - update: [详细说明](/reference/config/#update) + - cacheLast: [详细说明](/reference/config/#cachelast) + - replica: [详细说明](/reference/config/#replica) + - quorum: [详细说明](/reference/config/#quorum) + - maxVgroupsPerDb: [详细说明](/reference/config/#maxvgroupsperdb) + - comp: [详细说明](/reference/config/#comp) + - precision: [详细说明](/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/zh/12-taos-sql/03-table.md b/docs/zh/12-taos-sql/03-table.md new file mode 100644 index 0000000000000000000000000000000000000000..d7235f312933ec46ed427d5da7e2c5a229fa2926 --- /dev/null +++ b/docs/zh/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. 表的每行长度不能超过 48KB;（注意：每个 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/zh/12-taos-sql/04-stable.md b/docs/zh/12-taos-sql/04-stable.md new file mode 100644 index 0000000000000000000000000000000000000000..3901427736e80bc8dd0dd87b454947af6e586561 --- /dev/null +++ b/docs/zh/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 个，总长度不超过 16KB 。 + +### 删除标签 + +``` +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/zh/12-taos-sql/05-insert.md b/docs/zh/12-taos-sql/05-insert.md new file mode 100644 index 0000000000000000000000000000000000000000..04118303f3f6517d65d8ecbbe9fdeb774a3177b7 --- /dev/null +++ b/docs/zh/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 ('California.SanFrancisco', 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 ('California.SanFrancisco', 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 ('California.SanFrancisco', 2) FILE '/tmp/csvfile.csv'; +``` + +也可以在一条语句中向多个表以自动建表的方式插入记录。例如： + +``` +INSERT INTO d21001 USING meters TAGS ('California.SanFrancisco', 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('California.SanFrancisco', 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/zh/12-taos-sql/06-select.md b/docs/zh/12-taos-sql/06-select.md new file mode 100644 index 0000000000000000000000000000000000000000..92abc4344b7562842fae71a84fe0cb9a168596ed --- /dev/null +++ b/docs/zh/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 | California.LosAngeles | 2 | + 2018-10-03 14:38:16.600 | 13.40000 | 223 | 0.29000 | California.LosAngeles | 2 | + 2018-10-03 14:38:05.000 | 10.80000 | 223 | 0.29000 | California.LosAngeles | 3 | + 2018-10-03 14:38:06.500 | 11.50000 | 221 | 0.35000 | California.LosAngeles | 3 | + 2018-10-03 14:38:04.000 | 10.20000 | 220 | 0.23000 | California.SanFrancisco | 3 | + 2018-10-03 14:38:16.650 | 10.30000 | 218 | 0.25000 | California.SanFrancisco | 3 | + 2018-10-03 14:38:05.000 | 10.30000 | 219 | 0.31000 | California.SanFrancisco | 2 | + 2018-10-03 14:38:15.000 | 12.60000 | 218 | 0.33000 | California.SanFrancisco | 2 | + 2018-10-03 14:38:16.800 | 12.30000 | 221 | 0.31000 | California.SanFrancisco | 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 | +====================================================================== + California.SanFrancisco | 2 | 10.30000 | + California.SanFrancisco | 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 | California.LosAngeles | + d1003 | California.LosAngeles | + d1002 | California.SanFrancisco | + d1001 | California.SanFrancisco | +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 ('California.SanFrancisco', 'California.SanDieo')`。说明：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/zh/12-taos-sql/08-delete-data.mdx b/docs/zh/12-taos-sql/08-delete-data.mdx new file mode 100644 index 0000000000000000000000000000000000000000..eafe8cff264b271384096adc2a0be9a7d01e579a --- /dev/null +++ b/docs/zh/12-taos-sql/08-delete-data.mdx @@ -0,0 +1,43 @@ +--- +sidebar_label: 删除数据 +description: "删除指定表或超级表中的数据记录" +title: "删除数据" +--- + +删除数据是 TDengine 提供的根据指定时间段删除指定表或超级表中数据记录的功能，方便用户清理由于设备故障等原因产生的异常数据。 +注意：本功能只在企业版 2.6.0.0 及以后的版本中提供，如需此功能请点击下面的链接访问[企业版产品](https://www.taosdata.com/products#enterprise-edition-link) + + +**语法：** + +```sql +DELETE FROM [ db_name. ] tb_name [WHERE condition]; +``` + +**功能：** 删除指定表或超级表中的数据记录 + +**参数：** + +- `db_name` ： 可选参数，指定要删除表所在的数据库名，不填写则在当前数据库中 +- `tb_name` ： 必填参数，指定要删除数据的表名，可以是普通表、子表，也可以是超级表。 +- `condition`： 可选参数，指定删除数据的过滤条件，不指定过滤条件则为表中所有数据，请慎重使用。特别说明，这里的where 条件中只支持对第一列时间列的过滤，如果是超级表，支持对 tag 列过滤。 + +**特别说明：** + +数据删除后不可恢复，请慎重使用。为了确保删除的数据确实是自己要删除的，建议可以先使用 `select` 语句加 `where` 后的删除条件查看要删除的数据内容，确认无误后再执行 `delete` 命令。 + +**示例：** + +`meters` 是一个超级表，`groupid` 是 int 类型的 tag 列，现在要删除 `meters` 表中时间小于 2021-10-01 10:40:00.100 且 tag 列 `groupid` 值为 1 的所有数据，sql 如下： + +```sql +delete from meters where ts < '2021-10-01 10:40:00.100' and groupid=1 ; +``` + +执行后显示结果为： + +``` +Deleted 102000 row(s) from 1020 table(s) (0.421950s) +``` + +表示从 1020 个子表中共删除了 102000 行数据 diff --git a/docs/zh/12-taos-sql/10-function.md b/docs/zh/12-taos-sql/10-function.md new file mode 100644 index 0000000000000000000000000000000000000000..2349e6aa3c02eb62fba1fc7e4eef15e08e3924d1 --- /dev/null +++ b/docs/zh/12-taos-sql/10-function.md @@ -0,0 +1,1882 @@ +--- +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) +``` + +### MODE + +``` +SELECT MODE(field_name) FROM tb_name [WHERE clause]; +``` + +**功能说明**：返回出现频率最高的值，若存在多个频率相同的最高值，输出空。不能匹配标签、时间戳输出。 + +**返回数据类型**：同应用的字段。 + +**应用字段**：适合于除时间主列外的任何类型字段。 + +**使用说明**：由于返回数据量未知，考虑到内存因素，为了函数可以正常返回结果，建议不重复的数据量在 10 万级别，否则会报错。 + +**支持的版本**：2.6.0.0 及以后的版本。 + +**示例**： + +``` +taos> select voltage from d002; + voltage | +======================== + 1 | + 1 | + 2 | + 19 | +Query OK, 4 row(s) in set (0.003545s) + +taos> select mode(voltage) from d002; + mode(voltage) | +======================== + 1 | +Query OK, 1 row(s) in set (0.019393s) +``` + +### HYPERLOGLOG + +``` +SELECT HYPERLOGLOG(field_name) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**功能说明**： + - 采用 hyperloglog 算法，返回某列的基数。该算法在数据量很大的情况下，可以明显降低内存的占用，但是求出来的基数是个估算值，标准误差（标准误差是多次实验，每次的平均数的标准差，不是与真实结果的误差）为 0.81%。 + - 在数据量较少的时候该算法不是很准确，可以使用 select count(data) from (select unique(col) as data from table) 的方法。 + +**返回结果类型**：整形。 + +**应用字段**：适合于任何类型字段。 + +**支持的版本**：2.6.0.0 及以后的版本。 + +**示例**： + +``` +taos> select dbig from shll; + dbig | +======================== + 1 | + 1 | + 1 | + NULL | + 2 | + 19 | + NULL | + 9 | +Query OK, 8 row(s) in set (0.003755s) + +taos> select hyperloglog(dbig) from shll; + hyperloglog(dbig)| +======================== + 4 | +Query OK, 1 row(s) in set (0.008388s) +``` + +### HISTOGRAM + +``` +SELECT HISTOGRAM(field_name，bin_type, bin_description, normalized) FROM tb_name [WHERE clause]; +``` + +**功能说明**：统计数据按照用户指定区间的分布。 + +**返回结果类型**：如归一化参数 normalized 设置为 1，返回结果为双精度浮点类型 DOUBLE，否则为长整形 INT64。 + +**应用字段**：数值型字段。 + +**支持的版本**：2.6.0.0 及以后的版本。 + +**适用于**: 表和超级表。 + +**说明**： +1. bin_type 用户指定的分桶类型, 有效输入类型为"user_input“, ”linear_bin", "log_bin"。 +2. bin_description 描述如何生成分桶区间，针对三种桶类型，分别为以下描述格式(均为 JSON 格式字符串)： + - "user_input": "[1, 3, 5, 7]" + 用户指定 bin 的具体数值。 + + - "linear_bin": "{"start": 0.0, "width": 5.0, "count": 5, "infinity": true}" + "start" 表示数据起始点，"width" 表示每次 bin 偏移量, "count" 为 bin 的总数，"infinity" 表示是否添加（-inf, inf）作为区间起点跟终点， + 生成区间为[-inf, 0.0, 5.0, 10.0, 15.0, 20.0, +inf]。 + + - "log_bin": "{"start":1.0, "factor": 2.0, "count": 5, "infinity": true}" + "start" 表示数据起始点，"factor" 表示按指数递增的因子，"count" 为 bin 的总数，"infinity" 表示是否添加（-inf, inf）作为区间起点跟终点， + 生成区间为[-inf, 1.0, 2.0, 4.0, 8.0, 16.0, +inf]。 +3. normalized 是否将返回结果归一化到 0~1 之间 。有效输入为 0 和 1。 + +**示例**： + +```mysql +taos> SELECT HISTOGRAM(voltage, "user_input", "[1,3,5,7]", 1) FROM meters; + histogram(voltage, "user_input", "[1,3,5,7]", 1) | + ======================================================= + {"lower_bin":1, "upper_bin":3, "count":0.333333} | + {"lower_bin":3, "upper_bin":5, "count":0.333333} | + {"lower_bin":5, "upper_bin":7, "count":0.333333} | + Query OK, 3 row(s) in set (0.004273s) + +taos> SELECT HISTOGRAM(voltage, 'linear_bin', '{"start": 1, "width": 3, "count": 3, "infinity": false}', 0) FROM meters; + histogram(voltage, 'linear_bin', '{"start": 1, "width": 3, " | + =================================================================== + {"lower_bin":1, "upper_bin":4, "count":3} | + {"lower_bin":4, "upper_bin":7, "count":3} | + {"lower_bin":7, "upper_bin":10, "count":3} | + Query OK, 3 row(s) in set (0.004887s) + +taos> SELECT HISTOGRAM(voltage, 'log_bin', '{"start": 1, "factor": 3, "count": 3, "infinity": true}', 0) FROM meters; + histogram(voltage, 'log_bin', '{"start": 1, "factor": 3, "count" | + =================================================================== + {"lower_bin":-inf, "upper_bin":1, "count":3} | + {"lower_bin":1, "upper_bin":3, "count":2} | + {"lower_bin":3, "upper_bin":9, "count":6} | + {"lower_bin":9, "upper_bin":27, "count":3} | + {"lower_bin":27, "upper_bin":inf, "count":1} | +``` + +### ELAPSED + +```mysql +SELECT ELAPSED(field_name[, time_unit]) FROM { tb_name | stb_name } [WHERE clause] [INTERVAL(interval [, offset]) [SLIDING sliding]]; +``` + +**功能说明**：elapsed函数表达了统计周期内连续的时间长度，和twa函数配合使用可以计算统计曲线下的面积。在通过INTERVAL子句指定窗口的情况下，统计在给定时间范围内的每个窗口内有数据覆盖的时间范围；如果没有INTERVAL子句，则返回整个给定时间范围内的有数据覆盖的时间范围。注意，ELAPSED返回的并不是时间范围的绝对值，而是绝对值除以time_unit所得到的单位个数。 + +**返回结果类型**：Double + +**应用字段**：Timestamp类型 + +**支持的版本**：2.6.0.0 及以后的版本。 + +**适用于**: 表，超级表，嵌套查询的外层查询 + +**说明**： +- field_name参数只能是表的第一列，即timestamp主键列。 +- 按time_unit参数指定的时间单位返回，最小是数据库的时间分辨率。time_unit参数未指定时，以数据库的时间分辨率为时间单位。 +- 可以和interval组合使用，返回每个时间窗口的时间戳差值。需要特别注意的是，除第一个时间窗口和最后一个时间窗口外，中间窗口的时间戳差值均为窗口长度。 +- order by asc/desc不影响差值的计算结果。 +- 对于超级表，需要和group by tbname子句组合使用，不可以直接使用。 +- 对于普通表，不支持和group by子句组合使用。 +- 对于嵌套查询，仅当内层查询会输出隐式时间戳列时有效。例如select elapsed(ts) from (select diff(value) from sub1)语句，diff函数会让内层查询输出隐式时间戳列，此为主键列，可以用于elapsed函数的第一个参数。相反，例如select elapsed(ts) from (select * from sub1) 语句，ts列输出到外层时已经没有了主键列的含义，无法使用elapsed函数。此外，elapsed函数作为一个与时间线强依赖的函数，形如select elapsed(ts) from (select diff(value) from st group by tbname)尽管会返回一条计算结果，但并无实际意义，这种用法后续也将被限制。 +- 不支持与leastsquares、diff、derivative、top、bottom、last_row、interp等函数混合使用。 + +## 选择函数 + +在使用所有的选择函数的时候，可以同时指定输出 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) +``` + +### TAIL + +``` +SELECT TAIL(field_name, k, offset_val) FROM {tb_name | stb_name} [WHERE clause]; +``` + +**功能说明**：返回跳过最后 offset_val 个，然后取连续 k 个记录，不忽略 NULL 值。offset_val 可以不输入。此时返回最后的 k 个记录。当有 offset_val 输入的情况下，该函数功能等效于 `order by ts desc LIMIT k OFFSET offset_val`。 + +**参数范围**：k: [1,100] offset_val: [0,100]。 + +**返回结果数据类型**：同应用的字段。 + +**应用字段**：适合于除时间主列外的任何类型字段。 + +**支持版本**：2.6.0.0 及之后的版本。 + +**示例**： + +``` +taos> select ts,dbig from tail2; + ts | dbig | +================================================== +2021-10-15 00:31:33.000 | 1 | +2021-10-17 00:31:31.000 | NULL | +2021-12-24 00:31:34.000 | 2 | +2022-01-01 08:00:05.000 | 19 | +2022-01-01 08:00:06.000 | NULL | +2022-01-01 08:00:07.000 | 9 | +Query OK, 6 row(s) in set (0.001952s) + +taos> select tail(dbig,2,2) from tail2; +ts | tail(dbig,2,2) | +================================================== +2021-12-24 00:31:34.000 | 2 | +2022-01-01 08:00:05.000 | 19 | +Query OK, 2 row(s) in set (0.002307s) +``` + +### UNIQUE + +``` +SELECT UNIQUE(field_name) FROM {tb_name | stb_name} [WHERE clause]; +``` + +**功能说明**：返回该列的数值首次出现的值。该函数功能与 distinct 相似，但是可以匹配标签和时间戳信息。可以针对除时间列以外的字段进行查询，可以匹配标签和时间戳，其中的标签和时间戳是第一次出现时刻的标签和时间戳。 + +**返回结果数据类型**：同应用的字段。 + +**应用字段**：适合于除时间类型以外的字段。 + +**支持版本**：2.6.0.0 及之后的版本。 + +**使用说明**: + +- 该函数可以应用在普通表和超级表上。不能和窗口操作一起使用，例如 interval/state_window/session_window 。 +- 由于返回数据量未知，考虑到内存因素，为了函数可以正常返回结果，建议不重复的数据量在 10 万级别，否则会报错。 + +**示例**： + +``` +taos> select ts,voltage from unique1; + ts | voltage | +================================================== +2021-10-17 00:31:31.000 | 1 | +2022-01-24 00:31:31.000 | 1 | +2021-10-17 00:31:31.000 | 1 | +2021-12-24 00:31:31.000 | 2 | +2022-01-01 08:00:01.000 | 19 | +2021-10-17 00:31:31.000 | NULL | +2022-01-01 08:00:02.000 | NULL | +2022-01-01 08:00:03.000 | 9 | +Query OK, 8 row(s) in set (0.003018s) + +taos> select unique(voltage) from unique1; +ts | unique(voltage) | +================================================== +2021-10-17 00:31:31.000 | 1 | +2021-10-17 00:31:31.000 | NULL | +2021-12-24 00:31:31.000 | 2 | +2022-01-01 08:00:01.000 | 19 | +2022-01-01 08:00:03.000 | 9 | +Query OK, 5 row(s) in set (0.108458s) +``` + +## 计算函数 + +### 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）。 +- 从 2.6.0 开始，DIFF 函数支持 ignore_negative 参数 + +**示例**： + + ```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开始支持 + +### ASIN + +```sql + SELECT ASIN(field_name) FROM { tb_name | stb_name } [WHERE clause] +``` + +**功能说明**：获得指定列的反正弦结果 + +**返回结果类型**：DOUBLE。如果输入值为 NULL，输出值也为 NULL + +**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**使用说明**： + +- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 +- 该函数可以应用在普通表和超级表上。 +- 版本2.6.0.x后支持 + +### ACOS + +```sql + SELECT ACOS(field_name) FROM { tb_name | stb_name } [WHERE clause] +``` + +**功能说明**：获得指定列的反余弦结果 + +**返回结果类型**：DOUBLE。如果输入值为 NULL，输出值也为 NULL + +**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**使用说明**： + +- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 +- 该函数可以应用在普通表和超级表上。 +- 版本2.6.0.x后支持 + +### ATAN + +```sql + SELECT ATAN(field_name) FROM { tb_name | stb_name } [WHERE clause] +``` + +**功能说明**：获得指定列的反正切结果 + +**返回结果类型**：DOUBLE。如果输入值为 NULL，输出值也为 NULL + +**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**使用说明**： + +- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 +- 该函数可以应用在普通表和超级表上。 +- 版本2.6.0.x后支持 + +### SIN + +```sql + SELECT SIN(field_name) FROM { tb_name | stb_name } [WHERE clause] +``` + +**功能说明**：获得指定列的正弦结果 + +**返回结果类型**：DOUBLE。如果输入值为 NULL，输出值也为 NULL + +**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**使用说明**： + +- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 +- 该函数可以应用在普通表和超级表上。 +- 版本2.6.0.x后支持 + +### COS + +```sql + SELECT COS(field_name) FROM { tb_name | stb_name } [WHERE clause] +``` + +**功能说明**：获得指定列的余弦结果 + +**返回结果类型**：DOUBLE。如果输入值为 NULL，输出值也为 NULL + +**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**使用说明**： + +- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 +- 该函数可以应用在普通表和超级表上。 +- 版本2.6.0.x后支持 + +### TAN + +```sql + SELECT TAN(field_name) FROM { tb_name | stb_name } [WHERE clause] +``` + +**功能说明**：获得指定列的正切结果 + +**返回结果类型**：DOUBLE。如果输入值为 NULL，输出值也为 NULL + +**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**使用说明**： + +- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 +- 该函数可以应用在普通表和超级表上。 +- 版本2.6.0.x后支持 + +### POW + +```sql + SELECT POW(field_name, power) FROM { tb_name | stb_name } [WHERE clause] +``` + +**功能说明**：获得指定列的指数为 power 的幂 + +**返回结果类型**：DOUBLE。如果输入值为 NULL，输出值也为 NULL + +**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**使用说明**： + +- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 +- 该函数可以应用在普通表和超级表上。 +- 版本2.6.0.x后支持 + +### LOG + +```sql + SELECT LOG(field_name, base) FROM { tb_name | stb_name } [WHERE clause] +``` + +**功能说明**：获得指定列对于底数 base 的对数 + +**返回结果类型**：DOUBLE。如果输入值为 NULL，输出值也为 NULL + +**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**使用说明**： + +- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 +- 该函数可以应用在普通表和超级表上。 +- 版本2.6.0.x后支持 + +### ABS + +```sql + SELECT ABS(field_name) FROM { tb_name | stb_name } [WHERE clause] +``` + +**功能说明**：获得指定列的绝对值 + +**返回结果类型**：如果输入值为整数，输出值是 UBIGINT 类型。如果输入值是 FLOAT/DOUBLE 数据类型，输出值是 DOUBLE 数据类型。 + +**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**使用说明**： + +- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 +- 该函数可以应用在普通表和超级表上。 +- 版本2.6.0.x后支持 + +### SQRT + +```sql + SELECT SQRT(field_name) FROM { tb_name | stb_name } [WHERE clause] +``` + +**功能说明**：获得指定列的平方根 + +**返回结果类型**：DOUBLE。如果输入值为 NULL，输出值也为 NULL + +**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**使用说明**： + +- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 +- 该函数可以应用在普通表和超级表上。 +- 版本2.6.0.x后支持 + +### CAST + +```sql + SELECT CAST(expression AS type_name) FROM { tb_name | stb_name } [WHERE clause] +``` + +**功能说明**：数据类型转换函数，输入参数 expression 支持普通列、常量、标量函数及它们之间的四则运算，不支持 tag 列，只适用于 select 子句中。 + +**返回结果类型**：CAST 中指定的类型（type_name）。 + +**适用数据类型**： + +- 输入参数 expression 的类型可以是除 JSON 外目前所有类型字段（BOOL/TINYINT/SMALLINT/INT/BIGINT/FLOAT/DOUBLE/BINARY(M)/TIMESTAMP/NCHAR(M)/TINYINT UNSIGNED/SMALLINT UNSIGNED/INT UNSIGNED/BIGINT UNSIGNED）; +- 输出目标类型只支持 BIGINT/BINARY(N)/TIMESTAMP/NCHAR(N)/BIGINT UNSIGNED。 + +**使用说明**： + +- 对于不能支持的类型转换会直接报错。 +- 如果输入值为NULL则输出值也为NULL。 +- 对于类型支持但某些值无法正确转换的情况对应的转换后的值以转换函数输出为准。目前可能遇到的几种情况： + 1）BINARY/NCHAR转BIGINT/BIGINT UNSIGNED时可能出现的无效字符情况，例如"a"可能转为0。 + 2）有符号数或TIMESTAMP转BIGINT UNSIGNED可能遇到的溢出问题。 + 3）BIGINT UNSIGNED转BIGINT可能遇到的溢出问题。 + 4）FLOAT/DOUBLE转BIGINT/BIGINT UNSIGNED可能遇到的溢出问题。 +- 版本2.6.0.x后支持 + +### CONCAT + +```sql + SELECT CONCAT(str1|column1, str2|column2, ...) FROM { tb_name | stb_name } [WHERE clause] +``` + +**功能说明**：字符串连接函数。 + +**返回结果类型**：同输入参数类型，BINARY 或者 NCHAR。 + +**适用数据类型**：输入参数或者全部是 BINARY 格式的字符串或者列，或者全部是 NCHAR 格式的字符串或者列。不能应用在 TAG 列。 + +**使用说明**： + +- 如果输入值为NULL，输出值为NULL。 +- 该函数最小参数个数为2个，最大参数个数为8个。 +- 该函数可以应用在普通表和超级表上。 +- 该函数适用于内层查询和外层查询。 +- 版本2.6.0.x后支持 + +### CONCAT_WS + +``` + SELECT CONCAT_WS(separator, str1|column1, str2|column2, ...) FROM { tb_name | stb_name } [WHERE clause] +``` + +**功能说明**：带分隔符的字符串连接函数。 + +**返回结果类型**：同输入参数类型，BINARY 或者 NCHAR。 + +**适用数据类型**：输入参数或者全部是 BINARY 格式的字符串或者列，或者全部是 NCHAR 格式的字符串或者列。不能应用在 TAG 列。 + +**使用说明**： + +- 如果separator值为NULL，输出值为NULL。如果separator值不为NULL，其他输入为NULL，输出为空串 +- 该函数最小参数个数为3个，最大参数个数为9个。 +- 该函数可以应用在普通表和超级表上。 +- 该函数适用于内层查询和外层查询。 +- 版本2.6.0.x后支持 + +### LENGTH + +``` + SELECT LENGTH(str|column) FROM { tb_name | stb_name } [WHERE clause] +``` + +**功能说明**：以字节计数的字符串长度。 + +**返回结果类型**：INT。 + +**适用数据类型**：输入参数是 BINARY 类型或者 NCHAR 类型的字符串或者列。不能应用在 TAG 列。 + +**使用说明** + +- 如果输入值为NULL，输出值为NULL。 +- 该函数可以应用在普通表和超级表上。 +- 函数适用于内层查询和外层查询。 +- 版本2.6.0.x后支持 + +### CHAR_LENGTH + +``` + SELECT CHAR_LENGTH(str|column) FROM { tb_name | stb_name } [WHERE clause] +``` + +**功能说明**：以字符计数的字符串长度。 + +**返回结果类型**：INT。 + +**适用数据类型**：输入参数是 BINARY 类型或者 NCHAR 类型的字符串或者列。不能应用在 TAG 列。 + +**使用说明** + +- 如果输入值为NULL，输出值为NULL。 +- 该函数可以应用在普通表和超级表上。 +- 该函数适用于内层查询和外层查询。 +- 版本2.6.0.x后支持 + +### LOWER + +``` + SELECT LOWER(str|column) FROM { tb_name | stb_name } [WHERE clause] +``` + +**功能说明**：将字符串参数值转换为全小写字母。 + +**返回结果类型**：同输入类型。 + +**适用数据类型**：输入参数是 BINARY 类型或者 NCHAR 类型的字符串或者列。不能应用在 TAG 列。 + +**使用说明**： + +- 如果输入值为NULL，输出值为NULL。 +- 该函数可以应用在普通表和超级表上。 +- 该函数适用于内层查询和外层查询。 +- 版本2.6.0.x后支持 + +### UPPER + +``` + SELECT UPPER(str|column) FROM { tb_name | stb_name } [WHERE clause] +``` + +**功能说明**：将字符串参数值转换为全大写字母。 + +**返回结果类型**：同输入类型。 + +**适用数据类型**：输入参数是 BINARY 类型或者 NCHAR 类型的字符串或者列。不能应用在 TAG 列。 + +**使用说明**： + +- 如果输入值为NULL，输出值为NULL。 +- 该函数可以应用在普通表和超级表上。 +- 该函数适用于内层查询和外层查询。 +- 版本2.6.0.x后支持 + +### LTRIM + +``` + SELECT LTRIM(str|column) FROM { tb_name | stb_name } [WHERE clause] +``` + +**功能说明**：返回清除左边空格后的字符串。 + +**返回结果类型**：同输入类型。 + +**适用数据类型**：输入参数是 BINARY 类型或者 NCHAR 类型的字符串或者列。不能应用在 TAG 列。 + +**使用说明**： + +- 如果输入值为NULL，输出值为NULL。 +- 该函数可以应用在普通表和超级表上。 +- 该函数适用于内层查询和外层查询。 +- 版本2.6.0.x后支持 + +### RTRIM + +``` + SELECT RTRIM(str|column) FROM { tb_name | stb_name } [WHERE clause] +``` + +**功能说明**：返回清除右边空格后的字符串。 + +**返回结果类型**：同输入类型。 + +**适用数据类型**：输入参数是 BINARY 类型或者 NCHAR 类型的字符串或者列。不能应用在 TAG 列。 + +**使用说明**： + +- 如果输入值为NULL，输出值为NULL。 +- 该函数可以应用在普通表和超级表上。 +- 该函数适用于内层查询和外层查询。 +- 版本2.6.0.x后支持 + +### SUBSTR + +``` + SELECT SUBSTR(str,pos[,len]) FROM { tb_name | stb_name } [WHERE clause] +``` + +**功能说明**：从源字符串 str 中的指定位置 pos 开始取一个长度为 len 的子串并返回。 + +**返回结果类型**：同输入类型。 + +**适用数据类型**：输入参数是 BINARY 类型或者 NCHAR 类型的字符串或者列。不能应用在 TAG 列。 + +**使用说明**： + +- 如果输入值为NULL，输出值为NULL。 +- 输入参数pos可以为正数，也可以为负数。如果pos是正数，表示开始位置从字符串开头正数计算。如果pos为负数，表示开始位置从字符串结尾倒数计算。如果输入参数len被忽略，返回的子串包含从pos开始的整个字串。 +- 该函数可以应用在普通表和超级表上。 +- 该函数适用于内层查询和外层查询。 +- 版本2.6.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) +``` + +### STATECOUNT + +``` +SELECT STATECOUNT(field_name, oper, val) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**功能说明**：返回满足某个条件的连续记录的个数，结果作为新的一列追加在每行后面。条件根据参数计算，如果条件为 true 则加 1，条件为 false 则重置为-1，如果数据为 NULL，跳过该条数据。 + +**参数范围**： + +- oper : LT (小于)、GT（大于）、LE（小于等于）、GE（大于等于）、NE（不等于）、EQ（等于），不区分大小写。 +- val : 数值型 + +**返回结果类型**：整形。 + +**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上。 + +**嵌套子查询支持**：不支持应用在子查询上。 + +**支持的版本**：2.6 开始的版本。 + +**使用说明**： + +- 该函数可以应用在普通表上，在由 GROUP BY 划分出单独时间线的情况下用于超级表（也即 GROUP BY tbname） +- 不能和窗口操作一起使用，例如 interval/state_window/session_window。 + +**示例**： + +``` +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) +``` + +### STATEDURATION + +```sql +SELECT stateDuration(field_name, oper, val, unit) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**功能说明**：返回满足某个条件的连续记录的时间长度，结果作为新的一列追加在每行后面。条件根据参数计算，如果条件为 true 则加上两个记录之间的时间长度（第一个满足条件的记录时间长度记为 0），条件为 false 则重置为-1，如果数据为 NULL，跳过该条数据。 + +**参数范围**： + +- oper : LT (小于)、GT（大于）、LE（小于等于）、GE（大于等于）、NE（不等于）、EQ（等于），不区分大小写。 +- val : 数值型 +- unit : 时间长度的单位，范围[1s、1m、1h ]，不足一个单位舍去。默认为 1s。 + +**返回结果类型**：整形。 + +**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上。 + +**嵌套子查询支持**：不支持应用在子查询上。 + +**支持的版本**：2.6 开始的版本。 + +**使用说明**： + +- 该函数可以应用在普通表上，在由 GROUP BY 划分出单独时间线的情况下用于超级表（也即 GROUP BY tbname） +- 不能和窗口操作一起使用，例如 interval/state_window/session_window。 + +**示例**： + +``` +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.002407s) + +taos> select stateDuration(dbig,GT,2) from statef2; +ts | dbig | stateduration(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 | 0 | +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.002613s) +``` + +## 时间函数 + +从 2.6.0.0 版本开始，TDengine 查询引擎支持以下时间相关函数： + +### NOW + +```sql +SELECT NOW() FROM { tb_name | stb_name } [WHERE clause]; +SELECT select_expr FROM { tb_name | stb_name } WHERE ts_col cond_operatior NOW(); +INSERT INTO tb_name VALUES (NOW(), ...); +``` + +**功能说明**：返回客户端当前系统时间。 + +**返回结果数据类型**：TIMESTAMP 时间戳类型。 + +**应用字段**：在 WHERE 或 INSERT 语句中使用时只能作用于 TIMESTAMP 类型的字段。 + +**适用于**：表、超级表。 + +**使用说明**： + +- 支持时间加减操作，如 NOW() + 1s, 支持的时间单位如下： + b(纳秒)、u(微秒)、a(毫秒)、s(秒)、m(分)、h(小时)、d(天)、w(周)。 +- 返回的时间戳精度与当前 DATABASE 设置的时间精度一致。 + +**示例**： + +```sql +taos> SELECT NOW() FROM meters; + now() | +========================== + 2022-02-02 02:02:02.456 | +Query OK, 1 row(s) in set (0.002093s) + +taos> SELECT NOW() + 1h FROM meters; + now() + 1h | +========================== + 2022-02-02 03:02:02.456 | +Query OK, 1 row(s) in set (0.002093s) + +taos> SELECT COUNT(voltage) FROM d1001 WHERE ts < NOW(); + count(voltage) | +============================= + 5 | +Query OK, 5 row(s) in set (0.004475s) + +taos> INSERT INTO d1001 VALUES (NOW(), 10.2, 219, 0.32); +Query OK, 1 of 1 row(s) in database (0.002210s) +``` + +### TODAY + +```sql +SELECT TODAY() FROM { tb_name | stb_name } [WHERE clause]; +SELECT select_expr FROM { tb_name | stb_name } WHERE ts_col cond_operatior TODAY()]; +INSERT INTO tb_name VALUES (TODAY(), ...); +``` + +**功能说明**：返回客户端当日零时的系统时间。 + +**返回结果数据类型**：TIMESTAMP 时间戳类型。 + +**应用字段**：在 WHERE 或 INSERT 语句中使用时只能作用于 TIMESTAMP 类型的字段。 + +**适用于**：表、超级表。 + +**使用说明**： + +- 支持时间加减操作，如 TODAY() + 1s, 支持的时间单位如下： + b(纳秒)，u(微秒)，a(毫秒)，s(秒)，m(分)，h(小时)，d(天)，w(周)。 +- 返回的时间戳精度与当前 DATABASE 设置的时间精度一致。 + +**示例**： + +```sql +taos> SELECT TODAY() FROM meters; + today() | +========================== + 2022-02-02 00:00:00.000 | +Query OK, 1 row(s) in set (0.002093s) + +taos> SELECT TODAY() + 1h FROM meters; + today() + 1h | +========================== + 2022-02-02 01:00:00.000 | +Query OK, 1 row(s) in set (0.002093s) + +taos> SELECT COUNT(voltage) FROM d1001 WHERE ts < TODAY(); + count(voltage) | +============================= + 5 | +Query OK, 5 row(s) in set (0.004475s) + +taos> INSERT INTO d1001 VALUES (TODAY(), 10.2, 219, 0.32); +Query OK, 1 of 1 row(s) in database (0.002210s) +``` + +### TIMEZONE + +```sql +SELECT TIMEZONE() FROM { tb_name | stb_name } [WHERE clause]; +``` + +**功能说明**：返回客户端当前时区信息。 + +**返回结果数据类型**：BINARY 类型。 + +**应用字段**：无 + +**适用于**：表、超级表。 + +**示例**： + +```sql +taos> SELECT TIMEZONE() FROM meters; + timezone() | +================================= + UTC (UTC, +0000) | +Query OK, 1 row(s) in set (0.002093s) +``` + +### TO_ISO8601 + +```sql +SELECT TO_ISO8601(ts_val | ts_col) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**功能说明**：将 UNIX 时间戳转换成为 ISO8601 标准的日期时间格式，并附加客户端时区信息。 + +**返回结果数据类型**：BINARY 类型。 + +**应用字段**：UNIX 时间戳常量或是 TIMESTAMP 类型的列 + +**适用于**：表、超级表。 + +**使用说明**： + +- 如果输入是 UNIX 时间戳常量，返回格式精度由时间戳的位数决定; +- 如果输入是 TIMSTAMP 类型的列，返回格式的时间戳精度与当前 DATABASE 设置的时间精度一致。 + +**示例**： + +```sql +taos> SELECT TO_ISO8601(1643738400) FROM meters; + to_iso8601(1643738400) | +============================== + 2022-02-02T02:00:00+0800 | + +taos> SELECT TO_ISO8601(ts) FROM meters; + to_iso8601(ts) | +============================== + 2022-02-02T02:00:00+0800 | + 2022-02-02T02:00:00+0800 | + 2022-02-02T02:00:00+0800 | +``` + +### TO_UNIXTIMESTAMP + +```sql +SELECT TO_UNIXTIMESTAMP(datetime_string | ts_col) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**功能说明**：将日期时间格式的字符串转换成为 UNIX 时间戳。 + +**返回结果数据类型**：长整型 INT64。 + +**应用字段**：字符串常量或是 BINARY/NCHAR 类型的列。 + +**适用于**：表、超级表。 + +**使用说明**： + +- 输入的日期时间字符串须符合 ISO8601/RFC3339 标准，无法转换的字符串格式将返回 0。 +- 返回的时间戳精度与当前 DATABASE 设置的时间精度一致。 + +**示例**： + +```sql +taos> SELECT TO_UNIXTIMESTAMP("2022-02-02T02:00:00.000Z") FROM meters; +to_unixtimestamp("2022-02-02T02:00:00.000Z") | +============================================== + 1643767200000 | + +taos> SELECT TO_UNIXTIMESTAMP(col_binary) FROM meters; + to_unixtimestamp(col_binary) | +======================================== + 1643767200000 | + 1643767200000 | + 1643767200000 | +``` + +### TIMETRUNCATE + +```sql +SELECT TIMETRUNCATE(ts_val | datetime_string | ts_col, time_unit) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**功能说明**：将时间戳按照指定时间单位 time_unit 进行截断。 + +**返回结果数据类型**：TIMESTAMP 时间戳类型。 + +**应用字段**：UNIX 时间戳，日期时间格式的字符串，或者 TIMESTAMP 类型的列。 + +**适用于**：表、超级表。 + +**使用说明**： +- 支持的时间单位 time_unit 如下： + 1u(微秒)，1a(毫秒)，1s(秒)，1m(分)，1h(小时)，1d(天)。 +- 返回的时间戳精度与当前 DATABASE 设置的时间精度一致。 + +**示例**： + +```sql +taos> SELECT TIMETRUNCATE(1643738522000, 1h) FROM meters; + timetruncate(1643738522000, 1h) | +=================================== + 2022-02-02 02:00:00.000 | +Query OK, 1 row(s) in set (0.001499s) + +taos> SELECT TIMETRUNCATE("2022-02-02 02:02:02", 1h) FROM meters; + timetruncate("2022-02-02 02:02:02", 1h) | +=========================================== + 2022-02-02 02:00:00.000 | +Query OK, 1 row(s) in set (0.003903s) + +taos> SELECT TIMETRUNCATE(ts, 1h) FROM meters; + timetruncate(ts, 1h) | +========================== + 2022-02-02 02:00:00.000 | + 2022-02-02 02:00:00.000 | + 2022-02-02 02:00:00.000 | +Query OK, 3 row(s) in set (0.003903s) +``` + +### TIMEDIFF + +```sql +SELECT TIMEDIFF(ts_val1 | datetime_string1 | ts_col1, ts_val2 | datetime_string2 | ts_col2 [, time_unit]) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**功能说明**：计算两个时间戳之间的差值，并近似到时间单位 time_unit 指定的精度。 + +**返回结果数据类型**：长整型 INT64。 + +**应用字段**：UNIX 时间戳，日期时间格式的字符串，或者 TIMESTAMP 类型的列。 + +**适用于**：表、超级表。 + +**使用说明**： +- 支持的时间单位 time_unit 如下： + 1u(微秒)，1a(毫秒)，1s(秒)，1m(分)，1h(小时)，1d(天)。 +- 如果时间单位 time_unit 未指定， 返回的时间差值精度与当前 DATABASE 设置的时间精度一致。 + +**支持的版本**：2.6.0.0 及以后的版本。 + +**示例**： + +```sql +taos> SELECT TIMEDIFF(1643738400000, 1643742000000) FROM meters; + timediff(1643738400000, 1643742000000) | +========================================= + 3600000 | +Query OK, 1 row(s) in set (0.002553s) +taos> SELECT TIMEDIFF(1643738400000, 1643742000000, 1h) FROM meters; + timediff(1643738400000, 1643742000000, 1h) | +============================================= + 1 | +Query OK, 1 row(s) in set (0.003726s) + +taos> SELECT TIMEDIFF("2022-02-02 03:00:00", "2022-02-02 02:00:00", 1h) FROM meters; + timediff("2022-02-02 03:00:00", "2022-02-02 02:00:00", 1h) | +============================================================= + 1 | +Query OK, 1 row(s) in set (0.001937s) + +taos> SELECT TIMEDIFF(ts_col1, ts_col2, 1h) FROM meters; + timediff(ts_col1, ts_col2, 1h) | +=================================== + 1 | +Query OK, 1 row(s) in set (0.001937s) +``` diff --git a/docs/zh/12-taos-sql/12-interval.md b/docs/zh/12-taos-sql/12-interval.md new file mode 100644 index 0000000000000000000000000000000000000000..b0619ea5ce3759e9bca1234b76e2a16176511547 --- /dev/null +++ b/docs/zh/12-taos-sql/12-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 相等的时候，滑动窗口即为翻转窗口。 + +![TDengine Database 时间窗口示意图](./timewindow-1.webp) + +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]两个。（状态窗口暂不支持对超级表使用） + +![TDengine Database 时间窗口示意图](./timewindow-3.webp) + +使用 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 秒）。 + +![TDengine Database 时间窗口示意图](./timewindow-2.webp) + +在 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/zh/12-taos-sql/14-limit.md b/docs/zh/12-taos-sql/14-limit.md new file mode 100644 index 0000000000000000000000000000000000000000..7673e24a83cc1ba5335b11f29803cf9f3eae26e5 --- /dev/null +++ b/docs/zh/12-taos-sql/14-limit.md @@ -0,0 +1,54 @@ +--- +sidebar_label: 边界限制 +title: 边界限制 +--- + +## 一般限制 + +- 数据库名最大长度为 32。 +- 表名最大长度为 192，不包括数据库名前缀和分隔符 +- 每行数据最大长度 48KB （注意：数据行内每个 BINARY/NCHAR 类型的列还会额外占用 2 个字节的存储位置）。 +- 列名最大长度为 64，最多允许 4096 列，最少需要 2 列，第一列必须是时间戳。注：从 2.1.7.0 版本（不含)以前最多允许 4096 列 +- 标签名最大长度为 64，最多允许 128 个，至少要有 1 个标签，一个表中标签值的总长度不超过 16KB 。 +- 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/zh/12-taos-sql/16-json.md similarity index 100% rename from docs-cn/12-taos-sql/10-json.md rename to docs/zh/12-taos-sql/16-json.md diff --git a/docs-cn/12-taos-sql/11-escape.md b/docs/zh/12-taos-sql/18-escape.md similarity index 100% rename from docs-cn/12-taos-sql/11-escape.md rename to docs/zh/12-taos-sql/18-escape.md diff --git a/docs/zh/12-taos-sql/20-keywords.md b/docs/zh/12-taos-sql/20-keywords.md new file mode 100644 index 0000000000000000000000000000000000000000..91dd601ad68cad5e2cc98ad1821e2d7fc67f40d9 --- /dev/null +++ b/docs/zh/12-taos-sql/20-keywords.md @@ -0,0 +1,354 @@ +--- +sidebar_label: 参数限制与保留关键字 +title: TDengine 参数限制与保留关键字 +--- + +## 名称命名规则 + +1. 合法字符：英文字符、数字和下划线 +2. 允许英文字符或下划线开头，不允许以数字开头 +3. 不区分大小写 +4. 转义后表（列）名规则： + 为了兼容支持更多形式的表（列）名，TDengine 引入新的转义符 "`"。可用让表名与关键词不冲突，同时不受限于上述表名称合法性约束检查。 + 转义后的表（列）名同样受到长度限制要求，且长度计算的时候不计算转义符。使用转义字符以后，不再对转义字符中的内容进行大小写统一。 + + 例如：\`aBc\` 和 \`abc\` 是不同的表（列）名，但是 abc 和 aBc 是相同的表（列）名。 + 需要注意的是转义字符中的内容必须是可打印字符。 + 支持转义符的功能从 2.3.0.1 版本开始。 + +## 密码合法字符集 + +`[a-zA-Z0-9!?$%^&*()_–+={[}]:;@~#|<,>.?/]` + +去掉了 `` ‘“`\ `` (单双引号、撇号、反斜杠、空格) + +- 数据库名：不能包含“.”以及特殊字符，不能超过 32 个字符 +- 表名：不能包含“.”以及特殊字符，与所属数据库名一起，不能超过 192 个字节 ，每行数据最大长度 48KB +- 表的列名：不能包含特殊字符，不能超过 64 个字节 +- 数据库名、表名、列名，都不能以数字开头，合法的可用字符集是“英文字符、数字和下划线” +- 表的列数：不能超过 1024 列，最少需要 2 列，第一列必须是时间戳（从 2.1.7.0 版本开始，改为最多支持 4096 列） +- 记录的最大长度：包括时间戳 8 字节，不能超过 48KB（每个 BINARY/NCHAR 类型的列还会额外占用 2 个 字节 的存储位置） +- 单条 SQL 语句默认最大字符串长度：1048576 字节，但可通过系统配置参数 maxSQLLength 修改，取值范围 65480 ~ 1048576 字节 +- 数据库副本数：不能超过 3 +- 用户名：不能超过 23 个 字节 +- 用户密码：不能超过 15 个 字节 +- 标签(Tags)数量：不能超过 128 个，可以 0 个 +- 标签的总长度：不能超过 16KB +- 记录条数：仅受存储空间限制 +- 表的个数：仅受节点个数限制 +- 库的个数：仅受节点个数限制 +- 单个库上虚拟节点个数：不能超过 64 个 +- 库的数目，超级表的数目、表的数目，系统不做限制，仅受系统资源限制 +- SELECT 语句的查询结果，最多允许返回 1024 列（语句中的函数调用可能也会占用一些列空间），超限时需要显式指定较少的返回数据列，以避免语句执行报错。（从 2.1.7.0 版本开始，改为最多允许 4096 列） + +## 保留关键字 + +目前 TDengine 有将近 200 个内部保留关键字，这些关键字无论大小写均不可以用作库名、表名、STable 名、数据列名及标签列名等。这些关键字列表如下： + +### A + +- ABORT +- ACCOUNT +- ACCOUNTS +- ADD +- AFTER +- ALL +- ALTER +- AND +- AS +- ASC +- ATTACH + +### B + +- BEFORE +- BEGIN +- BETWEEN +- BIGINT +- BINARY +- BITAND +- BITNOT +- BITOR +- BLOCKS +- BOOL +- BY + +### C + +- CACHE +- CACHELAST +- CASCADE +- CHANGE +- CLUSTER +- COLON +- COLUMN +- COMMA +- COMP +- COMPACT +- CONCAT +- CONFLICT +- CONNECTION +- CONNECTIONS +- CONNS +- COPY +- CREATE +- CTIME + +### D + +- DATABASE +- DATABASES +- DAYS +- DBS +- DEFERRED +- DELETE +- DELIMITERS +- DESC +- DESCRIBE +- DETACH +- DISTINCT +- DIVIDE +- DNODE +- DNODES +- DOT +- DOUBLE +- DROP + +### E + +- END +- EQ +- EXISTS +- EXPLAIN + +### F + +- FAIL +- FILE +- FILL +- FLOAT +- FOR +- FROM +- FSYNC + +### G + +- GE +- GLOB +- GRANTS +- GROUP +- GT + +### H + +- HAVING + +### I + +- ID +- IF +- IGNORE +- IMMEDIA +- IMPORT +- IN +- INITIAL +- INSERT +- INSTEAD +- INT +- INTEGER +- INTERVA +- INTO +- IS +- ISNULL + +### J + +- JOIN + +### K + +- KEEP +- KEY +- KILL + +### L + +- LE +- LIKE +- LIMIT +- LINEAR +- LOCAL +- LP +- LSHIFT +- LT + +### M + +- MATCH +- MAXROWS +- MINROWS +- MINUS +- MNODES +- MODIFY +- MODULES + +### N + +- NE +- NONE +- NOT +- NOTNULL +- NOW +- NULL + +### O + +- OF +- OFFSET +- OR +- ORDER + +### P + +- PARTITION +- PASS +- PLUS +- PPS +- PRECISION +- PREV +- PRIVILEGE + +### Q + +- QTIME +- QUERIE +- QUERY +- QUORUM + +### R + +- RAISE +- REM +- REPLACE +- REPLICA +- RESET +- RESTRIC +- ROW +- RP +- RSHIFT + +### S + +- SCORES +- SELECT +- SEMI +- SESSION +- SET +- SHOW +- SLASH +- SLIDING +- SLIMIT +- SMALLIN +- SOFFSET +- STable +- STableS +- STAR +- STATE +- STATEMEN +- STATE_WI +- STORAGE +- STREAM +- STREAMS +- STRING +- SYNCDB + +### T + +- TABLE +- TABLES +- TAG +- TAGS +- TBNAME +- TIMES +- TIMESTAMP +- TINYINT +- TOPIC +- TOPICS +- TRIGGER +- TSERIES + +### U + +- UMINUS +- UNION +- UNSIGNED +- UPDATE +- UPLUS +- USE +- USER +- USERS +- USING + +### V + +- VALUES +- VARIABLE +- VARIABLES +- VGROUPS +- VIEW +- VNODES + +### W + +- WAL +- WHERE + +### _ + +- _C0 +- _QSTART +- _QSTOP +- _QDURATION +- _WSTART +- _WSTOP +- _WDURATION + + +## 特殊说明 +### TBNAME +`TBNAME` 可以视为超级表中一个特殊的标签，代表子表的表名。 + +获取一个超级表所有的子表名及相关的标签信息： +```mysql +SELECT TBNAME, location FROM meters; + +统计超级表下辖子表数量： +```mysql +SELECT COUNT(TBNAME) FROM meters; +``` + +以上两个查询均只支持在WHERE条件子句中添加针对标签（TAGS）的过滤条件。例如： +```mysql +taos> SELECT TBNAME, location FROM meters; + tbname | location | +================================================================== + d1004 | California.SanFrancisco | + d1003 | California.SanFrancisco | + d1002 | California.LosAngeles | + d1001 | California.LosAngeles | +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) +``` +### _QSTART/_QSTOP/_QDURATION +表示查询过滤窗口的起始，结束以及持续时间 (从2.6.0.0版本开始支持) + +### _WSTART/_WSTOP/_WDURATION +窗口切分聚合查询（例如 interval/session window/state window）中表示每个切分窗口的起始，结束以及持续时间（从 2.6.0.0 版本开始支持） + +### _c0 +表示表或超级表的第一列 \ No newline at end of file diff --git a/docs-cn/12-taos-sql/_category_.yml b/docs/zh/12-taos-sql/_category_.yml similarity index 100% rename from docs-cn/12-taos-sql/_category_.yml rename to docs/zh/12-taos-sql/_category_.yml diff --git a/docs/zh/12-taos-sql/index.md b/docs/zh/12-taos-sql/index.md new file mode 100644 index 0000000000000000000000000000000000000000..cb01b3a918778abc6c7891c1ff185f1db32d3d36 --- /dev/null +++ b/docs/zh/12-taos-sql/index.md @@ -0,0 +1,38 @@ +--- +title: TAOS SQL +description: "TAOS SQL 支持的语法规则、主要查询功能、支持的 SQL 查询函数，以及常用技巧等内容" +--- + +本文档说明 TAOS SQL 支持的语法规则、主要查询功能、支持的 SQL 查询函数，以及常用技巧等内容。阅读本文档需要读者具有基本的 SQL 语言的基础。 + +TAOS SQL 是用户对 TDengine 进行数据写入和查询的主要工具。TAOS SQL 为了便于用户快速上手，在一定程度上提供与标准 SQL 类似的风格和模式。严格意义上，TAOS SQL 并不是也不试图提供标准的 SQL 语法。此外，由于 TDengine 针对的时序性结构化数据不提供删除功能，因此在 TAO SQL 中不提供数据删除的相关功能。 + +本章节 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'; + + +``` diff --git a/docs/zh/12-taos-sql/timewindow-1.webp b/docs/zh/12-taos-sql/timewindow-1.webp new file mode 100644 index 0000000000000000000000000000000000000000..82747558e96df752a0010d85be79a4af07e4a1df Binary files /dev/null and b/docs/zh/12-taos-sql/timewindow-1.webp differ diff --git a/docs/zh/12-taos-sql/timewindow-2.webp b/docs/zh/12-taos-sql/timewindow-2.webp new file mode 100644 index 0000000000000000000000000000000000000000..8f1314ae34f7f5c5cca1d3cb80455f555fad38c3 Binary files /dev/null and b/docs/zh/12-taos-sql/timewindow-2.webp differ diff --git a/docs/zh/12-taos-sql/timewindow-3.webp b/docs/zh/12-taos-sql/timewindow-3.webp new file mode 100644 index 0000000000000000000000000000000000000000..5bd16e68e7fd5da6805551e9765975277cd5d4d9 Binary files /dev/null and b/docs/zh/12-taos-sql/timewindow-3.webp differ diff --git a/docs-cn/13-operation/01-pkg-install.md b/docs/zh/13-operation/01-pkg-install.md similarity index 100% rename from docs-cn/13-operation/01-pkg-install.md rename to docs/zh/13-operation/01-pkg-install.md diff --git a/docs-cn/13-operation/02-planning.mdx b/docs/zh/13-operation/02-planning.mdx similarity index 100% rename from docs-cn/13-operation/02-planning.mdx rename to docs/zh/13-operation/02-planning.mdx diff --git a/docs/zh/13-operation/03-tolerance.md b/docs/zh/13-operation/03-tolerance.md new file mode 100644 index 0000000000000000000000000000000000000000..2c466819621adc10423c452328714c81e6f6f966 --- /dev/null +++ b/docs/zh/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/zh/13-operation/06-admin.md similarity index 100% rename from docs-cn/13-operation/06-admin.md rename to docs/zh/13-operation/06-admin.md diff --git a/docs-cn/13-operation/07-import.md b/docs/zh/13-operation/07-import.md similarity index 100% rename from docs-cn/13-operation/07-import.md rename to docs/zh/13-operation/07-import.md diff --git a/docs-cn/13-operation/08-export.md b/docs/zh/13-operation/08-export.md similarity index 100% rename from docs-cn/13-operation/08-export.md rename to docs/zh/13-operation/08-export.md diff --git a/docs-cn/13-operation/09-status.md b/docs/zh/13-operation/09-status.md similarity index 100% rename from docs-cn/13-operation/09-status.md rename to docs/zh/13-operation/09-status.md diff --git a/docs-cn/13-operation/10-monitor.md b/docs/zh/13-operation/10-monitor.md similarity index 100% rename from docs-cn/13-operation/10-monitor.md rename to docs/zh/13-operation/10-monitor.md diff --git a/docs/zh/13-operation/11-optimize.md b/docs/zh/13-operation/11-optimize.md new file mode 100644 index 0000000000000000000000000000000000000000..d06c3cb8f5601a241fd63d73ef1a5a6165eb1617 --- /dev/null +++ b/docs/zh/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 个数。0：自动配置为 CPU 的核数。默认值：0。 +- 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/zh/13-operation/17-diagnose.md similarity index 100% rename from docs-cn/13-operation/17-diagnose.md rename to docs/zh/13-operation/17-diagnose.md diff --git a/docs/zh/13-operation/_category_.yml b/docs/zh/13-operation/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..315839970c47e4ac76f6f19f65331a44fd93229e --- /dev/null +++ b/docs/zh/13-operation/_category_.yml @@ -0,0 +1 @@ +label: 运维指南 diff --git a/docs/zh/13-operation/index.md b/docs/zh/13-operation/index.md new file mode 100644 index 0000000000000000000000000000000000000000..bc06fbdc138ee593c1206475095ef48d32493b37 --- /dev/null +++ b/docs/zh/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/zh/14-reference/02-rest-api/02-rest-api.mdx b/docs/zh/14-reference/02-rest-api/02-rest-api.mdx new file mode 100644 index 0000000000000000000000000000000000000000..43099319b9c5bb1420c199cfa9f7def0b2c44d3d --- /dev/null +++ b/docs/zh/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 接口的正常，验证前请确认 taosAdapter 服务已开启，在 Linux 系统上此服务默认由 systemd 管理，使用命令 `systemctl start taosadapter` 启动。 + +下面示例是列出所有的数据库，请把 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-en/14-reference/02-rest-api/_category_.yml b/docs/zh/14-reference/02-rest-api/_category_.yml similarity index 100% rename from docs-en/14-reference/02-rest-api/_category_.yml rename to docs/zh/14-reference/02-rest-api/_category_.yml diff --git a/docs/zh/14-reference/03-connector/03-connector.mdx b/docs/zh/14-reference/03-connector/03-connector.mdx new file mode 100644 index 0000000000000000000000000000000000000000..7a4a85276ef4bb4ab829250fcf67076962dbb871 --- /dev/null +++ b/docs/zh/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 连接器。 + +![TDengine Database connector architecture](./connector.webp) + +## 支持的平台 + +目前 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/zh/14-reference/03-connector/_category_.yml similarity index 100% rename from docs-cn/14-reference/03-connector/_category_.yml rename to docs/zh/14-reference/03-connector/_category_.yml diff --git a/docs-cn/14-reference/03-connector/_linux_install.mdx b/docs/zh/14-reference/03-connector/_linux_install.mdx similarity index 100% rename from docs-cn/14-reference/03-connector/_linux_install.mdx rename to docs/zh/14-reference/03-connector/_linux_install.mdx diff --git a/docs-cn/14-reference/03-connector/_preparition.mdx b/docs/zh/14-reference/03-connector/_preparition.mdx similarity index 100% rename from docs-cn/14-reference/03-connector/_preparition.mdx rename to docs/zh/14-reference/03-connector/_preparition.mdx diff --git a/docs/zh/14-reference/03-connector/_verify_linux.mdx b/docs/zh/14-reference/03-connector/_verify_linux.mdx new file mode 100644 index 0000000000000000000000000000000000000000..fcb8aae6ae27cdcec58e000c4ab2e8a7ec6d9a5e --- /dev/null +++ b/docs/zh/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-en/14-reference/03-connector/_verify_windows.mdx b/docs/zh/14-reference/03-connector/_verify_windows.mdx similarity index 100% rename from docs-en/14-reference/03-connector/_verify_windows.mdx rename to docs/zh/14-reference/03-connector/_verify_windows.mdx diff --git a/docs-cn/14-reference/03-connector/_windows_install.mdx b/docs/zh/14-reference/03-connector/_windows_install.mdx similarity index 100% rename from docs-cn/14-reference/03-connector/_windows_install.mdx rename to docs/zh/14-reference/03-connector/_windows_install.mdx diff --git a/docs/zh/14-reference/03-connector/connector.webp b/docs/zh/14-reference/03-connector/connector.webp new file mode 100644 index 0000000000000000000000000000000000000000..040cf5c26c726b345b2e0e5363dd3c677bec61be Binary files /dev/null and b/docs/zh/14-reference/03-connector/connector.webp differ diff --git a/docs/zh/14-reference/03-connector/cpp.mdx b/docs/zh/14-reference/03-connector/cpp.mdx new file mode 100644 index 0000000000000000000000000000000000000000..aba1d6c717dfec9228f38e89f90cbf1be0021045 --- /dev/null +++ b/docs/zh/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/zh/14-reference/03-connector/csharp.mdx b/docs/zh/14-reference/03-connector/csharp.mdx new file mode 100644 index 0000000000000000000000000000000000000000..1e23df9286bf0cb3bf1db95e334301c04d01ad04 --- /dev/null +++ b/docs/zh/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 连接方式，用户可以参考 [REST API](/reference/rest-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/zh/14-reference/03-connector/go.mdx b/docs/zh/14-reference/03-connector/go.mdx new file mode 100644 index 0000000000000000000000000000000000000000..88b09aa5d0b0161973e3e7eabb4cf04357c134f3 --- /dev/null +++ b/docs/zh/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/zh/14-reference/03-connector/java.mdx b/docs/zh/14-reference/03-connector/java.mdx new file mode 100644 index 0000000000000000000000000000000000000000..ddab9e5f24c64e51e82cad6e299f3ea0d741b349 --- /dev/null +++ b/docs/zh/14-reference/03-connector/java.mdx @@ -0,0 +1,840 @@ +--- +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 Database Connector Java](tdengine-jdbc-connector.webp) + +上图显示了两种 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/taos-connector-jdbc.git +cd taos-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 连接支持大数据量查询，并提升查询性能。 +- charset: 当开启批量拉取数据时，指定解析字符串数据的字符集。 +- 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('California.SanFrancisco') 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('California.SanFrancisco') 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：客户端使用的字符集，默认值为系统字符集。 +- 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/taos-connector-jdbc/blob/main/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, "California.SanFrancisco"); + + // 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("California.LosAngeles"); + } + 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\": \"California.SanFrancisco\", \"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/zh/14-reference/03-connector/node.mdx b/docs/zh/14-reference/03-connector/node.mdx new file mode 100644 index 0000000000000000000000000000000000000000..9f2bed9e97cb33aeabfce3d69dc3774931b426c0 --- /dev/null +++ b/docs/zh/14-reference/03-connector/node.mdx @@ -0,0 +1,252 @@ +--- +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"; + +`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/zh/14-reference/03-connector/php.mdx b/docs/zh/14-reference/03-connector/php.mdx new file mode 100644 index 0000000000000000000000000000000000000000..2b7ff2a6febd162fe34ebb737d2f33fbd9fc58a2 --- /dev/null +++ b/docs/zh/14-reference/03-connector/php.mdx @@ -0,0 +1,150 @@ +--- +sidebar_position: 1 +sidebar_label: PHP +title: PHP Connector +--- + +`php-tdengine` 是由社区贡献的 PHP 连接器扩展，还特别支持了 Swoole 协程化。 + +PHP 连接器依赖 TDengine 客户端驱动。 + +项目地址： + +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` + +## 支持的平台 + +* Windows、Linux、MacOS + +* PHP >= 7.4 + +* TDengine >= 2.0 + +* Swoole >= 4.8 (可选) + +## 支持的版本 + +TDengine 客户端驱动的版本号与 TDengine 服务端的版本号是一一对应的强对应关系，建议使用与 TDengine 服务端完全相同的客户端驱动。虽然低版本的客户端驱动在前三段版本号一致（即仅第四段版本号不同）的情况下也能够与高版本的服务端相兼容，但这并非推荐用法。强烈不建议使用高版本的客户端驱动访问低版本的服务端。 + +## 安装步骤 + +### 安装 TDengine 客户端驱动 + +TDengine 客户端驱动的安装请参考 [安装指南](/reference/connector#安装步骤) + +### 编译安装 php-tdengine + +**下载代码并解压：** + +```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.2` 可替换为任意更新的版本，可在 [TDengine PHP Connector 发布历史](https://github.com/Yurunsoft/php-tdengine/releases)。 + +**非 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 -dextension=tdengine test.php` + +## 示例程序 + +本节展示了使用客户端驱动访问 TDengine 集群的常见访问方式的示例代码。 + +> 所有错误都会抛出异常: `TDengine\Exception\TDengineException` + +### 建立连接 + +
+建立连接 + +```c +{{#include docs/examples/php/connect.php}} +``` + +
+ +### 插入数据 + +
+插入数据 + +```c +{{#include docs/examples/php/insert.php}} +``` + +
+ +### 同步查询 + +
+同步查询 + +```c +{{#include docs/examples/php/query.php}} +``` + +
+ +### 参数绑定 + +
+参数绑定 + +```c +{{#include docs/examples/php/insert_stmt.php}} +``` + +
+ +## 常量 + +| 常量 | 说明 | +| ------------ | ------------ +| `TDengine\TSDB_DATA_TYPE_NULL` | null | +| `TDengine\TSDB_DATA_TYPE_BOOL` | bool | +| `TDengine\TSDB_DATA_TYPE_TINYINT` | tinyint | +| `TDengine\TSDB_DATA_TYPE_SMALLINT` | smallint | +| `TDengine\TSDB_DATA_TYPE_INT` | int | +| `TDengine\TSDB_DATA_TYPE_BIGINT` | bigint | +| `TDengine\TSDB_DATA_TYPE_FLOAT` | float | +| `TDengine\TSDB_DATA_TYPE_DOUBLE` | double | +| `TDengine\TSDB_DATA_TYPE_BINARY` | binary | +| `TDengine\TSDB_DATA_TYPE_TIMESTAMP` | timestamp | +| `TDengine\TSDB_DATA_TYPE_NCHAR` | nchar | +| `TDengine\TSDB_DATA_TYPE_UTINYINT` | utinyint | +| `TDengine\TSDB_DATA_TYPE_USMALLINT` | usmallint | +| `TDengine\TSDB_DATA_TYPE_UINT` | uint | +| `TDengine\TSDB_DATA_TYPE_UBIGINT` | ubigint | diff --git a/docs/zh/14-reference/03-connector/python.mdx b/docs/zh/14-reference/03-connector/python.mdx new file mode 100644 index 0000000000000000000000000000000000000000..a77dc71db7d07c93084984d2e95e3d4267bca924 --- /dev/null +++ b/docs/zh/14-reference/03-connector/python.mdx @@ -0,0 +1,348 @@ +--- +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()` 函数的所有参数都是可选的关键字参数。下面是连接参数的具体说明： + +- `url`： taosAdapter REST 服务的 URL。默认是 。 +- `user`： TDenigne 用户名。默认是 root。 +- `password`： TDeingine 用户密码。默认是 taosdata。 +- `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/zh/14-reference/03-connector/rust.mdx b/docs/zh/14-reference/03-connector/rust.mdx new file mode 100644 index 0000000000000000000000000000000000000000..25a8409b6e6faca651d1eaf3e02fbd4a0199c557 --- /dev/null +++ b/docs/zh/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/zh/14-reference/03-connector/tdengine-jdbc-connector.webp b/docs/zh/14-reference/03-connector/tdengine-jdbc-connector.webp new file mode 100644 index 0000000000000000000000000000000000000000..0956d6005ffc5e90727d49d7566158affdda09c2 Binary files /dev/null and b/docs/zh/14-reference/03-connector/tdengine-jdbc-connector.webp differ diff --git a/docs/zh/14-reference/04-taosadapter.md b/docs/zh/14-reference/04-taosadapter.md new file mode 100644 index 0000000000000000000000000000000000000000..6e259391d40acfd48d8db8db3246ad2196ce0520 --- /dev/null +++ b/docs/zh/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 架构图 + +![TDengine Database taosAdapter Architecture](taosAdapter-architecture.webp) + +## 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/zh/14-reference/05-taosbenchmark.md b/docs/zh/14-reference/05-taosbenchmark.md new file mode 100644 index 0000000000000000000000000000000000000000..6b694543b1db435f507b5e2fb325cebe76261b48 --- /dev/null +++ b/docs/zh/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/zh/14-reference/06-taosdump.md b/docs/zh/14-reference/06-taosdump.md new file mode 100644 index 0000000000000000000000000000000000000000..3a9f2e9acd215be102991a1d91fba285ef6315bb --- /dev/null +++ b/docs/zh/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-en/14-reference/07-tdinsight/assets/15146-tdengine-monitor-dashboard.json b/docs/zh/14-reference/07-tdinsight/assets/15146-tdengine-monitor-dashboard.json similarity index 100% rename from docs-en/14-reference/07-tdinsight/assets/15146-tdengine-monitor-dashboard.json rename to docs/zh/14-reference/07-tdinsight/assets/15146-tdengine-monitor-dashboard.json diff --git a/docs-en/14-reference/07-tdinsight/assets/15155-tdengine-alert-demo.json b/docs/zh/14-reference/07-tdinsight/assets/15155-tdengine-alert-demo.json similarity index 100% rename from docs-en/14-reference/07-tdinsight/assets/15155-tdengine-alert-demo.json rename to docs/zh/14-reference/07-tdinsight/assets/15155-tdengine-alert-demo.json diff --git a/docs/zh/14-reference/07-tdinsight/assets/TDinsight-1-cluster-status.webp b/docs/zh/14-reference/07-tdinsight/assets/TDinsight-1-cluster-status.webp new file mode 100644 index 0000000000000000000000000000000000000000..a78e18028a94c2f6a783b08d992a25c791527407 Binary files /dev/null and b/docs/zh/14-reference/07-tdinsight/assets/TDinsight-1-cluster-status.webp differ diff --git a/docs/zh/14-reference/07-tdinsight/assets/TDinsight-2-dnodes.webp b/docs/zh/14-reference/07-tdinsight/assets/TDinsight-2-dnodes.webp new file mode 100644 index 0000000000000000000000000000000000000000..b152418d0902b8ebdf62ebce6705c10dd5ab4fbf Binary files /dev/null and b/docs/zh/14-reference/07-tdinsight/assets/TDinsight-2-dnodes.webp differ diff --git a/docs/zh/14-reference/07-tdinsight/assets/TDinsight-3-mnodes.webp b/docs/zh/14-reference/07-tdinsight/assets/TDinsight-3-mnodes.webp new file mode 100644 index 0000000000000000000000000000000000000000..f58f48b7f17375cb8e62e7c0126ca3aea56a13f6 Binary files /dev/null and b/docs/zh/14-reference/07-tdinsight/assets/TDinsight-3-mnodes.webp differ diff --git a/docs/zh/14-reference/07-tdinsight/assets/TDinsight-4-requests.webp b/docs/zh/14-reference/07-tdinsight/assets/TDinsight-4-requests.webp new file mode 100644 index 0000000000000000000000000000000000000000..00afcce013602dce0da17bfd033f65aaa8e43bb7 Binary files /dev/null and b/docs/zh/14-reference/07-tdinsight/assets/TDinsight-4-requests.webp differ diff --git a/docs/zh/14-reference/07-tdinsight/assets/TDinsight-5-database.webp b/docs/zh/14-reference/07-tdinsight/assets/TDinsight-5-database.webp new file mode 100644 index 0000000000000000000000000000000000000000..567e5694f9d7a035a3eb354493d3df8ed64db251 Binary files /dev/null and b/docs/zh/14-reference/07-tdinsight/assets/TDinsight-5-database.webp differ diff --git a/docs/zh/14-reference/07-tdinsight/assets/TDinsight-6-dnode-usage.webp b/docs/zh/14-reference/07-tdinsight/assets/TDinsight-6-dnode-usage.webp new file mode 100644 index 0000000000000000000000000000000000000000..cc8a912810f35e53a6e5fa96ea0c81e334ffc0df Binary files /dev/null and b/docs/zh/14-reference/07-tdinsight/assets/TDinsight-6-dnode-usage.webp differ diff --git a/docs/zh/14-reference/07-tdinsight/assets/TDinsight-7-login-history.webp b/docs/zh/14-reference/07-tdinsight/assets/TDinsight-7-login-history.webp new file mode 100644 index 0000000000000000000000000000000000000000..651b716bc511ba2ed5db5e6fc6b0591ef150cbf6 Binary files /dev/null and b/docs/zh/14-reference/07-tdinsight/assets/TDinsight-7-login-history.webp differ diff --git a/docs/zh/14-reference/07-tdinsight/assets/TDinsight-8-taosadapter.webp b/docs/zh/14-reference/07-tdinsight/assets/TDinsight-8-taosadapter.webp new file mode 100644 index 0000000000000000000000000000000000000000..8666193f59497180574fd2786266e5baabbe9761 Binary files /dev/null and b/docs/zh/14-reference/07-tdinsight/assets/TDinsight-8-taosadapter.webp differ diff --git a/docs/zh/14-reference/07-tdinsight/assets/TDinsight-full.webp b/docs/zh/14-reference/07-tdinsight/assets/TDinsight-full.webp new file mode 100644 index 0000000000000000000000000000000000000000..7f38a76a2b899ffebc7aecd39c8ec4fd0b2da778 Binary files /dev/null and b/docs/zh/14-reference/07-tdinsight/assets/TDinsight-full.webp differ diff --git a/docs/zh/14-reference/07-tdinsight/assets/alert-manager-status.webp b/docs/zh/14-reference/07-tdinsight/assets/alert-manager-status.webp new file mode 100644 index 0000000000000000000000000000000000000000..3d7fe932a23f3720e76e4217a7b5d1868d81fac8 Binary files /dev/null and b/docs/zh/14-reference/07-tdinsight/assets/alert-manager-status.webp differ diff --git a/docs/zh/14-reference/07-tdinsight/assets/alert-notification-channel.webp b/docs/zh/14-reference/07-tdinsight/assets/alert-notification-channel.webp new file mode 100644 index 0000000000000000000000000000000000000000..517123954efe4b94485fdab2e07be0d765f5daa2 Binary files /dev/null and b/docs/zh/14-reference/07-tdinsight/assets/alert-notification-channel.webp differ diff --git a/docs/zh/14-reference/07-tdinsight/assets/alert-query-demo.webp b/docs/zh/14-reference/07-tdinsight/assets/alert-query-demo.webp new file mode 100644 index 0000000000000000000000000000000000000000..6666296ac16e7a0c0ab3db23f0517f2089d09035 Binary files /dev/null and b/docs/zh/14-reference/07-tdinsight/assets/alert-query-demo.webp differ diff --git a/docs/zh/14-reference/07-tdinsight/assets/alert-rule-condition-notifications.webp b/docs/zh/14-reference/07-tdinsight/assets/alert-rule-condition-notifications.webp new file mode 100644 index 0000000000000000000000000000000000000000..6f74bc3a47a32de661ef25f787a947d823715810 Binary files /dev/null and b/docs/zh/14-reference/07-tdinsight/assets/alert-rule-condition-notifications.webp differ diff --git a/docs/zh/14-reference/07-tdinsight/assets/alert-rule-test.webp b/docs/zh/14-reference/07-tdinsight/assets/alert-rule-test.webp new file mode 100644 index 0000000000000000000000000000000000000000..acda3b24a6263815ac8b658709d2172300ca3b00 Binary files /dev/null and b/docs/zh/14-reference/07-tdinsight/assets/alert-rule-test.webp differ diff --git a/docs/zh/14-reference/07-tdinsight/assets/howto-add-datasource-button.webp b/docs/zh/14-reference/07-tdinsight/assets/howto-add-datasource-button.webp new file mode 100644 index 0000000000000000000000000000000000000000..903e236e2a776dfef7f85c014662e8913a9033a5 Binary files /dev/null and b/docs/zh/14-reference/07-tdinsight/assets/howto-add-datasource-button.webp differ diff --git a/docs/zh/14-reference/07-tdinsight/assets/howto-add-datasource-tdengine.webp b/docs/zh/14-reference/07-tdinsight/assets/howto-add-datasource-tdengine.webp new file mode 100644 index 0000000000000000000000000000000000000000..14fcfe9d183e8804199708ae4492d0904a7c9d62 Binary files /dev/null and b/docs/zh/14-reference/07-tdinsight/assets/howto-add-datasource-tdengine.webp differ diff --git a/docs/zh/14-reference/07-tdinsight/assets/howto-add-datasource-test.webp b/docs/zh/14-reference/07-tdinsight/assets/howto-add-datasource-test.webp new file mode 100644 index 0000000000000000000000000000000000000000..00b50cc619b030d1fb2be3a367183901d5c833e8 Binary files /dev/null and b/docs/zh/14-reference/07-tdinsight/assets/howto-add-datasource-test.webp differ diff --git a/docs/zh/14-reference/07-tdinsight/assets/howto-add-datasource.webp b/docs/zh/14-reference/07-tdinsight/assets/howto-add-datasource.webp new file mode 100644 index 0000000000000000000000000000000000000000..06d0ff6ed50091a6340508bc5b2b3f78b65dcb18 Binary files /dev/null and b/docs/zh/14-reference/07-tdinsight/assets/howto-add-datasource.webp differ diff --git a/docs/zh/14-reference/07-tdinsight/assets/howto-dashboard-display.webp b/docs/zh/14-reference/07-tdinsight/assets/howto-dashboard-display.webp new file mode 100644 index 0000000000000000000000000000000000000000..e2ec052b91e439a817f6e88b8afd0fcb4dcb7ef8 Binary files /dev/null and b/docs/zh/14-reference/07-tdinsight/assets/howto-dashboard-display.webp differ diff --git a/docs/zh/14-reference/07-tdinsight/assets/howto-dashboard-import-options.webp b/docs/zh/14-reference/07-tdinsight/assets/howto-dashboard-import-options.webp new file mode 100644 index 0000000000000000000000000000000000000000..665c035f9755b9472aee33cd61d3ab52831194b5 Binary files /dev/null and b/docs/zh/14-reference/07-tdinsight/assets/howto-dashboard-import-options.webp differ diff --git a/docs/zh/14-reference/07-tdinsight/assets/howto-import-dashboard.webp b/docs/zh/14-reference/07-tdinsight/assets/howto-import-dashboard.webp new file mode 100644 index 0000000000000000000000000000000000000000..7dc42eeba919fee7b438a453c00bb9fd0ac2d274 Binary files /dev/null and b/docs/zh/14-reference/07-tdinsight/assets/howto-import-dashboard.webp differ diff --git a/docs/zh/14-reference/07-tdinsight/assets/import-dashboard-15167.webp b/docs/zh/14-reference/07-tdinsight/assets/import-dashboard-15167.webp new file mode 100644 index 0000000000000000000000000000000000000000..7ef081900f8de99c859193b69d49b3d6bc187909 Binary files /dev/null and b/docs/zh/14-reference/07-tdinsight/assets/import-dashboard-15167.webp differ diff --git a/docs/zh/14-reference/07-tdinsight/assets/import-dashboard-for-tdengine.webp b/docs/zh/14-reference/07-tdinsight/assets/import-dashboard-for-tdengine.webp new file mode 100644 index 0000000000000000000000000000000000000000..602452fc4c89424d8e17d46d74949b69be84dbe8 Binary files /dev/null and b/docs/zh/14-reference/07-tdinsight/assets/import-dashboard-for-tdengine.webp differ diff --git a/docs/zh/14-reference/07-tdinsight/assets/import-via-grafana-dot-com.webp b/docs/zh/14-reference/07-tdinsight/assets/import-via-grafana-dot-com.webp new file mode 100644 index 0000000000000000000000000000000000000000..35a3ebba781f24dbb0066993d1ca2f02659997d2 Binary files /dev/null and b/docs/zh/14-reference/07-tdinsight/assets/import-via-grafana-dot-com.webp differ diff --git a/docs/zh/14-reference/07-tdinsight/assets/import_dashboard.webp b/docs/zh/14-reference/07-tdinsight/assets/import_dashboard.webp new file mode 100644 index 0000000000000000000000000000000000000000..fb7958f1b9fbd43c8f63136024842790e711c490 Binary files /dev/null and b/docs/zh/14-reference/07-tdinsight/assets/import_dashboard.webp differ diff --git a/docs-en/14-reference/07-tdinsight/assets/tdengine-grafana-7.x.json b/docs/zh/14-reference/07-tdinsight/assets/tdengine-grafana-7.x.json similarity index 100% rename from docs-en/14-reference/07-tdinsight/assets/tdengine-grafana-7.x.json rename to docs/zh/14-reference/07-tdinsight/assets/tdengine-grafana-7.x.json diff --git a/docs-en/14-reference/07-tdinsight/assets/tdengine-grafana.json b/docs/zh/14-reference/07-tdinsight/assets/tdengine-grafana.json similarity index 100% rename from docs-en/14-reference/07-tdinsight/assets/tdengine-grafana.json rename to docs/zh/14-reference/07-tdinsight/assets/tdengine-grafana.json diff --git a/docs/zh/14-reference/07-tdinsight/assets/tdengine_dashboard.webp b/docs/zh/14-reference/07-tdinsight/assets/tdengine_dashboard.webp new file mode 100644 index 0000000000000000000000000000000000000000..49f1d88f4ad93286cd8582536e82b4dcc4ff271b Binary files /dev/null and b/docs/zh/14-reference/07-tdinsight/assets/tdengine_dashboard.webp differ diff --git a/docs/zh/14-reference/07-tdinsight/index.md b/docs/zh/14-reference/07-tdinsight/index.md new file mode 100644 index 0000000000000000000000000000000000000000..5990a831b8bc1788deaddfb38f717f2723969362 --- /dev/null +++ b/docs/zh/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** 按钮。 + +![TDengine Database TDinsight 添加数据源按钮](./assets/howto-add-datasource-button.webp) + +搜索并选择**TDengine**。 + +![TDengine Database TDinsight 添加数据源](./assets/howto-add-datasource-tdengine.webp) + +配置 TDengine 数据源。 + +![TDengine Database TDinsight 数据源配置](./assets/howto-add-datasource.webp) + +保存并测试，正常情况下会报告 'TDengine Data source is working'。 + +![TDengine Database TDinsight 数据源测试](./assets/howto-add-datasource-test.webp) + +### 导入仪表盘 + +指向 **+** / **Create** - **import**（或 `/dashboard/import` url）。 + +![TDengine Database TDinsight 导入仪表盘和配置](./assets/import_dashboard.webp) + +在 **Import via grafana.com** 位置键入仪表盘 ID `15167` 并 **Load**。 + +![通过 grafana.com 导入](./assets/import-dashboard-15167.webp) + +导入完成后，TDinsight 的完整页面视图如下所示。 + +![TDengine Database TDinsight 显示](./assets/TDinsight-full.webp) + +## TDinsight 仪表盘详细信息 + +TDinsight 仪表盘旨在提供 TDengine 相关资源使用情况[dnodes, mnodes, vnodes](https://www.taosdata.com/cn/documentation/architecture#cluster)或数据库的使用情况和状态。 + +指标详情如下： + +### 集群状态 + +![TDengine Database TDinsight mnodes overview](./assets/TDinsight-1-cluster-status.webp) + +这部分包括集群当前信息和状态，告警信息也在此处（从左到右，从上到下）。 + +- **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 状态 + +![TDengine Database TDinsight mnodes overview](./assets/TDinsight-2-dnodes.webp) + +- **DNodes Status**：`show dnodes` 的简单表格视图。 +- **DNodes Lifetime**：从创建 dnode 开始经过的时间。 +- **DNodes Number**：DNodes 数量变化。 +- **Offline Reason**：如果有任何 dnode 状态为离线，则以饼图形式展示离线原因。 + +### MNode 概述 + +![TDengine Database TDinsight mnodes overview](./assets/TDinsight-3-mnodes.webp) + +1. **MNodes Status**：`show mnodes` 的简单表格视图。 +2. **MNodes Number**：类似于`DNodes Number`，MNodes 数量变化。 + +### 请求 + +![TDengine Database TDinsight requests](./assets/TDinsight-4-requests.webp) + +1. **Requests Rate(Inserts per Second)**：平均每秒插入次数。 +2. **Requests (Selects)**：查询请求数及变化率（count of second）。 +3. **Requests (HTTP)**：HTTP 请求数和请求速率（count of second）。 + +### 数据库 + +![TDengine Database TDinsight database](./assets/TDinsight-5-database.webp) + +数据库使用情况，对变量 `$database` 的每个值即每个数据库进行重复多行展示。 + +1. **STables**：超级表数量。 +2. **Total Tables**：所有表数量。 +3. **Sub Tables**：所有超级表子表的数量。 +4. **Tables**：所有普通表数量随时间变化图。 +5. **Tables Number Foreach VGroups**：每个 VGroups 包含的表数量。 + +### DNode 资源使用情况 + +![TDengine Database TDinsight dnode-usage](./assets/TDinsight-6-dnode-usage.webp) + +数据节点资源使用情况展示，对变量 `$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 速率。 + +### 登录历史 + +![TDengine Database TDinsight 登录历史](./assets/TDinsight-7-login-history.webp) + +目前只报告每分钟登录次数。 + +### 监控 taosAdapter + +![TDengine Database TDinsight monitor taosadapter](./assets/TDinsight-8-taosadapter.webp) + +支持监控 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/zh/14-reference/08-taos-shell.md b/docs/zh/14-reference/08-taos-shell.md new file mode 100644 index 0000000000000000000000000000000000000000..5778df7233e6997f9c0f71e4aa5b81d462746c19 --- /dev/null +++ b/docs/zh/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/#install-client-driver/#安装客户端驱动)。 + +## 执行 + +要进入 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/zh/14-reference/09-support-platform/_category_.yml similarity index 100% rename from docs-cn/14-reference/09-support-platform/_category_.yml rename to docs/zh/14-reference/09-support-platform/_category_.yml diff --git a/docs-cn/14-reference/09-support-platform/index.md b/docs/zh/14-reference/09-support-platform/index.md similarity index 100% rename from docs-cn/14-reference/09-support-platform/index.md rename to docs/zh/14-reference/09-support-platform/index.md diff --git a/docs-cn/14-reference/11-docker/_category_.yml b/docs/zh/14-reference/11-docker/_category_.yml similarity index 100% rename from docs-cn/14-reference/11-docker/_category_.yml rename to docs/zh/14-reference/11-docker/_category_.yml diff --git a/docs/zh/14-reference/11-docker/index.md b/docs/zh/14-reference/11-docker/index.md new file mode 100644 index 0000000000000000000000000000000000000000..d0b7f1420420655909f6ceec5b249d2dad16dd3c --- /dev/null +++ b/docs/zh/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/zh/14-reference/12-config/_category_.yml similarity index 100% rename from docs-cn/14-reference/12-config/_category_.yml rename to docs/zh/14-reference/12-config/_category_.yml diff --git a/docs/zh/14-reference/12-config/index.md b/docs/zh/14-reference/12-config/index.md new file mode 100644 index 0000000000000000000000000000000000000000..2d1866d5dd1874164d03ffdfb382010c8345ad63 --- /dev/null +++ b/docs/zh/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 +确保集群中所有主机在端口 6030-6042 上的 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：激活监控服务。 | +| 缺省值 | 1 | + +### 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 | +| 缺省值 | 0 | + +### 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/zh/14-reference/12-directory.md similarity index 100% rename from docs-cn/14-reference/12-directory.md rename to docs/zh/14-reference/12-directory.md diff --git a/docs/zh/14-reference/13-schemaless/13-schemaless.md b/docs/zh/14-reference/13-schemaless/13-schemaless.md new file mode 100644 index 0000000000000000000000000000000000000000..f2712f2814593bddd65401cb129c8c58ee55a316 --- /dev/null +++ b/docs/zh/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 对数据结构的底层限制，例如每行数据的总长度不能超过 +48KB。这方面的具体限制约束请参见 [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/zh/14-reference/13-schemaless/_category_.yml similarity index 100% rename from docs-cn/14-reference/13-schemaless/_category_.yml rename to docs/zh/14-reference/13-schemaless/_category_.yml diff --git a/docs/zh/14-reference/_category_.yml b/docs/zh/14-reference/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..ae861a15ff626b1e0424a28838830702262aa377 --- /dev/null +++ b/docs/zh/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/zh/14-reference/_collectd.mdx similarity index 100% rename from docs-cn/14-reference/_collectd.mdx rename to docs/zh/14-reference/_collectd.mdx diff --git a/docs-cn/14-reference/_icinga2.mdx b/docs/zh/14-reference/_icinga2.mdx similarity index 100% rename from docs-cn/14-reference/_icinga2.mdx rename to docs/zh/14-reference/_icinga2.mdx diff --git a/docs-cn/14-reference/_prometheus.mdx b/docs/zh/14-reference/_prometheus.mdx similarity index 100% rename from docs-cn/14-reference/_prometheus.mdx rename to docs/zh/14-reference/_prometheus.mdx diff --git a/docs-cn/14-reference/_statsd.mdx b/docs/zh/14-reference/_statsd.mdx similarity index 100% rename from docs-cn/14-reference/_statsd.mdx rename to docs/zh/14-reference/_statsd.mdx diff --git a/docs-cn/14-reference/_tcollector.mdx b/docs/zh/14-reference/_tcollector.mdx similarity index 100% rename from docs-cn/14-reference/_tcollector.mdx rename to docs/zh/14-reference/_tcollector.mdx diff --git a/docs-cn/14-reference/_telegraf.mdx b/docs/zh/14-reference/_telegraf.mdx similarity index 100% rename from docs-cn/14-reference/_telegraf.mdx rename to docs/zh/14-reference/_telegraf.mdx diff --git a/docs/zh/14-reference/index.md b/docs/zh/14-reference/index.md new file mode 100644 index 0000000000000000000000000000000000000000..f48ce31fcefd2f0d875aee64e7d92490f4e92fcb --- /dev/null +++ b/docs/zh/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/zh/14-reference/taosAdapter-architecture.webp b/docs/zh/14-reference/taosAdapter-architecture.webp new file mode 100644 index 0000000000000000000000000000000000000000..a4162b0a037c06d34191784716c51080b9f8a570 Binary files /dev/null and b/docs/zh/14-reference/taosAdapter-architecture.webp differ diff --git a/docs/zh/20-third-party/01-grafana.mdx b/docs/zh/20-third-party/01-grafana.mdx new file mode 100644 index 0000000000000000000000000000000000000000..b54989f0115bc07bef81ca363b5909ffa970c6ad --- /dev/null +++ b/docs/zh/20-third-party/01-grafana.mdx @@ -0,0 +1,146 @@ +--- +sidebar_label: Grafana +title: Grafana +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +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) + +记录以下信息： + +- TDengine 集群 REST API 地址，如：`http://tdengine.local:6041`。 +- TDengine 集群认证信息，可使用用户名及密码。 + +## 安装 Grafana + +目前 TDengine 支持 Grafana 7.5 以上的版本。用户可以根据当前的操作系统，到 Grafana 官网下载安装包，并执行安装。下载地址如下：。 + +## 配置 Grafana + +### 安装 Grafana Plugin 并配置数据源 + + + + +将集群信息设置为环境变量；也可以使用 `.env` 文件，请参考 [dotenv](https://hexdocs.pm/dotenvy/dotenv-file-format.html)： + +```sh +export TDENGINE_API=http://tdengine.local:6041 +# user + password +export TDENGINE_USER=user +export TDENGINE_PASSWORD=password + +# 其他环境变量： +# - 是否安装数据源，默认为 true，表示安装 +export TDENGINE_DS_ENABLED=false +# - 数据源名称，默认为 TDengine +export TDENGINE_DS_NAME=TDengine +# - 数据源所属组织 ID，默认为 1 +export GF_ORG_ID=1 +# - 数据源是否可通过管理面板编辑，默认为 0，表示不可编辑 +export TDENGINE_EDITABLE=1 +``` + +运行安装脚本： + +```sh +bash -c "$(curl -fsSL https://raw.githubusercontent.com/taosdata/grafanaplugin/master/install.sh)" +``` + +该脚本将自动安装 Grafana 插件并配置数据源。安装完毕后，需要重启 Grafana 服务后生效。 + +保存该脚本并执行 `./install.sh --help` 可查看详细帮助文档。 + + + + +使用 [`grafana-cli` 命令行工具](https://grafana.com/docs/grafana/latest/administration/cli/) 进行插件[安装](https://grafana.com/grafana/plugins/tdengine-datasource/?tab=installation)。 + +```bash +grafana-cli plugins install tdengine-datasource +# with sudo +sudo -u grafana grafana-cli plugins install tdengine-datasource +``` + +或者从 [GitHub](https://github.com/taosdata/grafanaplugin/tags) 或 [Grafana](https://grafana.com/grafana/plugins/tdengine-datasource/?tab=installation) 下载 .zip 文件到本地并解压到 Grafana 插件目录。命令行下载示例如下： + +```bash +GF_VERSION=3.2.2 +# from GitHub +wget https://github.com/taosdata/grafanaplugin/releases/download/v$GF_VERSION/tdengine-datasource-$GF_VERSION.zip +# from Grafana +wget -O tdengine-datasource-$GF_VERSION.zip https://grafana.com/api/plugins/tdengine-datasource/versions/$GF_VERSION/download +``` + +以 CentOS 7.2 操作系统为例，将插件包解压到 /var/lib/grafana/plugins 目录下，重新启动 grafana 即可。 + +```bash +sudo unzip tdengine-datasource-$GF_VERSION.zip -d /var/lib/grafana/plugins/ +``` + +如果 Grafana 在 Docker 环境下运行，可以使用如下的环境变量设置自动安装 TDengine 数据源插件： + +```bash +GF_INSTALL_PLUGINS=tdengine-datasource +``` + +之后，用户可以直接通过 的网址，登录 Grafana 服务器（用户名/密码：admin/admin），通过左侧 `Configuration -> Data Sources` 可以添加数据源，如下图所示： + +![TDengine Database Grafana plugin add data source](./add_datasource1.webp) + +点击 `Add data source` 可进入新增数据源页面，在查询框中输入 TDengine 可选择添加，如下图所示： + +![TDengine Database Grafana plugin add data source](./add_datasource2.webp) + +进入数据源配置页面，按照默认提示修改相应配置即可： + +![TDengine Database Grafana plugin add data source](./add_datasource3.webp) + +- Host： TDengine 集群中提供 REST 服务 （在 2.4 之前由 taosd 提供， 从 2.4 开始由 taosAdapter 提供）的组件所在服务器的 IP 地址与 TDengine REST 服务的端口号(6041)，默认 。 +- User：TDengine 用户名。 +- Password：TDengine 用户密码。 + +点击 `Save & Test` 进行测试，成功会有如下提示： + +![TDengine Database Grafana plugin add data source](./add_datasource4.webp) + + + + +### 创建 Dashboard + +回到主界面创建 Dashboard，点击 Add Query 进入面板查询页面： + +![TDengine Database Grafana plugin create dashboard](./create_dashboard1.webp) + +如上图所示，在 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 部署所在服务器指定间隔系统内存平均使用量如下： + +![TDengine Database Grafana plugin create dashboard](./create_dashboard2.webp) + +> 关于如何使用 Grafana 创建相应的监测界面以及更多有关使用 Grafana 的信息，请参考 Grafana 官方的[文档](https://grafana.com/docs/)。 + +### 导入 Dashboard + +在数据源配置页面，您可以为该数据源导入 TDinsight 面板，作为 TDengine 集群的监控可视化工具。该 Dashboard 已发布在 Grafana：[Dashboard 15167 - TDinsight](https://grafana.com/grafana/dashboards/15167)) 。其他安装方式和相关使用说明请见 [TDinsight 用户手册](/reference/tdinsight/)。 + +使用 TDengine 作为数据源的其他面板，可以[在此搜索](https://grafana.com/grafana/dashboards/?dataSource=tdengine-datasource)。以下是一份不完全列表： + +- [15146](https://grafana.com/grafana/dashboards/15146): 监控多个 TDengine 集群 +- [15155](https://grafana.com/grafana/dashboards/15155): TDengine 告警示例 +- [15167](https://grafana.com/grafana/dashboards/15167): TDinsight +- [16388](https://grafana.com/grafana/dashboards/16388): Telegraf 采集节点信息的数据展示 diff --git a/docs-cn/20-third-party/02-prometheus.md b/docs/zh/20-third-party/02-prometheus.md similarity index 100% rename from docs-cn/20-third-party/02-prometheus.md rename to docs/zh/20-third-party/02-prometheus.md diff --git a/docs-cn/20-third-party/03-telegraf.md b/docs/zh/20-third-party/03-telegraf.md similarity index 100% rename from docs-cn/20-third-party/03-telegraf.md rename to docs/zh/20-third-party/03-telegraf.md diff --git a/docs-cn/20-third-party/05-collectd.md b/docs/zh/20-third-party/05-collectd.md similarity index 100% rename from docs-cn/20-third-party/05-collectd.md rename to docs/zh/20-third-party/05-collectd.md diff --git a/docs-cn/20-third-party/06-statsd.md b/docs/zh/20-third-party/06-statsd.md similarity index 100% rename from docs-cn/20-third-party/06-statsd.md rename to docs/zh/20-third-party/06-statsd.md diff --git a/docs-cn/20-third-party/07-icinga2.md b/docs/zh/20-third-party/07-icinga2.md similarity index 100% rename from docs-cn/20-third-party/07-icinga2.md rename to docs/zh/20-third-party/07-icinga2.md diff --git a/docs/zh/20-third-party/08-tcollector.md b/docs/zh/20-third-party/08-tcollector.md new file mode 100644 index 0000000000000000000000000000000000000000..a1245e8c27f302d56f88fa382b5f38f9bd49a0aa --- /dev/null +++ b/docs/zh/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/zh/20-third-party/09-emq-broker.md b/docs/zh/20-third-party/09-emq-broker.md new file mode 100644 index 0000000000000000000000000000000000000000..84b1027f6b080cc5d5f8ac98f9aa6ea8be428f28 --- /dev/null +++ b/docs/zh/20-third-party/09-emq-broker.md @@ -0,0 +1,148 @@ +--- +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 数据创建相应数据库和表结构。进入 TDengine CLI 复制并执行以下 SQL 语句： + +```sql +CREATE DATABASE test; +USE test; +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`。 + +![TDengine Database EMQX login dashboard](./emqx/login-dashboard.webp) + +### 创建规则（Rule） + +选择左侧“规则引擎（Rule Engine）”中的“规则（Rule）”并点击“创建（Create）”按钮： + +![TDengine Database EMQX rule engine](./emqx/rule-engine.webp) + +### 编辑 SQL 字段 + +复制以下内容输入到 SQL 编辑框： + +```sql +SELECT + payload +FROM + "sensor/data" +``` + +其中 `payload` 代表整个消息体， `sensor/data` 为本规则选取的消息主题。 + +![TDengine Database EMQX create rule](./emqx/create-rule.webp) + +### 新增“动作（action handler）” + +![TDengine Database EMQX](./emqx/add-action-handler.webp) + +### 新增“资源（Resource）” + +![TDengine Database EMQX create resource](./emqx/create-resource.webp) + +选择“发送数据到 Web 服务”并点击“新建资源”按钮： + +### 编辑“资源（Resource）” + +选择“WebHook”并填写“请求 URL”为 taosAdapter 提供 REST 服务的地址，如果是本地启动的 taosadapter， 那么默认地址为： + +``` +http://127.0.0.1:6041/rest/sql +``` + +其他属性请保持默认值。 + +![TDengine Database EMQX edit resource](./emqx/edit-resource.webp) + +### 编辑“动作（action）” + +编辑资源配置，增加 Authorization 认证的键/值配对项。默认用户名和密码对应的 Authorization 值为： +``` +Basic cm9vdDp0YW9zZGF0YQ== +``` +相关文档请参考[ TDengine REST API 文档](/reference/rest-api/)。 + +在消息体中输入规则引擎替换模板: + +```sql +INSERT INTO test.sensor_data VALUES( + now, + ${payload.temperature}, + ${payload.humidity}, + ${payload.volume}, + ${payload.PM10}, + ${payload.pm25}, + ${payload.SO2}, + ${payload.NO2}, + ${payload.CO}, + '${payload.id}', + ${payload.area}, + ${payload.ts} +) +``` + +![TDengine Database EMQX edit action](./emqx/edit-action.webp) + +最后点击左下方的 “Create” 按钮，保存规则。 +## 编写模拟测试程序 + +```javascript +{{#include docs/examples/other/mock.js}} +``` + +注意：代码中 CLIENT_NUM 在开始测试中可以先设置一个较小的值，避免硬件性能不能完全处理较大并发客户端数量。 + +![TDengine Database EMQX client num](./emqx/client-num.webp) + +## 执行测试模拟发送 MQTT 数据 + +``` +npm install mqtt mockjs --save --registry=https://registry.npm.taobao.org +node mock.js +``` + +![TDengine Database EMQX run-mock](./emqx/run-mock.webp) + +## 验证 EMQX 接收到数据 + +在 EMQX Dashboard 规则引擎界面进行刷新，可以看到有多少条记录被正确接收到： + +![TDengine Database EMQX rule matched](./emqx/check-rule-matched.webp) + +## 验证数据写入到 TDengine + +使用 TDengine CLI 程序登录并查询相应数据库和表，验证数据是否被正确写入到 TDengine 中： + +![TDengine Database EMQX result in taos](./emqx/check-result-in-taos.webp) + +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/zh/20-third-party/10-hive-mq-broker.md similarity index 100% rename from docs-cn/20-third-party/10-hive-mq-broker.md rename to docs/zh/20-third-party/10-hive-mq-broker.md diff --git a/docs/zh/20-third-party/11-kafka.md b/docs/zh/20-third-party/11-kafka.md new file mode 100644 index 0000000000000000000000000000000000000000..8369806adcfe1b195348e7d60160609cde9150e8 --- /dev/null +++ b/docs/zh/20-third-party/11-kafka.md @@ -0,0 +1,448 @@ +--- +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](https://kafka.apache.org/) 的一个组件，用于使其它系统，比如数据库、云服务、文件系统等能方便地连接到 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 接收数据。 + +![TDengine Database Kafka Connector -- Kafka Connect structure](kafka/Kafka_Connect.webp) + +TDengine Source Connector 用于把数据实时地从 TDengine 读出来发送给 Kafka Connect。TDengine Sink Connector 用于 从 Kafka Connect 接收数据并写入 TDengine。 + +![TDengine Database Kafka Connector -- streaming integration with kafka connect](kafka/streaming-integration-with-kafka-connect.webp) + +## 什么是 Confluent？ + +[Confluent](https://www.confluent.io/) 在 Kafka 的基础上增加很多扩展功能。包括： + +1. Schema Registry +2. REST 代理 +3. 非 Java 客户端 +4. 很多打包好的 Kafka Connect 插件 +5. 管理和监控 Kafka 的 GUI —— Confluent 控制中心 + +这些扩展功能有的包含在社区版本的 Confluent 中，有的只有企业版能用。 +![TDengine Database Kafka Connector -- Confluent introduction](kafka/confluentPlatform.webp) + +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/java/ target/components/packages/taosdata-kafka-connect-tdengine-*.zip +``` + +以上脚本先 clone 项目源码，然后用 Maven 编译打包。打包完成后在 `target/components/packages/` 目录生成了插件的 zip 包。把这个 zip 包解压到安装插件的路径即可。上面的示例中使用了内置的插件安装路径： `$CONFLUENT_HOME/share/java/`。 + +### 用 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, 否则加载插件会失败。 +::: + +:::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`。 +::: + +### 验证各个组件是否启动成功 + +输入命令： + +``` +confluent local services status +``` + +如果各组件都启动成功，会得到如下输出： + +``` +Connect is [UP] +Control Center is [UP] +Kafka is [UP] +Kafka REST is [UP] +ksqlDB Server is [UP] +Schema Registry is [UP] +ZooKeeper is [UP] +``` + +### 验证插件是否安装成功 + +在 Kafka Connect 组件完全启动后，可用以下命令列出成功加载的插件： + +``` +confluent local services connect plugin list +``` + +如果成功安装，会输出如下： + +```txt {4,9} +Available Connect Plugins: +[ + { + "class": "com.taosdata.kafka.connect.sink.TDengineSinkConnector", + "type": "sink", + "version": "1.0.0" + }, + { + "class": "com.taosdata.kafka.connect.source.TDengineSourceConnector", + "type": "source", + "version": "1.0.0" + }, +...... +``` + +如果插件安装失败，请检查 Kafka Connect 的启动日志是否有异常信息，用以下命令输出日志路径： +``` +echo `cat /tmp/confluent.current`/connect/connect.stdout +``` +该命令的输出类似： `/tmp/confluent.104086/connect/connect.stdout`。 + +与日志文件 `connect.stdout` 同一目录，还有一个文件名为： `connect.properties`。在这个文件的末尾，可以看到最终生效的 `plugin.path`， 它是一系列用逗号分割的路径。如果插件安装失败，很可能是因为实际的安装路径不包含在 `plugin.path` 中。 + + +## 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=TDengineSinkConnector +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 +data.precision=ns +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", + "data.precision": "ns", + "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=California.LosAngeles,groupid=2 current=11.8,voltage=221,phase=0.28 1648432611249000000 +meters,location=California.LosAngeles,groupid=2 current=13.4,voltage=223,phase=0.29 1648432611250000000 +meters,location=California.LosAngeles,groupid=3 current=10.8,voltage=223,phase=0.29 1648432611249000000 +meters,location=California.LosAngeles,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 | California.LosAngeles | + 2022-03-28 09:56:51.250000000 | 13.400000000 | 223.000000000 | 0.290000000 | 2 | California.LosAngeles | + 2022-03-28 09:56:51.249000000 | 10.800000000 | 223.000000000 | 0.290000000 | 3 | California.LosAngeles | + 2022-03-28 09:56:51.250000000 | 11.300000000 | 221.000000000 | 0.350000000 | 3 | California.LosAngeles | +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(California.SanFrancisco, 2) VALUES('2018-10-03 14:38:05.000',10.30000,219,0.31000) d1001 USING meters TAGS(California.SanFrancisco, 2) VALUES('2018-10-03 14:38:15.000',12.60000,218,0.33000) d1001 USING meters TAGS(California.SanFrancisco, 2) VALUES('2018-10-03 14:38:16.800',12.30000,221,0.31000) d1002 USING meters TAGS(California.SanFrancisco, 3) VALUES('2018-10-03 14:38:16.650',10.30000,218,0.25000) d1003 USING meters TAGS(California.LosAngeles, 2) VALUES('2018-10-03 14:38:05.500',11.80000,221,0.28000) d1003 USING meters TAGS(California.LosAngeles, 2) VALUES('2018-10-03 14:38:16.600',13.40000,223,0.29000) d1004 USING meters TAGS(California.LosAngeles, 3) VALUES('2018-10-03 14:38:05.000',10.80000,223,0.29000) d1004 USING meters TAGS(California.LosAngeles, 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="California.SanFrancisco",groupid=2i32 current=10.3f32,voltage=219i32,phase=0.31f32 1538548685000000000 +meters,location="California.SanFrancisco",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`: 数据格式，可选值为： + 1. line ：代表 InfluxDB 行协议格式 + 2. json : 代表 OpenTSDB JSON 格式 + 3. telnet ：代表 OpenTSDB Telnet 行协议格式 +7. `data.precision`: 使用 InfluxDB 行协议格式时，时间戳的精度。可选值为： + 1. ms ： 表示毫秒 + 2. us ： 表示微秒 + 3. ns ： 表示纳秒。默认为纳秒。 + +### 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。 + +## 其他说明 + +1. 插件的安装位置可以自定义，请参考官方文档：https://docs.confluent.io/home/connect/self-managed/install.html#install-connector-manually。 +2. 本教程的示例程序使用了 Confluent 平台，但是 TDengine Kafka Connector 本身同样适用于独立安装的 Kafka, 且配置方法相同。关于如何在独立安装的 Kafka 环境使用 Kafka Connect 插件， 请参考官方文档： https://kafka.apache.org/documentation/#connect。 + +## 问题反馈 + +无论遇到任何问题，都欢迎在本项目的 Github 仓库反馈： 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/zh/20-third-party/_category_.yml b/docs/zh/20-third-party/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..514d8c19a878d9700bf11cd7f25208278dfa902e --- /dev/null +++ b/docs/zh/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/zh/20-third-party/_deploytaosadapter.mdx similarity index 100% rename from docs-cn/20-third-party/_deploytaosadapter.mdx rename to docs/zh/20-third-party/_deploytaosadapter.mdx diff --git a/docs/zh/20-third-party/add_datasource1.webp b/docs/zh/20-third-party/add_datasource1.webp new file mode 100644 index 0000000000000000000000000000000000000000..211edc4457abd0db6b0ef64636d61d65b5f43db6 Binary files /dev/null and b/docs/zh/20-third-party/add_datasource1.webp differ diff --git a/docs/zh/20-third-party/add_datasource2.webp b/docs/zh/20-third-party/add_datasource2.webp new file mode 100644 index 0000000000000000000000000000000000000000..8ab547231fee4d3b0874fcfe08c0ce152b0c53a1 Binary files /dev/null and b/docs/zh/20-third-party/add_datasource2.webp differ diff --git a/docs/zh/20-third-party/add_datasource3.webp b/docs/zh/20-third-party/add_datasource3.webp new file mode 100644 index 0000000000000000000000000000000000000000..d8a733360a09b4425c571f254a9ecb298c04b72f Binary files /dev/null and b/docs/zh/20-third-party/add_datasource3.webp differ diff --git a/docs/zh/20-third-party/add_datasource4.webp b/docs/zh/20-third-party/add_datasource4.webp new file mode 100644 index 0000000000000000000000000000000000000000..b1e0fc6e2b27df4af1bb5ad92756bcb5d4fda63e Binary files /dev/null and b/docs/zh/20-third-party/add_datasource4.webp differ diff --git a/docs/zh/20-third-party/create_dashboard1.webp b/docs/zh/20-third-party/create_dashboard1.webp new file mode 100644 index 0000000000000000000000000000000000000000..55eb388833e4df2a46f4d1cf6d346aa11429385d Binary files /dev/null and b/docs/zh/20-third-party/create_dashboard1.webp differ diff --git a/docs/zh/20-third-party/create_dashboard2.webp b/docs/zh/20-third-party/create_dashboard2.webp new file mode 100644 index 0000000000000000000000000000000000000000..bb40e407187718c52e9f617d8ebd3d25fd14b56b Binary files /dev/null and b/docs/zh/20-third-party/create_dashboard2.webp differ diff --git a/docs/zh/20-third-party/dashboard-15146.webp b/docs/zh/20-third-party/dashboard-15146.webp new file mode 100644 index 0000000000000000000000000000000000000000..fae586f5c74317621002416b2824830a7bdf3982 Binary files /dev/null and b/docs/zh/20-third-party/dashboard-15146.webp differ diff --git a/docs/zh/20-third-party/emqx/add-action-handler.webp b/docs/zh/20-third-party/emqx/add-action-handler.webp new file mode 100644 index 0000000000000000000000000000000000000000..4a8d105f711991226cfbd43b6e9ab07d7ccc686a Binary files /dev/null and b/docs/zh/20-third-party/emqx/add-action-handler.webp differ diff --git a/docs/zh/20-third-party/emqx/check-result-in-taos.webp b/docs/zh/20-third-party/emqx/check-result-in-taos.webp new file mode 100644 index 0000000000000000000000000000000000000000..8fa040a86104fece02ddaf8986f0a67de316143d Binary files /dev/null and b/docs/zh/20-third-party/emqx/check-result-in-taos.webp differ diff --git a/docs/zh/20-third-party/emqx/check-rule-matched.webp b/docs/zh/20-third-party/emqx/check-rule-matched.webp new file mode 100644 index 0000000000000000000000000000000000000000..e5a614035739df859b27c817f3b9f41be444b513 Binary files /dev/null and b/docs/zh/20-third-party/emqx/check-rule-matched.webp differ diff --git a/docs/zh/20-third-party/emqx/client-num.webp b/docs/zh/20-third-party/emqx/client-num.webp new file mode 100644 index 0000000000000000000000000000000000000000..a151b184843607d67b649babb3145bfb3e329cda Binary files /dev/null and b/docs/zh/20-third-party/emqx/client-num.webp differ diff --git a/docs/zh/20-third-party/emqx/create-resource.webp b/docs/zh/20-third-party/emqx/create-resource.webp new file mode 100644 index 0000000000000000000000000000000000000000..bf9cccbe49c57f925c5e6b094a4c0d88a64242cb Binary files /dev/null and b/docs/zh/20-third-party/emqx/create-resource.webp differ diff --git a/docs/zh/20-third-party/emqx/create-rule.webp b/docs/zh/20-third-party/emqx/create-rule.webp new file mode 100644 index 0000000000000000000000000000000000000000..13e8fc83d48d2fd9d0a303c707ef3024d3ee5203 Binary files /dev/null and b/docs/zh/20-third-party/emqx/create-rule.webp differ diff --git a/docs/zh/20-third-party/emqx/edit-action.webp b/docs/zh/20-third-party/emqx/edit-action.webp new file mode 100644 index 0000000000000000000000000000000000000000..7f6d2e36a82b1917930e5d3969115db9359674a0 Binary files /dev/null and b/docs/zh/20-third-party/emqx/edit-action.webp differ diff --git a/docs/zh/20-third-party/emqx/edit-resource.webp b/docs/zh/20-third-party/emqx/edit-resource.webp new file mode 100644 index 0000000000000000000000000000000000000000..fd5d278fab16bba4e04e1c348d4086dce77abb98 Binary files /dev/null and b/docs/zh/20-third-party/emqx/edit-resource.webp differ diff --git a/docs/zh/20-third-party/emqx/login-dashboard.webp b/docs/zh/20-third-party/emqx/login-dashboard.webp new file mode 100644 index 0000000000000000000000000000000000000000..f84cee668fb6efe1586515ba0dee3ae2f10a5b30 Binary files /dev/null and b/docs/zh/20-third-party/emqx/login-dashboard.webp differ diff --git a/docs/zh/20-third-party/emqx/rule-engine.webp b/docs/zh/20-third-party/emqx/rule-engine.webp new file mode 100644 index 0000000000000000000000000000000000000000..c1711c8cc757cd73fef5cb941a1818756241f7f0 Binary files /dev/null and b/docs/zh/20-third-party/emqx/rule-engine.webp differ diff --git a/docs/zh/20-third-party/emqx/rule-header-key-value.webp b/docs/zh/20-third-party/emqx/rule-header-key-value.webp new file mode 100644 index 0000000000000000000000000000000000000000..e645b3822dffec86f4926e78a57eaffa1e7f4d8d Binary files /dev/null and b/docs/zh/20-third-party/emqx/rule-header-key-value.webp differ diff --git a/docs/zh/20-third-party/emqx/run-mock.webp b/docs/zh/20-third-party/emqx/run-mock.webp new file mode 100644 index 0000000000000000000000000000000000000000..ed33f1666d456f1ab40ed6830af4550d4c7ca037 Binary files /dev/null and b/docs/zh/20-third-party/emqx/run-mock.webp differ diff --git a/docs/zh/20-third-party/import_dashboard1.webp b/docs/zh/20-third-party/import_dashboard1.webp new file mode 100644 index 0000000000000000000000000000000000000000..d4fb374ce8bb75c8a0fbdbb9cab5b30eb29ab06d Binary files /dev/null and b/docs/zh/20-third-party/import_dashboard1.webp differ diff --git a/docs/zh/20-third-party/import_dashboard2.webp b/docs/zh/20-third-party/import_dashboard2.webp new file mode 100644 index 0000000000000000000000000000000000000000..9f74dc96be20ab64b5fb555aaccdaa1c1139b35c Binary files /dev/null and b/docs/zh/20-third-party/import_dashboard2.webp differ diff --git a/docs/zh/20-third-party/index.md b/docs/zh/20-third-party/index.md new file mode 100644 index 0000000000000000000000000000000000000000..b493203225c89944759a216f2b75e0afa6ad03ba --- /dev/null +++ b/docs/zh/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/zh/20-third-party/kafka/Kafka_Connect.webp b/docs/zh/20-third-party/kafka/Kafka_Connect.webp new file mode 100644 index 0000000000000000000000000000000000000000..8f2000a749b0a2ccec9939abd144c53c44fbe171 Binary files /dev/null and b/docs/zh/20-third-party/kafka/Kafka_Connect.webp differ diff --git a/docs/zh/20-third-party/kafka/confluentPlatform.webp b/docs/zh/20-third-party/kafka/confluentPlatform.webp new file mode 100644 index 0000000000000000000000000000000000000000..ff03d4e51aaaec85f07ff41ecda0fb9bd6cb2847 Binary files /dev/null and b/docs/zh/20-third-party/kafka/confluentPlatform.webp differ diff --git a/docs/zh/20-third-party/kafka/streaming-integration-with-kafka-connect.webp b/docs/zh/20-third-party/kafka/streaming-integration-with-kafka-connect.webp new file mode 100644 index 0000000000000000000000000000000000000000..120d534ec132cea2ccef6cf87a3ce680a5ac6e9c Binary files /dev/null and b/docs/zh/20-third-party/kafka/streaming-integration-with-kafka-connect.webp differ diff --git a/docs/zh/21-tdinternal/01-arch.md b/docs/zh/21-tdinternal/01-arch.md new file mode 100644 index 0000000000000000000000000000000000000000..433cb4808b60ce73c639a23beef45fb8e1afb7dd --- /dev/null +++ b/docs/zh/21-tdinternal/01-arch.md @@ -0,0 +1,302 @@ +--- +sidebar_label: 整体架构 +title: 整体架构 +--- + +## 集群与基本逻辑单元 + +TDengine 的设计是基于单个硬件、软件系统不可靠，基于任何单台计算机都无法提供足够计算能力和存储能力处理海量数据的假设进行设计的。因此 TDengine 从研发的第一天起，就按照分布式高可靠架构进行设计，是支持水平扩展的，这样任何单台或多台服务器发生硬件故障或软件错误都不影响系统的可用性和可靠性。同时，通过节点虚拟化并辅以自动化负载均衡技术，TDengine 能最高效率地利用异构集群中的计算和存储资源降低硬件投资。 + +### 主要逻辑单元 + +TDengine 分布式架构的逻辑结构图如下： + +![TDengine Database 架构示意图](./structure.webp) + +
图 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 端口。确保集群中所有主机在端口 6030-6042 上的 TCP/UDP 协议能够互通。详细的端口情况请参见 [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 Database 典型的操作流程](./message.webp) + +
图 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 Database Master写入流程](./write_master.webp) + +
图 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 Database Slave 写入流程](./write_slave.webp) + +
图 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 下的全部或部分表进行聚合或统计操作，这样大大简化应用的开发。其具体流程如下图所示： + +![TDengine Database 多表聚合查询原理图](./multi_tables.webp) + +
图 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/zh/21-tdinternal/02-replica.md b/docs/zh/21-tdinternal/02-replica.md new file mode 100644 index 0000000000000000000000000000000000000000..25d1edab6e9b97be13c8675491cc90ed54520865 --- /dev/null +++ b/docs/zh/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)。 + +具体的流程图如下： + +![TDengine Database replica master](./replica-master.webp) + +选择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收到写的请求后，遵循下面的流程： + +![TDengine Database replica forward](./replica-forward.webp) + +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。具体流程如下： + +![TDengine Database replica restore](./replica-restore.webp) + +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/zh/21-tdinternal/03-taosd.md b/docs/zh/21-tdinternal/03-taosd.md new file mode 100644 index 0000000000000000000000000000000000000000..0cf0a1aaa222e82f7ca6cc4f0314aa5a50442924 --- /dev/null +++ b/docs/zh/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 等模块，具体如下图： + +![TDengine Database module](./modules.webp) + +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 通过读写线程池进行控制，是系统的中枢。该模块内的结构体图如下： + +![TDengine Database dnode](./dnode.webp) + +## VNODE 模块 + +vnode 是一独立的数据存储查询逻辑单元，但因为一个 vnode 只能容许一个 DB ，因此 vnode 内部没有 account，DB，user 等概念。为实现更好的模块化、封装以及未来的扩展，它有很多子模块，包括负责存储的 TSDB，负责查询的 query，负责数据复制的 sync，负责数据库日志的的 WAL，负责连续查询的 cq（continuous query），负责事件触发的流计算的 event 等模块，这些子模块只与 vnode 模块发生关系，与其他模块没有任何调用关系。模块图如下： + +![TDengine Database vnode](./vnode.webp) + +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/zh/21-tdinternal/12-tsz-compress.md similarity index 100% rename from docs-cn/21-tdinternal/12-tsz-compress.md rename to docs/zh/21-tdinternal/12-tsz-compress.md diff --git a/docs-cn/21-tdinternal/30-iot-big-data.md b/docs/zh/21-tdinternal/30-iot-big-data.md similarity index 100% rename from docs-cn/21-tdinternal/30-iot-big-data.md rename to docs/zh/21-tdinternal/30-iot-big-data.md diff --git a/docs/zh/21-tdinternal/_category_.yml b/docs/zh/21-tdinternal/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..c7509bf66224fa94759de9a2ae82955e2a7eb82f --- /dev/null +++ b/docs/zh/21-tdinternal/_category_.yml @@ -0,0 +1 @@ +label: 技术内幕 \ No newline at end of file diff --git a/docs/zh/21-tdinternal/dnode.webp b/docs/zh/21-tdinternal/dnode.webp new file mode 100644 index 0000000000000000000000000000000000000000..a56c7e4594df00a721cb48381d68ca3bc813cdc8 Binary files /dev/null and b/docs/zh/21-tdinternal/dnode.webp differ diff --git a/docs/zh/21-tdinternal/index.md b/docs/zh/21-tdinternal/index.md new file mode 100644 index 0000000000000000000000000000000000000000..63a746623e0dd955f61ba887a76f8ecf7eb16972 --- /dev/null +++ b/docs/zh/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/zh/21-tdinternal/message.webp b/docs/zh/21-tdinternal/message.webp new file mode 100644 index 0000000000000000000000000000000000000000..a2a42abff3d6e932b41a3abe9feae4a5cc13c9e5 Binary files /dev/null and b/docs/zh/21-tdinternal/message.webp differ diff --git a/docs/zh/21-tdinternal/modules.webp b/docs/zh/21-tdinternal/modules.webp new file mode 100644 index 0000000000000000000000000000000000000000..718a6abccdbe40d4a0df5e3812fe0ab943a7c523 Binary files /dev/null and b/docs/zh/21-tdinternal/modules.webp differ diff --git a/docs/zh/21-tdinternal/multi_tables.webp b/docs/zh/21-tdinternal/multi_tables.webp new file mode 100644 index 0000000000000000000000000000000000000000..8f649e34a3a62d1b11b4403b2e743ff6b5e47be2 Binary files /dev/null and b/docs/zh/21-tdinternal/multi_tables.webp differ diff --git a/docs/zh/21-tdinternal/replica-forward.webp b/docs/zh/21-tdinternal/replica-forward.webp new file mode 100644 index 0000000000000000000000000000000000000000..512efd4eba8f23ad0f8607eaaf5525f51ecdcf0e Binary files /dev/null and b/docs/zh/21-tdinternal/replica-forward.webp differ diff --git a/docs/zh/21-tdinternal/replica-master.webp b/docs/zh/21-tdinternal/replica-master.webp new file mode 100644 index 0000000000000000000000000000000000000000..57030a11f563af2689dbcfd206183f410b121aee Binary files /dev/null and b/docs/zh/21-tdinternal/replica-master.webp differ diff --git a/docs/zh/21-tdinternal/replica-restore.webp b/docs/zh/21-tdinternal/replica-restore.webp new file mode 100644 index 0000000000000000000000000000000000000000..f282c2d4d23f517e3ef08e906cea7e9c5edc0b2a Binary files /dev/null and b/docs/zh/21-tdinternal/replica-restore.webp differ diff --git a/docs/zh/21-tdinternal/structure.webp b/docs/zh/21-tdinternal/structure.webp new file mode 100644 index 0000000000000000000000000000000000000000..b77a42c074b15302b5c3ab889fb550a46dd549b3 Binary files /dev/null and b/docs/zh/21-tdinternal/structure.webp differ diff --git a/docs/zh/21-tdinternal/vnode.webp b/docs/zh/21-tdinternal/vnode.webp new file mode 100644 index 0000000000000000000000000000000000000000..fae3104c89c542c26790b509d12ad56661082c32 Binary files /dev/null and b/docs/zh/21-tdinternal/vnode.webp differ diff --git a/docs/zh/21-tdinternal/write_master.webp b/docs/zh/21-tdinternal/write_master.webp new file mode 100644 index 0000000000000000000000000000000000000000..9624036ed3d46ed60924ead9ce5c61acee0f4652 Binary files /dev/null and b/docs/zh/21-tdinternal/write_master.webp differ diff --git a/docs/zh/21-tdinternal/write_slave.webp b/docs/zh/21-tdinternal/write_slave.webp new file mode 100644 index 0000000000000000000000000000000000000000..7c45dec11b00e6a738de458f9e1bedacfad75a96 Binary files /dev/null and b/docs/zh/21-tdinternal/write_slave.webp differ diff --git a/docs/zh/25-application/01-telegraf.md b/docs/zh/25-application/01-telegraf.md new file mode 100644 index 0000000000000000000000000000000000000000..95df8699ef85b02d6e9dba398c787644fc9089b2 --- /dev/null +++ b/docs/zh/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 运维系统。架构如下图： + +![TDengine Database IT-DevOps-Solutions-Telegraf](./IT-DevOps-Solutions-Telegraf.webp) + +## 安装步骤 + +### 安装 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 文件后导入。之后可以看到如下界面的仪表盘： + +![TDengine Database IT-DevOps-Solutions-telegraf-dashboard](./IT-DevOps-Solutions-telegraf-dashboard.webp) + +## 总结 + +以上演示如何快速搭建一个完整的 IT 运维展示系统。得力于 TDengine 2.4.0.0 版本中新增的 schemaless 协议解析功能，以及强大的生态软件适配能力，用户可以短短数分钟就可以搭建一个高效易用的 IT 运维系统。TDengine 强大的数据写入查询性能和其他丰富功能请参考官方文档和产品落地案例。 diff --git a/docs/zh/25-application/02-collectd.md b/docs/zh/25-application/02-collectd.md new file mode 100644 index 0000000000000000000000000000000000000000..78c61bb969092d7040ddcb3d02ce7bd29a784858 --- /dev/null +++ b/docs/zh/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 运维系统。架构如下图： + +![TDengine Database IT-DevOps-Solutions-Collectd-StatsD](./IT-DevOps-Solutions-Collectd-StatsD.webp) + +## 安装步骤 + +安装 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 文件导入。之后可以看到如下界面的仪表盘： + +![TDengine Database IT-DevOps-Solutions-collectd-dashboard](./IT-DevOps-Solutions-collectd-dashboard.webp) + +#### 导入 StatsD 仪表盘 + +从 `https://github.com/taosdata/grafanaplugin/blob/master/examples/statsd/dashboards/statsd-with-tdengine-v0.1.0.json` 下载 dashboard json 文件，点击左侧加号图标并选择 `Import`，按照界面提示导入 JSON 文件。之后可以看到如下界面的仪表盘： +![TDengine Database IT-DevOps-Solutions-statsd-dashboard](./IT-DevOps-Solutions-statsd-dashboard.webp) + +## 总结 + +TDengine 作为新兴的时序大数据平台，具备极强的高性能、高可靠、易管理、易维护的优势。得力于 TDengine 2.4.0.0 版本中新增的 schemaless 协议解析功能，以及强大的生态软件适配能力，用户可以短短数分钟就可以搭建一个高效易用的 IT 运维系统或者适配一个已存在的系统。 + +TDengine 强大的数据写入查询性能和其他丰富功能请参考官方文档和产品成功落地案例。 diff --git a/docs/zh/25-application/03-immigrate.md b/docs/zh/25-application/03-immigrate.md new file mode 100644 index 0000000000000000000000000000000000000000..9d8946bc4a69639c5327ac1ffb6c0539ddbd0e63 --- /dev/null +++ b/docs/zh/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 场景中典型架构** +![TDengine Database IT-DevOps-Solutions-Immigrate-OpenTSDB-Arch](./IT-DevOps-Solutions-Immigrate-OpenTSDB-Arch.webp "图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 模板** +![TDengine Database IT-DevOps-Solutions-Immigrate-OpenTSDB-Dashboard](./IT-DevOps-Solutions-Immigrate-OpenTSDB-Dashboard.webp "图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. 迁移完成后的系统架构** +![TDengine Database IT-DevOps-Solutions-Immigrate-TDengine-Arch](./IT-DevOps-Solutions-Immigrate-TDengine-Arch.webp "图 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/zh/25-application/IT-DevOps-Solutions-Collectd-StatsD.webp b/docs/zh/25-application/IT-DevOps-Solutions-Collectd-StatsD.webp new file mode 100644 index 0000000000000000000000000000000000000000..147a65b17bff2aa0e44faa206618bdce5664e1ca Binary files /dev/null and b/docs/zh/25-application/IT-DevOps-Solutions-Collectd-StatsD.webp differ diff --git a/docs/zh/25-application/IT-DevOps-Solutions-Immigrate-OpenTSDB-Arch.webp b/docs/zh/25-application/IT-DevOps-Solutions-Immigrate-OpenTSDB-Arch.webp new file mode 100644 index 0000000000000000000000000000000000000000..3ca99c835b33df8845adf1b52d8fb8eb63076e82 Binary files /dev/null and b/docs/zh/25-application/IT-DevOps-Solutions-Immigrate-OpenTSDB-Arch.webp differ diff --git a/docs/zh/25-application/IT-DevOps-Solutions-Immigrate-OpenTSDB-Dashboard.webp b/docs/zh/25-application/IT-DevOps-Solutions-Immigrate-OpenTSDB-Dashboard.webp new file mode 100644 index 0000000000000000000000000000000000000000..04811f61b9b318e129552d87cd48eabf6e99feab Binary files /dev/null and b/docs/zh/25-application/IT-DevOps-Solutions-Immigrate-OpenTSDB-Dashboard.webp differ diff --git a/docs/zh/25-application/IT-DevOps-Solutions-Immigrate-TDengine-Arch.webp b/docs/zh/25-application/IT-DevOps-Solutions-Immigrate-TDengine-Arch.webp new file mode 100644 index 0000000000000000000000000000000000000000..36930068758556f4de5b58321804a96401c64b22 Binary files /dev/null and b/docs/zh/25-application/IT-DevOps-Solutions-Immigrate-TDengine-Arch.webp differ diff --git a/docs/zh/25-application/IT-DevOps-Solutions-Telegraf.webp b/docs/zh/25-application/IT-DevOps-Solutions-Telegraf.webp new file mode 100644 index 0000000000000000000000000000000000000000..fd5461ec9b37be66cac4c17fb1f81fec76158330 Binary files /dev/null and b/docs/zh/25-application/IT-DevOps-Solutions-Telegraf.webp differ diff --git a/docs/zh/25-application/IT-DevOps-Solutions-collectd-dashboard.webp b/docs/zh/25-application/IT-DevOps-Solutions-collectd-dashboard.webp new file mode 100644 index 0000000000000000000000000000000000000000..879c27a1a5843c714ff3c33c1dccfa32a2154b82 Binary files /dev/null and b/docs/zh/25-application/IT-DevOps-Solutions-collectd-dashboard.webp differ diff --git a/docs/zh/25-application/IT-DevOps-Solutions-statsd-dashboard.webp b/docs/zh/25-application/IT-DevOps-Solutions-statsd-dashboard.webp new file mode 100644 index 0000000000000000000000000000000000000000..1d4c655970b5f3fcb3be2d65d67eb42f08f35862 Binary files /dev/null and b/docs/zh/25-application/IT-DevOps-Solutions-statsd-dashboard.webp differ diff --git a/docs/zh/25-application/IT-DevOps-Solutions-telegraf-dashboard.webp b/docs/zh/25-application/IT-DevOps-Solutions-telegraf-dashboard.webp new file mode 100644 index 0000000000000000000000000000000000000000..105afcdb8312b23675f62ff6339d5e737b5cd958 Binary files /dev/null and b/docs/zh/25-application/IT-DevOps-Solutions-telegraf-dashboard.webp differ diff --git a/docs/zh/25-application/_category_.yml b/docs/zh/25-application/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..f43a4601b6c269822cbc0de1b7ed99dfdc70cfe5 --- /dev/null +++ b/docs/zh/25-application/_category_.yml @@ -0,0 +1 @@ +label: 应用实践 diff --git a/docs/zh/25-application/index.md b/docs/zh/25-application/index.md new file mode 100644 index 0000000000000000000000000000000000000000..1305cf230f78b68f988918921540a1df05f0931f --- /dev/null +++ b/docs/zh/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/zh/27-train-faq/01-faq.md b/docs/zh/27-train-faq/01-faq.md new file mode 100644 index 0000000000000000000000000000000000000000..9d80df8baaf04a13d39f5f60e195a692bb943df8 --- /dev/null +++ b/docs/zh/27-train-faq/01-faq.md @@ -0,0 +1,236 @@ +--- +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），确保集群中所有主机在端口 6030-6042 上的 TCP/UDP 协议能够互通。 + +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 命令 Test-NetConnection -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. Windows 系统下客户端无法正常显示中文字符？ + +Windows 系统中一般是采用 GBK/GB18030 存储中文字符，而 TDengine 的默认字符集为 UTF-8 ，在 Windows 系统中使用 TDengine 客户端时，客户端驱动会将字符统一转换为 UTF-8 编码后发送到服务端存储，因此在应用开发过程中，调用接口时正确配置当前的中文字符集即可。 + +【 v2.2.1.5以后版本 】在 Windows 10 环境下运行 TDengine 客户端命令行工具 taos 时，若无法正常输入、显示中文，可以对客户端 taos.cfg 做如下配置： + +``` +locale C +charset UTF-8 +``` + +### 14. JDBC 报错： the executed SQL is not a DML or a DDL？ + +请更新至最新的 JDBC 驱动，参考 [Java 连接器](/reference/connector/java) + +### 15. taos connect failed, reason: invalid timestamp + +常见原因是服务器和客户端时间没有校准，可以通过和时间服务器同步的方式（Linux 下使用 ntpdate 命令，Windows 在系统时间设置中选择自动同步）校准。 + +### 16. 表名显示不全 + +由于 taos shell 在终端中显示宽度有限，有可能比较长的表名显示不全，如果按照显示的不全的表名进行相关操作会发生 Table does not exist 错误。解决方法可以是通过修改 taos.cfg 文件中的设置项 maxBinaryDisplayWidth， 或者直接输入命令 set max_binary_display_width 100。或者在命令结尾使用 \G 参数来调整结果的显示方式。 + +### 17. 如何进行数据迁移？ + +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 版本的存储结构不兼容，需要使用迁移工具或者自己开发应用导出导入数据。 + +### 18. 如何在命令行程序 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; +``` + +其含义是，清空本机所有由客户端生成的日志文件。 + + + +### 19. 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。 + +### 20. 如何查询数据占用的存储空间大小？ + +默认情况下，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) + +### 21. 客户端连接串如何保证高可用？ + +请看为此问题撰写的 [技术博客](https://www.taosdata.com/blog/2021/04/16/2287.html) + +### 22. 时间戳的时区信息是怎样处理的？ + +TDengine 中时间戳的时区总是由客户端进行处理，而与服务端无关。具体来说，客户端会对 SQL 语句中的时间戳进行时区转换，转为 UTC 时区（即 Unix 时间戳——Unix Timestamp）再交由服务端进行写入和查询；在读取数据时，服务端也是采用 UTC 时区提供原始数据，客户端收到后再根据本地设置，把时间戳转换为本地系统所要求的时区进行显示。 + +客户端在处理时间戳字符串时，会采取如下逻辑： + +1. 在未做特殊设置的情况下，客户端默认使用所在操作系统的时区设置。 +2. 如果在 taos.cfg 中设置了 timezone 参数，则客户端会以这个配置文件中的设置为准。 +3. 如果在 C/C++/Java/Python 等各种编程语言的 Connector Driver 中，在建立数据库连接时显式指定了 timezone，那么会以这个指定的时区设置为准。例如 Java Connector 的 JDBC URL 中就有 timezone 参数。 +4. 在书写 SQL 语句时，也可以直接使用 Unix 时间戳（例如 `1554984068000`）或带有时区的时间戳字符串，也即以 RFC 3339 格式（例如 `2013-04-12T15:52:01.123+08:00`）或 ISO-8601 格式（例如 `2013-04-12T15:52:01.123+0800`）来书写时间戳，此时这些时间戳的取值将不再受其他时区设置的影响。 + +### 23. TDengine 2.0 都会用到哪些网络端口？ + +使用到的网络端口请看文档：[serverport](/reference/config/#serverport) + +需要注意，文档上列举的端口号都是以默认端口 6030 为前提进行说明，如果修改了配置文件中的设置，那么列举的端口都会随之出现变化，管理员可以参考上述的信息调整防火墙设置。 + +### 24. 为什么 RESTful 接口无响应、Grafana 无法添加 TDengine 为数据源、TDengineGUI 选了 6041 端口还是无法连接成功？？ + +taosAdapter 从 TDengine 2.4.0.0 版本开始成为 TDengine 服务端软件的组成部分，是 TDengine 集群和应用程序之间的桥梁和适配器。在此之前 RESTful 接口等功能是由 taosd 内置的 HTTP 服务提供的，而如今要实现上述功能需要执行：```systemctl start taosadapter``` 命令来启动 taosAdapter 服务。 + +需要说明的是，taosAdapter 的日志路径 path 需要单独配置，默认路径是 /var/log/taos ；日志等级 logLevel 有 8 个等级，默认等级是 info ，配置成 panic 可关闭日志输出。请注意操作系统 / 目录的空间大小，可通过命令行参数、环境变量或配置文件来修改配置，默认配置文件是 /etc/taos/taosadapter.toml 。 + +有关 taosAdapter 组件的详细介绍请看文档：[taosAdapter](https://docs.taosdata.com/reference/taosadapter/) + diff --git a/docs-cn/27-train-faq/02-video.mdx b/docs/zh/27-train-faq/02-video.mdx similarity index 100% rename from docs-cn/27-train-faq/02-video.mdx rename to docs/zh/27-train-faq/02-video.mdx diff --git a/docs/zh/27-train-faq/03-docker.md b/docs/zh/27-train-faq/03-docker.md new file mode 100644 index 0000000000000000000000000000000000000000..7791569b25e102b4634f0fb899fc0973cacc0aa1 --- /dev/null +++ b/docs/zh/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 被设置为 "California.SanFrancisco" 或者 "California.SanDieo"。 + + 最后共插入 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 | California.SanDieo | + 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/zh/27-train-faq/_category_.yml b/docs/zh/27-train-faq/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..16b32bc38fd3ef88313150cf89e32b15696fe7ff --- /dev/null +++ b/docs/zh/27-train-faq/_category_.yml @@ -0,0 +1 @@ +label: FAQ 及其他 diff --git a/docs/zh/27-train-faq/index.md b/docs/zh/27-train-faq/index.md new file mode 100644 index 0000000000000000000000000000000000000000..b42bff0288fc8ab59810a7d7121be28ddf781551 --- /dev/null +++ b/docs/zh/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/zh/30-release/02-2.6.md b/docs/zh/30-release/02-2.6.md new file mode 100644 index 0000000000000000000000000000000000000000..85b76d9999e211336b5859beab3fdfc7988f4fda --- /dev/null +++ b/docs/zh/30-release/02-2.6.md @@ -0,0 +1,9 @@ +--- +title: 2.6 +--- + +[2.6.0.4](https://github.com/taosdata/TDengine/releases/tag/ver-2.6.0.4) + +[2.6.0.1](https://github.com/taosdata/TDengine/releases/tag/ver-2.6.0.1) + +[2.6.0.0](https://github.com/taosdata/TDengine/releases/tag/ver-2.6.0.0) diff --git a/docs/zh/30-release/03-2.4.md b/docs/zh/30-release/03-2.4.md new file mode 100644 index 0000000000000000000000000000000000000000..62580b327a3bd5098e1b7f1162a1c398ac2a5eff --- /dev/null +++ b/docs/zh/30-release/03-2.4.md @@ -0,0 +1,29 @@ +--- +title: 2.4 +--- + +[2.4.0.26](https://github.com/taosdata/TDengine/releases/tag/ver-2.4.0.26) + +[2.4.0.25](https://github.com/taosdata/TDengine/releases/tag/ver-2.4.0.25) + +[2.4.0.24](https://github.com/taosdata/TDengine/releases/tag/ver-2.4.0.24) + +[2.4.0.20](https://github.com/taosdata/TDengine/releases/tag/ver-2.4.0.20) + +[2.4.0.18](https://github.com/taosdata/TDengine/releases/tag/ver-2.4.0.18) + +[2.4.0.16](https://github.com/taosdata/TDengine/releases/tag/ver-2.4.0.16) + +[2.4.0.14](https://github.com/taosdata/TDengine/releases/tag/ver-2.4.0.14) + +[2.4.0.12](https://github.com/taosdata/TDengine/releases/tag/ver-2.4.0.12) + +[2.4.0.10](https://github.com/taosdata/TDengine/releases/tag/ver-2.4.0.10) + +[2.4.0.7](https://github.com/taosdata/TDengine/releases/tag/ver-2.4.0.7) + +[2.4.0.5](https://github.com/taosdata/TDengine/releases/tag/ver-2.4.0.5) + +[2.4.0.4](https://github.com/taosdata/TDengine/releases/tag/ver-2.4.0.4) + +[2.4.0.0](https://github.com/taosdata/TDengine/releases/tag/ver-2.4.0.0) diff --git a/docs/zh/30-release/_category_.yml b/docs/zh/30-release/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..745709c561e56de77d3fc0a4da7fe77d96c0482b --- /dev/null +++ b/docs/zh/30-release/_category_.yml @@ -0,0 +1 @@ +label: 发布历史 diff --git a/docs/zh/30-release/index.md b/docs/zh/30-release/index.md new file mode 100644 index 0000000000000000000000000000000000000000..65fcf70acdf3747acfef13599a62db75e6b8758f --- /dev/null +++ b/docs/zh/30-release/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/zh/eco_system.webp b/docs/zh/eco_system.webp new file mode 100644 index 0000000000000000000000000000000000000000..d60c38e97c67fa7b2acc703b2ba777d19ae5be13 Binary files /dev/null and b/docs/zh/eco_system.webp differ diff --git a/documentation/tdenginedocs-cn/administrator/index.html b/documentation/tdenginedocs-cn/administrator/index.html deleted file mode 100644 index eaaf04ff95fa69cb3bae47d0e574c4f1931e7719..0000000000000000000000000000000000000000 --- a/documentation/tdenginedocs-cn/administrator/index.html +++ /dev/null @@ -1,137 +0,0 @@ -文档 | 涛思数据
回去

系统管理

-

文件目录结构

-

安装TDengine后，默认会在操作系统中生成下列目录或文件：

-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
目录/文件说明
/etc/taos/taos.cfgTDengine默认[配置文件]
/usr/local/taos/driverTDengine动态链接库目录
/var/lib/taosTDengine默认数据文件目录,可通过[配置文件]修改位置.
/var/log/taosTDengine默认日志文件目录,可通过[配置文件]修改位置
/usr/local/taos/binTDengine可执行文件目录
-

可执行文件

-

TDengine的所有可执行文件默认存放在 /usr/local/taos/bin 目录下。其中包括：

-
    -
  • taosd：TDengine服务端可执行文件
    • -
  • taos： TDengine Shell可执行文件
    • -
  • taosdump：数据导出工具
    • -
  • rmtaos： 一个卸载TDengine的脚本, 请谨慎执行
    • -
-

您可以通过修改系统配置文件taos.cfg来配置不同的数据目录和日志目录

-

服务端配置

-

TDengine系统后台服务由taosd提供，可以在配置文件taos.cfg里修改配置参数，以满足不同场景的需求。配置文件的缺省位置在/etc/taos目录，可以通过taosd命令行执行参数-c指定配置文件目录。比如taosd -c /home/user来指定配置文件位于/home/user这个目录。

-

下面仅仅列出一些重要的配置参数，更多的参数请看配置文件里的说明。各个参数的详细介绍及作用请看前述章节。注意：配置修改后，需要重启taosd服务才能生效。

-
    -
  • internalIp: 对外提供服务的IP地址，默认取第一个IP地址
    • -
  • mgmtShellPort：管理节点与客户端通信使用的TCP/UDP端口号（默认值是6030）。此端口号在内向后连续的5个端口都会被UDP通信占用，即UDP占用[6030-6034]，同时TCP通信也会使用端口[6030]。
    • -
  • vnodeShellPort：数据节点与客户端通信使用的TCP/UDP端口号（默认值是6035）。此端口号在内向后连续的5个端口都会被UDP通信占用，即UDP占用[6035-6039]，同时TCP通信也会使用端口[6035]
    • -
  • httpPort：数据节点对外提供RESTful服务使用TCP，端口号[6020]
    • -
  • dataDir: 数据文件目录，缺省是/var/lib/taos
    • -
  • maxUsers：用户的最大数量
    • -
  • maxDbs：数据库的最大数量
    • -
  • maxTables：数据表的最大数量
    • -
  • enableMonitor: 系统监测标志位，0：关闭，1：打开
    • -
  • logDir: 日志文件目录，缺省是/var/log/taos
    • -
  • numOfLogLines：日志文件的最大行数
    • -
  • debugFlag: 系统debug日志开关，131：仅错误和报警信息，135：调试信息，143：非常详细的调试信息
    • -
-

不同应用场景的数据往往具有不同的数据特征，比如保留天数、副本数、采集频次、记录大小、采集点的数量、压缩等都可完全不同。为获得在存储上的最高效率，TDengine提供如下存储相关的系统配置参数：

-
    -
  • days：一个数据文件覆盖的时间长度，单位为天
    • -
  • keep：数据库中数据保留的天数
    • -
  • rows: 文件块中记录条数
    • -
  • comp: 文件压缩标志位，0：关闭，1:一阶段压缩，2:两阶段压缩
    • -
  • ctime：数据从写入内存到写入硬盘的最长时间间隔，单位为秒
    • -
  • clog：数据提交日志(WAL)的标志位，0为关闭，1为打开
    • -
  • tables：每个vnode允许创建表的最大数目
    • -
  • cache: 内存块的大小（字节数）
    • -
  • tblocks: 每张表最大的内存块数
    • -
  • ablocks: 每张表平均的内存块数
    • -
  • precision：时间戳为微秒的标志位，ms表示毫秒，us表示微秒
    • -
-

对于一个应用场景，可能有多种数据特征的数据并存，最佳的设计是将具有相同数据特征的表放在一个库里，这样一个应用有多个库，而每个库可以配置不同的存储参数，从而保证系统有最优的性能。TDengine容许应用在创建库时指定上述存储参数，如果指定，该参数就将覆盖对应的系统配置参数。举例，有下述SQL：

-
 create database demo days 10 cache 16000 ablocks 4
-

该SQL创建了一个库demo, 每个数据文件保留10天数据，内存块为16000字节，每个表平均占用4个内存块，而其他参数与系统配置完全一致。

-

客户端配置

-

TDengine系统的前台交互客户端应用程序为taos，它与taosd共享同一个配置文件taos.cfg。运行taos时，使用参数-c指定配置文件目录，如taos -c /home/cfg，表示使用/home/cfg/目录下的taos.cfg配置文件中的参数，缺省目录是/etc/taos。更多taos的使用方法请见Shell命令行程序。本节主要讲解taos客户端应用在配置文件taos.cfg文件中使用到的参数。

-

客户端配置参数列表及解释

-
    -
  • masterIP：客户端默认发起请求的服务器的IP地址
    • -
  • charset：指明客户端所使用的字符集，默认值为UTF-8。TDengine存储nchar类型数据时使用的是unicode存储，因此客户端需要告知服务自己所使用的字符集，也即客户端所在系统的字符集。
    • -
  • locale：设置系统语言环境。Linux上客户端与服务端共享
    • -
  • defaultUser：默认登录用户，默认值root
    • -
  • defaultPass：默认登录密码，默认值taosdata
    • -
-

TCP/UDP端口，以及日志的配置参数，与server的配置参数完全一样。

-

启动taos时，你也可以从命令行指定IP地址、端口号，用户名和密码，否则就从taos.cfg读取。

-

用户管理

-

系统管理员可以在CLI界面里添加、删除用户，也可以修改密码。CLI里SQL语法如下：

-
CREATE USER user_name PASS ‘password’
-

创建用户，并制定用户名和密码，密码需要用单引号引起来

-
DROP USER user_name
-

删除用户，限root用户使用

-
ALTER USER user_name PASS ‘password’
-

修改用户密码, 为避免被转换为小写，密码需要用单引号引用

-
SHOW USERS
-

显示所有用户

-

数据导入

-

TDengine提供两种方便的数据导入功能，一种按脚本文件导入，一种按数据文件导入。

-

按脚本文件导入

-

TDengine的shell支持source filename命令，用于批量运行文件中的SQL语句。用户可将建库、建表、写数据等SQL命令写在同一个文件中，每条命令单独一行，在shell中运行source命令，即可按顺序批量运行文件中的SQL语句。以‘#’开头的SQL语句被认为是注释，shell将自动忽略。

-

按数据文件导入

-

TDengine也支持在shell对已存在的表从CSV文件中进行数据导入。每个CSV文件只属于一张表且CSV文件中的数据格式需与要导入表的结构相同。其语法如下

-
insert into tb1 file a.csv b.csv tb2 c.csv …
-import into tb1 file a.csv b.csv tb2 c.csv …
-

数据导出

-

为方便数据导出，TDengine提供了两种导出方式，分别是按表导出和用taosdump导出。

-

按表导出CSV文件

-

如果用户需要导出一个表或一个STable中的数据，可在shell中运行

-
select * from <tb_name> >> a.csv
-

这样，表tb中的数据就会按照CSV格式导出到文件a.csv中。

-

用taosdump导出数据

-

TDengine提供了方便的数据库导出工具taosdump。用户可以根据需要选择导出所有数据库、一个数据库或者数据库中的一张表,所有数据或一时间段的数据，甚至仅仅表的定义。其用法如下：

-
    -
  • 导出数据库中的一张或多张表：taosdump [OPTION…] dbname tbname …
    • -
  • 导出一个或多个数据库： taosdump [OPTION…] --databases dbname…
    • -
  • 导出所有数据库（不含监控数据库）：taosdump [OPTION…] --all-databases
    • -
-

用户可通过运行taosdump --help获得更详细的用法说明

-

系统连接、任务查询管理

-

系统管理员可以从CLI查询系统的连接、正在进行的查询、流式计算，并且可以关闭连接、停止正在进行的查询和流式计算。CLI里SQL语法如下：

-
SHOW CONNECTIONS
-

显示数据库的连接，其中一列显示ip:port, 为连接的IP地址和端口号。

-
KILL CONNECTION <connection-id>
-

强制关闭数据库连接，其中的connection-id是SHOW CONNECTIONS中显示的 ip:port字串，如“192.168.0.1:42198”，拷贝粘贴即可。

-
SHOW QUERIES
-

显示数据查询，其中一列显示ip:port:id, 为发起该query应用的IP地址，端口号，以及系统分配的ID。

-
KILL QUERY <query-id>
-

强制关闭数据查询，其中query-id是SHOW QUERIES中显示的ip:port:id字串，如“192.168.0.1:42198:11”，拷贝粘贴即可。

-
SHOW STREAMS
-

显示流式计算，其中一列显示ip:port:id, 为启动该stream的IP地址、端口和系统分配的ID。

-
KILL STREAM <stream-id>
-

强制关闭流式计算，其中的中stream-id是SHOW STREAMS中显示的ip:port:id字串，如“192.168.0.1:42198:18”，拷贝粘贴即可。

-

系统监控

-

TDengine启动后，会自动创建一个监测数据库SYS，并自动将服务器的CPU、内存、硬盘空间、带宽、请求数、磁盘读写速度、慢查询等信息定时写入该数据库。TDengine还将重要的系统操作（比如登录、创建、删除数据库等）日志以及各种错误报警信息记录下来存放在SYS库里。系统管理员可以从CLI直接查看这个数据库，也可以在WEB通过图形化界面查看这些监测信息。

-

这些监测信息的采集缺省是打开的，但可以修改配置文件里的选项enableMonitor将其关闭或打开。

回去
\ No newline at end of file diff --git a/documentation/tdenginedocs-cn/advanced-features/index.html b/documentation/tdenginedocs-cn/advanced-features/index.html deleted file mode 100644 index b4953b4dd482341ce937f56b806b682ff7145409..0000000000000000000000000000000000000000 --- a/documentation/tdenginedocs-cn/advanced-features/index.html +++ /dev/null @@ -1,64 +0,0 @@ -文档 | 涛思数据
回去

高级功能

-

连续查询(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可确保数据写回的有效性和连续性。

    • -
-

使用连续查询

-

使用TAOS SQL定义连续查询的过程，需要调用API taos_stream在应用端启动连续查询。例如要对统计表FOO_TABLE 每1分钟统计一次记录数量，前向滑动的时间是30秒，SQL语句如下：

-
SELECT COUNT(*) 
-FROM FOO_TABLE 
-INTERVAL(1M) SLIDING(30S)
-

其中查询的时间窗口（time window）是1分钟，前向增量（forward sliding time）时间是30秒。也可以不使用sliding来指定前向滑动时间，此时系统将自动向前滑动一个查询时间窗口再开始下一次计算，即时间窗口长度等于前向滑动时间。

-
SELECT COUNT(*) 
-FROM FOO_TABLE 
-INTERVAL(1M)
-

如果需要将连续查询的计算结果写回到数据库中，可以使用如下的SQL语句

-
CREATE TABLE QUERY_RES 
-  AS 
-  SELECT COUNT(*) 
-  FROM FOO_TABLE 
-  INTERVAL(1M) SLIDING(30S)
-

此时系统将自动创建表QUERY_RES，然后将连续查询的结果写入到该表。需要注意的是，前向滑动时间不能大于时间窗口的范围。如果用户指定的前向滑动时间超过时间窗口范围，系统将自动将其设置为时间窗口的范围值。如上所示SQL语句，如果用户设置前向滑动时间超过1分钟，系统将强制将其设置为1分钟。

-

此外，TDengine还支持用户指定连续查询的结束时间，默认如果不输入结束时间，连续查询将永久运行，如果用户指定了结束时间，连续查询在系统时间达到指定的时间以后停止运行。如SQL所示，连续查询将运行1个小时，1小时之后连续查询自动停止。

-
CREATE TABLE QUERY_RES 
-  AS 
-  SELECT COUNT(*) 
-  FROM FOO_TABLE 
-  WHERE TS > NOW AND TS <= NOW + 1H 
-  INTERVAL(1M) SLIDING(30S)
-

此外，还需要注意的是查询时间窗口的最小值是10毫秒，没有时间窗口范围的上限。

-

管理连续查询

-

用户可在控制台中通过 show streams 命令来查看系统中全部运行的连续查询，并可以通过 kill stream 命令杀掉对应的连续查询。在写回模式中，如果用户可以直接将写回的表删除，此时连续查询也会自动停止并关闭。后续版本会提供更细粒度和便捷的连续查询管理命令。

-

数据订阅(Publisher/Subscriber)

-

基于数据天然的时间序列特性，TDengine的数据写入（insert）与消息系统的数据发布（pub）逻辑上一致，均可视为系统中插入一条带时间戳的新记录。同时，TDengine在内部严格按照数据时间序列单调递增的方式保存数据。本质上来说，TDengine中里每一张表均可视为一个标准的消息队列。

-

TDengine内嵌支持轻量级的消息订阅与推送服务。使用系统提供的API，用户可订阅数据库中的某一张表（或超级表）。订阅的逻辑和操作状态的维护均是由客户端完成，客户端定时轮询服务器是否有新的记录到达，有新的记录到达就会将结果反馈到客户。

-

TDengine的订阅与推送服务的状态是客户端维持，TDengine服务器并不维持。因此如果应用重启，从哪个时间点开始获取最新数据，由应用决定。

-

API说明

-

使用订阅的功能，主要API如下：

-
    -

  • TAOS_SUB *taos_subscribe(char *host, char *user, char *pass, char *db, char *table, int64_t time, int mseconds)

    该函数负责启动订阅服务。其中参数说明：

      • -

    • host：主机IP地址

      • -

    • user：数据库登录用户名

      • -

    • pass：密码

      • -

    • db：数据库名称

      • -

    • table：(超级) 表的名称

      • -

    • time：启动时间，Unix Epoch时间，单位为毫秒。从1970年1月1日起计算的毫秒数。如果设为0，表示从当前时间开始订阅

      • -

    • mseconds：查询数据库更新的时间间隔，单位为毫秒。一般设置为1000毫秒。返回值为指向TDengine_SUB 结构的指针，如果返回为空，表示失败。

      • -

  • TAOS_ROW taos_consume(TAOS_SUB *tsub) -

    该函数用来获取订阅的结果，用户应用程序将其置于一个无限循环语句。如果数据库有新记录到达，该API将返回该最新的记录。如果没有新的记录，该API将阻塞。如果返回值为空，说明系统出错。参数说明：

    • tsub：taos_subscribe的结构体指针。

  • void taos_unsubscribe(TAOS_SUB *tsub)

    取消订阅。应用程序退出时，务必调用该函数以避免资源泄露。

    • -

  • int taos_num_fields(TAOS_SUB *tsub)

    获取返回的一行记录中数据包含多少列。

    • -

  • TAOS_FIELD *taos_fetch_fields(TAOS_SUB *tsub)

    获取每列数据的属性（数据类型、名字、长度），与taos_num_subfileds配合使用，可解析返回的每行数据。

-

示例代码：请看安装包中的的示范程序

-

缓存 (Cache)

-

TDengine采用时间驱动缓存管理策略（First-In-First-Out，FIFO），又称为写驱动的缓存管理机制。这种策略有别于读驱动的数据缓存模式（Least-Recent-Use，LRU），直接将最近写入的数据保存在系统的缓存中。当缓存达到临界值的时候，将最早的数据批量写入磁盘。一般意义上来说，对于物联网数据的使用，用户最为关心最近产生的数据，即当前状态。TDengine充分利用了这一特性，将最近到达的（当前状态）数据保存在缓存中。

-

TDengine通过查询函数向用户提供毫秒级的数据获取能力。直接将最近到达的数据保存在缓存中，可以更加快速地响应用户针对最近一条或一批数据的查询分析，整体上提供更快的数据库查询响应能力。从这个意义上来说，可通过设置合适的配置参数将TDengine作为数据缓存来使用，而不需要再部署额外的缓存系统，可有效地简化系统架构，降低运维的成本。需要注意的是，TDengine重启以后系统的缓存将被清空，之前缓存的数据均会被批量写入磁盘，缓存的数据将不会像专门的Key-value缓存系统再将之前缓存的数据重新加载到缓存中。

-

TDengine分配固定大小的内存空间作为缓存空间，缓存空间可根据应用的需求和硬件资源配置。通过适当的设置缓存空间，TDengine可以提供极高性能的写入和查询的支持。TDengine中每个虚拟节点（virtual node）创建时分配独立的缓存池。每个虚拟节点管理自己的缓存池，不同虚拟节点间不共享缓存池。每个虚拟节点内部所属的全部表共享该虚拟节点的缓存池。

-

一个缓存池了有很多个缓存块，缓存的大小由缓存块的个数以及缓存块的大小决定。参数cacheBlockSize决定每个缓存块的大小，参数cacheNumOfBlocks决定每个虚拟节点可用缓存块数量。因此单个虚拟节点总缓存开销为cacheBlockSize x cacheNumOfBlocks。参数numOfBlocksPerMeter决定每张表可用缓存块的数量，TDengine要求每张表至少有2个缓存块可供使用，因此cacheNumOfBlocks的数值不应该小于虚拟节点中所包含的表数量的两倍，即cacheNumOfBlocks ≤ sessionsPerVnode x 2。一般情况下cacheBlockSize可以不用调整，使用系统默认值即可，缓存块需要存储至少几十条记录才能确保TDengine更有效率地进行数据写入。

-

你可以通过函数last快速获取一张表或一张超级表的最后一条记录，这样很便于在大屏显示各设备的实时状态或采集值。例如：

-
select degree from thermometer where location='beijing';
-

该SQL语句将获取所有位于北京的传感器最后记录的温度值。

回去
\ No newline at end of file diff --git a/documentation/tdenginedocs-cn/assets/Picture2.png b/documentation/tdenginedocs-cn/assets/Picture2.png deleted file mode 100644 index 715a8bd37ee9fe7e96eacce4e7ff563fedeefbee..0000000000000000000000000000000000000000 Binary files a/documentation/tdenginedocs-cn/assets/Picture2.png and /dev/null differ diff --git a/documentation/tdenginedocs-cn/assets/clip_image001-2474914.png b/documentation/tdenginedocs-cn/assets/clip_image001-2474914.png deleted file mode 100644 index eb369b1567c860b772e1bfdad64ff17aaac2534d..0000000000000000000000000000000000000000 Binary files a/documentation/tdenginedocs-cn/assets/clip_image001-2474914.png and /dev/null differ diff --git a/documentation/tdenginedocs-cn/assets/clip_image001-2474939.png b/documentation/tdenginedocs-cn/assets/clip_image001-2474939.png deleted file mode 100644 index 53f00deea3a484986a5681ec9d00d8ae02e88fec..0000000000000000000000000000000000000000 Binary files a/documentation/tdenginedocs-cn/assets/clip_image001-2474939.png and /dev/null differ diff --git a/documentation/tdenginedocs-cn/assets/clip_image001-2474961.png b/documentation/tdenginedocs-cn/assets/clip_image001-2474961.png deleted file mode 100644 index 20ae8d6f7724a4bddcf8c7eb3809d468aa4223ed..0000000000000000000000000000000000000000 Binary files a/documentation/tdenginedocs-cn/assets/clip_image001-2474961.png and /dev/null differ diff --git a/documentation/tdenginedocs-cn/assets/clip_image001-2474987.png b/documentation/tdenginedocs-cn/assets/clip_image001-2474987.png deleted file mode 100644 index 3d09f7fc28e7a1fb7e3bb2b9b2bc7c20895e8bb4..0000000000000000000000000000000000000000 Binary files a/documentation/tdenginedocs-cn/assets/clip_image001-2474987.png and /dev/null differ diff --git a/documentation/tdenginedocs-cn/assets/clip_image001.png b/documentation/tdenginedocs-cn/assets/clip_image001.png deleted file mode 100644 index 78b6d06a9562b802e80f0ed5fdb8963b5e525589..0000000000000000000000000000000000000000 Binary files a/documentation/tdenginedocs-cn/assets/clip_image001.png and /dev/null differ diff --git a/documentation/tdenginedocs-cn/assets/fig1.png b/documentation/tdenginedocs-cn/assets/fig1.png deleted file mode 100644 index af9b74e0d1a872b8d93f71842dc0063bc8a86092..0000000000000000000000000000000000000000 Binary files a/documentation/tdenginedocs-cn/assets/fig1.png and /dev/null differ diff --git a/documentation/tdenginedocs-cn/assets/fig2.png b/documentation/tdenginedocs-cn/assets/fig2.png deleted file mode 100644 index 3bae70ba86964c3c341b72ea1d3af04201f7c6c1..0000000000000000000000000000000000000000 Binary files a/documentation/tdenginedocs-cn/assets/fig2.png and /dev/null differ diff --git a/documentation/tdenginedocs-cn/assets/image-20190707124650780.png b/documentation/tdenginedocs-cn/assets/image-20190707124650780.png deleted file mode 100644 index 9ebcac863e862d8b240c86dec29be1ebe7aa50f0..0000000000000000000000000000000000000000 Binary files a/documentation/tdenginedocs-cn/assets/image-20190707124650780.png and /dev/null differ diff --git a/documentation/tdenginedocs-cn/assets/image-20190707124818590.png b/documentation/tdenginedocs-cn/assets/image-20190707124818590.png deleted file mode 100644 index dc1cb6325b2d4cd6f05c88b75b4d17ef85caa67f..0000000000000000000000000000000000000000 Binary files a/documentation/tdenginedocs-cn/assets/image-20190707124818590.png and /dev/null differ diff --git a/documentation/tdenginedocs-cn/assets/nodes.png b/documentation/tdenginedocs-cn/assets/nodes.png deleted file mode 100644 index d4ae5120c29b8cfacdc543df5a2a7104d77a2a7b..0000000000000000000000000000000000000000 Binary files a/documentation/tdenginedocs-cn/assets/nodes.png and /dev/null differ diff --git a/documentation/tdenginedocs-cn/assets/structure.png b/documentation/tdenginedocs-cn/assets/structure.png deleted file mode 100644 index 801829b68580e1a46d0841a3d38e4885eb383991..0000000000000000000000000000000000000000 Binary files a/documentation/tdenginedocs-cn/assets/structure.png and /dev/null differ diff --git a/documentation/tdenginedocs-cn/assets/vnode.png b/documentation/tdenginedocs-cn/assets/vnode.png deleted file mode 100644 index 5247717f62118a8e690e80a3538c1a8dd1ab9416..0000000000000000000000000000000000000000 Binary files a/documentation/tdenginedocs-cn/assets/vnode.png and /dev/null differ diff --git a/documentation/tdenginedocs-cn/assets/write_process.png b/documentation/tdenginedocs-cn/assets/write_process.png deleted file mode 100644 index f7d60864824a34af48df637026d704a921dc49f6..0000000000000000000000000000000000000000 Binary files a/documentation/tdenginedocs-cn/assets/write_process.png and /dev/null differ diff --git a/documentation/tdenginedocs-cn/connections-with-other-tools/index.html b/documentation/tdenginedocs-cn/connections-with-other-tools/index.html deleted file mode 100644 index ad877bb4e7e0c9f458d4f77049c3834ad701c77a..0000000000000000000000000000000000000000 --- a/documentation/tdenginedocs-cn/connections-with-other-tools/index.html +++ /dev/null @@ -1,93 +0,0 @@ -文档 | 涛思数据
回去

与其他工具的连接

-

Telegraf

-

TDengine能够与开源数据采集系统Telegraf快速集成，整个过程无需任何代码开发。

-

安装Telegraf

-

目前TDengine支持Telegraf 1.7.4以上的版本。用户可以根据当前的操作系统，到Telegraf官网下载安装包，并执行安装。下载地址如下：https://portal.influxdata.com/downloads

-

配置Telegraf

-

修改Telegraf配置文件/etc/telegraf/telegraf.conf中与TDengine有关的配置项。

-

在output plugins部分，增加[[outputs.http]]配置项：

-
    -
  • url：http://ip:6020/telegraf/udb，其中ip为TDengine集群的中任意一台服务器的IP地址，6020为TDengine RESTful接口的端口号，telegraf为固定关键字，udb为用于存储采集数据的数据库名称，可预先创建。
    • -
  • method: "POST"
    • -
  • username: 登录TDengine的用户名
    • -
  • password: 登录TDengine的密码
    • -
  • data_format: "json"
    • -
  • json_timestamp_units: "1ms"
    • -
-

在agent部分：

-
    -
  • hostname: 区分不同采集设备的机器名称，需确保其唯一性
    • -
  • metric_batch_size: 30，允许Telegraf每批次写入记录最大数量，增大其数量可以降低Telegraf的请求发送频率，但对于TDengine，该数值不能超过50
    • -
-

关于如何使用Telegraf采集数据以及更多有关使用Telegraf的信息，请参考Telegraf官方的文档。

-

Grafana

-

TDengine能够与开源数据可视化系统Grafana快速集成搭建数据监测报警系统，整个过程无需任何代码开发，TDengine中数据表中内容可以在仪表盘(DashBoard)上进行可视化展现。

-

安装Grafana

-

目前TDengine支持Grafana 5.2.4以上的版本。用户可以根据当前的操作系统，到Grafana官网下载安装包，并执行安装。下载地址如下：https://grafana.com/grafana/download

-

配置Grafana

-

TDengine的Grafana插件在安装包的/usr/local/taos/connector/grafana目录下。

-

以CentOS 7.2操作系统为例，将tdengine目录拷贝到/var/lib/grafana/plugins目录下，重新启动grafana即可。

-

使用Grafana

-

用户可以直接通过localhost:3000的网址，登录Grafana服务器(用户名/密码:admin/admin)，配置TDengine数据源，如下图所示，此时可以在下拉列表中看到TDengine数据源。

-

img

-

TDengine数据源中的HTTP配置里面的Host地址要设置为TDengine集群的中任意一台服务器的IP地址与TDengine RESTful接口的端口号(6020)。假设TDengine数据库与Grafana部署在同一机器，那么应输入：http://localhost:6020。

-

此外，还需配置登录TDengine的用户名与密码，然后点击下图中的Save&Test按钮保存。

-

img

-

然后，就可以在Grafana的数据源列表中看到刚创建好的TDengine的数据源：

-

img

-

基于上面的步骤，就可以在创建Dashboard的时候使用TDengine数据源，如下图所示：

-

img

-

然后，可以点击Add Query按钮增加一个新查询。

-

在INPUT SQL输入框中输入查询SQL语句，该SQL语句的结果集应为两行多列的曲线数据，例如SELECT count(*) FROM sys.cpu WHERE ts>=from and ts<​to interval(interval)。其中，from、to和interval为TDengine插件的内置变量，表示从Grafana插件面板获取的查询范围和时间间隔。

-

ALIAS BY输入框为查询的别名，点击GENERATE SQL 按钮可以获取发送给TDengine的SQL语句。如下图所示：

-

img

-

关于如何使用Grafana创建相应的监测界面以及更多有关使用Grafana的信息，请参考Grafana官方的文档。

-

Matlab

-

MatLab可以通过安装包内提供的JDBC Driver直接连接到TDengine获取数据到本地工作空间。

-

MatLab的JDBC接口适配

-

MatLab的适配有下面几个步骤，下面以Windows10上适配MatLab2017a为例：

-
    -
  • 将TDengine安装包内的驱动程序JDBCDriver-1.0.0-dist.jar拷贝到${matlab_root}\MATLAB\R2017a\java\jar\toolbox
    • -
  • 将TDengine安装包内的taos.lib文件拷贝至${matlab_ root _dir}\MATLAB\R2017a\lib\win64
    • -
  • 将新添加的驱动jar包加入MatLab的classpath。在${matlab_ root _dir}\MATLAB\R2017a\toolbox\local\classpath.txt文件中添加下面一行
    • -
-

​ $matlabroot/java/jar/toolbox/JDBCDriver-1.0.0-dist.jar

-
    -
  • 在${user_home}\AppData\Roaming\MathWorks\MATLAB\R2017a\下添加一个文件javalibrarypath.txt, 并在该文件中添加taos.dll的路径，比如您的taos.dll是在安装时拷贝到了C:\Windows\System32下，那么就应该在javalibrarypath.txt中添加如下一行：
    • -
-

​ C:\Windows\System32

-

在MatLab中连接TDengine获取数据

-

在成功进行了上述配置后，打开MatLab。

-
    -

  • 创建一个连接：

    -

    conn = database(‘db’, ‘root’, ‘taosdata’, ‘com.taosdata.jdbc.TSDBDriver’, ‘jdbc:TSDB://127.0.0.1:0/’)

    • -

  • 执行一次查询：

    -

    sql0 = [‘select * from tb’]

    -

    data = select(conn, sql0);

    • -

  • 插入一条记录:

    -

    sql1 = [‘insert into tb values (now, 1)’]

    -

    exec(conn, sql1)

    • -
-

更多例子细节请参考安装包内examples\Matlab\TDengineDemo.m文件。

-

R

-

R语言支持通过JDBC接口来连接TDengine数据库。首先需要安装R语言的JDBC包。启动R语言环境，然后执行以下命令安装R语言的JDBC支持库：

-
install.packages('rJDBC', repos='http://cran.us.r-project.org')
-

安装完成以后，通过执行library('RJDBC')命令加载 RJDBC 包：

-

然后加载TDengine的JDBC驱动：

-
drv<-JDBC("com.taosdata.jdbc.TSDBDriver","JDBCDriver-1.0.0-dist.jar", identifier.quote="\"")
-

如果执行成功，不会出现任何错误信息。之后通过以下命令尝试连接数据库：

-
conn<-dbConnect(drv,"jdbc:TSDB://192.168.0.1:0/?user=root&password=taosdata","root","taosdata")
-

注意将上述命令中的IP地址替换成正确的IP地址。如果没有任务错误的信息，则连接数据库成功，否则需要根据错误提示调整连接的命令。TDengine支持以下的 RJDBC 包中函数：

-
    -
  • dbWriteTable(conn, "test", iris, overwrite=FALSE, append=TRUE)：将数据框iris写入表test中，overwrite必须设置为false，append必须设为TRUE,且数据框iris要与表test的结构一致。
    • -
  • dbGetQuery(conn, "select count(*) from test")：查询语句
    • -
  • dbSendUpdate(conn, "use db")：执行任何非查询sql语句。例如dbSendUpdate(conn, "use db")， 写入数据dbSendUpdate(conn, "insert into t1 values(now, 99)")等。
    • -
  • dbReadTable(conn, "test")：读取表test中数据
    • -
  • dbDisconnect(conn)：关闭连接
    • -
  • dbRemoveTable(conn, "test")：删除表test
    • -
-

TDengine客户端暂不支持如下函数：

-
    -
  • dbExistsTable(conn, "test")：是否存在表test
    • -
  • dbListTables(conn)：显示连接中的所有表
    • -
回去
\ No newline at end of file diff --git a/documentation/tdenginedocs-cn/connector/index.html b/documentation/tdenginedocs-cn/connector/index.html deleted file mode 100644 index 34ea19813fbd7a9f70074ff109308b37ba7b647a..0000000000000000000000000000000000000000 --- a/documentation/tdenginedocs-cn/connector/index.html +++ /dev/null @@ -1,262 +0,0 @@ -文档 | 涛思数据
回去

连接器

-

TDengine提供了丰富的应用程序开发接口，其中包括C/C++、JAVA、Python、RESTful、Go等，便于用户快速开发应用。

-

C/C++ Connector

-

C/C++的API类似于MySQL的C API。应用程序使用时，需要包含TDengine头文件 taos.h（安装后，位于/usr/local/taos/include）：

-
#include <taos.h>
-

在编译时需要链接TDengine动态库libtaos.so（安装后，位于/usr/local/taos/driver，gcc编译时，请加上 -ltaos）。 所有API都以返回-1或NULL均表示失败。

-

C/C++同步API

-

传统的数据库操作API，都属于同步操作。应用调用API后，一直处于阻塞状态，直到服务器返回结果。TDengine支持如下API：

-
    -

  • TAOS *taos_connect(char *ip, char *user, char *pass, char *db, int port)

    -

    创建数据库连接，初始化连接上下文。其中需要用户提供的参数包含：TDengine管理主节点的IP地址、用户名、密码、数据库名字和端口号。如果用户没有提供数据库名字，也可以正常连接，用户可以通过该连接创建新的数据库，如果用户提供了数据库名字，则说明该数据库用户已经创建好，缺省使用该数据库。返回值为空表示失败。应用程序需要保存返回的参数，以便后续API调用。

    • -

  • void taos_close(TAOS *taos)

    -

    关闭连接, 其中taos是taos_connect函数返回的指针。

    • -

  • int taos_query(TAOS *taos, char *sqlstr)

    -

    该API用来执行SQL语句，可以是DQL语句也可以是DML语句，或者DDL语句。其中的taos参数是通过taos_connect()获得的指针。返回值-1表示失败。

    • -

  • TAOS_RES *taos_use_result(TAOS *taos)

    -

    选择相应的查询结果集。

    • -

  • TAOS_ROW taos_fetch_row(TAOS_RES *res)

    -

    按行获取查询结果集中的数据。

    • -

  • int taos_num_fields(TAOS_RES *res)

    -

    获取查询结果集中的列数。

    • -

  • TAOS_FIELD *taos_fetch_fields(TAOS_RES *res)

    -

    获取查询结果集每列数据的属性（数据类型、名字、字节数），与taos_num_fileds配合使用，可用来解析taos_fetch_row返回的一个元组(一行)的数据。

    • -

  • void taos_free_result(TAOS_RES *res)

    -

    释放查询结果集以及相关的资源。查询完成后，务必调用该API释放资源，否则可能导致应用内存泄露。

    • -

  • void taos_init()

    -

    初始化环境变量。如果应用没有主动调用该API，那么应用在调用taos_connect时将自动调用。因此一般情况下应用程序无需手动调用该API。

    • -

  • char *taos_errstr(TAOS *taos)

    -

    获取最近一次API调用失败的原因,返回值为字符串。

    • -

  • char *taos_errno(TAOS *taos)

    -

    获取最近一次API调用失败的原因，返回值为错误代码。

    • -

  • int taos_options(TSDB_OPTION option, const void * arg, ...)

    -

    设置客户端选项，目前只支持时区设置（TSDB_OPTION_TIMEZONE）和编码设置（TSDB_OPTION_LOCALE）。时区和编码默认为操作系统当前设置。

    • -
-

上述12个API是C/C++接口中最重要的API，剩余的辅助API请参看taos.h文件。

-

注意：对于单个数据库连接，在同一时刻只能有一个线程使用该链接调用API，否则会有未定义的行为出现并可能导致客户端crash。客户端应用可以通过建立多个连接进行多线程的数据写入或查询处理。

-

C/C++异步API

-

同步API之外，TDengine还提供性能更高的异步调用API处理数据插入、查询操作。在软硬件环境相同的情况下，异步API处理数据插入的速度比同步API快2~4倍。异步API采用非阻塞式的调用方式，在系统真正完成某个具体数据库操作前，立即返回。调用的线程可以去处理其他工作，从而可以提升整个应用的性能。异步API在网络延迟严重的情况下，优点尤为突出。

-

异步API都需要应用提供相应的回调函数，回调函数参数设置如下：前两个参数都是一致的，第三个参数依不同的API而定。第一个参数param是应用调用异步API时提供给系统的，用于回调时，应用能够找回具体操作的上下文，依具体实现而定。第二个参数是SQL操作的结果集，如果为空，比如insert操作，表示没有记录返回，如果不为空，比如select操作，表示有记录返回。

-

异步API对于使用者的要求相对较高，用户可根据具体应用场景选择性使用。下面是三个重要的异步API：

-
    -

  • void taos_query_a(TAOS *taos, char *sqlstr, void (*fp)(void *param, TAOS_RES *, int code), void *param);

    -

    异步执行SQL语句。taos是调用taos_connect返回的数据库连接结构体。sqlstr是需要执行的SQL语句。fp是用户定义的回调函数。param是应用提供一个用于回调的参数。回调函数fp的第三个参数code用于指示操作是否成功，0表示成功，负数表示失败(调用taos_errstr获取失败原因)。应用在定义回调函数的时候，主要处理第二个参数TAOS_RES *，该参数是查询返回的结果集。

    • -

  • 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表明有fetch数据返回的行数（numOfRows并不是本次查询满足查询条件的全部元组数量）。在回调函数中，应用可以通过调用taos_fetch_row前向迭代获取批量记录中每一行记录。读完一块内的所有记录后，应用需要在回调函数中继续调用taos_fetch_rows_a获取下一批记录进行处理，直到返回的记录数（numOfRows）为零（结果返回完成）或记录数为负值（查询出错）。

    • -

  • void taos_fetch_row_a(TAOS_RES *res, void (*fp)(void *param, TAOS_RES *, TAOS_ROW row), void *param);

    -

    异步获取一条记录。其中res是taos_query_a回调时返回的结果集结构体指针。fp为回调函数。param是应用提供的一个用于回调的参数。回调时，第三个参数TAOS_ROW指向一行记录。不同于taos_fetch_rows_a，应用无需调用同步API taos_fetch_row来获取一个元组，更加简单。数据提取性能不及批量获取的API。

    • -
-

TDengine的异步API均采用非阻塞调用模式。应用程序可以用多线程同时打开多张表，并可以同时对每张打开的表进行查询或者插入操作。需要指出的是，客户端应用必须确保对同一张表的操作完全串行化，即对同一个表的插入或查询操作未完成时（未返回时），不能够执行第二个插入或查询操作。

-

C/C++ 连续查询接口

-

TDengine提供时间驱动的实时流式计算API。可以每隔一指定的时间段，对一张或多张数据库的表(数据流)进行各种实时聚合计算操作。操作简单，仅有打开、关闭流的API。具体如下：

-
    -

  • TAOS_STREAM *taos_open_stream(TAOS *taos, char *sqlstr, void (*fp)(void *param, TAOS_RES *, TAOS_ROW row), int64_t stime, void *param)

    -

    该API用来创建数据流，其中taos是调用taos_connect返回的结构体指针；sqlstr是SQL查询语句（仅能使用查询语句）；fp是用户定义的回调函数指针，每次流式计算完成后，均回调该函数，用户可在该函数内定义其内部业务逻辑；param是应用提供的用于回调的一个参数，回调时，提供给应用；stime是流式计算开始的时间，如果是0，表示从现在开始，如果不为零，表示从指定的时间开始计算（UTC时间从1970/1/1算起的毫秒数）。返回值为NULL，表示创建成功，返回值不为空，表示成功。TDengine将查询的结果（TAOS_ROW）、查询状态（TAOS_RES）、用户定义参数（PARAM）传递给回调函数，在回调函数内，用户可以使用taos_num_fields获取结果集列数，taos_fetch_fields获取结果集每列数据的类型。

    • -

  • void taos_close_stream (TAOS_STREAM *tstr)

    -

    关闭数据流，其中提供的参数是taos_open_stream的返回值。用户停止流式计算的时候，务必关闭该数据流。

    • -
-

C/C++ 数据订阅接口

-

订阅API目前支持订阅一张表，并通过定期轮询的方式不断获取写入表中的最新数据。

-
    -

  • TAOS_SUB *taos_subscribe(char *host, char *user, char *pass, char *db, char *table, long time, int mseconds)

    -

    该API用来启动订阅，需要提供的参数包含：TDengine管理主节点的IP地址、用户名、密码、数据库、数据库表的名字；time是开始订阅消息的时间，是从1970年1月1日起计算的毫秒数，为长整型, 如果设为0，表示从当前时间开始订阅；mseconds为查询数据库更新的时间间隔，单位为毫秒，建议设为1000毫秒。返回值为一指向TDengine_SUB结构的指针，如果返回为空，表示失败。

    • -

  • TAOS_ROW taos_consume(TAOS_SUB *tsub)

    -

    该API用来获取最新消息，应用程序一般会将其置于一个无限循环语句中。其中参数tsub是taos_subscribe的返回值。如果数据库有新的记录，该API将返回，返回参数是一行记录。如果没有新的记录，该API将阻塞。如果返回值为空，说明系统出错，需要检查系统是否还在正常运行。

    • -

  • void taos_unsubscribe(TAOS_SUB *tsub)

    -

    该API用于取消订阅，参数tsub是taos_subscribe的返回值。应用程序退出时，需要调用该API，否则有资源泄露。

    • -

  • int taos_num_fields(TAOS_SUB *tsub)

    -

    该API用来获取返回的一排数据中数据的列数

    • -

  • TAOS_FIELD *taos_fetch_fields(TAOS_RES *res)

    -

    该API用来获取每列数据的属性（数据类型、名字、字节数），与taos_num_subfileds配合使用，可用来解析返回的一排数据。

    • -
-

Java Connector

-

JDBC接口

-

如果用户使用Java开发企业级应用，可选用TDengine提供的JDBC Driver来调用服务。TDengine提供的JDBC Driver是标准JDBC规范的子集，遵循JDBC 标准(3.0)API规范，支持现有的各种Java开发框架。目前TDengine的JDBC driver并未发布到在线依赖仓库比如maven的中心仓库。因此用户开发时，需要手动把驱动包taos-jdbcdriver-x.x.x-dist.jar安装到开发环境的依赖仓库中。

-

TDengine 的驱动程序包的在不同操作系统上依赖不同的本地函数库（均由C语言编写）。Linux系统上，依赖一个名为libtaos.so 的本地库，.so即"Shared Object"缩写。成功安装TDengine后，libtaos.so 文件会被自动拷贝至/usr/local/lib/taos目录下，该目录也包含在Linux上自动扫描路径上。Windows系统上，JDBC驱动程序依赖于一个名为taos.dll 的本地库，.dll是动态链接库"Dynamic Link Library"的缩写。Windows上成功安装客户端后，JDBC驱动程序包默认位于C:/TDengine/driver/JDBC/目录下;其依赖的动态链接库taos.dll文件位于C:/TDengine/driver/C目录下，taos.dll 会被自动拷贝至系统默认搜索路径C:/Windows/System32下。

-

TDengine的JDBC Driver遵循标准JDBC规范，开发人员可以参考Oracle官方的JDBC相关文档来找到具体的接口和方法的定义与用法。TDengine的JDBC驱动在连接配置和支持的方法上与传统数据库驱动稍有不同。

-

TDengine的JDBC URL规范格式为：

-

jdbc:TSDB://{host_ip}:{port}/{database_name}?[user={user}|&password={password}|&charset={charset}|&cfgdir={config_dir}|&locale={locale}|&timezone={timezone}]

-

其中，{}中的内容必须，[]中为可选。配置参数说明如下：

-
    -
  • user：登陆TDengine所用用户名；默认值root
    • -
  • password：用户登陆密码；默认值taosdata
    • -
  • charset：客户端使用的字符集；默认值为系统字符集
    • -
  • cfgdir：客户端配置文件目录路径；Linux OS上默认值/etc/taos ，Windows OS上默认值 C:/TDengine/cfg
    • -
  • locale：客户端语言环境；默认值系统当前locale
    • -
  • timezone：客户端使用的时区；默认值为系统当前时区
    • -
-

以上所有参数均可在调用java.sql.DriverManager类创建连接时指定，示例如下：

-
import java.sql.Connection;
-import java.sql.DriverManager;
-import java.util.Properties;
-import com.taosdata.jdbc.TSDBDriver;
-
-public Connection getConn() throws Exception{
-  Class.forName("com.taosdata.jdbc.TSDBDriver");
-  String jdbcUrl = "jdbc:TAOS://127.0.0.1:0/db?user=root&password=taosdata";
-  Properties connProps = new Properties();
-  connProps.setProperty(TSDBDriver.PROPERTY_KEY_USER, "root");
-  connProps.setProperty(TSDBDriver.PROPERTY_KEY_PASSWORD, "taosdata");
-  connProps.setProperty(TSDBDriver.PROPERTY_KEY_CONFIG_DIR, "/etc/taos");
-  connProps.setProperty(TSDBDriver.PROPERTY_KEY_CHARSET, "UTF-8");
-  connProps.setProperty(TSDBDriver.PROPERTY_KEY_LOCALE, "en_US.UTF-8");
-  connProps.setProperty(TSDBDriver.PROPERTY_KEY_TIMEZONE, "UTC-8");
-  Connection conn = DriverManager.getConnection(jdbcUrl, connProps);
-  return conn;
-}
-

这些配置参数中除了cfgdir外，均可在客户端配置文件taos.cfg中进行配置。调用java.sql.DriverManager时声明的配置参数优先级最高，JDBC URL的优先级次之，配置文件的优先级最低。例如charset同时在配置文件taos.cfg中配置，也在JDBC URL中配置，则使用JDBC URL中的配置值。

-

此外，尽管TDengine的JDBC驱动实现尽可能的与关系型数据库驱动保持一致，但时序空间数据库与关系对象型数据库服务的对象和技术特征的差异导致TDengine的Java API并不能与标准完全相同。对于有大量关系型数据库开发经验而初次接触TDengine的开发者来说，有以下一些值的注意的地方：

-
    -
  • TDengine不提供针对单条数据记录的删除和修改的操作，驱动中也没有支持相关方法
    • -
  • 目前TDengine不支持表间的join或union操作，因此也缺乏对该部分API的支持
    • -
  • TDengine支持批量写入，但是支持停留在SQL语句级别，而不是API级别，也就是说用户需要通过写特殊的SQL语句来实现批量
    • -
  • 目前TDengine不支持嵌套查询(nested query)，对每个Connection的实例，至多只能有一个打开的ResultSet实例；如果在ResultSet还没关闭的情况下执行了新的查询，TSDBJDBCDriver则会自动关闭上一个ResultSet
    • -
-

对于TDengine操作的报错信息，用户可使用JDBCDriver包里提供的枚举类TSDBError.java来获取error message和error code的列表。对于更多的具体操作的相关代码，请参考TDengine提供的使用示范项目JDBCDemo。

-

Python Connector

-

安装准备

-
  • 已安装TDengine, 如果客户端在Windows上，需要安装Windows 版本的TDengine客户端
    • -
  • 已安装python 2.7 or >= 3.4
    • -
  • 已安装pip
    • -

    安装

    -

    Linux

    -

    用户可以在源代码的src/connector/python文件夹下找到python2和python3的安装包， 然后通过pip命令安装

    -
    pip install src/connector/python/linux/python2/
    -

    或者

    -
    pip install src/connector/python/linux/python3/
    -

    Windows

    -

    在已安装Windows TDengine 客户端的情况下， 将文件"C:\TDengine\driver\taos.dll" 拷贝到 "C:\windows\system32" 目录下, 然后进入Windwos cmd 命令行界面

    -
    cd C:\TDengine\connector\python\windows
    -
    pip install python2\
    -

    或者

    -
    cd C:\TDengine\connector\python\windows
    -
    pip install python3\
    -

    * 如果机器上没有pip命令，用户可将src/connector/python/windows/python3或src/connector/python/windows/python2下的taos文件夹拷贝到应用程序的目录使用。

    -

    使用

    -

    代码示例

    -
  • 导入TDengine客户端模块：
    • -
    import taos
    -
  • 获取连接
    • -
    
-conn = taos.connect(host="127.0.0.1", user="root", password="taosdata", config="/etc/taos")
-c1 = conn.cursor()
-
    -

    * host 是TDengine 服务端所有IP, config 为客户端配置文件所在目录

    -
  • 写入数据
    • -
    
-import datetime
- 
-# 创建数据库
-c1.execute('create database db')
-c1.execute('use db')
-# 建表
-c1.execute('create table tb (ts timestamp, temperature int, humidity float)')
-# 插入数据
-start_time = datetime.datetime(2019, 11, 1)
-affected_rows = c1.execute('insert into tb values (\'%s\', 0, 0.0)' %start_time)
-# 批量插入数据
-time_interval = datetime.timedelta(seconds=60)
-sqlcmd = ['insert into tb values']
-for irow in range(1,11):
-  start_time += time_interval
-  sqlcmd.append('(\'%s\', %d, %f)' %(start_time, irow, irow*1.2))
-affected_rows = c1.execute(' '.join(sqlcmd))
-
    -
  • 查询数据
    • -
    -c1.execute('select * from tb')
-# 拉取查询结果
-data = c1.fetchall()
-# 返回的结果是一个列表，每一行构成列表的一个元素
-numOfRows = c1.rowcount
-numOfCols = c1.descriptions
-for irow in range(numOfRows):
-  print("Row%d: ts=%s, temperature=%d, humidity=%f" %(irow, data[irow][0], data[irow][1],data[irow][2])
-  
-# 直接使用cursor 循环拉取查询结果
-c1.execute('select * from tb')
-for data in c1:
-  print("ts=%s, temperature=%d, humidity=%f" %(data[0], data[1],data[2])
-
     -
  • 关闭连接
    • -
    -c1.close()
-conn.close()
-
     -

    帮助信息

    -

    用户可通过python的帮助信息直接查看模块的使用信息，或者参考code/examples/python中的示例程序。以下为部分常用类和方法:

    -
      -

    • TaosConnection 类

      -

      参考python中help(taos.TDengineConnection)

      • -

    • TaosCursor 类

      -

      参考python中help(taos.TDengineCursor)

      • -

    • connect 方法

      -

      用于生成taos.TDengineConnection的实例。

      • -
    -

    RESTful Connector

    -

    为支持各种不同类型平台的开发，TDengine提供符合REST设计标准的API，即RESTful API。为最大程度降低学习成本，不同于其他数据库RESTful API的设计方法，TDengine直接通过HTTP POST 请求BODY中包含的SQL语句来操作数据库，仅需要一个URL。

    -

    HTTP请求格式

    -

    ​ http://<ip>:<PORT>/rest/sql

    -

    ​ 参数说明：

    -

    ​ IP: 集群中的任一台主机

    -

    ​ PORT: 配置文件中httpPort配置项，缺省为6020

    -

    如：http://192.168.0.1:6020/rest/sql 是指向IP地址为192.168.0.1的URL.

    -

    HTTP请求的Header里需带有身份认证信息，TDengine单机版仅支持Basic认证机制。

    -

    HTTP请求的BODY里就是一个完整的SQL语句，SQL语句中的数据表应提供数据库前缀，例如\.\。如果表名不带数据库前缀，系统会返回错误。因为HTTP模块只是一个简单的转发，没有当前DB的概念。

    -

    使用curl来发起一个HTTP Request, 语法如下：

    -
    curl -H 'Authorization: Basic <TOKEN>' -d '<SQL>' <ip>:<PORT>/rest/sql
    -

    或者

    -
    curl -u username:password -d '<SQL>' <ip>:<PORT>/rest/sql
    -

    其中，TOKEN为{username}:{password}经过Base64编码之后的字符串，例如root:taosdata编码后为cm9vdDp0YW9zZGF0YQ==

    -

    HTTP返回格式

    -

    返回值为JSON格式，如下：

    -
    {
-    "status": "succ",
-    "head": ["column1","column2", …],
-    "data": [
-        ["2017-12-12 23:44:25.730", 1],
-        ["2017-12-12 22:44:25.728", 4]
-    ],
-    "rows": 2
-}
    -

    说明：

    -
      -
    • 第一行”status”告知操作结果是成功还是失败;
      • -
    • 第二行”head”是表的定义，如果不返回结果集，仅有一列“affected_rows”;
      • -
    • 第三行是具体返回的数据，一排一排的呈现。如果不返回结果集，仅[[affected_rows]]
      • -
    • 第四行”rows”表明总共多少行数据
      • -
    -

    使用示例

    -
      -

    • 在demo库里查询表t1的所有记录, curl如下：

      -

      curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.t1' 192.168.0.1:6020/rest/sql

      -

      返回值：

      • -
    -
    {
-    "status": "succ",
-    "head": ["column1","column2","column3"],
-    "data": [
-        ["2017-12-12 23:44:25.730", 1, 2.3],
-        ["2017-12-12 22:44:25.728", 4, 5.6]
-    ],
-    "rows": 2
-}
    -
      -

    • 创建库demo：

      -

      curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'create database demo' 192.168.0.1:6020/rest/sql

      -

      返回值：

      • -
    -
    {
-    "status": "succ",
-    "head": ["affected_rows"],
-    "data": [[1]],
-    "rows": 1,
-}
    -

    Go Connector

    -

    TDengine提供了GO驱动程序“taosSql”包。taosSql驱动包是基于GO的“database/sql/driver”接口的实现。用户可在安装后的/usr/local/taos/connector/go目录获得GO的客户端驱动程序。用户需将驱动包/usr/local/taos/connector/go/src/taosSql目录拷贝到应用程序工程的src目录下。然后在应用程序中导入驱动包，就可以使用“database/sql”中定义的接口访问TDengine：

    -
    import (
-    "database/sql"
-    _ "taosSql"
-)
    -

    taosSql驱动包内采用cgo模式，调用了TDengine的C/C++同步接口，与TDengine进行交互，因此，在数据库操作执行完成之前，客户端应用将处于阻塞状态。单个数据库连接，在同一时刻只能有一个线程调用API。客户应用可以建立多个连接，进行多线程的数据写入或查询处理。

    -

    更多使用的细节，请参考下载目录中的示例源码。

    回去
    diff --git a/documentation/tdenginedocs-cn/data-model-and-architecture/index.html b/documentation/tdenginedocs-cn/data-model-and-architecture/index.html deleted file mode 100644 index 09e1212b04c2baa32b977eba4bf9540f447f325d..0000000000000000000000000000000000000000 --- a/documentation/tdenginedocs-cn/data-model-and-architecture/index.html +++ /dev/null @@ -1,128 +0,0 @@ -文档 | 涛思数据
    回去

    数据模型和设计

    -

    数据模型

    -

    物联网典型场景

    -

    在典型的物联网、车联网、运维监测场景中，往往有多种不同类型的数据采集设备，采集一个到多个不同的物理量。而同一种采集设备类型，往往又有多个具体的采集设备分布在不同的地点。大数据处理系统就是要将各种采集的数据汇总，然后进行计算和分析。对于同一类设备，其采集的数据类似如下的表格：

    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Device IDTime StampValue 1Value 2Value 3Tag 1Tag 2
    D1001153854868500010.32190.31RedTesla
    D1002153854868400010.22200.23BlueBMW
    D1003153854868650011.52210.35BlackHonda
    D1004153854868550013.42230.29RedVolvo
    D1001153854869500012.62180.33RedTesla
    D1004153854869660011.82210.28BlackHonda
    -

    每一条记录都有设备ID，时间戳，采集的物理量，还有与每个设备相关的静态标签。每个设备是受外界的触发，或按照设定的周期采集数据。采集的数据点是时序的，是一个数据流。

    -

    数据特征

    -

    除时序特征外，仔细研究发现，物联网、车联网、运维监测类数据还具有很多其他明显的特征。

    -
      -
    1. 数据是结构化的；
      2. -
    2. 数据极少有更新或删除操作；
      3. -
    3. 无需传统数据库的事务处理；
      4. -
    4. 相对互联网应用，写多读少；
      5. -
    5. 流量平稳，根据设备数量和采集频次，可以预测出来；
      6. -
    6. 用户关注的是一段时间的趋势，而不是某一特点时间点的值；
      7. -
    7. 数据是有保留期限的；
      8. -
    8. 数据的查询分析一定是基于时间段和地理区域的；
      9. -
    9. 除存储查询外，还往往需要各种统计和实时计算操作；
      10. -
    10. 数据量巨大，一天采集的数据就可以超过100亿条。
      11. -
    -

    充分利用上述特征，TDengine采取了一特殊的优化的存储和计算设计来处理时序数据，能将系统处理能力显著提高。

    -

    关系型数据库模型

    -

    因为采集的数据一般是结构化数据，而且为降低学习门槛，TDengine采用传统的关系型数据库模型管理数据。因此用户需要先创建库，然后创建表，之后才能插入或查询数据。

    -

    一个设备一张表

    -

    为充分利用其数据的时序性和其他数据特点，TDengine要求对每个数据采集点单独建表（比如有一千万个智能电表，就需创建一千万张表，上述表格中的D1001, D1002, D1003, D1004都需单独建表），用来存储这个采集点所采集的时序数据。这种设计能保证一个采集点的数据在存储介质上是一块一块连续的，大幅减少随机读取操作，成数量级的提升读取和查询速度。而且由于不同数据采集设备产生数据的过程完全独立，每个设备只产生属于自己的数据，一张表也就只有一个写入者。这样每个表就可以采用无锁方式来写，写入速度就能大幅提升。同时，对于一个数据采集点而言，其产生的数据是时序的，因此写的操作可用追加的方式实现，进一步大幅提高数据写入速度。

    -

    数据建模最佳实践

    -

    表(Table)：TDengine 建议用数据采集点的名字(如上表中的D1001)来做表名。每个数据采集点可能同时采集多个物理量(如上表中的value1, value2, value3)，每个物理量对应一张表中的一列，数据类型可以是整型、浮点型、字符串等。除此之外，表的第一列必须是时间戳，即数据类型为 timestamp。有的设备有多组采集量，每一组的采集频次是不一样的，这是需要对同一个设备建多张表。对采集的数据，TDengine将自动按照时间戳建立索引，但对采集的物理量不建任何索引。数据是用列式存储方式保存。

    -

    超级表(Super Table)：对于同一类型的采集点，为保证Schema的一致性，而且为便于聚合统计操作，可以先定义超级表STable(详见第10章)，然后再定义表。每个采集点往往还有静态标签信息(如上表中的Tag 1, Tag 2)，比如设备型号、颜色等，这些静态信息不会保存在存储采集数据的数据节点中，而是通过超级表保存在元数据节点中。这些静态标签信息将作为过滤条件，用于采集点之间的数据聚合统计操作。

    -

    库(DataBase)：不同的数据采集点往往具有不同的数据特征，包括数据采集频率高低，数据保留时间长短，备份数目，单个字段大小等等。为让各种场景下TDengine都能最大效率的工作，TDengine建议将不同数据特征的表创建在不同的库里。创建一个库时，除SQL标准的选项外，应用还可以指定保留时长、数据备份的份数、cache大小、文件块大小、是否压缩等多种参数(详见第19章)。

    -

    Schemaless vs Schema: 与NoSQL的各种引擎相比，由于应用需要定义schema，插入数据的灵活性降低。但对于物联网、金融这些典型的时序数据场景，schema会很少变更，因此这个灵活性不够的设计就不成问题。相反，TDengine采用结构化数据来进行处理的方式将让查询、分析的性能成数量级的提升。

    -

    TDengine对库的数量、超级表的数量以及表的数量没有做任何限制，而且其多少不会对性能产生影响，应用按照自己的场景创建即可。

    -

    主要模块

    -

    如图所示，TDengine服务主要包含两大模块：管理节点模块(MGMT) 和 数据节点模块(DNODE)。整个TDengine还包含客户端模块。

    -

    -
    图 1 TDengine架构示意图

    -

    管理节点模块

    -

    管理节点模块主要负责元数据的存储和查询等工作，其中包括用户信息的管理、数据库和表信息的创建、删除以及查询等。应用连接TDengine时会首先连接到管理节点。在创建/删除数据库和表时，请求也会首先发送请求到管理节点模块。由管理节点模块首先创建/删除元数据信息，然后发送请求到数据节点模块进行分配/删除所需要的资源。在数据写入和查询时，应用同样会首先访问管理节点模块，获取元数据信息。然后根据元数据管理信息访问数据节点模块。

    -

    数据节点模块

    -

    写入数据的存储和查询工作是由数据节点模块负责。 为了更高效地利用资源，以及方便将来进行水平扩展，TDengine内部对数据节点进行了虚拟化，引入了虚拟节点(virtual node, 简称vnode）的概念，作为存储、资源分配以及数据备份的单元。如图2所示，在一个dnode上，通过虚拟化，可以将该dnode视为多个虚拟节点的集合。

    -

    创建一个库时，系统会自动分配vnode。每个vnode存储一定数量的表中的数据，但一个表只会存在于一个vnode里，不会跨vnode。一个vnode只会属于一个库，但一个库会有一到多个vnode。不同的vnode之间资源互不共享。每个虚拟节点都有自己的缓存，在硬盘上也有自己的存储目录。而同一vnode内部无论是缓存还是硬盘的存储都是共享的。通过虚拟化，TDengine可以将dnode上有限的物理资源合理地分配给不同的vnode，大大提高资源的利用率和并发度。一台物理机器上的虚拟节点个数可以根据其硬件资源进行配置。

    -

    -
    图 2 TDengine虚拟化

    -

    客户端模块

    -

    TDengine客户端模块主要负责将应用传来的请求（SQL语句）进行解析，转化为内部结构体再发送到服务端。TDengine的各种接口都是基于TDengine的客户端模块进行开发的。客户端模块与管理模块使用TCP/UDP通讯，端口号由系统参数mgmtShellPort配置, 缺省值为6030。客户端与数据节点模块也是使用TCP/UDP通讯，端口号由系统参数vnodeShellPort配置, 缺省值为6035。两个端口号均可通过系统配置文件taos.cfg进行个性化设置。

    -

    写入流程

    -

    TDengine的完整写入流程如图3所示。为了保证写入数据的安全性和完整性，TDengine在写入数据时采用[预写日志算法]。客户端发来的数据在经过验证以后，首先会写入预写日志中，以保证TDengine能够在断电等因素导致的服务重启时从预写日志中恢复数据，避免数据的丢失。写入预写日志后，数据会被写到对应的vnode的缓存中。随后，服务端会发送确认信息给客户端表示写入成功。TDengine中存在两种机制可以促使缓存中的数据写入到硬盘上进行持久化存储：

    -

    -
    图 3 TDengine写入流程

    -
      -
    1. 时间驱动的落盘：TDengine服务会定时将vnode缓存中的数据写入到硬盘上，默认为一个小时落一次盘。落盘间隔可在配置文件taos.cfg中通过参数commitTime配置。
      2. -
    2. 数据驱动的落盘：当vnode中缓存的数据达到一定规模时，为了不阻塞后续数据的写入，TDengine也会拉起落盘线程将缓存中的数据清空。数据驱动的落盘会刷新定时落盘的时间。
      3. -
    -

    TDengine在数据落盘时会打开新的预写日志文件，在落盘后则会删除老的预写日志文件，避免日志文件无限制的增长。TDengine对缓存按照先进先出的原则进行管理，以保证每个表的最新数据都在缓存中。

    -

    数据存储

    -

    TDengine将所有数据存储在/var/lib/taos/目录下，您可以通过系统配置参数dataDir进行个性化配置。

    -

    TDengine中的元数据信息包括TDengine中的数据库、表、用户等信息。每个超级表、以及每个表的标签数据也存放在这里。为提高访问速度，元数据全部有缓存。

    -

    TDengine中写入的数据在硬盘上是按时间维度进行分片的。同一个vnode中的表在同一时间范围内的数据都存放在同一文件组中。这一数据分片方式可以大大简化数据在时间维度的查询，提高查询速度。在默认配置下，硬盘上的每个数据文件存放10天数据。用户可根据需要修改系统配置参数daysPerFile进行个性化配置。

    -

    表中的数据都有保存时间，一旦超过保存时间（缺省是3650天），数据将被系统自动删除。您可以通过系统配置参数daysToKeep进行个性化设置。

    -

    数据在文件中是按块存储的。每个数据块只包含一张表的数据，且数据是按照时间主键递增排列的。数据在数据块中按列存储，这样使得同列的数据存放在一起，对于不同的数据类型还采用不同的压缩方法，大大提高压缩的比例，节省存储空间。

    -

    数据文件总共有三类文件，一类是data文件，它存放了真实的数据块，该文件只进行追加操作；一类文件是head文件, 它存放了其对应的data文件中数据块的索引信息；第三类是last文件，专门存储最后写入的数据，每次落盘操作时，这部分数据会与内存里的数据合并，并决定是否写入data文件还是last文件。

    回去
    \ No newline at end of file diff --git a/documentation/tdenginedocs-cn/faq/index.html b/documentation/tdenginedocs-cn/faq/index.html deleted file mode 100644 index ea40348569eeffacfe5b46a4a09e7a028d2a33f1..0000000000000000000000000000000000000000 --- a/documentation/tdenginedocs-cn/faq/index.html +++ /dev/null @@ -1,33 +0,0 @@ -文档 | 涛思数据
    回去

    常见问题

    -

    1. 遇到错误"failed to connect to server", 我怎么办？

    -

    客户端遇到链接故障，请按照下面的步骤进行检查：

    -
      -
    1. 在服务器，执行 systemctl status taosd 检查taosd运行状态。如果没有运行，启动taosd
      2. -
    2. 确认客户端连接时指定了正确的服务器IP地址
      3. -
    3. ping服务器IP，如果没有反应，请检查你的网络
      4. -
    4. 检查防火墙设置，确认TCP/UDP 端口6030-6039 是打开的
      5. -
    5. 对于Linux上的JDBC（ODBC, Python, Go等接口类似）连接, 确保libtaos.so在目录/usr/local/lib/taos里, 并且/usr/local/lib/taos在系统库函数搜索路径LD_LIBRARY_PATH里
      6. -
    6. 对于windows上的JDBC, ODBC, Python, Go等连接，确保driver/c/taos.dll在你的系统搜索目录里 (建议taos.dll放在目录 C:\Windows\System32)
      7. -
    7. 如果仍不能排除连接故障，请使用命令行工具nc来分别判断指定端口的TCP和UDP连接是否通畅 -检查UDP端口连接是否工作：nc -vuz {hostIP} {port} -检查服务器侧TCP端口连接是否工作：nc -l {port} -检查客户端侧TCP端口链接是否工作：nc {hostIP} {port}
      8. -
    -

    2. 虽然语法正确，为什么我还是得到 "Invalid SQL" 错误

    -

    如果你确认语法正确，请检查SQL语句长度是否超过64K。如果超过，也会返回这个错误。

    -

    3. 为什么我删除超级表总是失败？

    -

    请确保超级表下已经没有其他表，否则系统不允许删除该超级表。

    -

    4. 是否支持validation queries?

    -

    TDengine还没有一组专用的validation queries。然而建议你使用系统监测的数据库”log"来做。

    -

    5. 我可以删除或更新一条记录吗？

    -

    不能。因为TDengine是为联网设备采集的数据设计的，不容许修改。但TDengine提供数据保留策略，只要数据记录超过保留时长，就会被自动删除。

    -

    6. 我怎么创建超过250列的表？

    -

    TDengine最大允许创建250列的表。但是如果确实超过，我们建议按照数据特性，逻辑地将这个宽表分解成几个小表。

    -

    7. 最有效的写入数据的方法是什么？

    -

    批量插入。每条写入语句可以一张表同时插入多条记录，也可以同时插入多张表的记录。

    -

    8. windows系统下插入的nchar类数据中的汉字被解析成了乱码如何解决？

    -

    windows下插入nchar类的数据中如果有中文，请先确认系统的地区设置成了中国（在Control Panel里可以设置），这时cmd中的taos客户端应该已经可以正常工作了；如果是在IDE里开发Java应用，比如Eclipse， Intellij，请确认IDE里的文件编码为GBK（这是Java默认的编码类型），然后在生成Connection时，初始化客户端的配置，具体语句如下：

    -

    ​ Class.forName("com.taosdata.jdbc.TSDBDriver");

    -

    ​ Properties properties = new Properties();

    -

    ​ properties.setProperty(TSDBDriver.LOCALE_KEY, "UTF-8");

    -

    ​ Connection = DriverManager.getConnection(url, properties);

    回去
    \ No newline at end of file diff --git a/documentation/tdenginedocs-cn/getting-started/index.html b/documentation/tdenginedocs-cn/getting-started/index.html deleted file mode 100644 index d7d5d8540c6c46bbf5210677339c2ee202a7ec86..0000000000000000000000000000000000000000 --- a/documentation/tdenginedocs-cn/getting-started/index.html +++ /dev/null @@ -1,88 +0,0 @@ -文档 | 涛思数据
    回去

    立即开始

    -

    快速上手

    -

    TDengine目前只支持在Linux系统上安装和运行。用户可根据需求选择通过源码或者安装包来安装。

    -

    通过源码安装

    -

    请参考我们的TDengine github主页下载源码并安装.

    -

    通过安装包安装

    -

    我们提供三种安装包，请选择你所需要的。TDengine的安装非常简单，从下载到安装成功仅仅只要几秒钟。

    - -

    目前，TDengine只支持在使用systemd做进程服务管理的linux系统上安装。其他linux系统的支持正在开发中。用which命令来检测系统中是否存在systemd:

    -
    which systemd
    -

    如果系统中不存在systemd命令，请考虑通过源码安装TDengine。

    -

    启动并体验TDengine

    -

    安装成功后，用户可使用systemctl命令来启动TDengine的服务进程。

    -
    systemctl start taosd
    -

    检查服务是否正常工作。

    -
    systemctl status taosd
    -

    如果TDengine服务正常工作，那么您可以通过TDengine的命令行程序taos来访问并体验TDengine。

    -

    注：systemctl 命令需要 root 权限来运行，如果您非 root 用户，请在命令前添加 sudo

    -

    TDengine命令行程序

    -

    执行TDengine命令行程序，您只要在Linux终端执行taos即可

    -
    taos
    -

    如果TDengine终端链接服务成功，将会打印出欢迎消息和版本信息。如果失败，则会打印错误消息出来（请参考FAQ来解决终端链接服务端失败的问题）。TDengine终端的提示符号如下：

    -
    taos>
    -

    在TDengine终端中，用户可以通过SQL命令来创建/删除数据库、表等，并进行插入查询操作。在终端中运行的SQL语句需要以分号结束来运行。示例：

    -
    create database db;
-use db;
-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   |
-===================================
- 19-07-15 00:00:00.000|         10|
- 19-07-15 01:00:00.000|         20|
-Query OK, 2 row(s) in set (0.001700s)
    -

    除执行SQL语句外，系统管理员还可以从TDengine终端检查系统运行状态，添加删除用户账号等。

    -

    命令行参数

    -

    您可通过配置命令行参数来改变TDengine终端的行为。以下为常用的几个命令行参数：

    -
      -
    • -c, --config-dir: 指定配置文件目录，默认为/etc/taos
      • -
    • -h, --host: 指定服务的IP地址，默认为本地服务
      • -
    • -s, --commands: 在不进入终端的情况下运行TDengine命令
      • -
    • -u, -- user: 链接TDengine服务器的用户名，缺省为root
      • -
    • -p, --password: 链接TDengine服务器的密码，缺省为taosdata
      • -
    • -?, --help: 打印出所有命令行参数
      • -
    -

    示例：

    -
    taos -h 192.168.0.1 -s "use db; show tables;"
    -

    运行SQL命令脚本

    -

    TDengine终端可以通过source命令来运行SQL命令脚本.

    -
    taos> source <filename>;
    -

    Shell小技巧

    -
      -
    • 可以使用上下光标键查看已经历史输入的命令
      • -
    • 修改用户密码。在shell中使用alter user命令
      • -
    • ctrl+c 中止正在进行中的查询
      • -
    • 执行RESET QUERY CACHE清空本地缓存的表的schema
      • -
    -

    主要功能

    -

    TDengine的核心功能是时序数据库。除此之外，为减少研发的复杂度、系统维护的难度，TDengine还提供缓存、消息队列、订阅、流式计算等功能。更详细的功能如下：

    -
      -
    • 使用类SQL语言插入或查询数据
      • -
    • 支持C/C++, Java(JDBC), Python, Go, RESTful, and Node.JS 开发接口
      • -
    • 可通过Python/R/Matlab or TDengine shell做Ad Hoc查询分析
      • -
    • 通过定时连续查询支持基于滑动窗口的流式计算
      • -
    • 使用超级表来更灵活高效的聚合多个时间线的数据
      • -
    • 时间轴上聚合一个或多个时间线的数据
      • -
    • 支持数据订阅，一旦有新数据，就立即通知应用
      • -
    • 支持缓存，每个时间线或设备的最新数据都从内存里快速获取
      • -
    • 历史数据与实时数据处理完全透明，不用区别对待
      • -
    • 支持链接Telegraf, Grafana等第三方工具
      • -
    • 成套的配置和工具，让你更好的管理TDengine
      • -
    -

    对于企业版，TDengine还提供如下高级功能：

    -
      -
    • 线性水平扩展能力，以提供更高的处理速度和数据容量
      • -
    • 高可靠，无单点故障，提供运营商级别的服务
      • -
    • 多个副本自动同步，而且可以跨机房
      • -
    • 多级存储，让历史数据处理的成本更低
      • -
    • 用户友好的管理后台和工具，让管理更轻松简单
      • -
    -

    TDengine是专为物联网、车联网、工业互联网、运维监测等场景优化设计的时序数据处理引擎。与其他方案相比，它的插入查询速度都快10倍以上。单核一秒钟就能插入100万数据点，读出1000万数据点。由于采用列式存储和优化的压缩算法，存储空间不及普通数据库的1/10.

    -

    深入了解TDengine

    -

    请继续阅读文档来深入了解TDengine。

    回去
    diff --git a/documentation/tdenginedocs-cn/index.html b/documentation/tdenginedocs-cn/index.html deleted file mode 100644 index 17ee078d048fa102bcc364d55363a10bbd020776..0000000000000000000000000000000000000000 --- a/documentation/tdenginedocs-cn/index.html +++ /dev/null @@ -1 +0,0 @@ -文档 | 涛思数据

    TDengine文档

    TDengine是一个高效的存储、查询、分析时序大数据的平台，专为物联网、车联网、工业互联网、运维监测等优化而设计。您可以像使用关系型数据库MySQL一样来使用它，但建议您在使用前仔细阅读一遍下面的文档，特别是数据模型与超级表一节。除本文档之外，欢迎下载产品白皮书。

    立即开始

    数据模型和设计

    • 数据模型：关系型数据库模型，但要求每个采集设备单独建表
    • 主要模块：包含管理节点、数据节点和客户端，数据节点支持虚拟化
    • 写入流程：先写入WAL、之后写入缓存，再给应用确认
    • 数据存储：数据按时间段切片、采取列存、不同数据类型不同压缩算法

    TAOS SQL

    • 支持的数据类型：支持时间戳、整型、浮点型、布尔型、字符型等多种数据类型
    • 数据库管理：添加、删除、查看数据库
    • 表管理：添加、删除、查看、修改表
    • 数据写入：支持单表单条、多条、多表多条写入，支持历史数据写入
    • 数据查询：支持时间段、值过滤、排序、查询结果手动分页等
    • SQL函数：支持各种聚合函数、选择函数、计算函数，如avg, min, diff等
    • 时间维度聚合：将表中数据按照时间段进行切割后聚合，降维处理

    超级表STable：多表聚合

    高级功能

    连接器

    与其他工具的连接

    • Telegraf：将DevOps采集的数据发送到TDengine
    • Grafana：获取并可视化保存在TDengine的数据
    • Matlab：通过配置Matlab的JDBC数据源访问保存在TDengine的数据
    • R：通过配置R的JDBC数据源访问保存在TDengine的数据

    系统管理

    TDengine的技术设计

    • 存储设计：为时序数据专门优化设计的列式存储格式
    • 查询处理：高效的查询计算时序数据的方法
    • 集群设计：吸取NoSQL的优点，支持高可靠，支持线性扩展
    • 技术博客：更多的技术分析和架构设计文章

    培训和FAQ

    • FAQ：常见问题与答案
    • 应用案列：一些使用实例来解释如何使用TDengine
    回去
    \ No newline at end of file diff --git a/documentation/tdenginedocs-cn/lib/bootstrap.min.css b/documentation/tdenginedocs-cn/lib/bootstrap.min.css deleted file mode 100644 index 882691283ab5b356f9643f8507666d71f3372ca1..0000000000000000000000000000000000000000 --- a/documentation/tdenginedocs-cn/lib/bootstrap.min.css +++ /dev/null @@ -1,7 +0,0 @@ -/*! - * Bootstrap v4.1.3 (https://getbootstrap.com/) - * Copyright 2011-2018 The Bootstrap Authors - * Copyright 2011-2018 Twitter, Inc. - * Licensed under MIT (https://github.com/twbs/bootstrap/blob/master/LICENSE) - */:root{--blue:#007bff;--indigo:#6610f2;--purple:#6f42c1;--pink:#e83e8c;--red:#dc3545;--orange:#fd7e14;--yellow:#ffc107;--green:#28a745;--teal:#20c997;--cyan:#17a2b8;--white:#fff;--gray:#6c757d;--gray-dark:#343a40;--primary:#007bff;--secondary:#6c757d;--success:#28a745;--info:#17a2b8;--warning:#ffc107;--danger:#dc3545;--light:#f8f9fa;--dark:#343a40;--breakpoint-xs:0;--breakpoint-sm:576px;--breakpoint-md:768px;--breakpoint-lg:992px;--breakpoint-xl:1200px;--font-family-sans-serif:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol","Noto Color Emoji";--font-family-monospace:SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",monospace}*,::after,::before{box-sizing:border-box}html{font-family:sans-serif;line-height:1.15;-webkit-text-size-adjust:100%;-ms-text-size-adjust:100%;-ms-overflow-style:scrollbar;-webkit-tap-highlight-color:transparent}@-ms-viewport{width:device-width}article,aside,figcaption,figure,footer,header,hgroup,main,nav,section{display:block}body{margin:0;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol","Noto Color Emoji";font-size:1rem;font-weight:400;line-height:1.5;color:#212529;text-align:left;background-color:#fff}[tabindex="-1"]:focus{outline:0!important}hr{box-sizing:content-box;height:0;overflow:visible}h1,h2,h3,h4,h5,h6{margin-top:0;margin-bottom:.5rem}p{margin-top:0;margin-bottom:1rem}abbr[data-original-title],abbr[title]{text-decoration:underline;-webkit-text-decoration:underline dotted;text-decoration:underline dotted;cursor:help;border-bottom:0}address{margin-bottom:1rem;font-style:normal;line-height:inherit}dl,ol,ul{margin-top:0;margin-bottom:1rem}ol ol,ol ul,ul ol,ul ul{margin-bottom:0}dt{font-weight:700}dd{margin-bottom:.5rem;margin-left:0}blockquote{margin:0 0 1rem}dfn{font-style:italic}b,strong{font-weight:bolder}small{font-size:80%}sub,sup{position:relative;font-size:75%;line-height:0;vertical-align:baseline}sub{bottom:-.25em}sup{top:-.5em}a{color:#007bff;text-decoration:none;background-color:transparent;-webkit-text-decoration-skip:objects}a:hover{color:#0056b3;text-decoration:underline}a:not([href]):not([tabindex]){color:inherit;text-decoration:none}a:not([href]):not([tabindex]):focus,a:not([href]):not([tabindex]):hover{color:inherit;text-decoration:none}a:not([href]):not([tabindex]):focus{outline:0}code,kbd,pre,samp{font-family:SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",monospace;font-size:1em}pre{margin-top:0;margin-bottom:1rem;overflow:auto;-ms-overflow-style:scrollbar}figure{margin:0 0 1rem}img{vertical-align:middle;border-style:none}svg{overflow:hidden;vertical-align:middle}table{border-collapse:collapse}caption{padding-top:.75rem;padding-bottom:.75rem;color:#6c757d;text-align:left;caption-side:bottom}th{text-align:inherit}label{display:inline-block;margin-bottom:.5rem}button{border-radius:0}button:focus{outline:1px dotted;outline:5px auto -webkit-focus-ring-color}button,input,optgroup,select,textarea{margin:0;font-family:inherit;font-size:inherit;line-height:inherit}button,input{overflow:visible}button,select{text-transform:none}[type=reset],[type=submit],button,html [type=button]{-webkit-appearance:button}[type=button]::-moz-focus-inner,[type=reset]::-moz-focus-inner,[type=submit]::-moz-focus-inner,button::-moz-focus-inner{padding:0;border-style:none}input[type=checkbox],input[type=radio]{box-sizing:border-box;padding:0}input[type=date],input[type=datetime-local],input[type=month],input[type=time]{-webkit-appearance:listbox}textarea{overflow:auto;resize:vertical}fieldset{min-width:0;padding:0;margin:0;border:0}legend{display:block;width:100%;max-width:100%;padding:0;margin-bottom:.5rem;font-size:1.5rem;line-height:inherit;color:inherit;white-space:normal}progress{vertical-align:baseline}[type=number]::-webkit-inner-spin-button,[type=number]::-webkit-outer-spin-button{height:auto}[type=search]{outline-offset:-2px;-webkit-appearance:none}[type=search]::-webkit-search-cancel-button,[type=search]::-webkit-search-decoration{-webkit-appearance:none}::-webkit-file-upload-button{font:inherit;-webkit-appearance:button}output{display:inline-block}summary{display:list-item;cursor:pointer}template{display:none}[hidden]{display:none!important}.h1,.h2,.h3,.h4,.h5,.h6,h1,h2,h3,h4,h5,h6{margin-bottom:.5rem;font-family:inherit;font-weight:500;line-height:1.2;color:inherit}.h1,h1{font-size:2.5rem}.h2,h2{font-size:2rem}.h3,h3{font-size:1.75rem}.h4,h4{font-size:1.5rem}.h5,h5{font-size:1.25rem}.h6,h6{font-size:1rem}.lead{font-size:1.25rem;font-weight:300}.display-1{font-size:6rem;font-weight:300;line-height:1.2}.display-2{font-size:5.5rem;font-weight:300;line-height:1.2}.display-3{font-size:4.5rem;font-weight:300;line-height:1.2}.display-4{font-size:3.5rem;font-weight:300;line-height:1.2}hr{margin-top:1rem;margin-bottom:1rem;border:0;border-top:1px solid rgba(0,0,0,.1)}.small,small{font-size:80%;font-weight:400}.mark,mark{padding:.2em;background-color:#fcf8e3}.list-unstyled{padding-left:0;list-style:none}.list-inline{padding-left:0;list-style:none}.list-inline-item{display:inline-block}.list-inline-item:not(:last-child){margin-right:.5rem}.initialism{font-size:90%;text-transform:uppercase}.blockquote{margin-bottom:1rem;font-size:1.25rem}.blockquote-footer{display:block;font-size:80%;color:#6c757d}.blockquote-footer::before{content:"\2014 \00A0"}.img-fluid{max-width:100%;height:auto}.img-thumbnail{padding:.25rem;background-color:#fff;border:1px solid #dee2e6;border-radius:.25rem;max-width:100%;height:auto}.figure{display:inline-block}.figure-img{margin-bottom:.5rem;line-height:1}.figure-caption{font-size:90%;color:#6c757d}code{font-size:87.5%;color:#e83e8c;word-break:break-word}a>code{color:inherit}kbd{padding:.2rem .4rem;font-size:87.5%;color:#fff;background-color:#212529;border-radius:.2rem}kbd kbd{padding:0;font-size:100%;font-weight:700}pre{display:block;font-size:87.5%;color:#212529}pre code{font-size:inherit;color:inherit;word-break:normal}.pre-scrollable{max-height:340px;overflow-y:scroll}.container{width:100%;padding-right:15px;padding-left:15px;margin-right:auto;margin-left:auto}@media (min-width:576px){.container{max-width:540px}}@media (min-width:768px){.container{max-width:720px}}@media (min-width:992px){.container{max-width:960px}}@media (min-width:1200px){.container{max-width:1140px}}.container-fluid{width:100%;padding-right:15px;padding-left:15px;margin-right:auto;margin-left:auto}.row{display:-ms-flexbox;display:flex;-ms-flex-wrap:wrap;flex-wrap:wrap;margin-right:-15px;margin-left:-15px}.no-gutters{margin-right:0;margin-left:0}.no-gutters>.col,.no-gutters>[class*=col-]{padding-right:0;padding-left:0}.col,.col-1,.col-10,.col-11,.col-12,.col-2,.col-3,.col-4,.col-5,.col-6,.col-7,.col-8,.col-9,.col-auto,.col-lg,.col-lg-1,.col-lg-10,.col-lg-11,.col-lg-12,.col-lg-2,.col-lg-3,.col-lg-4,.col-lg-5,.col-lg-6,.col-lg-7,.col-lg-8,.col-lg-9,.col-lg-auto,.col-md,.col-md-1,.col-md-10,.col-md-11,.col-md-12,.col-md-2,.col-md-3,.col-md-4,.col-md-5,.col-md-6,.col-md-7,.col-md-8,.col-md-9,.col-md-auto,.col-sm,.col-sm-1,.col-sm-10,.col-sm-11,.col-sm-12,.col-sm-2,.col-sm-3,.col-sm-4,.col-sm-5,.col-sm-6,.col-sm-7,.col-sm-8,.col-sm-9,.col-sm-auto,.col-xl,.col-xl-1,.col-xl-10,.col-xl-11,.col-xl-12,.col-xl-2,.col-xl-3,.col-xl-4,.col-xl-5,.col-xl-6,.col-xl-7,.col-xl-8,.col-xl-9,.col-xl-auto{position:relative;width:100%;min-height:1px;padding-right:15px;padding-left:15px}.col{-ms-flex-preferred-size:0;flex-basis:0;-ms-flex-positive:1;flex-grow:1;max-width:100%}.col-auto{-ms-flex:0 0 auto;flex:0 0 auto;width:auto;max-width:none}.col-1{-ms-flex:0 0 8.333333%;flex:0 0 8.333333%;max-width:8.333333%}.col-2{-ms-flex:0 0 16.666667%;flex:0 0 16.666667%;max-width:16.666667%}.col-3{-ms-flex:0 0 25%;flex:0 0 25%;max-width:25%}.col-4{-ms-flex:0 0 33.333333%;flex:0 0 33.333333%;max-width:33.333333%}.col-5{-ms-flex:0 0 41.666667%;flex:0 0 41.666667%;max-width:41.666667%}.col-6{-ms-flex:0 0 50%;flex:0 0 50%;max-width:50%}.col-7{-ms-flex:0 0 58.333333%;flex:0 0 58.333333%;max-width:58.333333%}.col-8{-ms-flex:0 0 66.666667%;flex:0 0 66.666667%;max-width:66.666667%}.col-9{-ms-flex:0 0 75%;flex:0 0 75%;max-width:75%}.col-10{-ms-flex:0 0 83.333333%;flex:0 0 83.333333%;max-width:83.333333%}.col-11{-ms-flex:0 0 91.666667%;flex:0 0 91.666667%;max-width:91.666667%}.col-12{-ms-flex:0 0 100%;flex:0 0 100%;max-width:100%}.order-first{-ms-flex-order:-1;order:-1}.order-last{-ms-flex-order:13;order:13}.order-0{-ms-flex-order:0;order:0}.order-1{-ms-flex-order:1;order:1}.order-2{-ms-flex-order:2;order:2}.order-3{-ms-flex-order:3;order:3}.order-4{-ms-flex-order:4;order:4}.order-5{-ms-flex-order:5;order:5}.order-6{-ms-flex-order:6;order:6}.order-7{-ms-flex-order:7;order:7}.order-8{-ms-flex-order:8;order:8}.order-9{-ms-flex-order:9;order:9}.order-10{-ms-flex-order:10;order:10}.order-11{-ms-flex-order:11;order:11}.order-12{-ms-flex-order:12;order:12}.offset-1{margin-left:8.333333%}.offset-2{margin-left:16.666667%}.offset-3{margin-left:25%}.offset-4{margin-left:33.333333%}.offset-5{margin-left:41.666667%}.offset-6{margin-left:50%}.offset-7{margin-left:58.333333%}.offset-8{margin-left:66.666667%}.offset-9{margin-left:75%}.offset-10{margin-left:83.333333%}.offset-11{margin-left:91.666667%}@media (min-width:576px){.col-sm{-ms-flex-preferred-size:0;flex-basis:0;-ms-flex-positive:1;flex-grow:1;max-width:100%}.col-sm-auto{-ms-flex:0 0 auto;flex:0 0 auto;width:auto;max-width:none}.col-sm-1{-ms-flex:0 0 8.333333%;flex:0 0 8.333333%;max-width:8.333333%}.col-sm-2{-ms-flex:0 0 16.666667%;flex:0 0 16.666667%;max-width:16.666667%}.col-sm-3{-ms-flex:0 0 25%;flex:0 0 25%;max-width:25%}.col-sm-4{-ms-flex:0 0 33.333333%;flex:0 0 33.333333%;max-width:33.333333%}.col-sm-5{-ms-flex:0 0 41.666667%;flex:0 0 41.666667%;max-width:41.666667%}.col-sm-6{-ms-flex:0 0 50%;flex:0 0 50%;max-width:50%}.col-sm-7{-ms-flex:0 0 58.333333%;flex:0 0 58.333333%;max-width:58.333333%}.col-sm-8{-ms-flex:0 0 66.666667%;flex:0 0 66.666667%;max-width:66.666667%}.col-sm-9{-ms-flex:0 0 75%;flex:0 0 75%;max-width:75%}.col-sm-10{-ms-flex:0 0 83.333333%;flex:0 0 83.333333%;max-width:83.333333%}.col-sm-11{-ms-flex:0 0 91.666667%;flex:0 0 91.666667%;max-width:91.666667%}.col-sm-12{-ms-flex:0 0 100%;flex:0 0 100%;max-width:100%}.order-sm-first{-ms-flex-order:-1;order:-1}.order-sm-last{-ms-flex-order:13;order:13}.order-sm-0{-ms-flex-order:0;order:0}.order-sm-1{-ms-flex-order:1;order:1}.order-sm-2{-ms-flex-order:2;order:2}.order-sm-3{-ms-flex-order:3;order:3}.order-sm-4{-ms-flex-order:4;order:4}.order-sm-5{-ms-flex-order:5;order:5}.order-sm-6{-ms-flex-order:6;order:6}.order-sm-7{-ms-flex-order:7;order:7}.order-sm-8{-ms-flex-order:8;order:8}.order-sm-9{-ms-flex-order:9;order:9}.order-sm-10{-ms-flex-order:10;order:10}.order-sm-11{-ms-flex-order:11;order:11}.order-sm-12{-ms-flex-order:12;order:12}.offset-sm-0{margin-left:0}.offset-sm-1{margin-left:8.333333%}.offset-sm-2{margin-left:16.666667%}.offset-sm-3{margin-left:25%}.offset-sm-4{margin-left:33.333333%}.offset-sm-5{margin-left:41.666667%}.offset-sm-6{margin-left:50%}.offset-sm-7{margin-left:58.333333%}.offset-sm-8{margin-left:66.666667%}.offset-sm-9{margin-left:75%}.offset-sm-10{margin-left:83.333333%}.offset-sm-11{margin-left:91.666667%}}@media (min-width:768px){.col-md{-ms-flex-preferred-size:0;flex-basis:0;-ms-flex-positive:1;flex-grow:1;max-width:100%}.col-md-auto{-ms-flex:0 0 auto;flex:0 0 auto;width:auto;max-width:none}.col-md-1{-ms-flex:0 0 8.333333%;flex:0 0 8.333333%;max-width:8.333333%}.col-md-2{-ms-flex:0 0 16.666667%;flex:0 0 16.666667%;max-width:16.666667%}.col-md-3{-ms-flex:0 0 25%;flex:0 0 25%;max-width:25%}.col-md-4{-ms-flex:0 0 33.333333%;flex:0 0 33.333333%;max-width:33.333333%}.col-md-5{-ms-flex:0 0 41.666667%;flex:0 0 41.666667%;max-width:41.666667%}.col-md-6{-ms-flex:0 0 50%;flex:0 0 50%;max-width:50%}.col-md-7{-ms-flex:0 0 58.333333%;flex:0 0 58.333333%;max-width:58.333333%}.col-md-8{-ms-flex:0 0 66.666667%;flex:0 0 66.666667%;max-width:66.666667%}.col-md-9{-ms-flex:0 0 75%;flex:0 0 75%;max-width:75%}.col-md-10{-ms-flex:0 0 83.333333%;flex:0 0 83.333333%;max-width:83.333333%}.col-md-11{-ms-flex:0 0 91.666667%;flex:0 0 91.666667%;max-width:91.666667%}.col-md-12{-ms-flex:0 0 100%;flex:0 0 100%;max-width:100%}.order-md-first{-ms-flex-order:-1;order:-1}.order-md-last{-ms-flex-order:13;order:13}.order-md-0{-ms-flex-order:0;order:0}.order-md-1{-ms-flex-order:1;order:1}.order-md-2{-ms-flex-order:2;order:2}.order-md-3{-ms-flex-order:3;order:3}.order-md-4{-ms-flex-order:4;order:4}.order-md-5{-ms-flex-order:5;order:5}.order-md-6{-ms-flex-order:6;order:6}.order-md-7{-ms-flex-order:7;order:7}.order-md-8{-ms-flex-order:8;order:8}.order-md-9{-ms-flex-order:9;order:9}.order-md-10{-ms-flex-order:10;order:10}.order-md-11{-ms-flex-order:11;order:11}.order-md-12{-ms-flex-order:12;order:12}.offset-md-0{margin-left:0}.offset-md-1{margin-left:8.333333%}.offset-md-2{margin-left:16.666667%}.offset-md-3{margin-left:25%}.offset-md-4{margin-left:33.333333%}.offset-md-5{margin-left:41.666667%}.offset-md-6{margin-left:50%}.offset-md-7{margin-left:58.333333%}.offset-md-8{margin-left:66.666667%}.offset-md-9{margin-left:75%}.offset-md-10{margin-left:83.333333%}.offset-md-11{margin-left:91.666667%}}@media (min-width:992px){.col-lg{-ms-flex-preferred-size:0;flex-basis:0;-ms-flex-positive:1;flex-grow:1;max-width:100%}.col-lg-auto{-ms-flex:0 0 auto;flex:0 0 auto;width:auto;max-width:none}.col-lg-1{-ms-flex:0 0 8.333333%;flex:0 0 8.333333%;max-width:8.333333%}.col-lg-2{-ms-flex:0 0 16.666667%;flex:0 0 16.666667%;max-width:16.666667%}.col-lg-3{-ms-flex:0 0 25%;flex:0 0 25%;max-width:25%}.col-lg-4{-ms-flex:0 0 33.333333%;flex:0 0 33.333333%;max-width:33.333333%}.col-lg-5{-ms-flex:0 0 41.666667%;flex:0 0 41.666667%;max-width:41.666667%}.col-lg-6{-ms-flex:0 0 50%;flex:0 0 50%;max-width:50%}.col-lg-7{-ms-flex:0 0 58.333333%;flex:0 0 58.333333%;max-width:58.333333%}.col-lg-8{-ms-flex:0 0 66.666667%;flex:0 0 66.666667%;max-width:66.666667%}.col-lg-9{-ms-flex:0 0 75%;flex:0 0 75%;max-width:75%}.col-lg-10{-ms-flex:0 0 83.333333%;flex:0 0 83.333333%;max-width:83.333333%}.col-lg-11{-ms-flex:0 0 91.666667%;flex:0 0 91.666667%;max-width:91.666667%}.col-lg-12{-ms-flex:0 0 100%;flex:0 0 100%;max-width:100%}.order-lg-first{-ms-flex-order:-1;order:-1}.order-lg-last{-ms-flex-order:13;order:13}.order-lg-0{-ms-flex-order:0;order:0}.order-lg-1{-ms-flex-order:1;order:1}.order-lg-2{-ms-flex-order:2;order:2}.order-lg-3{-ms-flex-order:3;order:3}.order-lg-4{-ms-flex-order:4;order:4}.order-lg-5{-ms-flex-order:5;order:5}.order-lg-6{-ms-flex-order:6;order:6}.order-lg-7{-ms-flex-order:7;order:7}.order-lg-8{-ms-flex-order:8;order:8}.order-lg-9{-ms-flex-order:9;order:9}.order-lg-10{-ms-flex-order:10;order:10}.order-lg-11{-ms-flex-order:11;order:11}.order-lg-12{-ms-flex-order:12;order:12}.offset-lg-0{margin-left:0}.offset-lg-1{margin-left:8.333333%}.offset-lg-2{margin-left:16.666667%}.offset-lg-3{margin-left:25%}.offset-lg-4{margin-left:33.333333%}.offset-lg-5{margin-left:41.666667%}.offset-lg-6{margin-left:50%}.offset-lg-7{margin-left:58.333333%}.offset-lg-8{margin-left:66.666667%}.offset-lg-9{margin-left:75%}.offset-lg-10{margin-left:83.333333%}.offset-lg-11{margin-left:91.666667%}}@media (min-width:1200px){.col-xl{-ms-flex-preferred-size:0;flex-basis:0;-ms-flex-positive:1;flex-grow:1;max-width:100%}.col-xl-auto{-ms-flex:0 0 auto;flex:0 0 auto;width:auto;max-width:none}.col-xl-1{-ms-flex:0 0 8.333333%;flex:0 0 8.333333%;max-width:8.333333%}.col-xl-2{-ms-flex:0 0 16.666667%;flex:0 0 16.666667%;max-width:16.666667%}.col-xl-3{-ms-flex:0 0 25%;flex:0 0 25%;max-width:25%}.col-xl-4{-ms-flex:0 0 33.333333%;flex:0 0 33.333333%;max-width:33.333333%}.col-xl-5{-ms-flex:0 0 41.666667%;flex:0 0 41.666667%;max-width:41.666667%}.col-xl-6{-ms-flex:0 0 50%;flex:0 0 50%;max-width:50%}.col-xl-7{-ms-flex:0 0 58.333333%;flex:0 0 58.333333%;max-width:58.333333%}.col-xl-8{-ms-flex:0 0 66.666667%;flex:0 0 66.666667%;max-width:66.666667%}.col-xl-9{-ms-flex:0 0 75%;flex:0 0 75%;max-width:75%}.col-xl-10{-ms-flex:0 0 83.333333%;flex:0 0 83.333333%;max-width:83.333333%}.col-xl-11{-ms-flex:0 0 91.666667%;flex:0 0 91.666667%;max-width:91.666667%}.col-xl-12{-ms-flex:0 0 100%;flex:0 0 100%;max-width:100%}.order-xl-first{-ms-flex-order:-1;order:-1}.order-xl-last{-ms-flex-order:13;order:13}.order-xl-0{-ms-flex-order:0;order:0}.order-xl-1{-ms-flex-order:1;order:1}.order-xl-2{-ms-flex-order:2;order:2}.order-xl-3{-ms-flex-order:3;order:3}.order-xl-4{-ms-flex-order:4;order:4}.order-xl-5{-ms-flex-order:5;order:5}.order-xl-6{-ms-flex-order:6;order:6}.order-xl-7{-ms-flex-order:7;order:7}.order-xl-8{-ms-flex-order:8;order:8}.order-xl-9{-ms-flex-order:9;order:9}.order-xl-10{-ms-flex-order:10;order:10}.order-xl-11{-ms-flex-order:11;order:11}.order-xl-12{-ms-flex-order:12;order:12}.offset-xl-0{margin-left:0}.offset-xl-1{margin-left:8.333333%}.offset-xl-2{margin-left:16.666667%}.offset-xl-3{margin-left:25%}.offset-xl-4{margin-left:33.333333%}.offset-xl-5{margin-left:41.666667%}.offset-xl-6{margin-left:50%}.offset-xl-7{margin-left:58.333333%}.offset-xl-8{margin-left:66.666667%}.offset-xl-9{margin-left:75%}.offset-xl-10{margin-left:83.333333%}.offset-xl-11{margin-left:91.666667%}}.table{width:100%;margin-bottom:1rem;background-color:transparent}.table td,.table th{padding:.75rem;vertical-align:top;border-top:1px solid #dee2e6}.table thead th{vertical-align:bottom;border-bottom:2px solid #dee2e6}.table tbody+tbody{border-top:2px solid #dee2e6}.table .table{background-color:#fff}.table-sm td,.table-sm th{padding:.3rem}.table-bordered{border:1px solid #dee2e6}.table-bordered td,.table-bordered th{border:1px solid #dee2e6}.table-bordered thead td,.table-bordered thead th{border-bottom-width:2px}.table-borderless tbody+tbody,.table-borderless td,.table-borderless th,.table-borderless thead th{border:0}.table-striped tbody tr:nth-of-type(odd){background-color:rgba(0,0,0,.05)}.table-hover tbody tr:hover{background-color:rgba(0,0,0,.075)}.table-primary,.table-primary>td,.table-primary>th{background-color:#b8daff}.table-hover .table-primary:hover{background-color:#9fcdff}.table-hover .table-primary:hover>td,.table-hover .table-primary:hover>th{background-color:#9fcdff}.table-secondary,.table-secondary>td,.table-secondary>th{background-color:#d6d8db}.table-hover .table-secondary:hover{background-color:#c8cbcf}.table-hover .table-secondary:hover>td,.table-hover .table-secondary:hover>th{background-color:#c8cbcf}.table-success,.table-success>td,.table-success>th{background-color:#c3e6cb}.table-hover .table-success:hover{background-color:#b1dfbb}.table-hover .table-success:hover>td,.table-hover .table-success:hover>th{background-color:#b1dfbb}.table-info,.table-info>td,.table-info>th{background-color:#bee5eb}.table-hover .table-info:hover{background-color:#abdde5}.table-hover .table-info:hover>td,.table-hover .table-info:hover>th{background-color:#abdde5}.table-warning,.table-warning>td,.table-warning>th{background-color:#ffeeba}.table-hover .table-warning:hover{background-color:#ffe8a1}.table-hover .table-warning:hover>td,.table-hover .table-warning:hover>th{background-color:#ffe8a1}.table-danger,.table-danger>td,.table-danger>th{background-color:#f5c6cb}.table-hover .table-danger:hover{background-color:#f1b0b7}.table-hover .table-danger:hover>td,.table-hover .table-danger:hover>th{background-color:#f1b0b7}.table-light,.table-light>td,.table-light>th{background-color:#fdfdfe}.table-hover .table-light:hover{background-color:#ececf6}.table-hover .table-light:hover>td,.table-hover .table-light:hover>th{background-color:#ececf6}.table-dark,.table-dark>td,.table-dark>th{background-color:#c6c8ca}.table-hover .table-dark:hover{background-color:#b9bbbe}.table-hover .table-dark:hover>td,.table-hover .table-dark:hover>th{background-color:#b9bbbe}.table-active,.table-active>td,.table-active>th{background-color:rgba(0,0,0,.075)}.table-hover .table-active:hover{background-color:rgba(0,0,0,.075)}.table-hover .table-active:hover>td,.table-hover .table-active:hover>th{background-color:rgba(0,0,0,.075)}.table .thead-dark th{color:#fff;background-color:#212529;border-color:#32383e}.table .thead-light th{color:#495057;background-color:#e9ecef;border-color:#dee2e6}.table-dark{color:#fff;background-color:#212529}.table-dark td,.table-dark th,.table-dark thead th{border-color:#32383e}.table-dark.table-bordered{border:0}.table-dark.table-striped tbody tr:nth-of-type(odd){background-color:rgba(255,255,255,.05)}.table-dark.table-hover tbody tr:hover{background-color:rgba(255,255,255,.075)}@media (max-width:575.98px){.table-responsive-sm{display:block;width:100%;overflow-x:auto;-webkit-overflow-scrolling:touch;-ms-overflow-style:-ms-autohiding-scrollbar}.table-responsive-sm>.table-bordered{border:0}}@media (max-width:767.98px){.table-responsive-md{display:block;width:100%;overflow-x:auto;-webkit-overflow-scrolling:touch;-ms-overflow-style:-ms-autohiding-scrollbar}.table-responsive-md>.table-bordered{border:0}}@media (max-width:991.98px){.table-responsive-lg{display:block;width:100%;overflow-x:auto;-webkit-overflow-scrolling:touch;-ms-overflow-style:-ms-autohiding-scrollbar}.table-responsive-lg>.table-bordered{border:0}}@media (max-width:1199.98px){.table-responsive-xl{display:block;width:100%;overflow-x:auto;-webkit-overflow-scrolling:touch;-ms-overflow-style:-ms-autohiding-scrollbar}.table-responsive-xl>.table-bordered{border:0}}.table-responsive{display:block;width:100%;overflow-x:auto;-webkit-overflow-scrolling:touch;-ms-overflow-style:-ms-autohiding-scrollbar}.table-responsive>.table-bordered{border:0}.form-control{display:block;width:100%;height:calc(2.25rem + 2px);padding:.375rem .75rem;font-size:1rem;line-height:1.5;color:#495057;background-color:#fff;background-clip:padding-box;border:1px solid #ced4da;border-radius:.25rem;transition:border-color .15s ease-in-out,box-shadow .15s ease-in-out}@media screen and (prefers-reduced-motion:reduce){.form-control{transition:none}}.form-control::-ms-expand{background-color:transparent;border:0}.form-control:focus{color:#495057;background-color:#fff;border-color:#80bdff;outline:0;box-shadow:0 0 0 .2rem rgba(0,123,255,.25)}.form-control::-webkit-input-placeholder{color:#6c757d;opacity:1}.form-control::-moz-placeholder{color:#6c757d;opacity:1}.form-control:-ms-input-placeholder{color:#6c757d;opacity:1}.form-control::-ms-input-placeholder{color:#6c757d;opacity:1}.form-control::placeholder{color:#6c757d;opacity:1}.form-control:disabled,.form-control[readonly]{background-color:#e9ecef;opacity:1}select.form-control:focus::-ms-value{color:#495057;background-color:#fff}.form-control-file,.form-control-range{display:block;width:100%}.col-form-label{padding-top:calc(.375rem + 1px);padding-bottom:calc(.375rem + 1px);margin-bottom:0;font-size:inherit;line-height:1.5}.col-form-label-lg{padding-top:calc(.5rem + 1px);padding-bottom:calc(.5rem + 1px);font-size:1.25rem;line-height:1.5}.col-form-label-sm{padding-top:calc(.25rem + 1px);padding-bottom:calc(.25rem + 1px);font-size:.875rem;line-height:1.5}.form-control-plaintext{display:block;width:100%;padding-top:.375rem;padding-bottom:.375rem;margin-bottom:0;line-height:1.5;color:#212529;background-color:transparent;border:solid transparent;border-width:1px 0}.form-control-plaintext.form-control-lg,.form-control-plaintext.form-control-sm{padding-right:0;padding-left:0}.form-control-sm{height:calc(1.8125rem + 2px);padding:.25rem .5rem;font-size:.875rem;line-height:1.5;border-radius:.2rem}.form-control-lg{height:calc(2.875rem + 2px);padding:.5rem 1rem;font-size:1.25rem;line-height:1.5;border-radius:.3rem}select.form-control[multiple],select.form-control[size]{height:auto}textarea.form-control{height:auto}.form-group{margin-bottom:1rem}.form-text{display:block;margin-top:.25rem}.form-row{display:-ms-flexbox;display:flex;-ms-flex-wrap:wrap;flex-wrap:wrap;margin-right:-5px;margin-left:-5px}.form-row>.col,.form-row>[class*=col-]{padding-right:5px;padding-left:5px}.form-check{position:relative;display:block;padding-left:1.25rem}.form-check-input{position:absolute;margin-top:.3rem;margin-left:-1.25rem}.form-check-input:disabled~.form-check-label{color:#6c757d}.form-check-label{margin-bottom:0}.form-check-inline{display:-ms-inline-flexbox;display:inline-flex;-ms-flex-align:center;align-items:center;padding-left:0;margin-right:.75rem}.form-check-inline .form-check-input{position:static;margin-top:0;margin-right:.3125rem;margin-left:0}.valid-feedback{display:none;width:100%;margin-top:.25rem;font-size:80%;color:#28a745}.valid-tooltip{position:absolute;top:100%;z-index:5;display:none;max-width:100%;padding:.25rem .5rem;margin-top:.1rem;font-size:.875rem;line-height:1.5;color:#fff;background-color:rgba(40,167,69,.9);border-radius:.25rem}.custom-select.is-valid,.form-control.is-valid,.was-validated .custom-select:valid,.was-validated .form-control:valid{border-color:#28a745}.custom-select.is-valid:focus,.form-control.is-valid:focus,.was-validated .custom-select:valid:focus,.was-validated .form-control:valid:focus{border-color:#28a745;box-shadow:0 0 0 .2rem rgba(40,167,69,.25)}.custom-select.is-valid~.valid-feedback,.custom-select.is-valid~.valid-tooltip,.form-control.is-valid~.valid-feedback,.form-control.is-valid~.valid-tooltip,.was-validated .custom-select:valid~.valid-feedback,.was-validated .custom-select:valid~.valid-tooltip,.was-validated .form-control:valid~.valid-feedback,.was-validated .form-control:valid~.valid-tooltip{display:block}.form-control-file.is-valid~.valid-feedback,.form-control-file.is-valid~.valid-tooltip,.was-validated .form-control-file:valid~.valid-feedback,.was-validated .form-control-file:valid~.valid-tooltip{display:block}.form-check-input.is-valid~.form-check-label,.was-validated .form-check-input:valid~.form-check-label{color:#28a745}.form-check-input.is-valid~.valid-feedback,.form-check-input.is-valid~.valid-tooltip,.was-validated .form-check-input:valid~.valid-feedback,.was-validated .form-check-input:valid~.valid-tooltip{display:block}.custom-control-input.is-valid~.custom-control-label,.was-validated .custom-control-input:valid~.custom-control-label{color:#28a745}.custom-control-input.is-valid~.custom-control-label::before,.was-validated .custom-control-input:valid~.custom-control-label::before{background-color:#71dd8a}.custom-control-input.is-valid~.valid-feedback,.custom-control-input.is-valid~.valid-tooltip,.was-validated .custom-control-input:valid~.valid-feedback,.was-validated .custom-control-input:valid~.valid-tooltip{display:block}.custom-control-input.is-valid:checked~.custom-control-label::before,.was-validated .custom-control-input:valid:checked~.custom-control-label::before{background-color:#34ce57}.custom-control-input.is-valid:focus~.custom-control-label::before,.was-validated .custom-control-input:valid:focus~.custom-control-label::before{box-shadow:0 0 0 1px #fff,0 0 0 .2rem rgba(40,167,69,.25)}.custom-file-input.is-valid~.custom-file-label,.was-validated .custom-file-input:valid~.custom-file-label{border-color:#28a745}.custom-file-input.is-valid~.custom-file-label::after,.was-validated .custom-file-input:valid~.custom-file-label::after{border-color:inherit}.custom-file-input.is-valid~.valid-feedback,.custom-file-input.is-valid~.valid-tooltip,.was-validated .custom-file-input:valid~.valid-feedback,.was-validated .custom-file-input:valid~.valid-tooltip{display:block}.custom-file-input.is-valid:focus~.custom-file-label,.was-validated .custom-file-input:valid:focus~.custom-file-label{box-shadow:0 0 0 .2rem rgba(40,167,69,.25)}.invalid-feedback{display:none;width:100%;margin-top:.25rem;font-size:80%;color:#dc3545}.invalid-tooltip{position:absolute;top:100%;z-index:5;display:none;max-width:100%;padding:.25rem .5rem;margin-top:.1rem;font-size:.875rem;line-height:1.5;color:#fff;background-color:rgba(220,53,69,.9);border-radius:.25rem}.custom-select.is-invalid,.form-control.is-invalid,.was-validated .custom-select:invalid,.was-validated .form-control:invalid{border-color:#dc3545}.custom-select.is-invalid:focus,.form-control.is-invalid:focus,.was-validated .custom-select:invalid:focus,.was-validated .form-control:invalid:focus{border-color:#dc3545;box-shadow:0 0 0 .2rem rgba(220,53,69,.25)}.custom-select.is-invalid~.invalid-feedback,.custom-select.is-invalid~.invalid-tooltip,.form-control.is-invalid~.invalid-feedback,.form-control.is-invalid~.invalid-tooltip,.was-validated .custom-select:invalid~.invalid-feedback,.was-validated .custom-select:invalid~.invalid-tooltip,.was-validated .form-control:invalid~.invalid-feedback,.was-validated .form-control:invalid~.invalid-tooltip{display:block}.form-control-file.is-invalid~.invalid-feedback,.form-control-file.is-invalid~.invalid-tooltip,.was-validated .form-control-file:invalid~.invalid-feedback,.was-validated .form-control-file:invalid~.invalid-tooltip{display:block}.form-check-input.is-invalid~.form-check-label,.was-validated .form-check-input:invalid~.form-check-label{color:#dc3545}.form-check-input.is-invalid~.invalid-feedback,.form-check-input.is-invalid~.invalid-tooltip,.was-validated .form-check-input:invalid~.invalid-feedback,.was-validated .form-check-input:invalid~.invalid-tooltip{display:block}.custom-control-input.is-invalid~.custom-control-label,.was-validated .custom-control-input:invalid~.custom-control-label{color:#dc3545}.custom-control-input.is-invalid~.custom-control-label::before,.was-validated .custom-control-input:invalid~.custom-control-label::before{background-color:#efa2a9}.custom-control-input.is-invalid~.invalid-feedback,.custom-control-input.is-invalid~.invalid-tooltip,.was-validated .custom-control-input:invalid~.invalid-feedback,.was-validated .custom-control-input:invalid~.invalid-tooltip{display:block}.custom-control-input.is-invalid:checked~.custom-control-label::before,.was-validated .custom-control-input:invalid:checked~.custom-control-label::before{background-color:#e4606d}.custom-control-input.is-invalid:focus~.custom-control-label::before,.was-validated .custom-control-input:invalid:focus~.custom-control-label::before{box-shadow:0 0 0 1px #fff,0 0 0 .2rem rgba(220,53,69,.25)}.custom-file-input.is-invalid~.custom-file-label,.was-validated .custom-file-input:invalid~.custom-file-label{border-color:#dc3545}.custom-file-input.is-invalid~.custom-file-label::after,.was-validated .custom-file-input:invalid~.custom-file-label::after{border-color:inherit}.custom-file-input.is-invalid~.invalid-feedback,.custom-file-input.is-invalid~.invalid-tooltip,.was-validated .custom-file-input:invalid~.invalid-feedback,.was-validated .custom-file-input:invalid~.invalid-tooltip{display:block}.custom-file-input.is-invalid:focus~.custom-file-label,.was-validated .custom-file-input:invalid:focus~.custom-file-label{box-shadow:0 0 0 .2rem rgba(220,53,69,.25)}.form-inline{display:-ms-flexbox;display:flex;-ms-flex-flow:row wrap;flex-flow:row wrap;-ms-flex-align:center;align-items:center}.form-inline .form-check{width:100%}@media (min-width:576px){.form-inline label{display:-ms-flexbox;display:flex;-ms-flex-align:center;align-items:center;-ms-flex-pack:center;justify-content:center;margin-bottom:0}.form-inline .form-group{display:-ms-flexbox;display:flex;-ms-flex:0 0 auto;flex:0 0 auto;-ms-flex-flow:row wrap;flex-flow:row wrap;-ms-flex-align:center;align-items:center;margin-bottom:0}.form-inline .form-control{display:inline-block;width:auto;vertical-align:middle}.form-inline .form-control-plaintext{display:inline-block}.form-inline .custom-select,.form-inline .input-group{width:auto}.form-inline .form-check{display:-ms-flexbox;display:flex;-ms-flex-align:center;align-items:center;-ms-flex-pack:center;justify-content:center;width:auto;padding-left:0}.form-inline .form-check-input{position:relative;margin-top:0;margin-right:.25rem;margin-left:0}.form-inline .custom-control{-ms-flex-align:center;align-items:center;-ms-flex-pack:center;justify-content:center}.form-inline .custom-control-label{margin-bottom:0}}.btn{display:inline-block;font-weight:400;text-align:center;white-space:nowrap;vertical-align:middle;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none;border:1px solid transparent;padding:.375rem .75rem;font-size:1rem;line-height:1.5;border-radius:.25rem;transition:color .15s ease-in-out,background-color .15s ease-in-out,border-color .15s ease-in-out,box-shadow .15s ease-in-out}@media screen and (prefers-reduced-motion:reduce){.btn{transition:none}}.btn:focus,.btn:hover{text-decoration:none}.btn.focus,.btn:focus{outline:0;box-shadow:0 0 0 .2rem rgba(0,123,255,.25)}.btn.disabled,.btn:disabled{opacity:.65}.btn:not(:disabled):not(.disabled){cursor:pointer}a.btn.disabled,fieldset:disabled a.btn{pointer-events:none}.btn-primary{color:#fff;background-color:#007bff;border-color:#007bff}.btn-primary:hover{color:#fff;background-color:#0069d9;border-color:#0062cc}.btn-primary.focus,.btn-primary:focus{box-shadow:0 0 0 .2rem rgba(0,123,255,.5)}.btn-primary.disabled,.btn-primary:disabled{color:#fff;background-color:#007bff;border-color:#007bff}.btn-primary:not(:disabled):not(.disabled).active,.btn-primary:not(:disabled):not(.disabled):active,.show>.btn-primary.dropdown-toggle{color:#fff;background-color:#0062cc;border-color:#005cbf}.btn-primary:not(:disabled):not(.disabled).active:focus,.btn-primary:not(:disabled):not(.disabled):active:focus,.show>.btn-primary.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(0,123,255,.5)}.btn-secondary{color:#fff;background-color:#6c757d;border-color:#6c757d}.btn-secondary:hover{color:#fff;background-color:#5a6268;border-color:#545b62}.btn-secondary.focus,.btn-secondary:focus{box-shadow:0 0 0 .2rem rgba(108,117,125,.5)}.btn-secondary.disabled,.btn-secondary:disabled{color:#fff;background-color:#6c757d;border-color:#6c757d}.btn-secondary:not(:disabled):not(.disabled).active,.btn-secondary:not(:disabled):not(.disabled):active,.show>.btn-secondary.dropdown-toggle{color:#fff;background-color:#545b62;border-color:#4e555b}.btn-secondary:not(:disabled):not(.disabled).active:focus,.btn-secondary:not(:disabled):not(.disabled):active:focus,.show>.btn-secondary.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(108,117,125,.5)}.btn-success{color:#fff;background-color:#28a745;border-color:#28a745}.btn-success:hover{color:#fff;background-color:#218838;border-color:#1e7e34}.btn-success.focus,.btn-success:focus{box-shadow:0 0 0 .2rem rgba(40,167,69,.5)}.btn-success.disabled,.btn-success:disabled{color:#fff;background-color:#28a745;border-color:#28a745}.btn-success:not(:disabled):not(.disabled).active,.btn-success:not(:disabled):not(.disabled):active,.show>.btn-success.dropdown-toggle{color:#fff;background-color:#1e7e34;border-color:#1c7430}.btn-success:not(:disabled):not(.disabled).active:focus,.btn-success:not(:disabled):not(.disabled):active:focus,.show>.btn-success.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(40,167,69,.5)}.btn-info{color:#fff;background-color:#17a2b8;border-color:#17a2b8}.btn-info:hover{color:#fff;background-color:#138496;border-color:#117a8b}.btn-info.focus,.btn-info:focus{box-shadow:0 0 0 .2rem rgba(23,162,184,.5)}.btn-info.disabled,.btn-info:disabled{color:#fff;background-color:#17a2b8;border-color:#17a2b8}.btn-info:not(:disabled):not(.disabled).active,.btn-info:not(:disabled):not(.disabled):active,.show>.btn-info.dropdown-toggle{color:#fff;background-color:#117a8b;border-color:#10707f}.btn-info:not(:disabled):not(.disabled).active:focus,.btn-info:not(:disabled):not(.disabled):active:focus,.show>.btn-info.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(23,162,184,.5)}.btn-warning{color:#212529;background-color:#ffc107;border-color:#ffc107}.btn-warning:hover{color:#212529;background-color:#e0a800;border-color:#d39e00}.btn-warning.focus,.btn-warning:focus{box-shadow:0 0 0 .2rem rgba(255,193,7,.5)}.btn-warning.disabled,.btn-warning:disabled{color:#212529;background-color:#ffc107;border-color:#ffc107}.btn-warning:not(:disabled):not(.disabled).active,.btn-warning:not(:disabled):not(.disabled):active,.show>.btn-warning.dropdown-toggle{color:#212529;background-color:#d39e00;border-color:#c69500}.btn-warning:not(:disabled):not(.disabled).active:focus,.btn-warning:not(:disabled):not(.disabled):active:focus,.show>.btn-warning.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(255,193,7,.5)}.btn-danger{color:#fff;background-color:#dc3545;border-color:#dc3545}.btn-danger:hover{color:#fff;background-color:#c82333;border-color:#bd2130}.btn-danger.focus,.btn-danger:focus{box-shadow:0 0 0 .2rem rgba(220,53,69,.5)}.btn-danger.disabled,.btn-danger:disabled{color:#fff;background-color:#dc3545;border-color:#dc3545}.btn-danger:not(:disabled):not(.disabled).active,.btn-danger:not(:disabled):not(.disabled):active,.show>.btn-danger.dropdown-toggle{color:#fff;background-color:#bd2130;border-color:#b21f2d}.btn-danger:not(:disabled):not(.disabled).active:focus,.btn-danger:not(:disabled):not(.disabled):active:focus,.show>.btn-danger.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(220,53,69,.5)}.btn-light{color:#212529;background-color:#f8f9fa;border-color:#f8f9fa}.btn-light:hover{color:#212529;background-color:#e2e6ea;border-color:#dae0e5}.btn-light.focus,.btn-light:focus{box-shadow:0 0 0 .2rem rgba(248,249,250,.5)}.btn-light.disabled,.btn-light:disabled{color:#212529;background-color:#f8f9fa;border-color:#f8f9fa}.btn-light:not(:disabled):not(.disabled).active,.btn-light:not(:disabled):not(.disabled):active,.show>.btn-light.dropdown-toggle{color:#212529;background-color:#dae0e5;border-color:#d3d9df}.btn-light:not(:disabled):not(.disabled).active:focus,.btn-light:not(:disabled):not(.disabled):active:focus,.show>.btn-light.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(248,249,250,.5)}.btn-dark{color:#fff;background-color:#343a40;border-color:#343a40}.btn-dark:hover{color:#fff;background-color:#23272b;border-color:#1d2124}.btn-dark.focus,.btn-dark:focus{box-shadow:0 0 0 .2rem rgba(52,58,64,.5)}.btn-dark.disabled,.btn-dark:disabled{color:#fff;background-color:#343a40;border-color:#343a40}.btn-dark:not(:disabled):not(.disabled).active,.btn-dark:not(:disabled):not(.disabled):active,.show>.btn-dark.dropdown-toggle{color:#fff;background-color:#1d2124;border-color:#171a1d}.btn-dark:not(:disabled):not(.disabled).active:focus,.btn-dark:not(:disabled):not(.disabled):active:focus,.show>.btn-dark.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(52,58,64,.5)}.btn-outline-primary{color:#007bff;background-color:transparent;background-image:none;border-color:#007bff}.btn-outline-primary:hover{color:#fff;background-color:#007bff;border-color:#007bff}.btn-outline-primary.focus,.btn-outline-primary:focus{box-shadow:0 0 0 .2rem rgba(0,123,255,.5)}.btn-outline-primary.disabled,.btn-outline-primary:disabled{color:#007bff;background-color:transparent}.btn-outline-primary:not(:disabled):not(.disabled).active,.btn-outline-primary:not(:disabled):not(.disabled):active,.show>.btn-outline-primary.dropdown-toggle{color:#fff;background-color:#007bff;border-color:#007bff}.btn-outline-primary:not(:disabled):not(.disabled).active:focus,.btn-outline-primary:not(:disabled):not(.disabled):active:focus,.show>.btn-outline-primary.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(0,123,255,.5)}.btn-outline-secondary{color:#6c757d;background-color:transparent;background-image:none;border-color:#6c757d}.btn-outline-secondary:hover{color:#fff;background-color:#6c757d;border-color:#6c757d}.btn-outline-secondary.focus,.btn-outline-secondary:focus{box-shadow:0 0 0 .2rem rgba(108,117,125,.5)}.btn-outline-secondary.disabled,.btn-outline-secondary:disabled{color:#6c757d;background-color:transparent}.btn-outline-secondary:not(:disabled):not(.disabled).active,.btn-outline-secondary:not(:disabled):not(.disabled):active,.show>.btn-outline-secondary.dropdown-toggle{color:#fff;background-color:#6c757d;border-color:#6c757d}.btn-outline-secondary:not(:disabled):not(.disabled).active:focus,.btn-outline-secondary:not(:disabled):not(.disabled):active:focus,.show>.btn-outline-secondary.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(108,117,125,.5)}.btn-outline-success{color:#28a745;background-color:transparent;background-image:none;border-color:#28a745}.btn-outline-success:hover{color:#fff;background-color:#28a745;border-color:#28a745}.btn-outline-success.focus,.btn-outline-success:focus{box-shadow:0 0 0 .2rem rgba(40,167,69,.5)}.btn-outline-success.disabled,.btn-outline-success:disabled{color:#28a745;background-color:transparent}.btn-outline-success:not(:disabled):not(.disabled).active,.btn-outline-success:not(:disabled):not(.disabled):active,.show>.btn-outline-success.dropdown-toggle{color:#fff;background-color:#28a745;border-color:#28a745}.btn-outline-success:not(:disabled):not(.disabled).active:focus,.btn-outline-success:not(:disabled):not(.disabled):active:focus,.show>.btn-outline-success.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(40,167,69,.5)}.btn-outline-info{color:#17a2b8;background-color:transparent;background-image:none;border-color:#17a2b8}.btn-outline-info:hover{color:#fff;background-color:#17a2b8;border-color:#17a2b8}.btn-outline-info.focus,.btn-outline-info:focus{box-shadow:0 0 0 .2rem rgba(23,162,184,.5)}.btn-outline-info.disabled,.btn-outline-info:disabled{color:#17a2b8;background-color:transparent}.btn-outline-info:not(:disabled):not(.disabled).active,.btn-outline-info:not(:disabled):not(.disabled):active,.show>.btn-outline-info.dropdown-toggle{color:#fff;background-color:#17a2b8;border-color:#17a2b8}.btn-outline-info:not(:disabled):not(.disabled).active:focus,.btn-outline-info:not(:disabled):not(.disabled):active:focus,.show>.btn-outline-info.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(23,162,184,.5)}.btn-outline-warning{color:#ffc107;background-color:transparent;background-image:none;border-color:#ffc107}.btn-outline-warning:hover{color:#212529;background-color:#ffc107;border-color:#ffc107}.btn-outline-warning.focus,.btn-outline-warning:focus{box-shadow:0 0 0 .2rem rgba(255,193,7,.5)}.btn-outline-warning.disabled,.btn-outline-warning:disabled{color:#ffc107;background-color:transparent}.btn-outline-warning:not(:disabled):not(.disabled).active,.btn-outline-warning:not(:disabled):not(.disabled):active,.show>.btn-outline-warning.dropdown-toggle{color:#212529;background-color:#ffc107;border-color:#ffc107}.btn-outline-warning:not(:disabled):not(.disabled).active:focus,.btn-outline-warning:not(:disabled):not(.disabled):active:focus,.show>.btn-outline-warning.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(255,193,7,.5)}.btn-outline-danger{color:#dc3545;background-color:transparent;background-image:none;border-color:#dc3545}.btn-outline-danger:hover{color:#fff;background-color:#dc3545;border-color:#dc3545}.btn-outline-danger.focus,.btn-outline-danger:focus{box-shadow:0 0 0 .2rem rgba(220,53,69,.5)}.btn-outline-danger.disabled,.btn-outline-danger:disabled{color:#dc3545;background-color:transparent}.btn-outline-danger:not(:disabled):not(.disabled).active,.btn-outline-danger:not(:disabled):not(.disabled):active,.show>.btn-outline-danger.dropdown-toggle{color:#fff;background-color:#dc3545;border-color:#dc3545}.btn-outline-danger:not(:disabled):not(.disabled).active:focus,.btn-outline-danger:not(:disabled):not(.disabled):active:focus,.show>.btn-outline-danger.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(220,53,69,.5)}.btn-outline-light{color:#f8f9fa;background-color:transparent;background-image:none;border-color:#f8f9fa}.btn-outline-light:hover{color:#212529;background-color:#f8f9fa;border-color:#f8f9fa}.btn-outline-light.focus,.btn-outline-light:focus{box-shadow:0 0 0 .2rem rgba(248,249,250,.5)}.btn-outline-light.disabled,.btn-outline-light:disabled{color:#f8f9fa;background-color:transparent}.btn-outline-light:not(:disabled):not(.disabled).active,.btn-outline-light:not(:disabled):not(.disabled):active,.show>.btn-outline-light.dropdown-toggle{color:#212529;background-color:#f8f9fa;border-color:#f8f9fa}.btn-outline-light:not(:disabled):not(.disabled).active:focus,.btn-outline-light:not(:disabled):not(.disabled):active:focus,.show>.btn-outline-light.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(248,249,250,.5)}.btn-outline-dark{color:#343a40;background-color:transparent;background-image:none;border-color:#343a40}.btn-outline-dark:hover{color:#fff;background-color:#343a40;border-color:#343a40}.btn-outline-dark.focus,.btn-outline-dark:focus{box-shadow:0 0 0 .2rem rgba(52,58,64,.5)}.btn-outline-dark.disabled,.btn-outline-dark:disabled{color:#343a40;background-color:transparent}.btn-outline-dark:not(:disabled):not(.disabled).active,.btn-outline-dark:not(:disabled):not(.disabled):active,.show>.btn-outline-dark.dropdown-toggle{color:#fff;background-color:#343a40;border-color:#343a40}.btn-outline-dark:not(:disabled):not(.disabled).active:focus,.btn-outline-dark:not(:disabled):not(.disabled):active:focus,.show>.btn-outline-dark.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(52,58,64,.5)}.btn-link{font-weight:400;color:#007bff;background-color:transparent}.btn-link:hover{color:#0056b3;text-decoration:underline;background-color:transparent;border-color:transparent}.btn-link.focus,.btn-link:focus{text-decoration:underline;border-color:transparent;box-shadow:none}.btn-link.disabled,.btn-link:disabled{color:#6c757d;pointer-events:none}.btn-group-lg>.btn,.btn-lg{padding:.5rem 1rem;font-size:1.25rem;line-height:1.5;border-radius:.3rem}.btn-group-sm>.btn,.btn-sm{padding:.25rem .5rem;font-size:.875rem;line-height:1.5;border-radius:.2rem}.btn-block{display:block;width:100%}.btn-block+.btn-block{margin-top:.5rem}input[type=button].btn-block,input[type=reset].btn-block,input[type=submit].btn-block{width:100%}.fade{transition:opacity .15s linear}@media screen and (prefers-reduced-motion:reduce){.fade{transition:none}}.fade:not(.show){opacity:0}.collapse:not(.show){display:none}.collapsing{position:relative;height:0;overflow:hidden;transition:height .35s ease}@media screen and (prefers-reduced-motion:reduce){.collapsing{transition:none}}.dropdown,.dropleft,.dropright,.dropup{position:relative}.dropdown-toggle::after{display:inline-block;width:0;height:0;margin-left:.255em;vertical-align:.255em;content:"";border-top:.3em solid;border-right:.3em solid transparent;border-bottom:0;border-left:.3em solid transparent}.dropdown-toggle:empty::after{margin-left:0}.dropdown-menu{position:absolute;top:100%;left:0;z-index:1000;display:none;float:left;min-width:10rem;padding:.5rem 0;margin:.125rem 0 0;font-size:1rem;color:#212529;text-align:left;list-style:none;background-color:#fff;background-clip:padding-box;border:1px solid rgba(0,0,0,.15);border-radius:.25rem}.dropdown-menu-right{right:0;left:auto}.dropup .dropdown-menu{top:auto;bottom:100%;margin-top:0;margin-bottom:.125rem}.dropup .dropdown-toggle::after{display:inline-block;width:0;height:0;margin-left:.255em;vertical-align:.255em;content:"";border-top:0;border-right:.3em solid transparent;border-bottom:.3em solid;border-left:.3em solid transparent}.dropup .dropdown-toggle:empty::after{margin-left:0}.dropright .dropdown-menu{top:0;right:auto;left:100%;margin-top:0;margin-left:.125rem}.dropright .dropdown-toggle::after{display:inline-block;width:0;height:0;margin-left:.255em;vertical-align:.255em;content:"";border-top:.3em solid transparent;border-right:0;border-bottom:.3em solid transparent;border-left:.3em solid}.dropright .dropdown-toggle:empty::after{margin-left:0}.dropright .dropdown-toggle::after{vertical-align:0}.dropleft .dropdown-menu{top:0;right:100%;left:auto;margin-top:0;margin-right:.125rem}.dropleft .dropdown-toggle::after{display:inline-block;width:0;height:0;margin-left:.255em;vertical-align:.255em;content:""}.dropleft .dropdown-toggle::after{display:none}.dropleft .dropdown-toggle::before{display:inline-block;width:0;height:0;margin-right:.255em;vertical-align:.255em;content:"";border-top:.3em solid transparent;border-right:.3em solid;border-bottom:.3em solid transparent}.dropleft .dropdown-toggle:empty::after{margin-left:0}.dropleft .dropdown-toggle::before{vertical-align:0}.dropdown-menu[x-placement^=bottom],.dropdown-menu[x-placement^=left],.dropdown-menu[x-placement^=right],.dropdown-menu[x-placement^=top]{right:auto;bottom:auto}.dropdown-divider{height:0;margin:.5rem 0;overflow:hidden;border-top:1px solid #e9ecef}.dropdown-item{display:block;width:100%;padding:.25rem 1.5rem;clear:both;font-weight:400;color:#212529;text-align:inherit;white-space:nowrap;background-color:transparent;border:0}.dropdown-item:focus,.dropdown-item:hover{color:#16181b;text-decoration:none;background-color:#f8f9fa}.dropdown-item.active,.dropdown-item:active{color:#fff;text-decoration:none;background-color:#007bff}.dropdown-item.disabled,.dropdown-item:disabled{color:#6c757d;background-color:transparent}.dropdown-menu.show{display:block}.dropdown-header{display:block;padding:.5rem 1.5rem;margin-bottom:0;font-size:.875rem;color:#6c757d;white-space:nowrap}.dropdown-item-text{display:block;padding:.25rem 1.5rem;color:#212529}.btn-group,.btn-group-vertical{position:relative;display:-ms-inline-flexbox;display:inline-flex;vertical-align:middle}.btn-group-vertical>.btn,.btn-group>.btn{position:relative;-ms-flex:0 1 auto;flex:0 1 auto}.btn-group-vertical>.btn:hover,.btn-group>.btn:hover{z-index:1}.btn-group-vertical>.btn.active,.btn-group-vertical>.btn:active,.btn-group-vertical>.btn:focus,.btn-group>.btn.active,.btn-group>.btn:active,.btn-group>.btn:focus{z-index:1}.btn-group .btn+.btn,.btn-group .btn+.btn-group,.btn-group .btn-group+.btn,.btn-group .btn-group+.btn-group,.btn-group-vertical .btn+.btn,.btn-group-vertical .btn+.btn-group,.btn-group-vertical .btn-group+.btn,.btn-group-vertical .btn-group+.btn-group{margin-left:-1px}.btn-toolbar{display:-ms-flexbox;display:flex;-ms-flex-wrap:wrap;flex-wrap:wrap;-ms-flex-pack:start;justify-content:flex-start}.btn-toolbar .input-group{width:auto}.btn-group>.btn:first-child{margin-left:0}.btn-group>.btn-group:not(:last-child)>.btn,.btn-group>.btn:not(:last-child):not(.dropdown-toggle){border-top-right-radius:0;border-bottom-right-radius:0}.btn-group>.btn-group:not(:first-child)>.btn,.btn-group>.btn:not(:first-child){border-top-left-radius:0;border-bottom-left-radius:0}.dropdown-toggle-split{padding-right:.5625rem;padding-left:.5625rem}.dropdown-toggle-split::after,.dropright .dropdown-toggle-split::after,.dropup .dropdown-toggle-split::after{margin-left:0}.dropleft .dropdown-toggle-split::before{margin-right:0}.btn-group-sm>.btn+.dropdown-toggle-split,.btn-sm+.dropdown-toggle-split{padding-right:.375rem;padding-left:.375rem}.btn-group-lg>.btn+.dropdown-toggle-split,.btn-lg+.dropdown-toggle-split{padding-right:.75rem;padding-left:.75rem}.btn-group-vertical{-ms-flex-direction:column;flex-direction:column;-ms-flex-align:start;align-items:flex-start;-ms-flex-pack:center;justify-content:center}.btn-group-vertical .btn,.btn-group-vertical .btn-group{width:100%}.btn-group-vertical>.btn+.btn,.btn-group-vertical>.btn+.btn-group,.btn-group-vertical>.btn-group+.btn,.btn-group-vertical>.btn-group+.btn-group{margin-top:-1px;margin-left:0}.btn-group-vertical>.btn-group:not(:last-child)>.btn,.btn-group-vertical>.btn:not(:last-child):not(.dropdown-toggle){border-bottom-right-radius:0;border-bottom-left-radius:0}.btn-group-vertical>.btn-group:not(:first-child)>.btn,.btn-group-vertical>.btn:not(:first-child){border-top-left-radius:0;border-top-right-radius:0}.btn-group-toggle>.btn,.btn-group-toggle>.btn-group>.btn{margin-bottom:0}.btn-group-toggle>.btn input[type=checkbox],.btn-group-toggle>.btn input[type=radio],.btn-group-toggle>.btn-group>.btn input[type=checkbox],.btn-group-toggle>.btn-group>.btn input[type=radio]{position:absolute;clip:rect(0,0,0,0);pointer-events:none}.input-group{position:relative;display:-ms-flexbox;display:flex;-ms-flex-wrap:wrap;flex-wrap:wrap;-ms-flex-align:stretch;align-items:stretch;width:100%}.input-group>.custom-file,.input-group>.custom-select,.input-group>.form-control{position:relative;-ms-flex:1 1 auto;flex:1 1 auto;width:1%;margin-bottom:0}.input-group>.custom-file+.custom-file,.input-group>.custom-file+.custom-select,.input-group>.custom-file+.form-control,.input-group>.custom-select+.custom-file,.input-group>.custom-select+.custom-select,.input-group>.custom-select+.form-control,.input-group>.form-control+.custom-file,.input-group>.form-control+.custom-select,.input-group>.form-control+.form-control{margin-left:-1px}.input-group>.custom-file .custom-file-input:focus~.custom-file-label,.input-group>.custom-select:focus,.input-group>.form-control:focus{z-index:3}.input-group>.custom-file .custom-file-input:focus{z-index:4}.input-group>.custom-select:not(:last-child),.input-group>.form-control:not(:last-child){border-top-right-radius:0;border-bottom-right-radius:0}.input-group>.custom-select:not(:first-child),.input-group>.form-control:not(:first-child){border-top-left-radius:0;border-bottom-left-radius:0}.input-group>.custom-file{display:-ms-flexbox;display:flex;-ms-flex-align:center;align-items:center}.input-group>.custom-file:not(:last-child) .custom-file-label,.input-group>.custom-file:not(:last-child) .custom-file-label::after{border-top-right-radius:0;border-bottom-right-radius:0}.input-group>.custom-file:not(:first-child) .custom-file-label{border-top-left-radius:0;border-bottom-left-radius:0}.input-group-append,.input-group-prepend{display:-ms-flexbox;display:flex}.input-group-append .btn,.input-group-prepend .btn{position:relative;z-index:2}.input-group-append .btn+.btn,.input-group-append .btn+.input-group-text,.input-group-append .input-group-text+.btn,.input-group-append .input-group-text+.input-group-text,.input-group-prepend .btn+.btn,.input-group-prepend .btn+.input-group-text,.input-group-prepend .input-group-text+.btn,.input-group-prepend .input-group-text+.input-group-text{margin-left:-1px}.input-group-prepend{margin-right:-1px}.input-group-append{margin-left:-1px}.input-group-text{display:-ms-flexbox;display:flex;-ms-flex-align:center;align-items:center;padding:.375rem .75rem;margin-bottom:0;font-size:1rem;font-weight:400;line-height:1.5;color:#495057;text-align:center;white-space:nowrap;background-color:#e9ecef;border:1px solid #ced4da;border-radius:.25rem}.input-group-text input[type=checkbox],.input-group-text input[type=radio]{margin-top:0}.input-group-lg>.form-control,.input-group-lg>.input-group-append>.btn,.input-group-lg>.input-group-append>.input-group-text,.input-group-lg>.input-group-prepend>.btn,.input-group-lg>.input-group-prepend>.input-group-text{height:calc(2.875rem + 2px);padding:.5rem 1rem;font-size:1.25rem;line-height:1.5;border-radius:.3rem}.input-group-sm>.form-control,.input-group-sm>.input-group-append>.btn,.input-group-sm>.input-group-append>.input-group-text,.input-group-sm>.input-group-prepend>.btn,.input-group-sm>.input-group-prepend>.input-group-text{height:calc(1.8125rem + 2px);padding:.25rem .5rem;font-size:.875rem;line-height:1.5;border-radius:.2rem}.input-group>.input-group-append:last-child>.btn:not(:last-child):not(.dropdown-toggle),.input-group>.input-group-append:last-child>.input-group-text:not(:last-child),.input-group>.input-group-append:not(:last-child)>.btn,.input-group>.input-group-append:not(:last-child)>.input-group-text,.input-group>.input-group-prepend>.btn,.input-group>.input-group-prepend>.input-group-text{border-top-right-radius:0;border-bottom-right-radius:0}.input-group>.input-group-append>.btn,.input-group>.input-group-append>.input-group-text,.input-group>.input-group-prepend:first-child>.btn:not(:first-child),.input-group>.input-group-prepend:first-child>.input-group-text:not(:first-child),.input-group>.input-group-prepend:not(:first-child)>.btn,.input-group>.input-group-prepend:not(:first-child)>.input-group-text{border-top-left-radius:0;border-bottom-left-radius:0}.custom-control{position:relative;display:block;min-height:1.5rem;padding-left:1.5rem}.custom-control-inline{display:-ms-inline-flexbox;display:inline-flex;margin-right:1rem}.custom-control-input{position:absolute;z-index:-1;opacity:0}.custom-control-input:checked~.custom-control-label::before{color:#fff;background-color:#007bff}.custom-control-input:focus~.custom-control-label::before{box-shadow:0 0 0 1px #fff,0 0 0 .2rem rgba(0,123,255,.25)}.custom-control-input:active~.custom-control-label::before{color:#fff;background-color:#b3d7ff}.custom-control-input:disabled~.custom-control-label{color:#6c757d}.custom-control-input:disabled~.custom-control-label::before{background-color:#e9ecef}.custom-control-label{position:relative;margin-bottom:0}.custom-control-label::before{position:absolute;top:.25rem;left:-1.5rem;display:block;width:1rem;height:1rem;pointer-events:none;content:"";-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none;background-color:#dee2e6}.custom-control-label::after{position:absolute;top:.25rem;left:-1.5rem;display:block;width:1rem;height:1rem;content:"";background-repeat:no-repeat;background-position:center center;background-size:50% 50%}.custom-checkbox .custom-control-label::before{border-radius:.25rem}.custom-checkbox .custom-control-input:checked~.custom-control-label::before{background-color:#007bff}.custom-checkbox .custom-control-input:checked~.custom-control-label::after{background-image:url("data:image/svg+xml;charset=utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 8 8'%3E%3Cpath fill='%23fff' d='M6.564.75l-3.59 3.612-1.538-1.55L0 4.26 2.974 7.25 8 2.193z'/%3E%3C/svg%3E")}.custom-checkbox .custom-control-input:indeterminate~.custom-control-label::before{background-color:#007bff}.custom-checkbox .custom-control-input:indeterminate~.custom-control-label::after{background-image:url("data:image/svg+xml;charset=utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 4 4'%3E%3Cpath stroke='%23fff' d='M0 2h4'/%3E%3C/svg%3E")}.custom-checkbox .custom-control-input:disabled:checked~.custom-control-label::before{background-color:rgba(0,123,255,.5)}.custom-checkbox .custom-control-input:disabled:indeterminate~.custom-control-label::before{background-color:rgba(0,123,255,.5)}.custom-radio .custom-control-label::before{border-radius:50%}.custom-radio .custom-control-input:checked~.custom-control-label::before{background-color:#007bff}.custom-radio .custom-control-input:checked~.custom-control-label::after{background-image:url("data:image/svg+xml;charset=utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='-4 -4 8 8'%3E%3Ccircle r='3' fill='%23fff'/%3E%3C/svg%3E")}.custom-radio .custom-control-input:disabled:checked~.custom-control-label::before{background-color:rgba(0,123,255,.5)}.custom-select{display:inline-block;width:100%;height:calc(2.25rem + 2px);padding:.375rem 1.75rem .375rem .75rem;line-height:1.5;color:#495057;vertical-align:middle;background:#fff url("data:image/svg+xml;charset=utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 4 5'%3E%3Cpath fill='%23343a40' d='M2 0L0 2h4zm0 5L0 3h4z'/%3E%3C/svg%3E") no-repeat right .75rem center;background-size:8px 10px;border:1px solid #ced4da;border-radius:.25rem;-webkit-appearance:none;-moz-appearance:none;appearance:none}.custom-select:focus{border-color:#80bdff;outline:0;box-shadow:0 0 0 .2rem rgba(128,189,255,.5)}.custom-select:focus::-ms-value{color:#495057;background-color:#fff}.custom-select[multiple],.custom-select[size]:not([size="1"]){height:auto;padding-right:.75rem;background-image:none}.custom-select:disabled{color:#6c757d;background-color:#e9ecef}.custom-select::-ms-expand{opacity:0}.custom-select-sm{height:calc(1.8125rem + 2px);padding-top:.375rem;padding-bottom:.375rem;font-size:75%}.custom-select-lg{height:calc(2.875rem + 2px);padding-top:.375rem;padding-bottom:.375rem;font-size:125%}.custom-file{position:relative;display:inline-block;width:100%;height:calc(2.25rem + 2px);margin-bottom:0}.custom-file-input{position:relative;z-index:2;width:100%;height:calc(2.25rem + 2px);margin:0;opacity:0}.custom-file-input:focus~.custom-file-label{border-color:#80bdff;box-shadow:0 0 0 .2rem rgba(0,123,255,.25)}.custom-file-input:focus~.custom-file-label::after{border-color:#80bdff}.custom-file-input:disabled~.custom-file-label{background-color:#e9ecef}.custom-file-input:lang(en)~.custom-file-label::after{content:"Browse"}.custom-file-label{position:absolute;top:0;right:0;left:0;z-index:1;height:calc(2.25rem + 2px);padding:.375rem .75rem;line-height:1.5;color:#495057;background-color:#fff;border:1px solid #ced4da;border-radius:.25rem}.custom-file-label::after{position:absolute;top:0;right:0;bottom:0;z-index:3;display:block;height:2.25rem;padding:.375rem .75rem;line-height:1.5;color:#495057;content:"Browse";background-color:#e9ecef;border-left:1px solid #ced4da;border-radius:0 .25rem .25rem 0}.custom-range{width:100%;padding-left:0;background-color:transparent;-webkit-appearance:none;-moz-appearance:none;appearance:none}.custom-range:focus{outline:0}.custom-range:focus::-webkit-slider-thumb{box-shadow:0 0 0 1px #fff,0 0 0 .2rem rgba(0,123,255,.25)}.custom-range:focus::-moz-range-thumb{box-shadow:0 0 0 1px #fff,0 0 0 .2rem rgba(0,123,255,.25)}.custom-range:focus::-ms-thumb{box-shadow:0 0 0 1px #fff,0 0 0 .2rem rgba(0,123,255,.25)}.custom-range::-moz-focus-outer{border:0}.custom-range::-webkit-slider-thumb{width:1rem;height:1rem;margin-top:-.25rem;background-color:#007bff;border:0;border-radius:1rem;transition:background-color .15s ease-in-out,border-color .15s ease-in-out,box-shadow .15s ease-in-out;-webkit-appearance:none;appearance:none}@media screen and (prefers-reduced-motion:reduce){.custom-range::-webkit-slider-thumb{transition:none}}.custom-range::-webkit-slider-thumb:active{background-color:#b3d7ff}.custom-range::-webkit-slider-runnable-track{width:100%;height:.5rem;color:transparent;cursor:pointer;background-color:#dee2e6;border-color:transparent;border-radius:1rem}.custom-range::-moz-range-thumb{width:1rem;height:1rem;background-color:#007bff;border:0;border-radius:1rem;transition:background-color .15s ease-in-out,border-color .15s ease-in-out,box-shadow .15s ease-in-out;-moz-appearance:none;appearance:none}@media screen and (prefers-reduced-motion:reduce){.custom-range::-moz-range-thumb{transition:none}}.custom-range::-moz-range-thumb:active{background-color:#b3d7ff}.custom-range::-moz-range-track{width:100%;height:.5rem;color:transparent;cursor:pointer;background-color:#dee2e6;border-color:transparent;border-radius:1rem}.custom-range::-ms-thumb{width:1rem;height:1rem;margin-top:0;margin-right:.2rem;margin-left:.2rem;background-color:#007bff;border:0;border-radius:1rem;transition:background-color .15s ease-in-out,border-color .15s ease-in-out,box-shadow .15s ease-in-out;appearance:none}@media screen and (prefers-reduced-motion:reduce){.custom-range::-ms-thumb{transition:none}}.custom-range::-ms-thumb:active{background-color:#b3d7ff}.custom-range::-ms-track{width:100%;height:.5rem;color:transparent;cursor:pointer;background-color:transparent;border-color:transparent;border-width:.5rem}.custom-range::-ms-fill-lower{background-color:#dee2e6;border-radius:1rem}.custom-range::-ms-fill-upper{margin-right:15px;background-color:#dee2e6;border-radius:1rem}.custom-control-label::before,.custom-file-label,.custom-select{transition:background-color .15s ease-in-out,border-color .15s ease-in-out,box-shadow .15s ease-in-out}@media screen and (prefers-reduced-motion:reduce){.custom-control-label::before,.custom-file-label,.custom-select{transition:none}}.nav{display:-ms-flexbox;display:flex;-ms-flex-wrap:wrap;flex-wrap:wrap;padding-left:0;margin-bottom:0;list-style:none}.nav-link{display:block;padding:.5rem 1rem}.nav-link:focus,.nav-link:hover{text-decoration:none}.nav-link.disabled{color:#6c757d}.nav-tabs{border-bottom:1px solid #dee2e6}.nav-tabs .nav-item{margin-bottom:-1px}.nav-tabs .nav-link{border:1px solid transparent;border-top-left-radius:.25rem;border-top-right-radius:.25rem}.nav-tabs .nav-link:focus,.nav-tabs .nav-link:hover{border-color:#e9ecef #e9ecef #dee2e6}.nav-tabs .nav-link.disabled{color:#6c757d;background-color:transparent;border-color:transparent}.nav-tabs .nav-item.show .nav-link,.nav-tabs .nav-link.active{color:#495057;background-color:#fff;border-color:#dee2e6 #dee2e6 #fff}.nav-tabs .dropdown-menu{margin-top:-1px;border-top-left-radius:0;border-top-right-radius:0}.nav-pills .nav-link{border-radius:.25rem}.nav-pills .nav-link.active,.nav-pills .show>.nav-link{color:#fff;background-color:#007bff}.nav-fill .nav-item{-ms-flex:1 1 auto;flex:1 1 auto;text-align:center}.nav-justified .nav-item{-ms-flex-preferred-size:0;flex-basis:0;-ms-flex-positive:1;flex-grow:1;text-align:center}.tab-content>.tab-pane{display:none}.tab-content>.active{display:block}.navbar{position:relative;display:-ms-flexbox;display:flex;-ms-flex-wrap:wrap;flex-wrap:wrap;-ms-flex-align:center;align-items:center;-ms-flex-pack:justify;justify-content:space-between;padding:.5rem 1rem}.navbar>.container,.navbar>.container-fluid{display:-ms-flexbox;display:flex;-ms-flex-wrap:wrap;flex-wrap:wrap;-ms-flex-align:center;align-items:center;-ms-flex-pack:justify;justify-content:space-between}.navbar-brand{display:inline-block;padding-top:.3125rem;padding-bottom:.3125rem;margin-right:1rem;font-size:1.25rem;line-height:inherit;white-space:nowrap}.navbar-brand:focus,.navbar-brand:hover{text-decoration:none}.navbar-nav{display:-ms-flexbox;display:flex;-ms-flex-direction:column;flex-direction:column;padding-left:0;margin-bottom:0;list-style:none}.navbar-nav .nav-link{padding-right:0;padding-left:0}.navbar-nav .dropdown-menu{position:static;float:none}.navbar-text{display:inline-block;padding-top:.5rem;padding-bottom:.5rem}.navbar-collapse{-ms-flex-preferred-size:100%;flex-basis:100%;-ms-flex-positive:1;flex-grow:1;-ms-flex-align:center;align-items:center}.navbar-toggler{padding:.25rem .75rem;font-size:1.25rem;line-height:1;background-color:transparent;border:1px solid transparent;border-radius:.25rem}.navbar-toggler:focus,.navbar-toggler:hover{text-decoration:none}.navbar-toggler:not(:disabled):not(.disabled){cursor:pointer}.navbar-toggler-icon{display:inline-block;width:1.5em;height:1.5em;vertical-align:middle;content:"";background:no-repeat center center;background-size:100% 100%}@media (max-width:575.98px){.navbar-expand-sm>.container,.navbar-expand-sm>.container-fluid{padding-right:0;padding-left:0}}@media (min-width:576px){.navbar-expand-sm{-ms-flex-flow:row nowrap;flex-flow:row nowrap;-ms-flex-pack:start;justify-content:flex-start}.navbar-expand-sm .navbar-nav{-ms-flex-direction:row;flex-direction:row}.navbar-expand-sm .navbar-nav .dropdown-menu{position:absolute}.navbar-expand-sm .navbar-nav .nav-link{padding-right:.5rem;padding-left:.5rem}.navbar-expand-sm>.container,.navbar-expand-sm>.container-fluid{-ms-flex-wrap:nowrap;flex-wrap:nowrap}.navbar-expand-sm .navbar-collapse{display:-ms-flexbox!important;display:flex!important;-ms-flex-preferred-size:auto;flex-basis:auto}.navbar-expand-sm .navbar-toggler{display:none}}@media (max-width:767.98px){.navbar-expand-md>.container,.navbar-expand-md>.container-fluid{padding-right:0;padding-left:0}}@media (min-width:768px){.navbar-expand-md{-ms-flex-flow:row nowrap;flex-flow:row nowrap;-ms-flex-pack:start;justify-content:flex-start}.navbar-expand-md .navbar-nav{-ms-flex-direction:row;flex-direction:row}.navbar-expand-md .navbar-nav .dropdown-menu{position:absolute}.navbar-expand-md .navbar-nav .nav-link{padding-right:.5rem;padding-left:.5rem}.navbar-expand-md>.container,.navbar-expand-md>.container-fluid{-ms-flex-wrap:nowrap;flex-wrap:nowrap}.navbar-expand-md .navbar-collapse{display:-ms-flexbox!important;display:flex!important;-ms-flex-preferred-size:auto;flex-basis:auto}.navbar-expand-md .navbar-toggler{display:none}}@media (max-width:991.98px){.navbar-expand-lg>.container,.navbar-expand-lg>.container-fluid{padding-right:0;padding-left:0}}@media (min-width:992px){.navbar-expand-lg{-ms-flex-flow:row nowrap;flex-flow:row nowrap;-ms-flex-pack:start;justify-content:flex-start}.navbar-expand-lg .navbar-nav{-ms-flex-direction:row;flex-direction:row}.navbar-expand-lg .navbar-nav .dropdown-menu{position:absolute}.navbar-expand-lg .navbar-nav .nav-link{padding-right:.5rem;padding-left:.5rem}.navbar-expand-lg>.container,.navbar-expand-lg>.container-fluid{-ms-flex-wrap:nowrap;flex-wrap:nowrap}.navbar-expand-lg .navbar-collapse{display:-ms-flexbox!important;display:flex!important;-ms-flex-preferred-size:auto;flex-basis:auto}.navbar-expand-lg .navbar-toggler{display:none}}@media (max-width:1199.98px){.navbar-expand-xl>.container,.navbar-expand-xl>.container-fluid{padding-right:0;padding-left:0}}@media (min-width:1200px){.navbar-expand-xl{-ms-flex-flow:row nowrap;flex-flow:row nowrap;-ms-flex-pack:start;justify-content:flex-start}.navbar-expand-xl .navbar-nav{-ms-flex-direction:row;flex-direction:row}.navbar-expand-xl .navbar-nav .dropdown-menu{position:absolute}.navbar-expand-xl .navbar-nav .nav-link{padding-right:.5rem;padding-left:.5rem}.navbar-expand-xl>.container,.navbar-expand-xl>.container-fluid{-ms-flex-wrap:nowrap;flex-wrap:nowrap}.navbar-expand-xl .navbar-collapse{display:-ms-flexbox!important;display:flex!important;-ms-flex-preferred-size:auto;flex-basis:auto}.navbar-expand-xl .navbar-toggler{display:none}}.navbar-expand{-ms-flex-flow:row nowrap;flex-flow:row nowrap;-ms-flex-pack:start;justify-content:flex-start}.navbar-expand>.container,.navbar-expand>.container-fluid{padding-right:0;padding-left:0}.navbar-expand .navbar-nav{-ms-flex-direction:row;flex-direction:row}.navbar-expand .navbar-nav .dropdown-menu{position:absolute}.navbar-expand .navbar-nav .nav-link{padding-right:.5rem;padding-left:.5rem}.navbar-expand>.container,.navbar-expand>.container-fluid{-ms-flex-wrap:nowrap;flex-wrap:nowrap}.navbar-expand .navbar-collapse{display:-ms-flexbox!important;display:flex!important;-ms-flex-preferred-size:auto;flex-basis:auto}.navbar-expand .navbar-toggler{display:none}.navbar-light .navbar-brand{color:rgba(0,0,0,.9)}.navbar-light .navbar-brand:focus,.navbar-light .navbar-brand:hover{color:rgba(0,0,0,.9)}.navbar-light .navbar-nav .nav-link{color:rgba(0,0,0,.5)}.navbar-light .navbar-nav .nav-link:focus,.navbar-light .navbar-nav .nav-link:hover{color:rgba(0,0,0,.7)}.navbar-light .navbar-nav .nav-link.disabled{color:rgba(0,0,0,.3)}.navbar-light .navbar-nav .active>.nav-link,.navbar-light .navbar-nav .nav-link.active,.navbar-light .navbar-nav .nav-link.show,.navbar-light .navbar-nav .show>.nav-link{color:rgba(0,0,0,.9)}.navbar-light .navbar-toggler{color:rgba(0,0,0,.5);border-color:rgba(0,0,0,.1)}.navbar-light .navbar-toggler-icon{background-image:url("data:image/svg+xml;charset=utf8,%3Csvg viewBox='0 0 30 30' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath stroke='rgba(0, 0, 0, 0.5)' stroke-width='2' stroke-linecap='round' stroke-miterlimit='10' d='M4 7h22M4 15h22M4 23h22'/%3E%3C/svg%3E")}.navbar-light .navbar-text{color:rgba(0,0,0,.5)}.navbar-light .navbar-text a{color:rgba(0,0,0,.9)}.navbar-light .navbar-text a:focus,.navbar-light .navbar-text a:hover{color:rgba(0,0,0,.9)}.navbar-dark .navbar-brand{color:#fff}.navbar-dark .navbar-brand:focus,.navbar-dark .navbar-brand:hover{color:#fff}.navbar-dark .navbar-nav .nav-link{color:rgba(255,255,255,.5)}.navbar-dark .navbar-nav .nav-link:focus,.navbar-dark .navbar-nav .nav-link:hover{color:rgba(255,255,255,.75)}.navbar-dark .navbar-nav .nav-link.disabled{color:rgba(255,255,255,.25)}.navbar-dark .navbar-nav .active>.nav-link,.navbar-dark .navbar-nav .nav-link.active,.navbar-dark .navbar-nav .nav-link.show,.navbar-dark .navbar-nav .show>.nav-link{color:#fff}.navbar-dark .navbar-toggler{color:rgba(255,255,255,.5);border-color:rgba(255,255,255,.1)}.navbar-dark .navbar-toggler-icon{background-image:url("data:image/svg+xml;charset=utf8,%3Csvg viewBox='0 0 30 30' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath stroke='rgba(255, 255, 255, 0.5)' stroke-width='2' stroke-linecap='round' stroke-miterlimit='10' d='M4 7h22M4 15h22M4 23h22'/%3E%3C/svg%3E")}.navbar-dark .navbar-text{color:rgba(255,255,255,.5)}.navbar-dark .navbar-text a{color:#fff}.navbar-dark .navbar-text a:focus,.navbar-dark .navbar-text a:hover{color:#fff}.card{position:relative;display:-ms-flexbox;display:flex;-ms-flex-direction:column;flex-direction:column;min-width:0;word-wrap:break-word;background-color:#fff;background-clip:border-box;border:1px solid rgba(0,0,0,.125);border-radius:.25rem}.card>hr{margin-right:0;margin-left:0}.card>.list-group:first-child .list-group-item:first-child{border-top-left-radius:.25rem;border-top-right-radius:.25rem}.card>.list-group:last-child .list-group-item:last-child{border-bottom-right-radius:.25rem;border-bottom-left-radius:.25rem}.card-body{-ms-flex:1 1 auto;flex:1 1 auto;padding:1.25rem}.card-title{margin-bottom:.75rem}.card-subtitle{margin-top:-.375rem;margin-bottom:0}.card-text:last-child{margin-bottom:0}.card-link:hover{text-decoration:none}.card-link+.card-link{margin-left:1.25rem}.card-header{padding:.75rem 1.25rem;margin-bottom:0;background-color:rgba(0,0,0,.03);border-bottom:1px solid rgba(0,0,0,.125)}.card-header:first-child{border-radius:calc(.25rem - 1px) calc(.25rem - 1px) 0 0}.card-header+.list-group .list-group-item:first-child{border-top:0}.card-footer{padding:.75rem 1.25rem;background-color:rgba(0,0,0,.03);border-top:1px solid rgba(0,0,0,.125)}.card-footer:last-child{border-radius:0 0 calc(.25rem - 1px) calc(.25rem - 1px)}.card-header-tabs{margin-right:-.625rem;margin-bottom:-.75rem;margin-left:-.625rem;border-bottom:0}.card-header-pills{margin-right:-.625rem;margin-left:-.625rem}.card-img-overlay{position:absolute;top:0;right:0;bottom:0;left:0;padding:1.25rem}.card-img{width:100%;border-radius:calc(.25rem - 1px)}.card-img-top{width:100%;border-top-left-radius:calc(.25rem - 1px);border-top-right-radius:calc(.25rem - 1px)}.card-img-bottom{width:100%;border-bottom-right-radius:calc(.25rem - 1px);border-bottom-left-radius:calc(.25rem - 1px)}.card-deck{display:-ms-flexbox;display:flex;-ms-flex-direction:column;flex-direction:column}.card-deck .card{margin-bottom:15px}@media (min-width:576px){.card-deck{-ms-flex-flow:row wrap;flex-flow:row wrap;margin-right:-15px;margin-left:-15px}.card-deck .card{display:-ms-flexbox;display:flex;-ms-flex:1 0 0%;flex:1 0 0%;-ms-flex-direction:column;flex-direction:column;margin-right:15px;margin-bottom:0;margin-left:15px}}.card-group{display:-ms-flexbox;display:flex;-ms-flex-direction:column;flex-direction:column}.card-group>.card{margin-bottom:15px}@media (min-width:576px){.card-group{-ms-flex-flow:row wrap;flex-flow:row wrap}.card-group>.card{-ms-flex:1 0 0%;flex:1 0 0%;margin-bottom:0}.card-group>.card+.card{margin-left:0;border-left:0}.card-group>.card:first-child{border-top-right-radius:0;border-bottom-right-radius:0}.card-group>.card:first-child .card-header,.card-group>.card:first-child .card-img-top{border-top-right-radius:0}.card-group>.card:first-child .card-footer,.card-group>.card:first-child .card-img-bottom{border-bottom-right-radius:0}.card-group>.card:last-child{border-top-left-radius:0;border-bottom-left-radius:0}.card-group>.card:last-child .card-header,.card-group>.card:last-child .card-img-top{border-top-left-radius:0}.card-group>.card:last-child .card-footer,.card-group>.card:last-child .card-img-bottom{border-bottom-left-radius:0}.card-group>.card:only-child{border-radius:.25rem}.card-group>.card:only-child .card-header,.card-group>.card:only-child .card-img-top{border-top-left-radius:.25rem;border-top-right-radius:.25rem}.card-group>.card:only-child .card-footer,.card-group>.card:only-child .card-img-bottom{border-bottom-right-radius:.25rem;border-bottom-left-radius:.25rem}.card-group>.card:not(:first-child):not(:last-child):not(:only-child){border-radius:0}.card-group>.card:not(:first-child):not(:last-child):not(:only-child) .card-footer,.card-group>.card:not(:first-child):not(:last-child):not(:only-child) .card-header,.card-group>.card:not(:first-child):not(:last-child):not(:only-child) .card-img-bottom,.card-group>.card:not(:first-child):not(:last-child):not(:only-child) .card-img-top{border-radius:0}}.card-columns .card{margin-bottom:.75rem}@media (min-width:576px){.card-columns{-webkit-column-count:3;-moz-column-count:3;column-count:3;-webkit-column-gap:1.25rem;-moz-column-gap:1.25rem;column-gap:1.25rem;orphans:1;widows:1}.card-columns .card{display:inline-block;width:100%}}.accordion .card:not(:first-of-type):not(:last-of-type){border-bottom:0;border-radius:0}.accordion .card:not(:first-of-type) .card-header:first-child{border-radius:0}.accordion .card:first-of-type{border-bottom:0;border-bottom-right-radius:0;border-bottom-left-radius:0}.accordion .card:last-of-type{border-top-left-radius:0;border-top-right-radius:0}.breadcrumb{display:-ms-flexbox;display:flex;-ms-flex-wrap:wrap;flex-wrap:wrap;padding:.75rem 1rem;margin-bottom:1rem;list-style:none;background-color:#e9ecef;border-radius:.25rem}.breadcrumb-item+.breadcrumb-item{padding-left:.5rem}.breadcrumb-item+.breadcrumb-item::before{display:inline-block;padding-right:.5rem;color:#6c757d;content:"/"}.breadcrumb-item+.breadcrumb-item:hover::before{text-decoration:underline}.breadcrumb-item+.breadcrumb-item:hover::before{text-decoration:none}.breadcrumb-item.active{color:#6c757d}.pagination{display:-ms-flexbox;display:flex;padding-left:0;list-style:none;border-radius:.25rem}.page-link{position:relative;display:block;padding:.5rem .75rem;margin-left:-1px;line-height:1.25;color:#007bff;background-color:#fff;border:1px solid #dee2e6}.page-link:hover{z-index:2;color:#0056b3;text-decoration:none;background-color:#e9ecef;border-color:#dee2e6}.page-link:focus{z-index:2;outline:0;box-shadow:0 0 0 .2rem rgba(0,123,255,.25)}.page-link:not(:disabled):not(.disabled){cursor:pointer}.page-item:first-child .page-link{margin-left:0;border-top-left-radius:.25rem;border-bottom-left-radius:.25rem}.page-item:last-child .page-link{border-top-right-radius:.25rem;border-bottom-right-radius:.25rem}.page-item.active .page-link{z-index:1;color:#fff;background-color:#007bff;border-color:#007bff}.page-item.disabled .page-link{color:#6c757d;pointer-events:none;cursor:auto;background-color:#fff;border-color:#dee2e6}.pagination-lg .page-link{padding:.75rem 1.5rem;font-size:1.25rem;line-height:1.5}.pagination-lg .page-item:first-child .page-link{border-top-left-radius:.3rem;border-bottom-left-radius:.3rem}.pagination-lg .page-item:last-child .page-link{border-top-right-radius:.3rem;border-bottom-right-radius:.3rem}.pagination-sm .page-link{padding:.25rem .5rem;font-size:.875rem;line-height:1.5}.pagination-sm .page-item:first-child .page-link{border-top-left-radius:.2rem;border-bottom-left-radius:.2rem}.pagination-sm .page-item:last-child .page-link{border-top-right-radius:.2rem;border-bottom-right-radius:.2rem}.badge{display:inline-block;padding:.25em .4em;font-size:75%;font-weight:700;line-height:1;text-align:center;white-space:nowrap;vertical-align:baseline;border-radius:.25rem}.badge:empty{display:none}.btn .badge{position:relative;top:-1px}.badge-pill{padding-right:.6em;padding-left:.6em;border-radius:10rem}.badge-primary{color:#fff;background-color:#007bff}.badge-primary[href]:focus,.badge-primary[href]:hover{color:#fff;text-decoration:none;background-color:#0062cc}.badge-secondary{color:#fff;background-color:#6c757d}.badge-secondary[href]:focus,.badge-secondary[href]:hover{color:#fff;text-decoration:none;background-color:#545b62}.badge-success{color:#fff;background-color:#28a745}.badge-success[href]:focus,.badge-success[href]:hover{color:#fff;text-decoration:none;background-color:#1e7e34}.badge-info{color:#fff;background-color:#17a2b8}.badge-info[href]:focus,.badge-info[href]:hover{color:#fff;text-decoration:none;background-color:#117a8b}.badge-warning{color:#212529;background-color:#ffc107}.badge-warning[href]:focus,.badge-warning[href]:hover{color:#212529;text-decoration:none;background-color:#d39e00}.badge-danger{color:#fff;background-color:#dc3545}.badge-danger[href]:focus,.badge-danger[href]:hover{color:#fff;text-decoration:none;background-color:#bd2130}.badge-light{color:#212529;background-color:#f8f9fa}.badge-light[href]:focus,.badge-light[href]:hover{color:#212529;text-decoration:none;background-color:#dae0e5}.badge-dark{color:#fff;background-color:#343a40}.badge-dark[href]:focus,.badge-dark[href]:hover{color:#fff;text-decoration:none;background-color:#1d2124}.jumbotron{padding:2rem 1rem;margin-bottom:2rem;background-color:#e9ecef;border-radius:.3rem}@media (min-width:576px){.jumbotron{padding:4rem 2rem}}.jumbotron-fluid{padding-right:0;padding-left:0;border-radius:0}.alert{position:relative;padding:.75rem 1.25rem;margin-bottom:1rem;border:1px solid transparent;border-radius:.25rem}.alert-heading{color:inherit}.alert-link{font-weight:700}.alert-dismissible{padding-right:4rem}.alert-dismissible .close{position:absolute;top:0;right:0;padding:.75rem 1.25rem;color:inherit}.alert-primary{color:#004085;background-color:#cce5ff;border-color:#b8daff}.alert-primary hr{border-top-color:#9fcdff}.alert-primary .alert-link{color:#002752}.alert-secondary{color:#383d41;background-color:#e2e3e5;border-color:#d6d8db}.alert-secondary hr{border-top-color:#c8cbcf}.alert-secondary .alert-link{color:#202326}.alert-success{color:#155724;background-color:#d4edda;border-color:#c3e6cb}.alert-success hr{border-top-color:#b1dfbb}.alert-success .alert-link{color:#0b2e13}.alert-info{color:#0c5460;background-color:#d1ecf1;border-color:#bee5eb}.alert-info hr{border-top-color:#abdde5}.alert-info .alert-link{color:#062c33}.alert-warning{color:#856404;background-color:#fff3cd;border-color:#ffeeba}.alert-warning hr{border-top-color:#ffe8a1}.alert-warning .alert-link{color:#533f03}.alert-danger{color:#721c24;background-color:#f8d7da;border-color:#f5c6cb}.alert-danger hr{border-top-color:#f1b0b7}.alert-danger .alert-link{color:#491217}.alert-light{color:#818182;background-color:#fefefe;border-color:#fdfdfe}.alert-light hr{border-top-color:#ececf6}.alert-light .alert-link{color:#686868}.alert-dark{color:#1b1e21;background-color:#d6d8d9;border-color:#c6c8ca}.alert-dark hr{border-top-color:#b9bbbe}.alert-dark .alert-link{color:#040505}@-webkit-keyframes progress-bar-stripes{from{background-position:1rem 0}to{background-position:0 0}}@keyframes progress-bar-stripes{from{background-position:1rem 0}to{background-position:0 0}}.progress{display:-ms-flexbox;display:flex;height:1rem;overflow:hidden;font-size:.75rem;background-color:#e9ecef;border-radius:.25rem}.progress-bar{display:-ms-flexbox;display:flex;-ms-flex-direction:column;flex-direction:column;-ms-flex-pack:center;justify-content:center;color:#fff;text-align:center;white-space:nowrap;background-color:#007bff;transition:width .6s ease}@media screen and (prefers-reduced-motion:reduce){.progress-bar{transition:none}}.progress-bar-striped{background-image:linear-gradient(45deg,rgba(255,255,255,.15) 25%,transparent 25%,transparent 50%,rgba(255,255,255,.15) 50%,rgba(255,255,255,.15) 75%,transparent 75%,transparent);background-size:1rem 1rem}.progress-bar-animated{-webkit-animation:progress-bar-stripes 1s linear infinite;animation:progress-bar-stripes 1s linear infinite}.media{display:-ms-flexbox;display:flex;-ms-flex-align:start;align-items:flex-start}.media-body{-ms-flex:1;flex:1}.list-group{display:-ms-flexbox;display:flex;-ms-flex-direction:column;flex-direction:column;padding-left:0;margin-bottom:0}.list-group-item-action{width:100%;color:#495057;text-align:inherit}.list-group-item-action:focus,.list-group-item-action:hover{color:#495057;text-decoration:none;background-color:#f8f9fa}.list-group-item-action:active{color:#212529;background-color:#e9ecef}.list-group-item{position:relative;display:block;padding:.75rem 1.25rem;margin-bottom:-1px;background-color:#fff;border:1px solid rgba(0,0,0,.125)}.list-group-item:first-child{border-top-left-radius:.25rem;border-top-right-radius:.25rem}.list-group-item:last-child{margin-bottom:0;border-bottom-right-radius:.25rem;border-bottom-left-radius:.25rem}.list-group-item:focus,.list-group-item:hover{z-index:1;text-decoration:none}.list-group-item.disabled,.list-group-item:disabled{color:#6c757d;background-color:#fff}.list-group-item.active{z-index:2;color:#fff;background-color:#007bff;border-color:#007bff}.list-group-flush .list-group-item{border-right:0;border-left:0;border-radius:0}.list-group-flush:first-child .list-group-item:first-child{border-top:0}.list-group-flush:last-child .list-group-item:last-child{border-bottom:0}.list-group-item-primary{color:#004085;background-color:#b8daff}.list-group-item-primary.list-group-item-action:focus,.list-group-item-primary.list-group-item-action:hover{color:#004085;background-color:#9fcdff}.list-group-item-primary.list-group-item-action.active{color:#fff;background-color:#004085;border-color:#004085}.list-group-item-secondary{color:#383d41;background-color:#d6d8db}.list-group-item-secondary.list-group-item-action:focus,.list-group-item-secondary.list-group-item-action:hover{color:#383d41;background-color:#c8cbcf}.list-group-item-secondary.list-group-item-action.active{color:#fff;background-color:#383d41;border-color:#383d41}.list-group-item-success{color:#155724;background-color:#c3e6cb}.list-group-item-success.list-group-item-action:focus,.list-group-item-success.list-group-item-action:hover{color:#155724;background-color:#b1dfbb}.list-group-item-success.list-group-item-action.active{color:#fff;background-color:#155724;border-color:#155724}.list-group-item-info{color:#0c5460;background-color:#bee5eb}.list-group-item-info.list-group-item-action:focus,.list-group-item-info.list-group-item-action:hover{color:#0c5460;background-color:#abdde5}.list-group-item-info.list-group-item-action.active{color:#fff;background-color:#0c5460;border-color:#0c5460}.list-group-item-warning{color:#856404;background-color:#ffeeba}.list-group-item-warning.list-group-item-action:focus,.list-group-item-warning.list-group-item-action:hover{color:#856404;background-color:#ffe8a1}.list-group-item-warning.list-group-item-action.active{color:#fff;background-color:#856404;border-color:#856404}.list-group-item-danger{color:#721c24;background-color:#f5c6cb}.list-group-item-danger.list-group-item-action:focus,.list-group-item-danger.list-group-item-action:hover{color:#721c24;background-color:#f1b0b7}.list-group-item-danger.list-group-item-action.active{color:#fff;background-color:#721c24;border-color:#721c24}.list-group-item-light{color:#818182;background-color:#fdfdfe}.list-group-item-light.list-group-item-action:focus,.list-group-item-light.list-group-item-action:hover{color:#818182;background-color:#ececf6}.list-group-item-light.list-group-item-action.active{color:#fff;background-color:#818182;border-color:#818182}.list-group-item-dark{color:#1b1e21;background-color:#c6c8ca}.list-group-item-dark.list-group-item-action:focus,.list-group-item-dark.list-group-item-action:hover{color:#1b1e21;background-color:#b9bbbe}.list-group-item-dark.list-group-item-action.active{color:#fff;background-color:#1b1e21;border-color:#1b1e21}.close{float:right;font-size:1.5rem;font-weight:700;line-height:1;color:#000;text-shadow:0 1px 0 #fff;opacity:.5}.close:not(:disabled):not(.disabled){cursor:pointer}.close:not(:disabled):not(.disabled):focus,.close:not(:disabled):not(.disabled):hover{color:#000;text-decoration:none;opacity:.75}button.close{padding:0;background-color:transparent;border:0;-webkit-appearance:none}.modal-open{overflow:hidden}.modal-open .modal{overflow-x:hidden;overflow-y:auto}.modal{position:fixed;top:0;right:0;bottom:0;left:0;z-index:1050;display:none;overflow:hidden;outline:0}.modal-dialog{position:relative;width:auto;margin:.5rem;pointer-events:none}.modal.fade .modal-dialog{transition:-webkit-transform .3s ease-out;transition:transform .3s ease-out;transition:transform .3s ease-out,-webkit-transform .3s ease-out;-webkit-transform:translate(0,-25%);transform:translate(0,-25%)}@media screen and (prefers-reduced-motion:reduce){.modal.fade .modal-dialog{transition:none}}.modal.show .modal-dialog{-webkit-transform:translate(0,0);transform:translate(0,0)}.modal-dialog-centered{display:-ms-flexbox;display:flex;-ms-flex-align:center;align-items:center;min-height:calc(100% - (.5rem * 2))}.modal-dialog-centered::before{display:block;height:calc(100vh - (.5rem * 2));content:""}.modal-content{position:relative;display:-ms-flexbox;display:flex;-ms-flex-direction:column;flex-direction:column;width:100%;pointer-events:auto;background-color:#fff;background-clip:padding-box;border:1px solid rgba(0,0,0,.2);border-radius:.3rem;outline:0}.modal-backdrop{position:fixed;top:0;right:0;bottom:0;left:0;z-index:1040;background-color:#000}.modal-backdrop.fade{opacity:0}.modal-backdrop.show{opacity:.5}.modal-header{display:-ms-flexbox;display:flex;-ms-flex-align:start;align-items:flex-start;-ms-flex-pack:justify;justify-content:space-between;padding:1rem;border-bottom:1px solid #e9ecef;border-top-left-radius:.3rem;border-top-right-radius:.3rem}.modal-header .close{padding:1rem;margin:-1rem -1rem -1rem auto}.modal-title{margin-bottom:0;line-height:1.5}.modal-body{position:relative;-ms-flex:1 1 auto;flex:1 1 auto;padding:1rem}.modal-footer{display:-ms-flexbox;display:flex;-ms-flex-align:center;align-items:center;-ms-flex-pack:end;justify-content:flex-end;padding:1rem;border-top:1px solid #e9ecef}.modal-footer>:not(:first-child){margin-left:.25rem}.modal-footer>:not(:last-child){margin-right:.25rem}.modal-scrollbar-measure{position:absolute;top:-9999px;width:50px;height:50px;overflow:scroll}@media (min-width:576px){.modal-dialog{max-width:500px;margin:1.75rem auto}.modal-dialog-centered{min-height:calc(100% - (1.75rem * 2))}.modal-dialog-centered::before{height:calc(100vh - (1.75rem * 2))}.modal-sm{max-width:300px}}@media (min-width:992px){.modal-lg{max-width:800px}}.tooltip{position:absolute;z-index:1070;display:block;margin:0;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol","Noto Color Emoji";font-style:normal;font-weight:400;line-height:1.5;text-align:left;text-align:start;text-decoration:none;text-shadow:none;text-transform:none;letter-spacing:normal;word-break:normal;word-spacing:normal;white-space:normal;line-break:auto;font-size:.875rem;word-wrap:break-word;opacity:0}.tooltip.show{opacity:.9}.tooltip .arrow{position:absolute;display:block;width:.8rem;height:.4rem}.tooltip .arrow::before{position:absolute;content:"";border-color:transparent;border-style:solid}.bs-tooltip-auto[x-placement^=top],.bs-tooltip-top{padding:.4rem 0}.bs-tooltip-auto[x-placement^=top] .arrow,.bs-tooltip-top .arrow{bottom:0}.bs-tooltip-auto[x-placement^=top] .arrow::before,.bs-tooltip-top .arrow::before{top:0;border-width:.4rem .4rem 0;border-top-color:#000}.bs-tooltip-auto[x-placement^=right],.bs-tooltip-right{padding:0 .4rem}.bs-tooltip-auto[x-placement^=right] .arrow,.bs-tooltip-right .arrow{left:0;width:.4rem;height:.8rem}.bs-tooltip-auto[x-placement^=right] .arrow::before,.bs-tooltip-right .arrow::before{right:0;border-width:.4rem .4rem .4rem 0;border-right-color:#000}.bs-tooltip-auto[x-placement^=bottom],.bs-tooltip-bottom{padding:.4rem 0}.bs-tooltip-auto[x-placement^=bottom] .arrow,.bs-tooltip-bottom .arrow{top:0}.bs-tooltip-auto[x-placement^=bottom] .arrow::before,.bs-tooltip-bottom .arrow::before{bottom:0;border-width:0 .4rem .4rem;border-bottom-color:#000}.bs-tooltip-auto[x-placement^=left],.bs-tooltip-left{padding:0 .4rem}.bs-tooltip-auto[x-placement^=left] .arrow,.bs-tooltip-left .arrow{right:0;width:.4rem;height:.8rem}.bs-tooltip-auto[x-placement^=left] .arrow::before,.bs-tooltip-left .arrow::before{left:0;border-width:.4rem 0 .4rem .4rem;border-left-color:#000}.tooltip-inner{max-width:200px;padding:.25rem .5rem;color:#fff;text-align:center;background-color:#000;border-radius:.25rem}.popover{position:absolute;top:0;left:0;z-index:1060;display:block;max-width:276px;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol","Noto Color Emoji";font-style:normal;font-weight:400;line-height:1.5;text-align:left;text-align:start;text-decoration:none;text-shadow:none;text-transform:none;letter-spacing:normal;word-break:normal;word-spacing:normal;white-space:normal;line-break:auto;font-size:.875rem;word-wrap:break-word;background-color:#fff;background-clip:padding-box;border:1px solid rgba(0,0,0,.2);border-radius:.3rem}.popover .arrow{position:absolute;display:block;width:1rem;height:.5rem;margin:0 .3rem}.popover .arrow::after,.popover .arrow::before{position:absolute;display:block;content:"";border-color:transparent;border-style:solid}.bs-popover-auto[x-placement^=top],.bs-popover-top{margin-bottom:.5rem}.bs-popover-auto[x-placement^=top] .arrow,.bs-popover-top .arrow{bottom:calc((.5rem + 1px) * -1)}.bs-popover-auto[x-placement^=top] .arrow::after,.bs-popover-auto[x-placement^=top] .arrow::before,.bs-popover-top .arrow::after,.bs-popover-top .arrow::before{border-width:.5rem .5rem 0}.bs-popover-auto[x-placement^=top] .arrow::before,.bs-popover-top .arrow::before{bottom:0;border-top-color:rgba(0,0,0,.25)}.bs-popover-auto[x-placement^=top] .arrow::after,.bs-popover-top .arrow::after{bottom:1px;border-top-color:#fff}.bs-popover-auto[x-placement^=right],.bs-popover-right{margin-left:.5rem}.bs-popover-auto[x-placement^=right] .arrow,.bs-popover-right .arrow{left:calc((.5rem + 1px) * -1);width:.5rem;height:1rem;margin:.3rem 0}.bs-popover-auto[x-placement^=right] .arrow::after,.bs-popover-auto[x-placement^=right] .arrow::before,.bs-popover-right .arrow::after,.bs-popover-right .arrow::before{border-width:.5rem .5rem .5rem 0}.bs-popover-auto[x-placement^=right] .arrow::before,.bs-popover-right .arrow::before{left:0;border-right-color:rgba(0,0,0,.25)}.bs-popover-auto[x-placement^=right] .arrow::after,.bs-popover-right .arrow::after{left:1px;border-right-color:#fff}.bs-popover-auto[x-placement^=bottom],.bs-popover-bottom{margin-top:.5rem}.bs-popover-auto[x-placement^=bottom] .arrow,.bs-popover-bottom .arrow{top:calc((.5rem + 1px) * -1)}.bs-popover-auto[x-placement^=bottom] .arrow::after,.bs-popover-auto[x-placement^=bottom] .arrow::before,.bs-popover-bottom .arrow::after,.bs-popover-bottom .arrow::before{border-width:0 .5rem .5rem .5rem}.bs-popover-auto[x-placement^=bottom] .arrow::before,.bs-popover-bottom .arrow::before{top:0;border-bottom-color:rgba(0,0,0,.25)}.bs-popover-auto[x-placement^=bottom] .arrow::after,.bs-popover-bottom .arrow::after{top:1px;border-bottom-color:#fff}.bs-popover-auto[x-placement^=bottom] .popover-header::before,.bs-popover-bottom .popover-header::before{position:absolute;top:0;left:50%;display:block;width:1rem;margin-left:-.5rem;content:"";border-bottom:1px solid #f7f7f7}.bs-popover-auto[x-placement^=left],.bs-popover-left{margin-right:.5rem}.bs-popover-auto[x-placement^=left] .arrow,.bs-popover-left .arrow{right:calc((.5rem + 1px) * -1);width:.5rem;height:1rem;margin:.3rem 0}.bs-popover-auto[x-placement^=left] .arrow::after,.bs-popover-auto[x-placement^=left] .arrow::before,.bs-popover-left .arrow::after,.bs-popover-left .arrow::before{border-width:.5rem 0 .5rem .5rem}.bs-popover-auto[x-placement^=left] .arrow::before,.bs-popover-left .arrow::before{right:0;border-left-color:rgba(0,0,0,.25)}.bs-popover-auto[x-placement^=left] .arrow::after,.bs-popover-left .arrow::after{right:1px;border-left-color:#fff}.popover-header{padding:.5rem .75rem;margin-bottom:0;font-size:1rem;color:inherit;background-color:#f7f7f7;border-bottom:1px solid #ebebeb;border-top-left-radius:calc(.3rem - 1px);border-top-right-radius:calc(.3rem - 1px)}.popover-header:empty{display:none}.popover-body{padding:.5rem .75rem;color:#212529}.carousel{position:relative}.carousel-inner{position:relative;width:100%;overflow:hidden}.carousel-item{position:relative;display:none;-ms-flex-align:center;align-items:center;width:100%;-webkit-backface-visibility:hidden;backface-visibility:hidden;-webkit-perspective:1000px;perspective:1000px}.carousel-item-next,.carousel-item-prev,.carousel-item.active{display:block;transition:-webkit-transform .6s ease;transition:transform .6s ease;transition:transform .6s ease,-webkit-transform .6s ease}@media screen and (prefers-reduced-motion:reduce){.carousel-item-next,.carousel-item-prev,.carousel-item.active{transition:none}}.carousel-item-next,.carousel-item-prev{position:absolute;top:0}.carousel-item-next.carousel-item-left,.carousel-item-prev.carousel-item-right{-webkit-transform:translateX(0);transform:translateX(0)}@supports ((-webkit-transform-style:preserve-3d) or (transform-style:preserve-3d)){.carousel-item-next.carousel-item-left,.carousel-item-prev.carousel-item-right{-webkit-transform:translate3d(0,0,0);transform:translate3d(0,0,0)}}.active.carousel-item-right,.carousel-item-next{-webkit-transform:translateX(100%);transform:translateX(100%)}@supports ((-webkit-transform-style:preserve-3d) or (transform-style:preserve-3d)){.active.carousel-item-right,.carousel-item-next{-webkit-transform:translate3d(100%,0,0);transform:translate3d(100%,0,0)}}.active.carousel-item-left,.carousel-item-prev{-webkit-transform:translateX(-100%);transform:translateX(-100%)}@supports ((-webkit-transform-style:preserve-3d) or (transform-style:preserve-3d)){.active.carousel-item-left,.carousel-item-prev{-webkit-transform:translate3d(-100%,0,0);transform:translate3d(-100%,0,0)}}.carousel-fade .carousel-item{opacity:0;transition-duration:.6s;transition-property:opacity}.carousel-fade .carousel-item-next.carousel-item-left,.carousel-fade .carousel-item-prev.carousel-item-right,.carousel-fade .carousel-item.active{opacity:1}.carousel-fade .active.carousel-item-left,.carousel-fade .active.carousel-item-right{opacity:0}.carousel-fade .active.carousel-item-left,.carousel-fade .active.carousel-item-prev,.carousel-fade .carousel-item-next,.carousel-fade .carousel-item-prev,.carousel-fade .carousel-item.active{-webkit-transform:translateX(0);transform:translateX(0)}@supports ((-webkit-transform-style:preserve-3d) or (transform-style:preserve-3d)){.carousel-fade .active.carousel-item-left,.carousel-fade .active.carousel-item-prev,.carousel-fade .carousel-item-next,.carousel-fade .carousel-item-prev,.carousel-fade .carousel-item.active{-webkit-transform:translate3d(0,0,0);transform:translate3d(0,0,0)}}.carousel-control-next,.carousel-control-prev{position:absolute;top:0;bottom:0;display:-ms-flexbox;display:flex;-ms-flex-align:center;align-items:center;-ms-flex-pack:center;justify-content:center;width:15%;color:#fff;text-align:center;opacity:.5}.carousel-control-next:focus,.carousel-control-next:hover,.carousel-control-prev:focus,.carousel-control-prev:hover{color:#fff;text-decoration:none;outline:0;opacity:.9}.carousel-control-prev{left:0}.carousel-control-next{right:0}.carousel-control-next-icon,.carousel-control-prev-icon{display:inline-block;width:20px;height:20px;background:transparent no-repeat center center;background-size:100% 100%}.carousel-control-prev-icon{background-image:url("data:image/svg+xml;charset=utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' fill='%23fff' viewBox='0 0 8 8'%3E%3Cpath d='M5.25 0l-4 4 4 4 1.5-1.5-2.5-2.5 2.5-2.5-1.5-1.5z'/%3E%3C/svg%3E")}.carousel-control-next-icon{background-image:url("data:image/svg+xml;charset=utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' fill='%23fff' viewBox='0 0 8 8'%3E%3Cpath d='M2.75 0l-1.5 1.5 2.5 2.5-2.5 2.5 1.5 1.5 4-4-4-4z'/%3E%3C/svg%3E")}.carousel-indicators{position:absolute;right:0;bottom:10px;left:0;z-index:15;display:-ms-flexbox;display:flex;-ms-flex-pack:center;justify-content:center;padding-left:0;margin-right:15%;margin-left:15%;list-style:none}.carousel-indicators li{position:relative;-ms-flex:0 1 auto;flex:0 1 auto;width:30px;height:3px;margin-right:3px;margin-left:3px;text-indent:-999px;cursor:pointer;background-color:rgba(255,255,255,.5)}.carousel-indicators li::before{position:absolute;top:-10px;left:0;display:inline-block;width:100%;height:10px;content:""}.carousel-indicators li::after{position:absolute;bottom:-10px;left:0;display:inline-block;width:100%;height:10px;content:""}.carousel-indicators .active{background-color:#fff}.carousel-caption{position:absolute;right:15%;bottom:20px;left:15%;z-index:10;padding-top:20px;padding-bottom:20px;color:#fff;text-align:center}.align-baseline{vertical-align:baseline!important}.align-top{vertical-align:top!important}.align-middle{vertical-align:middle!important}.align-bottom{vertical-align:bottom!important}.align-text-bottom{vertical-align:text-bottom!important}.align-text-top{vertical-align:text-top!important}.bg-primary{background-color:#007bff!important}a.bg-primary:focus,a.bg-primary:hover,button.bg-primary:focus,button.bg-primary:hover{background-color:#0062cc!important}.bg-secondary{background-color:#6c757d!important}a.bg-secondary:focus,a.bg-secondary:hover,button.bg-secondary:focus,button.bg-secondary:hover{background-color:#545b62!important}.bg-success{background-color:#28a745!important}a.bg-success:focus,a.bg-success:hover,button.bg-success:focus,button.bg-success:hover{background-color:#1e7e34!important}.bg-info{background-color:#17a2b8!important}a.bg-info:focus,a.bg-info:hover,button.bg-info:focus,button.bg-info:hover{background-color:#117a8b!important}.bg-warning{background-color:#ffc107!important}a.bg-warning:focus,a.bg-warning:hover,button.bg-warning:focus,button.bg-warning:hover{background-color:#d39e00!important}.bg-danger{background-color:#dc3545!important}a.bg-danger:focus,a.bg-danger:hover,button.bg-danger:focus,button.bg-danger:hover{background-color:#bd2130!important}.bg-light{background-color:#f8f9fa!important}a.bg-light:focus,a.bg-light:hover,button.bg-light:focus,button.bg-light:hover{background-color:#dae0e5!important}.bg-dark{background-color:#343a40!important}a.bg-dark:focus,a.bg-dark:hover,button.bg-dark:focus,button.bg-dark:hover{background-color:#1d2124!important}.bg-white{background-color:#fff!important}.bg-transparent{background-color:transparent!important}.border{border:1px solid #dee2e6!important}.border-top{border-top:1px solid #dee2e6!important}.border-right{border-right:1px solid #dee2e6!important}.border-bottom{border-bottom:1px solid #dee2e6!important}.border-left{border-left:1px solid #dee2e6!important}.border-0{border:0!important}.border-top-0{border-top:0!important}.border-right-0{border-right:0!important}.border-bottom-0{border-bottom:0!important}.border-left-0{border-left:0!important}.border-primary{border-color:#007bff!important}.border-secondary{border-color:#6c757d!important}.border-success{border-color:#28a745!important}.border-info{border-color:#17a2b8!important}.border-warning{border-color:#ffc107!important}.border-danger{border-color:#dc3545!important}.border-light{border-color:#f8f9fa!important}.border-dark{border-color:#343a40!important}.border-white{border-color:#fff!important}.rounded{border-radius:.25rem!important}.rounded-top{border-top-left-radius:.25rem!important;border-top-right-radius:.25rem!important}.rounded-right{border-top-right-radius:.25rem!important;border-bottom-right-radius:.25rem!important}.rounded-bottom{border-bottom-right-radius:.25rem!important;border-bottom-left-radius:.25rem!important}.rounded-left{border-top-left-radius:.25rem!important;border-bottom-left-radius:.25rem!important}.rounded-circle{border-radius:50%!important}.rounded-0{border-radius:0!important}.clearfix::after{display:block;clear:both;content:""}.d-none{display:none!important}.d-inline{display:inline!important}.d-inline-block{display:inline-block!important}.d-block{display:block!important}.d-table{display:table!important}.d-table-row{display:table-row!important}.d-table-cell{display:table-cell!important}.d-flex{display:-ms-flexbox!important;display:flex!important}.d-inline-flex{display:-ms-inline-flexbox!important;display:inline-flex!important}@media (min-width:576px){.d-sm-none{display:none!important}.d-sm-inline{display:inline!important}.d-sm-inline-block{display:inline-block!important}.d-sm-block{display:block!important}.d-sm-table{display:table!important}.d-sm-table-row{display:table-row!important}.d-sm-table-cell{display:table-cell!important}.d-sm-flex{display:-ms-flexbox!important;display:flex!important}.d-sm-inline-flex{display:-ms-inline-flexbox!important;display:inline-flex!important}}@media (min-width:768px){.d-md-none{display:none!important}.d-md-inline{display:inline!important}.d-md-inline-block{display:inline-block!important}.d-md-block{display:block!important}.d-md-table{display:table!important}.d-md-table-row{display:table-row!important}.d-md-table-cell{display:table-cell!important}.d-md-flex{display:-ms-flexbox!important;display:flex!important}.d-md-inline-flex{display:-ms-inline-flexbox!important;display:inline-flex!important}}@media (min-width:992px){.d-lg-none{display:none!important}.d-lg-inline{display:inline!important}.d-lg-inline-block{display:inline-block!important}.d-lg-block{display:block!important}.d-lg-table{display:table!important}.d-lg-table-row{display:table-row!important}.d-lg-table-cell{display:table-cell!important}.d-lg-flex{display:-ms-flexbox!important;display:flex!important}.d-lg-inline-flex{display:-ms-inline-flexbox!important;display:inline-flex!important}}@media (min-width:1200px){.d-xl-none{display:none!important}.d-xl-inline{display:inline!important}.d-xl-inline-block{display:inline-block!important}.d-xl-block{display:block!important}.d-xl-table{display:table!important}.d-xl-table-row{display:table-row!important}.d-xl-table-cell{display:table-cell!important}.d-xl-flex{display:-ms-flexbox!important;display:flex!important}.d-xl-inline-flex{display:-ms-inline-flexbox!important;display:inline-flex!important}}@media print{.d-print-none{display:none!important}.d-print-inline{display:inline!important}.d-print-inline-block{display:inline-block!important}.d-print-block{display:block!important}.d-print-table{display:table!important}.d-print-table-row{display:table-row!important}.d-print-table-cell{display:table-cell!important}.d-print-flex{display:-ms-flexbox!important;display:flex!important}.d-print-inline-flex{display:-ms-inline-flexbox!important;display:inline-flex!important}}.embed-responsive{position:relative;display:block;width:100%;padding:0;overflow:hidden}.embed-responsive::before{display:block;content:""}.embed-responsive .embed-responsive-item,.embed-responsive embed,.embed-responsive iframe,.embed-responsive object,.embed-responsive video{position:absolute;top:0;bottom:0;left:0;width:100%;height:100%;border:0}.embed-responsive-21by9::before{padding-top:42.857143%}.embed-responsive-16by9::before{padding-top:56.25%}.embed-responsive-4by3::before{padding-top:75%}.embed-responsive-1by1::before{padding-top:100%}.flex-row{-ms-flex-direction:row!important;flex-direction:row!important}.flex-column{-ms-flex-direction:column!important;flex-direction:column!important}.flex-row-reverse{-ms-flex-direction:row-reverse!important;flex-direction:row-reverse!important}.flex-column-reverse{-ms-flex-direction:column-reverse!important;flex-direction:column-reverse!important}.flex-wrap{-ms-flex-wrap:wrap!important;flex-wrap:wrap!important}.flex-nowrap{-ms-flex-wrap:nowrap!important;flex-wrap:nowrap!important}.flex-wrap-reverse{-ms-flex-wrap:wrap-reverse!important;flex-wrap:wrap-reverse!important}.flex-fill{-ms-flex:1 1 auto!important;flex:1 1 auto!important}.flex-grow-0{-ms-flex-positive:0!important;flex-grow:0!important}.flex-grow-1{-ms-flex-positive:1!important;flex-grow:1!important}.flex-shrink-0{-ms-flex-negative:0!important;flex-shrink:0!important}.flex-shrink-1{-ms-flex-negative:1!important;flex-shrink:1!important}.justify-content-start{-ms-flex-pack:start!important;justify-content:flex-start!important}.justify-content-end{-ms-flex-pack:end!important;justify-content:flex-end!important}.justify-content-center{-ms-flex-pack:center!important;justify-content:center!important}.justify-content-between{-ms-flex-pack:justify!important;justify-content:space-between!important}.justify-content-around{-ms-flex-pack:distribute!important;justify-content:space-around!important}.align-items-start{-ms-flex-align:start!important;align-items:flex-start!important}.align-items-end{-ms-flex-align:end!important;align-items:flex-end!important}.align-items-center{-ms-flex-align:center!important;align-items:center!important}.align-items-baseline{-ms-flex-align:baseline!important;align-items:baseline!important}.align-items-stretch{-ms-flex-align:stretch!important;align-items:stretch!important}.align-content-start{-ms-flex-line-pack:start!important;align-content:flex-start!important}.align-content-end{-ms-flex-line-pack:end!important;align-content:flex-end!important}.align-content-center{-ms-flex-line-pack:center!important;align-content:center!important}.align-content-between{-ms-flex-line-pack:justify!important;align-content:space-between!important}.align-content-around{-ms-flex-line-pack:distribute!important;align-content:space-around!important}.align-content-stretch{-ms-flex-line-pack:stretch!important;align-content:stretch!important}.align-self-auto{-ms-flex-item-align:auto!important;align-self:auto!important}.align-self-start{-ms-flex-item-align:start!important;align-self:flex-start!important}.align-self-end{-ms-flex-item-align:end!important;align-self:flex-end!important}.align-self-center{-ms-flex-item-align:center!important;align-self:center!important}.align-self-baseline{-ms-flex-item-align:baseline!important;align-self:baseline!important}.align-self-stretch{-ms-flex-item-align:stretch!important;align-self:stretch!important}@media (min-width:576px){.flex-sm-row{-ms-flex-direction:row!important;flex-direction:row!important}.flex-sm-column{-ms-flex-direction:column!important;flex-direction:column!important}.flex-sm-row-reverse{-ms-flex-direction:row-reverse!important;flex-direction:row-reverse!important}.flex-sm-column-reverse{-ms-flex-direction:column-reverse!important;flex-direction:column-reverse!important}.flex-sm-wrap{-ms-flex-wrap:wrap!important;flex-wrap:wrap!important}.flex-sm-nowrap{-ms-flex-wrap:nowrap!important;flex-wrap:nowrap!important}.flex-sm-wrap-reverse{-ms-flex-wrap:wrap-reverse!important;flex-wrap:wrap-reverse!important}.flex-sm-fill{-ms-flex:1 1 auto!important;flex:1 1 auto!important}.flex-sm-grow-0{-ms-flex-positive:0!important;flex-grow:0!important}.flex-sm-grow-1{-ms-flex-positive:1!important;flex-grow:1!important}.flex-sm-shrink-0{-ms-flex-negative:0!important;flex-shrink:0!important}.flex-sm-shrink-1{-ms-flex-negative:1!important;flex-shrink:1!important}.justify-content-sm-start{-ms-flex-pack:start!important;justify-content:flex-start!important}.justify-content-sm-end{-ms-flex-pack:end!important;justify-content:flex-end!important}.justify-content-sm-center{-ms-flex-pack:center!important;justify-content:center!important}.justify-content-sm-between{-ms-flex-pack:justify!important;justify-content:space-between!important}.justify-content-sm-around{-ms-flex-pack:distribute!important;justify-content:space-around!important}.align-items-sm-start{-ms-flex-align:start!important;align-items:flex-start!important}.align-items-sm-end{-ms-flex-align:end!important;align-items:flex-end!important}.align-items-sm-center{-ms-flex-align:center!important;align-items:center!important}.align-items-sm-baseline{-ms-flex-align:baseline!important;align-items:baseline!important}.align-items-sm-stretch{-ms-flex-align:stretch!important;align-items:stretch!important}.align-content-sm-start{-ms-flex-line-pack:start!important;align-content:flex-start!important}.align-content-sm-end{-ms-flex-line-pack:end!important;align-content:flex-end!important}.align-content-sm-center{-ms-flex-line-pack:center!important;align-content:center!important}.align-content-sm-between{-ms-flex-line-pack:justify!important;align-content:space-between!important}.align-content-sm-around{-ms-flex-line-pack:distribute!important;align-content:space-around!important}.align-content-sm-stretch{-ms-flex-line-pack:stretch!important;align-content:stretch!important}.align-self-sm-auto{-ms-flex-item-align:auto!important;align-self:auto!important}.align-self-sm-start{-ms-flex-item-align:start!important;align-self:flex-start!important}.align-self-sm-end{-ms-flex-item-align:end!important;align-self:flex-end!important}.align-self-sm-center{-ms-flex-item-align:center!important;align-self:center!important}.align-self-sm-baseline{-ms-flex-item-align:baseline!important;align-self:baseline!important}.align-self-sm-stretch{-ms-flex-item-align:stretch!important;align-self:stretch!important}}@media (min-width:768px){.flex-md-row{-ms-flex-direction:row!important;flex-direction:row!important}.flex-md-column{-ms-flex-direction:column!important;flex-direction:column!important}.flex-md-row-reverse{-ms-flex-direction:row-reverse!important;flex-direction:row-reverse!important}.flex-md-column-reverse{-ms-flex-direction:column-reverse!important;flex-direction:column-reverse!important}.flex-md-wrap{-ms-flex-wrap:wrap!important;flex-wrap:wrap!important}.flex-md-nowrap{-ms-flex-wrap:nowrap!important;flex-wrap:nowrap!important}.flex-md-wrap-reverse{-ms-flex-wrap:wrap-reverse!important;flex-wrap:wrap-reverse!important}.flex-md-fill{-ms-flex:1 1 auto!important;flex:1 1 auto!important}.flex-md-grow-0{-ms-flex-positive:0!important;flex-grow:0!important}.flex-md-grow-1{-ms-flex-positive:1!important;flex-grow:1!important}.flex-md-shrink-0{-ms-flex-negative:0!important;flex-shrink:0!important}.flex-md-shrink-1{-ms-flex-negative:1!important;flex-shrink:1!important}.justify-content-md-start{-ms-flex-pack:start!important;justify-content:flex-start!important}.justify-content-md-end{-ms-flex-pack:end!important;justify-content:flex-end!important}.justify-content-md-center{-ms-flex-pack:center!important;justify-content:center!important}.justify-content-md-between{-ms-flex-pack:justify!important;justify-content:space-between!important}.justify-content-md-around{-ms-flex-pack:distribute!important;justify-content:space-around!important}.align-items-md-start{-ms-flex-align:start!important;align-items:flex-start!important}.align-items-md-end{-ms-flex-align:end!important;align-items:flex-end!important}.align-items-md-center{-ms-flex-align:center!important;align-items:center!important}.align-items-md-baseline{-ms-flex-align:baseline!important;align-items:baseline!important}.align-items-md-stretch{-ms-flex-align:stretch!important;align-items:stretch!important}.align-content-md-start{-ms-flex-line-pack:start!important;align-content:flex-start!important}.align-content-md-end{-ms-flex-line-pack:end!important;align-content:flex-end!important}.align-content-md-center{-ms-flex-line-pack:center!important;align-content:center!important}.align-content-md-between{-ms-flex-line-pack:justify!important;align-content:space-between!important}.align-content-md-around{-ms-flex-line-pack:distribute!important;align-content:space-around!important}.align-content-md-stretch{-ms-flex-line-pack:stretch!important;align-content:stretch!important}.align-self-md-auto{-ms-flex-item-align:auto!important;align-self:auto!important}.align-self-md-start{-ms-flex-item-align:start!important;align-self:flex-start!important}.align-self-md-end{-ms-flex-item-align:end!important;align-self:flex-end!important}.align-self-md-center{-ms-flex-item-align:center!important;align-self:center!important}.align-self-md-baseline{-ms-flex-item-align:baseline!important;align-self:baseline!important}.align-self-md-stretch{-ms-flex-item-align:stretch!important;align-self:stretch!important}}@media (min-width:992px){.flex-lg-row{-ms-flex-direction:row!important;flex-direction:row!important}.flex-lg-column{-ms-flex-direction:column!important;flex-direction:column!important}.flex-lg-row-reverse{-ms-flex-direction:row-reverse!important;flex-direction:row-reverse!important}.flex-lg-column-reverse{-ms-flex-direction:column-reverse!important;flex-direction:column-reverse!important}.flex-lg-wrap{-ms-flex-wrap:wrap!important;flex-wrap:wrap!important}.flex-lg-nowrap{-ms-flex-wrap:nowrap!important;flex-wrap:nowrap!important}.flex-lg-wrap-reverse{-ms-flex-wrap:wrap-reverse!important;flex-wrap:wrap-reverse!important}.flex-lg-fill{-ms-flex:1 1 auto!important;flex:1 1 auto!important}.flex-lg-grow-0{-ms-flex-positive:0!important;flex-grow:0!important}.flex-lg-grow-1{-ms-flex-positive:1!important;flex-grow:1!important}.flex-lg-shrink-0{-ms-flex-negative:0!important;flex-shrink:0!important}.flex-lg-shrink-1{-ms-flex-negative:1!important;flex-shrink:1!important}.justify-content-lg-start{-ms-flex-pack:start!important;justify-content:flex-start!important}.justify-content-lg-end{-ms-flex-pack:end!important;justify-content:flex-end!important}.justify-content-lg-center{-ms-flex-pack:center!important;justify-content:center!important}.justify-content-lg-between{-ms-flex-pack:justify!important;justify-content:space-between!important}.justify-content-lg-around{-ms-flex-pack:distribute!important;justify-content:space-around!important}.align-items-lg-start{-ms-flex-align:start!important;align-items:flex-start!important}.align-items-lg-end{-ms-flex-align:end!important;align-items:flex-end!important}.align-items-lg-center{-ms-flex-align:center!important;align-items:center!important}.align-items-lg-baseline{-ms-flex-align:baseline!important;align-items:baseline!important}.align-items-lg-stretch{-ms-flex-align:stretch!important;align-items:stretch!important}.align-content-lg-start{-ms-flex-line-pack:start!important;align-content:flex-start!important}.align-content-lg-end{-ms-flex-line-pack:end!important;align-content:flex-end!important}.align-content-lg-center{-ms-flex-line-pack:center!important;align-content:center!important}.align-content-lg-between{-ms-flex-line-pack:justify!important;align-content:space-between!important}.align-content-lg-around{-ms-flex-line-pack:distribute!important;align-content:space-around!important}.align-content-lg-stretch{-ms-flex-line-pack:stretch!important;align-content:stretch!important}.align-self-lg-auto{-ms-flex-item-align:auto!important;align-self:auto!important}.align-self-lg-start{-ms-flex-item-align:start!important;align-self:flex-start!important}.align-self-lg-end{-ms-flex-item-align:end!important;align-self:flex-end!important}.align-self-lg-center{-ms-flex-item-align:center!important;align-self:center!important}.align-self-lg-baseline{-ms-flex-item-align:baseline!important;align-self:baseline!important}.align-self-lg-stretch{-ms-flex-item-align:stretch!important;align-self:stretch!important}}@media (min-width:1200px){.flex-xl-row{-ms-flex-direction:row!important;flex-direction:row!important}.flex-xl-column{-ms-flex-direction:column!important;flex-direction:column!important}.flex-xl-row-reverse{-ms-flex-direction:row-reverse!important;flex-direction:row-reverse!important}.flex-xl-column-reverse{-ms-flex-direction:column-reverse!important;flex-direction:column-reverse!important}.flex-xl-wrap{-ms-flex-wrap:wrap!important;flex-wrap:wrap!important}.flex-xl-nowrap{-ms-flex-wrap:nowrap!important;flex-wrap:nowrap!important}.flex-xl-wrap-reverse{-ms-flex-wrap:wrap-reverse!important;flex-wrap:wrap-reverse!important}.flex-xl-fill{-ms-flex:1 1 auto!important;flex:1 1 auto!important}.flex-xl-grow-0{-ms-flex-positive:0!important;flex-grow:0!important}.flex-xl-grow-1{-ms-flex-positive:1!important;flex-grow:1!important}.flex-xl-shrink-0{-ms-flex-negative:0!important;flex-shrink:0!important}.flex-xl-shrink-1{-ms-flex-negative:1!important;flex-shrink:1!important}.justify-content-xl-start{-ms-flex-pack:start!important;justify-content:flex-start!important}.justify-content-xl-end{-ms-flex-pack:end!important;justify-content:flex-end!important}.justify-content-xl-center{-ms-flex-pack:center!important;justify-content:center!important}.justify-content-xl-between{-ms-flex-pack:justify!important;justify-content:space-between!important}.justify-content-xl-around{-ms-flex-pack:distribute!important;justify-content:space-around!important}.align-items-xl-start{-ms-flex-align:start!important;align-items:flex-start!important}.align-items-xl-end{-ms-flex-align:end!important;align-items:flex-end!important}.align-items-xl-center{-ms-flex-align:center!important;align-items:center!important}.align-items-xl-baseline{-ms-flex-align:baseline!important;align-items:baseline!important}.align-items-xl-stretch{-ms-flex-align:stretch!important;align-items:stretch!important}.align-content-xl-start{-ms-flex-line-pack:start!important;align-content:flex-start!important}.align-content-xl-end{-ms-flex-line-pack:end!important;align-content:flex-end!important}.align-content-xl-center{-ms-flex-line-pack:center!important;align-content:center!important}.align-content-xl-between{-ms-flex-line-pack:justify!important;align-content:space-between!important}.align-content-xl-around{-ms-flex-line-pack:distribute!important;align-content:space-around!important}.align-content-xl-stretch{-ms-flex-line-pack:stretch!important;align-content:stretch!important}.align-self-xl-auto{-ms-flex-item-align:auto!important;align-self:auto!important}.align-self-xl-start{-ms-flex-item-align:start!important;align-self:flex-start!important}.align-self-xl-end{-ms-flex-item-align:end!important;align-self:flex-end!important}.align-self-xl-center{-ms-flex-item-align:center!important;align-self:center!important}.align-self-xl-baseline{-ms-flex-item-align:baseline!important;align-self:baseline!important}.align-self-xl-stretch{-ms-flex-item-align:stretch!important;align-self:stretch!important}}.float-left{float:left!important}.float-right{float:right!important}.float-none{float:none!important}@media (min-width:576px){.float-sm-left{float:left!important}.float-sm-right{float:right!important}.float-sm-none{float:none!important}}@media (min-width:768px){.float-md-left{float:left!important}.float-md-right{float:right!important}.float-md-none{float:none!important}}@media (min-width:992px){.float-lg-left{float:left!important}.float-lg-right{float:right!important}.float-lg-none{float:none!important}}@media (min-width:1200px){.float-xl-left{float:left!important}.float-xl-right{float:right!important}.float-xl-none{float:none!important}}.position-static{position:static!important}.position-relative{position:relative!important}.position-absolute{position:absolute!important}.position-fixed{position:fixed!important}.position-sticky{position:-webkit-sticky!important;position:sticky!important}.fixed-top{position:fixed;top:0;right:0;left:0;z-index:1030}.fixed-bottom{position:fixed;right:0;bottom:0;left:0;z-index:1030}@supports ((position:-webkit-sticky) or (position:sticky)){.sticky-top{position:-webkit-sticky;position:sticky;top:0;z-index:1020}}.sr-only{position:absolute;width:1px;height:1px;padding:0;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0}.sr-only-focusable:active,.sr-only-focusable:focus{position:static;width:auto;height:auto;overflow:visible;clip:auto;white-space:normal}.shadow-sm{box-shadow:0 .125rem .25rem rgba(0,0,0,.075)!important}.shadow{box-shadow:0 .5rem 1rem rgba(0,0,0,.15)!important}.shadow-lg{box-shadow:0 1rem 3rem rgba(0,0,0,.175)!important}.shadow-none{box-shadow:none!important}.w-25{width:25%!important}.w-50{width:50%!important}.w-75{width:75%!important}.w-100{width:100%!important}.w-auto{width:auto!important}.h-25{height:25%!important}.h-50{height:50%!important}.h-75{height:75%!important}.h-100{height:100%!important}.h-auto{height:auto!important}.mw-100{max-width:100%!important}.mh-100{max-height:100%!important}.m-0{margin:0!important}.mt-0,.my-0{margin-top:0!important}.mr-0,.mx-0{margin-right:0!important}.mb-0,.my-0{margin-bottom:0!important}.ml-0,.mx-0{margin-left:0!important}.m-1{margin:.25rem!important}.mt-1,.my-1{margin-top:.25rem!important}.mr-1,.mx-1{margin-right:.25rem!important}.mb-1,.my-1{margin-bottom:.25rem!important}.ml-1,.mx-1{margin-left:.25rem!important}.m-2{margin:.5rem!important}.mt-2,.my-2{margin-top:.5rem!important}.mr-2,.mx-2{margin-right:.5rem!important}.mb-2,.my-2{margin-bottom:.5rem!important}.ml-2,.mx-2{margin-left:.5rem!important}.m-3{margin:1rem!important}.mt-3,.my-3{margin-top:1rem!important}.mr-3,.mx-3{margin-right:1rem!important}.mb-3,.my-3{margin-bottom:1rem!important}.ml-3,.mx-3{margin-left:1rem!important}.m-4{margin:1.5rem!important}.mt-4,.my-4{margin-top:1.5rem!important}.mr-4,.mx-4{margin-right:1.5rem!important}.mb-4,.my-4{margin-bottom:1.5rem!important}.ml-4,.mx-4{margin-left:1.5rem!important}.m-5{margin:3rem!important}.mt-5,.my-5{margin-top:3rem!important}.mr-5,.mx-5{margin-right:3rem!important}.mb-5,.my-5{margin-bottom:3rem!important}.ml-5,.mx-5{margin-left:3rem!important}.p-0{padding:0!important}.pt-0,.py-0{padding-top:0!important}.pr-0,.px-0{padding-right:0!important}.pb-0,.py-0{padding-bottom:0!important}.pl-0,.px-0{padding-left:0!important}.p-1{padding:.25rem!important}.pt-1,.py-1{padding-top:.25rem!important}.pr-1,.px-1{padding-right:.25rem!important}.pb-1,.py-1{padding-bottom:.25rem!important}.pl-1,.px-1{padding-left:.25rem!important}.p-2{padding:.5rem!important}.pt-2,.py-2{padding-top:.5rem!important}.pr-2,.px-2{padding-right:.5rem!important}.pb-2,.py-2{padding-bottom:.5rem!important}.pl-2,.px-2{padding-left:.5rem!important}.p-3{padding:1rem!important}.pt-3,.py-3{padding-top:1rem!important}.pr-3,.px-3{padding-right:1rem!important}.pb-3,.py-3{padding-bottom:1rem!important}.pl-3,.px-3{padding-left:1rem!important}.p-4{padding:1.5rem!important}.pt-4,.py-4{padding-top:1.5rem!important}.pr-4,.px-4{padding-right:1.5rem!important}.pb-4,.py-4{padding-bottom:1.5rem!important}.pl-4,.px-4{padding-left:1.5rem!important}.p-5{padding:3rem!important}.pt-5,.py-5{padding-top:3rem!important}.pr-5,.px-5{padding-right:3rem!important}.pb-5,.py-5{padding-bottom:3rem!important}.pl-5,.px-5{padding-left:3rem!important}.m-auto{margin:auto!important}.mt-auto,.my-auto{margin-top:auto!important}.mr-auto,.mx-auto{margin-right:auto!important}.mb-auto,.my-auto{margin-bottom:auto!important}.ml-auto,.mx-auto{margin-left:auto!important}@media (min-width:576px){.m-sm-0{margin:0!important}.mt-sm-0,.my-sm-0{margin-top:0!important}.mr-sm-0,.mx-sm-0{margin-right:0!important}.mb-sm-0,.my-sm-0{margin-bottom:0!important}.ml-sm-0,.mx-sm-0{margin-left:0!important}.m-sm-1{margin:.25rem!important}.mt-sm-1,.my-sm-1{margin-top:.25rem!important}.mr-sm-1,.mx-sm-1{margin-right:.25rem!important}.mb-sm-1,.my-sm-1{margin-bottom:.25rem!important}.ml-sm-1,.mx-sm-1{margin-left:.25rem!important}.m-sm-2{margin:.5rem!important}.mt-sm-2,.my-sm-2{margin-top:.5rem!important}.mr-sm-2,.mx-sm-2{margin-right:.5rem!important}.mb-sm-2,.my-sm-2{margin-bottom:.5rem!important}.ml-sm-2,.mx-sm-2{margin-left:.5rem!important}.m-sm-3{margin:1rem!important}.mt-sm-3,.my-sm-3{margin-top:1rem!important}.mr-sm-3,.mx-sm-3{margin-right:1rem!important}.mb-sm-3,.my-sm-3{margin-bottom:1rem!important}.ml-sm-3,.mx-sm-3{margin-left:1rem!important}.m-sm-4{margin:1.5rem!important}.mt-sm-4,.my-sm-4{margin-top:1.5rem!important}.mr-sm-4,.mx-sm-4{margin-right:1.5rem!important}.mb-sm-4,.my-sm-4{margin-bottom:1.5rem!important}.ml-sm-4,.mx-sm-4{margin-left:1.5rem!important}.m-sm-5{margin:3rem!important}.mt-sm-5,.my-sm-5{margin-top:3rem!important}.mr-sm-5,.mx-sm-5{margin-right:3rem!important}.mb-sm-5,.my-sm-5{margin-bottom:3rem!important}.ml-sm-5,.mx-sm-5{margin-left:3rem!important}.p-sm-0{padding:0!important}.pt-sm-0,.py-sm-0{padding-top:0!important}.pr-sm-0,.px-sm-0{padding-right:0!important}.pb-sm-0,.py-sm-0{padding-bottom:0!important}.pl-sm-0,.px-sm-0{padding-left:0!important}.p-sm-1{padding:.25rem!important}.pt-sm-1,.py-sm-1{padding-top:.25rem!important}.pr-sm-1,.px-sm-1{padding-right:.25rem!important}.pb-sm-1,.py-sm-1{padding-bottom:.25rem!important}.pl-sm-1,.px-sm-1{padding-left:.25rem!important}.p-sm-2{padding:.5rem!important}.pt-sm-2,.py-sm-2{padding-top:.5rem!important}.pr-sm-2,.px-sm-2{padding-right:.5rem!important}.pb-sm-2,.py-sm-2{padding-bottom:.5rem!important}.pl-sm-2,.px-sm-2{padding-left:.5rem!important}.p-sm-3{padding:1rem!important}.pt-sm-3,.py-sm-3{padding-top:1rem!important}.pr-sm-3,.px-sm-3{padding-right:1rem!important}.pb-sm-3,.py-sm-3{padding-bottom:1rem!important}.pl-sm-3,.px-sm-3{padding-left:1rem!important}.p-sm-4{padding:1.5rem!important}.pt-sm-4,.py-sm-4{padding-top:1.5rem!important}.pr-sm-4,.px-sm-4{padding-right:1.5rem!important}.pb-sm-4,.py-sm-4{padding-bottom:1.5rem!important}.pl-sm-4,.px-sm-4{padding-left:1.5rem!important}.p-sm-5{padding:3rem!important}.pt-sm-5,.py-sm-5{padding-top:3rem!important}.pr-sm-5,.px-sm-5{padding-right:3rem!important}.pb-sm-5,.py-sm-5{padding-bottom:3rem!important}.pl-sm-5,.px-sm-5{padding-left:3rem!important}.m-sm-auto{margin:auto!important}.mt-sm-auto,.my-sm-auto{margin-top:auto!important}.mr-sm-auto,.mx-sm-auto{margin-right:auto!important}.mb-sm-auto,.my-sm-auto{margin-bottom:auto!important}.ml-sm-auto,.mx-sm-auto{margin-left:auto!important}}@media (min-width:768px){.m-md-0{margin:0!important}.mt-md-0,.my-md-0{margin-top:0!important}.mr-md-0,.mx-md-0{margin-right:0!important}.mb-md-0,.my-md-0{margin-bottom:0!important}.ml-md-0,.mx-md-0{margin-left:0!important}.m-md-1{margin:.25rem!important}.mt-md-1,.my-md-1{margin-top:.25rem!important}.mr-md-1,.mx-md-1{margin-right:.25rem!important}.mb-md-1,.my-md-1{margin-bottom:.25rem!important}.ml-md-1,.mx-md-1{margin-left:.25rem!important}.m-md-2{margin:.5rem!important}.mt-md-2,.my-md-2{margin-top:.5rem!important}.mr-md-2,.mx-md-2{margin-right:.5rem!important}.mb-md-2,.my-md-2{margin-bottom:.5rem!important}.ml-md-2,.mx-md-2{margin-left:.5rem!important}.m-md-3{margin:1rem!important}.mt-md-3,.my-md-3{margin-top:1rem!important}.mr-md-3,.mx-md-3{margin-right:1rem!important}.mb-md-3,.my-md-3{margin-bottom:1rem!important}.ml-md-3,.mx-md-3{margin-left:1rem!important}.m-md-4{margin:1.5rem!important}.mt-md-4,.my-md-4{margin-top:1.5rem!important}.mr-md-4,.mx-md-4{margin-right:1.5rem!important}.mb-md-4,.my-md-4{margin-bottom:1.5rem!important}.ml-md-4,.mx-md-4{margin-left:1.5rem!important}.m-md-5{margin:3rem!important}.mt-md-5,.my-md-5{margin-top:3rem!important}.mr-md-5,.mx-md-5{margin-right:3rem!important}.mb-md-5,.my-md-5{margin-bottom:3rem!important}.ml-md-5,.mx-md-5{margin-left:3rem!important}.p-md-0{padding:0!important}.pt-md-0,.py-md-0{padding-top:0!important}.pr-md-0,.px-md-0{padding-right:0!important}.pb-md-0,.py-md-0{padding-bottom:0!important}.pl-md-0,.px-md-0{padding-left:0!important}.p-md-1{padding:.25rem!important}.pt-md-1,.py-md-1{padding-top:.25rem!important}.pr-md-1,.px-md-1{padding-right:.25rem!important}.pb-md-1,.py-md-1{padding-bottom:.25rem!important}.pl-md-1,.px-md-1{padding-left:.25rem!important}.p-md-2{padding:.5rem!important}.pt-md-2,.py-md-2{padding-top:.5rem!important}.pr-md-2,.px-md-2{padding-right:.5rem!important}.pb-md-2,.py-md-2{padding-bottom:.5rem!important}.pl-md-2,.px-md-2{padding-left:.5rem!important}.p-md-3{padding:1rem!important}.pt-md-3,.py-md-3{padding-top:1rem!important}.pr-md-3,.px-md-3{padding-right:1rem!important}.pb-md-3,.py-md-3{padding-bottom:1rem!important}.pl-md-3,.px-md-3{padding-left:1rem!important}.p-md-4{padding:1.5rem!important}.pt-md-4,.py-md-4{padding-top:1.5rem!important}.pr-md-4,.px-md-4{padding-right:1.5rem!important}.pb-md-4,.py-md-4{padding-bottom:1.5rem!important}.pl-md-4,.px-md-4{padding-left:1.5rem!important}.p-md-5{padding:3rem!important}.pt-md-5,.py-md-5{padding-top:3rem!important}.pr-md-5,.px-md-5{padding-right:3rem!important}.pb-md-5,.py-md-5{padding-bottom:3rem!important}.pl-md-5,.px-md-5{padding-left:3rem!important}.m-md-auto{margin:auto!important}.mt-md-auto,.my-md-auto{margin-top:auto!important}.mr-md-auto,.mx-md-auto{margin-right:auto!important}.mb-md-auto,.my-md-auto{margin-bottom:auto!important}.ml-md-auto,.mx-md-auto{margin-left:auto!important}}@media (min-width:992px){.m-lg-0{margin:0!important}.mt-lg-0,.my-lg-0{margin-top:0!important}.mr-lg-0,.mx-lg-0{margin-right:0!important}.mb-lg-0,.my-lg-0{margin-bottom:0!important}.ml-lg-0,.mx-lg-0{margin-left:0!important}.m-lg-1{margin:.25rem!important}.mt-lg-1,.my-lg-1{margin-top:.25rem!important}.mr-lg-1,.mx-lg-1{margin-right:.25rem!important}.mb-lg-1,.my-lg-1{margin-bottom:.25rem!important}.ml-lg-1,.mx-lg-1{margin-left:.25rem!important}.m-lg-2{margin:.5rem!important}.mt-lg-2,.my-lg-2{margin-top:.5rem!important}.mr-lg-2,.mx-lg-2{margin-right:.5rem!important}.mb-lg-2,.my-lg-2{margin-bottom:.5rem!important}.ml-lg-2,.mx-lg-2{margin-left:.5rem!important}.m-lg-3{margin:1rem!important}.mt-lg-3,.my-lg-3{margin-top:1rem!important}.mr-lg-3,.mx-lg-3{margin-right:1rem!important}.mb-lg-3,.my-lg-3{margin-bottom:1rem!important}.ml-lg-3,.mx-lg-3{margin-left:1rem!important}.m-lg-4{margin:1.5rem!important}.mt-lg-4,.my-lg-4{margin-top:1.5rem!important}.mr-lg-4,.mx-lg-4{margin-right:1.5rem!important}.mb-lg-4,.my-lg-4{margin-bottom:1.5rem!important}.ml-lg-4,.mx-lg-4{margin-left:1.5rem!important}.m-lg-5{margin:3rem!important}.mt-lg-5,.my-lg-5{margin-top:3rem!important}.mr-lg-5,.mx-lg-5{margin-right:3rem!important}.mb-lg-5,.my-lg-5{margin-bottom:3rem!important}.ml-lg-5,.mx-lg-5{margin-left:3rem!important}.p-lg-0{padding:0!important}.pt-lg-0,.py-lg-0{padding-top:0!important}.pr-lg-0,.px-lg-0{padding-right:0!important}.pb-lg-0,.py-lg-0{padding-bottom:0!important}.pl-lg-0,.px-lg-0{padding-left:0!important}.p-lg-1{padding:.25rem!important}.pt-lg-1,.py-lg-1{padding-top:.25rem!important}.pr-lg-1,.px-lg-1{padding-right:.25rem!important}.pb-lg-1,.py-lg-1{padding-bottom:.25rem!important}.pl-lg-1,.px-lg-1{padding-left:.25rem!important}.p-lg-2{padding:.5rem!important}.pt-lg-2,.py-lg-2{padding-top:.5rem!important}.pr-lg-2,.px-lg-2{padding-right:.5rem!important}.pb-lg-2,.py-lg-2{padding-bottom:.5rem!important}.pl-lg-2,.px-lg-2{padding-left:.5rem!important}.p-lg-3{padding:1rem!important}.pt-lg-3,.py-lg-3{padding-top:1rem!important}.pr-lg-3,.px-lg-3{padding-right:1rem!important}.pb-lg-3,.py-lg-3{padding-bottom:1rem!important}.pl-lg-3,.px-lg-3{padding-left:1rem!important}.p-lg-4{padding:1.5rem!important}.pt-lg-4,.py-lg-4{padding-top:1.5rem!important}.pr-lg-4,.px-lg-4{padding-right:1.5rem!important}.pb-lg-4,.py-lg-4{padding-bottom:1.5rem!important}.pl-lg-4,.px-lg-4{padding-left:1.5rem!important}.p-lg-5{padding:3rem!important}.pt-lg-5,.py-lg-5{padding-top:3rem!important}.pr-lg-5,.px-lg-5{padding-right:3rem!important}.pb-lg-5,.py-lg-5{padding-bottom:3rem!important}.pl-lg-5,.px-lg-5{padding-left:3rem!important}.m-lg-auto{margin:auto!important}.mt-lg-auto,.my-lg-auto{margin-top:auto!important}.mr-lg-auto,.mx-lg-auto{margin-right:auto!important}.mb-lg-auto,.my-lg-auto{margin-bottom:auto!important}.ml-lg-auto,.mx-lg-auto{margin-left:auto!important}}@media (min-width:1200px){.m-xl-0{margin:0!important}.mt-xl-0,.my-xl-0{margin-top:0!important}.mr-xl-0,.mx-xl-0{margin-right:0!important}.mb-xl-0,.my-xl-0{margin-bottom:0!important}.ml-xl-0,.mx-xl-0{margin-left:0!important}.m-xl-1{margin:.25rem!important}.mt-xl-1,.my-xl-1{margin-top:.25rem!important}.mr-xl-1,.mx-xl-1{margin-right:.25rem!important}.mb-xl-1,.my-xl-1{margin-bottom:.25rem!important}.ml-xl-1,.mx-xl-1{margin-left:.25rem!important}.m-xl-2{margin:.5rem!important}.mt-xl-2,.my-xl-2{margin-top:.5rem!important}.mr-xl-2,.mx-xl-2{margin-right:.5rem!important}.mb-xl-2,.my-xl-2{margin-bottom:.5rem!important}.ml-xl-2,.mx-xl-2{margin-left:.5rem!important}.m-xl-3{margin:1rem!important}.mt-xl-3,.my-xl-3{margin-top:1rem!important}.mr-xl-3,.mx-xl-3{margin-right:1rem!important}.mb-xl-3,.my-xl-3{margin-bottom:1rem!important}.ml-xl-3,.mx-xl-3{margin-left:1rem!important}.m-xl-4{margin:1.5rem!important}.mt-xl-4,.my-xl-4{margin-top:1.5rem!important}.mr-xl-4,.mx-xl-4{margin-right:1.5rem!important}.mb-xl-4,.my-xl-4{margin-bottom:1.5rem!important}.ml-xl-4,.mx-xl-4{margin-left:1.5rem!important}.m-xl-5{margin:3rem!important}.mt-xl-5,.my-xl-5{margin-top:3rem!important}.mr-xl-5,.mx-xl-5{margin-right:3rem!important}.mb-xl-5,.my-xl-5{margin-bottom:3rem!important}.ml-xl-5,.mx-xl-5{margin-left:3rem!important}.p-xl-0{padding:0!important}.pt-xl-0,.py-xl-0{padding-top:0!important}.pr-xl-0,.px-xl-0{padding-right:0!important}.pb-xl-0,.py-xl-0{padding-bottom:0!important}.pl-xl-0,.px-xl-0{padding-left:0!important}.p-xl-1{padding:.25rem!important}.pt-xl-1,.py-xl-1{padding-top:.25rem!important}.pr-xl-1,.px-xl-1{padding-right:.25rem!important}.pb-xl-1,.py-xl-1{padding-bottom:.25rem!important}.pl-xl-1,.px-xl-1{padding-left:.25rem!important}.p-xl-2{padding:.5rem!important}.pt-xl-2,.py-xl-2{padding-top:.5rem!important}.pr-xl-2,.px-xl-2{padding-right:.5rem!important}.pb-xl-2,.py-xl-2{padding-bottom:.5rem!important}.pl-xl-2,.px-xl-2{padding-left:.5rem!important}.p-xl-3{padding:1rem!important}.pt-xl-3,.py-xl-3{padding-top:1rem!important}.pr-xl-3,.px-xl-3{padding-right:1rem!important}.pb-xl-3,.py-xl-3{padding-bottom:1rem!important}.pl-xl-3,.px-xl-3{padding-left:1rem!important}.p-xl-4{padding:1.5rem!important}.pt-xl-4,.py-xl-4{padding-top:1.5rem!important}.pr-xl-4,.px-xl-4{padding-right:1.5rem!important}.pb-xl-4,.py-xl-4{padding-bottom:1.5rem!important}.pl-xl-4,.px-xl-4{padding-left:1.5rem!important}.p-xl-5{padding:3rem!important}.pt-xl-5,.py-xl-5{padding-top:3rem!important}.pr-xl-5,.px-xl-5{padding-right:3rem!important}.pb-xl-5,.py-xl-5{padding-bottom:3rem!important}.pl-xl-5,.px-xl-5{padding-left:3rem!important}.m-xl-auto{margin:auto!important}.mt-xl-auto,.my-xl-auto{margin-top:auto!important}.mr-xl-auto,.mx-xl-auto{margin-right:auto!important}.mb-xl-auto,.my-xl-auto{margin-bottom:auto!important}.ml-xl-auto,.mx-xl-auto{margin-left:auto!important}}.text-monospace{font-family:SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",monospace}.text-justify{text-align:justify!important}.text-nowrap{white-space:nowrap!important}.text-truncate{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.text-left{text-align:left!important}.text-right{text-align:right!important}.text-center{text-align:center!important}@media (min-width:576px){.text-sm-left{text-align:left!important}.text-sm-right{text-align:right!important}.text-sm-center{text-align:center!important}}@media (min-width:768px){.text-md-left{text-align:left!important}.text-md-right{text-align:right!important}.text-md-center{text-align:center!important}}@media (min-width:992px){.text-lg-left{text-align:left!important}.text-lg-right{text-align:right!important}.text-lg-center{text-align:center!important}}@media (min-width:1200px){.text-xl-left{text-align:left!important}.text-xl-right{text-align:right!important}.text-xl-center{text-align:center!important}}.text-lowercase{text-transform:lowercase!important}.text-uppercase{text-transform:uppercase!important}.text-capitalize{text-transform:capitalize!important}.font-weight-light{font-weight:300!important}.font-weight-normal{font-weight:400!important}.font-weight-bold{font-weight:700!important}.font-italic{font-style:italic!important}.text-white{color:#fff!important}.text-primary{color:#007bff!important}a.text-primary:focus,a.text-primary:hover{color:#0062cc!important}.text-secondary{color:#6c757d!important}a.text-secondary:focus,a.text-secondary:hover{color:#545b62!important}.text-success{color:#28a745!important}a.text-success:focus,a.text-success:hover{color:#1e7e34!important}.text-info{color:#17a2b8!important}a.text-info:focus,a.text-info:hover{color:#117a8b!important}.text-warning{color:#ffc107!important}a.text-warning:focus,a.text-warning:hover{color:#d39e00!important}.text-danger{color:#dc3545!important}a.text-danger:focus,a.text-danger:hover{color:#bd2130!important}.text-light{color:#f8f9fa!important}a.text-light:focus,a.text-light:hover{color:#dae0e5!important}.text-dark{color:#343a40!important}a.text-dark:focus,a.text-dark:hover{color:#1d2124!important}.text-body{color:#212529!important}.text-muted{color:#6c757d!important}.text-black-50{color:rgba(0,0,0,.5)!important}.text-white-50{color:rgba(255,255,255,.5)!important}.text-hide{font:0/0 a;color:transparent;text-shadow:none;background-color:transparent;border:0}.visible{visibility:visible!important}.invisible{visibility:hidden!important}@media print{*,::after,::before{text-shadow:none!important;box-shadow:none!important}a:not(.btn){text-decoration:underline}abbr[title]::after{content:" (" attr(title) ")"}pre{white-space:pre-wrap!important}blockquote,pre{border:1px solid #adb5bd;page-break-inside:avoid}thead{display:table-header-group}img,tr{page-break-inside:avoid}h2,h3,p{orphans:3;widows:3}h2,h3{page-break-after:avoid}@page{size:a3}body{min-width:992px!important}.container{min-width:992px!important}.navbar{display:none}.badge{border:1px solid #000}.table{border-collapse:collapse!important}.table td,.table th{background-color:#fff!important}.table-bordered td,.table-bordered th{border:1px solid #dee2e6!important}.table-dark{color:inherit}.table-dark tbody+tbody,.table-dark td,.table-dark th,.table-dark thead th{border-color:#dee2e6}.table .thead-dark th{color:inherit;border-color:#dee2e6}} -/*# sourceMappingURL=bootstrap.min.css.map */ \ No newline at end of file diff --git a/documentation/tdenginedocs-cn/lib/docs/docs.css b/documentation/tdenginedocs-cn/lib/docs/docs.css deleted file mode 100644 index bfb6f808e6cf1b5abaa4167c169d16abee639976..0000000000000000000000000000000000000000 --- a/documentation/tdenginedocs-cn/lib/docs/docs.css +++ /dev/null @@ -1,269 +0,0 @@ -.documentation strong { - font-weight:600; -} -.documentation { - overflow:hidden; - margin-bottom: 10rem; -} -.documentation a { - font-size:1em; - text-decoration: none; -} -.documentation > a > h2 { - cursor:pointer; - color:var(--sg1); - -} -.documentation > a >h2:hover { - color:var(--b2); -} -.documentation a:hover { - text-decoration: none; -} -.documentation pre { - margin-top: 0; -margin-bottom: 7px; -overflow: auto; --ms-overflow-style: scrollbar; -margin-top: 7px; -} -pre * { - font-family:monospace !important -} -.documentation a { - color:var(--b2); - padding-bottom: 2px; - position: relative; - font-style: normal; - cursor: pointer; -} -.documentation a:hover,a:focus { - text-decoration: none; - color:var(--b2); -} -.documentation a::before { - content: ""; - left: 0; - background-color: var(--b2); - width: 0%; - height: 1px; - top:-webkit-calc(1em + 8px); - top:calc(1em + 8px); - position: absolute; - z-index: 2; - -webkit-transition: background-color 0.2s, height 0.2s, top 0.2s, width 0.2s; - -o-transition: background-color 0.2s, height 0.2s, top 0.2s, width 0.2s; - transition: background-color 0.2s, height 0.2s, top 0.2s, width 0.2s;; -} -.documentation a:hover::before, .documentation a:focus::before { - content: ""; - left: 0; - background-color: var(--b2); - width: 100%; - height: 1px; - top:-webkit-calc(1em + 8px); - top:calc(1em + 8px); - position: absolute; - z-index: 2; - -webkit-transition: background-color 0.2s, height 0.2s, top 0.2s, width 0.2s; - -o-transition: background-color 0.2s, height 0.2s, top 0.2s, width 0.2s; - transition: background-color 0.2s, height 0.2s, top 0.2s, width 0.2s; - text-decoration: none; -} -.documentation img { - width:100%; - max-width:640px; - margin-left: 50%; - -webkit-transform: translate(-50%,0); - -ms-transform: translate(-50%,0); - transform: translate(-50%,0); - -} -h1, -h2, -h3, -h4, -h5, -h6 { - position: relative; - margin-bottom: 0.5rem; - font-weight: 500; - line-height: 1.4; - cursor: text; -} -h1:hover a.anchor, -h2:hover a.anchor, -h3:hover a.anchor, -h4:hover a.anchor, -h5:hover a.anchor, -h6:hover a.anchor { - text-decoration: none; -} -h1 tt, -h1 code { - font-size: inherit; -} -h2 tt, -h2 code { - font-size: inherit; -} -h3 tt, -h3 code { - font-size: inherit; -} -h4 tt, -h4 code { - font-size: inherit; -} -h5 tt, -h5 code { - font-size: inherit; -} -h6 tt, -h6 code { - font-size: inherit; -} -h1 { - font-size: 2.5rem; - line-height: 1.8; -} -h2 { - font-size: 1.7rem; - line-height: 1.8; - padding-left: 0.5em; -} -.documentation h2::before { - content:""; - height:1em;; - display: block; - width:3px; - margin-left: -0.5em; - margin-top: 0.4em; - position: absolute; - background-color: var(--b1); -} -h3 { - font-size: 1.4rem; - line-height: 1.43; -} -h4 { - font-size: 1.25rem; -} -h5 { - font-size: 1rem; -} -h6 { - font-size: 1rem; - color: #777; -} -p { - margin-bottom:0.5rem; - font-size:1em; - margin-top:0; - font-weight:300; -} -ol,ul,dl { - margin-top:0; - margin-bottom: 1rem; -} -li p { - margin-bottom: 0; -} -blockquote, -table{ - margin: 0.8em 0; - width:100%; -} -figure table{ - overflow: scroll; -} -hr { - height: 2px; - padding: 0; - margin: 16px 0; - background-color: #e7e7e7; - border: 0 none; - overflow: hidden; - -webkit-box-sizing: content-box; - box-sizing: content-box; -} - -li p.first { - display: inline-block; -} -ul, -ol { - padding-left: 30px; -} -ul:first-child, -ol:first-child { - margin-top: 0; -} -ul:last-child, -ol:last-child { - margin-bottom: 0; -} -blockquote { - border-left: 4px solid #dfe2e5; - padding: 0 15px; - color: #777777; -} -blockquote blockquote { - padding-right: 0; -} -table { - padding: 0; - word-break: initial; -} -table tr { - border-top: 1px solid #dfe2e5; - margin: 0; - padding: 0; -} -table tr:nth-child(2n), -thead { - background-color: #f8f8f8; -} -table tr th { - font-weight: bold; - border: 1px solid #dfe2e5; - border-bottom: 0; - text-align: left; - margin: 0; - padding: 6px 13px; -} -table tr td { - border: 1px solid #dfe2e5; - text-align: left; - margin: 0; - padding: 6px 13px; -} -table tr th:first-child, -table tr td:first-child { - margin-top: 0; -} -table tr th:last-child, -table tr td:last-child { - margin-bottom: 0; -} -h1 code,h2 code, h3 code, h4 code, h5 code, h6 code, -p code, li code, td code, -tt { - border: 1px solid #e7eaed; - background-color: #f8f8f8; - -webkit-border-radius: 3px; - border-radius: 3px; - padding: 0; - font-size: 0.9em; - color:var(--sg1); - font-family:monospace; - background-color: #f3f4f4; - padding: 0 2px 0 2px; -} -/*Tell prettyprinted code not to follow above*/ -.prettyprint code{ - border:none; - background-color:transparent; - font-size:inherit; - padding:0 1px 0 0px; -} \ No newline at end of file diff --git a/documentation/tdenginedocs-cn/lib/docs/liner.js b/documentation/tdenginedocs-cn/lib/docs/liner.js deleted file mode 100644 index 9cfeb88e1042ba9156234de4fcc5f9b82f82cf7a..0000000000000000000000000000000000000000 --- a/documentation/tdenginedocs-cn/lib/docs/liner.js +++ /dev/null @@ -1,19 +0,0 @@ -/*JS to determine how many lines used in pre/code block, sets CSS appropriately. MUST be placed after elements with prettyprint class are loaded*/ -$('.prettyprint').toArray().forEach(function(element){ - let linenums = element.clientHeight / 25.2; - if (linenums > 99) { - $(element).addClass('threec'); - } - else if (linenums > 9) { - $(element).addClass('twoc'); - } - }); -$('.prettyprint').toArray().forEach(function(element){ - let linenums = element.clientHeight / 25.2; - if (linenums > 99) { - $(element).addClass('threec'); - } - else if (linenums > 9) { - $(element).addClass('twoc'); - } -}); \ No newline at end of file diff --git a/documentation/tdenginedocs-cn/lib/docs/prettify.js b/documentation/tdenginedocs-cn/lib/docs/prettify.js deleted file mode 100644 index d2acd5d9d4f14db8bef0005d7ba891042a6820e8..0000000000000000000000000000000000000000 --- a/documentation/tdenginedocs-cn/lib/docs/prettify.js +++ /dev/null @@ -1,46 +0,0 @@ -!function(){/* - - Copyright (C) 2006 Google Inc. - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. -*/ -"undefined"!==typeof window&&(window.PR_SHOULD_USE_CONTINUATION=!0); -(function(){function T(a){function d(e){var a=e.charCodeAt(0);if(92!==a)return a;var c=e.charAt(1);return(a=w[c])?a:"0"<=c&&"7">=c?parseInt(e.substring(1),8):"u"===c||"x"===c?parseInt(e.substring(2),16):e.charCodeAt(1)}function f(e){if(32>e)return(16>e?"\\x0":"\\x")+e.toString(16);e=String.fromCharCode(e);return"\\"===e||"-"===e||"]"===e||"^"===e?"\\"+e:e}function c(e){var c=e.substring(1,e.length-1).match(RegExp("\\\\u[0-9A-Fa-f]{4}|\\\\x[0-9A-Fa-f]{2}|\\\\[0-3][0-7]{0,2}|\\\\[0-7]{1,2}|\\\\[\\s\\S]|-|[^-\\\\]","g")); -e=[];var a="^"===c[0],b=["["];a&&b.push("^");for(var a=a?1:0,g=c.length;ak||122k||90k||122h[0]&&(h[1]+1>h[0]&&b.push("-"),b.push(f(h[1])));b.push("]");return b.join("")}function m(e){for(var a=e.source.match(RegExp("(?:\\[(?:[^\\x5C\\x5D]|\\\\[\\s\\S])*\\]|\\\\u[A-Fa-f0-9]{4}|\\\\x[A-Fa-f0-9]{2}|\\\\[0-9]+|\\\\[^ux0-9]|\\(\\?[:!=]|[\\(\\)\\^]|[^\\x5B\\x5C\\(\\)\\^]+)","g")),b=a.length,d=[],g=0,h=0;g/,null])):d.push(["com",/^#[^\r\n]*/,null,"#"]));a.cStyleComments&&(f.push(["com",/^\/\/[^\r\n]*/,null]),f.push(["com",/^\/\*[\s\S]*?(?:\*\/|$)/,null]));if(c=a.regexLiterals){var m=(c=1|\\/=?|::?|<>?>?=?|,|;|\\?|@|\\[|~|{|\\^\\^?=?|\\|\\|?=?|break|case|continue|delete|do|else|finally|instanceof|return|throw|try|typeof)\\s*("+ -("/(?=[^/*"+c+"])(?:[^/\\x5B\\x5C"+c+"]|\\x5C"+m+"|\\x5B(?:[^\\x5C\\x5D"+c+"]|\\x5C"+m+")*(?:\\x5D|$))+/")+")")])}(c=a.types)&&f.push(["typ",c]);c=(""+a.keywords).replace(/^ | $/g,"");c.length&&f.push(["kwd",new RegExp("^(?:"+c.replace(/[\s,]+/g,"|")+")\\b"),null]);d.push(["pln",/^\s+/,null," \r\n\t\u00a0"]);c="^.[^\\s\\w.$@'\"`/\\\\]*";a.regexLiterals&&(c+="(?!s*/)");f.push(["lit",/^@[a-z_$][a-z_$@0-9]*/i,null],["typ",/^(?:[@_]?[A-Z]+[a-z][A-Za-z_$@0-9]*|\w+_t\b)/,null],["pln",/^[a-z_$][a-z_$@0-9]*/i, -null],["lit",/^(?:0x[a-f0-9]+|(?:\d(?:_\d+)*\d*(?:\.\d*)?|\.\d\+)(?:e[+\-]?\d+)?)[a-z]*/i,null,"0123456789"],["pln",/^\\[\s\S]?/,null],["pun",new RegExp(c),null]);return G(d,f)}function L(a,d,f){function c(a){var b=a.nodeType;if(1==b&&!t.test(a.className))if("br"===a.nodeName.toLowerCase())m(a),a.parentNode&&a.parentNode.removeChild(a);else for(a=a.firstChild;a;a=a.nextSibling)c(a);else if((3==b||4==b)&&f){var e=a.nodeValue,d=e.match(q);d&&(b=e.substring(0,d.index),a.nodeValue=b,(e=e.substring(d.index+ -d[0].length))&&a.parentNode.insertBefore(l.createTextNode(e),a.nextSibling),m(a),b||a.parentNode.removeChild(a))}}function m(a){function c(a,b){var e=b?a.cloneNode(!1):a,k=a.parentNode;if(k){var k=c(k,1),d=a.nextSibling;k.appendChild(e);for(var f=d;f;f=d)d=f.nextSibling,k.appendChild(f)}return e}for(;!a.nextSibling;)if(a=a.parentNode,!a)return;a=c(a.nextSibling,0);for(var e;(e=a.parentNode)&&1===e.nodeType;)a=e;b.push(a)}for(var t=/(?:^|\s)nocode(?:\s|$)/,q=/\r\n?|\n/,l=a.ownerDocument,n=l.createElement("li");a.firstChild;)n.appendChild(a.firstChild); -for(var b=[n],p=0;p=+m[1],d=/\n/g,t=a.a,q=t.length,f=0,l=a.c,n=l.length,c=0,b=a.g,p=b.length,w=0;b[p]=q;var r,e;for(e=r=0;e=h&&(c+=2);f>=k&&(w+=2)}}finally{g&&(g.style.display=a)}}catch(y){D.console&&console.log(y&&y.stack||y)}}var D="undefined"!==typeof window? -window:{},B=["break,continue,do,else,for,if,return,while"],F=[[B,"auto,case,char,const,default,double,enum,extern,float,goto,inline,int,long,register,restrict,short,signed,sizeof,static,struct,switch,typedef,union,unsigned,void,volatile"],"catch,class,delete,false,import,new,operator,private,protected,public,this,throw,true,try,typeof"],H=[F,"alignas,alignof,align_union,asm,axiom,bool,concept,concept_map,const_cast,constexpr,decltype,delegate,dynamic_cast,explicit,export,friend,generic,late_check,mutable,namespace,noexcept,noreturn,nullptr,property,reinterpret_cast,static_assert,static_cast,template,typeid,typename,using,virtual,where"], -O=[F,"abstract,assert,boolean,byte,extends,finally,final,implements,import,instanceof,interface,null,native,package,strictfp,super,synchronized,throws,transient"],P=[F,"abstract,add,alias,as,ascending,async,await,base,bool,by,byte,checked,decimal,delegate,descending,dynamic,event,finally,fixed,foreach,from,get,global,group,implicit,in,interface,internal,into,is,join,let,lock,null,object,out,override,orderby,params,partial,readonly,ref,remove,sbyte,sealed,select,set,stackalloc,string,select,uint,ulong,unchecked,unsafe,ushort,value,var,virtual,where,yield"], -F=[F,"abstract,async,await,constructor,debugger,enum,eval,export,from,function,get,import,implements,instanceof,interface,let,null,of,set,undefined,var,with,yield,Infinity,NaN"],Q=[B,"and,as,assert,class,def,del,elif,except,exec,finally,from,global,import,in,is,lambda,nonlocal,not,or,pass,print,raise,try,with,yield,False,True,None"],R=[B,"alias,and,begin,case,class,def,defined,elsif,end,ensure,false,in,module,next,nil,not,or,redo,rescue,retry,self,super,then,true,undef,unless,until,when,yield,BEGIN,END"], -B=[B,"case,done,elif,esac,eval,fi,function,in,local,set,then,until"],S=/^(DIR|FILE|array|vector|(de|priority_)?queue|(forward_)?list|stack|(const_)?(reverse_)?iterator|(unordered_)?(multi)?(set|map)|bitset|u?(int|float)\d*)\b/,W=/\S/,X=x({keywords:[H,P,O,F,"caller,delete,die,do,dump,elsif,eval,exit,foreach,for,goto,if,import,last,local,my,next,no,our,print,package,redo,require,sub,undef,unless,until,use,wantarray,while,BEGIN,END",Q,R,B],hashComments:!0,cStyleComments:!0,multiLineStrings:!0,regexLiterals:!0}), -I={};t(X,["default-code"]);t(G([],[["pln",/^[^]*(?:>|$)/],["com",/^<\!--[\s\S]*?(?:-\->|$)/],["lang-",/^<\?([\s\S]+?)(?:\?>|$)/],["lang-",/^<%([\s\S]+?)(?:%>|$)/],["pun",/^(?:<[%?]|[%?]>)/],["lang-",/^]*>([\s\S]+?)<\/xmp\b[^>]*>/i],["lang-js",/^]*>([\s\S]*?)(<\/script\b[^>]*>)/i],["lang-css",/^]*>([\s\S]*?)(<\/style\b[^>]*>)/i],["lang-in.tag",/^(<\/?[a-z][^<>]*>)/i]]),"default-markup htm html mxml xhtml xml xsl".split(" "));t(G([["pln",/^[\s]+/, -null," \t\r\n"],["atv",/^(?:\"[^\"]*\"?|\'[^\']*\'?)/,null,"\"'"]],[["tag",/^^<\/?[a-z](?:[\w.:-]*\w)?|\/?>$/i],["atn",/^(?!style[\s=]|on)[a-z](?:[\w:-]*\w)?/i],["lang-uq.val",/^=\s*([^>\'\"\s]*(?:[^>\'\"\s\/]|\/(?=\s)))/],["pun",/^[=<>\/]+/],["lang-js",/^on\w+\s*=\s*\"([^\"]+)\"/i],["lang-js",/^on\w+\s*=\s*\'([^\']+)\'/i],["lang-js",/^on\w+\s*=\s*([^\"\'>\s]+)/i],["lang-css",/^style\s*=\s*\"([^\"]+)\"/i],["lang-css",/^style\s*=\s*\'([^\']+)\'/i],["lang-css",/^style\s*=\s*([^\"\'>\s]+)/i]]),["in.tag"]); -t(G([],[["atv",/^[\s\S]+/]]),["uq.val"]);t(x({keywords:H,hashComments:!0,cStyleComments:!0,types:S}),"c cc cpp cxx cyc m".split(" "));t(x({keywords:"null,true,false"}),["json"]);t(x({keywords:P,hashComments:!0,cStyleComments:!0,verbatimStrings:!0,types:S}),["cs"]);t(x({keywords:O,cStyleComments:!0}),["java"]);t(x({keywords:B,hashComments:!0,multiLineStrings:!0}),["bash","bsh","csh","sh"]);t(x({keywords:Q,hashComments:!0,multiLineStrings:!0,tripleQuotedStrings:!0}),["cv","py","python"]);t(x({keywords:"caller,delete,die,do,dump,elsif,eval,exit,foreach,for,goto,if,import,last,local,my,next,no,our,print,package,redo,require,sub,undef,unless,until,use,wantarray,while,BEGIN,END", -hashComments:!0,multiLineStrings:!0,regexLiterals:2}),["perl","pl","pm"]);t(x({keywords:R,hashComments:!0,multiLineStrings:!0,regexLiterals:!0}),["rb","ruby"]);t(x({keywords:F,cStyleComments:!0,regexLiterals:!0}),["javascript","js","ts","typescript"]);t(x({keywords:"all,and,by,catch,class,else,extends,false,finally,for,if,in,is,isnt,loop,new,no,not,null,of,off,on,or,return,super,then,throw,true,try,unless,until,when,while,yes",hashComments:3,cStyleComments:!0,multilineStrings:!0,tripleQuotedStrings:!0, -regexLiterals:!0}),["coffee"]);t(G([],[["str",/^[\s\S]+/]]),["regex"]);var Y=D.PR={createSimpleLexer:G,registerLangHandler:t,sourceDecorator:x,PR_ATTRIB_NAME:"atn",PR_ATTRIB_VALUE:"atv",PR_COMMENT:"com",PR_DECLARATION:"dec",PR_KEYWORD:"kwd",PR_LITERAL:"lit",PR_NOCODE:"nocode",PR_PLAIN:"pln",PR_PUNCTUATION:"pun",PR_SOURCE:"src",PR_STRING:"str",PR_TAG:"tag",PR_TYPE:"typ",TAOSDATA_FUNCTION:"td-fun",TAOSDATA_DATATYPE:"td-dtp",TAOSDATA_TERMINAL:"tem",TAOSDATA_OPTION:"td-opt",prettyPrintOne:D.prettyPrintOne=function(a,d,f){f=f||!1;d=d||null;var c=document.createElement("div");c.innerHTML="
    "+a+"
    "; -c=c.firstChild;f&&L(c,f,!0);M({j:d,m:f,h:c,l:1,a:null,i:null,c:null,g:null});return c.innerHTML},prettyPrint:D.prettyPrint=function(a,d){function f(){for(var c=D.PR_SHOULD_USE_CONTINUATION?b.now()+250:Infinity;p li { - counter-increment: customlistcounter; -} -pre.prettyprint ol > li:first-child:before { - border-top-left-radius: 0.25rem; -} -pre.prettyprint ol > li:last-child:before { - border-bottom-left-radius: 0.25rem; -} -pre.prettyprint ol > li:before { - content: counter(customlistcounter) " "; - font-weight: 300; - display: inline-block; - position: absolute; - transform:translateX(-38px); - width: 27px; - text-align: right; - background-color:var(--white); - padding-bottom: 0.1px; -} -pre.prettyprint ol > li:nth-last-child(1)::before { - padding-bottom: 0px !important; -} - -pre.prettyprint.twoc ol > li:before { - transform:translateX(-45px); - width:34px; -} -pre.prettyprint.twoc { - padding-left:35px; -} -pre.prettyprint.threec ol > li:before { - transform:translateX(-53px); - width:42px; -} -pre.prettyprint.threec { - padding-left:43px; -} - -ol:first-child { - counter-reset: customlistcounter; -} -pre.prettyprint ol { - padding-right: 4px; -} -pre .atn, -pre .kwd, -pre .tag { - font-weight: 400 -} -pre * { - font-family:monospace; -} -pre.prettyprint li { - background-color:rgb(244,245,246); -} -pre.prettyprint { - display: block; - background-color:rgb(244,245,246); - border-radius:0.25rem; - padding-left: 27px; - /*each additional digit needs 8px*/ - width:100%; - border:1px solid #e7eaed; - color:#d58936; -} -/* TAOSDATA Specific */ -pre.lang-blank span { - color:var(--sg1); -} -pre.lang-blank { - -} -pre.lang-term span{ - color: var(--white) ; -} -pre.lang-term ol { - background-color: var(--sg1); -} -pre.lang-term ol.linenums { - border-left:1px solid var(--sg1); -} -pre.lang-term li { - background-color:var(--sg1); -} -/*Functions*/ -pre .td-fun { - color:#f24352; -} -/*Options*/ -pre .td-opt { - /*color:mediumpurple;*/ - color:#5882bc; -} -/*Datatypes*/ -pre .td-dtp { - color:darkcyan; -} -pre .nocode { - background-color: var(--white); - color: var(--sg1); -} -/*Strings*/ -pre .str { - color: #690; -} -/*Keywords*/ -pre .kwd { - color: #5882bc; -} -/*Comments*/ -pre .com { - color: slategray; -} -/*Type*/ -pre .typ { - color: #9c5fc6; -} -/*Literals*/ -pre .lit { - color: #91001f; -} -/*Plain Text*/ -pre .pln { - color: #d58936; -} -/*Punctuation*/ -pre .pun { - color: rgb(51,66,78); -} -pre .tag { - color: khaki -} - -pre .atn { - color: #bdb76b -} - -pre .atv { - color: #ffa0a0 -} - -pre .dec { - color: #98fb98 -} - -ol.linenums { - margin-top: 0; - margin-bottom: 0; - color: #AEAEAE; - border-left:1px solid var(--b1); - padding-left: 0px; -} -pre li { - padding-left: 0.6rem; -} -li.L0, -li.L1, -li.L2, -li.L3, -li.L5, -li.L6, -li.L7, -li.L8 { - list-style-type: none -} - -@media print { - pre.prettyprint { - background-color: none - } - - code .str, - pre .str { - color: #690; - } - - code .kwd, - pre .kwd { - color: #5882bc; - font-weight: 400 - } - - code .com, - pre .com { - color: #600; - font-style: italic - } - - code .typ, - pre .typ { - color: #404; - font-weight: 400 - } - - code .lit, - pre .lit { - color: #044 - } - - code .pun, - pre .pun { - color: #440 - } - - code .pln, - pre .pln { - color: #000 - } - - code .tag, - pre .tag { - color: #006; - font-weight: 400 - } - - code .atn, - pre .atn { - color: #404 - } - - code .atv, - pre .atv { - color: #060 - } -} \ No newline at end of file diff --git a/documentation/tdenginedocs-cn/lib/jquery-3.4.1.min.js b/documentation/tdenginedocs-cn/lib/jquery-3.4.1.min.js deleted file mode 100644 index a1c07fd803b5fc9c54f44e31123ae4fa11e134b0..0000000000000000000000000000000000000000 --- a/documentation/tdenginedocs-cn/lib/jquery-3.4.1.min.js +++ /dev/null @@ -1,2 +0,0 @@ -/*! jQuery v3.4.1 | (c) JS Foundation and other contributors | jquery.org/license */ -!function(e,t){"use strict";"object"==typeof module&&"object"==typeof module.exports?module.exports=e.document?t(e,!0):function(e){if(!e.document)throw new Error("jQuery requires a window with a document");return t(e)}:t(e)}("undefined"!=typeof window?window:this,function(C,e){"use strict";var t=[],E=C.document,r=Object.getPrototypeOf,s=t.slice,g=t.concat,u=t.push,i=t.indexOf,n={},o=n.toString,v=n.hasOwnProperty,a=v.toString,l=a.call(Object),y={},m=function(e){return"function"==typeof e&&"number"!=typeof e.nodeType},x=function(e){return null!=e&&e===e.window},c={type:!0,src:!0,nonce:!0,noModule:!0};function b(e,t,n){var r,i,o=(n=n||E).createElement("script");if(o.text=e,t)for(r in c)(i=t[r]||t.getAttribute&&t.getAttribute(r))&&o.setAttribute(r,i);n.head.appendChild(o).parentNode.removeChild(o)}function w(e){return null==e?e+"":"object"==typeof e||"function"==typeof e?n[o.call(e)]||"object":typeof e}var f="3.4.1",k=function(e,t){return new k.fn.init(e,t)},p=/^[\s\uFEFF\xA0]+|[\s\uFEFF\xA0]+$/g;function d(e){var t=!!e&&"length"in e&&e.length,n=w(e);return!m(e)&&!x(e)&&("array"===n||0===t||"number"==typeof t&&0+~]|"+M+")"+M+"*"),U=new RegExp(M+"|>"),X=new RegExp($),V=new RegExp("^"+I+"$"),G={ID:new RegExp("^#("+I+")"),CLASS:new RegExp("^\\.("+I+")"),TAG:new RegExp("^("+I+"|[*])"),ATTR:new RegExp("^"+W),PSEUDO:new RegExp("^"+$),CHILD:new RegExp("^:(only|first|last|nth|nth-last)-(child|of-type)(?:\\("+M+"*(even|odd|(([+-]|)(\\d*)n|)"+M+"*(?:([+-]|)"+M+"*(\\d+)|))"+M+"*\\)|)","i"),bool:new RegExp("^(?:"+R+")$","i"),needsContext:new RegExp("^"+M+"*[>+~]|:(even|odd|eq|gt|lt|nth|first|last)(?:\\("+M+"*((?:-\\d)?\\d*)"+M+"*\\)|)(?=[^-]|$)","i")},Y=/HTML$/i,Q=/^(?:input|select|textarea|button)$/i,J=/^h\d$/i,K=/^[^{]+\{\s*\[native \w/,Z=/^(?:#([\w-]+)|(\w+)|\.([\w-]+))$/,ee=/[+~]/,te=new RegExp("\\\\([\\da-f]{1,6}"+M+"?|("+M+")|.)","ig"),ne=function(e,t,n){var r="0x"+t-65536;return r!=r||n?t:r<0?String.fromCharCode(r+65536):String.fromCharCode(r>>10|55296,1023&r|56320)},re=/([\0-\x1f\x7f]|^-?\d)|^-$|[^\0-\x1f\x7f-\uFFFF\w-]/g,ie=function(e,t){return t?"\0"===e?"\ufffd":e.slice(0,-1)+"\\"+e.charCodeAt(e.length-1).toString(16)+" ":"\\"+e},oe=function(){T()},ae=be(function(e){return!0===e.disabled&&"fieldset"===e.nodeName.toLowerCase()},{dir:"parentNode",next:"legend"});try{H.apply(t=O.call(m.childNodes),m.childNodes),t[m.childNodes.length].nodeType}catch(e){H={apply:t.length?function(e,t){L.apply(e,O.call(t))}:function(e,t){var n=e.length,r=0;while(e[n++]=t[r++]);e.length=n-1}}}function se(t,e,n,r){var i,o,a,s,u,l,c,f=e&&e.ownerDocument,p=e?e.nodeType:9;if(n=n||[],"string"!=typeof t||!t||1!==p&&9!==p&&11!==p)return n;if(!r&&((e?e.ownerDocument||e:m)!==C&&T(e),e=e||C,E)){if(11!==p&&(u=Z.exec(t)))if(i=u[1]){if(9===p){if(!(a=e.getElementById(i)))return n;if(a.id===i)return n.push(a),n}else if(f&&(a=f.getElementById(i))&&y(e,a)&&a.id===i)return n.push(a),n}else{if(u[2])return H.apply(n,e.getElementsByTagName(t)),n;if((i=u[3])&&d.getElementsByClassName&&e.getElementsByClassName)return H.apply(n,e.getElementsByClassName(i)),n}if(d.qsa&&!A[t+" "]&&(!v||!v.test(t))&&(1!==p||"object"!==e.nodeName.toLowerCase())){if(c=t,f=e,1===p&&U.test(t)){(s=e.getAttribute("id"))?s=s.replace(re,ie):e.setAttribute("id",s=k),o=(l=h(t)).length;while(o--)l[o]="#"+s+" "+xe(l[o]);c=l.join(","),f=ee.test(t)&&ye(e.parentNode)||e}try{return H.apply(n,f.querySelectorAll(c)),n}catch(e){A(t,!0)}finally{s===k&&e.removeAttribute("id")}}}return g(t.replace(B,"$1"),e,n,r)}function ue(){var r=[];return function e(t,n){return r.push(t+" ")>b.cacheLength&&delete e[r.shift()],e[t+" "]=n}}function le(e){return e[k]=!0,e}function ce(e){var t=C.createElement("fieldset");try{return!!e(t)}catch(e){return!1}finally{t.parentNode&&t.parentNode.removeChild(t),t=null}}function fe(e,t){var n=e.split("|"),r=n.length;while(r--)b.attrHandle[n[r]]=t}function pe(e,t){var n=t&&e,r=n&&1===e.nodeType&&1===t.nodeType&&e.sourceIndex-t.sourceIndex;if(r)return r;if(n)while(n=n.nextSibling)if(n===t)return-1;return e?1:-1}function de(t){return function(e){return"input"===e.nodeName.toLowerCase()&&e.type===t}}function he(n){return function(e){var t=e.nodeName.toLowerCase();return("input"===t||"button"===t)&&e.type===n}}function ge(t){return function(e){return"form"in e?e.parentNode&&!1===e.disabled?"label"in e?"label"in e.parentNode?e.parentNode.disabled===t:e.disabled===t:e.isDisabled===t||e.isDisabled!==!t&&ae(e)===t:e.disabled===t:"label"in e&&e.disabled===t}}function ve(a){return le(function(o){return o=+o,le(function(e,t){var n,r=a([],e.length,o),i=r.length;while(i--)e[n=r[i]]&&(e[n]=!(t[n]=e[n]))})})}function ye(e){return e&&"undefined"!=typeof e.getElementsByTagName&&e}for(e in d=se.support={},i=se.isXML=function(e){var t=e.namespaceURI,n=(e.ownerDocument||e).documentElement;return!Y.test(t||n&&n.nodeName||"HTML")},T=se.setDocument=function(e){var t,n,r=e?e.ownerDocument||e:m;return r!==C&&9===r.nodeType&&r.documentElement&&(a=(C=r).documentElement,E=!i(C),m!==C&&(n=C.defaultView)&&n.top!==n&&(n.addEventListener?n.addEventListener("unload",oe,!1):n.attachEvent&&n.attachEvent("onunload",oe)),d.attributes=ce(function(e){return e.className="i",!e.getAttribute("className")}),d.getElementsByTagName=ce(function(e){return e.appendChild(C.createComment("")),!e.getElementsByTagName("*").length}),d.getElementsByClassName=K.test(C.getElementsByClassName),d.getById=ce(function(e){return a.appendChild(e).id=k,!C.getElementsByName||!C.getElementsByName(k).length}),d.getById?(b.filter.ID=function(e){var t=e.replace(te,ne);return function(e){return e.getAttribute("id")===t}},b.find.ID=function(e,t){if("undefined"!=typeof t.getElementById&&E){var n=t.getElementById(e);return n?[n]:[]}}):(b.filter.ID=function(e){var n=e.replace(te,ne);return function(e){var t="undefined"!=typeof e.getAttributeNode&&e.getAttributeNode("id");return t&&t.value===n}},b.find.ID=function(e,t){if("undefined"!=typeof t.getElementById&&E){var n,r,i,o=t.getElementById(e);if(o){if((n=o.getAttributeNode("id"))&&n.value===e)return[o];i=t.getElementsByName(e),r=0;while(o=i[r++])if((n=o.getAttributeNode("id"))&&n.value===e)return[o]}return[]}}),b.find.TAG=d.getElementsByTagName?function(e,t){return"undefined"!=typeof t.getElementsByTagName?t.getElementsByTagName(e):d.qsa?t.querySelectorAll(e):void 0}:function(e,t){var n,r=[],i=0,o=t.getElementsByTagName(e);if("*"===e){while(n=o[i++])1===n.nodeType&&r.push(n);return r}return o},b.find.CLASS=d.getElementsByClassName&&function(e,t){if("undefined"!=typeof t.getElementsByClassName&&E)return t.getElementsByClassName(e)},s=[],v=[],(d.qsa=K.test(C.querySelectorAll))&&(ce(function(e){a.appendChild(e).innerHTML="",e.querySelectorAll("[msallowcapture^='']").length&&v.push("[*^$]="+M+"*(?:''|\"\")"),e.querySelectorAll("[selected]").length||v.push("\\["+M+"*(?:value|"+R+")"),e.querySelectorAll("[id~="+k+"-]").length||v.push("~="),e.querySelectorAll(":checked").length||v.push(":checked"),e.querySelectorAll("a#"+k+"+*").length||v.push(".#.+[+~]")}),ce(function(e){e.innerHTML="";var t=C.createElement("input");t.setAttribute("type","hidden"),e.appendChild(t).setAttribute("name","D"),e.querySelectorAll("[name=d]").length&&v.push("name"+M+"*[*^$|!~]?="),2!==e.querySelectorAll(":enabled").length&&v.push(":enabled",":disabled"),a.appendChild(e).disabled=!0,2!==e.querySelectorAll(":disabled").length&&v.push(":enabled",":disabled"),e.querySelectorAll("*,:x"),v.push(",.*:")})),(d.matchesSelector=K.test(c=a.matches||a.webkitMatchesSelector||a.mozMatchesSelector||a.oMatchesSelector||a.msMatchesSelector))&&ce(function(e){d.disconnectedMatch=c.call(e,"*"),c.call(e,"[s!='']:x"),s.push("!=",$)}),v=v.length&&new RegExp(v.join("|")),s=s.length&&new RegExp(s.join("|")),t=K.test(a.compareDocumentPosition),y=t||K.test(a.contains)?function(e,t){var n=9===e.nodeType?e.documentElement:e,r=t&&t.parentNode;return e===r||!(!r||1!==r.nodeType||!(n.contains?n.contains(r):e.compareDocumentPosition&&16&e.compareDocumentPosition(r)))}:function(e,t){if(t)while(t=t.parentNode)if(t===e)return!0;return!1},D=t?function(e,t){if(e===t)return l=!0,0;var n=!e.compareDocumentPosition-!t.compareDocumentPosition;return n||(1&(n=(e.ownerDocument||e)===(t.ownerDocument||t)?e.compareDocumentPosition(t):1)||!d.sortDetached&&t.compareDocumentPosition(e)===n?e===C||e.ownerDocument===m&&y(m,e)?-1:t===C||t.ownerDocument===m&&y(m,t)?1:u?P(u,e)-P(u,t):0:4&n?-1:1)}:function(e,t){if(e===t)return l=!0,0;var n,r=0,i=e.parentNode,o=t.parentNode,a=[e],s=[t];if(!i||!o)return e===C?-1:t===C?1:i?-1:o?1:u?P(u,e)-P(u,t):0;if(i===o)return pe(e,t);n=e;while(n=n.parentNode)a.unshift(n);n=t;while(n=n.parentNode)s.unshift(n);while(a[r]===s[r])r++;return r?pe(a[r],s[r]):a[r]===m?-1:s[r]===m?1:0}),C},se.matches=function(e,t){return se(e,null,null,t)},se.matchesSelector=function(e,t){if((e.ownerDocument||e)!==C&&T(e),d.matchesSelector&&E&&!A[t+" "]&&(!s||!s.test(t))&&(!v||!v.test(t)))try{var n=c.call(e,t);if(n||d.disconnectedMatch||e.document&&11!==e.document.nodeType)return n}catch(e){A(t,!0)}return 0":{dir:"parentNode",first:!0}," ":{dir:"parentNode"},"+":{dir:"previousSibling",first:!0},"~":{dir:"previousSibling"}},preFilter:{ATTR:function(e){return e[1]=e[1].replace(te,ne),e[3]=(e[3]||e[4]||e[5]||"").replace(te,ne),"~="===e[2]&&(e[3]=" "+e[3]+" "),e.slice(0,4)},CHILD:function(e){return e[1]=e[1].toLowerCase(),"nth"===e[1].slice(0,3)?(e[3]||se.error(e[0]),e[4]=+(e[4]?e[5]+(e[6]||1):2*("even"===e[3]||"odd"===e[3])),e[5]=+(e[7]+e[8]||"odd"===e[3])):e[3]&&se.error(e[0]),e},PSEUDO:function(e){var t,n=!e[6]&&e[2];return G.CHILD.test(e[0])?null:(e[3]?e[2]=e[4]||e[5]||"":n&&X.test(n)&&(t=h(n,!0))&&(t=n.indexOf(")",n.length-t)-n.length)&&(e[0]=e[0].slice(0,t),e[2]=n.slice(0,t)),e.slice(0,3))}},filter:{TAG:function(e){var t=e.replace(te,ne).toLowerCase();return"*"===e?function(){return!0}:function(e){return e.nodeName&&e.nodeName.toLowerCase()===t}},CLASS:function(e){var t=p[e+" "];return t||(t=new RegExp("(^|"+M+")"+e+"("+M+"|$)"))&&p(e,function(e){return t.test("string"==typeof e.className&&e.className||"undefined"!=typeof e.getAttribute&&e.getAttribute("class")||"")})},ATTR:function(n,r,i){return function(e){var t=se.attr(e,n);return null==t?"!="===r:!r||(t+="","="===r?t===i:"!="===r?t!==i:"^="===r?i&&0===t.indexOf(i):"*="===r?i&&-1:\x20\t\r\n\f]*)[\x20\t\r\n\f]*\/?>(?:<\/\1>|)$/i;function j(e,n,r){return m(n)?k.grep(e,function(e,t){return!!n.call(e,t,e)!==r}):n.nodeType?k.grep(e,function(e){return e===n!==r}):"string"!=typeof n?k.grep(e,function(e){return-1)[^>]*|#([\w-]+))$/;(k.fn.init=function(e,t,n){var r,i;if(!e)return this;if(n=n||q,"string"==typeof e){if(!(r="<"===e[0]&&">"===e[e.length-1]&&3<=e.length?[null,e,null]:L.exec(e))||!r[1]&&t)return!t||t.jquery?(t||n).find(e):this.constructor(t).find(e);if(r[1]){if(t=t instanceof k?t[0]:t,k.merge(this,k.parseHTML(r[1],t&&t.nodeType?t.ownerDocument||t:E,!0)),D.test(r[1])&&k.isPlainObject(t))for(r in t)m(this[r])?this[r](t[r]):this.attr(r,t[r]);return this}return(i=E.getElementById(r[2]))&&(this[0]=i,this.length=1),this}return e.nodeType?(this[0]=e,this.length=1,this):m(e)?void 0!==n.ready?n.ready(e):e(k):k.makeArray(e,this)}).prototype=k.fn,q=k(E);var H=/^(?:parents|prev(?:Until|All))/,O={children:!0,contents:!0,next:!0,prev:!0};function P(e,t){while((e=e[t])&&1!==e.nodeType);return e}k.fn.extend({has:function(e){var t=k(e,this),n=t.length;return this.filter(function(){for(var e=0;e\x20\t\r\n\f]*)/i,he=/^$|^module$|\/(?:java|ecma)script/i,ge={option:[1,""],thead:[1,"","
    "],col:[2,"","
    "],tr:[2,"","
    "],td:[3,"","
    "],_default:[0,"",""]};function ve(e,t){var n;return n="undefined"!=typeof e.getElementsByTagName?e.getElementsByTagName(t||"*"):"undefined"!=typeof e.querySelectorAll?e.querySelectorAll(t||"*"):[],void 0===t||t&&A(e,t)?k.merge([e],n):n}function ye(e,t){for(var n=0,r=e.length;nx",y.noCloneChecked=!!me.cloneNode(!0).lastChild.defaultValue;var Te=/^key/,Ce=/^(?:mouse|pointer|contextmenu|drag|drop)|click/,Ee=/^([^.]*)(?:\.(.+)|)/;function ke(){return!0}function Se(){return!1}function Ne(e,t){return e===function(){try{return E.activeElement}catch(e){}}()==("focus"===t)}function Ae(e,t,n,r,i,o){var a,s;if("object"==typeof t){for(s in"string"!=typeof n&&(r=r||n,n=void 0),t)Ae(e,s,n,r,t[s],o);return e}if(null==r&&null==i?(i=n,r=n=void 0):null==i&&("string"==typeof n?(i=r,r=void 0):(i=r,r=n,n=void 0)),!1===i)i=Se;else if(!i)return e;return 1===o&&(a=i,(i=function(e){return k().off(e),a.apply(this,arguments)}).guid=a.guid||(a.guid=k.guid++)),e.each(function(){k.event.add(this,t,i,r,n)})}function De(e,i,o){o?(Q.set(e,i,!1),k.event.add(e,i,{namespace:!1,handler:function(e){var t,n,r=Q.get(this,i);if(1&e.isTrigger&&this[i]){if(r.length)(k.event.special[i]||{}).delegateType&&e.stopPropagation();else if(r=s.call(arguments),Q.set(this,i,r),t=o(this,i),this[i](),r!==(n=Q.get(this,i))||t?Q.set(this,i,!1):n={},r!==n)return e.stopImmediatePropagation(),e.preventDefault(),n.value}else r.length&&(Q.set(this,i,{value:k.event.trigger(k.extend(r[0],k.Event.prototype),r.slice(1),this)}),e.stopImmediatePropagation())}})):void 0===Q.get(e,i)&&k.event.add(e,i,ke)}k.event={global:{},add:function(t,e,n,r,i){var o,a,s,u,l,c,f,p,d,h,g,v=Q.get(t);if(v){n.handler&&(n=(o=n).handler,i=o.selector),i&&k.find.matchesSelector(ie,i),n.guid||(n.guid=k.guid++),(u=v.events)||(u=v.events={}),(a=v.handle)||(a=v.handle=function(e){return"undefined"!=typeof k&&k.event.triggered!==e.type?k.event.dispatch.apply(t,arguments):void 0}),l=(e=(e||"").match(R)||[""]).length;while(l--)d=g=(s=Ee.exec(e[l])||[])[1],h=(s[2]||"").split(".").sort(),d&&(f=k.event.special[d]||{},d=(i?f.delegateType:f.bindType)||d,f=k.event.special[d]||{},c=k.extend({type:d,origType:g,data:r,handler:n,guid:n.guid,selector:i,needsContext:i&&k.expr.match.needsContext.test(i),namespace:h.join(".")},o),(p=u[d])||((p=u[d]=[]).delegateCount=0,f.setup&&!1!==f.setup.call(t,r,h,a)||t.addEventListener&&t.addEventListener(d,a)),f.add&&(f.add.call(t,c),c.handler.guid||(c.handler.guid=n.guid)),i?p.splice(p.delegateCount++,0,c):p.push(c),k.event.global[d]=!0)}},remove:function(e,t,n,r,i){var o,a,s,u,l,c,f,p,d,h,g,v=Q.hasData(e)&&Q.get(e);if(v&&(u=v.events)){l=(t=(t||"").match(R)||[""]).length;while(l--)if(d=g=(s=Ee.exec(t[l])||[])[1],h=(s[2]||"").split(".").sort(),d){f=k.event.special[d]||{},p=u[d=(r?f.delegateType:f.bindType)||d]||[],s=s[2]&&new RegExp("(^|\\.)"+h.join("\\.(?:.*\\.|)")+"(\\.|$)"),a=o=p.length;while(o--)c=p[o],!i&&g!==c.origType||n&&n.guid!==c.guid||s&&!s.test(c.namespace)||r&&r!==c.selector&&("**"!==r||!c.selector)||(p.splice(o,1),c.selector&&p.delegateCount--,f.remove&&f.remove.call(e,c));a&&!p.length&&(f.teardown&&!1!==f.teardown.call(e,h,v.handle)||k.removeEvent(e,d,v.handle),delete u[d])}else for(d in u)k.event.remove(e,d+t[l],n,r,!0);k.isEmptyObject(u)&&Q.remove(e,"handle events")}},dispatch:function(e){var t,n,r,i,o,a,s=k.event.fix(e),u=new Array(arguments.length),l=(Q.get(this,"events")||{})[s.type]||[],c=k.event.special[s.type]||{};for(u[0]=s,t=1;t\x20\t\r\n\f]*)[^>]*)\/>/gi,qe=/\s*$/g;function Oe(e,t){return A(e,"table")&&A(11!==t.nodeType?t:t.firstChild,"tr")&&k(e).children("tbody")[0]||e}function Pe(e){return e.type=(null!==e.getAttribute("type"))+"/"+e.type,e}function Re(e){return"true/"===(e.type||"").slice(0,5)?e.type=e.type.slice(5):e.removeAttribute("type"),e}function Me(e,t){var n,r,i,o,a,s,u,l;if(1===t.nodeType){if(Q.hasData(e)&&(o=Q.access(e),a=Q.set(t,o),l=o.events))for(i in delete a.handle,a.events={},l)for(n=0,r=l[i].length;n")},clone:function(e,t,n){var r,i,o,a,s,u,l,c=e.cloneNode(!0),f=oe(e);if(!(y.noCloneChecked||1!==e.nodeType&&11!==e.nodeType||k.isXMLDoc(e)))for(a=ve(c),r=0,i=(o=ve(e)).length;r").attr(n.scriptAttrs||{}).prop({charset:n.scriptCharset,src:n.url}).on("load error",i=function(e){r.remove(),i=null,e&&t("error"===e.type?404:200,e.type)}),E.head.appendChild(r[0])},abort:function(){i&&i()}}});var Vt,Gt=[],Yt=/(=)\?(?=&|$)|\?\?/;k.ajaxSetup({jsonp:"callback",jsonpCallback:function(){var e=Gt.pop()||k.expando+"_"+kt++;return this[e]=!0,e}}),k.ajaxPrefilter("json jsonp",function(e,t,n){var r,i,o,a=!1!==e.jsonp&&(Yt.test(e.url)?"url":"string"==typeof e.data&&0===(e.contentType||"").indexOf("application/x-www-form-urlencoded")&&Yt.test(e.data)&&"data");if(a||"jsonp"===e.dataTypes[0])return r=e.jsonpCallback=m(e.jsonpCallback)?e.jsonpCallback():e.jsonpCallback,a?e[a]=e[a].replace(Yt,"$1"+r):!1!==e.jsonp&&(e.url+=(St.test(e.url)?"&":"?")+e.jsonp+"="+r),e.converters["script json"]=function(){return o||k.error(r+" was not called"),o[0]},e.dataTypes[0]="json",i=C[r],C[r]=function(){o=arguments},n.always(function(){void 0===i?k(C).removeProp(r):C[r]=i,e[r]&&(e.jsonpCallback=t.jsonpCallback,Gt.push(r)),o&&m(i)&&i(o[0]),o=i=void 0}),"script"}),y.createHTMLDocument=((Vt=E.implementation.createHTMLDocument("").body).innerHTML="
    ",2===Vt.childNodes.length),k.parseHTML=function(e,t,n){return"string"!=typeof e?[]:("boolean"==typeof t&&(n=t,t=!1),t||(y.createHTMLDocument?((r=(t=E.implementation.createHTMLDocument("")).createElement("base")).href=E.location.href,t.head.appendChild(r)):t=E),o=!n&&[],(i=D.exec(e))?[t.createElement(i[1])]:(i=we([e],t,o),o&&o.length&&k(o).remove(),k.merge([],i.childNodes)));var r,i,o},k.fn.load=function(e,t,n){var r,i,o,a=this,s=e.indexOf(" ");return-1").append(k.parseHTML(e)).find(r):e)}).always(n&&function(e,t){a.each(function(){n.apply(this,o||[e.responseText,t,e])})}),this},k.each(["ajaxStart","ajaxStop","ajaxComplete","ajaxError","ajaxSuccess","ajaxSend"],function(e,t){k.fn[t]=function(e){return this.on(t,e)}}),k.expr.pseudos.animated=function(t){return k.grep(k.timers,function(e){return t===e.elem}).length},k.offset={setOffset:function(e,t,n){var r,i,o,a,s,u,l=k.css(e,"position"),c=k(e),f={};"static"===l&&(e.style.position="relative"),s=c.offset(),o=k.css(e,"top"),u=k.css(e,"left"),("absolute"===l||"fixed"===l)&&-1<(o+u).indexOf("auto")?(a=(r=c.position()).top,i=r.left):(a=parseFloat(o)||0,i=parseFloat(u)||0),m(t)&&(t=t.call(e,n,k.extend({},s))),null!=t.top&&(f.top=t.top-s.top+a),null!=t.left&&(f.left=t.left-s.left+i),"using"in t?t.using.call(e,f):c.css(f)}},k.fn.extend({offset:function(t){if(arguments.length)return void 0===t?this:this.each(function(e){k.offset.setOffset(this,t,e)});var e,n,r=this[0];return r?r.getClientRects().length?(e=r.getBoundingClientRect(),n=r.ownerDocument.defaultView,{top:e.top+n.pageYOffset,left:e.left+n.pageXOffset}):{top:0,left:0}:void 0},position:function(){if(this[0]){var e,t,n,r=this[0],i={top:0,left:0};if("fixed"===k.css(r,"position"))t=r.getBoundingClientRect();else{t=this.offset(),n=r.ownerDocument,e=r.offsetParent||n.documentElement;while(e&&(e===n.body||e===n.documentElement)&&"static"===k.css(e,"position"))e=e.parentNode;e&&e!==r&&1===e.nodeType&&((i=k(e).offset()).top+=k.css(e,"borderTopWidth",!0),i.left+=k.css(e,"borderLeftWidth",!0))}return{top:t.top-i.top-k.css(r,"marginTop",!0),left:t.left-i.left-k.css(r,"marginLeft",!0)}}},offsetParent:function(){return this.map(function(){var e=this.offsetParent;while(e&&"static"===k.css(e,"position"))e=e.offsetParent;return e||ie})}}),k.each({scrollLeft:"pageXOffset",scrollTop:"pageYOffset"},function(t,i){var o="pageYOffset"===i;k.fn[t]=function(e){return _(this,function(e,t,n){var r;if(x(e)?r=e:9===e.nodeType&&(r=e.defaultView),void 0===n)return r?r[i]:e[t];r?r.scrollTo(o?r.pageXOffset:n,o?n:r.pageYOffset):e[t]=n},t,e,arguments.length)}}),k.each(["top","left"],function(e,n){k.cssHooks[n]=ze(y.pixelPosition,function(e,t){if(t)return t=_e(e,n),$e.test(t)?k(e).position()[n]+"px":t})}),k.each({Height:"height",Width:"width"},function(a,s){k.each({padding:"inner"+a,content:s,"":"outer"+a},function(r,o){k.fn[o]=function(e,t){var n=arguments.length&&(r||"boolean"!=typeof e),i=r||(!0===e||!0===t?"margin":"border");return _(this,function(e,t,n){var r;return x(e)?0===o.indexOf("outer")?e["inner"+a]:e.document.documentElement["client"+a]:9===e.nodeType?(r=e.documentElement,Math.max(e.body["scroll"+a],r["scroll"+a],e.body["offset"+a],r["offset"+a],r["client"+a])):void 0===n?k.css(e,t,i):k.style(e,t,n,i)},s,n?e:void 0,n)}})}),k.each("blur focus focusin focusout resize scroll click dblclick mousedown mouseup mousemove mouseover mouseout mouseenter mouseleave change select submit keydown keypress keyup contextmenu".split(" "),function(e,n){k.fn[n]=function(e,t){return 0文档 | 涛思数据
    回去

    TDengine的技术设计

    -

    存储设计

    -

    TDengine的数据存储主要包含元数据的存储和写入数据的存储。以下章节详细介绍了TDengine各种数据的存储结构。

    -

    元数据的存储

    -

    TDengine中的元数据信息包括TDengine中的数据库，表，超级表等信息。元数据信息默认存放在 /var/lib/taos/mgmt/ 文件夹下。该文件夹的目录结构如下所示：

    -
    /var/lib/taos/
-      +--mgmt/
-          +--db.db
-          +--meters.db
-          +--user.db
-          +--vgroups.db
    -

    元数据在文件中按顺序排列。文件中的每条记录代表TDengine中的一个元数据机构（数据库、表等）。元数据文件只进行追加操作，即便是元数据的删除，也只是在数据文件中追加一条删除的记录。

    -

    写入数据的存储

    -

    TDengine中写入的数据在硬盘上是按时间维度进行分片的。同一个vnode中的表在同一时间范围内的数据都存放在同一文件组中，如下图中的v0f1804*文件。这一数据分片方式可以大大简化数据在时间维度的查询，提高查询速度。在默认配置下，硬盘上的每个文件存放10天数据。用户可根据需要调整数据库的 daysPerFile 配置项进行配置。 数据在文件中是按块存储的。每个数据块只包含一张表的数据，且数据是按照时间主键递增排列的。数据在数据块中按列存储，这样使得同类型的数据存放在一起，可以大大提高压缩的比例，节省存储空间。TDengine对不同类型的数据采用了不同的压缩算法进行压缩，以达到最优的压缩结果。TDengine使用的压缩算法包括simple8B、delta-of-delta、RLE以及LZ4等。

    -

    TDengine的数据文件默认存放在 /var/lib/taos/data/ 下。而 /var/lib/taos/tsdb/ 文件夹下存放了vnode的信息、vnode中表的信息以及数据文件的链接等。其完整目录结构如下所示：

    -
    /var/lib/taos/
-      +--tsdb/
-      |   +--vnode0
-      |        +--meterObj.v0
-      |        +--db/
-      |            +--v0f1804.head->/var/lib/taos/data/vnode0/v0f1804.head1
-      |            +--v0f1804.data->/var/lib/taos/data/vnode0/v0f1804.data
-      |            +--v0f1804.last->/var/lib/taos/data/vnode0/v0f1804.last1
-      |            +--v0f1805.head->/var/lib/taos/data/vnode0/v0f1805.head1
-      |            +--v0f1805.data->/var/lib/taos/data/vnode0/v0f1805.data
-      |            +--v0f1805.last->/var/lib/taos/data/vnode0/v0f1805.last1
-      |                   :
-      +--data/
-          +--vnode0/
-                +--v0f1804.head1
-                +--v0f1804.data
-                +--v0f1804.last1
-                +--v0f1805.head1
-                +--v0f1805.data
-                +--v0f1805.last1
-                        :
    -

    meterObj文件

    -

    每个vnode中只存在一个 meterObj 文件。该文件中存储了vnode的基本信息（创建时间，配置信息，vnode的统计信息等）以及该vnode中表的信息。其结构如下所示：

    -
    <文件开始>
-[文件头]
-[表记录1偏移量和长度]
-[表记录2偏移量和长度]
-...
-[表记录N偏移量和长度]
-[表记录1]
-[表记录2]
-...
-[表记录N]
-[表记录]
-<文件结尾>
    -

    其中，文件头大小为512字节，主要存放vnode的基本信息。每条表记录代表属于该vnode中的一张表在硬盘上的表示。

    -

    head文件

    -

    head文件中存放了其对应的data文件中数据块的索引信息。该文件组织形式如下：

    -
    <文件开始>
-[文件头]
-[表1偏移量]
-[表2偏移量]
-...
-[表N偏移量]
-[表1数据索引]
-[表2数据索引]
-...
-[表N数据索引]
-<文件结尾>
    -

    文件开头的偏移量列表表示对应表的数据索引块的开始位置在文件中的偏移量。每张表的数据索引信息在head文件中都是连续存放的。这也使得TDengine在读取单表数据时，可以将该表所有的数据块索引一次性读入内存，大大提高读取速度。表的数据索引块组织如下：

    -
    [索引块信息]
-[数据块1索引]
-[数据块2索引]
-...
-[数据块N索引]
    -

    其中，索引块信息中记录了数据块的个数等描述信息。每个数据块索引对应一个在data文件或last文件中的一个单独的数据块。索引信息中记录了数据块存放的文件、数据块起始位置的偏移量、数据块中数据时间主键的范围等。索引块中的数据块索引是按照时间范围顺序排放的，这也就是说，索引块M对应的数据块中的数据时间范围都大于索引块M-1的。这种预先排序的存储方式使得在TDengine在进行按照时间戳进行查询时可以使用折半查找算法，大大提高查询速度。

    -

    data文件

    -

    data文件中存放了真实的数据块。该文件只进行追加操作。其文件组织形式如下：

    -
    <文件开始>
-[文件头]
-[数据块1]
-[数据块2]
-...
-[数据块N]
-<文件结尾>
    -

    每个数据块只属于vnode中的一张表，且数据块中的数据按照时间主键排列。数据块中的数据按列组织排放，使得同一类型的数据排放在一起，方便压缩和读取。每个数据块的组织形式如下所示：

    -
    [列1信息]
-[列2信息]
-...
-[列N信息]
-[列1数据]
-[列2数据]
-...
-[列N数据]
    -

    列信息中包含该列的类型，列的压缩算法，列数据在文件中的偏移量以及长度等。除此之外，列信息中也包含该内存块中该列数据的预计算结果，从而在过滤查询时根据预计算结果判定是否读取数据块，大大提高读取速度。

    -

    last文件

    -

    为了防止数据块的碎片化，提高查询速度和压缩率，TDengine引入了last文件。当要落盘的数据块中的数据条数低于某个阈值时，TDengine会先将该数据块写入到last文件中进行暂时存储。当有新的数据需要落盘时，last文件中的数据会被读取出来与新数据组成新的数据块写入到data文件中。last文件的组织形式与data文件类似。

    -

    TDengine数据存储小结

    -

    TDengine通过其创新的架构和存储结构设计，有效提高了计算机资源的使用率。一方面，TDengine的虚拟化使得TDengine的水平扩展及备份非常容易。另一方面，TDengine将表中数据按时间主键排序存储且其列式存储的组织形式都使TDengine在写入、查询以及压缩方面拥有非常大的优势。

    -

    查询处理

    -

    概述

    -

    TDengine提供了多种多样针对表和超级表的查询处理功能，除了常规的聚合查询之外，还提供针对时序数据的窗口查询、统计聚合等功能。TDengine的查询处理需要客户端、管理节点、数据节点协同完成。 各组件包含的与查询处理相关的功能和模块如下：

    -

    客户端（Client App）。客户端包含TAOS SQL的解析（SQL Parser）和查询请求执行器（Query Executor），第二阶段聚合器（Result Merger），连续查询管理器（Continuous Query Manager）等主要功能模块构成。SQL解析器负责对SQL语句进行解析校验，并转化为抽象语法树，查询执行器负责将抽象语法树转化查询执行逻辑，并根据SQL语句查询条件，将其转换为针对管理节点元数据查询和针对数据节点的数据查询两级查询处理。由于TAOS SQL当前不提供复杂的嵌套查询和pipeline查询处理机制，所以不再需要查询计划优化、逻辑查询计划到物理查询计划转换等过程。第二阶段聚合器负责将各数据节点查询返回的独立结果进行二阶段聚合生成最后的结果。连续查询管理器则负责针对用户建立的连续查询进行管理，负责定时拉起查询请求并按需将结果写回TDengine或返回给客户应用。此外，客户端还负责查询失败后重试、取消查询请求、以及维持连接心跳、向管理节点上报查询状态等工作。

    -

    管理节点（Management Node）。管理节点保存了整个集群系统的全部数据的元数据信息，向客户端节点提供查询所需的数据的元数据，并根据集群的负载情况切分查询请求。通过超级表包含了通过该超级表创建的所有表的信息，因此查询处理器（Query Executor）负责针对标签（TAG）的查询处理，并将满足标签查询请求的表信息返回给客户端。此外，管理节点还维护集群的查询状态（Query Status Manager）维护，查询状态管理中在内存中临时保存有当前正在执行的全部查询，当客户端使用 show queries 命令的时候，将当前系统正在运行的查询信息返回客户端。

    -

    数据节点（Data Node）。数据节点保存了数据库中全部数据内容，并通过查询执行器、查询处理调度器、查询任务队列（Query Task Queue）进行查询处理的调度执行，从客户端接收到的查询处理请求都统一放置到处理队列中，查询执行器从队列中获得查询请求，并负责执行。通过查询优化器（Query Optimizer）对于查询进行基本的优化处理，以及通过数据节点的查询执行器（Query Executor）扫描符合条件的数据单元并返回计算结果。等接收客户端发出的查询请求，执行查询处理，并将结果返回。同时数据节点还需要响应来自管理节点的管理信息和命令，例如 kill query 命令以后，需要即刻停止执行的查询任务。

    -

    -
    图 1. 系统查询处理架构图(只包含查询相关组件)

    -

    普通查询处理

    -

    客户端、管理节点、数据节点协同完成TDengine的查询处理全流程。我们以一个具体的SQL查询为例，说明TDengine的查询处理流程。SQL语句向超级表FOO_SUPER_TABLE查询获取时间范围在2019年1月12日整天，标签TAG_LOC是'beijing'的表所包含的所有记录总数，SQL语句如下：

    -
    SELECT COUNT(*) 
-FROM FOO_SUPER_TABLE
-WHERE TAG_LOC = 'beijing' AND TS >= '2019-01-12 00:00:00' AND TS < '2019-01-13 00:00:00'
    -

    首先，客户端调用TAOS SQL解析器对SQL语句进行解析及合法性检查，然后生成语法树，并从中提取查询的对象 — 超级表 FOO_SUPER_TABLE ，然后解析器向管理节点（Management Node）请求其相应的元数据信息，并将过滤信息（TAG_LOC='beijing'）同时发送到管理节点。

    -

    管理节点接收元数据获取的请求，首先找到超级表 FOO_SUPER_TABLE 基础信息，然后应用查询条件来过滤通过该超级表创建的全部表，最后满足查询条件（TAG_LOC='beijing'），即 TAG_LOC 标签列是 'beijing' 的的通过其查询执行器将满足查询要求的对象（表或超级表）的元数据信息返回给客户端。

    -

    客户端获得了 FOO_SUPER_TABLE 的元数据信息后，查询执行器根据元数据中的数据分布，分别向保存有相应数据的节点发起查询请求，此时时间戳范围过滤条件（TS >= '2019-01-12 00:00:00' AND TS < '2019-01-13 00:00:00'）需要同时发送给全部的数据节点。

    -

    数据节点接收到发自客户端的查询，转化为内部结构并进行优化以后将其放入任务执行队列，等待查询执行器执行。当查询结果获得以后，将查询结果返回客户端。数据节点执行查询的过程均相互独立，完全只依赖于自身的数据和内容进行计算。

    -

    当所有查询涉及的数据节点返回结果后，客户端将每个数据节点查询的结果集再次进行聚合（针对本案例，即将所有结果再次进行累加），累加的结果即为最后的查询结果。第二阶段聚合并不是所有的查询都需要。例如，针对数据的列选取操作，实际上是不需要第二阶段聚合。

    -

    REST查询处理

    -

    在 C/C++ 、Python接口、 JDBC 接口之外，TDengine 还提供基于 HTTP 协议的 REST 接口。不同于使用应用客户端开发程序进行的开发。当用户使用 REST 接口的时候，所有的查询处理过程都是在服务器端来完成，用户的应用服务不会参与数据库的计算过程，查询处理完成后结果通过 HTTP的 JSON 格式返回给用户。

    -

    -
    图 2. REST查询架构

    -

    当用户使用基于HTTP的REST查询接口，HTTP的请求首先与位于数据节点的HTTP连接器（ Connector），建立连接，然后通过REST的签名机制，使用Token来确保请求的可靠性。对于数据节点，HTTP连接器接收到请求后，调用内嵌的客户端程序发起查询请求，内嵌客户端将解析通过HTTP连接器传递过来的SQL语句，解析该SQL语句并按需向管理节点请求元数据信息，然后向本机或集群中其他节点发送查询请求，最后按需聚合计算结果。HTTP连接器接收到请求SQL以后，后续的流程处理与采用应用客户端方式的查询处理完全一致。最后，还需要将查询的结果转换为JSON格式字符串，并通过HTTP 响应返回给客户端。

    -

    可以看到，在处理HTTP流程的整个过程中，用户应用不再参与到查询处理的过程中，只负责通过HTTP协议发送SQL请求并接收JSON格式的结果。同时还需要注意的是，每个数据节点均内嵌了一个HTTP连接器和客户端程序，因此请求集群中任何一个数据节点，该数据节点均能够通过HTTP协议返回用户的查询结果。

    -

    技术特征

    -

    由于TDengine采用数据和标签分离存储的模式，能够极大地降低标签数据存储的冗余度。标签数据直接关联到每个表，并采用全内存的结构进行管理和维护标签数据,全内存的结构提供快速的查询处理，千万级别规模的标签数据查询可以在毫秒级别返回。首先针对标签数据的过滤可以有效地降低第二阶段的查询涉及的数据规模。为有效地提升查询处理的性能，针对物联网数据的不可更改的特点，TDengine采用在每个保存的数据块上，都记录下该数据块中数据的最大值、最小值、和等统计数据。如果查询处理涉及整个数据块的全部数据，则直接使用预计算结果，不再读取数据块的内容。由于预计算模块的大小远小于磁盘上存储的具体数据的大小，对于磁盘IO为瓶颈的查询处理，使用预计算结果可以极大地减小读取IO，并加速查询处理的流程。

    -

    由于TDengine采用按列存储数据。当从磁盘中读取数据块进行计算的时候，按照查询列信息读取该列数据，并不需要读取其他不相关的数据，可以最小化读取数据。此外，由于采用列存储结构，数据节点针对数据的扫描采用该列数据块进行，可以充分利用CPU L2高速缓存，极大地加速数据扫描的速度。此外，对于某些查询，并不会等全部查询结果生成后再返回结果。例如，列选取查询，当第一批查询结果获得以后，数据节点直接将其返回客户端。同时，在查询处理过程中，系统在数据节点接收到查询请求以后马上返回客户端查询确认信息，并同时拉起查询处理过程，并等待查询执行完成后才返回给用户查询有响应。

    -

    TDengine集群设计

    -

    1：集群与主要逻辑单元

    -

    TDengine是基于硬件、软件系统不可靠、一定会有故障的假设进行设计的，是基于任何单台计算机都无足够能力处理海量数据的假设进行设计的。因此TDengine从研发的第一天起，就按照分布式高可靠架构进行设计，是完全去中心化的，是水平扩展的，这样任何单台或多台服务器宕机或软件错误都不影响系统的服务。通过节点虚拟化并辅以自动化负载均衡技术，TDengine能最大限度地利用异构集群中的计算和存储资源。而且只要数据副本数大于一，无论是硬软件的升级、还是IDC的迁移等都无需停止集群的服务，极大地保证系统的正常运行，并且降低了系统管理员和运维人员的工作量。

    -

    下面的示例图上有八个物理节点，每个物理节点被逻辑的划分为多个虚拟节点。下面对系统的基本概念进行介绍。

    -

    assets/nodes.png

    -

    物理节点(dnode)：集群中的一物理服务器或云平台上的一虚拟机。为安全以及通讯效率，一个物理节点可配置两张网卡，或两个IP地址。其中一张网卡用于集群内部通讯，其IP地址为privateIp, 另外一张网卡用于与集群外部应用的通讯，其IP地址为publicIp。在一些云平台（如阿里云），对外的IP地址是映射过来的，因此publicIp还有一个对应的内部IP地址internalIp(与privateIp不同)。对于只有一个IP地址的物理节点，publicIp, privateIp以及internalIp都是同一个地址，没有任何区别。一个dnode上有而且只有一个taosd实例运行。

    -

    虚拟数据节点(vnode)：在物理节点之上的可独立运行的基础逻辑单元，时序数据写入、存储、查询等操作逻辑都在虚拟节点中进行(图中V)，采集的时序数据就存储在vnode上。一个vnode包含固定数量的表。当创建一张新表时，系统会检查是否需要创建新的vnode。一个物理节点上能创建的vnode的数量取决于物理节点的硬件资源。一个vnode只属于一个DB，但一个DB可以有多个vnode。

    -

    虚拟数据节点组(vgroup): 位于不同物理节点的vnode可以组成一个虚拟数据节点组vnode group(如上图dnode0中的V0, dnode1中的V1, dnode6中的V2属于同一个虚拟节点组)。归属于同一个vgroup的虚拟节点采取master/slave的方式进行管理。写只能在master上进行，但采用asynchronous的方式将数据同步到slave，这样确保了一份数据在多个物理节点上有拷贝。如果master节点宕机，其他节点监测到后，将重新选举vgroup里的master, 新的master能继续处理数据请求，从而保证系统运行的可靠性。一个vgroup里虚拟节点个数就是数据的副本数。如果一个DB的副本数为N，系统必须有至少N个物理节点。副本数在创建DB时通过参数replica可以指定，缺省为1。使用TDengine, 数据的安全依靠多副本解决，因此不再需要昂贵的磁盘阵列等存储设备。

    -

    虚拟管理节点(mnode)：负责所有节点运行状态的监控和维护，以及节点之间的负载均衡（图中M）。同时，虚拟管理节点也负责元数据(包括用户、数据库、表、静态标签等)的存储和管理，因此也称为Meta Node。TDengine集群中可配置多个(最多不超过5个) mnode，它们自动构建成为一个管理节点集群(图中M0, M1, M2)。mnode间采用master/slave的机制进行管理，而且采取强一致方式进行数据同步。mnode集群的创建由系统自动完成，无需人工干预。每个dnode上至多有一个mnode，而且每个dnode都知道整个集群中所有mnode的IP地址。

    -

    taosc：一个软件模块，是TDengine给应用提供的驱动程序（driver）,内嵌于JDBC、ODBC driver中，或者C语言连接库里。应用都是通过taosc而不是直接来与整个集群进行交互的。这个模块负责获取并缓存元数据；将插入、查询等请求转发到正确的虚拟节点；在把结果返回给应用时，还需要负责最后一级的聚合、排序、过滤等操作。对于JDBC, ODBC, C/C++接口而言，这个模块是在应用所处的计算机上运行，但消耗的资源很小。为支持全分布式的REST接口，taosc在TDengine集群的每个dnode上都有一运行实例。

    -

    对外服务地址：TDengine集群可以容纳单台、多台甚至几千台物理节点。应用只需要向集群中任何一个物理节点的publicIp发起连接即可。启动CLI应用taos时，选项-h需要提供的就是publicIp。

    -

    master/secondIp：每一个dnode都需要配置一个masterIp。dnode启动后，将对配置的masterIp发起加入集群的连接请求。masterIp是已经创建的集群中的任何一个节点的privateIp，对于集群中的第一个节点，就是它自己的privateIp。为保证连接成功，每个dnode还可配置secondIp, 该IP地址也是已创建的集群中的任何一个节点的privateIp。如果一个节点连接masterIp失败,它将试图链接secondIp。

    -

    dnode启动后，会获知集群的mnode IP列表，并且定时向mnode发送状态信息。

    -

    vnode与mnode只是逻辑上的划分，都是执行程序taosd里的不同线程而已，无需安装不同的软件，做任何特殊的配置。最小的系统配置就是一个物理节点,vnode,mnode和taosc都存在而且都正常运行，但单一节点无法保证系统的高可靠。

    -

    2：一典型的操作流程

    -

    为解释vnode, mnode, taosc和应用之间的关系以及各自扮演的角色，下面对写入数据这个典型操作的流程进行剖析。

    -

    Picture1

    -
      -
    1. 应用通过JDBC、ODBC或其他API接口发起插入数据的请求。
      2. -
    2. taosc会检查缓存，看是有保存有该表的meta data。如果有，直接到第4步。如果没有，taosc将向mnode发出get meta-data请求。
      3. -
    3. mnode将该表的meta-data返回给taosc。Meta-data包含有该表的schema, 而且还有该表所属的vgroup信息（vnode ID以及所在的dnode的IP地址，如果副本数为N，就有N组vnodeID/IP)。如果taosc迟迟得不到mnode回应，而且存在多个mnode,taosc将向下一个mnode发出请求。
      4. -
    4. taosc向master vnode发起插入请求。
      5. -
    5. vnode插入数据后，给taosc一个应答，表示插入成功。如果taosc迟迟得不到vnode的回应，taosc会认为该节点已经离线。这种情况下，如果被插入的数据库有多个副本，taosc将向vgroup里下一个vnode发出插入请求。
      6. -
    6. taosc通知APP，写入成功。
      7. -
    -

    对于第二和第三步，taosc启动时，并不知道mnode的IP地址，因此会直接向配置的集群对外服务的IP地址发起请求。如果接收到该请求的dnode并没有配置mnode，该dnode会在回复的消息中告知mnode的IP地址列表（如果有多个dnodes，mnode的IP地址可以有多个），这样taosc会重新向新的mnode的IP地址发出获取meta-data的请求。

    -

    对于第四和第五步，没有缓存的情况下，taosc无法知道虚拟节点组里谁是master，就假设第一个vnodeID/IP就是master,向它发出请求。如果接收到请求的vnode并不是master,它会在回复中告知谁是master，这样taosc就向建议的master vnode发出请求。一旦得到插入成功的回复，taosc会缓存住master节点的信息。

    -

    上述是插入数据的流程，查询、计算的流程也完全一致。taosc把这些复杂的流程全部封装屏蔽了，因此应用无需处理重定向、获取meta data等细节，完全是透明的。

    -

    通过taosc缓存机制，只有在第一次对一张表操作时，才需要访问mnode, 因此mnode不会成为系统瓶颈。但因为schema有可能变化，而且vgroup有可能发生改变（比如负载均衡发生），因此taosc需要定时自动刷新缓存。

    -

    3：数据分区

    -

    vnode(虚拟数据节点)保存采集的时序数据，而且查询、计算都在这些节点上进行。为便于负载均衡、数据恢复、支持异构环境，TDengine将一个物理节点根据其计算和存储资源切分为多个vnode。这些vnode的管理是TDengine自动完成的，对应用完全透明。

    -

    对于单独一个数据采集点，无论其数据量多大，一个vnode（或vnode group, 如果副本数大于1）有足够的计算资源和存储资源来处理（如果每秒生成一条16字节的记录，一年产生的原始数据不到0.5G），因此TDengine将一张表的所有数据都存放在一个vnode里，而不会让同一个采集点的数据分布到两个或多个dnode上。而且一个vnode可存储多张表的数据，一个vnode可容纳的表的数目由配置参数tables指定，缺省为2000。设计上，一个vnode里所有的表都属于同一个DB。因此一个数据库DB需要的vnode或vgroup的个数等于：数据库表的数目/tables。

    -

    创建DB时，系统并不会马上分配资源。但当创建一张表时，系统将看是否有已经分配的vnode, 而且是否有空位，如果有，立即在该有空位的vnode创建表。如果没有，系统将从集群中，根据当前的负载情况，在一个dnode上创建一新的vnode, 然后创建表。如果DB有多个副本，系统不是只创建一个vnode，而是一个vgroup(虚拟数据节点组)。系统对vnode的数目没有任何限制，仅仅受限于物理节点本身的计算和存储资源。

    -

    参数tables的设置需要考虑具体场景，创建DB时，可以个性化指定该参数。该参数不宜过大，也不宜过小。过小，极端情况，就是每个数据采集点一个vnode, 这样导致系统数据文件过多。过大，虚拟化带来的优势就会丧失。给定集群计算资源的情况下，整个系统vnode的个数应该是CPU核的数目的两倍以上。

    -

    4：负载均衡

    -

    每个dnode(物理节点)都定时向 mnode(虚拟管理节点)报告其状态（包括硬盘空间、内存大小、CPU、网络、虚拟节点个数等），因此mnode了解整个集群的状态。基于整体状态，当mnode发现某个dnode负载过重，它会将dnode上的一个或多个vnode挪到其他dnode。在挪动过程中，对外服务继续进行，数据插入、查询和计算操作都不受影响。负载均衡操作结束后，应用也无需重启，将自动连接新的vnode。

    -

    如果mnode一段时间没有收到dnode的状态报告，mnode会认为这个dnode已经离线。如果离线时间超过一定时长（时长由配置参数offlineThreshold决定），该dnode将被mnode强制剔除出集群。该dnode上的vnodes如果副本数大于一，系统将自动在其他dnode上创建新的副本，以保证数据的副本数。

    -

    Note：目前集群功能仅仅限于企业版

    回去
    \ No newline at end of file diff --git a/documentation/tdenginedocs-cn/styles/base.css b/documentation/tdenginedocs-cn/styles/base.css deleted file mode 100644 index 564b587eb166c7fdca9f4d95070a4b16d743744a..0000000000000000000000000000000000000000 --- a/documentation/tdenginedocs-cn/styles/base.css +++ /dev/null @@ -1,1112 +0,0 @@ -:root { - --b1:rgb(0,118,206);/*#0077bf*//*PANTONE 2174 C*/ - --b1t:rgba(0,118,206,0.15); - --b2:rgb(72,159,223);/*PANTONE 2171 C*//*OLD:#4193c5*/ - --sg-1:#b3b4b9; - --sg0:#585c66; - --sg1:rgb(51,56,68); - --sg2:#2F333E; - --sg3:#21242c; - --black: #212529; - --white: #fefefe; /*rgb(254,254,254)*/ - --white2:rgb(251, 251, 253); /*#fafbfc*/ - --white3:rgb(240,242,244); - --footer1:#fefefe; - --footer2:#333844; - --red:#ea4741; - --green:#72c156; - /*PRODUCT COLORS*/ - --p1:#72c156;/*#30D387;*/ - --p1t:rgba(114,193,86,0.15); - --p2:#43b3ae;/*rgb(70,161,168);/*#46a1a8*//*#D879D0;*/ - --p2t:rgba(70,161,168,0.15); - --p3:#4997d0;/*#30B7E8;*/ - --p3t:rgba(73,151,208,0.15); -} -/*@font-face{font-family:"Open Sans";src:url(fonts/Light/OpenSans-Light.woff2?v=1.101) format("woff2"),url(fonts/Light/OpenSans-Light.woff?v=1.101) format("woff");font-weight:300;font-style:normal}@font-face{font-family:"Open Sans";src:url(fonts/LightItalic/OpenSans-LightItalic.woff2?v=1.101) format("woff2"),url(fonts/LightItalic/OpenSans-LightItalic.woff?v=1.101) format("woff");font-weight:300;font-style:italic}@font-face{font-family:"Open Sans";src:url(fonts/Regular/OpenSans-Regular.woff2?v=1.101) format("woff2"),url(fonts/Regular/OpenSans-Regular.woff?v=1.101) format("woff");font-weight:400;font-style:normal}@font-face{font-family:"Open Sans";src:url(fonts/Italic/OpenSans-Italic.woff2?v=1.101) format("woff2"),url(fonts/Italic/OpenSans-Italic.woff?v=1.101) format("woff");font-weight:400;font-style:italic}@font-face{font-family:"Open Sans";src:url(fonts/SemiBold/OpenSans-SemiBold.woff2?v=1.101) format("woff2"),url(fonts/SemiBold/OpenSans-SemiBold.woff?v=1.101) format("woff");font-weight:600;font-style:normal}@font-face{font-family:"Open Sans";src:url(fonts/SemiBoldItalic/OpenSans-SemiBoldItalic.woff2?v=1.101) format("woff2"),url(fonts/SemiBoldItalic/OpenSans-SemiBoldItalic.woff?v=1.101) format("woff");font-weight:600;font-style:italic}@font-face{font-family:"Open Sans";src:url(fonts/Bold/OpenSans-Bold.woff2?v=1.101) format("woff2"),url(fonts/Bold/OpenSans-Bold.woff?v=1.101) format("woff");font-weight:700;font-style:normal}@font-face{font-family:"Open Sans";src:url(fonts/BoldItalic/OpenSans-BoldItalic.woff2?v=1.101) format("woff2"),url(fonts/BoldItalic/OpenSans-BoldItalic.woff?v=1.101) format("woff");font-weight:700;font-style:italic}@font-face{font-family:"Open Sans";src:url(fonts/ExtraBold/OpenSans-ExtraBold.woff2?v=1.101) format("woff2"),url(fonts/ExtraBold/OpenSans-ExtraBold.woff?v=1.101) format("woff");font-weight:800;font-style:normal}@font-face{font-family:"Open Sans";src:url(fonts/ExtraBoldItalic/OpenSans-ExtraBoldItalic.woff2?v=1.101) format("woff2"),url(fonts/ExtraBoldItalic/OpenSans-ExtraBoldItalic.woff?v=1.101) format("woff");font-weight:800;font-style:italic}*/ -html { - font-size:12pt; /*20px*/ - background-color: var(--white); -} -body, body * { - font-family: "Open Sans", Helvetica,'Hiragino Sans GB', sans-serif,"Apple Color Emoji"; - -webkit-font-smoothing:auto !important; - -moz-osx-font-smoothing:auto !important; - font-smooth: auto !important; - letter-spacing: normal; - line-height: 1.6; -} -body{ - -webkit-box-sizing: border-box; - box-sizing: border-box; - font-weight: 300; - color:var(--sg1); - font-family: "Open Sans", Helvetica, sans-serif !important; - background-color: var(--white); - -} -strong { - font-weight:600; -} -.anchor { - display: block; - position: relative; - z-index: -1; - top: -10px; -} -/* FORMS */ -input { - outline: none; - -webkit-box-shadow: inset 0px 0px 0px 0px transparent; - box-shadow: inset 0px 0px 0px 0px transparent; -} -input[type='text'], input[type='submit'],textarea { - -webkit-appearance: none; -} -input[l]{ - font-size:inherit; - outline: none; - - color:var(--sg1); - padding-left: 0.4em; - width:-webkit-calc(100%); - width:calc(100%); - border:solid 1px; - display: inline-block; - border-left:1px solid; - -webkit-border-radius:4px; - border-radius:4px; - -webkit-transition: border-left 0.2s; - -o-transition: border-left 0.2s; - transition: border-left 0.2s; - vertical-align: top; - font-weight:400; - border-color:inherit; - margin-bottom: 0.5rem; -} -input[l]:focus { - border-left:1rem solid; -} -input[l]:focus { - width:-webkit-calc(auto); - width:calc(auto); -} -input[plain]:valid { - border-color: var(--b1); -} -input[plain]:focus:valid { - border-color: var(--b1); -} -textarea { - -webkit-box-shadow: inset 0px 0px 0px 0px transparent; - box-shadow: inset 0px 0px 0px 0px transparent; -} -textarea[l] { - font-size:inherit; - outline: none; - - color:var(--sg1); - padding-left: 0.4em; - width:-webkit-calc(100%); - width:calc(100%); - border:solid 1px; - display: inline-block; - border-left:1px solid; - -webkit-border-radius:4px; - border-radius:4px; - -webkit-transition: border-left 0.2s; - -o-transition: border-left 0.2s; - transition: border-left 0.2s; - vertical-align: top; - font-weight:400; - border-color:inherit; - margin-bottom: 0.5rem; -} - -/*Other Text*/ -ul { - padding-left:30px; -} -p, li { - font-size:1em; - -} -p { - margin-bottom: 0.5rem; -} -/*Headers*/ -h1 { - font-size: 2.5rem; - line-height: 1.8; -} -h2 { - font-size: 1.7rem; - line-height: 1.8; -} -h3 { - font-size: 1.4rem; - line-height: 1.43; -} -h4 { - font-size: 1.25rem; -} -h5 { - font-size: 1rem; -} -h6 { - font-size: 1rem; - color: #777; -} -h1[b]::before,h2[b]::before, h3[b]::before { - content:""; - height:1em;; - display: block; - width:3px; - margin-left: -0.5em; - margin-top: 0.45em; - position: absolute; - background-color: var(--b1); -} -h1[b],h2[b], h3[b] { - padding-left: 0.5em -} -/* Navigation Bar */ -.logo { - height: 2.5rem; -} -a { - font-size:1em; -} -a:hover { - text-decoration: none; -} -a[l] { - color:var(--b2); - padding-bottom: 2px; - position: relative; - font-style: normal; - cursor: pointer; -} -a[l]:hover,a[l]:focus { - text-decoration: none; -} -a[l]::before { - content: ""; - left: 0; - background-color: var(--b2); - width: 0%; - height: 1px; - top:-webkit-calc(1em + 8px); - top:calc(1em + 8px); - position: absolute; - z-index: 2; - -webkit-transition: background-color 0.2s, height 0.2s, top 0.2s, width 0.2s; - -o-transition: background-color 0.2s, height 0.2s, top 0.2s, width 0.2s; - transition: background-color 0.2s, height 0.2s, top 0.2s, width 0.2s;; -} -a[l]:hover::before, a[l]:focus::before { - content: ""; - left: 0; - background-color: var(--b2); - width: 100%; - height: 1px; - top:-webkit-calc(1em + 8px); - top:calc(1em + 8px); - position: absolute; - z-index: 2; - -webkit-transition: background-color 0.2s, height 0.2s, top 0.2s, width 0.2s; - -o-transition: background-color 0.2s, height 0.2s, top 0.2s, width 0.2s; - transition: background-color 0.2s, height 0.2s, top 0.2s, width 0.2s; - text-decoration: none; -} -.navbar-brand { - margin-left: 10%; - padding-left: 15px; - color:var(--white) !important; -} -.navbar-nav { - top:0px; -} -.navbar { - background-color:var(--sg1); - z-index:10000; - padding-left: 0px; - padding-right: 0px; - padding-top:0.75rem; - padding-bottom: 0.75rem; -} -.navbar-toggler { - margin-right: -webkit-calc(2rem + 15px); - margin-right: calc(2rem + 15px); -} -.nav-link { - color:var(--white) !important; - line-height: 3.65rem; -} -.nav-item { - height:4.65rem; - font-size:1.1rem; - padding-left: 0.15rem; - padding-right: 0.15rem; - -webkit-transition: all 0.2s; - -o-transition: all 0.2s; - transition: all 0.2s; - border-bottom: 0rem solid var(--white); -} -.nav-item:hover { - border-bottom: 0.45rem solid var(--white); -} -.dropdown-menu { - top:4.1rem; - z-index:1000; - border-top:none; - border:none; - min-width: 120px; - margin-left:-1px; - -webkit-border-top-left-radius: 0; - border-top-left-radius: 0; - -webkit-border-top-right-radius: 0; - border-top-right-radius: 0; - -webkit-border-bottom-left-radius:0.25rem; - border-bottom-left-radius:0.25rem; - -webkit-border-bottom-right-radius:0.25rem; - border-bottom-right-radius:0.25rem; -} -.dropdown-menu.show { - -webkit-box-shadow: 0 4px 24px rgba(100, 109, 146, 0.15); - box-shadow: 0 4px 24px rgba(100, 109, 146, 0.15); -} -.dropdown-item { - color:var(--sg1); - background-color: var(--white); - -webkit-transition:all 0.2s; - -o-transition:all 0.2s; - transition:all 0.2s; - cursor:pointer; -} -.dropdown-item:hover, .dropdown-item:active { - background-color:var(--sg1); - color:var(--white) !important; -} -.dropdown-toggle::after { - display:none; -} -.dropdown a::after { - -webkit-transform: rotate(-90deg); - -ms-transform: rotate(-90deg); - transform: rotate(-90deg); - -webkit-transition: -webkit-transform 0.2s; - transition: -webkit-transform 0.2s; - -o-transition: transform 0.2s; - transition: transform 0.2s; - transition: transform 0.2s, -webkit-transform 0.2s; -} -.dropdown.show a::after { - -webkit-transform: rotate(0deg); - -ms-transform: rotate(0deg); - transform: rotate(0deg); -} -.navbar-nav .active { - border-bottom: 0.45rem solid var(--white); -} -.navbar-nav { - position: absolute; - right:-webkit-calc(10% + 15px); - right:calc(10% + 15px); -} -#language-dropdown .dropdown-menu{ - width:50px; -} -/*FOOTER*/ -footer { - background-color: var(--footer2); - padding-top: 1rem; -} -.page-footer { - padding-bottom: 2rem; -} -.footer-content, .footer-legal, .footer-contact { - width:80%; - margin-left: 10%; - padding-top:1rem; - color:var(--footer1); - font-size:0.8em; -} -.footer-content a { - color:var(--footer1); -} -.footer-content a { - color:var(--footer1); -} -.links-list { - text-align: left; - list-style: none; - padding: 0px; -} -.content-wrapper > .links-list { - padding-left:15px; -} -.links-list-title h4 { - font-size:1.2em; - font-weight:400; -} -.legal-links { - position: absolute; - right:-webkit-calc(10% + 15px); - right:calc(10% + 15px); -} -.legal-links a { - color:var(--footer1); -} -.links-list li { - height:2em; -} -.links-list li a::before, .legal-links a::before { - background-color:var(--footer1); -} -.links-list li a:hover::before, .legal-links a:hover::before { - background-color:var(--footer1); -} -.links-list .divider { - border-bottom: 1px solid var(--footer1); - opacity: 0.15; - height:0px; - margin-bottom: 0.3em; -} -.footer-divider { - border-bottom: 1px solid var(--footer1); - width:-webkit-calc(80% - 30px); - width:calc(80% - 30px); - margin-left: -webkit-calc(10% + 15px); - margin-left: calc(10% + 15px); -} -#social-media-links li { - height:2rem; - line-height:2rem; - display: inline-block; - font-size:1em; -} - -#social-media-links li:last-child::after { - content:""; -} -#social-media-links li::after { - content:" | "; -} -#social-media-links svg { - margin-left:2px;margin-right: 0.4rem; - width:20px; -} -#social-media-links svg path { - fill:var(--footer1); -} -#social-media-links li a::before { - left:1.9rem; - background-color:var(--footer1); -} -#social-media-links li a:hover::before, #social-media-links li a:focus::before { - left:1.9rem; - width: -webkit-calc(100% - 1.9rem); - width: calc(100% - 1.9rem); - background-color:var(--footer1); -} -#social-media-links ion-icon { - font-size:20px; - margin-right: 0.5rem; -} -#social-media-links svg { - font-size:20px; - margin-right: 0.5rem; -} -#email-subscribe-form { - width:-webkit-calc(100% - 160px); - width:calc(100% - 160px); -} -#email-subscribe-form input{ - width:-webkit-calc(100% - 4rem); - width:calc(100% - 4rem); - font-size:1.2em; - outline: none; - height:1.8em; - color:var(--sg1); - padding-left: 0.6em; - border:none; - display: inline-block; - border-left:0px solid var(--b1); - -webkit-border-radius:4px; - border-radius:4px; - -webkit-transition: border-left 0.2s; - -o-transition: border-left 0.2s; - transition: border-left 0.2s; - vertical-align: top; - font-weight:400; -} -#email-subscribe-form input:focus { - border-left:1rem solid var(--b1); - padding-top:2px; -} -#email-subscribe-form input:invalid, #email-subscribe-form input:invalid:focus { - border-color:var(--b1); -} -#email-subscribe-form input.invalid-input, #email-subscribe-form input.invalid-input:focus { - border-color:var(--red); -} -#email-subscribe-form input:valid, #email-subscribe-form input:valid:focus { - border-color:var(--green); -} -#email-subscribe-form button { - font-size:1.2em; - height:1.8em; - line-height: 1em; - float:right; - width:3rem; - padding:0; -} -form { - border-color:var(--b1); -} -form input:invalid, form input:invalid:focus { - border-color:inherit; -} -form input.invalid-input, form input.invalid-input:focus, form textarea.invalid-input, form textarea.invalid-input:focus { - border-color:var(--red); -} -form input:valid, form input:valid:focus { - border-color:var(--green); -} - -.sub-arrow { - width:1.2em; - fill:var(--b1); -} - - -@media only screen and (max-width:991px){ - .page-footer { - padding-left:20px; - padding-right:20px; - } - .footer-legal { - width:100%; - } - #legal-1 { - padding-left: 20px; - } - .legal-links { - right:20px; - } - .footer-content .col-xl-8, .footer-content .col-xl-4{ - padding-left:20px; - padding-right:20px; - } - .footer-content { - width:-webkit-calc(100% + 40px); - width:calc(100% + 40px); - } - .footer-divider { - width:100%; - margin-left: 0; - } -} - -/*SECTIONS AND CONTENT*/ -.content-wrapper { - width: 80%; - margin-left: 10%; - margin-top: 6rem; - margin-bottom: 3rem; - min-height: -webkit-calc(100vh - 187.7px - 74.45px); - min-height: calc(100vh - 187.7px - 74.45px); -} -.section { - /* border-bottom:2px solid rgba(0,0,0,0.2);*/ -} -.section-item { - -} -.section-title, -.section-item-title { - color:var(--b1); - -} -.container-fluid { - background-color: var(--white); -} -.center { - left:50%; - position: relative; -} -/*BUTTONS*/ -.btn-primary { - color:var(--b1); - background-color: var(--white); - border-color:var(--b1); - -webkit-box-shadow:0px 0px 0px 0px rgba(255,255,255,0.55); - box-shadow:0px 0px 0px 0px rgba(255,255,255,0.55); - -webkit-transition: all 0.2s; - -o-transition: all 0.2s; - transition: all 0.2s; -} -.btn-primary:hover,.btn-primary:focus { - color:var(--b1); - background-color: var(--white); - border-color:var(--b1); - -webkit-box-shadow:4px 4px 0px 0px var(--b1t); - box-shadow:4px 4px 0px 0px var(--b1t); - -webkit-transform: translate(-2px,-2px); - -ms-transform: translate(-2px,-2px); - transform: translate(-2px,-2px); -} -.btn-primary:active { - color:var(--b1) !important; - background-color: var(--white) !important; - border-color:var(--b1) !important; - -webkit-box-shadow:2px 2px 0px 0px var(--b1t); - box-shadow:2px 2px 0px 0px var(--b1t); - -webkit-transform: translate(-1px,-1px); - -ms-transform: translate(-1px,-1px); - transform: translate(-1px,-1px); -} -.btn-white { - color:var(--b1); - background-color: var(--white); - -webkit-transition: all 0.2s; - -o-transition: all 0.2s; - transition: all 0.2s; - -webkit-box-shadow:0px 0px 0px 0px rgba(255,255,255,0.55); - box-shadow:0px 0px 0px 0px rgba(255,255,255,0.55); -} -.btn-white:hover,.btn-white:focus { - color:var(--b1); - background-color: var(--white); - -webkit-box-shadow:4px 4px 0px 0px rgba(255,255,255,0.55); - box-shadow:4px 4px 0px 0px rgba(255,255,255,0.55); - -webkit-transform: translate(-2px,-2px); - -ms-transform: translate(-2px,-2px); - transform: translate(-2px,-2px); -} -.btn-white:active { - color:var(--b1) !important; - background-color: var(--white) !important; - -webkit-box-shadow:2px 2px 0px 0px rgba(255,255,255,0.55); - box-shadow:2px 2px 0px 0px rgba(255,255,255,0.55); - -webkit-transform: translate(-1px,-1px); - -ms-transform: translate(-1px,-1px); - transform: translate(-1px,-1px); -} -.btn-filled { - color:var(--white) !important; - background-color: var(--b1); - border-color:var(--b1); - -webkit-box-shadow:0px 0px 0px 0px rgba(255,255,255,0.55); - box-shadow:0px 0px 0px 0px rgba(255,255,255,0.55); - -webkit-transition: all 0.2s; - -o-transition: all 0.2s; - transition: all 0.2s; -} -.btn-filled:hover { - color:var(--white) !important;; - background-color: var(--b1); - border-color:var(--b1); - -webkit-box-shadow:4px 4px 0px 0px var(--b1t); - box-shadow:4px 4px 0px 0px var(--b1t); - -webkit-transform: translate(-2px,-2px); - -ms-transform: translate(-2px,-2px); - transform: translate(-2px,-2px); -} -.btn-filled:active { - color:var(--white) !important; - background-color: var(--b1) !important; - border-color:var(--b1) !important; - -webkit-box-shadow:2px 2px 0px 0px var(--b1t); - box-shadow:2px 2px 0px 0px var(--b1t); - -webkit-transform: translate(-1px,-1px); - -ms-transform: translate(-1px,-1px); - transform: translate(-1px,-1px); -} -/*Popup*/ -#popup-wrapper { - display: block; - position: absolute; - z-index:1000; - -webkit-transition:opacity 0.5s; - -o-transition:opacity 0.5s; - transition:opacity 0.5s; - opacity: 1; -} -#popup-page-cover { - display:none; - position: fixed; - height: 100vh; - width:100vw; - top:0;left:0; - background-color: rgba(131, 145, 174, 0.32); - z-index:1000; - -webkit-transition:opacity 0.5s; - -o-transition:opacity 0.5s; - transition:opacity 0.5s; - opacity:0; -} -#popup { - position: fixed; - display: none; - height:auto; - width:100px; - z-index: 1001; - max-width: -webkit-calc(100% - 30px); - max-width: calc(100% - 30px); - background-color: var(--white); - left:50%; - -webkit-transform:translate(-50%,-50%); - -ms-transform:translate(-50%,-50%); - transform:translate(-50%,-50%); - top:50%; - -webkit-transition:opacity 0.5s; - -o-transition:opacity 0.5s; - transition:opacity 0.5s; - opacity:0; - -webkit-border-radius:0.25rem; - border-radius:0.25rem; - -webkit-box-shadow: 0 12px 48px 0 rgba(0, 0, 0, 0.24); - box-shadow: 0 12px 48px 0 rgba(0, 0, 0, 0.24) -} -#close-popup { - position: absolute;right:1rem; - z-index: 1; - cursor: pointer; - top:0; -} -#close-popup svg { - margin-top:4px; -} -#close-popup::before { - content:""; - width:0px; - display: block; - position: absolute; - top:50%; - left:50%; - height:0px; - background-color:rgba(0,0,0,0.15); - -webkit-border-radius:50%; - border-radius:50%; - z-index:-1; - cursor: pointer; - -webkit-transition:all 0.2s; - -o-transition:all 0.2s; - transition:all 0.2s; -} -#close-popup:hover::before { - content:""; - width:32px;; - display: block; - position: absolute; - top:10px; - left:0px; - height:32px; - background-color:rgba(0,0,0,0.15); - -webkit-border-radius:50%; - border-radius:50%; -z-index:-1; -} -#popup-title { - padding-left: 1rem; - background-color:var(--b1); - color:var(--white); - font-weight:400; - font-size:1.6em; - width:100%; - display:block; - -webkit-border-radius:0.25rem 0.25rem 0 0; - border-radius:0.25rem 0.25rem 0 0; - padding-right:60px; - position: relative; -} -#popup-title-text { - line-height: 1.2; - display: inline-block; - padding-top: 9px; -} -#popup-content { - padding:1rem; - display: block; -} -#popup-title path { - fill:var(--white); -} -/*Banners*/ -.banner-content { - padding-right:32px; -} -.banner-wrapper { - width:100vw; - position: fixed; - top:4.3rem; - left:0; - z-index: 1000; -} -.banner { - background-color: var(--b1); - width:-webkit-calc(100% - 20px); - width:calc(100% - 20px); - margin: auto; - -webkit-border-radius:0.25rem; - border-radius:0.25rem; - padding:0.5rem; - color:var(--white); - font-size:1.6em; - margin-top: 1rem; - -webkit-box-shadow:0 4px 12px 0 rgba(0, 0, 0, 0.24); - box-shadow:0 4px 12px 0 rgba(0, 0, 0, 0.24); - opacity: 1; - -webkit-animation: bannerOpaque 0.2s; - animation: bannerOpaque 0.2s; -} -@-webkit-keyframes bannerOpaque { - from { - opacity:0 - } - to { - opacity:1; - } -} -@keyframes bannerOpaque { - from { - opacity:0 - } - to { - opacity:1; - } -} -.close-banner { - position: absolute;right:1rem; - z-index: 1; - cursor: pointer; - -webkit-transform: translate(0,-3px); - -ms-transform: translate(0,-3px); - transform: translate(0,-3px); -} -.close-banner::before { - content:""; - width:0px; - display: block; - position: absolute; - margin-top:26px; - left:50%; - height:0px; - background-color:rgba(0,0,0,0.15); - -webkit-border-radius:50%; - border-radius:50%; - z-index:-1; - cursor: pointer; - -webkit-transition:all 0.2s; - -o-transition:all 0.2s; - transition:all 0.2s; -} -.close-banner:hover::before { - content:""; - width:32px; - margin-top: 7px; - display: block; - position: absolute; - left:0px; - height:32px; - background-color:rgba(0,0,0,0.15); - -webkit-border-radius:50%; - border-radius:50%; -z-index:-1; -} -@media only screen and (max-width:991px) { - .banner { - font-size:1.2rem; - } -} -/*OTHER*/ -#globe-svg { - height:60px; - fill:#fefefe -} -#page-cover { - width:100vw; - top:-100vh; - left:0px; - -webkit-transition-delay: 0.3s; - -o-transition-delay: 0.3s; - transition-delay: 0.3s; - -webkit-transition:all 0.7s; - -o-transition:all 0.7s; - transition:all 0.7s; - height:100vh; - position: fixed; - z-index:1000; - background-color: rgba(54, 61, 75, 0.25); -} -#menu-button { - border:none; - outline:none; -} -#menu-bar { - -webkit-transition: all 0.15s; - -o-transition: all 0.15s; - transition: all 0.15s; -} -#close-bar { - -webkit-transition: all 0.15s; - -o-transition: all 0.15s; - transition: all 0.15s; - display: none; -} -#rect1 { - -webkit-transition: all 0.2s; - -o-transition: all 0.2s; - transition: all 0.2s; -} -#rect2 { --webkit-transition: all 0.2s; --o-transition: all 0.2s; -transition: all 0.2s; -} -#rect3 { --webkit-transition: all 0.2s; --o-transition: all 0.2s; -transition: all 0.2s; -} -@media only screen and (max-width: 991px) { - - .content-wrapper { - width:-webkit-calc(100%); - width:calc(100%); - left:0; - padding-left: 0; - margin-left:0; - margin-top:4.7rem; - } - .container-fluid { - padding-left:20px; - padding-right:20px; - } - .row { - margin-left:-20px; - margin-right:-20px; - } - #menu-button { - margin-right:20px; - padding:0px; - } - .navbar-brand { - margin-left: 20px; - padding-left: 0px; - } -} -.bot-logo { - margin-bottom:0.5rem; -} -@media only screen and (min-width:1200px){ - #page-cover { - display: none - } - .bot-logo { - margin-left:15px; - } -} -@media only screen and (max-width: 1199px) { - #globe-svg { - height:60px; - fill:var(--sg1); - } - .navbar-collapse.show { - -webkit-box-shadow:0px 10px 24px rgba(0,0,0,0.15) ; - box-shadow:0px 10px 24px rgba(0,0,0,0.15) ; - } - .nav-item:first-child { - border-top: 1px solid rgba(255,255,255,0.35); - } - #menu-button { - margin-right: -webkit-calc(10% + 15px); - margin-right: calc(10% + 15px); - padding:0; - } - #menu-button:hover { - background-color: transparent; - } - .nav-item { - height:auto; - border-bottom: 1px solid rgba(0,0,0,0.35); - padding-left: -webkit-calc(10% + 15px); - padding-left: calc(10% + 15px); - } - .nav-link{ - line-height: 3rem; - padding: 0px; - - } - .nav-link{ - color:var(--sg1) !important; - } - .nav-item:hover { - border-bottom: 1px solid rgba(0,0,0,0.35); - - } - .navbar-nav { - background-color: var(--white2); - margin-top: 15px; - } - .navbar-nav .active { - border-bottom: 1px solid rgba(0,0,0,0.35); - } - .nav-item:nth-child(even) { - /* - background-color:rgba(0,0,0,0.05); - padding-left: 1rem; - margin-left: -1rem; - */ - } - #navbarSupportedContent { - - } - #language-dropdown .dropdown-menu{ - width: -webkit-calc(80% + 4rem); - width: calc(80% + 4rem); - background-color: var(--white); - - } - .dropdown-menu { - border:none; - margin-top: -20px; - } - .nav-item:last-child { - border-bottom:none; - } - .dropdown-menu.show { - -webkit-box-shadow: 0 4px 24px rgba(100, 109, 146, 0.15); - box-shadow: 0 4px 24px rgba(100, 109, 146, 0.15); - margin-bottom:1rem; - margin-top:-0.5rem; - } - .dropdown-item { - padding-left: 15px; - font-weight:300; - } - .navbar-nav { - position: relative; - right:0rem; - } - .long-form input { - width:100%; - } -} -@media only screen and (max-width: 991px) { - .nav-item { - padding-left: 20px; - padding-right: 20px; - } - #language-dropdown{ - padding-left:20px; - } - #language-dropdown .dropdown-menu { - width:100%; - } - #menu-button { - margin-right: 20px; - padding:0; - } - .navbar { - padding-top: 0.25rem; - padding-bottom:0.25rem; - } - .logo { - height:1.8rem; - } - .anchor { - top: -55px; - } -} -@media only screen and (max-width:556px) { - #legal-1 { - width:100%; - } - .legal-links { - position: inherit; - margin-left: 20px; - margin-bottom: 1em; - } -} -@media only screen and (max-width:375px) { - #legal-1 p { - display: block; - } -} - -/*Footer media queries*/ -@media only screen and (max-width:830px) { -} -@media only screen and (max-width:650px) { -} -@media only screen and (max-width:352px) { -} - -.lds-ring { - display: inline-block; - position: relative; - width: 18px; - height: 18px; - padding-top:2px; -} -#email-subscribe-form .lds-ring { - padding-top:1px; -} -.lds-ring div { - -webkit-box-sizing: border-box; - box-sizing: border-box; - display: block; - position: absolute; - width: 18px; - height: 18px; - border: 2px solid var(--b2); - -webkit-border-radius: 50%; - border-radius: 50%; - -webkit-animation: lds-ring 1.2s cubic-bezier(0.5, 0, 0.5, 1) infinite; - animation: lds-ring 1.2s cubic-bezier(0.5, 0, 0.5, 1) infinite; - border-color: var(--b2) transparent transparent transparent; -} -.lds-ring div:nth-child(1) { - -webkit-animation-delay: -0.45s; - animation-delay: -0.45s; -} -.lds-ring div:nth-child(2) { - -webkit-animation-delay: -0.3s; - animation-delay: -0.3s; -} -.lds-ring div:nth-child(3) { - -webkit-animation-delay: -0.15s; - animation-delay: -0.15s; -} -@-webkit-keyframes lds-ring { - 0% { - -webkit-transform: rotate(0deg); - transform: rotate(0deg); - } - 100% { - -webkit-transform: rotate(360deg); - transform: rotate(360deg); - } -} -@keyframes lds-ring { - 0% { - -webkit-transform: rotate(0deg); - transform: rotate(0deg); - } - 100% { - -webkit-transform: rotate(360deg); - transform: rotate(360deg); - } -} -#email-subscribe-form .sub-arrow { - padding-top:2px; -} -.sub-arrow { - display: inline-block; -} -.sub-load { - display:none; -} diff --git a/documentation/tdenginedocs-cn/styles/base.min.css b/documentation/tdenginedocs-cn/styles/base.min.css deleted file mode 100644 index 7aa94277026265a64decb3717fdc680b8a338d59..0000000000000000000000000000000000000000 --- a/documentation/tdenginedocs-cn/styles/base.min.css +++ /dev/null @@ -1 +0,0 @@ -:root{--b1:rgb(0,118,206);--b1t:rgba(0,118,206,0.15);--b2:rgb(72,159,223);--sg-1:#b3b4b9;--sg0:#585c66;--sg1:rgb(51,56,68);--sg2:#2F333E;--sg3:#21242c;--black:#212529;--white:#fefefe;--white2:rgb(251, 251, 253);--white3:rgb(240,242,244);--footer1:#fefefe;--footer2:#333844;--red:#ea4741;--green:#72c156;--p1:#72c156;--p1t:rgba(114,193,86,0.15);--p2:#43b3ae;--p2t:rgba(70,161,168,0.15);--p3:#4997d0;--p3t:rgba(73,151,208,0.15)}html{font-size:12pt;background-color:var(--white)}body,body *{font-family:"Open Sans",Helvetica,'Hiragino Sans GB',sans-serif,"Apple Color Emoji";-webkit-font-smoothing:auto!important;-moz-osx-font-smoothing:auto!important;font-smooth:auto!important;letter-spacing:normal;line-height:1.6}body{-webkit-box-sizing:border-box;box-sizing:border-box;font-weight:300;color:var(--sg1);font-family:"Open Sans",Helvetica,sans-serif!important;background-color:var(--white)}strong{font-weight:600}.anchor{display:block;position:relative;z-index:-1;top:-10px}input{outline:0;-webkit-box-shadow:inset 0 0 0 0 transparent;box-shadow:inset 0 0 0 0 transparent}input[type=submit],input[type=text],textarea{-webkit-appearance:none}input[l]{font-size:inherit;outline:0;color:var(--sg1);padding-left:.4em;width:-webkit-calc(100%);width:calc(100%);border:solid 1px;display:inline-block;border-left:1px solid;-webkit-border-radius:4px;border-radius:4px;-webkit-transition:border-left .2s;-o-transition:border-left .2s;transition:border-left .2s;vertical-align:top;font-weight:400;border-color:inherit;margin-bottom:.5rem}input[l]:focus{border-left:1rem solid}input[l]:focus{width:-webkit-calc(auto);width:calc(auto)}input[plain]:valid{border-color:var(--b1)}input[plain]:focus:valid{border-color:var(--b1)}textarea{-webkit-box-shadow:inset 0 0 0 0 transparent;box-shadow:inset 0 0 0 0 transparent}textarea[l]{font-size:inherit;outline:0;color:var(--sg1);padding-left:.4em;width:-webkit-calc(100%);width:calc(100%);border:solid 1px;display:inline-block;border-left:1px solid;-webkit-border-radius:4px;border-radius:4px;-webkit-transition:border-left .2s;-o-transition:border-left .2s;transition:border-left .2s;vertical-align:top;font-weight:400;border-color:inherit;margin-bottom:.5rem}ul{padding-left:30px}li,p{font-size:1em}p{margin-bottom:.5rem}h1{font-size:2.5rem;line-height:1.8}h2{font-size:1.7rem;line-height:1.8}h3{font-size:1.4rem;line-height:1.43}h4{font-size:1.25rem}h5{font-size:1rem}h6{font-size:1rem;color:#777}h1[b]::before,h2[b]::before,h3[b]::before{content:"";height:1em;display:block;width:3px;margin-left:-.5em;margin-top:.45em;position:absolute;background-color:var(--b1)}h1[b],h2[b],h3[b]{padding-left:.5em}.logo{height:2.5rem}a{font-size:1em}a:hover{text-decoration:none}a[l]{color:var(--b2);padding-bottom:2px;position:relative;font-style:normal;cursor:pointer}a[l]:focus,a[l]:hover{text-decoration:none}a[l]::before{content:"";left:0;background-color:var(--b2);width:0%;height:1px;top:-webkit-calc(1em + 8px);top:calc(1em + 8px);position:absolute;z-index:2;-webkit-transition:background-color .2s,height .2s,top .2s,width .2s;-o-transition:background-color .2s,height .2s,top .2s,width .2s;transition:background-color .2s,height .2s,top .2s,width .2s}a[l]:focus::before,a[l]:hover::before{content:"";left:0;background-color:var(--b2);width:100%;height:1px;top:-webkit-calc(1em + 8px);top:calc(1em + 8px);position:absolute;z-index:2;-webkit-transition:background-color .2s,height .2s,top .2s,width .2s;-o-transition:background-color .2s,height .2s,top .2s,width .2s;transition:background-color .2s,height .2s,top .2s,width .2s;text-decoration:none}.navbar-brand{margin-left:10%;padding-left:15px;color:var(--white)!important}.navbar-nav{top:0}.navbar{background-color:var(--sg1);z-index:10000;padding-left:0;padding-right:0;padding-top:.75rem;padding-bottom:.75rem}.navbar-toggler{margin-right:-webkit-calc(2rem + 15px);margin-right:calc(2rem + 15px)}.nav-link{color:var(--white)!important;line-height:3.65rem}.nav-item{height:4.65rem;font-size:1.1rem;padding-left:.15rem;padding-right:.15rem;-webkit-transition:all .2s;-o-transition:all .2s;transition:all .2s;border-bottom:0 solid var(--white)}.nav-item:hover{border-bottom:.45rem solid var(--white)}.dropdown-menu{top:4.1rem;z-index:1000;border-top:none;border:none;min-width:120px;margin-left:-1px;-webkit-border-top-left-radius:0;border-top-left-radius:0;-webkit-border-top-right-radius:0;border-top-right-radius:0;-webkit-border-bottom-left-radius:.25rem;border-bottom-left-radius:.25rem;-webkit-border-bottom-right-radius:.25rem;border-bottom-right-radius:.25rem}.dropdown-menu.show{-webkit-box-shadow:0 4px 24px rgba(100,109,146,.15);box-shadow:0 4px 24px rgba(100,109,146,.15)}.dropdown-item{color:var(--sg1);background-color:var(--white);-webkit-transition:all .2s;-o-transition:all .2s;transition:all .2s;cursor:pointer}.dropdown-item:active,.dropdown-item:hover{background-color:var(--sg1);color:var(--white)!important}.dropdown-toggle::after{display:none}.dropdown a::after{-webkit-transform:rotate(-90deg);-ms-transform:rotate(-90deg);transform:rotate(-90deg);-webkit-transition:-webkit-transform .2s;transition:-webkit-transform .2s;-o-transition:transform .2s;transition:transform .2s;transition:transform .2s,-webkit-transform .2s}.dropdown.show a::after{-webkit-transform:rotate(0);-ms-transform:rotate(0);transform:rotate(0)}.navbar-nav .active{border-bottom:.45rem solid var(--white)}.navbar-nav{position:absolute;right:-webkit-calc(10% + 15px);right:calc(10% + 15px)}#language-dropdown .dropdown-menu{width:50px}footer{background-color:var(--footer2);padding-top:1rem}.page-footer{padding-bottom:2rem}.footer-contact,.footer-content,.footer-legal{width:80%;margin-left:10%;padding-top:1rem;color:var(--footer1);font-size:.8em}.footer-content a{color:var(--footer1)}.footer-content a{color:var(--footer1)}.links-list{text-align:left;list-style:none;padding:0}.content-wrapper>.links-list{padding-left:15px}.links-list-title h4{font-size:1.2em;font-weight:400}.legal-links{position:absolute;right:-webkit-calc(10% + 15px);right:calc(10% + 15px)}.legal-links a{color:var(--footer1)}.links-list li{height:2em}.legal-links a::before,.links-list li a::before{background-color:var(--footer1)}.legal-links a:hover::before,.links-list li a:hover::before{background-color:var(--footer1)}.links-list .divider{border-bottom:1px solid var(--footer1);opacity:.15;height:0;margin-bottom:.3em}.footer-divider{border-bottom:1px solid var(--footer1);width:-webkit-calc(80% - 30px);width:calc(80% - 30px);margin-left:-webkit-calc(10% + 15px);margin-left:calc(10% + 15px)}#social-media-links li{height:2rem;line-height:2rem;display:inline-block;font-size:1em}#social-media-links li:last-child::after{content:""}#social-media-links li::after{content:" | "}#social-media-links svg{margin-left:2px;margin-right:.4rem;width:20px}#social-media-links svg path{fill:var(--footer1)}#social-media-links li a::before{left:1.9rem;background-color:var(--footer1)}#social-media-links li a:focus::before,#social-media-links li a:hover::before{left:1.9rem;width:-webkit-calc(100% - 1.9rem);width:calc(100% - 1.9rem);background-color:var(--footer1)}#social-media-links ion-icon{font-size:20px;margin-right:.5rem}#social-media-links svg{font-size:20px;margin-right:.5rem}#email-subscribe-form{width:-webkit-calc(100% - 160px);width:calc(100% - 160px)}#email-subscribe-form input{width:-webkit-calc(100% - 4rem);width:calc(100% - 4rem);font-size:1.2em;outline:0;height:1.8em;color:var(--sg1);padding-left:.6em;border:none;display:inline-block;border-left:0 solid var(--b1);-webkit-border-radius:4px;border-radius:4px;-webkit-transition:border-left .2s;-o-transition:border-left .2s;transition:border-left .2s;vertical-align:top;font-weight:400}#email-subscribe-form input:focus{border-left:1rem solid var(--b1);padding-top:2px}#email-subscribe-form input:invalid,#email-subscribe-form input:invalid:focus{border-color:var(--b1)}#email-subscribe-form input.invalid-input,#email-subscribe-form input.invalid-input:focus{border-color:var(--red)}#email-subscribe-form input:valid,#email-subscribe-form input:valid:focus{border-color:var(--green)}#email-subscribe-form button{font-size:1.2em;height:1.8em;line-height:1em;float:right;width:3rem;padding:0}form{border-color:var(--b1)}form input:invalid,form input:invalid:focus{border-color:inherit}form input.invalid-input,form input.invalid-input:focus,form textarea.invalid-input,form textarea.invalid-input:focus{border-color:var(--red)}form input:valid,form input:valid:focus{border-color:var(--green)}.sub-arrow{width:1.2em;fill:var(--b1)}@media only screen and (max-width:991px){.page-footer{padding-left:20px;padding-right:20px}.footer-legal{width:100%}#legal-1{padding-left:20px}.legal-links{right:20px}.footer-content .col-xl-4,.footer-content .col-xl-8{padding-left:20px;padding-right:20px}.footer-content{width:-webkit-calc(100% + 40px);width:calc(100% + 40px)}.footer-divider{width:100%;margin-left:0}}.content-wrapper{width:80%;margin-left:10%;margin-top:6rem;margin-bottom:3rem;min-height:-webkit-calc(100vh - 187.7px - 74.45px);min-height:calc(100vh - 187.7px - 74.45px)}.section-item-title,.section-title{color:var(--b1)}.container-fluid{background-color:var(--white)}.center{left:50%;position:relative}.btn-primary{color:var(--b1);background-color:var(--white);border-color:var(--b1);-webkit-box-shadow:0 0 0 0 rgba(255,255,255,.55);box-shadow:0 0 0 0 rgba(255,255,255,.55);-webkit-transition:all .2s;-o-transition:all .2s;transition:all .2s}.btn-primary:focus,.btn-primary:hover{color:var(--b1);background-color:var(--white);border-color:var(--b1);-webkit-box-shadow:4px 4px 0 0 var(--b1t);box-shadow:4px 4px 0 0 var(--b1t);-webkit-transform:translate(-2px,-2px);-ms-transform:translate(-2px,-2px);transform:translate(-2px,-2px)}.btn-primary:active{color:var(--b1)!important;background-color:var(--white)!important;border-color:var(--b1)!important;-webkit-box-shadow:2px 2px 0 0 var(--b1t);box-shadow:2px 2px 0 0 var(--b1t);-webkit-transform:translate(-1px,-1px);-ms-transform:translate(-1px,-1px);transform:translate(-1px,-1px)}.btn-white{color:var(--b1);background-color:var(--white);-webkit-transition:all .2s;-o-transition:all .2s;transition:all .2s;-webkit-box-shadow:0 0 0 0 rgba(255,255,255,.55);box-shadow:0 0 0 0 rgba(255,255,255,.55)}.btn-white:focus,.btn-white:hover{color:var(--b1);background-color:var(--white);-webkit-box-shadow:4px 4px 0 0 rgba(255,255,255,.55);box-shadow:4px 4px 0 0 rgba(255,255,255,.55);-webkit-transform:translate(-2px,-2px);-ms-transform:translate(-2px,-2px);transform:translate(-2px,-2px)}.btn-white:active{color:var(--b1)!important;background-color:var(--white)!important;-webkit-box-shadow:2px 2px 0 0 rgba(255,255,255,.55);box-shadow:2px 2px 0 0 rgba(255,255,255,.55);-webkit-transform:translate(-1px,-1px);-ms-transform:translate(-1px,-1px);transform:translate(-1px,-1px)}.btn-filled{color:var(--white)!important;background-color:var(--b1);border-color:var(--b1);-webkit-box-shadow:0 0 0 0 rgba(255,255,255,.55);box-shadow:0 0 0 0 rgba(255,255,255,.55);-webkit-transition:all .2s;-o-transition:all .2s;transition:all .2s}.btn-filled:hover{color:var(--white)!important;background-color:var(--b1);border-color:var(--b1);-webkit-box-shadow:4px 4px 0 0 var(--b1t);box-shadow:4px 4px 0 0 var(--b1t);-webkit-transform:translate(-2px,-2px);-ms-transform:translate(-2px,-2px);transform:translate(-2px,-2px)}.btn-filled:active{color:var(--white)!important;background-color:var(--b1)!important;border-color:var(--b1)!important;-webkit-box-shadow:2px 2px 0 0 var(--b1t);box-shadow:2px 2px 0 0 var(--b1t);-webkit-transform:translate(-1px,-1px);-ms-transform:translate(-1px,-1px);transform:translate(-1px,-1px)}#popup-wrapper{display:block;position:absolute;z-index:1000;-webkit-transition:opacity .5s;-o-transition:opacity .5s;transition:opacity .5s;opacity:1}#popup-page-cover{display:none;position:fixed;height:100vh;width:100vw;top:0;left:0;background-color:rgba(131,145,174,.32);z-index:1000;-webkit-transition:opacity .5s;-o-transition:opacity .5s;transition:opacity .5s;opacity:0}#popup{position:fixed;display:none;height:auto;width:100px;z-index:1001;max-width:-webkit-calc(100% - 30px);max-width:calc(100% - 30px);background-color:var(--white);left:50%;-webkit-transform:translate(-50%,-50%);-ms-transform:translate(-50%,-50%);transform:translate(-50%,-50%);top:50%;-webkit-transition:opacity .5s;-o-transition:opacity .5s;transition:opacity .5s;opacity:0;-webkit-border-radius:.25rem;border-radius:.25rem;-webkit-box-shadow:0 12px 48px 0 rgba(0,0,0,.24);box-shadow:0 12px 48px 0 rgba(0,0,0,.24)}#close-popup{position:absolute;right:1rem;z-index:1;cursor:pointer;top:0}#close-popup svg{margin-top:4px}#close-popup::before{content:"";width:0;display:block;position:absolute;top:50%;left:50%;height:0;background-color:rgba(0,0,0,.15);-webkit-border-radius:50%;border-radius:50%;z-index:-1;cursor:pointer;-webkit-transition:all .2s;-o-transition:all .2s;transition:all .2s}#close-popup:hover::before{content:"";width:32px;display:block;position:absolute;top:10px;left:0;height:32px;background-color:rgba(0,0,0,.15);-webkit-border-radius:50%;border-radius:50%;z-index:-1}#popup-title{padding-left:1rem;background-color:var(--b1);color:var(--white);font-weight:400;font-size:1.6em;width:100%;display:block;-webkit-border-radius:.25rem .25rem 0 0;border-radius:.25rem .25rem 0 0;padding-right:60px;position:relative}#popup-title-text{line-height:1.2;display:inline-block;padding-top:9px}#popup-content{padding:1rem;display:block}#popup-title path{fill:var(--white)}.banner-content{padding-right:32px}.banner-wrapper{width:100vw;position:fixed;top:4.3rem;left:0;z-index:1000}.banner{background-color:var(--b1);width:-webkit-calc(100% - 20px);width:calc(100% - 20px);margin:auto;-webkit-border-radius:.25rem;border-radius:.25rem;padding:.5rem;color:var(--white);font-size:1.6em;margin-top:1rem;-webkit-box-shadow:0 4px 12px 0 rgba(0,0,0,.24);box-shadow:0 4px 12px 0 rgba(0,0,0,.24);opacity:1;-webkit-animation:bannerOpaque .2s;animation:bannerOpaque .2s}@-webkit-keyframes bannerOpaque{from{opacity:0}to{opacity:1}}@keyframes bannerOpaque{from{opacity:0}to{opacity:1}}.close-banner{position:absolute;right:1rem;z-index:1;cursor:pointer;-webkit-transform:translate(0,-3px);-ms-transform:translate(0,-3px);transform:translate(0,-3px)}.close-banner::before{content:"";width:0;display:block;position:absolute;margin-top:26px;left:50%;height:0;background-color:rgba(0,0,0,.15);-webkit-border-radius:50%;border-radius:50%;z-index:-1;cursor:pointer;-webkit-transition:all .2s;-o-transition:all .2s;transition:all .2s}.close-banner:hover::before{content:"";width:32px;margin-top:7px;display:block;position:absolute;left:0;height:32px;background-color:rgba(0,0,0,.15);-webkit-border-radius:50%;border-radius:50%;z-index:-1}@media only screen and (max-width:991px){.banner{font-size:1.2rem}}#globe-svg{height:60px;fill:#fefefe}#page-cover{width:100vw;top:-100vh;left:0;-webkit-transition-delay:.3s;-o-transition-delay:.3s;transition-delay:.3s;-webkit-transition:all .7s;-o-transition:all .7s;transition:all .7s;height:100vh;position:fixed;z-index:1000;background-color:rgba(54,61,75,.25)}#menu-button{border:none;outline:0}#menu-bar{-webkit-transition:all .15s;-o-transition:all .15s;transition:all .15s}#close-bar{-webkit-transition:all .15s;-o-transition:all .15s;transition:all .15s;display:none}#rect1{-webkit-transition:all .2s;-o-transition:all .2s;transition:all .2s}#rect2{-webkit-transition:all .2s;-o-transition:all .2s;transition:all .2s}#rect3{-webkit-transition:all .2s;-o-transition:all .2s;transition:all .2s}@media only screen and (max-width:991px){.content-wrapper{width:-webkit-calc(100%);width:calc(100%);left:0;padding-left:0;margin-left:0;margin-top:4.7rem}.container-fluid{padding-left:20px;padding-right:20px}.row{margin-left:-20px;margin-right:-20px}#menu-button{margin-right:20px;padding:0}.navbar-brand{margin-left:20px;padding-left:0}}.bot-logo{margin-bottom:.5rem}@media only screen and (min-width:1200px){#page-cover{display:none}.bot-logo{margin-left:15px}}@media only screen and (max-width:1199px){#globe-svg{height:60px;fill:var(--sg1)}.navbar-collapse.show{-webkit-box-shadow:0 10px 24px rgba(0,0,0,.15);box-shadow:0 10px 24px rgba(0,0,0,.15)}.nav-item:first-child{border-top:1px solid rgba(255,255,255,.35)}#menu-button{margin-right:-webkit-calc(10% + 15px);margin-right:calc(10% + 15px);padding:0}#menu-button:hover{background-color:transparent}.nav-item{height:auto;border-bottom:1px solid rgba(0,0,0,.35);padding-left:-webkit-calc(10% + 15px);padding-left:calc(10% + 15px)}.nav-link{line-height:3rem;padding:0}.nav-link{color:var(--sg1)!important}.nav-item:hover{border-bottom:1px solid rgba(0,0,0,.35)}.navbar-nav{background-color:var(--white2);margin-top:15px}.navbar-nav .active{border-bottom:1px solid rgba(0,0,0,.35)}#language-dropdown .dropdown-menu{width:-webkit-calc(80% + 4rem);width:calc(80% + 4rem);background-color:var(--white)}.dropdown-menu{border:none;margin-top:-20px}.nav-item:last-child{border-bottom:none}.dropdown-menu.show{-webkit-box-shadow:0 4px 24px rgba(100,109,146,.15);box-shadow:0 4px 24px rgba(100,109,146,.15);margin-bottom:1rem;margin-top:-.5rem}.dropdown-item{padding-left:15px;font-weight:300}.navbar-nav{position:relative;right:0}.long-form input{width:100%}}@media only screen and (max-width:991px){.nav-item{padding-left:20px;padding-right:20px}#language-dropdown{padding-left:20px}#language-dropdown .dropdown-menu{width:100%}#menu-button{margin-right:20px;padding:0}.navbar{padding-top:.25rem;padding-bottom:.25rem}.logo{height:1.8rem}.anchor{top:-55px}}@media only screen and (max-width:556px){#legal-1{width:100%}.legal-links{position:inherit;margin-left:20px;margin-bottom:1em}}@media only screen and (max-width:375px){#legal-1 p{display:block}}.lds-ring{display:inline-block;position:relative;width:18px;height:18px;padding-top:2px}#email-subscribe-form .lds-ring{padding-top:1px}.lds-ring div{-webkit-box-sizing:border-box;box-sizing:border-box;display:block;position:absolute;width:18px;height:18px;border:2px solid var(--b2);-webkit-border-radius:50%;border-radius:50%;-webkit-animation:lds-ring 1.2s cubic-bezier(.5,0,.5,1) infinite;animation:lds-ring 1.2s cubic-bezier(.5,0,.5,1) infinite;border-color:var(--b2) transparent transparent transparent}.lds-ring div:nth-child(1){-webkit-animation-delay:-.45s;animation-delay:-.45s}.lds-ring div:nth-child(2){-webkit-animation-delay:-.3s;animation-delay:-.3s}.lds-ring div:nth-child(3){-webkit-animation-delay:-.15s;animation-delay:-.15s}@-webkit-keyframes lds-ring{0%{-webkit-transform:rotate(0);transform:rotate(0)}100%{-webkit-transform:rotate(360deg);transform:rotate(360deg)}}@keyframes lds-ring{0%{-webkit-transform:rotate(0);transform:rotate(0)}100%{-webkit-transform:rotate(360deg);transform:rotate(360deg)}}#email-subscribe-form .sub-arrow{padding-top:2px}.sub-arrow{display:inline-block}.sub-load{display:none} \ No newline at end of file diff --git a/documentation/tdenginedocs-cn/super-table/index.html b/documentation/tdenginedocs-cn/super-table/index.html deleted file mode 100644 index 42d54ce7e260a7955f746002091919043dc318ff..0000000000000000000000000000000000000000 --- a/documentation/tdenginedocs-cn/super-table/index.html +++ /dev/null @@ -1,110 +0,0 @@ -文档 | 涛思数据
    回去

    超级表STable：多表聚合

    -

    TDengine要求每个数据采集点单独建表，这样能极大提高数据的插入/查询性能，但是导致系统中表的数量猛增，让应用对表的维护以及聚合、统计操作难度加大。为降低应用的开发难度，TDengine引入了超级表STable (Super Table)的概念。

    -

    什么是超级表

    -

    STable是同一类型数据采集点的抽象，是同类型采集实例的集合，包含多张数据结构一样的子表。每个STable为其子表定义了表结构和一组标签：表结构即表中记录的数据列及其数据类型；标签名和数据类型由STable定义，标签值记录着每个子表的静态信息，用以对子表进行分组过滤。子表本质上就是普通的表，由一个时间戳主键和若干个数据列组成，每行记录着具体的数据，数据查询操作与普通表完全相同；但子表与普通表的区别在于每个子表从属于一张超级表，并带有一组由STable定义的标签值。每种类型的采集设备可以定义一个STable。数据模型定义表的每列数据的类型，如温度、压力、电压、电流、GPS实时位置等，而标签信息属于Meta Data，如采集设备的序列号、型号、位置等，是静态的，是表的元数据。用户在创建表（数据采集点）时指定STable(采集类型)外，还可以指定标签的值，也可事后增加或修改。

    -

    TDengine扩展标准SQL语法用于定义STable，使用关键词tags指定标签信息。语法如下：

    -
    CREATE TABLE <stable_name> (<field_name> TIMESTAMP, field_name1 field_type,…)   TAGS(tag_name tag_type, …)
    -

    其中tag_name是标签名，tag_type是标签的数据类型。标签可以使用时间戳之外的其他TDengine支持的数据类型，标签的个数最多为6个，名字不能与系统关键词相同，也不能与其他列名相同。如：

    -
    create table thermometer (ts timestamp, degree float) 
-tags (location binary(20), type int)
    -

    上述SQL创建了一个名为thermometer的STable，带有标签location和标签type。

    -

    为某个采集点创建表时，可以指定其所属的STable以及标签的值，语法如下：

    -
    CREATE TABLE <tb_name> USING <stb_name> TAGS (tag_value1,...)
    -

    沿用上面温度计的例子，使用超级表thermometer建立单个温度计数据表的语句如下：

    -
    create table t1 using thermometer tags (‘beijing', 10)
    -

    上述SQL以thermometer为模板，创建了名为t1的表，这张表的Schema就是thermometer的Schema，但标签location值为'beijing'，标签type值为10。

    -

    用户可以使用一个STable创建数量无上限的具有不同标签的表，从这个意义上理解，STable就是若干具有相同数据模型，不同标签的表的集合。与普通表一样，用户可以创建、删除、查看超级表STable，大部分适用于普通表的查询操作都可运用到STable上，包括各种聚合和投影选择函数。除此之外，可以设置标签的过滤条件，仅对STbale中部分表进行聚合查询，大大简化应用的开发。

    -

    TDengine对表的主键（时间戳）建立索引，暂时不提供针对数据模型中其他采集量（比如温度、压力值）的索引。每个数据采集点会采集若干数据记录，但每个采集点的标签仅仅是一条记录，因此数据标签在存储上没有冗余，且整体数据规模有限。TDengine将标签数据与采集的动态数据完全分离存储，而且针对STable的标签建立了高性能内存索引结构，为标签提供全方位的快速操作支持。用户可按照需求对其进行增删改查（Create，Retrieve，Update，Delete，CRUD）操作。

    -

    STable从属于库，一个STable只属于一个库，但一个库可以有一到多个STable, 一个STable可有多个子表。

    -

    超级表管理

    -
      -

    • 创建超级表

      -
      CREATE TABLE <stable_name> (<field_name> TIMESTAMP, field_name1 field_type,…) TAGS(tag_name tag_type, …)
      -

      与创建表的SQL语法相似。但需指定TAGS字段的名称和类型。

      -

      说明：

      -
        -
      1. TAGS列总长度不能超过512 bytes；
        2. -
      2. TAGS列的数据类型不能是timestamp类型；
        3. -
      3. TAGS列名不能与其他列名相同;
        4. -
      4. TAGS列名不能为预留关键字.
      • -

    • 显示已创建的超级表

      -
      show stables;
      -

      查看数据库内全部STable，及其相关信息，包括STable的名称、创建时间、列数量、标签（TAG）数量、通过该STable建表的数量。

      • -

    • 删除超级表

      -
      DROP TABLE <stable_name>
      -

      Note: 删除STable时，所有通过该STable创建的表都将被删除。

      • -

    • 查看属于某STable并满足查询条件的表

      -
      SELECT TBNAME,[TAG_NAME,…] FROM <stable_name> WHERE <tag_name> <[=|=<|>=|<>] values..> ([AND|OR] …)
      -

      查看属于某STable并满足查询条件的表。说明：TBNAME为关键词，显示通过STable建立的子表表名，查询过程中可以使用针对标签的条件。

      -
      SELECT COUNT(TBNAME) FROM <stable_name> WHERE <tag_name> <[=|=<|>=|<>] values..> ([AND|OR] …)
      -

      统计属于某个STable并满足查询条件的子表的数量

      • -
    -

    写数据时自动建子表

    -

    在某些特殊场景中，用户在写数据时并不确定某个设备的表是否存在，此时可使用自动建表语法来实现写入数据时用超级表定义的表结构自动创建不存在的子表，若该表已存在则不会建立新表。注意：自动建表语句只能自动建立子表而不能建立超级表，这就要求超级表已经被事先定义好。自动建表语法跟insert/import语法非常相似，唯一区别是语句中增加了超级表和标签信息。具体语法如下：

    -
    INSERT INTO <tb_name> USING <stb_name> TAGS (<tag1_value>, ...) VALUES (field_value, ...) (field_value, ...) ...;
    -

    向表tb_name中插入一条或多条记录，如果tb_name这张表不存在，则会用超级表stb_name定义的表结构以及用户指定的标签值(即tag1_value…)来创建名为tb_name新表，并将用户指定的值写入表中。如果tb_name已经存在，则建表过程会被忽略，系统也不会检查tb_name的标签是否与用户指定的标签值一致，也即不会更新已存在表的标签。

    -
    INSERT INTO <tb1_name> USING <stb1_name> TAGS (<tag1_value1>, ...) VALUES (<field1_value1>, ...) (<field1_value2>, ...) ... <tb_name2> USING <stb_name2> TAGS(<tag1_value2>, ...) VALUES (<field1_value1>, ...) ...;
    -

    向多张表tb1_name，tb2_name等插入一条或多条记录，并分别指定各自的超级表进行自动建表。

    -

    STable中TAG管理

    -

    除了更新标签的值的操作是针对子表进行，其他所有的标签操作（添加标签、删除标签等）均只能作用于STable，不能对单个子表操作。对STable添加标签以后，依托于该STable建立的所有表将自动增加了一个标签，对于数值型的标签，新增加的标签的默认值是0.

    -
      -

    • 添加新的标签

      -
      ALTER TABLE <stable_name> ADD TAG <new_tag_name> <TYPE>
      -

      为STable增加一个新的标签，并指定新标签的类型。标签总数不能超过6个。

      • -

    • 删除标签

      -
      ALTER TABLE <stable_name> DROP TAG <tag_name>
      -

      删除超级表的一个标签，从超级表删除某个标签后，该超级表下的所有子表也会自动删除该标签。

      -

      说明：第一列标签不能删除，至少需要为STable保留一个标签。

      • -

    • 修改标签名

      -
      ALTER TABLE <stable_name> CHANGE TAG <old_tag_name> <new_tag_name>
      -

      修改超级表的标签名，从超级表修改某个标签名后，该超级表下的所有子表也会自动更新该标签名。

      • -

    • 修改子表的标签值

      -
      ALTER TABLE <table_name> SET TAG <tag_name>=<new_tag_value>
      • -
    -

    STable多表聚合

    -

    针对所有的通过STable创建的子表进行多表聚合查询，支持按照全部的TAG值进行条件过滤，并可将结果按照TAGS中的值进行聚合，暂不支持针对binary类型的模糊匹配过滤。语法如下：

    -
    SELECT function<field_name>,… 
- FROM <stable_name> 
- WHERE <tag_name> <[=|<=|>=|<>] values..> ([AND|OR] …)
- INTERVAL (<time range>)
- GROUP BY <tag_name>, <tag_name>…
- ORDER BY <tag_name> <asc|desc>
- SLIMIT <group_limit>
- SOFFSET <group_offset>
- LIMIT <record_limit>
- OFFSET <record_offset>
    -

    说明：

    -

    超级表聚合查询，TDengine目前支持以下聚合\选择函数：sum、count、avg、first、last、min、max、top、bottom，以及针对全部或部分列的投影操作，使用方式与单表查询的计算过程相同。暂不支持其他类型的聚合计算和四则运算。当前所有的函数及计算过程均不支持嵌套的方式进行执行。

    -

    不使用GROUP BY的查询将会对超级表下所有满足筛选条件的表按时间进行聚合，结果输出默认是按照时间戳单调递增输出，用户可以使用ORDER BY _c0 ASC|DESC选择查询结果时间戳的升降排序；使用GROUP BY 的聚合查询会按照tags进行分组，并对每个组内的数据分别进行聚合，输出结果为各个组的聚合结果，组间的排序可以由ORDER BY 语句指定，每个分组内部，时间序列是单调递增的。

    -

    使用SLIMIT/SOFFSET语句指定组间分页，即指定结果集中输出的最大组数以及对组起始的位置。使用LIMIT/OFFSET语句指定组内分页，即指定结果集中每个组内最多输出多少条记录以及记录起始的位置。

    -

    STable使用示例

    -

    以温度传感器采集时序数据作为例，示范STable的使用。 在这个例子中，对每个温度计都会建立一张表，表名为温度计的ID，温度计读数的时刻记为ts，采集的值记为degree。通过tags给每个采集器打上不同的标签，其中记录温度计的地区和类型，以方便我们后面的查询。所有温度计的采集量都一样，因此我们用STable来定义表结构。

    -

    定义STable表结构并使用它创建子表

    -

    创建STable语句如下：

    -
    CREATE TABLE thermometer (ts timestamp, degree double) 
-TAGS(location binary(20), type int)
    -

    假设有北京，天津和上海三个地区的采集器共4个，温度采集器有3种类型，我们就可以对每个采集器建表如下：

    -
    CREATE TABLE therm1 USING thermometer TAGS ('beijing', 1);
-CREATE TABLE therm2 USING thermometer TAGS ('beijing', 2);
-CREATE TABLE therm3 USING thermometer TAGS ('tianjin', 1);
-CREATE TABLE therm4 USING thermometer TAGS ('shanghai', 3);
    -

    其中therm1，therm2，therm3，therm4是超级表thermometer四个具体的子表，也即普通的Table。以therm1为例，它表示采集器therm1的数据，表结构完全由thermometer定义，标签location=”beijing”, type=1表示therm1的地区是北京，类型是第1类的温度计。

    -

    写入数据

    -

    注意，写入数据时不能直接对STable操作，而是要对每张子表进行操作。我们分别向四张表therm1，therm2， therm3， therm4写入一条数据，写入语句如下：

    -
    INSERT INTO therm1 VALUES ('2018-01-01 00:00:00.000', 20);
-INSERT INTO therm2 VALUES ('2018-01-01 00:00:00.000', 21);
-INSERT INTO therm3 VALUES ('2018-01-01 00:00:00.000', 24);
-INSERT INTO therm4 VALUES ('2018-01-01 00:00:00.000', 23);
    -

    按标签聚合查询

    -

    查询位于北京(beijing)和天津(tianjing)两个地区的温度传感器采样值的数量count(*)、平均温度avg(degree)、最高温度max(degree)、最低温度min(degree)，并将结果按所处地域(location)和传感器类型(type)进行聚合。

    -
    SELECT COUNT(*), AVG(degree), MAX(degree), MIN(degree)
-FROM thermometer
-WHERE location='beijing' or location='tianjin'
-GROUP BY location, type
    -

    按时间周期聚合查询

    -

    查询仅位于北京以外地区的温度传感器最近24小时(24h)采样值的数量count(*)、平均温度avg(degree)、最高温度max(degree)和最低温度min(degree)，将采集结果按照10分钟为周期进行聚合，并将结果按所处地域(location)和传感器类型(type)再次进行聚合。

    -
    SELECT COUNT(*), AVG(degree), MAX(degree), MIN(degree)
-FROM thermometer
-WHERE location<>'beijing' and ts>=now-1d
-INTERVAL(10M)
-GROUP BY location, type
    回去
    diff --git a/documentation/tdenginedocs-cn/taos-sql/index.html b/documentation/tdenginedocs-cn/taos-sql/index.html deleted file mode 100644 index 207bfe03fd41fb91322c34b754e07fd77711881e..0000000000000000000000000000000000000000 --- a/documentation/tdenginedocs-cn/taos-sql/index.html +++ /dev/null @@ -1,388 +0,0 @@ -文档 | 涛思数据
    回去

    TAOS SQL

    -

    TDengine提供类似SQL语法，用户可以在TDengine Shell中使用SQL语句操纵数据库，也可以通过C/C++, Java(JDBC), Python, Go等各种程序来执行SQL语句。

    -

    本章节SQL语法遵循如下约定：

    -
      -
    • < > 里的内容是用户需要输入的，但不要输入<>本身
      • -
    • [ ]表示内容为可选项，但不能输入[]本身
      • -
    • | 表示多选一，选择其中一个即可，但不能输入|本身
      • -
    • … 表示前面的项可重复多个
      • -
    -

    支持的数据类型

    -

    使用TDengine，最重要的是时间戳。创建并插入记录、查询历史记录的时候，均需要指定时间戳。时间戳有如下规则：

    -
      -
    • 时间格式为YYYY-MM-DD HH:mm:ss.MS, 默认时间分辨率为毫秒。比如：2017-08-12 18:25:58.128
      • -
    • 内部函数now是服务器的当前时间
      • -
    • 插入记录时，如果时间戳为0，插入数据时使用服务器当前时间
      • -
    • Epoch Time: 时间戳也可以是一个长整数，表示从1970-01-01 08:00:00.000开始的毫秒数
      • -
    • 时间可以加减，比如 now-2h，表明查询时刻向前推2个小时(最近2小时)。数字后面的时间单位：a(毫秒), s(秒), m(分), h(小时), d(天)，w(周), n(月), y(年)。比如select * from t1 where ts > now-2w and ts <= now-1w, 表示查询两周前整整一周的数据
      • -
    -

    TDengine缺省的时间戳是毫秒精度，但通过修改配置参数enableMicrosecond就可支持微秒。

    -

    在TDengine中，普通表的数据模型中可使用以下10种数据类型。

    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    类型Bytes说明
    1TIMESTAMP8时间戳。最小精度毫秒。从格林威治时间1970-01-01 08:00:00.000开始，计时不能早于该时间。
    2INT4整型，范围 [-2^31+1, 2^31-1], -2^31被用作Null值
    3BIGINT8长整型，范围 [-2^59, 2^59]
    4FLOAT4浮点型，有效位数6-7，范围 [-3.4E38, 3.4E38]
    5DOUBLE8双精度浮点型，有效位数15-16，范围 [-1.7E308, 1.7E308]
    6BINARY自定义用于记录字符串，最长不能超过504 bytes。binary仅支持字符串输入，字符串两端使用单引号引用，否则英文全部自动转化为小写。使用时须指定大小，如binary(20)定义了最长为20个字符的字符串，每个字符占1byte的存储空间。如果用户字符串超出20字节，将被自动截断。对于字符串内的单引号，可以用转义字符反斜线加单引号来表示， 即 \’。
    7SMALLINT2短整型， 范围 [-32767, 32767]
    8TINYINT1单字节整型，范围 [-127, 127]
    9BOOL1布尔型，{true, false}
    10NCHAR自定义用于记录非ASCII字符串，如中文字符。每个nchar字符占用4bytes的存储空间。字符串两端使用单引号引用，字符串内的单引号需用转义字符 \’。nchar使用时须指定字符串大小，类型为nchar(10)的列表示此列的字符串最多存储10个nchar字符，会固定占用40bytes的空间。如用户字符串长度超出声明长度，则将被自动截断。
    -

    Tips: TDengine对SQL语句中的英文字符不区分大小写，自动转化为小写执行。因此用户大小写敏感的字符串及密码，需要使用单引号将字符串引起来。

    -

    数据库管理

    -
      -

    • 创建数据库

      -
      CREATE DATABASE [IF NOT EXISTS] db_name [KEEP keep]
      -

      创建数据库。KEEP是该数据库的数据保留多长天数，缺省是3650天(10年)，数据库会自动删除超过时限的数据。数据库还有更多与存储相关的配置参数，请参见系统管理。

      • -

    • 使用数据库

      -
      USE db_name
      -

      使用/切换数据库

      • -

    • 删除数据库

      -
      DROP DATABASE [IF EXISTS] db_name
      -

      删除数据库。所包含的全部数据表将被删除，谨慎使用

      • -

    • 显示系统所有数据库

      -
      SHOW DATABASES
      • -
    -

    表管理

    -
      -

    • 创建数据表

      -
      CREATE TABLE [IF NOT EXISTS] tb_name (timestamp_field_name TIMESTAMP, field1_name data_type1 [, field2_name data_type2 ...])
      -

      说明：1）表的第一个字段必须是TIMESTAMP，并且系统自动将其设为主键；2）表的每行长度不能超过4096字节；3）使用数据类型binary或nchar，需指定其最长的字节数，如binary(20)，表示20字节。

      • -

    • 删除数据表

      -
      DROP TABLE [IF EXISTS] tb_name
      • -

    • 显示当前数据库下的所有数据表信息

      -
      SHOW TABLES [LIKE tb_name_wildcar]
      -

      显示当前数据库下的所有数据表信息。说明：可在like中使用通配符进行名称的匹配。 通配符匹配：1）’%’ (百分号)匹配0到任意个字符；2）’_’下划线匹配一个字符。

      • -

    • 获取表的结构信息

      -
      DESCRIBE tb_name
      • -

    • 表增加列

      -
      ALTER TABLE tb_name ADD COLUMN field_name data_type
      • -

    • 表删除列

      -
      ALTER TABLE tb_name DROP COLUMN field_name
      -

      如果表是通过超级表创建，更改表结构的操作只能对超级表进行。同时针对超级表的结构更改对所有通过该结构创建的表生效。对于不是通过超级表创建的表，可以直接修改表结构

      -

      Tips：SQL语句中操作的当前数据库（通过use db_name的方式指定）中的表不需要指定表所属数据库。如果要操作非当前数据库中的表，需要采用“库名”.“表名”的方式。例如：demo.tb1，是指数据库demo中的表tb1。

      • -
    -

    数据写入

    -
      -

    • 插入一条记录

      -
      INSERT INTO tb_name VALUES (field_value, ...);
      -

      向表tb_name中插入一条记录

      • -

    • 插入一条记录，数据对应到指定的列

      -
      INSERT INTO tb_name (field1_name, ...) VALUES(field1_value, ...)
      -

      向表tb_name中插入一条记录，数据对应到指定的列。SQL语句中没有出现的列，数据库将自动填充为NULL。主键（时间戳）不能为NULL。

      • -

    • 插入多条记录

      -
      INSERT INTO tb_name VALUES (field1_value1, ...) (field1_value2, ...)...;
      -

      向表tb_name中插入多条记录

      • -

    • 按指定的列插入多条记录

      -
      INSERT INTO tb_name (field1_name, ...) VALUES(field1_value1, ...) (field1_value2, ...)
      -

      向表tb_name中按指定的列插入多条记录

      • -

    • 向多个表插入多条记录

      -
      INSERT INTO tb1_name VALUES (field1_value1, ...)(field1_value2, ...)... 
-            tb2_name VALUES (field1_value1, ...)(field1_value2, ...)...;
      -

      同时向表tb1_name和tb2_name中分别插入多条记录

      • -

    • 同时向多个表按列插入多条记录

      -
      INSERT INTO tb1_name (tb1_field1_name, ...) VALUES (field1_value1, ...) (field1_value1, ...)
-            tb2_name (tb2_field1_name, ...) VALUES(field1_value1, ...) (field1_value2, ...)
      -

      同时向表tb1_name和tb2_name中按列分别插入多条记录

      • -
    -

    注意：对同一张表，插入的新记录的时间戳必须递增，否则会跳过插入该条记录。如果时间戳为0，系统将自动使用服务器当前时间作为该记录的时间戳。

    -

    IMPORT：如果需要将时间戳小于最后一条记录时间的记录写入到数据库中，可使用IMPORT替代INSERT命令，IMPORT的语法与INSERT完全一样。如果同时IMPORT多条记录，需要保证一批记录是按时间戳排序好的。

    -

    数据查询

    -

    查询语法是：

    -
    SELECT {* | expr_list} FROM tb_name
-    [WHERE where_condition]
-    [ORDER BY _c0 { DESC | ASC }]
-    [LIMIT limit [, OFFSET offset]]
-    [>> export_file]
-
-SELECT function_list FROM tb_name
-    [WHERE where_condition]
-    [LIMIT limit [, OFFSET offset]]
-    [>> export_file]
    -
      -
    • 可以使用* 返回所有列，或指定列名。可以对数字列进行四则运算，可以给输出的列取列名
      • -
    • where语句可以使用各种逻辑判断来过滤数字值，或使用通配符来过滤字符串
      • -
    • 输出结果缺省按首列时间戳升序排序，但可以指定按降序排序(_c0指首列时间戳)。使用ORDER BY对其他字段进行排序为非法操作。
      • -
    • 参数LIMIT控制输出条数，OFFSET指定从第几条开始输出。LIMIT/OFFSET对结果集的执行顺序在ORDER BY之后。
      • -
    • 通过”>>"输出结果可以导出到指定文件
      • -
    -

    支持的条件过滤操作

    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    OperationNoteApplicable Data Types
    >larger thantimestamp and all numeric types
    <smaller thantimestamp and all numeric types
    >=larger than or equal totimestamp and all numeric types
    <=smaller than or equal totimestamp and all numeric types
    =equal toall types
    <>not equal toall types
    %match with any char sequencesbinary nchar
    _match with a single charbinary nchar
    -
      -
    1. 同时进行多个字段的范围过滤需要使用关键词AND进行连接不同的查询条件，暂不支持OR连接的查询条件。
      2. -
    2. 针对某一字段的过滤只支持单一区间的过滤条件。例如：value>20 and value<30是合法的过滤条件, 而Value<20 AND value<>5是非法的过滤条件。
      3. -
    -

    Some Examples

    -
      -

    • 对于下面的例子，表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时间范围，并且clo3的字符串是'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/testoutpu.csv.

      -
      SELECT COUNT(*) FROM tb1 WHERE ts >= NOW - 10m AND col2 > 3.14 >> /home/testoutpu.csv
      • -
    -

    SQL函数

    -

    聚合函数

    -

    TDengine支持针对数据的聚合查询。提供支持的聚合和提取函数如下表：

    -
      -

    • COUNT

      -
      SELECT COUNT([*|field_name]) FROM tb_name [WHERE clause]
      -

      功能说明：统计表/超级表中记录行数或某列的非空值个数。
      -返回结果数据类型：长整型INT64。
      -应用字段：应用全部字段。
      -适用于：表、超级表。
      -说明：1）可以使用星号来替代具体的字段，使用星号()返回全部记录数量。2）针对同一表的（不包含NULL值）字段查询结果均相同。3）如果统计对象是具体的列，则返回该列中非NULL值的记录数量。

      • -

    • AVG

      -
      SELECT AVG(field_name) FROM tb_name [WHERE clause]
      -

      功能说明：统计表/超级表中某列的平均值。
      -返回结果数据类型：双精度浮点数Double。
      -应用字段：不能应用在timestamp、binary、nchar、bool字段。
      -适用于：表、超级表。

      • -

    • WAVG

      -
      SELECT WAVG(field_name) FROM tb_name WHERE clause
      -

      功能说明：统计表/超级表中某列在一段时间内的时间加权平均。
      -返回结果数据类型：双精度浮点数Double。
      -应用字段：不能应用在timestamp、binary、nchar、bool类型字段。
      -适用于：表、超级表。

      • -

    • SUM

      -
      SELECT SUM(field_name) FROM tb_name [WHERE clause]
      -

      功能说明：统计表/超级表中某列的和。
      -返回结果数据类型：双精度浮点数Double和长整型INT64。
      -应用字段：不能应用在timestamp、binary、nchar、bool类型字段。
      -适用于：表、超级表。

      • -

    • STDDEV

      -
      SELECT STDDEV(field_name) FROM tb_name [WHERE clause]
      -

      功能说明：统计表中某列的均方差。
      -返回结果数据类型：双精度浮点数Double。
      -应用字段：不能应用在timestamp、binary、nchar、bool类型字段。
      -适用于：表。

      • -

    • LEASTSQUARES

      -
      SELECT LEASTSQUARES(field_name) FROM tb_name [WHERE clause]
      -

      功能说明：统计表中某列的值是主键（时间戳）的拟合直线方程。
      -返回结果数据类型：字符串表达式（斜率, 截距）。
      -应用字段：不能应用在timestamp、binary、nchar、bool类型字段。
      -说明：自变量是时间戳，因变量是该列的值。
      -适用于：表。

      • -
    -

    选择函数

    -
      -

    • MIN

      -
      SELECT MIN(field_name) FROM {tb_name | stb_name} [WHERE clause]
      -

      功能说明：统计表/超级表中某列的值最小值。
      -返回结果数据类型：同应用的字段。
      -应用字段：不能应用在timestamp、binary、nchar、bool类型字段。

      • -

    • MAX

      -
      SELECT MAX(field_name) FROM { tb_name | stb_name } [WHERE clause]
      -

      功能说明：统计表/超级表中某列的值最大值。
      -返回结果数据类型：同应用的字段。
      -应用字段：不能应用在timestamp、binary、nchar、bool类型字段。

      • -

    • FIRST

      -
      SELECT FIRST(field_name) FROM { tb_name | stb_name } [WHERE clause]
      -

      功能说明：统计表/超级表中某列的值最先写入的非NULL值。
      -返回结果数据类型：同应用的字段。
      -应用字段：所有字段。
      -说明：1）如果要返回各个列的首个（时间戳最小）非NULL值，可以使用FIRST(*)；2) 如果结果集中的某列全部为NULL值，则该列的返回结果也是NULL；3) 如果结果集中所有列全部为NULL值，则不返回结果。

      • -

    • LAST

      -
      SELECT LAST(field_name) FROM { tb_name | stb_name } [WHERE clause]
      -

      功能说明：统计表/超级表中某列的值最后写入的非NULL值。
      -返回结果数据类型：同应用的字段。
      -应用字段：所有字段。
      -说明：1）如果要返回各个列的最后（时间戳最大）一个非NULL值，可以使用LAST(*)；2）如果结果集中的某列全部为NULL值，则该列的返回结果也是NULL；如果结果集中所有列全部为NULL值，则不返回结果。

      • -

    • TOP

      -
      SELECT TOP(field_name, K) FROM { tb_name | stb_name } [WHERE clause]
      -

      功能说明： 统计表/超级表中某列的值最大k个非NULL值。若多于k个列值并列最大，则返回时间戳小的。
      -返回结果数据类型：同应用的字段。
      -应用字段：不能应用在timestamp、binary、nchar、bool类型字段。
      -说明：1）k值取值范围1≤k≤100；2）系统同时返回该记录关联的时间戳列。

      • -

    • BOTTOM

      -
      SELECT BOTTOM(field_name, K) FROM { tb_name | stb_name } [WHERE clause]
      -

      功能说明：统计表/超级表中某列的值最小k个非NULL值。若多于k个列值并列最小，则返回时间戳小的。
      -返回结果数据类型：同应用的字段。
      -应用字段：不能应用在timestamp、binary、nchar、bool类型字段。
      -说明：1）k值取值范围1≤k≤100；2）系统同时返回该记录关联的时间戳列。

      • -

    • PERCENTILE

      -
      SELECT PERCENTILE(field_name, P) FROM { tb_name | stb_name } [WHERE clause]
      -

      功能说明：统计表中某列的值百分比分位数。
      -返回结果数据类型： 双精度浮点数Double。
      -应用字段：不能应用在timestamp、binary、nchar、bool类型字段。
      -说明：k值取值范围0≤k≤100，为0的时候等同于MIN，为100的时候等同于MAX。

      • -

    • LAST_ROW

      -
      SELECT LAST_ROW(field_name) FROM { tb_name | stb_name }
      -

      功能说明：返回表（超级表）的最后一条记录。
      -返回结果数据类型：同应用的字段。
      -应用字段：所有字段。
      -说明：与last函数不同，last_row不支持时间范围限制，强制返回最后一条记录。

      • -
    -

    计算函数

    -
      -

    • DIFF

      -
      SELECT DIFF(field_name) FROM tb_name [WHERE clause]
      -

      功能说明：统计表中某列的值与前一行对应值的差。
      -返回结果数据类型： 同应用字段。
      -应用字段：不能应用在timestamp、binary、nchar、bool类型字段。
      -说明：输出结果行数是范围内总行数减一，第一行没有结果输出。

      • -

    • SPREAD

      -
      SELECT SPREAD(field_name) FROM { tb_name | stb_name } [WHERE clause]
      -

      功能说明：统计表/超级表中某列的最大值和最小值之差。
      -返回结果数据类型： 双精度浮点数。
      -应用字段：不能应用在binary、nchar、bool类型字段。
      -说明：可用于TIMESTAMP字段，此时表示记录的时间覆盖范围。

      • -

    • 四则运算

      -
      SELECT field_name [+|-|*|/|%][Value|field_name] FROM { tb_name | stb_name }  [WHERE clause]
      -

      功能说明：统计表/超级表中某列或多列间的值加、减、乘、除、取余计算结果。
      -返回结果数据类型：双精度浮点数。
      -应用字段：不能应用在timestamp、binary、nchar、bool类型字段。
      -说明：1）支持两列或多列之间进行计算，可使用括号控制计算优先级;2）NULL字段不参与计算，如果参与计算的某行中包含NULL，该行的计算结果为NULL。

      • -
    -

    时间维度聚合

    -

    TDengine支持按时间段进行聚合，可以将表中数据按照时间段进行切割后聚合生成结果，比如温度传感器每秒采集一次数据，但需查询每隔10分钟的温度平均值。这个聚合适合于降维(down sample)操作, 语法如下：

    -
    SELECT function_list FROM tb_name 
-  [WHERE where_condition]
-  INTERVAL (interval)
-  [FILL ({NONE | VALUE | PREV | NULL | LINEAR})]
-
-SELECT function_list FROM stb_name 
-  [WHERE where_condition]
-  [FILL ({ VALUE | PREV | NULL | LINEAR})]
-  INTERVAL (interval)
-  [GROUP BY tags]
    -
      -
    • 聚合时间段的长度由关键词INTERVAL指定，最短时间间隔10毫秒（10a）。聚合查询中，能够同时执行的聚合和选择函数仅限于单个输出的函数：count、avg、sum 、stddev、leastsquares、percentile、min、max、first、last，不能使用具有多行输出结果的函数（例如：top、bottom、diff以及四则运算）。
      • -
    • WHERE语句可以指定查询的起止时间和其他过滤条件
      • -
    • FILL语句指定某一时间区间数据缺失的情况下的填充模式。填充模式包括以下几种：
      • -
    -
      -

    1. 不进行填充：NONE(默认填充模式)。

      2. -

    2. VALUE填充：固定值填充，此时需要指定填充的数值。例如：fill(value, 1.23)。

      3. -

    3. NULL填充：使用NULL填充数据。例如：fill(null)。

      4. -

    4. PREV填充：使用前一个非NULL值填充数据。例如：fill(prev)。

      5. -
    -

    说明：

    -
      -
    1. 使用FILL语句的时候可能生成大量的填充输出，务必指定查询的时间区间。针对每次查询，系统可返回不超过1千万条具有插值的结果。
      2. -
    2. 在时间维度聚合中，返回的结果中时间序列严格单调递增。
      3. -
    3. 如果查询对象是超级表，则聚合函数会作用于该超级表下满足值过滤条件的所有表的数据。如果查询中没有使用group by语句，则返回的结果按照时间序列严格单调递增；如果查询中使用了group by语句分组，则返回结果中每个group内不按照时间序列严格单调递增。
      4. -
    -

    示例：温度数据表的建表语句如下：

    -
    create table sensor(ts timestamp, degree double, pm25 smallint)
    -

    针对传感器采集的数据，以10分钟为一个阶段，计算过去24小时的温度数据的平均值、最大值、温度的中位数、以及随着时间变化的温度走势拟合直线。如果没有计算值，用前一个非NULL值填充。

    -
    SELECT AVG(degree),MAX(degree),LEASTSQUARES(degree), PERCENTILE(degree, 50) FROM sensor
-  WHERE TS>=NOW-1d
-  INTERVAL(10m)
-  FILL(PREV);
    回去
    \ No newline at end of file diff --git a/documentation/tdenginedocs-en/administrator/index.html b/documentation/tdenginedocs-en/administrator/index.html deleted file mode 100644 index 1615fbfb6a7aaedf208b2b0f959f08f9bb26cac8..0000000000000000000000000000000000000000 --- a/documentation/tdenginedocs-en/administrator/index.html +++ /dev/null @@ -1,137 +0,0 @@ -Documentation | Taos Data
    Back

    Administrator

    -

    Directory and Files

    -

    After TDengine is installed, by default, the following directories will be created:

    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Directory/FileDescription
    /etc/taos/taos.cfgTDengine configuration file
    /usr/local/taos/driverTDengine dynamic link library
    /var/lib/taosTDengine default data directory
    /var/log/taosTDengine default log directory
    /usr/local/taos/bin.TDengine executables
    -

    Executables

    -

    All TDengine executables are located at /usr/local/taos/bin , including:

    -
      -
    • taosd：TDengine server
      • -
    • taos： TDengine Shell, the command line interface.
      • -
    • taosdump：TDengine data export tool
      • -
    • rmtaos： a script to uninstall TDengine
      • -
    -

    You can change the data directory and log directory setting through the system configuration file

    -

    Configuration on Server

    -

    taosd is running on the server side, you can change the system configuration file taos.cfg to customize its behavior. By default, taos.cfg is located at /etc/taos, but you can specify the path to configuration file via the command line parameter -c. For example: taosd -c /home/user means the configuration file will be read from directory /home/user.

    -

    This section lists only the most important configuration parameters. Please check taos.cfg to find all the configurable parameters. Note: to make your new configurations work, you have to restart taosd after you change taos.cfg.

    -
      -
    • mgmtShellPort: TCP and UDP port between client and TDengine mgmt (default: 6030). Note: 5 successive UDP ports (6030-6034) starting from this number will be used.
      • -
    • vnodeShellPort: TCP and UDP port between client and TDengine vnode (default: 6035). Note: 5 successive UDP ports (6035-6039) starting from this number will be used.
      • -
    • httpPort: TCP port for RESTful service (default: 6020)
      • -
    • dataDir: data directory, default is /var/lib/taos
      • -
    • maxUsers: maximum number of users allowed
      • -
    • maxDbs: maximum number of databases allowed
      • -
    • maxTables: maximum number of tables allowed
      • -
    • enableMonitor: turn on/off system monitoring, 0: off, 1: on
      • -
    • logDir: log directory, default is /var/log/taos
      • -
    • numOfLogLines: maximum number of lines in the log file
      • -
    • debugFlag: log level, 131: only error and warnings, 135: all
      • -
    -

    In different scenarios, data characteristics are different. For example, the retention policy, data sampling period, record size, the number of devices, and data compression may be different. To gain the best performance, you can change the following configurations related to storage:

    -
      -
    • days: number of days to cover for a data file
      • -
    • keep: number of days to keep the data
      • -
    • rows: number of rows of records in a block in data file.
      • -
    • comp: compression algorithm, 0: off, 1: standard; 2: maximum compression
      • -
    • ctime: period (seconds) to flush data to disk
      • -
    • clog: flag to turn on/off Write Ahead Log, 0: off, 1: on
      • -
    • tables: maximum number of tables allowed in a vnode
      • -
    • cache: cache block size (bytes)
      • -
    • tblocks: maximum number of cache blocks for a table
      • -
    • abloks: average number of cache blocks for a table
      • -
    • precision: timestamp precision, us: microsecond ms: millisecond, default is ms
      • -
    -

    For an application, there may be multiple data scenarios. The best design is to put all data with the same characteristics into one database. One application may have multiple databases, and every database has its own configuration to maximize the system performance. You can specify the above configurations related to storage when you create a database. For example:

    -
    CREATE DATABASE demo DAYS 10 CACHE 16000 ROWS 2000
    -

    The above SQL statement will create a database demo, with 10 days for each data file, 16000 bytes for a cache block, and 2000 rows in a file block.

    -

    The configuration provided when creating a database will overwrite the configuration in taos.cfg.

    -

    Configuration on Client

    -

    taos is the TDengine shell and is a client that connects to taosd. TDengine uses the same configuration file taos.cfg for the client, with default location at /etc/taos. You can change it by specifying command line parameter -c when you run taos. For example, taos -c /home/user, it will read the configuration file taos.cfg from directory /home/user.

    -

    The parameters related to client configuration are listed below:

    -
      -
    • masterIP: IP address of TDengine server
      • -
    • charset: character set, default is the system . For data type nchar, TDengine uses unicode to store the data. Thus, the client needs to tell its character set.
      • -
    • locale: system language setting
      • -
    • defaultUser: default login user, default is root
      • -
    • defaultPass: default password, default is taosdata
      • -
    -

    For TCP/UDP port, and system debug/log configuration, it is the same as the server side.

    -

    For server IP, user name, password, you can always specify them in the command line when you run taos. If they are not specified, they will be read from the taos.cfg

    -

    User Management

    -

    System administrator (user root) can add, remove a user, or change the password from the TDengine shell. Commands are listed below:

    -

    Create a user, password shall be quoted with the single quote.

    -
    CREATE USER user_name PASS ‘password’
    -

    Remove a user

    -
    DROP USER user_name
    -

    Change the password for a user

    -
    ALTER USER user_name PASS ‘password’
    -

    List all users

    -
    SHOW USERS
    -

    Import Data

    -

    Inside the TDengine shell, you can import data into TDengine from either a script or CSV file

    -

    Import from Script

    -
    source <filename>
    -

    Inside the file, you can put all SQL statements there. Each SQL statement has a line. If a line starts with "#", it means comments, it will be skipped. The system will execute the SQL statements line by line automatically until the ends

    -

    Import from CVS

    -
    insert into tb1 file a.csv b.csv tb2 c.csv …
-import into tb1 file a.csv b.csv tb2 c.csv …
    -

    Each csv file contains records for only one table, and the data structure shall be the same as the defined schema for the table.

    -

    Export Data

    -

    You can export data either from TDengine shell or from tool taosdump.

    -

    Export from TDengine Shell

    -
    select * from <tb_name> >> a.csv
    -

    The above SQL statement will dump the query result set into a csv file.

    -

    Export Using taosdump

    -

    TDengine provides a data dumping tool taosdump. You can choose to dump a database, a table, all data or data only a time range, even only the metadata. For example:

    -
      -
    • Export one or more tables in a DB: taosdump [OPTION…] dbname tbname …
      • -
    • Export one or more DBs: taosdump [OPTION…] --databases dbname…
      • -
    • Export all DBs (excluding system DB): taosdump [OPTION…] --all-databases
      • -
    -

    run taosdump —help to get a full list of the options

    -

    Management of Connections, Streams, Queries

    -

    The system administrator can check, kill the ongoing connections, streams, or queries.

    -
    SHOW CONNECTIONS
    -

    It lists all connections, one column shows ip:port from the client.

    -
    KILL CONNECTION <connection-id>
    -

    It kills the connection, where connection-id is the ip:port showed by "SHOW CONNECTIONS". You can copy and paste it.

    -
    SHOW QUERIES
    -

    It shows the ongoing queries, one column ip:port:id shows the ip:port from the client, and id assigned by the system

    -
    KILL QUERY <query-id>
    -

    It kills the query, where query-id is the ip:port:id showed by "SHOW QUERIES". You can copy and paste it.

    -
    SHOW STREAMS
    -

    It shows the continuous queries, one column shows the ip:port:id, where ip:port is the connection from the client, and id assigned by the system.

    -
    KILL STREAM <stream-id>
    -

    It kills the continuous query, where stream-id is the ip:port:id showed by "SHOW STREAMS". You can copy and paste it.

    -

    System Monitor

    -

    TDengine runs a system monitor in the background. Once it is started, it will create a database sys automatically. System monitor collects the metric like CPU, memory, network, disk, number of requests periodically, and writes them into database sys. Also, TDengine will log all important actions, like login, logout, create database, drop database and so on, and write them into database sys.

    -

    You can check all the saved monitor information from database sys. By default, system monitor is turned on. But you can turn it off by changing the parameter in the configuration file.

    Back
    \ No newline at end of file diff --git a/documentation/tdenginedocs-en/advanced-features/index.html b/documentation/tdenginedocs-en/advanced-features/index.html deleted file mode 100644 index cb8fd04c8ec0ef7c6941b49fb96526d9b8c5178c..0000000000000000000000000000000000000000 --- a/documentation/tdenginedocs-en/advanced-features/index.html +++ /dev/null @@ -1,41 +0,0 @@ -Documentation | Taos Data
    Back

    Advanced Features

    -

    Continuous Query

    -

    Continuous Query is a query executed by TDengine periodically with a sliding window, it is a simplified stream computing driven by timers, not by events. Continuous query can be applied to a table or a STable, and the result set can be passed to the application directly via call back function, or written into a new table in TDengine. The query is always executed on a specified time window (window size is specified by parameter interval), and this window slides forward while time flows (the sliding period is specified by parameter sliding).

    -

    Continuous query is defined by TAOS SQL, there is nothing special. One of the best applications is downsampling. Once it is defined, at the end of each cycle, the system will execute the query, pass the result to the application or write it to a database.

    -

    If historical data pints are inserted into the stream, the query won't be re-executed, and the result set won't be updated. If the result set is passed to the application, the application needs to keep the status of continuous query, the server won't maintain it. If application re-starts, it needs to decide the time where the stream computing shall be started.

    -

    How to use continuous query

    -
      -

    • Pass result set to application

      -

      Application shall use API taos_stream (details in connector section) to start the stream computing. Inside the API, the SQL syntax is:

      -
      SELECT aggregation FROM [table_name | stable_name] 
-INTERVAL(window_size) SLIDING(period)
      -

      where the new keyword INTERVAL specifies the window size, and SLIDING specifies the sliding period. If parameter sliding is not specified, the sliding period will be the same as window size. The minimum window size is 10ms. The sliding period shall not be larger than the window size. If you set a value larger than the window size, the system will adjust it to window size automatically.

      -

      For example:

      -
      SELECT COUNT(*) FROM FOO_TABLE 
-INTERVAL(1M) SLIDING(30S)
      -

      The above SQL statement will count the number of records for the past 1-minute window every 30 seconds.

      • -

    • Save the result into a database

      -

      If you want to save the result set of stream computing into a new table, the SQL shall be:

      -
      CREATE TABLE table_name AS 
-SELECT aggregation from [table_name | stable_name]  
-INTERVAL(window_size) SLIDING(period)
      -

      Also, you can set the time range to execute the continuous query. If no range is specified, the continuous query will be executed forever. For example, the following continuous query will be executed from now and will stop in one hour.

      -
      CREATE TABLE QUERY_RES AS 
-SELECT COUNT(*) FROM FOO_TABLE 
-WHERE TS > NOW AND TS <= NOW + 1H 
-INTERVAL(1M) SLIDING(30S)
      • -
    -

    Manage the Continuous Query

    -

    Inside TDengine shell, you can use the command "show streams" to list the ongoing continuous queries, the command "kill stream" to kill a specific continuous query.

    -

    If you drop a table generated by the continuous query, the query will be removed too.

    -

    Publisher/Subscriber

    -

    Time series data is a sequence of data points over time. Inside a table, the data points are stored in order of timestamp. Also, there is a data retention policy, the data points will be removed once their lifetime is passed. From another view, a table in TDengine is just a standard message queue.

    -

    To reduce the development complexity and improve data consistency, TDengine provides the pub/sub functionality. To publish a message, you simply insert a record into a table. Compared with popular messaging tool Kafka, you subscribe to a table or a SQL query statement, instead of a topic. Once new data points arrive, TDengine will notify the application. The process is just like Kafka.

    -

    The detailed API will be introduced in the connectors section.

    -

    Caching

    -

    TDengine allocates a fixed-size buffer in memory, the newly arrived data will be written into the buffer first. Every device or table gets one or more memory blocks. For typical IoT scenarios, the hot data shall always be newly arrived data, they are more important for timely analysis. Based on this observation, TDengine manages the cache blocks in First-In-First-Out strategy. If no enough space in the buffer, the oldest data will be saved into hard disk first, then be overwritten by newly arrived data. TDengine also guarantees every device can keep at least one block of data in the buffer.

    -

    By this design, the application can retrieve the latest data from each device super-fast, since they are all available in memory. You can use last or last_row function to return the last data record. If the super table is used, it can be used to return the last data records of all or a subset of devices. For example, to retrieve the latest temperature from thermometers in located Beijing, execute the following SQL

    -
    select last(*) from thermometers where location=’beijing’
    -

    By this design, caching tool, like Redis, is not needed in the system. It will reduce the complexity of the system.

    -

    TDengine creates one or more virtual nodes(vnode) in each data node. Each vnode contains data for multiple tables and has its own buffer. The buffer of a vnode is fully separated from the buffer of another vnode, not shared. But the tables in a vnode share the same buffer.

    -

    System configuration parameter cacheBlockSize configures the cache block size in bytes, and another parameter cacheNumOfBlocks configures the number of cache blocks. The total memory for the buffer of a vnode is $cacheBlockSize \times cacheNumOfBlocks$. Another system parameter numOfBlocksPerMeter configures the maximum number of cache blocks a table can use. When you create a database, you can specify these parameters.

    Back
    diff --git a/documentation/tdenginedocs-en/assets/Picture2.png b/documentation/tdenginedocs-en/assets/Picture2.png deleted file mode 100644 index 715a8bd37ee9fe7e96eacce4e7ff563fedeefbee..0000000000000000000000000000000000000000 Binary files a/documentation/tdenginedocs-en/assets/Picture2.png and /dev/null differ diff --git a/documentation/tdenginedocs-en/assets/clip_image001-2474914.png b/documentation/tdenginedocs-en/assets/clip_image001-2474914.png deleted file mode 100644 index eb369b1567c860b772e1bfdad64ff17aaac2534d..0000000000000000000000000000000000000000 Binary files a/documentation/tdenginedocs-en/assets/clip_image001-2474914.png and /dev/null differ diff --git a/documentation/tdenginedocs-en/assets/clip_image001-2474939.png b/documentation/tdenginedocs-en/assets/clip_image001-2474939.png deleted file mode 100644 index 53f00deea3a484986a5681ec9d00d8ae02e88fec..0000000000000000000000000000000000000000 Binary files a/documentation/tdenginedocs-en/assets/clip_image001-2474939.png and /dev/null differ diff --git a/documentation/tdenginedocs-en/assets/clip_image001-2474961.png b/documentation/tdenginedocs-en/assets/clip_image001-2474961.png deleted file mode 100644 index 20ae8d6f7724a4bddcf8c7eb3809d468aa4223ed..0000000000000000000000000000000000000000 Binary files a/documentation/tdenginedocs-en/assets/clip_image001-2474961.png and /dev/null differ diff --git a/documentation/tdenginedocs-en/assets/clip_image001-2474987.png b/documentation/tdenginedocs-en/assets/clip_image001-2474987.png deleted file mode 100644 index 3d09f7fc28e7a1fb7e3bb2b9b2bc7c20895e8bb4..0000000000000000000000000000000000000000 Binary files a/documentation/tdenginedocs-en/assets/clip_image001-2474987.png and /dev/null differ diff --git a/documentation/tdenginedocs-en/assets/clip_image001.png b/documentation/tdenginedocs-en/assets/clip_image001.png deleted file mode 100644 index 78b6d06a9562b802e80f0ed5fdb8963b5e525589..0000000000000000000000000000000000000000 Binary files a/documentation/tdenginedocs-en/assets/clip_image001.png and /dev/null differ diff --git a/documentation/tdenginedocs-en/assets/fig1.png b/documentation/tdenginedocs-en/assets/fig1.png deleted file mode 100644 index af9b74e0d1a872b8d93f71842dc0063bc8a86092..0000000000000000000000000000000000000000 Binary files a/documentation/tdenginedocs-en/assets/fig1.png and /dev/null differ diff --git a/documentation/tdenginedocs-en/assets/fig2.png b/documentation/tdenginedocs-en/assets/fig2.png deleted file mode 100644 index 3bae70ba86964c3c341b72ea1d3af04201f7c6c1..0000000000000000000000000000000000000000 Binary files a/documentation/tdenginedocs-en/assets/fig2.png and /dev/null differ diff --git a/documentation/tdenginedocs-en/assets/image-20190707124650780.png b/documentation/tdenginedocs-en/assets/image-20190707124650780.png deleted file mode 100644 index 9ebcac863e862d8b240c86dec29be1ebe7aa50f0..0000000000000000000000000000000000000000 Binary files a/documentation/tdenginedocs-en/assets/image-20190707124650780.png and /dev/null differ diff --git a/documentation/tdenginedocs-en/assets/image-20190707124818590.png b/documentation/tdenginedocs-en/assets/image-20190707124818590.png deleted file mode 100644 index dc1cb6325b2d4cd6f05c88b75b4d17ef85caa67f..0000000000000000000000000000000000000000 Binary files a/documentation/tdenginedocs-en/assets/image-20190707124818590.png and /dev/null differ diff --git a/documentation/tdenginedocs-en/assets/nodes.png b/documentation/tdenginedocs-en/assets/nodes.png deleted file mode 100644 index d4ae5120c29b8cfacdc543df5a2a7104d77a2a7b..0000000000000000000000000000000000000000 Binary files a/documentation/tdenginedocs-en/assets/nodes.png and /dev/null differ diff --git a/documentation/tdenginedocs-en/assets/structure.png b/documentation/tdenginedocs-en/assets/structure.png deleted file mode 100644 index 801829b68580e1a46d0841a3d38e4885eb383991..0000000000000000000000000000000000000000 Binary files a/documentation/tdenginedocs-en/assets/structure.png and /dev/null differ diff --git a/documentation/tdenginedocs-en/assets/vnode.png b/documentation/tdenginedocs-en/assets/vnode.png deleted file mode 100644 index 5247717f62118a8e690e80a3538c1a8dd1ab9416..0000000000000000000000000000000000000000 Binary files a/documentation/tdenginedocs-en/assets/vnode.png and /dev/null differ diff --git a/documentation/tdenginedocs-en/assets/write_process.png b/documentation/tdenginedocs-en/assets/write_process.png deleted file mode 100644 index f7d60864824a34af48df637026d704a921dc49f6..0000000000000000000000000000000000000000 Binary files a/documentation/tdenginedocs-en/assets/write_process.png and /dev/null differ diff --git a/documentation/tdenginedocs-en/connections-with-other-tools/index.html b/documentation/tdenginedocs-en/connections-with-other-tools/index.html deleted file mode 100644 index 2c68a01063987a23547c75368062f9434185cb8c..0000000000000000000000000000000000000000 --- a/documentation/tdenginedocs-en/connections-with-other-tools/index.html +++ /dev/null @@ -1,93 +0,0 @@ -Documentation | Taos Data
    Back

    Connect with other tools

    -

    Telegraf

    -

    TDengine is easy to integrate with Telegraf, an open-source server agent for collecting and sending metrics and events, without more development.

    -

    Install Telegraf

    -

    At present, TDengine supports Telegraf newer than version 1.7.4. Users can go to the download link and choose the proper package to install on your system.

    -

    Configure Telegraf

    -

    Telegraf is configured by changing items in the configuration file /etc/telegraf/telegraf.conf.

    -

    In output plugins section，add [[outputs.http]] iterm：

    -
      -
    • url: http://ip:6020/telegraf/udb, in which ip is the IP address of any node in TDengine cluster. Port 6020 is the RESTful APT port used by TDengine. udb is the name of the database to save data, which needs to create beforehand.
      • -
    • method: "POST"
      • -
    • username: username to login TDengine
      • -
    • password: password to login TDengine
      • -
    • data_format: "json"
      • -
    • json_timestamp_units: "1ms"
      • -
    -

    In agent part：

    -
      -
    • hostname: used to distinguish different machines. Need to be unique.
      • -
    • metric_batch_size: 30，the maximum number of records allowed to write in Telegraf. The larger the value is, the less frequent requests are sent. For TDengine, the value should be less than 50.
      • -
    -

    Please refer to the Telegraf docs for more information.

    -

    Grafana

    -

    Grafana is an open-source system for time-series data display. It is easy to integrate TDengine and Grafana to build a monitor system. Data saved in TDengine can be fetched and shown on the Grafana dashboard.

    -

    Install Grafana

    -

    For now, TDengine only supports Grafana newer than version 5.2.4. Users can go to the Grafana download page for the proper package to download.

    -

    Configure Grafana

    -

    TDengine Grafana plugin is in the /usr/local/taos/connector/grafana directory. -Taking Centos 7.2 as an example, just copy TDengine directory to /var/lib/grafana/plugins directory and restart Grafana.

    -

    Use Grafana

    -

    Users can log in the Grafana server (username/password:admin/admin) through localhost:3000 to configure TDengine as the data source. As is shown in the picture below, TDengine as a data source option is shown in the box:

    -

    img

    -

    When choosing TDengine as the data source, the Host in HTTP configuration should be configured as the IP address of any node of a TDengine cluster. The port should be set as 6020. For example, when TDengine and Grafana are on the same machine, it should be configured as _http://localhost:6020.

    -

    Besides, users also should set the username and password used to log into TDengine. Then click Save&Test button to save.

    -

    img

    -

    Then, TDengine as a data source should show in the Grafana data source list.

    -

    img

    -

    Then, users can create Dashboards in Grafana using TDengine as the data source:

    -

    img

    -

    Click Add Query button to add a query and input the SQL command you want to run in the INPUT SQL text box. The SQL command should expect a two-row, multi-column result, such as SELECT count(*) FROM sys.cpu WHERE ts>=from and ts<​to interval(interval), in which, from, to and inteval are TDengine inner variables representing query time range and time interval.

    -

    ALIAS BY field is to set the query alias. Click GENERATE SQL to send the command to TDengine:

    -

    img

    -

    Please refer to the Grafana official document for more information about Grafana.

    -

    Matlab

    -

    Matlab can connect to and retrieve data from TDengine by TDengine JDBC Driver.

    -

    MatLab and TDengine JDBC adaptation

    -

    Several steps are required to adapt Matlab to TDengine. Taking adapting Matlab2017a on Windows10 as an example:

    -
      -
    1. Copy the file JDBCDriver-1.0.0-dist.jar in TDengine package to the directory ${matlab_root}\MATLAB\R2017a\java\jar\toolbox
      2. -
    2. Copy the file taos.lib in TDengine package to ${matlab root dir}\MATLAB\R2017a\lib\win64
      3. -
    3. Add the .jar package just copied to the Matlab classpath. Append the line below as the end of the file of ${matlab root dir}\MATLAB\R2017a\toolbox\local\classpath.txt
      4. -
    -

    ​ $matlabroot/java/jar/toolbox/JDBCDriver-1.0.0-dist.jar

    -
      -
    1. Create a file called javalibrarypath.txt in directory ${user_home}\AppData\Roaming\MathWorks\MATLAB\R2017a_, and add the _taos.dll path in the file. For example, if the file taos.dll is in the directory of C:\Windows\System32，then add the following line in file javalibrarypath.txt:
      2. -
    -

    ​ C:\Windows\System32

    -

    TDengine operations in Matlab

    -

    After correct configuration, open Matlab:

    -
      -

    • build a connection：

      -

      conn = database(‘db’, ‘root’, ‘taosdata’, ‘com.taosdata.jdbc.TSDBDriver’, ‘jdbc:TSDB://127.0.0.1:0/’)

      • -

    • Query：

      -

      sql0 = [‘select * from tb’]

      -

      data = select(conn, sql0);

      • -

    • Insert a record:

      -

      sql1 = [‘insert into tb values (now, 1)’]

      -

      exec(conn, sql1)

      • -
    -

    Please refer to the file examples\Matlab\TDengineDemo.m for more information.

    -

    R

    -

    Users can use R language to access the TDengine server with the JDBC interface. At first, install JDBC package in R:

    -
    install.packages('rJDBC', repos='http://cran.us.r-project.org')
    -

    Then use library function to load the package:

    -
    library('RJDBC')
    -

    Then load the TDengine JDBC driver:

    -
    drv<-JDBC("com.taosdata.jdbc.TSDBDriver","JDBCDriver-1.0.0-dist.jar", identifier.quote="\"")
    -

    If succeed, no error message will display. Then use the following command to try a database connection:

    -
    conn<-dbConnect(drv,"jdbc:TSDB://192.168.0.1:0/?user=root&password=taosdata","root","taosdata")
    -

    Please replace the IP address in the command above to the correct one. If no error message is shown, then the connection is established successfully. TDengine supports below functions in RJDBC package:

    -
      -
    • dbWriteTable(conn, "test", iris, overwrite=FALSE, append=TRUE): write the data in a data frame iris to the table test in the TDengine server. Parameter overwrite must be false. append must be TRUE and the schema of the data frame iris should be the same as the table test.
      • -
    • dbGetQuery(conn, "select count(*) from test"): run a query command
      • -
    • dbSendUpdate(conn, "use db"): run any non-query command.
      • -
    • dbReadTable(conn, "test"): read all the data in table test
      • -
    • dbDisconnect(conn): close a connection
      • -
    • dbRemoveTable(conn, "test"): remove table test
      • -
    -

    Below functions are not supported currently:

    -
      -
    • dbExistsTable(conn, "test"): if talbe test exists
      • -
    • dbListTables(conn): list all tables in the connection
      • -
    Back
    \ No newline at end of file diff --git a/documentation/tdenginedocs-en/connector/index.html b/documentation/tdenginedocs-en/connector/index.html deleted file mode 100644 index ea1f75ae00300a84560b93156853152ac8f77398..0000000000000000000000000000000000000000 --- a/documentation/tdenginedocs-en/connector/index.html +++ /dev/null @@ -1,354 +0,0 @@ -Documentation | Taos Data
    Back

    TDengine connectors

    -

    TDengine provides many connectors for development, including C/C++, JAVA, Python, RESTful, Go, Node.JS, etc.

    -

    C/C++ API

    -

    C/C++ APIs are similar to the MySQL APIs. Applications should include TDengine head file taos.h to use C/C++ APIs by adding the following line in code:

    -
    #include <taos.h>
    -

    Make sure TDengine library libtaos.so is installed and use -ltaos option to link the library when compiling. The return values of all APIs are -1 or NULL for failure.

    -

    C/C++ sync API

    -

    Sync APIs are those APIs waiting for responses from the server after sending a request. TDengine has the following sync APIs:

    -
      -

    • TAOS *taos_connect(char *ip, char *user, char *pass, char *db, int port)

      -

      Open a connection to a TDengine server. The parameters are ip (IP address of the server), user (username to login), pass (password to login), db (database to use after connection) and port (port number to connect). The parameter db can be NULL for no database to use after connection. Otherwise, the database should exist before connection or a connection error is reported. The handle returned by this API should be kept for future use.

      • -

    • void taos_close(TAOS *taos)

      -

      Close a connection to a TDengine server by the handle returned by taos_connect`

      • -

    • int taos_query(TAOS *taos, char *sqlstr)

      -

      The API used to run a SQL command. The command can be DQL or DML. The parameter taos is the handle returned by taos_connect. Return value -1 means failure.

      • -

    • TAOS_RES *taos_use_result(TAOS *taos)

      -

      Use the result after running taos_query. The handle returned should be kept for future fetch.

      • -

    • TAOS_ROW taos_fetch_row(TAOS_RES *res)

      -

      Fetch a row of return results through res, the handle returned by taos_use_result.

      • -

    • int taos_num_fields(TAOS_RES *res)

      -

      Get the number of fields in the return result.

      • -

    • TAOS_FIELD *taos_fetch_fields(TAOS_RES *res)

      -

      Fetch the description of each field. The description includes the property of data type, field name, and bytes. The API should be used with taos_num_fields to fetch a row of data.

      • -

    • void taos_free_result(TAOS_RES *res)

      -

      Free the resources used by a result set. Make sure to call this API after fetching results or memory leak would happen.

      • -

    • void taos_init()

      -

      Initialize the environment variable used by TDengine client. The API is not necessary since it is called int taos_connect by default.

      • -

    • char *taos_errstr(TAOS *taos)

      -

      Return the reason of the last API call failure. The return value is a string.

      • -

    • int *taos_errno(TAOS *taos)

      -

      Return the error code of the last API call failure. The return value is an integer.

      • -

    • int taos_options(TSDB_OPTION option, const void * arg, ...)

      -

      Set client options. The parameter option supports values of TSDB_OPTION_CONFIGDIR (configuration directory), TSDB_OPTION_SHELL_ACTIVITY_TIMER, TSDB_OPTION_LOCALE (client locale) and TSDB_OPTION_TIMEZONE (client timezone).

      • -
    -

    The 12 APIs are the most important APIs frequently used. Users can check taos.h file for more API information.

    -

    Note: The connection to a TDengine server is not multi-thread safe. So a connection can only be used by one thread.

    -

    C/C++ async API

    -

    In addition to sync APIs, TDengine also provides async APIs, which are more efficient. Async APIs are returned right away without waiting for a response from the server, allowing the application to continute with other tasks without blocking. So async APIs are more efficient, especially useful when in a poor network.

    -

    All async APIs require callback functions. The callback functions have the format:

    -
    void fp(void *param, TAOS_RES * res, TYPE param3)
    -

    The first two parameters of the callback function are the same for all async APIs. The third parameter is different for different APIs. Generally, the first parameter is the handle provided to the API for action. The second parameter is a result handle.

    -
      -

    • void taos_query_a(TAOS *taos, char *sqlstr, void (*fp)(void *param, TAOS_RES *, int code), void *param);

      -

      The async query interface. taos is the handle returned by taos_connect interface. sqlstr is the SQL command to run. fp is the callback function. param is the parameter required by the callback function. The third parameter of the callback function code is 0 (for success) or a negative number (for failure, call taos_errstr to get the error as a string). Applications mainly handle with the second parameter, the returned result set.

      • -

    • void taos_fetch_rows_a(TAOS_RES *res, void (*fp)(void *param, TAOS_RES *, int numOfRows), void *param);

      -

      The async API to fetch a batch of rows, which should only be used with a taos_query_a call. The parameter res is the result handle returned by taos_query_a. fp is the callback function. param is a user-defined structure to pass to fp. The parameter numOfRows is the number of result rows in the current fetch cycle. In the callback function, applications should call taos_fetch_row to get records from the result handle. After getting a batch of results, applications should continue to call taos_fetch_rows_a API to handle the next batch, until the numOfRows is 0 (for no more data to fetch) or -1 (for failure).

      • -

    • void taos_fetch_row_a(TAOS_RES *res, void (*fp)(void *param, TAOS_RES *, TAOS_ROW row), void *param);

      -

      The async API to fetch a result row. res is the result handle. fp is the callback function. param is a user-defined structure to pass to fp. The third parameter of the callback function is a single result row, which is different from that of taos_fetch_rows_a API. With this API, it is not necessary to call taos_fetch_row to retrieve each result row, which is handier than taos_fetch_rows_a but less efficient.

      • -
    -

    Applications may apply operations on multiple tables. However, it is important to make sure the operations on the same table are serialized. That means after sending an insert request in a table to the server, no operations on the table are allowed before a response is received.

    -

    C/C++ continuous query interface

    -

    TDengine provides APIs for continuous query driven by time, which run queries periodically in the background. There are only two APIs:

    -
      -

    • TAOS_STREAM *taos_open_stream(TAOS *taos, char *sqlstr, void (*fp)(void *param, TAOS_RES *, TAOS_ROW row), int64_t stime, void *param, void (*callback)(void *));

      -

      The API is used to create a continuous query.

      • -

    • taos: the connection handle returned by taos_connect.

      • -

    • sqlstr: the SQL string to run. Only query commands are allowed.

      • -

    • fp: the callback function to run after a query

      • -

    • param: a parameter passed to fp

      • -

    • stime: the time of the stream starts in the form of epoch milliseconds. If 0 is given, the start time is set as the current time.

      • -

    • callback: a callback function to run when the continuous query stops automatically.

      -

      The API is expected to return a handle for success. Otherwise, a NULL pointer is returned.

      • -

    • void taos_close_stream (TAOS_STREAM *tstr)

      -

      Close the continuous query by the handle returned by taos_open_stream. Make sure to call this API when the continuous query is not needed anymore.

      • -
    -

    C/C++ subscription API

    -

    For the time being, TDengine supports subscription on one table. It is implemented through periodic pulling from a TDengine server.

    -
      -

    • TAOS_SUB *taos_subscribe(char *host, char *user, char *pass, char *db, char *table, long time, int mseconds) -The API is used to start a subscription session by given a handle. The parameters required are host (IP address of a TDenginer server), user (username), pass (password), db (database to use), table (table name to subscribe), time (start time to subscribe, 0 for now), mseconds (pulling period). If failed to open a subscription session, a NULL pointer is returned.

      • -

    • TAOS_ROW taos_consume(TAOS_SUB *tsub) -The API used to get the new data from a TDengine server. It should be put in an infinite loop. The parameter tsub is the handle returned by taos_subscribe. If new data are updated, the API will return a row of the result. Otherwise, the API is blocked until new data arrives. If NULL pointer is returned, it means an error occurs.

      • -

    • void taos_unsubscribe(TAOS_SUB *tsub) -Stop a subscription session by the handle returned by taos_subscribe.

      • -

    • int taos_num_fields(TAOS_SUB *tsub) -The API used to get the number of fields in a row.

      • -

    • TAOS_FIELD *taos_fetch_fields(TAOS_RES *res) -The API used to get the description of each column.

      • -
    -

    Java Connector

    -

    JDBC Interface

    -

    TDengine provides a JDBC driver taos-jdbcdriver-x.x.x.jar for Enterprise Java developers. TDengine's JDBC Driver is implemented as a subset of the standard JDBC 3.0 Specification and supports the most common Java development frameworks. The driver is currently not published to the online dependency repositories such as Maven Center Repository, and users should manually add the .jar file to their local dependency repository.

    -

    Please note the JDBC driver itself relies on a native library written in C. On a Linux OS, the driver relies on a libtaos.so native library, where .so stands for "Shared Object". After the successful installation of TDengine on Linux, libtaos.so should be automatically copied to /usr/local/lib/taos and added to the system's default search path. On a Windows OS, the driver relies on a taos.dll native library, where .dll stands for "Dynamic Link Library". After the successful installation of the TDengine client on Windows, the taos-jdbcdriver.jar file can be found in C:/TDengine/driver/JDBC; the taos.dll file can be found in C:/TDengine/driver/C and should have been automatically copied to the system's searching path C:/Windows/System32.

    -

    Developers can refer to the Oracle's official JDBC API documentation for detailed usage on classes and methods. However, there are some differences of connection configurations and supported methods in the driver implementation between TDengine and traditional relational databases.

    -

    For database connections, TDengine's JDBC driver has the following configurable parameters in the JDBC URL. The standard format of a TDengine JDBC URL is:

    -

    jdbc:TSDB://{host_ip}:{port}/{database_name}?[user={user}|&password={password}|&charset={charset}|&cfgdir={config_dir}|&locale={locale}|&timezone={timezone}]

    -

    where {} marks the required parameters and [] marks the optional. The usage of each parameter is pretty straightforward:

    -
      -
    • user - login user name for TDengine; by default, it's root
      • -
    • password - login password; by default, it's taosdata
      • -
    • charset - the client-side charset; by default, it's the operation system's charset
      • -
    • cfgdir - the directory of TDengine client configuration file; by default it's /etc/taos on Linux and C:\TDengine/cfg on Windows
      • -
    • locale - the language environment of TDengine client; by default, it's the operation system's locale
      • -
    • timezone - the timezone of the TDengine client; by default, it's the operation system's timezone
      • -
    -

    All parameters can be configured at the time when creating a connection using the java.sql.DriverManager class, for example:

    -
    import java.sql.Connection;
-import java.sql.DriverManager;
-import java.util.Properties;
-import com.taosdata.jdbc.TSDBDriver;
-
-public Connection getConn() throws Exception{
-    Class.forName("com.taosdata.jdbc.TSDBDriver");
-  String jdbcUrl = "jdbc:TAOS://127.0.0.1:0/db?user=root&password=taosdata";
-  Properties connProps = new Properties();
-  connProps.setProperty(TSDBDriver.PROPERTY_KEY_USER, "root");
-  connProps.setProperty(TSDBDriver.PROPERTY_KEY_PASSWORD, "taosdata");
-  connProps.setProperty(TSDBDriver.PROPERTY_KEY_CONFIG_DIR, "/etc/taos");
-  connProps.setProperty(TSDBDriver.PROPERTY_KEY_CHARSET, "UTF-8");
-  connProps.setProperty(TSDBDriver.PROPERTY_KEY_LOCALE, "en_US.UTF-8");
-  connProps.setProperty(TSDBDriver.PROPERTY_KEY_TIMEZONE, "UTC-8");
-  Connection conn = DriverManager.getConnection(jdbcUrl, connProps);
-  return conn;
-}
    -

    Except cfgdir, all the parameters listed above can also be configured in the configuration file. The properties specified when calling DriverManager.getConnection() has the highest priority among all configuration methods. The JDBC URL has the second-highest priority, and the configuration file has the lowest priority. The explicitly configured parameters in a method with higher priorities always overwrite that same parameter configured in methods with lower priorities. For example, if charset is explicitly configured as "UTF-8" in the JDBC URL and "GKB" in the taos.cfg file, then "UTF-8" will be used.

    -

    Although the JDBC driver is implemented following the JDBC standard as much as possible, there are major differences between TDengine and traditional databases in terms of data models that lead to the differences in the driver implementation. Here is a list of head-ups for developers who have plenty of experience on traditional databases but little on TDengine:

    -
      -
    • TDengine does NOT support updating or deleting a specific record, which leads to some unsupported methods in the JDBC driver
      • -
    • TDengine currently does not support join or union operations, and thus, is lack of support for associated methods in the JDBC driver
      • -
    • TDengine supports batch insertions which are controlled at the level of SQL statement writing instead of API calls
      • -
    • TDengine doesn't support nested queries and neither does the JDBC driver. Thus for each established connection to TDengine, there should be only one open result set associated with it
      • -
    -

    All the error codes and error messages can be found in TSDBError.java . For a more detailed coding example, please refer to the demo project JDBCDemo in TDengine's code examples.

    -

    Python Connector

    -

    Pre-requirement

    -
  • TDengine installed, TDengine-client installed if on Windows
    • -
  • python 2.7 or >= 3.4
    • -
  • pip installed
    • -

    Installation

    -

    Linux

    -

    Users can find python client packages in our source code directory src/connector/python. There are two directories corresponding to two python versions. Please choose the correct package to install. Users can use pip command to install:

    -
    pip install src/connector/python/linux/python2/
    -

    or

    -
    pip install src/connector/python/linux/python3/
    -

    Windows

    -

    Assumed the Windows TDengine client has been installed , copy the file "C:\TDengine\driver\taos.dll" to the folder "C:\windows\system32", and then enter the cmd Windows command interface

    -
    cd C:\TDengine\connector\python\windows
    -
    pip install python2\
    -

    or

    -
    cd C:\TDengine\connector\python\windows
    -
    pip install python3\
    -

    * If pip command is not installed on the system, users can choose to install pip or just copy the taos directory in the python client directory to the application directory to use.

    -

    Usage

    -

    Examples

    -
  • import TDengine module at first:
    • -
    import taos
    -
  • get the connection
    • -
    
-conn = taos.connect(host="127.0.0.1", user="root", password="taosdata", config="/etc/taos")
-c1 = conn.cursor()
-
    -

    * host is the IP of TDengine server, and config is the directory where exists the TDengine client configure file

    -
  • insert records into the database
    • -
    
-import datetime
- 
-# create a database
-c1.execute('create database db')
-c1.execute('use db')
-# create a table
-c1.execute('create table tb (ts timestamp, temperature int, humidity float)')
-# insert a record
-start_time = datetime.datetime(2019, 11, 1)
-affected_rows = c1.execute('insert into tb values (\'%s\', 0, 0.0)' %start_time)
-# insert multiple records in a batch
-time_interval = datetime.timedelta(seconds=60)
-sqlcmd = ['insert into tb values']
-for irow in range(1,11):
-  start_time += time_interval
-  sqlcmd.append('(\'%s\', %d, %f)' %(start_time, irow, irow*1.2))
-affected_rows = c1.execute(' '.join(sqlcmd))
-
    -
  • query the database
    • -
    -c1.execute('select * from tb')
-# fetch all returned results
-data = c1.fetchall()
-# data is a list of returned rows with each row being a tuple
-numOfRows = c1.rowcount
-numOfCols = c1.descriptions
-for irow in range(numOfRows):
-  print("Row%d: ts=%s, temperature=%d, humidity=%f" %(irow, data[irow][0], data[irow][1],data[irow][2])
-  
-# use the cursor as an iterator to retrieve all returned results
-c1.execute('select * from tb')
-for data in c1:
-  print("ts=%s, temperature=%d, humidity=%f" %(data[0], data[1],data[2])
-
     -
  • close the connection
    • -
    -c1.close()
-conn.close()
-
     -

    Help information

    -

    Users can get module information from Python help interface or refer to our [python code example](). We list the main classes and methods below:

    -
      -

    • TaosConnection class

      -

      Run help(taos.TaosConnection) in python terminal for details.

      • -

    • TaosCursor class

      -

      Run help(taos.TaosCursor) in python terminal for details.

      • -

    • connect method

      -

      Open a connection. Run help(taos.connect) in python terminal for details.

      • -
    -

    RESTful Connector

    -

    TDengine also provides RESTful API to satisfy developing on different platforms. Unlike other databases, TDengine RESTful API applies operations to the database through the SQL command in the body of HTTP POST request. What users are required to provide is just a URL.

    -

    For the time being, TDengine RESTful API uses a \ generated from username and password for identification. Safer identification methods will be provided in the future.

    -

    HTTP URL encoding

    -

    To use TDengine RESTful API, the URL should have the following encoding format:

    -
    http://<ip>:<PORT>/rest/sql
    -
      -
    • ip: IP address of any node in a TDengine cluster
      • -
    • PORT: TDengine HTTP service port. It is 6020 by default.
      • -
    -

    For example, the URL encoding http://192.168.0.1:6020/rest/sql used to send HTTP request to a TDengine server with IP address as 192.168.0.1.

    -

    It is required to add a token in an HTTP request header for identification.

    -
    Authorization: Basic <TOKEN>
    -

    The HTTP request body contains the SQL command to run. If the SQL command contains a table name, it should also provide the database name it belongs to in the form of <db_name>.<tb_name>. Otherwise, an error code is returned.

    -

    For example, use curl command to send a HTTP request:

    -
    curl -H 'Authorization: Basic <TOKEN>' -d '<SQL>' <ip>:<PORT>/rest/sql
    -

    or use

    -
    curl -u username:password -d '<SQL>' <ip>:<PORT>/rest/sql
    -

    where TOKEN is the encryted string of {username}:{password} using the Base64 algorithm, e.g. root:taosdata will be encoded as cm9vdDp0YW9zZGF0YQ==

    -

    HTTP response

    -

    The HTTP resonse is in JSON format as below:

    -
    {
-    "status": "succ",
-    "head": ["column1","column2", …],
-    "data": [
-        ["2017-12-12 23:44:25.730", 1],
-        ["2017-12-12 22:44:25.728", 4]
-    ],
-    "rows": 2
-}
    -

    Specifically,

    -
      -
    • status: the result of the operation, success or failure
      • -
    • head: description of returned result columns
      • -
    • data: the returned data array. If no data is returned, only an affected_rows field is listed
      • -
    • rows: the number of rows returned
      • -
    -

    Example

    -
      -

    • Use curl command to query all the data in table t1 of database demo:

      -

      curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.t1' 192.168.0.1:6020/rest/sql

      • -
    -

    The return value is like:

    -
    {
-    "status": "succ",
-    "head": ["column1","column2","column3"],
-    "data": [
-        ["2017-12-12 23:44:25.730", 1, 2.3],
-        ["2017-12-12 22:44:25.728", 4, 5.6]
-    ],
-    "rows": 2
-}
    -
      -

    • Use HTTP to create a database：

      -

      curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'create database demo' 192.168.0.1:6020/rest/sql

      -

      The return value should be:

      • -
    -
    {
-    "status": "succ",
-    "head": ["affected_rows"],
-    "data": [[1]],
-    "rows": 1,
-}
    -

    Go Connector

    -

    TDengine also provides a Go client package named taosSql for users to access TDengine with Go. The package is in /usr/local/taos/connector/go/src/taosSql by default if you installed TDengine. Users can copy the directory /usr/local/taos/connector/go/src/taosSql to the src directory of your project and import the package in the source code for use.

    -
    import (
-    "database/sql"
-    _ "taosSql"
-)
    -

    The taosSql package is in cgo form, which calls TDengine C/C++ sync interfaces. So a connection is allowed to be used by one thread at the same time. Users can open multiple connections for multi-thread operations.

    -

    Please refer the the demo code in the package for more information.

    -

    Node.js Connector

    -

    TDengine also provides a node.js connector package that is installable through npm. The package is also in our source code at src/connector/nodejs/. The following instructions are also available here

    -

    To get started, just type in the following to install the connector through npm.

    -
    npm install td-connector
    -

    It is highly suggested you use npm. If you don't have it installed, you can also just copy the nodejs folder from src/connector/nodejs/ into your node project folder.

    -

    To interact with TDengine, we make use of the node-gyp library. To install, you will need to install the following depending on platform (the following instructions are quoted from node-gyp)

    -

    On Unix

    -
      -
    • python (v2.7 recommended, v3.x.x is not supported)
      • -
    • make
      • -
    • A proper C/C++ compiler toolchain, like GCC
      • -
    -

    On macOS

    -
      -

    • python (v2.7 recommended, v3.x.x is not supported) (already installed on macOS)

      • -

    • Xcode

      • -

    • You also need to install the

      -
      Command Line Tools
      -

      via Xcode. You can find this under the menu

      -
      Xcode -> Preferences -> Locations
      -

      (or by running

      -
      xcode-select --install
      -

      in your Terminal)

      -
        -
      • This step will install gcc and the related toolchain containing make
      • -
    -

    On Windows

    -

    Option 1

    -

    Install all the required tools and configurations using Microsoft's windows-build-tools using npm install --global --production windows-build-tools from an elevated PowerShell or CMD.exe (run as Administrator).

    -

    Option 2

    -

    Install tools and configuration manually:

    -
      -
    • Install Visual C++ Build Environment: Visual Studio Build Tools (using "Visual C++ build tools" workload) or Visual Studio 2017 Community (using the "Desktop development with C++" workload)
      • -
    • Install Python 2.7 (v3.x.x is not supported), and run npm config set python python2.7 (or see below for further instructions on specifying the proper Python version and path.)
      • -
    • Launch cmd, npm config set msvs_version 2017
      • -
    -

    If the above steps didn't work for you, please visit Microsoft's Node.js Guidelines for Windows for additional tips.

    -

    To target native ARM64 Node.js on Windows 10 on ARM, add the components "Visual C++ compilers and libraries for ARM64" and "Visual C++ ATL for ARM64".

    -

    Usage

    -

    The following is a short summary of the basic usage of the connector, the full api and documentation can be found here

    -

    Connection

    -

    To use the connector, first require the library td-connector. Running the function taos.connect with the connection options passed in as an object will return a TDengine connection object. The required connection option is host, other options if not set, will be the default values as shown below.

    -

    A cursor also needs to be initialized in order to interact with TDengine from Node.js.

    -
    const taos = require('td-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
    -

    To close a connection, run

    -
    conn.close();
    -

    Queries

    -

    We can now start executing simple queries through the cursor.query function, which returns a TaosQuery object.

    -
    var query = cursor.query('show databases;')
    -

    We can get the results of the queries through the query.execute() function, which returns a promise that resolves with a TaosResult object, which contains the raw data and additional functionalities such as pretty printing the results.

    -
    var promise = query.execute();
-promise.then(function(result) {
-  result.pretty(); //logs the results to the console as if you were in the taos shell
-});
    -

    You can also query by binding parameters to a query by filling in the question marks in a string as so. The query will automatically parse what was binded and convert it to the proper format for use with TDengine

    -
    var query = cursor.query('select * from meterinfo.meters where ts <= ? and areaid = ?;').bind(new Date(), 5);
-query.execute().then(function(result) {
-  result.pretty();
-})
    -

    The TaosQuery object can also be immediately executed upon creation by passing true as the second argument, returning a promise instead of a TaosQuery.

    -
    var promise = cursor.query('select * from meterinfo.meters where v1 = 30;', true)
-promise.then(function(result) {
-  result.pretty();
-})
    -

    Async functionality

    -

    Async queries can be performed using the same functions such as cursor.execute, cursor.query, but now with _a appended to them.

    -

    Say you want to execute an two async query on two seperate tables, using cursor.query_a, you can do that and get a TaosQuery object, which upon executing with the execute_a function, returns a promise that resolves with a TaosResult object.

    -
    var promise1 = cursor.query_a('select count(*), avg(v1), avg(v2) from meter1;').execute_a()
-var promise2 = cursor.query_a('select count(*), avg(v1), avg(v2) from meter2;').execute_a();
-promise1.then(function(result) {
-  result.pretty();
-})
-promise2.then(function(result) {
-  result.pretty();
-})
    -

    Example

    -

    An example of using the NodeJS connector to create a table with weather data and create and execute queries can be found here (The preferred method for using the connector)

    -

    An example of using the NodeJS connector to achieve the same things but without all the object wrappers that wrap around the data returned to achieve higher functionality can be found here

    Back
    diff --git a/documentation/tdenginedocs-en/contributor_license_agreement/index.html b/documentation/tdenginedocs-en/contributor_license_agreement/index.html deleted file mode 100644 index a012993efef2539843d2f26cf91e5d805aa66490..0000000000000000000000000000000000000000 --- a/documentation/tdenginedocs-en/contributor_license_agreement/index.html +++ /dev/null @@ -1,20 +0,0 @@ -Documentation | Taos Data
    Back

    TaosData Contributor License Agreement

    -

    This TaosData Contributor License Agreement (CLA) applies to any contribution you make to any TaosData projects. If you are representing your employing organization to sign this agreement, please warrant that you have the authority to grant the agreement.

    -

    Terms

    -

    "TaosData", "we", "our" and "us" means TaosData, inc.

    -

    "You" and "your" means you or the organization you are on behalf of to sign this agreement.

    -

    "Contribution" means any original work you, or the organization you represent submit to TaosData for any project in any manner.

    -

    Copyright License

    -

    All rights of your Contribution submitted to TaosData in any manner are granted to TaosData and recipients of software distributed by TaosData. You waive any rights that my affect our ownership of the copyright and grant to us a perpetual, worldwide, transferable, non-exclusive, no-charge, royalty-free, irrevocable, and sublicensable license to use, reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute Contributions and any derivative work created based on a Contribution.

    -

    Patent License

    -

    With respect to any patents you own or that you can license without payment to any third party, you grant to us and to any recipient of software distributed by us, a perpetual, worldwide, transferable, non-exclusive, no-charge, royalty-free, irrevocable patent license to make, have make, use, sell, offer to sell, import, and otherwise transfer the Contribution in whole or in part, alone or included in any product under any patent you own, or license from a third party, that is necessarily infringed by the Contribution or by combination of the Contribution with any Work.

    -

    Your Representations and Warranties

    -

    You represent and warrant that:

    -
      -

    • the Contribution you submit is an original work that you can legally grant the rights set out in this agreement.

      • -

    • the Contribution you submit and licenses you granted does not and will not, infringe the rights of any third party.

      • -

    • you are not aware of any pending or threatened claims, suits, actions, or charges pertaining to the contributions. You also warrant to notify TaosData immediately if you become aware of any such actual or potential claims, suits, actions, allegations or charges.

      • -
    -

    Support

    -

    You are not obligated to support your Contribution except you volunteer to provide support. If you want, you can provide for a fee.

    -

    I agree and accept on behalf of myself and behalf of my organization:

    Back
    \ No newline at end of file diff --git a/documentation/tdenginedocs-en/data-model-and-architecture/index.html b/documentation/tdenginedocs-en/data-model-and-architecture/index.html deleted file mode 100644 index 4ee5a553f582187da7adf90aa1b8722dc69de92f..0000000000000000000000000000000000000000 --- a/documentation/tdenginedocs-en/data-model-and-architecture/index.html +++ /dev/null @@ -1,129 +0,0 @@ -Documentation | Taos Data
    Back

    Data Model and Architecture

    -

    Data Model

    -

    A Typical IoT Scenario

    -

    In a typical IoT scenario, there are many types of devices. Each device is collecting one or multiple metrics. For a specific type of device, the collected data looks like the table below:

    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Device IDTime StampValue 1Value 2Value 3Tag 1Tag 2
    D1001153854868500010.32190.31RedTesla
    D1002153854868400010.22200.23BlueBMW
    D1003153854868650011.52210.35BlackHonda
    D1004153854868550013.42230.29RedVolvo
    D1001153854869500012.62180.33RedTesla
    D1004153854869660011.82210.28BlackHonda
    -

    Each data record has device ID, timestamp, the collected metrics, and static tags associated with the device. Each device generates a data record in a pre-defined timer or triggered by an event. It is a sequence of data points, like a stream.

    -

    Data Characteristics

    -

    Being a series of data points over time, data points generated by devices, sensors, servers, or applications have strong common characteristics.

    -
      -
    1. metric is always structured data;
      2. -
    2. there are rarely delete/update operations on collected data;
      3. -
    3. there is only one single data source for one device or sensor;
      4. -
    4. ratio of read/write is much lower than typical Internet application;
      5. -
    5. the user pays attention to the trend of data, not the specific value at a specific time;
      6. -
    6. there is always a data retention policy;
      7. -
    7. the data query is always executed in a given time range and a subset of devices;
      8. -
    8. real-time aggregation or analytics is mandatory;
      9. -
    9. traffic is predictable based on the number of devices and sampling frequency;
      10. -
    10. data volume is huge, a system may generate 10 billion data points in a day.
      11. -
    -

    By utilizing the above characteristics, TDengine designs the storage and computing engine in a special and optimized way for time-series data. The system efficiency is improved significantly.

    -

    Relational Database Model

    -

    Since time-series data is more likely to be structured data, TDengine adopts the traditional relational database model to process them. You need to create a database, create tables with schema definition, then insert data points and execute queries to explore the data. Standard SQL is used, there is no learning curve.

    -

    One Table for One Device

    -

    Due to different network latency, the data points from different devices may arrive at the server out of order. But for the same device, data points will arrive at the server in order if system is designed well. To utilize this special feature, TDengine requires the user to create a table for each device (time-stream). For example, if there are over 10,000 smart meters, 10,000 tables shall be created. For the table above, 4 tables shall be created for device D1001, D1002, D1003 and D1004, to store the data collected.

    -

    This strong requirement can guarantee the data points from a device can be saved in a continuous memory/hard disk space block by block. If queries are applied only on one device in a time range, this design will reduce the read latency significantly since a whole block is owned by one single device. Also, write latency can be significantly reduced too, since the data points generated by the same device will arrive in order, the new data point will be simply appended to a block. Cache block size and the rows of records in a file block can be configured to fit the scenarios.

    -

    Best Practices

    -

    Table: TDengine suggests to use device ID as the table name (like D1001 in the above diagram). Each device may collect one or more metrics (like value1, valu2, valu3 in the diagram). Each metric has a column in the table, the metric name can be used as the column name. The data type for a column can be int, float, double, tinyint, bigint, bool or binary. Sometimes, a device may have multiple metric group, each group have different sampling period, you shall create a table for each group for each device. The first column in the table must be time stamp. TDengine uses time stamp as the index, and won’t build the index on any metrics stored.

    -

    Tags: to support aggregation over multiple tables efficiently, STable(Super Table) concept is introduced by TDengine. A STable is used to represent the same type of device. The schema is used to define the collected metrics(like value1, value2, value3 in the diagram), and tags are used to define the static attributes for each table or device(like tag1, tag2 in the diagram). A table is created via STable with a specific tag value. All or a subset of tables in a STable can be aggregated by filtering tag values.

    -

    Database: different types of devices may generate data points in different patterns and shall be processed differently. For example, sampling frequency, data retention policy, replication number, cache size, record size, the compression algorithm may be different. To make the system more efficient, TDengine suggests creating a different database with unique configurations for different scenarios

    -

    Schemaless vs Schema: compared with NoSQL database, since a table with schema definition shall be created before the data points can be inserted, flexibilities are not that good, especially when the schema is changed. But in most IoT scenarios, the schema is well defined and is rarely changed, the loss of flexibilities won’t be a big pain to developers or the administrator. TDengine allows the application to change the schema in a second even there is a huge amount of historical data when schema has to be changed.

    -

    TDengine does not impose a limitation on the number of tables, STables, or databases. You can create any number of STable or databases to fit the scenarios.

    -

    Architecture

    -

    There are two main modules in TDengine server as shown in Picture 1: Management Module (MGMT) and Data Module(DNODE). The whole TDengine architecture also includes a TDengine Client Module.

    -

    -
    Picture 1 TDengine Architecture

    -

    MGMT Module

    -

    The MGMT module deals with the storage and querying on metadata, which includes information about users, databases, and tables. Applications will connect to the MGMT module at first when connecting the TDengine server. When creating/dropping databases/tables, The request is sent to the MGMT module at first to create/delete metadata. Then the MGMT module will send requests to the data module to allocate/free resources required. In the case of writing or querying, applications still need to visit MGMT module to get meta data, according to which, then access the DNODE module.

    -

    DNODE Module

    -

    The DNODE module is responsible for storing and querying data. For the sake of future scaling and high-efficient resource usage, TDengine applies virtualization on resources it uses. TDengine introduces the concept of virtual node (vnode), which is the unit of storage, resource allocation and data replication (enterprise edition). As is shown in Picture 2, TDengine treats each data node as an aggregation of vnodes.

    -

    When a DB is created, the system will allocate a vnode. Each vnode contains multiple tables, but a table belongs to only one vnode. Each DB has one or mode vnodes, but one vnode belongs to only one DB. Each vnode contains all the data in a set of tables. Vnodes have their own cache, directory to store data. Resources between different vnodes are exclusive with each other, no matter cache or file directory. However, resources in the same vnode are shared between all the tables in it. By virtualization, TDengine can distribute resources reasonably to each vnode and improve resource usage and concurrency. The number of vnodes on a dnode is configurable according to its hardware resources.

    -

    -
    Picture 2 TDengine Virtualization

    -

    Client Module

    -

    TDengine client module accepts requests (mainly in SQL form) from applications and converts the requests to internal representations and sends to the server side. TDengine supports multiple interfaces, which are all built on top of TDengine client module.

    -

    For the communication between client and MGMT module, TCP/UDP is used, the port is set by the parameter mgmtShellPort in system configuration file taos.cfg, default is 6030. For the communication between client and DNODE module, TCP/UDP is used, the port is set by the parameter vnodeShellPort in the system configuration file, default is 6035.

    -

    Writing Process

    -

    Picture 3 shows the full writing process of TDengine. TDengine uses Writing Ahead Log strategy to assure data security and integrity. Data received from the client is written to the commit log at first. When TDengine recovers from crashes caused by power lose or other situations, the commit log is used to recover data. After writting to commit log, data will be wrtten to the corresponding vnode cache, then an acknowledgment is sent to the application. There are two mechanisms that can flush data in cache to disk for persistent storage:

    -
      -
    1. Flush driven by timer: There is a backend timer which flushes data in cache periodically to disks. The period is configurable via parameter commitTime in system configuration file taos.cfg.
      2. -
    2. Flush driven by data: Data in the cache is also flushed to disks when the left buffer size is below a threshold. Flush driven by data can reset the timer of flush driven by the timer.
      3. -
    -

    -
    Picture 3 TDengine Writting Process

    -

    New commit log file will be opened when the committing process begins. When the committing process finishes, the old commit file will be removed.

    -

    Data Storage

    -

    TDengine data are saved in /var/lib/taos directory by default. It can be changed to other directories by setting the parameter dataDir in system configuration file taos.cfg.

    -

    TDengine's metadata includes the database, table, user, super table and tag information. To reduce the latency, metadata are all buffered in the cache.

    -

    Data records saved in tables are sharded according to the time range. Data of tables in the same vnode in a certain time range are saved in the same file group. This sharding strategy can effectively improve data searching speed. By default, one group of files contain data in 10 days, which can be configured by daysPerFile in the configuration file or by DAYS keyword in CREATE DATABASE clause.

    -

    Data records are removed automatically once their lifetime is passed. The lifetime is configurable via parameter daysToKeep in the system configuration file. The default value is 3650 days.

    -

    Data in files are blockwise. A data block only contains one table's data. Records in the same data block are sorted according to the primary timestamp. To improve the compression ratio, records are stored column by column, and the different compression algorithm is applied based on each column's data type.

    Back
    \ No newline at end of file diff --git a/documentation/tdenginedocs-en/faq/index.html b/documentation/tdenginedocs-en/faq/index.html deleted file mode 100644 index 2d716cd6dc1b4bc233dbe3a680fa17286f651c91..0000000000000000000000000000000000000000 --- a/documentation/tdenginedocs-en/faq/index.html +++ /dev/null @@ -1,27 +0,0 @@ -Documentation | Taos Data
    Back

    FAQ

    -

    1. When encountered with the error "failed to connect to server", what can I do?

    -

    The client may encounter connection errors. Please follow the steps below for troubleshooting:

    -
      -
    1. On the server side, execute systemctl status taosd to check the status of taosd service. If taosd is not running, start it and retry connecting.
      2. -
    2. Make sure you have used the correct server IP address to connect to.
      3. -
    3. Ping the server. If no response is received, check your network connection.
      4. -
    4. Check the firewall setting, make sure the TCP/UDP ports from 6030-6039 are enabled.
      5. -
    5. For JDBC, ODBC, Python, Go connections on Linux, make sure the native library libtaos.so are located at /usr/local/lib/taos, and /usr/local/lib/taos is in the LD_LIBRARY_PATH.
      6. -
    6. For JDBC, ODBC, Python, Go connections on Windows, make sure driver/c/taos.dll is in the system search path (or you can copy taos.dll into C:\Windows\System32)
      7. -
    7. If the above steps can not help, try the network diagnostic tool nc to check if TCP/UDP port works - check UDP port：nc -vuz {hostIP} {port} - check TCP port on server: nc -l {port} - check TCP port on client: nc {hostIP} {port}
      8. -
    -

    2. Why I get "Invalid SQL" error when a query is syntactically correct?

    -

    If you are sure your query has correct syntax, please check the length of the SQL string, it shall be less than 64KB.

    -

    3. Why I could not delete a super table?

    -

    Please make sure there are no tables under the super table. You could not delete a super table which still has associated tables.

    -

    4. Does TDengine support validation queries?

    -

    For the time being, TDengine does not have a specific set of validation queries. However, TDengine comes with a system monitoring database named 'sys', which can usually be used as a validation query object.

    -

    5. Can I delete or update a record that has been written into TDengine?

    -

    The answer is NO. The design of TDengine is based on the assumption that records are generated by the connected devices, you won't be allowed to change it. But TDengine provides a retention policy, the data records will be removed once their lifetime is passed.

    -

    6. How do I create a table with more than 250 columns?

    -

    For a single table, the maximum number of columns is 250. If for some reason, 250 columns are still not quite enough, our suggestion is to split the huge table into several smaller ones.

    -

    7. What is the most efficient way to write data to TDengine?

    -

    TDengine supports several different writing regimes. The most efficient way to write data to TDengine is to use batch inserting. For details on batch insertion syntax, please refer to Taos SQL

    Back
    \ No newline at end of file diff --git a/documentation/tdenginedocs-en/getting-started/index.html b/documentation/tdenginedocs-en/getting-started/index.html deleted file mode 100644 index 8968441b55664cd4f76dc4493c94bc95eb3eaa4d..0000000000000000000000000000000000000000 --- a/documentation/tdenginedocs-en/getting-started/index.html +++ /dev/null @@ -1,88 +0,0 @@ -Documentation | Taos Data
    Back

    Getting Started

    -

    Quick Start

    -

    At the moment, TDengine only runs on Linux. You can set up and install it either from the source code or the packages. It takes only a few seconds from download to run it successfully.

    -

    Install from Source

    -

    Please visit our github page for instructions on installation from the source code.

    -

    Install from Package

    -

    Three different packages are provided, please pick up the one you like.

    - -

    For the time being, TDengine only supports installation on Linux systems using systemd as the service manager. To check if your system has systemd, use the which command.

    -
    which systemd
    -

    If the systemd command is not found, please install from source code.

    -

    Running TDengine

    -

    After installation, start the TDengine service by the systemctl command.

    -
    systemctl start taosd
    -

    Then check if the server is working now.

    -
    systemctl status taosd
    -

    If the service is running successfully, you can play around through TDengine shell taos, the command line interface tool located in directory /usr/local/bin/taos

    -

    Note: The systemctl command needs the root privilege. Use sudo if you are not the root user.

    -

    TDengine Shell

    -

    To launch TDengine shell, the command line interface, in a Linux terminal, type:

    -
    taos
    -

    The welcome message is printed if the shell connects to TDengine server successfully, otherwise, an error message will be printed (refer to our FAQ page for troubleshooting the connection error). The TDengine shell prompt is:

    -
    taos>
    -

    In the TDengine shell, you can create databases, create tables and insert/query data with SQL. Each query command ends with a semicolon. It works like MySQL, for example:

    -
    create database db;
-use db;
-create table t (ts timestamp, speed int);
-insert into t values ('2019-07-15 10:00:00', 10);
-insert into t values ('2019-07-15 10:01:05', 20);
-select * from t;
-          ts          |   speed   |
-===================================
- 19-07-15 10:00:00.000|         10|
- 19-07-15 10:01:05.000|         20|
-Query OK, 2 row(s) in set (0.001700s)
    -

    Besides the SQL commands, the system administrator can check system status, add or delete accounts, and manage the servers.

    -

    Shell Command Line Parameters

    -

    You can run taos command with command line options to fit your needs. Some frequently used options are listed below:

    -
      -
    • -c, --config-dir: set the configuration directory. It is /etc/taos by default
      • -
    • -h, --host: set the IP address of the server it will connect to, Default is localhost
      • -
    • -s, --commands: set the command to run without entering the shell
      • -
    • -u, -- user: user name to connect to server. Default is root
      • -
    • -p, --password: password. Default is 'taosdata'
      • -
    • -?, --help: get a full list of supported options
      • -
    -

    Examples:

    -
    taos -h 192.168.0.1 -s "use db; show tables;"
    -

    Run Batch Commands

    -

    Inside TDengine shell, you can run batch commands in a file with source command.

    -
    taos> source <filename>;
    -

    Tips

    -
      -
    • Use up/down arrow key to check the command history
      • -
    • To change the default password, use "alter user" command
      • -
    • ctrl+c to interrupt any queries
      • -
    • To clean the cached schema of tables or STables, execute command RESET QUERY CACHE
      • -
    -

    Major Features

    -

    The core functionality of TDengine is the time-series database. To reduce the development and management complexity, and to improve the system efficiency further, TDengine also provides caching, pub/sub messaging system, and stream computing functionalities. It provides a full stack for IoT big data platform. The detailed features are listed below:

    -
      -

    • SQL like query language used to insert or explore data

      • -

    • C/C++, Java(JDBC), Python, Go, RESTful, and Node.JS interfaces for development

      • -

    • Ad hoc queries/analysis via Python/R/Matlab or TDengine shell

      • -

    • Continuous queries to support sliding-window based stream computing

      • -

    • Super table to aggregate multiple time-streams efficiently with flexibility

      • -

    • Aggregation over a time window on one or multiple time-streams

      • -

    • Built-in messaging system to support publisher/subscriber model

      • -

    • Built-in cache for each time stream to make latest data available as fast as light speed

      • -

    • Transparent handling of historical data and real-time data

      • -

    • Integrating with Telegraf, Grafana and other tools seamlessly

      • -

    • A set of tools or configuration to manage TDengine

      • -
    -

    For enterprise edition, TDengine provides more advanced features below:

    -
      -

    • Linear scalability to deliver higher capacity/throughput

      • -

    • High availability to guarantee the carrier-grade service

      • -

    • Built-in replication between nodes which may span multiple geographical sites

      • -

    • Multi-tier storage to make historical data management simpler and cost-effective

      • -

    • Web-based management tools and other tools to make maintenance simpler

      • -
    -

    TDengine is specially designed and optimized for time-series data processing in IoT, connected cars, Industrial IoT, IT infrastructure and application monitoring, and other scenarios. Compared with other solutions, it is 10x faster on insert/query speed. With a single-core machine, over 20K requestes can be processed, millions data points can be ingested, and over 10 million data points can be retrieved in a second. Via column-based storage and tuned compression algorithm for different data types, less than 1/10 storage space is required.

    -

    Explore More on TDengine

    -

    Please read through the whole documentation to learn more about TDengine.

    Back
    diff --git a/documentation/tdenginedocs-en/index.html b/documentation/tdenginedocs-en/index.html deleted file mode 100644 index ebb728a0dfcc0faa972ae9620cf302ce2b76e580..0000000000000000000000000000000000000000 --- a/documentation/tdenginedocs-en/index.html +++ /dev/null @@ -1 +0,0 @@ -Documentation | Taos Data

    Documentation

    TDengine is a highly efficient platform to store, query, and analyze time-series data. It works like a relational database, but you are strongly suggested to read through the following documentation before you experience it.

    Getting Started

    • Quick Start: download, install and experience TDengine in a few seconds
    • TDengine Shell: command-line interface to access TDengine server
    • Major Features: insert/query, aggregation, cache, pub/sub, continuous query

    Data Model and Architecture

    • Data Model: relational database model, but one table for one device with static tags
    • Architecture: Management Module, Data Module, Client Module
    • Writing Process: records recieved are written to WAL, cache, then ack is sent back to client
    • Data Storage: records are sharded in the time range, and stored column by column

    TAOS SQL

    • Data Types: support timestamp, int, float, double, binary, nchar, bool, and other types
    • Database Management: add, drop, check databases
    • Table Management: add, drop, check, alter tables
    • Inserting Records: insert one or more records into tables, historical records can be imported
    • Data Query: query data with time range and filter conditions, support limit/offset
    • SQL Functions: support aggregation, selector, transformation functions
    • Downsampling: aggregate data in successive time windows, support interpolation

    Super Table

    Advanced Features

    • Continuous Query: query executed by TDengine periodically with a sliding window
    • Publisher/Subscriber: subscribe to the newly arrived data like a typical messaging system
    • Caching: the newly arrived data of each device/table will always be cached

    Connector

    • C/C++ Connector: primary method to connect to the server through libtaos client library
    • Java Connector: driver for connecting to the server from Java applications using the JDBC API
    • Python Connector: driver for connecting to the server from Python applications
    • RESTful Connector: a simple way to interact with TDengine via HTTP
    • Go Connector: driver for connecting to the server from Go applications
    • Node.js Connector: driver for connecting to the server from node applications

    Connections with Other Tools

    • Telegraf: pass the collected DevOps metrics to TDengine
    • Grafana: query the data saved in TDengine and visualize them
    • Matlab: access TDengine server from Matlab via JDBC
    • R: access TDengine server from R via JDBC

    Administrator

    More on System Architecture

    Tutorials & FAQ

    • FAQ: a list of frequently asked questions and answers
    • Use cases: a few typical cases to explain how to use TDengine in IoT platform
    Back
    \ No newline at end of file diff --git a/documentation/tdenginedocs-en/lib/bootstrap.min.css b/documentation/tdenginedocs-en/lib/bootstrap.min.css deleted file mode 100644 index 882691283ab5b356f9643f8507666d71f3372ca1..0000000000000000000000000000000000000000 --- a/documentation/tdenginedocs-en/lib/bootstrap.min.css +++ /dev/null @@ -1,7 +0,0 @@ -/*! - * Bootstrap v4.1.3 (https://getbootstrap.com/) - * Copyright 2011-2018 The Bootstrap Authors - * Copyright 2011-2018 Twitter, Inc. - * Licensed under MIT (https://github.com/twbs/bootstrap/blob/master/LICENSE) - */:root{--blue:#007bff;--indigo:#6610f2;--purple:#6f42c1;--pink:#e83e8c;--red:#dc3545;--orange:#fd7e14;--yellow:#ffc107;--green:#28a745;--teal:#20c997;--cyan:#17a2b8;--white:#fff;--gray:#6c757d;--gray-dark:#343a40;--primary:#007bff;--secondary:#6c757d;--success:#28a745;--info:#17a2b8;--warning:#ffc107;--danger:#dc3545;--light:#f8f9fa;--dark:#343a40;--breakpoint-xs:0;--breakpoint-sm:576px;--breakpoint-md:768px;--breakpoint-lg:992px;--breakpoint-xl:1200px;--font-family-sans-serif:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol","Noto Color Emoji";--font-family-monospace:SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",monospace}*,::after,::before{box-sizing:border-box}html{font-family:sans-serif;line-height:1.15;-webkit-text-size-adjust:100%;-ms-text-size-adjust:100%;-ms-overflow-style:scrollbar;-webkit-tap-highlight-color:transparent}@-ms-viewport{width:device-width}article,aside,figcaption,figure,footer,header,hgroup,main,nav,section{display:block}body{margin:0;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol","Noto Color Emoji";font-size:1rem;font-weight:400;line-height:1.5;color:#212529;text-align:left;background-color:#fff}[tabindex="-1"]:focus{outline:0!important}hr{box-sizing:content-box;height:0;overflow:visible}h1,h2,h3,h4,h5,h6{margin-top:0;margin-bottom:.5rem}p{margin-top:0;margin-bottom:1rem}abbr[data-original-title],abbr[title]{text-decoration:underline;-webkit-text-decoration:underline dotted;text-decoration:underline dotted;cursor:help;border-bottom:0}address{margin-bottom:1rem;font-style:normal;line-height:inherit}dl,ol,ul{margin-top:0;margin-bottom:1rem}ol ol,ol ul,ul ol,ul ul{margin-bottom:0}dt{font-weight:700}dd{margin-bottom:.5rem;margin-left:0}blockquote{margin:0 0 1rem}dfn{font-style:italic}b,strong{font-weight:bolder}small{font-size:80%}sub,sup{position:relative;font-size:75%;line-height:0;vertical-align:baseline}sub{bottom:-.25em}sup{top:-.5em}a{color:#007bff;text-decoration:none;background-color:transparent;-webkit-text-decoration-skip:objects}a:hover{color:#0056b3;text-decoration:underline}a:not([href]):not([tabindex]){color:inherit;text-decoration:none}a:not([href]):not([tabindex]):focus,a:not([href]):not([tabindex]):hover{color:inherit;text-decoration:none}a:not([href]):not([tabindex]):focus{outline:0}code,kbd,pre,samp{font-family:SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",monospace;font-size:1em}pre{margin-top:0;margin-bottom:1rem;overflow:auto;-ms-overflow-style:scrollbar}figure{margin:0 0 1rem}img{vertical-align:middle;border-style:none}svg{overflow:hidden;vertical-align:middle}table{border-collapse:collapse}caption{padding-top:.75rem;padding-bottom:.75rem;color:#6c757d;text-align:left;caption-side:bottom}th{text-align:inherit}label{display:inline-block;margin-bottom:.5rem}button{border-radius:0}button:focus{outline:1px dotted;outline:5px auto -webkit-focus-ring-color}button,input,optgroup,select,textarea{margin:0;font-family:inherit;font-size:inherit;line-height:inherit}button,input{overflow:visible}button,select{text-transform:none}[type=reset],[type=submit],button,html [type=button]{-webkit-appearance:button}[type=button]::-moz-focus-inner,[type=reset]::-moz-focus-inner,[type=submit]::-moz-focus-inner,button::-moz-focus-inner{padding:0;border-style:none}input[type=checkbox],input[type=radio]{box-sizing:border-box;padding:0}input[type=date],input[type=datetime-local],input[type=month],input[type=time]{-webkit-appearance:listbox}textarea{overflow:auto;resize:vertical}fieldset{min-width:0;padding:0;margin:0;border:0}legend{display:block;width:100%;max-width:100%;padding:0;margin-bottom:.5rem;font-size:1.5rem;line-height:inherit;color:inherit;white-space:normal}progress{vertical-align:baseline}[type=number]::-webkit-inner-spin-button,[type=number]::-webkit-outer-spin-button{height:auto}[type=search]{outline-offset:-2px;-webkit-appearance:none}[type=search]::-webkit-search-cancel-button,[type=search]::-webkit-search-decoration{-webkit-appearance:none}::-webkit-file-upload-button{font:inherit;-webkit-appearance:button}output{display:inline-block}summary{display:list-item;cursor:pointer}template{display:none}[hidden]{display:none!important}.h1,.h2,.h3,.h4,.h5,.h6,h1,h2,h3,h4,h5,h6{margin-bottom:.5rem;font-family:inherit;font-weight:500;line-height:1.2;color:inherit}.h1,h1{font-size:2.5rem}.h2,h2{font-size:2rem}.h3,h3{font-size:1.75rem}.h4,h4{font-size:1.5rem}.h5,h5{font-size:1.25rem}.h6,h6{font-size:1rem}.lead{font-size:1.25rem;font-weight:300}.display-1{font-size:6rem;font-weight:300;line-height:1.2}.display-2{font-size:5.5rem;font-weight:300;line-height:1.2}.display-3{font-size:4.5rem;font-weight:300;line-height:1.2}.display-4{font-size:3.5rem;font-weight:300;line-height:1.2}hr{margin-top:1rem;margin-bottom:1rem;border:0;border-top:1px solid rgba(0,0,0,.1)}.small,small{font-size:80%;font-weight:400}.mark,mark{padding:.2em;background-color:#fcf8e3}.list-unstyled{padding-left:0;list-style:none}.list-inline{padding-left:0;list-style:none}.list-inline-item{display:inline-block}.list-inline-item:not(:last-child){margin-right:.5rem}.initialism{font-size:90%;text-transform:uppercase}.blockquote{margin-bottom:1rem;font-size:1.25rem}.blockquote-footer{display:block;font-size:80%;color:#6c757d}.blockquote-footer::before{content:"\2014 \00A0"}.img-fluid{max-width:100%;height:auto}.img-thumbnail{padding:.25rem;background-color:#fff;border:1px solid #dee2e6;border-radius:.25rem;max-width:100%;height:auto}.figure{display:inline-block}.figure-img{margin-bottom:.5rem;line-height:1}.figure-caption{font-size:90%;color:#6c757d}code{font-size:87.5%;color:#e83e8c;word-break:break-word}a>code{color:inherit}kbd{padding:.2rem .4rem;font-size:87.5%;color:#fff;background-color:#212529;border-radius:.2rem}kbd kbd{padding:0;font-size:100%;font-weight:700}pre{display:block;font-size:87.5%;color:#212529}pre code{font-size:inherit;color:inherit;word-break:normal}.pre-scrollable{max-height:340px;overflow-y:scroll}.container{width:100%;padding-right:15px;padding-left:15px;margin-right:auto;margin-left:auto}@media (min-width:576px){.container{max-width:540px}}@media (min-width:768px){.container{max-width:720px}}@media (min-width:992px){.container{max-width:960px}}@media (min-width:1200px){.container{max-width:1140px}}.container-fluid{width:100%;padding-right:15px;padding-left:15px;margin-right:auto;margin-left:auto}.row{display:-ms-flexbox;display:flex;-ms-flex-wrap:wrap;flex-wrap:wrap;margin-right:-15px;margin-left:-15px}.no-gutters{margin-right:0;margin-left:0}.no-gutters>.col,.no-gutters>[class*=col-]{padding-right:0;padding-left:0}.col,.col-1,.col-10,.col-11,.col-12,.col-2,.col-3,.col-4,.col-5,.col-6,.col-7,.col-8,.col-9,.col-auto,.col-lg,.col-lg-1,.col-lg-10,.col-lg-11,.col-lg-12,.col-lg-2,.col-lg-3,.col-lg-4,.col-lg-5,.col-lg-6,.col-lg-7,.col-lg-8,.col-lg-9,.col-lg-auto,.col-md,.col-md-1,.col-md-10,.col-md-11,.col-md-12,.col-md-2,.col-md-3,.col-md-4,.col-md-5,.col-md-6,.col-md-7,.col-md-8,.col-md-9,.col-md-auto,.col-sm,.col-sm-1,.col-sm-10,.col-sm-11,.col-sm-12,.col-sm-2,.col-sm-3,.col-sm-4,.col-sm-5,.col-sm-6,.col-sm-7,.col-sm-8,.col-sm-9,.col-sm-auto,.col-xl,.col-xl-1,.col-xl-10,.col-xl-11,.col-xl-12,.col-xl-2,.col-xl-3,.col-xl-4,.col-xl-5,.col-xl-6,.col-xl-7,.col-xl-8,.col-xl-9,.col-xl-auto{position:relative;width:100%;min-height:1px;padding-right:15px;padding-left:15px}.col{-ms-flex-preferred-size:0;flex-basis:0;-ms-flex-positive:1;flex-grow:1;max-width:100%}.col-auto{-ms-flex:0 0 auto;flex:0 0 auto;width:auto;max-width:none}.col-1{-ms-flex:0 0 8.333333%;flex:0 0 8.333333%;max-width:8.333333%}.col-2{-ms-flex:0 0 16.666667%;flex:0 0 16.666667%;max-width:16.666667%}.col-3{-ms-flex:0 0 25%;flex:0 0 25%;max-width:25%}.col-4{-ms-flex:0 0 33.333333%;flex:0 0 33.333333%;max-width:33.333333%}.col-5{-ms-flex:0 0 41.666667%;flex:0 0 41.666667%;max-width:41.666667%}.col-6{-ms-flex:0 0 50%;flex:0 0 50%;max-width:50%}.col-7{-ms-flex:0 0 58.333333%;flex:0 0 58.333333%;max-width:58.333333%}.col-8{-ms-flex:0 0 66.666667%;flex:0 0 66.666667%;max-width:66.666667%}.col-9{-ms-flex:0 0 75%;flex:0 0 75%;max-width:75%}.col-10{-ms-flex:0 0 83.333333%;flex:0 0 83.333333%;max-width:83.333333%}.col-11{-ms-flex:0 0 91.666667%;flex:0 0 91.666667%;max-width:91.666667%}.col-12{-ms-flex:0 0 100%;flex:0 0 100%;max-width:100%}.order-first{-ms-flex-order:-1;order:-1}.order-last{-ms-flex-order:13;order:13}.order-0{-ms-flex-order:0;order:0}.order-1{-ms-flex-order:1;order:1}.order-2{-ms-flex-order:2;order:2}.order-3{-ms-flex-order:3;order:3}.order-4{-ms-flex-order:4;order:4}.order-5{-ms-flex-order:5;order:5}.order-6{-ms-flex-order:6;order:6}.order-7{-ms-flex-order:7;order:7}.order-8{-ms-flex-order:8;order:8}.order-9{-ms-flex-order:9;order:9}.order-10{-ms-flex-order:10;order:10}.order-11{-ms-flex-order:11;order:11}.order-12{-ms-flex-order:12;order:12}.offset-1{margin-left:8.333333%}.offset-2{margin-left:16.666667%}.offset-3{margin-left:25%}.offset-4{margin-left:33.333333%}.offset-5{margin-left:41.666667%}.offset-6{margin-left:50%}.offset-7{margin-left:58.333333%}.offset-8{margin-left:66.666667%}.offset-9{margin-left:75%}.offset-10{margin-left:83.333333%}.offset-11{margin-left:91.666667%}@media (min-width:576px){.col-sm{-ms-flex-preferred-size:0;flex-basis:0;-ms-flex-positive:1;flex-grow:1;max-width:100%}.col-sm-auto{-ms-flex:0 0 auto;flex:0 0 auto;width:auto;max-width:none}.col-sm-1{-ms-flex:0 0 8.333333%;flex:0 0 8.333333%;max-width:8.333333%}.col-sm-2{-ms-flex:0 0 16.666667%;flex:0 0 16.666667%;max-width:16.666667%}.col-sm-3{-ms-flex:0 0 25%;flex:0 0 25%;max-width:25%}.col-sm-4{-ms-flex:0 0 33.333333%;flex:0 0 33.333333%;max-width:33.333333%}.col-sm-5{-ms-flex:0 0 41.666667%;flex:0 0 41.666667%;max-width:41.666667%}.col-sm-6{-ms-flex:0 0 50%;flex:0 0 50%;max-width:50%}.col-sm-7{-ms-flex:0 0 58.333333%;flex:0 0 58.333333%;max-width:58.333333%}.col-sm-8{-ms-flex:0 0 66.666667%;flex:0 0 66.666667%;max-width:66.666667%}.col-sm-9{-ms-flex:0 0 75%;flex:0 0 75%;max-width:75%}.col-sm-10{-ms-flex:0 0 83.333333%;flex:0 0 83.333333%;max-width:83.333333%}.col-sm-11{-ms-flex:0 0 91.666667%;flex:0 0 91.666667%;max-width:91.666667%}.col-sm-12{-ms-flex:0 0 100%;flex:0 0 100%;max-width:100%}.order-sm-first{-ms-flex-order:-1;order:-1}.order-sm-last{-ms-flex-order:13;order:13}.order-sm-0{-ms-flex-order:0;order:0}.order-sm-1{-ms-flex-order:1;order:1}.order-sm-2{-ms-flex-order:2;order:2}.order-sm-3{-ms-flex-order:3;order:3}.order-sm-4{-ms-flex-order:4;order:4}.order-sm-5{-ms-flex-order:5;order:5}.order-sm-6{-ms-flex-order:6;order:6}.order-sm-7{-ms-flex-order:7;order:7}.order-sm-8{-ms-flex-order:8;order:8}.order-sm-9{-ms-flex-order:9;order:9}.order-sm-10{-ms-flex-order:10;order:10}.order-sm-11{-ms-flex-order:11;order:11}.order-sm-12{-ms-flex-order:12;order:12}.offset-sm-0{margin-left:0}.offset-sm-1{margin-left:8.333333%}.offset-sm-2{margin-left:16.666667%}.offset-sm-3{margin-left:25%}.offset-sm-4{margin-left:33.333333%}.offset-sm-5{margin-left:41.666667%}.offset-sm-6{margin-left:50%}.offset-sm-7{margin-left:58.333333%}.offset-sm-8{margin-left:66.666667%}.offset-sm-9{margin-left:75%}.offset-sm-10{margin-left:83.333333%}.offset-sm-11{margin-left:91.666667%}}@media (min-width:768px){.col-md{-ms-flex-preferred-size:0;flex-basis:0;-ms-flex-positive:1;flex-grow:1;max-width:100%}.col-md-auto{-ms-flex:0 0 auto;flex:0 0 auto;width:auto;max-width:none}.col-md-1{-ms-flex:0 0 8.333333%;flex:0 0 8.333333%;max-width:8.333333%}.col-md-2{-ms-flex:0 0 16.666667%;flex:0 0 16.666667%;max-width:16.666667%}.col-md-3{-ms-flex:0 0 25%;flex:0 0 25%;max-width:25%}.col-md-4{-ms-flex:0 0 33.333333%;flex:0 0 33.333333%;max-width:33.333333%}.col-md-5{-ms-flex:0 0 41.666667%;flex:0 0 41.666667%;max-width:41.666667%}.col-md-6{-ms-flex:0 0 50%;flex:0 0 50%;max-width:50%}.col-md-7{-ms-flex:0 0 58.333333%;flex:0 0 58.333333%;max-width:58.333333%}.col-md-8{-ms-flex:0 0 66.666667%;flex:0 0 66.666667%;max-width:66.666667%}.col-md-9{-ms-flex:0 0 75%;flex:0 0 75%;max-width:75%}.col-md-10{-ms-flex:0 0 83.333333%;flex:0 0 83.333333%;max-width:83.333333%}.col-md-11{-ms-flex:0 0 91.666667%;flex:0 0 91.666667%;max-width:91.666667%}.col-md-12{-ms-flex:0 0 100%;flex:0 0 100%;max-width:100%}.order-md-first{-ms-flex-order:-1;order:-1}.order-md-last{-ms-flex-order:13;order:13}.order-md-0{-ms-flex-order:0;order:0}.order-md-1{-ms-flex-order:1;order:1}.order-md-2{-ms-flex-order:2;order:2}.order-md-3{-ms-flex-order:3;order:3}.order-md-4{-ms-flex-order:4;order:4}.order-md-5{-ms-flex-order:5;order:5}.order-md-6{-ms-flex-order:6;order:6}.order-md-7{-ms-flex-order:7;order:7}.order-md-8{-ms-flex-order:8;order:8}.order-md-9{-ms-flex-order:9;order:9}.order-md-10{-ms-flex-order:10;order:10}.order-md-11{-ms-flex-order:11;order:11}.order-md-12{-ms-flex-order:12;order:12}.offset-md-0{margin-left:0}.offset-md-1{margin-left:8.333333%}.offset-md-2{margin-left:16.666667%}.offset-md-3{margin-left:25%}.offset-md-4{margin-left:33.333333%}.offset-md-5{margin-left:41.666667%}.offset-md-6{margin-left:50%}.offset-md-7{margin-left:58.333333%}.offset-md-8{margin-left:66.666667%}.offset-md-9{margin-left:75%}.offset-md-10{margin-left:83.333333%}.offset-md-11{margin-left:91.666667%}}@media (min-width:992px){.col-lg{-ms-flex-preferred-size:0;flex-basis:0;-ms-flex-positive:1;flex-grow:1;max-width:100%}.col-lg-auto{-ms-flex:0 0 auto;flex:0 0 auto;width:auto;max-width:none}.col-lg-1{-ms-flex:0 0 8.333333%;flex:0 0 8.333333%;max-width:8.333333%}.col-lg-2{-ms-flex:0 0 16.666667%;flex:0 0 16.666667%;max-width:16.666667%}.col-lg-3{-ms-flex:0 0 25%;flex:0 0 25%;max-width:25%}.col-lg-4{-ms-flex:0 0 33.333333%;flex:0 0 33.333333%;max-width:33.333333%}.col-lg-5{-ms-flex:0 0 41.666667%;flex:0 0 41.666667%;max-width:41.666667%}.col-lg-6{-ms-flex:0 0 50%;flex:0 0 50%;max-width:50%}.col-lg-7{-ms-flex:0 0 58.333333%;flex:0 0 58.333333%;max-width:58.333333%}.col-lg-8{-ms-flex:0 0 66.666667%;flex:0 0 66.666667%;max-width:66.666667%}.col-lg-9{-ms-flex:0 0 75%;flex:0 0 75%;max-width:75%}.col-lg-10{-ms-flex:0 0 83.333333%;flex:0 0 83.333333%;max-width:83.333333%}.col-lg-11{-ms-flex:0 0 91.666667%;flex:0 0 91.666667%;max-width:91.666667%}.col-lg-12{-ms-flex:0 0 100%;flex:0 0 100%;max-width:100%}.order-lg-first{-ms-flex-order:-1;order:-1}.order-lg-last{-ms-flex-order:13;order:13}.order-lg-0{-ms-flex-order:0;order:0}.order-lg-1{-ms-flex-order:1;order:1}.order-lg-2{-ms-flex-order:2;order:2}.order-lg-3{-ms-flex-order:3;order:3}.order-lg-4{-ms-flex-order:4;order:4}.order-lg-5{-ms-flex-order:5;order:5}.order-lg-6{-ms-flex-order:6;order:6}.order-lg-7{-ms-flex-order:7;order:7}.order-lg-8{-ms-flex-order:8;order:8}.order-lg-9{-ms-flex-order:9;order:9}.order-lg-10{-ms-flex-order:10;order:10}.order-lg-11{-ms-flex-order:11;order:11}.order-lg-12{-ms-flex-order:12;order:12}.offset-lg-0{margin-left:0}.offset-lg-1{margin-left:8.333333%}.offset-lg-2{margin-left:16.666667%}.offset-lg-3{margin-left:25%}.offset-lg-4{margin-left:33.333333%}.offset-lg-5{margin-left:41.666667%}.offset-lg-6{margin-left:50%}.offset-lg-7{margin-left:58.333333%}.offset-lg-8{margin-left:66.666667%}.offset-lg-9{margin-left:75%}.offset-lg-10{margin-left:83.333333%}.offset-lg-11{margin-left:91.666667%}}@media (min-width:1200px){.col-xl{-ms-flex-preferred-size:0;flex-basis:0;-ms-flex-positive:1;flex-grow:1;max-width:100%}.col-xl-auto{-ms-flex:0 0 auto;flex:0 0 auto;width:auto;max-width:none}.col-xl-1{-ms-flex:0 0 8.333333%;flex:0 0 8.333333%;max-width:8.333333%}.col-xl-2{-ms-flex:0 0 16.666667%;flex:0 0 16.666667%;max-width:16.666667%}.col-xl-3{-ms-flex:0 0 25%;flex:0 0 25%;max-width:25%}.col-xl-4{-ms-flex:0 0 33.333333%;flex:0 0 33.333333%;max-width:33.333333%}.col-xl-5{-ms-flex:0 0 41.666667%;flex:0 0 41.666667%;max-width:41.666667%}.col-xl-6{-ms-flex:0 0 50%;flex:0 0 50%;max-width:50%}.col-xl-7{-ms-flex:0 0 58.333333%;flex:0 0 58.333333%;max-width:58.333333%}.col-xl-8{-ms-flex:0 0 66.666667%;flex:0 0 66.666667%;max-width:66.666667%}.col-xl-9{-ms-flex:0 0 75%;flex:0 0 75%;max-width:75%}.col-xl-10{-ms-flex:0 0 83.333333%;flex:0 0 83.333333%;max-width:83.333333%}.col-xl-11{-ms-flex:0 0 91.666667%;flex:0 0 91.666667%;max-width:91.666667%}.col-xl-12{-ms-flex:0 0 100%;flex:0 0 100%;max-width:100%}.order-xl-first{-ms-flex-order:-1;order:-1}.order-xl-last{-ms-flex-order:13;order:13}.order-xl-0{-ms-flex-order:0;order:0}.order-xl-1{-ms-flex-order:1;order:1}.order-xl-2{-ms-flex-order:2;order:2}.order-xl-3{-ms-flex-order:3;order:3}.order-xl-4{-ms-flex-order:4;order:4}.order-xl-5{-ms-flex-order:5;order:5}.order-xl-6{-ms-flex-order:6;order:6}.order-xl-7{-ms-flex-order:7;order:7}.order-xl-8{-ms-flex-order:8;order:8}.order-xl-9{-ms-flex-order:9;order:9}.order-xl-10{-ms-flex-order:10;order:10}.order-xl-11{-ms-flex-order:11;order:11}.order-xl-12{-ms-flex-order:12;order:12}.offset-xl-0{margin-left:0}.offset-xl-1{margin-left:8.333333%}.offset-xl-2{margin-left:16.666667%}.offset-xl-3{margin-left:25%}.offset-xl-4{margin-left:33.333333%}.offset-xl-5{margin-left:41.666667%}.offset-xl-6{margin-left:50%}.offset-xl-7{margin-left:58.333333%}.offset-xl-8{margin-left:66.666667%}.offset-xl-9{margin-left:75%}.offset-xl-10{margin-left:83.333333%}.offset-xl-11{margin-left:91.666667%}}.table{width:100%;margin-bottom:1rem;background-color:transparent}.table td,.table th{padding:.75rem;vertical-align:top;border-top:1px solid #dee2e6}.table thead th{vertical-align:bottom;border-bottom:2px solid #dee2e6}.table tbody+tbody{border-top:2px solid #dee2e6}.table .table{background-color:#fff}.table-sm td,.table-sm th{padding:.3rem}.table-bordered{border:1px solid #dee2e6}.table-bordered td,.table-bordered th{border:1px solid #dee2e6}.table-bordered thead td,.table-bordered thead th{border-bottom-width:2px}.table-borderless tbody+tbody,.table-borderless td,.table-borderless th,.table-borderless thead th{border:0}.table-striped tbody tr:nth-of-type(odd){background-color:rgba(0,0,0,.05)}.table-hover tbody tr:hover{background-color:rgba(0,0,0,.075)}.table-primary,.table-primary>td,.table-primary>th{background-color:#b8daff}.table-hover .table-primary:hover{background-color:#9fcdff}.table-hover .table-primary:hover>td,.table-hover .table-primary:hover>th{background-color:#9fcdff}.table-secondary,.table-secondary>td,.table-secondary>th{background-color:#d6d8db}.table-hover .table-secondary:hover{background-color:#c8cbcf}.table-hover .table-secondary:hover>td,.table-hover .table-secondary:hover>th{background-color:#c8cbcf}.table-success,.table-success>td,.table-success>th{background-color:#c3e6cb}.table-hover .table-success:hover{background-color:#b1dfbb}.table-hover .table-success:hover>td,.table-hover .table-success:hover>th{background-color:#b1dfbb}.table-info,.table-info>td,.table-info>th{background-color:#bee5eb}.table-hover .table-info:hover{background-color:#abdde5}.table-hover .table-info:hover>td,.table-hover .table-info:hover>th{background-color:#abdde5}.table-warning,.table-warning>td,.table-warning>th{background-color:#ffeeba}.table-hover .table-warning:hover{background-color:#ffe8a1}.table-hover .table-warning:hover>td,.table-hover .table-warning:hover>th{background-color:#ffe8a1}.table-danger,.table-danger>td,.table-danger>th{background-color:#f5c6cb}.table-hover .table-danger:hover{background-color:#f1b0b7}.table-hover .table-danger:hover>td,.table-hover .table-danger:hover>th{background-color:#f1b0b7}.table-light,.table-light>td,.table-light>th{background-color:#fdfdfe}.table-hover .table-light:hover{background-color:#ececf6}.table-hover .table-light:hover>td,.table-hover .table-light:hover>th{background-color:#ececf6}.table-dark,.table-dark>td,.table-dark>th{background-color:#c6c8ca}.table-hover .table-dark:hover{background-color:#b9bbbe}.table-hover .table-dark:hover>td,.table-hover .table-dark:hover>th{background-color:#b9bbbe}.table-active,.table-active>td,.table-active>th{background-color:rgba(0,0,0,.075)}.table-hover .table-active:hover{background-color:rgba(0,0,0,.075)}.table-hover .table-active:hover>td,.table-hover .table-active:hover>th{background-color:rgba(0,0,0,.075)}.table .thead-dark th{color:#fff;background-color:#212529;border-color:#32383e}.table .thead-light th{color:#495057;background-color:#e9ecef;border-color:#dee2e6}.table-dark{color:#fff;background-color:#212529}.table-dark td,.table-dark th,.table-dark thead th{border-color:#32383e}.table-dark.table-bordered{border:0}.table-dark.table-striped tbody tr:nth-of-type(odd){background-color:rgba(255,255,255,.05)}.table-dark.table-hover tbody tr:hover{background-color:rgba(255,255,255,.075)}@media (max-width:575.98px){.table-responsive-sm{display:block;width:100%;overflow-x:auto;-webkit-overflow-scrolling:touch;-ms-overflow-style:-ms-autohiding-scrollbar}.table-responsive-sm>.table-bordered{border:0}}@media (max-width:767.98px){.table-responsive-md{display:block;width:100%;overflow-x:auto;-webkit-overflow-scrolling:touch;-ms-overflow-style:-ms-autohiding-scrollbar}.table-responsive-md>.table-bordered{border:0}}@media (max-width:991.98px){.table-responsive-lg{display:block;width:100%;overflow-x:auto;-webkit-overflow-scrolling:touch;-ms-overflow-style:-ms-autohiding-scrollbar}.table-responsive-lg>.table-bordered{border:0}}@media (max-width:1199.98px){.table-responsive-xl{display:block;width:100%;overflow-x:auto;-webkit-overflow-scrolling:touch;-ms-overflow-style:-ms-autohiding-scrollbar}.table-responsive-xl>.table-bordered{border:0}}.table-responsive{display:block;width:100%;overflow-x:auto;-webkit-overflow-scrolling:touch;-ms-overflow-style:-ms-autohiding-scrollbar}.table-responsive>.table-bordered{border:0}.form-control{display:block;width:100%;height:calc(2.25rem + 2px);padding:.375rem .75rem;font-size:1rem;line-height:1.5;color:#495057;background-color:#fff;background-clip:padding-box;border:1px solid #ced4da;border-radius:.25rem;transition:border-color .15s ease-in-out,box-shadow .15s ease-in-out}@media screen and (prefers-reduced-motion:reduce){.form-control{transition:none}}.form-control::-ms-expand{background-color:transparent;border:0}.form-control:focus{color:#495057;background-color:#fff;border-color:#80bdff;outline:0;box-shadow:0 0 0 .2rem rgba(0,123,255,.25)}.form-control::-webkit-input-placeholder{color:#6c757d;opacity:1}.form-control::-moz-placeholder{color:#6c757d;opacity:1}.form-control:-ms-input-placeholder{color:#6c757d;opacity:1}.form-control::-ms-input-placeholder{color:#6c757d;opacity:1}.form-control::placeholder{color:#6c757d;opacity:1}.form-control:disabled,.form-control[readonly]{background-color:#e9ecef;opacity:1}select.form-control:focus::-ms-value{color:#495057;background-color:#fff}.form-control-file,.form-control-range{display:block;width:100%}.col-form-label{padding-top:calc(.375rem + 1px);padding-bottom:calc(.375rem + 1px);margin-bottom:0;font-size:inherit;line-height:1.5}.col-form-label-lg{padding-top:calc(.5rem + 1px);padding-bottom:calc(.5rem + 1px);font-size:1.25rem;line-height:1.5}.col-form-label-sm{padding-top:calc(.25rem + 1px);padding-bottom:calc(.25rem + 1px);font-size:.875rem;line-height:1.5}.form-control-plaintext{display:block;width:100%;padding-top:.375rem;padding-bottom:.375rem;margin-bottom:0;line-height:1.5;color:#212529;background-color:transparent;border:solid transparent;border-width:1px 0}.form-control-plaintext.form-control-lg,.form-control-plaintext.form-control-sm{padding-right:0;padding-left:0}.form-control-sm{height:calc(1.8125rem + 2px);padding:.25rem .5rem;font-size:.875rem;line-height:1.5;border-radius:.2rem}.form-control-lg{height:calc(2.875rem + 2px);padding:.5rem 1rem;font-size:1.25rem;line-height:1.5;border-radius:.3rem}select.form-control[multiple],select.form-control[size]{height:auto}textarea.form-control{height:auto}.form-group{margin-bottom:1rem}.form-text{display:block;margin-top:.25rem}.form-row{display:-ms-flexbox;display:flex;-ms-flex-wrap:wrap;flex-wrap:wrap;margin-right:-5px;margin-left:-5px}.form-row>.col,.form-row>[class*=col-]{padding-right:5px;padding-left:5px}.form-check{position:relative;display:block;padding-left:1.25rem}.form-check-input{position:absolute;margin-top:.3rem;margin-left:-1.25rem}.form-check-input:disabled~.form-check-label{color:#6c757d}.form-check-label{margin-bottom:0}.form-check-inline{display:-ms-inline-flexbox;display:inline-flex;-ms-flex-align:center;align-items:center;padding-left:0;margin-right:.75rem}.form-check-inline .form-check-input{position:static;margin-top:0;margin-right:.3125rem;margin-left:0}.valid-feedback{display:none;width:100%;margin-top:.25rem;font-size:80%;color:#28a745}.valid-tooltip{position:absolute;top:100%;z-index:5;display:none;max-width:100%;padding:.25rem .5rem;margin-top:.1rem;font-size:.875rem;line-height:1.5;color:#fff;background-color:rgba(40,167,69,.9);border-radius:.25rem}.custom-select.is-valid,.form-control.is-valid,.was-validated .custom-select:valid,.was-validated .form-control:valid{border-color:#28a745}.custom-select.is-valid:focus,.form-control.is-valid:focus,.was-validated .custom-select:valid:focus,.was-validated .form-control:valid:focus{border-color:#28a745;box-shadow:0 0 0 .2rem rgba(40,167,69,.25)}.custom-select.is-valid~.valid-feedback,.custom-select.is-valid~.valid-tooltip,.form-control.is-valid~.valid-feedback,.form-control.is-valid~.valid-tooltip,.was-validated .custom-select:valid~.valid-feedback,.was-validated .custom-select:valid~.valid-tooltip,.was-validated .form-control:valid~.valid-feedback,.was-validated .form-control:valid~.valid-tooltip{display:block}.form-control-file.is-valid~.valid-feedback,.form-control-file.is-valid~.valid-tooltip,.was-validated .form-control-file:valid~.valid-feedback,.was-validated .form-control-file:valid~.valid-tooltip{display:block}.form-check-input.is-valid~.form-check-label,.was-validated .form-check-input:valid~.form-check-label{color:#28a745}.form-check-input.is-valid~.valid-feedback,.form-check-input.is-valid~.valid-tooltip,.was-validated .form-check-input:valid~.valid-feedback,.was-validated .form-check-input:valid~.valid-tooltip{display:block}.custom-control-input.is-valid~.custom-control-label,.was-validated .custom-control-input:valid~.custom-control-label{color:#28a745}.custom-control-input.is-valid~.custom-control-label::before,.was-validated .custom-control-input:valid~.custom-control-label::before{background-color:#71dd8a}.custom-control-input.is-valid~.valid-feedback,.custom-control-input.is-valid~.valid-tooltip,.was-validated .custom-control-input:valid~.valid-feedback,.was-validated .custom-control-input:valid~.valid-tooltip{display:block}.custom-control-input.is-valid:checked~.custom-control-label::before,.was-validated .custom-control-input:valid:checked~.custom-control-label::before{background-color:#34ce57}.custom-control-input.is-valid:focus~.custom-control-label::before,.was-validated .custom-control-input:valid:focus~.custom-control-label::before{box-shadow:0 0 0 1px #fff,0 0 0 .2rem rgba(40,167,69,.25)}.custom-file-input.is-valid~.custom-file-label,.was-validated .custom-file-input:valid~.custom-file-label{border-color:#28a745}.custom-file-input.is-valid~.custom-file-label::after,.was-validated .custom-file-input:valid~.custom-file-label::after{border-color:inherit}.custom-file-input.is-valid~.valid-feedback,.custom-file-input.is-valid~.valid-tooltip,.was-validated .custom-file-input:valid~.valid-feedback,.was-validated .custom-file-input:valid~.valid-tooltip{display:block}.custom-file-input.is-valid:focus~.custom-file-label,.was-validated .custom-file-input:valid:focus~.custom-file-label{box-shadow:0 0 0 .2rem rgba(40,167,69,.25)}.invalid-feedback{display:none;width:100%;margin-top:.25rem;font-size:80%;color:#dc3545}.invalid-tooltip{position:absolute;top:100%;z-index:5;display:none;max-width:100%;padding:.25rem .5rem;margin-top:.1rem;font-size:.875rem;line-height:1.5;color:#fff;background-color:rgba(220,53,69,.9);border-radius:.25rem}.custom-select.is-invalid,.form-control.is-invalid,.was-validated .custom-select:invalid,.was-validated .form-control:invalid{border-color:#dc3545}.custom-select.is-invalid:focus,.form-control.is-invalid:focus,.was-validated .custom-select:invalid:focus,.was-validated .form-control:invalid:focus{border-color:#dc3545;box-shadow:0 0 0 .2rem rgba(220,53,69,.25)}.custom-select.is-invalid~.invalid-feedback,.custom-select.is-invalid~.invalid-tooltip,.form-control.is-invalid~.invalid-feedback,.form-control.is-invalid~.invalid-tooltip,.was-validated .custom-select:invalid~.invalid-feedback,.was-validated .custom-select:invalid~.invalid-tooltip,.was-validated .form-control:invalid~.invalid-feedback,.was-validated .form-control:invalid~.invalid-tooltip{display:block}.form-control-file.is-invalid~.invalid-feedback,.form-control-file.is-invalid~.invalid-tooltip,.was-validated .form-control-file:invalid~.invalid-feedback,.was-validated .form-control-file:invalid~.invalid-tooltip{display:block}.form-check-input.is-invalid~.form-check-label,.was-validated .form-check-input:invalid~.form-check-label{color:#dc3545}.form-check-input.is-invalid~.invalid-feedback,.form-check-input.is-invalid~.invalid-tooltip,.was-validated .form-check-input:invalid~.invalid-feedback,.was-validated .form-check-input:invalid~.invalid-tooltip{display:block}.custom-control-input.is-invalid~.custom-control-label,.was-validated .custom-control-input:invalid~.custom-control-label{color:#dc3545}.custom-control-input.is-invalid~.custom-control-label::before,.was-validated .custom-control-input:invalid~.custom-control-label::before{background-color:#efa2a9}.custom-control-input.is-invalid~.invalid-feedback,.custom-control-input.is-invalid~.invalid-tooltip,.was-validated .custom-control-input:invalid~.invalid-feedback,.was-validated .custom-control-input:invalid~.invalid-tooltip{display:block}.custom-control-input.is-invalid:checked~.custom-control-label::before,.was-validated .custom-control-input:invalid:checked~.custom-control-label::before{background-color:#e4606d}.custom-control-input.is-invalid:focus~.custom-control-label::before,.was-validated .custom-control-input:invalid:focus~.custom-control-label::before{box-shadow:0 0 0 1px #fff,0 0 0 .2rem rgba(220,53,69,.25)}.custom-file-input.is-invalid~.custom-file-label,.was-validated .custom-file-input:invalid~.custom-file-label{border-color:#dc3545}.custom-file-input.is-invalid~.custom-file-label::after,.was-validated .custom-file-input:invalid~.custom-file-label::after{border-color:inherit}.custom-file-input.is-invalid~.invalid-feedback,.custom-file-input.is-invalid~.invalid-tooltip,.was-validated .custom-file-input:invalid~.invalid-feedback,.was-validated .custom-file-input:invalid~.invalid-tooltip{display:block}.custom-file-input.is-invalid:focus~.custom-file-label,.was-validated .custom-file-input:invalid:focus~.custom-file-label{box-shadow:0 0 0 .2rem rgba(220,53,69,.25)}.form-inline{display:-ms-flexbox;display:flex;-ms-flex-flow:row wrap;flex-flow:row wrap;-ms-flex-align:center;align-items:center}.form-inline .form-check{width:100%}@media (min-width:576px){.form-inline label{display:-ms-flexbox;display:flex;-ms-flex-align:center;align-items:center;-ms-flex-pack:center;justify-content:center;margin-bottom:0}.form-inline .form-group{display:-ms-flexbox;display:flex;-ms-flex:0 0 auto;flex:0 0 auto;-ms-flex-flow:row wrap;flex-flow:row wrap;-ms-flex-align:center;align-items:center;margin-bottom:0}.form-inline .form-control{display:inline-block;width:auto;vertical-align:middle}.form-inline .form-control-plaintext{display:inline-block}.form-inline .custom-select,.form-inline .input-group{width:auto}.form-inline .form-check{display:-ms-flexbox;display:flex;-ms-flex-align:center;align-items:center;-ms-flex-pack:center;justify-content:center;width:auto;padding-left:0}.form-inline .form-check-input{position:relative;margin-top:0;margin-right:.25rem;margin-left:0}.form-inline .custom-control{-ms-flex-align:center;align-items:center;-ms-flex-pack:center;justify-content:center}.form-inline .custom-control-label{margin-bottom:0}}.btn{display:inline-block;font-weight:400;text-align:center;white-space:nowrap;vertical-align:middle;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none;border:1px solid transparent;padding:.375rem .75rem;font-size:1rem;line-height:1.5;border-radius:.25rem;transition:color .15s ease-in-out,background-color .15s ease-in-out,border-color .15s ease-in-out,box-shadow .15s ease-in-out}@media screen and (prefers-reduced-motion:reduce){.btn{transition:none}}.btn:focus,.btn:hover{text-decoration:none}.btn.focus,.btn:focus{outline:0;box-shadow:0 0 0 .2rem rgba(0,123,255,.25)}.btn.disabled,.btn:disabled{opacity:.65}.btn:not(:disabled):not(.disabled){cursor:pointer}a.btn.disabled,fieldset:disabled a.btn{pointer-events:none}.btn-primary{color:#fff;background-color:#007bff;border-color:#007bff}.btn-primary:hover{color:#fff;background-color:#0069d9;border-color:#0062cc}.btn-primary.focus,.btn-primary:focus{box-shadow:0 0 0 .2rem rgba(0,123,255,.5)}.btn-primary.disabled,.btn-primary:disabled{color:#fff;background-color:#007bff;border-color:#007bff}.btn-primary:not(:disabled):not(.disabled).active,.btn-primary:not(:disabled):not(.disabled):active,.show>.btn-primary.dropdown-toggle{color:#fff;background-color:#0062cc;border-color:#005cbf}.btn-primary:not(:disabled):not(.disabled).active:focus,.btn-primary:not(:disabled):not(.disabled):active:focus,.show>.btn-primary.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(0,123,255,.5)}.btn-secondary{color:#fff;background-color:#6c757d;border-color:#6c757d}.btn-secondary:hover{color:#fff;background-color:#5a6268;border-color:#545b62}.btn-secondary.focus,.btn-secondary:focus{box-shadow:0 0 0 .2rem rgba(108,117,125,.5)}.btn-secondary.disabled,.btn-secondary:disabled{color:#fff;background-color:#6c757d;border-color:#6c757d}.btn-secondary:not(:disabled):not(.disabled).active,.btn-secondary:not(:disabled):not(.disabled):active,.show>.btn-secondary.dropdown-toggle{color:#fff;background-color:#545b62;border-color:#4e555b}.btn-secondary:not(:disabled):not(.disabled).active:focus,.btn-secondary:not(:disabled):not(.disabled):active:focus,.show>.btn-secondary.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(108,117,125,.5)}.btn-success{color:#fff;background-color:#28a745;border-color:#28a745}.btn-success:hover{color:#fff;background-color:#218838;border-color:#1e7e34}.btn-success.focus,.btn-success:focus{box-shadow:0 0 0 .2rem rgba(40,167,69,.5)}.btn-success.disabled,.btn-success:disabled{color:#fff;background-color:#28a745;border-color:#28a745}.btn-success:not(:disabled):not(.disabled).active,.btn-success:not(:disabled):not(.disabled):active,.show>.btn-success.dropdown-toggle{color:#fff;background-color:#1e7e34;border-color:#1c7430}.btn-success:not(:disabled):not(.disabled).active:focus,.btn-success:not(:disabled):not(.disabled):active:focus,.show>.btn-success.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(40,167,69,.5)}.btn-info{color:#fff;background-color:#17a2b8;border-color:#17a2b8}.btn-info:hover{color:#fff;background-color:#138496;border-color:#117a8b}.btn-info.focus,.btn-info:focus{box-shadow:0 0 0 .2rem rgba(23,162,184,.5)}.btn-info.disabled,.btn-info:disabled{color:#fff;background-color:#17a2b8;border-color:#17a2b8}.btn-info:not(:disabled):not(.disabled).active,.btn-info:not(:disabled):not(.disabled):active,.show>.btn-info.dropdown-toggle{color:#fff;background-color:#117a8b;border-color:#10707f}.btn-info:not(:disabled):not(.disabled).active:focus,.btn-info:not(:disabled):not(.disabled):active:focus,.show>.btn-info.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(23,162,184,.5)}.btn-warning{color:#212529;background-color:#ffc107;border-color:#ffc107}.btn-warning:hover{color:#212529;background-color:#e0a800;border-color:#d39e00}.btn-warning.focus,.btn-warning:focus{box-shadow:0 0 0 .2rem rgba(255,193,7,.5)}.btn-warning.disabled,.btn-warning:disabled{color:#212529;background-color:#ffc107;border-color:#ffc107}.btn-warning:not(:disabled):not(.disabled).active,.btn-warning:not(:disabled):not(.disabled):active,.show>.btn-warning.dropdown-toggle{color:#212529;background-color:#d39e00;border-color:#c69500}.btn-warning:not(:disabled):not(.disabled).active:focus,.btn-warning:not(:disabled):not(.disabled):active:focus,.show>.btn-warning.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(255,193,7,.5)}.btn-danger{color:#fff;background-color:#dc3545;border-color:#dc3545}.btn-danger:hover{color:#fff;background-color:#c82333;border-color:#bd2130}.btn-danger.focus,.btn-danger:focus{box-shadow:0 0 0 .2rem rgba(220,53,69,.5)}.btn-danger.disabled,.btn-danger:disabled{color:#fff;background-color:#dc3545;border-color:#dc3545}.btn-danger:not(:disabled):not(.disabled).active,.btn-danger:not(:disabled):not(.disabled):active,.show>.btn-danger.dropdown-toggle{color:#fff;background-color:#bd2130;border-color:#b21f2d}.btn-danger:not(:disabled):not(.disabled).active:focus,.btn-danger:not(:disabled):not(.disabled):active:focus,.show>.btn-danger.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(220,53,69,.5)}.btn-light{color:#212529;background-color:#f8f9fa;border-color:#f8f9fa}.btn-light:hover{color:#212529;background-color:#e2e6ea;border-color:#dae0e5}.btn-light.focus,.btn-light:focus{box-shadow:0 0 0 .2rem rgba(248,249,250,.5)}.btn-light.disabled,.btn-light:disabled{color:#212529;background-color:#f8f9fa;border-color:#f8f9fa}.btn-light:not(:disabled):not(.disabled).active,.btn-light:not(:disabled):not(.disabled):active,.show>.btn-light.dropdown-toggle{color:#212529;background-color:#dae0e5;border-color:#d3d9df}.btn-light:not(:disabled):not(.disabled).active:focus,.btn-light:not(:disabled):not(.disabled):active:focus,.show>.btn-light.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(248,249,250,.5)}.btn-dark{color:#fff;background-color:#343a40;border-color:#343a40}.btn-dark:hover{color:#fff;background-color:#23272b;border-color:#1d2124}.btn-dark.focus,.btn-dark:focus{box-shadow:0 0 0 .2rem rgba(52,58,64,.5)}.btn-dark.disabled,.btn-dark:disabled{color:#fff;background-color:#343a40;border-color:#343a40}.btn-dark:not(:disabled):not(.disabled).active,.btn-dark:not(:disabled):not(.disabled):active,.show>.btn-dark.dropdown-toggle{color:#fff;background-color:#1d2124;border-color:#171a1d}.btn-dark:not(:disabled):not(.disabled).active:focus,.btn-dark:not(:disabled):not(.disabled):active:focus,.show>.btn-dark.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(52,58,64,.5)}.btn-outline-primary{color:#007bff;background-color:transparent;background-image:none;border-color:#007bff}.btn-outline-primary:hover{color:#fff;background-color:#007bff;border-color:#007bff}.btn-outline-primary.focus,.btn-outline-primary:focus{box-shadow:0 0 0 .2rem rgba(0,123,255,.5)}.btn-outline-primary.disabled,.btn-outline-primary:disabled{color:#007bff;background-color:transparent}.btn-outline-primary:not(:disabled):not(.disabled).active,.btn-outline-primary:not(:disabled):not(.disabled):active,.show>.btn-outline-primary.dropdown-toggle{color:#fff;background-color:#007bff;border-color:#007bff}.btn-outline-primary:not(:disabled):not(.disabled).active:focus,.btn-outline-primary:not(:disabled):not(.disabled):active:focus,.show>.btn-outline-primary.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(0,123,255,.5)}.btn-outline-secondary{color:#6c757d;background-color:transparent;background-image:none;border-color:#6c757d}.btn-outline-secondary:hover{color:#fff;background-color:#6c757d;border-color:#6c757d}.btn-outline-secondary.focus,.btn-outline-secondary:focus{box-shadow:0 0 0 .2rem rgba(108,117,125,.5)}.btn-outline-secondary.disabled,.btn-outline-secondary:disabled{color:#6c757d;background-color:transparent}.btn-outline-secondary:not(:disabled):not(.disabled).active,.btn-outline-secondary:not(:disabled):not(.disabled):active,.show>.btn-outline-secondary.dropdown-toggle{color:#fff;background-color:#6c757d;border-color:#6c757d}.btn-outline-secondary:not(:disabled):not(.disabled).active:focus,.btn-outline-secondary:not(:disabled):not(.disabled):active:focus,.show>.btn-outline-secondary.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(108,117,125,.5)}.btn-outline-success{color:#28a745;background-color:transparent;background-image:none;border-color:#28a745}.btn-outline-success:hover{color:#fff;background-color:#28a745;border-color:#28a745}.btn-outline-success.focus,.btn-outline-success:focus{box-shadow:0 0 0 .2rem rgba(40,167,69,.5)}.btn-outline-success.disabled,.btn-outline-success:disabled{color:#28a745;background-color:transparent}.btn-outline-success:not(:disabled):not(.disabled).active,.btn-outline-success:not(:disabled):not(.disabled):active,.show>.btn-outline-success.dropdown-toggle{color:#fff;background-color:#28a745;border-color:#28a745}.btn-outline-success:not(:disabled):not(.disabled).active:focus,.btn-outline-success:not(:disabled):not(.disabled):active:focus,.show>.btn-outline-success.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(40,167,69,.5)}.btn-outline-info{color:#17a2b8;background-color:transparent;background-image:none;border-color:#17a2b8}.btn-outline-info:hover{color:#fff;background-color:#17a2b8;border-color:#17a2b8}.btn-outline-info.focus,.btn-outline-info:focus{box-shadow:0 0 0 .2rem rgba(23,162,184,.5)}.btn-outline-info.disabled,.btn-outline-info:disabled{color:#17a2b8;background-color:transparent}.btn-outline-info:not(:disabled):not(.disabled).active,.btn-outline-info:not(:disabled):not(.disabled):active,.show>.btn-outline-info.dropdown-toggle{color:#fff;background-color:#17a2b8;border-color:#17a2b8}.btn-outline-info:not(:disabled):not(.disabled).active:focus,.btn-outline-info:not(:disabled):not(.disabled):active:focus,.show>.btn-outline-info.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(23,162,184,.5)}.btn-outline-warning{color:#ffc107;background-color:transparent;background-image:none;border-color:#ffc107}.btn-outline-warning:hover{color:#212529;background-color:#ffc107;border-color:#ffc107}.btn-outline-warning.focus,.btn-outline-warning:focus{box-shadow:0 0 0 .2rem rgba(255,193,7,.5)}.btn-outline-warning.disabled,.btn-outline-warning:disabled{color:#ffc107;background-color:transparent}.btn-outline-warning:not(:disabled):not(.disabled).active,.btn-outline-warning:not(:disabled):not(.disabled):active,.show>.btn-outline-warning.dropdown-toggle{color:#212529;background-color:#ffc107;border-color:#ffc107}.btn-outline-warning:not(:disabled):not(.disabled).active:focus,.btn-outline-warning:not(:disabled):not(.disabled):active:focus,.show>.btn-outline-warning.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(255,193,7,.5)}.btn-outline-danger{color:#dc3545;background-color:transparent;background-image:none;border-color:#dc3545}.btn-outline-danger:hover{color:#fff;background-color:#dc3545;border-color:#dc3545}.btn-outline-danger.focus,.btn-outline-danger:focus{box-shadow:0 0 0 .2rem rgba(220,53,69,.5)}.btn-outline-danger.disabled,.btn-outline-danger:disabled{color:#dc3545;background-color:transparent}.btn-outline-danger:not(:disabled):not(.disabled).active,.btn-outline-danger:not(:disabled):not(.disabled):active,.show>.btn-outline-danger.dropdown-toggle{color:#fff;background-color:#dc3545;border-color:#dc3545}.btn-outline-danger:not(:disabled):not(.disabled).active:focus,.btn-outline-danger:not(:disabled):not(.disabled):active:focus,.show>.btn-outline-danger.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(220,53,69,.5)}.btn-outline-light{color:#f8f9fa;background-color:transparent;background-image:none;border-color:#f8f9fa}.btn-outline-light:hover{color:#212529;background-color:#f8f9fa;border-color:#f8f9fa}.btn-outline-light.focus,.btn-outline-light:focus{box-shadow:0 0 0 .2rem rgba(248,249,250,.5)}.btn-outline-light.disabled,.btn-outline-light:disabled{color:#f8f9fa;background-color:transparent}.btn-outline-light:not(:disabled):not(.disabled).active,.btn-outline-light:not(:disabled):not(.disabled):active,.show>.btn-outline-light.dropdown-toggle{color:#212529;background-color:#f8f9fa;border-color:#f8f9fa}.btn-outline-light:not(:disabled):not(.disabled).active:focus,.btn-outline-light:not(:disabled):not(.disabled):active:focus,.show>.btn-outline-light.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(248,249,250,.5)}.btn-outline-dark{color:#343a40;background-color:transparent;background-image:none;border-color:#343a40}.btn-outline-dark:hover{color:#fff;background-color:#343a40;border-color:#343a40}.btn-outline-dark.focus,.btn-outline-dark:focus{box-shadow:0 0 0 .2rem rgba(52,58,64,.5)}.btn-outline-dark.disabled,.btn-outline-dark:disabled{color:#343a40;background-color:transparent}.btn-outline-dark:not(:disabled):not(.disabled).active,.btn-outline-dark:not(:disabled):not(.disabled):active,.show>.btn-outline-dark.dropdown-toggle{color:#fff;background-color:#343a40;border-color:#343a40}.btn-outline-dark:not(:disabled):not(.disabled).active:focus,.btn-outline-dark:not(:disabled):not(.disabled):active:focus,.show>.btn-outline-dark.dropdown-toggle:focus{box-shadow:0 0 0 .2rem rgba(52,58,64,.5)}.btn-link{font-weight:400;color:#007bff;background-color:transparent}.btn-link:hover{color:#0056b3;text-decoration:underline;background-color:transparent;border-color:transparent}.btn-link.focus,.btn-link:focus{text-decoration:underline;border-color:transparent;box-shadow:none}.btn-link.disabled,.btn-link:disabled{color:#6c757d;pointer-events:none}.btn-group-lg>.btn,.btn-lg{padding:.5rem 1rem;font-size:1.25rem;line-height:1.5;border-radius:.3rem}.btn-group-sm>.btn,.btn-sm{padding:.25rem .5rem;font-size:.875rem;line-height:1.5;border-radius:.2rem}.btn-block{display:block;width:100%}.btn-block+.btn-block{margin-top:.5rem}input[type=button].btn-block,input[type=reset].btn-block,input[type=submit].btn-block{width:100%}.fade{transition:opacity .15s linear}@media screen and (prefers-reduced-motion:reduce){.fade{transition:none}}.fade:not(.show){opacity:0}.collapse:not(.show){display:none}.collapsing{position:relative;height:0;overflow:hidden;transition:height .35s ease}@media screen and (prefers-reduced-motion:reduce){.collapsing{transition:none}}.dropdown,.dropleft,.dropright,.dropup{position:relative}.dropdown-toggle::after{display:inline-block;width:0;height:0;margin-left:.255em;vertical-align:.255em;content:"";border-top:.3em solid;border-right:.3em solid transparent;border-bottom:0;border-left:.3em solid transparent}.dropdown-toggle:empty::after{margin-left:0}.dropdown-menu{position:absolute;top:100%;left:0;z-index:1000;display:none;float:left;min-width:10rem;padding:.5rem 0;margin:.125rem 0 0;font-size:1rem;color:#212529;text-align:left;list-style:none;background-color:#fff;background-clip:padding-box;border:1px solid rgba(0,0,0,.15);border-radius:.25rem}.dropdown-menu-right{right:0;left:auto}.dropup .dropdown-menu{top:auto;bottom:100%;margin-top:0;margin-bottom:.125rem}.dropup .dropdown-toggle::after{display:inline-block;width:0;height:0;margin-left:.255em;vertical-align:.255em;content:"";border-top:0;border-right:.3em solid transparent;border-bottom:.3em solid;border-left:.3em solid transparent}.dropup .dropdown-toggle:empty::after{margin-left:0}.dropright .dropdown-menu{top:0;right:auto;left:100%;margin-top:0;margin-left:.125rem}.dropright .dropdown-toggle::after{display:inline-block;width:0;height:0;margin-left:.255em;vertical-align:.255em;content:"";border-top:.3em solid transparent;border-right:0;border-bottom:.3em solid transparent;border-left:.3em solid}.dropright .dropdown-toggle:empty::after{margin-left:0}.dropright .dropdown-toggle::after{vertical-align:0}.dropleft .dropdown-menu{top:0;right:100%;left:auto;margin-top:0;margin-right:.125rem}.dropleft .dropdown-toggle::after{display:inline-block;width:0;height:0;margin-left:.255em;vertical-align:.255em;content:""}.dropleft .dropdown-toggle::after{display:none}.dropleft .dropdown-toggle::before{display:inline-block;width:0;height:0;margin-right:.255em;vertical-align:.255em;content:"";border-top:.3em solid transparent;border-right:.3em solid;border-bottom:.3em solid transparent}.dropleft .dropdown-toggle:empty::after{margin-left:0}.dropleft .dropdown-toggle::before{vertical-align:0}.dropdown-menu[x-placement^=bottom],.dropdown-menu[x-placement^=left],.dropdown-menu[x-placement^=right],.dropdown-menu[x-placement^=top]{right:auto;bottom:auto}.dropdown-divider{height:0;margin:.5rem 0;overflow:hidden;border-top:1px solid #e9ecef}.dropdown-item{display:block;width:100%;padding:.25rem 1.5rem;clear:both;font-weight:400;color:#212529;text-align:inherit;white-space:nowrap;background-color:transparent;border:0}.dropdown-item:focus,.dropdown-item:hover{color:#16181b;text-decoration:none;background-color:#f8f9fa}.dropdown-item.active,.dropdown-item:active{color:#fff;text-decoration:none;background-color:#007bff}.dropdown-item.disabled,.dropdown-item:disabled{color:#6c757d;background-color:transparent}.dropdown-menu.show{display:block}.dropdown-header{display:block;padding:.5rem 1.5rem;margin-bottom:0;font-size:.875rem;color:#6c757d;white-space:nowrap}.dropdown-item-text{display:block;padding:.25rem 1.5rem;color:#212529}.btn-group,.btn-group-vertical{position:relative;display:-ms-inline-flexbox;display:inline-flex;vertical-align:middle}.btn-group-vertical>.btn,.btn-group>.btn{position:relative;-ms-flex:0 1 auto;flex:0 1 auto}.btn-group-vertical>.btn:hover,.btn-group>.btn:hover{z-index:1}.btn-group-vertical>.btn.active,.btn-group-vertical>.btn:active,.btn-group-vertical>.btn:focus,.btn-group>.btn.active,.btn-group>.btn:active,.btn-group>.btn:focus{z-index:1}.btn-group .btn+.btn,.btn-group .btn+.btn-group,.btn-group .btn-group+.btn,.btn-group .btn-group+.btn-group,.btn-group-vertical .btn+.btn,.btn-group-vertical .btn+.btn-group,.btn-group-vertical .btn-group+.btn,.btn-group-vertical .btn-group+.btn-group{margin-left:-1px}.btn-toolbar{display:-ms-flexbox;display:flex;-ms-flex-wrap:wrap;flex-wrap:wrap;-ms-flex-pack:start;justify-content:flex-start}.btn-toolbar .input-group{width:auto}.btn-group>.btn:first-child{margin-left:0}.btn-group>.btn-group:not(:last-child)>.btn,.btn-group>.btn:not(:last-child):not(.dropdown-toggle){border-top-right-radius:0;border-bottom-right-radius:0}.btn-group>.btn-group:not(:first-child)>.btn,.btn-group>.btn:not(:first-child){border-top-left-radius:0;border-bottom-left-radius:0}.dropdown-toggle-split{padding-right:.5625rem;padding-left:.5625rem}.dropdown-toggle-split::after,.dropright .dropdown-toggle-split::after,.dropup .dropdown-toggle-split::after{margin-left:0}.dropleft .dropdown-toggle-split::before{margin-right:0}.btn-group-sm>.btn+.dropdown-toggle-split,.btn-sm+.dropdown-toggle-split{padding-right:.375rem;padding-left:.375rem}.btn-group-lg>.btn+.dropdown-toggle-split,.btn-lg+.dropdown-toggle-split{padding-right:.75rem;padding-left:.75rem}.btn-group-vertical{-ms-flex-direction:column;flex-direction:column;-ms-flex-align:start;align-items:flex-start;-ms-flex-pack:center;justify-content:center}.btn-group-vertical .btn,.btn-group-vertical .btn-group{width:100%}.btn-group-vertical>.btn+.btn,.btn-group-vertical>.btn+.btn-group,.btn-group-vertical>.btn-group+.btn,.btn-group-vertical>.btn-group+.btn-group{margin-top:-1px;margin-left:0}.btn-group-vertical>.btn-group:not(:last-child)>.btn,.btn-group-vertical>.btn:not(:last-child):not(.dropdown-toggle){border-bottom-right-radius:0;border-bottom-left-radius:0}.btn-group-vertical>.btn-group:not(:first-child)>.btn,.btn-group-vertical>.btn:not(:first-child){border-top-left-radius:0;border-top-right-radius:0}.btn-group-toggle>.btn,.btn-group-toggle>.btn-group>.btn{margin-bottom:0}.btn-group-toggle>.btn input[type=checkbox],.btn-group-toggle>.btn input[type=radio],.btn-group-toggle>.btn-group>.btn input[type=checkbox],.btn-group-toggle>.btn-group>.btn input[type=radio]{position:absolute;clip:rect(0,0,0,0);pointer-events:none}.input-group{position:relative;display:-ms-flexbox;display:flex;-ms-flex-wrap:wrap;flex-wrap:wrap;-ms-flex-align:stretch;align-items:stretch;width:100%}.input-group>.custom-file,.input-group>.custom-select,.input-group>.form-control{position:relative;-ms-flex:1 1 auto;flex:1 1 auto;width:1%;margin-bottom:0}.input-group>.custom-file+.custom-file,.input-group>.custom-file+.custom-select,.input-group>.custom-file+.form-control,.input-group>.custom-select+.custom-file,.input-group>.custom-select+.custom-select,.input-group>.custom-select+.form-control,.input-group>.form-control+.custom-file,.input-group>.form-control+.custom-select,.input-group>.form-control+.form-control{margin-left:-1px}.input-group>.custom-file .custom-file-input:focus~.custom-file-label,.input-group>.custom-select:focus,.input-group>.form-control:focus{z-index:3}.input-group>.custom-file .custom-file-input:focus{z-index:4}.input-group>.custom-select:not(:last-child),.input-group>.form-control:not(:last-child){border-top-right-radius:0;border-bottom-right-radius:0}.input-group>.custom-select:not(:first-child),.input-group>.form-control:not(:first-child){border-top-left-radius:0;border-bottom-left-radius:0}.input-group>.custom-file{display:-ms-flexbox;display:flex;-ms-flex-align:center;align-items:center}.input-group>.custom-file:not(:last-child) .custom-file-label,.input-group>.custom-file:not(:last-child) .custom-file-label::after{border-top-right-radius:0;border-bottom-right-radius:0}.input-group>.custom-file:not(:first-child) .custom-file-label{border-top-left-radius:0;border-bottom-left-radius:0}.input-group-append,.input-group-prepend{display:-ms-flexbox;display:flex}.input-group-append .btn,.input-group-prepend .btn{position:relative;z-index:2}.input-group-append .btn+.btn,.input-group-append .btn+.input-group-text,.input-group-append .input-group-text+.btn,.input-group-append .input-group-text+.input-group-text,.input-group-prepend .btn+.btn,.input-group-prepend .btn+.input-group-text,.input-group-prepend .input-group-text+.btn,.input-group-prepend .input-group-text+.input-group-text{margin-left:-1px}.input-group-prepend{margin-right:-1px}.input-group-append{margin-left:-1px}.input-group-text{display:-ms-flexbox;display:flex;-ms-flex-align:center;align-items:center;padding:.375rem .75rem;margin-bottom:0;font-size:1rem;font-weight:400;line-height:1.5;color:#495057;text-align:center;white-space:nowrap;background-color:#e9ecef;border:1px solid #ced4da;border-radius:.25rem}.input-group-text input[type=checkbox],.input-group-text input[type=radio]{margin-top:0}.input-group-lg>.form-control,.input-group-lg>.input-group-append>.btn,.input-group-lg>.input-group-append>.input-group-text,.input-group-lg>.input-group-prepend>.btn,.input-group-lg>.input-group-prepend>.input-group-text{height:calc(2.875rem + 2px);padding:.5rem 1rem;font-size:1.25rem;line-height:1.5;border-radius:.3rem}.input-group-sm>.form-control,.input-group-sm>.input-group-append>.btn,.input-group-sm>.input-group-append>.input-group-text,.input-group-sm>.input-group-prepend>.btn,.input-group-sm>.input-group-prepend>.input-group-text{height:calc(1.8125rem + 2px);padding:.25rem .5rem;font-size:.875rem;line-height:1.5;border-radius:.2rem}.input-group>.input-group-append:last-child>.btn:not(:last-child):not(.dropdown-toggle),.input-group>.input-group-append:last-child>.input-group-text:not(:last-child),.input-group>.input-group-append:not(:last-child)>.btn,.input-group>.input-group-append:not(:last-child)>.input-group-text,.input-group>.input-group-prepend>.btn,.input-group>.input-group-prepend>.input-group-text{border-top-right-radius:0;border-bottom-right-radius:0}.input-group>.input-group-append>.btn,.input-group>.input-group-append>.input-group-text,.input-group>.input-group-prepend:first-child>.btn:not(:first-child),.input-group>.input-group-prepend:first-child>.input-group-text:not(:first-child),.input-group>.input-group-prepend:not(:first-child)>.btn,.input-group>.input-group-prepend:not(:first-child)>.input-group-text{border-top-left-radius:0;border-bottom-left-radius:0}.custom-control{position:relative;display:block;min-height:1.5rem;padding-left:1.5rem}.custom-control-inline{display:-ms-inline-flexbox;display:inline-flex;margin-right:1rem}.custom-control-input{position:absolute;z-index:-1;opacity:0}.custom-control-input:checked~.custom-control-label::before{color:#fff;background-color:#007bff}.custom-control-input:focus~.custom-control-label::before{box-shadow:0 0 0 1px #fff,0 0 0 .2rem rgba(0,123,255,.25)}.custom-control-input:active~.custom-control-label::before{color:#fff;background-color:#b3d7ff}.custom-control-input:disabled~.custom-control-label{color:#6c757d}.custom-control-input:disabled~.custom-control-label::before{background-color:#e9ecef}.custom-control-label{position:relative;margin-bottom:0}.custom-control-label::before{position:absolute;top:.25rem;left:-1.5rem;display:block;width:1rem;height:1rem;pointer-events:none;content:"";-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none;background-color:#dee2e6}.custom-control-label::after{position:absolute;top:.25rem;left:-1.5rem;display:block;width:1rem;height:1rem;content:"";background-repeat:no-repeat;background-position:center center;background-size:50% 50%}.custom-checkbox .custom-control-label::before{border-radius:.25rem}.custom-checkbox .custom-control-input:checked~.custom-control-label::before{background-color:#007bff}.custom-checkbox .custom-control-input:checked~.custom-control-label::after{background-image:url("data:image/svg+xml;charset=utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 8 8'%3E%3Cpath fill='%23fff' d='M6.564.75l-3.59 3.612-1.538-1.55L0 4.26 2.974 7.25 8 2.193z'/%3E%3C/svg%3E")}.custom-checkbox .custom-control-input:indeterminate~.custom-control-label::before{background-color:#007bff}.custom-checkbox .custom-control-input:indeterminate~.custom-control-label::after{background-image:url("data:image/svg+xml;charset=utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 4 4'%3E%3Cpath stroke='%23fff' d='M0 2h4'/%3E%3C/svg%3E")}.custom-checkbox .custom-control-input:disabled:checked~.custom-control-label::before{background-color:rgba(0,123,255,.5)}.custom-checkbox .custom-control-input:disabled:indeterminate~.custom-control-label::before{background-color:rgba(0,123,255,.5)}.custom-radio .custom-control-label::before{border-radius:50%}.custom-radio .custom-control-input:checked~.custom-control-label::before{background-color:#007bff}.custom-radio .custom-control-input:checked~.custom-control-label::after{background-image:url("data:image/svg+xml;charset=utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='-4 -4 8 8'%3E%3Ccircle r='3' fill='%23fff'/%3E%3C/svg%3E")}.custom-radio .custom-control-input:disabled:checked~.custom-control-label::before{background-color:rgba(0,123,255,.5)}.custom-select{display:inline-block;width:100%;height:calc(2.25rem + 2px);padding:.375rem 1.75rem .375rem .75rem;line-height:1.5;color:#495057;vertical-align:middle;background:#fff url("data:image/svg+xml;charset=utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 4 5'%3E%3Cpath fill='%23343a40' d='M2 0L0 2h4zm0 5L0 3h4z'/%3E%3C/svg%3E") no-repeat right .75rem center;background-size:8px 10px;border:1px solid #ced4da;border-radius:.25rem;-webkit-appearance:none;-moz-appearance:none;appearance:none}.custom-select:focus{border-color:#80bdff;outline:0;box-shadow:0 0 0 .2rem rgba(128,189,255,.5)}.custom-select:focus::-ms-value{color:#495057;background-color:#fff}.custom-select[multiple],.custom-select[size]:not([size="1"]){height:auto;padding-right:.75rem;background-image:none}.custom-select:disabled{color:#6c757d;background-color:#e9ecef}.custom-select::-ms-expand{opacity:0}.custom-select-sm{height:calc(1.8125rem + 2px);padding-top:.375rem;padding-bottom:.375rem;font-size:75%}.custom-select-lg{height:calc(2.875rem + 2px);padding-top:.375rem;padding-bottom:.375rem;font-size:125%}.custom-file{position:relative;display:inline-block;width:100%;height:calc(2.25rem + 2px);margin-bottom:0}.custom-file-input{position:relative;z-index:2;width:100%;height:calc(2.25rem + 2px);margin:0;opacity:0}.custom-file-input:focus~.custom-file-label{border-color:#80bdff;box-shadow:0 0 0 .2rem rgba(0,123,255,.25)}.custom-file-input:focus~.custom-file-label::after{border-color:#80bdff}.custom-file-input:disabled~.custom-file-label{background-color:#e9ecef}.custom-file-input:lang(en)~.custom-file-label::after{content:"Browse"}.custom-file-label{position:absolute;top:0;right:0;left:0;z-index:1;height:calc(2.25rem + 2px);padding:.375rem .75rem;line-height:1.5;color:#495057;background-color:#fff;border:1px solid #ced4da;border-radius:.25rem}.custom-file-label::after{position:absolute;top:0;right:0;bottom:0;z-index:3;display:block;height:2.25rem;padding:.375rem .75rem;line-height:1.5;color:#495057;content:"Browse";background-color:#e9ecef;border-left:1px solid #ced4da;border-radius:0 .25rem .25rem 0}.custom-range{width:100%;padding-left:0;background-color:transparent;-webkit-appearance:none;-moz-appearance:none;appearance:none}.custom-range:focus{outline:0}.custom-range:focus::-webkit-slider-thumb{box-shadow:0 0 0 1px #fff,0 0 0 .2rem rgba(0,123,255,.25)}.custom-range:focus::-moz-range-thumb{box-shadow:0 0 0 1px #fff,0 0 0 .2rem rgba(0,123,255,.25)}.custom-range:focus::-ms-thumb{box-shadow:0 0 0 1px #fff,0 0 0 .2rem rgba(0,123,255,.25)}.custom-range::-moz-focus-outer{border:0}.custom-range::-webkit-slider-thumb{width:1rem;height:1rem;margin-top:-.25rem;background-color:#007bff;border:0;border-radius:1rem;transition:background-color .15s ease-in-out,border-color .15s ease-in-out,box-shadow .15s ease-in-out;-webkit-appearance:none;appearance:none}@media screen and (prefers-reduced-motion:reduce){.custom-range::-webkit-slider-thumb{transition:none}}.custom-range::-webkit-slider-thumb:active{background-color:#b3d7ff}.custom-range::-webkit-slider-runnable-track{width:100%;height:.5rem;color:transparent;cursor:pointer;background-color:#dee2e6;border-color:transparent;border-radius:1rem}.custom-range::-moz-range-thumb{width:1rem;height:1rem;background-color:#007bff;border:0;border-radius:1rem;transition:background-color .15s ease-in-out,border-color .15s ease-in-out,box-shadow .15s ease-in-out;-moz-appearance:none;appearance:none}@media screen and (prefers-reduced-motion:reduce){.custom-range::-moz-range-thumb{transition:none}}.custom-range::-moz-range-thumb:active{background-color:#b3d7ff}.custom-range::-moz-range-track{width:100%;height:.5rem;color:transparent;cursor:pointer;background-color:#dee2e6;border-color:transparent;border-radius:1rem}.custom-range::-ms-thumb{width:1rem;height:1rem;margin-top:0;margin-right:.2rem;margin-left:.2rem;background-color:#007bff;border:0;border-radius:1rem;transition:background-color .15s ease-in-out,border-color .15s ease-in-out,box-shadow .15s ease-in-out;appearance:none}@media screen and (prefers-reduced-motion:reduce){.custom-range::-ms-thumb{transition:none}}.custom-range::-ms-thumb:active{background-color:#b3d7ff}.custom-range::-ms-track{width:100%;height:.5rem;color:transparent;cursor:pointer;background-color:transparent;border-color:transparent;border-width:.5rem}.custom-range::-ms-fill-lower{background-color:#dee2e6;border-radius:1rem}.custom-range::-ms-fill-upper{margin-right:15px;background-color:#dee2e6;border-radius:1rem}.custom-control-label::before,.custom-file-label,.custom-select{transition:background-color .15s ease-in-out,border-color .15s ease-in-out,box-shadow .15s ease-in-out}@media screen and (prefers-reduced-motion:reduce){.custom-control-label::before,.custom-file-label,.custom-select{transition:none}}.nav{display:-ms-flexbox;display:flex;-ms-flex-wrap:wrap;flex-wrap:wrap;padding-left:0;margin-bottom:0;list-style:none}.nav-link{display:block;padding:.5rem 1rem}.nav-link:focus,.nav-link:hover{text-decoration:none}.nav-link.disabled{color:#6c757d}.nav-tabs{border-bottom:1px solid #dee2e6}.nav-tabs .nav-item{margin-bottom:-1px}.nav-tabs .nav-link{border:1px solid transparent;border-top-left-radius:.25rem;border-top-right-radius:.25rem}.nav-tabs .nav-link:focus,.nav-tabs .nav-link:hover{border-color:#e9ecef #e9ecef #dee2e6}.nav-tabs .nav-link.disabled{color:#6c757d;background-color:transparent;border-color:transparent}.nav-tabs .nav-item.show .nav-link,.nav-tabs .nav-link.active{color:#495057;background-color:#fff;border-color:#dee2e6 #dee2e6 #fff}.nav-tabs .dropdown-menu{margin-top:-1px;border-top-left-radius:0;border-top-right-radius:0}.nav-pills .nav-link{border-radius:.25rem}.nav-pills .nav-link.active,.nav-pills .show>.nav-link{color:#fff;background-color:#007bff}.nav-fill .nav-item{-ms-flex:1 1 auto;flex:1 1 auto;text-align:center}.nav-justified .nav-item{-ms-flex-preferred-size:0;flex-basis:0;-ms-flex-positive:1;flex-grow:1;text-align:center}.tab-content>.tab-pane{display:none}.tab-content>.active{display:block}.navbar{position:relative;display:-ms-flexbox;display:flex;-ms-flex-wrap:wrap;flex-wrap:wrap;-ms-flex-align:center;align-items:center;-ms-flex-pack:justify;justify-content:space-between;padding:.5rem 1rem}.navbar>.container,.navbar>.container-fluid{display:-ms-flexbox;display:flex;-ms-flex-wrap:wrap;flex-wrap:wrap;-ms-flex-align:center;align-items:center;-ms-flex-pack:justify;justify-content:space-between}.navbar-brand{display:inline-block;padding-top:.3125rem;padding-bottom:.3125rem;margin-right:1rem;font-size:1.25rem;line-height:inherit;white-space:nowrap}.navbar-brand:focus,.navbar-brand:hover{text-decoration:none}.navbar-nav{display:-ms-flexbox;display:flex;-ms-flex-direction:column;flex-direction:column;padding-left:0;margin-bottom:0;list-style:none}.navbar-nav .nav-link{padding-right:0;padding-left:0}.navbar-nav .dropdown-menu{position:static;float:none}.navbar-text{display:inline-block;padding-top:.5rem;padding-bottom:.5rem}.navbar-collapse{-ms-flex-preferred-size:100%;flex-basis:100%;-ms-flex-positive:1;flex-grow:1;-ms-flex-align:center;align-items:center}.navbar-toggler{padding:.25rem .75rem;font-size:1.25rem;line-height:1;background-color:transparent;border:1px solid transparent;border-radius:.25rem}.navbar-toggler:focus,.navbar-toggler:hover{text-decoration:none}.navbar-toggler:not(:disabled):not(.disabled){cursor:pointer}.navbar-toggler-icon{display:inline-block;width:1.5em;height:1.5em;vertical-align:middle;content:"";background:no-repeat center center;background-size:100% 100%}@media (max-width:575.98px){.navbar-expand-sm>.container,.navbar-expand-sm>.container-fluid{padding-right:0;padding-left:0}}@media (min-width:576px){.navbar-expand-sm{-ms-flex-flow:row nowrap;flex-flow:row nowrap;-ms-flex-pack:start;justify-content:flex-start}.navbar-expand-sm .navbar-nav{-ms-flex-direction:row;flex-direction:row}.navbar-expand-sm .navbar-nav .dropdown-menu{position:absolute}.navbar-expand-sm .navbar-nav .nav-link{padding-right:.5rem;padding-left:.5rem}.navbar-expand-sm>.container,.navbar-expand-sm>.container-fluid{-ms-flex-wrap:nowrap;flex-wrap:nowrap}.navbar-expand-sm .navbar-collapse{display:-ms-flexbox!important;display:flex!important;-ms-flex-preferred-size:auto;flex-basis:auto}.navbar-expand-sm .navbar-toggler{display:none}}@media (max-width:767.98px){.navbar-expand-md>.container,.navbar-expand-md>.container-fluid{padding-right:0;padding-left:0}}@media (min-width:768px){.navbar-expand-md{-ms-flex-flow:row nowrap;flex-flow:row nowrap;-ms-flex-pack:start;justify-content:flex-start}.navbar-expand-md .navbar-nav{-ms-flex-direction:row;flex-direction:row}.navbar-expand-md .navbar-nav .dropdown-menu{position:absolute}.navbar-expand-md .navbar-nav .nav-link{padding-right:.5rem;padding-left:.5rem}.navbar-expand-md>.container,.navbar-expand-md>.container-fluid{-ms-flex-wrap:nowrap;flex-wrap:nowrap}.navbar-expand-md .navbar-collapse{display:-ms-flexbox!important;display:flex!important;-ms-flex-preferred-size:auto;flex-basis:auto}.navbar-expand-md .navbar-toggler{display:none}}@media (max-width:991.98px){.navbar-expand-lg>.container,.navbar-expand-lg>.container-fluid{padding-right:0;padding-left:0}}@media (min-width:992px){.navbar-expand-lg{-ms-flex-flow:row nowrap;flex-flow:row nowrap;-ms-flex-pack:start;justify-content:flex-start}.navbar-expand-lg .navbar-nav{-ms-flex-direction:row;flex-direction:row}.navbar-expand-lg .navbar-nav .dropdown-menu{position:absolute}.navbar-expand-lg .navbar-nav .nav-link{padding-right:.5rem;padding-left:.5rem}.navbar-expand-lg>.container,.navbar-expand-lg>.container-fluid{-ms-flex-wrap:nowrap;flex-wrap:nowrap}.navbar-expand-lg .navbar-collapse{display:-ms-flexbox!important;display:flex!important;-ms-flex-preferred-size:auto;flex-basis:auto}.navbar-expand-lg .navbar-toggler{display:none}}@media (max-width:1199.98px){.navbar-expand-xl>.container,.navbar-expand-xl>.container-fluid{padding-right:0;padding-left:0}}@media (min-width:1200px){.navbar-expand-xl{-ms-flex-flow:row nowrap;flex-flow:row nowrap;-ms-flex-pack:start;justify-content:flex-start}.navbar-expand-xl .navbar-nav{-ms-flex-direction:row;flex-direction:row}.navbar-expand-xl .navbar-nav .dropdown-menu{position:absolute}.navbar-expand-xl .navbar-nav .nav-link{padding-right:.5rem;padding-left:.5rem}.navbar-expand-xl>.container,.navbar-expand-xl>.container-fluid{-ms-flex-wrap:nowrap;flex-wrap:nowrap}.navbar-expand-xl .navbar-collapse{display:-ms-flexbox!important;display:flex!important;-ms-flex-preferred-size:auto;flex-basis:auto}.navbar-expand-xl .navbar-toggler{display:none}}.navbar-expand{-ms-flex-flow:row nowrap;flex-flow:row nowrap;-ms-flex-pack:start;justify-content:flex-start}.navbar-expand>.container,.navbar-expand>.container-fluid{padding-right:0;padding-left:0}.navbar-expand .navbar-nav{-ms-flex-direction:row;flex-direction:row}.navbar-expand .navbar-nav .dropdown-menu{position:absolute}.navbar-expand .navbar-nav .nav-link{padding-right:.5rem;padding-left:.5rem}.navbar-expand>.container,.navbar-expand>.container-fluid{-ms-flex-wrap:nowrap;flex-wrap:nowrap}.navbar-expand .navbar-collapse{display:-ms-flexbox!important;display:flex!important;-ms-flex-preferred-size:auto;flex-basis:auto}.navbar-expand .navbar-toggler{display:none}.navbar-light .navbar-brand{color:rgba(0,0,0,.9)}.navbar-light .navbar-brand:focus,.navbar-light .navbar-brand:hover{color:rgba(0,0,0,.9)}.navbar-light .navbar-nav .nav-link{color:rgba(0,0,0,.5)}.navbar-light .navbar-nav .nav-link:focus,.navbar-light .navbar-nav .nav-link:hover{color:rgba(0,0,0,.7)}.navbar-light .navbar-nav .nav-link.disabled{color:rgba(0,0,0,.3)}.navbar-light .navbar-nav .active>.nav-link,.navbar-light .navbar-nav .nav-link.active,.navbar-light .navbar-nav .nav-link.show,.navbar-light .navbar-nav .show>.nav-link{color:rgba(0,0,0,.9)}.navbar-light .navbar-toggler{color:rgba(0,0,0,.5);border-color:rgba(0,0,0,.1)}.navbar-light .navbar-toggler-icon{background-image:url("data:image/svg+xml;charset=utf8,%3Csvg viewBox='0 0 30 30' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath stroke='rgba(0, 0, 0, 0.5)' stroke-width='2' stroke-linecap='round' stroke-miterlimit='10' d='M4 7h22M4 15h22M4 23h22'/%3E%3C/svg%3E")}.navbar-light .navbar-text{color:rgba(0,0,0,.5)}.navbar-light .navbar-text a{color:rgba(0,0,0,.9)}.navbar-light .navbar-text a:focus,.navbar-light .navbar-text a:hover{color:rgba(0,0,0,.9)}.navbar-dark .navbar-brand{color:#fff}.navbar-dark .navbar-brand:focus,.navbar-dark .navbar-brand:hover{color:#fff}.navbar-dark .navbar-nav .nav-link{color:rgba(255,255,255,.5)}.navbar-dark .navbar-nav .nav-link:focus,.navbar-dark .navbar-nav .nav-link:hover{color:rgba(255,255,255,.75)}.navbar-dark .navbar-nav .nav-link.disabled{color:rgba(255,255,255,.25)}.navbar-dark .navbar-nav .active>.nav-link,.navbar-dark .navbar-nav .nav-link.active,.navbar-dark .navbar-nav .nav-link.show,.navbar-dark .navbar-nav .show>.nav-link{color:#fff}.navbar-dark .navbar-toggler{color:rgba(255,255,255,.5);border-color:rgba(255,255,255,.1)}.navbar-dark .navbar-toggler-icon{background-image:url("data:image/svg+xml;charset=utf8,%3Csvg viewBox='0 0 30 30' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath stroke='rgba(255, 255, 255, 0.5)' stroke-width='2' stroke-linecap='round' stroke-miterlimit='10' d='M4 7h22M4 15h22M4 23h22'/%3E%3C/svg%3E")}.navbar-dark .navbar-text{color:rgba(255,255,255,.5)}.navbar-dark .navbar-text a{color:#fff}.navbar-dark .navbar-text a:focus,.navbar-dark .navbar-text a:hover{color:#fff}.card{position:relative;display:-ms-flexbox;display:flex;-ms-flex-direction:column;flex-direction:column;min-width:0;word-wrap:break-word;background-color:#fff;background-clip:border-box;border:1px solid rgba(0,0,0,.125);border-radius:.25rem}.card>hr{margin-right:0;margin-left:0}.card>.list-group:first-child .list-group-item:first-child{border-top-left-radius:.25rem;border-top-right-radius:.25rem}.card>.list-group:last-child .list-group-item:last-child{border-bottom-right-radius:.25rem;border-bottom-left-radius:.25rem}.card-body{-ms-flex:1 1 auto;flex:1 1 auto;padding:1.25rem}.card-title{margin-bottom:.75rem}.card-subtitle{margin-top:-.375rem;margin-bottom:0}.card-text:last-child{margin-bottom:0}.card-link:hover{text-decoration:none}.card-link+.card-link{margin-left:1.25rem}.card-header{padding:.75rem 1.25rem;margin-bottom:0;background-color:rgba(0,0,0,.03);border-bottom:1px solid rgba(0,0,0,.125)}.card-header:first-child{border-radius:calc(.25rem - 1px) calc(.25rem - 1px) 0 0}.card-header+.list-group .list-group-item:first-child{border-top:0}.card-footer{padding:.75rem 1.25rem;background-color:rgba(0,0,0,.03);border-top:1px solid rgba(0,0,0,.125)}.card-footer:last-child{border-radius:0 0 calc(.25rem - 1px) calc(.25rem - 1px)}.card-header-tabs{margin-right:-.625rem;margin-bottom:-.75rem;margin-left:-.625rem;border-bottom:0}.card-header-pills{margin-right:-.625rem;margin-left:-.625rem}.card-img-overlay{position:absolute;top:0;right:0;bottom:0;left:0;padding:1.25rem}.card-img{width:100%;border-radius:calc(.25rem - 1px)}.card-img-top{width:100%;border-top-left-radius:calc(.25rem - 1px);border-top-right-radius:calc(.25rem - 1px)}.card-img-bottom{width:100%;border-bottom-right-radius:calc(.25rem - 1px);border-bottom-left-radius:calc(.25rem - 1px)}.card-deck{display:-ms-flexbox;display:flex;-ms-flex-direction:column;flex-direction:column}.card-deck .card{margin-bottom:15px}@media (min-width:576px){.card-deck{-ms-flex-flow:row wrap;flex-flow:row wrap;margin-right:-15px;margin-left:-15px}.card-deck .card{display:-ms-flexbox;display:flex;-ms-flex:1 0 0%;flex:1 0 0%;-ms-flex-direction:column;flex-direction:column;margin-right:15px;margin-bottom:0;margin-left:15px}}.card-group{display:-ms-flexbox;display:flex;-ms-flex-direction:column;flex-direction:column}.card-group>.card{margin-bottom:15px}@media (min-width:576px){.card-group{-ms-flex-flow:row wrap;flex-flow:row wrap}.card-group>.card{-ms-flex:1 0 0%;flex:1 0 0%;margin-bottom:0}.card-group>.card+.card{margin-left:0;border-left:0}.card-group>.card:first-child{border-top-right-radius:0;border-bottom-right-radius:0}.card-group>.card:first-child .card-header,.card-group>.card:first-child .card-img-top{border-top-right-radius:0}.card-group>.card:first-child .card-footer,.card-group>.card:first-child .card-img-bottom{border-bottom-right-radius:0}.card-group>.card:last-child{border-top-left-radius:0;border-bottom-left-radius:0}.card-group>.card:last-child .card-header,.card-group>.card:last-child .card-img-top{border-top-left-radius:0}.card-group>.card:last-child .card-footer,.card-group>.card:last-child .card-img-bottom{border-bottom-left-radius:0}.card-group>.card:only-child{border-radius:.25rem}.card-group>.card:only-child .card-header,.card-group>.card:only-child .card-img-top{border-top-left-radius:.25rem;border-top-right-radius:.25rem}.card-group>.card:only-child .card-footer,.card-group>.card:only-child .card-img-bottom{border-bottom-right-radius:.25rem;border-bottom-left-radius:.25rem}.card-group>.card:not(:first-child):not(:last-child):not(:only-child){border-radius:0}.card-group>.card:not(:first-child):not(:last-child):not(:only-child) .card-footer,.card-group>.card:not(:first-child):not(:last-child):not(:only-child) .card-header,.card-group>.card:not(:first-child):not(:last-child):not(:only-child) .card-img-bottom,.card-group>.card:not(:first-child):not(:last-child):not(:only-child) .card-img-top{border-radius:0}}.card-columns .card{margin-bottom:.75rem}@media (min-width:576px){.card-columns{-webkit-column-count:3;-moz-column-count:3;column-count:3;-webkit-column-gap:1.25rem;-moz-column-gap:1.25rem;column-gap:1.25rem;orphans:1;widows:1}.card-columns .card{display:inline-block;width:100%}}.accordion .card:not(:first-of-type):not(:last-of-type){border-bottom:0;border-radius:0}.accordion .card:not(:first-of-type) .card-header:first-child{border-radius:0}.accordion .card:first-of-type{border-bottom:0;border-bottom-right-radius:0;border-bottom-left-radius:0}.accordion .card:last-of-type{border-top-left-radius:0;border-top-right-radius:0}.breadcrumb{display:-ms-flexbox;display:flex;-ms-flex-wrap:wrap;flex-wrap:wrap;padding:.75rem 1rem;margin-bottom:1rem;list-style:none;background-color:#e9ecef;border-radius:.25rem}.breadcrumb-item+.breadcrumb-item{padding-left:.5rem}.breadcrumb-item+.breadcrumb-item::before{display:inline-block;padding-right:.5rem;color:#6c757d;content:"/"}.breadcrumb-item+.breadcrumb-item:hover::before{text-decoration:underline}.breadcrumb-item+.breadcrumb-item:hover::before{text-decoration:none}.breadcrumb-item.active{color:#6c757d}.pagination{display:-ms-flexbox;display:flex;padding-left:0;list-style:none;border-radius:.25rem}.page-link{position:relative;display:block;padding:.5rem .75rem;margin-left:-1px;line-height:1.25;color:#007bff;background-color:#fff;border:1px solid #dee2e6}.page-link:hover{z-index:2;color:#0056b3;text-decoration:none;background-color:#e9ecef;border-color:#dee2e6}.page-link:focus{z-index:2;outline:0;box-shadow:0 0 0 .2rem rgba(0,123,255,.25)}.page-link:not(:disabled):not(.disabled){cursor:pointer}.page-item:first-child .page-link{margin-left:0;border-top-left-radius:.25rem;border-bottom-left-radius:.25rem}.page-item:last-child .page-link{border-top-right-radius:.25rem;border-bottom-right-radius:.25rem}.page-item.active .page-link{z-index:1;color:#fff;background-color:#007bff;border-color:#007bff}.page-item.disabled .page-link{color:#6c757d;pointer-events:none;cursor:auto;background-color:#fff;border-color:#dee2e6}.pagination-lg .page-link{padding:.75rem 1.5rem;font-size:1.25rem;line-height:1.5}.pagination-lg .page-item:first-child .page-link{border-top-left-radius:.3rem;border-bottom-left-radius:.3rem}.pagination-lg .page-item:last-child .page-link{border-top-right-radius:.3rem;border-bottom-right-radius:.3rem}.pagination-sm .page-link{padding:.25rem .5rem;font-size:.875rem;line-height:1.5}.pagination-sm .page-item:first-child .page-link{border-top-left-radius:.2rem;border-bottom-left-radius:.2rem}.pagination-sm .page-item:last-child .page-link{border-top-right-radius:.2rem;border-bottom-right-radius:.2rem}.badge{display:inline-block;padding:.25em .4em;font-size:75%;font-weight:700;line-height:1;text-align:center;white-space:nowrap;vertical-align:baseline;border-radius:.25rem}.badge:empty{display:none}.btn .badge{position:relative;top:-1px}.badge-pill{padding-right:.6em;padding-left:.6em;border-radius:10rem}.badge-primary{color:#fff;background-color:#007bff}.badge-primary[href]:focus,.badge-primary[href]:hover{color:#fff;text-decoration:none;background-color:#0062cc}.badge-secondary{color:#fff;background-color:#6c757d}.badge-secondary[href]:focus,.badge-secondary[href]:hover{color:#fff;text-decoration:none;background-color:#545b62}.badge-success{color:#fff;background-color:#28a745}.badge-success[href]:focus,.badge-success[href]:hover{color:#fff;text-decoration:none;background-color:#1e7e34}.badge-info{color:#fff;background-color:#17a2b8}.badge-info[href]:focus,.badge-info[href]:hover{color:#fff;text-decoration:none;background-color:#117a8b}.badge-warning{color:#212529;background-color:#ffc107}.badge-warning[href]:focus,.badge-warning[href]:hover{color:#212529;text-decoration:none;background-color:#d39e00}.badge-danger{color:#fff;background-color:#dc3545}.badge-danger[href]:focus,.badge-danger[href]:hover{color:#fff;text-decoration:none;background-color:#bd2130}.badge-light{color:#212529;background-color:#f8f9fa}.badge-light[href]:focus,.badge-light[href]:hover{color:#212529;text-decoration:none;background-color:#dae0e5}.badge-dark{color:#fff;background-color:#343a40}.badge-dark[href]:focus,.badge-dark[href]:hover{color:#fff;text-decoration:none;background-color:#1d2124}.jumbotron{padding:2rem 1rem;margin-bottom:2rem;background-color:#e9ecef;border-radius:.3rem}@media (min-width:576px){.jumbotron{padding:4rem 2rem}}.jumbotron-fluid{padding-right:0;padding-left:0;border-radius:0}.alert{position:relative;padding:.75rem 1.25rem;margin-bottom:1rem;border:1px solid transparent;border-radius:.25rem}.alert-heading{color:inherit}.alert-link{font-weight:700}.alert-dismissible{padding-right:4rem}.alert-dismissible .close{position:absolute;top:0;right:0;padding:.75rem 1.25rem;color:inherit}.alert-primary{color:#004085;background-color:#cce5ff;border-color:#b8daff}.alert-primary hr{border-top-color:#9fcdff}.alert-primary .alert-link{color:#002752}.alert-secondary{color:#383d41;background-color:#e2e3e5;border-color:#d6d8db}.alert-secondary hr{border-top-color:#c8cbcf}.alert-secondary .alert-link{color:#202326}.alert-success{color:#155724;background-color:#d4edda;border-color:#c3e6cb}.alert-success hr{border-top-color:#b1dfbb}.alert-success .alert-link{color:#0b2e13}.alert-info{color:#0c5460;background-color:#d1ecf1;border-color:#bee5eb}.alert-info hr{border-top-color:#abdde5}.alert-info .alert-link{color:#062c33}.alert-warning{color:#856404;background-color:#fff3cd;border-color:#ffeeba}.alert-warning hr{border-top-color:#ffe8a1}.alert-warning .alert-link{color:#533f03}.alert-danger{color:#721c24;background-color:#f8d7da;border-color:#f5c6cb}.alert-danger hr{border-top-color:#f1b0b7}.alert-danger .alert-link{color:#491217}.alert-light{color:#818182;background-color:#fefefe;border-color:#fdfdfe}.alert-light hr{border-top-color:#ececf6}.alert-light .alert-link{color:#686868}.alert-dark{color:#1b1e21;background-color:#d6d8d9;border-color:#c6c8ca}.alert-dark hr{border-top-color:#b9bbbe}.alert-dark .alert-link{color:#040505}@-webkit-keyframes progress-bar-stripes{from{background-position:1rem 0}to{background-position:0 0}}@keyframes progress-bar-stripes{from{background-position:1rem 0}to{background-position:0 0}}.progress{display:-ms-flexbox;display:flex;height:1rem;overflow:hidden;font-size:.75rem;background-color:#e9ecef;border-radius:.25rem}.progress-bar{display:-ms-flexbox;display:flex;-ms-flex-direction:column;flex-direction:column;-ms-flex-pack:center;justify-content:center;color:#fff;text-align:center;white-space:nowrap;background-color:#007bff;transition:width .6s ease}@media screen and (prefers-reduced-motion:reduce){.progress-bar{transition:none}}.progress-bar-striped{background-image:linear-gradient(45deg,rgba(255,255,255,.15) 25%,transparent 25%,transparent 50%,rgba(255,255,255,.15) 50%,rgba(255,255,255,.15) 75%,transparent 75%,transparent);background-size:1rem 1rem}.progress-bar-animated{-webkit-animation:progress-bar-stripes 1s linear infinite;animation:progress-bar-stripes 1s linear infinite}.media{display:-ms-flexbox;display:flex;-ms-flex-align:start;align-items:flex-start}.media-body{-ms-flex:1;flex:1}.list-group{display:-ms-flexbox;display:flex;-ms-flex-direction:column;flex-direction:column;padding-left:0;margin-bottom:0}.list-group-item-action{width:100%;color:#495057;text-align:inherit}.list-group-item-action:focus,.list-group-item-action:hover{color:#495057;text-decoration:none;background-color:#f8f9fa}.list-group-item-action:active{color:#212529;background-color:#e9ecef}.list-group-item{position:relative;display:block;padding:.75rem 1.25rem;margin-bottom:-1px;background-color:#fff;border:1px solid rgba(0,0,0,.125)}.list-group-item:first-child{border-top-left-radius:.25rem;border-top-right-radius:.25rem}.list-group-item:last-child{margin-bottom:0;border-bottom-right-radius:.25rem;border-bottom-left-radius:.25rem}.list-group-item:focus,.list-group-item:hover{z-index:1;text-decoration:none}.list-group-item.disabled,.list-group-item:disabled{color:#6c757d;background-color:#fff}.list-group-item.active{z-index:2;color:#fff;background-color:#007bff;border-color:#007bff}.list-group-flush .list-group-item{border-right:0;border-left:0;border-radius:0}.list-group-flush:first-child .list-group-item:first-child{border-top:0}.list-group-flush:last-child .list-group-item:last-child{border-bottom:0}.list-group-item-primary{color:#004085;background-color:#b8daff}.list-group-item-primary.list-group-item-action:focus,.list-group-item-primary.list-group-item-action:hover{color:#004085;background-color:#9fcdff}.list-group-item-primary.list-group-item-action.active{color:#fff;background-color:#004085;border-color:#004085}.list-group-item-secondary{color:#383d41;background-color:#d6d8db}.list-group-item-secondary.list-group-item-action:focus,.list-group-item-secondary.list-group-item-action:hover{color:#383d41;background-color:#c8cbcf}.list-group-item-secondary.list-group-item-action.active{color:#fff;background-color:#383d41;border-color:#383d41}.list-group-item-success{color:#155724;background-color:#c3e6cb}.list-group-item-success.list-group-item-action:focus,.list-group-item-success.list-group-item-action:hover{color:#155724;background-color:#b1dfbb}.list-group-item-success.list-group-item-action.active{color:#fff;background-color:#155724;border-color:#155724}.list-group-item-info{color:#0c5460;background-color:#bee5eb}.list-group-item-info.list-group-item-action:focus,.list-group-item-info.list-group-item-action:hover{color:#0c5460;background-color:#abdde5}.list-group-item-info.list-group-item-action.active{color:#fff;background-color:#0c5460;border-color:#0c5460}.list-group-item-warning{color:#856404;background-color:#ffeeba}.list-group-item-warning.list-group-item-action:focus,.list-group-item-warning.list-group-item-action:hover{color:#856404;background-color:#ffe8a1}.list-group-item-warning.list-group-item-action.active{color:#fff;background-color:#856404;border-color:#856404}.list-group-item-danger{color:#721c24;background-color:#f5c6cb}.list-group-item-danger.list-group-item-action:focus,.list-group-item-danger.list-group-item-action:hover{color:#721c24;background-color:#f1b0b7}.list-group-item-danger.list-group-item-action.active{color:#fff;background-color:#721c24;border-color:#721c24}.list-group-item-light{color:#818182;background-color:#fdfdfe}.list-group-item-light.list-group-item-action:focus,.list-group-item-light.list-group-item-action:hover{color:#818182;background-color:#ececf6}.list-group-item-light.list-group-item-action.active{color:#fff;background-color:#818182;border-color:#818182}.list-group-item-dark{color:#1b1e21;background-color:#c6c8ca}.list-group-item-dark.list-group-item-action:focus,.list-group-item-dark.list-group-item-action:hover{color:#1b1e21;background-color:#b9bbbe}.list-group-item-dark.list-group-item-action.active{color:#fff;background-color:#1b1e21;border-color:#1b1e21}.close{float:right;font-size:1.5rem;font-weight:700;line-height:1;color:#000;text-shadow:0 1px 0 #fff;opacity:.5}.close:not(:disabled):not(.disabled){cursor:pointer}.close:not(:disabled):not(.disabled):focus,.close:not(:disabled):not(.disabled):hover{color:#000;text-decoration:none;opacity:.75}button.close{padding:0;background-color:transparent;border:0;-webkit-appearance:none}.modal-open{overflow:hidden}.modal-open .modal{overflow-x:hidden;overflow-y:auto}.modal{position:fixed;top:0;right:0;bottom:0;left:0;z-index:1050;display:none;overflow:hidden;outline:0}.modal-dialog{position:relative;width:auto;margin:.5rem;pointer-events:none}.modal.fade .modal-dialog{transition:-webkit-transform .3s ease-out;transition:transform .3s ease-out;transition:transform .3s ease-out,-webkit-transform .3s ease-out;-webkit-transform:translate(0,-25%);transform:translate(0,-25%)}@media screen and (prefers-reduced-motion:reduce){.modal.fade .modal-dialog{transition:none}}.modal.show .modal-dialog{-webkit-transform:translate(0,0);transform:translate(0,0)}.modal-dialog-centered{display:-ms-flexbox;display:flex;-ms-flex-align:center;align-items:center;min-height:calc(100% - (.5rem * 2))}.modal-dialog-centered::before{display:block;height:calc(100vh - (.5rem * 2));content:""}.modal-content{position:relative;display:-ms-flexbox;display:flex;-ms-flex-direction:column;flex-direction:column;width:100%;pointer-events:auto;background-color:#fff;background-clip:padding-box;border:1px solid rgba(0,0,0,.2);border-radius:.3rem;outline:0}.modal-backdrop{position:fixed;top:0;right:0;bottom:0;left:0;z-index:1040;background-color:#000}.modal-backdrop.fade{opacity:0}.modal-backdrop.show{opacity:.5}.modal-header{display:-ms-flexbox;display:flex;-ms-flex-align:start;align-items:flex-start;-ms-flex-pack:justify;justify-content:space-between;padding:1rem;border-bottom:1px solid #e9ecef;border-top-left-radius:.3rem;border-top-right-radius:.3rem}.modal-header .close{padding:1rem;margin:-1rem -1rem -1rem auto}.modal-title{margin-bottom:0;line-height:1.5}.modal-body{position:relative;-ms-flex:1 1 auto;flex:1 1 auto;padding:1rem}.modal-footer{display:-ms-flexbox;display:flex;-ms-flex-align:center;align-items:center;-ms-flex-pack:end;justify-content:flex-end;padding:1rem;border-top:1px solid #e9ecef}.modal-footer>:not(:first-child){margin-left:.25rem}.modal-footer>:not(:last-child){margin-right:.25rem}.modal-scrollbar-measure{position:absolute;top:-9999px;width:50px;height:50px;overflow:scroll}@media (min-width:576px){.modal-dialog{max-width:500px;margin:1.75rem auto}.modal-dialog-centered{min-height:calc(100% - (1.75rem * 2))}.modal-dialog-centered::before{height:calc(100vh - (1.75rem * 2))}.modal-sm{max-width:300px}}@media (min-width:992px){.modal-lg{max-width:800px}}.tooltip{position:absolute;z-index:1070;display:block;margin:0;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol","Noto Color Emoji";font-style:normal;font-weight:400;line-height:1.5;text-align:left;text-align:start;text-decoration:none;text-shadow:none;text-transform:none;letter-spacing:normal;word-break:normal;word-spacing:normal;white-space:normal;line-break:auto;font-size:.875rem;word-wrap:break-word;opacity:0}.tooltip.show{opacity:.9}.tooltip .arrow{position:absolute;display:block;width:.8rem;height:.4rem}.tooltip .arrow::before{position:absolute;content:"";border-color:transparent;border-style:solid}.bs-tooltip-auto[x-placement^=top],.bs-tooltip-top{padding:.4rem 0}.bs-tooltip-auto[x-placement^=top] .arrow,.bs-tooltip-top .arrow{bottom:0}.bs-tooltip-auto[x-placement^=top] .arrow::before,.bs-tooltip-top .arrow::before{top:0;border-width:.4rem .4rem 0;border-top-color:#000}.bs-tooltip-auto[x-placement^=right],.bs-tooltip-right{padding:0 .4rem}.bs-tooltip-auto[x-placement^=right] .arrow,.bs-tooltip-right .arrow{left:0;width:.4rem;height:.8rem}.bs-tooltip-auto[x-placement^=right] .arrow::before,.bs-tooltip-right .arrow::before{right:0;border-width:.4rem .4rem .4rem 0;border-right-color:#000}.bs-tooltip-auto[x-placement^=bottom],.bs-tooltip-bottom{padding:.4rem 0}.bs-tooltip-auto[x-placement^=bottom] .arrow,.bs-tooltip-bottom .arrow{top:0}.bs-tooltip-auto[x-placement^=bottom] .arrow::before,.bs-tooltip-bottom .arrow::before{bottom:0;border-width:0 .4rem .4rem;border-bottom-color:#000}.bs-tooltip-auto[x-placement^=left],.bs-tooltip-left{padding:0 .4rem}.bs-tooltip-auto[x-placement^=left] .arrow,.bs-tooltip-left .arrow{right:0;width:.4rem;height:.8rem}.bs-tooltip-auto[x-placement^=left] .arrow::before,.bs-tooltip-left .arrow::before{left:0;border-width:.4rem 0 .4rem .4rem;border-left-color:#000}.tooltip-inner{max-width:200px;padding:.25rem .5rem;color:#fff;text-align:center;background-color:#000;border-radius:.25rem}.popover{position:absolute;top:0;left:0;z-index:1060;display:block;max-width:276px;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol","Noto Color Emoji";font-style:normal;font-weight:400;line-height:1.5;text-align:left;text-align:start;text-decoration:none;text-shadow:none;text-transform:none;letter-spacing:normal;word-break:normal;word-spacing:normal;white-space:normal;line-break:auto;font-size:.875rem;word-wrap:break-word;background-color:#fff;background-clip:padding-box;border:1px solid rgba(0,0,0,.2);border-radius:.3rem}.popover .arrow{position:absolute;display:block;width:1rem;height:.5rem;margin:0 .3rem}.popover .arrow::after,.popover .arrow::before{position:absolute;display:block;content:"";border-color:transparent;border-style:solid}.bs-popover-auto[x-placement^=top],.bs-popover-top{margin-bottom:.5rem}.bs-popover-auto[x-placement^=top] .arrow,.bs-popover-top .arrow{bottom:calc((.5rem + 1px) * -1)}.bs-popover-auto[x-placement^=top] .arrow::after,.bs-popover-auto[x-placement^=top] .arrow::before,.bs-popover-top .arrow::after,.bs-popover-top .arrow::before{border-width:.5rem .5rem 0}.bs-popover-auto[x-placement^=top] .arrow::before,.bs-popover-top .arrow::before{bottom:0;border-top-color:rgba(0,0,0,.25)}.bs-popover-auto[x-placement^=top] .arrow::after,.bs-popover-top .arrow::after{bottom:1px;border-top-color:#fff}.bs-popover-auto[x-placement^=right],.bs-popover-right{margin-left:.5rem}.bs-popover-auto[x-placement^=right] .arrow,.bs-popover-right .arrow{left:calc((.5rem + 1px) * -1);width:.5rem;height:1rem;margin:.3rem 0}.bs-popover-auto[x-placement^=right] .arrow::after,.bs-popover-auto[x-placement^=right] .arrow::before,.bs-popover-right .arrow::after,.bs-popover-right .arrow::before{border-width:.5rem .5rem .5rem 0}.bs-popover-auto[x-placement^=right] .arrow::before,.bs-popover-right .arrow::before{left:0;border-right-color:rgba(0,0,0,.25)}.bs-popover-auto[x-placement^=right] .arrow::after,.bs-popover-right .arrow::after{left:1px;border-right-color:#fff}.bs-popover-auto[x-placement^=bottom],.bs-popover-bottom{margin-top:.5rem}.bs-popover-auto[x-placement^=bottom] .arrow,.bs-popover-bottom .arrow{top:calc((.5rem + 1px) * -1)}.bs-popover-auto[x-placement^=bottom] .arrow::after,.bs-popover-auto[x-placement^=bottom] .arrow::before,.bs-popover-bottom .arrow::after,.bs-popover-bottom .arrow::before{border-width:0 .5rem .5rem .5rem}.bs-popover-auto[x-placement^=bottom] .arrow::before,.bs-popover-bottom .arrow::before{top:0;border-bottom-color:rgba(0,0,0,.25)}.bs-popover-auto[x-placement^=bottom] .arrow::after,.bs-popover-bottom .arrow::after{top:1px;border-bottom-color:#fff}.bs-popover-auto[x-placement^=bottom] .popover-header::before,.bs-popover-bottom .popover-header::before{position:absolute;top:0;left:50%;display:block;width:1rem;margin-left:-.5rem;content:"";border-bottom:1px solid #f7f7f7}.bs-popover-auto[x-placement^=left],.bs-popover-left{margin-right:.5rem}.bs-popover-auto[x-placement^=left] .arrow,.bs-popover-left .arrow{right:calc((.5rem + 1px) * -1);width:.5rem;height:1rem;margin:.3rem 0}.bs-popover-auto[x-placement^=left] .arrow::after,.bs-popover-auto[x-placement^=left] .arrow::before,.bs-popover-left .arrow::after,.bs-popover-left .arrow::before{border-width:.5rem 0 .5rem .5rem}.bs-popover-auto[x-placement^=left] .arrow::before,.bs-popover-left .arrow::before{right:0;border-left-color:rgba(0,0,0,.25)}.bs-popover-auto[x-placement^=left] .arrow::after,.bs-popover-left .arrow::after{right:1px;border-left-color:#fff}.popover-header{padding:.5rem .75rem;margin-bottom:0;font-size:1rem;color:inherit;background-color:#f7f7f7;border-bottom:1px solid #ebebeb;border-top-left-radius:calc(.3rem - 1px);border-top-right-radius:calc(.3rem - 1px)}.popover-header:empty{display:none}.popover-body{padding:.5rem .75rem;color:#212529}.carousel{position:relative}.carousel-inner{position:relative;width:100%;overflow:hidden}.carousel-item{position:relative;display:none;-ms-flex-align:center;align-items:center;width:100%;-webkit-backface-visibility:hidden;backface-visibility:hidden;-webkit-perspective:1000px;perspective:1000px}.carousel-item-next,.carousel-item-prev,.carousel-item.active{display:block;transition:-webkit-transform .6s ease;transition:transform .6s ease;transition:transform .6s ease,-webkit-transform .6s ease}@media screen and (prefers-reduced-motion:reduce){.carousel-item-next,.carousel-item-prev,.carousel-item.active{transition:none}}.carousel-item-next,.carousel-item-prev{position:absolute;top:0}.carousel-item-next.carousel-item-left,.carousel-item-prev.carousel-item-right{-webkit-transform:translateX(0);transform:translateX(0)}@supports ((-webkit-transform-style:preserve-3d) or (transform-style:preserve-3d)){.carousel-item-next.carousel-item-left,.carousel-item-prev.carousel-item-right{-webkit-transform:translate3d(0,0,0);transform:translate3d(0,0,0)}}.active.carousel-item-right,.carousel-item-next{-webkit-transform:translateX(100%);transform:translateX(100%)}@supports ((-webkit-transform-style:preserve-3d) or (transform-style:preserve-3d)){.active.carousel-item-right,.carousel-item-next{-webkit-transform:translate3d(100%,0,0);transform:translate3d(100%,0,0)}}.active.carousel-item-left,.carousel-item-prev{-webkit-transform:translateX(-100%);transform:translateX(-100%)}@supports ((-webkit-transform-style:preserve-3d) or (transform-style:preserve-3d)){.active.carousel-item-left,.carousel-item-prev{-webkit-transform:translate3d(-100%,0,0);transform:translate3d(-100%,0,0)}}.carousel-fade .carousel-item{opacity:0;transition-duration:.6s;transition-property:opacity}.carousel-fade .carousel-item-next.carousel-item-left,.carousel-fade .carousel-item-prev.carousel-item-right,.carousel-fade .carousel-item.active{opacity:1}.carousel-fade .active.carousel-item-left,.carousel-fade .active.carousel-item-right{opacity:0}.carousel-fade .active.carousel-item-left,.carousel-fade .active.carousel-item-prev,.carousel-fade .carousel-item-next,.carousel-fade .carousel-item-prev,.carousel-fade .carousel-item.active{-webkit-transform:translateX(0);transform:translateX(0)}@supports ((-webkit-transform-style:preserve-3d) or (transform-style:preserve-3d)){.carousel-fade .active.carousel-item-left,.carousel-fade .active.carousel-item-prev,.carousel-fade .carousel-item-next,.carousel-fade .carousel-item-prev,.carousel-fade .carousel-item.active{-webkit-transform:translate3d(0,0,0);transform:translate3d(0,0,0)}}.carousel-control-next,.carousel-control-prev{position:absolute;top:0;bottom:0;display:-ms-flexbox;display:flex;-ms-flex-align:center;align-items:center;-ms-flex-pack:center;justify-content:center;width:15%;color:#fff;text-align:center;opacity:.5}.carousel-control-next:focus,.carousel-control-next:hover,.carousel-control-prev:focus,.carousel-control-prev:hover{color:#fff;text-decoration:none;outline:0;opacity:.9}.carousel-control-prev{left:0}.carousel-control-next{right:0}.carousel-control-next-icon,.carousel-control-prev-icon{display:inline-block;width:20px;height:20px;background:transparent no-repeat center center;background-size:100% 100%}.carousel-control-prev-icon{background-image:url("data:image/svg+xml;charset=utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' fill='%23fff' viewBox='0 0 8 8'%3E%3Cpath d='M5.25 0l-4 4 4 4 1.5-1.5-2.5-2.5 2.5-2.5-1.5-1.5z'/%3E%3C/svg%3E")}.carousel-control-next-icon{background-image:url("data:image/svg+xml;charset=utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' fill='%23fff' viewBox='0 0 8 8'%3E%3Cpath d='M2.75 0l-1.5 1.5 2.5 2.5-2.5 2.5 1.5 1.5 4-4-4-4z'/%3E%3C/svg%3E")}.carousel-indicators{position:absolute;right:0;bottom:10px;left:0;z-index:15;display:-ms-flexbox;display:flex;-ms-flex-pack:center;justify-content:center;padding-left:0;margin-right:15%;margin-left:15%;list-style:none}.carousel-indicators li{position:relative;-ms-flex:0 1 auto;flex:0 1 auto;width:30px;height:3px;margin-right:3px;margin-left:3px;text-indent:-999px;cursor:pointer;background-color:rgba(255,255,255,.5)}.carousel-indicators li::before{position:absolute;top:-10px;left:0;display:inline-block;width:100%;height:10px;content:""}.carousel-indicators li::after{position:absolute;bottom:-10px;left:0;display:inline-block;width:100%;height:10px;content:""}.carousel-indicators .active{background-color:#fff}.carousel-caption{position:absolute;right:15%;bottom:20px;left:15%;z-index:10;padding-top:20px;padding-bottom:20px;color:#fff;text-align:center}.align-baseline{vertical-align:baseline!important}.align-top{vertical-align:top!important}.align-middle{vertical-align:middle!important}.align-bottom{vertical-align:bottom!important}.align-text-bottom{vertical-align:text-bottom!important}.align-text-top{vertical-align:text-top!important}.bg-primary{background-color:#007bff!important}a.bg-primary:focus,a.bg-primary:hover,button.bg-primary:focus,button.bg-primary:hover{background-color:#0062cc!important}.bg-secondary{background-color:#6c757d!important}a.bg-secondary:focus,a.bg-secondary:hover,button.bg-secondary:focus,button.bg-secondary:hover{background-color:#545b62!important}.bg-success{background-color:#28a745!important}a.bg-success:focus,a.bg-success:hover,button.bg-success:focus,button.bg-success:hover{background-color:#1e7e34!important}.bg-info{background-color:#17a2b8!important}a.bg-info:focus,a.bg-info:hover,button.bg-info:focus,button.bg-info:hover{background-color:#117a8b!important}.bg-warning{background-color:#ffc107!important}a.bg-warning:focus,a.bg-warning:hover,button.bg-warning:focus,button.bg-warning:hover{background-color:#d39e00!important}.bg-danger{background-color:#dc3545!important}a.bg-danger:focus,a.bg-danger:hover,button.bg-danger:focus,button.bg-danger:hover{background-color:#bd2130!important}.bg-light{background-color:#f8f9fa!important}a.bg-light:focus,a.bg-light:hover,button.bg-light:focus,button.bg-light:hover{background-color:#dae0e5!important}.bg-dark{background-color:#343a40!important}a.bg-dark:focus,a.bg-dark:hover,button.bg-dark:focus,button.bg-dark:hover{background-color:#1d2124!important}.bg-white{background-color:#fff!important}.bg-transparent{background-color:transparent!important}.border{border:1px solid #dee2e6!important}.border-top{border-top:1px solid #dee2e6!important}.border-right{border-right:1px solid #dee2e6!important}.border-bottom{border-bottom:1px solid #dee2e6!important}.border-left{border-left:1px solid #dee2e6!important}.border-0{border:0!important}.border-top-0{border-top:0!important}.border-right-0{border-right:0!important}.border-bottom-0{border-bottom:0!important}.border-left-0{border-left:0!important}.border-primary{border-color:#007bff!important}.border-secondary{border-color:#6c757d!important}.border-success{border-color:#28a745!important}.border-info{border-color:#17a2b8!important}.border-warning{border-color:#ffc107!important}.border-danger{border-color:#dc3545!important}.border-light{border-color:#f8f9fa!important}.border-dark{border-color:#343a40!important}.border-white{border-color:#fff!important}.rounded{border-radius:.25rem!important}.rounded-top{border-top-left-radius:.25rem!important;border-top-right-radius:.25rem!important}.rounded-right{border-top-right-radius:.25rem!important;border-bottom-right-radius:.25rem!important}.rounded-bottom{border-bottom-right-radius:.25rem!important;border-bottom-left-radius:.25rem!important}.rounded-left{border-top-left-radius:.25rem!important;border-bottom-left-radius:.25rem!important}.rounded-circle{border-radius:50%!important}.rounded-0{border-radius:0!important}.clearfix::after{display:block;clear:both;content:""}.d-none{display:none!important}.d-inline{display:inline!important}.d-inline-block{display:inline-block!important}.d-block{display:block!important}.d-table{display:table!important}.d-table-row{display:table-row!important}.d-table-cell{display:table-cell!important}.d-flex{display:-ms-flexbox!important;display:flex!important}.d-inline-flex{display:-ms-inline-flexbox!important;display:inline-flex!important}@media (min-width:576px){.d-sm-none{display:none!important}.d-sm-inline{display:inline!important}.d-sm-inline-block{display:inline-block!important}.d-sm-block{display:block!important}.d-sm-table{display:table!important}.d-sm-table-row{display:table-row!important}.d-sm-table-cell{display:table-cell!important}.d-sm-flex{display:-ms-flexbox!important;display:flex!important}.d-sm-inline-flex{display:-ms-inline-flexbox!important;display:inline-flex!important}}@media (min-width:768px){.d-md-none{display:none!important}.d-md-inline{display:inline!important}.d-md-inline-block{display:inline-block!important}.d-md-block{display:block!important}.d-md-table{display:table!important}.d-md-table-row{display:table-row!important}.d-md-table-cell{display:table-cell!important}.d-md-flex{display:-ms-flexbox!important;display:flex!important}.d-md-inline-flex{display:-ms-inline-flexbox!important;display:inline-flex!important}}@media (min-width:992px){.d-lg-none{display:none!important}.d-lg-inline{display:inline!important}.d-lg-inline-block{display:inline-block!important}.d-lg-block{display:block!important}.d-lg-table{display:table!important}.d-lg-table-row{display:table-row!important}.d-lg-table-cell{display:table-cell!important}.d-lg-flex{display:-ms-flexbox!important;display:flex!important}.d-lg-inline-flex{display:-ms-inline-flexbox!important;display:inline-flex!important}}@media (min-width:1200px){.d-xl-none{display:none!important}.d-xl-inline{display:inline!important}.d-xl-inline-block{display:inline-block!important}.d-xl-block{display:block!important}.d-xl-table{display:table!important}.d-xl-table-row{display:table-row!important}.d-xl-table-cell{display:table-cell!important}.d-xl-flex{display:-ms-flexbox!important;display:flex!important}.d-xl-inline-flex{display:-ms-inline-flexbox!important;display:inline-flex!important}}@media print{.d-print-none{display:none!important}.d-print-inline{display:inline!important}.d-print-inline-block{display:inline-block!important}.d-print-block{display:block!important}.d-print-table{display:table!important}.d-print-table-row{display:table-row!important}.d-print-table-cell{display:table-cell!important}.d-print-flex{display:-ms-flexbox!important;display:flex!important}.d-print-inline-flex{display:-ms-inline-flexbox!important;display:inline-flex!important}}.embed-responsive{position:relative;display:block;width:100%;padding:0;overflow:hidden}.embed-responsive::before{display:block;content:""}.embed-responsive .embed-responsive-item,.embed-responsive embed,.embed-responsive iframe,.embed-responsive object,.embed-responsive video{position:absolute;top:0;bottom:0;left:0;width:100%;height:100%;border:0}.embed-responsive-21by9::before{padding-top:42.857143%}.embed-responsive-16by9::before{padding-top:56.25%}.embed-responsive-4by3::before{padding-top:75%}.embed-responsive-1by1::before{padding-top:100%}.flex-row{-ms-flex-direction:row!important;flex-direction:row!important}.flex-column{-ms-flex-direction:column!important;flex-direction:column!important}.flex-row-reverse{-ms-flex-direction:row-reverse!important;flex-direction:row-reverse!important}.flex-column-reverse{-ms-flex-direction:column-reverse!important;flex-direction:column-reverse!important}.flex-wrap{-ms-flex-wrap:wrap!important;flex-wrap:wrap!important}.flex-nowrap{-ms-flex-wrap:nowrap!important;flex-wrap:nowrap!important}.flex-wrap-reverse{-ms-flex-wrap:wrap-reverse!important;flex-wrap:wrap-reverse!important}.flex-fill{-ms-flex:1 1 auto!important;flex:1 1 auto!important}.flex-grow-0{-ms-flex-positive:0!important;flex-grow:0!important}.flex-grow-1{-ms-flex-positive:1!important;flex-grow:1!important}.flex-shrink-0{-ms-flex-negative:0!important;flex-shrink:0!important}.flex-shrink-1{-ms-flex-negative:1!important;flex-shrink:1!important}.justify-content-start{-ms-flex-pack:start!important;justify-content:flex-start!important}.justify-content-end{-ms-flex-pack:end!important;justify-content:flex-end!important}.justify-content-center{-ms-flex-pack:center!important;justify-content:center!important}.justify-content-between{-ms-flex-pack:justify!important;justify-content:space-between!important}.justify-content-around{-ms-flex-pack:distribute!important;justify-content:space-around!important}.align-items-start{-ms-flex-align:start!important;align-items:flex-start!important}.align-items-end{-ms-flex-align:end!important;align-items:flex-end!important}.align-items-center{-ms-flex-align:center!important;align-items:center!important}.align-items-baseline{-ms-flex-align:baseline!important;align-items:baseline!important}.align-items-stretch{-ms-flex-align:stretch!important;align-items:stretch!important}.align-content-start{-ms-flex-line-pack:start!important;align-content:flex-start!important}.align-content-end{-ms-flex-line-pack:end!important;align-content:flex-end!important}.align-content-center{-ms-flex-line-pack:center!important;align-content:center!important}.align-content-between{-ms-flex-line-pack:justify!important;align-content:space-between!important}.align-content-around{-ms-flex-line-pack:distribute!important;align-content:space-around!important}.align-content-stretch{-ms-flex-line-pack:stretch!important;align-content:stretch!important}.align-self-auto{-ms-flex-item-align:auto!important;align-self:auto!important}.align-self-start{-ms-flex-item-align:start!important;align-self:flex-start!important}.align-self-end{-ms-flex-item-align:end!important;align-self:flex-end!important}.align-self-center{-ms-flex-item-align:center!important;align-self:center!important}.align-self-baseline{-ms-flex-item-align:baseline!important;align-self:baseline!important}.align-self-stretch{-ms-flex-item-align:stretch!important;align-self:stretch!important}@media (min-width:576px){.flex-sm-row{-ms-flex-direction:row!important;flex-direction:row!important}.flex-sm-column{-ms-flex-direction:column!important;flex-direction:column!important}.flex-sm-row-reverse{-ms-flex-direction:row-reverse!important;flex-direction:row-reverse!important}.flex-sm-column-reverse{-ms-flex-direction:column-reverse!important;flex-direction:column-reverse!important}.flex-sm-wrap{-ms-flex-wrap:wrap!important;flex-wrap:wrap!important}.flex-sm-nowrap{-ms-flex-wrap:nowrap!important;flex-wrap:nowrap!important}.flex-sm-wrap-reverse{-ms-flex-wrap:wrap-reverse!important;flex-wrap:wrap-reverse!important}.flex-sm-fill{-ms-flex:1 1 auto!important;flex:1 1 auto!important}.flex-sm-grow-0{-ms-flex-positive:0!important;flex-grow:0!important}.flex-sm-grow-1{-ms-flex-positive:1!important;flex-grow:1!important}.flex-sm-shrink-0{-ms-flex-negative:0!important;flex-shrink:0!important}.flex-sm-shrink-1{-ms-flex-negative:1!important;flex-shrink:1!important}.justify-content-sm-start{-ms-flex-pack:start!important;justify-content:flex-start!important}.justify-content-sm-end{-ms-flex-pack:end!important;justify-content:flex-end!important}.justify-content-sm-center{-ms-flex-pack:center!important;justify-content:center!important}.justify-content-sm-between{-ms-flex-pack:justify!important;justify-content:space-between!important}.justify-content-sm-around{-ms-flex-pack:distribute!important;justify-content:space-around!important}.align-items-sm-start{-ms-flex-align:start!important;align-items:flex-start!important}.align-items-sm-end{-ms-flex-align:end!important;align-items:flex-end!important}.align-items-sm-center{-ms-flex-align:center!important;align-items:center!important}.align-items-sm-baseline{-ms-flex-align:baseline!important;align-items:baseline!important}.align-items-sm-stretch{-ms-flex-align:stretch!important;align-items:stretch!important}.align-content-sm-start{-ms-flex-line-pack:start!important;align-content:flex-start!important}.align-content-sm-end{-ms-flex-line-pack:end!important;align-content:flex-end!important}.align-content-sm-center{-ms-flex-line-pack:center!important;align-content:center!important}.align-content-sm-between{-ms-flex-line-pack:justify!important;align-content:space-between!important}.align-content-sm-around{-ms-flex-line-pack:distribute!important;align-content:space-around!important}.align-content-sm-stretch{-ms-flex-line-pack:stretch!important;align-content:stretch!important}.align-self-sm-auto{-ms-flex-item-align:auto!important;align-self:auto!important}.align-self-sm-start{-ms-flex-item-align:start!important;align-self:flex-start!important}.align-self-sm-end{-ms-flex-item-align:end!important;align-self:flex-end!important}.align-self-sm-center{-ms-flex-item-align:center!important;align-self:center!important}.align-self-sm-baseline{-ms-flex-item-align:baseline!important;align-self:baseline!important}.align-self-sm-stretch{-ms-flex-item-align:stretch!important;align-self:stretch!important}}@media (min-width:768px){.flex-md-row{-ms-flex-direction:row!important;flex-direction:row!important}.flex-md-column{-ms-flex-direction:column!important;flex-direction:column!important}.flex-md-row-reverse{-ms-flex-direction:row-reverse!important;flex-direction:row-reverse!important}.flex-md-column-reverse{-ms-flex-direction:column-reverse!important;flex-direction:column-reverse!important}.flex-md-wrap{-ms-flex-wrap:wrap!important;flex-wrap:wrap!important}.flex-md-nowrap{-ms-flex-wrap:nowrap!important;flex-wrap:nowrap!important}.flex-md-wrap-reverse{-ms-flex-wrap:wrap-reverse!important;flex-wrap:wrap-reverse!important}.flex-md-fill{-ms-flex:1 1 auto!important;flex:1 1 auto!important}.flex-md-grow-0{-ms-flex-positive:0!important;flex-grow:0!important}.flex-md-grow-1{-ms-flex-positive:1!important;flex-grow:1!important}.flex-md-shrink-0{-ms-flex-negative:0!important;flex-shrink:0!important}.flex-md-shrink-1{-ms-flex-negative:1!important;flex-shrink:1!important}.justify-content-md-start{-ms-flex-pack:start!important;justify-content:flex-start!important}.justify-content-md-end{-ms-flex-pack:end!important;justify-content:flex-end!important}.justify-content-md-center{-ms-flex-pack:center!important;justify-content:center!important}.justify-content-md-between{-ms-flex-pack:justify!important;justify-content:space-between!important}.justify-content-md-around{-ms-flex-pack:distribute!important;justify-content:space-around!important}.align-items-md-start{-ms-flex-align:start!important;align-items:flex-start!important}.align-items-md-end{-ms-flex-align:end!important;align-items:flex-end!important}.align-items-md-center{-ms-flex-align:center!important;align-items:center!important}.align-items-md-baseline{-ms-flex-align:baseline!important;align-items:baseline!important}.align-items-md-stretch{-ms-flex-align:stretch!important;align-items:stretch!important}.align-content-md-start{-ms-flex-line-pack:start!important;align-content:flex-start!important}.align-content-md-end{-ms-flex-line-pack:end!important;align-content:flex-end!important}.align-content-md-center{-ms-flex-line-pack:center!important;align-content:center!important}.align-content-md-between{-ms-flex-line-pack:justify!important;align-content:space-between!important}.align-content-md-around{-ms-flex-line-pack:distribute!important;align-content:space-around!important}.align-content-md-stretch{-ms-flex-line-pack:stretch!important;align-content:stretch!important}.align-self-md-auto{-ms-flex-item-align:auto!important;align-self:auto!important}.align-self-md-start{-ms-flex-item-align:start!important;align-self:flex-start!important}.align-self-md-end{-ms-flex-item-align:end!important;align-self:flex-end!important}.align-self-md-center{-ms-flex-item-align:center!important;align-self:center!important}.align-self-md-baseline{-ms-flex-item-align:baseline!important;align-self:baseline!important}.align-self-md-stretch{-ms-flex-item-align:stretch!important;align-self:stretch!important}}@media (min-width:992px){.flex-lg-row{-ms-flex-direction:row!important;flex-direction:row!important}.flex-lg-column{-ms-flex-direction:column!important;flex-direction:column!important}.flex-lg-row-reverse{-ms-flex-direction:row-reverse!important;flex-direction:row-reverse!important}.flex-lg-column-reverse{-ms-flex-direction:column-reverse!important;flex-direction:column-reverse!important}.flex-lg-wrap{-ms-flex-wrap:wrap!important;flex-wrap:wrap!important}.flex-lg-nowrap{-ms-flex-wrap:nowrap!important;flex-wrap:nowrap!important}.flex-lg-wrap-reverse{-ms-flex-wrap:wrap-reverse!important;flex-wrap:wrap-reverse!important}.flex-lg-fill{-ms-flex:1 1 auto!important;flex:1 1 auto!important}.flex-lg-grow-0{-ms-flex-positive:0!important;flex-grow:0!important}.flex-lg-grow-1{-ms-flex-positive:1!important;flex-grow:1!important}.flex-lg-shrink-0{-ms-flex-negative:0!important;flex-shrink:0!important}.flex-lg-shrink-1{-ms-flex-negative:1!important;flex-shrink:1!important}.justify-content-lg-start{-ms-flex-pack:start!important;justify-content:flex-start!important}.justify-content-lg-end{-ms-flex-pack:end!important;justify-content:flex-end!important}.justify-content-lg-center{-ms-flex-pack:center!important;justify-content:center!important}.justify-content-lg-between{-ms-flex-pack:justify!important;justify-content:space-between!important}.justify-content-lg-around{-ms-flex-pack:distribute!important;justify-content:space-around!important}.align-items-lg-start{-ms-flex-align:start!important;align-items:flex-start!important}.align-items-lg-end{-ms-flex-align:end!important;align-items:flex-end!important}.align-items-lg-center{-ms-flex-align:center!important;align-items:center!important}.align-items-lg-baseline{-ms-flex-align:baseline!important;align-items:baseline!important}.align-items-lg-stretch{-ms-flex-align:stretch!important;align-items:stretch!important}.align-content-lg-start{-ms-flex-line-pack:start!important;align-content:flex-start!important}.align-content-lg-end{-ms-flex-line-pack:end!important;align-content:flex-end!important}.align-content-lg-center{-ms-flex-line-pack:center!important;align-content:center!important}.align-content-lg-between{-ms-flex-line-pack:justify!important;align-content:space-between!important}.align-content-lg-around{-ms-flex-line-pack:distribute!important;align-content:space-around!important}.align-content-lg-stretch{-ms-flex-line-pack:stretch!important;align-content:stretch!important}.align-self-lg-auto{-ms-flex-item-align:auto!important;align-self:auto!important}.align-self-lg-start{-ms-flex-item-align:start!important;align-self:flex-start!important}.align-self-lg-end{-ms-flex-item-align:end!important;align-self:flex-end!important}.align-self-lg-center{-ms-flex-item-align:center!important;align-self:center!important}.align-self-lg-baseline{-ms-flex-item-align:baseline!important;align-self:baseline!important}.align-self-lg-stretch{-ms-flex-item-align:stretch!important;align-self:stretch!important}}@media (min-width:1200px){.flex-xl-row{-ms-flex-direction:row!important;flex-direction:row!important}.flex-xl-column{-ms-flex-direction:column!important;flex-direction:column!important}.flex-xl-row-reverse{-ms-flex-direction:row-reverse!important;flex-direction:row-reverse!important}.flex-xl-column-reverse{-ms-flex-direction:column-reverse!important;flex-direction:column-reverse!important}.flex-xl-wrap{-ms-flex-wrap:wrap!important;flex-wrap:wrap!important}.flex-xl-nowrap{-ms-flex-wrap:nowrap!important;flex-wrap:nowrap!important}.flex-xl-wrap-reverse{-ms-flex-wrap:wrap-reverse!important;flex-wrap:wrap-reverse!important}.flex-xl-fill{-ms-flex:1 1 auto!important;flex:1 1 auto!important}.flex-xl-grow-0{-ms-flex-positive:0!important;flex-grow:0!important}.flex-xl-grow-1{-ms-flex-positive:1!important;flex-grow:1!important}.flex-xl-shrink-0{-ms-flex-negative:0!important;flex-shrink:0!important}.flex-xl-shrink-1{-ms-flex-negative:1!important;flex-shrink:1!important}.justify-content-xl-start{-ms-flex-pack:start!important;justify-content:flex-start!important}.justify-content-xl-end{-ms-flex-pack:end!important;justify-content:flex-end!important}.justify-content-xl-center{-ms-flex-pack:center!important;justify-content:center!important}.justify-content-xl-between{-ms-flex-pack:justify!important;justify-content:space-between!important}.justify-content-xl-around{-ms-flex-pack:distribute!important;justify-content:space-around!important}.align-items-xl-start{-ms-flex-align:start!important;align-items:flex-start!important}.align-items-xl-end{-ms-flex-align:end!important;align-items:flex-end!important}.align-items-xl-center{-ms-flex-align:center!important;align-items:center!important}.align-items-xl-baseline{-ms-flex-align:baseline!important;align-items:baseline!important}.align-items-xl-stretch{-ms-flex-align:stretch!important;align-items:stretch!important}.align-content-xl-start{-ms-flex-line-pack:start!important;align-content:flex-start!important}.align-content-xl-end{-ms-flex-line-pack:end!important;align-content:flex-end!important}.align-content-xl-center{-ms-flex-line-pack:center!important;align-content:center!important}.align-content-xl-between{-ms-flex-line-pack:justify!important;align-content:space-between!important}.align-content-xl-around{-ms-flex-line-pack:distribute!important;align-content:space-around!important}.align-content-xl-stretch{-ms-flex-line-pack:stretch!important;align-content:stretch!important}.align-self-xl-auto{-ms-flex-item-align:auto!important;align-self:auto!important}.align-self-xl-start{-ms-flex-item-align:start!important;align-self:flex-start!important}.align-self-xl-end{-ms-flex-item-align:end!important;align-self:flex-end!important}.align-self-xl-center{-ms-flex-item-align:center!important;align-self:center!important}.align-self-xl-baseline{-ms-flex-item-align:baseline!important;align-self:baseline!important}.align-self-xl-stretch{-ms-flex-item-align:stretch!important;align-self:stretch!important}}.float-left{float:left!important}.float-right{float:right!important}.float-none{float:none!important}@media (min-width:576px){.float-sm-left{float:left!important}.float-sm-right{float:right!important}.float-sm-none{float:none!important}}@media (min-width:768px){.float-md-left{float:left!important}.float-md-right{float:right!important}.float-md-none{float:none!important}}@media (min-width:992px){.float-lg-left{float:left!important}.float-lg-right{float:right!important}.float-lg-none{float:none!important}}@media (min-width:1200px){.float-xl-left{float:left!important}.float-xl-right{float:right!important}.float-xl-none{float:none!important}}.position-static{position:static!important}.position-relative{position:relative!important}.position-absolute{position:absolute!important}.position-fixed{position:fixed!important}.position-sticky{position:-webkit-sticky!important;position:sticky!important}.fixed-top{position:fixed;top:0;right:0;left:0;z-index:1030}.fixed-bottom{position:fixed;right:0;bottom:0;left:0;z-index:1030}@supports ((position:-webkit-sticky) or (position:sticky)){.sticky-top{position:-webkit-sticky;position:sticky;top:0;z-index:1020}}.sr-only{position:absolute;width:1px;height:1px;padding:0;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0}.sr-only-focusable:active,.sr-only-focusable:focus{position:static;width:auto;height:auto;overflow:visible;clip:auto;white-space:normal}.shadow-sm{box-shadow:0 .125rem .25rem rgba(0,0,0,.075)!important}.shadow{box-shadow:0 .5rem 1rem rgba(0,0,0,.15)!important}.shadow-lg{box-shadow:0 1rem 3rem rgba(0,0,0,.175)!important}.shadow-none{box-shadow:none!important}.w-25{width:25%!important}.w-50{width:50%!important}.w-75{width:75%!important}.w-100{width:100%!important}.w-auto{width:auto!important}.h-25{height:25%!important}.h-50{height:50%!important}.h-75{height:75%!important}.h-100{height:100%!important}.h-auto{height:auto!important}.mw-100{max-width:100%!important}.mh-100{max-height:100%!important}.m-0{margin:0!important}.mt-0,.my-0{margin-top:0!important}.mr-0,.mx-0{margin-right:0!important}.mb-0,.my-0{margin-bottom:0!important}.ml-0,.mx-0{margin-left:0!important}.m-1{margin:.25rem!important}.mt-1,.my-1{margin-top:.25rem!important}.mr-1,.mx-1{margin-right:.25rem!important}.mb-1,.my-1{margin-bottom:.25rem!important}.ml-1,.mx-1{margin-left:.25rem!important}.m-2{margin:.5rem!important}.mt-2,.my-2{margin-top:.5rem!important}.mr-2,.mx-2{margin-right:.5rem!important}.mb-2,.my-2{margin-bottom:.5rem!important}.ml-2,.mx-2{margin-left:.5rem!important}.m-3{margin:1rem!important}.mt-3,.my-3{margin-top:1rem!important}.mr-3,.mx-3{margin-right:1rem!important}.mb-3,.my-3{margin-bottom:1rem!important}.ml-3,.mx-3{margin-left:1rem!important}.m-4{margin:1.5rem!important}.mt-4,.my-4{margin-top:1.5rem!important}.mr-4,.mx-4{margin-right:1.5rem!important}.mb-4,.my-4{margin-bottom:1.5rem!important}.ml-4,.mx-4{margin-left:1.5rem!important}.m-5{margin:3rem!important}.mt-5,.my-5{margin-top:3rem!important}.mr-5,.mx-5{margin-right:3rem!important}.mb-5,.my-5{margin-bottom:3rem!important}.ml-5,.mx-5{margin-left:3rem!important}.p-0{padding:0!important}.pt-0,.py-0{padding-top:0!important}.pr-0,.px-0{padding-right:0!important}.pb-0,.py-0{padding-bottom:0!important}.pl-0,.px-0{padding-left:0!important}.p-1{padding:.25rem!important}.pt-1,.py-1{padding-top:.25rem!important}.pr-1,.px-1{padding-right:.25rem!important}.pb-1,.py-1{padding-bottom:.25rem!important}.pl-1,.px-1{padding-left:.25rem!important}.p-2{padding:.5rem!important}.pt-2,.py-2{padding-top:.5rem!important}.pr-2,.px-2{padding-right:.5rem!important}.pb-2,.py-2{padding-bottom:.5rem!important}.pl-2,.px-2{padding-left:.5rem!important}.p-3{padding:1rem!important}.pt-3,.py-3{padding-top:1rem!important}.pr-3,.px-3{padding-right:1rem!important}.pb-3,.py-3{padding-bottom:1rem!important}.pl-3,.px-3{padding-left:1rem!important}.p-4{padding:1.5rem!important}.pt-4,.py-4{padding-top:1.5rem!important}.pr-4,.px-4{padding-right:1.5rem!important}.pb-4,.py-4{padding-bottom:1.5rem!important}.pl-4,.px-4{padding-left:1.5rem!important}.p-5{padding:3rem!important}.pt-5,.py-5{padding-top:3rem!important}.pr-5,.px-5{padding-right:3rem!important}.pb-5,.py-5{padding-bottom:3rem!important}.pl-5,.px-5{padding-left:3rem!important}.m-auto{margin:auto!important}.mt-auto,.my-auto{margin-top:auto!important}.mr-auto,.mx-auto{margin-right:auto!important}.mb-auto,.my-auto{margin-bottom:auto!important}.ml-auto,.mx-auto{margin-left:auto!important}@media (min-width:576px){.m-sm-0{margin:0!important}.mt-sm-0,.my-sm-0{margin-top:0!important}.mr-sm-0,.mx-sm-0{margin-right:0!important}.mb-sm-0,.my-sm-0{margin-bottom:0!important}.ml-sm-0,.mx-sm-0{margin-left:0!important}.m-sm-1{margin:.25rem!important}.mt-sm-1,.my-sm-1{margin-top:.25rem!important}.mr-sm-1,.mx-sm-1{margin-right:.25rem!important}.mb-sm-1,.my-sm-1{margin-bottom:.25rem!important}.ml-sm-1,.mx-sm-1{margin-left:.25rem!important}.m-sm-2{margin:.5rem!important}.mt-sm-2,.my-sm-2{margin-top:.5rem!important}.mr-sm-2,.mx-sm-2{margin-right:.5rem!important}.mb-sm-2,.my-sm-2{margin-bottom:.5rem!important}.ml-sm-2,.mx-sm-2{margin-left:.5rem!important}.m-sm-3{margin:1rem!important}.mt-sm-3,.my-sm-3{margin-top:1rem!important}.mr-sm-3,.mx-sm-3{margin-right:1rem!important}.mb-sm-3,.my-sm-3{margin-bottom:1rem!important}.ml-sm-3,.mx-sm-3{margin-left:1rem!important}.m-sm-4{margin:1.5rem!important}.mt-sm-4,.my-sm-4{margin-top:1.5rem!important}.mr-sm-4,.mx-sm-4{margin-right:1.5rem!important}.mb-sm-4,.my-sm-4{margin-bottom:1.5rem!important}.ml-sm-4,.mx-sm-4{margin-left:1.5rem!important}.m-sm-5{margin:3rem!important}.mt-sm-5,.my-sm-5{margin-top:3rem!important}.mr-sm-5,.mx-sm-5{margin-right:3rem!important}.mb-sm-5,.my-sm-5{margin-bottom:3rem!important}.ml-sm-5,.mx-sm-5{margin-left:3rem!important}.p-sm-0{padding:0!important}.pt-sm-0,.py-sm-0{padding-top:0!important}.pr-sm-0,.px-sm-0{padding-right:0!important}.pb-sm-0,.py-sm-0{padding-bottom:0!important}.pl-sm-0,.px-sm-0{padding-left:0!important}.p-sm-1{padding:.25rem!important}.pt-sm-1,.py-sm-1{padding-top:.25rem!important}.pr-sm-1,.px-sm-1{padding-right:.25rem!important}.pb-sm-1,.py-sm-1{padding-bottom:.25rem!important}.pl-sm-1,.px-sm-1{padding-left:.25rem!important}.p-sm-2{padding:.5rem!important}.pt-sm-2,.py-sm-2{padding-top:.5rem!important}.pr-sm-2,.px-sm-2{padding-right:.5rem!important}.pb-sm-2,.py-sm-2{padding-bottom:.5rem!important}.pl-sm-2,.px-sm-2{padding-left:.5rem!important}.p-sm-3{padding:1rem!important}.pt-sm-3,.py-sm-3{padding-top:1rem!important}.pr-sm-3,.px-sm-3{padding-right:1rem!important}.pb-sm-3,.py-sm-3{padding-bottom:1rem!important}.pl-sm-3,.px-sm-3{padding-left:1rem!important}.p-sm-4{padding:1.5rem!important}.pt-sm-4,.py-sm-4{padding-top:1.5rem!important}.pr-sm-4,.px-sm-4{padding-right:1.5rem!important}.pb-sm-4,.py-sm-4{padding-bottom:1.5rem!important}.pl-sm-4,.px-sm-4{padding-left:1.5rem!important}.p-sm-5{padding:3rem!important}.pt-sm-5,.py-sm-5{padding-top:3rem!important}.pr-sm-5,.px-sm-5{padding-right:3rem!important}.pb-sm-5,.py-sm-5{padding-bottom:3rem!important}.pl-sm-5,.px-sm-5{padding-left:3rem!important}.m-sm-auto{margin:auto!important}.mt-sm-auto,.my-sm-auto{margin-top:auto!important}.mr-sm-auto,.mx-sm-auto{margin-right:auto!important}.mb-sm-auto,.my-sm-auto{margin-bottom:auto!important}.ml-sm-auto,.mx-sm-auto{margin-left:auto!important}}@media (min-width:768px){.m-md-0{margin:0!important}.mt-md-0,.my-md-0{margin-top:0!important}.mr-md-0,.mx-md-0{margin-right:0!important}.mb-md-0,.my-md-0{margin-bottom:0!important}.ml-md-0,.mx-md-0{margin-left:0!important}.m-md-1{margin:.25rem!important}.mt-md-1,.my-md-1{margin-top:.25rem!important}.mr-md-1,.mx-md-1{margin-right:.25rem!important}.mb-md-1,.my-md-1{margin-bottom:.25rem!important}.ml-md-1,.mx-md-1{margin-left:.25rem!important}.m-md-2{margin:.5rem!important}.mt-md-2,.my-md-2{margin-top:.5rem!important}.mr-md-2,.mx-md-2{margin-right:.5rem!important}.mb-md-2,.my-md-2{margin-bottom:.5rem!important}.ml-md-2,.mx-md-2{margin-left:.5rem!important}.m-md-3{margin:1rem!important}.mt-md-3,.my-md-3{margin-top:1rem!important}.mr-md-3,.mx-md-3{margin-right:1rem!important}.mb-md-3,.my-md-3{margin-bottom:1rem!important}.ml-md-3,.mx-md-3{margin-left:1rem!important}.m-md-4{margin:1.5rem!important}.mt-md-4,.my-md-4{margin-top:1.5rem!important}.mr-md-4,.mx-md-4{margin-right:1.5rem!important}.mb-md-4,.my-md-4{margin-bottom:1.5rem!important}.ml-md-4,.mx-md-4{margin-left:1.5rem!important}.m-md-5{margin:3rem!important}.mt-md-5,.my-md-5{margin-top:3rem!important}.mr-md-5,.mx-md-5{margin-right:3rem!important}.mb-md-5,.my-md-5{margin-bottom:3rem!important}.ml-md-5,.mx-md-5{margin-left:3rem!important}.p-md-0{padding:0!important}.pt-md-0,.py-md-0{padding-top:0!important}.pr-md-0,.px-md-0{padding-right:0!important}.pb-md-0,.py-md-0{padding-bottom:0!important}.pl-md-0,.px-md-0{padding-left:0!important}.p-md-1{padding:.25rem!important}.pt-md-1,.py-md-1{padding-top:.25rem!important}.pr-md-1,.px-md-1{padding-right:.25rem!important}.pb-md-1,.py-md-1{padding-bottom:.25rem!important}.pl-md-1,.px-md-1{padding-left:.25rem!important}.p-md-2{padding:.5rem!important}.pt-md-2,.py-md-2{padding-top:.5rem!important}.pr-md-2,.px-md-2{padding-right:.5rem!important}.pb-md-2,.py-md-2{padding-bottom:.5rem!important}.pl-md-2,.px-md-2{padding-left:.5rem!important}.p-md-3{padding:1rem!important}.pt-md-3,.py-md-3{padding-top:1rem!important}.pr-md-3,.px-md-3{padding-right:1rem!important}.pb-md-3,.py-md-3{padding-bottom:1rem!important}.pl-md-3,.px-md-3{padding-left:1rem!important}.p-md-4{padding:1.5rem!important}.pt-md-4,.py-md-4{padding-top:1.5rem!important}.pr-md-4,.px-md-4{padding-right:1.5rem!important}.pb-md-4,.py-md-4{padding-bottom:1.5rem!important}.pl-md-4,.px-md-4{padding-left:1.5rem!important}.p-md-5{padding:3rem!important}.pt-md-5,.py-md-5{padding-top:3rem!important}.pr-md-5,.px-md-5{padding-right:3rem!important}.pb-md-5,.py-md-5{padding-bottom:3rem!important}.pl-md-5,.px-md-5{padding-left:3rem!important}.m-md-auto{margin:auto!important}.mt-md-auto,.my-md-auto{margin-top:auto!important}.mr-md-auto,.mx-md-auto{margin-right:auto!important}.mb-md-auto,.my-md-auto{margin-bottom:auto!important}.ml-md-auto,.mx-md-auto{margin-left:auto!important}}@media (min-width:992px){.m-lg-0{margin:0!important}.mt-lg-0,.my-lg-0{margin-top:0!important}.mr-lg-0,.mx-lg-0{margin-right:0!important}.mb-lg-0,.my-lg-0{margin-bottom:0!important}.ml-lg-0,.mx-lg-0{margin-left:0!important}.m-lg-1{margin:.25rem!important}.mt-lg-1,.my-lg-1{margin-top:.25rem!important}.mr-lg-1,.mx-lg-1{margin-right:.25rem!important}.mb-lg-1,.my-lg-1{margin-bottom:.25rem!important}.ml-lg-1,.mx-lg-1{margin-left:.25rem!important}.m-lg-2{margin:.5rem!important}.mt-lg-2,.my-lg-2{margin-top:.5rem!important}.mr-lg-2,.mx-lg-2{margin-right:.5rem!important}.mb-lg-2,.my-lg-2{margin-bottom:.5rem!important}.ml-lg-2,.mx-lg-2{margin-left:.5rem!important}.m-lg-3{margin:1rem!important}.mt-lg-3,.my-lg-3{margin-top:1rem!important}.mr-lg-3,.mx-lg-3{margin-right:1rem!important}.mb-lg-3,.my-lg-3{margin-bottom:1rem!important}.ml-lg-3,.mx-lg-3{margin-left:1rem!important}.m-lg-4{margin:1.5rem!important}.mt-lg-4,.my-lg-4{margin-top:1.5rem!important}.mr-lg-4,.mx-lg-4{margin-right:1.5rem!important}.mb-lg-4,.my-lg-4{margin-bottom:1.5rem!important}.ml-lg-4,.mx-lg-4{margin-left:1.5rem!important}.m-lg-5{margin:3rem!important}.mt-lg-5,.my-lg-5{margin-top:3rem!important}.mr-lg-5,.mx-lg-5{margin-right:3rem!important}.mb-lg-5,.my-lg-5{margin-bottom:3rem!important}.ml-lg-5,.mx-lg-5{margin-left:3rem!important}.p-lg-0{padding:0!important}.pt-lg-0,.py-lg-0{padding-top:0!important}.pr-lg-0,.px-lg-0{padding-right:0!important}.pb-lg-0,.py-lg-0{padding-bottom:0!important}.pl-lg-0,.px-lg-0{padding-left:0!important}.p-lg-1{padding:.25rem!important}.pt-lg-1,.py-lg-1{padding-top:.25rem!important}.pr-lg-1,.px-lg-1{padding-right:.25rem!important}.pb-lg-1,.py-lg-1{padding-bottom:.25rem!important}.pl-lg-1,.px-lg-1{padding-left:.25rem!important}.p-lg-2{padding:.5rem!important}.pt-lg-2,.py-lg-2{padding-top:.5rem!important}.pr-lg-2,.px-lg-2{padding-right:.5rem!important}.pb-lg-2,.py-lg-2{padding-bottom:.5rem!important}.pl-lg-2,.px-lg-2{padding-left:.5rem!important}.p-lg-3{padding:1rem!important}.pt-lg-3,.py-lg-3{padding-top:1rem!important}.pr-lg-3,.px-lg-3{padding-right:1rem!important}.pb-lg-3,.py-lg-3{padding-bottom:1rem!important}.pl-lg-3,.px-lg-3{padding-left:1rem!important}.p-lg-4{padding:1.5rem!important}.pt-lg-4,.py-lg-4{padding-top:1.5rem!important}.pr-lg-4,.px-lg-4{padding-right:1.5rem!important}.pb-lg-4,.py-lg-4{padding-bottom:1.5rem!important}.pl-lg-4,.px-lg-4{padding-left:1.5rem!important}.p-lg-5{padding:3rem!important}.pt-lg-5,.py-lg-5{padding-top:3rem!important}.pr-lg-5,.px-lg-5{padding-right:3rem!important}.pb-lg-5,.py-lg-5{padding-bottom:3rem!important}.pl-lg-5,.px-lg-5{padding-left:3rem!important}.m-lg-auto{margin:auto!important}.mt-lg-auto,.my-lg-auto{margin-top:auto!important}.mr-lg-auto,.mx-lg-auto{margin-right:auto!important}.mb-lg-auto,.my-lg-auto{margin-bottom:auto!important}.ml-lg-auto,.mx-lg-auto{margin-left:auto!important}}@media (min-width:1200px){.m-xl-0{margin:0!important}.mt-xl-0,.my-xl-0{margin-top:0!important}.mr-xl-0,.mx-xl-0{margin-right:0!important}.mb-xl-0,.my-xl-0{margin-bottom:0!important}.ml-xl-0,.mx-xl-0{margin-left:0!important}.m-xl-1{margin:.25rem!important}.mt-xl-1,.my-xl-1{margin-top:.25rem!important}.mr-xl-1,.mx-xl-1{margin-right:.25rem!important}.mb-xl-1,.my-xl-1{margin-bottom:.25rem!important}.ml-xl-1,.mx-xl-1{margin-left:.25rem!important}.m-xl-2{margin:.5rem!important}.mt-xl-2,.my-xl-2{margin-top:.5rem!important}.mr-xl-2,.mx-xl-2{margin-right:.5rem!important}.mb-xl-2,.my-xl-2{margin-bottom:.5rem!important}.ml-xl-2,.mx-xl-2{margin-left:.5rem!important}.m-xl-3{margin:1rem!important}.mt-xl-3,.my-xl-3{margin-top:1rem!important}.mr-xl-3,.mx-xl-3{margin-right:1rem!important}.mb-xl-3,.my-xl-3{margin-bottom:1rem!important}.ml-xl-3,.mx-xl-3{margin-left:1rem!important}.m-xl-4{margin:1.5rem!important}.mt-xl-4,.my-xl-4{margin-top:1.5rem!important}.mr-xl-4,.mx-xl-4{margin-right:1.5rem!important}.mb-xl-4,.my-xl-4{margin-bottom:1.5rem!important}.ml-xl-4,.mx-xl-4{margin-left:1.5rem!important}.m-xl-5{margin:3rem!important}.mt-xl-5,.my-xl-5{margin-top:3rem!important}.mr-xl-5,.mx-xl-5{margin-right:3rem!important}.mb-xl-5,.my-xl-5{margin-bottom:3rem!important}.ml-xl-5,.mx-xl-5{margin-left:3rem!important}.p-xl-0{padding:0!important}.pt-xl-0,.py-xl-0{padding-top:0!important}.pr-xl-0,.px-xl-0{padding-right:0!important}.pb-xl-0,.py-xl-0{padding-bottom:0!important}.pl-xl-0,.px-xl-0{padding-left:0!important}.p-xl-1{padding:.25rem!important}.pt-xl-1,.py-xl-1{padding-top:.25rem!important}.pr-xl-1,.px-xl-1{padding-right:.25rem!important}.pb-xl-1,.py-xl-1{padding-bottom:.25rem!important}.pl-xl-1,.px-xl-1{padding-left:.25rem!important}.p-xl-2{padding:.5rem!important}.pt-xl-2,.py-xl-2{padding-top:.5rem!important}.pr-xl-2,.px-xl-2{padding-right:.5rem!important}.pb-xl-2,.py-xl-2{padding-bottom:.5rem!important}.pl-xl-2,.px-xl-2{padding-left:.5rem!important}.p-xl-3{padding:1rem!important}.pt-xl-3,.py-xl-3{padding-top:1rem!important}.pr-xl-3,.px-xl-3{padding-right:1rem!important}.pb-xl-3,.py-xl-3{padding-bottom:1rem!important}.pl-xl-3,.px-xl-3{padding-left:1rem!important}.p-xl-4{padding:1.5rem!important}.pt-xl-4,.py-xl-4{padding-top:1.5rem!important}.pr-xl-4,.px-xl-4{padding-right:1.5rem!important}.pb-xl-4,.py-xl-4{padding-bottom:1.5rem!important}.pl-xl-4,.px-xl-4{padding-left:1.5rem!important}.p-xl-5{padding:3rem!important}.pt-xl-5,.py-xl-5{padding-top:3rem!important}.pr-xl-5,.px-xl-5{padding-right:3rem!important}.pb-xl-5,.py-xl-5{padding-bottom:3rem!important}.pl-xl-5,.px-xl-5{padding-left:3rem!important}.m-xl-auto{margin:auto!important}.mt-xl-auto,.my-xl-auto{margin-top:auto!important}.mr-xl-auto,.mx-xl-auto{margin-right:auto!important}.mb-xl-auto,.my-xl-auto{margin-bottom:auto!important}.ml-xl-auto,.mx-xl-auto{margin-left:auto!important}}.text-monospace{font-family:SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",monospace}.text-justify{text-align:justify!important}.text-nowrap{white-space:nowrap!important}.text-truncate{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.text-left{text-align:left!important}.text-right{text-align:right!important}.text-center{text-align:center!important}@media (min-width:576px){.text-sm-left{text-align:left!important}.text-sm-right{text-align:right!important}.text-sm-center{text-align:center!important}}@media (min-width:768px){.text-md-left{text-align:left!important}.text-md-right{text-align:right!important}.text-md-center{text-align:center!important}}@media (min-width:992px){.text-lg-left{text-align:left!important}.text-lg-right{text-align:right!important}.text-lg-center{text-align:center!important}}@media (min-width:1200px){.text-xl-left{text-align:left!important}.text-xl-right{text-align:right!important}.text-xl-center{text-align:center!important}}.text-lowercase{text-transform:lowercase!important}.text-uppercase{text-transform:uppercase!important}.text-capitalize{text-transform:capitalize!important}.font-weight-light{font-weight:300!important}.font-weight-normal{font-weight:400!important}.font-weight-bold{font-weight:700!important}.font-italic{font-style:italic!important}.text-white{color:#fff!important}.text-primary{color:#007bff!important}a.text-primary:focus,a.text-primary:hover{color:#0062cc!important}.text-secondary{color:#6c757d!important}a.text-secondary:focus,a.text-secondary:hover{color:#545b62!important}.text-success{color:#28a745!important}a.text-success:focus,a.text-success:hover{color:#1e7e34!important}.text-info{color:#17a2b8!important}a.text-info:focus,a.text-info:hover{color:#117a8b!important}.text-warning{color:#ffc107!important}a.text-warning:focus,a.text-warning:hover{color:#d39e00!important}.text-danger{color:#dc3545!important}a.text-danger:focus,a.text-danger:hover{color:#bd2130!important}.text-light{color:#f8f9fa!important}a.text-light:focus,a.text-light:hover{color:#dae0e5!important}.text-dark{color:#343a40!important}a.text-dark:focus,a.text-dark:hover{color:#1d2124!important}.text-body{color:#212529!important}.text-muted{color:#6c757d!important}.text-black-50{color:rgba(0,0,0,.5)!important}.text-white-50{color:rgba(255,255,255,.5)!important}.text-hide{font:0/0 a;color:transparent;text-shadow:none;background-color:transparent;border:0}.visible{visibility:visible!important}.invisible{visibility:hidden!important}@media print{*,::after,::before{text-shadow:none!important;box-shadow:none!important}a:not(.btn){text-decoration:underline}abbr[title]::after{content:" (" attr(title) ")"}pre{white-space:pre-wrap!important}blockquote,pre{border:1px solid #adb5bd;page-break-inside:avoid}thead{display:table-header-group}img,tr{page-break-inside:avoid}h2,h3,p{orphans:3;widows:3}h2,h3{page-break-after:avoid}@page{size:a3}body{min-width:992px!important}.container{min-width:992px!important}.navbar{display:none}.badge{border:1px solid #000}.table{border-collapse:collapse!important}.table td,.table th{background-color:#fff!important}.table-bordered td,.table-bordered th{border:1px solid #dee2e6!important}.table-dark{color:inherit}.table-dark tbody+tbody,.table-dark td,.table-dark th,.table-dark thead th{border-color:#dee2e6}.table .thead-dark th{color:inherit;border-color:#dee2e6}} -/*# sourceMappingURL=bootstrap.min.css.map */ \ No newline at end of file diff --git a/documentation/tdenginedocs-en/lib/docs/docs.css b/documentation/tdenginedocs-en/lib/docs/docs.css deleted file mode 100644 index bfb6f808e6cf1b5abaa4167c169d16abee639976..0000000000000000000000000000000000000000 --- a/documentation/tdenginedocs-en/lib/docs/docs.css +++ /dev/null @@ -1,269 +0,0 @@ -.documentation strong { - font-weight:600; -} -.documentation { - overflow:hidden; - margin-bottom: 10rem; -} -.documentation a { - font-size:1em; - text-decoration: none; -} -.documentation > a > h2 { - cursor:pointer; - color:var(--sg1); - -} -.documentation > a >h2:hover { - color:var(--b2); -} -.documentation a:hover { - text-decoration: none; -} -.documentation pre { - margin-top: 0; -margin-bottom: 7px; -overflow: auto; --ms-overflow-style: scrollbar; -margin-top: 7px; -} -pre * { - font-family:monospace !important -} -.documentation a { - color:var(--b2); - padding-bottom: 2px; - position: relative; - font-style: normal; - cursor: pointer; -} -.documentation a:hover,a:focus { - text-decoration: none; - color:var(--b2); -} -.documentation a::before { - content: ""; - left: 0; - background-color: var(--b2); - width: 0%; - height: 1px; - top:-webkit-calc(1em + 8px); - top:calc(1em + 8px); - position: absolute; - z-index: 2; - -webkit-transition: background-color 0.2s, height 0.2s, top 0.2s, width 0.2s; - -o-transition: background-color 0.2s, height 0.2s, top 0.2s, width 0.2s; - transition: background-color 0.2s, height 0.2s, top 0.2s, width 0.2s;; -} -.documentation a:hover::before, .documentation a:focus::before { - content: ""; - left: 0; - background-color: var(--b2); - width: 100%; - height: 1px; - top:-webkit-calc(1em + 8px); - top:calc(1em + 8px); - position: absolute; - z-index: 2; - -webkit-transition: background-color 0.2s, height 0.2s, top 0.2s, width 0.2s; - -o-transition: background-color 0.2s, height 0.2s, top 0.2s, width 0.2s; - transition: background-color 0.2s, height 0.2s, top 0.2s, width 0.2s; - text-decoration: none; -} -.documentation img { - width:100%; - max-width:640px; - margin-left: 50%; - -webkit-transform: translate(-50%,0); - -ms-transform: translate(-50%,0); - transform: translate(-50%,0); - -} -h1, -h2, -h3, -h4, -h5, -h6 { - position: relative; - margin-bottom: 0.5rem; - font-weight: 500; - line-height: 1.4; - cursor: text; -} -h1:hover a.anchor, -h2:hover a.anchor, -h3:hover a.anchor, -h4:hover a.anchor, -h5:hover a.anchor, -h6:hover a.anchor { - text-decoration: none; -} -h1 tt, -h1 code { - font-size: inherit; -} -h2 tt, -h2 code { - font-size: inherit; -} -h3 tt, -h3 code { - font-size: inherit; -} -h4 tt, -h4 code { - font-size: inherit; -} -h5 tt, -h5 code { - font-size: inherit; -} -h6 tt, -h6 code { - font-size: inherit; -} -h1 { - font-size: 2.5rem; - line-height: 1.8; -} -h2 { - font-size: 1.7rem; - line-height: 1.8; - padding-left: 0.5em; -} -.documentation h2::before { - content:""; - height:1em;; - display: block; - width:3px; - margin-left: -0.5em; - margin-top: 0.4em; - position: absolute; - background-color: var(--b1); -} -h3 { - font-size: 1.4rem; - line-height: 1.43; -} -h4 { - font-size: 1.25rem; -} -h5 { - font-size: 1rem; -} -h6 { - font-size: 1rem; - color: #777; -} -p { - margin-bottom:0.5rem; - font-size:1em; - margin-top:0; - font-weight:300; -} -ol,ul,dl { - margin-top:0; - margin-bottom: 1rem; -} -li p { - margin-bottom: 0; -} -blockquote, -table{ - margin: 0.8em 0; - width:100%; -} -figure table{ - overflow: scroll; -} -hr { - height: 2px; - padding: 0; - margin: 16px 0; - background-color: #e7e7e7; - border: 0 none; - overflow: hidden; - -webkit-box-sizing: content-box; - box-sizing: content-box; -} - -li p.first { - display: inline-block; -} -ul, -ol { - padding-left: 30px; -} -ul:first-child, -ol:first-child { - margin-top: 0; -} -ul:last-child, -ol:last-child { - margin-bottom: 0; -} -blockquote { - border-left: 4px solid #dfe2e5; - padding: 0 15px; - color: #777777; -} -blockquote blockquote { - padding-right: 0; -} -table { - padding: 0; - word-break: initial; -} -table tr { - border-top: 1px solid #dfe2e5; - margin: 0; - padding: 0; -} -table tr:nth-child(2n), -thead { - background-color: #f8f8f8; -} -table tr th { - font-weight: bold; - border: 1px solid #dfe2e5; - border-bottom: 0; - text-align: left; - margin: 0; - padding: 6px 13px; -} -table tr td { - border: 1px solid #dfe2e5; - text-align: left; - margin: 0; - padding: 6px 13px; -} -table tr th:first-child, -table tr td:first-child { - margin-top: 0; -} -table tr th:last-child, -table tr td:last-child { - margin-bottom: 0; -} -h1 code,h2 code, h3 code, h4 code, h5 code, h6 code, -p code, li code, td code, -tt { - border: 1px solid #e7eaed; - background-color: #f8f8f8; - -webkit-border-radius: 3px; - border-radius: 3px; - padding: 0; - font-size: 0.9em; - color:var(--sg1); - font-family:monospace; - background-color: #f3f4f4; - padding: 0 2px 0 2px; -} -/*Tell prettyprinted code not to follow above*/ -.prettyprint code{ - border:none; - background-color:transparent; - font-size:inherit; - padding:0 1px 0 0px; -} \ No newline at end of file diff --git a/documentation/tdenginedocs-en/lib/docs/liner.js b/documentation/tdenginedocs-en/lib/docs/liner.js deleted file mode 100644 index 9cfeb88e1042ba9156234de4fcc5f9b82f82cf7a..0000000000000000000000000000000000000000 --- a/documentation/tdenginedocs-en/lib/docs/liner.js +++ /dev/null @@ -1,19 +0,0 @@ -/*JS to determine how many lines used in pre/code block, sets CSS appropriately. MUST be placed after elements with prettyprint class are loaded*/ -$('.prettyprint').toArray().forEach(function(element){ - let linenums = element.clientHeight / 25.2; - if (linenums > 99) { - $(element).addClass('threec'); - } - else if (linenums > 9) { - $(element).addClass('twoc'); - } - }); -$('.prettyprint').toArray().forEach(function(element){ - let linenums = element.clientHeight / 25.2; - if (linenums > 99) { - $(element).addClass('threec'); - } - else if (linenums > 9) { - $(element).addClass('twoc'); - } -}); \ No newline at end of file diff --git a/documentation/tdenginedocs-en/lib/docs/prettify.js b/documentation/tdenginedocs-en/lib/docs/prettify.js deleted file mode 100644 index d2acd5d9d4f14db8bef0005d7ba891042a6820e8..0000000000000000000000000000000000000000 --- a/documentation/tdenginedocs-en/lib/docs/prettify.js +++ /dev/null @@ -1,46 +0,0 @@ -!function(){/* - - Copyright (C) 2006 Google Inc. - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. -*/ -"undefined"!==typeof window&&(window.PR_SHOULD_USE_CONTINUATION=!0); -(function(){function T(a){function d(e){var a=e.charCodeAt(0);if(92!==a)return a;var c=e.charAt(1);return(a=w[c])?a:"0"<=c&&"7">=c?parseInt(e.substring(1),8):"u"===c||"x"===c?parseInt(e.substring(2),16):e.charCodeAt(1)}function f(e){if(32>e)return(16>e?"\\x0":"\\x")+e.toString(16);e=String.fromCharCode(e);return"\\"===e||"-"===e||"]"===e||"^"===e?"\\"+e:e}function c(e){var c=e.substring(1,e.length-1).match(RegExp("\\\\u[0-9A-Fa-f]{4}|\\\\x[0-9A-Fa-f]{2}|\\\\[0-3][0-7]{0,2}|\\\\[0-7]{1,2}|\\\\[\\s\\S]|-|[^-\\\\]","g")); -e=[];var a="^"===c[0],b=["["];a&&b.push("^");for(var a=a?1:0,g=c.length;ak||122k||90k||122h[0]&&(h[1]+1>h[0]&&b.push("-"),b.push(f(h[1])));b.push("]");return b.join("")}function m(e){for(var a=e.source.match(RegExp("(?:\\[(?:[^\\x5C\\x5D]|\\\\[\\s\\S])*\\]|\\\\u[A-Fa-f0-9]{4}|\\\\x[A-Fa-f0-9]{2}|\\\\[0-9]+|\\\\[^ux0-9]|\\(\\?[:!=]|[\\(\\)\\^]|[^\\x5B\\x5C\\(\\)\\^]+)","g")),b=a.length,d=[],g=0,h=0;g/,null])):d.push(["com",/^#[^\r\n]*/,null,"#"]));a.cStyleComments&&(f.push(["com",/^\/\/[^\r\n]*/,null]),f.push(["com",/^\/\*[\s\S]*?(?:\*\/|$)/,null]));if(c=a.regexLiterals){var m=(c=1|\\/=?|::?|<>?>?=?|,|;|\\?|@|\\[|~|{|\\^\\^?=?|\\|\\|?=?|break|case|continue|delete|do|else|finally|instanceof|return|throw|try|typeof)\\s*("+ -("/(?=[^/*"+c+"])(?:[^/\\x5B\\x5C"+c+"]|\\x5C"+m+"|\\x5B(?:[^\\x5C\\x5D"+c+"]|\\x5C"+m+")*(?:\\x5D|$))+/")+")")])}(c=a.types)&&f.push(["typ",c]);c=(""+a.keywords).replace(/^ | $/g,"");c.length&&f.push(["kwd",new RegExp("^(?:"+c.replace(/[\s,]+/g,"|")+")\\b"),null]);d.push(["pln",/^\s+/,null," \r\n\t\u00a0"]);c="^.[^\\s\\w.$@'\"`/\\\\]*";a.regexLiterals&&(c+="(?!s*/)");f.push(["lit",/^@[a-z_$][a-z_$@0-9]*/i,null],["typ",/^(?:[@_]?[A-Z]+[a-z][A-Za-z_$@0-9]*|\w+_t\b)/,null],["pln",/^[a-z_$][a-z_$@0-9]*/i, -null],["lit",/^(?:0x[a-f0-9]+|(?:\d(?:_\d+)*\d*(?:\.\d*)?|\.\d\+)(?:e[+\-]?\d+)?)[a-z]*/i,null,"0123456789"],["pln",/^\\[\s\S]?/,null],["pun",new RegExp(c),null]);return G(d,f)}function L(a,d,f){function c(a){var b=a.nodeType;if(1==b&&!t.test(a.className))if("br"===a.nodeName.toLowerCase())m(a),a.parentNode&&a.parentNode.removeChild(a);else for(a=a.firstChild;a;a=a.nextSibling)c(a);else if((3==b||4==b)&&f){var e=a.nodeValue,d=e.match(q);d&&(b=e.substring(0,d.index),a.nodeValue=b,(e=e.substring(d.index+ -d[0].length))&&a.parentNode.insertBefore(l.createTextNode(e),a.nextSibling),m(a),b||a.parentNode.removeChild(a))}}function m(a){function c(a,b){var e=b?a.cloneNode(!1):a,k=a.parentNode;if(k){var k=c(k,1),d=a.nextSibling;k.appendChild(e);for(var f=d;f;f=d)d=f.nextSibling,k.appendChild(f)}return e}for(;!a.nextSibling;)if(a=a.parentNode,!a)return;a=c(a.nextSibling,0);for(var e;(e=a.parentNode)&&1===e.nodeType;)a=e;b.push(a)}for(var t=/(?:^|\s)nocode(?:\s|$)/,q=/\r\n?|\n/,l=a.ownerDocument,n=l.createElement("li");a.firstChild;)n.appendChild(a.firstChild); -for(var b=[n],p=0;p=+m[1],d=/\n/g,t=a.a,q=t.length,f=0,l=a.c,n=l.length,c=0,b=a.g,p=b.length,w=0;b[p]=q;var r,e;for(e=r=0;e=h&&(c+=2);f>=k&&(w+=2)}}finally{g&&(g.style.display=a)}}catch(y){D.console&&console.log(y&&y.stack||y)}}var D="undefined"!==typeof window? -window:{},B=["break,continue,do,else,for,if,return,while"],F=[[B,"auto,case,char,const,default,double,enum,extern,float,goto,inline,int,long,register,restrict,short,signed,sizeof,static,struct,switch,typedef,union,unsigned,void,volatile"],"catch,class,delete,false,import,new,operator,private,protected,public,this,throw,true,try,typeof"],H=[F,"alignas,alignof,align_union,asm,axiom,bool,concept,concept_map,const_cast,constexpr,decltype,delegate,dynamic_cast,explicit,export,friend,generic,late_check,mutable,namespace,noexcept,noreturn,nullptr,property,reinterpret_cast,static_assert,static_cast,template,typeid,typename,using,virtual,where"], -O=[F,"abstract,assert,boolean,byte,extends,finally,final,implements,import,instanceof,interface,null,native,package,strictfp,super,synchronized,throws,transient"],P=[F,"abstract,add,alias,as,ascending,async,await,base,bool,by,byte,checked,decimal,delegate,descending,dynamic,event,finally,fixed,foreach,from,get,global,group,implicit,in,interface,internal,into,is,join,let,lock,null,object,out,override,orderby,params,partial,readonly,ref,remove,sbyte,sealed,select,set,stackalloc,string,select,uint,ulong,unchecked,unsafe,ushort,value,var,virtual,where,yield"], -F=[F,"abstract,async,await,constructor,debugger,enum,eval,export,from,function,get,import,implements,instanceof,interface,let,null,of,set,undefined,var,with,yield,Infinity,NaN"],Q=[B,"and,as,assert,class,def,del,elif,except,exec,finally,from,global,import,in,is,lambda,nonlocal,not,or,pass,print,raise,try,with,yield,False,True,None"],R=[B,"alias,and,begin,case,class,def,defined,elsif,end,ensure,false,in,module,next,nil,not,or,redo,rescue,retry,self,super,then,true,undef,unless,until,when,yield,BEGIN,END"], -B=[B,"case,done,elif,esac,eval,fi,function,in,local,set,then,until"],S=/^(DIR|FILE|array|vector|(de|priority_)?queue|(forward_)?list|stack|(const_)?(reverse_)?iterator|(unordered_)?(multi)?(set|map)|bitset|u?(int|float)\d*)\b/,W=/\S/,X=x({keywords:[H,P,O,F,"caller,delete,die,do,dump,elsif,eval,exit,foreach,for,goto,if,import,last,local,my,next,no,our,print,package,redo,require,sub,undef,unless,until,use,wantarray,while,BEGIN,END",Q,R,B],hashComments:!0,cStyleComments:!0,multiLineStrings:!0,regexLiterals:!0}), -I={};t(X,["default-code"]);t(G([],[["pln",/^[^]*(?:>|$)/],["com",/^<\!--[\s\S]*?(?:-\->|$)/],["lang-",/^<\?([\s\S]+?)(?:\?>|$)/],["lang-",/^<%([\s\S]+?)(?:%>|$)/],["pun",/^(?:<[%?]|[%?]>)/],["lang-",/^]*>([\s\S]+?)<\/xmp\b[^>]*>/i],["lang-js",/^]*>([\s\S]*?)(<\/script\b[^>]*>)/i],["lang-css",/^]*>([\s\S]*?)(<\/style\b[^>]*>)/i],["lang-in.tag",/^(<\/?[a-z][^<>]*>)/i]]),"default-markup htm html mxml xhtml xml xsl".split(" "));t(G([["pln",/^[\s]+/, -null," \t\r\n"],["atv",/^(?:\"[^\"]*\"?|\'[^\']*\'?)/,null,"\"'"]],[["tag",/^^<\/?[a-z](?:[\w.:-]*\w)?|\/?>$/i],["atn",/^(?!style[\s=]|on)[a-z](?:[\w:-]*\w)?/i],["lang-uq.val",/^=\s*([^>\'\"\s]*(?:[^>\'\"\s\/]|\/(?=\s)))/],["pun",/^[=<>\/]+/],["lang-js",/^on\w+\s*=\s*\"([^\"]+)\"/i],["lang-js",/^on\w+\s*=\s*\'([^\']+)\'/i],["lang-js",/^on\w+\s*=\s*([^\"\'>\s]+)/i],["lang-css",/^style\s*=\s*\"([^\"]+)\"/i],["lang-css",/^style\s*=\s*\'([^\']+)\'/i],["lang-css",/^style\s*=\s*([^\"\'>\s]+)/i]]),["in.tag"]); -t(G([],[["atv",/^[\s\S]+/]]),["uq.val"]);t(x({keywords:H,hashComments:!0,cStyleComments:!0,types:S}),"c cc cpp cxx cyc m".split(" "));t(x({keywords:"null,true,false"}),["json"]);t(x({keywords:P,hashComments:!0,cStyleComments:!0,verbatimStrings:!0,types:S}),["cs"]);t(x({keywords:O,cStyleComments:!0}),["java"]);t(x({keywords:B,hashComments:!0,multiLineStrings:!0}),["bash","bsh","csh","sh"]);t(x({keywords:Q,hashComments:!0,multiLineStrings:!0,tripleQuotedStrings:!0}),["cv","py","python"]);t(x({keywords:"caller,delete,die,do,dump,elsif,eval,exit,foreach,for,goto,if,import,last,local,my,next,no,our,print,package,redo,require,sub,undef,unless,until,use,wantarray,while,BEGIN,END", -hashComments:!0,multiLineStrings:!0,regexLiterals:2}),["perl","pl","pm"]);t(x({keywords:R,hashComments:!0,multiLineStrings:!0,regexLiterals:!0}),["rb","ruby"]);t(x({keywords:F,cStyleComments:!0,regexLiterals:!0}),["javascript","js","ts","typescript"]);t(x({keywords:"all,and,by,catch,class,else,extends,false,finally,for,if,in,is,isnt,loop,new,no,not,null,of,off,on,or,return,super,then,throw,true,try,unless,until,when,while,yes",hashComments:3,cStyleComments:!0,multilineStrings:!0,tripleQuotedStrings:!0, -regexLiterals:!0}),["coffee"]);t(G([],[["str",/^[\s\S]+/]]),["regex"]);var Y=D.PR={createSimpleLexer:G,registerLangHandler:t,sourceDecorator:x,PR_ATTRIB_NAME:"atn",PR_ATTRIB_VALUE:"atv",PR_COMMENT:"com",PR_DECLARATION:"dec",PR_KEYWORD:"kwd",PR_LITERAL:"lit",PR_NOCODE:"nocode",PR_PLAIN:"pln",PR_PUNCTUATION:"pun",PR_SOURCE:"src",PR_STRING:"str",PR_TAG:"tag",PR_TYPE:"typ",TAOSDATA_FUNCTION:"td-fun",TAOSDATA_DATATYPE:"td-dtp",TAOSDATA_TERMINAL:"tem",TAOSDATA_OPTION:"td-opt",prettyPrintOne:D.prettyPrintOne=function(a,d,f){f=f||!1;d=d||null;var c=document.createElement("div");c.innerHTML="
    "+a+"
    "; -c=c.firstChild;f&&L(c,f,!0);M({j:d,m:f,h:c,l:1,a:null,i:null,c:null,g:null});return c.innerHTML},prettyPrint:D.prettyPrint=function(a,d){function f(){for(var c=D.PR_SHOULD_USE_CONTINUATION?b.now()+250:Infinity;p li { - counter-increment: customlistcounter; -} -pre.prettyprint ol > li:first-child:before { - border-top-left-radius: 0.25rem; -} -pre.prettyprint ol > li:last-child:before { - border-bottom-left-radius: 0.25rem; -} -pre.prettyprint ol > li:before { - content: counter(customlistcounter) " "; - font-weight: 300; - display: inline-block; - position: absolute; - transform:translateX(-38px); - width: 27px; - text-align: right; - background-color:var(--white); - padding-bottom: 0.1px; -} -pre.prettyprint ol > li:nth-last-child(1)::before { - padding-bottom: 0px !important; -} - -pre.prettyprint.twoc ol > li:before { - transform:translateX(-45px); - width:34px; -} -pre.prettyprint.twoc { - padding-left:35px; -} -pre.prettyprint.threec ol > li:before { - transform:translateX(-53px); - width:42px; -} -pre.prettyprint.threec { - padding-left:43px; -} - -ol:first-child { - counter-reset: customlistcounter; -} -pre.prettyprint ol { - padding-right: 4px; -} -pre .atn, -pre .kwd, -pre .tag { - font-weight: 400 -} -pre * { - font-family:monospace; -} -pre.prettyprint li { - background-color:rgb(244,245,246); -} -pre.prettyprint { - display: block; - background-color:rgb(244,245,246); - border-radius:0.25rem; - padding-left: 27px; - /*each additional digit needs 8px*/ - width:100%; - border:1px solid #e7eaed; - color:#d58936; -} -/* TAOSDATA Specific */ -pre.lang-blank span { - color:var(--sg1); -} -pre.lang-blank { - -} -pre.lang-term span{ - color: var(--white) ; -} -pre.lang-term ol { - background-color: var(--sg1); -} -pre.lang-term ol.linenums { - border-left:1px solid var(--sg1); -} -pre.lang-term li { - background-color:var(--sg1); -} -/*Functions*/ -pre .td-fun { - color:#f24352; -} -/*Options*/ -pre .td-opt { - /*color:mediumpurple;*/ - color:#5882bc; -} -/*Datatypes*/ -pre .td-dtp { - color:darkcyan; -} -pre .nocode { - background-color: var(--white); - color: var(--sg1); -} -/*Strings*/ -pre .str { - color: #690; -} -/*Keywords*/ -pre .kwd { - color: #5882bc; -} -/*Comments*/ -pre .com { - color: slategray; -} -/*Type*/ -pre .typ { - color: #9c5fc6; -} -/*Literals*/ -pre .lit { - color: #91001f; -} -/*Plain Text*/ -pre .pln { - color: #d58936; -} -/*Punctuation*/ -pre .pun { - color: rgb(51,66,78); -} -pre .tag { - color: khaki -} - -pre .atn { - color: #bdb76b -} - -pre .atv { - color: #ffa0a0 -} - -pre .dec { - color: #98fb98 -} - -ol.linenums { - margin-top: 0; - margin-bottom: 0; - color: #AEAEAE; - border-left:1px solid var(--b1); - padding-left: 0px; -} -pre li { - padding-left: 0.6rem; -} -li.L0, -li.L1, -li.L2, -li.L3, -li.L5, -li.L6, -li.L7, -li.L8 { - list-style-type: none -} - -@media print { - pre.prettyprint { - background-color: none - } - - code .str, - pre .str { - color: #690; - } - - code .kwd, - pre .kwd { - color: #5882bc; - font-weight: 400 - } - - code .com, - pre .com { - color: #600; - font-style: italic - } - - code .typ, - pre .typ { - color: #404; - font-weight: 400 - } - - code .lit, - pre .lit { - color: #044 - } - - code .pun, - pre .pun { - color: #440 - } - - code .pln, - pre .pln { - color: #000 - } - - code .tag, - pre .tag { - color: #006; - font-weight: 400 - } - - code .atn, - pre .atn { - color: #404 - } - - code .atv, - pre .atv { - color: #060 - } -} \ No newline at end of file diff --git a/documentation/tdenginedocs-en/lib/jquery-3.4.1.min.js b/documentation/tdenginedocs-en/lib/jquery-3.4.1.min.js deleted file mode 100644 index a1c07fd803b5fc9c54f44e31123ae4fa11e134b0..0000000000000000000000000000000000000000 --- a/documentation/tdenginedocs-en/lib/jquery-3.4.1.min.js +++ /dev/null @@ -1,2 +0,0 @@ -/*! jQuery v3.4.1 | (c) JS Foundation and other contributors | jquery.org/license */ -!function(e,t){"use strict";"object"==typeof module&&"object"==typeof module.exports?module.exports=e.document?t(e,!0):function(e){if(!e.document)throw new Error("jQuery requires a window with a document");return t(e)}:t(e)}("undefined"!=typeof window?window:this,function(C,e){"use strict";var t=[],E=C.document,r=Object.getPrototypeOf,s=t.slice,g=t.concat,u=t.push,i=t.indexOf,n={},o=n.toString,v=n.hasOwnProperty,a=v.toString,l=a.call(Object),y={},m=function(e){return"function"==typeof e&&"number"!=typeof e.nodeType},x=function(e){return null!=e&&e===e.window},c={type:!0,src:!0,nonce:!0,noModule:!0};function b(e,t,n){var r,i,o=(n=n||E).createElement("script");if(o.text=e,t)for(r in c)(i=t[r]||t.getAttribute&&t.getAttribute(r))&&o.setAttribute(r,i);n.head.appendChild(o).parentNode.removeChild(o)}function w(e){return null==e?e+"":"object"==typeof e||"function"==typeof e?n[o.call(e)]||"object":typeof e}var f="3.4.1",k=function(e,t){return new k.fn.init(e,t)},p=/^[\s\uFEFF\xA0]+|[\s\uFEFF\xA0]+$/g;function d(e){var t=!!e&&"length"in e&&e.length,n=w(e);return!m(e)&&!x(e)&&("array"===n||0===t||"number"==typeof t&&0+~]|"+M+")"+M+"*"),U=new RegExp(M+"|>"),X=new RegExp($),V=new RegExp("^"+I+"$"),G={ID:new RegExp("^#("+I+")"),CLASS:new RegExp("^\\.("+I+")"),TAG:new RegExp("^("+I+"|[*])"),ATTR:new RegExp("^"+W),PSEUDO:new RegExp("^"+$),CHILD:new RegExp("^:(only|first|last|nth|nth-last)-(child|of-type)(?:\\("+M+"*(even|odd|(([+-]|)(\\d*)n|)"+M+"*(?:([+-]|)"+M+"*(\\d+)|))"+M+"*\\)|)","i"),bool:new RegExp("^(?:"+R+")$","i"),needsContext:new RegExp("^"+M+"*[>+~]|:(even|odd|eq|gt|lt|nth|first|last)(?:\\("+M+"*((?:-\\d)?\\d*)"+M+"*\\)|)(?=[^-]|$)","i")},Y=/HTML$/i,Q=/^(?:input|select|textarea|button)$/i,J=/^h\d$/i,K=/^[^{]+\{\s*\[native \w/,Z=/^(?:#([\w-]+)|(\w+)|\.([\w-]+))$/,ee=/[+~]/,te=new RegExp("\\\\([\\da-f]{1,6}"+M+"?|("+M+")|.)","ig"),ne=function(e,t,n){var r="0x"+t-65536;return r!=r||n?t:r<0?String.fromCharCode(r+65536):String.fromCharCode(r>>10|55296,1023&r|56320)},re=/([\0-\x1f\x7f]|^-?\d)|^-$|[^\0-\x1f\x7f-\uFFFF\w-]/g,ie=function(e,t){return t?"\0"===e?"\ufffd":e.slice(0,-1)+"\\"+e.charCodeAt(e.length-1).toString(16)+" ":"\\"+e},oe=function(){T()},ae=be(function(e){return!0===e.disabled&&"fieldset"===e.nodeName.toLowerCase()},{dir:"parentNode",next:"legend"});try{H.apply(t=O.call(m.childNodes),m.childNodes),t[m.childNodes.length].nodeType}catch(e){H={apply:t.length?function(e,t){L.apply(e,O.call(t))}:function(e,t){var n=e.length,r=0;while(e[n++]=t[r++]);e.length=n-1}}}function se(t,e,n,r){var i,o,a,s,u,l,c,f=e&&e.ownerDocument,p=e?e.nodeType:9;if(n=n||[],"string"!=typeof t||!t||1!==p&&9!==p&&11!==p)return n;if(!r&&((e?e.ownerDocument||e:m)!==C&&T(e),e=e||C,E)){if(11!==p&&(u=Z.exec(t)))if(i=u[1]){if(9===p){if(!(a=e.getElementById(i)))return n;if(a.id===i)return n.push(a),n}else if(f&&(a=f.getElementById(i))&&y(e,a)&&a.id===i)return n.push(a),n}else{if(u[2])return H.apply(n,e.getElementsByTagName(t)),n;if((i=u[3])&&d.getElementsByClassName&&e.getElementsByClassName)return H.apply(n,e.getElementsByClassName(i)),n}if(d.qsa&&!A[t+" "]&&(!v||!v.test(t))&&(1!==p||"object"!==e.nodeName.toLowerCase())){if(c=t,f=e,1===p&&U.test(t)){(s=e.getAttribute("id"))?s=s.replace(re,ie):e.setAttribute("id",s=k),o=(l=h(t)).length;while(o--)l[o]="#"+s+" "+xe(l[o]);c=l.join(","),f=ee.test(t)&&ye(e.parentNode)||e}try{return H.apply(n,f.querySelectorAll(c)),n}catch(e){A(t,!0)}finally{s===k&&e.removeAttribute("id")}}}return g(t.replace(B,"$1"),e,n,r)}function ue(){var r=[];return function e(t,n){return r.push(t+" ")>b.cacheLength&&delete e[r.shift()],e[t+" "]=n}}function le(e){return e[k]=!0,e}function ce(e){var t=C.createElement("fieldset");try{return!!e(t)}catch(e){return!1}finally{t.parentNode&&t.parentNode.removeChild(t),t=null}}function fe(e,t){var n=e.split("|"),r=n.length;while(r--)b.attrHandle[n[r]]=t}function pe(e,t){var n=t&&e,r=n&&1===e.nodeType&&1===t.nodeType&&e.sourceIndex-t.sourceIndex;if(r)return r;if(n)while(n=n.nextSibling)if(n===t)return-1;return e?1:-1}function de(t){return function(e){return"input"===e.nodeName.toLowerCase()&&e.type===t}}function he(n){return function(e){var t=e.nodeName.toLowerCase();return("input"===t||"button"===t)&&e.type===n}}function ge(t){return function(e){return"form"in e?e.parentNode&&!1===e.disabled?"label"in e?"label"in e.parentNode?e.parentNode.disabled===t:e.disabled===t:e.isDisabled===t||e.isDisabled!==!t&&ae(e)===t:e.disabled===t:"label"in e&&e.disabled===t}}function ve(a){return le(function(o){return o=+o,le(function(e,t){var n,r=a([],e.length,o),i=r.length;while(i--)e[n=r[i]]&&(e[n]=!(t[n]=e[n]))})})}function ye(e){return e&&"undefined"!=typeof e.getElementsByTagName&&e}for(e in d=se.support={},i=se.isXML=function(e){var t=e.namespaceURI,n=(e.ownerDocument||e).documentElement;return!Y.test(t||n&&n.nodeName||"HTML")},T=se.setDocument=function(e){var t,n,r=e?e.ownerDocument||e:m;return r!==C&&9===r.nodeType&&r.documentElement&&(a=(C=r).documentElement,E=!i(C),m!==C&&(n=C.defaultView)&&n.top!==n&&(n.addEventListener?n.addEventListener("unload",oe,!1):n.attachEvent&&n.attachEvent("onunload",oe)),d.attributes=ce(function(e){return e.className="i",!e.getAttribute("className")}),d.getElementsByTagName=ce(function(e){return e.appendChild(C.createComment("")),!e.getElementsByTagName("*").length}),d.getElementsByClassName=K.test(C.getElementsByClassName),d.getById=ce(function(e){return a.appendChild(e).id=k,!C.getElementsByName||!C.getElementsByName(k).length}),d.getById?(b.filter.ID=function(e){var t=e.replace(te,ne);return function(e){return e.getAttribute("id")===t}},b.find.ID=function(e,t){if("undefined"!=typeof t.getElementById&&E){var n=t.getElementById(e);return n?[n]:[]}}):(b.filter.ID=function(e){var n=e.replace(te,ne);return function(e){var t="undefined"!=typeof e.getAttributeNode&&e.getAttributeNode("id");return t&&t.value===n}},b.find.ID=function(e,t){if("undefined"!=typeof t.getElementById&&E){var n,r,i,o=t.getElementById(e);if(o){if((n=o.getAttributeNode("id"))&&n.value===e)return[o];i=t.getElementsByName(e),r=0;while(o=i[r++])if((n=o.getAttributeNode("id"))&&n.value===e)return[o]}return[]}}),b.find.TAG=d.getElementsByTagName?function(e,t){return"undefined"!=typeof t.getElementsByTagName?t.getElementsByTagName(e):d.qsa?t.querySelectorAll(e):void 0}:function(e,t){var n,r=[],i=0,o=t.getElementsByTagName(e);if("*"===e){while(n=o[i++])1===n.nodeType&&r.push(n);return r}return o},b.find.CLASS=d.getElementsByClassName&&function(e,t){if("undefined"!=typeof t.getElementsByClassName&&E)return t.getElementsByClassName(e)},s=[],v=[],(d.qsa=K.test(C.querySelectorAll))&&(ce(function(e){a.appendChild(e).innerHTML="",e.querySelectorAll("[msallowcapture^='']").length&&v.push("[*^$]="+M+"*(?:''|\"\")"),e.querySelectorAll("[selected]").length||v.push("\\["+M+"*(?:value|"+R+")"),e.querySelectorAll("[id~="+k+"-]").length||v.push("~="),e.querySelectorAll(":checked").length||v.push(":checked"),e.querySelectorAll("a#"+k+"+*").length||v.push(".#.+[+~]")}),ce(function(e){e.innerHTML="";var t=C.createElement("input");t.setAttribute("type","hidden"),e.appendChild(t).setAttribute("name","D"),e.querySelectorAll("[name=d]").length&&v.push("name"+M+"*[*^$|!~]?="),2!==e.querySelectorAll(":enabled").length&&v.push(":enabled",":disabled"),a.appendChild(e).disabled=!0,2!==e.querySelectorAll(":disabled").length&&v.push(":enabled",":disabled"),e.querySelectorAll("*,:x"),v.push(",.*:")})),(d.matchesSelector=K.test(c=a.matches||a.webkitMatchesSelector||a.mozMatchesSelector||a.oMatchesSelector||a.msMatchesSelector))&&ce(function(e){d.disconnectedMatch=c.call(e,"*"),c.call(e,"[s!='']:x"),s.push("!=",$)}),v=v.length&&new RegExp(v.join("|")),s=s.length&&new RegExp(s.join("|")),t=K.test(a.compareDocumentPosition),y=t||K.test(a.contains)?function(e,t){var n=9===e.nodeType?e.documentElement:e,r=t&&t.parentNode;return e===r||!(!r||1!==r.nodeType||!(n.contains?n.contains(r):e.compareDocumentPosition&&16&e.compareDocumentPosition(r)))}:function(e,t){if(t)while(t=t.parentNode)if(t===e)return!0;return!1},D=t?function(e,t){if(e===t)return l=!0,0;var n=!e.compareDocumentPosition-!t.compareDocumentPosition;return n||(1&(n=(e.ownerDocument||e)===(t.ownerDocument||t)?e.compareDocumentPosition(t):1)||!d.sortDetached&&t.compareDocumentPosition(e)===n?e===C||e.ownerDocument===m&&y(m,e)?-1:t===C||t.ownerDocument===m&&y(m,t)?1:u?P(u,e)-P(u,t):0:4&n?-1:1)}:function(e,t){if(e===t)return l=!0,0;var n,r=0,i=e.parentNode,o=t.parentNode,a=[e],s=[t];if(!i||!o)return e===C?-1:t===C?1:i?-1:o?1:u?P(u,e)-P(u,t):0;if(i===o)return pe(e,t);n=e;while(n=n.parentNode)a.unshift(n);n=t;while(n=n.parentNode)s.unshift(n);while(a[r]===s[r])r++;return r?pe(a[r],s[r]):a[r]===m?-1:s[r]===m?1:0}),C},se.matches=function(e,t){return se(e,null,null,t)},se.matchesSelector=function(e,t){if((e.ownerDocument||e)!==C&&T(e),d.matchesSelector&&E&&!A[t+" "]&&(!s||!s.test(t))&&(!v||!v.test(t)))try{var n=c.call(e,t);if(n||d.disconnectedMatch||e.document&&11!==e.document.nodeType)return n}catch(e){A(t,!0)}return 0":{dir:"parentNode",first:!0}," ":{dir:"parentNode"},"+":{dir:"previousSibling",first:!0},"~":{dir:"previousSibling"}},preFilter:{ATTR:function(e){return e[1]=e[1].replace(te,ne),e[3]=(e[3]||e[4]||e[5]||"").replace(te,ne),"~="===e[2]&&(e[3]=" "+e[3]+" "),e.slice(0,4)},CHILD:function(e){return e[1]=e[1].toLowerCase(),"nth"===e[1].slice(0,3)?(e[3]||se.error(e[0]),e[4]=+(e[4]?e[5]+(e[6]||1):2*("even"===e[3]||"odd"===e[3])),e[5]=+(e[7]+e[8]||"odd"===e[3])):e[3]&&se.error(e[0]),e},PSEUDO:function(e){var t,n=!e[6]&&e[2];return G.CHILD.test(e[0])?null:(e[3]?e[2]=e[4]||e[5]||"":n&&X.test(n)&&(t=h(n,!0))&&(t=n.indexOf(")",n.length-t)-n.length)&&(e[0]=e[0].slice(0,t),e[2]=n.slice(0,t)),e.slice(0,3))}},filter:{TAG:function(e){var t=e.replace(te,ne).toLowerCase();return"*"===e?function(){return!0}:function(e){return e.nodeName&&e.nodeName.toLowerCase()===t}},CLASS:function(e){var t=p[e+" "];return t||(t=new RegExp("(^|"+M+")"+e+"("+M+"|$)"))&&p(e,function(e){return t.test("string"==typeof e.className&&e.className||"undefined"!=typeof e.getAttribute&&e.getAttribute("class")||"")})},ATTR:function(n,r,i){return function(e){var t=se.attr(e,n);return null==t?"!="===r:!r||(t+="","="===r?t===i:"!="===r?t!==i:"^="===r?i&&0===t.indexOf(i):"*="===r?i&&-1:\x20\t\r\n\f]*)[\x20\t\r\n\f]*\/?>(?:<\/\1>|)$/i;function j(e,n,r){return m(n)?k.grep(e,function(e,t){return!!n.call(e,t,e)!==r}):n.nodeType?k.grep(e,function(e){return e===n!==r}):"string"!=typeof n?k.grep(e,function(e){return-1)[^>]*|#([\w-]+))$/;(k.fn.init=function(e,t,n){var r,i;if(!e)return this;if(n=n||q,"string"==typeof e){if(!(r="<"===e[0]&&">"===e[e.length-1]&&3<=e.length?[null,e,null]:L.exec(e))||!r[1]&&t)return!t||t.jquery?(t||n).find(e):this.constructor(t).find(e);if(r[1]){if(t=t instanceof k?t[0]:t,k.merge(this,k.parseHTML(r[1],t&&t.nodeType?t.ownerDocument||t:E,!0)),D.test(r[1])&&k.isPlainObject(t))for(r in t)m(this[r])?this[r](t[r]):this.attr(r,t[r]);return this}return(i=E.getElementById(r[2]))&&(this[0]=i,this.length=1),this}return e.nodeType?(this[0]=e,this.length=1,this):m(e)?void 0!==n.ready?n.ready(e):e(k):k.makeArray(e,this)}).prototype=k.fn,q=k(E);var H=/^(?:parents|prev(?:Until|All))/,O={children:!0,contents:!0,next:!0,prev:!0};function P(e,t){while((e=e[t])&&1!==e.nodeType);return e}k.fn.extend({has:function(e){var t=k(e,this),n=t.length;return this.filter(function(){for(var e=0;e\x20\t\r\n\f]*)/i,he=/^$|^module$|\/(?:java|ecma)script/i,ge={option:[1,""],thead:[1,"","
    "],col:[2,"","
    "],tr:[2,"","
    "],td:[3,"","
    "],_default:[0,"",""]};function ve(e,t){var n;return n="undefined"!=typeof e.getElementsByTagName?e.getElementsByTagName(t||"*"):"undefined"!=typeof e.querySelectorAll?e.querySelectorAll(t||"*"):[],void 0===t||t&&A(e,t)?k.merge([e],n):n}function ye(e,t){for(var n=0,r=e.length;nx",y.noCloneChecked=!!me.cloneNode(!0).lastChild.defaultValue;var Te=/^key/,Ce=/^(?:mouse|pointer|contextmenu|drag|drop)|click/,Ee=/^([^.]*)(?:\.(.+)|)/;function ke(){return!0}function Se(){return!1}function Ne(e,t){return e===function(){try{return E.activeElement}catch(e){}}()==("focus"===t)}function Ae(e,t,n,r,i,o){var a,s;if("object"==typeof t){for(s in"string"!=typeof n&&(r=r||n,n=void 0),t)Ae(e,s,n,r,t[s],o);return e}if(null==r&&null==i?(i=n,r=n=void 0):null==i&&("string"==typeof n?(i=r,r=void 0):(i=r,r=n,n=void 0)),!1===i)i=Se;else if(!i)return e;return 1===o&&(a=i,(i=function(e){return k().off(e),a.apply(this,arguments)}).guid=a.guid||(a.guid=k.guid++)),e.each(function(){k.event.add(this,t,i,r,n)})}function De(e,i,o){o?(Q.set(e,i,!1),k.event.add(e,i,{namespace:!1,handler:function(e){var t,n,r=Q.get(this,i);if(1&e.isTrigger&&this[i]){if(r.length)(k.event.special[i]||{}).delegateType&&e.stopPropagation();else if(r=s.call(arguments),Q.set(this,i,r),t=o(this,i),this[i](),r!==(n=Q.get(this,i))||t?Q.set(this,i,!1):n={},r!==n)return e.stopImmediatePropagation(),e.preventDefault(),n.value}else r.length&&(Q.set(this,i,{value:k.event.trigger(k.extend(r[0],k.Event.prototype),r.slice(1),this)}),e.stopImmediatePropagation())}})):void 0===Q.get(e,i)&&k.event.add(e,i,ke)}k.event={global:{},add:function(t,e,n,r,i){var o,a,s,u,l,c,f,p,d,h,g,v=Q.get(t);if(v){n.handler&&(n=(o=n).handler,i=o.selector),i&&k.find.matchesSelector(ie,i),n.guid||(n.guid=k.guid++),(u=v.events)||(u=v.events={}),(a=v.handle)||(a=v.handle=function(e){return"undefined"!=typeof k&&k.event.triggered!==e.type?k.event.dispatch.apply(t,arguments):void 0}),l=(e=(e||"").match(R)||[""]).length;while(l--)d=g=(s=Ee.exec(e[l])||[])[1],h=(s[2]||"").split(".").sort(),d&&(f=k.event.special[d]||{},d=(i?f.delegateType:f.bindType)||d,f=k.event.special[d]||{},c=k.extend({type:d,origType:g,data:r,handler:n,guid:n.guid,selector:i,needsContext:i&&k.expr.match.needsContext.test(i),namespace:h.join(".")},o),(p=u[d])||((p=u[d]=[]).delegateCount=0,f.setup&&!1!==f.setup.call(t,r,h,a)||t.addEventListener&&t.addEventListener(d,a)),f.add&&(f.add.call(t,c),c.handler.guid||(c.handler.guid=n.guid)),i?p.splice(p.delegateCount++,0,c):p.push(c),k.event.global[d]=!0)}},remove:function(e,t,n,r,i){var o,a,s,u,l,c,f,p,d,h,g,v=Q.hasData(e)&&Q.get(e);if(v&&(u=v.events)){l=(t=(t||"").match(R)||[""]).length;while(l--)if(d=g=(s=Ee.exec(t[l])||[])[1],h=(s[2]||"").split(".").sort(),d){f=k.event.special[d]||{},p=u[d=(r?f.delegateType:f.bindType)||d]||[],s=s[2]&&new RegExp("(^|\\.)"+h.join("\\.(?:.*\\.|)")+"(\\.|$)"),a=o=p.length;while(o--)c=p[o],!i&&g!==c.origType||n&&n.guid!==c.guid||s&&!s.test(c.namespace)||r&&r!==c.selector&&("**"!==r||!c.selector)||(p.splice(o,1),c.selector&&p.delegateCount--,f.remove&&f.remove.call(e,c));a&&!p.length&&(f.teardown&&!1!==f.teardown.call(e,h,v.handle)||k.removeEvent(e,d,v.handle),delete u[d])}else for(d in u)k.event.remove(e,d+t[l],n,r,!0);k.isEmptyObject(u)&&Q.remove(e,"handle events")}},dispatch:function(e){var t,n,r,i,o,a,s=k.event.fix(e),u=new Array(arguments.length),l=(Q.get(this,"events")||{})[s.type]||[],c=k.event.special[s.type]||{};for(u[0]=s,t=1;t\x20\t\r\n\f]*)[^>]*)\/>/gi,qe=/\s*$/g;function Oe(e,t){return A(e,"table")&&A(11!==t.nodeType?t:t.firstChild,"tr")&&k(e).children("tbody")[0]||e}function Pe(e){return e.type=(null!==e.getAttribute("type"))+"/"+e.type,e}function Re(e){return"true/"===(e.type||"").slice(0,5)?e.type=e.type.slice(5):e.removeAttribute("type"),e}function Me(e,t){var n,r,i,o,a,s,u,l;if(1===t.nodeType){if(Q.hasData(e)&&(o=Q.access(e),a=Q.set(t,o),l=o.events))for(i in delete a.handle,a.events={},l)for(n=0,r=l[i].length;n")},clone:function(e,t,n){var r,i,o,a,s,u,l,c=e.cloneNode(!0),f=oe(e);if(!(y.noCloneChecked||1!==e.nodeType&&11!==e.nodeType||k.isXMLDoc(e)))for(a=ve(c),r=0,i=(o=ve(e)).length;r").attr(n.scriptAttrs||{}).prop({charset:n.scriptCharset,src:n.url}).on("load error",i=function(e){r.remove(),i=null,e&&t("error"===e.type?404:200,e.type)}),E.head.appendChild(r[0])},abort:function(){i&&i()}}});var Vt,Gt=[],Yt=/(=)\?(?=&|$)|\?\?/;k.ajaxSetup({jsonp:"callback",jsonpCallback:function(){var e=Gt.pop()||k.expando+"_"+kt++;return this[e]=!0,e}}),k.ajaxPrefilter("json jsonp",function(e,t,n){var r,i,o,a=!1!==e.jsonp&&(Yt.test(e.url)?"url":"string"==typeof e.data&&0===(e.contentType||"").indexOf("application/x-www-form-urlencoded")&&Yt.test(e.data)&&"data");if(a||"jsonp"===e.dataTypes[0])return r=e.jsonpCallback=m(e.jsonpCallback)?e.jsonpCallback():e.jsonpCallback,a?e[a]=e[a].replace(Yt,"$1"+r):!1!==e.jsonp&&(e.url+=(St.test(e.url)?"&":"?")+e.jsonp+"="+r),e.converters["script json"]=function(){return o||k.error(r+" was not called"),o[0]},e.dataTypes[0]="json",i=C[r],C[r]=function(){o=arguments},n.always(function(){void 0===i?k(C).removeProp(r):C[r]=i,e[r]&&(e.jsonpCallback=t.jsonpCallback,Gt.push(r)),o&&m(i)&&i(o[0]),o=i=void 0}),"script"}),y.createHTMLDocument=((Vt=E.implementation.createHTMLDocument("").body).innerHTML="
    ",2===Vt.childNodes.length),k.parseHTML=function(e,t,n){return"string"!=typeof e?[]:("boolean"==typeof t&&(n=t,t=!1),t||(y.createHTMLDocument?((r=(t=E.implementation.createHTMLDocument("")).createElement("base")).href=E.location.href,t.head.appendChild(r)):t=E),o=!n&&[],(i=D.exec(e))?[t.createElement(i[1])]:(i=we([e],t,o),o&&o.length&&k(o).remove(),k.merge([],i.childNodes)));var r,i,o},k.fn.load=function(e,t,n){var r,i,o,a=this,s=e.indexOf(" ");return-1").append(k.parseHTML(e)).find(r):e)}).always(n&&function(e,t){a.each(function(){n.apply(this,o||[e.responseText,t,e])})}),this},k.each(["ajaxStart","ajaxStop","ajaxComplete","ajaxError","ajaxSuccess","ajaxSend"],function(e,t){k.fn[t]=function(e){return this.on(t,e)}}),k.expr.pseudos.animated=function(t){return k.grep(k.timers,function(e){return t===e.elem}).length},k.offset={setOffset:function(e,t,n){var r,i,o,a,s,u,l=k.css(e,"position"),c=k(e),f={};"static"===l&&(e.style.position="relative"),s=c.offset(),o=k.css(e,"top"),u=k.css(e,"left"),("absolute"===l||"fixed"===l)&&-1<(o+u).indexOf("auto")?(a=(r=c.position()).top,i=r.left):(a=parseFloat(o)||0,i=parseFloat(u)||0),m(t)&&(t=t.call(e,n,k.extend({},s))),null!=t.top&&(f.top=t.top-s.top+a),null!=t.left&&(f.left=t.left-s.left+i),"using"in t?t.using.call(e,f):c.css(f)}},k.fn.extend({offset:function(t){if(arguments.length)return void 0===t?this:this.each(function(e){k.offset.setOffset(this,t,e)});var e,n,r=this[0];return r?r.getClientRects().length?(e=r.getBoundingClientRect(),n=r.ownerDocument.defaultView,{top:e.top+n.pageYOffset,left:e.left+n.pageXOffset}):{top:0,left:0}:void 0},position:function(){if(this[0]){var e,t,n,r=this[0],i={top:0,left:0};if("fixed"===k.css(r,"position"))t=r.getBoundingClientRect();else{t=this.offset(),n=r.ownerDocument,e=r.offsetParent||n.documentElement;while(e&&(e===n.body||e===n.documentElement)&&"static"===k.css(e,"position"))e=e.parentNode;e&&e!==r&&1===e.nodeType&&((i=k(e).offset()).top+=k.css(e,"borderTopWidth",!0),i.left+=k.css(e,"borderLeftWidth",!0))}return{top:t.top-i.top-k.css(r,"marginTop",!0),left:t.left-i.left-k.css(r,"marginLeft",!0)}}},offsetParent:function(){return this.map(function(){var e=this.offsetParent;while(e&&"static"===k.css(e,"position"))e=e.offsetParent;return e||ie})}}),k.each({scrollLeft:"pageXOffset",scrollTop:"pageYOffset"},function(t,i){var o="pageYOffset"===i;k.fn[t]=function(e){return _(this,function(e,t,n){var r;if(x(e)?r=e:9===e.nodeType&&(r=e.defaultView),void 0===n)return r?r[i]:e[t];r?r.scrollTo(o?r.pageXOffset:n,o?n:r.pageYOffset):e[t]=n},t,e,arguments.length)}}),k.each(["top","left"],function(e,n){k.cssHooks[n]=ze(y.pixelPosition,function(e,t){if(t)return t=_e(e,n),$e.test(t)?k(e).position()[n]+"px":t})}),k.each({Height:"height",Width:"width"},function(a,s){k.each({padding:"inner"+a,content:s,"":"outer"+a},function(r,o){k.fn[o]=function(e,t){var n=arguments.length&&(r||"boolean"!=typeof e),i=r||(!0===e||!0===t?"margin":"border");return _(this,function(e,t,n){var r;return x(e)?0===o.indexOf("outer")?e["inner"+a]:e.document.documentElement["client"+a]:9===e.nodeType?(r=e.documentElement,Math.max(e.body["scroll"+a],r["scroll"+a],e.body["offset"+a],r["offset"+a],r["client"+a])):void 0===n?k.css(e,t,i):k.style(e,t,n,i)},s,n?e:void 0,n)}})}),k.each("blur focus focusin focusout resize scroll click dblclick mousedown mouseup mousemove mouseover mouseout mouseenter mouseleave change select submit keydown keypress keyup contextmenu".split(" "),function(e,n){k.fn[n]=function(e,t){return 0Documentation | Taos Data
    Back

    TDengine System Architecture

    -

    Storage Design

    -

    TDengine data mainly include metadata and data that we will introduce in the following sections.

    -

    Metadata Storage

    -

    Metadata include the information of databases, tables, etc. Metadata files are saved in /var/lib/taos/mgmt/ directory by default. The directory tree is as below:

    -
    /var/lib/taos/
-      +--mgmt/
-          +--db.db
-          +--meters.db
-          +--user.db
-          +--vgroups.db
    -

    A metadata structure (database, table, etc.) is saved as a record in a metadata file. All metadata files are appended only, and even a drop operation adds a deletion record at the end of the file.

    -

    Data storage

    -

    Data in TDengine are sharded according to the time range. Data of tables in the same vnode in a certain time range are saved in the same filegroup, such as files v0f1804*. This sharding strategy can effectively improve data searching speed. By default, a group of files contains data in 10 days, which can be configured by *daysPerFile* in the configuration file or by DAYS keyword in CREATE DATABASE clause. Data in files are blockwised. A data block only contains one table's data. Records in the same data block are sorted according to the primary timestamp, which helps to improve the compression rate and save storage. The compression algorithms used in TDengine include simple8B, delta-of-delta, RLE, LZ4, etc.

    -

    By default, TDengine data are saved in /var/lib/taos/data/ directory. /var/lib/taos/tsdb/ directory contains vnode informations and data file linkes.

    -
    /var/lib/taos/
-      +--tsdb/
-      |   +--vnode0
-      |        +--meterObj.v0
-      |        +--db/
-      |            +--v0f1804.head->/var/lib/taos/data/vnode0/v0f1804.head1
-      |            +--v0f1804.data->/var/lib/taos/data/vnode0/v0f1804.data
-      |            +--v0f1804.last->/var/lib/taos/data/vnode0/v0f1804.last1
-      |            +--v0f1805.head->/var/lib/taos/data/vnode0/v0f1805.head1
-      |            +--v0f1805.data->/var/lib/taos/data/vnode0/v0f1805.data
-      |            +--v0f1805.last->/var/lib/taos/data/vnode0/v0f1805.last1
-      |                   :
-      +--data/
-          +--vnode0/
-                +--v0f1804.head1
-                +--v0f1804.data
-                +--v0f1804.last1
-                +--v0f1805.head1
-                +--v0f1805.data
-                +--v0f1805.last1
-                        :
    -

    meterObj file

    -

    There are only one meterObj file in a vnode. Informations bout the vnode, such as created time, configuration information, vnode statistic informations are saved in this file. It has the structure like below:

    -
    <start_of_file>
-[file_header]
-[table_record1_offset&length]
-[table_record2_offset&length]
-...
-[table_recordN_offset&length]
-[table_record1]
-[table_record2]
-...
-[table_recordN]
-<end_of_file>
    -

    The file header takes 512 bytes, which mainly contains informations about the vnode. Each table record is the representation of a table on disk.

    -

    head file

    -

    The head files contain the index of data blocks in the data file. The inner organization is as below:

    -
    <start_of_file>
-[file_header]
-[table1_offset]
-[table2_offset]
-...
-[tableN_offset]
-[table1_index_block]
-[table2_index_block]
-...
-[tableN_index_block]
-<end_of_file>
    -

    The table offset array in the head file saves the information about the offsets of each table index block. Indices on data blocks in the same table are saved continuously. This also makes it efficient to load data indices on the same table. The data index block has a structure like:

    -
    [index_block_info]
-[block1_index]
-[block2_index]
-...
-[blockN_index]
    -

    The index block info part contains the information about the index block such as the number of index blocks, etc. Each block index corresponds to a real data block in the data file or last file. Information about the location of the real data block, the primary timestamp range of the data block, etc. are all saved in the block index part. The block indices are sorted in ascending order according to the primary timestamp. So we can apply algorithms such as the binary search on the data to efficiently search blocks according to time.

    -

    data file

    -

    The data files store the real data block. They are append-only. The organization is as:

    -
    <start_of_file>
-[file_header]
-[block1]
-[block2]
-...
-[blockN]
-<end_of_file>
    -

    A data block in data files only belongs to a table in the vnode and the records in a data block are sorted in ascending order according to the primary timestamp key. Data blocks are column-oriented. Data in the same column are stored contiguously, which improves reading speed and compression rate because of their similarity. A data block has the following organization:

    -
    [column1_info]
-[column2_info]
-...
-[columnN_info]
-[column1_data]
-[column2_data]
-...
-[columnN_data]
    -

    The column info part includes information about column types, column compression algorithm, column data offset and length in the data file, etc. Besides, pre-calculated results of the column data in the block are also in the column info part, which helps to improve reading speed by avoiding loading data block necessarily.

    -

    last file

    -

    To avoid storage fragment and to import query speed and compression rate, TDengine introduces an extra file, the last file. When the number of records in a data block is lower than a threshold, TDengine will flush the block to the last file for temporary storage. When new data comes, the data in the last file will be merged with the new data and form a larger data block and written to the data file. The organization of the last file is similar to the data file.

    -

    Summary

    -

    The innovation in architecture and storage design of TDengine improves resource usage. On the one hand, the virtualization makes it easy to distribute resources between different vnodes and for future scaling. On the other hand, sorted and column-oriented storage makes TDengine have a great advantage in writing, querying and compression.

    -

    Query Design

    -

    Introduction

    -

    TDengine provides a variety of query functions for both tables and super tables. In addition to regular aggregate queries, it also provides time window based query and statistical aggregation for time series data. TDengine's query processing requires the client app, management node, and data node to work together. The functions and modules involved in query processing included in each component are as follows:

    -

    Client (Client App). The client development kit, embed in a client application, consists of TAOS SQL parser and query executor, the second-stage aggregator (Result Merger), continuous query manager and other major functional modules. The SQL parser is responsible for parsing and verifying the SQL statement and converting it into an abstract syntax tree. The query executor is responsible for transforming the abstract syntax tree into the query execution logic and creates the metadata query according to the query condition of the SQL statement. Since TAOS SQL does not currently include complex nested queries and pipeline query processing mechanism, there is no longer need for query plan optimization and physical query plan conversions. The second-stage aggregator is responsible for performing the aggregation of the independent results returned by query involved data nodes at the client side to generate final results. The continuous query manager is dedicated to managing the continuous queries created by users, including issuing fixed-interval query requests and writing the results back to TDengine or returning to the client application as needed. Also, the client is also responsible for retrying after the query fails, canceling the query request, and maintaining the connection heartbeat and reporting the query status to the management node.

    -

    Management Node. The management node keeps the metadata of all the data of the entire cluster system, provides the metadata of the data required for the query from the client node, and divides the query request according to the load condition of the cluster. The super table contains information about all the tables created according to the super table, so the query processor (Query Executor) of the management node is responsible for the query processing of the tags of tables and returns the table information satisfying the tag query. Besides, the management node maintains the query status of the cluster in the Query Status Manager component, in which the metadata of all queries that are currently executing are temporarily stored in-memory buffer. When the client issues show queries command to management node, current running queries information is returned to the client.

    -

    Data Node. The data node, responsible for storing all data of the database, consists of query executor, query processing scheduler, query task queue, and other related components. Once the query requests from the client received, they are put into query task queue and waiting to be processed by query executor. The query executor extracts the query request from the query task queue and invokes the query optimizer to perform the basic optimization for the query execution plan. And then query executor scans the qualified data blocks in both cache and disk to obtain qualified data and return the calculated results. Besides, the data node also needs to respond to management information and commands from the management node. For example, after the kill query received from the management node, the query task needs to be stopped immediately.

    -

    -
    Fig 1. System query processing architecture diagram (only query related components)

    -

    Query Process Design

    -

    The client, the management node, and the data node cooperate to complete the entire query processing of TDengine. Let's take a concrete SQL query as an example to illustrate the whole query processing flow. The SQL statement is to query on super table FOO_SUPER_TABLE to get the total number of records generated on January 12, 2019, from the table, of which TAG_LOC equals to 'beijing'. The SQL statement is as follows:

    -
    SELECT COUNT(*) 
-FROM FOO_SUPER_TABLE
-WHERE TAG_LOC = 'beijing' AND TS >= '2019-01-12 00:00:00' AND TS < '2019-01-13 00:00:00'
    -

    First, the client invokes the TAOS SQL parser to parse and validate the SQL statement, then generates a syntax tree, and extracts the object of the query - the super table FOO_SUPER_TABLE, and then the parser sends requests with filtering information (TAG_LOC='beijing') to management node to get the corresponding metadata about FOO_SUPER_TABLE.

    -

    Once the management node receives the request for metadata acquisition, first finds the super table FOO_SUPER_TABLE basic information, and then applies the query condition (TAG_LOC='beijing') to filter all the related tables created according to it. And finally, the query executor returns the metadata information that satisfies the query request to the client.

    -

    After the client obtains the metadata information of FOO_SUPER_TABLE, the query executor initiates a query request with timestamp range filtering condition (TS >= '2019- 01-12 00:00:00' AND TS < '2019-01-13 00:00:00') to all nodes that hold the corresponding data according to the information about data distribution in metadata.

    -

    The data node receives the query sent from the client, converts it into an internal structure and puts it into the query task queue to be executed by query executor after optimizing the execution plan. When the query result is obtained, the query result is returned to the client. It should be noted that the data nodes perform the query process independently of each other, and rely solely on their data and content for processing.

    -

    When all data nodes involved in the query return results, the client aggregates the result sets from each data node. In this case, all results are accumulated to generate the final query result. The second stage of aggregation is not always required for all queries. For example, a column selection query does not require a second-stage aggregation at all.

    -

    REST Query Process

    -

    In addition to C/C++, Python, and JDBC interface, TDengine also provides a REST interface based on the HTTP protocol, which is different from using the client application programming interface. When the user uses the REST interface, all the query processing is completed on the server-side, and the user's application is not involved in query processing anymore. After the query processing is completed, the result is returned to the client through the HTTP JSON string.

    -

    -
    Fig. 2 REST query architecture

    -

    When a client uses an HTTP-based REST query interface, the client first establishes a connection with the HTTP connector at the data node and then uses the token to ensure the reliability of the request through the REST signature mechanism. For the data node, after receiving the request, the HTTP connector invokes the embedded client program to initiate a query processing, and then the embedded client parses the SQL statement from the HTTP connector and requests the management node to get metadata as needed. After that, the embedded client sends query requests to the same data node or other nodes in the cluster and aggregates the calculation results on demand. Finally, you also need to convert the result of the query into a JSON format string and return it to the client via an HTTP response. After the HTTP connector receives the request SQL, the subsequent process processing is completely consistent with the query processing using the client application development kit.

    -

    It should be noted that during the entire processing, the client application is no longer involved in, and is only responsible for sending SQL requests through the HTTP protocol and receiving the results in JSON format. Besides, each data node is embedded with an HTTP connector and a client, so any data node in the cluster received requests from a client, the data node can initiate the query and return the result to the client through the HTTP protocol, with transfer the request to other data nodes.

    -

    Technology

    -

    Because TDengine stores data and tags value separately, the tag value is kept in the management node and directly associated with each table instead of records, resulting in a great reduction of the data storage. Therefore, the tag value can be managed by a fully in-memory structure. First, the filtering of the tag data can drastically reduce the data size involved in the second phase of the query. The query processing for the data is performed at the data node. TDengine takes advantage of the immutable characteristics of IoT data by calculating the maximum, minimum, and other statistics of the data in one data block on each saved data block, to effectively improve the performance of query processing. If the query process involves all the data of the entire data block, the pre-computed result is used directly, and the content of the data block is no longer needed. Since the size of disk space required to store the pre-computation result is much smaller than the size of the specific data, the pre-computation result can greatly reduce the disk IO and speed up the query processing.

    -

    TDengine employs column-oriented data storage techniques. When the data block is involved to be loaded from the disk for calculation, only the required column is read according to the query condition, and the read overhead can be minimized. The data of one column is stored in a contiguous memory block and therefore can make full use of the CPU L2 cache to greatly speed up the data scanning. Besides, TDengine utilizes the eagerly responding mechanism and returns a partial result before the complete result is acquired. For example, when the first batch of results is obtained, the data node immediately returns it directly to the client in case of a column select query.

    Back
    \ No newline at end of file diff --git a/documentation/tdenginedocs-en/styles/base.css b/documentation/tdenginedocs-en/styles/base.css deleted file mode 100644 index 564b587eb166c7fdca9f4d95070a4b16d743744a..0000000000000000000000000000000000000000 --- a/documentation/tdenginedocs-en/styles/base.css +++ /dev/null @@ -1,1112 +0,0 @@ -:root { - --b1:rgb(0,118,206);/*#0077bf*//*PANTONE 2174 C*/ - --b1t:rgba(0,118,206,0.15); - --b2:rgb(72,159,223);/*PANTONE 2171 C*//*OLD:#4193c5*/ - --sg-1:#b3b4b9; - --sg0:#585c66; - --sg1:rgb(51,56,68); - --sg2:#2F333E; - --sg3:#21242c; - --black: #212529; - --white: #fefefe; /*rgb(254,254,254)*/ - --white2:rgb(251, 251, 253); /*#fafbfc*/ - --white3:rgb(240,242,244); - --footer1:#fefefe; - --footer2:#333844; - --red:#ea4741; - --green:#72c156; - /*PRODUCT COLORS*/ - --p1:#72c156;/*#30D387;*/ - --p1t:rgba(114,193,86,0.15); - --p2:#43b3ae;/*rgb(70,161,168);/*#46a1a8*//*#D879D0;*/ - --p2t:rgba(70,161,168,0.15); - --p3:#4997d0;/*#30B7E8;*/ - --p3t:rgba(73,151,208,0.15); -} -/*@font-face{font-family:"Open Sans";src:url(fonts/Light/OpenSans-Light.woff2?v=1.101) format("woff2"),url(fonts/Light/OpenSans-Light.woff?v=1.101) format("woff");font-weight:300;font-style:normal}@font-face{font-family:"Open Sans";src:url(fonts/LightItalic/OpenSans-LightItalic.woff2?v=1.101) format("woff2"),url(fonts/LightItalic/OpenSans-LightItalic.woff?v=1.101) format("woff");font-weight:300;font-style:italic}@font-face{font-family:"Open Sans";src:url(fonts/Regular/OpenSans-Regular.woff2?v=1.101) format("woff2"),url(fonts/Regular/OpenSans-Regular.woff?v=1.101) format("woff");font-weight:400;font-style:normal}@font-face{font-family:"Open Sans";src:url(fonts/Italic/OpenSans-Italic.woff2?v=1.101) format("woff2"),url(fonts/Italic/OpenSans-Italic.woff?v=1.101) format("woff");font-weight:400;font-style:italic}@font-face{font-family:"Open Sans";src:url(fonts/SemiBold/OpenSans-SemiBold.woff2?v=1.101) format("woff2"),url(fonts/SemiBold/OpenSans-SemiBold.woff?v=1.101) format("woff");font-weight:600;font-style:normal}@font-face{font-family:"Open Sans";src:url(fonts/SemiBoldItalic/OpenSans-SemiBoldItalic.woff2?v=1.101) format("woff2"),url(fonts/SemiBoldItalic/OpenSans-SemiBoldItalic.woff?v=1.101) format("woff");font-weight:600;font-style:italic}@font-face{font-family:"Open Sans";src:url(fonts/Bold/OpenSans-Bold.woff2?v=1.101) format("woff2"),url(fonts/Bold/OpenSans-Bold.woff?v=1.101) format("woff");font-weight:700;font-style:normal}@font-face{font-family:"Open Sans";src:url(fonts/BoldItalic/OpenSans-BoldItalic.woff2?v=1.101) format("woff2"),url(fonts/BoldItalic/OpenSans-BoldItalic.woff?v=1.101) format("woff");font-weight:700;font-style:italic}@font-face{font-family:"Open Sans";src:url(fonts/ExtraBold/OpenSans-ExtraBold.woff2?v=1.101) format("woff2"),url(fonts/ExtraBold/OpenSans-ExtraBold.woff?v=1.101) format("woff");font-weight:800;font-style:normal}@font-face{font-family:"Open Sans";src:url(fonts/ExtraBoldItalic/OpenSans-ExtraBoldItalic.woff2?v=1.101) format("woff2"),url(fonts/ExtraBoldItalic/OpenSans-ExtraBoldItalic.woff?v=1.101) format("woff");font-weight:800;font-style:italic}*/ -html { - font-size:12pt; /*20px*/ - background-color: var(--white); -} -body, body * { - font-family: "Open Sans", Helvetica,'Hiragino Sans GB', sans-serif,"Apple Color Emoji"; - -webkit-font-smoothing:auto !important; - -moz-osx-font-smoothing:auto !important; - font-smooth: auto !important; - letter-spacing: normal; - line-height: 1.6; -} -body{ - -webkit-box-sizing: border-box; - box-sizing: border-box; - font-weight: 300; - color:var(--sg1); - font-family: "Open Sans", Helvetica, sans-serif !important; - background-color: var(--white); - -} -strong { - font-weight:600; -} -.anchor { - display: block; - position: relative; - z-index: -1; - top: -10px; -} -/* FORMS */ -input { - outline: none; - -webkit-box-shadow: inset 0px 0px 0px 0px transparent; - box-shadow: inset 0px 0px 0px 0px transparent; -} -input[type='text'], input[type='submit'],textarea { - -webkit-appearance: none; -} -input[l]{ - font-size:inherit; - outline: none; - - color:var(--sg1); - padding-left: 0.4em; - width:-webkit-calc(100%); - width:calc(100%); - border:solid 1px; - display: inline-block; - border-left:1px solid; - -webkit-border-radius:4px; - border-radius:4px; - -webkit-transition: border-left 0.2s; - -o-transition: border-left 0.2s; - transition: border-left 0.2s; - vertical-align: top; - font-weight:400; - border-color:inherit; - margin-bottom: 0.5rem; -} -input[l]:focus { - border-left:1rem solid; -} -input[l]:focus { - width:-webkit-calc(auto); - width:calc(auto); -} -input[plain]:valid { - border-color: var(--b1); -} -input[plain]:focus:valid { - border-color: var(--b1); -} -textarea { - -webkit-box-shadow: inset 0px 0px 0px 0px transparent; - box-shadow: inset 0px 0px 0px 0px transparent; -} -textarea[l] { - font-size:inherit; - outline: none; - - color:var(--sg1); - padding-left: 0.4em; - width:-webkit-calc(100%); - width:calc(100%); - border:solid 1px; - display: inline-block; - border-left:1px solid; - -webkit-border-radius:4px; - border-radius:4px; - -webkit-transition: border-left 0.2s; - -o-transition: border-left 0.2s; - transition: border-left 0.2s; - vertical-align: top; - font-weight:400; - border-color:inherit; - margin-bottom: 0.5rem; -} - -/*Other Text*/ -ul { - padding-left:30px; -} -p, li { - font-size:1em; - -} -p { - margin-bottom: 0.5rem; -} -/*Headers*/ -h1 { - font-size: 2.5rem; - line-height: 1.8; -} -h2 { - font-size: 1.7rem; - line-height: 1.8; -} -h3 { - font-size: 1.4rem; - line-height: 1.43; -} -h4 { - font-size: 1.25rem; -} -h5 { - font-size: 1rem; -} -h6 { - font-size: 1rem; - color: #777; -} -h1[b]::before,h2[b]::before, h3[b]::before { - content:""; - height:1em;; - display: block; - width:3px; - margin-left: -0.5em; - margin-top: 0.45em; - position: absolute; - background-color: var(--b1); -} -h1[b],h2[b], h3[b] { - padding-left: 0.5em -} -/* Navigation Bar */ -.logo { - height: 2.5rem; -} -a { - font-size:1em; -} -a:hover { - text-decoration: none; -} -a[l] { - color:var(--b2); - padding-bottom: 2px; - position: relative; - font-style: normal; - cursor: pointer; -} -a[l]:hover,a[l]:focus { - text-decoration: none; -} -a[l]::before { - content: ""; - left: 0; - background-color: var(--b2); - width: 0%; - height: 1px; - top:-webkit-calc(1em + 8px); - top:calc(1em + 8px); - position: absolute; - z-index: 2; - -webkit-transition: background-color 0.2s, height 0.2s, top 0.2s, width 0.2s; - -o-transition: background-color 0.2s, height 0.2s, top 0.2s, width 0.2s; - transition: background-color 0.2s, height 0.2s, top 0.2s, width 0.2s;; -} -a[l]:hover::before, a[l]:focus::before { - content: ""; - left: 0; - background-color: var(--b2); - width: 100%; - height: 1px; - top:-webkit-calc(1em + 8px); - top:calc(1em + 8px); - position: absolute; - z-index: 2; - -webkit-transition: background-color 0.2s, height 0.2s, top 0.2s, width 0.2s; - -o-transition: background-color 0.2s, height 0.2s, top 0.2s, width 0.2s; - transition: background-color 0.2s, height 0.2s, top 0.2s, width 0.2s; - text-decoration: none; -} -.navbar-brand { - margin-left: 10%; - padding-left: 15px; - color:var(--white) !important; -} -.navbar-nav { - top:0px; -} -.navbar { - background-color:var(--sg1); - z-index:10000; - padding-left: 0px; - padding-right: 0px; - padding-top:0.75rem; - padding-bottom: 0.75rem; -} -.navbar-toggler { - margin-right: -webkit-calc(2rem + 15px); - margin-right: calc(2rem + 15px); -} -.nav-link { - color:var(--white) !important; - line-height: 3.65rem; -} -.nav-item { - height:4.65rem; - font-size:1.1rem; - padding-left: 0.15rem; - padding-right: 0.15rem; - -webkit-transition: all 0.2s; - -o-transition: all 0.2s; - transition: all 0.2s; - border-bottom: 0rem solid var(--white); -} -.nav-item:hover { - border-bottom: 0.45rem solid var(--white); -} -.dropdown-menu { - top:4.1rem; - z-index:1000; - border-top:none; - border:none; - min-width: 120px; - margin-left:-1px; - -webkit-border-top-left-radius: 0; - border-top-left-radius: 0; - -webkit-border-top-right-radius: 0; - border-top-right-radius: 0; - -webkit-border-bottom-left-radius:0.25rem; - border-bottom-left-radius:0.25rem; - -webkit-border-bottom-right-radius:0.25rem; - border-bottom-right-radius:0.25rem; -} -.dropdown-menu.show { - -webkit-box-shadow: 0 4px 24px rgba(100, 109, 146, 0.15); - box-shadow: 0 4px 24px rgba(100, 109, 146, 0.15); -} -.dropdown-item { - color:var(--sg1); - background-color: var(--white); - -webkit-transition:all 0.2s; - -o-transition:all 0.2s; - transition:all 0.2s; - cursor:pointer; -} -.dropdown-item:hover, .dropdown-item:active { - background-color:var(--sg1); - color:var(--white) !important; -} -.dropdown-toggle::after { - display:none; -} -.dropdown a::after { - -webkit-transform: rotate(-90deg); - -ms-transform: rotate(-90deg); - transform: rotate(-90deg); - -webkit-transition: -webkit-transform 0.2s; - transition: -webkit-transform 0.2s; - -o-transition: transform 0.2s; - transition: transform 0.2s; - transition: transform 0.2s, -webkit-transform 0.2s; -} -.dropdown.show a::after { - -webkit-transform: rotate(0deg); - -ms-transform: rotate(0deg); - transform: rotate(0deg); -} -.navbar-nav .active { - border-bottom: 0.45rem solid var(--white); -} -.navbar-nav { - position: absolute; - right:-webkit-calc(10% + 15px); - right:calc(10% + 15px); -} -#language-dropdown .dropdown-menu{ - width:50px; -} -/*FOOTER*/ -footer { - background-color: var(--footer2); - padding-top: 1rem; -} -.page-footer { - padding-bottom: 2rem; -} -.footer-content, .footer-legal, .footer-contact { - width:80%; - margin-left: 10%; - padding-top:1rem; - color:var(--footer1); - font-size:0.8em; -} -.footer-content a { - color:var(--footer1); -} -.footer-content a { - color:var(--footer1); -} -.links-list { - text-align: left; - list-style: none; - padding: 0px; -} -.content-wrapper > .links-list { - padding-left:15px; -} -.links-list-title h4 { - font-size:1.2em; - font-weight:400; -} -.legal-links { - position: absolute; - right:-webkit-calc(10% + 15px); - right:calc(10% + 15px); -} -.legal-links a { - color:var(--footer1); -} -.links-list li { - height:2em; -} -.links-list li a::before, .legal-links a::before { - background-color:var(--footer1); -} -.links-list li a:hover::before, .legal-links a:hover::before { - background-color:var(--footer1); -} -.links-list .divider { - border-bottom: 1px solid var(--footer1); - opacity: 0.15; - height:0px; - margin-bottom: 0.3em; -} -.footer-divider { - border-bottom: 1px solid var(--footer1); - width:-webkit-calc(80% - 30px); - width:calc(80% - 30px); - margin-left: -webkit-calc(10% + 15px); - margin-left: calc(10% + 15px); -} -#social-media-links li { - height:2rem; - line-height:2rem; - display: inline-block; - font-size:1em; -} - -#social-media-links li:last-child::after { - content:""; -} -#social-media-links li::after { - content:" | "; -} -#social-media-links svg { - margin-left:2px;margin-right: 0.4rem; - width:20px; -} -#social-media-links svg path { - fill:var(--footer1); -} -#social-media-links li a::before { - left:1.9rem; - background-color:var(--footer1); -} -#social-media-links li a:hover::before, #social-media-links li a:focus::before { - left:1.9rem; - width: -webkit-calc(100% - 1.9rem); - width: calc(100% - 1.9rem); - background-color:var(--footer1); -} -#social-media-links ion-icon { - font-size:20px; - margin-right: 0.5rem; -} -#social-media-links svg { - font-size:20px; - margin-right: 0.5rem; -} -#email-subscribe-form { - width:-webkit-calc(100% - 160px); - width:calc(100% - 160px); -} -#email-subscribe-form input{ - width:-webkit-calc(100% - 4rem); - width:calc(100% - 4rem); - font-size:1.2em; - outline: none; - height:1.8em; - color:var(--sg1); - padding-left: 0.6em; - border:none; - display: inline-block; - border-left:0px solid var(--b1); - -webkit-border-radius:4px; - border-radius:4px; - -webkit-transition: border-left 0.2s; - -o-transition: border-left 0.2s; - transition: border-left 0.2s; - vertical-align: top; - font-weight:400; -} -#email-subscribe-form input:focus { - border-left:1rem solid var(--b1); - padding-top:2px; -} -#email-subscribe-form input:invalid, #email-subscribe-form input:invalid:focus { - border-color:var(--b1); -} -#email-subscribe-form input.invalid-input, #email-subscribe-form input.invalid-input:focus { - border-color:var(--red); -} -#email-subscribe-form input:valid, #email-subscribe-form input:valid:focus { - border-color:var(--green); -} -#email-subscribe-form button { - font-size:1.2em; - height:1.8em; - line-height: 1em; - float:right; - width:3rem; - padding:0; -} -form { - border-color:var(--b1); -} -form input:invalid, form input:invalid:focus { - border-color:inherit; -} -form input.invalid-input, form input.invalid-input:focus, form textarea.invalid-input, form textarea.invalid-input:focus { - border-color:var(--red); -} -form input:valid, form input:valid:focus { - border-color:var(--green); -} - -.sub-arrow { - width:1.2em; - fill:var(--b1); -} - - -@media only screen and (max-width:991px){ - .page-footer { - padding-left:20px; - padding-right:20px; - } - .footer-legal { - width:100%; - } - #legal-1 { - padding-left: 20px; - } - .legal-links { - right:20px; - } - .footer-content .col-xl-8, .footer-content .col-xl-4{ - padding-left:20px; - padding-right:20px; - } - .footer-content { - width:-webkit-calc(100% + 40px); - width:calc(100% + 40px); - } - .footer-divider { - width:100%; - margin-left: 0; - } -} - -/*SECTIONS AND CONTENT*/ -.content-wrapper { - width: 80%; - margin-left: 10%; - margin-top: 6rem; - margin-bottom: 3rem; - min-height: -webkit-calc(100vh - 187.7px - 74.45px); - min-height: calc(100vh - 187.7px - 74.45px); -} -.section { - /* border-bottom:2px solid rgba(0,0,0,0.2);*/ -} -.section-item { - -} -.section-title, -.section-item-title { - color:var(--b1); - -} -.container-fluid { - background-color: var(--white); -} -.center { - left:50%; - position: relative; -} -/*BUTTONS*/ -.btn-primary { - color:var(--b1); - background-color: var(--white); - border-color:var(--b1); - -webkit-box-shadow:0px 0px 0px 0px rgba(255,255,255,0.55); - box-shadow:0px 0px 0px 0px rgba(255,255,255,0.55); - -webkit-transition: all 0.2s; - -o-transition: all 0.2s; - transition: all 0.2s; -} -.btn-primary:hover,.btn-primary:focus { - color:var(--b1); - background-color: var(--white); - border-color:var(--b1); - -webkit-box-shadow:4px 4px 0px 0px var(--b1t); - box-shadow:4px 4px 0px 0px var(--b1t); - -webkit-transform: translate(-2px,-2px); - -ms-transform: translate(-2px,-2px); - transform: translate(-2px,-2px); -} -.btn-primary:active { - color:var(--b1) !important; - background-color: var(--white) !important; - border-color:var(--b1) !important; - -webkit-box-shadow:2px 2px 0px 0px var(--b1t); - box-shadow:2px 2px 0px 0px var(--b1t); - -webkit-transform: translate(-1px,-1px); - -ms-transform: translate(-1px,-1px); - transform: translate(-1px,-1px); -} -.btn-white { - color:var(--b1); - background-color: var(--white); - -webkit-transition: all 0.2s; - -o-transition: all 0.2s; - transition: all 0.2s; - -webkit-box-shadow:0px 0px 0px 0px rgba(255,255,255,0.55); - box-shadow:0px 0px 0px 0px rgba(255,255,255,0.55); -} -.btn-white:hover,.btn-white:focus { - color:var(--b1); - background-color: var(--white); - -webkit-box-shadow:4px 4px 0px 0px rgba(255,255,255,0.55); - box-shadow:4px 4px 0px 0px rgba(255,255,255,0.55); - -webkit-transform: translate(-2px,-2px); - -ms-transform: translate(-2px,-2px); - transform: translate(-2px,-2px); -} -.btn-white:active { - color:var(--b1) !important; - background-color: var(--white) !important; - -webkit-box-shadow:2px 2px 0px 0px rgba(255,255,255,0.55); - box-shadow:2px 2px 0px 0px rgba(255,255,255,0.55); - -webkit-transform: translate(-1px,-1px); - -ms-transform: translate(-1px,-1px); - transform: translate(-1px,-1px); -} -.btn-filled { - color:var(--white) !important; - background-color: var(--b1); - border-color:var(--b1); - -webkit-box-shadow:0px 0px 0px 0px rgba(255,255,255,0.55); - box-shadow:0px 0px 0px 0px rgba(255,255,255,0.55); - -webkit-transition: all 0.2s; - -o-transition: all 0.2s; - transition: all 0.2s; -} -.btn-filled:hover { - color:var(--white) !important;; - background-color: var(--b1); - border-color:var(--b1); - -webkit-box-shadow:4px 4px 0px 0px var(--b1t); - box-shadow:4px 4px 0px 0px var(--b1t); - -webkit-transform: translate(-2px,-2px); - -ms-transform: translate(-2px,-2px); - transform: translate(-2px,-2px); -} -.btn-filled:active { - color:var(--white) !important; - background-color: var(--b1) !important; - border-color:var(--b1) !important; - -webkit-box-shadow:2px 2px 0px 0px var(--b1t); - box-shadow:2px 2px 0px 0px var(--b1t); - -webkit-transform: translate(-1px,-1px); - -ms-transform: translate(-1px,-1px); - transform: translate(-1px,-1px); -} -/*Popup*/ -#popup-wrapper { - display: block; - position: absolute; - z-index:1000; - -webkit-transition:opacity 0.5s; - -o-transition:opacity 0.5s; - transition:opacity 0.5s; - opacity: 1; -} -#popup-page-cover { - display:none; - position: fixed; - height: 100vh; - width:100vw; - top:0;left:0; - background-color: rgba(131, 145, 174, 0.32); - z-index:1000; - -webkit-transition:opacity 0.5s; - -o-transition:opacity 0.5s; - transition:opacity 0.5s; - opacity:0; -} -#popup { - position: fixed; - display: none; - height:auto; - width:100px; - z-index: 1001; - max-width: -webkit-calc(100% - 30px); - max-width: calc(100% - 30px); - background-color: var(--white); - left:50%; - -webkit-transform:translate(-50%,-50%); - -ms-transform:translate(-50%,-50%); - transform:translate(-50%,-50%); - top:50%; - -webkit-transition:opacity 0.5s; - -o-transition:opacity 0.5s; - transition:opacity 0.5s; - opacity:0; - -webkit-border-radius:0.25rem; - border-radius:0.25rem; - -webkit-box-shadow: 0 12px 48px 0 rgba(0, 0, 0, 0.24); - box-shadow: 0 12px 48px 0 rgba(0, 0, 0, 0.24) -} -#close-popup { - position: absolute;right:1rem; - z-index: 1; - cursor: pointer; - top:0; -} -#close-popup svg { - margin-top:4px; -} -#close-popup::before { - content:""; - width:0px; - display: block; - position: absolute; - top:50%; - left:50%; - height:0px; - background-color:rgba(0,0,0,0.15); - -webkit-border-radius:50%; - border-radius:50%; - z-index:-1; - cursor: pointer; - -webkit-transition:all 0.2s; - -o-transition:all 0.2s; - transition:all 0.2s; -} -#close-popup:hover::before { - content:""; - width:32px;; - display: block; - position: absolute; - top:10px; - left:0px; - height:32px; - background-color:rgba(0,0,0,0.15); - -webkit-border-radius:50%; - border-radius:50%; -z-index:-1; -} -#popup-title { - padding-left: 1rem; - background-color:var(--b1); - color:var(--white); - font-weight:400; - font-size:1.6em; - width:100%; - display:block; - -webkit-border-radius:0.25rem 0.25rem 0 0; - border-radius:0.25rem 0.25rem 0 0; - padding-right:60px; - position: relative; -} -#popup-title-text { - line-height: 1.2; - display: inline-block; - padding-top: 9px; -} -#popup-content { - padding:1rem; - display: block; -} -#popup-title path { - fill:var(--white); -} -/*Banners*/ -.banner-content { - padding-right:32px; -} -.banner-wrapper { - width:100vw; - position: fixed; - top:4.3rem; - left:0; - z-index: 1000; -} -.banner { - background-color: var(--b1); - width:-webkit-calc(100% - 20px); - width:calc(100% - 20px); - margin: auto; - -webkit-border-radius:0.25rem; - border-radius:0.25rem; - padding:0.5rem; - color:var(--white); - font-size:1.6em; - margin-top: 1rem; - -webkit-box-shadow:0 4px 12px 0 rgba(0, 0, 0, 0.24); - box-shadow:0 4px 12px 0 rgba(0, 0, 0, 0.24); - opacity: 1; - -webkit-animation: bannerOpaque 0.2s; - animation: bannerOpaque 0.2s; -} -@-webkit-keyframes bannerOpaque { - from { - opacity:0 - } - to { - opacity:1; - } -} -@keyframes bannerOpaque { - from { - opacity:0 - } - to { - opacity:1; - } -} -.close-banner { - position: absolute;right:1rem; - z-index: 1; - cursor: pointer; - -webkit-transform: translate(0,-3px); - -ms-transform: translate(0,-3px); - transform: translate(0,-3px); -} -.close-banner::before { - content:""; - width:0px; - display: block; - position: absolute; - margin-top:26px; - left:50%; - height:0px; - background-color:rgba(0,0,0,0.15); - -webkit-border-radius:50%; - border-radius:50%; - z-index:-1; - cursor: pointer; - -webkit-transition:all 0.2s; - -o-transition:all 0.2s; - transition:all 0.2s; -} -.close-banner:hover::before { - content:""; - width:32px; - margin-top: 7px; - display: block; - position: absolute; - left:0px; - height:32px; - background-color:rgba(0,0,0,0.15); - -webkit-border-radius:50%; - border-radius:50%; -z-index:-1; -} -@media only screen and (max-width:991px) { - .banner { - font-size:1.2rem; - } -} -/*OTHER*/ -#globe-svg { - height:60px; - fill:#fefefe -} -#page-cover { - width:100vw; - top:-100vh; - left:0px; - -webkit-transition-delay: 0.3s; - -o-transition-delay: 0.3s; - transition-delay: 0.3s; - -webkit-transition:all 0.7s; - -o-transition:all 0.7s; - transition:all 0.7s; - height:100vh; - position: fixed; - z-index:1000; - background-color: rgba(54, 61, 75, 0.25); -} -#menu-button { - border:none; - outline:none; -} -#menu-bar { - -webkit-transition: all 0.15s; - -o-transition: all 0.15s; - transition: all 0.15s; -} -#close-bar { - -webkit-transition: all 0.15s; - -o-transition: all 0.15s; - transition: all 0.15s; - display: none; -} -#rect1 { - -webkit-transition: all 0.2s; - -o-transition: all 0.2s; - transition: all 0.2s; -} -#rect2 { --webkit-transition: all 0.2s; --o-transition: all 0.2s; -transition: all 0.2s; -} -#rect3 { --webkit-transition: all 0.2s; --o-transition: all 0.2s; -transition: all 0.2s; -} -@media only screen and (max-width: 991px) { - - .content-wrapper { - width:-webkit-calc(100%); - width:calc(100%); - left:0; - padding-left: 0; - margin-left:0; - margin-top:4.7rem; - } - .container-fluid { - padding-left:20px; - padding-right:20px; - } - .row { - margin-left:-20px; - margin-right:-20px; - } - #menu-button { - margin-right:20px; - padding:0px; - } - .navbar-brand { - margin-left: 20px; - padding-left: 0px; - } -} -.bot-logo { - margin-bottom:0.5rem; -} -@media only screen and (min-width:1200px){ - #page-cover { - display: none - } - .bot-logo { - margin-left:15px; - } -} -@media only screen and (max-width: 1199px) { - #globe-svg { - height:60px; - fill:var(--sg1); - } - .navbar-collapse.show { - -webkit-box-shadow:0px 10px 24px rgba(0,0,0,0.15) ; - box-shadow:0px 10px 24px rgba(0,0,0,0.15) ; - } - .nav-item:first-child { - border-top: 1px solid rgba(255,255,255,0.35); - } - #menu-button { - margin-right: -webkit-calc(10% + 15px); - margin-right: calc(10% + 15px); - padding:0; - } - #menu-button:hover { - background-color: transparent; - } - .nav-item { - height:auto; - border-bottom: 1px solid rgba(0,0,0,0.35); - padding-left: -webkit-calc(10% + 15px); - padding-left: calc(10% + 15px); - } - .nav-link{ - line-height: 3rem; - padding: 0px; - - } - .nav-link{ - color:var(--sg1) !important; - } - .nav-item:hover { - border-bottom: 1px solid rgba(0,0,0,0.35); - - } - .navbar-nav { - background-color: var(--white2); - margin-top: 15px; - } - .navbar-nav .active { - border-bottom: 1px solid rgba(0,0,0,0.35); - } - .nav-item:nth-child(even) { - /* - background-color:rgba(0,0,0,0.05); - padding-left: 1rem; - margin-left: -1rem; - */ - } - #navbarSupportedContent { - - } - #language-dropdown .dropdown-menu{ - width: -webkit-calc(80% + 4rem); - width: calc(80% + 4rem); - background-color: var(--white); - - } - .dropdown-menu { - border:none; - margin-top: -20px; - } - .nav-item:last-child { - border-bottom:none; - } - .dropdown-menu.show { - -webkit-box-shadow: 0 4px 24px rgba(100, 109, 146, 0.15); - box-shadow: 0 4px 24px rgba(100, 109, 146, 0.15); - margin-bottom:1rem; - margin-top:-0.5rem; - } - .dropdown-item { - padding-left: 15px; - font-weight:300; - } - .navbar-nav { - position: relative; - right:0rem; - } - .long-form input { - width:100%; - } -} -@media only screen and (max-width: 991px) { - .nav-item { - padding-left: 20px; - padding-right: 20px; - } - #language-dropdown{ - padding-left:20px; - } - #language-dropdown .dropdown-menu { - width:100%; - } - #menu-button { - margin-right: 20px; - padding:0; - } - .navbar { - padding-top: 0.25rem; - padding-bottom:0.25rem; - } - .logo { - height:1.8rem; - } - .anchor { - top: -55px; - } -} -@media only screen and (max-width:556px) { - #legal-1 { - width:100%; - } - .legal-links { - position: inherit; - margin-left: 20px; - margin-bottom: 1em; - } -} -@media only screen and (max-width:375px) { - #legal-1 p { - display: block; - } -} - -/*Footer media queries*/ -@media only screen and (max-width:830px) { -} -@media only screen and (max-width:650px) { -} -@media only screen and (max-width:352px) { -} - -.lds-ring { - display: inline-block; - position: relative; - width: 18px; - height: 18px; - padding-top:2px; -} -#email-subscribe-form .lds-ring { - padding-top:1px; -} -.lds-ring div { - -webkit-box-sizing: border-box; - box-sizing: border-box; - display: block; - position: absolute; - width: 18px; - height: 18px; - border: 2px solid var(--b2); - -webkit-border-radius: 50%; - border-radius: 50%; - -webkit-animation: lds-ring 1.2s cubic-bezier(0.5, 0, 0.5, 1) infinite; - animation: lds-ring 1.2s cubic-bezier(0.5, 0, 0.5, 1) infinite; - border-color: var(--b2) transparent transparent transparent; -} -.lds-ring div:nth-child(1) { - -webkit-animation-delay: -0.45s; - animation-delay: -0.45s; -} -.lds-ring div:nth-child(2) { - -webkit-animation-delay: -0.3s; - animation-delay: -0.3s; -} -.lds-ring div:nth-child(3) { - -webkit-animation-delay: -0.15s; - animation-delay: -0.15s; -} -@-webkit-keyframes lds-ring { - 0% { - -webkit-transform: rotate(0deg); - transform: rotate(0deg); - } - 100% { - -webkit-transform: rotate(360deg); - transform: rotate(360deg); - } -} -@keyframes lds-ring { - 0% { - -webkit-transform: rotate(0deg); - transform: rotate(0deg); - } - 100% { - -webkit-transform: rotate(360deg); - transform: rotate(360deg); - } -} -#email-subscribe-form .sub-arrow { - padding-top:2px; -} -.sub-arrow { - display: inline-block; -} -.sub-load { - display:none; -} diff --git a/documentation/tdenginedocs-en/styles/base.min.css b/documentation/tdenginedocs-en/styles/base.min.css deleted file mode 100644 index 7aa94277026265a64decb3717fdc680b8a338d59..0000000000000000000000000000000000000000 --- a/documentation/tdenginedocs-en/styles/base.min.css +++ /dev/null @@ -1 +0,0 @@ -:root{--b1:rgb(0,118,206);--b1t:rgba(0,118,206,0.15);--b2:rgb(72,159,223);--sg-1:#b3b4b9;--sg0:#585c66;--sg1:rgb(51,56,68);--sg2:#2F333E;--sg3:#21242c;--black:#212529;--white:#fefefe;--white2:rgb(251, 251, 253);--white3:rgb(240,242,244);--footer1:#fefefe;--footer2:#333844;--red:#ea4741;--green:#72c156;--p1:#72c156;--p1t:rgba(114,193,86,0.15);--p2:#43b3ae;--p2t:rgba(70,161,168,0.15);--p3:#4997d0;--p3t:rgba(73,151,208,0.15)}html{font-size:12pt;background-color:var(--white)}body,body *{font-family:"Open Sans",Helvetica,'Hiragino Sans GB',sans-serif,"Apple Color Emoji";-webkit-font-smoothing:auto!important;-moz-osx-font-smoothing:auto!important;font-smooth:auto!important;letter-spacing:normal;line-height:1.6}body{-webkit-box-sizing:border-box;box-sizing:border-box;font-weight:300;color:var(--sg1);font-family:"Open Sans",Helvetica,sans-serif!important;background-color:var(--white)}strong{font-weight:600}.anchor{display:block;position:relative;z-index:-1;top:-10px}input{outline:0;-webkit-box-shadow:inset 0 0 0 0 transparent;box-shadow:inset 0 0 0 0 transparent}input[type=submit],input[type=text],textarea{-webkit-appearance:none}input[l]{font-size:inherit;outline:0;color:var(--sg1);padding-left:.4em;width:-webkit-calc(100%);width:calc(100%);border:solid 1px;display:inline-block;border-left:1px solid;-webkit-border-radius:4px;border-radius:4px;-webkit-transition:border-left .2s;-o-transition:border-left .2s;transition:border-left .2s;vertical-align:top;font-weight:400;border-color:inherit;margin-bottom:.5rem}input[l]:focus{border-left:1rem solid}input[l]:focus{width:-webkit-calc(auto);width:calc(auto)}input[plain]:valid{border-color:var(--b1)}input[plain]:focus:valid{border-color:var(--b1)}textarea{-webkit-box-shadow:inset 0 0 0 0 transparent;box-shadow:inset 0 0 0 0 transparent}textarea[l]{font-size:inherit;outline:0;color:var(--sg1);padding-left:.4em;width:-webkit-calc(100%);width:calc(100%);border:solid 1px;display:inline-block;border-left:1px solid;-webkit-border-radius:4px;border-radius:4px;-webkit-transition:border-left .2s;-o-transition:border-left .2s;transition:border-left .2s;vertical-align:top;font-weight:400;border-color:inherit;margin-bottom:.5rem}ul{padding-left:30px}li,p{font-size:1em}p{margin-bottom:.5rem}h1{font-size:2.5rem;line-height:1.8}h2{font-size:1.7rem;line-height:1.8}h3{font-size:1.4rem;line-height:1.43}h4{font-size:1.25rem}h5{font-size:1rem}h6{font-size:1rem;color:#777}h1[b]::before,h2[b]::before,h3[b]::before{content:"";height:1em;display:block;width:3px;margin-left:-.5em;margin-top:.45em;position:absolute;background-color:var(--b1)}h1[b],h2[b],h3[b]{padding-left:.5em}.logo{height:2.5rem}a{font-size:1em}a:hover{text-decoration:none}a[l]{color:var(--b2);padding-bottom:2px;position:relative;font-style:normal;cursor:pointer}a[l]:focus,a[l]:hover{text-decoration:none}a[l]::before{content:"";left:0;background-color:var(--b2);width:0%;height:1px;top:-webkit-calc(1em + 8px);top:calc(1em + 8px);position:absolute;z-index:2;-webkit-transition:background-color .2s,height .2s,top .2s,width .2s;-o-transition:background-color .2s,height .2s,top .2s,width .2s;transition:background-color .2s,height .2s,top .2s,width .2s}a[l]:focus::before,a[l]:hover::before{content:"";left:0;background-color:var(--b2);width:100%;height:1px;top:-webkit-calc(1em + 8px);top:calc(1em + 8px);position:absolute;z-index:2;-webkit-transition:background-color .2s,height .2s,top .2s,width .2s;-o-transition:background-color .2s,height .2s,top .2s,width .2s;transition:background-color .2s,height .2s,top .2s,width .2s;text-decoration:none}.navbar-brand{margin-left:10%;padding-left:15px;color:var(--white)!important}.navbar-nav{top:0}.navbar{background-color:var(--sg1);z-index:10000;padding-left:0;padding-right:0;padding-top:.75rem;padding-bottom:.75rem}.navbar-toggler{margin-right:-webkit-calc(2rem + 15px);margin-right:calc(2rem + 15px)}.nav-link{color:var(--white)!important;line-height:3.65rem}.nav-item{height:4.65rem;font-size:1.1rem;padding-left:.15rem;padding-right:.15rem;-webkit-transition:all .2s;-o-transition:all .2s;transition:all .2s;border-bottom:0 solid var(--white)}.nav-item:hover{border-bottom:.45rem solid var(--white)}.dropdown-menu{top:4.1rem;z-index:1000;border-top:none;border:none;min-width:120px;margin-left:-1px;-webkit-border-top-left-radius:0;border-top-left-radius:0;-webkit-border-top-right-radius:0;border-top-right-radius:0;-webkit-border-bottom-left-radius:.25rem;border-bottom-left-radius:.25rem;-webkit-border-bottom-right-radius:.25rem;border-bottom-right-radius:.25rem}.dropdown-menu.show{-webkit-box-shadow:0 4px 24px rgba(100,109,146,.15);box-shadow:0 4px 24px rgba(100,109,146,.15)}.dropdown-item{color:var(--sg1);background-color:var(--white);-webkit-transition:all .2s;-o-transition:all .2s;transition:all .2s;cursor:pointer}.dropdown-item:active,.dropdown-item:hover{background-color:var(--sg1);color:var(--white)!important}.dropdown-toggle::after{display:none}.dropdown a::after{-webkit-transform:rotate(-90deg);-ms-transform:rotate(-90deg);transform:rotate(-90deg);-webkit-transition:-webkit-transform .2s;transition:-webkit-transform .2s;-o-transition:transform .2s;transition:transform .2s;transition:transform .2s,-webkit-transform .2s}.dropdown.show a::after{-webkit-transform:rotate(0);-ms-transform:rotate(0);transform:rotate(0)}.navbar-nav .active{border-bottom:.45rem solid var(--white)}.navbar-nav{position:absolute;right:-webkit-calc(10% + 15px);right:calc(10% + 15px)}#language-dropdown .dropdown-menu{width:50px}footer{background-color:var(--footer2);padding-top:1rem}.page-footer{padding-bottom:2rem}.footer-contact,.footer-content,.footer-legal{width:80%;margin-left:10%;padding-top:1rem;color:var(--footer1);font-size:.8em}.footer-content a{color:var(--footer1)}.footer-content a{color:var(--footer1)}.links-list{text-align:left;list-style:none;padding:0}.content-wrapper>.links-list{padding-left:15px}.links-list-title h4{font-size:1.2em;font-weight:400}.legal-links{position:absolute;right:-webkit-calc(10% + 15px);right:calc(10% + 15px)}.legal-links a{color:var(--footer1)}.links-list li{height:2em}.legal-links a::before,.links-list li a::before{background-color:var(--footer1)}.legal-links a:hover::before,.links-list li a:hover::before{background-color:var(--footer1)}.links-list .divider{border-bottom:1px solid var(--footer1);opacity:.15;height:0;margin-bottom:.3em}.footer-divider{border-bottom:1px solid var(--footer1);width:-webkit-calc(80% - 30px);width:calc(80% - 30px);margin-left:-webkit-calc(10% + 15px);margin-left:calc(10% + 15px)}#social-media-links li{height:2rem;line-height:2rem;display:inline-block;font-size:1em}#social-media-links li:last-child::after{content:""}#social-media-links li::after{content:" | "}#social-media-links svg{margin-left:2px;margin-right:.4rem;width:20px}#social-media-links svg path{fill:var(--footer1)}#social-media-links li a::before{left:1.9rem;background-color:var(--footer1)}#social-media-links li a:focus::before,#social-media-links li a:hover::before{left:1.9rem;width:-webkit-calc(100% - 1.9rem);width:calc(100% - 1.9rem);background-color:var(--footer1)}#social-media-links ion-icon{font-size:20px;margin-right:.5rem}#social-media-links svg{font-size:20px;margin-right:.5rem}#email-subscribe-form{width:-webkit-calc(100% - 160px);width:calc(100% - 160px)}#email-subscribe-form input{width:-webkit-calc(100% - 4rem);width:calc(100% - 4rem);font-size:1.2em;outline:0;height:1.8em;color:var(--sg1);padding-left:.6em;border:none;display:inline-block;border-left:0 solid var(--b1);-webkit-border-radius:4px;border-radius:4px;-webkit-transition:border-left .2s;-o-transition:border-left .2s;transition:border-left .2s;vertical-align:top;font-weight:400}#email-subscribe-form input:focus{border-left:1rem solid var(--b1);padding-top:2px}#email-subscribe-form input:invalid,#email-subscribe-form input:invalid:focus{border-color:var(--b1)}#email-subscribe-form input.invalid-input,#email-subscribe-form input.invalid-input:focus{border-color:var(--red)}#email-subscribe-form input:valid,#email-subscribe-form input:valid:focus{border-color:var(--green)}#email-subscribe-form button{font-size:1.2em;height:1.8em;line-height:1em;float:right;width:3rem;padding:0}form{border-color:var(--b1)}form input:invalid,form input:invalid:focus{border-color:inherit}form input.invalid-input,form input.invalid-input:focus,form textarea.invalid-input,form textarea.invalid-input:focus{border-color:var(--red)}form input:valid,form input:valid:focus{border-color:var(--green)}.sub-arrow{width:1.2em;fill:var(--b1)}@media only screen and (max-width:991px){.page-footer{padding-left:20px;padding-right:20px}.footer-legal{width:100%}#legal-1{padding-left:20px}.legal-links{right:20px}.footer-content .col-xl-4,.footer-content .col-xl-8{padding-left:20px;padding-right:20px}.footer-content{width:-webkit-calc(100% + 40px);width:calc(100% + 40px)}.footer-divider{width:100%;margin-left:0}}.content-wrapper{width:80%;margin-left:10%;margin-top:6rem;margin-bottom:3rem;min-height:-webkit-calc(100vh - 187.7px - 74.45px);min-height:calc(100vh - 187.7px - 74.45px)}.section-item-title,.section-title{color:var(--b1)}.container-fluid{background-color:var(--white)}.center{left:50%;position:relative}.btn-primary{color:var(--b1);background-color:var(--white);border-color:var(--b1);-webkit-box-shadow:0 0 0 0 rgba(255,255,255,.55);box-shadow:0 0 0 0 rgba(255,255,255,.55);-webkit-transition:all .2s;-o-transition:all .2s;transition:all .2s}.btn-primary:focus,.btn-primary:hover{color:var(--b1);background-color:var(--white);border-color:var(--b1);-webkit-box-shadow:4px 4px 0 0 var(--b1t);box-shadow:4px 4px 0 0 var(--b1t);-webkit-transform:translate(-2px,-2px);-ms-transform:translate(-2px,-2px);transform:translate(-2px,-2px)}.btn-primary:active{color:var(--b1)!important;background-color:var(--white)!important;border-color:var(--b1)!important;-webkit-box-shadow:2px 2px 0 0 var(--b1t);box-shadow:2px 2px 0 0 var(--b1t);-webkit-transform:translate(-1px,-1px);-ms-transform:translate(-1px,-1px);transform:translate(-1px,-1px)}.btn-white{color:var(--b1);background-color:var(--white);-webkit-transition:all .2s;-o-transition:all .2s;transition:all .2s;-webkit-box-shadow:0 0 0 0 rgba(255,255,255,.55);box-shadow:0 0 0 0 rgba(255,255,255,.55)}.btn-white:focus,.btn-white:hover{color:var(--b1);background-color:var(--white);-webkit-box-shadow:4px 4px 0 0 rgba(255,255,255,.55);box-shadow:4px 4px 0 0 rgba(255,255,255,.55);-webkit-transform:translate(-2px,-2px);-ms-transform:translate(-2px,-2px);transform:translate(-2px,-2px)}.btn-white:active{color:var(--b1)!important;background-color:var(--white)!important;-webkit-box-shadow:2px 2px 0 0 rgba(255,255,255,.55);box-shadow:2px 2px 0 0 rgba(255,255,255,.55);-webkit-transform:translate(-1px,-1px);-ms-transform:translate(-1px,-1px);transform:translate(-1px,-1px)}.btn-filled{color:var(--white)!important;background-color:var(--b1);border-color:var(--b1);-webkit-box-shadow:0 0 0 0 rgba(255,255,255,.55);box-shadow:0 0 0 0 rgba(255,255,255,.55);-webkit-transition:all .2s;-o-transition:all .2s;transition:all .2s}.btn-filled:hover{color:var(--white)!important;background-color:var(--b1);border-color:var(--b1);-webkit-box-shadow:4px 4px 0 0 var(--b1t);box-shadow:4px 4px 0 0 var(--b1t);-webkit-transform:translate(-2px,-2px);-ms-transform:translate(-2px,-2px);transform:translate(-2px,-2px)}.btn-filled:active{color:var(--white)!important;background-color:var(--b1)!important;border-color:var(--b1)!important;-webkit-box-shadow:2px 2px 0 0 var(--b1t);box-shadow:2px 2px 0 0 var(--b1t);-webkit-transform:translate(-1px,-1px);-ms-transform:translate(-1px,-1px);transform:translate(-1px,-1px)}#popup-wrapper{display:block;position:absolute;z-index:1000;-webkit-transition:opacity .5s;-o-transition:opacity .5s;transition:opacity .5s;opacity:1}#popup-page-cover{display:none;position:fixed;height:100vh;width:100vw;top:0;left:0;background-color:rgba(131,145,174,.32);z-index:1000;-webkit-transition:opacity .5s;-o-transition:opacity .5s;transition:opacity .5s;opacity:0}#popup{position:fixed;display:none;height:auto;width:100px;z-index:1001;max-width:-webkit-calc(100% - 30px);max-width:calc(100% - 30px);background-color:var(--white);left:50%;-webkit-transform:translate(-50%,-50%);-ms-transform:translate(-50%,-50%);transform:translate(-50%,-50%);top:50%;-webkit-transition:opacity .5s;-o-transition:opacity .5s;transition:opacity .5s;opacity:0;-webkit-border-radius:.25rem;border-radius:.25rem;-webkit-box-shadow:0 12px 48px 0 rgba(0,0,0,.24);box-shadow:0 12px 48px 0 rgba(0,0,0,.24)}#close-popup{position:absolute;right:1rem;z-index:1;cursor:pointer;top:0}#close-popup svg{margin-top:4px}#close-popup::before{content:"";width:0;display:block;position:absolute;top:50%;left:50%;height:0;background-color:rgba(0,0,0,.15);-webkit-border-radius:50%;border-radius:50%;z-index:-1;cursor:pointer;-webkit-transition:all .2s;-o-transition:all .2s;transition:all .2s}#close-popup:hover::before{content:"";width:32px;display:block;position:absolute;top:10px;left:0;height:32px;background-color:rgba(0,0,0,.15);-webkit-border-radius:50%;border-radius:50%;z-index:-1}#popup-title{padding-left:1rem;background-color:var(--b1);color:var(--white);font-weight:400;font-size:1.6em;width:100%;display:block;-webkit-border-radius:.25rem .25rem 0 0;border-radius:.25rem .25rem 0 0;padding-right:60px;position:relative}#popup-title-text{line-height:1.2;display:inline-block;padding-top:9px}#popup-content{padding:1rem;display:block}#popup-title path{fill:var(--white)}.banner-content{padding-right:32px}.banner-wrapper{width:100vw;position:fixed;top:4.3rem;left:0;z-index:1000}.banner{background-color:var(--b1);width:-webkit-calc(100% - 20px);width:calc(100% - 20px);margin:auto;-webkit-border-radius:.25rem;border-radius:.25rem;padding:.5rem;color:var(--white);font-size:1.6em;margin-top:1rem;-webkit-box-shadow:0 4px 12px 0 rgba(0,0,0,.24);box-shadow:0 4px 12px 0 rgba(0,0,0,.24);opacity:1;-webkit-animation:bannerOpaque .2s;animation:bannerOpaque .2s}@-webkit-keyframes bannerOpaque{from{opacity:0}to{opacity:1}}@keyframes bannerOpaque{from{opacity:0}to{opacity:1}}.close-banner{position:absolute;right:1rem;z-index:1;cursor:pointer;-webkit-transform:translate(0,-3px);-ms-transform:translate(0,-3px);transform:translate(0,-3px)}.close-banner::before{content:"";width:0;display:block;position:absolute;margin-top:26px;left:50%;height:0;background-color:rgba(0,0,0,.15);-webkit-border-radius:50%;border-radius:50%;z-index:-1;cursor:pointer;-webkit-transition:all .2s;-o-transition:all .2s;transition:all .2s}.close-banner:hover::before{content:"";width:32px;margin-top:7px;display:block;position:absolute;left:0;height:32px;background-color:rgba(0,0,0,.15);-webkit-border-radius:50%;border-radius:50%;z-index:-1}@media only screen and (max-width:991px){.banner{font-size:1.2rem}}#globe-svg{height:60px;fill:#fefefe}#page-cover{width:100vw;top:-100vh;left:0;-webkit-transition-delay:.3s;-o-transition-delay:.3s;transition-delay:.3s;-webkit-transition:all .7s;-o-transition:all .7s;transition:all .7s;height:100vh;position:fixed;z-index:1000;background-color:rgba(54,61,75,.25)}#menu-button{border:none;outline:0}#menu-bar{-webkit-transition:all .15s;-o-transition:all .15s;transition:all .15s}#close-bar{-webkit-transition:all .15s;-o-transition:all .15s;transition:all .15s;display:none}#rect1{-webkit-transition:all .2s;-o-transition:all .2s;transition:all .2s}#rect2{-webkit-transition:all .2s;-o-transition:all .2s;transition:all .2s}#rect3{-webkit-transition:all .2s;-o-transition:all .2s;transition:all .2s}@media only screen and (max-width:991px){.content-wrapper{width:-webkit-calc(100%);width:calc(100%);left:0;padding-left:0;margin-left:0;margin-top:4.7rem}.container-fluid{padding-left:20px;padding-right:20px}.row{margin-left:-20px;margin-right:-20px}#menu-button{margin-right:20px;padding:0}.navbar-brand{margin-left:20px;padding-left:0}}.bot-logo{margin-bottom:.5rem}@media only screen and (min-width:1200px){#page-cover{display:none}.bot-logo{margin-left:15px}}@media only screen and (max-width:1199px){#globe-svg{height:60px;fill:var(--sg1)}.navbar-collapse.show{-webkit-box-shadow:0 10px 24px rgba(0,0,0,.15);box-shadow:0 10px 24px rgba(0,0,0,.15)}.nav-item:first-child{border-top:1px solid rgba(255,255,255,.35)}#menu-button{margin-right:-webkit-calc(10% + 15px);margin-right:calc(10% + 15px);padding:0}#menu-button:hover{background-color:transparent}.nav-item{height:auto;border-bottom:1px solid rgba(0,0,0,.35);padding-left:-webkit-calc(10% + 15px);padding-left:calc(10% + 15px)}.nav-link{line-height:3rem;padding:0}.nav-link{color:var(--sg1)!important}.nav-item:hover{border-bottom:1px solid rgba(0,0,0,.35)}.navbar-nav{background-color:var(--white2);margin-top:15px}.navbar-nav .active{border-bottom:1px solid rgba(0,0,0,.35)}#language-dropdown .dropdown-menu{width:-webkit-calc(80% + 4rem);width:calc(80% + 4rem);background-color:var(--white)}.dropdown-menu{border:none;margin-top:-20px}.nav-item:last-child{border-bottom:none}.dropdown-menu.show{-webkit-box-shadow:0 4px 24px rgba(100,109,146,.15);box-shadow:0 4px 24px rgba(100,109,146,.15);margin-bottom:1rem;margin-top:-.5rem}.dropdown-item{padding-left:15px;font-weight:300}.navbar-nav{position:relative;right:0}.long-form input{width:100%}}@media only screen and (max-width:991px){.nav-item{padding-left:20px;padding-right:20px}#language-dropdown{padding-left:20px}#language-dropdown .dropdown-menu{width:100%}#menu-button{margin-right:20px;padding:0}.navbar{padding-top:.25rem;padding-bottom:.25rem}.logo{height:1.8rem}.anchor{top:-55px}}@media only screen and (max-width:556px){#legal-1{width:100%}.legal-links{position:inherit;margin-left:20px;margin-bottom:1em}}@media only screen and (max-width:375px){#legal-1 p{display:block}}.lds-ring{display:inline-block;position:relative;width:18px;height:18px;padding-top:2px}#email-subscribe-form .lds-ring{padding-top:1px}.lds-ring div{-webkit-box-sizing:border-box;box-sizing:border-box;display:block;position:absolute;width:18px;height:18px;border:2px solid var(--b2);-webkit-border-radius:50%;border-radius:50%;-webkit-animation:lds-ring 1.2s cubic-bezier(.5,0,.5,1) infinite;animation:lds-ring 1.2s cubic-bezier(.5,0,.5,1) infinite;border-color:var(--b2) transparent transparent transparent}.lds-ring div:nth-child(1){-webkit-animation-delay:-.45s;animation-delay:-.45s}.lds-ring div:nth-child(2){-webkit-animation-delay:-.3s;animation-delay:-.3s}.lds-ring div:nth-child(3){-webkit-animation-delay:-.15s;animation-delay:-.15s}@-webkit-keyframes lds-ring{0%{-webkit-transform:rotate(0);transform:rotate(0)}100%{-webkit-transform:rotate(360deg);transform:rotate(360deg)}}@keyframes lds-ring{0%{-webkit-transform:rotate(0);transform:rotate(0)}100%{-webkit-transform:rotate(360deg);transform:rotate(360deg)}}#email-subscribe-form .sub-arrow{padding-top:2px}.sub-arrow{display:inline-block}.sub-load{display:none} \ No newline at end of file diff --git a/documentation/tdenginedocs-en/super-table/index.html b/documentation/tdenginedocs-en/super-table/index.html deleted file mode 100644 index 0e47a7bb9b4a170c70f9b484096f3af625865961..0000000000000000000000000000000000000000 --- a/documentation/tdenginedocs-en/super-table/index.html +++ /dev/null @@ -1,95 +0,0 @@ -Documentation | Taos Data
    Back

    STable: Super Table

    -

    "One Table for One Device" design can improve the insert/query performance significantly for a single device. But it has a side effect, the aggregation of multiple tables becomes hard. To reduce the complexity and improve the efficiency, TDengine introduced a new concept: STable (Super Table).

    -

    What is a Super Table

    -

    STable is an abstract and a template for a type of device. A STable contains a set of devices (tables) that have the same schema or data structure. Besides the shared schema, a STable has a set of tags, like the model, serial number and so on. Tags are used to record the static attributes for the devices and are used to group a set of devices (tables) for aggregation. Tags are metadata of a table and can be added, deleted or changed.

    -

    TDengine does not save tags as a part of the data points collected. Instead, tags are saved as metadata. Each table has a set of tags. To improve query performance, tags are all cached and indexed. One table can only belong to one STable, but one STable may contain many tables.

    -

    Like a table, you can create, show, delete and describe STables. Most query operations on tables can be applied to STable too, including the aggregation and selector functions. For queries on a STable, if no tags filter, the operations are applied to all the tables created via this STable. If there is a tag filter, the operations are applied only to a subset of the tables which satisfy the tag filter conditions. It will be very convenient to use tags to put devices into different groups for aggregation.

    -

    Create a STable

    -

    Similiar to creating a standard table, syntax is:

    -
    CREATE TABLE <stable_name> (<field_name> TIMESTAMP, field_name1 field_type, ...) TAGS(tag_name tag_type, ...)
    -

    New keyword "tags" is introduced, where tag_name is the tag name, and tag_type is the associated data type.

    -

    Note:

    -
      -
    1. The bytes of all tags together shall be less than 512
      2. -
    2. Tag's data type can not be time stamp or nchar
      3. -
    3. Tag name shall be different from the field name
      4. -
    4. Tag name shall not be the same as system keywords
      5. -
    5. Maximum number of tags is 6
      6. -
    -

    For example:

    -
    create table thermometer (ts timestamp, degree float) 
-tags (location binary(20), type int)
    -

    The above statement creates a STable thermometer with two tag "location" and "type"

    -

    Create a Table via STable

    -

    To create a table for a device, you can use a STable as its template and assign the tag values. The syntax is:

    -
    CREATE TABLE <tb_name> USING <stb_name> TAGS (tag_value1,...)
    -

    You can create any number of tables via a STable, and each table may have different tag values. For example, you create five tables via STable thermometer below:

    -
     create table t1 using thermometer tags ('beijing', 10);
- create table t2 using thermometer tags ('beijing', 20);
- create table t3 using thermometer tags ('shanghai', 10);
- create table t4 using thermometer tags ('shanghai', 20);
- create table t5 using thermometer tags ('new york', 10);
    -

    Aggregate Tables via STable

    -

    You can group a set of tables together by specifying the tags filter condition, then apply the aggregation operations. The result set can be grouped and ordered based on tag value. Syntax is:

    -
    SELECT function<field_name>, ... 
- FROM <stable_name> 
- WHERE <tag_name> <[=|<=|>=|<>] values..> ([AND|OR] ...
- INTERVAL (<time range>)
- GROUP BY <tag_name>, <tag_name> ... 
- ORDER BY <tag_name> <asc|desc>
- SLIMIT <group_limit>
- SOFFSET <group_offset>
- LIMIT <record_limit>
- OFFSET <record_offset>
    -

    For the time being, STable supports only the following aggregation/selection functions: sum, count, avg, first, last, min, max, top, bottom, and the projection operations, the same syntax as a standard table. Arithmetic operations are not supported, embedded queries not either.

    -

    INTERVAL is used for the aggregation over a time range.

    -

    If GROUP BY is not used, the aggregation is applied to all the selected tables, and the result set is output in ascending order of the timestamp, but you can use "ORDER BY _c0 ASC|DESC" to specify the order you like.

    -

    If GROUP BY is used, the aggregation is applied to groups based on tags. Each group is aggregated independently. Result set is a group of aggregation results. The group order is decided by ORDER BY . Inside each group, the result set is in the ascending order of the time stamp.

    -

    SLIMIT/SOFFSET are used to limit the number of groups and starting group number.

    -

    LIMIT/OFFSET are used to limit the number of records in a group and the starting rows.

    -

    Example 1:

    -

    Check the average, maximum, and minimum temperatures of Beijing and Shanghai, and group the result set by location and type. The SQL statement shall be:

    -
    SELECT COUNT(*), AVG(degree), MAX(degree), MIN(degree)
-FROM thermometer
-WHERE location='beijing' or location='tianjin'
-GROUP BY location, type
    -

    Example 2:

    -

    List the number of records, average, maximum, and minimum temperature every 10 minutes for the past 24 hours for all the thermometers located in Beijing with type 10. The SQL statement shall be:

    -
    SELECT COUNT(*), AVG(degree), MAX(degree), MIN(degree)
-FROM thermometer
-WHERE name='beijing' and type=10 and ts>=now-1d
-INTERVAL(10M)
    -

    Create Table Automatically

    -

    Insert operation will fail if the table is not created yet. But for STable, TDengine can create the table automatically if the application provides the STable name, table name and tags' value when inserting data points. The syntax is:

    -
    INSERT INTO <tb_name> USING <stb_name> TAGS (<tag1_value>, ...) VALUES (field_value, ...) (field_value, ...) ... <tb_name2> USING <stb_name2> TAGS(<tag1_value2>, ...) VALUES (<field1_value1>, ...) ...;
    -

    When inserting data points into table tb_name, the system will check if table tb_name is created or not. If it is already created, the data points will be inserted as usual. But if the table is not created yet, the system will create the table tb_bame using STable stb_name as the template with the tags. Multiple tables can be specified in the SQL statement.

    -

    Management of STables

    -

    After you can create a STable, you can describe, delete, change STables. This section lists all the supported operations.

    -

    Show STables in current DB

    -
    show stables;
    -

    It lists all STables in current DB, including the name, created time, number of fileds, number of tags, and number of tables which are created via this STable.

    -

    Describe a STable

    -
    DESCRIBE <stable_name>
    -

    It lists the STable's schema and tags

    -

    Drop a STable

    -
    DROP TABLE <stable_name>
    -

    To delete a STable, all the tables created via this STable will be deleted.

    -

    List the Associated Tables of a STable

    -
    SELECT TBNAME,[TAG_NAME, ...] FROM <stable_name> WHERE <tag_name> <[=|=<|>=|<>] values..> ([AND|OR] ...)
    -

    It will list all the tables which satisfy the tag filter conditions. The tables are all created from this specific STable. TBNAME is a new keyword introduced, it is the table name associated with the STable.

    -
    SELECT COUNT(TBNAME) FROM <stable_name> WHERE <tag_name> <[=|=<|>=|<>] values..> ([AND|OR] ...)
    -

    The above SQL statement will list the number of tables in a STable, which satisfy the filter condition.

    -

    Management of Tags

    -

    You can add, delete and change the tags for a STable, and you can change the tag value of a table. The SQL commands are listed below.

    -

    Add a Tag

    -
    ALTER TABLE <stable_name> ADD TAG <new_tag_name> <TYPE>
    -

    It adds a new tag to the STable with a data type. The maximum number of tags is 6.

    -

    Drop a Tag

    -
    ALTER TABLE <stable_name> DROP TAG <tag_name>
    -

    It drops a tag from a STable. The first tag could not be deleted, and there must be at least one tag.

    -

    Change a Tag's Name

    -
    ALTER TABLE <stable_name> CHANGE TAG <old_tag_name> <new_tag_name>
    -

    It changes the name of a tag from old to new.

    -

    Change the Tag's Value

    -
    ALTER TABLE <table_name> SET TAG <tag_name>=<new_tag_value>
    -

    It changes a table's tag value to a new one.

    Back
    diff --git a/documentation/tdenginedocs-en/taos-sql/index.html b/documentation/tdenginedocs-en/taos-sql/index.html deleted file mode 100644 index 6b73a70cd63d7abfac6706acda0f7b55630b6f0e..0000000000000000000000000000000000000000 --- a/documentation/tdenginedocs-en/taos-sql/index.html +++ /dev/null @@ -1,423 +0,0 @@ -Documentation | Taos Data
    Back

    TAOS SQL

    -

    TDengine provides a SQL like query language to insert or query data. You can execute the SQL statements through TDengine Shell, or through C/C++, Java(JDBC), Python, Restful, Go APIs to interact with the taosd service.

    -

    Before reading through, please have a look at the conventions used for syntax descriptions here in this documentation.

    -
      -
    • Squared brackets ("[]") indicate optional arguments or clauses
      • -
    • Curly braces ("{}") indicate that one member from a set of choices in the braces must be chosen
      • -
    • A single verticle line ("|") works a separator for multiple optional args or clauses
      • -
    • Dots ("…") means repeating for as many times
      • -
    -

    Data Types

    -

    Timestamp

    -

    The timestamp is the most important data type in TDengine. The first column of each table must be TIMESTAMP type, but other columns can also be TIMESTAMP type. The following rules for timestamp:

    -
      -

    • String Format: 'YYYY-MM-DD HH:mm:ss.MS', which represents the year, month, day, hour, minute and second and milliseconds. For example,'2017-08-12 18:52:58.128' is a valid timestamp string. Note: timestamp string must be quoted by either single quote or double quote.

      • -

    • Epoch Time: a timestamp value can also be a long integer representing milliseconds since the epoch. For example, the values in the above example can be represented as an epoch 1502535178128 in milliseconds. Please note the epoch time doesn't need any quotes.

      • -

    • Internal FunctionNOW : this is the current time of the server

      • -

    • If timestamp is 0 when inserting a record, timestamp will be set to the current time of the server

      • -

    • Arithmetic operations can be applied to timestamp. For example: now-2h represents a timestamp which is 2 hours ago from the current server time. Units include a (milliseconds), s (seconds), m (minutes), h (hours), d (days), w (weeks), n (months), y (years). NOW can be used in either insertions or queries.

      • -
    -

    Default time precision is millisecond, you can change it to microseocnd by setting parameter enableMicrosecond in system configuration. For epoch time, the long integer shall be microseconds since the epoch. For the above string format, MS shall be six digits.

    -

    Data Types

    -

    The full list of data types is listed below. For string types of data, we will use M to indicate the maximum length of that type.

    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Data TypeBytesNote
    1TINYINT1A nullable integer type with a range of [-127, 127]​
    2SMALLINT2A nullable integer type with a range of [-32767, 32767]​
    3INT4A nullable integer type with a range of [-2^31+1, 2^31-1 ]
    4BIGINT8A nullable integer type with a range of [-2^59, 2^59 ]​
    5FLOAT4A standard nullable float type with 6 -7 significant digits and a range of [-3.4E38, 3.4E38]
    6DOUBLE8A standard nullable double float type with 15-16 significant digits and a range of [-1.7E308, 1.7E308]​
    7BOOL1A nullable boolean type, [true, false]
    8TIMESTAMP8A nullable timestamp type with the same usage as the primary column timestamp
    9BINARY(M)MA nullable string type whose length is M, any exceeded chars will be automatically truncated. This type of string only supports ASCii encoded chars.
    10NCHAR(M)4 * MA nullable string type whose length is M, any exceeded chars will be truncated. The NCHAR type supports Unicode encoded chars.
    -

    All the keywords in a SQL statement are case-insensitive, but strings values are case-sensitive and must be quoted by a pair of ' or ". To quote a ' or a " , you can use the escape character \.

    -

    Database Management

    -
      -

    • Create a Database

      -
      CREATE DATABASE [IF NOT EXISTS] db_name [KEEP keep]
      -

      Option: KEEP is used for data retention policy. The data records will be removed once keep-days are passed. There are more parameters related to DB storage, please check system configuration.

      • -

    • Use a Database

      -
      USE db_name
      -

      Use or switch the current database.

      • -

    • Drop a Database

      -
      DROP DATABASE [IF EXISTS] db_name
      -

      Remove a database, all the tables inside the DB will be removed too, be careful.

      • -

    • List all Databases

      -
      SHOW DATABASES
      • -
    -

    Table Management

    -
      -

    • Create a Table

      -
      CREATE TABLE [IF NOT EXISTS] tb_name (timestamp_field_name TIMESTAMP, field1_name data_type1 [, field2_name data_type2 ...])
      -

      Note: 1) the first column must be timstamp, and system will set it as the primary key; 2) the record size is limited to 4096 bytes; 3) for binary or nachr data type, the length shall be specified, for example, binary(20), it means 20 bytes.

      • -

    • Drop a Table

      -
      DROP TABLE [IF EXISTS] tb_name
      • -

    • **List all Tables **

      -
      SHOW TABLES [LIKE tb_name_wildcar]
      -

      It shows all tables in the current DB. Note: wildcard character can be used in the table name to filter tables. Wildcard character: 1) ’%’ means 0 to any number of characters; 2）’_’ underscore means exactly one character.

      • -

    • Print Table Schema

      -
      DESCRIBE tb_name
      • -

    • Add a Column

      -
      ALTER TABLE tb_name ADD COLUMN field_name data_type
      • -

    • Drop a Column

      -
      ALTER TABLE tb_name DROP COLUMN field_name
      -

      If the table is created via [Super Table](), the schema can only be changed via STable. But for tables not created from STable, you can change their schema directly.

      • -
    -

    Tips: You can apply an operation on a table not in the current DB by concatenating DB name with the character '.', then with table name. For example, 'demo.tb1' means the operation is applied to table tb1 in DB demo although demo is not the current selected DB.

    -

    Inserting Records

    -
      -

    • Insert a Record

      -
      INSERT INTO tb_name VALUES (field_value, ...);
      -

      Insert a data record into table tb_name

      • -

    • Insert a Record with Selected Columns

      -
      INSERT INTO tb_name (field1_name, ...) VALUES(field1_value, ...)
      -

      Insert a data record into table tb_name, with data in selected columns. If a column is not selected, the system will put NULL there. First column (time stamp ) cant not be null, it must be inserted.

      • -

    • Insert a Batch of Records

      -
      INSERT INTO tb_name VALUES (field1_value1, ...) (field1_value2, ...)...;
      -

      Insert multiple data records to the table

      • -

    • Insert a Batch of Records with Selected Columns

      -
      INSERT INTO tb_name (field1_name, ...) VALUES(field1_value1, ...) (field1_value2, ...)
      • -

    • Insert Records into Multiple Tables

      -
      INSERT INTO tb1_name VALUES (field1_value1, ...)(field1_value2, ...)... 
-            tb2_name VALUES (field1_value1, ...)(field1_value2, ...)...;
      -

      Insert data records into table tb1_name and tb2_name

      • -

    • Insert Records into Multiple Tables with Selected Columns

      -
      INSERT INTO tb1_name (tb1_field1_name, ...) VALUES (field1_value1, ...) (field1_value1, ...)
-            tb2_name (tb2_field1_name, ...) VALUES(field1_value1, ...) (field1_value2, ...)
      • -
    -

    Note: For a table, the new record must have timestamp bigger than the last data record, otherwise, it will be thrown away. If timestamp is 0, the time stamp will be set to the system time on server.

    -

    IMPORT: If you do want to insert a historical data record into a table, use IMPORT command instead of INSERT. IMPORT has the same syntax as INSERT. If you want to import a batch of historical records, the records shall be ordered in the timestamp, otherwise, TDengine won't handle it in the right way.

    -

    Data Query

    -

    Query Syntax:

    -
    SELECT {* | expr_list} FROM tb_name
-    [WHERE where_condition]
-    [ORDER BY _c0 { DESC | ASC }]
-    [LIMIT limit [, OFFSET offset]]
-    [>> export_file]
-
-SELECT function_list FROM tb_name
-    [WHERE where_condition]
-    [LIMIT limit [, OFFSET offset]]
-    [>> export_file]
    -
      -
    • To query a table, use * to select all data from a table; or a specified list of expressions expr_list of columns. The SQL expression can contain alias and arithmetic operations between numeric typed columns.
      • -
    • For the WHERE conditions, use logical operations to filter the timestamp column and all numeric columns, and wild cards to filter the two string typed columns.
      • -
    • Sort the result set by the first column timestamp _c0 (or directly use the timestamp column name) in either descending or ascending order (by default). "Order by" could not be applied to other columns.
      • -
    • Use LIMIT and OFFSET to control the number of rows returned and the starting position of the retrieved rows. LIMIT/OFFSET is applied after "order by" operations.
      • -
    • Export the retrieved result set into a CSV file using >>. The target file's full path should be explicitly specified in the statement.
      • -
    -

    Supported Operations of Data Filtering:

    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    OperationNoteApplicable Data Types
    >larger thantimestamp and all numeric types
    <smaller thantimestamp and all numeric types
    >=larger than or equal totimestamp and all numeric types
    <=smaller than or equal totimestamp and all numeric types
    =equal toall types
    <>not equal toall types
    %match with any char sequencesbinary nchar
    _match with a single charbinary nchar
    -
      -
    1. For two or more conditions, only AND is supported, OR is not supported yet.
      2. -
    2. For filtering, only a single range is supported. For example, value>20 and value<30 is valid condition, but value<20 AND value<>5 is invalid condition
      3. -
    -

    Some Examples

    -
      -

    • For the examples below, table tb1 is created via the following statements

      -
      CREATE TABLE tb1 (ts timestamp, col1 int, col2 float, col3 binary(50))
      • -

    • Query all the records in tb1 in the last hour:

      -
      SELECT * FROM tb1 WHERE ts >= NOW - 1h
      • -

    • Query all the records in tb1 between 2018-06-01 08:00:00.000 and 2018-06-02 08:00:00.000, and filter out only the records whose col3 value ends with 'nny', and sort the records by their timestamp in a descending order:

      -
      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
      • -

    • Query the sum of col1 and col2 as alias 'complex_metric', and filter on the timestamp and col2 values. Limit the number of returned rows to 10, and offset the result by 5.

      -
      SELECT (col1 + col2) AS 'complex_metric' FROM tb1 WHERE ts > '2018-06-01 08:00:00.000' and col2 > 1.2 LIMIT 10 OFFSET 5
      • -

    • Query the number of records in tb1 in the last 10 minutes, whose col2 value is larger than 3.14, and export the result to file /home/testoutpu.csv.

      -
      SELECT COUNT(*) FROM tb1 WHERE ts >= NOW - 10m AND col2 > 3.14 >> /home/testoutpu.csv
      • -
    -

    SQL Functions

    -

    Aggregation Functions

    -

    TDengine supports aggregations over numerical values, they are listed below:

    -
      -

    • COUNT

      -
      SELECT COUNT([*|field_name]) FROM tb_name [WHERE clause]
      -

      Function: return the number of rows.
      -Return Data Type: integer.
      -Applicable Data Types: all.
      -Applied to: table/STable.
      -Note: 1) * can be used for all columns, as long as a column has non-NULL value, it will be counted; 2) If it is on a specific column, only rows with non-NULL value will be counted

      • -

    • AVG

      -
      SELECT AVG(field_name) FROM tb_name [WHERE clause]
      -

      Function: return the average value of a specific column.
      -Return Data Type: double.
      -Applicable Data Types: all types except timestamp, binary, nchar, bool.
      -Applied to: table/STable.

      • -

    • WAVG

      -
      SELECT WAVG(field_name) FROM tb_name WHERE clause
      -

      Function: return the time-weighted average value of a specific column
      -Return Data Type: double
      -Applicable Data Types: all types except timestamp, binary, nchar, bool
      -Applied to: table/STable

      • -

    • SUM

      -
      SELECT SUM(field_name) FROM tb_name [WHERE clause]
      -

      Function: return the sum of a specific column.
      -Return Data Type: long integer or double.
      -Applicable Data Types: all types except timestamp, binary, nchar, bool.
      -Applied to: table/STable.

      • -

    • STDDEV

      -
      SELECT STDDEV(field_name) FROM tb_name [WHERE clause]
      -

      Function: return the standard deviation of a specific column.
      -Return Data Type: double.
      -Applicable Data Types: all types except timestamp, binary, nchar, bool.
      -Applied to: table.

      • -

    • LEASTSQUARES

      -
      SELECT LEASTSQUARES(field_name) FROM tb_name [WHERE clause]
      -

      Function: performs a linear fit to the primary timestamp and the specified column. -Return Data Type: return a string of the coefficient and the interception of the fitted line.
      -Applicable Data Types: all types except timestamp, binary, nchar, bool.
      -Applied to: table.
      -Note: The timestmap is taken as the independent variable while the specified column value is taken as the dependent variables.

      • -
    -

    Selector Functions

    -
      -

    • MIN

      -
      SELECT MIN(field_name) FROM {tb_name | stb_name} [WHERE clause]
      -

      Function: return the minimum value of a specific column.
      -Return Data Type: the same data type.
      -Applicable Data Types: all types except timestamp, binary, nchar, bool.
      -Applied to: table/STable.

      • -

    • MAX

      -
      SELECT MAX(field_name) FROM { tb_name | stb_name } [WHERE clause]
      -

      Function: return the maximum value of a specific column.
      -Return Data Type: the same data type.
      -Applicable Data Types: all types except timestamp, binary, nchar, bool.
      -Applied to: table/STable.

      • -

    • FIRST

      -
      SELECT FIRST(field_name) FROM { tb_name | stb_name } [WHERE clause]
      -

      Function: return the first non-NULL value.
      -Return Data Type: the same data type.
      -Applicable Data Types: all types.
      -Applied to: table/STable.
      -Note: To return all columns, use first(*).

      • -

    • LAST

      -
      SELECT LAST(field_name) FROM { tb_name | stb_name } [WHERE clause]
      -

      Function: return the last non-NULL value.
      -Return Data Type: the same data type.
      -Applicable Data Types: all types.
      -Applied to: table/STable.
      -Note: To return all columns, use last(*).

      • -

    • TOP

      -
      SELECT TOP(field_name, K) FROM { tb_name | stb_name } [WHERE clause]
      -

      Function: return the k largest values.
      -Return Data Type: the same data type.
      -Applicable Data Types: all types except timestamp, binary, nchar, bool.
      -Applied to: table/STable.
      -Note: 1) valid range of K: 1≤k≤100; 2) the associated time stamp will be returned too.

      • -

    • BOTTOM

      -
      SELECT BOTTOM(field_name, K) FROM { tb_name | stb_name } [WHERE clause]
      -

      Function: return the k smallest values.
      -Return Data Type: the same data type.
      -Applicable Data Types: all types except timestamp, binary, nchar, bool.
      -Applied to: table/STable.
      -Note: 1) valid range of K: 1≤k≤100; 2) the associated timestamp will be returned too.

      • -

    • PERCENTILE

      -
      SELECT PERCENTILE(field_name, P) FROM { tb_name | stb_name } [WHERE clause]
      -

      Function: the value of the specified column below which P percent of the data points fall.
      -Return Data Type: the same data type.
      -Applicable Data Types: all types except timestamp, binary, nchar, bool.
      -Applied to: table/STable.
      -Note: The range of P is [0, 100]. When P=0 , PERCENTILE returns the equal value as MIN; when P=100, PERCENTILE returns the equal value as MAX.

      • -

    • LAST_ROW

      -
      SELECT LAST_ROW(field_name) FROM { tb_name | stb_name }
      -

      Function: return the last row.
      -Return Data Type: the same data type.
      -Applicable Data Types: all types.
      -Applied to: table/STable.
      -Note: different from last, last_row returns the last row even it has NULL value.

      • -
    -

    Transformation Functions

    -
      -

    • DIFF

      -
      SELECT DIFF(field_name) FROM tb_name [WHERE clause]
      -

      Function: return the difference between successive values of the specified column.
      -Return Data Type: the same data type.
      -Applicable Data Types: all types except timestamp, binary, nchar, bool.
      -Applied to: table.

      • -

    • SPREAD

      -
      SELECT SPREAD(field_name) FROM { tb_name | stb_name } [WHERE clause]
      -

      Function: return the difference between the maximum and the mimimum value.
      -Return Data Type: the same data type.
      -Applicable Data Types: all types except timestamp, binary, nchar, bool.
      -Applied to: table/STable.
      -Note: spread gives the range of data variation in a table/supertable; it is equivalent to MAX() - MIN()

      • -

    • Arithmetic Operations

      -
      SELECT field_name [+|-|*|/|%][Value|field_name] FROM { tb_name | stb_name }  [WHERE clause]
      -

      Function: arithmetic operations on the selected columns.
      -Return Data Type: double.
      -Applicable Data Types: all types except timestamp, binary, nchar, bool.
      -Applied to: table/STable.
      -Note: 1) bracket can be used for operation priority; 2) If a column has NULL value, the result is NULL.

      • -
    -

    Downsampling

    -

    Time-series data are usually sampled by sensors at a very high frequency, but more often we are only interested in the downsampled, aggregated data of each timeline. TDengine provides a convenient way to downsample the highly frequently sampled data points as well as filling the missing data with a variety of interpolation choices.

    -
    SELECT function_list FROM tb_name 
-  [WHERE where_condition]
-  INTERVAL (interval)
-  [FILL ({NONE | VALUE | PREV | NULL | LINEAR})]
-
-SELECT function_list FROM stb_name 
-  [WHERE where_condition]
-  [GROUP BY tags]
-  INTERVAL (interval)
-  [FILL ({ VALUE | PREV | NULL | LINEAR})]
    -

    The downsampling time window is defined by interval, which is at least 10 milliseconds. The query returns a new series of downsampled data that has a series of fixed timestamps with an increment of interval.

    -

    For the time being, only function count, avg, sum, stddev, leastsquares, percentile, min, max, first, last are supported. Functions that may return multiple rows are not supported.

    -

    You can also use FILL to interpolate the intervals that don't contain any data.FILL currently supports four different interpolation strategies which are listed below:

    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    InterpolationUsage
    FILL(VALUE, val1 [, val2, ...])Interpolate with specified constants
    FILL(PREV)Interpolate with the value at the previous timestamp
    FILL(LINEAR)Linear interpolation with the non-null values at the previous timestamp and at the next timestamp
    FILL(NULL)Interpolate with NULL value
    -

    A few downsampling examples:

    -
      -

    • Find the number of data points, the maximum value of col1 and minimum value of col2 in a tb1 for every 10 minutes in the last 5 hours:

      -
      SELECT COUNT(*), MAX(col1), MIN(col2) FROM tb1 WHERE ts > NOW - 5h INTERVAL (10m)
      • -

    • Fill the above downsampling results using constant-value interpolation:

      -
      SELECT COUNT(*), MAX(col1), MIN(col2) FROM tb1 WHERE ts > NOW - 5h INTERVAL(10m) FILL(VALUE, 0, 1, -1)
      -

      Note that the number of constant values in FILL() should be equal or fewer than the number of functions in the SELECT clause. Exceeding fill constants will be ignored.

      • -

    • Fill the above downsampling results using PREV interpolation:

      -
      SELECT COUNT(*), MAX(col1), MIN(col2) FROM tb1 WHERE ts > NOW - 5h INTERVAL(10m) FILL(PREV)
      -

      This will interpolate missing data points with the value at the previous timestamp.

      • -

    • Fill the above downsampling results using NULL interpolation:

      -
      SELECT COUNT(*), MAX(col1), MIN(col2) FROM tb1 WHERE ts > NOW - 5h INTERVAL(10m) FILL(NULL)
      -

      Fill NULL to the interpolated data points.

      • -
    -

    Notes:

    -
      -
    1. FILL can generate tons of interpolated data points if the interval is small and the queried time range is large. So always remember to specify a time range when using interpolation. For each query with interpolation, the result set can not exceed 10,000,000 records.
      2. -
    2. The result set will always be sorted by time in ascending order.
      3. -
    3. If the query object is a supertable, then all the functions will be applied to all the tables that qualify the WHERE conditions. If the GROUP BY clause is also applied, the result set will be sorted ascendingly by time in each single group, otherwise, the result set will be sorted ascendingly by time as a whole.
      4. -
    Back
    \ No newline at end of file diff --git a/documentation/webdocs/assets/Picture2.png b/documentation/webdocs/assets/Picture2.png deleted file mode 100644 index 715a8bd37ee9fe7e96eacce4e7ff563fedeefbee..0000000000000000000000000000000000000000 Binary files a/documentation/webdocs/assets/Picture2.png and /dev/null differ diff --git a/documentation/webdocs/assets/add_datasource1.jpg b/documentation/webdocs/assets/add_datasource1.jpg deleted file mode 100644 index 1f0f5110f312c57f3ec1788bbc02f04fac6ac142..0000000000000000000000000000000000000000 Binary files a/documentation/webdocs/assets/add_datasource1.jpg and /dev/null differ diff --git a/documentation/webdocs/assets/add_datasource2.jpg b/documentation/webdocs/assets/add_datasource2.jpg deleted file mode 100644 index fa7a83e00e96fae649910dff4edf5f5bdadd7850..0000000000000000000000000000000000000000 Binary files a/documentation/webdocs/assets/add_datasource2.jpg and /dev/null differ diff --git a/documentation/webdocs/assets/add_datasource3.jpg b/documentation/webdocs/assets/add_datasource3.jpg deleted file mode 100644 index 1d8a4a5d7644e9fb6dfbd86ed897cdaf2093148f..0000000000000000000000000000000000000000 Binary files a/documentation/webdocs/assets/add_datasource3.jpg and /dev/null differ diff --git a/documentation/webdocs/assets/add_datasource4.jpg b/documentation/webdocs/assets/add_datasource4.jpg deleted file mode 100644 index befb4243414554f24d165688f5117f1e70f8f21d..0000000000000000000000000000000000000000 Binary files a/documentation/webdocs/assets/add_datasource4.jpg and /dev/null differ diff --git a/documentation/webdocs/assets/create_dashboard1.jpg b/documentation/webdocs/assets/create_dashboard1.jpg deleted file mode 100644 index 3b83c3a1714e9e7540e0b06239ef7c1c4f63fe2c..0000000000000000000000000000000000000000 Binary files a/documentation/webdocs/assets/create_dashboard1.jpg and /dev/null differ diff --git a/documentation/webdocs/assets/create_dashboard2.jpg b/documentation/webdocs/assets/create_dashboard2.jpg deleted file mode 100644 index fe5d768ac55254251e0290bf257178f5ff28f5a5..0000000000000000000000000000000000000000 Binary files a/documentation/webdocs/assets/create_dashboard2.jpg and /dev/null differ diff --git a/documentation/webdocs/assets/fig1.png b/documentation/webdocs/assets/fig1.png deleted file mode 100644 index af9b74e0d1a872b8d93f71842dc0063bc8a86092..0000000000000000000000000000000000000000 Binary files a/documentation/webdocs/assets/fig1.png and /dev/null differ diff --git a/documentation/webdocs/assets/fig2.png b/documentation/webdocs/assets/fig2.png deleted file mode 100644 index 3bae70ba86964c3c341b72ea1d3af04201f7c6c1..0000000000000000000000000000000000000000 Binary files a/documentation/webdocs/assets/fig2.png and /dev/null differ diff --git a/documentation/webdocs/assets/image-20190707124650780.png b/documentation/webdocs/assets/image-20190707124650780.png deleted file mode 100644 index 9ebcac863e862d8b240c86dec29be1ebe7aa50f0..0000000000000000000000000000000000000000 Binary files a/documentation/webdocs/assets/image-20190707124650780.png and /dev/null differ diff --git a/documentation/webdocs/assets/image-20190707124818590.png b/documentation/webdocs/assets/image-20190707124818590.png deleted file mode 100644 index dc1cb6325b2d4cd6f05c88b75b4d17ef85caa67f..0000000000000000000000000000000000000000 Binary files a/documentation/webdocs/assets/image-20190707124818590.png and /dev/null differ diff --git a/documentation/webdocs/assets/import_dashboard1.jpg b/documentation/webdocs/assets/import_dashboard1.jpg deleted file mode 100644 index 9d2ce7ed65eb0c2c729de50283b30491793493dc..0000000000000000000000000000000000000000 Binary files a/documentation/webdocs/assets/import_dashboard1.jpg and /dev/null differ diff --git a/documentation/webdocs/assets/import_dashboard2.jpg b/documentation/webdocs/assets/import_dashboard2.jpg deleted file mode 100644 index 94b09f0ee39552bb84f7ba1f65815ce2c9548b2d..0000000000000000000000000000000000000000 Binary files a/documentation/webdocs/assets/import_dashboard2.jpg and /dev/null differ diff --git a/documentation/webdocs/assets/nodes.png b/documentation/webdocs/assets/nodes.png deleted file mode 100644 index d4ae5120c29b8cfacdc543df5a2a7104d77a2a7b..0000000000000000000000000000000000000000 Binary files a/documentation/webdocs/assets/nodes.png and /dev/null differ diff --git a/documentation/webdocs/assets/structure.png b/documentation/webdocs/assets/structure.png deleted file mode 100644 index 801829b68580e1a46d0841a3d38e4885eb383991..0000000000000000000000000000000000000000 Binary files a/documentation/webdocs/assets/structure.png and /dev/null differ diff --git a/documentation/webdocs/assets/vnode.png b/documentation/webdocs/assets/vnode.png deleted file mode 100644 index 5247717f62118a8e690e80a3538c1a8dd1ab9416..0000000000000000000000000000000000000000 Binary files a/documentation/webdocs/assets/vnode.png and /dev/null differ diff --git a/documentation/webdocs/assets/write_process.png b/documentation/webdocs/assets/write_process.png deleted file mode 100644 index f7d60864824a34af48df637026d704a921dc49f6..0000000000000000000000000000000000000000 Binary files a/documentation/webdocs/assets/write_process.png and /dev/null differ diff --git a/documentation/webdocs/markdowndocs/Connections with other Tools-ch.md b/documentation/webdocs/markdowndocs/Connections with other Tools-ch.md deleted file mode 100644 index f7da0c654d493bb932b2b0edceccd16fbac2091b..0000000000000000000000000000000000000000 --- a/documentation/webdocs/markdowndocs/Connections with other Tools-ch.md +++ /dev/null @@ -1,175 +0,0 @@ -# 与其他工具的连接 - -## Telegraf - -TDengine能够与开源数据采集系统[Telegraf](https://www.influxdata.com/time-series-platform/telegraf/)快速集成，整个过程无需任何代码开发。 - -### 安装Telegraf - -目前TDengine支持Telegraf 1.7.4以上的版本。用户可以根据当前的操作系统，到Telegraf官网下载安装包，并执行安装。下载地址如下：https://portal.influxdata.com/downloads - -### 配置Telegraf - -修改Telegraf配置文件/etc/telegraf/telegraf.conf中与TDengine有关的配置项。 - -在output plugins部分，增加[[outputs.http]]配置项： - -- url：http://ip:6020/telegraf/udb，其中ip为TDengine集群的中任意一台服务器的IP地址，6020为TDengine RESTful接口的端口号，telegraf为固定关键字，udb为用于存储采集数据的数据库名称，可预先创建。 -- method: "POST" -- username: 登录TDengine的用户名 -- password: 登录TDengine的密码 -- data_format: "json" -- json_timestamp_units: "1ms" - -在agent部分： - -- hostname: 区分不同采集设备的机器名称，需确保其唯一性 -- metric_batch_size: 30，允许Telegraf每批次写入记录最大数量，增大其数量可以降低Telegraf的请求发送频率，但对于TDengine，该数值不能超过50 - -关于如何使用Telegraf采集数据以及更多有关使用Telegraf的信息，请参考Telegraf官方的[文档](https://docs.influxdata.com/telegraf/v1.11/)。 - -## Grafana - -TDengine能够与开源数据可视化系统[Grafana](https://www.grafana.com/)快速集成搭建数据监测报警系统，整个过程无需任何代码开发，TDengine中数据表中内容可以在仪表盘(DashBoard)上进行可视化展现。 - -### 安装Grafana - -目前TDengine支持Grafana 5.2.4以上的版本。用户可以根据当前的操作系统，到Grafana官网下载安装包，并执行安装。下载地址如下：https://grafana.com/grafana/download。 - -### 配置Grafana - -TDengine的Grafana插件在安装包的/usr/local/taos/connector/grafana目录下。 - -以CentOS 7.2操作系统为例，将tdengine目录拷贝到/var/lib/grafana/plugins目录下，重新启动grafana即可。 - -### 使用 Grafana - -#### 配置数据源 - -用户可以直接通过 localhost:3000 的网址，登录 Grafana 服务器(用户名/密码:admin/admin)，通过左侧 `Configuration -> Data Sources` 可以添加数据源，如下图所示： - -![img](../assets/add_datasource1.jpg) - -点击 `Add data source` 可进入新增数据源页面，在查询框中输入 TDengine 可选择添加，如下图所示： - -![img](../assets/add_datasource2.jpg) - -进入数据源配置页面，按照默认提示修改相应配置即可： - -![img](../assets/add_datasource3.jpg) - -* Host： TDengine 集群的中任意一台服务器的 IP 地址与 TDengine RESTful 接口的端口号(6020)，默认 http://localhost:6020。 -* User：TDengine 用户名。 -* Password：TDengine 用户密码。 - -点击 `Save & Test` 进行测试，成功会有如下提示： - -![img](../assets/add_datasource4.jpg) - -#### 创建 Dashboard - -回到主界面创建 Dashboard，点击 Add Query 进入面板查询页面： - -![img](../assets/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](../assets/create_dashboard2.jpg) - -> 关于如何使用Grafana创建相应的监测界面以及更多有关使用Grafana的信息，请参考Grafana官方的[文档](https://grafana.com/docs/)。 - -#### 导入 Dashboard - -在 Grafana 插件目录 /usr/local/taos/connector/grafana/tdengine/dashboard/ 下提供了一个 `tdengine-grafana.json` 可导入的 dashboard。 - -点击左侧 `Import` 按钮，并上传 `tdengine-grafana.json` 文件： - -![img](../assets/import_dashboard1.jpg) - -导入完成之后可看到如下效果： - -![img](../assets/import_dashboard2.jpg) - - -## Matlab - -MatLab可以通过安装包内提供的JDBC Driver直接连接到TDengine获取数据到本地工作空间。 - -### MatLab的JDBC接口适配 - -MatLab的适配有下面几个步骤，下面以Windows10上适配MatLab2017a为例： - -- 将TDengine安装包内的驱动程序JDBCDriver-1.0.0-dist.jar拷贝到${matlab_root}\MATLAB\R2017a\java\jar\toolbox -- 将TDengine安装包内的taos.lib文件拷贝至${matlab_ root _dir}\MATLAB\R2017a\lib\win64 -- 将新添加的驱动jar包加入MatLab的classpath。在${matlab_ root _dir}\MATLAB\R2017a\toolbox\local\classpath.txt文件中添加下面一行 - -​ `$matlabroot/java/jar/toolbox/JDBCDriver-1.0.0-dist.jar` - -- 在${user_home}\AppData\Roaming\MathWorks\MATLAB\R2017a\下添加一个文件javalibrarypath.txt, 并在该文件中添加taos.dll的路径，比如您的taos.dll是在安装时拷贝到了C:\Windows\System32下，那么就应该在javalibrarypath.txt中添加如下一行： - -​ `C:\Windows\System32` - -### 在MatLab中连接TDengine获取数据 - -在成功进行了上述配置后，打开MatLab。 - -- 创建一个连接： - - `conn = database(‘db’, ‘root’, ‘taosdata’, ‘com.taosdata.jdbc.TSDBDriver’, ‘jdbc:TSDB://127.0.0.1:0/’)` - -- 执行一次查询： - - `sql0 = [‘select * from tb’]` - - `data = select(conn, sql0);` - -- 插入一条记录: - - `sql1 = [‘insert into tb values (now, 1)’]` - - `exec(conn, sql1)` - -更多例子细节请参考安装包内examples\Matlab\TDengineDemo.m文件。 - -## R - -R语言支持通过JDBC接口来连接TDengine数据库。首先需要安装R语言的JDBC包。启动R语言环境，然后执行以下命令安装R语言的JDBC支持库： - -```R -install.packages('rJDBC', repos='http://cran.us.r-project.org') -``` - -安装完成以后，通过执行`library('RJDBC')`命令加载 _RJDBC_ 包： - -然后加载TDengine的JDBC驱动： - -```R -drv<-JDBC("com.taosdata.jdbc.TSDBDriver","JDBCDriver-1.0.0-dist.jar", identifier.quote="\"") -``` -如果执行成功，不会出现任何错误信息。之后通过以下命令尝试连接数据库： - -```R -conn<-dbConnect(drv,"jdbc:TSDB://192.168.0.1:0/?user=root&password=taosdata","root","taosdata") -``` - -注意将上述命令中的IP地址替换成正确的IP地址。如果没有任务错误的信息，则连接数据库成功，否则需要根据错误提示调整连接的命令。TDengine支持以下的 _RJDBC_ 包中函数： - - -- dbWriteTable(conn, "test", iris, overwrite=FALSE, append=TRUE)：将数据框iris写入表test中，overwrite必须设置为false，append必须设为TRUE,且数据框iris要与表test的结构一致。 -- dbGetQuery(conn, "select count(*) from test")：查询语句 -- dbSendUpdate(conn, "use db")：执行任何非查询sql语句。例如dbSendUpdate(conn, "use db")， 写入数据dbSendUpdate(conn, "insert into t1 values(now, 99)")等。 -- dbReadTable(conn, "test")：读取表test中数据 -- dbDisconnect(conn)：关闭连接 -- dbRemoveTable(conn, "test")：删除表test - -TDengine客户端暂不支持如下函数： -- dbExistsTable(conn, "test")：是否存在表test -- dbListTables(conn)：显示连接中的所有表 - - diff --git a/documentation/webdocs/markdowndocs/Connections with other Tools.md b/documentation/webdocs/markdowndocs/Connections with other Tools.md deleted file mode 100644 index 8be05698497184aee2c41a60e32f39b636e2070e..0000000000000000000000000000000000000000 --- a/documentation/webdocs/markdowndocs/Connections with other Tools.md +++ /dev/null @@ -1,167 +0,0 @@ -# Connect with other tools - -## Telegraf - -TDengine is easy to integrate with [Telegraf](https://www.influxdata.com/time-series-platform/telegraf/), an open-source server agent for collecting and sending metrics and events, without more development. - -### Install Telegraf - -At present, TDengine supports Telegraf newer than version 1.7.4. Users can go to the [download link] and choose the proper package to install on your system. - -### Configure Telegraf - -Telegraf is configured by changing items in the configuration file */etc/telegraf/telegraf.conf*. - - -In **output plugins** section，add _[[outputs.http]]_ iterm： - -- _url_: http://ip:6020/telegraf/udb, in which _ip_ is the IP address of any node in TDengine cluster. Port 6020 is the RESTful APT port used by TDengine. _udb_ is the name of the database to save data, which needs to create beforehand. -- _method_: "POST" -- _username_: username to login TDengine -- _password_: password to login TDengine -- _data_format_: "json" -- _json_timestamp_units_: "1ms" - -In **agent** part： - -- hostname: used to distinguish different machines. Need to be unique. -- metric_batch_size: 30，the maximum number of records allowed to write in Telegraf. The larger the value is, the less frequent requests are sent. For TDengine, the value should be less than 50. - -Please refer to the [Telegraf docs](https://docs.influxdata.com/telegraf/v1.11/) for more information. - -## Grafana - -[Grafana] is an open-source system for time-series data display. It is easy to integrate TDengine and Grafana to build a monitor system. Data saved in TDengine can be fetched and shown on the Grafana dashboard. - -### Install Grafana - -For now, TDengine only supports Grafana newer than version 5.2.4. Users can go to the [Grafana download page] for the proper package to download. - -### Configure Grafana - -TDengine Grafana plugin is in the _/usr/local/taos/connector/grafana_ directory. -Taking Centos 7.2 as an example, just copy TDengine directory to _/var/lib/grafana/plugins_ directory and restart Grafana. - -### Use Grafana - -Users can log in the Grafana server (username/password:admin/admin) through localhost:3000 to configure TDengine as the data source. As is shown in the picture below, TDengine as a data source option is shown in the box: - - -![img](../assets/clip_image001.png) - -When choosing TDengine as the data source, the Host in HTTP configuration should be configured as the IP address of any node of a TDengine cluster. The port should be set as 6020. For example, when TDengine and Grafana are on the same machine, it should be configured as _http://localhost:6020. - - -Besides, users also should set the username and password used to log into TDengine. Then click _Save&Test_ button to save. - -![img](../assets/clip_image001-2474914.png) - -Then, TDengine as a data source should show in the Grafana data source list. - -![img](../assets/clip_image001-2474939.png) - - -Then, users can create Dashboards in Grafana using TDengine as the data source: - - -![img](../assets/clip_image001-2474961.png) - - - -Click _Add Query_ button to add a query and input the SQL command you want to run in the _INPUT SQL_ text box. The SQL command should expect a two-row, multi-column result, such as _SELECT count(*) FROM sys.cpu WHERE ts>=from and ts<​to interval(interval)_, in which, _from_, _to_ and _inteval_ are TDengine inner variables representing query time range and time interval. - - -_ALIAS BY_ field is to set the query alias. Click _GENERATE SQL_ to send the command to TDengine: - -![img](../assets/clip_image001-2474987.png) - -Please refer to the [Grafana official document] for more information about Grafana. - - -## Matlab - -Matlab can connect to and retrieve data from TDengine by TDengine JDBC Driver. - -### MatLab and TDengine JDBC adaptation - -Several steps are required to adapt Matlab to TDengine. Taking adapting Matlab2017a on Windows10 as an example: - -1. Copy the file _JDBCDriver-1.0.0-dist.jar_ in TDengine package to the directory _${matlab_root}\MATLAB\R2017a\java\jar\toolbox_ -2. Copy the file _taos.lib_ in TDengine package to _${matlab_ root _dir}\MATLAB\R2017a\lib\win64_ -3. Add the .jar package just copied to the Matlab classpath. Append the line below as the end of the file of _${matlab_ root _dir}\MATLAB\R2017a\toolbox\local\classpath.txt_ - -​ `$matlabroot/java/jar/toolbox/JDBCDriver-1.0.0-dist.jar` - -4. Create a file called _javalibrarypath.txt_ in directory _${user_home}\AppData\Roaming\MathWorks\MATLAB\R2017a\_, and add the _taos.dll_ path in the file. For example, if the file _taos.dll_ is in the directory of _C:\Windows\System32_，then add the following line in file *javalibrarypath.txt*: - -​ `C:\Windows\System32` - -### TDengine operations in Matlab - -After correct configuration, open Matlab: - -- build a connection： - - `conn = database(‘db’, ‘root’, ‘taosdata’, ‘com.taosdata.jdbc.TSDBDriver’, ‘jdbc:TSDB://127.0.0.1:0/’)` - -- Query： - - `sql0 = [‘select * from tb’]` - - `data = select(conn, sql0);` - -- Insert a record: - - `sql1 = [‘insert into tb values (now, 1)’]` - - `exec(conn, sql1)` - -Please refer to the file _examples\Matlab\TDengineDemo.m_ for more information. - -## R - -Users can use R language to access the TDengine server with the JDBC interface. At first, install JDBC package in R: - -```R -install.packages('rJDBC', repos='http://cran.us.r-project.org') -``` - -Then use _library_ function to load the package: - -```R -library('RJDBC') -``` - -Then load the TDengine JDBC driver: - -```R -drv<-JDBC("com.taosdata.jdbc.TSDBDriver","JDBCDriver-1.0.0-dist.jar", identifier.quote="\"") -``` -If succeed, no error message will display. Then use the following command to try a database connection: - -```R -conn<-dbConnect(drv,"jdbc:TSDB://192.168.0.1:0/?user=root&password=taosdata","root","taosdata") -``` - -Please replace the IP address in the command above to the correct one. If no error message is shown, then the connection is established successfully. TDengine supports below functions in _RJDBC_ package: - - -- _dbWriteTable(conn, "test", iris, overwrite=FALSE, append=TRUE)_: write the data in a data frame _iris_ to the table _test_ in the TDengine server. Parameter _overwrite_ must be _false_. _append_ must be _TRUE_ and the schema of the data frame _iris_ should be the same as the table _test_. -- _dbGetQuery(conn, "select count(*) from test")_: run a query command -- _dbSendUpdate(conn, "use db")_: run any non-query command. -- _dbReadTable(conn, "test"_): read all the data in table _test_ -- _dbDisconnect(conn)_: close a connection -- _dbRemoveTable(conn, "test")_: remove table _test_ - -Below functions are **not supported** currently: -- _dbExistsTable(conn, "test")_: if talbe _test_ exists -- _dbListTables(conn)_: list all tables in the connection - - -[Telegraf]: www.taosdata.com -[download link]: https://portal.influxdata.com/downloads -[Telegraf document]: www.taosdata.com -[Grafana]: https://grafana.com -[Grafana download page]: https://grafana.com/grafana/download -[Grafana official document]: https://grafana.com/docs/ - diff --git a/documentation/webdocs/markdowndocs/Connector.md b/documentation/webdocs/markdowndocs/Connector.md deleted file mode 100644 index fcd6976cb0ee9dcfe44926db7bb327f09e82e39f..0000000000000000000000000000000000000000 --- a/documentation/webdocs/markdowndocs/Connector.md +++ /dev/null @@ -1,918 +0,0 @@ -# TDengine connectors - -TDengine provides many connectors for development, including C/C++, JAVA, Python, RESTful, Go, Node.JS, etc. - -NOTE: All APIs which require a SQL string as parameter, including but not limit to `taos_query`, `taos_query_a`, `taos_subscribe` in the C/C++ Connector and their counterparts in other connectors, can ONLY process one SQL statement at a time. If more than one SQL statements are provided, their behaviors are undefined. - -## C/C++ API - -C/C++ APIs are similar to the MySQL APIs. Applications should include TDengine head file _taos.h_ to use C/C++ APIs by adding the following line in code: -```C -#include -``` -Make sure TDengine library _libtaos.so_ is installed and use _-ltaos_ option to link the library when compiling. In most cases, if the return value of an API is integer, it return _0_ for success and other values as an error code for failure; if the return value is pointer, then _NULL_ is used for failure. - - -### C/C++ sync API - -Sync APIs are those APIs waiting for responses from the server after sending a request. TDengine has the following sync APIs: - - -- `TAOS *taos_connect(char *ip, char *user, char *pass, char *db, int port)` - - Open a connection to a TDengine server. The parameters are _ip_ (IP address of the server), _user_ (username to login), _pass_ (password to login), _db_ (database to use after connection) and _port_ (port number to connect). The parameter _db_ can be NULL for no database to use after connection. Otherwise, the database should exist before connection or a connection error is reported. The handle returned by this API should be kept for future use. - -- `void taos_close(TAOS *taos)` - - Close a connection to a TDengine server by the handle returned by _taos_connect_` - - -- `int taos_query(TAOS *taos, char *sqlstr)` - - The API used to run a SQL command. The command can be DQL or DML. The parameter _taos_ is the handle returned by _taos_connect_. Return value _-1_ means failure. - - -- `TAOS_RES *taos_use_result(TAOS *taos)` - - Use the result after running _taos_query_. The handle returned should be kept for future fetch. - - -- `TAOS_ROW taos_fetch_row(TAOS_RES *res)` - - Fetch a row of return results through _res_, the handle returned by _taos_use_result_. - - -- `int taos_num_fields(TAOS_RES *res)` - - Get the number of fields in the return result. - - -- `TAOS_FIELD *taos_fetch_fields(TAOS_RES *res)` - - Fetch the description of each field. The description includes the property of data type, field name, and bytes. The API should be used with _taos_num_fields_ to fetch a row of data. - - -- `void taos_free_result(TAOS_RES *res)` - - Free the resources used by a result set. Make sure to call this API after fetching results or memory leak would happen. - - -- `void taos_init()` - - Initialize the environment variable used by TDengine client. The API is not necessary since it is called int _taos_connect_ by default. - - -- `char *taos_errstr(TAOS *taos)` - - Return the reason of the last API call failure. The return value is a string. - - -- `int *taos_errno(TAOS *taos)` - - Return the error code of the last API call failure. The return value is an integer. - - -- `int taos_options(TSDB_OPTION option, const void * arg, ...)` - - Set client options. The parameter _option_ supports values of _TSDB_OPTION_CONFIGDIR_ (configuration directory), _TSDB_OPTION_SHELL_ACTIVITY_TIMER_, _TSDB_OPTION_LOCALE_ (client locale) and _TSDB_OPTION_TIMEZONE_ (client timezone). - -The 12 APIs are the most important APIs frequently used. Users can check _taos.h_ file for more API information. - -**Note**: The connection to a TDengine server is not multi-thread safe. So a connection can only be used by one thread. - -### C/C++ parameter binding API - -TDengine also provides parameter binding APIs, like MySQL, only question mark `?` can be used to represent a parameter in these APIs. - -- `TAOS_STMT* taos_stmt_init(TAOS *taos)` - - Create a TAOS_STMT to represent the prepared statement for other APIs. - -- `int taos_stmt_prepare(TAOS_STMT *stmt, const char *sql, unsigned long length)` - - Parse SQL statement _sql_ and bind result to _stmt_ , if _length_ larger than 0, its value is used to determine the length of _sql_, the API auto detects the actual length of _sql_ otherwise. - -- `int taos_stmt_bind_param(TAOS_STMT *stmt, TAOS_BIND *bind)` - - Bind values to parameters. _bind_ points to an array, the element count and sequence of the array must be identical as the parameters of the SQL statement. The usage of _TAOS_BIND_ is same as _MYSQL_BIND_ in MySQL, its definition is as below: - - ```c - typedef struct TAOS_BIND { - int buffer_type; - void * buffer; - unsigned long buffer_length; // not used in TDengine - unsigned long *length; - int * is_null; - int is_unsigned; // not used in TDengine - int * error; // not used in TDengine - } TAOS_BIND; - ``` - -- `int taos_stmt_add_batch(TAOS_STMT *stmt)` - - Add bound parameters to batch, client can call `taos_stmt_bind_param` again after calling this API. Note this API only support _insert_ / _import_ statements, it returns an error in other cases. - -- `int taos_stmt_execute(TAOS_STMT *stmt)` - - Execute the prepared statement. This API can only be called once for a statement at present. - -- `TAOS_RES* taos_stmt_use_result(TAOS_STMT *stmt)` - - Acquire the result set of an executed statement. The usage of the result is same as `taos_use_result`, `taos_free_result` must be called after one you are done with the result set to release resources. - -- `int taos_stmt_close(TAOS_STMT *stmt)` - - Close the statement, release all resources. - - -### C/C++ async API - -In addition to sync APIs, TDengine also provides async APIs, which are more efficient. Async APIs are returned right away without waiting for a response from the server, allowing the application to continute with other tasks without blocking. So async APIs are more efficient, especially useful when in a poor network. - -All async APIs require callback functions. The callback functions have the format: -```C -void fp(void *param, TAOS_RES * res, TYPE param3) -``` -The first two parameters of the callback function are the same for all async APIs. The third parameter is different for different APIs. Generally, the first parameter is the handle provided to the API for action. The second parameter is a result handle. - -- `void taos_query_a(TAOS *taos, char *sqlstr, void (*fp)(void *param, TAOS_RES *, int code), void *param);` - - The async query interface. _taos_ is the handle returned by _taos_connect_ interface. _sqlstr_ is the SQL command to run. _fp_ is the callback function. _param_ is the parameter required by the callback function. The third parameter of the callback function _code_ is _0_ (for success) or a negative number (for failure, call taos_errstr to get the error as a string). Applications mainly handle with the second parameter, the returned result set. - - -- `void taos_fetch_rows_a(TAOS_RES *res, void (*fp)(void *param, TAOS_RES *, int numOfRows), void *param);` - - The async API to fetch a batch of rows, which should only be used with a _taos_query_a_ call. The parameter _res_ is the result handle returned by _taos_query_a_. _fp_ is the callback function. _param_ is a user-defined structure to pass to _fp_. The parameter _numOfRows_ is the number of result rows in the current fetch cycle. In the callback function, applications should call _taos_fetch_row_ to get records from the result handle. After getting a batch of results, applications should continue to call _taos_fetch_rows_a_ API to handle the next batch, until the _numOfRows_ is _0_ (for no more data to fetch) or _-1_ (for failure). - - -- `void taos_fetch_row_a(TAOS_RES *res, void (*fp)(void *param, TAOS_RES *, TAOS_ROW row), void *param);` - - The async API to fetch a result row. _res_ is the result handle. _fp_ is the callback function. _param_ is a user-defined structure to pass to _fp_. The third parameter of the callback function is a single result row, which is different from that of _taos_fetch_rows_a_ API. With this API, it is not necessary to call _taos_fetch_row_ to retrieve each result row, which is handier than _taos_fetch_rows_a_ but less efficient. - - -Applications may apply operations on multiple tables. However, **it is important to make sure the operations on the same table are serialized**. That means after sending an insert request in a table to the server, no operations on the table are allowed before a response is received. - -### C/C++ continuous query interface - -TDengine provides APIs for continuous query driven by time, which run queries periodically in the background. There are only two APIs: - - -- `TAOS_STREAM *taos_open_stream(TAOS *taos, char *sqlstr, void (*fp)(void *param, TAOS_RES *, TAOS_ROW row), int64_t stime, void *param, void (*callback)(void *));` - - The API is used to create a continuous query. - * _taos_: the connection handle returned by _taos_connect_. - * _sqlstr_: the SQL string to run. Only query commands are allowed. - * _fp_: the callback function to run after a query - * _param_: a parameter passed to _fp_ - * _stime_: the time of the stream starts in the form of epoch milliseconds. If _0_ is given, the start time is set as the current time. - * _callback_: a callback function to run when the continuous query stops automatically. - - The API is expected to return a handle for success. Otherwise, a NULL pointer is returned. - - -- `void taos_close_stream (TAOS_STREAM *tstr)` - - Close the continuous query by the handle returned by _taos_open_stream_. Make sure to call this API when the continuous query is not needed anymore. - - -### C/C++ subscription API - -For the time being, TDengine supports subscription on one or multiple tables. It is implemented through periodic pulling from a TDengine server. - -* `TAOS_SUB *taos_subscribe(TAOS* taos, int restart, const char* topic, const char *sql, TAOS_SUBSCRIBE_CALLBACK fp, void *param, int interval)` - - The API is used to start a subscription session, it returns the subscription object on success and `NULL` in case of failure, the parameters are: - * **taos**: The database connnection, which must be established already. - * **restart**: `Zero` to continue a subscription if it already exits, other value to start from the beginning. - * **topic**: The unique identifier of a subscription. - * **sql**: A sql statement for data query, it can only be a `select` statement, can only query for raw data, and can only query data in ascending order of the timestamp field. - * **fp**: A callback function to receive query result, only used in asynchronization mode and should be `NULL` in synchronization mode, please refer below for its prototype. - * **param**: User provided additional parameter for the callback function. - * **interval**: Pulling interval in millisecond. Under asynchronization mode, API will call the callback function `fp` in this interval, system performance will be impacted if this interval is too short. Under synchronization mode, if the duration between two call to `taos_consume` is less than this interval, the second call blocks until the duration exceed this interval. - -* `typedef void (*TAOS_SUBSCRIBE_CALLBACK)(TAOS_SUB* tsub, TAOS_RES *res, void* param, int code)` - - Prototype of the callback function, the parameters are: - * tsub: The subscription object. - * res: The query result. - * param: User provided additional parameter when calling `taos_subscribe`. - * code: Error code in case of failures. - -* `TAOS_RES *taos_consume(TAOS_SUB *tsub)` - - The API used to get the new data from a TDengine server. It should be put in an loop. The parameter `tsub` is the handle returned by `taos_subscribe`. This API should only be called in synchronization mode. If the duration between two call to `taos_consume` is less than pulling interval, the second call blocks until the duration exceed the interval. The API returns the new rows if new data arrives, or empty rowset otherwise, and if there's an error, it returns `NULL`. - -* `void taos_unsubscribe(TAOS_SUB *tsub, int keepProgress)` - - Stop a subscription session by the handle returned by `taos_subscribe`. If `keepProgress` is **not** zero, the subscription progress information is kept and can be reused in later call to `taos_subscribe`, the information is removed otherwise. - -## Java Connector - -To Java delevopers, TDengine provides `taos-jdbcdriver` according to the JDBC(3.0) API. Users can find and download it through [Sonatype Repository][1]. - -Since the native language of TDengine is C, the necessary TDengine library should be checked before using the taos-jdbcdriver: - -* libtaos.so (Linux) - After TDengine is installed successfully, the library `libtaos.so` will be automatically copied to the `/usr/lib/`, which is the system's default search path. - -* taos.dll (Windows) - After TDengine client is installed, the library `taos.dll` will be automatically copied to the `C:/Windows/System32`, which is the system's default search path. - -> Note: Please make sure that [TDengine Windows client][14] has been installed if developing on Windows. Now although TDengine client would be defaultly installed together with TDengine server, it can also be installed [alone][15]. - -Since TDengine is time-series database, there are still some differences compared with traditional databases in using TDengine JDBC driver: -* TDengine doesn't allow to delete/modify a single record, and thus JDBC driver also has no such method. -* No support for transaction -* No support for union between tables -* No support for nested query，`There is at most one open ResultSet for each Connection. Thus, TSDB JDBC Driver will close current ResultSet if it is not closed and a new query begins`. - -## Version list of TAOS-JDBCDriver and required TDengine and JDK - -| taos-jdbcdriver | TDengine | JDK | -| --- | --- | --- | -| 1.0.3 | 1.6.1.x or higher | 1.8.x | -| 1.0.2 | 1.6.1.x or higher | 1.8.x | -| 1.0.1 | 1.6.1.x or higher | 1.8.x | - -## DataType in TDengine and Java - -The datatypes in TDengine include timestamp, number, string and boolean, which are converted as follows in Java: - -| TDengine | Java | -| --- | --- | -| TIMESTAMP | java.sql.Timestamp | -| INT | java.lang.Integer | -| BIGINT | java.lang.Long | -| FLOAT | java.lang.Float | -| DOUBLE | java.lang.Double | -| SMALLINT, TINYINT |java.lang.Short | -| BOOL | java.lang.Boolean | -| BINARY, NCHAR | java.lang.String | - -## How to get TAOS-JDBC Driver - -### maven repository - -taos-jdbcdriver has been published to [Sonatype Repository][1]: -* [sonatype][8] -* [mvnrepository][9] -* [maven.aliyun][10] - -Using the following pom.xml for maven projects - -```xml - - - com.taosdata.jdbc - taos-jdbcdriver - 1.0.3 - - -``` - -### JAR file from the source code - -After downloading the [TDengine][3] source code, execute `mvn clean package` in the directory `src/connector/jdbc` and then the corresponding jar file is generated. - -## Usage - -### get the connection - -```java -Class.forName("com.taosdata.jdbc.TSDBDriver"); -String jdbcUrl = "jdbc:TAOS://127.0.0.1:6030/log?user=root&password=taosdata"; -Connection conn = DriverManager.getConnection(jdbcUrl); -``` -> `6030` is the default port and `log` is the default database for system monitor. - -A normal JDBC URL looks as follows: -`jdbc:TAOS://{host_ip}:{port}/[database_name]?[user={user}|&password={password}|&charset={charset}|&cfgdir={config_dir}|&locale={locale}|&timezone={timezone}]` - -values in `{}` are necessary while values in `[]` are optional。Each option in the above URL denotes: - -* user：user name for login, defaultly root。 -* password：password for login，defaultly taosdata。 -* charset：charset for client，defaultly system charset -* cfgdir：log directory for client, defaultly _/etc/taos/_ on Linux and _C:/TDengine/cfg_ on Windows。 -* locale：language for client，defaultly system locale。 -* timezone：timezone for client，defaultly system timezone。 - -The options above can be configures (`ordered by priority`): -1. JDBC URL - - As explained above. -2. java.sql.DriverManager.getConnection(String jdbcUrl, Properties connProps) -```java -public Connection getConn() throws Exception{ - Class.forName("com.taosdata.jdbc.TSDBDriver"); - String jdbcUrl = "jdbc:TAOS://127.0.0.1:0/log?user=root&password=taosdata"; - Properties connProps = new Properties(); - connProps.setProperty(TSDBDriver.PROPERTY_KEY_USER, "root"); - connProps.setProperty(TSDBDriver.PROPERTY_KEY_PASSWORD, "taosdata"); - connProps.setProperty(TSDBDriver.PROPERTY_KEY_CONFIG_DIR, "/etc/taos"); - 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; -} -``` - -3. Configuration file (taos.cfg) - - Default configuration file is _/var/lib/taos/taos.cfg_ On Linux and _C:\TDengine\cfg\taos.cfg_ on Windows -```properties -# client default username -# defaultUser root - -# client default password -# defaultPass taosdata - -# default system charset -# charset UTF-8 - -# system locale -# locale en_US.UTF-8 -``` -> More options can refer to [client configuration][13] - -### Create databases and tables - -```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)"); -``` -> Note: if no step like `use db`, the name of database must be added as prefix like _db.tb_ when operating on tables - -### Insert data - -```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_ is the server time. -> _now+1s_ is 1 second later than current server time. The time unit includes: _a_(millisecond), _s_(second), _m_(minute), _h_(hour), _d_(day), _w_(week), _n_(month), _y_(year). - -### Query database - -```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); -} -``` -> query is consistent with relational database. The subscript start with 1 when retrieving return results. It is recommended to use the column name to retrieve results. - -### Close all - -```java -resultSet.close(); -stmt.close(); -conn.close(); -``` -> `please make sure the connection is closed to avoid the error like connection leakage` - -## Using connection pool - -**HikariCP** - -* dependence in pom.xml： -```xml - - com.zaxxer - HikariCP - 3.4.1 - -``` - -* Examples： -```java - public static void main(String[] args) throws SQLException { - HikariConfig config = new HikariConfig(); - config.setJdbcUrl("jdbc:TAOS://127.0.0.1:6030/log"); - config.setUsername("root"); - config.setPassword("taosdata"); - - config.setMinimumIdle(3); //minimum number of idle connection - config.setMaximumPoolSize(10); //maximum number of connection in the pool - config.setConnectionTimeout(10000); //maximum wait milliseconds for get connection from pool - config.setIdleTimeout(60000); // max idle time for recycle idle connection - config.setConnectionTestQuery("describe log.dn"); //validation query - config.setValidationTimeout(3000); //validation query timeout - - 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 -} -``` -> The close() method will not close the connection from HikariDataSource.getConnection(). Instead, the connection is put back to the connection pool. -> More instructions can refer to [User Guide][5] - -**Druid** - -* dependency in pom.xml： - -```xml - - com.alibaba - druid - 1.1.20 - -``` - -* Examples： -```java -public static void main(String[] args) throws Exception { - Properties properties = new Properties(); - properties.put("driverClassName","com.taosdata.jdbc.TSDBDriver"); - properties.put("url","jdbc:TAOS://127.0.0.1:6030/log"); - properties.put("username","root"); - properties.put("password","taosdata"); - - properties.put("maxActive","10"); //maximum number of connection in the pool - properties.put("initialSize","3");//initial number of connection - properties.put("maxWait","10000");//maximum wait milliseconds for get connection from pool - properties.put("minIdle","3");//minimum number of connection in the pool - - properties.put("timeBetweenEvictionRunsMillis","3000");// the interval milliseconds to test connection - - properties.put("minEvictableIdleTimeMillis","60000");//the minimum milliseconds to keep idle - properties.put("maxEvictableIdleTimeMillis","90000");//the maximum milliseconds to keep idle - - properties.put("validationQuery","describe log.dn"); //validation query - properties.put("testWhileIdle","true"); // test connection while idle - properties.put("testOnBorrow","false"); // don't need while testWhileIdle is true - properties.put("testOnReturn","false"); // don't need while testWhileIdle is true - - //create druid datasource - DataSource ds = DruidDataSourceFactory.createDataSource(properties); - Connection connection = ds.getConnection(); // get connection - Statement statement = connection.createStatement(); // get statement - - //query or insert - // ... - - connection.close(); // put back to conneciton pool -} -``` -> More instructions can refer to [User Guide][6] - -**Notice** -* TDengine `v1.6.4.1` provides a function `select server_status()` to check heartbeat. It is highly recommended to use this function for `Validation Query`. - -As follows，`1` will be returned if `select server_status()` is successfully executed。 -```shell -taos> select server_status(); -server_status()| -================ -1 | -Query OK, 1 row(s) in set (0.000141s) -``` - -## Integrated with framework - -* Please refer to [SpringJdbcTemplate][11] if using taos-jdbcdriver in Spring JdbcTemplate -* Please refer to [springbootdemo][12] if using taos-jdbcdriver in Spring JdbcTemplate - -## FAQ - -* java.lang.UnsatisfiedLinkError: no taos in java.library.path - - **Cause**：The application program cannot find Library function _taos_ - - **Answer**：Copy `C:\TDengine\driver\taos.dll` to `C:\Windows\System32\` on Windows and make a soft link through ` ln -s /usr/local/taos/driver/libtaos.so.x.x.x.x /usr/lib/libtaos.so` on Linux. - -* java.lang.UnsatisfiedLinkError: taos.dll Can't load AMD 64 bit on a IA 32-bit platform - - **Cause**：Currently TDengine only support 64bit JDK - - **Answer**：re-install 64bit JDK. - -* For other questions, please refer to [Issues][7] - - -## Python Connector - -### Pre-requirement -* TDengine installed, TDengine-client installed if on Windows [(Windows TDengine client installation)](https://www.taosdata.com/cn/documentation/connector/#Windows客户端及程序接口) -* python 2.7 or >= 3.4 -* pip installed - -### Installation -#### Linux - -Users can find python client packages in our source code directory _src/connector/python_. There are two directories corresponding to two python versions. Please choose the correct package to install. Users can use _pip_ command to install: - -```cmd -pip install src/connector/python/linux/python3/ -``` - -or - -``` -pip install src/connector/python/linux/python2/ -``` -#### Windows -Assumed the Windows TDengine client has been installed , copy the file "C:\TDengine\driver\taos.dll" to the folder "C:\windows\system32", and then enter the _cmd_ Windows command interface -``` -cd C:\TDengine\connector\python\windows -pip install python3\ -``` -or -``` -cd C:\TDengine\connector\python\windows -pip install python2\ -``` -*If _pip_ command is not installed on the system, users can choose to install pip or just copy the _taos_ directory in the python client directory to the application directory to use. - -### Usage -#### Examples -* import TDengine module - -```python -import taos -``` -* get the connection -```python -conn = taos.connect(host="127.0.0.1", user="root", password="taosdata", config="/etc/taos") -c1 = conn.cursor() -``` -*host is the IP of TDengine server, and config is the directory where exists the TDengine client configure file -* insert records into the database -```python -import datetime - -# create a database -c1.execute('create database db') -c1.execute('use db') -# create a table -c1.execute('create table tb (ts timestamp, temperature int, humidity float)') -# insert a record -start_time = datetime.datetime(2019, 11, 1) -affected_rows = c1.execute('insert into tb values (\'%s\', 0, 0.0)' %start_time) -# insert multiple records in a batch -time_interval = datetime.timedelta(seconds=60) -sqlcmd = ['insert into tb values'] -for irow in range(1,11): - start_time += time_interval - sqlcmd.append('(\'%s\', %d, %f)' %(start_time, irow, irow*1.2)) -affected_rows = c1.execute(' '.join(sqlcmd)) -``` -* query the database -```python -c1.execute('select * from tb') -# fetch all returned results -data = c1.fetchall() -# data is a list of returned rows with each row being a tuple -numOfRows = c1.rowcount -numOfCols = len(c1.description) -for irow in range(numOfRows): - print("Row%d: ts=%s, temperature=%d, humidity=%f" %(irow, data[irow][0], data[irow][1],data[irow][2])) - -# use the cursor as an iterator to retrieve all returned results -c1.execute('select * from tb') -for data in c1: - print("ts=%s, temperature=%d, humidity=%f" %(data[0], data[1],data[2]) -``` - -* create a subscription -```python -# Create a subscription with topic 'test' and consumption interval 1000ms. -# The first argument is True means to restart the subscription; -# if the subscription with topic 'test' has already been created, then pass -# False to this argument means to continue the existing subscription. -sub = conn.subscribe(True, "test", "select * from meters;", 1000) -``` - -* consume a subscription -```python -data = sub.consume() -for d in data: - print(d) -``` - -* close the subscription -```python -sub.close() -``` - -* close the connection -```python -c1.close() -conn.close() -``` -#### Help information - -Users can get module information from Python help interface or refer to our [python code example](). We list the main classes and methods below: - -- _TDengineConnection_ class - - Run `help(taos.TDengineConnection)` in python terminal for details. - -- _TDengineCursor_ class - - Run `help(taos.TDengineCursor)` in python terminal for details. - -- connect method - - Open a connection. Run `help(taos.connect)` in python terminal for details. - -## RESTful Connector - -TDengine also provides RESTful API to satisfy developing on different platforms. Unlike other databases, TDengine RESTful API applies operations to the database through the SQL command in the body of HTTP POST request. What users are required to provide is just a URL. - - -For the time being, TDengine RESTful API uses a _\_ generated from username and password for identification. Safer identification methods will be provided in the future. - - -### HTTP URL encoding - -To use TDengine RESTful API, the URL should have the following encoding format: -``` -http://:/rest/sql -``` -- _ip_: IP address of any node in a TDengine cluster -- _PORT_: TDengine HTTP service port. It is 6020 by default. - -For example, the URL encoding _http://192.168.0.1:6020/rest/sql_ used to send HTTP request to a TDengine server with IP address as 192.168.0.1. - -It is required to add a token in an HTTP request header for identification. - -``` -Authorization: Basic -``` - -The HTTP request body contains the SQL command to run. If the SQL command contains a table name, it should also provide the database name it belongs to in the form of `.`. Otherwise, an error code is returned. - -For example, use _curl_ command to send a HTTP request: - -``` -curl -H 'Authorization: Basic ' -d '' :/rest/sql -``` - -or use - -``` -curl -u username:password -d '' :/rest/sql -``` - -where `TOKEN` is the encryted string of `{username}:{password}` using the Base64 algorithm, e.g. `root:taosdata` will be encoded as `cm9vdDp0YW9zZGF0YQ==` - -### HTTP response - -The HTTP resonse is in JSON format as below: - -``` -{ - "status": "succ", - "head": ["column1","column2", …], - "data": [ - ["2017-12-12 23:44:25.730", 1], - ["2017-12-12 22:44:25.728", 4] - ], - "rows": 2 -} -``` -Specifically, -- _status_: the result of the operation, success or failure -- _head_: description of returned result columns -- _data_: the returned data array. If no data is returned, only an _affected_rows_ field is listed -- _rows_: the number of rows returned - -### Example - -- Use _curl_ command to query all the data in table _t1_ of database _demo_: - - `curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.t1' 192.168.0.1:6020/rest/sql` - -The return value is like: - -``` -{ - "status": "succ", - "head": ["column1","column2","column3"], - "data": [ - ["2017-12-12 23:44:25.730", 1, 2.3], - ["2017-12-12 22:44:25.728", 4, 5.6] - ], - "rows": 2 -} -``` - -- Use HTTP to create a database： - - `curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'create database demo' 192.168.0.1:6020/rest/sql` - - The return value should be: - -``` -{ - "status": "succ", - "head": ["affected_rows"], - "data": [[1]], - "rows": 1, -} -``` - -## Go Connector - -TDengine also provides a Go client package named _taosSql_ for users to access TDengine with Go. The package is in _/usr/local/taos/connector/go/src/taosSql_ by default if you installed TDengine. Users can copy the directory _/usr/local/taos/connector/go/src/taosSql_ to the _src_ directory of your project and import the package in the source code for use. - -```Go -import ( - "database/sql" - _ "taosSql" -) -``` - -The _taosSql_ package is in _cgo_ form, which calls TDengine C/C++ sync interfaces. So a connection is allowed to be used by one thread at the same time. Users can open multiple connections for multi-thread operations. - -Please refer the the demo code in the package for more information. - -## Node.js Connector - -TDengine also provides a node.js connector package that is installable through [npm](https://www.npmjs.com/). The package is also in our source code at *src/connector/nodejs/*. The following instructions are also available [here](https://github.com/taosdata/tdengine/tree/master/src/connector/nodejs) - -To get started, just type in the following to install the connector through [npm](https://www.npmjs.com/). - -```cmd -npm install td-connector -``` - -It is highly suggested you use npm. If you don't have it installed, you can also just copy the nodejs folder from *src/connector/nodejs/* into your node project folder. - -To interact with TDengine, we make use of the [node-gyp](https://github.com/nodejs/node-gyp) library. To install, you will need to install the following depending on platform (the following instructions are quoted from node-gyp) - -### On Unix - -- `python` (`v2.7` recommended, `v3.x.x` is **not** supported) -- `make` -- A proper C/C++ compiler toolchain, like [GCC](https://gcc.gnu.org) - -### On macOS - -- `python` (`v2.7` recommended, `v3.x.x` is **not** supported) (already installed on macOS) - -- Xcode - - - You also need to install the - - ``` - Command Line Tools - ``` - - via Xcode. You can find this under the menu - - ``` - Xcode -> Preferences -> Locations - ``` - - (or by running - - ``` - xcode-select --install - ``` - - in your Terminal) - - - This step will install `gcc` and the related toolchain containing `make` - -### On Windows - -#### Option 1 - -Install all the required tools and configurations using Microsoft's [windows-build-tools](https://github.com/felixrieseberg/windows-build-tools) using `npm install --global --production windows-build-tools` from an elevated PowerShell or CMD.exe (run as Administrator). - -#### Option 2 - -Install tools and configuration manually: - -- Install Visual C++ Build Environment: [Visual Studio Build Tools](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=BuildTools) (using "Visual C++ build tools" workload) or [Visual Studio 2017 Community](https://visualstudio.microsoft.com/pl/thank-you-downloading-visual-studio/?sku=Community) (using the "Desktop development with C++" workload) -- Install [Python 2.7](https://www.python.org/downloads/) (`v3.x.x` is not supported), and run `npm config set python python2.7` (or see below for further instructions on specifying the proper Python version and path.) -- Launch cmd, `npm config set msvs_version 2017` - -If the above steps didn't work for you, please visit [Microsoft's Node.js Guidelines for Windows](https://github.com/Microsoft/nodejs-guidelines/blob/master/windows-environment.md#compiling-native-addon-modules) for additional tips. - -To target native ARM64 Node.js on Windows 10 on ARM, add the components "Visual C++ compilers and libraries for ARM64" and "Visual C++ ATL for ARM64". - -### Usage - -The following is a short summary of the basic usage of the connector, the full api and documentation can be found [here](http://docs.taosdata.com/node) - -#### Connection - -To use the connector, first require the library ```td-connector```. Running the function ```taos.connect``` with the connection options passed in as an object will return a TDengine connection object. The required connection option is ```host```, other options if not set, will be the default values as shown below. - -A cursor also needs to be initialized in order to interact with TDengine from Node.js. - -```javascript -const taos = require('td-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 -``` - -To close a connection, run - -```javascript -conn.close(); -``` - -#### Queries - -We can now start executing simple queries through the ```cursor.query``` function, which returns a TaosQuery object. - -```javascript -var query = cursor.query('show databases;') -``` - -We can get the results of the queries through the ```query.execute()``` function, which returns a promise that resolves with a TaosResult object, which contains the raw data and additional functionalities such as pretty printing the results. - -```javascript -var promise = query.execute(); -promise.then(function(result) { - result.pretty(); //logs the results to the console as if you were in the taos shell -}); -``` - -You can also query by binding parameters to a query by filling in the question marks in a string as so. The query will automatically parse what was binded and convert it to the proper format for use with TDengine - -```javascript -var query = cursor.query('select * from meterinfo.meters where ts <= ? and areaid = ?;').bind(new Date(), 5); -query.execute().then(function(result) { - result.pretty(); -}) -``` - -The TaosQuery object can also be immediately executed upon creation by passing true as the second argument, returning a promise instead of a TaosQuery. - -```javascript -var promise = cursor.query('select * from meterinfo.meters where v1 = 30;', true) -promise.then(function(result) { - result.pretty(); -}) -``` -#### Async functionality - -Async queries can be performed using the same functions such as `cursor.execute`, `TaosQuery.execute`, but now with `_a` appended to them. - -Say you want to execute an two async query on two seperate tables, using `cursor.query`, you can do that and get a TaosQuery object, which upon executing with the `execute_a` function, returns a promise that resolves with a TaosResult object. - -```javascript -var promise1 = cursor.query('select count(*), avg(v1), avg(v2) from meter1;').execute_a() -var promise2 = cursor.query('select count(*), avg(v1), avg(v2) from meter2;').execute_a(); -promise1.then(function(result) { - result.pretty(); -}) -promise2.then(function(result) { - result.pretty(); -}) -``` - - -### Example - -An example of using the NodeJS connector to create a table with weather data and create and execute queries can be found [here](https://github.com/taosdata/TDengine/tree/master/tests/examples/nodejs/node-example.js) (The preferred method for using the connector) - -An example of using the NodeJS connector to achieve the same things but without all the object wrappers that wrap around the data returned to achieve higher functionality can be found [here](https://github.com/taosdata/TDengine/tree/master/tests/examples/nodejs/node-example-raw.js) - -[1]: https://search.maven.org/artifact/com.taosdata.jdbc/taos-jdbcdriver -[2]: https://mvnrepository.com/artifact/com.taosdata.jdbc/taos-jdbcdriver -[3]: https://github.com/taosdata/TDengine -[4]: https://www.taosdata.com/blog/2019/12/03/jdbcdriver%e6%89%be%e4%b8%8d%e5%88%b0%e5%8a%a8%e6%80%81%e9%93%be%e6%8e%a5%e5%ba%93/ -[5]: https://github.com/brettwooldridge/HikariCP -[6]: https://github.com/alibaba/druid -[7]: https://github.com/taosdata/TDengine/issues -[8]: https://search.maven.org/artifact/com.taosdata.jdbc/taos-jdbcdriver -[9]: https://mvnrepository.com/artifact/com.taosdata.jdbc/taos-jdbcdriver -[10]: https://maven.aliyun.com/mvn/search -[11]: https://github.com/taosdata/TDengine/tree/develop/tests/examples/JDBC/SpringJdbcTemplate -[12]: https://github.com/taosdata/TDengine/tree/develop/tests/examples/JDBC/springbootdemo -[13]: https://www.taosdata.com/cn/documentation/administrator/#%E5%AE%A2%E6%88%B7%E7%AB%AF%E9%85%8D%E7%BD%AE -[14]: https://www.taosdata.com/cn/documentation/connector/#Windows%E5%AE%A2%E6%88%B7%E7%AB%AF%E5%8F%8A%E7%A8%8B%E5%BA%8F%E6%8E%A5%E5%8F%A3 -[15]: https://www.taosdata.com/cn/getting-started/#%E5%BF%AB%E9%80%9F%E4%B8%8A%E6%89%8B diff --git a/documentation/webdocs/markdowndocs/Contributor_License_Agreement.md b/documentation/webdocs/markdowndocs/Contributor_License_Agreement.md deleted file mode 100644 index 8c158da4c5958384064b9993de6643be86b94fee..0000000000000000000000000000000000000000 --- a/documentation/webdocs/markdowndocs/Contributor_License_Agreement.md +++ /dev/null @@ -1,35 +0,0 @@ -# TaosData Contributor License Agreement - -This TaosData Contributor License Agreement (CLA) applies to any contribution you make to any TaosData projects. If you are representing your employing organization to sign this agreement, please warrant that you have the authority to grant the agreement. - -## Terms - -**"TaosData"**, **"we"**, **"our"** and **"us"** means TaosData, inc. - -**"You"** and **"your"** means you or the organization you are on behalf of to sign this agreement. - -**"Contribution"** means any original work you, or the organization you represent submit to TaosData for any project in any manner. - -## Copyright License - -All rights of your Contribution submitted to TaosData in any manner are granted to TaosData and recipients of software distributed by TaosData. You waive any rights that my affect our ownership of the copyright and grant to us a perpetual, worldwide, transferable, non-exclusive, no-charge, royalty-free, irrevocable, and sublicensable license to use, reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute Contributions and any derivative work created based on a Contribution. - -## Patent License - -With respect to any patents you own or that you can license without payment to any third party, you grant to us and to any recipient of software distributed by us, a perpetual, worldwide, transferable, non-exclusive, no-charge, royalty-free, irrevocable patent license to make, have make, use, sell, offer to sell, import, and otherwise transfer the Contribution in whole or in part, alone or included in any product under any patent you own, or license from a third party, that is necessarily infringed by the Contribution or by combination of the Contribution with any Work. - -## Your Representations and Warranties - -You represent and warrant that: - -- the Contribution you submit is an original work that you can legally grant the rights set out in this agreement. - -- the Contribution you submit and licenses you granted does not and will not, infringe the rights of any third party. - -- you are not aware of any pending or threatened claims, suits, actions, or charges pertaining to the contributions. You also warrant to notify TaosData immediately if you become aware of any such actual or potential claims, suits, actions, allegations or charges. - -## Support - -You are not obligated to support your Contribution except you volunteer to provide support. If you want, you can provide for a fee. - -**I agree and accept on behalf of myself and behalf of my organization:** \ No newline at end of file diff --git a/documentation/webdocs/markdowndocs/Data model and architecture-ch.md b/documentation/webdocs/markdowndocs/Data model and architecture-ch.md deleted file mode 100644 index f17b015172095be051d6fe78c47db458ca2c797f..0000000000000000000000000000000000000000 --- a/documentation/webdocs/markdowndocs/Data model and architecture-ch.md +++ /dev/null @@ -1,100 +0,0 @@ -# 数据模型和设计 - -## 数据模型 - -### 物联网典型场景 - -在典型的物联网、车联网、运维监测场景中，往往有多种不同类型的数据采集设备，采集一个到多个不同的物理量。而同一种采集设备类型，往往又有多个具体的采集设备分布在不同的地点。大数据处理系统就是要将各种采集的数据汇总，然后进行计算和分析。对于同一类设备，其采集的数据类似如下的表格： - -| Device ID | Time Stamp | Value 1 | Value 2 | Value 3 | Tag 1 | Tag 2 | -| :-------: | :-----------: | :-----: | :-----: | :-----: | :---: | :---: | -| D1001 | 1538548685000 | 10.3 | 219 | 0.31 | Red | Tesla | -| D1002 | 1538548684000 | 10.2 | 220 | 0.23 | Blue | BMW | -| D1003 | 1538548686500 | 11.5 | 221 | 0.35 | Black | Honda | -| D1004 | 1538548685500 | 13.4 | 223 | 0.29 | Red | Volvo | -| D1001 | 1538548695000 | 12.6 | 218 | 0.33 | Red | Tesla | -| D1004 | 1538548696600 | 11.8 | 221 | 0.28 | Black | Honda | - -每一条记录都有设备ID，时间戳，采集的物理量，还有与每个设备相关的静态标签。每个设备是受外界的触发，或按照设定的周期采集数据。采集的数据点是时序的，是一个数据流。 - -### 数据特征 - -除时序特征外，仔细研究发现，物联网、车联网、运维监测类数据还具有很多其他明显的特征。 - -1. 数据是结构化的； -2. 数据极少有更新或删除操作； -3. 无需传统数据库的事务处理； -4. 相对互联网应用，写多读少； -5. 流量平稳，根据设备数量和采集频次，可以预测出来； -6. 用户关注的是一段时间的趋势，而不是某一特点时间点的值； -7. 数据是有保留期限的； -8. 数据的查询分析一定是基于时间段和地理区域的； -9. 除存储查询外，还往往需要各种统计和实时计算操作； -10. 数据量巨大，一天采集的数据就可以超过100亿条。 - -充分利用上述特征，TDengine采取了一特殊的优化的存储和计算设计来处理时序数据，能将系统处理能力显著提高。 - -### 关系型数据库模型 - -因为采集的数据一般是结构化数据，而且为降低学习门槛，TDengine采用传统的关系型数据库模型管理数据。因此用户需要先创建库，然后创建表，之后才能插入或查询数据。 - -### 一个设备一张表 - -为充分利用其数据的时序性和其他数据特点，TDengine要求**对每个数据采集点单独建表**（比如有一千万个智能电表，就需创建一千万张表，上述表格中的D1001, D1002, D1003, D1004都需单独建表），用来存储这个采集点所采集的时序数据。这种设计能保证一个采集点的数据在存储介质上是一块一块连续的，大幅减少随机读取操作，成数量级的提升读取和查询速度。而且由于不同数据采集设备产生数据的过程完全独立，每个设备只产生属于自己的数据，一张表也就只有一个写入者。这样每个表就可以采用无锁方式来写，写入速度就能大幅提升。同时，对于一个数据采集点而言，其产生的数据是时序的，因此写的操作可用追加的方式实现，进一步大幅提高数据写入速度。 - -### 数据建模最佳实践 - -**表(Table)**：TDengine 建议用数据采集点的名字(如上表中的D1001)来做表名。每个数据采集点可能同时采集多个物理量(如上表中的value1, value2, value3)，每个物理量对应一张表中的一列，数据类型可以是整型、浮点型、字符串等。除此之外，表的第一列必须是时间戳，即数据类型为 timestamp。有的设备有多组采集量，每一组的采集频次是不一样的，这是需要对同一个设备建多张表。对采集的数据，TDengine将自动按照时间戳建立索引，但对采集的物理量不建任何索引。数据是用列式存储方式保存。 - -**超级表(Super Table)**：对于同一类型的采集点，为保证Schema的一致性，而且为便于聚合统计操作，可以先定义超级表STable(详见第10章)，然后再定义表。每个采集点往往还有静态标签信息(如上表中的Tag 1, Tag 2)，比如设备型号、颜色等，这些静态信息不会保存在存储采集数据的数据节点中，而是通过超级表保存在元数据节点中。这些静态标签信息将作为过滤条件，用于采集点之间的数据聚合统计操作。 - -**库(DataBase)**：不同的数据采集点往往具有不同的数据特征，包括数据采集频率高低，数据保留时间长短，备份数目，单个字段大小等等。为让各种场景下TDengine都能最大效率的工作，TDengine建议将不同数据特征的表创建在不同的库里。创建一个库时，除SQL标准的选项外，应用还可以指定保留时长、数据备份的份数、cache大小、文件块大小、是否压缩等多种参数(详见第19章)。 - -**Schemaless vs Schema**: 与NoSQL的各种引擎相比，由于应用需要定义schema，插入数据的灵活性降低。但对于物联网、金融这些典型的时序数据场景，schema会很少变更，因此这个灵活性不够的设计就不成问题。相反，TDengine采用结构化数据来进行处理的方式将让查询、分析的性能成数量级的提升。 - -TDengine对库的数量、超级表的数量以及表的数量没有做任何限制，而且其多少不会对性能产生影响，应用按照自己的场景创建即可。 - -## 主要模块 -如图所示，TDengine服务主要包含两大模块：**管理节点模块(MGMT)** 和 **数据节点模块(DNODE)**。整个TDengine还包含**客户端模块**。 - -
    -
    图 1 TDengine架构示意图
    - -### 管理节点模块 -管理节点模块主要负责元数据的存储和查询等工作，其中包括用户信息的管理、数据库和表信息的创建、删除以及查询等。应用连接TDengine时会首先连接到管理节点。在创建/删除数据库和表时，请求也会首先发送请求到管理节点模块。由管理节点模块首先创建/删除元数据信息，然后发送请求到数据节点模块进行分配/删除所需要的资源。在数据写入和查询时，应用同样会首先访问管理节点模块，获取元数据信息。然后根据元数据管理信息访问数据节点模块。 - -### 数据节点模块 -写入数据的存储和查询工作是由数据节点模块负责。 为了更高效地利用资源，以及方便将来进行水平扩展，TDengine内部对数据节点进行了虚拟化，引入了虚拟节点(virtual node, 简称vnode）的概念，作为存储、资源分配以及数据备份的单元。如图2所示，在一个dnode上，通过虚拟化，可以将该dnode视为多个虚拟节点的集合。 - -创建一个库时，系统会自动分配vnode。每个vnode存储一定数量的表中的数据，但一个表只会存在于一个vnode里，不会跨vnode。一个vnode只会属于一个库，但一个库会有一到多个vnode。不同的vnode之间资源互不共享。每个虚拟节点都有自己的缓存，在硬盘上也有自己的存储目录。而同一vnode内部无论是缓存还是硬盘的存储都是共享的。通过虚拟化，TDengine可以将dnode上有限的物理资源合理地分配给不同的vnode，大大提高资源的利用率和并发度。一台物理机器上的虚拟节点个数可以根据其硬件资源进行配置。 - -
    -
    图 2 TDengine虚拟化
    - -### 客户端模块 -TDengine客户端模块主要负责将应用传来的请求（SQL语句）进行解析，转化为内部结构体再发送到服务端。TDengine的各种接口都是基于TDengine的客户端模块进行开发的。客户端模块与管理模块使用TCP/UDP通讯，端口号由系统参数mgmtShellPort配置, 缺省值为6030。客户端与数据节点模块也是使用TCP/UDP通讯，端口号由系统参数vnodeShellPort配置, 缺省值为6035。两个端口号均可通过系统配置文件taos.cfg进行个性化设置。 - -## 写入流程 -TDengine的完整写入流程如图3所示。为了保证写入数据的安全性和完整性，TDengine在写入数据时采用[预写日志算法]。客户端发来的数据在经过验证以后，首先会写入预写日志中，以保证TDengine能够在断电等因素导致的服务重启时从预写日志中恢复数据，避免数据的丢失。写入预写日志后，数据会被写到对应的vnode的缓存中。随后，服务端会发送确认信息给客户端表示写入成功。TDengine中存在两种机制可以促使缓存中的数据写入到硬盘上进行持久化存储： - -
    -
    图 3 TDengine写入流程
    - -1. **时间驱动的落盘**：TDengine服务会定时将vnode缓存中的数据写入到硬盘上，默认为一个小时落一次盘。落盘间隔可在配置文件taos.cfg中通过参数commitTime配置。 -2. **数据驱动的落盘**：当vnode中缓存的数据达到一定规模时，为了不阻塞后续数据的写入，TDengine也会拉起落盘线程将缓存中的数据清空。数据驱动的落盘会刷新定时落盘的时间。 - -TDengine在数据落盘时会打开新的预写日志文件，在落盘后则会删除老的预写日志文件，避免日志文件无限制的增长。TDengine对缓存按照先进先出的原则进行管理，以保证每个表的最新数据都在缓存中。 - -## 数据存储 - -TDengine将所有数据存储在/var/lib/taos/目录下，您可以通过系统配置参数dataDir进行个性化配置。 - -TDengine中的元数据信息包括TDengine中的数据库、表、用户等信息。每个超级表、以及每个表的标签数据也存放在这里。为提高访问速度，元数据全部有缓存。 - -TDengine中写入的数据在硬盘上是按时间维度进行分片的。同一个vnode中的表在同一时间范围内的数据都存放在同一文件组中。这一数据分片方式可以大大简化数据在时间维度的查询，提高查询速度。在默认配置下，硬盘上的每个数据文件存放10天数据。用户可根据需要修改系统配置参数daysPerFile进行个性化配置。 - -表中的数据都有保存时间，一旦超过保存时间（缺省是3650天），数据将被系统自动删除。您可以通过系统配置参数daysToKeep进行个性化设置。 - -数据在文件中是按块存储的。每个数据块只包含一张表的数据，且数据是按照时间主键递增排列的。数据在数据块中按列存储，这样使得同列的数据存放在一起，对于不同的数据类型还采用不同的压缩方法，大大提高压缩的比例，节省存储空间。 - -数据文件总共有三类文件，一类是data文件，它存放了真实的数据块，该文件只进行追加操作；一类文件是head文件, 它存放了其对应的data文件中数据块的索引信息；第三类是last文件，专门存储最后写入的数据，每次落盘操作时，这部分数据会与内存里的数据合并，并决定是否写入data文件还是last文件。 \ No newline at end of file diff --git a/documentation/webdocs/markdowndocs/Data model and architecture.md b/documentation/webdocs/markdowndocs/Data model and architecture.md deleted file mode 100644 index 1cf503f3c1694b65d4e181a8439e96d1735f8c56..0000000000000000000000000000000000000000 --- a/documentation/webdocs/markdowndocs/Data model and architecture.md +++ /dev/null @@ -1,101 +0,0 @@ -# Data Model and Architecture -## Data Model - -### A Typical IoT Scenario - -In a typical IoT scenario, there are many types of devices. Each device is collecting one or multiple metrics. For a specific type of device, the collected data could look like the table below: - -| Device ID | Time Stamp | Value 1 | Value 2 | Value 3 | Tag 1 | Tag 2 | -| :-------: | :-----------: | :-----: | :-----: | :-----: | :---: | :---: | -| D1001 | 1538548685000 | 10.3 | 219 | 0.31 | Red | Tesla | -| D1002 | 1538548684000 | 10.2 | 220 | 0.23 | Blue | BMW | -| D1003 | 1538548686500 | 11.5 | 221 | 0.35 | Black | Honda | -| D1004 | 1538548685500 | 13.4 | 223 | 0.29 | Red | Volvo | -| D1001 | 1538548695000 | 12.6 | 218 | 0.33 | Red | Tesla | -| D1004 | 1538548696600 | 11.8 | 221 | 0.28 | Black | Honda | - -Each data record contains the device ID, timestamp, collected metrics, and static tags associated with the device. Each device generates a data record in a pre-defined timer or triggered by an event. It is a sequence of data points like a stream. - -### Data Characteristics - -As the data points are a series of data points over time, the data points generated by devices, sensors, servers, and/or applications have some strong common characteristics: - -1. metrics are always structured data; -2. there are rarely delete/update operations on collected data; -3. there is only one single data source for one device or sensor; -4. ratio of read/write is much lower than typical Internet applications; -5. the user pays attention to the trend of data, not a specific value at a specific time; -6. there is always a data retention policy; -7. the data query is always executed in a given time range and a subset of devices; -8. real-time aggregation or analytics is mandatory; -9. traffic is predictable based on the number of devices and sampling frequency; -10. data volume is huge, a system may generate 10 billion data points in a day. - -By utilizing the above characteristics, TDengine designs the storage and computing engine in a special and optimized way for time-series data, resulting in massive improvements in system efficiency. - -### Relational Database Model - -Since time-series data is most likely to be structured data, TDengine adopts the traditional relational database model to process them. You need to create a database, create tables with schema definitions, then insert data points and execute queries to explore the data. Standard SQL is used, making it easy for anyone to get started and eliminating any learning curve. - -### One Table for One Device - -Due to different network latencies, the data points from different devices may arrive to the server out of order. But for the same device, data points will arrive to the server in order if the system is designed well. To utilize this special feature, TDengine requires the user to create a table for each device (time-stream). For example, if there are over 10,000 smart meters, 10,000 tables shall be created. For the table above, 4 tables shall be created for device D1001, D1002, D1003, and D1004 to store the data collected. - -This strong requirement can guarantee that all data points from a device can be saved in a continuous memory/hard disk space block by block. If queries are applied only on one device in a time range, this design will reduce the read latency significantly since a whole block is owned by one single device. Additionally, write latency can be significantly reduced too as the data points generated by the same device will arrive in order, the new data point will be simply appended to a block. Cache block size and the rows of records in a file block can be configured to fit different scenarios for optimal efficiency. - -### Best Practices - -**Table**: TDengine suggests to use device ID as the table name (like D1001 in the above diagram). Each device may collect one or more metrics (like value1, value2, value3 in the diagram). Each metric has a column in the table, the metric name can be used as the column name. The data type for a column can be int, float, double, tinyint, bigint, bool or binary. Sometimes, a device may have multiple metric groups, each group containing different sampling periods, so for best practice you should create a table for each group for each device. The first column in the table must be a time stamp. TDengine uses the time stamp as the index, and won’t build the index on any metrics stored. - -**Tags:** To support aggregation over multiple tables efficiently, the [STable(Super Table)](../super-table) concept is introduced by TDengine. A STable is used to represent the same type of device. The schema is used to define the collected metrics (like value1, value2, value3 in the diagram), and tags are used to define the static attributes for each table or device (like tag1, tag2 in the diagram). A table is created via STable with a specific tag value. All or a subset of tables in a STable can be aggregated by filtering tag values. - -**Database:** Different types of devices may generate data points in different patterns and should be processed differently. For example, sampling frequency, data retention policy, replication number, cache size, record size, the compression algorithm may be different. To make the system more efficient, TDengine suggests creating a different database with unique configurations for different scenarios. - -**Schemaless vs Schema:** Compared with NoSQL databases, since a table with schema definitions must be created before the data points can be inserted, flexibilities are not that good, especially when the schema is changed. But in most IoT scenarios, the schema is well defined and is rarely changed, the loss of flexibility won't pose any impact to developers or administrators. TDengine allows the application to change the schema in a second even there is a huge amount of historical data when schema has to be changed. - -TDengine does not impose a limitation on the number of tables, [STables](../super-table), or databases. You can create any number of STable or databases to fit different scenarios. - -## Architecture - -There are two main modules in TDengine server as shown in Picture 1: **Management Module (MGMT)** and **Data Module(DNODE)**. The whole TDengine architecture also includes a **TDengine Client Module**. - -
    -
    Picture 1 TDengine Architecture
    -### MGMT Module -The MGMT module deals with the storage and querying on metadata, which includes information about users, databases, and tables. Applications will connect to the MGMT module at first when connecting the TDengine server. When creating/dropping databases/tables, The request is sent to the MGMT module at first to create/delete metadata. Then the MGMT module will send requests to the data module to allocate/free resources required. In the case of writing or querying, applications still need to visit the MGMT module to get meta data, according to which, then access the DNODE module. - -### DNODE Module -The DNODE module is responsible for storing and querying data. For the sake of future scaling and high-efficient resource usage, TDengine applies virtualization on resources it uses. TDengine introduces the concept of a virtual node (vnode), which is the unit of storage, resource allocation and data replication (enterprise edition). As is shown in Picture 2, TDengine treats each data node as an aggregation of vnodes. - -When a DB is created, the system will allocate a vnode. Each vnode contains multiple tables, but a table belongs to only one vnode. Each DB has one or mode vnodes, but one vnode belongs to only one DB. Each vnode contains all the data in a set of tables. Vnodes have their own cache and directory to store data. Resources between different vnodes are exclusive with each other, no matter cache or file directory. However, resources in the same vnode are shared between all the tables in it. Through virtualization, TDengine can distribute resources reasonably to each vnode and improve resource usage and concurrency. The number of vnodes on a dnode is configurable according to its hardware resources. - -
    -
    Picture 2 TDengine Virtualization
    - -### Client Module -TDengine client module accepts requests (mainly in SQL form) from applications and converts the requests to internal representations and sends to the server side. TDengine supports multiple interfaces, which are all built on top of TDengine client module. - -For the communication between client and MGMT module, TCP/UDP is used, the port is set by the parameter `mgmtShellPort` in system configuration file `taos.cfg`, default is 6030. For communication between the client and the DNODE module, TCP/UDP is used, the port is set by the parameter `vnodeShellPort` in the system configuration file, default is 6035. - -## Writing Process -Picture 3 shows the full writing process of TDengine. TDengine uses the [Writing Ahead Log] (http://en.wikipedia.org/wiki/Write-ahead_logging) strategy to assure data security and integrity. Data received from the client is written to the commit log at first. When TDengine recovers from crashes caused by power loss or other situations, the commit log is used to recover data. After writting to the commit log, data will be wrtten to the corresponding vnode cache, then an acknowledgment is sent to the application. There are two mechanisms that can flush data in cache to disk for persistent storage: - -1. **Flush driven by timer**: There is a backend timer which flushes data in cache periodically to disks. The period is configurable via parameter commitTime in system configuration file taos.cfg. -2. **Flush driven by data**: Data in the cache is also flushed to disks when the left buffer size is below a threshold. Flush driven by data can reset the timer of flush driven by the timer. - -
    -
    Picture 3 TDengine Writting Process
    - -New commit log files will be opened when the committing process begins. When the committing process finishes, the old commit file will be removed. - -## Data Storage - -TDengine data are saved in _/var/lib/taos_ directory by default. It can be changed to other directories by setting the parameter `dataDir` in system configuration file taos.cfg. - -TDengine's metadata includes the database, table, user, super table and tag information. To reduce the latency, metadata are all buffered in the cache. - -Data records saved in tables are sharded according to the time range. Data from tables in the same vnode in a certain time range are saved in the same file group. This sharding strategy can effectively improve data search speed. By default, one group of files contain data in 10 days, which can be configured by `daysPerFile` in the configuration file or by the *DAYS* keyword in *CREATE DATABASE* clause. - -Data records are removed automatically once their lifetime is passed. The lifetime is configurable via parameter daysToKeep in the system configuration file. The default value is 3650 days. - -Data in files are blockwise. A data block only contains one table's data. Records in the same data block are sorted according to the primary timestamp. To improve the compression ratio, records are stored column by column, and different compression algorithms are applied based on each column's data type. \ No newline at end of file diff --git a/documentation/webdocs/markdowndocs/More on System Architecture-ch.md b/documentation/webdocs/markdowndocs/More on System Architecture-ch.md deleted file mode 100644 index 77ce9638884a00bafbb8ddbe90ff9839a9cb266e..0000000000000000000000000000000000000000 --- a/documentation/webdocs/markdowndocs/More on System Architecture-ch.md +++ /dev/null @@ -1,248 +0,0 @@ -# TDengine的技术设计 - -## 存储设计 - -TDengine的数据存储主要包含**元数据的存储**和**写入数据的存储**。以下章节详细介绍了TDengine各种数据的存储结构。 - -### 元数据的存储 - -TDengine中的元数据信息包括TDengine中的数据库，表，超级表等信息。元数据信息默认存放在 _/var/lib/taos/mgmt/_ 文件夹下。该文件夹的目录结构如下所示： -``` -/var/lib/taos/ - +--mgmt/ - +--db.db - +--meters.db - +--user.db - +--vgroups.db -``` -元数据在文件中按顺序排列。文件中的每条记录代表TDengine中的一个元数据机构（数据库、表等）。元数据文件只进行追加操作，即便是元数据的删除，也只是在数据文件中追加一条删除的记录。 - -### 写入数据的存储 - -TDengine中写入的数据在硬盘上是按时间维度进行分片的。同一个vnode中的表在同一时间范围内的数据都存放在同一文件组中，如下图中的v0f1804*文件。这一数据分片方式可以大大简化数据在时间维度的查询，提高查询速度。在默认配置下，硬盘上的每个文件存放10天数据。用户可根据需要调整数据库的 _daysPerFile_ 配置项进行配置。 数据在文件中是按块存储的。每个数据块只包含一张表的数据，且数据是按照时间主键递增排列的。数据在数据块中按列存储，这样使得同类型的数据存放在一起，可以大大提高压缩的比例，节省存储空间。TDengine对不同类型的数据采用了不同的压缩算法进行压缩，以达到最优的压缩结果。TDengine使用的压缩算法包括simple8B、delta-of-delta、RLE以及LZ4等。 - -TDengine的数据文件默认存放在 */var/lib/taos/data/* 下。而 */var/lib/taos/tsdb/* 文件夹下存放了vnode的信息、vnode中表的信息以及数据文件的链接等。其完整目录结构如下所示： -``` -/var/lib/taos/ - +--tsdb/ - | +--vnode0 - | +--meterObj.v0 - | +--db/ - | +--v0f1804.head->/var/lib/taos/data/vnode0/v0f1804.head1 - | +--v0f1804.data->/var/lib/taos/data/vnode0/v0f1804.data - | +--v0f1804.last->/var/lib/taos/data/vnode0/v0f1804.last1 - | +--v0f1805.head->/var/lib/taos/data/vnode0/v0f1805.head1 - | +--v0f1805.data->/var/lib/taos/data/vnode0/v0f1805.data - | +--v0f1805.last->/var/lib/taos/data/vnode0/v0f1805.last1 - | : - +--data/ - +--vnode0/ - +--v0f1804.head1 - +--v0f1804.data - +--v0f1804.last1 - +--v0f1805.head1 - +--v0f1805.data - +--v0f1805.last1 - : -``` - -#### meterObj文件 -每个vnode中只存在一个 _meterObj_ 文件。该文件中存储了vnode的基本信息（创建时间，配置信息，vnode的统计信息等）以及该vnode中表的信息。其结构如下所示： -``` -<文件开始> -[文件头] -[表记录1偏移量和长度] -[表记录2偏移量和长度] -... -[表记录N偏移量和长度] -[表记录1] -[表记录2] -... -[表记录N] -[表记录] -<文件结尾> -``` -其中，文件头大小为512字节，主要存放vnode的基本信息。每条表记录代表属于该vnode中的一张表在硬盘上的表示。 - -#### head文件 -head文件中存放了其对应的data文件中数据块的索引信息。该文件组织形式如下： -``` -<文件开始> -[文件头] -[表1偏移量] -[表2偏移量] -... -[表N偏移量] -[表1数据索引] -[表2数据索引] -... -[表N数据索引] -<文件结尾> -``` -文件开头的偏移量列表表示对应表的数据索引块的开始位置在文件中的偏移量。每张表的数据索引信息在head文件中都是连续存放的。这也使得TDengine在读取单表数据时，可以将该表所有的数据块索引一次性读入内存，大大提高读取速度。表的数据索引块组织如下： -``` -[索引块信息] -[数据块1索引] -[数据块2索引] -... -[数据块N索引] -``` -其中，索引块信息中记录了数据块的个数等描述信息。每个数据块索引对应一个在data文件或last文件中的一个单独的数据块。索引信息中记录了数据块存放的文件、数据块起始位置的偏移量、数据块中数据时间主键的范围等。索引块中的数据块索引是按照时间范围顺序排放的，这也就是说，索引块M对应的数据块中的数据时间范围都大于索引块M-1的。这种预先排序的存储方式使得在TDengine在进行按照时间戳进行查询时可以使用折半查找算法，大大提高查询速度。 - -#### data文件 -data文件中存放了真实的数据块。该文件只进行追加操作。其文件组织形式如下： -``` -<文件开始> -[文件头] -[数据块1] -[数据块2] -... -[数据块N] -<文件结尾> -``` -每个数据块只属于vnode中的一张表，且数据块中的数据按照时间主键排列。数据块中的数据按列组织排放，使得同一类型的数据排放在一起，方便压缩和读取。每个数据块的组织形式如下所示： -``` -[列1信息] -[列2信息] -... -[列N信息] -[列1数据] -[列2数据] -... -[列N数据] -``` -列信息中包含该列的类型，列的压缩算法，列数据在文件中的偏移量以及长度等。除此之外，列信息中也包含该内存块中该列数据的预计算结果，从而在过滤查询时根据预计算结果判定是否读取数据块，大大提高读取速度。 - -#### last文件 -为了防止数据块的碎片化，提高查询速度和压缩率，TDengine引入了last文件。当要落盘的数据块中的数据条数低于某个阈值时，TDengine会先将该数据块写入到last文件中进行暂时存储。当有新的数据需要落盘时，last文件中的数据会被读取出来与新数据组成新的数据块写入到data文件中。last文件的组织形式与data文件类似。 - -### TDengine数据存储小结 -TDengine通过其创新的架构和存储结构设计，有效提高了计算机资源的使用率。一方面，TDengine的虚拟化使得TDengine的水平扩展及备份非常容易。另一方面，TDengine将表中数据按时间主键排序存储且其列式存储的组织形式都使TDengine在写入、查询以及压缩方面拥有非常大的优势。 - - -## 查询处理 - -### 概述 - -TDengine提供了多种多样针对表和超级表的查询处理功能，除了常规的聚合查询之外，还提供针对时序数据的窗口查询、统计聚合等功能。TDengine的查询处理需要客户端、管理节点、数据节点协同完成。 各组件包含的与查询处理相关的功能和模块如下： - -客户端（Client App）。客户端包含TAOS SQL的解析（SQL Parser）和查询请求执行器（Query Executor），第二阶段聚合器（Result Merger），连续查询管理器（Continuous Query Manager）等主要功能模块构成。SQL解析器负责对SQL语句进行解析校验，并转化为抽象语法树，查询执行器负责将抽象语法树转化查询执行逻辑，并根据SQL语句查询条件，将其转换为针对管理节点元数据查询和针对数据节点的数据查询两级查询处理。由于TAOS SQL当前不提供复杂的嵌套查询和pipeline查询处理机制，所以不再需要查询计划优化、逻辑查询计划到物理查询计划转换等过程。第二阶段聚合器负责将各数据节点查询返回的独立结果进行二阶段聚合生成最后的结果。连续查询管理器则负责针对用户建立的连续查询进行管理，负责定时拉起查询请求并按需将结果写回TDengine或返回给客户应用。此外，客户端还负责查询失败后重试、取消查询请求、以及维持连接心跳、向管理节点上报查询状态等工作。 - -管理节点（Management Node）。管理节点保存了整个集群系统的全部数据的元数据信息，向客户端节点提供查询所需的数据的元数据，并根据集群的负载情况切分查询请求。通过超级表包含了通过该超级表创建的所有表的信息，因此查询处理器（Query Executor）负责针对标签（TAG）的查询处理，并将满足标签查询请求的表信息返回给客户端。此外，管理节点还维护集群的查询状态（Query Status Manager）维护，查询状态管理中在内存中临时保存有当前正在执行的全部查询，当客户端使用 *show queries* 命令的时候，将当前系统正在运行的查询信息返回客户端。 - -数据节点（Data Node）。数据节点保存了数据库中全部数据内容，并通过查询执行器、查询处理调度器、查询任务队列（Query Task Queue）进行查询处理的调度执行，从客户端接收到的查询处理请求都统一放置到处理队列中，查询执行器从队列中获得查询请求，并负责执行。通过查询优化器（Query Optimizer）对于查询进行基本的优化处理，以及通过数据节点的查询执行器（Query Executor）扫描符合条件的数据单元并返回计算结果。等接收客户端发出的查询请求，执行查询处理，并将结果返回。同时数据节点还需要响应来自管理节点的管理信息和命令，例如 *kill query* 命令以后，需要即刻停止执行的查询任务。 - -
    -
    图 1. 系统查询处理架构图(只包含查询相关组件)
    - -### 普通查询处理 - -客户端、管理节点、数据节点协同完成TDengine的查询处理全流程。我们以一个具体的SQL查询为例，说明TDengine的查询处理流程。SQL语句向超级表*FOO_SUPER_TABLE*查询获取时间范围在2019年1月12日整天，标签TAG_LOC是'beijing'的表所包含的所有记录总数，SQL语句如下： - -```sql -SELECT COUNT(*) -FROM FOO_SUPER_TABLE -WHERE TAG_LOC = 'beijing' AND TS >= '2019-01-12 00:00:00' AND TS < '2019-01-13 00:00:00' -``` - -首先，客户端调用TAOS SQL解析器对SQL语句进行解析及合法性检查，然后生成语法树，并从中提取查询的对象 — 超级表 *FOO_SUPER_TABLE* ，然后解析器向管理节点（Management Node）请求其相应的元数据信息，并将过滤信息（TAG_LOC='beijing'）同时发送到管理节点。 - -管理节点接收元数据获取的请求，首先找到超级表 *FOO_SUPER_TABLE* 基础信息，然后应用查询条件来过滤通过该超级表创建的全部表，最后满足查询条件（TAG_LOC='beijing'），即 *TAG_LOC* 标签列是 'beijing' 的的通过其查询执行器将满足查询要求的对象（表或超级表）的元数据信息返回给客户端。 - -客户端获得了 *FOO_SUPER_TABLE* 的元数据信息后，查询执行器根据元数据中的数据分布，分别向保存有相应数据的节点发起查询请求，此时时间戳范围过滤条件（TS >= '2019-01-12 00:00:00' AND TS < '2019-01-13 00:00:00'）需要同时发送给全部的数据节点。 - -数据节点接收到发自客户端的查询，转化为内部结构并进行优化以后将其放入任务执行队列，等待查询执行器执行。当查询结果获得以后，将查询结果返回客户端。数据节点执行查询的过程均相互独立，完全只依赖于自身的数据和内容进行计算。 - -当所有查询涉及的数据节点返回结果后，客户端将每个数据节点查询的结果集再次进行聚合（针对本案例，即将所有结果再次进行累加），累加的结果即为最后的查询结果。第二阶段聚合并不是所有的查询都需要。例如，针对数据的列选取操作，实际上是不需要第二阶段聚合。 - -### REST查询处理 - -在 C/C++ 、Python接口、 JDBC 接口之外，TDengine 还提供基于 HTTP 协议的 REST 接口。不同于使用应用客户端开发程序进行的开发。当用户使用 REST 接口的时候，所有的查询处理过程都是在服务器端来完成，用户的应用服务不会参与数据库的计算过程，查询处理完成后结果通过 HTTP的 JSON 格式返回给用户。 - -
    -
    图 2. REST查询架构
    - -当用户使用基于HTTP的REST查询接口，HTTP的请求首先与位于数据节点的HTTP连接器（ Connector），建立连接，然后通过REST的签名机制，使用Token来确保请求的可靠性。对于数据节点，HTTP连接器接收到请求后，调用内嵌的客户端程序发起查询请求，内嵌客户端将解析通过HTTP连接器传递过来的SQL语句，解析该SQL语句并按需向管理节点请求元数据信息，然后向本机或集群中其他节点发送查询请求，最后按需聚合计算结果。HTTP连接器接收到请求SQL以后，后续的流程处理与采用应用客户端方式的查询处理完全一致。最后，还需要将查询的结果转换为JSON格式字符串，并通过HTTP 响应返回给客户端。 - -可以看到，在处理HTTP流程的整个过程中，用户应用不再参与到查询处理的过程中，只负责通过HTTP协议发送SQL请求并接收JSON格式的结果。同时还需要注意的是，每个数据节点均内嵌了一个HTTP连接器和客户端程序，因此请求集群中任何一个数据节点，该数据节点均能够通过HTTP协议返回用户的查询结果。 - -### 技术特征 - -由于TDengine采用数据和标签分离存储的模式，能够极大地降低标签数据存储的冗余度。标签数据直接关联到每个表，并采用全内存的结构进行管理和维护标签数据,全内存的结构提供快速的查询处理，千万级别规模的标签数据查询可以在毫秒级别返回。首先针对标签数据的过滤可以有效地降低第二阶段的查询涉及的数据规模。为有效地提升查询处理的性能，针对物联网数据的不可更改的特点，TDengine采用在每个保存的数据块上，都记录下该数据块中数据的最大值、最小值、和等统计数据。如果查询处理涉及整个数据块的全部数据，则直接使用预计算结果，不再读取数据块的内容。由于预计算模块的大小远小于磁盘上存储的具体数据的大小，对于磁盘IO为瓶颈的查询处理，使用预计算结果可以极大地减小读取IO，并加速查询处理的流程。 - -由于TDengine采用按列存储数据。当从磁盘中读取数据块进行计算的时候，按照查询列信息读取该列数据，并不需要读取其他不相关的数据，可以最小化读取数据。此外，由于采用列存储结构，数据节点针对数据的扫描采用该列数据块进行，可以充分利用CPU L2高速缓存，极大地加速数据扫描的速度。此外，对于某些查询，并不会等全部查询结果生成后再返回结果。例如，列选取查询，当第一批查询结果获得以后，数据节点直接将其返回客户端。同时，在查询处理过程中，系统在数据节点接收到查询请求以后马上返回客户端查询确认信息，并同时拉起查询处理过程，并等待查询执行完成后才返回给用户查询有响应。 - -## 集群设计 - -### 1：集群与主要逻辑单元 - -TDengine是基于硬件、软件系统不可靠、一定会有故障的假设进行设计的，是基于任何单台计算机都无足够能力处理海量数据的假设进行设计的。因此TDengine从研发的第一天起，就按照分布式高可靠架构进行设计，是完全去中心化的，是水平扩展的，这样任何单台或多台服务器宕机或软件错误都不影响系统的服务。通过节点虚拟化并辅以自动化负载均衡技术，TDengine能最大限度地利用异构集群中的计算和存储资源。而且只要数据副本数大于一，无论是硬软件的升级、还是IDC的迁移等都无需停止集群的服务，极大地保证系统的正常运行，并且降低了系统管理员和运维人员的工作量。 - -下面的示例图上有八个物理节点，每个物理节点被逻辑的划分为多个虚拟节点。下面对系统的基本概念进行介绍。 - - - -![assets/nodes.png](../assets/nodes.png) - -**物理节点(dnode)**：集群中的一物理服务器或云平台上的一虚拟机。为安全以及通讯效率，一个物理节点可配置两张网卡，或两个IP地址。其中一张网卡用于集群内部通讯，其IP地址为**privateIp**, 另外一张网卡用于与集群外部应用的通讯，其IP地址为**publicIp**。在一些云平台（如阿里云），对外的IP地址是映射过来的，因此publicIp还有一个对应的内部IP地址**internalIp**(与privateIp不同)。对于只有一个IP地址的物理节点，publicIp, privateIp以及internalIp都是同一个地址，没有任何区别。一个dnode上有而且只有一个taosd实例运行。 - -**虚拟数据节点(vnode)**：在物理节点之上的可独立运行的基础逻辑单元，时序数据写入、存储、查询等操作逻辑都在虚拟节点中进行(图中V)，采集的时序数据就存储在vnode上。一个vnode包含固定数量的表。当创建一张新表时，系统会检查是否需要创建新的vnode。一个物理节点上能创建的vnode的数量取决于物理节点的硬件资源。一个vnode只属于一个DB，但一个DB可以有多个vnode。 - -**虚拟数据节点组(vgroup)**: 位于不同物理节点的vnode可以组成一个虚拟数据节点组vnode group(如上图dnode0中的V0, dnode1中的V1, dnode6中的V2属于同一个虚拟节点组)。归属于同一个vgroup的虚拟节点采取master/slave的方式进行管理。写只能在master上进行，但采用asynchronous的方式将数据同步到slave，这样确保了一份数据在多个物理节点上有拷贝。如果master节点宕机，其他节点监测到后，将重新选举vgroup里的master, 新的master能继续处理数据请求，从而保证系统运行的可靠性。一个vgroup里虚拟节点个数就是数据的副本数。如果一个DB的副本数为N，系统必须有至少N个物理节点。副本数在创建DB时通过参数replica可以指定，缺省为1。使用TDengine, 数据的安全依靠多副本解决，因此不再需要昂贵的磁盘阵列等存储设备。 - -**虚拟管理节点(mnode)**：负责所有节点运行状态的监控和维护，以及节点之间的负载均衡（图中M）。同时，虚拟管理节点也负责元数据(包括用户、数据库、表、静态标签等)的存储和管理，因此也称为Meta Node。TDengine集群中可配置多个(最多不超过5个) mnode，它们自动构建成为一个管理节点集群(图中M0, M1, M2)。mnode间采用master/slave的机制进行管理，而且采取强一致方式进行数据同步。mnode集群的创建由系统自动完成，无需人工干预。每个dnode上至多有一个mnode，而且每个dnode都知道整个集群中所有mnode的IP地址。 - -**taosc**：一个软件模块，是TDengine给应用提供的驱动程序（driver）,内嵌于JDBC、ODBC driver中，或者C语言连接库里。应用都是通过taosc而不是直接来与整个集群进行交互的。这个模块负责获取并缓存元数据；将插入、查询等请求转发到正确的虚拟节点；在把结果返回给应用时，还需要负责最后一级的聚合、排序、过滤等操作。对于JDBC, ODBC, C/C++接口而言，这个模块是在应用所处的计算机上运行，但消耗的资源很小。为支持全分布式的REST接口，taosc在TDengine集群的每个dnode上都有一运行实例。 - -**对外服务地址**：TDengine集群可以容纳单台、多台甚至几千台物理节点。应用只需要向集群中任何一个物理节点的publicIp发起连接即可。启动CLI应用taos时，选项-h需要提供的就是publicIp。 - -**master/secondIp**：每一个dnode都需要配置一个masterIp。dnode启动后，将对配置的masterIp发起加入集群的连接请求。masterIp是已经创建的集群中的任何一个节点的privateIp，对于集群中的第一个节点，就是它自己的privateIp。为保证连接成功，每个dnode还可配置secondIp, 该IP地址也是已创建的集群中的任何一个节点的privateIp。如果一个节点连接masterIp失败,它将试图链接secondIp。 - -dnode启动后，会获知集群的mnode IP列表，并且定时向mnode发送状态信息。 - -vnode与mnode只是逻辑上的划分，都是执行程序taosd里的不同线程而已，无需安装不同的软件，做任何特殊的配置。最小的系统配置就是一个物理节点,vnode,mnode和taosc都存在而且都正常运行，但单一节点无法保证系统的高可靠。 - -### 2：一典型的操作流程 - -为解释vnode, mnode, taosc和应用之间的关系以及各自扮演的角色，下面对写入数据这个典型操作的流程进行剖析。 - - - -![Picture1](../assets/Picture2.png) - - - -1. 应用通过JDBC、ODBC或其他API接口发起插入数据的请求。 -2. taosc会检查缓存，看是有保存有该表的meta data。如果有，直接到第4步。如果没有，taosc将向mnode发出get meta-data请求。 -3. mnode将该表的meta-data返回给taosc。Meta-data包含有该表的schema, 而且还有该表所属的vgroup信息（vnode ID以及所在的dnode的IP地址，如果副本数为N，就有N组vnodeID/IP)。如果taosc迟迟得不到mnode回应，而且存在多个mnode,taosc将向下一个mnode发出请求。 -4. taosc向master vnode发起插入请求。 -5. vnode插入数据后，给taosc一个应答，表示插入成功。如果taosc迟迟得不到vnode的回应，taosc会认为该节点已经离线。这种情况下，如果被插入的数据库有多个副本，taosc将向vgroup里下一个vnode发出插入请求。 -6. taosc通知APP，写入成功。 - -对于第二和第三步，taosc启动时，并不知道mnode的IP地址，因此会直接向配置的集群对外服务的IP地址发起请求。如果接收到该请求的dnode并没有配置mnode，该dnode会在回复的消息中告知mnode的IP地址列表（如果有多个dnodes，mnode的IP地址可以有多个），这样taosc会重新向新的mnode的IP地址发出获取meta-data的请求。 - -对于第四和第五步，没有缓存的情况下，taosc无法知道虚拟节点组里谁是master，就假设第一个vnodeID/IP就是master,向它发出请求。如果接收到请求的vnode并不是master,它会在回复中告知谁是master，这样taosc就向建议的master vnode发出请求。一旦得到插入成功的回复，taosc会缓存住master节点的信息。 - -上述是插入数据的流程，查询、计算的流程也完全一致。taosc把这些复杂的流程全部封装屏蔽了，因此应用无需处理重定向、获取meta data等细节，完全是透明的。 - -通过taosc缓存机制，只有在第一次对一张表操作时，才需要访问mnode, 因此mnode不会成为系统瓶颈。但因为schema有可能变化，而且vgroup有可能发生改变（比如负载均衡发生），因此taosc需要定时自动刷新缓存。 - -### 3：数据分区 - -vnode(虚拟数据节点)保存采集的时序数据，而且查询、计算都在这些节点上进行。为便于负载均衡、数据恢复、支持异构环境，TDengine将一个物理节点根据其计算和存储资源切分为多个vnode。这些vnode的管理是TDengine自动完成的，对应用完全透明。 - -对于单独一个数据采集点，无论其数据量多大，一个vnode（或vnode group, 如果副本数大于1）有足够的计算资源和存储资源来处理（如果每秒生成一条16字节的记录，一年产生的原始数据不到0.5G），因此TDengine将一张表的所有数据都存放在一个vnode里，而不会让同一个采集点的数据分布到两个或多个dnode上。而且一个vnode可存储多张表的数据，一个vnode可容纳的表的数目由配置参数tables指定，缺省为2000。设计上，一个vnode里所有的表都属于同一个DB。因此一个数据库DB需要的vnode或vgroup的个数等于：数据库表的数目/tables。 - -创建DB时，系统并不会马上分配资源。但当创建一张表时，系统将看是否有已经分配的vnode, 而且是否有空位，如果有，立即在该有空位的vnode创建表。如果没有，系统将从集群中，根据当前的负载情况，在一个dnode上创建一新的vnode, 然后创建表。如果DB有多个副本，系统不是只创建一个vnode，而是一个vgroup(虚拟数据节点组)。系统对vnode的数目没有任何限制，仅仅受限于物理节点本身的计算和存储资源。 - -参数tables的设置需要考虑具体场景，创建DB时，可以个性化指定该参数。该参数不宜过大，也不宜过小。过小，极端情况，就是每个数据采集点一个vnode, 这样导致系统数据文件过多。过大，虚拟化带来的优势就会丧失。给定集群计算资源的情况下，整个系统vnode的个数应该是CPU核的数目的两倍以上。 - -### 4：负载均衡 - -每个dnode(物理节点)都定时向 mnode(虚拟管理节点)报告其状态（包括硬盘空间、内存大小、CPU、网络、虚拟节点个数等），因此mnode了解整个集群的状态。基于整体状态，当mnode发现某个dnode负载过重，它会将dnode上的一个或多个vnode挪到其他dnode。在挪动过程中，对外服务继续进行，数据插入、查询和计算操作都不受影响。负载均衡操作结束后，应用也无需重启，将自动连接新的vnode。 - -如果mnode一段时间没有收到dnode的状态报告，mnode会认为这个dnode已经离线。如果离线时间超过一定时长（时长由配置参数offlineThreshold决定），该dnode将被mnode强制剔除出集群。该dnode上的vnodes如果副本数大于一，系统将自动在其他dnode上创建新的副本，以保证数据的副本数。 - - - -**Note：**目前集群功能仅仅限于企业版 diff --git a/documentation/webdocs/markdowndocs/More on System Architecture.md b/documentation/webdocs/markdowndocs/More on System Architecture.md deleted file mode 100644 index d7a38b99a3ae5a630509f3ef0f0ffdc97d3aaaf1..0000000000000000000000000000000000000000 --- a/documentation/webdocs/markdowndocs/More on System Architecture.md +++ /dev/null @@ -1,176 +0,0 @@ -# TDengine System Architecture - -## Storage Design - -TDengine data mainly include **metadata** and **data** that we will introduce in the following sections. - -### Metadata Storage - -Metadata include the information of databases, tables, etc. Metadata files are saved in _/var/lib/taos/mgmt/_ directory by default. The directory tree is as below: -``` -/var/lib/taos/ - +--mgmt/ - +--db.db - +--meters.db - +--user.db - +--vgroups.db -``` - -A metadata structure (database, table, etc.) is saved as a record in a metadata file. All metadata files are appended only, and even a drop operation adds a deletion record at the end of the file. - -### Data storage - -Data in TDengine are sharded according to the time range. Data of tables in the same vnode in a certain time range are saved in the same filegroup, such as files v0f1804*. This sharding strategy can effectively improve data searching speed. By default, a group of files contains data in 10 days, which can be configured by *daysPerFile* in the configuration file or by *DAYS* keyword in *CREATE DATABASE* clause. Data in files are blockwised. A data block only contains one table's data. Records in the same data block are sorted according to the primary timestamp, which helps to improve the compression rate and save storage. The compression algorithms used in TDengine include simple8B, delta-of-delta, RLE, LZ4, etc. - -By default, TDengine data are saved in */var/lib/taos/data/* directory. _/var/lib/taos/tsdb/_ directory contains vnode informations and data file linkes. - -``` -/var/lib/taos/ - +--tsdb/ - | +--vnode0 - | +--meterObj.v0 - | +--db/ - | +--v0f1804.head->/var/lib/taos/data/vnode0/v0f1804.head1 - | +--v0f1804.data->/var/lib/taos/data/vnode0/v0f1804.data - | +--v0f1804.last->/var/lib/taos/data/vnode0/v0f1804.last1 - | +--v0f1805.head->/var/lib/taos/data/vnode0/v0f1805.head1 - | +--v0f1805.data->/var/lib/taos/data/vnode0/v0f1805.data - | +--v0f1805.last->/var/lib/taos/data/vnode0/v0f1805.last1 - | : - +--data/ - +--vnode0/ - +--v0f1804.head1 - +--v0f1804.data - +--v0f1804.last1 - +--v0f1805.head1 - +--v0f1805.data - +--v0f1805.last1 - : -``` - -#### meterObj file -There are only one meterObj file in a vnode. Informations bout the vnode, such as created time, configuration information, vnode statistic informations are saved in this file. It has the structure like below: - -``` - -[file_header] -[table_record1_offset&length] -[table_record2_offset&length] -... -[table_recordN_offset&length] -[table_record1] -[table_record2] -... -[table_recordN] - -``` -The file header takes 512 bytes, which mainly contains informations about the vnode. Each table record is the representation of a table on disk. - -#### head file -The _head_ files contain the index of data blocks in the _data_ file. The inner organization is as below: -``` - -[file_header] -[table1_offset] -[table2_offset] -... -[tableN_offset] -[table1_index_block] -[table2_index_block] -... -[tableN_index_block] - -``` -The table offset array in the _head_ file saves the information about the offsets of each table index block. Indices on data blocks in the same table are saved continuously. This also makes it efficient to load data indices on the same table. The data index block has a structure like: - -``` -[index_block_info] -[block1_index] -[block2_index] -... -[blockN_index] -``` -The index block info part contains the information about the index block such as the number of index blocks, etc. Each block index corresponds to a real data block in the _data_ file or _last_ file. Information about the location of the real data block, the primary timestamp range of the data block, etc. are all saved in the block index part. The block indices are sorted in ascending order according to the primary timestamp. So we can apply algorithms such as the binary search on the data to efficiently search blocks according to time. - -#### data file -The _data_ files store the real data block. They are append-only. The organization is as: -``` - -[file_header] -[block1] -[block2] -... -[blockN] - -``` -A data block in _data_ files only belongs to a table in the vnode and the records in a data block are sorted in ascending order according to the primary timestamp key. Data blocks are column-oriented. Data in the same column are stored contiguously, which improves reading speed and compression rate because of their similarity. A data block has the following organization: - -``` -[column1_info] -[column2_info] -... -[columnN_info] -[column1_data] -[column2_data] -... -[columnN_data] -``` -The column info part includes information about column types, column compression algorithm, column data offset and length in the _data_ file, etc. Besides, pre-calculated results of the column data in the block are also in the column info part, which helps to improve reading speed by avoiding loading data block necessarily. - -#### last file -To avoid storage fragment and to import query speed and compression rate, TDengine introduces an extra file, the _last_ file. When the number of records in a data block is lower than a threshold, TDengine will flush the block to the _last_ file for temporary storage. When new data comes, the data in the _last_ file will be merged with the new data and form a larger data block and written to the _data_ file. The organization of the _last_ file is similar to the _data_ file. - -### Summary -The innovation in architecture and storage design of TDengine improves resource usage. On the one hand, the virtualization makes it easy to distribute resources between different vnodes and for future scaling. On the other hand, sorted and column-oriented storage makes TDengine have a great advantage in writing, querying and compression. - -## Query Design - -#### Introduction - -TDengine provides a variety of query functions for both tables and super tables. In addition to regular aggregate queries, it also provides time window based query and statistical aggregation for time series data. TDengine's query processing requires the client app, management node, and data node to work together. The functions and modules involved in query processing included in each component are as follows: - -Client (Client App). The client development kit, embed in a client application, consists of TAOS SQL parser and query executor, the second-stage aggregator (Result Merger), continuous query manager and other major functional modules. The SQL parser is responsible for parsing and verifying the SQL statement and converting it into an abstract syntax tree. The query executor is responsible for transforming the abstract syntax tree into the query execution logic and creates the metadata query according to the query condition of the SQL statement. Since TAOS SQL does not currently include complex nested queries and pipeline query processing mechanism, there is no longer need for query plan optimization and physical query plan conversions. The second-stage aggregator is responsible for performing the aggregation of the independent results returned by query involved data nodes at the client side to generate final results. The continuous query manager is dedicated to managing the continuous queries created by users, including issuing fixed-interval query requests and writing the results back to TDengine or returning to the client application as needed. Also, the client is also responsible for retrying after the query fails, canceling the query request, and maintaining the connection heartbeat and reporting the query status to the management node. - -Management Node. The management node keeps the metadata of all the data of the entire cluster system, provides the metadata of the data required for the query from the client node, and divides the query request according to the load condition of the cluster. The super table contains information about all the tables created according to the super table, so the query processor (Query Executor) of the management node is responsible for the query processing of the tags of tables and returns the table information satisfying the tag query. Besides, the management node maintains the query status of the cluster in the Query Status Manager component, in which the metadata of all queries that are currently executing are temporarily stored in-memory buffer. When the client issues *show queries* command to management node, current running queries information is returned to the client. - -Data Node. The data node, responsible for storing all data of the database, consists of query executor, query processing scheduler, query task queue, and other related components. Once the query requests from the client received, they are put into query task queue and waiting to be processed by query executor. The query executor extracts the query request from the query task queue and invokes the query optimizer to perform the basic optimization for the query execution plan. And then query executor scans the qualified data blocks in both cache and disk to obtain qualified data and return the calculated results. Besides, the data node also needs to respond to management information and commands from the management node. For example, after the *kill query* received from the management node, the query task needs to be stopped immediately. - -
    -
    Fig 1. System query processing architecture diagram (only query related components)
    - -#### Query Process Design - -The client, the management node, and the data node cooperate to complete the entire query processing of TDengine. Let's take a concrete SQL query as an example to illustrate the whole query processing flow. The SQL statement is to query on super table *FOO_SUPER_TABLE* to get the total number of records generated on January 12, 2019, from the table, of which TAG_LOC equals to 'beijing'. The SQL statement is as follows: - -```sql -SELECT COUNT(*) -FROM FOO_SUPER_TABLE -WHERE TAG_LOC = 'beijing' AND TS >= '2019-01-12 00:00:00' AND TS < '2019-01-13 00:00:00' -``` - -First, the client invokes the TAOS SQL parser to parse and validate the SQL statement, then generates a syntax tree, and extracts the object of the query - the super table *FOO_SUPER_TABLE*, and then the parser sends requests with filtering information (TAG_LOC='beijing') to management node to get the corresponding metadata about *FOO_SUPER_TABLE*. - -Once the management node receives the request for metadata acquisition, first finds the super table *FOO_SUPER_TABLE* basic information, and then applies the query condition (TAG_LOC='beijing') to filter all the related tables created according to it. And finally, the query executor returns the metadata information that satisfies the query request to the client. - -After the client obtains the metadata information of *FOO_SUPER_TABLE*, the query executor initiates a query request with timestamp range filtering condition (TS >= '2019- 01-12 00:00:00' AND TS < '2019-01-13 00:00:00') to all nodes that hold the corresponding data according to the information about data distribution in metadata. - -The data node receives the query sent from the client, converts it into an internal structure and puts it into the query task queue to be executed by query executor after optimizing the execution plan. When the query result is obtained, the query result is returned to the client. It should be noted that the data nodes perform the query process independently of each other, and rely solely on their data and content for processing. - -When all data nodes involved in the query return results, the client aggregates the result sets from each data node. In this case, all results are accumulated to generate the final query result. The second stage of aggregation is not always required for all queries. For example, a column selection query does not require a second-stage aggregation at all. - -#### REST Query Process - -In addition to C/C++, Python, and JDBC interface, TDengine also provides a REST interface based on the HTTP protocol, which is different from using the client application programming interface. When the user uses the REST interface, all the query processing is completed on the server-side, and the user's application is not involved in query processing anymore. After the query processing is completed, the result is returned to the client through the HTTP JSON string. - -
    -
    Fig. 2 REST query architecture
    - -When a client uses an HTTP-based REST query interface, the client first establishes a connection with the HTTP connector at the data node and then uses the token to ensure the reliability of the request through the REST signature mechanism. For the data node, after receiving the request, the HTTP connector invokes the embedded client program to initiate a query processing, and then the embedded client parses the SQL statement from the HTTP connector and requests the management node to get metadata as needed. After that, the embedded client sends query requests to the same data node or other nodes in the cluster and aggregates the calculation results on demand. Finally, you also need to convert the result of the query into a JSON format string and return it to the client via an HTTP response. After the HTTP connector receives the request SQL, the subsequent process processing is completely consistent with the query processing using the client application development kit. - -It should be noted that during the entire processing, the client application is no longer involved in, and is only responsible for sending SQL requests through the HTTP protocol and receiving the results in JSON format. Besides, each data node is embedded with an HTTP connector and a client, so any data node in the cluster received requests from a client, the data node can initiate the query and return the result to the client through the HTTP protocol, with transfer the request to other data nodes. - -#### Technology - -Because TDengine stores data and tags value separately, the tag value is kept in the management node and directly associated with each table instead of records, resulting in a great reduction of the data storage. Therefore, the tag value can be managed by a fully in-memory structure. First, the filtering of the tag data can drastically reduce the data size involved in the second phase of the query. The query processing for the data is performed at the data node. TDengine takes advantage of the immutable characteristics of IoT data by calculating the maximum, minimum, and other statistics of the data in one data block on each saved data block, to effectively improve the performance of query processing. If the query process involves all the data of the entire data block, the pre-computed result is used directly, and the content of the data block is no longer needed. Since the size of disk space required to store the pre-computation result is much smaller than the size of the specific data, the pre-computation result can greatly reduce the disk IO and speed up the query processing. - -TDengine employs column-oriented data storage techniques. When the data block is involved to be loaded from the disk for calculation, only the required column is read according to the query condition, and the read overhead can be minimized. The data of one column is stored in a contiguous memory block and therefore can make full use of the CPU L2 cache to greatly speed up the data scanning. Besides, TDengine utilizes the eagerly responding mechanism and returns a partial result before the complete result is acquired. For example, when the first batch of results is obtained, the data node immediately returns it directly to the client in case of a column select query. \ No newline at end of file diff --git a/documentation/webdocs/markdowndocs/Super Table-ch.md b/documentation/webdocs/markdowndocs/Super Table-ch.md deleted file mode 100644 index f45f2f91b1ae6cf7e5ab3c8270de5c3c6bca6c97..0000000000000000000000000000000000000000 --- a/documentation/webdocs/markdowndocs/Super Table-ch.md +++ /dev/null @@ -1,225 +0,0 @@ -# 超级表STable：多表聚合 - -TDengine要求每个数据采集点单独建表。独立建表的模式能够避免写入过程中的同步加锁，因此能够极大地提升数据的插入/查询性能。但是独立建表意味着系统中表的数量与采集点的数量在同一个量级。如果采集点众多，将导致系统中表的数量也非常庞大，让应用对表的维护以及聚合、统计操作难度加大。为降低应用的开发难度，TDengine引入了超级表(Super Table, 简称为STable)的概念。 - -## 什么是超级表 - -超级表是同一类型数据采集点的抽象，是同类型采集实例的集合，包含多张数据结构一样的子表。每个STable为其子表定义了表结构和一组标签：表结构即表中记录的数据列及其数据类型；标签名和数据类型由STable定义，标签值记录着每个子表的静态信息，用以对子表进行分组过滤。子表本质上就是普通的表，由一个时间戳主键和若干个数据列组成，每行记录着具体的数据，数据查询操作与普通表完全相同；但子表与普通表的区别在于每个子表从属于一张超级表，并带有一组由STable定义的标签值。每种类型的采集设备可以定义一个STable。数据模型定义表的每列数据的类型，如温度、压力、电压、电流、GPS实时位置等，而标签信息属于Meta Data，如采集设备的序列号、型号、位置等，是静态的，是表的元数据。用户在创建表（数据采集点）时指定STable(采集类型)外，还可以指定标签的值，也可事后增加或修改。 - -TDengine扩展标准SQL语法用于定义STable，使用关键词tags指定标签信息。语法如下： - -```mysql -CREATE TABLE ( TIMESTAMP, field_name1 field_type,…) TAGS(tag_name tag_type, …) -``` - -其中tag_name是标签名，tag_type是标签的数据类型。标签可以使用时间戳之外的其他TDengine支持的数据类型，标签的个数最多为32个，名字不能与系统关键词相同，也不能与其他列名相同。如： - -```mysql -CREATE TABLE thermometer (ts timestamp, degree float) -TAGS (location binary(20), type int) -``` - -上述SQL创建了一个名为thermometer的STable，带有标签location和标签type。 - -为某个采集点创建表时，可以指定其所属的STable以及标签的值，语法如下： - -```mysql -CREATE TABLE USING TAGS (tag_value1,...) -``` - -沿用上面温度计的例子，使用超级表thermometer建立单个温度计数据表的语句如下： - -```mysql -CREATE TABLE t1 USING thermometer TAGS ('beijing', 10) -``` - -上述SQL以thermometer为模板，创建了名为t1的表，这张表的Schema就是thermometer的Schema，但标签location值为'beijing'，标签type值为10。 - -用户可以使用一个STable创建数量无上限的具有不同标签的表，从这个意义上理解，STable就是若干具有相同数据模型，不同标签的表的集合。与普通表一样，用户可以创建、删除、查看超级表STable，大部分适用于普通表的查询操作都可运用到STable上，包括各种聚合和投影选择函数。除此之外，可以设置标签的过滤条件，仅对STbale中部分表进行聚合查询，大大简化应用的开发。 - -TDengine对表的主键（时间戳）建立索引，暂时不提供针对数据模型中其他采集量（比如温度、压力值）的索引。每个数据采集点会采集若干数据记录，但每个采集点的标签仅仅是一条记录，因此数据标签在存储上没有冗余，且整体数据规模有限。TDengine将标签数据与采集的动态数据完全分离存储，而且针对STable的标签建立了高性能内存索引结构，为标签提供全方位的快速操作支持。用户可按照需求对其进行增删改查（Create，Retrieve，Update，Delete，CRUD）操作。 - -STable从属于库，一个STable只属于一个库，但一个库可以有一到多个STable, 一个STable可有多个子表。 - -## 超级表管理 - -- 创建超级表 - - ```mysql - CREATE TABLE ( TIMESTAMP, field_name1 field_type,…) TAGS(tag_name tag_type, …) - ``` - - 与创建表的SQL语法相似。但需指定TAGS字段的名称和类型。 - - 说明： - - 1. TAGS列总长度不能超过16k bytes； - 2. TAGS列的数据类型不能是timestamp； - 3. TAGS列名不能与其他列名相同; - 4. TAGS列名不能为预留关键字. - 5. TAGS总数的上限是128. - -- 显示已创建的超级表 - - ```mysql - show stables; - ``` - - 查看数据库内全部STable，及其相关信息，包括STable的名称、创建时间、列数量、标签（TAG）数量、通过该STable建表的数量。 - -- 删除超级表 - - ```mysql - DROP TABLE - ``` - - Note: 删除STable时，所有通过该STable创建的表都将被删除。 - -- 查看属于某STable并满足查询条件的表 - - ```mysql - SELECT TBNAME,[TAG_NAME,…] FROM WHERE <[=|<=|>=|<>] values..> ([AND|OR] …) - ``` - - 查看属于某STable并满足查询条件的表。说明：TBNAME为关键词，显示通过STable建立的子表表名，查询过程中可以使用针对标签的条件。 - - ```mysql - SELECT COUNT(TBNAME) FROM WHERE <[=|<=|>=|<>] values..> ([AND|OR] …) - ``` - - 统计属于某个STable并满足查询条件的子表的数量 - -## 写数据时自动建子表 - -在某些特殊场景中，用户在写数据时并不确定某个设备的表是否存在，此时可使用自动建表语法来实现写入数据时里用超级表定义的表结构自动创建不存在的子表，若该表已存在则不会建立新表。注意：自动建表语句只能自动建立子表而不能建立超级表，这就要求超级表已经被事先定义好。自动建表语法跟insert/import语法非常相似，唯一区别是语句中增加了超级表和标签信息。具体语法如下： - -```mysql -INSERT INTO USING TAGS (, ...) VALUES (field_value, ...) (field_value, ...) ...; -``` - -向表tb_name中插入一条或多条记录，如果tb_name这张表不存在，则会用超级表stb_name定义的表结构以及用户指定的标签值(即tag1_value…)来创建名为tb_name新表，并将用户指定的值写入表中。如果tb_name已经存在，则建表过程会被忽略，系统也不会检查tb_name的标签是否与用户指定的标签值一致，也即不会更新已存在表的标签。 - -```mysql -INSERT INTO USING TAGS (, ...) VALUES (, ...) (, ...) ... USING TAGS(, ...) VALUES (, ...) ...; -``` - -向多张表tb1_name，tb2_name等插入一条或多条记录，并分别指定各自的超级表进行自动建表。 - -## STable中TAG管理 - -除了更新标签的值的操作是针对子表进行，其他所有的标签操作（添加标签、删除标签等）均只能作用于STable，不能对单个子表操作。对STable添加标签以后，依托于该STable建立的所有表将自动增加了一个标签，对于数值型的标签，新增加的标签的默认值是0. - -- 添加新的标签 - - ```mysql - ALTER TABLE ADD TAG - ``` - - 为STable增加一个新的标签，并指定新标签的类型。标签总数不能超过128个。 - -- 删除标签 - - ```mysql - ALTER TABLE DROP TAG - ``` - - 删除超级表的一个标签，从超级表删除某个标签后，该超级表下的所有子表也会自动删除该标签。 - - 说明：第一列标签不能删除，至少需要为STable保留一个标签。 - -- 修改标签名 - - ```mysql - ALTER TABLE CHANGE TAG - ``` - - 修改超级表的标签名，从超级表修改某个标签名后，该超级表下的所有子表也会自动更新该标签名。 - -- 修改子表的标签值 - - ```mysql - ALTER TABLE SET TAG = - ``` - -## STable多表聚合 - -针对所有的通过STable创建的子表进行多表聚合查询，支持按照全部的TAG值进行条件过滤，并可将结果按照TAGS中的值进行聚合，暂不支持针对binary类型的模糊匹配过滤。语法如下： - -```mysql -SELECT function,… - FROM - WHERE <[=|<=|>=|<>] values..> ([AND|OR] …) - INTERVAL (