From acb102285e43ef1dcb06c84e0c3049cdeff1e9b9 Mon Sep 17 00:00:00 2001 From: Shuduo Sang Date: Thu, 28 Apr 2022 11:23:37 +0800 Subject: [PATCH] docs: go connector refine (#11983) * docs: refine connector doc [TD-14839] * docs: use TDengine CLI [TD-14839] * docs: replace JNI with navtive connection [TD-14839] * docs: make connectors doc use same preparition [TD-14839] * docs: refine connectors doc [TD-14839] * docs: refine connectors doc [TD-14839] * docs: refine connector docs * docs: refine connector doc [TD-14839] * docs: refine connector doc [TD-14839] * docs: refine connector [TD-14839] * docs: fix faq path * docs: refine cpp connector doc * docs: refine cpp docs * docs: fix java preparition * docs: refine connector docs * docs: refine connector docs [TD-14839] * docs: refine connector doc [TD-14839] * docs: refine connector docs [TD-14839] * docs: fix node.mdx [TD-14839] * docs: refine connector [TD-14839] * docs: refine cpp connector [TD-14839] * docs: correct bind parameter interface name [TD-14839] * docs: refine connector docs [TD-14839] * docs: refine connector [TD-14839] * docs: refine connector [TD-14839] * docs: refine connector docs [TD-14839] * docs: refine connector [TD-14839] * docs: fix connector tabs [TD-14839] * fix tabitem values * docs: refine connector [TD-14839] * fix typo * docs: fix connector [TD-14839] * fix csharp.mdx * refine connector docs question list is numerical * refine go connector doc --- .../03-connector/03-connector.mdx | 7 +- docs-cn/14-reference/03-connector/csharp.mdx | 8 +- docs-cn/14-reference/03-connector/go.mdx | 131 ++++++++++-------- docs-cn/14-reference/03-connector/java.mdx | 8 +- docs-cn/14-reference/03-connector/node.mdx | 8 +- 5 files changed, 89 insertions(+), 73 deletions(-) diff --git a/docs-cn/14-reference/03-connector/03-connector.mdx b/docs-cn/14-reference/03-connector/03-connector.mdx index 2f4924fc07..b6b0a28ac4 100644 --- a/docs-cn/14-reference/03-connector/03-connector.mdx +++ b/docs-cn/14-reference/03-connector/03-connector.mdx @@ -40,7 +40,7 @@ TDengine 版本更新往往会增加新的功能特性，列表中的连接器 ## 功能特性 -连接器对 TDengine 功能特性的支持对照如下[^1]： +连接器对 TDengine 功能特性的支持对照如下： ### 使用原生接口（taosc） @@ -53,6 +53,10 @@ TDengine 版本更新往往会增加新的功能特性，列表中的连接器 | **订阅功能** | 支持 | 支持 | 支持 | 支持 | 支持 | 暂不支持 | | **Schemaless** | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 | +:::info +由于不同编程语言数据库框架规范不同，并不意味着所有 C/C++ 接口都需要对应封装支持。 +::: + ### 使用 REST 接口 | **功能特性** | **Java** | **Python（暂不支持）** | **Go** | **C#（暂不支持）** | **Node.js** | **Rust** | @@ -109,4 +113,3 @@ import VerifyLinux from "./_verify_linux.mdx"; -[^1]: 由于不同语言数据库框架规范不同，并不意味着所有 C/C++ 接口都需要对应封装支持。 diff --git a/docs-cn/14-reference/03-connector/csharp.mdx b/docs-cn/14-reference/03-connector/csharp.mdx index f9e9cb5f65..bbefaacb45 100644 --- a/docs-cn/14-reference/03-connector/csharp.mdx +++ b/docs-cn/14-reference/03-connector/csharp.mdx @@ -176,13 +176,13 @@ namespace TDengineExample ## 常见问题 -* "Unable to establish connection"，"Unable to resolve FQDN" +1. "Unable to establish connection"，"Unable to resolve FQDN" -一般是因为 FQDN 配置不正确。可以参考[如何彻底搞懂 TDengine 的 FQDN](https://www.taosdata.com/blog/2021/07/29/2741.html)解决。 + 一般是因为 FQDN 配置不正确。可以参考[如何彻底搞懂 TDengine 的 FQDN](https://www.taosdata.com/blog/2021/07/29/2741.html)解决。 -* Unhandled exception. System.DllNotFoundException: Unable to load DLL 'taos' or one of its dependencies: 找不到指定的模块。 +2. Unhandled exception. System.DllNotFoundException: Unable to load DLL 'taos' or one of its dependencies: 找不到指定的模块。 -一般是因为程序没有找到依赖的客户端驱动。解决方法为：Windows 下可以将 `C:\TDengine\driver\taos.dll` 拷贝到 `C:\Windows\System32\ ` 目录下，Linux 下建立如下软链接 `ln -s /usr/local/taos/driver/libtaos.so.x.x.x.x /usr/lib/libtaos.so` 即可。 + 一般是因为程序没有找到依赖的客户端驱动。解决方法为：Windows 下可以将 `C:\TDengine\driver\taos.dll` 拷贝到 `C:\Windows\System32\ ` 目录下，Linux 下建立如下软链接 `ln -s /usr/local/taos/driver/libtaos.so.x.x.x.x /usr/lib/libtaos.so` 即可。 ## API 参考 diff --git a/docs-cn/14-reference/03-connector/go.mdx b/docs-cn/14-reference/03-connector/go.mdx index ce89f3bd7c..f8b0c6d34f 100644 --- a/docs-cn/14-reference/03-connector/go.mdx +++ b/docs-cn/14-reference/03-connector/go.mdx @@ -69,26 +69,33 @@ REST 连接器支持所有能运行 Go 的平台。 ### 使用 go mod 管理 -`go mod` 初始化项目： +1. 使用 `go mod` 命令初始化项目： -```text -go mod init taos-demo -``` + ```text + go mod init taos-demo + ``` -引入taosSql： +2. 引入 taosSql ： -```go -import ( + ```go + import ( "database/sql" _ "github.com/taosdata/driver-go/v2/taosSql" -) -``` + ) + ``` -使用`go mod`方式管理依赖包： +3. 使用 `go mod tidy` 更新依赖包： -```text -go mod tidy -``` + ```text + go mod tidy + ``` + +4. 使用 `go run taos-demo` 运行程序或使用 `go build` 命令编译出二进制文件。 + + ```text + go run taos-demo + go build + ``` ## 建立连接 @@ -259,37 +266,37 @@ func main() { ## 常见问题 -* 无法找到包 `github.com/taosdata/driver-go/v2/taosRestful` +1. 无法找到包 `github.com/taosdata/driver-go/v2/taosRestful` -将 `go.mod` 中 require 块对`github.com/taosdata/driver-go/v2`的引用改为`github.com/taosdata/driver-go/v2 develop`，之后执行 `go mod tidy`。 + 将 `go.mod` 中 require 块对`github.com/taosdata/driver-go/v2`的引用改为`github.com/taosdata/driver-go/v2 develop`，之后执行 `go mod tidy`。 -* database/sql 中 stmt 相关接口崩溃 +2. database/sql 中 stmt（参数绑定）相关接口崩溃 -REST 不支持 stmt 相关接口，建议使用`db.Exec`和`db.Query`。 + REST 不支持参数绑定相关接口，建议使用`db.Exec`和`db.Query`。 -* 使用 `use db` 语句后执行其他语句报错 `[0x217] Database not specified or available` +3. 使用 `use db` 语句后执行其他语句报错 `[0x217] Database not specified or available` -在 REST 接口中 SQL 语句的执行无上下文关联，使用 `use db` 语句不会生效，解决办法见上方使用限制章节。 + 在 REST 接口中 SQL 语句的执行无上下文关联，使用 `use db` 语句不会生效，解决办法见上方使用限制章节。 -* 使用 taosSql 不报错使用 taosRestful 报错 `[0x217] Database not specified or available` +4. 使用 taosSql 不报错使用 taosRestful 报错 `[0x217] Database not specified or available` -因为 REST 接口无状态，使用 `use db` 语句不会生效，解决办法见上方使用限制章节。 + 因为 REST 接口无状态，使用 `use db` 语句不会生效，解决办法见上方使用限制章节。 -* 升级 `github.com/taosdata/driver-go/v2/taosRestful` +5. 升级 `github.com/taosdata/driver-go/v2/taosRestful` -将 `go.mod` 文件中对 `github.com/taosdata/driver-go/v2` 的引用改为 `github.com/taosdata/driver-go/v2 develop`，之后执行 `go mod tidy`。 + 将 `go.mod` 文件中对 `github.com/taosdata/driver-go/v2` 的引用改为 `github.com/taosdata/driver-go/v2 develop`，之后执行 `go mod tidy`。 -* `readBufferSize` 参数调大后无明显效果 +6. `readBufferSize` 参数调大后无明显效果 -`readBufferSize` 调大后会减少获取结果时 `syscall` 的调用。如果查询结果的数据量不大，修改该参数不会带来明显提升，如果该参数修改过大，瓶颈会在解析 JSON 数据。如果需要优化查询速度，需要根据实际情况调整该值来达到查询效果最优。 + `readBufferSize` 调大后会减少获取结果时 `syscall` 的调用。如果查询结果的数据量不大，修改该参数不会带来明显提升，如果该参数修改过大，瓶颈会在解析 JSON 数据。如果需要优化查询速度，需要根据实际情况调整该值来达到查询效果最优。 -* `disableCompression` 参数设置为 `false` 时查询效率降低 +7. `disableCompression` 参数设置为 `false` 时查询效率降低 -当 `disableCompression` 参数设置为 `false` 时查询结果会使用 `gzip` 压缩后传输，拿到数据后要先进行 `gzip` 解压。 + 当 `disableCompression` 参数设置为 `false` 时查询结果会使用 `gzip` 压缩后传输，拿到数据后要先进行 `gzip` 解压。 -* `go get` 命令无法获取包，或者获取包超时 +8. `go get` 命令无法获取包，或者获取包超时 -设置 Go 代理 `go env -w GOPROXY=https://goproxy.cn,direct`。 + 设置 Go 代理 `go env -w GOPROXY=https://goproxy.cn,direct`。 ## 常用 API @@ -297,103 +304,105 @@ REST 不支持 stmt 相关接口，建议使用`db.Exec`和`db.Query`。 * `sql.Open(DRIVER_NAME string, dataSourceName string) *DB` -该 API 用来打开 DB，返回一个类型为 \*DB 的对象。 + 该 API 用来打开 DB，返回一个类型为 \*DB 的对象。 -**注意**： 该 API 成功创建的时候，并没有做权限等检查，只有在真正执行 Query 或者 Exec 的时候才能真正的去创建连接，并同时检查 user/password/host/port 是不是合法。 +:::info +该 API 成功创建的时候，并没有做权限等检查，只有在真正执行 Query 或者 Exec 的时候才能真正的去创建连接，并同时检查 user/password/host/port 是不是合法。 +::: * `func (db *DB) Exec(query string, args ...interface{}) (Result, error)` -`sql.Open` 内置的方法，用来执行非查询相关 SQL。 + `sql.Open` 内置的方法，用来执行非查询相关 SQL。 * `func (db *DB) Query(query string, args ...interface{}) (*Rows, error)` -`sql.Open` 内置的方法，用来执行查询语句。 + `sql.Open` 内置的方法，用来执行查询语句。 -### 高级功能 API +### 高级功能（af）API -af 包封装了订阅、stmt 等 TDengine 高级功能。 +`af` 包封装了订阅、schemaless、参数绑定等 TDengine 高级功能。 * `af.Open(host, user, pass, db string, port int) (*Connector, error)` -该 API 通过 cgo 创建与 taosd 的连接。 + 该 API 通过 cgo 创建与 taosd 的连接。 * `func (conn *Connector) Close() error` -关闭与 taosd 的连接。 - -* `func (conn *Connector) StmtExecute(sql string, params *param.Param) (res driver.Result, err error)` - -stmt 单行插入。 - -* `func (conn *Connector) StmtQuery(sql string, params *param.Param) (rows driver.Rows, err error)` - -stmt 查询，返回 `database/sql/driver` 包的 `Rows` 结构。 + 关闭与 taosd 的连接。 订阅 * `func (conn *Connector) Subscribe(restart bool, topic string, sql string, interval time.Duration) (Subscriber, error)` -订阅数据。 + 订阅数据。 * `func (s *taosSubscriber) Consume() (driver.Rows, error)` -消费订阅数据，返回 `database/sql/driver` 包的 `Rows` 结构。 + 消费订阅数据，返回 `database/sql/driver` 包的 `Rows` 结构。 * `func (s *taosSubscriber) Unsubscribe(keepProgress bool)` -取消订阅数据。 + 取消订阅数据。 schemaless 写入 * `func (conn *Connector) InfluxDBInsertLines(lines []string, precision string) error` -写入 influxDB 行协议。 + 写入 influxDB 行协议。 * `func (conn *Connector) OpenTSDBInsertTelnetLines(lines []string) error` -写入 OpenTDSB telnet 协议。 + 写入 OpenTDSB telnet 协议数据。 * `func (conn *Connector) OpenTSDBInsertJsonPayload(payload string) error` -写入 OpenTSDB json 协议。 + 写入 OpenTSDB JSON 协议数据。 + +参数绑定 + +* `func (conn *Connector) StmtExecute(sql string, params *param.Param) (res driver.Result, err error)` + + 参数绑定单行插入。 + +* `func (conn *Connector) StmtQuery(sql string, params *param.Param) (rows driver.Rows, err error)` -批量 stmt 插入 + 参数绑定查询，返回 `database/sql/driver` 包的 `Rows` 结构。 * `func (conn *Connector) InsertStmt() *insertstmt.InsertStmt` -初始化 stmt。 + 初始化参数。 * `func (stmt *InsertStmt) Prepare(sql string) error` -预处理 SQL 语句。 + 参数绑定预处理 SQL 语句。 * `func (stmt *InsertStmt) SetTableName(name string) error` -设置表名。 + 参数绑定设置表名。 * `func (stmt *InsertStmt) SetSubTableName(name string) error` -设置子表名。 + 参数绑定设置子表名。 * `func (stmt *InsertStmt) BindParam(params []*param.Param, bindType *param.ColumnType) error` -绑定多行数据。 + 参数绑定多行数据。 * `func (stmt *InsertStmt) AddBatch() error` -添加到批处理。 + 添加到参数绑定批处理。 * `func (stmt *InsertStmt) Execute() error` -执行 stmt。 + 执行参数绑定。 * `func (stmt *InsertStmt) GetAffectedRows() int` -获取受影响行数。 + 获取参数绑定插入受影响行数。 * `func (stmt *InsertStmt) Close() error` -结束 stmt。 + 结束参数绑定。 ## API 参考 diff --git a/docs-cn/14-reference/03-connector/java.mdx b/docs-cn/14-reference/03-connector/java.mdx index e2d603e010..293deb4fe6 100644 --- a/docs-cn/14-reference/03-connector/java.mdx +++ b/docs-cn/14-reference/03-connector/java.mdx @@ -814,25 +814,25 @@ Query OK, 1 row(s) in set (0.000141s) ## 常见问题 -- 使用 Statement 的 `addBatch` 和 `executeBatch` 来执行“批量写入/更行”，为什么没有带来性能上的提升？ +1. 使用 Statement 的 `addBatch` 和 `executeBatch` 来执行“批量写入/更行”，为什么没有带来性能上的提升？ **原因**：TDengine 的 JDBC 实现中，通过 `addBatch` 方法提交的 SQL 语句，会按照添加的顺序，依次执行，这种方式没有减少与服务端的交互次数，不会带来性能上的提升。 **解决方法**：1. 在一条 insert 语句中拼接多个 values 值；2. 使用多线程的方式并发插入；3. 使用参数绑定的写入方式 -- java.lang.UnsatisfiedLinkError: no taos in java.library.path +2. java.lang.UnsatisfiedLinkError: no taos in java.library.path **原因**：程序没有找到依赖的本地函数库 taos。 **解决方法**：Windows 下可以将 C:\TDengine\driver\taos.dll 拷贝到 C:\Windows\System32\ 目录下，Linux 下将建立如下软链 `ln -s /usr/local/taos/driver/libtaos.so.x.x.x.x /usr/lib/libtaos.so` 即可。 -- java.lang.UnsatisfiedLinkError: taos.dll Can't load AMD 64 bit on a IA 32-bit platform +3. java.lang.UnsatisfiedLinkError: taos.dll Can't load AMD 64 bit on a IA 32-bit platform **原因**：目前 TDengine 只支持 64 位 JDK。 **解决方法**：重新安装 64 位 JDK。 -- 其它问题请参考 [FAQ](/train-faq/faq) +4. 其它问题请参考 [FAQ](/train-faq/faq) ## API 参考 diff --git a/docs-cn/14-reference/03-connector/node.mdx b/docs-cn/14-reference/03-connector/node.mdx index c088aeb4e3..c95e0dfaed 100644 --- a/docs-cn/14-reference/03-connector/node.mdx +++ b/docs-cn/14-reference/03-connector/node.mdx @@ -230,9 +230,13 @@ Node.js 连接器的使用参见[视频教程](https://www.taosdata.com/blog/202 sudo systemctl start taosadapter ``` -2. 连接器 >v2.0.6 目前兼容的 Node.js 为：>=v10.20.0 <= v10.9.0 || >=v12.8.0 <= v12.9.1 +2. Node.js 版本 -3. "Unable to establish connection"，"Unable to resolve FQDN" 等问题一般都是因为配置 FQDN 不正确。 可以参考[如何彻底搞懂 TDengine 的 FQDN](https://www.taosdata.com/blog/2021/07/29/2741.html) 。 + 连接器 >v2.0.6 目前兼容的 Node.js 版本为：>=v10.20.0 <= v10.9.0 || >=v12.8.0 <= v12.9.1 + +3. "Unable to establish connection"，"Unable to resolve FQDN" + + 一般都是因为配置 FQDN 不正确。 可以参考[如何彻底搞懂 TDengine 的 FQDN](https://www.taosdata.com/blog/2021/07/29/2741.html) 。 ## 重要更新记录 -- GitLab