diff --git a/docs-cn/04-develop/01-connect/_connect_c.mdx b/docs-cn/04-develop/01-connect/_connect_c.mdx index b4f774c77f9f85c89a99552ae4ec6b0a3b9b1855..9cd8669561195b49e8428ed490ad97bb5653ae6a 100644 --- a/docs-cn/04-develop/01-connect/_connect_c.mdx +++ b/docs-cn/04-develop/01-connect/_connect_c.mdx @@ -1,3 +1,3 @@ -```c title="本地连接" +```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 index 52a2702b6cc77657f08b27dc3030e44c5afea7f1..204173dd329f6f214a9ea44c2f360be2cdbfdab8 100644 --- a/docs-cn/04-develop/01-connect/_connect_cs.mdx +++ b/docs-cn/04-develop/01-connect/_connect_cs.mdx @@ -1,7 +1,7 @@ -```csharp title="本地连接" +```csharp title="原生连接" {{#include docs-examples/csharp/ConnectExample.cs}} ``` :::info -C# 连接器目前只支持本地连接。 +C# 连接器目前只支持原生连接。 ::: \ No newline at end of file diff --git a/docs-cn/04-develop/01-connect/_connect_go.mdx b/docs-cn/04-develop/01-connect/_connect_go.mdx index bde027247d1a1923be60a474768a5d9387cef751..0cd219f2469497b4e1a2d2905ec91ee972f74e89 100644 --- a/docs-cn/04-develop/01-connect/_connect_go.mdx +++ b/docs-cn/04-develop/01-connect/_connect_go.mdx @@ -1,14 +1,14 @@ #### 使用数据库访问统一接口 -```go title="本地连接" +```go title="原生连接" {{#include docs-examples/go/connect/cgoexample/main.go}} ``` -```go title="RESTful 连接" +```go title="REST 连接" {{#include docs-examples/go/connect/restexample/main.go}} ``` #### 使用高级封装 也可以使用 driver-go 的 af 包建立连接。这个模块封装了 TDengine 的高级功能, 如：动态绑定、订阅等。 -```go title="使用 af 包建立本地连接" +```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 index a95c1a1766b6fe9f9a577fcd82d81fb993a27dee..cd6d7c4cab9a84abb22895c704debd260884081f 100644 --- a/docs-cn/04-develop/01-connect/_connect_java.mdx +++ b/docs-cn/04-develop/01-connect/_connect_java.mdx @@ -1,10 +1,10 @@ -```java title="本地连接" +```java title="原生连接" {{#include docs-examples/java/src/main/java/com/taos/example/JNIConnectExample.java}} ``` -```java title="RESTful 连接" +```java title="REST 连接" {{#include docs-examples/java/src/main/java/com/taos/example/RESTConnectExample.java:main}} ``` -使用RESTful 连接时，如果查询数据量比较大，还可开启批量拉取功能。 +使用REST 连接时，如果查询数据量比较大，还可开启批量拉取功能。 ```java title="开启批量拉取功能" {4} {{#include docs-examples/java/src/main/java/com/taos/example/WSConnectExample.java:main}} ``` diff --git a/docs-cn/04-develop/01-connect/_connect_node.mdx b/docs-cn/04-develop/01-connect/_connect_node.mdx index 9e54159a9464c512ced5a0e3b61625388190314e..8a259888f87d4d441c58b9a8a9008b19273c1a58 100644 --- a/docs-cn/04-develop/01-connect/_connect_node.mdx +++ b/docs-cn/04-develop/01-connect/_connect_node.mdx @@ -1,6 +1,6 @@ -```js title="本地连接" +```js title="原生连接" {{#include docs-examples/node/nativeexample/connect.js}} ``` -```js title="RESTful 连接" +```js title="REST 连接" {{#include docs-examples/node/restexample/connect.js}} ``` \ No newline at end of file diff --git a/docs-cn/04-develop/01-connect/_connect_python.mdx b/docs-cn/04-develop/01-connect/_connect_python.mdx index 0f90860d0cce31cce9e65be2bc9ddbea3702c760..331ec0f693601baeb28ede7b0278e67f1471c187 100644 --- a/docs-cn/04-develop/01-connect/_connect_python.mdx +++ b/docs-cn/04-develop/01-connect/_connect_python.mdx @@ -1,3 +1,3 @@ -```python title="本地连接" +```python title="原生连接" {{#include docs-examples/python/connect_exmaple.py}} ``` \ No newline at end of file diff --git a/docs-cn/04-develop/01-connect/_connect_r.mdx b/docs-cn/04-develop/01-connect/_connect_r.mdx index c1eea10151b906ce6d16170b18864bdb975bb67d..a69a57f66be3672d61cb0f84f43aba123cfbd5aa 100644 --- a/docs-cn/04-develop/01-connect/_connect_r.mdx +++ b/docs-cn/04-develop/01-connect/_connect_r.mdx @@ -1,3 +1,3 @@ -```r title="本地连接" +```r title="原生连接" {{#include docs-examples/R/connect_native.r:demo}} ``` \ No newline at end of file diff --git a/docs-cn/04-develop/01-connect/_connect_rust.mdx b/docs-cn/04-develop/01-connect/_connect_rust.mdx index 7e3ab13649b3533ead96020eee3eb44f2264b163..b051108452d16f207ce10b128f5de2e5f507200f 100644 --- a/docs-cn/04-develop/01-connect/_connect_rust.mdx +++ b/docs-cn/04-develop/01-connect/_connect_rust.mdx @@ -1,4 +1,4 @@ -```rust title="本地连接/RESTful 连接" +```rust title="原生连接/REST 连接" {{#include docs-examples/rust/nativeexample/examples/connect.rs}} ``` :::note diff --git a/docs-cn/04-develop/01-connect/index.md b/docs-cn/04-develop/01-connect/index.md index 850263eef6e280eff31be2f3a62e686533ab3c5b..23d4816d01277b20a1e2a35173eca7e84eb5b4e3 100644 --- a/docs-cn/04-develop/01-connect/index.md +++ b/docs-cn/04-develop/01-connect/index.md @@ -1,6 +1,6 @@ --- title: 建立连接 ---- +--- import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem"; @@ -17,24 +17,25 @@ 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 提供 RESTful 接口，容许在任何平台的任何应用程序通过它访问TDengine运行实例，详细介绍请看 [REST API](/reference/rest-api/)。除 REST API 之外，TDengine 还提供多种编程语言的连接器方便用户开发应用程序，其中包括 C/C++、Java、Python、Go、Node.js、C# 等。 本节介绍如何使用连接器建立与 TDengine 的连接，给出连接器安装、连接的简单说明。关于各连接器的详细功能说明，请查看[连接器](https://docs.taosdata.com/reference/connector/) +TDengine 提供 RESTful 接口，容许在任何平台的任何应用程序通过它访问 TDengine 运行实例，详细介绍请看 [REST API](/reference/rest-api/)。除 REST API 之外，TDengine 还提供多种编程语言的连接器方便用户开发应用程序，其中包括 C/C++、Java、Python、Go、Node.js、C# 等。 本节介绍如何使用连接器建立与 TDengine 的连接，给出连接器安装、连接的简单说明。关于各连接器的详细功能说明，请查看[连接器](https://docs.taosdata.com/reference/connector/) ## 连接器建立连接的方式 -连接器建立连接的方式，TDengine提供两种: - 1. 通过 taosAdapter 组件提供的 REST API 建立与 taosd 的连接，这种连接方式下文中简称"RESTful 连接“ - 2. 通过客户端驱动程序 taosc 直接与服务端程序 taosd 建立连接，这种连接方式下文中简称“本地连接”。 +连接器建立连接的方式，TDengine 提供两种: + +1. 通过 taosAdapter 组件提供的 REST API 建立与 taosd 的连接，这种连接方式下文中简称"REST 连接“ +2. 通过客户端驱动程序 taosc 直接与服务端程序 taosd 建立连接，这种连接方式下文中简称“原生连接”。 无论使用何种方式建立连接，连接器都提供了相同或相似的 API 操作数据库，都可以执行 SQL 语句，只是初始化连接的方式稍有不同，用户在使用上不会感到什么差别。 关键不同点在于： -1. 使用 RESTful 连接，用户无需安装客户端驱动程序 taosc，具有跨平台易用的优势，但性能要下降30%左右。 -2. 使用本地连接可以体验 TDengine 的全部功能，如[原生接口写入](/reference/connector/cpp#参数绑定-api)、[订阅](reference/connector/cpp#数据订阅接口)等等。 +1. 使用 REST 连接，用户无需安装客户端驱动程序 taosc，具有跨平台易用的优势，但性能要下降 30%左右。 +2. 使用原生连接可以体验 TDengine 的全部功能，如[原生接口写入](/reference/connector/cpp#参数绑定-api)、[订阅](reference/connector/cpp#数据订阅接口)等等。 ## 安装客户端驱动 taosc -如果选择本地连接，而且应用程序不在 TDengine 同一台服务器上运行，你需要先安装客户端驱动，否则可以跳过此一步。为避免客户端驱动和服务端不兼容，请使用一致的版本。 +如果选择原生连接，而且应用程序不在 TDengine 同一台服务器上运行，你需要先安装客户端驱动，否则可以跳过此一步。为避免客户端驱动和服务端不兼容，请使用一致的版本。 ### 安装步骤 @@ -79,10 +80,13 @@ TDengine 提供 RESTful 接口，容许在任何平台的任何应用程序通 使用 `pip` 从 PyPI 安装: + ``` pip install taospy ``` + 从 Git URL 安装： + ``` pip install git+https://github.com/taosdata/taos-connector-python.git ``` @@ -91,6 +95,7 @@ pip install git+https://github.com/taosdata/taos-connector-python.git 编辑 `go.mod` 添加 `driver-go` 依赖即可。 + ```go-mod title=go.mod module goexample @@ -98,6 +103,7 @@ go 1.17 require github.com/taosdata/driver-go/v2 develop ``` + :::note driver-go 使用 cgo 封装了 taosc 的 API。cgo 需要使用 gcc 编译 C 的源码。因此需要确保你的系统上有 gcc。 @@ -107,12 +113,15 @@ driver-go 使用 cgo 封装了 taosc 的 API。cgo 需要使用 gcc 编译 C 的 编辑 `Cargo.toml` 添加 `libtaos` 依赖即可。 + ```toml title=Cargo.toml [dependencies] libtaos = { version = "0.4.2"} ``` + :::info -Rust 连接器通过不同的特性区分不同的连接方式。如果要建立 RESTful 连接，需要开启 `rest` 特性： +Rust 连接器通过不同的特性区分不同的连接方式。如果要建立 REST 连接，需要开启 `rest` 特性： + ```toml libtaos = { version = "*", features = ["rest"] } ``` @@ -124,18 +133,20 @@ libtaos = { version = "*", features = ["rest"] } Node.js 连接器通过不同的包提供不同的连接方式。 -1. 安装 Node.js 本地连接器 - ``` - npm i td2.0-connector - ``` - :::note - 推荐Node版本大于等于 `node-v12.8.0` 小于 `node-v13.0.0` +1. 安装 Node.js 原生连接器 - ::: -2. 安装 Node.js RESTful 连接器 - ``` - npm i td2.0-rest-connector - ``` +``` +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 +``` @@ -159,12 +170,15 @@ Node.js 连接器通过不同的包提供不同的连接方式。 ``` + 也可通过 dotnet 命令添加： + ``` dotnet add package TDengine.Connector ``` -:::note -以下示例代码，均基于 dotnet6.0，如果使用其它版本，可能需要做适当调整。 + +:::note +以下示例代码，均基于 dotnet6.0，如果使用其它版本，可能需要做适当调整。 ::: @@ -173,9 +187,11 @@ dotnet add package TDengine.Connector 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") ``` + @@ -185,10 +201,9 @@ install.packages("RJDBC") - ## 建立连接 -在执行这一步之前，请确保有一个正在运行的，且可以访问到的 TDengine，而且服务端的FQDN配置正确。以下示例代码，都假设 TDengine 安装在本机，且 FQDN（默认 localhost） 和 serverPort（默认 6030） 都使用默认配置。 +在执行这一步之前，请确保有一个正在运行的，且可以访问到的 TDengine，而且服务端的 FQDN 配置正确。以下示例代码，都假设 TDengine 安装在本机，且 FQDN（默认 localhost） 和 serverPort（默认 6030） 都使用默认配置。 @@ -218,8 +233,6 @@ install.packages("RJDBC") :::tip -如果建立连接失败，大部分情况下是FQDN或防火墙的配置不正确，详细的排查方法请看[《常见问题及反馈》](https://docs.taosdata.com/train-fqa/faq)中的“遇到错误Unable to establish connection, 我怎么办？” +如果建立连接失败，大部分情况下是 FQDN 或防火墙的配置不正确，详细的排查方法请看[《常见问题及反馈》](https://docs.taosdata.com/train-fqa/faq)中的“遇到错误 Unable to establish connection, 我怎么办？” ::: - - 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 index ed6d504f0551ed829d024fad37d22ed278ac5ab4..e0536d9548ef0530e8a1da8713628b1c234bf488 100644 --- a/docs-cn/04-develop/03-insert-data/01-sql-writing.mdx +++ b/docs-cn/04-develop/03-insert-data/01-sql-writing.mdx @@ -101,7 +101,7 @@ INSERT INTO d1001 VALUES (1538548685000, 10.3, 219, 0.31) (1538548695000, 12.6, TDengine 也提供了支持参数绑定的 Prepare API，与 MySQL 一样，这些 API 目前也仅支持用问号 `?` 来代表待绑定的参数。文档中有时也会把此功能称为“原生接口写入”。从 2.1.1.0 和 2.1.2.0 版本开始，TDengine 大幅改进了参数绑定接口对数据写入（INSERT）场景的支持。这样在通过参数绑定接口写入数据时，就避免了 SQL 语法解析的资源消耗，从而在绝大多数情况下显著提升写入性能。 -需要注意的是，只有使用本地连接的连接器，才能使用动态绑定功能。 +需要注意的是，只有使用原生连接的连接器，才能使用动态绑定功能。 diff --git a/docs-cn/04-develop/04-query-data/index.mdx b/docs-cn/04-develop/04-query-data/index.mdx index 43d46855f1a0f8b62e3dcac2d64c9a1686a34da9..02e20a7418fb341f0eb6326d576b1ec5487e38c3 100644 --- a/docs-cn/04-develop/04-query-data/index.mdx +++ b/docs-cn/04-develop/04-query-data/index.mdx @@ -1,6 +1,7 @@ --- slug: /query-data title: 查询数据 +description: "主要查询功能，通过连接器执行同步查询和异步查询" --- import Tabs from "@theme/Tabs"; @@ -19,7 +20,7 @@ import CAsync from "./_c_async.mdx"; ## 主要查询功能 -TDengine 采用 SQL 作为查询语言。应用程序可以通过RESTful接口或连接器发送 SQL 语句，用户还可以通过 TDengine 命令行工具 taos 手动执行 SQL 即席查询（Ad-Hoc Query）。TDengine 支持如下查询功能： +TDengine 采用 SQL 作为查询语言。应用程序可以通过 REST API 或连接器发送 SQL 语句，用户还可以通过 TDengine 命令行工具 taos 手动执行 SQL 即席查询（Ad-Hoc Query）。TDengine 支持如下查询功能： - 单列、多列数据查询 - 标签和数值的多种过滤条件：>, <, =, <\>, like 等 @@ -61,6 +62,7 @@ Query OK, 2 row(s) in set (0.002136s) ``` #### 示例二 + 在 TAOS shell, 查找 groupId 为 2 的所有智能电表过去 24 小时的记录条数，电流的最大值。 ``` @@ -152,7 +154,7 @@ Query OK, 5 row(s) in set (0.001521s) :::note -1. 无论是使用 RESTful 连接还是本地连接的连接器，以上示例代码都能正常工作。 +1. 无论是使用 REST 连接还是原生连接的连接器，以上示例代码都能正常工作。 2. 唯一需要注意的是：由于 RESTful 接口无状态， 不能使用 `use db` 语句来切换数据库。 ::: @@ -161,7 +163,7 @@ Query OK, 5 row(s) in set (0.001521s) 除同步查询 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 index 1934d8c39e3d7f91239f0d7797798459cfe3ae62..2fd1b3cc755188f513fe511541a84efa3558d3ea 100644 --- a/docs-cn/04-develop/05-continuous-query.mdx +++ b/docs-cn/04-develop/05-continuous-query.mdx @@ -1,10 +1,9 @@ --- sidebar_label: 连续查询 description: "连续查询是一个按照预设频率自动执行的查询功能，提供按照时间窗口的聚合查询能力，是一种简化的时间驱动流式计算。" +title: "连续查询（Continuous Query）" --- -# 连续查询（Continuous Query） - 连续查询是 TDengine 定期自动执行的查询，采用滑动窗口的方式进行计算，是一种简化的时间驱动的流式计算。针对库中的表或超级表，TDengine 可提供定期自动执行的连续查询，用户可让 TDengine 推送查询的结果，也可以将结果再写回到 TDengine 中。每次执行的查询是一个时间窗口，时间窗口随着时间流动向前滑动。在定义连续查询的时候需要指定时间窗口（time window, 参数 interval）大小和每次前向增量时间（forward sliding times, 参数 sliding）。 TDengine 的连续查询采用时间驱动模式，可以直接使用 TAOS SQL 进行定义，不需要额外的操作。使用连续查询，可以方便快捷地按照时间窗口生成结果，从而对原始采集数据进行降采样（down sampling）。用户通过 TAOS SQL 定义连续查询以后，TDengine 自动在最后的一个完整的时间周期末端拉起查询，并将计算获得的结果推送给用户或者写回 TDengine。 diff --git a/docs-cn/04-develop/06-subscribe.mdx b/docs-cn/04-develop/06-subscribe.mdx index d329c84c27f609ca2907c258316ac41a23878a98..bf5b2c138e2182df8ed8baf9442a7b7ed6d62f2f 100644 --- a/docs-cn/04-develop/06-subscribe.mdx +++ b/docs-cn/04-develop/06-subscribe.mdx @@ -1,10 +1,9 @@ --- sidebar_label: 数据订阅 description: "轻量级的数据订阅与推送服务。连续写入到 TDengine 中的时序数据能够被自动推送到订阅客户端。" +title: 数据订阅 --- -# 数据订阅 - import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem"; import Java from "./_sub_java.mdx"; diff --git a/docs-cn/04-develop/_category_.yml b/docs-cn/04-develop/_category_.yml index 509a9405c42939a4819b87669a4c5b244bd29a8b..83687164926268d4ae4cbe897006dde89d2e2c7b 100644 --- a/docs-cn/04-develop/_category_.yml +++ b/docs-cn/04-develop/_category_.yml @@ -1 +1,4 @@ -label: 开发指南 \ No newline at end of file +label: 开发指南 +link: + slug: /develop + type: generated-index \ No newline at end of file diff --git a/docs-cn/12-taos-sql/02-database.md b/docs-cn/12-taos-sql/02-database.md index 863cdc2e7688bb872b13024a93315d21fb824945..764b0ad12204c8abc4a78e0d0ced3e47fe806af4 100644 --- a/docs-cn/12-taos-sql/02-database.md +++ b/docs-cn/12-taos-sql/02-database.md @@ -34,7 +34,7 @@ SHOW VARIABLES; USE db_name; ``` -使用/切换数据库（在 RESTful 连接方式下无效）。 +使用/切换数据库（在 REST 连接方式下无效）。 ## 删除数据库 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 index e37f518f950fd833c5f0acbe8828970159cf6b48..42f93fce0d325eb5c42392bcffb678b113612961 100644 --- a/docs-cn/14-reference/02-rest-api/02-rest-api.mdx +++ b/docs-cn/14-reference/02-rest-api/02-rest-api.mdx @@ -2,7 +2,7 @@ title: REST API --- -为支持各种不同类型平台的开发，TDengine 提供符合 REST 设计标准的 API，即 REST API。为最大程度降低学习成本，不同于其他数据库 REST API 的设计方法，TDengine 直接通过 HTTP POST 请求 BODY 中包含的 SQL 语句来操作数据库，仅需要一个 URL。RESTful 连接器的使用参见[视频教程](https://www.taosdata.com/blog/2020/11/11/1965.html)。 +为支持各种不同类型平台的开发，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。） diff --git a/docs-cn/14-reference/03-connector/03-connector.mdx b/docs-cn/14-reference/03-connector/03-connector.mdx index 7b799b0044edbd46bf1fc0b13bbbb21a81c9f86b..0badf1e13fc2d5cd89d69badf249f1a7ba74a8b0 100644 --- a/docs-cn/14-reference/03-connector/03-connector.mdx +++ b/docs-cn/14-reference/03-connector/03-connector.mdx @@ -80,7 +80,7 @@ import VerifyLinux from "./_verify_linux.mdx"; ## 安装客户端驱动 :::info -只有在没有安装 TDengine 服务端软件的系统上使用非 RESTful 连接器才需要安装客户端驱动。 +只有在没有安装 TDengine 服务端软件的系统上使用非 REST 连接器才需要安装客户端驱动。 ::: diff --git a/docs-cn/14-reference/03-connector/cpp.mdx b/docs-cn/14-reference/03-connector/cpp.mdx index f0b206d3e7c58c355b2f06e8a8b6e14bbb569ab6..3dcf2623b8a2f16ba8bf42f54590bdb1653945b9 100644 --- a/docs-cn/14-reference/03-connector/cpp.mdx +++ b/docs-cn/14-reference/03-connector/cpp.mdx @@ -199,7 +199,7 @@ TDengine 的异步 API 均采用非阻塞调用模式。应用程序可以用多 说明：如果 `taos_stmt_execute` 执行成功，假如不需要改变 SQL 语句的话，那么是可以复用 `taos_stmt_prepare` 的解析结果，直接进行第 3 ～ 6 步绑定新数据的。但如果执行出错，那么并不建议继续在当前的环境上下文下继续工作，而是建议释放资源，然后从 `taos_stmt_init` 步骤重新开始。 -除 C/C++ 语言外，TDengine 的 Java 语言本地连接 Connector 也提供参数绑定接口支持，具体请另外参见：[参数绑定接口的 Java 用法](/reference/connector/java#通过参数绑定写入数据)。 +除 C/C++ 语言外，TDengine 的 Java 语言原生连接 Connector 也提供参数绑定接口支持，具体请另外参见：[参数绑定接口的 Java 用法](/reference/connector/java#通过参数绑定写入数据)。 接口相关的具体函数如下（也可以参考 [prepare.c](https://github.com/taosdata/TDengine/blob/develop/examples/c/prepare.c) 文件中使用对应函数的方式）： diff --git a/docs-cn/14-reference/03-connector/go.mdx b/docs-cn/14-reference/03-connector/go.mdx index 0a61e3e65244b2f19c49c9cd098d818118f285a4..7299ec281820cb01ee5b981c7822367a36362b0b 100644 --- a/docs-cn/14-reference/03-connector/go.mdx +++ b/docs-cn/14-reference/03-connector/go.mdx @@ -26,9 +26,9 @@ Go 连接器的源码托管在 github。项目名称：driver-go。欢迎 [贡 ## 支持的特性 -### 本地连接 +### 原生连接 -`本地连接` 指连接器通过本地的客户端驱动程序直接与服务端程序 taosd 建立连接。 +`原生连接` 指连接器通过本地的客户端驱动程序直接与服务端程序 taosd 建立连接。 * database/sql (cgo 模式) * 订阅 @@ -74,7 +74,7 @@ REST 连接指连接器通过 taosAdapter 组件提供的 REST API 建立与 tao username:password@protocol(address)/dbname?param=value ``` -### 建立本地连接 +### 建立原生连接 _taosSql_ 通过 cgo 实现了 Go 的 `database/sql/driver` 接口。只需要引入驱动就可以使用[`database/sql`](https://golang.org/pkg/database/sql/)的接口。 diff --git a/docs-cn/14-reference/03-connector/java.mdx b/docs-cn/14-reference/03-connector/java.mdx index 13dcc1cdf40e5db8122b4d8a0f47116940a94634..28770b6f41b22a2a1c06838eb4c745acb1b2f146 100644 --- a/docs-cn/14-reference/03-connector/java.mdx +++ b/docs-cn/14-reference/03-connector/java.mdx @@ -7,15 +7,15 @@ description: 此连接器基于标准 JDBC API 实现。 ## 总体介绍 -`taos-jdbcdriver` 的实现包括两种形式： JDBC 本地连接和 JDBC-REST（taos-jdbcdriver-2.0.18 开始支持 JDBC-RESTful）。 JDBC 本地连接通过调用客户端驱动 libtaos.so（或 taos.dll ）的本地方法实现， JDBC-RESTful 则通过封装 TDengine REST 服务接口建立连接，REST 连接实现的功能集合和本地连接有少量不同。 +`taos-jdbcdriver` 的实现包括两种形式： JDBC 原生连接和 JDBC-REST（taos-jdbcdriver-2.0.18 开始支持 JDBC-RESTful）。 JDBC 原生连接通过调用客户端驱动 libtaos.so（或 taos.dll ）的本地方法实现， JDBC-RESTful 则通过封装 TDengine REST 服务接口建立连接，REST 连接实现的功能集合和原生连接有少量不同。 ![tdengine-connector](/img/tdengine-jdbc-connector.png) 上图显示了三种 Java 应用使用连接器访问 TDengine 的方式： -- JDBC 本地连接：Java 应用在物理节点 1（pnode1）上使用 JDBC 本地连接的 API ，直接调用客户端驱动（libtaos.so 或 taos.dll）的 API 将写入和查询请求发送到位于物理节点 2（pnode2）上的 taosd 实例。 -- RESTful：应用将 SQL 发送给位于物理节点 2（pnode2）上的 RESTful 连接器，再调用客户端驱动 API。 -- JDBC-RESTful：Java 应用通过 JDBC-RESTful 的 API ，将 SQL 封装成一个 RESTful 请求，发送给物理节点 2 的 RESTful 连接器。 +- JDBC 原生连接：Java 应用在物理节点 1（pnode1）上使用 JDBC 原生连接的 API ，直接调用客户端驱动（libtaos.so 或 taos.dll）的 API 将写入和查询请求发送到位于物理节点 2（pnode2）上的 taosd 实例。 +- RESTful：应用将 SQL 发送给位于物理节点 2（pnode2）上的 REST 连接器，再调用客户端驱动 API。 +- JDBC-RESTful：Java 应用通过 JDBC-RESTful 的 API ，将 SQL 封装成一个 RESTful 请求，发送给物理节点 2 的 REST 连接器。 TDengine 的 JDBC 驱动实现尽可能与关系型数据库驱动保持一致，但 TDengine 与关系对象型数据库的使用场景和技术特征存在差异，导致 `taos-jdbcdriver` 与传统的 JDBC driver 也存在一定差异。在使用时需要注意以下几点： @@ -27,7 +27,7 @@ TDengine 的 JDBC 驱动实现尽可能与关系型数据库驱动保持一致 - + @@ -47,17 +47,17 @@ TDengine 的 JDBC 驱动实现尽可能与关系型数据库驱动保持一致 - + - +
对比项JDBC 本地连接JDBC 原生连接 JDBC-RESTful
写入性能JDBC-RESTful 是 JDBC 本地连接的 50%～90% JDBC-RESTful 是 JDBC 原生连接的 50%～90%
查询性能JDBC-RESTful 与 JDBC 本地连接没有差别JDBC-RESTful 与 JDBC 原生连接没有差别
**注意**： -- 与本地连接方式不同，RESTful 接口是无状态的。在使用 JDBC-RESTful 时，需要在 SQL 中指定表、超级表的数据库名称。例如： +- 与原生连接方式不同，RESTful 接口是无状态的。在使用 JDBC-RESTful 时，需要在 SQL 中指定表、超级表的数据库名称。例如： ```sql INSERT INTO test.t1 USING test.weather (ts, temperature) TAGS('beijing') VALUES(now, 24.6); @@ -108,7 +108,7 @@ TDengine 目前支持时间戳、数字、字符、布尔类型，与 Java 对 1. Linux 或 Windows 操作系统 2. 已安装 Java 1.8 及以上运行时环境 3. 已安装 maven 3.6 及以上版本 -4. 已安装 TDengine-client（使用 JDBC 本地连接必须安装，使用 JDBC-RESTful 无需安装） +4. 已安装 TDengine-client（使用 JDBC 原生连接必须安装，使用 JDBC-RESTful 无需安装） **注意**：由于 TDengine 的应用驱动是使用 C 语言开发的，使用 taos-jdbcdriver 驱动包时需要依赖系统对应的本地函数库。 @@ -152,7 +152,7 @@ mvn clean install -Dmaven.test.skip=true 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}]` -### 建立本地连接 +### 建立原生连接 ```java Class.forName("com.taosdata.jdbc.TSDBDriver"); @@ -160,9 +160,9 @@ String jdbcUrl = "jdbc:TAOS://taosdemo.com:6030/test?user=root&password=taosdata Connection conn = DriverManager.getConnection(jdbcUrl); ``` -以上示例，使用了 JDBC 本地连接的 driver，建立了到 hostname 为 taosdemo.com，端口为 6030（TDengine 的默认端口），数据库名为 test 的连接。这个 URL 中指定用户名（user）为 root，密码（password）为 taosdata。 +以上示例，使用了 JDBC 原生连接的 driver，建立了到 hostname 为 taosdemo.com，端口为 6030（TDengine 的默认端口），数据库名为 test 的连接。这个 URL 中指定用户名（user）为 root，密码（password）为 taosdata。 -**注意**：使用 JDBC 本地连接的 driver，taos-jdbcdriver 驱动包时需要依赖系统对应的本地客户端驱动（Linux 下是 libtaos.so；Windows 下是 taos.dll）。 +**注意**：使用 JDBC 原生连接的 driver，taos-jdbcdriver 驱动包时需要依赖系统对应的本地客户端驱动（Linux 下是 libtaos.so；Windows 下是 taos.dll）。 url 中的配置参数如下： @@ -175,11 +175,11 @@ url 中的配置参数如下： - batchfetch: true：在执行查询时批量拉取结果集；false：逐行拉取结果集。默认值为：false。开启批量拉取同时获取一批数据在查询数据量较大时批量拉取可以有效的提升查询性能。 - batchErrorIgnore：true：在执行 Statement 的 executeBatch 时，如果中间有一条 SQL 执行失败将继续执行下面的 SQL。false：不再执行失败 SQL 后的任何语句。默认值为：false。 -JDBC 本地连接的使用请参见[视频教程](https://www.taosdata.com/blog/2020/11/11/1955.html)。 +JDBC 原生连接的使用请参见[视频教程](https://www.taosdata.com/blog/2020/11/11/1955.html)。 #### 使用客户端配置文件建立连接 -当使用 JDBC 本地连接连接 TDengine 集群时，可以使用客户端配置文件，在客户端配置文件中指定集群的 firstEp、secondEp 参数。如下所示： +当使用 JDBC 原生连接连接 TDengine 集群时，可以使用客户端配置文件，在客户端配置文件中指定集群的 firstEp、secondEp 参数。如下所示： 1. 在 Java 应用中不指定 hostname 和 port @@ -218,7 +218,7 @@ TDengine 中，只要保证 firstEp 和 secondEp 中一个节点有效，就可 > **注意**：这里的配置文件指的是调用 JDBC Connector 的应用程序所在机器上的配置文件，Linux OS 上默认值 /etc/taos/taos.cfg ，Windows OS 上默认值 C://TDengine/cfg/taos.cfg。 -### 建立 RESTful 连接 +### 建立 REST 连接 ```java Class.forName("com.taosdata.jdbc.rs.RestfulDriver"); @@ -228,7 +228,7 @@ Connection conn = DriverManager.getConnection(jdbcUrl); 以上示例，使用 **JDBC-RESTful** 的 driver，建立了到 hostname 为 taosdemo.com，端口为 6041，数据库名为 test 的连接。这个 URL 中指定用户名（user）为 root，密码（password）为 taosdata。 -使用 JDBC-RESTful 接口，不需要依赖本地函数库。与 JDBC 本地连接相比，仅需要： +使用 JDBC-RESTful 接口，不需要依赖本地函数库。与 JDBC 原生连接相比，仅需要： 1. driverClass 指定为“com.taosdata.jdbc.rs.RestfulDriver”； 2. jdbcUrl 以“jdbc:TAOS-RS://”开头； @@ -240,7 +240,7 @@ Connection conn = DriverManager.getConnection(jdbcUrl); - timestampFormat: 'TIMESTAMP'：结果集中 timestamp 类型的字段为一个 long 值; 'UTC'：结果集中 timestamp 类型的字段为一个 UTC 时间格式的字符串; 'STRING'：结果集中 timestamp 类型的字段为一个本地时间格式的字符串。默认值为'STRING'。 - batchErrorIgnore：true：在执行 Statement 的 executeBatch 时，如果中间有一条 SQL 执行失败，继续执行下面的 SQL 了。false：不再执行失败 SQL 后的任何语句。默认值为：false。 -**注意**：部分配置项（比如：locale、timezone）在 RESTful 连接中不生效。 +**注意**：部分配置项（比如：locale、timezone）在 REST 连接中不生效。 ### 指定 URL 和 Properties 获取连接 @@ -267,10 +267,10 @@ properties 中的配置参数如下： - TSDBDriver.PROPERTY_KEY_USER：登录 TDengine 用户名，默认值 'root'。 - TSDBDriver.PROPERTY_KEY_PASSWORD：用户登录密码，默认值 'taosdata'。 -- 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 本地连接时生效。 客户端使用的时区，默认值为系统当前时区。 +- 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 原生连接时生效。 客户端使用的时区，默认值为系统当前时区。 - TSDBDriver.PROPERTY_KEY_BATCH_LOAD: true：在执行查询时批量拉取结果集；false：逐行拉取结果集。默认值为：false。 - TSDBDriver.PROPERTY_KEY_TIMESTAMP_FORMAT: 仅在使用 JDBC-RESTful 时生效。 'TIMESTAMP'：结果集中 timestamp 类型的字段为一个 long 值; 'UTC'：结果集中 timestamp 类型的字段为一个 UTC 时间格式的字符串; 'STRING'：结果集中 timestamp 类型的字段为一个本地时间格式的字符串。默认值为'STRING'。 - TSDBDriver.PROPERTY_KEY_BATCH_ERROR_IGNORE：true：在执行 Statement 的 executeBatch 时，如果中间有一条 SQL 执行失败，继续执行下面的 sq 了。false：不再执行失败 SQL 后的任何语句。默认值为：false。 @@ -356,7 +356,7 @@ try (Statement statement = connection.createStatement()) { } ``` -JDBC 连接器可能报错的错误码包括 3 种：JDBC driver 本身的报错（错误码在 0x2301 到 0x2350 之间），本地连接方法的报错（错误码在 0x2351 到 0x2400 之间），TDengine 其他功能模块的报错。 +JDBC 连接器可能报错的错误码包括 3 种：JDBC driver 本身的报错（错误码在 0x2301 到 0x2350 之间），原生连接方法的报错（错误码在 0x2351 到 0x2400 之间），TDengine 其他功能模块的报错。 具体的错误码请参考： @@ -365,7 +365,7 @@ JDBC 连接器可能报错的错误码包括 3 种：JDBC driver 本身的报错 ### 通过参数绑定写入数据 -从 2.1.2.0 版本开始，TDengine 的 JDBC 本地连接实现大幅改进了参数绑定方式对数据写入（INSERT）场景的支持。采用这种方式写入数据时，能避免 SQL 语法解析的资源消耗，从而在很多情况下显著提升写入性能。 +从 2.1.2.0 版本开始，TDengine 的 JDBC 原生连接实现大幅改进了参数绑定方式对数据写入（INSERT）场景的支持。采用这种方式写入数据时，能避免 SQL 语法解析的资源消耗，从而在很多情况下显著提升写入性能。 **注意**： @@ -675,7 +675,7 @@ public class SchemalessInsertTest { ### 设置客户端参数 -从 TDengine-2.3.5.0 版本开始，jdbc driver 支持在应用的第一次连接中，设置 TDengine 的客户端参数。Driver 支持 JDBC 本地连接方式中，通过 jdbcUrl 和 properties 两种方式设置 client parameter。 +从 TDengine-2.3.5.0 版本开始，jdbc driver 支持在应用的第一次连接中，设置 TDengine 的客户端参数。Driver 支持 JDBC 原生连接方式中，通过 jdbcUrl 和 properties 两种方式设置 client parameter。 **注意**： diff --git a/docs-cn/14-reference/03-connector/node.mdx b/docs-cn/14-reference/03-connector/node.mdx index 267f5ea9822f70037dd219d91099fc90fc8686d1..17cf287533b1bc55dcaa7d41281e250947dbdd3f 100644 --- a/docs-cn/14-reference/03-connector/node.mdx +++ b/docs-cn/14-reference/03-connector/node.mdx @@ -202,12 +202,12 @@ promise2.then(function (result) { [所有示例代码](https://github.com/taosdata/TDengine/tree/develop/src/connector/nodejs/examples) -## 使用 RESTful 连接器 +## 使用 REST 连接器 -TDengine 还提供 TypeScript 的 RESTful 连接器。 +TDengine 还提供 TypeScript 的 REST 连接器。 注意：`td2.0-rest-connector` 依赖 [node-fetch v2](https://github.com/node-fetch/node-fetch/tree/2.x) 。 -### RESTful 连接器的使用 +### REST 连接器的使用 * 安装连接器