From d72eacc7216614fdc09b130945b15586799246f4 Mon Sep 17 00:00:00 2001 From: sheyanjie-qq <249478495@qq.com> Date: Fri, 6 Dec 2024 18:11:54 +0800 Subject: [PATCH 1/7] update version history of connector doc --- docs/zh/14-reference/05-connector/14-java.mdx | 56 +++++++++---------- docs/zh/14-reference/05-connector/26-rust.mdx | 26 ++++----- docs/zh/14-reference/05-connector/50-odbc.mdx | 6 +- 3 files changed, 44 insertions(+), 44 deletions(-) diff --git a/docs/zh/14-reference/05-connector/14-java.mdx b/docs/zh/14-reference/05-connector/14-java.mdx index e8554ae668..a90d66235e 100644 --- a/docs/zh/14-reference/05-connector/14-java.mdx +++ b/docs/zh/14-reference/05-connector/14-java.mdx @@ -21,43 +21,43 @@ TDengine 的 JDBC 驱动实现尽可能与关系型数据库驱动保持一致 ## JDBC 和 JRE 兼容性 -- JDBC: 支持 JDBC 4.2 版本，部分功能如无模式写入和数据订阅单独提供 -- JRE: 支持 JRE 8 及以上版本 +- JDBC: 支持 JDBC 4.2 及以上版本。 +- JRE: 支持 JRE 8 及以上版本。 ## 支持的平台 -原生连接支持的平台和 TDengine 客户端驱动支持的平台一致。 -REST 连接支持所有能运行 Java 的平台。 +- 原生连接支持的平台和 TDengine 客户端驱动支持的平台一致。 +- WebSocket/REST 连接支持所有能运行 Java 的平台。 ## 版本历史 | taos-jdbcdriver 版本 | 主要变化 | TDengine 版本 | -| :------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------: | :----------------: | -| 3.4.0 | 1. 使用 jackson 库替换 fastjson 库；2. WebSocket 采用独立协议标识；3. 优化后台拉取线程使用，避免用户误用导致超时。 | - | -| 3.3.4 | 1. 解决了 getInt 在数据类型为 float 报错 | - | -| 3.3.3 | 1. 解决了 WebSocket statement 关闭导致的内存泄漏 | - | -| 3.3.2 | 1. 优化 WebSocket 连接下的参数绑定性能；2. 优化了对 mybatis 的支持 | - | -| 3.3.0 | 1. 优化 WebSocket 连接下的数据传输性能；2. 支持跳过 SSL 验证，默认关闭 | 3.3.2.0 及更高版本 | +| :------------------| :---------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------- | +| 3.4.0 | 1. 使用 jackson 库替换 fastjson 库
2. WebSocket 采用独立协议标识
3. 优化后台拉取线程使用，避免用户误用导致超时 | - | +| 3.3.4 | 解决了 getInt 在数据类型为 float 报错 | - | +| 3.3.3 | 解决了 WebSocket statement 关闭导致的内存泄漏 | - | +| 3.3.2 | 1. 优化 WebSocket 连接下的参数绑定性能
2. 优化了对 mybatis 的支持 | - | +| 3.3.0 | 1. 优化 WebSocket 连接下的数据传输性能
2. 支持跳过 SSL 验证，默认关闭 | 3.3.2.0 及更高版本 | | 3.2.11 | 解决了 Native 连接关闭结果集 bug | - | -| 3.2.10 | 1. REST/WebSocket 连接支持传输中的数据压缩；2. WebSocket 自动重连机制，默认关闭；3. Connection 类提供无模式写入的方法；4. 优化了原生连接的数据拉取性能；5. 修复了一些已知问题；6.元数据获取函数可以返回支持的函数列表。 | - | +| 3.2.10 | 1. REST/WebSocket 连接支持传输中的数据压缩
2. WebSocket 自动重连机制，默认关闭
3. Connection 类提供无模式写入的方法
4. 优化了原生连接的数据拉取性能
5. 修复了一些已知问题
6.元数据获取函数可以返回支持的函数列表 | - | | 3.2.9 | 解决了 WebSocket prepareStatement 关闭 bug | - | -| 3.2.8 | 优化了自动提交, 解决了 WebSocket 手动提交 bug, 优化 WebSocket prepareStatement 使用一个连接, 元数据支持视图 | - | -| 3.2.7 | 支持 VARBINARY 和 GEOMETRY 类型，增加 native 连接的时区设置支持。增加 WebSocket 自动重连功能。 | 3.2.0.0 及更高版本 | -| 3.2.5 | 数据订阅增加 committed()、assignment() 方法 | 3.1.0.3 及更高版本 | -| 3.2.4 | 数据订阅在 WebSocket 连接下增加 enable.auto.commit 参数，以及 unsubscribe() 方法。 | - | -| 3.2.3 | 修复 ResultSet 在一些情况数据解析失败 | - | -| 3.2.2 | 新增功能：数据订阅支持 seek 功能。 | 3.0.5.0 及更高版本 | -| 3.2.1 | 新增功能：WebSocket 连接支持 schemaless 与 prepareStatement 写入。变更：consumer poll 返回结果集为 ConsumerRecord，可通过 value() 获取指定结果集数据。 | 3.0.3.0 及更高版本 | -| 3.2.0 | 存在连接问题，不推荐使用 | - | -| 3.1.0 | WebSocket 连接支持订阅功能 | - | -| 3.0.1 - 3.0.4 | 修复一些情况下结果集数据解析错误的问题。3.0.1 在 JDK 11 环境编译，JDK 8 环境下建议使用其他版本 | - | -| 3.0.0 | 支持 TDengine 3.0 | 3.0.0.0 及更高版本 | -| 2.0.42 | 修复 WebSocket 连接中 wasNull 接口返回值 | - | -| 2.0.41 | 修复 REST 连接中用户名和密码转码方式 | - | -| 2.0.39 - 2.0.40 | 增加 REST 连接/请求 超时设置 | - | -| 2.0.38 | JDBC REST 连接增加批量拉取功能 | - | -| 2.0.37 | 增加对 json tag 支持 | - | -| 2.0.36 | 增加对 schemaless 写入支持 | - | +| 3.2.8 | 1. 优化了自动提交
2. 解决了 WebSocket 手动提交 bug
3.优化 WebSocket prepareStatement 使用一个连接
4.元数据支持视图 | - | +| 3.2.7 | 1. 支持 VARBINARY 和 GEOMETRY 类型
2. 增加 native 连接的时区设置支持
3. 增加 WebSocket 自动重连功能 | 3.2.0.0 及更高版本 | +| 3.2.5 | 数据订阅增加 committed()、assignment() 方法 | 3.1.0.3 及更高版本 | +| 3.2.4 | 数据订阅在 WebSocket 连接下增加 enable.auto.commit 参数，以及 unsubscribe 方法 | - | +| 3.2.3 | 修复 ResultSet 在一些情况数据解析失败 | - | +| 3.2.2 | 数据订阅支持 seek 功能 | 3.0.5.0 及更高版本 | +| 3.2.1 | 1. WebSocket 连接支持 schemaless 与 prepareStatement 写入
2. consumer poll 返回结果集为 ConsumerRecord，可通过 value() 获取指定结果集数据 | 3.0.3.0 及更高版本 | +| 3.2.0 | 存在连接问题，不推荐使用 | - | +| 3.1.0 | WebSocket 连接支持订阅功能 | - | +| 3.0.1 - 3.0.4 | 修复一些情况下结果集数据解析错误的问题。3.0.1 在 JDK 11 环境编译，JDK 8 环境下建议使用其他版本 | - | +| 3.0.0 | 支持 TDengine 3.0 | 3.0.0.0 及更高版本 | +| 2.0.42 | 修复 WebSocket 连接中 wasNull 接口返回值 | - | +| 2.0.41 | 修复 REST 连接中用户名和密码转码方式 | - | +| 2.0.39 - 2.0.40 | 增加 REST 连接/请求 超时设置 | - | +| 2.0.38 | JDBC REST 连接增加批量拉取功能 | - | +| 2.0.37 | 增加对 json tag 支持 | - | +| 2.0.36 | 增加对 schemaless 写入支持 | - | ## 异常和错误码 diff --git a/docs/zh/14-reference/05-connector/26-rust.mdx b/docs/zh/14-reference/05-connector/26-rust.mdx index cfabed4c61..863da4cb47 100644 --- a/docs/zh/14-reference/05-connector/26-rust.mdx +++ b/docs/zh/14-reference/05-connector/26-rust.mdx @@ -28,22 +28,22 @@ import RequestId from "./_request_id.mdx"; ## 支持的平台 -原生连接支持的平台和 TDengine 客户端驱动支持的平台一致。 -WebSocket 连接支持所有能运行 Rust 的平台。 +- 原生连接支持的平台和 TDengine 客户端驱动支持的平台一致。 +- WebSocket 连接支持所有能运行 Rust 的平台。 ## 版本历史 -| Rust 连接器版本 | TDengine 版本 | 主要功能 | -| :----------------: | :--------------: | :--------------------------------------------------: | -| v0.12.3 | 3.3.0.0 or later | 优化了 WebSocket 查询和插入性能，支持了 VARBINARY 和 GEOMETRY 类型 | -| v0.12.0 | 3.2.3.0 or later | WS 支持压缩。 | -| v0.11.0 | 3.2.0.0 | TMQ 功能优化。 | -| v0.10.0 | 3.1.0.0 | WS endpoint 变更。 | -| v0.9.2 | 3.0.7.0 | STMT：ws 下获取 tag_fields、col_fields。 | -| v0.8.12 | 3.0.5.0 | 消息订阅：获取消费进度及按照指定进度开始消费。 | -| v0.8.0 | 3.0.4.0 | 支持无模式写入。 | -| v0.7.6 | 3.0.3.0 | 支持在请求中使用 req_id。 | -| v0.6.0 | 3.0.0.0 | 基础功能。 | +| Rust 连接器版本 | 主要变化 | TDengine 版本 | +| :---------------- | :-------------------------------------------------- | :-------------- | +| v0.12.3 | 1. 优化了 WebSocket 查询和插入性能
2. 支持了 VARBINARY 和 GEOMETRY 类型 | 3.3.0.0 及更高版本 | +| v0.12.0 | WS 支持压缩。 | 3.2.3.0 及更高版本 | +| v0.11.0 | TMQ 功能优化。 | 3.2.0.0 | +| v0.10.0 | WS endpoint 变更。 | 3.1.0.0 | +| v0.9.2 | STMT：ws 下获取 tag_fields、col_fields。 | 3.0.7.0 | +| v0.8.12 | 消息订阅：获取消费进度及按照指定进度开始消费。 | 3.0.5.0 | +| v0.8.0 | 支持无模式写入。 | 3.0.4.0 | +| v0.7.6 | 支持在请求中使用 req_id。 | 3.0.3.0 | +| v0.6.0 | 基础功能。 | 3.0.0.0 | ## 处理错误 diff --git a/docs/zh/14-reference/05-connector/50-odbc.mdx b/docs/zh/14-reference/05-connector/50-odbc.mdx index 63837fd282..027099cc54 100644 --- a/docs/zh/14-reference/05-connector/50-odbc.mdx +++ b/docs/zh/14-reference/05-connector/50-odbc.mdx @@ -15,7 +15,7 @@ TDengine ODBC 提供 64 位 和 32 位 两种驱动程序。但 32 位仅企业 想更多了解 TDengine 时序时序数据库的使用，可访问 [TDengine官方文档](https://docs.taosdata.com/intro/)。 ## ODBC 版本兼容性 -- 支持 ODBC 3.8 及以前所有版本。 +- 支持 ODBC 所有版本 ## 安装 @@ -106,8 +106,8 @@ TDengine ODBC 支持两种连接 TDengine 数据库方式：WebSocket 连接与 ## 支持的平台 -原生连接方式支持的平台和 TDengine Windows X64版 客户端驱动支持的平台一致。 -WebSocket 连接方式除此之外还支持 Windows X64系统上运行的 32 位应用程序上使用。 +- 原生连接方式支持的平台和 TDengine Windows X64版 客户端驱动支持的平台一致。 +- WebSocket 连接方式除此之外还支持 Windows X64系统上运行的 32 位应用程序上使用。 ## 版本历史 From 5675f29f9116d8958d7b0acf28f06bb4a5c7751e Mon Sep 17 00:00:00 2001 From: t_max <1172915550@qq.com> Date: Mon, 9 Dec 2024 11:43:25 +0800 Subject: [PATCH 2/7] docs: modify connector compatibility description --- docs/zh/08-operation/12-multi.md | 4 +-- docs/zh/14-reference/05-connector/20-go.mdx | 29 +++++++++++---- docs/zh/14-reference/05-connector/26-rust.mdx | 2 +- .../14-reference/05-connector/40-csharp.mdx | 36 ++++++++----------- 4 files changed, 40 insertions(+), 31 deletions(-) diff --git a/docs/zh/08-operation/12-multi.md b/docs/zh/08-operation/12-multi.md index 1e81a7ff1e..14db264522 100644 --- a/docs/zh/08-operation/12-multi.md +++ b/docs/zh/08-operation/12-multi.md @@ -121,7 +121,7 @@ s3migrate database ; 当 TSDB 时序数据超过 `s3_keeplocal` 参数指定的时间，相关的数据文件会被切分成多个文件块，每个文件块的默认大小是 512M 字节 (`s3_chunkpages * tsdb_pagesize`)。除了最后一个文件块保留在本地文件系统外，其余的文件块会被上传到对象存储服务。 ```math -上传次数 = 数据文件大小 / (s3_chunkpages * tsdb_pagesize) - 1 +\text{上传次数} = \text{数据文件大小} / (s3_chunkpages * tsdb_pagesize) - 1 ``` 在创建数据库时，可以通过 `s3_chunkpages` 参数调整每个文件块的大小，从而控制每个数据文件的上传次数。 @@ -135,7 +135,7 @@ s3migrate database ; 相邻的多个数据页会作为一个数据块从对象存储下载一次，以减少从对象存储下载的次数。每个数据页的大小，在创建数据库时，通过 `tsdb_pagesize` 参数指定，默认 4K 字节。 ```math -下载次数 = 查询需要的数据块数量 - 已缓存的数据块数量 +\text{下载次数} = \text{查询需要的数据块数量} - \text{已缓存的数据块数量} ``` 页缓存是内存缓存，节点重启后，再次查询需要重新下载数据。缓存采用 LRU (Least Recently Used) 策略，当缓存空间不足时，最近最少使用的数据将被淘汰。缓存的大小可以通过 `s3PageCacheSize` 参数进行调整，通常来说，缓存越大，下载次数越少。 diff --git a/docs/zh/14-reference/05-connector/20-go.mdx b/docs/zh/14-reference/05-connector/20-go.mdx index 61048f7b85..03ddcf51cf 100644 --- a/docs/zh/14-reference/05-connector/20-go.mdx +++ b/docs/zh/14-reference/05-connector/20-go.mdx @@ -14,18 +14,35 @@ import RequestId from "./_request_id.mdx"; ## 兼容性 -支持最低 Go 版本 1.14，建议使用最新 Go 版本 +支持 Go 版本 1.14及以上版本。 ## 支持的平台 -原生连接支持的平台和 TDengine 客户端驱动支持的平台一致。 -REST 连接支持所有能运行 Go 的平台。 +- 原生连接支持的平台和 TDengine 客户端驱动支持的平台一致。 +- WebSocket/REST 连接支持所有能运行 Go 的平台。 -## 版本支持 +## 版本历史 -请参考[版本支持列表](https://github.com/taosdata/driver-go#remind) +| driver-go 版本 | 主要变化 | TDengine 版本 | +|:-------------|:-------------------------------------|:------------| +| v3.5.8 | 修复空指针异常 | 3.3.2.0 | +| v3.5.7 | taosWS 和 taosRestful 支持传入 request id | 3.3.2.0 | +| v3.5.6 | 提升 websocket 查询和写入性能 | 3.3.2.0 | +| v3.5.5 | restful 支持跳过 ssl 证书检查 | 3.2.3.0 | +| v3.5.4 | 兼容 TDengine 3.3.0.0 tmq raw data | 3.2.3.0 | +| v3.5.3 | 重构 taosWS | 3.2.3.0 | +| v3.5.2 | websocket 压缩和优化消息订阅性能 | 3.2.3.0 | +| v3.5.1 | 原生 stmt 查询和 geometry 类型支持 | 3.2.1.0 | +| v3.5.0 | 获取消费进度及按照指定进度开始消费 | 3.0.5.0 | +| v3.3.1 | 基于 websocket 的 schemaless 协议写入 | 3.0.4.1 | +| v3.1.0 | 提供贴近 kafka 的订阅 api | 3.0.2.2 | +| v3.0.4 | 新增 request id 相关接口 | 3.0.2.2 | +| v3.0.3 | 基于 websocket 的 statement 写入 | 3.0.1.5 | +| v3.0.2 | 基于 websocket 的数据查询和写入 | 3.0.1.5 | +| v3.0.1 | 基于 websocket 的消息订阅 | 3.0.0.0 | +| v3.0.0 | 适配 TDengine 3.0 查询和写入 | 3.0.0.0 | -## 处理异常 +## 异常和错误码 如果是 TDengine 错误可以通过以下方式获取错误码和错误信息。 diff --git a/docs/zh/14-reference/05-connector/26-rust.mdx b/docs/zh/14-reference/05-connector/26-rust.mdx index 863da4cb47..06d59d6343 100644 --- a/docs/zh/14-reference/05-connector/26-rust.mdx +++ b/docs/zh/14-reference/05-connector/26-rust.mdx @@ -35,7 +35,7 @@ import RequestId from "./_request_id.mdx"; | Rust 连接器版本 | 主要变化 | TDengine 版本 | | :---------------- | :-------------------------------------------------- | :-------------- | -| v0.12.3 | 1. 优化了 WebSocket 查询和插入性能
2. 支持了 VARBINARY 和 GEOMETRY 类型 | 3.3.0.0 及更高版本 | +| v0.12.3 | 1. 优化了 WebSocket 查询和插入性能
2. 支持了 VARBINARY 和 GEOMETRY 类型 | 3.3.0.0 及更高版本 | | v0.12.0 | WS 支持压缩。 | 3.2.3.0 及更高版本 | | v0.11.0 | TMQ 功能优化。 | 3.2.0.0 | | v0.10.0 | WS endpoint 变更。 | 3.1.0.0 | diff --git a/docs/zh/14-reference/05-connector/40-csharp.mdx b/docs/zh/14-reference/05-connector/40-csharp.mdx index e4e778eeff..488a50e812 100644 --- a/docs/zh/14-reference/05-connector/40-csharp.mdx +++ b/docs/zh/14-reference/05-connector/40-csharp.mdx @@ -10,35 +10,27 @@ import RequestId from "./_request_id.mdx"; `TDengine.Connector` 是 TDengine 提供的 C# 语言连接器。C# 开发人员可以通过它开发存取 TDengine 集群数据的 C# 应用软件。 -## 连接方式 - -`TDengine.Connector` 提供两种形式的连接器 -* **原生连接**，通过 TDengine 客户端驱动程序（taosc）原生连接 TDengine 实例，支持数据写入、查询、数据订阅、schemaless 接口和参数绑定接口等功能。 -* **WebSocket 连接**，通过 taosAdapter 提供的 WebSocket 接口连接 TDengine 实例，WebSocket 连接实现的功能集合和原生连接有少量不同。（自 v3.0.1 起） - -连接方式的详细介绍请参考：[连接方式](../../../develop/connect/#连接方式) - ## 兼容性 -* `TDengine.Connector` 3.1.0 版本进行了完整的重构，不再兼容 3.0.2 及以前版本。3.0.2 文档请参考 [nuget](https://www.nuget.org/packages/TDengine.Connector/3.0.2) -* `TDengine.Connector` 3.x 不兼容 TDengine 2.x，如果在运行 TDengine 2.x 版本的环境下需要使用 C# 连接器请使用 TDengine.Connector 的 1.x 版本。 +- .NET Framework 4.6 及以上版本。 +- .NET 5.0 及以上版本。 +- `TDengine.Connector` 3.1.0 版本进行了完整的重构，不再兼容 3.0.2 及以前版本。3.0.2 文档请参考 [nuget](https://www.nuget.org/packages/TDengine.Connector/3.0.2) +- `TDengine.Connector` 3.x 不兼容 TDengine 2.x，如果在运行 TDengine 2.x 版本的环境下需要使用 C# 连接器请使用 TDengine.Connector 的 1.x 版本。 ## 支持的平台 -支持的平台和 TDengine 客户端驱动支持的平台一致。 +- 原生连接支持的平台和 TDengine 客户端驱动支持的平台一致。 +- WebSocket 连接支持所有能运行 .NET 运行时的平台。 -:::warning -TDengine 不再支持 32 位 Windows 平台。 -::: +## 版本历史 -## 版本支持 - -| **Connector 版本** | **TDengine 版本** | **主要功能** | -|------------------|------------------|----------------------------| -| 3.1.3 | 3.2.1.0/3.1.1.18 | 支持 WebSocket 自动重连 | -| 3.1.2 | 3.2.1.0/3.1.1.18 | 修复 schemaless 资源释放 | -| 3.1.1 | 3.2.1.0/3.1.1.18 | 支持 varbinary 和 geometry 类型 | -| 3.1.0 | 3.2.1.0/3.1.1.18 | WebSocket 使用原生实现 | +| Connector 版本 | 主要变化 | TDengine 版本 | +|:-------------|:---------------------------|:------------| +| 3.1.4 | 提升 websocket 查询和写入性能 | 3.3.2.0 | +| 3.1.3 | 支持 WebSocket 自动重连 | 3.2.1.0 | +| 3.1.2 | 修复 schemaless 资源释放 | 3.2.1.0 | +| 3.1.1 | 支持 varbinary 和 geometry 类型 | 3.2.1.0 | +| 3.1.0 | WebSocket 使用原生实现 | 3.2.1.0 | ## 处理异常 From d21ea47966b85fd721b10feb8b8b25bf018542e3 Mon Sep 17 00:00:00 2001 From: qevolg <2227465945@qq.com> Date: Mon, 9 Dec 2024 13:33:36 +0800 Subject: [PATCH 3/7] docs(rust): update rust connector doc --- docs/zh/14-reference/05-connector/26-rust.mdx | 158 +++++++++++++----- 1 file changed, 115 insertions(+), 43 deletions(-) diff --git a/docs/zh/14-reference/05-connector/26-rust.mdx b/docs/zh/14-reference/05-connector/26-rust.mdx index 863da4cb47..fbeb2f250e 100644 --- a/docs/zh/14-reference/05-connector/26-rust.mdx +++ b/docs/zh/14-reference/05-connector/26-rust.mdx @@ -4,27 +4,21 @@ sidebar_label: Rust title: TDengine Rust Connector --- -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; -import Preparation from "./_preparation.mdx" +import Preparation from "./_preparation.mdx"; import RequestId from "./_request_id.mdx"; [![Crates.io](https://img.shields.io/crates/v/taos)](https://crates.io/crates/taos) ![Crates.io](https://img.shields.io/crates/d/taos) [![docs.rs](https://img.shields.io/docsrs/taos)](https://docs.rs/taos) -`taos` 是 TDengine 的官方 Rust 语言连接器。Rust 开发人员可以通过它开发存取 TDengine 数据库的应用软件。 +`taos` 是 TDengine 的官方 Rust 语言连接器，Rust 开发人员可以通过它开发存取 TDengine 数据库的应用软件。 该 Rust 连接器的源码托管在 [GitHub](https://github.com/taosdata/taos-connector-rust)。 -## 连接方式 +## Rust 兼容性 -`taos` 提供两种建立连接的方式。一般我们推荐使用 **WebSocket 连接**。 -- **原生连接**，它通过 TDengine 客户端驱动程序（taosc）连接 TDengine 运行实例。 -- **WebSocket 连接**，它通过 taosAdapter 的 WebSocket 接口连接 TDengine 运行实例。 - -你可以通过不同的 “特性（即 Cargo 关键字 `features`）” 来指定使用哪种连接器（默认同时支持）。 - -连接方式的详细介绍请参考：[连接方式](../../../develop/connect/#连接方式) +支持 1.70 及以上版本。 ## 支持的平台 @@ -33,20 +27,19 @@ import RequestId from "./_request_id.mdx"; ## 版本历史 -| Rust 连接器版本 | 主要变化 | TDengine 版本 | -| :---------------- | :-------------------------------------------------- | :-------------- | -| v0.12.3 | 1. 优化了 WebSocket 查询和插入性能
2. 支持了 VARBINARY 和 GEOMETRY 类型 | 3.3.0.0 及更高版本 | -| v0.12.0 | WS 支持压缩。 | 3.2.3.0 及更高版本 | -| v0.11.0 | TMQ 功能优化。 | 3.2.0.0 | -| v0.10.0 | WS endpoint 变更。 | 3.1.0.0 | -| v0.9.2 | STMT：ws 下获取 tag_fields、col_fields。 | 3.0.7.0 | -| v0.8.12 | 消息订阅：获取消费进度及按照指定进度开始消费。 | 3.0.5.0 | -| v0.8.0 | 支持无模式写入。 | 3.0.4.0 | -| v0.7.6 | 支持在请求中使用 req_id。 | 3.0.3.0 | -| v0.6.0 | 基础功能。 | 3.0.0.0 | +| Rust 连接器版本 | 主要变化 | TDengine 版本 | +| :-------------- | :------------------------------------------------------------------------ | :----------------- | +| v0.12.3 | 1. 优化 WebSocket 查询和插入性能
2. 支持 VARBINARY 和 GEOMETRY 类型 | 3.3.0.0 及更高版本 | +| v0.12.0 | 支持 WebSocket 压缩 | 3.2.3.0 及更高版本 | +| v0.11.0 | 消息订阅功能优化 | 3.2.0.0 | +| v0.10.0 | WebSocket endpoint 变更 | 3.1.0.0 | +| v0.9.2 | STMT：通过 WebSocket 获取 `tag_fields` 和 `col_fields` 信息 | 3.0.7.0 | +| v0.8.12 | 消息订阅：支持获取消费进度及按照指定进度开始消费 | 3.0.5.0 | +| v0.8.0 | 支持无模式写入 | 3.0.4.0 | +| v0.7.6 | 支持在请求中使用 `req_id` | 3.0.3.0 | +| v0.6.0 | 基础功能 | 3.0.0.0 | - -## 处理错误 +## 异常和错误码 在报错后，可以获取到错误的具体信息： @@ -61,7 +54,8 @@ match conn.exec(sql) { } } ``` -错误信息的错误码可以参考：[错误码](../../../reference/error-code) + +错误信息的错误码可以参考：[错误码](../../../reference/error-code) ## 数据类型映射 @@ -80,14 +74,14 @@ TDengine 目前支持时间戳、数字、字符、布尔类型，与 Rust 对 | BINARY | Vec\ | | NCHAR | String | | JSON | serde_json::Value | -| VARBINARY | Bytes | -| GEOMETRY | Bytes | +| VARBINARY | Bytes | +| GEOMETRY | Bytes | **注意**：JSON 类型仅在 tag 中支持。 ## 示例程序汇总 -示例程序源码请参考：[rust example](https://github.com/taosdata/TDengine/tree/main/docs/examples/rust) +请参考：[rust example](https://github.com/taosdata/TDengine/tree/main/docs/examples/rust) ## 常见问题 @@ -96,9 +90,10 @@ TDengine 目前支持时间戳、数字、字符、布尔类型，与 Rust 对 ## API 参考 Rust 连接器的接口分为同步接口和异步接口，一般同步接口是由异步接口实现，方法签名除 async 关键字外基本相同。对于同步接口和异步接口功能一样的接口，本文档只提供同步接口的说明。 -对于 WebSocket 连接和原生连接两种方式，除了建立连接的 DSN 不同，其余接口调用没有区别。 +对于 WebSocket 连接和原生连接两种方式，除了建立连接的 DSN 不同，其余接口调用没有区别。 + +### 连接功能 -### 连接功能 #### DSN TaosBuilder 通过 DSN 连接描述字符串创建一个连接构造器。 @@ -126,29 +121,35 @@ DSN 描述字符串基本结构如下： 一个完整的 DSN 描述字符串示例如下：`taos+ws://localhost:6041/test`， 表示使用 WebSocket（`ws`）方式通过 `6041` 端口连接服务器 `localhost`，并指定默认数据库为 `test`。 #### TaosBuilder + TaosBuilder 结构体主要提供了根据 DSN 构建 Taos 对象的方法，还提供了检查连接，以及获取客户端版本号等功能。 - `fn available_params() -> &'static [&'static str]` + - **接口说明**：获取 DSN 中可用的参数列表。 - **返回值**：返回静态字符串切片的引用，包含可用的参数名称。 - `fn from_dsn(dsn: D) -> RawResult` + - **接口说明**：使用 DSN 字符串创建连接，不检查连接。 - **参数说明**： - `dsn`：DSN 字符串或可转换为 DSN 的类型。 - **返回值**：成功时返回自身类型的 `RawResult`，失败时返回错误。 - `fn client_version() -> &'static str` + - **接口说明**：获取客户端版本。 - **返回值**：返回客户端版本的静态字符串。 - `fn ping(&self, _: &mut Self::Target) -> RawResult<()>` + - **接口说明**：检查连接是否仍然存活。 - **参数说明**： - `_`：目标连接的可变引用。 - **返回值**：成功时返回空的 `RawResult`，失败时返回错误。 - `fn ready(&self) -> bool` + - **接口说明**：检查是否准备好连接。 - **返回值**：大多数情况下返回 `true`，表示地址准备好连接。 @@ -157,26 +158,32 @@ TaosBuilder 结构体主要提供了根据 DSN 构建 Taos 对象的方法，还 - **返回值**：成功时返回目标连接类型的 `RawResult`，失败时返回错误。 ### 执行 SQL + 执行 SQL 主要使用 Taos 结构体，获取结果集以及元数据需要使用下节介绍的 ResultSet 结构体 和列信息 Field 结构体。 #### Taos + Taos 结构体提供了多个数据库操作的 API，包括：执行 SQL，无模式写入，以及一些常用数据库查询的封装（如创建数据库，获取） - `pub fn is_native(&self) -> bool` + - **接口说明**：判断连接是否使用本地协议。 - **返回值**：如果使用本地协议，则返回 `true`，否则返回 `false`。 - `pub fn is_ws(&self) -> bool` - - **接口说明**：判断连接是否使用websocket协议。 - - **返回值**：如果使用websocket协议，则返回 `true`，否则返回 `false`。 + + - **接口说明**：判断连接是否使用 WebSocket 协议。 + - **返回值**：如果使用 WebSocket 协议，则返回 `true`，否则返回 `false`。 - `fn query>(&self, sql: T) -> RawResult` + - **接口说明**：执行 SQL 查询。 - **参数说明**： - `sql`：要执行的 SQL 语句。 - **返回值**：成功时返回结果集 `ResultSet` 的 `RawResult`，失败时返回错误。 - `fn query_with_req_id>(&self, sql: T, req_id: u64) -> RawResult` + - **接口说明**：带请求 ID 执行 SQL 查询。 - **参数说明**： - `sql`：要执行的 SQL 语句。 @@ -184,49 +191,58 @@ Taos 结构体提供了多个数据库操作的 API，包括：执行 SQL，无 - **返回值**：成功时返回结果集 `ResultSet` 的 `RawResult`，失败时返回错误。 - `fn exec>(&self, sql: T) -> RawResult` + - **接口说明**：执行 SQL 语句。 - **参数说明**： - `sql`：要执行的 SQL 语句。 - **返回值**：成功时返回受影响的行数，失败时返回错误。 - `fn exec_many, I: IntoIterator>(&self, input: I) -> RawResult` + - **接口说明**：批量执行 SQL 语句。 - **参数说明**： - `input`：要执行的 SQL 语句集合。 - **返回值**：成功时返回总共受影响的行数，失败时返回错误。 - `fn query_one, O: DeserializeOwned>(&self, sql: T) -> RawResult>` + - **接口说明**：执行 SQL 查询并返回单个结果。 - **参数说明**： - `sql`：要执行的 SQL 语句。 - **返回值**：成功时返回可选的结果对象，失败时返回错误。 - `fn server_version(&self) -> RawResult>` + - **接口说明**：获取服务器版本。 - **返回值**：成功时返回服务器版本字符串的 `RawResult`，失败时返回错误。 - `fn create_topic(&self, name: impl AsRef, sql: impl AsRef) -> RawResult<()>` + - **接口说明**：创建主题。 - **参数说明**： - `name`：主题名称。 - - `sql`：关联的 SQ L语句。 + - `sql`：关联的 SQL 语句。 - **返回值**：成功时返回空的 `RawResult`，失败时返回错误。 - `fn databases(&self) -> RawResult>` + - **接口说明**：获取数据库列表。 - **返回值**：成功时返回数据库列表的 `RawResult`，失败时返回错误。 - `fn topics(&self) -> RawResult>` + - **接口说明**：获取主题信息。 - **返回值**：成功时返回主题列表的 `RawResult`，失败时返回错误。 - `fn describe(&self, table: &str) -> RawResult` + - **接口说明**：描述表结构。 - **参数说明**： - `table`：表名称。 - **返回值**：成功时返回表结构描述的 `RawResult`，失败时返回错误。 - `fn database_exists(&self, name: &str) -> RawResult` + - **接口说明**：检查数据库是否存在。 - **参数说明**： - `name`：数据库名称。 @@ -238,9 +254,12 @@ Taos 结构体提供了多个数据库操作的 API，包括：执行 SQL，无 - `data`：无模式数据。 - **返回值**：成功时返回空的 `RawResult`，失败时返回错误。 -### SmlData +### SmlData + SmlData 结构体提供了无模式写入的数据结构，以及获取属性的方法。 + - `pub struct SmlData` + - **结构体说明**：`SmlData` 结构体用于存储无模式数据及其相关信息。 - **字段说明**： - `protocol`：无模式协议，支持 InfluxDB `Line`, OpenTSDB `Telnet`, OpenTSDB `Json`, 三种。 @@ -250,18 +269,22 @@ SmlData 结构体提供了无模式写入的数据结构，以及获取属性的 - `req_id`：请求 ID。 - `pub fn protocol(&self) -> SchemalessProtocol` + - **接口说明**：获取无模式协议。 - **返回值**：无模式协议类型，支持 InfluxDB `Line`, OpenTSDB `Telnet`, OpenTSDB `Json`, 三种。 - `pub fn precision(&self) -> SchemalessPrecision` + - **接口说明**：获取时间戳精度。 - **返回值**：时间戳精度类型，支持 `Hours`, `Minutes`, `Seconds`, `Millisecond`（默认）, `Microsecond`, `Nanosecond`。 - `pub fn data(&self) -> &Vec` + - **接口说明**：获取数据列表。 - **返回值**：数据列表的引用。 - `pub fn ttl(&self) -> Option` + - **接口说明**：获取数据存活时间。 - **返回值**：数据存活时间（可选），单位为秒。 @@ -269,39 +292,49 @@ SmlData 结构体提供了无模式写入的数据结构，以及获取属性的 - **接口说明**：获取请求 ID。 - **返回值**：请求 ID（可选）。 -### 结果获取 +### 结果获取 + #### ResultSet + ResultSet 结构体提供了结果集的一些方法，可以用来获取结果集的数据和元数据。 - `fn affected_rows(&self) -> i32` + - **接口说明**：获取受影响的行数。 - **返回值**：受影响的行数，类型为 `i32`。 - `fn precision(&self) -> Precision` + - **接口说明**：获取精度信息。 - **返回值**：精度信息，类型为 `Precision`。 - `fn fields(&self) -> &[Field]` + - **接口说明**：获取字段信息。见下文 Feild 结构体描述。 - **返回值**：字段信息数组的引用。 - `fn summary(&self) -> (usize, usize)` + - **接口说明**：获取摘要信息。 - **返回值**：包含两个 `usize` 类型的元组，分别表示某些统计信息。 - `fn num_of_fields(&self) -> usize` + - **接口说明**：获取字段数量。 - **返回值**：字段数量，类型为 `usize`。 - `fn blocks(&mut self) -> IBlockIter<'_, Self>` + - **接口说明**：获取原始数据块的迭代器。 - **返回值**：原始数据块的迭代器，类型为 `IBlockIter<'_, Self>`。 - `fn rows(&mut self) -> IRowsIter<'_, Self>` + - **接口说明**：获取按行查询的迭代器。 - **返回值**：按行查询的迭代器，类型为 `IRowsIter<'_, Self>`。 - `fn deserialize(&mut self) -> Map, fn(_: Result, Error>) -> Result>` + - **接口说明**：反序列化行数据。 - **泛型参数**： - `T`：目标类型，需实现 `DeserializeOwned`。 @@ -311,14 +344,17 @@ ResultSet 结构体提供了结果集的一些方法，可以用来获取结果 - **接口说明**：将结果集转换为值的二维向量。 - **返回值**：成功时返回值的二维向量，失败时返回错误，类型为 `Result>, Error>`。 -#### Feild +#### Feild + Feild 结构体提供了字段信息的一些方法。 - `pub const fn empty() -> Field` + - **接口说明**：创建一个空的 `Field` 实例。 - **返回值**：返回一个空的 `Field` 实例。 - `pub fn new(name: impl Into, ty: Ty, bytes: u32) -> Field` + - **接口说明**：创建一个新的 `Field` 实例。 - **参数说明**： - `name`：字段名称。 @@ -327,22 +363,27 @@ Feild 结构体提供了字段信息的一些方法。 - **返回值**：返回一个新的 `Field` 实例。 - `pub fn name(&self) -> &str` + - **接口说明**：获取字段名称。 - **返回值**：返回字段的名称。 - `pub fn escaped_name(&self) -> String` + - **接口说明**：获取转义后的字段名称。 - **返回值**：返回转义后的字段名称。 - `pub const fn ty(&self) -> Ty` + - **接口说明**：获取字段类型。 - **返回值**：返回字段的类型。 - `pub const fn bytes(&self) -> u32` + - **接口说明**：获取字段的预设长度。 - **返回值**：对于变长数据类型，返回其预设长度；对于其他类型，返回其字节宽度。 - `pub fn to_c_field(&self) -> c_field_t` + - **接口说明**：将 `Field` 实例转换为 C 语言结构体。 - **返回值**：返回 C 语言结构体表示的字段。 @@ -351,17 +392,22 @@ Feild 结构体提供了字段信息的一些方法。 - **返回值**：例如："INT", "VARCHAR(100)" 等 SQL 数据类型表示。 ### 参数绑定 + 参数绑定功能主要由 Stmt 结构体支持。 -#### Stmt + +#### Stmt + Stmt 结构体提供了参数绑定相关功能，用于实现高效写入。 - `fn init(taos: &Q) -> RawResult` + - **接口说明**：初始化参数绑定实例。 - **参数说明**： - `taos`：数据库连接实例。 - **返回值**：成功时返回初始化的实例，失败时返回错误。 - `fn init_with_req_id(taos: &Q, req_id: u64) -> RawResult` + - **接口说明**：使用请求 ID 初始化参数绑定实例。 - **参数说明**： - `taos`：数据库连接实例。 @@ -369,24 +415,28 @@ Stmt 结构体提供了参数绑定相关功能，用于实现高效写入。 - **返回值**：成功时返回初始化的实例，失败时返回错误。 - `fn prepare>(&mut self, sql: S) -> RawResult<&mut Self>` + - **接口说明**：准备要绑定的 SQL 语句。 - **参数说明**： - `sql`：要准备的 SQL 语句。 - **返回值**：成功时返回自身的可变引用，失败时返回错误。 - `fn set_tbname>(&mut self, name: S) -> RawResult<&mut Self>` + - **接口说明**：设置表名称。 - **参数说明**： - `name`：表名称。 - **返回值**：成功时返回自身的可变引用，失败时返回错误。 - `fn set_tags(&mut self, tags: &[Value]) -> RawResult<&mut Self>` + - **接口说明**：设置标签。 - **参数说明**： - `tags`：标签数组。 - **返回值**：成功时返回自身的可变引用，失败时返回错误。 - `fn set_tbname_tags>(&mut self, name: S, tags: &[Value]) -> RawResult<&mut Self>` + - **接口说明**：设置表名称和标签。 - **参数说明**： - `name`：表名称。 @@ -394,16 +444,19 @@ Stmt 结构体提供了参数绑定相关功能，用于实现高效写入。 - **返回值**：成功时返回自身的可变引用，失败时返回错误。 - `fn bind(&mut self, params: &[ColumnView]) -> RawResult<&mut Self>` + - **接口说明**：绑定参数。 - **参数说明**： - `params`：参数数组。 - **返回值**：成功时返回自身的可变引用，失败时返回错误。 - `fn add_batch(&mut self) -> RawResult<&mut Self>` + - **接口说明**：添加批处理。 - **返回值**：成功时返回自身的可变引用，失败时返回错误。 - `fn execute(&mut self) -> RawResult` + - **接口说明**：执行语句。 - **返回值**：成功时返回受影响的行数，失败时返回错误。 @@ -412,32 +465,39 @@ Stmt 结构体提供了参数绑定相关功能，用于实现高效写入。 - **返回值**：受影响的行数。 ### 数据订阅 + 数据订阅主要涉及三个结构体，提供连接建立的 TmqBuilder， 消费数据和提交偏移量的 Consumer，以及偏移量 Offset。 #### TmqBuilder + 同 TaosBuilder 类似，TmqBuilder 提供了创建消费者对象的功能。 - `fn available_params() -> &'static [&'static str]` + - **接口说明**：获取 DSN 中可用的参数列表。 - **返回值**：返回静态字符串切片的引用，包含可用的参数名称。 - `fn from_dsn(dsn: D) -> RawResult` + - **接口说明**：使用 DSN 字符串创建连接，不检查连接。 - **参数说明**： - - `dsn`：DSN 字符串或可转换为DSN的类型。 + - `dsn`：DSN 字符串或可转换为 DSN 的类型。 - **返回值**：成功时返回自身类型的 `RawResult`，失败时返回错误。 - `fn client_version() -> &'static str` + - **接口说明**：获取客户端版本。 - **返回值**：返回客户端版本的静态字符串。 - `fn ping(&self, conn: &mut Self::Target) -> RawResult<()>` + - **接口说明**：检查连接是否仍然存活。 - **参数说明**： - `conn`：目标连接的可变引用。 - **返回值**：成功时返回空的 `RawResult`，失败时返回错误。 - `fn ready(&self) -> bool` + - **接口说明**：检查是否准备好连接。 - **返回值**：大多数情况下返回 `true`，表示地址准备好连接。 @@ -446,27 +506,32 @@ Stmt 结构体提供了参数绑定相关功能，用于实现高效写入。 - **返回值**：成功时返回目标连接类型的 `RawResult`，失败时返回错误。 #### Consumer + Consumer 结构体提供了订阅相关的功能，包括订阅，获取消息，提交偏移量，设置偏移量等。 - `fn subscribe, I: IntoIterator + Send>(&mut self, topics: I) -> RawResult<()>` + - **接口说明**：订阅一系列主题。 - **参数说明**： - `topics`：要订阅的主题列表。 - **返回值**：成功时返回空的 `RawResult`，失败时返回错误。 - `fn recv_timeout(&self, timeout: Timeout) -> RawResult)>>` + - **接口说明**：在指定超时时间内接收消息。 - **参数说明**： - `timeout`：超时时间。 - **返回值**：成功时返回消息，失败时返回错误。 - `fn commit(&self, offset: Self::Offset) -> RawResult<()>` + - **接口说明**：提交给定的偏移量。 - **参数说明**： - `offset`：要提交的偏移量，见下文 Offset 结构体。 - **返回值**：成功时返回空的 `RawResult`，失败时返回错误。 - `fn commit_offset(&self, topic_name: &str, vgroup_id: VGroupId, offset: i64) -> RawResult<()>` + - **接口说明**：为特定主题和分区提交偏移量。 - **参数说明**： - `topic_name`：主题名称。 @@ -475,14 +540,17 @@ Consumer 结构体提供了订阅相关的功能，包括订阅，获取消息 - **返回值**：成功时返回空的 `RawResult`，失败时返回错误。 - `fn list_topics(&self) -> RawResult>` + - **接口说明**：列出所有可用主题。 - **返回值**：成功时返回主题列表，失败时返回错误。 - `fn assignments(&self) -> Option)>>` + - **接口说明**：获取当前分配的主题和分区。 - **返回值**：成功时返回分配信息，失败时返回 `None`。 - `fn offset_seek(&mut self, topic: &str, vg_id: VGroupId, offset: i64) -> RawResult<()>` + - **接口说明**：为特定主题和分区设置偏移量。 - **参数说明**： - `topic`：主题名称。 @@ -491,6 +559,7 @@ Consumer 结构体提供了订阅相关的功能，包括订阅，获取消息 - **返回值**：成功时返回空的 `RawResult`，失败时返回错误。 - `fn committed(&self, topic: &str, vgroup_id: VGroupId) -> RawResult` + - **接口说明**：获取特定主题和分区的已提交偏移量。 - **参数说明**： - `topic`：主题名称。 @@ -509,10 +578,12 @@ Consumer 结构体提供了订阅相关的功能，包括订阅，获取消息 Offset 结构体提供了获取当前消息所属的数据库，主题和分区信息。 - `fn database(&self) -> &str` + - **接口说明**：获取当前消息的数据库名称。 - **返回值**：数据库名称的引用。 - `fn topic(&self) -> &str` + - **接口说明**：获取当前消息的主题名称。 - **返回值**：主题名称的引用。 @@ -520,8 +591,9 @@ Offset 结构体提供了获取当前消息所属的数据库，主题和分区 - **接口说明**：获取当前消息的分区 ID。 - **返回值**：分区 ID。 -## 附录 +## 附录 + - Rust 连接器文档：https://docs.rs/taos -- Rust 连接器项目地址: https://github.com/taosdata/taos-connector-rust -- deadpool 连接池: https://crates.io/crates/deadpool -- r2d2 连接池: https://crates.io/crates/r2d2 +- Rust 连接器项目地址: https://github.com/taosdata/taos-connector-rust +- deadpool 连接池: https://crates.io/crates/deadpool +- r2d2 连接池: https://crates.io/crates/r2d2 From c61bf7a6c0a0ebc396c0f21282d06a5231d82be7 Mon Sep 17 00:00:00 2001 From: menshibin Date: Mon, 9 Dec 2024 14:03:55 +0800 Subject: [PATCH 4/7] update connector update history --- docs/en/14-reference/05-connector/10-cpp.mdx | 6 +- docs/en/14-reference/05-connector/14-java.mdx | 64 ++++---- docs/en/14-reference/05-connector/20-go.mdx | 32 +++- docs/en/14-reference/05-connector/26-rust.mdx | 127 ++++++++++----- .../14-reference/05-connector/30-python.mdx | 85 +++++----- docs/en/14-reference/05-connector/35-node.mdx | 16 +- .../14-reference/05-connector/40-csharp.mdx | 39 ++--- docs/en/14-reference/05-connector/50-odbc.mdx | 14 +- .../node/websocketexample/sql_example.js | 1 - docs/zh/14-reference/05-connector/10-cpp.mdx | 4 +- docs/zh/14-reference/05-connector/14-java.mdx | 4 +- docs/zh/14-reference/05-connector/20-go.mdx | 40 ++--- docs/zh/14-reference/05-connector/26-rust.mdx | 22 +-- .../14-reference/05-connector/30-python.mdx | 148 ++++++++++-------- docs/zh/14-reference/05-connector/35-node.mdx | 18 +-- .../14-reference/05-connector/40-csharp.mdx | 18 +-- docs/zh/14-reference/05-connector/50-odbc.mdx | 8 +- 17 files changed, 365 insertions(+), 281 deletions(-) diff --git a/docs/en/14-reference/05-connector/10-cpp.mdx b/docs/en/14-reference/05-connector/10-cpp.mdx index ef3026bd0c..9b7ca15cd1 100644 --- a/docs/en/14-reference/05-connector/10-cpp.mdx +++ b/docs/en/14-reference/05-connector/10-cpp.mdx @@ -35,9 +35,9 @@ Please refer to the [Supported Platforms List](../#supported-platforms) ### Version History -| TDengine Client Version | Main Changes | TDengine Version | -| :------------------: | :---------------------------: | :----------------: | -| 3.3.3.0 | First release, providing comprehensive support for SQL execution, parameter binding, schema-less writing, and data subscription. | 3.3.2.0 and higher versions | +| TDengine Client Version | Major Changes | TDengine Version | +| ------------------ | --------------------------- | ---------------- | +| 3.3.3.0 | First release, providing comprehensive support for SQL execution, parameter binding, schema-less writing, and data subscription. | 3.3.2.0 and higher | ### Error Codes diff --git a/docs/en/14-reference/05-connector/14-java.mdx b/docs/en/14-reference/05-connector/14-java.mdx index 188aa6e6b4..f92a4cc1c2 100644 --- a/docs/en/14-reference/05-connector/14-java.mdx +++ b/docs/en/14-reference/05-connector/14-java.mdx @@ -18,45 +18,45 @@ The JDBC driver implementation for TDengine strives to be consistent with relati ::: -## JDBC and JRE Compatibility +## JDBC and JRE Version Compatibility -- JDBC: Supports JDBC 4.2, with some features like schemaless writing and data subscription provided separately -- JRE: Supports JRE 8 and above +- JDBC: Supports JDBC 4.2 and above. +- JRE: Supports JRE 8 and above. ## Supported Platforms -Native connection supports the same platforms as the TDengine client driver. -REST connection supports all platforms that can run Java. +- Native connection supports the same platforms as the TDengine client driver. +- WebSocket/REST connection supports all platforms that can run Java. ## Version History -| taos-jdbcdriver Version | Main Changes | TDengine Version | -| :------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------: | :----------------: | -| 3.4.0 | 1. Replaced fastjson library with jackson; 2. WebSocket uses a separate protocol identifier; 3. Optimized background thread usage to avoid user misuse leading to timeouts. | - | -| 3.3.4 | 1. Fixed getInt error when data type is float | - | -| 3.3.3 | 1. Fixed memory leak caused by closing WebSocket statement | - | -| 3.3.2 | 1. Optimized parameter binding performance under WebSocket connection; 2. Improved support for mybatis | - | -| 3.3.0 | 1. Optimized data transmission performance under WebSocket connection; 2. Supports skipping SSL verification, off by default | 3.3.2.0 and higher | -| 3.2.11 | Fixed a bug in closing result set in Native connection | - | -| 3.2.10 | 1. REST/WebSocket connections support data compression during transmission; 2. WebSocket automatic reconnection mechanism, off by default; 3. Connection class provides methods for schemaless writing; 4. Optimized data fetching performance for native connections; 5. Fixed some known issues; 6. Metadata retrieval functions can return a list of supported functions. | - | -| 3.2.9 | Fixed bug in closing WebSocket prepareStatement | - | -| 3.2.8 | Optimized auto-commit, fixed manual commit bug in WebSocket, optimized WebSocket prepareStatement using a single connection, metadata supports views | - | -| 3.2.7 | Supports VARBINARY and GEOMETRY types, added timezone setting support for native connections. Added WebSocket automatic reconnection feature. | 3.2.0.0 and higher | -| 3.2.5 | Data subscription adds committed() and assignment() methods | 3.1.0.3 and higher | -| 3.2.4 | Data subscription adds enable.auto.commit parameter under WebSocket connection, as well as unsubscribe() method. | - | -| 3.2.3 | Fixed ResultSet data parsing failure in some cases | - | -| 3.2.2 | New feature: Data subscription supports seek function. | 3.0.5.0 and higher | -| 3.2.1 | New feature: WebSocket connection supports schemaless and prepareStatement writing. Change: consumer poll returns result set as ConsumerRecord, which can be accessed through value() method. | 3.0.3.0 and higher | -| 3.2.0 | Connection issues, not recommended for use | - | -| 3.1.0 | WebSocket connection supports subscription function | - | -| 3.0.1 - 3.0.4 | Fixed data parsing errors in result sets under some conditions. 3.0.1 compiled in JDK 11 environment, other versions recommended for JDK 8 | - | -| 3.0.0 | Supports TDengine 3.0 | 3.0.0.0 and higher | -| 2.0.42 | Fixed wasNull interface return value in WebSocket connection | - | -| 2.0.41 | Fixed username and password encoding method in REST connection | - | -| 2.0.39 - 2.0.40 | Added REST connection/request timeout settings | - | -| 2.0.38 | JDBC REST connection adds batch fetching function | - | -| 2.0.37 | Added support for json tag | - | -| 2.0.36 | Added support for schemaless writing | - | +| taos-jdbcdriver Version | Major Changes | TDengine Version | +| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | +| 3.4.0 | 1. Replaced fastjson library with jackson.
2. WebSocket uses a separate protocol identifier.
3. Optimized background thread usage to avoid user misuse leading to timeouts. | - | +| 3.3.4 | Fixed getInt error when data type is float. | - | +| 3.3.3 | Fixed memory leak caused by closing WebSocket statement. | - | +| 3.3.2 | 1. Optimized parameter binding performance under WebSocket connection.
2. Improved support for mybatis. | - | +| 3.3.0 | 1. Optimized data transmission performance under WebSocket connection.
2. Supports skipping SSL verification, off by default. | 3.3.2.0 and higher | +| 3.2.11 | Fixed a bug in closing result set in Native connection. | - | +| 3.2.10 | 1. REST/WebSocket connections support data compression during transmission.
2. WebSocket automatic reconnection mechanism, off by default.
3. Connection class provides methods for schemaless writing.
4. Optimized data fetching performance for native connections.
5. Fixed some known issues.
6. Metadata retrieval functions can return a list of supported functions. | - | +| 3.2.9 | Fixed bug in closing WebSocket prepareStatement. | - | +| 3.2.8 | 1. Optimized auto-commit.
2. Fixed manual commit bug in WebSocket.
3. Optimized WebSocket prepareStatement using a single connection.
4. Metadata supports views. | - | +| 3.2.7 | 1. Supports VARBINARY and GEOMETRY types.
2. Added timezone setting support for native connections.
3. Added WebSocket automatic reconnection feature. | 3.2.0.0 and higher | +| 3.2.5 | Data subscription adds committed() and assignment() methods. | 3.1.0.3 and higher | +| 3.2.4 | Data subscription adds enable.auto.commit parameter under WebSocket connection, as well as unsubscribe() method. | - | +| 3.2.3 | Fixed ResultSet data parsing failure in some cases. | - | +| 3.2.2 | New feature: Data subscription supports seek function. | 3.0.5.0 and higher | +| 3.2.1 | 1. WebSocket connection supports schemaless and prepareStatement writing.
2. Consumer poll returns result set as ConsumerRecord, which can be accessed through value() method. | 3.0.3.0 and higher | +| 3.2.0 | Connection issues, not recommended for use. | - | +| 3.1.0 | WebSocket connection supports subscription function. | - | +| 3.0.1 - 3.0.4 | Fixed data parsing errors in result sets under some conditions. 3.0.1 compiled in JDK 11 environment, other versions recommended for JDK 8. | - | +| 3.0.0 | Supports TDengine 3.0 | 3.0.0.0 and higher | +| 2.0.42 | Fixed wasNull interface return value in WebSocket connection. | - | +| 2.0.41 | Fixed username and password encoding method in REST connection. | - | +| 2.0.39 - 2.0.40 | Added REST connection/request timeout settings. | - | +| 2.0.38 | JDBC REST connection adds batch fetching function. | - | +| 2.0.37 | Added support for json tag. | - | +| 2.0.36 | Added support for schemaless writing. | - | ## Exceptions and Error Codes diff --git a/docs/en/14-reference/05-connector/20-go.mdx b/docs/en/14-reference/05-connector/20-go.mdx index b6313ae3b1..48716ec428 100644 --- a/docs/en/14-reference/05-connector/20-go.mdx +++ b/docs/en/14-reference/05-connector/20-go.mdx @@ -10,20 +10,38 @@ import RequestId from "./_request_id.mdx"; `driver-go` is the official Go language connector for TDengine, implementing the interface of the Go language [database/sql](https://golang.org/pkg/database/sql/) package. Go developers can use it to develop applications that access data in the TDengine cluster. -## Compatibility +## Go Version Compatibility -Supports a minimum Go version of 1.14, but the latest version of Go is recommended. +Supports Go 1.14 and above. ## Supported Platforms -Native connections support the same platforms as the TDengine client driver. -REST connections support all platforms that can run Go. +- Native connections support the same platforms as the TDengine client driver. +- WebSocket/REST connections support all platforms that can run Go. -## Version Support +## Version History -Please refer to the [version support list](https://github.com/taosdata/driver-go#remind). +| driver-go Version | Major Changes | TDengine Version | +|------------------|------------------------------------------------------------------|-------------------| +| v3.5.8 | Fixed null pointer exception. | - | +| v3.5.7 | taosWS and taosRestful support passing request id. | - | +| v3.5.6 | Improved websocket query and insert performance. | 3.3.2.0 and higher | +| v3.5.5 | Restful supports skipping SSL certificate check. | - | +| v3.5.4 | Compatible with TDengine 3.3.0.0 tmq raw data. | - | +| v3.5.3 | Refactored taosWS. | - | +| v3.5.2 | Websocket compression and optimized tmq subscription performance. | 3.2.3.0 and higher | +| v3.5.1 | Native stmt query and geometry type support. | 3.2.1.0 and higher | +| v3.5.0 | Support tmq get assignment and seek offset. | 3.0.5.0 and higher | +| v3.3.1 | Schemaless protocol insert based on websocket. | 3.0.4.1 and higher | +| v3.1.0 | Provided Kafka-like subscription API. | - | +| v3.0.4 | Added request id related interfaces. | 3.0.2.2 and higher | +| v3.0.3 | Websocket-based statement insert. | - | +| v3.0.2 | Websocket-based data query and insert. | 3.0.1.5 and higher | +| v3.0.1 | Websocket-based message subscription. | - | +| v3.0.0 | Adapted to TDengine 3.0 query and insert. | 3.0.0.0 and higher | -## Handling Exceptions + +## Exceptions and Error Codes If it is a TDengine error, you can obtain the error code and error message as follows. diff --git a/docs/en/14-reference/05-connector/26-rust.mdx b/docs/en/14-reference/05-connector/26-rust.mdx index 5ed51e158d..f3b8b0e5eb 100644 --- a/docs/en/14-reference/05-connector/26-rust.mdx +++ b/docs/en/14-reference/05-connector/26-rust.mdx @@ -4,10 +4,10 @@ title: Rust Client Library slug: /tdengine-reference/client-libraries/rust --- -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; -import Preparation from "./_preparation.mdx" +import Preparation from "./_preparation.mdx"; import RequestId from "./_request_id.mdx"; [![Crates.io](https://img.shields.io/crates/v/taos)](https://crates.io/crates/taos) ![Crates.io](https://img.shields.io/crates/d/taos) [![docs.rs](https://img.shields.io/docsrs/taos)](https://docs.rs/taos) @@ -16,37 +16,30 @@ import RequestId from "./_request_id.mdx"; The source code for this Rust connector is hosted on [GitHub](https://github.com/taosdata/taos-connector-rust). -## Connection Methods +## Rust Version Compatibility -`taos` provides two ways to establish a connection. Generally, we recommend using **WebSocket Connection**. - -- **Native Connection**, which connects to a TDengine instance via the TDengine client driver (taosc). -- **WebSocket Connection**, which connects to a TDengine instance via the WebSocket interface of taosAdapter. - -You can specify which connector to use through different "features (i.e., the Cargo keyword `features`)" (both are supported by default). - -For a detailed introduction to connection methods, please refer to: [Connection Methods](../../../developer-guide/connecting-to-tdengine/) +Supports Rust 1.70 and above. ## Supported Platforms -The platforms supported by the native connection are consistent with those supported by the TDengine client driver. -WebSocket connection supports all platforms that can run Rust. +- The platforms supported by the native connection are consistent with those supported by the TDengine client driver. +- WebSocket connection supports all platforms that can run Rust. ## Version History -| Rust Connector Version | TDengine Version | Main Features | -| :----------------: | :--------------: | :--------------------------------------------------: | -| v0.12.3 | 3.3.0.0 or later | Optimized WebSocket query and insertion performance, support for VARBINARY and GEOMETRY types | -| v0.12.0 | 3.2.3.0 or later | WS supports compression. | -| v0.11.0 | 3.2.0.0 | TMQ feature optimization. | -| v0.10.0 | 3.1.0.0 | WS endpoint change. | -| v0.9.2 | 3.0.7.0 | STMT: ws to get tag_fields, col_fields. | -| v0.8.12 | 3.0.5.0 | Message subscription: get consumption progress and start consuming at a specified progress. | -| v0.8.0 | 3.0.4.0 | Supports schema-less writing. | -| v0.7.6 | 3.0.3.0 | Supports using req_id in requests. | -| v0.6.0 | 3.0.0.0 | Basic functionality. | +| Rust Connector Version | Major Changes | TDengine Version | +| -------------------- | --------------------------------------------------------------------------------------------------- | --------------- | +| v0.12.3 | 1. Optimized WebSocket query and insert performance.
2. Supported VARBINARY and GEOMETRY types. | 3.3.0.0 and higher | +| v0.12.0 | WebSocket supports compression. | 3.2.3.0 and higher | +| v0.11.0 | TMQ feature optimization. | 3.2.0.0 and higher | +| v0.10.0 | WebSocket endpoint change. | 3.1.0.0 and higher | +| v0.9.2 | STMT: WebSocket to get tag_fields, col_fields. | 3.0.7.0 and higher | +| v0.8.12 | Message subscription: get consumption progress and start consuming at a specified progress. | 3.0.5.0 and higher | +| v0.8.0 | Supports schema-less writing. | 3.0.4.0 and higher | +| v0.7.6 | Supports using req_id in requests. | 3.0.3.0 and higher | +| v0.6.0 | Basic functionality. | 3.0.0.0 and higher | -## Error Handling +## Exceptions and Error Codes After an error occurs, you can obtain detailed information about the error: @@ -81,14 +74,14 @@ TDengine currently supports timestamp, numeric, character, and boolean types, wi | BINARY | Vec\ | | NCHAR | String | | JSON | serde_json::Value | -| VARBINARY | Bytes | -| GEOMETRY | Bytes | +| VARBINARY | Bytes | +| GEOMETRY | Bytes | **Note**: The JSON type is only supported in tags. ## Summary of Example Programs -For the source code of the example programs, please refer to: [rust example](https://github.com/taosdata/TDengine/tree/main/docs/examples/rust) +Please refer to: [rust example](https://github.com/taosdata/TDengine/tree/main/docs/examples/rust) ## Frequently Asked Questions @@ -97,9 +90,9 @@ Please refer to [FAQ](../../../frequently-asked-questions/) ## API Reference The Rust connector interfaces are divided into synchronous and asynchronous interfaces, where the synchronous interfaces are generally implemented by the asynchronous ones, and the method signatures are basically the same except for the async keyword. For interfaces where the synchronous and asynchronous functionalities are the same, this document only provides explanations for the synchronous interfaces. -For WebSocket connections and native connections, other than the different DSNs required to establish the connections, there is no difference in calling other interfaces. +For WebSocket connections and native connections, other than the different DSNs required to establish the connections, there is no difference in calling other interfaces. -### Connection Features +### Connection Features #### DSN @@ -132,26 +125,31 @@ A complete DSN description string example is as follows: `taos+ws://localhost:60 The TaosBuilder struct primarily provides methods for building Taos objects based on DSN, as well as features for checking connections and obtaining the client version number. - `fn available_params() -> &'static [&'static str]` + - **Interface Description**: Retrieves a list of available parameters in the DSN. - **Return Value**: Returns a reference to a static slice of strings containing the names of available parameters. - `fn from_dsn(dsn: D) -> RawResult` + - **Interface Description**: Creates a connection using a DSN string without checking the connection. - **Parameter Description**: - `dsn`: DSN string or a type that can be converted into a DSN. - **Return Value**: On success, returns a `RawResult` of its own type; on failure, returns an error. - `fn client_version() -> &'static str` + - **Interface Description**: Gets the client version. - **Return Value**: Returns a static string of the client version. - `fn ping(&self, _: &mut Self::Target) -> RawResult<()>` + - **Interface Description**: Checks if the connection is still alive. - **Parameter Description**: - `_`: Mutable reference to the target connection. - **Return Value**: On success, returns an empty `RawResult`; on failure, returns an error. - `fn ready(&self) -> bool` + - **Interface Description**: Checks if it is ready to connect. - **Return Value**: Mostly returns `true`, indicating the address is ready for connection. @@ -168,20 +166,24 @@ Executing SQL primarily uses the Taos struct, and obtaining the result set and m The Taos struct provides multiple database operation APIs, including: executing SQL, schema-less writing, and some common database query encapsulations (such as creating databases, fetching) - `pub fn is_native(&self) -> bool` + - **Interface Description**: Determines if the connection uses a native protocol. - **Return Value**: Returns `true` if using a native protocol, otherwise returns `false`. - `pub fn is_ws(&self) -> bool` + - **Interface Description**: Determines if the connection uses the WebSocket protocol. - **Return Value**: Returns `true` if using the WebSocket protocol, otherwise returns `false`. - `fn query>(&self, sql: T) -> RawResult` + - **Interface Description**: Executes an SQL query. - **Parameter Description**: - `sql`: The SQL statement to execute. - **Return Value**: On success, returns a `RawResult` of the `ResultSet`; on failure, returns an error. - `fn query_with_req_id>(&self, sql: T, req_id: u64) -> RawResult` + - **Interface Description**: Executes an SQL query with a request ID. - **Parameter Description**: - `sql`: The SQL statement to execute. @@ -189,28 +191,33 @@ The Taos struct provides multiple database operation APIs, including: executing - **Return Value**: On success, returns a `RawResult` of the `ResultSet`; on failure, returns an error. - `fn exec>(&self, sql: T) -> RawResult` + - **Interface Description**: Executes an SQL statement. - **Parameter Description**: - `sql`: The SQL statement to execute. - **Return Value**: On success, returns the number of affected rows; on failure, returns an error. - `fn exec_many, I: IntoIterator>(&self, input: I) -> RawResult` + - **Interface Description**: Executes multiple SQL statements in batch. - **Parameter Description**: - `input`: Collection of SQL statements to execute. - **Return Value**: On success, returns the total number of affected rows; on failure, returns an error. - `fn query_one, O: DeserializeOwned>(&self, sql: T) -> RawResult>` + - **Interface Description**: Executes an SQL query and returns a single result. - **Parameter Description**: - `sql`: The SQL statement to execute. - **Return Value**: On success, returns an optional result object; on failure, returns an error. - `fn server_version(&self) -> RawResult>` + - **Interface Description**: Gets the server version. - **Return Value**: On success, returns the server version string as a `RawResult`; on failure, returns an error. - `fn create_topic(&self, name: impl AsRef, sql: impl AsRef) -> RawResult<()>` + - **Interface Description**: Creates a topic. - **Parameter Description**: - `name`: The name of the topic. @@ -218,20 +225,24 @@ The Taos struct provides multiple database operation APIs, including: executing - **Return Value**: On success, returns an empty `RawResult`; on failure, returns an error. - `fn databases(&self) -> RawResult>` + - **Interface Description**: Retrieves a list of databases. - **Return Value**: On success, returns a list of databases as a `RawResult`; on failure, returns an error. - `fn topics(&self) -> RawResult>` + - **Interface Description**: Retrieves topic information. - **Return Value**: On success, returns a list of topics as a `RawResult`; on failure, returns an error. - `fn describe(&self, table: &str) -> RawResult` + - **Interface Description**: Describes the table structure. - **Parameter Description**: - `table`: The name of the table. - **Return Value**: On success, returns a description of the table structure as a `RawResult`; on failure, returns an error. - `fn database_exists(&self, name: &str) -> RawResult` + - **Interface Description**: Checks if a database exists. - **Parameter Description**: - `name`: The name of the database. @@ -243,11 +254,12 @@ The Taos struct provides multiple database operation APIs, including: executing - `data`: Schema-less data. - **Return Value**: On success, returns an empty `RawResult`; on failure, returns an error. -### SmlData +### SmlData The SmlData structure provides a data structure for schema-less writing and methods for accessing properties. - `pub struct SmlData` + - **Structure Description**: The `SmlData` structure is used to store schema-less data and related information. - **Field Description**: - `protocol`: Schema-less protocol, supports InfluxDB `Line`, OpenTSDB `Telnet`, OpenTSDB `Json`. @@ -257,18 +269,22 @@ The SmlData structure provides a data structure for schema-less writing and meth - `req_id`: Request ID. - `pub fn protocol(&self) -> SchemalessProtocol` + - **Interface Description**: Gets the schema-less protocol. - **Return Value**: Schema-less protocol type, supports InfluxDB `Line`, OpenTSDB `Telnet`, OpenTSDB `Json`. - `pub fn precision(&self) -> SchemalessPrecision` + - **Interface Description**: Gets the timestamp precision. - **Return Value**: Timestamp precision type, supports `Hours`, `Minutes`, `Seconds`, `Millisecond` (default), `Microsecond`, `Nanosecond`. - `pub fn data(&self) -> &Vec` + - **Interface Description**: Retrieves the list of data. - **Return Value**: Reference to the list of data. - `pub fn ttl(&self) -> Option` + - **Interface Description**: Get the data time-to-live. - **Return Value**: Time-to-live of the data (optional), in seconds. @@ -276,41 +292,49 @@ The SmlData structure provides a data structure for schema-less writing and meth - **Interface Description**: Get the request ID. - **Return Value**: Request ID (optional). -### Result Retrieval +### Result Retrieval #### ResultSet The ResultSet structure provides methods for accessing the data and metadata of the result set. - `fn affected_rows(&self) -> i32` + - **Interface Description**: Get the number of affected rows. - **Return Value**: Number of affected rows, type `i32`. - `fn precision(&self) -> Precision` + - **Interface Description**: Get precision information. - **Return Value**: Precision information, type `Precision`. - `fn fields(&self) -> &[Field]` + - **Interface Description**: Get field information. See the Field structure description below. - **Return Value**: Reference to an array of field information. - `fn summary(&self) -> (usize, usize)` + - **Interface Description**: Get summary information. - **Return Value**: A tuple containing two `usize` types, representing some statistical information. - `fn num_of_fields(&self) -> usize` + - **Interface Description**: Get the number of fields. - **Return Value**: Number of fields, type `usize`. - `fn blocks(&mut self) -> IBlockIter<'_, Self>` + - **Interface Description**: Get an iterator for the raw data blocks. - **Return Value**: Iterator for the raw data blocks, type `IBlockIter<'_, Self>`. - `fn rows(&mut self) -> IRowsIter<'_, Self>` + - **Interface Description**: Get an iterator for row-wise querying. - **Return Value**: Iterator for row-wise querying, type `IRowsIter<'_, Self>`. - `fn deserialize(&mut self) -> Map, fn(_: Result, Error>) -> Result>` + - **Interface Description**: Deserialize row data. - **Generic Parameters**: - `T`: Target type, must implement `DeserializeOwned`. @@ -320,15 +344,17 @@ The ResultSet structure provides methods for accessing the data and metadata of - **Interface Description**: Convert the result set into a two-dimensional vector of values. - **Return Value**: On success, returns a two-dimensional vector of values, on failure returns an error, type `Result>, Error>`. -#### Field +#### Field The Field structure provides methods for accessing field information. - `pub const fn empty() -> Field` + - **Interface Description**: Create an empty `Field` instance. - **Return Value**: Returns an empty `Field` instance. - `pub fn new(name: impl Into, ty: Ty, bytes: u32) -> Field` + - **Interface Description**: Create a new `Field` instance. - **Parameter Description**: - `name`: Field name. @@ -337,22 +363,27 @@ The Field structure provides methods for accessing field information. - **Return Value**: Returns a new `Field` instance. - `pub fn name(&self) -> &str` + - **Interface Description**: Get the field name. - **Return Value**: Returns the field name. - `pub fn escaped_name(&self) -> String` + - **Interface Description**: Get the escaped field name. - **Return Value**: Returns the escaped field name. - `pub const fn ty(&self) -> Ty` + - **Interface Description**: Get the field type. - **Return Value**: Returns the field type. - `pub const fn bytes(&self) -> u32` + - **Interface Description**: Get the preset length of the field. - **Return Value**: For variable-length data types, returns the preset length; for other types, returns the byte width. - `pub fn to_c_field(&self) -> c_field_t` + - **Interface Description**: Converts a `Field` instance into a C language structure. - **Return Value**: Returns the field represented by a C language structure. @@ -364,17 +395,19 @@ The Field structure provides methods for accessing field information. Parameter binding functionality is mainly supported by the Stmt structure. -#### Stmt +#### Stmt The Stmt structure provides functionality related to parameter binding, used for efficient writing. - `fn init(taos: &Q) -> RawResult` + - **Interface Description**: Initialize the parameter binding instance. - **Parameter Description**: - `taos`: Database connection instance. - **Return Value**: On success, returns the initialized instance; on failure, returns an error. - `fn init_with_req_id(taos: &Q, req_id: u64) -> RawResult` + - **Interface Description**: Initialize the parameter binding instance using a request ID. - **Parameter Description**: - `taos`: Database connection instance. @@ -382,24 +415,28 @@ The Stmt structure provides functionality related to parameter binding, used for - **Return Value**: On success, returns the initialized instance; on failure, returns an error. - `fn prepare>(&mut self, sql: S) -> RawResult<&mut Self>` + - **Interface Description**: Prepare the SQL statement to be bound. - **Parameter Description**: - `sql`: SQL statement to prepare. - **Return Value**: On success, returns a mutable reference to itself; on failure, returns an error. - `fn set_tbname>(&mut self, name: S) -> RawResult<&mut Self>` + - **Interface Description**: Set the table name. - **Parameter Description**: - `name`: Table name. - **Return Value**: On success, returns a mutable reference to itself; on failure, returns an error. - `fn set_tags(&mut self, tags: &[Value]) -> RawResult<&mut Self>` + - **Interface Description**: Set tags. - **Parameter Description**: - `tags`: Array of tags. - **Return Value**: On success, returns a mutable reference to itself; on failure, returns an error. - `fn set_tbname_tags>(&mut self, name: S, tags: &[Value]) -> RawResult<&mut Self>` + - **Interface Description**: Set the table name and tags. - **Parameter Description**: - `name`: Table name. @@ -407,16 +444,19 @@ The Stmt structure provides functionality related to parameter binding, used for - **Return Value**: On success, returns a mutable reference to itself; on failure, returns an error. - `fn bind(&mut self, params: &[ColumnView]) -> RawResult<&mut Self>` + - **Interface Description**: Bind parameters. - **Parameter Description**: - `params`: Array of parameters. - **Return Value**: On success, returns a mutable reference to itself; on failure, returns an error. - `fn add_batch(&mut self) -> RawResult<&mut Self>` + - **Interface Description**: Add a batch. - **Return Value**: On success, returns a mutable reference to itself; on failure, returns an error. - `fn execute(&mut self) -> RawResult` + - **Interface Description**: Execute the statement. - **Return Value**: On success, returns the number of affected rows; on failure, returns an error. @@ -433,26 +473,31 @@ Data subscription mainly involves three structures, providing connection establi Similar to TaosBuilder, TmqBuilder provides the functionality to create consumer objects. - `fn available_params() -> &'static [&'static str]` + - **Interface Description**: Get the list of available parameters in the DSN. - **Return Value**: Returns a reference to a static slice of strings, containing the names of available parameters. - `fn from_dsn(dsn: D) -> RawResult` + - **Interface Description**: Create a connection using a DSN string, without checking the connection. - **Parameter Description**: - `dsn`: DSN string or a type that can be converted into DSN. - **Return Value**: On success, returns `RawResult` of its own type, on failure returns an error. - `fn client_version() -> &'static str` + - **Interface Description**: Get the client version. - **Return Value**: Returns a static string of the client version. - `fn ping(&self, conn: &mut Self::Target) -> RawResult<()>` + - **Interface Description**: Check if the connection is still alive. - **Parameter Description**: - `conn`: Mutable reference to the target connection. - **Return Value**: On success, returns an empty `RawResult`, on failure returns an error. - `fn ready(&self) -> bool` + - **Interface Description**: Check if it is ready to connect. - **Return Value**: Mostly returns `true`, indicating that the address is ready to connect. @@ -465,24 +510,28 @@ Similar to TaosBuilder, TmqBuilder provides the functionality to create consumer The Consumer structure provides subscription-related functionalities, including subscribing, fetching messages, committing offsets, setting offsets, etc. - `fn subscribe, I: IntoIterator + Send>(&mut self, topics: I) -> RawResult<()>` + - **Interface Description**: Subscribe to a series of topics. - **Parameter Description**: - `topics`: List of topics to subscribe to. - **Return Value**: On success, returns an empty `RawResult`, on failure returns an error. - `fn recv_timeout(&self, timeout: Timeout) -> RawResult)>>` + - **Interface Description**: Receive messages within a specified timeout period. - **Parameter Description**: - `timeout`: Timeout period. - **Return Value**: On success, returns messages, on failure returns an error. - `fn commit(&self, offset: Self::Offset) -> RawResult<()>` + - **Interface Description**: Commit the given offset. - **Parameter Description**: - `offset`: The offset to commit, see the Offset structure below. - **Return Value**: On success, returns an empty `RawResult`, on failure returns an error. - `fn commit_offset(&self, topic_name: &str, vgroup_id: VGroupId, offset: i64) -> RawResult<()>` + - **Interface Description**: Commit offset for a specific topic and partition. - **Parameter Description**: - `topic_name`: Topic name. @@ -491,14 +540,17 @@ The Consumer structure provides subscription-related functionalities, including - **Return Value**: On success, returns an empty `RawResult`, on failure returns an error. - `fn list_topics(&self) -> RawResult>` + - **Interface Description**: List all available topics. - **Return Value**: On success, returns a list of topics, on failure returns an error. - `fn assignments(&self) -> Option)>>` + - **Interface Description**: Get the current assignments of topics and partitions. - **Return Value**: On success, returns assignment information, on failure returns `None`. - `fn offset_seek(&mut self, topic: &str, vg_id: VGroupId, offset: i64) -> RawResult<()>` + - **Interface Description**: Set the offset for a specific topic and partition. - **Parameter Description**: - `topic`: Topic name. @@ -507,6 +559,7 @@ The Consumer structure provides subscription-related functionalities, including - **Return Value**: On success, returns an empty `RawResult`, on failure returns an error. - `fn committed(&self, topic: &str, vgroup_id: VGroupId) -> RawResult` + - **Interface Description**: Get the committed offset for a specific topic and partition. - **Parameter Description**: - `topic`: Topic name. @@ -525,10 +578,12 @@ The Consumer structure provides subscription-related functionalities, including The Offset structure provides information about the database, topic, and partition to which the current message belongs. - `fn database(&self) -> &str` + - **Interface Description**: Get the database name of the current message. - **Return Value**: Reference to the database name. - `fn topic(&self) -> &str` + - **Interface Description**: Get the topic name of the current message. - **Return Value**: Reference to the topic name. @@ -536,7 +591,7 @@ The Offset structure provides information about the database, topic, and partiti - **Interface Description**: Get the partition ID of the current message. - **Return Value**: Partition ID. -## Appendix +## Appendix - [Rust connector documentation](https://docs.rs/taos) - [Rust connector project URL](https://github.com/taosdata/taos-connector-rust) diff --git a/docs/en/14-reference/05-connector/30-python.mdx b/docs/en/14-reference/05-connector/30-python.mdx index 058f21de7f..abf8302f4f 100644 --- a/docs/en/14-reference/05-connector/30-python.mdx +++ b/docs/en/14-reference/05-connector/30-python.mdx @@ -8,55 +8,70 @@ import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem"; import RequestId from "./_request_id.mdx"; -`taospy` is the official Python connector for TDengine. `taospy` provides a rich API, making it convenient for Python applications to use TDengine. +`taopsy` is the official connector provided by TDengine database for Python language, which provides multiple access interfaces for database writing, querying, subscribing, etc. -The source code for the Python connector is hosted on [GitHub](https://github.com/taosdata/taos-connector-python). +The installation command is as follows: +``` bash +# Native connection and REST connection +pip3 install taospy + +# WebSocket connection, optional installation +pip3 install taos-ws-py +``` + +The connector code is open sourced and hosted on Github [Taos Connector Python](https://github.com/taosdata/taos-connector-python). ## Connection Methods -`taospy` mainly provides three types of connectors. We generally recommend using **WebSocket Connection**. +`taopsy` provides three connection methods, and we recommend using WebSocket connection. -- **Native Connection**, corresponding to the `taos` module of the `taospy` package. Connects to a TDengine instance natively through the TDengine client driver (taosc), supporting data writing, querying, data subscription, schemaless interface, and parameter binding interface. -- **REST Connection**, corresponding to the `taosrest` module of the `taospy` package. Connects to a TDengine instance through the HTTP interface provided by taosAdapter, does not support schemaless and data subscription features. -- **WebSocket Connection**, corresponding to the `taos-ws-py` package, which is optional. Connects to a TDengine instance through the WebSocket interface provided by taosAdapter, with a feature set slightly different from the native connection. +- **Native Connection**, Python connector loads TDengine client driver (libtaos.so/taos.dll), directly connects to TDengine instance, with high performance and fast speed. + Functionally, it supports functions such as data writing, querying, data subscription, schemaless interface, and parameter binding interface. +- **REST Connection**, The Python connector connects to the TDengine instance through the HTTP interface provided by the taosAdapter, with minimal dependencies and no need to install the TDengine client driver. + Functionality does not support features such as schemaless and data subscription. +- **WebSocket Connection**, The Python connector connects to the TDengine instance through the WebSocket interface provided by the taosAdapter, which combines the advantages of the first two types of connections, namely high performance and low dependency. + In terms of functionality, there are slight differences between the WebSocket connection implementation feature set and native connections. -For a detailed introduction to connection methods, please refer to: [Connection Methods](../../../developer-guide/connecting-to-tdengine/) +For a detailed introduction of the connection method, please refer to: [Connection Method](../../../developer-guide/connecting-to-tdengine/) -In addition to encapsulating the native and REST interfaces, `taospy` also provides a programming interface compliant with [Python Data Access Standard (PEP 249)](https://peps.python.org/pep-0249/). This makes `taospy` easily integrated with many third-party tools, such as [SQLAlchemy](https://www.sqlalchemy.org/) and [pandas](https://pandas.pydata.org/). +In addition to encapsulating Native and REST interfaces, `taopsy` also provides compliance with [the Python Data Access Specification (PEP 249)](https://peps.python.org/pep-0249/) The programming interface. +This makes it easy to integrate `taopsy` with many third-party tools, such as [SQLAlchemy](https://www.sqlalchemy.org/) and [pandas](https://pandas.pydata.org/). -The method of establishing a connection directly with the server using the native interface provided by the client driver is referred to as "Native Connection"; the method of establishing a connection with the server using the REST interface or WebSocket interface provided by taosAdapter is referred to as "REST Connection" or "WebSocket Connection". +The method of establishing a connection directly with the server using the native interface provided by the client driver is referred to as "Native Connection" in the following text; +The method of establishing a connection with the server using the REST interface or WebSocket interface provided by the taosAdapter is referred to as a "REST Connection" or "WebSocket connection" in the following text. + +## Python Version Compatibility + +Supports Python 3.0 and above. ## Supported Platforms -- Native Connection [Supported Platforms](../../supported-platforms/) are consistent with the platforms supported by the TDengine client. -- REST Connection supports all platforms that can run Python. +-The platforms supported by native connections are consistent with those supported by the TDengine client driver. +-WebSocket/REST connections support all platforms that can run Python. -### Supported Features +## Versions History -- Native Connection supports all core features of TDengine, including: connection management, executing SQL, parameter binding, subscription, schemaless writing. -- REST Connection supports features including: connection management, executing SQL. (Through executing SQL, you can: manage databases, manage tables and supertables, write data, query data, create continuous queries, etc.) +Python Connector historical versions (it is recommended to use the latest version of 'taopsy'): -## Version History +|Python Connector Version | Major Changes | TDengine Version| +| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | +|2.7.16 | Add subscription configuration (session. timeout. ms, Max. roll. interval. ms). | - | +|2.7.15 | Added support for VARBINRY and GEOMETRY types. | - | +|2.7.14 | Fix Known Issues. | - | +|2.7.13 | Added tmq synchronous submission offset interface. | - | +|2.7.12 | 1. Added support for varbinary type (STMT currently does not support varbinary).
2 Query performance improvement (thanks to contributor [hadrianl](https://github.com/taosdata/taos-connector-python/pull/209) ). | 3.1.1.2 and higher| +|2.7.9 | Data subscription supports obtaining and resetting consumption progress. | 3.0.2.6 and higher| +|2.7.8 | Added 'executioner_many'. | 3.0.0.0 and higher| -Regardless of the version of TDengine used, it is recommended to use the latest version of `taospy`. +WebSocket Connector Historical Versions: -|Python Connector Version|Main Changes| -|:-------------------:|:----:| -|2.7.16|Added subscription configuration (session.timeout.ms, max.poll.interval.ms)| -|2.7.15|Added support for VARBINARY and GEOMETRY types| -|2.7.14|Fixed known issues| -|2.7.13|Added tmq synchronous commit offset interface| -|2.7.12|1. Added support for varbinary type (STMT does not support varbinary yet)
2. Improved query performance (thanks to contributor [hadrianl](https://github.com/taosdata/taos-connector-python/pull/209))| -|2.7.9|Data subscription supports obtaining consumption progress and resetting consumption progress| -|2.7.8|Added `execute_many`| - -|Python WebSocket Connector Version|Major Changes| -|:----------------------------:|:-----:| -|0.3.5|Added support for VARBINARY and GEOMETRY types, fixed known issues| -|0.3.2|Optimized WebSocket SQL query and insertion performance, updated readme and documentation, fixed known issues| -|0.2.9|Fixed known issues| -|0.2.5|1. Data subscription supports obtaining and resetting consumption progress
2. Supports schemaless
3. Supports STMT| -|0.2.4|Data subscription adds unsubscribe method| +|WebSocket Connector Version | Major Changes | TDengine Version| +| ----------------------- | -------------------------------------------------------------------------------------------------- | ----------------- | +|0.3.5 | Added support for VARBINARY and GEOMETRY types, fixed known issues. | 3.3.0.0 and higher| +|0.3.2 | Optimize WebSocket SQL query and insertion performance, modify readme and documentation, fix known issues. | 3.2.3.0 and higher| +|0.2.9 | Known issue fixes. | - | +|0.2.5 | 1. Data subscription supports obtaining and resetting consumption progress.
2 Support schemaless.
3 Support STMT. | - | +|0.2.4 | Data Subscription Addition/Unsubscribe Method. | 3.0.5.0 and higher| ## Exception Handling @@ -69,7 +84,7 @@ The Python connector may generate 4 types of exceptions: - For other TDengine module errors, please refer to [Error Codes](../../error-codes/) |Error Type|Description|Suggested Actions| -|:--------:|:---------:|:---------------:| +|:---------|:----------|:----------------| |InterfaceError|taosc version too low, does not support the used interface|Please check the TDengine client version| |ConnectionError|Database connection error|Please check the TDengine server status and connection parameters| |DatabaseError|Database error|Please check the TDengine server version and upgrade the Python connector to the latest version| @@ -94,7 +109,7 @@ All database operations in the Python Connector, if an exception occurs, will be TDengine currently supports timestamp, numeric, character, boolean types, and the corresponding Python type conversions are as follows: |TDengine DataType|Python DataType| -|:---------------:|:-------------:| +|:---------------|:--------------| |TIMESTAMP|datetime| |INT|int| |BIGINT|int| diff --git a/docs/en/14-reference/05-connector/35-node.mdx b/docs/en/14-reference/05-connector/35-node.mdx index 202f151469..3dde87fd5b 100644 --- a/docs/en/14-reference/05-connector/35-node.mdx +++ b/docs/en/14-reference/05-connector/35-node.mdx @@ -12,23 +12,21 @@ import RequestId from "./_request_id.mdx"; The source code for the Node.js connector is hosted on [GitHub](https://github.com/taosdata/taos-connector-node/tree/main). -## Connection Method +## Node.js Version Compatibility -The Node.js connector currently only supports WebSocket connections, which connect to a TDengine instance through the WebSocket interface provided by taosAdapter. - -For a detailed introduction to the connection method, please refer to: [Connection Method](../../../developer-guide/connecting-to-tdengine/) +- Supports Node.js 14 and above. ## Supported Platforms -Supports Node.js version 14 and above. +- Support all platforms that can run Node.js. ## Version History | Node.js Connector Version | Major Changes | TDengine Version | -| :------------------: | :----------------------: | :----------------: | -| 3.1.2 | Optimized data protocol and parsing, significantly improved performance| 3.3.2.0 and higher versions | -| 3.1.1 | Optimized data transmission performance | 3.3.2.0 and higher versions | -| 3.1.0 | New release, supports WebSocket connection | 3.2.0.0 and higher versions | +| ------------------ | ---------------------- | ----------------| +| 3.1.2 | Optimized data protocol and parsing, significantly improved performance.| - | +| 3.1.1 | Optimized data transmission performance. | 3.3.2.0 and higher versions | +| 3.1.0 | New release, supports WebSocket connection. | 3.2.0.0 and higher versions | ## Exception Handling diff --git a/docs/en/14-reference/05-connector/40-csharp.mdx b/docs/en/14-reference/05-connector/40-csharp.mdx index 0012b483ec..42d8238189 100644 --- a/docs/en/14-reference/05-connector/40-csharp.mdx +++ b/docs/en/14-reference/05-connector/40-csharp.mdx @@ -10,38 +10,27 @@ import RequestId from "./_request_id.mdx"; `TDengine.Connector` is the C# language connector provided by TDengine. C# developers can use it to develop C# applications that access data in the TDengine cluster. -## Connection Methods +## .Net Version Compatibility -`TDengine.Connector` provides two types of connectors: - -* **Native Connection**, which connects to a TDengine instance natively through the TDengine client driver (taosc), supporting data writing, querying, data subscription, schemaless interfaces, and parameter binding interfaces. -* **WebSocket Connection**, which connects to a TDengine instance through the WebSocket interface provided by taosAdapter, with a slightly different set of features implemented compared to the native connection. (From v3.0.1 onwards) - -For a detailed introduction to connection methods, please refer to: [Connection Methods](../../../developer-guide/connecting-to-tdengine/) - -## Compatibility - -* `TDengine.Connector` version 3.1.0 has been completely restructured and is no longer compatible with versions 3.0.2 and earlier. For documentation on version 3.0.2, please refer to [nuget](https://www.nuget.org/packages/TDengine.Connector/3.0.2) -* `TDengine.Connector` 3.x is not compatible with TDengine 2.x. If you need to use the C# connector in an environment running TDengine 2.x, please use version 1.x of TDengine.Connector. +- Supports .NET Framework 4.6 and above. +- Supports .NET 5.0 and above. ## Supported Platforms -The supported platforms are consistent with those supported by the TDengine client driver. +- Native connection supports the same platforms as the TDengine client driver. +- WebSocket connection supports all platforms that can run the .NET runtime. -:::warning -TDengine no longer supports the 32-bit Windows platform. -::: +## Version History -## Version Support +| Connector Version | Major Changes | TDengine Version | +|------------------|-------------------------------------------------|-------------------| +| 3.1.4 | Improved WebSocket query and insert performance. | 3.3.2.0 and higher | +| 3.1.3 | Supported WebSocket auto-reconnect. | - | +| 3.1.2 | Fixed schemaless resource release. | - | +| 3.1.1 | Supported varbinary and geometry types. | - | +| 3.1.0 | WebSocket uses a native C# implementation. | 3.2.1.0 and higher | -| **Connector Version** | **TDengine Version** | **Main Features** | -|------------------|------------------|----------------------------| -| 3.1.3 | 3.2.1.0/3.1.1.18 | Supports WebSocket auto-reconnect | -| 3.1.2 | 3.2.1.0/3.1.1.18 | Fixes schemaless resource release | -| 3.1.1 | 3.2.1.0/3.1.1.18 | Supports varbinary and geometry types | -| 3.1.0 | 3.2.1.0/3.1.1.18 | Native implementation of WebSocket | - -## Exception Handling +## Exceptions and Error Codes `TDengine.Connector` will throw exceptions, and applications need to handle these exceptions. The taosc exception type `TDengineError` includes an error code and error message, which applications can use to handle the error. For error reporting in other TDengine modules, please refer to [Error Codes](../../error-codes/) diff --git a/docs/en/14-reference/05-connector/50-odbc.mdx b/docs/en/14-reference/05-connector/50-odbc.mdx index 7d99568d63..aa015b7ba7 100644 --- a/docs/en/14-reference/05-connector/50-odbc.mdx +++ b/docs/en/14-reference/05-connector/50-odbc.mdx @@ -20,7 +20,7 @@ TDengine ODBC provides both 64-bit and 32-bit drivers. However, the 32-bit versi ## ODBC Version Compatibility -- Supports ODBC 3.8 and all previous versions. +- Supports all ODBC versions. ## Installation @@ -119,12 +119,12 @@ In addition to this, the WebSocket connection method also supports 32-bit applic ## Version History -| taos_odbc Version | Main Changes | TDengine Version | -| :----------- | :-------------------------------------------------------------------------------------------------- | :---------------- | -| v1.1.0 | 1. Supports view functionality;
2. Supports VARBINARY/GEOMETRY data types;
3. Supports ODBC 32-bit WebSocket connection method (Enterprise edition only);
4. Supports ODBC data source configuration dialog settings for compatibility adaptation options for industrial software like KingSCADA, Kepware, etc. (Enterprise edition only); | 3.3.3.0 and higher | -| v1.0.2 | Supports CP1252 character encoding; | 3.2.3.0 and higher | -| v1.0.1 | 1. Supports DSN settings for BI mode, in BI mode TDengine database does not return system database and supertable subtable information;
2. Refactored character set conversion module, improving read and write performance;
3. Default connection method in ODBC data source configuration dialog changed to "WebSocket";
4. Added "Test Connection" control in ODBC data source configuration dialog;
5. ODBC data source configuration supports Chinese/English interface; | - | -| v1.0.0.0 | Initial release, supports interacting with Tdengine database to read and write data, refer to the "API Reference" section for details | 3.2.2.0 and higher | +| taos_odbc Version | Major Changes | TDengine Version | +| ----------- | -------------------------------------------------------------------------------------------------- | ---------------- | +| v1.1.0 | 1. Supports view functionality.
2. Supports VARBINARY/GEOMETRY data types.
3. Supports ODBC 32-bit WebSocket connection method (Enterprise edition only).
4. Supports ODBC data source configuration dialog settings for compatibility adaptation options for industrial software like KingSCADA, Kepware, etc. (Enterprise edition only). | 3.3.3.0 and higher | +| v1.0.2 | Supports CP1252 character encoding. | 3.2.3.0 and higher | +| v1.0.1 | 1. Supports DSN settings for BI mode, in BI mode TDengine database does not return system database and supertable subtable information.
2. Refactored character set conversion module, improving read and write performance.
3. Default connection method in ODBC data source configuration dialog changed to "WebSocket".
4. Added "Test Connection" control in ODBC data source configuration dialog.
5. ODBC data source configuration supports Chinese/English interface. | - | +| v1.0.0.0 | Initial release, supports interacting with Tdengine database to read and write data, refer to the "API Reference" section for details. | 3.2.2.0 and higher | ## Data Type Mapping diff --git a/docs/examples/node/websocketexample/sql_example.js b/docs/examples/node/websocketexample/sql_example.js index c120b84d99..7e78bb6c64 100644 --- a/docs/examples/node/websocketexample/sql_example.js +++ b/docs/examples/node/websocketexample/sql_example.js @@ -26,7 +26,6 @@ async function createDbAndTable() { let conf = new taos.WSConfig(dsn); conf.setUser('root'); conf.setPwd('taosdata'); - conf.setDb('power'); wsSql = await taos.sqlConnect(conf); console.log("Connected to " + dsn + " successfully."); // create database diff --git a/docs/zh/14-reference/05-connector/10-cpp.mdx b/docs/zh/14-reference/05-connector/10-cpp.mdx index 7164baad2a..215cf6ed69 100644 --- a/docs/zh/14-reference/05-connector/10-cpp.mdx +++ b/docs/zh/14-reference/05-connector/10-cpp.mdx @@ -37,8 +37,8 @@ TDengine 客户端驱动的动态库位于： ### 版本历史 | TDengine 客户端版本 | 主要变化 | TDengine 版本 | -| :------------------: | :---------------------------: | :----------------: | -| 3.3.3.0 | 首次发布，提供了 SQL执行，参数绑定，无模式写入和数据订阅等全面功能支持。 | 3.3.2.0及更高版本 | +| ------------------ | --------------------------- | ---------------- | +| 3.3.3.0 | 首次发布，提供了 SQL执行，参数绑定，无模式写入和数据订阅等全面功能支持。 | 3.3.2.0 及更高版本 | ### 错误码 diff --git a/docs/zh/14-reference/05-connector/14-java.mdx b/docs/zh/14-reference/05-connector/14-java.mdx index a90d66235e..17c10ba313 100644 --- a/docs/zh/14-reference/05-connector/14-java.mdx +++ b/docs/zh/14-reference/05-connector/14-java.mdx @@ -19,7 +19,7 @@ TDengine 的 JDBC 驱动实现尽可能与关系型数据库驱动保持一致 ::: -## JDBC 和 JRE 兼容性 +## JDBC 和 JRE 版本兼容性 - JDBC: 支持 JDBC 4.2 及以上版本。 - JRE: 支持 JRE 8 及以上版本。 @@ -32,7 +32,7 @@ TDengine 的 JDBC 驱动实现尽可能与关系型数据库驱动保持一致 ## 版本历史 | taos-jdbcdriver 版本 | 主要变化 | TDengine 版本 | -| :------------------| :---------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------- | +| ------------------| ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | | 3.4.0 | 1. 使用 jackson 库替换 fastjson 库
2. WebSocket 采用独立协议标识
3. 优化后台拉取线程使用，避免用户误用导致超时 | - | | 3.3.4 | 解决了 getInt 在数据类型为 float 报错 | - | | 3.3.3 | 解决了 WebSocket statement 关闭导致的内存泄漏 | - | diff --git a/docs/zh/14-reference/05-connector/20-go.mdx b/docs/zh/14-reference/05-connector/20-go.mdx index 03ddcf51cf..85c65a5fb8 100644 --- a/docs/zh/14-reference/05-connector/20-go.mdx +++ b/docs/zh/14-reference/05-connector/20-go.mdx @@ -12,9 +12,9 @@ import RequestId from "./_request_id.mdx"; `driver-go` 是 TDengine 的官方 Go 语言连接器，实现了 Go 语言 [database/sql](https://golang.org/pkg/database/sql/) 包的接口。Go 开发人员可以通过它开发存取 TDengine 集群数据的应用软件。 -## 兼容性 +## Go 版本兼容性 -支持 Go 版本 1.14及以上版本。 +支持 Go 1.14 及以上版本。 ## 支持的平台 @@ -23,24 +23,24 @@ import RequestId from "./_request_id.mdx"; ## 版本历史 -| driver-go 版本 | 主要变化 | TDengine 版本 | -|:-------------|:-------------------------------------|:------------| -| v3.5.8 | 修复空指针异常 | 3.3.2.0 | -| v3.5.7 | taosWS 和 taosRestful 支持传入 request id | 3.3.2.0 | -| v3.5.6 | 提升 websocket 查询和写入性能 | 3.3.2.0 | -| v3.5.5 | restful 支持跳过 ssl 证书检查 | 3.2.3.0 | -| v3.5.4 | 兼容 TDengine 3.3.0.0 tmq raw data | 3.2.3.0 | -| v3.5.3 | 重构 taosWS | 3.2.3.0 | -| v3.5.2 | websocket 压缩和优化消息订阅性能 | 3.2.3.0 | -| v3.5.1 | 原生 stmt 查询和 geometry 类型支持 | 3.2.1.0 | -| v3.5.0 | 获取消费进度及按照指定进度开始消费 | 3.0.5.0 | -| v3.3.1 | 基于 websocket 的 schemaless 协议写入 | 3.0.4.1 | -| v3.1.0 | 提供贴近 kafka 的订阅 api | 3.0.2.2 | -| v3.0.4 | 新增 request id 相关接口 | 3.0.2.2 | -| v3.0.3 | 基于 websocket 的 statement 写入 | 3.0.1.5 | -| v3.0.2 | 基于 websocket 的数据查询和写入 | 3.0.1.5 | -| v3.0.1 | 基于 websocket 的消息订阅 | 3.0.0.0 | -| v3.0.0 | 适配 TDengine 3.0 查询和写入 | 3.0.0.0 | +| driver-go 版本 | 主要变化 | TDengine 版本 | +|-------------|-------------------------------------|---------------| +| v3.5.8 | 修复空指针异常 | - | +| v3.5.7 | taosWS 和 taosRestful 支持传入 request id | - | +| v3.5.6 | 提升 websocket 查询和写入性能 | 3.3.2.0 及更高版本 | +| v3.5.5 | restful 支持跳过 ssl 证书检查 | - | +| v3.5.4 | 兼容 TDengine 3.3.0.0 tmq raw data | - | +| v3.5.3 | 重构 taosWS | - | +| v3.5.2 | websocket 压缩和优化消息订阅性能 | 3.2.3.0 及更高版本 | +| v3.5.1 | 原生 stmt 查询和 geometry 类型支持 | 3.2.1.0 及更高版本 | +| v3.5.0 | 获取消费进度及按照指定进度开始消费 | 3.0.5.0 及更高版本 | +| v3.3.1 | 基于 websocket 的 schemaless 协议写入 | 3.0.4.1 及更高版本 | +| v3.1.0 | 提供贴近 kafka 的订阅 api | - | +| v3.0.4 | 新增 request id 相关接口 | 3.0.2.2 及更高版本 | +| v3.0.3 | 基于 websocket 的 statement 写入 | - | +| v3.0.2 | 基于 websocket 的数据查询和写入 | 3.0.1.5 及更高版本 | +| v3.0.1 | 基于 websocket 的消息订阅 | - | +| v3.0.0 | 适配 TDengine 3.0 查询和写入 | 3.0.0.0 及更高版本 | ## 异常和错误码 diff --git a/docs/zh/14-reference/05-connector/26-rust.mdx b/docs/zh/14-reference/05-connector/26-rust.mdx index f14176f979..4baa4371a3 100644 --- a/docs/zh/14-reference/05-connector/26-rust.mdx +++ b/docs/zh/14-reference/05-connector/26-rust.mdx @@ -16,9 +16,9 @@ import RequestId from "./_request_id.mdx"; 该 Rust 连接器的源码托管在 [GitHub](https://github.com/taosdata/taos-connector-rust)。 -## Rust 兼容性 +## Rust 版本兼容性 -支持 1.70 及以上版本。 +支持 Rust 1.70 及以上版本。 ## 支持的平台 @@ -28,16 +28,16 @@ import RequestId from "./_request_id.mdx"; ## 版本历史 | Rust 连接器版本 | 主要变化 | TDengine 版本 | -| :-------------- | :---------------------------------------------------------------------------- | :----------------- | +| -------------- | ---------------------------------------------------------------------------- | ----------------- | | v0.12.3 | 1. 优化了 WebSocket 查询和插入性能
2. 支持了 VARBINARY 和 GEOMETRY 类型 | 3.3.0.0 及更高版本 | -| v0.12.0 | WS 支持压缩。 | 3.2.3.0 及更高版本 | -| v0.11.0 | TMQ 功能优化。 | 3.2.0.0 | -| v0.10.0 | WS endpoint 变更。 | 3.1.0.0 | -| v0.9.2 | STMT：ws 下获取 tag_fields、col_fields。 | 3.0.7.0 | -| v0.8.12 | 消息订阅：获取消费进度及按照指定进度开始消费。 | 3.0.5.0 | -| v0.8.0 | 支持无模式写入。 | 3.0.4.0 | -| v0.7.6 | 支持在请求中使用 req_id。 | 3.0.3.0 | -| v0.6.0 | 基础功能。 | 3.0.0.0 | +| v0.12.0 | WebSocket 支持压缩 | 3.2.3.0 及更高版本 | +| v0.11.0 | TMQ 功能优化 | 3.2.0.0 及更高版本 | +| v0.10.0 | WebSocket endpoint 变更 | 3.1.0.0 及更高版本 | +| v0.9.2 | STMT：WebSocket 下获取 tag_fields、col_fields | 3.0.7.0 及更高版本 | +| v0.8.12 | 消息订阅：获取消费进度及按照指定进度开始消费 | 3.0.5.0 及更高版本 | +| v0.8.0 | 支持无模式写入 | 3.0.4.0 及更高版本 | +| v0.7.6 | 支持在请求中使用 req_id | 3.0.3.0 及更高版本 | +| v0.6.0 | 基础功能 | 3.0.0.0 及更高版本 | ## 异常和错误码 diff --git a/docs/zh/14-reference/05-connector/30-python.mdx b/docs/zh/14-reference/05-connector/30-python.mdx index 3991477635..2a5c84a374 100644 --- a/docs/zh/14-reference/05-connector/30-python.mdx +++ b/docs/zh/14-reference/05-connector/30-python.mdx @@ -2,60 +2,74 @@ toc_max_heading_level: 4 sidebar_label: Python title: TDengine Python Connector -description: "taospy 是 TDengine 的官方 Python 连接器。taospy 提供了丰富的 API， 使得 Python 应用可以很方便地使用 TDengine。tasopy 对 TDengine 的原生接口和 REST 接口都进行了封装， 分别对应 tasopy 的两个子模块：taos 和 taosrest。除了对原生接口和 REST 接口的封装，taospy 还提供了符合 Python 数据访问规范(PEP 249)的编程接口。这使得 taospy 和很多第三方工具集成变得简单，比如 SQLAlchemy 和 pandas" +description: "TDengine 数据库面向 Python 语言提供的连接器" --- import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem"; import RequestId from "./_request_id.mdx"; -`taospy` 是 TDengine 的官方 Python 连接器。`taospy` 提供了丰富的 API， 使得 Python 应用可以很方便地使用 TDengine。 +`taospy` 是 TDengine 数据库面向 Python 语言提供的官方连接器，连接器对外提供对数据库写入、查询、订阅等多种访问接口。 -Python 连接器的源码托管在 [GitHub](https://github.com/taosdata/taos-connector-python)。 +安装连接器命令如下： +``` bash +# 原生连接和 REST 连接 +pip3 install taospy + +# WebSocket 连接，可选装 +pip3 install taos-ws-py +``` + +连接器代码对外开源，源码托管在 Github [taos-connector-python](https://github.com/taosdata/taos-connector-python) 仓库。 ## 连接方式 -`taospy`主要提供三种形式的连接器。一般我们推荐使用 **WebSocket 连接**。 -- **原生连接**，对应 `taospy` 包的 `taos` 模块。通过 TDengine 客户端驱动程序（taosc）原生连接 TDengine 实例，支持数据写入、查询、数据订阅、schemaless 接口和参数绑定接口等功能。 -- **REST 连接**，对应 `taospy` 包的 `taosrest` 模块。通过 taosAdapter 提供的 HTTP 接口连接 TDengine 实例，不支持 schemaless 和数据订阅等特性。 -- **WebSocket 连接**，对应 `taos-ws-py` 包，可以选装。通过 taosAdapter 提供的 WebSocket 接口连接 TDengine 实例，WebSocket 连接实现的功能集合和原生连接有少量不同。 + +`taospy`提供三种连接方式，我们推荐使用 **WebSocket 连接**。 + +- **原生连接**，Python 连接器加载 TDengine 客户端驱动程序(libtaos.so/taos.dll)，直接连接 TDengine 实例，特点性能高，速度快。功能上支持数据写入、查询、数据订阅、schemaless 接口和参数绑定接口等功能。对应 `taospy` 包的 `taos` 模块。 +- **REST 连接**，Python 连接器通过 `taosAdapter` 提供的 HTTP 接口连接 TDengine 实例，特点依赖小，不需要安装 TDengine 客户端驱动。功能上不支持 schemaless 和数据订阅等特性。对应 `taospy` 包的 `taosrest` 模块。 +- **WebSocket 连接**，Python 连接器通过 `taosAdapter` 提供的 WebSocket 接口连接 TDengine 实例，特点是兼具前两种连接的优势， 即性能高又依赖小。功能上 WebSocket 连接实现功能集合和原生连接有少量不同。对应 `taos-ws-py` 包，可以选装。 连接方式的详细介绍请参考：[连接方式](../../../develop/connect/#连接方式) 除了对原生接口和 REST 接口的封装，`taospy` 还提供了符合 [Python 数据访问规范(PEP 249)](https://peps.python.org/pep-0249/) 的编程接口。这使得 `taospy` 和很多第三方工具集成变得简单，比如 [SQLAlchemy](https://www.sqlalchemy.org/) 和 [pandas](https://pandas.pydata.org/)。 -使用客户端驱动提供的原生接口直接与服务端建立的连接的方式下文中称为“原生连接”；使用 taosAdapter 提供的 REST 接口或 WebSocket 接口与服务端建立的连接的方式下文中称为“REST 连接”或“WebSocket 连接”。 +使用客户端驱动提供的原生接口直接与服务端建立的连接的方式下文中称为“原生连接”；使用 `taosAdapter` 提供的 REST 接口或 WebSocket 接口与服务端建立的连接的方式下文中称为“REST 连接”或“WebSocket 连接”。 + +## Python 版本兼容性 + +支持 Python 3.0 及以上版本。 ## 支持的平台 -- 原生连接[支持的平台](../#支持的平台)和 TDengine 客户端支持的平台一致。 -- REST 连接支持所有能运行 Python 的平台。 - -### 支持的功能 - -- 原生连接支持 TDengine 的所有核心功能， 包括： 连接管理、执行 SQL、参数绑定、订阅、无模式写入（schemaless）。 -- REST 连接支持的功能包括：连接管理、执行 SQL。 (通过执行 SQL 可以： 管理数据库、管理表和超级表、写入数据、查询数据、创建连续查询等)。 +- 原生连接支持的平台和 TDengine 客户端驱动支持的平台一致。 +- WebSocket/REST 连接支持所有能运行 Python 的平台。 ## 历史版本 -无论使用什么版本的 TDengine 都建议使用最新版本的 `taospy`。 +Python Connector 历史版本（建议使用最新版本的 `taospy`）： -|Python Connector 版本|主要变化| -|:-------------------:|:----:| -|2.7.16|新增订阅配置 (session.timeout.ms, max.poll.interval.ms)| -|2.7.15|新增 VARBINARY 和 GEOMETRY 类型支持| -|2.7.14|修复已知问题| -|2.7.13|新增 tmq 同步提交 offset 接口| -|2.7.12|1. 新增 varbinary 类型支持（STMT暂不支持 varbinary ）
2. query 性能提升（感谢贡献者[hadrianl](https://github.com/taosdata/taos-connector-python/pull/209)）| -|2.7.9|数据订阅支持获取消费进度和重置消费进度| -|2.7.8|新增 `execute_many`| -|Python WebSocket Connector 版本|主要变化| -|:----------------------------:|:-----:| -|0.3.5|新增 VARBINARY 和 GEOMETRY 类型支持，修复已知问题| -|0.3.2|优化 WebSocket sql 查询和插入性能，修改 readme 和 文档，修复已知问题| -|0.2.9|已知问题修复| -|0.2.5|1. 数据订阅支持获取消费进度和重置消费进度
2. 支持 schemaless
3. 支持 STMT| -|0.2.4|数据订阅新增取消订阅方法| +| Python Connector 版本 | 主要变化 | TDengine 版本 | +| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | +| 2.7.16 | 新增订阅配置 (session.timeout.ms, max.poll.interval.ms) | - | +| 2.7.15 | 新增 VARBINARY 和 GEOMETRY 类型支持 | - | +| 2.7.14 | 修复已知问题 | - | +| 2.7.13 | 新增 tmq 同步提交 offset 接口 | - | +| 2.7.12 | 1. 新增 varbinary 类型支持（STMT暂不支持 varbinary ）
2. query 性能提升（感谢贡献者[hadrianl](https://github.com/taosdata/taos-connector-python/pull/209)） | 3.1.1.2 及更高版本 | +| 2.7.9 | 数据订阅支持获取消费进度和重置消费进度 | 3.0.2.6 及更高版本 | +| 2.7.8 | 新增 `execute_many` | 3.0.0.0 及更高版本 | + +WebSocket Connector 历史版本： + + +| WebSocket Connector 版本 | 主要变化 | TDengine 版本 | +| ----------------------- | ------------------------------------------------------------------------------------- | ----------------- | +| 0.3.5 | 新增 VARBINARY 和 GEOMETRY 类型支持，修复已知问题 | 3.3.0.0 及更高版本 | +| 0.3.2 | 优化 WebSocket sql 查询和插入性能，修改 readme 和 文档，修复已知问题 | 3.2.3.0 及更高版本 | +| 0.2.9 | 已知问题修复 | - | +| 0.2.5 | 1. 数据订阅支持获取消费进度和重置消费进度
2. 支持 schemaless
3. 支持 STMT | - | +| 0.2.4 | 数据订阅新增取消订阅方法 | 3.0.5.0 及更高版本 | ## 处理异常 @@ -67,17 +81,17 @@ Python 连接器可能会产生 4 种异常： - 数据订阅异常 - TDengine 其他功能模块的报错，请参考 [错误码](../../../reference/error-code) -|Error Type|Description|Suggested Actions| -|:--------:|:---------:|:---------------:| -|InterfaceError|taosc 版本太低，不支持所使用的接口|请检查 TDengine 客户端版本| -|ConnectionError|数据库链接错误|请检查 TDengine 服务端状态和连接参数| -|DatabaseError|数据库错误|请检查 TDengine 服务端版本，并将 Python 连接器升级到最新版| -|OperationalError|操作错误|API 使用错误，请检查代码| -|ProgrammingError|接口调用错误|请检查提交的数据是否正确| -|StatementError|stmt 相关异常|请检查绑定参数与 sql 是否匹配| -|ResultError|操作数据错误|请检查操作的数据与数据库中的数据类型是否匹配| -|SchemalessError|schemaless 相关异常|请检查数据格式及对应的协议类型是否正确| -|TmqError|tmq 相关异常|请检查 Topic 及 consumer 配置是否正确| +| Error Type | Description | Suggested Actions | +| :--------------- | :--------------------------------- | :--------------------------------------------------------- | +| InterfaceError | taosc 版本太低，不支持所使用的接口 | 请检查 TDengine 客户端版本 | +| ConnectionError | 数据库链接错误 | 请检查 TDengine 服务端状态和连接参数 | +| DatabaseError | 数据库错误 | 请检查 TDengine 服务端版本，并将 Python 连接器升级到最新版 | +| OperationalError | 操作错误 | API 使用错误，请检查代码 | +| ProgrammingError | 接口调用错误 | 请检查提交的数据是否正确 | +| StatementError | stmt 相关异常 | 请检查绑定参数与 sql 是否匹配 | +| ResultError | 操作数据错误 | 请检查操作的数据与数据库中的数据类型是否匹配 | +| SchemalessError | schemaless 相关异常 | 请检查数据格式及对应的协议类型是否正确 | +| TmqError | tmq 相关异常 | 请检查 Topic 及 consumer 配置是否正确 | Python 中通常通过 try-expect 处理异常，异常处理相关请参考 [Python 错误和异常文档](https://docs.python.org/3/tutorial/errors.html)。 TDengine 其他功能模块的报错，请参考 [错误码](../../../reference/error-code) @@ -92,32 +106,32 @@ Python Connector 的所有数据库操作如果出现异常，都会直接抛出 TDengine 目前支持时间戳、数字、字符、布尔类型，与 Python 对应类型转换如下： -|TDengine DataType|Python DataType| -|:---------------:|:-------------:| -|TIMESTAMP|datetime| -|INT|int| -|BIGINT|int| -|FLOAT|float| -|DOUBLE|int| -|SMALLINT|int| -|TINYINT|int| -|BOOL|bool| -|BINARY|str| -|NCHAR|str| -|JSON|str| -|GEOMETRY|bytearray| -|VARBINARY|bytearray| +| TDengine DataType | Python DataType | +| :---------------- | :-------------- | +| TIMESTAMP | datetime | +| INT | int | +| BIGINT | int | +| FLOAT | float | +| DOUBLE | int | +| SMALLINT | int | +| TINYINT | int | +| BOOL | bool | +| BINARY | str | +| NCHAR | str | +| JSON | str | +| GEOMETRY | bytearray | +| VARBINARY | bytearray | ## 示例程序汇总 -| 示例程序链接 | 示例程序内容 | -| ------------------------------------------------------------------------------------------------------------- | ----------------------- | -| [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 类型的标签 | -| [tmq_consumer.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/tmq_consumer.py) | tmq 订阅 | -| [native_all_type_query.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/native_all_type_query.py) | 支持全部类型示例 | -| [native_all_type_stmt.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/native_all_type_stmt.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 类型的标签 | +| [tmq_consumer.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/tmq_consumer.py) | tmq 订阅 | +| [native_all_type_query.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/native_all_type_query.py) | 支持全部类型示例 | +| [native_all_type_stmt.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/native_all_type_stmt.py) | 参数绑定支持全部类型示例 | 示例程序源码请参考： diff --git a/docs/zh/14-reference/05-connector/35-node.mdx b/docs/zh/14-reference/05-connector/35-node.mdx index df2abfab3d..d188da9e4b 100644 --- a/docs/zh/14-reference/05-connector/35-node.mdx +++ b/docs/zh/14-reference/05-connector/35-node.mdx @@ -9,26 +9,24 @@ import TabItem from "@theme/TabItem"; import RequestId from "./_request_id.mdx"; `@tdengine/websocket` 是 TDengine 的官方 Node.js 语言连接器。Node.js 开发人员可以通过它开发存取 TDengine 数据库的应用软件。 - Node.js 连接器源码托管在 [GitHub](https://github.com/taosdata/taos-connector-node/tree/main)。 -## 连接方式 +## Node.js 版本兼容性 -Node.js 连接器目前仅支持 WebSocket 连接器， 其通过 taosAdapter 提供的 WebSocket 接口连接 TDengine 实例。 - -连接方式的详细介绍请参考：[连接方式](../../../develop/connect/#连接方式) +- 支持 Node.js 14 及以上版本。 ## 支持的平台 -支持 Node.js 14及以上版本。 +- 支持所有能运行 Node.js 的平台。 + ## 版本历史 | Node.js 连接器 版本 | 主要变化 | TDengine 版本 | -| :------------------: | :----------------------: | :----------------: | -| 3.1.2 | 对数据协议和解析进行了优化，性能得到大幅提升| 3.3.2.0 及更高版本 | -| 3.1.1 | 优化了数据传输性能 | 3.3.2.0 及更高版本 | -| 3.1.0 | 新版本发布，支持 WebSocket 连接 | 3.2.0.0 及更高版本 | +| ------------------| ----------------------| ----------------| +| 3.1.2 | 对数据协议和解析进行了优化，性能得到大幅提升| - | +| 3.1.1 | 优化了数据传输性能 | 3.3.2.0 及更高版本 | +| 3.1.0 | 新版本发布，支持 WebSocket 连接 | 3.2.0.0 及更高版本 | ## 处理异常 diff --git a/docs/zh/14-reference/05-connector/40-csharp.mdx b/docs/zh/14-reference/05-connector/40-csharp.mdx index 488a50e812..f5f2d91863 100644 --- a/docs/zh/14-reference/05-connector/40-csharp.mdx +++ b/docs/zh/14-reference/05-connector/40-csharp.mdx @@ -10,12 +10,10 @@ import RequestId from "./_request_id.mdx"; `TDengine.Connector` 是 TDengine 提供的 C# 语言连接器。C# 开发人员可以通过它开发存取 TDengine 集群数据的 C# 应用软件。 -## 兼容性 +## .NET 版本兼容性 - .NET Framework 4.6 及以上版本。 - .NET 5.0 及以上版本。 -- `TDengine.Connector` 3.1.0 版本进行了完整的重构，不再兼容 3.0.2 及以前版本。3.0.2 文档请参考 [nuget](https://www.nuget.org/packages/TDengine.Connector/3.0.2) -- `TDengine.Connector` 3.x 不兼容 TDengine 2.x，如果在运行 TDengine 2.x 版本的环境下需要使用 C# 连接器请使用 TDengine.Connector 的 1.x 版本。 ## 支持的平台 @@ -24,13 +22,13 @@ import RequestId from "./_request_id.mdx"; ## 版本历史 -| Connector 版本 | 主要变化 | TDengine 版本 | -|:-------------|:---------------------------|:------------| -| 3.1.4 | 提升 websocket 查询和写入性能 | 3.3.2.0 | -| 3.1.3 | 支持 WebSocket 自动重连 | 3.2.1.0 | -| 3.1.2 | 修复 schemaless 资源释放 | 3.2.1.0 | -| 3.1.1 | 支持 varbinary 和 geometry 类型 | 3.2.1.0 | -| 3.1.0 | WebSocket 使用原生实现 | 3.2.1.0 | +| Connector 版本 | 主要变化 | TDengine 版本 | +|:-------------|:---------------------------|:--------------| +| 3.1.4 | 提升 websocket 查询和写入性能 | 3.3.2.0 及更高版本 | +| 3.1.3 | 支持 WebSocket 自动重连 | - | +| 3.1.2 | 修复 schemaless 资源释放 | - | +| 3.1.1 | 支持 varbinary 和 geometry 类型 | - | +| 3.1.0 | WebSocket 使用原生实现 | 3.2.1.0 及更高版本 | ## 处理异常 diff --git a/docs/zh/14-reference/05-connector/50-odbc.mdx b/docs/zh/14-reference/05-connector/50-odbc.mdx index 027099cc54..322e90e138 100644 --- a/docs/zh/14-reference/05-connector/50-odbc.mdx +++ b/docs/zh/14-reference/05-connector/50-odbc.mdx @@ -113,11 +113,11 @@ TDengine ODBC 支持两种连接 TDengine 数据库方式：WebSocket 连接与 ## 版本历史 | taos_odbc 版本 | 主要变化 | TDengine 版本 | -| :----------- | :-------------------------------------------------------------------------------------------------- | :---------------- | -| v1.1.0 | 1. 支持视图功能；
2. 支持 VARBINARY/GEOMETRY 数据类型；
3. 支持 ODBC 32 位 WebSocket 连接方式（仅企业版支持）；
4. 支持 ODBC 数据源配置对话框设置对工业软件 KingSCADA、Kepware 等的兼容性适配选项（仅企业版支持）； | 3.3.3.0及更高版本 | -| v1.0.2 | 支持 CP1252 字符编码； | 3.2.3.0及更高版本 | +| ----------- | -------------------------------------------------------------------------------------------------- | ---------------- | +| v1.1.0 | 1. 支持视图功能；
2. 支持 VARBINARY/GEOMETRY 数据类型；
3. 支持 ODBC 32 位 WebSocket 连接方式（仅企业版支持）；
4. 支持 ODBC 数据源配置对话框设置对工业软件 KingSCADA、Kepware 等的兼容性适配选项（仅企业版支持）； | 3.3.3.0 及更高版本 | +| v1.0.2 | 支持 CP1252 字符编码； | 3.2.3.0 及更高版本 | | v1.0.1 | 1. 支持 DSN 设置 BI 模式，在 BI 模式下 TDengine 数据库不返回系统数据库和超级表子表信息；
2. 重构字符集转换模块，提升读写性能；
3. ODBC 数据源配置对话框中默认修改默认连接方式为“WebSocket”；
4. ODBC 数据源配置对话框增加“测试连接”控件；
5. ODBC 数据源配置支持中文/英文界面； | - | -| v1.0.0.0 | 发布初始版本，支持与Tdengine数据库交互以读写数据，具体请参考“API 参考”一节 | 3.2.2.0及更高版本 | +| v1.0.0.0 | 发布初始版本，支持与Tdengine数据库交互以读写数据，具体请参考“API 参考”一节 | 3.2.2.0 及更高版本 | ## 数据类型映射 From 82a0414650af5bd050df72afa6a10a5b27168722 Mon Sep 17 00:00:00 2001 From: sheyanjie-qq <249478495@qq.com> Date: Fri, 13 Dec 2024 15:22:56 +0800 Subject: [PATCH 5/7] remove useless muti doc modify --- docs/zh/08-operation/12-multi.md | 44 ++++++++++++++++---------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/docs/zh/08-operation/12-multi.md b/docs/zh/08-operation/12-multi.md index 14db264522..d18957d7d2 100644 --- a/docs/zh/08-operation/12-multi.md +++ b/docs/zh/08-operation/12-multi.md @@ -68,19 +68,19 @@ dataDir /mnt/data6 2 0 在配置文件 /etc/taos/taos.cfg 中，添加用于 S3 访问的参数： -|参数名称 | 参数含义 | -|:-------------|:-----------------------------------------------| -|s3EndPoint | 用户所在地域的 COS 服务域名，支持 http 和 https，bucket 的区域需要与 endpoint 的保持一致，否则无法访问。 | -|s3AccessKey |冒号分隔的用户 SecretId:SecretKey。例如：AKIDsQmwsfKxTo2A6nGVXZN0UlofKn6JRRSJ:lIdoy99ygEacU7iHfogaN2Xq0yumSm1E | -|s3BucketName | 存储桶名称，减号后面是用户注册 COS 服务的 AppId。其中 AppId 是 COS 特有，AWS 和阿里云都没有，配置时需要作为 bucket name 的一部分，使用减号分隔。参数值均为字符串类型，但不需要引号。例如：test0711-1309024725 | -|s3UploadDelaySec | data 文件持续多长时间不再变动后上传至 s3，单位：秒。最小值：1；最大值：2592000 (30天），默认值 60 秒 | -|s3PageCacheSize |s3 page cache 缓存页数目，单位：页。最小值：4；最大值：1024*1024\*1024。 ，默认值 4096| -|s3MigrateIntervalSec | 本地数据文件自动上传 S3 的触发周期，单位为秒。最小值：600；最大值：100000。默认值 3600 | -|s3MigrateEnabled | 是否自动进行 S3 迁移，默认值为 0，表示关闭自动 S3 迁移，可配置为 1。 | +| 参数名称 | 参数含义 | +|:---------------------|:-----------------------------------------------| +| s3EndPoint | 用户所在地域的 COS 服务域名，支持 http 和 https，bucket 的区域需要与 endpoint 的保持一致，否则无法访问。 | +| s3AccessKey | 冒号分隔的用户 SecretId:SecretKey。例如：AKIDsQmwsfKxTo2A6nGVXZN0UlofKn6JRRSJ:lIdoy99ygEacU7iHfogaN2Xq0yumSm1E | +| s3BucketName | 存储桶名称，减号后面是用户注册 COS 服务的 AppId。其中 AppId 是 COS 特有，AWS 和阿里云都没有，配置时需要作为 bucket name 的一部分，使用减号分隔。参数值均为字符串类型，但不需要引号。例如：test0711-1309024725 | +| s3UploadDelaySec | data 文件持续多长时间不再变动后上传至 s3，单位：秒。最小值：1；最大值：2592000（30天），默认值 60 秒 | +| s3PageCacheSize | S3 page cache 缓存页数目，单位：页。最小值：4；最大值：1024*1024*1024。 ，默认值 4096| +| s3MigrateIntervalSec | 本地数据文件自动上传 S3 的触发周期，单位为秒。最小值：600；最大值：100000。默认值 3600 | +| s3MigrateEnabled | 是否自动进行 S3 迁移，默认值为 0，表示关闭自动 S3 迁移，可配置为 1。 | ### 检查配置参数可用性 -在 taos.cfg 中完成对 s3 的配置后，通过 taosd 命令的 checks3 参数可以检查所配置的 S3 服务是否可用： +在 taos.cfg 中完成对 S3 的配置后，通过 taosd 命令的 checks3 参数可以检查所配置的 S3 服务是否可用： ``` taosd --checks3 @@ -106,11 +106,11 @@ s3migrate database ; 详细的 DB 参数见下表： -| # | 参数 | 默认值 | 最小值 | 最大值 | 描述 | -| :--- | :----------- | :----- | :----- | :------ | :----------------------------------------------------------- | -| 1 | s3_keeplocal | 365 | 1 | 365000 | 数据在本地保留的天数，即 data 文件在本地磁盘保留多长时间后可以上传到 S3。默认单位：天，支持 m（分钟）、h（小时）和 d（天）三个单位 | -| 2 | s3_chunkpages | 131072 | 131072 | 1048576 | 上传对象的大小阈值，与 tsdb_pagesize 参数一样，不可修改，单位为 TSDB 页 | -| 3 | s3_compact | 1 | 0 | 1 | TSDB 文件组首次上传 S3 时，是否自动进行 compact 操作。 | +| # | 参数 | 默认值 | 最小值 | 最大值 | 描述 | +|:--|:--------------|:-------|:------ |:------- | :----------------------------------------------------------- | +| 1 | s3_keeplocal | 365 | 1 | 365000 | 数据在本地保留的天数，即 data 文件在本地磁盘保留多长时间后可以上传到 S3。默认单位：天，支持 m（分钟）、h（小时）和 d（天）三个单位 | +| 2 | s3_chunkpages | 131072 | 131072 | 1048576 | 上传对象的大小阈值，与 tsdb_pagesize 参数一样，不可修改，单位为 TSDB 页 | +| 3 | s3_compact | 1 | 0 | 1 | TSDB 文件组首次上传 S3 时，是否自动进行 compact 操作 | ### 对象存储读写次数估算 @@ -121,7 +121,7 @@ s3migrate database ; 当 TSDB 时序数据超过 `s3_keeplocal` 参数指定的时间，相关的数据文件会被切分成多个文件块，每个文件块的默认大小是 512M 字节 (`s3_chunkpages * tsdb_pagesize`)。除了最后一个文件块保留在本地文件系统外，其余的文件块会被上传到对象存储服务。 ```math -\text{上传次数} = \text{数据文件大小} / (s3_chunkpages * tsdb_pagesize) - 1 +上传次数 = 数据文件大小 / (s3_chunkpages * tsdb_pagesize) - 1 ``` 在创建数据库时，可以通过 `s3_chunkpages` 参数调整每个文件块的大小，从而控制每个数据文件的上传次数。 @@ -135,7 +135,7 @@ s3migrate database ; 相邻的多个数据页会作为一个数据块从对象存储下载一次，以减少从对象存储下载的次数。每个数据页的大小，在创建数据库时，通过 `tsdb_pagesize` 参数指定，默认 4K 字节。 ```math -\text{下载次数} = \text{查询需要的数据块数量} - \text{已缓存的数据块数量} +下载次数 = 查询需要的数据块数量 - 已缓存的数据块数量 ``` 页缓存是内存缓存，节点重启后，再次查询需要重新下载数据。缓存采用 LRU (Least Recently Used) 策略，当缓存空间不足时，最近最少使用的数据将被淘汰。缓存的大小可以通过 `s3PageCacheSize` 参数进行调整，通常来说，缓存越大，下载次数越少。 @@ -168,10 +168,10 @@ s3BucketName td-test 用户界面同 S3，不同的地方在于下面三个参数的配置： -| # | 参数 | 示例值 | 描述 | -| :--- | :----------- | :--------------------------------------- | :----------------------------------------------------------- | -| 1 | s3EndPoint | https://fd2d01c73.blob.core.windows.net | Blob URL | -| 2 | s3AccessKey | fd2d01c73:veUy/iRBeWaI2YAerl+AStw6PPqg== | 冒号分隔的用户 accountId:accountKey | -| 3 | s3BucketName | test-container | Container name | +| # | 参数 | 示例值 | 描述 | +|:--|:-------------|:-----------------------------------------|:----------------------------------| +| 1 | s3EndPoint | https://fd2d01c73.blob.core.windows.net | Blob URL | +| 2 | s3AccessKey | fd2d01c73:veUy/iRBeWaI2YAerl+AStw6PPqg== | 冒号分隔的用户 accountId:accountKey | +| 3 | s3BucketName | test-container | Container name | 其中 fd2d01c73 是账户 ID；微软 Blob 存储服务只支持 Https 协议，不支持 Http。 From 0bacc05bef6437f720e86aa7c08339a8960273cf Mon Sep 17 00:00:00 2001 From: Alex Duan <417921451@qq.com> Date: Fri, 13 Dec 2024 16:22:39 +0800 Subject: [PATCH 6/7] fix: python doc talbe format --- .../14-reference/05-connector/30-python.mdx | 29 +++++++++---------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/docs/zh/14-reference/05-connector/30-python.mdx b/docs/zh/14-reference/05-connector/30-python.mdx index 2a5c84a374..6ca50cd959 100644 --- a/docs/zh/14-reference/05-connector/30-python.mdx +++ b/docs/zh/14-reference/05-connector/30-python.mdx @@ -64,12 +64,11 @@ WebSocket Connector 历史版本： | WebSocket Connector 版本 | 主要变化 | TDengine 版本 | -| ----------------------- | ------------------------------------------------------------------------------------- | ----------------- | -| 0.3.5 | 新增 VARBINARY 和 GEOMETRY 类型支持，修复已知问题 | 3.3.0.0 及更高版本 | -| 0.3.2 | 优化 WebSocket sql 查询和插入性能，修改 readme 和 文档，修复已知问题 | 3.2.3.0 及更高版本 | -| 0.2.9 | 已知问题修复 | - | -| 0.2.5 | 1. 数据订阅支持获取消费进度和重置消费进度
2. 支持 schemaless
3. 支持 STMT | - | -| 0.2.4 | 数据订阅新增取消订阅方法 | 3.0.5.0 及更高版本 | +| ----------------------- | ------------------------------------------------------------------------------------ | ----------------- | +| 0.3.2 | 优化 WebSocket sql 查询和插入性能，修改 readme 和 文档，修复已知问题 | 3.2.3.0 及更高版本 | +| 0.2.9 | 已知问题修复 | - | +| 0.2.5 | 1. 数据订阅支持获取消费进度和重置消费进度
2. 支持 schemaless
3. 支持 STMT | - | +| 0.2.4 | 数据订阅新增取消订阅方法 | 3.0.5.0 及更高版本 | ## 处理异常 @@ -83,15 +82,15 @@ Python 连接器可能会产生 4 种异常： | Error Type | Description | Suggested Actions | | :--------------- | :--------------------------------- | :--------------------------------------------------------- | -| InterfaceError | taosc 版本太低，不支持所使用的接口 | 请检查 TDengine 客户端版本 | -| ConnectionError | 数据库链接错误 | 请检查 TDengine 服务端状态和连接参数 | -| DatabaseError | 数据库错误 | 请检查 TDengine 服务端版本，并将 Python 连接器升级到最新版 | -| OperationalError | 操作错误 | API 使用错误，请检查代码 | -| ProgrammingError | 接口调用错误 | 请检查提交的数据是否正确 | -| StatementError | stmt 相关异常 | 请检查绑定参数与 sql 是否匹配 | -| ResultError | 操作数据错误 | 请检查操作的数据与数据库中的数据类型是否匹配 | -| SchemalessError | schemaless 相关异常 | 请检查数据格式及对应的协议类型是否正确 | -| TmqError | tmq 相关异常 | 请检查 Topic 及 consumer 配置是否正确 | +| InterfaceError | taosc 版本太低，不支持所使用的接口 | 请检查 TDengine 客户端版本 | +| ConnectionError | 数据库链接错误 | 请检查 TDengine 服务端状态和连接参数 | +| DatabaseError | 数据库错误 | 请检查 TDengine 服务端版本，并将 Python 连接器升级到最新版 | +| OperationalError | 操作错误 | API 使用错误，请检查代码 | +| ProgrammingError | 接口调用错误 | 请检查提交的数据是否正确 | +| StatementError | stmt 相关异常 | 请检查绑定参数与 sql 是否匹配 | +| ResultError | 操作数据错误 | 请检查操作的数据与数据库中的数据类型是否匹配 | +| SchemalessError | schemaless 相关异常 | 请检查数据格式及对应的协议类型是否正确 | +| TmqError | tmq 相关异常 | 请检查 Topic 及 consumer 配置是否正确 | Python 中通常通过 try-expect 处理异常，异常处理相关请参考 [Python 错误和异常文档](https://docs.python.org/3/tutorial/errors.html)。 TDengine 其他功能模块的报错，请参考 [错误码](../../../reference/error-code) From ebd71c7939d2d2a364f9764c19d14da3d7117b97 Mon Sep 17 00:00:00 2001 From: Alex Duan <417921451@qq.com> Date: Sat, 14 Dec 2024 21:01:22 +0800 Subject: [PATCH 7/7] docs: publish 2.1.18 for Apache SuperSet --- docs/en/14-reference/05-connector/30-python.mdx | 1 + docs/zh/14-reference/05-connector/30-python.mdx | 1 + 2 files changed, 2 insertions(+) diff --git a/docs/en/14-reference/05-connector/30-python.mdx b/docs/en/14-reference/05-connector/30-python.mdx index abf8302f4f..92fdbc9960 100644 --- a/docs/en/14-reference/05-connector/30-python.mdx +++ b/docs/en/14-reference/05-connector/30-python.mdx @@ -55,6 +55,7 @@ Python Connector historical versions (it is recommended to use the latest versio |Python Connector Version | Major Changes | TDengine Version| | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | +|2.7.18 | Support Apache SuperSet BI Tools. | - | |2.7.16 | Add subscription configuration (session. timeout. ms, Max. roll. interval. ms). | - | |2.7.15 | Added support for VARBINRY and GEOMETRY types. | - | |2.7.14 | Fix Known Issues. | - | diff --git a/docs/zh/14-reference/05-connector/30-python.mdx b/docs/zh/14-reference/05-connector/30-python.mdx index 6ca50cd959..d724fc796c 100644 --- a/docs/zh/14-reference/05-connector/30-python.mdx +++ b/docs/zh/14-reference/05-connector/30-python.mdx @@ -52,6 +52,7 @@ Python Connector 历史版本（建议使用最新版本的 `taospy`）： | Python Connector 版本 | 主要变化 | TDengine 版本 | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | +| 2.7.18 | 支持 Apache Superset BI 产品 | - | | 2.7.16 | 新增订阅配置 (session.timeout.ms, max.poll.interval.ms) | - | | 2.7.15 | 新增 VARBINARY 和 GEOMETRY 类型支持 | - | | 2.7.14 | 修复已知问题 | - |