From e7e10312e31804bc0737371e786907e88d08cfee Mon Sep 17 00:00:00 2001 From: sheyanjie-qq <249478495@qq.com> Date: Wed, 31 Jul 2024 14:20:20 +0800 Subject: [PATCH 1/7] mod jdbc doc --- docs/zh/08-develop/01-connect/index.md | 7 +++- docs/zh/08-develop/04-schemaless.md | 30 +++++++++++-- docs/zh/08-develop/07-tmq.md | 2 + docs/zh/08-develop/index.md | 2 +- docs/zh/14-reference/05-connector/index.md | 42 +++++++++---------- .../taosdata/example/AbsConsumerLoopFull.java | 6 +++ .../taosdata/example/AbsWsConsumerLoop.java | 6 +++ 7 files changed, 68 insertions(+), 27 deletions(-) diff --git a/docs/zh/08-develop/01-connect/index.md b/docs/zh/08-develop/01-connect/index.md index fcb70f2293..6392f324db 100644 --- a/docs/zh/08-develop/01-connect/index.md +++ b/docs/zh/08-develop/01-connect/index.md @@ -264,6 +264,8 @@ phpize && ./configure --enable-swoole && make -j && make install 在执行这一步之前，请确保有一个正在运行的，且可以访问到的 TDengine，而且服务端的 FQDN 配置正确。以下示例代码，都假设 TDengine 安装在本机，且 FQDN（默认 localhost） 和 serverPort（默认 6030） 都使用默认配置。 ### 连接参数 +连接的配置项较多，因此在建立连接之前，我们能先介绍一下各语言连接器建立连接使用的参数。 + @@ -317,7 +319,7 @@ properties 中的配置参数如下： **配置参数的优先级：** -通过前面三种方式获取连接，如果配置参数在 url、Properties、客户端配置文件中有重复，则参数的`优先级由高到低`分别如下： +通过前面三种方式获取连接，如果配置参数在 url、Properties、客户端配置文件中有重复，则参数的**优先级由高到低**分别如下： 1. JDBC URL 参数，如上所述，可以在 JDBC URL 的参数中指定。 2. Properties connProps @@ -344,6 +346,7 @@ properties 中的配置参数如下： ### Websocket 连接 +各语言连接器建立 Websocket 连接代码样例。 @@ -383,6 +386,7 @@ properties 中的配置参数如下： ### 原生连接 +各语言连接器建立原生连接代码样例。 ```java @@ -414,6 +418,7 @@ properties 中的配置参数如下： ### REST 连接 +各语言连接器建立 REST 连接代码样例。 ```java diff --git a/docs/zh/08-develop/04-schemaless.md b/docs/zh/08-develop/04-schemaless.md index 6ce5d69c82..816b3aa170 100644 --- a/docs/zh/08-develop/04-schemaless.md +++ b/docs/zh/08-develop/04-schemaless.md @@ -158,7 +158,6 @@ st,t1=3,t2=4,t3=t3 c1=3i64,c6="passit" 1626006833640000000 - ```java {{#include examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/SchemalessWsTest.java:schemaless}} ``` @@ -190,9 +189,9 @@ writer.write(lineDemo, SchemalessProtocolType.LINE, SchemalessTimestampType.NANO ### 原生连接 - ```java - {{#include examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/SchemalessJniTest.java:schemaless}} - ``` +```java +{{#include examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/SchemalessJniTest.java:schemaless}} +``` 执行带有 reqId 的无模式写入，此 reqId 可用于请求链路追踪。 @@ -219,6 +218,29 @@ writer.write(lineDemo, SchemalessProtocolType.LINE, SchemalessTimestampType.NANO +### REST 连接 + + + 不支持 + + + + + + + + + + + + + + + + + + + ## 查询写入的数据 运行上节的样例代码，会在 power 数据库中自动建表，我们可以通过 taos shell 或者应用程序来查询数据。下面给出用 taos shell 查询超级表和 meters 表数据的样例。 diff --git a/docs/zh/08-develop/07-tmq.md b/docs/zh/08-develop/07-tmq.md index 64b01eea54..e6d866c29c 100644 --- a/docs/zh/08-develop/07-tmq.md +++ b/docs/zh/08-develop/07-tmq.md @@ -26,6 +26,8 @@ TDengine 消费者的概念跟 Kafka 类似，消费者通过订阅主题来接 ### 创建参数 +创建消费者的参数较多，非常灵活的支持了各种连接类型、 Offset 提交方式、压缩、重连、反序列化等特性，下面单独介绍各语言连接器创建消费者的参数。 + Java 连接器创建消费者的参数为 Properties， 可以设置如下参数： diff --git a/docs/zh/08-develop/index.md b/docs/zh/08-develop/index.md index e7578232c0..d7b0c137e2 100644 --- a/docs/zh/08-develop/index.md +++ b/docs/zh/08-develop/index.md @@ -15,7 +15,7 @@ description: 让开发者能够快速上手的指南 7. 在很多场景下（如车辆管理），应用需要获取每个数据采集点的最新状态，那么建议你采用 TDengine 的 Cache 功能，而不用单独部署 Redis 等缓存软件。 8. 如果你发现 TDengine 的函数无法满足你的要求，那么你可以使用用户自定义函数（UDF）来解决问题。 -本部分内容就是按照上述顺序组织的。为便于理解，TDengine 为每个功能和每个支持的编程语言都提供了示例代码。如果你希望深入了解 SQL 的使用，需要查看[SQL 手册](../taos-sql/)。如果想更深入地了解各连接器的使用，请阅读[连接器参考指南](../connector/)。如果还希望想将 TDengine 与第三方系统集成起来，比如 Grafana, 请参考[第三方工具](../third-party/)。 +本部分内容就是按照上述顺序组织的。为便于理解，TDengine 为每个功能和每个支持的编程语言都提供了示例代码。如果你希望深入了解 SQL 的使用，需要查看[SQL 手册](../taos-sql/)。如果想更深入地了解各连接器的使用，请阅读[连接器参考指南](../reference/connector/)。如果还希望想将 TDengine 与第三方系统集成起来，比如 Grafana, 请参考[第三方工具](../third-party/)。 如果在开发过程中遇到任何问题，请点击每个页面下方的["反馈问题"](https://github.com/taosdata/TDengine/issues/new/choose), 在 GitHub 上直接递交 Issue。 diff --git a/docs/zh/14-reference/05-connector/index.md b/docs/zh/14-reference/05-connector/index.md index e3c7a0be3f..1e68dcc40e 100644 --- a/docs/zh/14-reference/05-connector/index.md +++ b/docs/zh/14-reference/05-connector/index.md @@ -12,13 +12,13 @@ TDengine 提供了丰富的应用程序开发接口，为了便于用户快速 目前 TDengine 的原生接口连接器可支持的平台包括：X64/ARM64 等硬件平台，以及 Linux/Win64 等开发环境。对照矩阵如下： -| **CPU** | **OS** | **Java** | **Python** | **Go** | **Node.js** | **C#** | **Rust** | C/C++ | -| -------------- | --------- | -------- | ---------- | ------ | ----------- | ------ | -------- | ----- | -| **X86 64bit** | **Linux** | ● | ● | ● | ● | ● | ● | ● | -| **X86 64bit** | **Win64** | ● | ● | ● | ● | ● | ● | ● | -| **X86 64bit** | **macOS** | ● | ● | ● | ○ | ○ | ● | ● | -| **ARM64** | **Linux** | ● | ● | ● | ● | ○ | ○ | ● | -| **ARM64** | **macOS** | ● | ● | ● | ○ | ○ | ● | ● | +| **CPU** | **OS** | **Java** | **Python** | **Go** | **Node.js** | **C#** | **Rust** | C/C++ | +| ------------- | --------- | -------- | ---------- | ------ | ----------- | ------ | -------- | ----- | +| **X86 64bit** | **Linux** | ● | ● | ● | ● | ● | ● | ● | +| **X86 64bit** | **Win64** | ● | ● | ● | ● | ● | ● | ● | +| **X86 64bit** | **macOS** | ● | ● | ● | ○ | ○ | ● | ● | +| **ARM64** | **Linux** | ● | ● | ● | ● | ○ | ○ | ● | +| **ARM64** | **macOS** | ● | ● | ● | ○ | ○ | ● | ● | 其中 ● 表示官方测试验证通过，○ 表示非官方测试验证通过，-- 表示未经验证。 @@ -30,7 +30,7 @@ TDengine 版本更新往往会增加新的功能特性，列表中的连接器 | **TDengine 版本** | **Java** | **Python** | **Go** | **C#** | **Node.js** | **Rust** | | ---------------------- | --------- | ---------- | ------------ | ------------- | --------------- | -------- | -| **3.0.0.0 及以上** | 3.0.2以上 | 当前版本 | 3.0 分支 | 3.0.0 | 3.0.0 | 当前版本 | +| **3.0.0.0 及以上** | 3.0.2以上 | 当前版本 | 3.0 分支 | 3.0.0 | 3.1.0 | 当前版本 | | **2.4.0.14 及以上** | 2.0.38 | 当前版本 | develop 分支 | 1.0.2 - 1.0.6 | 2.0.10 - 2.0.12 | 当前版本 | | **2.4.0.4 - 2.4.0.13** | 2.0.37 | 当前版本 | develop 分支 | 1.0.2 - 1.0.6 | 2.0.10 - 2.0.12 | 当前版本 | | **2.2.x.x ** | 2.0.36 | 当前版本 | master 分支 | n/a | 2.0.7 - 2.0.9 | 当前版本 | @@ -44,11 +44,11 @@ TDengine 版本更新往往会增加新的功能特性，列表中的连接器 | **功能特性** | **Java** | **Python** | **Go** | **C#** | **Node.js** | **Rust** | | ------------------- | -------- | ---------- | ------ | ------ | ----------- | -------- | -| **连接管理** | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 | -| **普通查询** | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 | -| **参数绑定** | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 | -| **数据订阅（TMQ）** | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 | -| **Schemaless** | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 | +| **连接管理** | 支持 | 支持 | 支持 | 支持 | 不支持 | 支持 | +| **普通查询** | 支持 | 支持 | 支持 | 支持 | 不支持 | 支持 | +| **参数绑定** | 支持 | 支持 | 支持 | 支持 | 不支持 | 支持 | +| **数据订阅（TMQ）** | 支持 | 支持 | 支持 | 支持 | 不支持 | 支持 | +| **Schemaless** | 支持 | 支持 | 支持 | 支持 | 不支持 | 支持 | :::info 由于不同编程语言数据库框架规范不同，并不意味着所有 C/C++ 接口都需要对应封装支持。 @@ -56,14 +56,14 @@ TDengine 版本更新往往会增加新的功能特性，列表中的连接器 ### 使用 http (REST 或 WebSocket) 接口 -| **功能特性** | **Java** | **Python** | **Go** | **C# ** | **Node.js** | **Rust** | -| ------------------------------ | -------- | ---------- | -------- | ---- | ----------- | -------- | -| **连接管理** | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 | -| **普通查询** | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 | -| **参数绑定** | 支持 | 支持 | 支持 | 支持 | 暂不支持 | 支持 | -| **数据订阅（TMQ）** | 支持 | 支持 | 支持 | 支持 | 暂不支持 | 支持 | -| **Schemaless** | 支持 | 支持 | 支持 | 支持 | 暂不支持 | 支持 | -| **批量拉取（基于 WebSocket）** | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 | +| **功能特性** | **Java** | **Python** | **Go** | **C# ** | **Node.js** | **Rust** | +| ------------------------------ | -------- | ---------- | ------ | ------- | ----------- | -------- | +| **连接管理** | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 | +| **普通查询** | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 | +| **参数绑定** | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 | +| **数据订阅（TMQ）** | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 | +| **Schemaless** | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 | +| **批量拉取（基于 WebSocket）** | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 | :::warning diff --git a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/AbsConsumerLoopFull.java b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/AbsConsumerLoopFull.java index 86a823bbb1..af3537ef0e 100644 --- a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/AbsConsumerLoopFull.java +++ b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/AbsConsumerLoopFull.java @@ -52,16 +52,21 @@ public abstract class AbsConsumerLoopFull { public void pollData() throws SQLException { try { + // subscribe to the topics consumer.subscribe(topics); while (!shutdown.get()) { + // poll data ConsumerRecords records = consumer.poll(Duration.ofMillis(100)); for (ConsumerRecord record : records) { ResultBean bean = record.value(); + // process the data here process(bean); } } + // unsubscribe the topics consumer.unsubscribe(); } finally { + // close the consumer consumer.close(); shutdownLatch.countDown(); } @@ -76,6 +81,7 @@ public abstract class AbsConsumerLoopFull { } + // use this class to define the data structure of the result record public static class ResultBean { private Timestamp ts; private double current; diff --git a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/AbsWsConsumerLoop.java b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/AbsWsConsumerLoop.java index c622c20cba..5abfc95cae 100644 --- a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/AbsWsConsumerLoop.java +++ b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/AbsWsConsumerLoop.java @@ -53,17 +53,22 @@ try { public void pollData() throws SQLException { try { + // Subscribe to the topic consumer.subscribe(topics); while (!shutdown.get()) { + // poll data ConsumerRecords records = consumer.poll(Duration.ofMillis(100)); for (ConsumerRecord record : records) { ResultBean bean = record.value(); + // process data here process(bean); } } + // unsubscribe the topics consumer.unsubscribe(); } finally { + // close the consumer consumer.close(); shutdownLatch.countDown(); } @@ -78,6 +83,7 @@ try { } + // use this class to define the data structure of the result record public static class ResultBean { private Timestamp ts; private double current; From a675425f5ddd6aa3c10e93e77669f7d25f0b1882 Mon Sep 17 00:00:00 2001 From: sheyanjie-qq <249478495@qq.com> Date: Wed, 31 Jul 2024 15:18:37 +0800 Subject: [PATCH 2/7] use table for properties --- docs/zh/08-develop/01-connect/index.md | 66 ++++++++------ docs/zh/14-reference/05-connector/14-java.mdx | 91 ++++++++++--------- 2 files changed, 85 insertions(+), 72 deletions(-) diff --git a/docs/zh/08-develop/01-connect/index.md b/docs/zh/08-develop/01-connect/index.md index 6392f324db..93da9c9266 100644 --- a/docs/zh/08-develop/01-connect/index.md +++ b/docs/zh/08-develop/01-connect/index.md @@ -279,43 +279,49 @@ TDengine 的 JDBC URL 规范格式为： **注意**：使用 JDBC 原生连接，taos-jdbcdriver 需要依赖客户端驱动（Linux 下是 libtaos.so；Windows 下是 taos.dll；macOS 下是 libtaos.dylib）。 url 中的配置参数如下： -- user：登录 TDengine 用户名，默认值 'root'。 -- password：用户登录密码，默认值 'taosdata'。 -- batchfetch: true：在执行查询时批量拉取结果集；false：逐行拉取结果集。默认值为：false。逐行拉取结果集使用 HTTP 方式进行数据传输。JDBC REST 连接支持批量拉取数据功能。taos-jdbcdriver 与 TDengine 之间通过 WebSocket 连接进行数据传输。相较于 HTTP，WebSocket 可以使 JDBC REST 连接支持大数据量查询，并提升查询性能。 -- charset: 当开启批量拉取数据时，指定解析字符串数据的字符集。 -- batchErrorIgnore：true：在执行 Statement 的 executeBatch 时，如果中间有一条 SQL 执行失败，继续执行下面的 SQL 了。false：不再执行失败 SQL 后的任何语句。默认值为：false。 -- httpConnectTimeout: 连接超时时间，单位 ms， 默认值为 60000。 -- httpSocketTimeout: socket 超时时间，单位 ms，默认值为 60000。仅在 batchfetch 设置为 false 时生效。 -- messageWaitTimeout: 消息超时时间, 单位 ms， 默认值为 60000。 仅在 batchfetch 设置为 true 时生效。 -- useSSL: 连接中是否使用 SSL。 -- httpPoolSize: REST 并发请求大小，默认 20。 + +| 参数 | 描述 | 默认值 | +| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | +| user | 登录 TDengine 用户名 | 'root' | +| password | 用户登录密码 | 'taosdata' | +| batchfetch | true：在执行查询时批量拉取结果集；false：逐行拉取结果集。逐行拉取结果集使用 HTTP 方式进行数据传输。JDBC REST 连接支持批量拉取数据功能。taos-jdbcdriver 与 TDengine 之间通过 WebSocket 连接进行数据传输。相较于 HTTP，WebSocket 可以使 JDBC REST 连接支持大数据量查询，并提升查询性能。 | false | +| charset | 当开启批量拉取数据时，指定解析字符串数据的字符集。 | | +| batchErrorIgnore | true：在执行 Statement 的 executeBatch 时，如果中间有一条 SQL 执行失败，继续执行下面的 SQL 了。false：不再执行失败 SQL 后的任何语句。 | false | +| httpConnectTimeout | 连接超时时间，单位 ms | 60000 | +| httpSocketTimeout | socket 超时时间，单位 ms，仅在 batchfetch 设置为 false 时生效。 | 60000 | +| messageWaitTimeout | 消息超时时间, 单位 ms，仅在 batchfetch 设置为 true 时生效。 | 60000 | +| useSSL | 连接中是否使用 SSL。 | | +| httpPoolSize | REST 并发请求大小，默认 20。 | 20 | **注意**：部分配置项（比如：locale、timezone）在 REST 连接中不生效。 除了通过指定的 URL 获取连接，还可以使用 Properties 指定建立连接时的参数。 -properties 中的配置参数如下： -- TSDBDriver.PROPERTY_KEY_USER：登录 TDengine 用户名，默认值 'root'。 -- TSDBDriver.PROPERTY_KEY_PASSWORD：用户登录密码，默认值 'taosdata'。 -- TSDBDriver.PROPERTY_KEY_BATCH_LOAD: true：在执行查询时批量拉取结果集；false：逐行拉取结果集。默认值为：false。 -- TSDBDriver.PROPERTY_KEY_BATCH_ERROR_IGNORE：true：在执行 Statement 的 executeBatch 时，如果中间有一条 SQL 执行失败，继续执行下面的 sq 了。false：不再执行失败 SQL 后的任何语句。默认值为：false。 -- TSDBDriver.PROPERTY_KEY_CONFIG_DIR：仅在使用 JDBC 原生连接时生效。客户端配置文件目录路径，Linux OS 上默认值 `/etc/taos`，Windows OS 上默认值 `C:/TDengine/cfg`。 -- TSDBDriver.PROPERTY_KEY_CHARSET：客户端使用的字符集，默认值为系统字符集。 -- TSDBDriver.PROPERTY_KEY_LOCALE：仅在使用 JDBC 原生连接时生效。 客户端语言环境，默认值系统当前 locale。 -- TSDBDriver.PROPERTY_KEY_TIME_ZONE：仅在使用 JDBC 原生连接时生效。 客户端使用的时区，默认值为系统当前时区。因为历史的原因，我们只支持POSIX标准的部分规范，如UTC-8(代表中国上上海), GMT-8，Asia/Shanghai 这几种形式。 -- TSDBDriver.HTTP_CONNECT_TIMEOUT: 连接超时时间，单位 ms， 默认值为 60000。仅在 REST 连接时生效。 -- TSDBDriver.HTTP_SOCKET_TIMEOUT: socket 超时时间，单位 ms，默认值为 60000。仅在 REST 连接且 batchfetch 设置为 false 时生效。 -- TSDBDriver.PROPERTY_KEY_MESSAGE_WAIT_TIMEOUT: 消息超时时间, 单位 ms， 默认值为 60000。 仅在 REST 连接且 batchfetch 设置为 true 时生效。 -- TSDBDriver.PROPERTY_KEY_USE_SSL: 连接中是否使用 SSL。仅在 REST 连接时生效。 -- TSDBDriver.HTTP_POOL_SIZE: REST 并发请求大小，默认 20。 -- TSDBDriver.PROPERTY_KEY_ENABLE_COMPRESSION: 传输过程是否启用压缩。仅在使用 REST/Websocket 连接时生效。true: 启用，false: 不启用。默认为 false。 -- TSDBDriver.PROPERTY_KEY_ENABLE_AUTO_RECONNECT: 是否启用自动重连。仅在使用 Websocket 连接时生效。true: 启用，false: 不启用。默认为 false。 -> **注意**：启用自动重连仅对简单执行 SQL 语句以及 无模式写入、数据订阅有效。对于参数绑定无效。自动重连仅对连接建立时通过参数指定数据库有效，对后面的 `use db` 语句切换数据库无效。 +properties 中的配置参数如下（**注意**：属性使用需要加上类名，如 `TSDBDriver.PROPERTY_KEY_USER` ）： -- TSDBDriver.PROPERTY_KEY_RECONNECT_INTERVAL_MS: 自动重连重试间隔，单位毫秒，默认值 2000。仅在 PROPERTY_KEY_ENABLE_AUTO_RECONNECT 为 true 时生效。 -- TSDBDriver.PROPERTY_KEY_RECONNECT_RETRY_COUNT: 自动重连重试次数，默认值 3，仅在 PROPERTY_KEY_ENABLE_AUTO_RECONNECT 为 true 时生效。 -- TSDBDriver.PROPERTY_KEY_DISABLE_SSL_CERT_VALIDATION: 关闭 SSL 证书验证 。仅在使用 Websocket 连接时生效。true: 启用，false: 不启用。默认为 false。 +| 属性 | 描述 | 默认值 | +| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------- | +| PROPERTY_KEY_USER | 登录 TDengine 用户名 | 'root' | +| PROPERTY_KEY_PASSWORD | 用户登录密码 | 'taosdata' | +| PROPERTY_KEY_BATCH_LOAD | true：在执行查询时批量拉取结果集；false：逐行拉取结果集 | false | +| PROPERTY_KEY_BATCH_ERROR_IGNORE | true：在执行 Statement 的 executeBatch 时，如果中间有一条 SQL 执行失败，继续执行下面的 SQL；false：不再执行失败 SQL 后的任何语句 | false | +| PROPERTY_KEY_CONFIG_DIR | 仅在使用 JDBC 原生连接时生效。客户端配置文件目录路径，Linux OS 上默认值 /etc/taos，Windows OS 上默认值 C:/TDengine/cfg | 系统依赖 | +| PROPERTY_KEY_CHARSET | 客户端使用的字符集 | 系统字符集 | +| PROPERTY_KEY_LOCALE | 仅在使用 JDBC 原生连接时生效。客户端语言环境 | 系统当前 locale | +| PROPERTY_KEY_TIME_ZONE | 仅在使用 JDBC 原生连接时生效。客户端使用的时区 | 系统当前时区 | +| HTTP_CONNECT_TIMEOUT | 连接超时时间，单位 ms，仅在 REST 连接时生效 | 60000 | +| HTTP_SOCKET_TIMEOUT | socket 超时时间，单位 ms，仅在 REST 连接且 batchfetch 设置为 false 时生效 | 60000 | +| PROPERTY_KEY_MESSAGE_WAIT_TIMEOUT | 消息超时时间, 单位 ms，仅在 REST 连接且 batchfetch 设置为 true 时生效 | 60000 | +| PROPERTY_KEY_USE_SSL | 连接中是否使用 SSL。仅在 REST 连接时生效 | | +| HTTP_POOL_SIZE | REST 并发请求大小 | 20 | +| PROPERTY_KEY_ENABLE_COMPRESSION | 传输过程是否启用压缩。仅在使用 REST/Websocket 连接时生效 | false | +| PROPERTY_KEY_ENABLE_AUTO_RECONNECT | 是否启用自动重连。仅在使用 Websocket 连接时生效 | false | +| PROPERTY_KEY_RECONNECT_INTERVAL_MS | 自动重连重试间隔，单位毫秒。仅在 PROPERTY_KEY_ENABLE_AUTO_RECONNECT 为 true 时生效 | 2000 | +| PROPERTY_KEY_RECONNECT_RETRY_COUNT | 自动重连重试次数。仅在 PROPERTY_KEY_ENABLE_AUTO_RECONNECT 为 true 时生效 | 3 | +| PROPERTY_KEY_DISABLE_SSL_CERT_VALIDATION | 关闭 SSL 证书验证。仅在使用 Websocket 连接时生效 | false | + +> **注意**：启用自动重连仅对简单执行 SQL 语句以及 无模式写入、数据订阅有效。对于参数绑定无效。自动重连仅对连接建立时通过参数指定数据库有效，对后面的 `use db` 语句切换数据库无效。 **配置参数的优先级：** diff --git a/docs/zh/14-reference/05-connector/14-java.mdx b/docs/zh/14-reference/05-connector/14-java.mdx index 47a0625b9b..23b4392008 100644 --- a/docs/zh/14-reference/05-connector/14-java.mdx +++ b/docs/zh/14-reference/05-connector/14-java.mdx @@ -205,7 +205,7 @@ TDengine 的 JDBC URL 规范格式为： **注**：REST 连接中增加 `batchfetch` 参数并设置为 true，将开启 WebSocket 连接。 -##### 原生连接 +**原生连接** `jdbc:TAOS://taosdemo.com:6030/power?user=root&password=taosdata`，使用了 JDBC 原生连接的 TSDBDriver，建立了到 hostname 为 taosdemo.com，端口为 6030（TDengine 的默认端口），数据库名为 power 的连接。这个 URL 中指定用户名（user）为 root，密码（password）为 taosdata。 @@ -213,18 +213,20 @@ TDengine 的 JDBC URL 规范格式为： 对于原生连接 url 中支持的配置参数如下： -- user：登录 TDengine 用户名，默认值 'root'。 -- password：用户登录密码，默认值 'taosdata'。 -- cfgdir：客户端配置文件目录路径，Linux OS 上默认值 `/etc/taos`，Windows OS 上默认值 `C:/TDengine/cfg`。 -- charset：客户端使用的字符集，默认值为系统字符集。 -- locale：客户端语言环境，默认值系统当前 locale。 -- timezone：客户端使用的时区，默认值为系统当前时区。 -- batchfetch: true：在执行查询时批量拉取结果集；false：逐行拉取结果集。默认值为：true。开启批量拉取同时获取一批数据在查询数据量较大时批量拉取可以有效的提升查询性能。 -- batchErrorIgnore：true：在执行 Statement 的 executeBatch 时，如果中间有一条 SQL 执行失败将继续执行下面的 SQL。false：不再执行失败 SQL 后的任何语句。默认值为：false。 +| 属性 | 描述 | 默认值 | +|------------------|--------------------------------------------------------------------------------------------------------|-----------------| +| user | 登录 TDengine 用户名 | 'root' | +| password | 用户登录密码 | 'taosdata' | +| cfgdir | 客户端配置文件目录路径，Linux OS 上默认值 `/etc/taos`，Windows OS 上默认值 `C:/TDengine/cfg` | 系统依赖 | +| charset | 客户端使用的字符集 | 系统字符集 | +| locale | 客户端语言环境 | 系统当前 locale | +| timezone | 客户端使用的时区 | 系统当前时区 | +| batchfetch | 在执行查询时批量拉取结果集；false：逐行拉取结果集。开启批量拉取可以有效的提升查询性能 | true | +| batchErrorIgnore | true：在执行 Statement 的 executeBatch 时，如果中间有一条 SQL 执行失败将继续执行下面的 SQL。false：不再执行失败 SQL 后的任何语句 | false | JDBC 原生连接的使用请参见[视频教程](https://www.taosdata.com/blog/2020/11/11/1955.html)。 -**使用 TDengine 客户端驱动配置文件建立连接** +**使用 TDengine 客户端驱动配置文件建立连接** 当使用 JDBC 原生连接连接 TDengine 集群时，可以使用 TDengine 客户端驱动配置文件，在配置文件中指定集群的 firstEp、secondEp 等参数。 此时在 JDBC url 中不指定 `hostname` 和 `port`。 配置如 `jdbc:TAOS://:/power?user=root&password=taosdata`。 @@ -234,7 +236,7 @@ TDengine 中，只要保证 firstEp 和 secondEp 中一个节点有效，就可 > **注意**：这里的配置文件指的是调用 JDBC Connector 的应用程序所在机器上的配置文件，Linux OS 上默认值 /etc/taos/taos.cfg ，Windows OS 上默认值 C://TDengine/cfg/taos.cfg。 -##### Websocket 和 REST 连接 +**Websocket 和 REST 连接** 使用 JDBC Websocket 或 REST 连接，不需要依赖客户端驱动。与 JDBC 原生连接相比，仅需要： 1. driverClass 指定为“com.taosdata.jdbc.rs.RestfulDriver”； @@ -243,16 +245,19 @@ TDengine 中，只要保证 firstEp 和 secondEp 中一个节点有效，就可 对于 Websocket 和 REST 连接，url 中的配置参数如下： -- user：登录 TDengine 用户名，默认值 'root'。 -- password：用户登录密码，默认值 'taosdata'。 -- batchfetch: true：在执行查询时批量拉取结果集；false：逐行拉取结果集。默认值为：false。逐行拉取结果集使用 HTTP 方式进行数据传输。JDBC REST 连接支持批量拉取数据功能。taos-jdbcdriver 与 TDengine 之间通过 WebSocket 连接进行数据传输。相较于 HTTP，WebSocket 可以使 JDBC REST 连接支持大数据量查询，并提升查询性能。 -- charset: 当开启批量拉取数据时，指定解析字符串数据的字符集。 -- batchErrorIgnore：true：在执行 Statement 的 executeBatch 时，如果中间有一条 SQL 执行失败，继续执行下面的 SQL 了。false：不再执行失败 SQL 后的任何语句。默认值为：false。 -- httpConnectTimeout: 连接超时时间，单位 ms， 默认值为 60000。 -- httpSocketTimeout: socket 超时时间，单位 ms，默认值为 60000。仅在 batchfetch 设置为 false 时生效。 -- messageWaitTimeout: 消息超时时间, 单位 ms， 默认值为 60000。 仅在 batchfetch 设置为 true 时生效。 -- useSSL: 连接中是否使用 SSL。 -- httpPoolSize: REST 并发请求大小，默认 20。 +| 属性 | 描述 | 默认值 | +|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------| +| user | 登录 TDengine 用户名 | 'root' | +| password | 用户登录密码 | 'taosdata' | +| batchfetch | true：在执行查询时批量拉取结果集；false：逐行拉取结果集。逐行拉取结果集使用 HTTP 方式进行数据传输。JDBC REST 连接支持批量拉取数据功能。taos-jdbcdriver 与 TDengine 之间通过 WebSocket 连接进行数据传输，提升查询性能。 | false | +| charset | 当开启批量拉取数据时，指定解析字符串数据的字符集。 | | +| batchErrorIgnore | true：在执行 Statement 的 executeBatch 时，如果中间有一条 SQL 执行失败，继续执行下面的 SQL。false：不再执行失败 SQL 后的任何语句。 | false | +| httpConnectTimeout| 连接超时时间，单位 ms | 60000 | +| httpSocketTimeout | socket 超时时间，单位 ms。仅在 batchfetch 设置为 false 时生效。 | 60000 | +| messageWaitTimeout| 消息超时时间, 单位 ms。仅在 batchfetch 设置为 true 时生效。 | 60000 | +| useSSL | 连接中是否使用 SSL。 | | +| httpPoolSize | REST 并发请求大小 | 20 | + **注意**：部分配置项（比如：locale、timezone）在 REST 连接中不生效。 @@ -269,33 +274,35 @@ TDengine 中，只要保证 firstEp 和 secondEp 中一个节点有效，就可 > **注意**：应用中设置的 client parameter 为进程级别的，即如果要更新 client 的参数，需要重启应用。这是因为 client parameter 是全局参数，仅在应用程序的第一次设置生效。 -properties 中的配置参数如下： +properties 中的配置参数如下（**注意**：属性使用需要加上类名，如 `TSDBDriver.PROPERTY_KEY_USER` ）： + +| 属性 | 描述 | 默认值 | +|-------------------------------------------|------------------------------------------------------------------------------------------------------------------------------|----------------------| +| PROPERTY_KEY_USER | 登录 TDengine 用户名 | 'root' | +| PROPERTY_KEY_PASSWORD | 用户登录密码 | 'taosdata' | +| PROPERTY_KEY_BATCH_LOAD | 在执行查询时批量拉取结果集；false：逐行拉取结果集 | false | +| PROPERTY_KEY_BATCH_ERROR_IGNORE | 在执行 Statement 的 executeBatch 时，如果中间有一条 SQL 执行失败，继续执行下面的 SQL。false：不再执行失败 SQL 后的任何语句。 | false | +| PROPERTY_KEY_CONFIG_DIR | 仅在使用 JDBC 原生连接时生效。客户端配置文件目录路径 | Linux: `/etc/taos`, Windows: `C:/TDengine/cfg` | +| PROPERTY_KEY_CHARSET | 客户端使用的字符集 | 系统字符集 | +| PROPERTY_KEY_LOCALE | 仅在使用 JDBC 原生连接时生效。客户端语言环境 | 系统当前 locale | +| PROPERTY_KEY_TIME_ZONE | 仅在使用 JDBC 原生连接时生效。客户端使用的时区 | 系统当前时区 | +| HTTP_CONNECT_TIMEOUT | 连接超时时间，单位 ms。仅在 REST 连接时生效。 | 60000 | +| HTTP_SOCKET_TIMEOUT | socket 超时时间，单位 ms。仅在 REST 连接且 batchfetch 设置为 false 时生效。 | 60000 | +| PROPERTY_KEY_MESSAGE_WAIT_TIMEOUT | 消息超时时间, 单位 ms。仅在 REST 连接且 batchfetch 设置为 true 时生效。 | 60000 | +| PROPERTY_KEY_USE_SSL | 连接中是否使用 SSL。仅在 REST 连接时生效。 | | +| HTTP_POOL_SIZE | REST 并发请求大小 | 20 | +| PROPERTY_KEY_ENABLE_COMPRESSION | 传输过程是否启用压缩。仅在使用 REST/Websocket 连接时生效。 | false | +| PROPERTY_KEY_ENABLE_AUTO_RECONNECT | 是否启用自动重连。仅在使用 Websocket 连接时生效。 | false | +| PROPERTY_KEY_RECONNECT_INTERVAL_MS | 自动重连重试间隔，单位毫秒。仅在 PROPERTY_KEY_ENABLE_AUTO_RECONNECT 为 true 时生效。 | 2000 | +| PROPERTY_KEY_RECONNECT_RETRY_COUNT | 自动重连重试次数。仅在 PROPERTY_KEY_ENABLE_AUTO_RECONNECT 为 true 时生效。 | 3 | +| PROPERTY_KEY_DISABLE_SSL_CERT_VALIDATION | 关闭 SSL 证书验证。仅在使用 Websocket 连接时生效。 | false | -- TSDBDriver.PROPERTY_KEY_USER：登录 TDengine 用户名，默认值 'root'。 -- TSDBDriver.PROPERTY_KEY_PASSWORD：用户登录密码，默认值 'taosdata'。 -- TSDBDriver.PROPERTY_KEY_BATCH_LOAD: true：在执行查询时批量拉取结果集；false：逐行拉取结果集。默认值为：false。 -- TSDBDriver.PROPERTY_KEY_BATCH_ERROR_IGNORE：true：在执行 Statement 的 executeBatch 时，如果中间有一条 SQL 执行失败，继续执行下面的 sq 了。false：不再执行失败 SQL 后的任何语句。默认值为：false。 -- TSDBDriver.PROPERTY_KEY_CONFIG_DIR：仅在使用 JDBC 原生连接时生效。客户端配置文件目录路径，Linux OS 上默认值 `/etc/taos`，Windows OS 上默认值 `C:/TDengine/cfg`。 -- TSDBDriver.PROPERTY_KEY_CHARSET：客户端使用的字符集，默认值为系统字符集。 -- TSDBDriver.PROPERTY_KEY_LOCALE：仅在使用 JDBC 原生连接时生效。 客户端语言环境，默认值系统当前 locale。 -- TSDBDriver.PROPERTY_KEY_TIME_ZONE：仅在使用 JDBC 原生连接时生效。 客户端使用的时区，默认值为系统当前时区。因为历史的原因，我们只支持POSIX标准的部分规范，如UTC-8(代表中国上上海), GMT-8，Asia/Shanghai 这几种形式。 -- TSDBDriver.HTTP_CONNECT_TIMEOUT: 连接超时时间，单位 ms， 默认值为 60000。仅在 REST 连接时生效。 -- TSDBDriver.HTTP_SOCKET_TIMEOUT: socket 超时时间，单位 ms，默认值为 60000。仅在 REST 连接且 batchfetch 设置为 false 时生效。 -- TSDBDriver.PROPERTY_KEY_MESSAGE_WAIT_TIMEOUT: 消息超时时间, 单位 ms， 默认值为 60000。 仅在 REST 连接且 batchfetch 设置为 true 时生效。 -- TSDBDriver.PROPERTY_KEY_USE_SSL: 连接中是否使用 SSL。仅在 REST 连接时生效。 -- TSDBDriver.HTTP_POOL_SIZE: REST 并发请求大小，默认 20。 -- TSDBDriver.PROPERTY_KEY_ENABLE_COMPRESSION: 传输过程是否启用压缩。仅在使用 REST/Websocket 连接时生效。true: 启用，false: 不启用。默认为 false。 -- TSDBDriver.PROPERTY_KEY_ENABLE_AUTO_RECONNECT: 是否启用自动重连。仅在使用 Websocket 连接时生效。true: 启用，false: 不启用。默认为 false。 > **注意**：启用自动重连仅对简单执行 SQL 语句以及 无模式写入、数据订阅有效。对于参数绑定无效。自动重连仅对连接建立时通过参数指定数据库有效，对后面的 `use db` 语句切换数据库无效。 -- TSDBDriver.PROPERTY_KEY_RECONNECT_INTERVAL_MS: 自动重连重试间隔，单位毫秒，默认值 2000。仅在 PROPERTY_KEY_ENABLE_AUTO_RECONNECT 为 true 时生效。 -- TSDBDriver.PROPERTY_KEY_RECONNECT_RETRY_COUNT: 自动重连重试次数，默认值 3，仅在 PROPERTY_KEY_ENABLE_AUTO_RECONNECT 为 true 时生效。 -- TSDBDriver.PROPERTY_KEY_DISABLE_SSL_CERT_VALIDATION: 关闭 SSL 证书验证 。仅在使用 Websocket 连接时生效。true: 启用，false: 不启用。默认为 false。 - 此外对 JDBC 原生连接，通过指定 URL 和 Properties 还可以指定其他参数，比如日志级别、SQL 长度等。更多详细配置请参考[客户端配置](../../reference/config/)。 -##### 配置参数的优先级 +**配置参数的优先级** 通过前面三种方式获取连接，如果配置参数在 url、Properties、客户端配置文件中有重复，则参数的`优先级由高到低`分别如下： From d3a70581434b6010f366615ab3ffda9b4e56a65c Mon Sep 17 00:00:00 2001 From: sheyanjie-qq <249478495@qq.com> Date: Wed, 31 Jul 2024 17:18:07 +0800 Subject: [PATCH 3/7] mod jdbc doc --- .../com/taos/example/JNIConnectExample.java | 6 +- .../com/taos/example/RESTConnectExample.java | 6 +- .../com/taos/example/WSConnectExample.java | 10 +- docs/zh/08-develop/01-connect/index.md | 62 +----------- docs/zh/08-develop/07-tmq.md | 96 +++++++++++-------- docs/zh/14-reference/05-connector/14-java.mdx | 29 +++--- .../com/taosdata/example/AbsConsumerLoop.java | 26 ++--- .../taosdata/example/AbsWsConsumerLoop.java | 5 +- .../com/taosdata/example/JdbcBasicDemo.java | 5 +- .../com/taosdata/example/JdbcCreatDBDemo.java | 5 +- .../taosdata/example/JdbcInsertDataDemo.java | 5 +- .../com/taosdata/example/JdbcQueryDemo.java | 5 +- .../com/taosdata/example/JdbcReqIdDemo.java | 5 +- .../example/ParameterBindingBasicDemo.java | 5 +- .../taosdata/example/SchemalessJniTest.java | 4 +- .../taosdata/example/SchemalessWsTest.java | 4 +- .../example/WSParameterBindingBasicDemo.java | 5 +- .../example/WSParameterBindingDemo.java | 4 +- .../example/WSParameterBindingFullDemo.java | 4 +- 19 files changed, 142 insertions(+), 149 deletions(-) diff --git a/docs/examples/java/src/main/java/com/taos/example/JNIConnectExample.java b/docs/examples/java/src/main/java/com/taos/example/JNIConnectExample.java index 24cf3c98ef..8905150a0a 100644 --- a/docs/examples/java/src/main/java/com/taos/example/JNIConnectExample.java +++ b/docs/examples/java/src/main/java/com/taos/example/JNIConnectExample.java @@ -25,8 +25,10 @@ public static void main(String[] args) throws SQLException { // you can use the connection for execute SQL here } catch (SQLException ex) { - // handle any errors - System.out.println("SQLException: " + ex.getMessage()); + // handle any errors, please refer to the JDBC specifications for detailed exceptions info + System.out.println("SQLState: " + ex.getSQLState()); + System.out.println("Error Code: " + ex.getErrorCode()); + System.out.println("Message: " + ex.getMessage()); } } // ANCHOR_END: main diff --git a/docs/examples/java/src/main/java/com/taos/example/RESTConnectExample.java b/docs/examples/java/src/main/java/com/taos/example/RESTConnectExample.java index 1eb4c0755e..cd129db699 100644 --- a/docs/examples/java/src/main/java/com/taos/example/RESTConnectExample.java +++ b/docs/examples/java/src/main/java/com/taos/example/RESTConnectExample.java @@ -14,8 +14,10 @@ public static void main(String[] args) throws SQLException { // you can use the connection for execute SQL here } catch (SQLException ex) { - // handle any errors - System.out.println("SQLException: " + ex.getMessage()); + // handle any errors, please refer to the JDBC specifications for detailed exceptions info + System.out.println("SQLState: " + ex.getSQLState()); + System.out.println("Error Code: " + ex.getErrorCode()); + System.out.println("Message: " + ex.getMessage()); } } // ANCHOR_END: main diff --git a/docs/examples/java/src/main/java/com/taos/example/WSConnectExample.java b/docs/examples/java/src/main/java/com/taos/example/WSConnectExample.java index b28f4c7ff8..3f417841b2 100644 --- a/docs/examples/java/src/main/java/com/taos/example/WSConnectExample.java +++ b/docs/examples/java/src/main/java/com/taos/example/WSConnectExample.java @@ -16,14 +16,20 @@ public static void main(String[] args) throws SQLException { String jdbcUrl = "jdbc:TAOS-RS://localhost:6041?user=root&password=taosdata"; Properties connProps = new Properties(); connProps.setProperty(TSDBDriver.PROPERTY_KEY_BATCH_LOAD, "true"); + connProps.setProperty(TSDBDriver.PROPERTY_KEY_ENABLE_AUTO_RECONNECT, "true"); + connProps.setProperty(TSDBDriver.PROPERTY_KEY_CHARSET, "UTF-8"); + connProps.setProperty(TSDBDriver.PROPERTY_KEY_TIME_ZONE, "UTC-8"); + try (Connection conn = DriverManager.getConnection(jdbcUrl, connProps)){ System.out.println("Connected"); // you can use the connection for execute SQL here } catch (SQLException ex) { - // handle any errors - System.out.println("SQLException: " + ex.getMessage()); + // handle any errors, please refer to the JDBC specifications for detailed exceptions info + System.out.println("SQLState: " + ex.getSQLState()); + System.out.println("Error Code: " + ex.getErrorCode()); + System.out.println("Message: " + ex.getMessage()); } } // ANCHOR_END: main diff --git a/docs/zh/08-develop/01-connect/index.md b/docs/zh/08-develop/01-connect/index.md index 93da9c9266..29e363c019 100644 --- a/docs/zh/08-develop/01-connect/index.md +++ b/docs/zh/08-develop/01-connect/index.md @@ -269,69 +269,11 @@ phpize && ./configure --enable-swoole && make -j && make install -Java 连接器建立连接的参数有 URL 和 properties，下面分别详细介绍。 +Java 连接器建立连接的参数有 URL 和 Properties。 TDengine 的 JDBC URL 规范格式为： `jdbc:[TAOS|TAOS-RS]://[host_name]:[port]/[database_name]?[user={user}|&password={password}|&charset={charset}|&cfgdir={config_dir}|&locale={locale}|&timezone={timezone}]` -对于建立连接，原生连接与 REST 连接有细微不同。 -**注**：REST 连接中增加 `batchfetch` 参数并设置为 true，将开启 WebSocket 连接。 - -**注意**：使用 JDBC 原生连接，taos-jdbcdriver 需要依赖客户端驱动（Linux 下是 libtaos.so；Windows 下是 taos.dll；macOS 下是 libtaos.dylib）。 - -url 中的配置参数如下： - -| 参数 | 描述 | 默认值 | -| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | -| user | 登录 TDengine 用户名 | 'root' | -| password | 用户登录密码 | 'taosdata' | -| batchfetch | true：在执行查询时批量拉取结果集；false：逐行拉取结果集。逐行拉取结果集使用 HTTP 方式进行数据传输。JDBC REST 连接支持批量拉取数据功能。taos-jdbcdriver 与 TDengine 之间通过 WebSocket 连接进行数据传输。相较于 HTTP，WebSocket 可以使 JDBC REST 连接支持大数据量查询，并提升查询性能。 | false | -| charset | 当开启批量拉取数据时，指定解析字符串数据的字符集。 | | -| batchErrorIgnore | true：在执行 Statement 的 executeBatch 时，如果中间有一条 SQL 执行失败，继续执行下面的 SQL 了。false：不再执行失败 SQL 后的任何语句。 | false | -| httpConnectTimeout | 连接超时时间，单位 ms | 60000 | -| httpSocketTimeout | socket 超时时间，单位 ms，仅在 batchfetch 设置为 false 时生效。 | 60000 | -| messageWaitTimeout | 消息超时时间, 单位 ms，仅在 batchfetch 设置为 true 时生效。 | 60000 | -| useSSL | 连接中是否使用 SSL。 | | -| httpPoolSize | REST 并发请求大小，默认 20。 | 20 | - - -**注意**：部分配置项（比如：locale、timezone）在 REST 连接中不生效。 - - -除了通过指定的 URL 获取连接，还可以使用 Properties 指定建立连接时的参数。 -properties 中的配置参数如下（**注意**：属性使用需要加上类名，如 `TSDBDriver.PROPERTY_KEY_USER` ）： - -| 属性 | 描述 | 默认值 | -| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------- | -| PROPERTY_KEY_USER | 登录 TDengine 用户名 | 'root' | -| PROPERTY_KEY_PASSWORD | 用户登录密码 | 'taosdata' | -| PROPERTY_KEY_BATCH_LOAD | true：在执行查询时批量拉取结果集；false：逐行拉取结果集 | false | -| PROPERTY_KEY_BATCH_ERROR_IGNORE | true：在执行 Statement 的 executeBatch 时，如果中间有一条 SQL 执行失败，继续执行下面的 SQL；false：不再执行失败 SQL 后的任何语句 | false | -| PROPERTY_KEY_CONFIG_DIR | 仅在使用 JDBC 原生连接时生效。客户端配置文件目录路径，Linux OS 上默认值 /etc/taos，Windows OS 上默认值 C:/TDengine/cfg | 系统依赖 | -| PROPERTY_KEY_CHARSET | 客户端使用的字符集 | 系统字符集 | -| PROPERTY_KEY_LOCALE | 仅在使用 JDBC 原生连接时生效。客户端语言环境 | 系统当前 locale | -| PROPERTY_KEY_TIME_ZONE | 仅在使用 JDBC 原生连接时生效。客户端使用的时区 | 系统当前时区 | -| HTTP_CONNECT_TIMEOUT | 连接超时时间，单位 ms，仅在 REST 连接时生效 | 60000 | -| HTTP_SOCKET_TIMEOUT | socket 超时时间，单位 ms，仅在 REST 连接且 batchfetch 设置为 false 时生效 | 60000 | -| PROPERTY_KEY_MESSAGE_WAIT_TIMEOUT | 消息超时时间, 单位 ms，仅在 REST 连接且 batchfetch 设置为 true 时生效 | 60000 | -| PROPERTY_KEY_USE_SSL | 连接中是否使用 SSL。仅在 REST 连接时生效 | | -| HTTP_POOL_SIZE | REST 并发请求大小 | 20 | -| PROPERTY_KEY_ENABLE_COMPRESSION | 传输过程是否启用压缩。仅在使用 REST/Websocket 连接时生效 | false | -| PROPERTY_KEY_ENABLE_AUTO_RECONNECT | 是否启用自动重连。仅在使用 Websocket 连接时生效 | false | -| PROPERTY_KEY_RECONNECT_INTERVAL_MS | 自动重连重试间隔，单位毫秒。仅在 PROPERTY_KEY_ENABLE_AUTO_RECONNECT 为 true 时生效 | 2000 | -| PROPERTY_KEY_RECONNECT_RETRY_COUNT | 自动重连重试次数。仅在 PROPERTY_KEY_ENABLE_AUTO_RECONNECT 为 true 时生效 | 3 | -| PROPERTY_KEY_DISABLE_SSL_CERT_VALIDATION | 关闭 SSL 证书验证。仅在使用 Websocket 连接时生效 | false | - -> **注意**：启用自动重连仅对简单执行 SQL 语句以及 无模式写入、数据订阅有效。对于参数绑定无效。自动重连仅对连接建立时通过参数指定数据库有效，对后面的 `use db` 语句切换数据库无效。 - -**配置参数的优先级：** - -通过前面三种方式获取连接，如果配置参数在 url、Properties、客户端配置文件中有重复，则参数的**优先级由高到低**分别如下： - -1. JDBC URL 参数，如上所述，可以在 JDBC URL 的参数中指定。 -2. Properties connProps -3. 使用原生连接时，TDengine 客户端驱动的配置文件 taos.cfg - -例如：在 url 中指定了 password 为 taosdata，在 Properties 中指定了 password 为 taosdemo，那么，JDBC 会使用 url 中的 password 建立连接。 +URL 和 Properties 的详细参数说明和如何使用详见 [API 说明](../../reference/connector/java/#url-规范) diff --git a/docs/zh/08-develop/07-tmq.md b/docs/zh/08-develop/07-tmq.md index e6d866c29c..f548126e49 100644 --- a/docs/zh/08-develop/07-tmq.md +++ b/docs/zh/08-develop/07-tmq.md @@ -7,7 +7,7 @@ toc_max_heading_level: 4 import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem"; -TDengine 提供了类似于消息队列产品的数据订阅和消费接口。在许多场景中，采用TDengine 的时序大数据平台，无须再集成消息队列产品，从而简化应用程序设计并降低运维成本。本章介绍各语言连接器数据订阅的相关API以及使用方法。 数据订阅的基础知识请参考 [数据订阅](../../advanced/subscription/) +TDengine 提供了类似于消息队列产品的数据订阅和消费接口。在许多场景中，采用 TDengine 的时序大数据平台，无须再集成消息队列产品，从而简化应用程序设计并降低运维成本。本章介绍各语言连接器数据订阅的相关 API 以及使用方法。 数据订阅的基础知识请参考 [数据订阅](../../advanced/subscription/) ## 创建主题 请用 taos shell 或者 参考 [执行 SQL](../sql/) 章节用程序执行创建主题的 SQL：`CREATE TOPIC IF NOT EXISTS topic_meters AS SELECT ts, current, voltage, phase, groupid, location FROM meters` @@ -16,7 +16,7 @@ TDengine 提供了类似于消息队列产品的数据订阅和消费接口。 **注意** 在 TDengine 连接器实现中，对于订阅查询，有以下限制。 -- 查询语句限制：订阅查询只能使用 select 语句，不支持其他类型的SQL，如 insert、update或delete等。 +- 查询语句限制：订阅查询只能使用 select 语句，不支持其他类型的SQL，如 insert、update 或 delete 等。 - 原始始数据查询：订阅查询只能查询原始数据，而不能查询聚合或计算结果。 - 时间顺序限制：订阅查询只能按照时间正序查询数据。 @@ -26,32 +26,29 @@ TDengine 消费者的概念跟 Kafka 类似，消费者通过订阅主题来接 ### 创建参数 -创建消费者的参数较多，非常灵活的支持了各种连接类型、 Offset 提交方式、压缩、重连、反序列化等特性，下面单独介绍各语言连接器创建消费者的参数。 +创建消费者的参数较多，非常灵活的支持了各种连接类型、 Offset 提交方式、压缩、重连、反序列化等特性。各语言连接器都适用的通用基础配置项如下表所示： +| 参数名称 | 类型 | 参数说明 | 备注 | +| :-----------------------: | :-----: | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `td.connect.ip` | string | 服务端的 IP 地址 | | +| `td.connect.user` | string | 用户名 | | +| `td.connect.pass` | string | 密码 | | +| `td.connect.port` | integer | 服务端的端口号 | | +| `group.id` | string | 消费组 ID，同一消费组共享消费进度 |
**必填项**。最大长度：192。
每个topic最多可建立100个 consumer group | +| `client.id` | string | 客户端 ID | 最大长度：192。 | +| `auto.offset.reset` | enum | 消费组订阅的初始位置 |
`earliest`: default(version < 3.2.0.0);从头开始订阅;
`latest`: default(version >= 3.2.0.0);仅从最新数据开始订阅;
`none`: 没有提交的 offset 无法订阅 | +| `enable.auto.commit` | boolean | 是否启用消费位点自动提交，true: 自动提交，客户端应用无需commit；false：客户端应用需要自行commit | 默认值为 true | +| `auto.commit.interval.ms` | integer | 消费记录自动提交消费位点时间间隔，单位为毫秒 | 默认值为 5000 | +| `msg.with.table.name` | boolean | 是否允许从消息中解析表名, 不适用于列订阅（列订阅时可将 tbname 作为列写入 subquery 语句）（从3.2.0.0版本该参数废弃，恒为true） | 默认关闭 | +| `enable.replay` | boolean | 是否开启数据回放功能 | 默认关闭 | + + +下面是各语言连接器创建参数： -Java 连接器创建消费者的参数为 Properties， 可以设置如下参数： +Java 连接器创建消费者的参数为 Properties， 可以设置的参数列表请参考 [API 说明](../../reference/connector/java/#消费者) +其他参数请参考上文通用基础配置项。 -- td.connect.type: 连接方式。jni：表示使用动态库连接的方式，ws/WebSocket：表示使用 WebSocket 进行数据通信。默认为 jni 方式。 -- bootstrap.servers: TDengine 服务端所在的`ip:port`，如果使用 WebSocket 连接，则为 taosAdapter 所在的`ip:port`。 -- enable.auto.commit: 是否允许自动提交。 -- group.id: consumer: 所在的 group。 -- value.deserializer: 结果集反序列化方法，可以继承 `com.taosdata.jdbc.tmq.ReferenceDeserializer`，并指定结果集 bean，实现反序列化。也可以继承 `com.taosdata.jdbc.tmq.Deserializer`，根据 SQL 的 resultSet 自定义反序列化方式。 -- httpConnectTimeout: 创建连接超时参数，单位 ms，默认为 5000 ms。仅在 WebSocket 连接下有效。 -- messageWaitTimeout: 数据传输超时参数，单位 ms，默认为 10000 ms。仅在 WebSocket 连接下有效。 -- httpPoolSize: 同一个连接下最大并行请求数。仅在 WebSocket 连接下有效。 -- TSDBDriver.PROPERTY_KEY_ENABLE_COMPRESSION: 传输过程是否启用压缩。仅在使用 Websocket 连接时生效。true: 启用，false: 不启用。默认为 false。 -- TSDBDriver.PROPERTY_KEY_ENABLE_AUTO_RECONNECT: 是否启用自动重连。仅在使用 Websocket 连接时生效。true: 启用，false: 不启用。默认为 false。 -- TSDBDriver.PROPERTY_KEY_RECONNECT_INTERVAL_MS: 自动重连重试间隔，单位毫秒，默认值 2000。仅在 PROPERTY_KEY_ENABLE_AUTO_RECONNECT 为 true 时生效。 -- TSDBDriver.PROPERTY_KEY_RECONNECT_RETRY_COUNT: 自动重连重试次数，默认值 3，仅在 PROPERTY_KEY_ENABLE_AUTO_RECONNECT 为 true 时生效。 - -其他参数请参考：[Consumer 参数列表](../../develop/tmq/#数据订阅相关参数)， 注意TDengine服务端自 3.2.0.0 版本开始消息订阅中的 auto.offset.reset 默认值发生变化。 - -:::note - -- Java 连接器数据订阅 WebSocket 连接方式跟 原生连接方式，除了在创建消费者时参数不同之外，其他接口并无区别。因此我们以 Websocket 连接方式为例介绍数据订阅的其他功能。 - -::: @@ -81,6 +78,7 @@ Java 连接器创建消费者的参数为 Properties， 可以设置如下参数 ### Websocket 连接 +介绍各语言连接器使用 Websocket 连接方式创建消费者。 @@ -128,6 +126,8 @@ Java 连接器创建消费者的参数为 Properties， 可以设置如下参数 ### 原生连接 +介绍各语言连接器使用原生连接方式创建消费者。 + @@ -271,20 +271,27 @@ Java 连接器创建消费者的参数为 Properties， 可以设置如下参数 ```java -// 获取订阅的 topicPartition -Set assignment() throws SQLException; -// 指定下一次 poll 中使用的 offset +// 获取指定分区的当前偏移量 +long position(TopicPartition partition) throws SQLException; +// 获取指定主题的所有分区的当前偏移量 +Map position(String topic) throws SQLException; +// 获取指定主题的所有分区的起始偏移量 +Map beginningOffsets(String topic) throws SQLException; +// 获取指定主题的所有分区的最新偏移量 +Map endOffsets(String topic) throws SQLException; +// 获取指定分区集合中的已提交偏移量 +Map committed(Set partitions) throws SQLException; + +// 设置指定分区的偏移量 void seek(TopicPartition partition, long offset) throws SQLException; -void seekToBeginning(Collection partitions) throws SQLException; +// 将指定分区集合的偏移量设置为最新 +void seekToEnd(Collection partitions) throws SQLException; ``` 示例代码： @@ -381,11 +388,16 @@ void seekToEnd(Collection ```java -void commitSync() throws SQLException; -void commitSync(Map offsets) throws SQLException; + // 异步提交仅在 native 连接下有效 -void commitAsync(OffsetCommitCallback callback) throws SQLException; +// 异步提交指定的偏移量，需要提供回调以处理可能的提交结果 +void commitAsync(Map offsets, OffsetCommitCallback callback) throws SQLException; ``` @@ -583,7 +595,8 @@ void commitAsync(Map @@ -630,6 +643,9 @@ void commitAsync(Map diff --git a/docs/zh/14-reference/05-connector/14-java.mdx b/docs/zh/14-reference/05-connector/14-java.mdx index 23b4392008..acb1dee674 100644 --- a/docs/zh/14-reference/05-connector/14-java.mdx +++ b/docs/zh/14-reference/05-connector/14-java.mdx @@ -1348,18 +1348,23 @@ JDBC 标准不支持数据订阅，因此本章所有接口都是扩展接口。 - **异常**：如果创建失败，抛出 SQLException 异常。 创建消费者支持属性列表： -- td.connect.type: 连接方式。jni：表示使用动态库连接的方式，ws/WebSocket：表示使用 WebSocket 进行数据通信。默认为 jni 方式。 -- bootstrap.servers: TDengine 服务端所在的`ip:port`，如果使用 WebSocket 连接，则为 taosAdapter 所在的`ip:port`。 -- enable.auto.commit: 是否允许自动提交。 -- group.id: consumer: 所在的 group。 -- value.deserializer: 结果集反序列化方法，可以继承 `com.taosdata.jdbc.tmq.ReferenceDeserializer`，并指定结果集 bean，实现反序列化。也可以继承 `com.taosdata.jdbc.tmq.Deserializer`，根据 SQL 的 resultSet 自定义反序列化方式。 -- httpConnectTimeout: 创建连接超时参数，单位 ms，默认为 5000 ms。仅在 WebSocket 连接下有效。 -- messageWaitTimeout: 数据传输超时参数，单位 ms，默认为 10000 ms。仅在 WebSocket 连接下有效。 -- httpPoolSize: 同一个连接下最大并行请求数。仅在 WebSocket 连接下有效。 -- TSDBDriver.PROPERTY_KEY_ENABLE_COMPRESSION: 传输过程是否启用压缩。仅在使用 Websocket 连接时生效。true: 启用，false: 不启用。默认为 false。 -- TSDBDriver.PROPERTY_KEY_ENABLE_AUTO_RECONNECT: 是否启用自动重连。仅在使用 Websocket 连接时生效。true: 启用，false: 不启用。默认为 false。 -- TSDBDriver.PROPERTY_KEY_RECONNECT_INTERVAL_MS: 自动重连重试间隔，单位毫秒，默认值 2000。仅在 PROPERTY_KEY_ENABLE_AUTO_RECONNECT 为 true 时生效。 -- TSDBDriver.PROPERTY_KEY_RECONNECT_RETRY_COUNT: 自动重连重试次数，默认值 3，仅在 PROPERTY_KEY_ENABLE_AUTO_RECONNECT 为 true 时生效。 + + +| 属性 | 描述 | 默认值 | +| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| td.connect.type | 连接方式。jni：表示使用动态库连接的方式，ws/WebSocket：表示使用 WebSocket 进行数据通信。 | jni | +| bootstrap.servers | TDengine 服务端所在的ip:port，如果使用 WebSocket 连接，则为 taosAdapter 所在的ip:port。 | | +| enable.auto.commit | 是否允许自动提交。 | | +| group.id | consumer 所在的 group。 | | +| value.deserializer | 结果集反序列化方法。可以继承 com.taosdata.jdbc.tmq.ReferenceDeserializer，并指定结果集 bean，实现反序列化。也可以继承 com.taosdata.jdbc.tmq.Deserializer，根据 SQL 的 resultSet 自定义反序列化方式。 | | +| httpConnectTimeout | 创建连接超时参数，单位 ms。仅在 WebSocket 连接下有效。 | 5000 ms | +| messageWaitTimeout | 数据传输超时参数，单位 ms。仅在 WebSocket 连接下有效。 | 10000 ms | +| httpPoolSize | 同一个连接下最大并行请求数。仅在 WebSocket 连接下有效。 | | +| enableCompression | 传输过程是否启用压缩。仅在使用 Websocket 连接时生效。true: 启用，false: 不启用。 | false | +| enableAutoReconnect | 是否启用自动重连。仅在使用 Websocket 连接时生效。true: 启用，false: 不启用。 | false | +| reconnectIntervalMs | 自动重连重试间隔，单位毫秒。仅在 enableCompression 为 true 时生效。 | 2000 ms | +| reconnectRetryCount | 自动重连重试次数。仅在 enableCompression 为 true 时生效。 | 3 | + 其他参数请参考：[Consumer 参数列表](../../develop/tmq/#数据订阅相关参数)， 注意TDengine服务端自 3.2.0.0 版本开始消息订阅中的 auto.offset.reset 默认值发生变化。 - `public void subscribe(Collection topics) throws SQLException` diff --git a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/AbsConsumerLoop.java b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/AbsConsumerLoop.java index d3a484dc43..62e3939573 100644 --- a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/AbsConsumerLoop.java +++ b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/AbsConsumerLoop.java @@ -38,8 +38,9 @@ config.setProperty("value.deserializer.encoding", "UTF-8"); try { this.consumer = new TaosConsumer<>(config); } catch (SQLException ex) { - // handle exception - System.out.println("SQLException: " + ex.getMessage()); + // handle any errors, please refer to the JDBC specifications for detailed exceptions info + System.out.println("Error Code: " + ex.getErrorCode()); + System.out.println("Message: " + ex.getMessage()); throw new SQLException("Failed to create consumer", ex); } // ANCHOR_END: create_consumer @@ -63,9 +64,10 @@ try { process(bean); } } -} catch (Exception ex){ - // handle exception - System.out.println("SQLException: " + ex.getMessage()); +} catch (SQLException ex){ + // handle any errors, please refer to the JDBC specifications for detailed exceptions info + System.out.println("Error Code: " + ex.getErrorCode()); + System.out.println("Message: " + ex.getMessage()); } finally { consumer.close(); @@ -90,9 +92,10 @@ try { consumer.commitSync(); } } -} catch (Exception ex){ - // handle exception - System.out.println("SQLException: " + ex.getMessage()); +} catch (SQLException ex){ + // handle any errors, please refer to the JDBC specifications for detailed exceptions info + System.out.println("Error Code: " + ex.getErrorCode()); + System.out.println("Message: " + ex.getMessage()); } finally { consumer.close(); @@ -105,9 +108,10 @@ try { // ANCHOR: unsubscribe_data_code_piece try { consumer.unsubscribe(); -} catch (Exception ex){ - // handle exception - System.out.println("SQLException: " + ex.getMessage()); +} catch (SQLException ex){ + // handle any errors, please refer to the JDBC specifications for detailed exceptions info + System.out.println("Error Code: " + ex.getErrorCode()); + System.out.println("Message: " + ex.getMessage()); } finally { consumer.close(); } diff --git a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/AbsWsConsumerLoop.java b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/AbsWsConsumerLoop.java index 5abfc95cae..98ff5657d8 100644 --- a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/AbsWsConsumerLoop.java +++ b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/AbsWsConsumerLoop.java @@ -38,8 +38,9 @@ config.setProperty("value.deserializer.encoding", "UTF-8"); try { this.consumer = new TaosConsumer<>(config); } catch (SQLException ex) { - // handle exception - System.out.println("SQLException: " + ex.getMessage()); + // handle any errors, please refer to the JDBC specifications for detailed exceptions info + System.out.println("Error Code: " + ex.getErrorCode()); + System.out.println("Message: " + ex.getMessage()); throw new SQLException("Failed to create consumer", ex); } // ANCHOR_END: create_consumer diff --git a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/JdbcBasicDemo.java b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/JdbcBasicDemo.java index ca5813710b..4831567eab 100644 --- a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/JdbcBasicDemo.java +++ b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/JdbcBasicDemo.java @@ -109,8 +109,9 @@ try (Statement statement = connection.createStatement(); } // ANCHOR_END: jdbc_exception } catch (SQLException ex) { - // handle any errors - System.out.println("SQLException: " + ex.getMessage()); + // handle any errors, please refer to the JDBC specifications for detailed exceptions info + System.out.println("Error Code: " + ex.getErrorCode()); + System.out.println("Message: " + ex.getMessage()); } } diff --git a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/JdbcCreatDBDemo.java b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/JdbcCreatDBDemo.java index 0f12b6828c..b2246e96cf 100644 --- a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/JdbcCreatDBDemo.java +++ b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/JdbcCreatDBDemo.java @@ -43,8 +43,9 @@ try (Connection connection = DriverManager.getConnection(url, properties); assert rowsAffected == 0; } catch (SQLException ex) { - // handle any errors - System.out.println("SQLException: " + ex.getMessage()); + // handle any errors, please refer to the JDBC specifications for detailed exceptions info + System.out.println("Error Code: " + ex.getErrorCode()); + System.out.println("Message: " + ex.getMessage()); } // ANCHOR_END: create_db_and_table diff --git a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/JdbcInsertDataDemo.java b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/JdbcInsertDataDemo.java index e56a47279b..76e16c9cee 100644 --- a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/JdbcInsertDataDemo.java +++ b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/JdbcInsertDataDemo.java @@ -41,8 +41,9 @@ try (Connection connection = DriverManager.getConnection(url, properties); // you can check affectedRows here System.out.println("insert " + affectedRows + " rows."); } catch (SQLException ex) { - // handle any errors - System.out.println("SQLException: " + ex.getMessage()); + // handle any errors, please refer to the JDBC specifications for detailed exceptions info + System.out.println("Error Code: " + ex.getErrorCode()); + System.out.println("Message: " + ex.getMessage()); } // ANCHOR_END: insert_data } diff --git a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/JdbcQueryDemo.java b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/JdbcQueryDemo.java index d0cc362bbe..fdbab204c2 100644 --- a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/JdbcQueryDemo.java +++ b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/JdbcQueryDemo.java @@ -42,8 +42,9 @@ try (Connection connection = DriverManager.getConnection(url, properties); System.out.printf("%s, %f, %s\n", ts, current, location); } } catch (SQLException ex) { - // handle any errors - System.out.println("SQLException: " + ex.getMessage()); + // handle any errors, please refer to the JDBC specifications for detailed exceptions info + System.out.println("Error Code: " + ex.getErrorCode()); + System.out.println("Message: " + ex.getMessage()); } // ANCHOR_END: query_data } diff --git a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/JdbcReqIdDemo.java b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/JdbcReqIdDemo.java index 1c44c2916e..5fb7e9760e 100644 --- a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/JdbcReqIdDemo.java +++ b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/JdbcReqIdDemo.java @@ -42,8 +42,9 @@ try (Connection connection = DriverManager.getConnection(url, properties); } } } catch (SQLException ex) { - // handle any errors - System.out.println("SQLException: " + ex.getMessage()); + // handle any errors, please refer to the JDBC specifications for detailed exceptions info + System.out.println("Error Code: " + ex.getErrorCode()); + System.out.println("Message: " + ex.getMessage()); } // ANCHOR_END: with_reqid } diff --git a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/ParameterBindingBasicDemo.java b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/ParameterBindingBasicDemo.java index ee70049dba..d5f547b50f 100644 --- a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/ParameterBindingBasicDemo.java +++ b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/ParameterBindingBasicDemo.java @@ -69,8 +69,9 @@ public class ParameterBindingBasicDemo { pstmt.columnDataExecuteBatch(); } } catch (SQLException ex) { - // handle any errors - System.out.println("SQLException: " + ex.getMessage()); + // handle any errors, please refer to the JDBC specifications for detailed exceptions info + System.out.println("Error Code: " + ex.getErrorCode()); + System.out.println("Message: " + ex.getMessage()); } } diff --git a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/SchemalessJniTest.java b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/SchemalessJniTest.java index 61d1acf08b..238ad35502 100644 --- a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/SchemalessJniTest.java +++ b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/SchemalessJniTest.java @@ -26,7 +26,9 @@ public class SchemalessJniTest { conn.write(telnetDemo, SchemalessProtocolType.TELNET, SchemalessTimestampType.MILLI_SECONDS); conn.write(jsonDemo, SchemalessProtocolType.JSON, SchemalessTimestampType.NOT_CONFIGURED); } catch (SQLException ex) { - System.out.println("SQLException: " + ex.getMessage()); + // handle any errors, please refer to the JDBC specifications for detailed exceptions info + System.out.println("Error Code: " + ex.getErrorCode()); + System.out.println("Message: " + ex.getMessage()); } } diff --git a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/SchemalessWsTest.java b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/SchemalessWsTest.java index 4c7a93981a..ed5444a4ec 100644 --- a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/SchemalessWsTest.java +++ b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/SchemalessWsTest.java @@ -26,7 +26,9 @@ public class SchemalessWsTest { conn.write(telnetDemo, SchemalessProtocolType.TELNET, SchemalessTimestampType.MILLI_SECONDS); conn.write(jsonDemo, SchemalessProtocolType.JSON, SchemalessTimestampType.SECONDS); } catch (SQLException ex) { - System.out.println("SQLException: " + ex.getMessage()); + // handle any errors, please refer to the JDBC specifications for detailed exceptions info + System.out.println("Error Code: " + ex.getErrorCode()); + System.out.println("Message: " + ex.getMessage()); } } diff --git a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/WSParameterBindingBasicDemo.java b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/WSParameterBindingBasicDemo.java index 72a6d0e887..9501d4adab 100644 --- a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/WSParameterBindingBasicDemo.java +++ b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/WSParameterBindingBasicDemo.java @@ -48,8 +48,9 @@ public class WSParameterBindingBasicDemo { } } } catch (SQLException ex) { - // handle any errors - System.out.println("SQLException: " + ex.getMessage()); + // handle any errors, please refer to the JDBC specifications for detailed exceptions info + System.out.println("Error Code: " + ex.getErrorCode()); + System.out.println("Message: " + ex.getMessage()); } } diff --git a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/WSParameterBindingDemo.java b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/WSParameterBindingDemo.java index 75261e93e5..a4d3bf2659 100644 --- a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/WSParameterBindingDemo.java +++ b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/WSParameterBindingDemo.java @@ -36,7 +36,9 @@ public class WSParameterBindingDemo { bindString(conn); } catch (SQLException ex) { - System.out.println("SQLException: " + ex.getMessage()); + // handle any errors, please refer to the JDBC specifications for detailed exceptions info + System.out.println("Error Code: " + ex.getErrorCode()); + System.out.println("Message: " + ex.getMessage()); } } diff --git a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/WSParameterBindingFullDemo.java b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/WSParameterBindingFullDemo.java index f9cf5cc992..5d63ce8bf3 100644 --- a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/WSParameterBindingFullDemo.java +++ b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/WSParameterBindingFullDemo.java @@ -38,7 +38,9 @@ public class WSParameterBindingFullDemo { bindString(conn); } catch (SQLException ex) { - System.out.println("SQLException: " + ex.getMessage()); + // handle any errors, please refer to the JDBC specifications for detailed exceptions info + System.out.println("Error Code: " + ex.getErrorCode()); + System.out.println("Message: " + ex.getMessage()); } } From 46591c88f394cd4066e2f2bc8553a9af80316e35 Mon Sep 17 00:00:00 2001 From: sheyanjie-qq <249478495@qq.com> Date: Wed, 31 Jul 2024 17:21:41 +0800 Subject: [PATCH 4/7] mod jdbc doc --- docs/zh/08-develop/02-sql.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/zh/08-develop/02-sql.md b/docs/zh/08-develop/02-sql.md index 4fef3c8659..eec1bcd70b 100644 --- a/docs/zh/08-develop/02-sql.md +++ b/docs/zh/08-develop/02-sql.md @@ -11,7 +11,6 @@ TDengine 对 SQL 语言提供了全面的支持，允许用户以熟悉的 SQL 下面介绍使用各语言连接器通过执行 SQL 完成建库、建表、写入数据和查询数据。 - ## 建库和表 以智能电表为例，展示如何使用连接器执行 SQL 来创建数据库和表。 @@ -70,7 +69,6 @@ NOW 为系统内部函数，默认为客户端所在计算机当前时间。 NOW - ## 查询数据 以智能电表为例，展示如何使用各语言连接器执行 SQL 来查询数据，并将获取到的结果打印出来。 @@ -100,7 +98,6 @@ NOW 为系统内部函数，默认为客户端所在计算机当前时间。 NOW - ## 执行带有 reqId 的 SQL reqId 可用于请求链路追踪，reqId 就像分布式系统中的 traceId 作用一样。一个请求可能需要经过多个服务或者模块才能完成。reqId 用于标识和关联这个请求的所有相关操作，以便于我们可以追踪和分析请求的完整路径。 From 31bdddde5706766250f7a3f4671938e7429fc6fb Mon Sep 17 00:00:00 2001 From: t_max <1172915550@qq.com> Date: Thu, 1 Aug 2024 13:55:01 +0800 Subject: [PATCH 5/7] docs: go and csharp api reference documentation --- docs/zh/14-reference/05-connector/20-go.mdx | 801 +++++++++++++++++- .../14-reference/05-connector/40-csharp.mdx | 738 ++++++++++++++++ 2 files changed, 1538 insertions(+), 1 deletion(-) diff --git a/docs/zh/14-reference/05-connector/20-go.mdx b/docs/zh/14-reference/05-connector/20-go.mdx index 97fc474e44..0c3dfa6681 100644 --- a/docs/zh/14-reference/05-connector/20-go.mdx +++ b/docs/zh/14-reference/05-connector/20-go.mdx @@ -396,4 +396,803 @@ TDengine Go 连接器支持订阅功能，应用 API 如下： ## API 参考 -全部 API 见 [driver-go 文档](https://pkg.go.dev/github.com/taosdata/driver-go/v3) +### database/sql 驱动 + +`driver-go` 实现了 Go 的 `database/sql/driver` 接口，可以直接使用 Go 的 `database/sql` 包。提供了三个驱动：`github.com/taosdata/driver-go/v3/taosSql` 、`github.com/taosdata/driver-go/v3/taosRestful` 和 `github.com/taosdata/driver-go/v3/taosWS` 分别对应 `原生连接`、`REST 连接` 和 `WebSocket 连接`。 + +#### DSN 规范 + +数据源名称具有通用格式，例如 [PEAR DB](http://pear.php.net/manual/en/package.database.db.intro-dsn.php)，但没有类型前缀（方括号表示可选）： + +``` text +[username[:password]@][protocol[(address)]]/[dbname][?param1=value1&...¶mN=valueN] +``` + +完整形式的 DSN： + +```text +username:password@protocol(address)/dbname?param=value +``` + +##### 原生连接 + +导入驱动： + +```go +import ( + "database/sql" + _ "github.com/taosdata/driver-go/v3/taosSql" +) +``` + +使用 `taosSql` 作为 `driverName` 并且使用一个正确的 DSN 作为 `dataSourceName` 如下： + +```go +var taosUri = "root:taosdata@tcp(localhost:6030)/" +taos, err := sql.Open("taosSql", taosUri) +``` + +支持的 DSN 参数： + +* `cfg` 指定 taos.cfg 目录 +* `cgoThread` 指定 cgo 同时执行的数量，默认为系统核数 +* `cgoAsyncHandlerPoolSize` 指定异步函数的 handle 大小，默认为 10000 + +##### Rest 连接 + +导入驱动： + +```go +import ( + "database/sql" + _ "github.com/taosdata/driver-go/v3/taosRestful" +) +``` + +使用 `taosRestful` 作为 `driverName` 并且使用一个正确的 DSN 作为 `dataSourceName` 如下： + +```go +var taosUri = "root:taosdata@http(localhost:6041)/" +taos, err := sql.Open("taosRestful", taosUri) +``` + +支持的 DSN 参数： + +* `disableCompression` 是否接受压缩数据，默认为 true 不接受压缩数据，如果传输数据使用 gzip 压缩设置为 false。 +* `readBufferSize` 读取数据的缓存区大小默认为 4K（4096），当查询结果数据量多时可以适当调大该值。 +* `token` 连接云服务时使用的 token。 +* `skipVerify` 是否跳过证书验证，默认为 false 不跳过证书验证，如果连接的是不安全的服务设置为 true。 + +##### WebSocket 连接 + +导入驱动： + +```go +import ( + "database/sql" + _ "github.com/taosdata/driver-go/v3/taosWS" +) +``` + +使用 `taosWS` 作为 `driverName` 并且使用一个正确的 DSN 作为 `dataSourceName` 如下： + +```go +var taosUri = "root:taosdata@ws(localhost:6041)/" +taos, err := sql.Open("taosWS", taosUri) +``` + +支持的 DSN 参数： + +* `enableCompression` 是否发送压缩数据，默认为 false 不发送压缩数据，如果传输数据使用压缩设置为 true。 +* `readTimeout` 读取数据的超时时间，默认为 5m。 +* `writeTimeout` 写入数据的超时时间，默认为 10s。 + +:::note + +- 与原生连接方式不同，REST 接口是无状态的。在使用 REST 连接时，需要在 SQL 中指定表、超级表的数据库名称。 +- 如果在 DSN 中指定了 dbname，那么，REST 连接会默认使用/rest/sql/dbname 作为 restful 请求的 url，在 SQL 中不需要指定 dbname。 + +::: + +### 连接功能 + +Go 驱动支持创建连接，返回支持 `sql/driver` 标准的 `Connector` 接口的对象，还提供了 `af` 包，扩充了一些无模式写入接口。 + +#### 标准接口 + +`database/sql` 包中创建连接的接口 + +- `func Open(driverName, dataSourceName string) (*DB, error)` + - **接口说明**：(`database/sql`)连接数据库 + - **参数说明**： + - `driverName`：驱动名称。 + - `dataSourceName`：连接参数 DSN。 + - **返回值**：连接对象，错误信息。 + +#### 扩展接口 + +`af` 包中创建连接的接口 + +- `func Open(host, user, pass, db string, port int) (*Connector, error)` + - **接口说明**：连接数据库。 + - **参数说明**： + - `host`：主机地址。 + - `user`：用户名。 + - `pass`：密码。 + - `db`：数据库名称。 + - `port`：端口号。 + - **返回值**：连接对象，错误信息。 + +#### 无模式写入 + +`af` 包中使用原生连接进行无模式写入的接口。 + +- `func (conn *Connector) InfluxDBInsertLines(lines []string, precision string) error` + - **接口说明**：无模式写入 influxDB 格式数据。 + - **参数说明**： + - `lines`：写入的数据。 + - `precision`：时间精度。 + - **返回值**：错误信息。 + +- `func (conn *Connector) OpenTSDBInsertJsonPayload(payload string) error` + - **接口说明**：无模式写入 OpenTSDB JSON 格式数据。 + - **参数说明**： + - `payload`：写入的数据。 + - **返回值**：错误信息。 + +- `func (conn *Connector) OpenTSDBInsertTelnetLines(lines []string) error` + - **接口说明**：无模式写入 OpenTSDB Telnet 格式数据。 + - **参数说明**： + - `lines`：写入的数据。 + - **返回值**：错误信息。 + +`ws/schemaless` 包中使用 WebSocket 无模式写入的接口 + +- `func (s *Schemaless) Insert(lines string, protocol int, precision string, ttl int, reqID int64) error` + - **接口说明**：无模式写入数据。 + - **参数说明**： + - `lines`：写入的数据。 + - `protocol`：写入的数据协议支持的协议 `InfluxDBLineProtocol = 1` `OpenTSDBTelnetLineProtocol = 2` `OpenTSDBJsonFormatProtocol = 3`。 + - `precision`：时间精度。 + - `ttl`：数据过期时间，0 表示不过期。 + - `reqID`：请求 ID。 + - **返回值**：错误信息。 + +### 执行 SQL + +Go 驱动提供了符合 `database/sql` 标准的接口，支持以下功能： + +1. **执行 SQL 语句**：执行静态 SQL 语句，并返回其生成的结果对象。 +2. **查询执行**：可以执行返回数据集的查询（`SELECT` 语句）。 +3. **更新执行**：可以执行影响行数的 SQL 语句，如 `INSERT`、`UPDATE`、`DELETE` 等。 +4. **获取结果**：可以获取查询执行后返回的结果集，并遍历查询返回的数据。 +5. **获取更新计数**：对于非查询 SQL 语句，可以获取执行后影响的行数。 +6. **关闭资源**：释放数据库资源。 + +#### 标准接口 + +- `func (db *DB) Close() error` + - **接口说明**：关闭连接。 + - **返回值**：错误信息。 + +- `func (db *DB) Exec(query string, args ...any) (Result, error)` + - **接口说明**：执行查询但不返回任何行。 + - **参数说明**： + - `query`：要执行的命令。 + - `args`：命令参数。 + - **返回值**：Result 对象（只有影响行数），错误信息。 + +- `func (db *DB) Query(query string, args ...any) (*Rows, error)` + - **接口说明**：执行查询并返回行的结果。 + - **参数说明**： + - `query`：要执行的命令。 + - `args`：命令参数。 + - **返回值**：Rows 对象，错误信息。 + +- `func (db *DB) QueryRow(query string, args ...any) *Row` + - **接口说明**：执行查询并返回一行结果。 + - **参数说明**： + - `query`：要执行的命令。 + - `args`：命令参数。 + - **返回值**：Row 对象。 + +#### 扩展接口 + +- `func (db *DB) ExecContext(ctx context.Context, query string, args ...any) (Result, error)` + - **接口说明**：执行查询但不返回任何行。 + - **参数说明**： + - `ctx`：上下文，使用 Value 传递请求 id 进行链路追踪，key 为 `taos_req_id` value 为 int64 类型值。 + - `query`：要执行的命令。 + - `args`：命令参数。 + - **返回值**：结果 Result 对象（只有影响行数），错误信息。 + +- `func (db *DB) QueryContext(ctx context.Context, query string, args ...any) (*Rows, error)` + - **接口说明**：执行查询并返回行结果。 + - **参数说明**： + - `ctx`：上下文，使用 Value 传递请求 id 进行链路追踪，key 为 `taos_req_id` value 为 int64 类型值。 + - `query`：要执行的命令。 + - `args`：命令参数。 + - **返回值**：结果集 Rows 对象，错误信息。 + +- `func (db *DB) QueryRowContext(ctx context.Context, query string, args ...any) *Row` + - **接口说明**：执行查询并返回一行结果，错误信息会在扫描 Row 时延迟返回。 + - **参数说明**： + - `ctx`：上下文，使用 Value 传递请求 id 进行链路追踪，key 为 `taos_req_id` value 为 int64 类型值。 + - `query`：要执行的命令。 + - `args`：命令参数。 + - **返回值**：单行结果 Row 对象。 + +### 结果获取 + +Go 驱动支持获取查询结果集，以及对应的结果集元数据，提供了用于读取结果集中元数据和数据的方法。 + +#### 结果集 + +通过 `Rows` 对象获取查询结果集，提供了以下方法： + +- `func (rs *Rows) Next() bool` + - **接口说明**：准备下一行数据。 + - **返回值**：是否有下一行数据。 + +- `func (rs *Rows) Columns() ([]string, error)` + - **接口说明**：返回列名。 + - **返回值**：列名，错误信息。 + +- `func (rs *Rows) Scan(dest ...any) error` + - **接口说明**：将当前行的列值复制到 dest 指向的值中。 + - **参数说明**： + - `dest`：目标值。 + - **返回值**：错误信息。 + +- `func (rs *Rows) Close() error` + - **接口说明**：关闭行。 + - **返回值**：错误信息。 + +- `func (r *Row) Scan(dest ...any) error` + - **接口说明**：将当前行的列值复制到 dest 指向的值中。 + - **参数说明**： + - `dest`：目标值。 + - **返回值**：错误信息。 + +通过 `Result` 对象获取更新结果集，提供了以下方法： + +- `func (dr driverResult) RowsAffected() (int64, error)` + - **接口说明**：返回受影响的行数。 + - **返回值**：受影响的行数，错误信息。 + +#### 结果集元数据 + +通过 `Rows` 对象获取查询结果集元数据，提供了以下方法： + +- `func (rs *Rows) ColumnTypes() ([]*ColumnType, error)` + - **接口说明**：返回列类型。 + - **返回值**：列类型，错误信息。 + +- `func (ci *ColumnType) Name() string` + - **接口说明**：返回列名。 + - **返回值**：列名。 + +- `func (ci *ColumnType) Length() (length int64, ok bool)` + - **接口说明**：返回列长度。 + - **返回值**：列长度，是否有长度。 + +- `func (ci *ColumnType) ScanType() reflect.Type` + - **接口说明**：返回列类型对应的 Go 类型。 + - **返回值**：列类型。 + +- `func (ci *ColumnType) DatabaseTypeName() string` + - **接口说明**：返回列类型数据库名称。 + - **返回值**：列类型名称。 + +### 参数绑定 + +Prepare 允许使用预编译的 SQL 语句，可以提高性能并提供参数化查询的能力，从而增加安全性。 + +#### 标准接口 + +使用 `sql/driver` 的 `Conn` 接口中的 `Prepare` 方法准备一个与此连接绑定的准备好的语句，返回 `Stmt` 对象，使用。 + +- `Prepare(query string) (Stmt, error)` + - **接口说明**：准备返回一个与此连接绑定的准备好的语句(statement)。 + - **参数说明**： + - `query`：要进行参数绑定的语句。 + - **返回值**：Stmt 对象，错误信息。 + +- `func (s *Stmt) Exec(args ...any) (Result, error)` + - **接口说明**：使用给定的参数执行准备好的语句并返回总结该语句效果的结果（只可以绑定列值，不支持绑定表名和 tag）。 + - **参数说明**： + - `args`：命令参数，Go 原始类型会自动转换数据库类型，类型不匹配可能会丢精度，建议使用与数据库相同的类型，时间类型使用 int64 或 `RFC3339Nano` 格式化后的字符串。 + - **返回值**：结果 Result 对象（只有影响行数），错误信息。 + +- `func (s *Stmt) Query(args ...any) (*Rows, error)` + - **接口说明**：使用给定的参数执行准备好的语句并返回行的结果。 + - **参数说明**： + - `args`：命令参数，Go 原始类型会自动转换数据库类型，类型不匹配可能会丢精度，建议使用与数据库相同的类型，时间类型使用 int64 或 `RFC3339Nano` 格式化后的字符串。 + - **返回值**：结果集 Rows 对象，错误信息。 + +- `func (s *Stmt) Close() error` + - **接口说明**：关闭语句。 + - **返回值**：错误信息。 + +#### 扩展接口 + +`af` 包中提供了使用原生连接进行参数绑定的更多接口 + +- `func (conn *Connector) Stmt() *Stmt` + - **接口说明**：返回一个与此连接绑定的 Stmt 对象。 + - **返回值**：Stmt 对象。 + +- `func (s *Stmt) Prepare(sql string) error` + - **接口说明**：准备一个 sql 。 + - **参数说明**： + - `sql`：要进行参数绑定的语句。 + - **返回值**：错误信息。 + +- `func (s *Stmt) NumParams() (int, error)` + - **接口说明**：返回参数数量。 + - **返回值**：参数数量，错误信息。 + +- `func (s *Stmt) SetTableNameWithTags(tableName string, tags *param.Param)` + - **接口说明**：设置表名和 tag。 + - **参数说明**： + - `tableName`：表名。 + - `tags`：tag。 + - **返回值**：错误信息。 + +- `func (s *Stmt) SetTableName(tableName string) error` + - **接口说明**：设置表名。 + - **参数说明**： + - `tableName`：表名。 + - **返回值**：错误信息。 + +- `func (s *Stmt) BindRow(row *param.Param) error` + - **接口说明**：绑定行。 + - **参数说明**： + - `row`：行数据。 + - **返回值**：错误信息。 + +- `func (s *Stmt) GetAffectedRows() int` + - **接口说明**：获取受影响的行数。 + - **返回值**：受影响的行数。 + +- `func (s *Stmt) AddBatch() error` + - **接口说明**：添加批处理。 + - **返回值**：错误信息。 + +- `func (s *Stmt) Execute() error` + - **接口说明**：执行批处理。 + - **返回值**：错误信息。 + +- `func (s *Stmt) UseResult() (driver.Rows, error)` + - **接口说明**：使用结果。 + - **返回值**：结果集 Rows 对象，错误信息。 + +- `func (s *Stmt) Close() error` + - **接口说明**：关闭语句。 + - **返回值**：错误信息。 + +`ws/stmt` 包提供了通过 WebSocket 进行参数绑定的接口 + +- `func (c *Connector) Init() (*Stmt, error)` + - **接口说明**：初始化。 + - **返回值**：Stmt 对象，错误信息。 + +- `func (s *Stmt) Prepare(sql string) error` + - **接口说明**：准备一个 sql 。 + - **参数说明**： + - `sql`：要进行参数绑定的语句。 + - **返回值**：错误信息。 + +- `func (s *Stmt) SetTableName(name string) error` + - **接口说明**：设置表名。 + - **参数说明**： + - `name`：表名。 + - **返回值**：错误信息。 + +- `func (s *Stmt) SetTags(tags *param.Param, bindType *param.ColumnType)` + - **接口说明**：设置 tag。 + - **参数说明**： + - `tags`：tag。 + - `bindType`：类型信息。 + - **返回值**：错误信息。 + +- `func (s *Stmt) BindParam(params []*param.Param, bindType *param.ColumnType) error` + - **接口说明**：绑定参数。 + - **参数说明**： + - `params`：参数。 + - `bindType`：类型信息。 + - **返回值**：错误信息。 + +- `func (s *Stmt) AddBatch() error` + - **接口说明**：添加批处理。 + - **返回值**：错误信息。 + +- `func (s *Stmt) Exec() error` + - **接口说明**：执行批处理。 + - **返回值**：错误信息。 + +- `func (s *Stmt) GetAffectedRows() int` + - **接口说明**：获取受影响的行数。 + - **返回值**：受影响的行数。 + +- `func (s *Stmt) UseResult() (*Rows, error)` + - **接口说明**：使用结果。 + - **返回值**：Rows 对象，错误信息。 + +- `func (s *Stmt) Close() error` + - **接口说明**：关闭语句。 + - **返回值**：错误信息。 + +Rows 行结果参考 `sql/driver` 包中的 `Rows` 接口，提供以下接口 + +- `func (rs *Rows) Columns() []string` + - **接口说明**：返回列名。 + - **返回值**：列名。 + +- `func (rs *Rows) ColumnTypeDatabaseTypeName(i int) string` + - **接口说明**：返回列类型数据库名称。 + - **参数说明**： + - `i`：列索引。 + - **返回值**：列类型名称。 + +- `func (rs *Rows) ColumnTypeLength(i int) (length int64, ok bool)` + - **接口说明**：返回列长度。 + - **参数说明**： + - `i`：列索引。 + - **返回值**：列长度，是否有长度。 + +- `func (rs *Rows) ColumnTypeScanType(i int) reflect.Type` + - **接口说明**：返回列类型对应的 Go 类型。 + - **参数说明**： + - `i`：列索引。 + - **返回值**：列类型。 + +- `func (rs *Rows) Next(dest []driver.Value) error` + - **接口说明**：准备下一行数据，并赋值给目标。 + - **参数说明**： + - `dest`：目标值。 + - **返回值**：错误信息。 + +- `func (rs *Rows) Close() error` + - **接口说明**：关闭行。 + - **返回值**：错误信息。 + + +`common/param` 包中提供了参数绑定数据结构 + +以下是按照偏移设置参数的接口： + +- `func NewParam(size int) *Param` + - **接口说明**：创建一个参数绑定数据结构。 + - **参数说明**： + - `size`：参数数量。 + - **返回值**：Param 对象。 + +- `func (p *Param) SetBool(offset int, value bool)` + - **接口说明**：设置布尔值。 + - **参数说明**： + - `offset`：偏移量(列或标签)。 + - `value`：布尔值。 + +- `func (p *Param) SetNull(offset int)` + - **接口说明**：设置空值。 + - **参数说明**： + - `offset`：偏移量(列或标签)。 + +- `func (p *Param) SetTinyint(offset int, value int)` + - **接口说明**：设置 Tinyint 值。 + - **参数说明**： + - `offset`：偏移量(列或标签)。 + - `value`：Tinyint 值。 + +- `func (p *Param) SetSmallint(offset int, value int)` + - **接口说明**：设置 Smallint 值。 + - **参数说明**： + - `offset`：偏移量(列或标签)。 + - `value`：Smallint 值。 + +- `func (p *Param) SetInt(offset int, value int)` + - **接口说明**：设置 Int 值。 + - **参数说明**： + - `offset`：偏移量(列或标签)。 + - `value`：Int 值。 + +- `func (p *Param) SetBigint(offset int, value int)` + - **接口说明**：设置 Bigint 值。 + - **参数说明**： + - `offset`：偏移量(列或标签)。 + - `value`：Bigint 值。 + +- `func (p *Param) SetUTinyint(offset int, value uint)` + - **接口说明**：设置 UTinyint 值。 + - **参数说明**： + - `offset`：偏移量(列或标签)。 + - `value`：UTinyint 值。 + +- `func (p *Param) SetUSmallint(offset int, value uint)` + - **接口说明**：设置 USmallint 值。 + - **参数说明**： + - `offset`：偏移量(列或标签)。 + - `value`：USmallint 值。 + +- `func (p *Param) SetUInt(offset int, value uint)` + - **接口说明**：设置 UInt 值。 + - **参数说明**： + - `offset`：偏移量(列或标签)。 + - `value`：UInt 值。 + +- `func (p *Param) SetUBigint(offset int, value uint)` + - **接口说明**：设置 UBigint 值。 + - **参数说明**： + - `offset`：偏移量(列或标签)。 + - `value`：UBigint 值。 + +- `func (p *Param) SetFloat(offset int, value float32)` + - **接口说明**：设置 Float 值。 + - **参数说明**： + - `offset`：偏移量(列或标签)。 + - `value`：Float 值。 + +- `func (p *Param) SetDouble(offset int, value float64)` + - **接口说明**：设置 Double 值。 + - **参数说明**： + - `offset`：偏移量(列或标签)。 + - `value`：Double 值。 + +- `func (p *Param) SetBinary(offset int, value []byte)` + - **接口说明**：设置 Binary 值。 + - **参数说明**： + - `offset`：偏移量(列或标签)。 + - `value`：Binary 值。 + +- `func (p *Param) SetVarBinary(offset int, value []byte)` + - **接口说明**：设置 VarBinary 值。 + - **参数说明**： + - `offset`：偏移量(列或标签)。 + - `value`：VarBinary 值。 + +- `func (p *Param) SetNchar(offset int, value string)` + - **接口说明**：设置 Nchar 值。 + - **参数说明**： + - `offset`：偏移量(列或标签)。 + - `value`：Nchar 值。 + +- `func (p *Param) SetTimestamp(offset int, value time.Time, precision int)` + - **接口说明**：设置 Timestamp 值。 + - **参数说明**： + - `offset`：偏移量(列或标签)。 + - `value`：Timestamp 值。 + - `precision`：时间精度。 + +- `func (p *Param) SetJson(offset int, value []byte)` + - **接口说明**：设置 Json 值。 + - **参数说明**： + - `offset`：偏移量(列或标签)。 + - `value`：Json 值。 + +- `func (p *Param) SetGeometry(offset int, value []byte)` + - **接口说明**：设置 Geometry 值。 + - **参数说明**： + - `offset`：偏移量(列或标签)。 + - `value`：Geometry 值。 + +以下是链式调用设置参数的接口： + +- `func (p *Param) AddBool(value bool) *Param` + - **接口说明**：添加布尔值。 + - **参数说明**： + - `value`：布尔值。 + - **返回值**：Param 对象。 + +其他类型与布尔值类似，具体接口如下： + +- AddNull +- AddTinyint +- AddSmallint +- AddInt +- AddBigint +- AddUTinyint +- AddUSmallint +- AddUInt +- AddUBigint +- AddFloat +- AddDouble +- AddBinary +- AddVarBinary +- AddNchar +- AddTimestamp +- AddJson +- AddGeometry + +以下是设置列类型信息的接口： + +- `func NewColumnType(size int) *ColumnType` + - **接口说明**：创建一个列类型信息数据结构。 + - **参数说明**： + - `size`：列数量。 + - **返回值**：ColumnType 对象。 + +- `func (c *ColumnType) AddBool() *ColumnType` + - **接口说明**：添加布尔类型。 + - **返回值**：ColumnType 对象。 + +其他类型与布尔类型类似，具体接口如下： + +- AddTinyint +- AddSmallint +- AddInt +- AddBigint +- AddUTinyint +- AddUSmallint +- AddUInt +- AddUBigint +- AddFloat +- AddDouble +- AddBinary +- AddVarBinary +- AddNchar +- AddTimestamp +- AddJson +- AddGeometry + + +### 数据订阅 + +Go 驱动支持数据订阅功能，提供了基于原生连接和 WebSocket 连接的数据订阅接口。原生实现在 `af/tmq` 包中，WebSocket 实现在 `ws/tmq` 包中。 + +#### 消费者 + +- `func NewConsumer(conf *tmq.ConfigMap) (*Consumer, error)` + - **接口说明**：创建一个消费者。 + - **参数说明**： + - `conf`：配置信息。 + - **返回值**：Consumer 对象，错误信息。 + +配置信息定义为： + +```go +type ConfigValue interface{} +type ConfigMap map[string]ConfigValue +``` +创建消费者支持属性列表： + +- `ws.url`：WebSocket 连接地址。 +- `ws.message.channelLen`：WebSocket 消息通道缓存长度，默认 0。 +- `ws.message.timeout`：WebSocket 消息超时时间，默认 5m。 +- `ws.message.writeWait`：WebSocket 写入消息超时时间，默认 10s。 +- `ws.message.enableCompression`：WebSocket 是否启用压缩，默认 false。 +- `ws.autoReconnect`：WebSocket 是否自动重连，默认 false。 +- `ws.reconnectIntervalMs`：WebSocket 重连间隔时间毫秒，默认 2000。 +- `ws.reconnectRetryCount`：WebSocket 重连重试次数，默认 3。 + +其他参数请参考：[Consumer 参数列表](../../develop/tmq/#数据订阅相关参数)， 注意TDengine服务端自 3.2.0.0 版本开始消息订阅中的 auto.offset.reset 默认值发生变化。 + +- `func (c *Consumer) Subscribe(topic string, rebalanceCb RebalanceCb) error` + - **接口说明**：订阅主题。 + - **参数说明**： + - `topic`：主题。 + - `rebalanceCb`：平衡回调（未使用）。 + - **返回值**：错误信息。 + +- `func (c *Consumer) SubscribeTopics(topics []string, rebalanceCb RebalanceCb) error` + - **接口说明**：订阅主题列表。 + - **参数说明**： + - `topics`：主题列表。 + - `rebalanceCb`：平衡回调（未使用）。 + - **返回值**：错误信息。 + +- `func (c *Consumer) Unsubscribe() error` + - **接口说明**：取消订阅。 + - **返回值**：错误信息。 + +- `func (c *Consumer) Poll(timeoutMs int) tmq.Event` + - **接口说明**：轮询事件。 + - **参数说明**： + - `timeoutMs`：超时时间。 + - **返回值**：事件。 + +- `func (c *Consumer) Commit() ([]tmq.TopicPartition, error)` + - **接口说明**：提交偏移量。 + - **返回值**：TopicPartition 列表，错误信息。 + +- `func (c *Consumer) Assignment() (partitions []tmq.TopicPartition, err error)` + - **接口说明**：获取分配信息。 + - **返回值**：TopicPartition 列表，错误信息。 + +- `func (c *Consumer) Seek(partition tmq.TopicPartition, ignoredTimeoutMs int) error` + - **接口说明**：跳转到偏移量。 + - **参数说明**： + - `partition`：分区和偏移信息。 + - `ignoredTimeoutMs`：超时时间（未使用）。 + - **返回值**：错误信息。 + +- `func (c *Consumer) Committed(partitions []tmq.TopicPartition, timeoutMs int) (offsets []tmq.TopicPartition, err error)` + - **接口说明**：获取提交的偏移量。 + - **参数说明**： + - `partitions`：分区列表。 + - `timeoutMs`：超时时间。 + - **返回值**：TopicPartition 列表，错误信息。 + +- `func (c *Consumer) CommitOffsets(offsets []tmq.TopicPartition) ([]tmq.TopicPartition, error) ` + - **接口说明**：提交偏移量。 + - **参数说明**： + - `offsets`：偏移量列表。 + - **返回值**：TopicPartition 列表，错误信息。 + +- `func (c *Consumer) Position(partitions []tmq.TopicPartition) (offsets []tmq.TopicPartition, err error)` + - **接口说明**：获取当前偏移量。 + - **参数说明**： + - `partitions`：分区列表。 + - **返回值**：TopicPartition 列表，错误信息。 + +- `func (c *Consumer) Close() error` + - **接口说明**：关闭消费者。 + - **返回值**：错误信息。 + +#### 消费记录 + +当 `Poll` 返回 `tmq.Event` 事件时，可以通过判断 `tmq.Event` 的类型获取消费记录或错误信息。当类型为 `*tmq.DataMessage` 时，可以获取消费记录。 + +- `func (m *DataMessage) Topic() string` + - **接口说明**：获取主题。 + - **返回值**：主题。 + +- `func (m *DataMessage) DBName() string` + - **接口说明**：获取数据库名称。 + - **返回值**：数据库名称。 + +- `func (m *DataMessage) Offset() Offset` + - **接口说明**：获取偏移量。 + - **返回值**：偏移量。 + +- `func (m *DataMessage) Value() interface{}` + - **接口说明**：获取值，具体值为 `[]*tmq.data`。 + - **返回值**：消费到的值。 + +tmq.data 结构如下： + +```go +type Data struct { + TableName string + Data [][]driver.Value +} +``` + +- TableName 为表名 +- Data 为数据，每个元素为一行数据，每行数据为一个数组，数组元素为列值。 + +当 Poll 返回类型为 `tmq.Error` 时，可以使用 `func (e Error) Error() string` 获取错误信息。 + +#### 分区信息 + +当消费到数据类型为 `*tmq.DataMessage` 时，可以从 `TopicPartition` 属性中获取分区信息。 + +```go +type TopicPartition struct { + Topic *string + Partition int32 + Offset Offset + Metadata *string + Error error +} +``` + +- `Topic`：主题。 +- `Partition`：分区。 +- `Offset`：偏移量。 +- `Metadata`：元数据（未使用）。 +- `Error`：错误信息。 + +可以使用 `func (p TopicPartition) String() string` 获取分区信息。 + +#### 偏移量元数据 + +从 `TopicPartition` 中获取的偏移量信息，可以通过 `Offset` 属性获取偏移量元数据。当偏移量为 `-2147467247` 时表示未设置偏移量。 + +#### 反序列化 + +当消费到数据类型为 `*tmq.DataMessage` 时，可以使用 `func (m *DataMessage) Value() interface{}` 获取数据，数据类型为 `[]*tmq.data` 。 + +## 附录 + +[driver-go 文档](https://pkg.go.dev/github.com/taosdata/driver-go/v3) diff --git a/docs/zh/14-reference/05-connector/40-csharp.mdx b/docs/zh/14-reference/05-connector/40-csharp.mdx index a175e6bf05..ad316d581c 100644 --- a/docs/zh/14-reference/05-connector/40-csharp.mdx +++ b/docs/zh/14-reference/05-connector/40-csharp.mdx @@ -1207,3 +1207,741 @@ namespace WSADO ### 更多示例程序 [示例程序](https://github.com/taosdata/taos-connector-dotnet/tree/3.0/examples) + +## API 参考 + +### ADO.NET 驱动 + +`TDengine.Data.Client` 接口实现了 ADO.NET 驱动，支持连接 TDengine 数据库，进行数据操作。 + +#### 参数规范 + +ConnectionStringBuilder 使用 key-value 对方式设置连接参数，key 为参数名，value 为参数值，不同参数之间使用分号 `;` 分割。 + +例如： + +```csharp +"protocol=WebSocket;host=127.0.0.1;port=6041;useSSL=false" +``` + +##### 原生连接 + +例如：`"host=127.0.0.1;port=6030;username=root;password=taosdata;protocol=Native;db=test"` + +支持的参数如下： + +- `host`：TDengine 运行实例的地址。 +- `port`：TDengine 运行实例的端口。 +- `username`：连接的用户名。 +- `password`：连接的密码。 +- `protocol`：连接的协议，可选值为 Native 或 WebSocket，默认为 Native。 +- `db`：连接的数据库。 +- `timezone`：时区，默认为本地时区。 + +##### WebSocket 连接 + +例如：`"protocol=WebSocket;host=127.0.0.1;port=6041;useSSL=false;enableCompression=true;autoReconnect=true;reconnectIntervalMs=10;reconnectRetryCount=5"` + +支持的参数如下： + +- `host`：TDengine 运行实例的地址。 +- `port`：TDengine 运行实例的端口。 +- `username`：连接的用户名。 +- `password`：连接的密码。 +- `protocol`：连接的协议，可选值为 Native 或 WebSocket，默认为 Native。 +- `db`：连接的数据库。 +- `timezone`：时区，默认为本地时区。 +- `connTimeout`：连接超时时间，默认为 1 分钟。 +- `readTimeout`：读取超时时间，默认为 5 分钟。 +- `writeTimeout`：发送超时时间，默认为 10 秒。 +- `token`：连接 TDengine cloud 的 token。 +- `useSSL`：是否使用 SSL 连接，默认为 false。 +- `enableCompression`：是否启用 WebSocket 压缩，默认为 false。 +- `autoReconnect`：是否自动重连，默认为 false。 +- `reconnectRetryCount`：重连次数，默认为 3。 +- `reconnectIntervalMs`：重连间隔毫秒时间，默认为 2000。 + +#### 接口说明 + +`ConnectionStringBuilder` 类提供了连接配置字符串的解析功能。 + +- `public ConnectionStringBuilder(string connectionString)` + - **接口说明**：ConnectionStringBuilder 构造函数。 + - **参数说明**： + - `connectionString`：连接配置字符串。 + +### 连接功能 + +C# 驱动支持创建 ADO.NET 连接，返回支持 ADO.NET 标准的 `DbConnection` 接口的对象，还提供了 `ITDengineClient` 接口，扩充了一些无模式写入接口。 + +#### 标准接口 + +ADO.NET 连接支持的标准接口如下： + +- `public TDengineConnection(string connectionString)` + - **接口说明**：TDengineConnection 构造函数。 + - **参数说明**： + - `connectionString`：连接配置字符串。 + - **异常**：格式错误抛出 `ArgumentException` 异常。 + +- `public void ChangeDatabase(string databaseName)` + - **接口说明**：切换数据库。 + - **参数说明**： + - `databaseName`：数据库名。 + - **异常**：执行失败抛出 `TDengineError` 异常。 + +- `public void Close()` + - **接口说明**：关闭连接。 + +- `public void Open()` + - **接口说明**：打开连接。 + - **异常**：打开失败抛出 `TDengineError` 异常，WebSocket 连接可能存在网络异常须注意处理。 + +- `public string ServerVersion` + - **接口说明**：返回服务器版本。 + - **返回值**：服务器版本字符串。 + - **异常**：执行失败抛出 `TDengineError` 异常。 + +- `public string DataSource` + - **接口说明**：返回数据源。 + - **返回值**：创建连接 host 配置。 + +- `public string Database` + - **接口说明**：返回连接数据库。 + - **返回值**：创建连接 db 配置。 + +- `public TDengineCommand(TDengineConnection connection)` + - **接口说明**：TDengineCommand 构造函数。 + - **参数说明**： + - `connection`：TDengineConnection 对象。 + - **异常**：执行失败抛出 `TDengineError` 异常。 + +- `public void Prepare()` + - **接口说明**：检查连接和命令文本，并准备命令执行。 + - **异常**：未执行 open 或未设置 CommandText 抛出 `InvalidOperationException` 异常。 + +- `public string CommandText` + - **接口说明**：获取或设置命令文本。 + - **返回值**：命令文本。 + +- `public new virtual TDengineParameterCollection Parameters` + - **接口说明**：获取参数集合。 + - **返回值**：TDengineParameterCollection 对象。 + + +#### 无模式写入 + +- `public static ITDengineClient Open(ConnectionStringBuilder builder)` + - **接口说明**：打开连接。 + - **参数说明**： + - `builder`：连接配置。 + - **返回值**：ITDengineClient 接口。 + - **异常**：打开失败抛出 `TDengineError` 异常，WebSocket 连接可能存在网络异常须注意处理。 + +- `void SchemalessInsert(string[] lines, TDengineSchemalessProtocol protocol,TDengineSchemalessPrecision precision, int ttl, long reqId)` + - **接口说明**：无模式写入。 + - **参数说明**： + - `lines`：数据行数组。 + - `protocol`：数据协议，支持协议：`TSDB_SML_LINE_PROTOCOL = 1` `TSDB_SML_TELNET_PROTOCOL = 2` `TSDB_SML_JSON_PROTOCOL = 3`。 + - `precision`：时间精度，支持配置：`TSDB_SML_TIMESTAMP_NOT_CONFIGURED = 0` `TSDB_SML_TIMESTAMP_HOURS = 1` `TSDB_SML_TIMESTAMP_MINUTES = 2` `TSDB_SML_TIMESTAMP_SECONDS = 3` `TSDB_SML_TIMESTAMP_MILLI_SECONDS = 4` `TSDB_SML_TIMESTAMP_MICRO_SECONDS = 5` `TSDB_SML_TIMESTAMP_NANO_SECONDS = 6`。 + - `ttl`：数据过期时间，0表示不配置。 + - `reqId`：请求 ID。 + - **异常**：执行失败抛出 `TDengineError` 异常。 + +### 执行 SQL + +C# 驱动提供了符合 ADO.NET 标准的 `DbCommand` 接口，支持以下功能： + +1. **执行 SQL 语句**：执行静态 SQL 语句，并返回其生成的结果对象。 +2. **查询执行**：可以执行返回数据集的查询（`SELECT` 语句）。 +3. **更新执行**：可以执行影响行数的 SQL 语句，如 `INSERT`、`UPDATE`、`DELETE` 等。 +4. **获取结果**：可以获取查询执行后返回的结果集（`ResultSet` 对象），并遍历查询返回的数据。 +5. **获取更新计数**：对于非查询 SQL 语句，可以获取执行后影响的行数。 +6. **关闭资源**：提供了关闭的方法，以释放数据库资源。 + +另外 C# 驱动还提供了用于请求链路跟踪的扩展接口。 + +#### 标准接口 + +- `public int ExecuteNonQuery()` + - **接口说明**：执行 SQL 语句，返回受影响的行数。 + - **返回值**：受影响的行数。 + - **异常**：执行失败抛出 `TDengineError` 异常。 + +- `public object ExecuteScalar()` + - **接口说明**：执行查询，并返回查询结果的第一行第一列。 + - **返回值**：查询结果的第一行第一列。 + - **异常**：执行失败抛出 `TDengineError` 异常。 + +- `public DbDataReader ExecuteReader()` + - **接口说明**：执行查询，并返回查询结果的数据读取器。 + - **返回值**：查询结果的数据读取器。 + - **异常**：执行失败抛出 `TDengineError` 异常。 + +- `public void Dispose();` + - **接口说明**：释放资源。 + +#### 扩展接口 + +扩展接口主要用于请求链路跟踪。 + +- `IRows Query(string query, long reqId)` + - **接口说明**：执行查询，返回查询结果。 + - **参数说明**： + - `query`：查询语句。 + - `reqId`：请求 ID。 + - **返回值**：查询结果。 + - **异常**：执行失败抛出 `TDengineError` 异常。 + +- `long Exec(string query, long reqId)` + - **接口说明**：执行 SQL 语句。 + - **参数说明**： + - `query`：SQL 语句。 + - `reqId`：请求 ID。 + - **返回值**：受影响的行数。 + - **异常**：执行失败抛出 `TDengineError` 异常。 + + +### 结果获取 + +C# 驱动提供了符合 ADO.NET 标准的 `DbDataReader` 接口，提供了用于读取结果集中元数据和数据的方法。 + +#### 结果集 + +`DbDataReader` 接口提供了以下方法获取结果集： + +- `public bool GetBoolean(int ordinal)` + - **接口说明**：获取指定列的布尔值。 + - **参数说明**： + - `ordinal`：列索引。 + - **返回值**：布尔值。 + - **异常**：类型不对应抛出 `InvalidCastException` 异常。 + +- `public byte GetByte(int ordinal)` + - **接口说明**：获取指定列的字节值。 + - **参数说明**： + - `ordinal`：列索引。 + - **返回值**：字节值。 + - **异常**：类型不对应抛出 `InvalidCastException` 异常。 + +- `public long GetBytes(int ordinal, long dataOffset, byte[] buffer, int bufferOffset, int length)` + - **接口说明**：获取指定列的字节值。 + - **参数说明**： + - `ordinal`：列索引。 + - `dataOffset`：数据偏移量。 + - `buffer`：缓冲区。 + - `bufferOffset`：缓冲区偏移量。 + - `length`：长度。 + - **返回值**：字节值。 + - **异常**：类型不对应抛出 `InvalidCastException` 异常。 + +- `public char GetChar(int ordinal)` + - **接口说明**：获取指定列的字符值。 + - **参数说明**： + - `ordinal`：列索引。 + - **返回值**：字符值。 + - **异常**：类型不对应抛出 `InvalidCastException` 异常。 + +- `public long GetChars(int ordinal, long dataOffset, char[] buffer, int bufferOffset, int length)` + - **接口说明**：获取指定列的字符值。 + - **参数说明**： + - `ordinal`：列索引。 + - `dataOffset`：数据偏移量。 + - `buffer`：缓冲区。 + - `bufferOffset`：缓冲区偏移量。 + - `length`：长度。 + - **返回值**：字符值。 + - **异常**：类型不对应抛出 `InvalidCastException` 异常。 + +- `public DateTime GetDateTime(int ordinal)` + - **接口说明**：获取指定列的日期时间值。 + - **参数说明**： + - `ordinal`：列索引。 + - **返回值**：日期时间值。 + - **异常**：类型不对应抛出 `InvalidCastException` 异常。 + +- `public double GetDouble(int ordinal)` + - **接口说明**：获取指定列的双精度浮点数值。 + - **参数说明**： + - `ordinal`：列索引。 + - **返回值**：双精度浮点数值。 + - **异常**：类型不对应抛出 `InvalidCastException` 异常。 + +- `public float GetFloat(int ordinal)` + - **接口说明**：获取指定列的单精度浮点数值。 + - **参数说明**： + - `ordinal`：列索引。 + - **返回值**：单精度浮点数值。 + - **异常**：类型不对应抛出 `InvalidCastException` 异常。 + +- `public short GetInt16(int ordinal)` + - **接口说明**：获取指定列的 16 位整数值。 + - **参数说明**： + - `ordinal`：列索引。 + - **返回值**：16 位整数值。 + - **异常**：类型不对应抛出 `InvalidCastException` 异常。 + +- `public int GetInt32(int ordinal)` + - **接口说明**：获取指定列的 32 位整数值。 + - **参数说明**： + - `ordinal`：列索引。 + - **返回值**：32 位整数值。 + - **异常**：类型不对应抛出 `InvalidCastException` 异常。 + +- `public long GetInt64(int ordinal)` + - **接口说明**：获取指定列的 64 位整数值。 + - **参数说明**： + - `ordinal`：列索引。 + - **返回值**：64 位整数值。 + - **异常**：类型不对应抛出 `InvalidCastException` 异常。 + +- `public string GetString(int ordinal)` + - **接口说明**：获取指定列的字符串值。 + - **参数说明**： + - `ordinal`：列索引。 + - **返回值**：字符串值。 + - **异常**：类型不对应抛出 `InvalidCastException` 异常。 + +- `public object GetValue(int ordinal)` + - **接口说明**：获取指定列的值。 + - **参数说明**： + - `ordinal`：列索引。 + - **返回值**： 结果对象。 + + +- `public int GetValues(object[] values)` + - **接口说明**：获取所有列的值。 + - **参数说明**： + - `values`：值数组。 + - **返回值**：值数量。 + +- `public bool IsDBNull(int ordinal)` + - **接口说明**：判断指定列是否为 NULL。 + - **参数说明**： + - `ordinal`：列索引。 + - **返回值**：是否为 NULL。 + +- `public int RecordsAffected` + - **接口说明**：获取受影响的行数。 + - **返回值**：受影响的行数。 + +- `public bool HasRows` + - **接口说明**：结果是否有行数据。 + - **返回值**：结果是否有行数据。 + +- `public bool Read()` + - **接口说明**：读取下一行。 + - **返回值**：是否读取成功。 + +- `public IEnumerator GetEnumerator()` + - **接口说明**：获取枚举器。 + - **返回值**：枚举器。 + +- `public void Close()` + - **接口说明**：关闭结果集。 + +#### 结果集元数据 + +`DbDataReader` 接口提供了以下方法获取结果集元数据： + +- `public DataTable GetSchemaTable()` + - **接口说明**：获取结果集元数据。 + - **返回值**：结果集元数据。 + +- `public string GetDataTypeName(int ordinal)` + - **接口说明**：获取指定列的数据类型名称。 + - **参数说明**： + - `ordinal`：列索引。 + - **返回值**：数据类型名称。 + +- ` public Type GetFieldType(int ordinal)` + - **接口说明**：获取指定列的数据类型。 + - **参数说明**： + - `ordinal`：列索引。 + - **返回值**：数据类型。 + +- `public string GetName(int ordinal)` + - **接口说明**：获取指定列的名称。 + - **参数说明**： + - `ordinal`：列索引。 + - **返回值**：列名称。 + +- ` public int GetFieldSize(int ordinal)` + - **接口说明**：获取指定列的大小。 + - **参数说明**： + - `ordinal`：列索引。 + - **返回值**：列大小。 + +- `public int GetOrdinal(string name)` + - **接口说明**：获取指定列的索引。 + - **参数说明**： + - `name`：列名称。 + - **返回值**：列索引。 + +- `public int FieldCount` + - **接口说明**：获取列数。 + - **返回值**：列数。 + +### 参数绑定 + +`TDengineCommand` 类支持参数绑定。 + +#### 标准接口 + +`TDengineCommand` 类继承了 `DbCommand` 接口，支持以下功能： + +- `public string CommandText` + - **接口说明**：获取或设置命令文本，支持参数绑定。 + - **返回值**：命令文本。 + +- `public new virtual TDengineParameterCollection Parameters` + - **接口说明**：获取参数集合。 + - **返回值**：`TDengineParameterCollection` 对象。 + +#### 参数元数据 + +`TDengineParameterCollection` 继承了 `DbParameterCollection` 接口，支持以下功能： + +- `public int Add(object value)` + - **接口说明**：添加参数。 + - **参数说明**： + - `value`：参数值。 + - **返回值**：参数索引。 + +- `public void Clear()` + - **接口说明**：清空参数。 + +- `public bool Contains(object value)` + - **接口说明**：是否包含参数。 + - **参数说明**： + - `value`：参数值。 + - **返回值**：是否包含参数。 + +- `public int IndexOf(object value)` + - **接口说明**：获取参数索引。 + - **参数说明**： + - `value`：参数值。 + - **返回值**：参数索引。 + +- `public void Insert(int index, object value)` + - **接口说明**：插入参数。 + - **参数说明**： + - `index`：索引。 + - `value`：参数值。 + +- `public void Remove(object value)` + - **接口说明**：移除参数。 + - **参数说明**： + - `value`：参数值。 + +- `public void RemoveAt(int index)` + - **接口说明**：移除参数。 + - **参数说明**： + - `index`：索引。 + +- `public void RemoveAt(string parameterName)` + - **接口说明**：移除参数。 + - **参数说明**： + - `parameterName`：参数名。 + +- `public int Count` + - **接口说明**：获取参数数量。 + - **返回值**：参数数量。 + +- `public int IndexOf(string parameterName)` + - **接口说明**：获取参数索引。 + - **参数说明**： + - `parameterName`：参数名。 + - **返回值**：参数索引。 + +- `public bool Contains(string value)` + - **接口说明**：是否包含参数。 + - **参数说明**： + - `value`：参数名。 + - **返回值**：是否包含参数。 + +- `public void CopyTo(Array array, int index)` + - **接口说明**：复制参数。 + - **参数说明**： + - `array`：目标数组。 + - `index`：索引。 + +- `public IEnumerator GetEnumerator()` + - **接口说明**：获取枚举器。 + - **返回值**：枚举器。 + +- `public void AddRange(Array values)` + - **接口说明**：添加参数。 + - **参数说明**： + - `values`：参数数组。 + +`TDengineParameter` 继承了 `DbParameter` 接口，支持以下功能： + +- `public TDengineParameter(string name, object value)` + - **接口说明**：TDengineParameter 构造函数。 + - **参数说明**： + - `name`：参数名，需要以 @ 开头，如 @0、@1、@2 等。 + - `value`：参数值，需要 C# 列类型与 TDengine 列类型一一对应。 + +- `public string ParameterName` + - **接口说明**：获取或设置参数名。 + - **返回值**：参数名。 + +- `public object Value` + - **接口说明**：获取或设置参数值。 + - **返回值**：参数值。 + +#### 扩展接口 + +`ITDengineClient` 接口提供了扩展的参数绑定接口。 + +- `IStmt StmtInit(long reqId)` + - **接口说明**：初始化 statement 对象。 + - **参数说明**： + - `reqId`：请求 ID。 + - **返回值**：实现 IStmt 接口的对象。 + - **异常**：执行失败抛出 `TDengineError` 异常。 + +`IStmt` 接口提供了扩展的参数绑定接口。 + +- `void Prepare(string query)` + - **接口说明**：准备 statement。 + - **参数说明**： + - `query`：查询语句。 + - **异常**：执行失败抛出 `TDengineError` 异常。 + +- `bool IsInsert()` + - **接口说明**：判断是否为插入语句。 + - **返回值**：是否为插入语句。 + - **异常**：执行失败抛出 `TDengineError` 异常。 + +- `void SetTableName(string tableName)` + - **接口说明**：设置表名。 + - **参数说明**： + - `tableName`：表名。 + - **异常**：执行失败抛出 `TDengineError` 异常。 + +- `void SetTags(object[] tags)` + - **接口说明**：设置标签。 + - **参数说明**： + - `tags`：标签数组。 + - **异常**：执行失败抛出 `TDengineError` 异常。 + +- `TaosFieldE[] GetTagFields()` + - **接口说明**：获取标签属性。 + - **返回值**：标签属性数组。 + - **异常**：执行失败抛出 `TDengineError` 异常。 + +- `TaosFieldE[] GetColFields()` + - **接口说明**：获取列属性。 + - **返回值**：列属性数组。 + - **异常**：执行失败抛出 `TDengineError` 异常。 + +- `void BindRow(object[] row)` + - **接口说明**：绑定行。 + - **参数说明**： + - `row`：行数据数组。 + - **异常**：执行失败抛出 `TDengineError` 异常。 + +- `void BindColumn( TaosFieldE[] fields,params Array[] arrays)` + - **接口说明**：绑定全部列。 + - **参数说明**： + - `fields`：字段属性数组。 + - `arrays`：多列数据数组。 + - **异常**：执行失败抛出 `TDengineError` 异常。 + +- `void AddBatch()` + - **接口说明**：添加批处理。 + - **异常**：执行失败抛出 `TDengineError` 异常。 + +- `void Exec()` + - **接口说明**：执行参数绑定。 + - **异常**：执行失败抛出 `TDengineError` 异常。 + +- `long Affected()` + - **接口说明**：获取受影响的行数。 + - **返回值**：受影响的行数。 + - **异常**：执行失败抛出 `TDengineError` 异常。 + +- `IRows Result()` + - **接口说明**：获取结果。 + - **返回值**：结果对象。 + - **异常**：执行失败抛出 `TDengineError` 异常。 + +### 数据订阅 + +`ConsumerBuilder` 类提供了消费者构建相关接口，`ConsumeResult` 类提供了消费结果相关接口，`TopicPartitionOffset` 类提供了分区偏移量相关接口。`ReferenceDeserializer` 和 `DictionaryDeserializer` 提供了反序列化的支持。 + +#### 消费者 + +- `public ConsumerBuilder(IEnumerable> config)` + - **接口说明**：ConsumerBuilder 构造函数。 + - **参数说明**： + - `config`：消费配置。 + +创建消费者支持属性列表： + +- `useSSL`：是否使用 SSL 连接，默认为 false +- `token`：连接 TDengine cloud 的 token +- `ws.message.enableCompression`：是否启用 WebSocket 压缩，默认为 false +- `ws.autoReconnect`：是否自动重连，默认为 false +- `ws.reconnect.retry.count`：重连次数，默认为 3 +- `ws.reconnect.interval.ms`：重连间隔毫秒时间，默认为 2000 + +其他参数请参考：[Consumer 参数列表](../../develop/tmq/#数据订阅相关参数)， 注意TDengine服务端自 3.2.0.0 版本开始消息订阅中的 auto.offset.reset 默认值发生变化。 + +- `public IConsumer Build()` + - **接口说明**：构建消费者。 + - **返回值**：消费者对象。 + +`IConsumer` 接口提供了消费者相关 API： + +- `ConsumeResult Consume(int millisecondsTimeout)` + - **接口说明**：消费消息。 + - **参数说明**： + - `millisecondsTimeout`：毫秒超时时间。 + - **返回值**：消费结果。 + - **异常**：执行失败抛出 `TDengineError` 异常。 + +- `List Assignment { get; }` + - **接口说明**：获取分配信息。 + - **返回值**：分配信息。 + - **异常**：执行失败抛出 `TDengineError` 异常。 + +- `List Subscription()` + - **接口说明**：获取订阅的主题。 + - **返回值**：主题列表。 + - **异常**：执行失败抛出 `TDengineError` 异常。 + +- `void Subscribe(IEnumerable topic)` + - **接口说明**：订阅主题列表。 + - **参数说明**： + - `topic`：主题列表。 + - **异常**：执行失败抛出 `TDengineError` 异常。 + +- `void Subscribe(string topic)` + - **接口说明**：订阅单个主题。 + - **参数说明**： + - `topic`：主题。 + - **异常**：执行失败抛出 `TDengineError` 异常。 + +- `void Unsubscribe()` + - **接口说明**：取消订阅。 + - **异常**：执行失败抛出 `TDengineError` 异常。 + +- `void Commit(ConsumeResult consumerResult)` + - **接口说明**：提交消费结果。 + - **参数说明**： + - `consumerResult`：消费结果。 + - **异常**：执行失败抛出 `TDengineError` 异常。 + +- `List Commit()` + - **接口说明**：提交全部消费结果。 + - **返回值**：分区偏移量。 + - **异常**：执行失败抛出 `TDengineError` 异常。 + +- `void Commit(IEnumerable offsets)` + - **接口说明**：提交消费结果。 + - **参数说明**： + - `offsets`：分区偏移量。 + - **异常**：执行失败抛出 `TDengineError` 异常。 + +- `void Seek(TopicPartitionOffset tpo)` + - **接口说明**：跳转到分区偏移量。 + - **参数说明**： + - `tpo`：分区偏移量。 + - **异常**：执行失败抛出 `TDengineError` 异常。 + +- `List Committed(TimeSpan timeout)` + - **接口说明**：获取分区偏移量。 + - **参数说明**： + - `timeout`：超时时间(未使用)。 + - **返回值**：分区偏移量。 + - **异常**：执行失败抛出 `TDengineError` 异常。 + +- `List Committed(IEnumerable partitions, TimeSpan timeout)` + - **接口说明**：获取指定分区偏移量。 + - **参数说明**： + - `partitions`：分区列表。 + - `timeout`：超时时间(未使用)。 + - **返回值**：分区偏移量。 + - **异常**：执行失败抛出 `TDengineError` 异常。 + +- `Offset Position(TopicPartition partition)` + - **接口说明**：获取消费位置。 + - **参数说明**： + - `partition`：分区。 + - **返回值**：偏移量。 + - **异常**：执行失败抛出 `TDengineError` 异常。 + +- `void Close()` + - **接口说明**：关闭消费者。 + +#### 消费记录 + +`ConsumeResult` 类提供了消费结果相关接口： + +- `public List> Message` + - **接口说明**：获取消息列表。 + - **返回值**：消息列表。 + +`TmqMessage` 类提供了消息具体内容： + +```csharp + public class TmqMessage + { + public string TableName { get; set; } + public TValue Value { get; set; } + } +``` + +- `TableName`：表名 +- `Value`：消息内容 + +#### 分区信息 + +从 `ConsumeResult` 获取 `TopicPartitionOffset`： + +```csharp +public TopicPartitionOffset TopicPartitionOffset +``` + +`TopicPartitionOffset` 类提供了获取分区信息的接口： + +- `public string Topic { get; }` + - **接口说明**：获取主题。 + - **返回值**：主题。 + +- `public Partition Partition { get; }` + - **接口说明**：获取分区。 + - **返回值**：分区。 + +- `public Offset Offset { get; }` + - **接口说明**：获取偏移量。 + - **返回值**：偏移量。 + +- `public TopicPartition TopicPartition` + - **接口说明**：获取主题分区。 + - **返回值**：主题分区。 + +- `public string ToString()` + - **接口说明**：转换为字符串。 + - **返回值**：字符串信息。 + +#### 偏移量元数据 + +`Offset` 类提供了偏移量相关接口： + +- `public long Value` + - **接口说明**：获取偏移量值。 + - **返回值**：偏移量值。 + +#### 反序列化 + +C# 驱动提供了两个反序列化类：`ReferenceDeserializer` 和 `DictionaryDeserializer`。它们都实现了 `IDeserializer` 接口。 + +ReferenceDeserializer 用来将消费到的一条记录反序列化为一个对象，需要保证对象类的属性名与消费到的数据的列名能够对应，且类型能够匹配。 + +DictionaryDeserializer 则会将消费到的一行数据反序列化为一个 `Dictionary` 对象，其 key 为列名，值为对象。 + +ReferenceDeserializer 和 DictionaryDeserializer 的接口不会被用户直接调用，请参考使用样例。 \ No newline at end of file From 5ab0b112239da41c8630226e14b335a96a8cac9a Mon Sep 17 00:00:00 2001 From: sheyanjie-qq <249478495@qq.com> Date: Thu, 1 Aug 2024 14:26:55 +0800 Subject: [PATCH 6/7] mod sample code --- .../com/taos/example/JNIConnectExample.java | 6 +- .../com/taos/example/RESTConnectExample.java | 6 +- .../com/taos/example/WSConnectExample.java | 6 +- docs/zh/08-develop/01-connect/index.md | 8 +- docs/zh/08-develop/02-sql.md | 7 +- docs/zh/08-develop/04-schemaless.md | 6 ++ docs/zh/08-develop/05-stmt.md | 9 +- docs/zh/08-develop/07-tmq.md | 6 +- docs/zh/14-reference/05-connector/14-java.mdx | 2 +- .../com/taosdata/example/AbsConsumerLoop.java | 17 ++-- .../taosdata/example/AbsConsumerLoopFull.java | 4 +- .../taosdata/example/AbsWsConsumerLoop.java | 5 +- .../taosdata/example/ConsumerOffsetSeek.java | 6 +- .../com/taosdata/example/JdbcCreatDBDemo.java | 7 +- .../taosdata/example/JdbcInsertDataDemo.java | 10 +-- .../com/taosdata/example/JdbcQueryDemo.java | 11 ++- .../com/taosdata/example/JdbcReqIdDemo.java | 16 ++-- .../example/ParameterBindingBasicDemo.java | 49 +++-------- .../example/ParameterBindingBatchDemo.java | 83 +++++++++++++++++++ .../taosdata/example/SchemalessJniTest.java | 11 ++- .../taosdata/example/SchemalessWsTest.java | 7 +- .../example/WSParameterBindingBasicDemo.java | 3 +- 22 files changed, 171 insertions(+), 114 deletions(-) create mode 100644 examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/ParameterBindingBatchDemo.java diff --git a/docs/examples/java/src/main/java/com/taos/example/JNIConnectExample.java b/docs/examples/java/src/main/java/com/taos/example/JNIConnectExample.java index 8905150a0a..8b9f27c5ab 100644 --- a/docs/examples/java/src/main/java/com/taos/example/JNIConnectExample.java +++ b/docs/examples/java/src/main/java/com/taos/example/JNIConnectExample.java @@ -20,15 +20,13 @@ public static void main(String[] args) throws SQLException { connProps.setProperty(TSDBDriver.PROPERTY_KEY_TIME_ZONE, "UTC-8"); try (Connection conn = DriverManager.getConnection(jdbcUrl, connProps)) { - System.out.println("Connected"); + System.out.println("Connected to " + jdbcUrl + " successfully."); // you can use the connection for execute SQL here } catch (SQLException ex) { // handle any errors, please refer to the JDBC specifications for detailed exceptions info - System.out.println("SQLState: " + ex.getSQLState()); - System.out.println("Error Code: " + ex.getErrorCode()); - System.out.println("Message: " + ex.getMessage()); + System.out.println("Failed to connect to " + jdbcUrl + "; ErrCode:" + ex.getErrorCode() + "; ErrMessage: " + ex.getMessage()); } } // ANCHOR_END: main diff --git a/docs/examples/java/src/main/java/com/taos/example/RESTConnectExample.java b/docs/examples/java/src/main/java/com/taos/example/RESTConnectExample.java index cd129db699..22bf1d61f4 100644 --- a/docs/examples/java/src/main/java/com/taos/example/RESTConnectExample.java +++ b/docs/examples/java/src/main/java/com/taos/example/RESTConnectExample.java @@ -9,15 +9,13 @@ public class RESTConnectExample { public static void main(String[] args) throws SQLException { String jdbcUrl = "jdbc:TAOS-RS://localhost:6041?user=root&password=taosdata"; try (Connection conn = DriverManager.getConnection(jdbcUrl)){ - System.out.println("Connected"); + System.out.println("Connected to " + jdbcUrl + " successfully."); // you can use the connection for execute SQL here } catch (SQLException ex) { // handle any errors, please refer to the JDBC specifications for detailed exceptions info - System.out.println("SQLState: " + ex.getSQLState()); - System.out.println("Error Code: " + ex.getErrorCode()); - System.out.println("Message: " + ex.getMessage()); + System.out.println("Failed to connect to " + jdbcUrl + "; ErrCode:" + ex.getErrorCode() + "; ErrMessage: " + ex.getMessage()); } } // ANCHOR_END: main diff --git a/docs/examples/java/src/main/java/com/taos/example/WSConnectExample.java b/docs/examples/java/src/main/java/com/taos/example/WSConnectExample.java index 3f417841b2..b355a28f6f 100644 --- a/docs/examples/java/src/main/java/com/taos/example/WSConnectExample.java +++ b/docs/examples/java/src/main/java/com/taos/example/WSConnectExample.java @@ -21,15 +21,13 @@ public static void main(String[] args) throws SQLException { connProps.setProperty(TSDBDriver.PROPERTY_KEY_TIME_ZONE, "UTC-8"); try (Connection conn = DriverManager.getConnection(jdbcUrl, connProps)){ - System.out.println("Connected"); + System.out.println("Connected to " + jdbcUrl + " successfully."); // you can use the connection for execute SQL here } catch (SQLException ex) { // handle any errors, please refer to the JDBC specifications for detailed exceptions info - System.out.println("SQLState: " + ex.getSQLState()); - System.out.println("Error Code: " + ex.getErrorCode()); - System.out.println("Message: " + ex.getMessage()); + System.out.println("Failed to connect to " + jdbcUrl + "; ErrCode:" + ex.getErrorCode() + "; ErrMessage: " + ex.getMessage()); } } // ANCHOR_END: main diff --git a/docs/zh/08-develop/01-connect/index.md b/docs/zh/08-develop/01-connect/index.md index 29e363c019..08a39ac815 100644 --- a/docs/zh/08-develop/01-connect/index.md +++ b/docs/zh/08-develop/01-connect/index.md @@ -294,7 +294,7 @@ URL 和 Properties 的详细参数说明和如何使用详见 [API 说明](../.. ### Websocket 连接 -各语言连接器建立 Websocket 连接代码样例。 +下面是各语言连接器建立 Websocket 连接代码样例。演示了如何使用 Websocket 连接方式连接到 TDengine 数据库，并对连接设定一些参数。整个过程主要涉及到数据库连接的建立和异常处理。 @@ -334,7 +334,8 @@ URL 和 Properties 的详细参数说明和如何使用详见 [API 说明](../.. ### 原生连接 -各语言连接器建立原生连接代码样例。 +下面是各语言连接器建立原生连接代码样例。演示了如何使用原生连接方式连接到 TDengine 数据库，并对连接设定一些参数。整个过程主要涉及到数据库连接的建立和异常处理。 + ```java @@ -366,7 +367,8 @@ URL 和 Properties 的详细参数说明和如何使用详见 [API 说明](../.. ### REST 连接 -各语言连接器建立 REST 连接代码样例。 +下面是各语言连接器建立 RESt 连接代码样例。演示了如何使用 REST 连接方式连接到 TDengine 数据库。整个过程主要涉及到数据库连接的建立和异常处理。 + ```java diff --git a/docs/zh/08-develop/02-sql.md b/docs/zh/08-develop/02-sql.md index eec1bcd70b..105b42d120 100644 --- a/docs/zh/08-develop/02-sql.md +++ b/docs/zh/08-develop/02-sql.md @@ -12,7 +12,8 @@ TDengine 对 SQL 语言提供了全面的支持，允许用户以熟悉的 SQL 下面介绍使用各语言连接器通过执行 SQL 完成建库、建表、写入数据和查询数据。 ## 建库和表 -以智能电表为例，展示如何使用连接器执行 SQL 来创建数据库和表。 +下面以智能电表为例，展示使用各语言连接器如何执行 SQL 命令创建一个名为 `power` 的数据库，然后使用 `power` 数据库为默认数据库。 +接着创建一个名为 `meters` 的超级表（STABLE），其表结构包含时间戳、电流、电压、相位等列，以及分组 ID 和位置作为标签。 @@ -40,7 +41,7 @@ TDengine 对 SQL 语言提供了全面的支持，允许用户以熟悉的 SQL ## 插入数据 -以智能电表为例，展示如何使用连接器执行 SQL 来插入数据。 +下面以智能电表为例，展示如何使用连接器执行 SQL 来插入数据到 `power` 数据库的 `meters` 超级表。样例使用 TDengine 自动建表 SQL 语法，写入 d1001 子表中 3 条数据，写入 d1002 子表中 1 条数据，然后打印出实际插入数据条数。 @@ -70,7 +71,7 @@ NOW 为系统内部函数，默认为客户端所在计算机当前时间。 NOW ## 查询数据 -以智能电表为例，展示如何使用各语言连接器执行 SQL 来查询数据，并将获取到的结果打印出来。 +下面以智能电表为例，展示如何使用各语言连接器执行 SQL 来查询数据，从 `power` 数据库 `meters` 超级表中查询最多 100 行数据，并将获取到的结果按行打印出来。 diff --git a/docs/zh/08-develop/04-schemaless.md b/docs/zh/08-develop/04-schemaless.md index 816b3aa170..734e9558a2 100644 --- a/docs/zh/08-develop/04-schemaless.md +++ b/docs/zh/08-develop/04-schemaless.md @@ -153,6 +153,12 @@ st,t1=3,t2=4,t3=t3 c1=3i64,c6="passit" 1626006833640000000 ## 无模式写入示例 下面以智能电表为例，介绍各语言连接器使用无模式写入接口写入数据的代码样例，包含了三种协议： InfluxDB 的行协议、OpenTSDB 的 TELNET 行协议和 OpenTSDB 的 JSON 格式协议。 +:::note +- 因为无模式写入自动建表规则与之前执行 SQL 样例中不同，因此运行代码样例前请确保 `meters`、`metric_telnet` 和 `metric_json` 表不存在。 +- OpenTSDB 的 TELNET 行协议和 OpenTSDB 的 JSON 格式协议只支持一个数据列，因此我们采用了其他示例。 + +::: + ### Websocket 连接 diff --git a/docs/zh/08-develop/05-stmt.md b/docs/zh/08-develop/05-stmt.md index 214984c86c..132a1b8850 100644 --- a/docs/zh/08-develop/05-stmt.md +++ b/docs/zh/08-develop/05-stmt.md @@ -13,7 +13,14 @@ import TabItem from "@theme/TabItem"; - 预编译：当使用参数绑定时，SQL 语句可以被预编译并缓存，后续使用不同的参数值执行时，可以直接使用预编译的版本，提高执行效率。 - 减少网络开销：参数绑定还可以减少发送到数据库的数据量，因为只需要发送参数值而不是完整的 SQL 语句，特别是在执行大量相似的插入或更新操作时，这种差异尤为明显。 -下面我们继续以智能电表为例，展示各语言连接器使用参数绑定高效写入的功能。 +下面我们继续以智能电表为例，展示各语言连接器使用参数绑定高效写入的功能： +1. 准备一个参数化的 SQL 插入语句，用于向超级表 `meters` 中插入数据。这个语句允许动态地指定子表名、标签和列值。 +2. 循环生成多个子表及其对应的数据行。对于每个子表： + - 设置子表的名称和标签值（分组 ID 和位置）。 + - 生成多行数据，每行包括一个时间戳、随机生成的电流、电压和相位值。 + - 执行批量插入操作，将这些数据行插入到对应的子表中。 +3. 最后打印实际插入表中的行数。 + ## Websocket 连接 diff --git a/docs/zh/08-develop/07-tmq.md b/docs/zh/08-develop/07-tmq.md index f548126e49..16a538757f 100644 --- a/docs/zh/08-develop/07-tmq.md +++ b/docs/zh/08-develop/07-tmq.md @@ -78,7 +78,8 @@ Java 连接器创建消费者的参数为 Properties， 可以设置的参数列 ### Websocket 连接 -介绍各语言连接器使用 Websocket 连接方式创建消费者。 +介绍各语言连接器使用 Websocket 连接方式创建消费者。指定连接的服务器地址，设置自动提交，从最新消息开始消费，指定 `group.id` 和 `client.id` 等信息。有的语言的连接器还支持反序列化参数。 + @@ -126,7 +127,8 @@ Java 连接器创建消费者的参数为 Properties， 可以设置的参数列 ### 原生连接 -介绍各语言连接器使用原生连接方式创建消费者。 +介绍各语言连接器使用原生连接方式创建消费者。指定连接的服务器地址，设置自动提交，从最新消息开始消费，指定 `group.id` 和 `client.id` 等信息。有的语言的连接器还支持反序列化参数。 + diff --git a/docs/zh/14-reference/05-connector/14-java.mdx b/docs/zh/14-reference/05-connector/14-java.mdx index acb1dee674..33f63916d2 100644 --- a/docs/zh/14-reference/05-connector/14-java.mdx +++ b/docs/zh/14-reference/05-connector/14-java.mdx @@ -1365,7 +1365,7 @@ JDBC 标准不支持数据订阅，因此本章所有接口都是扩展接口。 | reconnectIntervalMs | 自动重连重试间隔，单位毫秒。仅在 enableCompression 为 true 时生效。 | 2000 ms | | reconnectRetryCount | 自动重连重试次数。仅在 enableCompression 为 true 时生效。 | 3 | -其他参数请参考：[Consumer 参数列表](../../develop/tmq/#数据订阅相关参数)， 注意TDengine服务端自 3.2.0.0 版本开始消息订阅中的 auto.offset.reset 默认值发生变化。 +其他参数请参考：[Consumer 参数列表](../../../develop/tmq/#创建参数)， 注意TDengine服务端自 3.2.0.0 版本开始消息订阅中的 auto.offset.reset 默认值发生变化。 - `public void subscribe(Collection topics) throws SQLException` - **接口说明**：订阅一组主题。 diff --git a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/AbsConsumerLoop.java b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/AbsConsumerLoop.java index 62e3939573..90e6a950cd 100644 --- a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/AbsConsumerLoop.java +++ b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/AbsConsumerLoop.java @@ -39,8 +39,7 @@ try { this.consumer = new TaosConsumer<>(config); } catch (SQLException ex) { // handle any errors, please refer to the JDBC specifications for detailed exceptions info - System.out.println("Error Code: " + ex.getErrorCode()); - System.out.println("Message: " + ex.getMessage()); + System.out.println("Failed to create jni consumer with " + config.getProperty("bootstrap.servers") + " ErrCode:" + ex.getErrorCode() + "; ErrMessage: " + ex.getMessage()); throw new SQLException("Failed to create consumer", ex); } // ANCHOR_END: create_consumer @@ -66,9 +65,8 @@ try { } } catch (SQLException ex){ // handle any errors, please refer to the JDBC specifications for detailed exceptions info - System.out.println("Error Code: " + ex.getErrorCode()); - System.out.println("Message: " + ex.getMessage()); - + System.out.println("Failed to poll data; ErrCode:" + ex.getErrorCode() + "; ErrMessage: " + ex.getMessage()); + throw new SQLException("Failed to poll data", ex); } finally { consumer.close(); shutdownLatch.countDown(); @@ -94,9 +92,8 @@ try { } } catch (SQLException ex){ // handle any errors, please refer to the JDBC specifications for detailed exceptions info - System.out.println("Error Code: " + ex.getErrorCode()); - System.out.println("Message: " + ex.getMessage()); - + System.out.println("Failed to execute consumer functions. ErrCode:" + ex.getErrorCode() + "; ErrMessage: " + ex.getMessage()); + throw new SQLException("Failed to execute consumer functions", ex); } finally { consumer.close(); shutdownLatch.countDown(); @@ -110,8 +107,8 @@ try { consumer.unsubscribe(); } catch (SQLException ex){ // handle any errors, please refer to the JDBC specifications for detailed exceptions info - System.out.println("Error Code: " + ex.getErrorCode()); - System.out.println("Message: " + ex.getMessage()); + System.out.println("Failed to unsubscribe consumer. ErrCode:" + ex.getErrorCode() + "; ErrMessage: " + ex.getMessage()); + throw new SQLException("Failed to unsubscribe consumer", ex); } finally { consumer.close(); } diff --git a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/AbsConsumerLoopFull.java b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/AbsConsumerLoopFull.java index af3537ef0e..bd8f1799f6 100644 --- a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/AbsConsumerLoopFull.java +++ b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/AbsConsumerLoopFull.java @@ -38,8 +38,8 @@ public abstract class AbsConsumerLoopFull { try { this.consumer = new TaosConsumer<>(config); } catch (SQLException ex) { - // handle exception - System.out.println("SQLException: " + ex.getMessage()); + // handle any errors, please refer to the JDBC specifications for detailed exceptions info + System.out.println("Failed to create jni consumer, host : " + config.getProperty("bootstrap.servers") + "; ErrCode:" + ex.getErrorCode() + "; ErrMessage: " + ex.getMessage()); throw new SQLException("Failed to create consumer", ex); } diff --git a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/AbsWsConsumerLoop.java b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/AbsWsConsumerLoop.java index 98ff5657d8..690c05841c 100644 --- a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/AbsWsConsumerLoop.java +++ b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/AbsWsConsumerLoop.java @@ -39,13 +39,12 @@ try { this.consumer = new TaosConsumer<>(config); } catch (SQLException ex) { // handle any errors, please refer to the JDBC specifications for detailed exceptions info - System.out.println("Error Code: " + ex.getErrorCode()); - System.out.println("Message: " + ex.getMessage()); + System.out.println("Failed to create ws consumer with " + config.getProperty("bootstrap.servers") + " ErrCode:" + ex.getErrorCode() + "; ErrMessage: " + ex.getMessage()); throw new SQLException("Failed to create consumer", ex); } // ANCHOR_END: create_consumer - this.topics = Collections.singletonList("topic_speed"); + this.topics = Collections.singletonList("topic_meters"); this.shutdown = new AtomicBoolean(false); this.shutdownLatch = new CountDownLatch(1); } diff --git a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/ConsumerOffsetSeek.java b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/ConsumerOffsetSeek.java index 3b1ff88b28..b9463d30f7 100644 --- a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/ConsumerOffsetSeek.java +++ b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/ConsumerOffsetSeek.java @@ -54,9 +54,9 @@ try (TaosConsumer consumer = new TaosConsumer<>(conf // you can handle data here } } catch (SQLException ex) { - // handle exception - System.out.println("SQLException: " + ex.getMessage()); - throw new SQLException("Failed to create consumer", ex); + // handle any errors, please refer to the JDBC specifications for detailed exceptions info + System.out.println("Failed to execute consumer functions. server: " + config.getProperty("bootstrap.servers") + "; ErrCode:" + ex.getErrorCode() + "; ErrMessage: " + ex.getMessage()); + throw new SQLException("Failed to execute consumer functions", ex); } // ANCHOR_END: consumer_seek } diff --git a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/JdbcCreatDBDemo.java b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/JdbcCreatDBDemo.java index b2246e96cf..d02b3c8789 100644 --- a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/JdbcCreatDBDemo.java +++ b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/JdbcCreatDBDemo.java @@ -15,7 +15,7 @@ public class JdbcCreatDBDemo { public static void main(String[] args) throws SQLException { -final String url = "jdbc:TAOS://" + host + ":6030/?user=" + user + "&password=" + password; +final String jdbcUrl = "jdbc:TAOS://" + host + ":6030/?user=" + user + "&password=" + password; // get connection Properties properties = new Properties(); @@ -24,7 +24,7 @@ properties.setProperty("locale", "en_US.UTF-8"); properties.setProperty("timezone", "UTC-8"); System.out.println("get connection starting..."); // ANCHOR: create_db_and_table -try (Connection connection = DriverManager.getConnection(url, properties); +try (Connection connection = DriverManager.getConnection(jdbcUrl, properties); Statement stmt = connection.createStatement()) { // create database @@ -44,8 +44,7 @@ try (Connection connection = DriverManager.getConnection(url, properties); } catch (SQLException ex) { // handle any errors, please refer to the JDBC specifications for detailed exceptions info - System.out.println("Error Code: " + ex.getErrorCode()); - System.out.println("Message: " + ex.getMessage()); + System.out.println("Failed to create db and table, url:" + jdbcUrl + "; ErrCode:" + ex.getErrorCode() + "; ErrMessage: " + ex.getMessage()); } // ANCHOR_END: create_db_and_table diff --git a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/JdbcInsertDataDemo.java b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/JdbcInsertDataDemo.java index 76e16c9cee..7fc6d5137d 100644 --- a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/JdbcInsertDataDemo.java +++ b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/JdbcInsertDataDemo.java @@ -15,7 +15,7 @@ public class JdbcInsertDataDemo { public static void main(String[] args) throws SQLException { -final String url = "jdbc:TAOS://" + host + ":6030/?user=" + user + "&password=" + password; +final String jdbcUrl = "jdbc:TAOS://" + host + ":6030/?user=" + user + "&password=" + password; // get connection Properties properties = new Properties(); @@ -24,7 +24,7 @@ properties.setProperty("locale", "en_US.UTF-8"); properties.setProperty("timezone", "UTC-8"); System.out.println("get connection starting..."); // ANCHOR: insert_data -try (Connection connection = DriverManager.getConnection(url, properties); +try (Connection connection = DriverManager.getConnection(jdbcUrl, properties); Statement stmt = connection.createStatement()) { // insert data, please make sure the database and table are created before @@ -39,11 +39,11 @@ try (Connection connection = DriverManager.getConnection(url, properties); "(NOW + 1a, 10.30000, 218, 0.25000) "; int affectedRows = stmt.executeUpdate(insertQuery); // you can check affectedRows here - System.out.println("insert " + affectedRows + " rows."); + System.out.println("inserted into " + affectedRows + " rows to power.meters successfully."); } catch (SQLException ex) { // handle any errors, please refer to the JDBC specifications for detailed exceptions info - System.out.println("Error Code: " + ex.getErrorCode()); - System.out.println("Message: " + ex.getMessage()); + System.out.println("Failed to insert data to power.meters, url:" + jdbcUrl + "; ErrCode:" + ex.getErrorCode() + "; ErrMessage: " + ex.getMessage()); + } // ANCHOR_END: insert_data } diff --git a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/JdbcQueryDemo.java b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/JdbcQueryDemo.java index fdbab204c2..30a835bb11 100644 --- a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/JdbcQueryDemo.java +++ b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/JdbcQueryDemo.java @@ -15,7 +15,7 @@ public class JdbcQueryDemo { public static void main(String[] args) throws SQLException { -final String url = "jdbc:TAOS://" + host + ":6030/?user=" + user + "&password=" + password; +final String jdbcUrl = "jdbc:TAOS://" + host + ":6030/?user=" + user + "&password=" + password; // get connection Properties properties = new Properties(); @@ -24,10 +24,10 @@ properties.setProperty("locale", "en_US.UTF-8"); properties.setProperty("timezone", "UTC-8"); System.out.println("get connection starting..."); // ANCHOR: query_data -try (Connection connection = DriverManager.getConnection(url, properties); +try (Connection connection = DriverManager.getConnection(jdbcUrl, properties); Statement stmt = connection.createStatement(); // query data, make sure the database and table are created before - ResultSet resultSet = stmt.executeQuery("SELECT * FROM power.meters")) { + ResultSet resultSet = stmt.executeQuery("SELECT ts, current, location FROM power.meters limit 100")) { Timestamp ts; float current; @@ -39,12 +39,11 @@ try (Connection connection = DriverManager.getConnection(url, properties); location = resultSet.getString("location"); // you can check data here - System.out.printf("%s, %f, %s\n", ts, current, location); + System.out.printf("ts: %s, current: %f, location: %s %n", ts, current, location); } } catch (SQLException ex) { // handle any errors, please refer to the JDBC specifications for detailed exceptions info - System.out.println("Error Code: " + ex.getErrorCode()); - System.out.println("Message: " + ex.getMessage()); + System.out.println("Failed to query data from power.meters, url:" + jdbcUrl + "; ErrCode:" + ex.getErrorCode() + "; ErrMessage: " + ex.getMessage()); } // ANCHOR_END: query_data } diff --git a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/JdbcReqIdDemo.java b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/JdbcReqIdDemo.java index 5fb7e9760e..cc557c18c5 100644 --- a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/JdbcReqIdDemo.java +++ b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/JdbcReqIdDemo.java @@ -15,7 +15,7 @@ public class JdbcReqIdDemo { public static void main(String[] args) throws SQLException { -final String url = "jdbc:TAOS://" + host + ":6030/?user=" + user + "&password=" + password; +final String jdbcUrl = "jdbc:TAOS://" + host + ":6030/?user=" + user + "&password=" + password; // get connection Properties properties = new Properties(); @@ -25,17 +25,11 @@ properties.setProperty("timezone", "UTC-8"); System.out.println("get connection starting..."); // ANCHOR: with_reqid -try (Connection connection = DriverManager.getConnection(url, properties); +try (Connection connection = DriverManager.getConnection(jdbcUrl, properties); // Create a statement that allows specifying a request ID AbstractStatement aStmt = (AbstractStatement) connection.createStatement()) { - boolean hasResultSet = aStmt.execute("CREATE DATABASE IF NOT EXISTS power", 1L); - assert !hasResultSet; - - int rowsAffected = aStmt.executeUpdate("USE power", 2L); - assert rowsAffected == 0; - - try (ResultSet rs = aStmt.executeQuery("SELECT * FROM meters limit 1", 3L)) { + try (ResultSet rs = aStmt.executeQuery("SELECT ts, current, location FROM power.meters limit 1", 3L)) { while (rs.next()) { Timestamp timestamp = rs.getTimestamp(1); System.out.println("timestamp = " + timestamp); @@ -43,8 +37,8 @@ try (Connection connection = DriverManager.getConnection(url, properties); } } catch (SQLException ex) { // handle any errors, please refer to the JDBC specifications for detailed exceptions info - System.out.println("Error Code: " + ex.getErrorCode()); - System.out.println("Message: " + ex.getMessage()); + System.out.println("Failed to execute sql with reqId, url:" + jdbcUrl + "; ErrCode:" + ex.getErrorCode() + "; ErrMessage: " + ex.getMessage()); + } // ANCHOR_END: with_reqid } diff --git a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/ParameterBindingBasicDemo.java b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/ParameterBindingBasicDemo.java index d5f547b50f..469316efc7 100644 --- a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/ParameterBindingBasicDemo.java +++ b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/ParameterBindingBasicDemo.java @@ -1,14 +1,9 @@ package com.taosdata.example; import com.taosdata.jdbc.TSDBPreparedStatement; -import com.taosdata.jdbc.utils.StringUtils; -import java.sql.Connection; -import java.sql.DriverManager; -import java.sql.SQLException; -import java.sql.Statement; +import java.sql.*; import java.util.ArrayList; -import java.util.List; import java.util.Random; // ANCHOR: para_bind @@ -29,7 +24,6 @@ public class ParameterBindingBasicDemo { String sql = "INSERT INTO ? USING meters TAGS(?,?) VALUES (?,?,?,?)"; try (TSDBPreparedStatement pstmt = conn.prepareStatement(sql).unwrap(TSDBPreparedStatement.class)) { - for (int i = 1; i <= numOfSubTable; i++) { // set table name pstmt.setTableName("d_bind_" + i); @@ -38,40 +32,23 @@ public class ParameterBindingBasicDemo { pstmt.setTagInt(0, i); pstmt.setTagString(1, "location_" + i); - // set column ts - ArrayList tsList = new ArrayList<>(); + // set columns long current = System.currentTimeMillis(); - for (int j = 0; j < numOfRow; j++) - tsList.add(current + j); - pstmt.setTimestamp(0, tsList); - - // set column current - ArrayList f1List = new ArrayList<>(); - for (int j = 0; j < numOfRow; j++) - f1List.add(random.nextFloat() * 30); - pstmt.setFloat(1, f1List); - - // set column voltage - ArrayList f2List = new ArrayList<>(); - for (int j = 0; j < numOfRow; j++) - f2List.add(random.nextInt(300)); - pstmt.setInt(2, f2List); - - // set column phase - ArrayList f3List = new ArrayList<>(); - for (int j = 0; j < numOfRow; j++) - f3List.add(random.nextFloat()); - pstmt.setFloat(3, f3List); - // add column - pstmt.columnDataAddBatch(); + for (int j = 0; j < numOfRow; j++) { + pstmt.setTimestamp(1, new Timestamp(current + j)); + pstmt.setFloat(2, random.nextFloat() * 30); + pstmt.setInt(3, random.nextInt(300)); + pstmt.setFloat(4, random.nextFloat()); + pstmt.addBatch(); + } + int [] exeResult = pstmt.executeBatch(); + // you can check exeResult here + System.out.println("insert " + exeResult.length + " rows."); } - // execute column - pstmt.columnDataExecuteBatch(); } } catch (SQLException ex) { // handle any errors, please refer to the JDBC specifications for detailed exceptions info - System.out.println("Error Code: " + ex.getErrorCode()); - System.out.println("Message: " + ex.getMessage()); + System.out.println("Failed to insert to table meters using stmt, url: " + jdbcUrl + "; ErrCode:" + ex.getErrorCode() + "; ErrMessage: " + ex.getMessage()); } } diff --git a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/ParameterBindingBatchDemo.java b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/ParameterBindingBatchDemo.java new file mode 100644 index 0000000000..60d76eee4f --- /dev/null +++ b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/ParameterBindingBatchDemo.java @@ -0,0 +1,83 @@ +package com.taosdata.example; + +import com.taosdata.jdbc.TSDBPreparedStatement; + +import java.sql.Connection; +import java.sql.DriverManager; +import java.sql.SQLException; +import java.sql.Statement; +import java.util.ArrayList; +import java.util.Random; + +// ANCHOR: para_bind +public class ParameterBindingBatchDemo { + + // modify host to your own + private static final String host = "127.0.0.1"; + private static final Random random = new Random(System.currentTimeMillis()); + private static final int numOfSubTable = 10, numOfRow = 10; + + public static void main(String[] args) throws SQLException { + + String jdbcUrl = "jdbc:TAOS://" + host + ":6030/"; + try (Connection conn = DriverManager.getConnection(jdbcUrl, "root", "taosdata")) { + + init(conn); + + String sql = "INSERT INTO ? USING meters TAGS(?,?) VALUES (?,?,?,?)"; + + try (TSDBPreparedStatement pstmt = conn.prepareStatement(sql).unwrap(TSDBPreparedStatement.class)) { + + for (int i = 1; i <= numOfSubTable; i++) { + // set table name + pstmt.setTableName("d_bind_" + i); + + // set tags + pstmt.setTagInt(0, i); + pstmt.setTagString(1, "location_" + i); + + // set column ts + ArrayList tsList = new ArrayList<>(); + long current = System.currentTimeMillis(); + for (int j = 0; j < numOfRow; j++) + tsList.add(current + j); + pstmt.setTimestamp(0, tsList); + + // set column current + ArrayList f1List = new ArrayList<>(); + for (int j = 0; j < numOfRow; j++) + f1List.add(random.nextFloat() * 30); + pstmt.setFloat(1, f1List); + + // set column voltage + ArrayList f2List = new ArrayList<>(); + for (int j = 0; j < numOfRow; j++) + f2List.add(random.nextInt(300)); + pstmt.setInt(2, f2List); + + // set column phase + ArrayList f3List = new ArrayList<>(); + for (int j = 0; j < numOfRow; j++) + f3List.add(random.nextFloat()); + pstmt.setFloat(3, f3List); + // add column + pstmt.columnDataAddBatch(); + } + // execute column + pstmt.columnDataExecuteBatch(); + } + } catch (SQLException ex) { + // handle any errors, please refer to the JDBC specifications for detailed exceptions info + System.out.println("Failed to insert to table meters using stmt, url: " + jdbcUrl + "; ErrCode:" + ex.getErrorCode() + "; ErrMessage: " + ex.getMessage()); + } + } + + private static void init(Connection conn) throws SQLException { + try (Statement stmt = conn.createStatement()) { + stmt.execute("CREATE DATABASE IF NOT EXISTS power"); + stmt.execute("USE power"); + stmt.execute("CREATE STABLE IF NOT EXISTS meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (groupId INT, location BINARY(24))"); + } + } +} +// ANCHOR_END: para_bind diff --git a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/SchemalessJniTest.java b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/SchemalessJniTest.java index 238ad35502..8f5fe0e7cf 100644 --- a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/SchemalessJniTest.java +++ b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/SchemalessJniTest.java @@ -13,12 +13,12 @@ import java.sql.Statement; public class SchemalessJniTest { private static final String host = "127.0.0.1"; private static final String lineDemo = "meters,groupid=2,location=California.SanFrancisco current=10.3000002f64,voltage=219i32,phase=0.31f64 1626006833639"; - private static final String telnetDemo = "stb0_0 1707095283260 4 host=host0 interface=eth0"; - private static final String jsonDemo = "{\"metric\": \"meter_current\",\"timestamp\": 1626846400,\"value\": 10.3, \"tags\": {\"groupid\": 2, \"location\": \"California.SanFrancisco\", \"id\": \"d1001\"}}"; + private static final String telnetDemo = "metric_telnet 1707095283260 4 host=host0 interface=eth0"; + private static final String jsonDemo = "{\"metric\": \"metric_json\",\"timestamp\": 1626846400,\"value\": 10.3, \"tags\": {\"groupid\": 2, \"location\": \"California.SanFrancisco\", \"id\": \"d1001\"}}"; public static void main(String[] args) throws SQLException { - final String url = "jdbc:TAOS://" + host + ":6030/?user=root&password=taosdata"; - try (Connection connection = DriverManager.getConnection(url)) { + final String jdbcUrl = "jdbc:TAOS://" + host + ":6030/?user=root&password=taosdata"; + try (Connection connection = DriverManager.getConnection(jdbcUrl)) { init(connection); AbstractConnection conn = connection.unwrap(AbstractConnection.class); @@ -27,8 +27,7 @@ public class SchemalessJniTest { conn.write(jsonDemo, SchemalessProtocolType.JSON, SchemalessTimestampType.NOT_CONFIGURED); } catch (SQLException ex) { // handle any errors, please refer to the JDBC specifications for detailed exceptions info - System.out.println("Error Code: " + ex.getErrorCode()); - System.out.println("Message: " + ex.getMessage()); + System.out.println("Failed to insert data with schemaless, host:" + host + "; ErrCode:" + ex.getErrorCode() + "; ErrMessage: " + ex.getMessage()); } } diff --git a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/SchemalessWsTest.java b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/SchemalessWsTest.java index ed5444a4ec..922781af56 100644 --- a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/SchemalessWsTest.java +++ b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/SchemalessWsTest.java @@ -13,8 +13,8 @@ import java.sql.Statement; public class SchemalessWsTest { private static final String host = "127.0.0.1"; private static final String lineDemo = "meters,groupid=2,location=California.SanFrancisco current=10.3000002f64,voltage=219i32,phase=0.31f64 1626006833639"; - private static final String telnetDemo = "stb0_0 1707095283260 4 host=host0 interface=eth0"; - private static final String jsonDemo = "{\"metric\": \"meter_current\",\"timestamp\": 1626846400,\"value\": 10.3, \"tags\": {\"groupid\": 2, \"location\": \"California.SanFrancisco\", \"id\": \"d1001\"}}"; + private static final String telnetDemo = "metric_telnet 1707095283260 4 host=host0 interface=eth0"; + private static final String jsonDemo = "{\"metric\": \"metric_json\",\"timestamp\": 1626846400,\"value\": 10.3, \"tags\": {\"groupid\": 2, \"location\": \"California.SanFrancisco\", \"id\": \"d1001\"}}"; public static void main(String[] args) throws SQLException { final String url = "jdbc:TAOS-RS://" + host + ":6041?user=root&password=taosdata&batchfetch=true"; @@ -27,8 +27,7 @@ public class SchemalessWsTest { conn.write(jsonDemo, SchemalessProtocolType.JSON, SchemalessTimestampType.SECONDS); } catch (SQLException ex) { // handle any errors, please refer to the JDBC specifications for detailed exceptions info - System.out.println("Error Code: " + ex.getErrorCode()); - System.out.println("Message: " + ex.getMessage()); + System.out.println("Failed to insert data with schemaless, host:" + host + "; ErrCode:" + ex.getErrorCode() + "; ErrMessage: " + ex.getMessage()); } } diff --git a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/WSParameterBindingBasicDemo.java b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/WSParameterBindingBasicDemo.java index 9501d4adab..9eca3c973a 100644 --- a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/WSParameterBindingBasicDemo.java +++ b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/WSParameterBindingBasicDemo.java @@ -49,8 +49,7 @@ public class WSParameterBindingBasicDemo { } } catch (SQLException ex) { // handle any errors, please refer to the JDBC specifications for detailed exceptions info - System.out.println("Error Code: " + ex.getErrorCode()); - System.out.println("Message: " + ex.getMessage()); + System.out.println("Failed to insert to table meters using stmt, url: " + jdbcUrl + "; ErrCode:" + ex.getErrorCode() + "; ErrMessage: " + ex.getMessage()); } } From f399771a2f0124c7fcde508178238886fecf05f1 Mon Sep 17 00:00:00 2001 From: sheyanjie-qq <249478495@qq.com> Date: Thu, 1 Aug 2024 15:15:10 +0800 Subject: [PATCH 7/7] mod reference --- docs/zh/14-reference/05-connector/14-java.mdx | 373 +++++++++--------- docs/zh/14-reference/05-connector/20-go.mdx | 2 +- .../taosdata/example/AbsWsConsumerLoop.java | 4 +- 3 files changed, 182 insertions(+), 197 deletions(-) diff --git a/docs/zh/14-reference/05-connector/14-java.mdx b/docs/zh/14-reference/05-connector/14-java.mdx index 33f63916d2..322c2091ac 100644 --- a/docs/zh/14-reference/05-connector/14-java.mdx +++ b/docs/zh/14-reference/05-connector/14-java.mdx @@ -212,17 +212,14 @@ TDengine 的 JDBC URL 规范格式为： **注意**：使用 JDBC 原生连接，taos-jdbcdriver 需要依赖客户端驱动（Linux 下是 libtaos.so；Windows 下是 taos.dll；macOS 下是 libtaos.dylib）。 对于原生连接 url 中支持的配置参数如下： - -| 属性 | 描述 | 默认值 | -|------------------|--------------------------------------------------------------------------------------------------------|-----------------| -| user | 登录 TDengine 用户名 | 'root' | -| password | 用户登录密码 | 'taosdata' | -| cfgdir | 客户端配置文件目录路径，Linux OS 上默认值 `/etc/taos`，Windows OS 上默认值 `C:/TDengine/cfg` | 系统依赖 | -| charset | 客户端使用的字符集 | 系统字符集 | -| locale | 客户端语言环境 | 系统当前 locale | -| timezone | 客户端使用的时区 | 系统当前时区 | -| batchfetch | 在执行查询时批量拉取结果集；false：逐行拉取结果集。开启批量拉取可以有效的提升查询性能 | true | -| batchErrorIgnore | true：在执行 Statement 的 executeBatch 时，如果中间有一条 SQL 执行失败将继续执行下面的 SQL。false：不再执行失败 SQL 后的任何语句 | false | +- user：登录 TDengine 用户名，默认值 'root'。 +- password：用户登录密码，默认值 'taosdata'。 +- cfgdir：客户端配置文件目录路径，Linux OS 上默认值 `/etc/taos`，Windows OS 上默认值 `C:/TDengine/cfg`。 +- charset：客户端使用的字符集，默认值为系统字符集。 +- locale：客户端语言环境，默认值系统当前 locale。 +- timezone：客户端使用的时区，默认值为系统当前时区。 +- batchfetch: true：在执行查询时批量拉取结果集；false：逐行拉取结果集。默认值为：true。开启批量拉取同时获取一批数据在查询数据量较大时批量拉取可以有效的提升查询性能。 +- batchErrorIgnore：true：在执行 Statement 的 executeBatch 时，如果中间有一条 SQL 执行失败将继续执行下面的 SQL。false：不再执行失败 SQL 后的任何语句。默认值为：false。 JDBC 原生连接的使用请参见[视频教程](https://www.taosdata.com/blog/2020/11/11/1955.html)。 @@ -244,20 +241,16 @@ TDengine 中，只要保证 firstEp 和 secondEp 中一个节点有效，就可 3. 使用 6041 作为连接端口。 对于 Websocket 和 REST 连接，url 中的配置参数如下： - -| 属性 | 描述 | 默认值 | -|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------| -| user | 登录 TDengine 用户名 | 'root' | -| password | 用户登录密码 | 'taosdata' | -| batchfetch | true：在执行查询时批量拉取结果集；false：逐行拉取结果集。逐行拉取结果集使用 HTTP 方式进行数据传输。JDBC REST 连接支持批量拉取数据功能。taos-jdbcdriver 与 TDengine 之间通过 WebSocket 连接进行数据传输，提升查询性能。 | false | -| charset | 当开启批量拉取数据时，指定解析字符串数据的字符集。 | | -| batchErrorIgnore | true：在执行 Statement 的 executeBatch 时，如果中间有一条 SQL 执行失败，继续执行下面的 SQL。false：不再执行失败 SQL 后的任何语句。 | false | -| httpConnectTimeout| 连接超时时间，单位 ms | 60000 | -| httpSocketTimeout | socket 超时时间，单位 ms。仅在 batchfetch 设置为 false 时生效。 | 60000 | -| messageWaitTimeout| 消息超时时间, 单位 ms。仅在 batchfetch 设置为 true 时生效。 | 60000 | -| useSSL | 连接中是否使用 SSL。 | | -| httpPoolSize | REST 并发请求大小 | 20 | - +- user：登录 TDengine 用户名，默认值 'root'。 +- password：用户登录密码，默认值 'taosdata'。 +- batchfetch: true：在执行查询时批量拉取结果集；false：逐行拉取结果集。默认值为：false。逐行拉取结果集使用 HTTP 方式进行数据传输。JDBC REST 连接支持批量拉取数据功能。taos-jdbcdriver 与 TDengine 之间通过 WebSocket 连接进行数据传输。相较于 HTTP，WebSocket 可以使 JDBC REST 连接支持大数据量查询，并提升查询性能。 +- charset: 当开启批量拉取数据时，指定解析字符串数据的字符集。 +- batchErrorIgnore：true：在执行 Statement 的 executeBatch 时，如果中间有一条 SQL 执行失败，继续执行下面的 SQL 了。false：不再执行失败 SQL 后的任何语句。默认值为：false。 +- httpConnectTimeout: 连接超时时间，单位 ms， 默认值为 60000。 +- httpSocketTimeout: socket 超时时间，单位 ms，默认值为 60000。仅在 batchfetch 设置为 false 时生效。 +- messageWaitTimeout: 消息超时时间, 单位 ms， 默认值为 60000。 仅在 batchfetch 设置为 true 时生效。 +- useSSL: 连接中是否使用 SSL。 +- httpPoolSize: REST 并发请求大小，默认 20。 **注意**：部分配置项（比如：locale、timezone）在 REST 连接中不生效。 @@ -274,31 +267,27 @@ TDengine 中，只要保证 firstEp 和 secondEp 中一个节点有效，就可 > **注意**：应用中设置的 client parameter 为进程级别的，即如果要更新 client 的参数，需要重启应用。这是因为 client parameter 是全局参数，仅在应用程序的第一次设置生效。 -properties 中的配置参数如下（**注意**：属性使用需要加上类名，如 `TSDBDriver.PROPERTY_KEY_USER` ）： - -| 属性 | 描述 | 默认值 | -|-------------------------------------------|------------------------------------------------------------------------------------------------------------------------------|----------------------| -| PROPERTY_KEY_USER | 登录 TDengine 用户名 | 'root' | -| PROPERTY_KEY_PASSWORD | 用户登录密码 | 'taosdata' | -| PROPERTY_KEY_BATCH_LOAD | 在执行查询时批量拉取结果集；false：逐行拉取结果集 | false | -| PROPERTY_KEY_BATCH_ERROR_IGNORE | 在执行 Statement 的 executeBatch 时，如果中间有一条 SQL 执行失败，继续执行下面的 SQL。false：不再执行失败 SQL 后的任何语句。 | false | -| PROPERTY_KEY_CONFIG_DIR | 仅在使用 JDBC 原生连接时生效。客户端配置文件目录路径 | Linux: `/etc/taos`, Windows: `C:/TDengine/cfg` | -| PROPERTY_KEY_CHARSET | 客户端使用的字符集 | 系统字符集 | -| PROPERTY_KEY_LOCALE | 仅在使用 JDBC 原生连接时生效。客户端语言环境 | 系统当前 locale | -| PROPERTY_KEY_TIME_ZONE | 仅在使用 JDBC 原生连接时生效。客户端使用的时区 | 系统当前时区 | -| HTTP_CONNECT_TIMEOUT | 连接超时时间，单位 ms。仅在 REST 连接时生效。 | 60000 | -| HTTP_SOCKET_TIMEOUT | socket 超时时间，单位 ms。仅在 REST 连接且 batchfetch 设置为 false 时生效。 | 60000 | -| PROPERTY_KEY_MESSAGE_WAIT_TIMEOUT | 消息超时时间, 单位 ms。仅在 REST 连接且 batchfetch 设置为 true 时生效。 | 60000 | -| PROPERTY_KEY_USE_SSL | 连接中是否使用 SSL。仅在 REST 连接时生效。 | | -| HTTP_POOL_SIZE | REST 并发请求大小 | 20 | -| PROPERTY_KEY_ENABLE_COMPRESSION | 传输过程是否启用压缩。仅在使用 REST/Websocket 连接时生效。 | false | -| PROPERTY_KEY_ENABLE_AUTO_RECONNECT | 是否启用自动重连。仅在使用 Websocket 连接时生效。 | false | -| PROPERTY_KEY_RECONNECT_INTERVAL_MS | 自动重连重试间隔，单位毫秒。仅在 PROPERTY_KEY_ENABLE_AUTO_RECONNECT 为 true 时生效。 | 2000 | -| PROPERTY_KEY_RECONNECT_RETRY_COUNT | 自动重连重试次数。仅在 PROPERTY_KEY_ENABLE_AUTO_RECONNECT 为 true 时生效。 | 3 | -| PROPERTY_KEY_DISABLE_SSL_CERT_VALIDATION | 关闭 SSL 证书验证。仅在使用 Websocket 连接时生效。 | false | - +properties 中的配置参数如下： +- TSDBDriver.PROPERTY_KEY_USER：登录 TDengine 用户名，默认值 'root'。 +- TSDBDriver.PROPERTY_KEY_PASSWORD：用户登录密码，默认值 'taosdata'。 +- TSDBDriver.PROPERTY_KEY_BATCH_LOAD: true：在执行查询时批量拉取结果集；false：逐行拉取结果集。默认值为：false。 +- TSDBDriver.PROPERTY_KEY_BATCH_ERROR_IGNORE：true：在执行 Statement 的 executeBatch 时，如果中间有一条 SQL 执行失败，继续执行下面的 sq 了。false：不再执行失败 SQL 后的任何语句。默认值为：false。 +- TSDBDriver.PROPERTY_KEY_CONFIG_DIR：仅在使用 JDBC 原生连接时生效。客户端配置文件目录路径，Linux OS 上默认值 `/etc/taos`，Windows OS 上默认值 `C:/TDengine/cfg`。 +- TSDBDriver.PROPERTY_KEY_CHARSET：客户端使用的字符集，默认值为系统字符集。 +- TSDBDriver.PROPERTY_KEY_LOCALE：仅在使用 JDBC 原生连接时生效。 客户端语言环境，默认值系统当前 locale。 +- TSDBDriver.PROPERTY_KEY_TIME_ZONE：仅在使用 JDBC 原生连接时生效。 客户端使用的时区，默认值为系统当前时区。因为历史的原因，我们只支持POSIX标准的部分规范，如UTC-8(代表中国上上海), GMT-8，Asia/Shanghai 这几种形式。 +- TSDBDriver.HTTP_CONNECT_TIMEOUT: 连接超时时间，单位 ms， 默认值为 60000。仅在 REST 连接时生效。 +- TSDBDriver.HTTP_SOCKET_TIMEOUT: socket 超时时间，单位 ms，默认值为 60000。仅在 REST 连接且 batchfetch 设置为 false 时生效。 +- TSDBDriver.PROPERTY_KEY_MESSAGE_WAIT_TIMEOUT: 消息超时时间, 单位 ms， 默认值为 60000。 仅在 REST 连接且 batchfetch 设置为 true 时生效。 +- TSDBDriver.PROPERTY_KEY_USE_SSL: 连接中是否使用 SSL。仅在 REST 连接时生效。 +- TSDBDriver.HTTP_POOL_SIZE: REST 并发请求大小，默认 20。 +- TSDBDriver.PROPERTY_KEY_ENABLE_COMPRESSION: 传输过程是否启用压缩。仅在使用 REST/Websocket 连接时生效。true: 启用，false: 不启用。默认为 false。 +- TSDBDriver.PROPERTY_KEY_ENABLE_AUTO_RECONNECT: 是否启用自动重连。仅在使用 Websocket 连接时生效。true: 启用，false: 不启用。默认为 false。 > **注意**：启用自动重连仅对简单执行 SQL 语句以及 无模式写入、数据订阅有效。对于参数绑定无效。自动重连仅对连接建立时通过参数指定数据库有效，对后面的 `use db` 语句切换数据库无效。 +- TSDBDriver.PROPERTY_KEY_RECONNECT_INTERVAL_MS: 自动重连重试间隔，单位毫秒，默认值 2000。仅在 PROPERTY_KEY_ENABLE_AUTO_RECONNECT 为 true 时生效。 +- TSDBDriver.PROPERTY_KEY_RECONNECT_RETRY_COUNT: 自动重连重试次数，默认值 3，仅在 PROPERTY_KEY_ENABLE_AUTO_RECONNECT 为 true 时生效。 +- TSDBDriver.PROPERTY_KEY_DISABLE_SSL_CERT_VALIDATION: 关闭 SSL 证书验证 。仅在使用 Websocket 连接时生效。true: 启用，false: 不启用。默认为 false。 此外对 JDBC 原生连接，通过指定 URL 和 Properties 还可以指定其他参数，比如日志级别、SQL 长度等。更多详细配置请参考[客户端配置](../../reference/config/)。 @@ -315,142 +304,142 @@ properties 中的配置参数如下（**注意**：属性使用需要加上类 #### 接口说明 - `Connection connect(String url, java.util.Properties info) throws SQLException` - - **接口说明**：连接 TDengine 数据库 + - **接口说明**：连接 TDengine 数据库。 - **参数说明**： - - `url`：连接地址 url，详见上文 URL 规范 - - `info`：连接属性，详见上文 Properties 章节 - - **返回值**：连接对象 - - **异常**：连接失败抛出 `SQLException` 异常 + - `url`：连接地址 url，详见上文 URL 规范。 + - `info`：连接属性，详见上文 Properties 章节。 + - **返回值**：连接对象。 + - **异常**：连接失败抛出 `SQLException` 异常。 - `boolean acceptsURL(String url) throws SQLException` - - **接口说明**：判断驱动是否支持 url + - **接口说明**：判断驱动是否支持 url。 - **参数说明**： - - `url`：连接地址 url - - **返回值**：`true`：支持，`false`：不支持 - - **异常**：url 非法抛出 `SQLException` 异常 + - `url`：连接地址 url。 + - **返回值**：`true`：支持，`false`：不支持。 + - **异常**：url 非法抛出 `SQLException` 异常。 - `DriverPropertyInfo[] getPropertyInfo(String url, java.util.Properties info) throws SQLException` - - **接口说明**：获取尝试连接数据库时可能需要的所有属性的详细信息。这些属性信息被封装在 DriverPropertyInfo 对象数组中返回。每个 DriverPropertyInfo 对象包含了一个数据库连接属性的详细信息，比如属性名、属性值、描述等 + - **接口说明**：获取尝试连接数据库时可能需要的所有属性的详细信息。这些属性信息被封装在 DriverPropertyInfo 对象数组中返回。每个 DriverPropertyInfo 对象包含了一个数据库连接属性的详细信息，比如属性名、属性值、描述等。 - **参数说明**： - - `url`：一个 String 类型的参数，表示数据库的 URL - - `info`：一个 java.util.Properties 类型的参数，包含了尝试连接时用户可能提供的属性列表 - - **返回值**：返回值类型为 `DriverPropertyInfo[]`，即 `DriverPropertyInfo` 对象的数组。每个 `DriverPropertyInfo` 对象包含了一个特定的数据库连接属性的详细信息 - - **异常**：如果在获取属性信息的过程中发生数据库访问错误或其他错误，将抛出 `SQLException` 异常 + - `url`：一个 String 类型的参数，表示数据库的 URL。 + - `info`：一个 java.util.Properties 类型的参数，包含了尝试连接时用户可能提供的属性列表。 + - **返回值**：返回值类型为 `DriverPropertyInfo[]`，即 `DriverPropertyInfo` 对象的数组。每个 `DriverPropertyInfo` 对象包含了一个特定的数据库连接属性的详细信息。 + - **异常**：如果在获取属性信息的过程中发生数据库访问错误或其他错误，将抛出 `SQLException` 异常。 - `int getMajorVersion()` - - **接口说明**：获取 JDBC 驱动程序的主版本号 + - **接口说明**：获取 JDBC 驱动程序的主版本号。 - `int getMinorVersion()` - - **接口说明**：获取 JDBC 驱动程序的次版本号 + - **接口说明**：获取 JDBC 驱动程序的次版本号。 ### 数据库元数据 `DatabaseMetaData` 是 JDBC API 的一部分，它提供了关于数据库的元数据的详细信息，元数据意味着关于数据库数据的数据。通过 `DatabaseMetaData` 接口，可以查询数据库服务器的详细信息，比如数据库产品名称、版本、已安装的功能、表、视图、存储过程的列表等。这对于了解和适应不同数据库的特性非常有用。 - `String getURL() throws SQLException` - - **接口说明**：获取用于连接数据库的 URL - - **返回值**：连接数据库的 URL - - **异常**：获取失败将抛出 `SQLException` 异常 + - **接口说明**：获取用于连接数据库的 URL。 + - **返回值**：连接数据库的 URL。 + - **异常**：获取失败将抛出 `SQLException` 异常。 - `String getUserName() throws SQLException` - - **接口说明**：获取用于连接获取数据库的用户名 - - **返回值**：连接数据库的用户名 - - **异常**：获取失败将抛出 `SQLException` 异常 + - **接口说明**：获取用于连接获取数据库的用户名。 + - **返回值**：连接数据库的用户名。 + - **异常**：获取失败将抛出 `SQLException` 异常。 - `String getDriverName() throws SQLException` - - **接口说明**：获取 JDBC 驱动程序的名称 - - **返回值**：驱动名称字符串 - - **异常**：获取失败将抛出 `SQLException` 异常 + - **接口说明**：获取 JDBC 驱动程序的名称。 + - **返回值**：驱动名称字符串。 + - **异常**：获取失败将抛出 `SQLException` 异常。 - `String getDriverVersion() throws SQLException` - - **接口说明**：获取 JDBC 驱动版本 - - **返回值**：驱动版本字符串 - - **异常**：获取失败将抛出 `SQLException` 异常 + - **接口说明**：获取 JDBC 驱动版本。 + - **返回值**：驱动版本字符串。 + - **异常**：获取失败将抛出 `SQLException` 异常。 - `int getDriverMajorVersion()` - - **接口说明**：获取 JDBC 驱动主版本号 + - **接口说明**：获取 JDBC 驱动主版本号。 - `int getDriverMinorVersion()` - - **接口说明**：获取 JDBC 驱动次版本号 + - **接口说明**：获取 JDBC 驱动次版本号。 - `String getDatabaseProductName() throws SQLException` - - **接口说明**：获取数据库产品的名称 + - **接口说明**：获取数据库产品的名称。 - `String getDatabaseProductVersion() throws SQLException` - - **接口说明**：获取数据库产品的版本号 + - **接口说明**：获取数据库产品的版本号。 - `String getIdentifierQuoteString() throws SQLException` - - **接口说明**：获取用于引用 SQL 标识符的字符串 + - **接口说明**：获取用于引用 SQL 标识符的字符串。 - `String getSQLKeywords() throws SQLException` - - **接口说明**：获取数据库特有的 SQL 关键字列表 + - **接口说明**：获取数据库特有的 SQL 关键字列表。 - `String getNumericFunctions() throws SQLException` - - **接口说明**：获取数据库支持的数值函数名称列表 + - **接口说明**：获取数据库支持的数值函数名称列表。 - `String getStringFunctions() throws SQLException` - - **接口说明**：获取数据库支持的字符串函数名称列表 + - **接口说明**：获取数据库支持的字符串函数名称列表。 - `String getSystemFunctions() throws SQLException` - - **接口说明**：获取数据库支持的系统函数名称列表 + - **接口说明**：获取数据库支持的系统函数名称列表。 - `String getTimeDateFunctions() throws SQLException` - - **接口说明**：获取数据库支持的时间日期函数名称列表 + - **接口说明**：获取数据库支持的时间日期函数名称列表。 - `String getCatalogTerm() throws SQLException` - - **接口说明**：获取数据库中目录的术语 + - **接口说明**：获取数据库中目录的术语。 - `String getCatalogSeparator() throws SQLException` - - **接口说明**：获取用于分隔目录和表名的分隔符 + - **接口说明**：获取用于分隔目录和表名的分隔符。 - `int getDefaultTransactionIsolation() throws SQLException` - - **接口说明**：获取数据库的默认事务隔离级别 + - **接口说明**：获取数据库的默认事务隔离级别。 - `boolean supportsTransactionIsolationLevel(int level) throws SQLException` - - **接口说明**：判断数据库是否支持给定的事务隔离级别 + - **接口说明**：判断数据库是否支持给定的事务隔离级别。 - **参数说明**： - - `level`：事务隔离级别 - - **返回值**：`true`：支持，`false`：不支持 - - **异常**：操作失败抛出 `SQLException` 异常 + - `level`：事务隔离级别。 + - **返回值**：`true`：支持，`false`：不支持。 + - **异常**：操作失败抛出 `SQLException` 异常。 - `ResultSet getTables(String catalog, String schemaPattern, String tableNamePattern, String[] types) throws SQLException` - - **接口说明**：获取数据库中匹配指定模式的表信息 + - **接口说明**：获取数据库中匹配指定模式的表信息。 - **参数说明**： - - `catalog`：目录名称；`null` 表示不指定目录 - - `schemaPattern`：模式名称的模式；null 表示不指定模式 - - `tableNamePattern`：表名称的模式 - - `types`：表类型列表，返回指定类型的表 - - **返回值**：包含表信息的 `ResultSet` - - **异常**：操作失败抛出 `SQLException` 异常 + - `catalog`：目录名称；`null` 表示不指定目录。 + - `schemaPattern`：模式名称的模式；null 表示不指定模式。 + - `tableNamePattern`：表名称的模式。 + - `types`：表类型列表，返回指定类型的表。 + - **返回值**：包含表信息的 `ResultSet`。 + - **异常**：操作失败抛出 `SQLException` 异常。 - `ResultSet getCatalogs() throws SQLException` - - **接口说明**：获取数据库中所有目录的信息 - - **返回值**：包含目录信息的 `ResultSet` - - **异常**：操作失败抛出 `SQLException` 异常 + - **接口说明**：获取数据库中所有目录的信息。 + - **返回值**：包含目录信息的 `ResultSet`。 + - **异常**：操作失败抛出 `SQLException` 异常。 - `ResultSet getTableTypes() throws SQLException` - - **接口说明**：获取数据库支持的表类型 - - **返回值**：包含表类型的 `ResultSet` - - **异常**：操作失败抛出 `SQLException` 异常 + - **接口说明**：获取数据库支持的表类型。 + - **返回值**：包含表类型的 `ResultSet`。 + - **异常**：操作失败抛出 `SQLException` 异常。 - `ResultSet getColumns(String catalog, String schemaPattern, String tableNamePattern, String columnNamePattern) throws SQLException` - - **接口说明**：获取指定表中匹配指定模式的列信息 + - **接口说明**：获取指定表中匹配指定模式的列信息。 - **参数说明**： - - `catalog`：目录名称；`null` 表示不指定目录 - - `schemaPattern`：模式名称的模式；`null` 表示不指定模式 - - `tableNamePattern`：表名称的模式 - - `columnNamePattern`：列名称的模式 - - **返回值**：包含列信息的 `ResultSet` - - **异常**：操作失败抛出 `SQLException` 异常 + - `catalog`：目录名称；`null` 表示不指定目录。 + - `schemaPattern`：模式名称的模式；`null` 表示不指定模式。 + - `tableNamePattern`：表名称的模式。 + - `columnNamePattern`：列名称的模式。 + - **返回值**：包含列信息的 `ResultSet`。 + - **异常**：操作失败抛出 `SQLException` 异常。 - `ResultSet getPrimaryKeys(String catalog, String schema, String table) throws SQLException` - - **接口说明**：获取指定表的主键信息 + - **接口说明**：获取指定表的主键信息。 - **参数说明**： - - `catalog`：目录名称；`null` 表示不指定目录 - - `schema`：模式名称；`null` 表示不指定模式 - - `table`：表名称 - - **返回值**：包含主键信息的 `ResultSet` - - **异常**：操作失败抛出 `SQLException` 异常 + - `catalog`：目录名称；`null` 表示不指定目录。 + - `schema`：模式名称；`null` 表示不指定模式。 + - `table`：表名称。 + - **返回值**：包含主键信息的 `ResultSet`。 + - **异常**：操作失败抛出 `SQLException` 异常。 - `Connection getConnection() throws SQLException` - **接口说明**：获取数据库连接。 @@ -615,7 +604,7 @@ JDBC 驱动支持创建连接，返回支持 JDBC 标准的 `Connection` 接口 注：下面 abstract 类型接口会被具体实现类实现，因此建立连接后得到连接对象可以直接调用。 -- `public abstract void write(String[] lines, SchemalessProtocolType protocolType, SchemalessTimestampType timestampType, Integer ttl, Long reqId) throws SQLException` +- `abstract void write(String[] lines, SchemalessProtocolType protocolType, SchemalessTimestampType timestampType, Integer ttl, Long reqId) throws SQLException` - **接口说明**：以指定的协议类型、时间戳类型、TTL（生存时间）和请求 ID 写入多行数据。 - **参数说明**： - `lines`：待写入的数据行数组。 @@ -624,28 +613,28 @@ JDBC 驱动支持创建连接，返回支持 JDBC 标准的 `Connection` 接口 - `ttl`：数据的生存时间，单位天。 - `reqId`：请求 ID。 - **异常**：操作失败抛出 SQLException 异常。 -- `public void write(String[] lines, SchemalessProtocolType protocolType, SchemalessTimestampType timestampType) throws SQLException` +- `void write(String[] lines, SchemalessProtocolType protocolType, SchemalessTimestampType timestampType) throws SQLException` - **接口说明**：以指定的协议类型和时间戳类型写入多行数据。 - **参数说明**： - `lines`：待写入的数据行数组。 - `protocolType`：协议类型：支持 LINE， TELNET， JSON 三种。 - `timestampType`：时间戳类型，支持 HOURS，MINUTES，SECONDS，MILLI_SECONDS，MICRO_SECONDS 和 NANO_SECONDS。 - **异常**：操作失败抛出 SQLException 异常。 -- `public void write(String line, SchemalessProtocolType protocolType, SchemalessTimestampType timestampType) throws SQLException` +- `void write(String line, SchemalessProtocolType protocolType, SchemalessTimestampType timestampType) throws SQLException` - **接口说明**：以指定的协议类型和时间戳类型写入单行数据。 - **参数说明**： - `line`：待写入的数据行。 - `protocolType`：协议类型：支持 LINE， TELNET， JSON 三种。 - `timestampType`：时间戳类型，支持 HOURS，MINUTES，SECONDS，MILLI_SECONDS，MICRO_SECONDS 和 NANO_SECONDS。 - **异常**：操作失败抛出 SQLException 异常。 -- `public void write(List lines, SchemalessProtocolType protocolType, SchemalessTimestampType timestampType) throws SQLException` +- `void write(List lines, SchemalessProtocolType protocolType, SchemalessTimestampType timestampType) throws SQLException` - **接口说明**：以指定的协议类型和时间戳类型写入多行数据（使用列表）。 - **参数说明**： - `lines`：待写入的数据行列表。 - `protocolType`：协议类型：支持 LINE， TELNET， JSON 三种。 - `timestampType`：时间戳类型，支持 HOURS，MINUTES，SECONDS，MILLI_SECONDS，MICRO_SECONDS 和 NANO_SECONDS。 - **异常**：操作失败抛出 SQLException 异常。 -- `public int writeRaw(String line, SchemalessProtocolType protocolType, SchemalessTimestampType timestampType) throws SQLException` +- `int writeRaw(String line, SchemalessProtocolType protocolType, SchemalessTimestampType timestampType) throws SQLException` - **接口说明**：以指定的协议类型和时间戳类型写入多行回车符分割的原始数据，回车符分割，并返回操作结果。 - **参数说明**： - `line`：待写入的原始数据。 @@ -653,7 +642,7 @@ JDBC 驱动支持创建连接，返回支持 JDBC 标准的 `Connection` 接口 - `timestampType`：时间戳类型，支持 HOURS，MINUTES，SECONDS，MILLI_SECONDS，MICRO_SECONDS 和 NANO_SECONDS。 - **返回值**：操作结果。 - **异常**：操作失败抛出 SQLException 异常。 -- `public abstract int writeRaw(String line, SchemalessProtocolType protocolType, SchemalessTimestampType timestampType, Integer ttl, Long reqId) throws SQLException` +- `abstract int writeRaw(String line, SchemalessProtocolType protocolType, SchemalessTimestampType timestampType, Integer ttl, Long reqId) throws SQLException` - **接口说明**：以指定的协议类型、时间戳类型、TTL（生存时间）和请求 ID 写入多行回车符分割的原始数据，并返回操作结果。 - **参数说明**： - `line`：待写入的原始数据。 @@ -1270,35 +1259,35 @@ ParameterMetaData 提供了参数元数据接口： #### 扩展接口 -- `public void setTableName(String name) throws SQLException` +- `void setTableName(String name) throws SQLException` - **接口说明**：设置当前操作的表名。 - **参数说明**： - `name`：一个 String 类型的参数，表示要绑定的表名。 -- `public void setTagNull(int index, int type)` +- `void setTagNull(int index, int type)` - **接口说明**：为指定索引的标签设置 null 值。 - **参数说明**： - `index`：标签的索引位置。 - `type`：标签的数据类型。 -- `public void setTagBoolean(int index, boolean value)` +- `void setTagBoolean(int index, boolean value)` - **接口说明**：为指定索引的标签设置布尔值。 - **参数说明**： - `index`：标签的索引位置。 - `value`：要设置的布尔值。 - 下面接口除了要设置的值类型不同外，其余同 setTagBoolean，不再赘述： - - `public void setTagInt(int index, int value)` - - `public void setTagByte(int index, byte value)` - - `public void setTagShort(int index, short value)` - - `public void setTagLong(int index, long value)` - - `public void setTagTimestamp(int index, long value)` - - `public void setTagFloat(int index, float value)` - - `public void setTagDouble(int index, double value)` - - `public void setTagString(int index, String value)` - - `public void setTagNString(int index, String value)` - - `public void setTagJson(int index, String value)` - - `public void setTagVarbinary(int index, byte[] value)` - - `public void setTagGeometry(int index, byte[] value)` + - `void setTagInt(int index, int value)` + - `void setTagByte(int index, byte value)` + - `void setTagShort(int index, short value)` + - `void setTagLong(int index, long value)` + - `void setTagTimestamp(int index, long value)` + - `void setTagFloat(int index, float value)` + - `void setTagDouble(int index, double value)` + - `void setTagString(int index, String value)` + - `void setTagNString(int index, String value)` + - `void setTagJson(int index, String value)` + - `void setTagVarbinary(int index, byte[] value)` + - `void setTagGeometry(int index, byte[] value)` -- `public void setInt(int columnIndex, ArrayList list) throws SQLException` +- `void setInt(int columnIndex, ArrayList list) throws SQLException` - **接口说明**：为指定列索引设置批量整型值。 - **参数说明**： - `columnIndex`：列的索引位置。 @@ -1306,14 +1295,14 @@ ParameterMetaData 提供了参数元数据接口： - **异常**： - 如果操作过程中发生错误，将抛出 SQLException 异常。 - 下面接口除了要设置的值类型不同外，其余同 setInt： - - `public void setFloat(int columnIndex, ArrayList list) throws SQLException` - - `public void setTimestamp(int columnIndex, ArrayList list) throws SQLException` - - `public void setLong(int columnIndex, ArrayList list) throws SQLException` - - `public void setDouble(int columnIndex, ArrayList list) throws SQLException` - - `public void setBoolean(int columnIndex, ArrayList list) throws SQLException` - - `public void setByte(int columnIndex, ArrayList list) throws SQLException` - - `public void setShort(int columnIndex, ArrayList list) throws SQLException` -- `public void setString(int columnIndex, ArrayList list, int size) throws SQLException` + - `void setFloat(int columnIndex, ArrayList list) throws SQLException` + - `void setTimestamp(int columnIndex, ArrayList list) throws SQLException` + - `void setLong(int columnIndex, ArrayList list) throws SQLException` + - `void setDouble(int columnIndex, ArrayList list) throws SQLException` + - `void setBoolean(int columnIndex, ArrayList list) throws SQLException` + - `void setByte(int columnIndex, ArrayList list) throws SQLException` + - `void setShort(int columnIndex, ArrayList list) throws SQLException` +- `void setString(int columnIndex, ArrayList list, int size) throws SQLException` - **接口说明**：为指定列索引设置字符串值列表。 - **参数说明**： - `columnIndex`：列的索引位置。 @@ -1322,9 +1311,9 @@ ParameterMetaData 提供了参数元数据接口： - **异常**： - 如果操作过程中发生错误，将抛出 SQLException 异常。 - 下面接口除了要设置的值类型不同外，其余同 setString： - - `public void setVarbinary(int columnIndex, ArrayList list, int size) throws SQLException` - - `public void setGeometry(int columnIndex, ArrayList list, int size) throws SQLException` - - `public void setNString(int columnIndex, ArrayList list, int size) throws SQLException` + - `void setVarbinary(int columnIndex, ArrayList list, int size) throws SQLException` + - `void setGeometry(int columnIndex, ArrayList list, int size) throws SQLException` + - `void setNString(int columnIndex, ArrayList list, int size) throws SQLException` - `void columnDataAddBatch() throws SQLException` - **接口说明**：将 `setInt（int columnIndex， ArrayList list）` 等数组形式接口设置的数据添加到当前 PrepareStatement 对象的批处理中。 - **异常**： @@ -1348,97 +1337,93 @@ JDBC 标准不支持数据订阅，因此本章所有接口都是扩展接口。 - **异常**：如果创建失败，抛出 SQLException 异常。 创建消费者支持属性列表： +- td.connect.type: 连接方式。jni：表示使用动态库连接的方式，ws/WebSocket：表示使用 WebSocket 进行数据通信。默认为 jni 方式。 +- bootstrap.servers: TDengine 服务端所在的`ip:port`，如果使用 WebSocket 连接，则为 taosAdapter 所在的`ip:port`。 +- enable.auto.commit: 是否允许自动提交。 +- group.id: consumer: 所在的 group。 +- value.deserializer: 结果集反序列化方法，可以继承 `com.taosdata.jdbc.tmq.ReferenceDeserializer`，并指定结果集 bean，实现反序列化。也可以继承 `com.taosdata.jdbc.tmq.Deserializer`，根据 SQL 的 resultSet 自定义反序列化方式。 +- httpConnectTimeout: 创建连接超时参数，单位 ms，默认为 5000 ms。仅在 WebSocket 连接下有效。 +- messageWaitTimeout: 数据传输超时参数，单位 ms，默认为 10000 ms。仅在 WebSocket 连接下有效。 +- httpPoolSize: 同一个连接下最大并行请求数。仅在 WebSocket 连接下有效。 +- TSDBDriver.PROPERTY_KEY_ENABLE_COMPRESSION: 传输过程是否启用压缩。仅在使用 Websocket 连接时生效。true: 启用，false: 不启用。默认为 false。 +- TSDBDriver.PROPERTY_KEY_ENABLE_AUTO_RECONNECT: 是否启用自动重连。仅在使用 Websocket 连接时生效。true: 启用，false: 不启用。默认为 false。 +- TSDBDriver.PROPERTY_KEY_RECONNECT_INTERVAL_MS: 自动重连重试间隔，单位毫秒，默认值 2000。仅在 PROPERTY_KEY_ENABLE_AUTO_RECONNECT 为 true 时生效。 +- TSDBDriver.PROPERTY_KEY_RECONNECT_RETRY_COUNT: 自动重连重试次数，默认值 3，仅在 PROPERTY_KEY_ENABLE_AUTO_RECONNECT 为 true 时生效。 - -| 属性 | 描述 | 默认值 | -| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -| td.connect.type | 连接方式。jni：表示使用动态库连接的方式，ws/WebSocket：表示使用 WebSocket 进行数据通信。 | jni | -| bootstrap.servers | TDengine 服务端所在的ip:port，如果使用 WebSocket 连接，则为 taosAdapter 所在的ip:port。 | | -| enable.auto.commit | 是否允许自动提交。 | | -| group.id | consumer 所在的 group。 | | -| value.deserializer | 结果集反序列化方法。可以继承 com.taosdata.jdbc.tmq.ReferenceDeserializer，并指定结果集 bean，实现反序列化。也可以继承 com.taosdata.jdbc.tmq.Deserializer，根据 SQL 的 resultSet 自定义反序列化方式。 | | -| httpConnectTimeout | 创建连接超时参数，单位 ms。仅在 WebSocket 连接下有效。 | 5000 ms | -| messageWaitTimeout | 数据传输超时参数，单位 ms。仅在 WebSocket 连接下有效。 | 10000 ms | -| httpPoolSize | 同一个连接下最大并行请求数。仅在 WebSocket 连接下有效。 | | -| enableCompression | 传输过程是否启用压缩。仅在使用 Websocket 连接时生效。true: 启用，false: 不启用。 | false | -| enableAutoReconnect | 是否启用自动重连。仅在使用 Websocket 连接时生效。true: 启用，false: 不启用。 | false | -| reconnectIntervalMs | 自动重连重试间隔，单位毫秒。仅在 enableCompression 为 true 时生效。 | 2000 ms | -| reconnectRetryCount | 自动重连重试次数。仅在 enableCompression 为 true 时生效。 | 3 | - 其他参数请参考：[Consumer 参数列表](../../../develop/tmq/#创建参数)， 注意TDengine服务端自 3.2.0.0 版本开始消息订阅中的 auto.offset.reset 默认值发生变化。 -- `public void subscribe(Collection topics) throws SQLException` +- `void subscribe(Collection topics) throws SQLException` - **接口说明**：订阅一组主题。 - **参数说明**： - `topics`：一个 `Collection` 类型的参数，表示要订阅的主题列表。 - **异常**：如果在订阅过程中发生错误，将抛出 SQLException 异常。 -- `public void unsubscribe() throws SQLException` +- `void unsubscribe() throws SQLException` - **接口说明**：取消订阅所有主题。 - **异常**：如果在取消订阅过程中发生错误，将抛出 SQLException 异常。 -- `public Set subscription() throws SQLException` +- `Set subscription() throws SQLException` - **接口说明**：获取当前订阅的所有主题。 - **返回值**：返回值类型为 `Set`，即当前订阅的所有主题集合。 - **异常**：如果在获取订阅信息过程中发生错误，将抛出 SQLException 异常。 -- `public ConsumerRecords poll(Duration timeout) throws SQLException` +- `ConsumerRecords poll(Duration timeout) throws SQLException` - **接口说明**：轮询消息。 - **参数说明**： - `timeout`：一个 `Duration` 类型的参数，表示轮询的超时时间。 - **返回值**：返回值类型为 `ConsumerRecords`，即轮询到的消息记录。 - **异常**：如果在轮询过程中发生错误，将抛出 SQLException 异常。 -- `public void commitAsync() throws SQLException` +- `void commitAsync() throws SQLException` - **接口说明**：异步提交当前处理的消息的偏移量。 - **异常**：如果在提交过程中发生错误，将抛出 SQLException 异常。 -- `public void commitSync() throws SQLException` +- `void commitSync() throws SQLException` - **接口说明**：同步提交当前处理的消息的偏移量。 - **异常**：如果在提交过程中发生错误，将抛出 SQLException 异常。 -- `public void close() throws SQLException` +- `void close() throws SQLException` - **接口说明**：关闭消费者，释放资源。 - **异常**：如果在关闭过程中发生错误，将抛出 SQLException 异常。 -- `public void seek(TopicPartition partition, long offset) throws SQLException` +- `void seek(TopicPartition partition, long offset) throws SQLException` - **接口说明**：将给定分区的偏移量设置到指定的位置。 - **参数说明**： - `partition`：一个 `TopicPartition` 类型的参数，表示要操作的分区。 - `offset`：一个 `long` 类型的参数，表示要设置的偏移量。 - **异常**：如果在设置偏移量过程中发生错误，将抛出 SQLException 异常。 -- `public long position(TopicPartition tp) throws SQLException` +- `long position(TopicPartition tp) throws SQLException` - **接口说明**：获取给定分区当前的偏移量。 - **参数说明**： - `tp`：一个 `TopicPartition` 类型的参数，表示要查询的分区。 - **返回值**：返回值类型为 `long`，即给定分区当前的偏移量。 - **异常**：如果在获取偏移量过程中发生错误，将抛出 SQLException 异常。 -- `public Map beginningOffsets(String topic) throws SQLException` +- `Map beginningOffsets(String topic) throws SQLException` - **接口说明**：获取指定主题的每个分区的最早偏移量。 - **参数说明**： - `topic`：一个 `String` 类型的参数，表示要查询的主题。 - **返回值**：返回值类型为 `Map`，即指定主题的每个分区的最早偏移量。 - **异常**：如果在获取最早偏移量过程中发生错误，将抛出 SQLException 异常。 -- `public Map endOffsets(String topic) throws SQLException` +- `Map endOffsets(String topic) throws SQLException` - **接口说明**：获取指定主题的每个分区的最新偏移量。 - **参数说明**： - `topic`：一个 `String` 类型的参数，表示要查询的主题。 - **返回值**：返回值类型为 `Map`，即指定主题的每个分区的最新偏移量。 - **异常**：如果在获取最新偏移量过程中发生错误，将抛出 SQLException 异常。 -- `public void seekToBeginning(Collection partitions) throws SQLException` +- `void seekToBeginning(Collection partitions) throws SQLException` - **接口说明**：将一组分区的偏移量设置到最早的偏移量。 - **参数说明**： - `partitions`：一个 `Collection` 类型的参数，表示要操作的分区集合。 - **异常**：如果在设置偏移量过程中发生错误，将抛出 SQLException 异常。 -- `public void seekToEnd(Collection partitions) throws SQLException` +- `void seekToEnd(Collection partitions) throws SQLException` - **接口说明**：将一组分区的偏移量设置到最新的偏移量。 - **参数说明**： - `partitions`：一个 `Collection` 类型的参数，表示要操作的分区集合。 - **异常**：如果在设置偏移量过程中发生错误，将抛出 SQLException 异常。 -- `public Set assignment() throws SQLException` +- `Set assignment() throws SQLException` - **接口说明**：获取消费者当前分配的所有分区。 - **返回值**：返回值类型为 `Set`，即消费者当前分配的所有分区。 - **异常**：如果在获取分配的分区过程中发生错误，将抛出 SQLException 异常。 -- `public OffsetAndMetadata committed(TopicPartition partition) throws SQLException` +- `OffsetAndMetadata committed(TopicPartition partition) throws SQLException` - **接口说明**：获取指定分区最后提交的偏移量。 - **参数说明**： - `partition`：一个 `TopicPartition` 类型的参数，表示要查询的分区。 - **返回值**：返回值类型为 `OffsetAndMetadata`，即指定分区最后提交的偏移量。 - **异常**：如果在获取提交的偏移量过程中发生错误，将抛出 SQLException 异常。 -- `public Map committed(Set partitions) throws SQLException` +- `Map committed(Set partitions) throws SQLException` - **接口说明**：获取一组分区最后提交的偏移量。 - **参数说明**： - `partitions`：一个 `Set` 类型的参数，表示要查询的分区集合。 @@ -1451,19 +1436,19 @@ ConsumerRecords 类提供了消费记录信息，可以迭代 ConsumerRecord 对 ConsumerRecord 提供的接口： -- `public String getTopic()` +- `String getTopic()` - **接口说明**：获取消息的主题。 - **返回值**：返回值类型为 `String`，即消息的主题。 -- `public String getDbName()` +- `String getDbName()` - **接口说明**：获取数据库名称。 - **返回值**：返回值类型为 `String`，即数据库名称。 -- `public int getVGroupId()` +- `int getVGroupId()` - **接口说明**：获取虚拟组 ID。 - **返回值**：返回值类型为 `int`，即虚拟组 ID。 -- `public V value()` +- `V value()` - **接口说明**：获取消息的值。 - **返回值**：返回值类型为 `V`，即消息的值。 -- `public long getOffset()` +- `long getOffset()` - **接口说明**：获取消息的偏移量。 - **返回值**：返回值类型为 `long`，即消息的偏移量。 @@ -1471,15 +1456,15 @@ ConsumerRecord 提供的接口： TopicPartition 类提供了分区信息，包含消息主题和虚拟组 ID。 -- `public TopicPartition(String topic, int vGroupId)` +- `TopicPartition(String topic, int vGroupId)` - **接口说明**：构造一个新的 TopicPartition 实例，用于表示一个特定的主题和虚拟组 ID。 - **参数说明**： - `topic`：一个 `String` 类型的参数，表示消息的主题。 - `vGroupId`：一个 `int` 类型的参数，表示虚拟组 ID。 -- `public String getTopic()` +- `String getTopic()` - **接口说明**：获取此 TopicPartition 实例的主题。 - **返回值**：返回值类型为 `String`，即此 TopicPartition 实例的主题。 -- `public int getVGroupId()` +- `int getVGroupId()` - **接口说明**：获取此 TopicPartition 实例的虚拟组 ID。 - **返回值**：返回值类型为 `int`，即此 TopicPartition 实例的虚拟组 ID。 @@ -1487,10 +1472,10 @@ TopicPartition 类提供了分区信息，包含消息主题和虚拟组 ID。 OffsetAndMetadata 类提供了偏移量元数据信息。 -- `public long offset()` +- `long offset()` - **接口说明**：获取此 OffsetAndMetadata 实例中的偏移量。 - **返回值**：返回值类型为 `long`，即此 OffsetAndMetadata 实例中的偏移量。 -- `public String metadata()` +- `String metadata()` - **接口说明**：获取此 OffsetAndMetadata 实例中的元数据。 - **返回值**：返回值类型为 `String`，即此 OffsetAndMetadata 实例中的元数据。 diff --git a/docs/zh/14-reference/05-connector/20-go.mdx b/docs/zh/14-reference/05-connector/20-go.mdx index 0c3dfa6681..c53f681f06 100644 --- a/docs/zh/14-reference/05-connector/20-go.mdx +++ b/docs/zh/14-reference/05-connector/20-go.mdx @@ -1065,7 +1065,7 @@ type ConfigMap map[string]ConfigValue - `ws.reconnectIntervalMs`：WebSocket 重连间隔时间毫秒，默认 2000。 - `ws.reconnectRetryCount`：WebSocket 重连重试次数，默认 3。 -其他参数请参考：[Consumer 参数列表](../../develop/tmq/#数据订阅相关参数)， 注意TDengine服务端自 3.2.0.0 版本开始消息订阅中的 auto.offset.reset 默认值发生变化。 +其他参数请参考：[Consumer 参数列表](../../../develop/tmq/#数据订阅相关参数)， 注意TDengine服务端自 3.2.0.0 版本开始消息订阅中的 auto.offset.reset 默认值发生变化。 - `func (c *Consumer) Subscribe(topic string, rebalanceCb RebalanceCb) error` - **接口说明**：订阅主题。 diff --git a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/AbsWsConsumerLoop.java b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/AbsWsConsumerLoop.java index 690c05841c..60466629f6 100644 --- a/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/AbsWsConsumerLoop.java +++ b/examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/AbsWsConsumerLoop.java @@ -30,8 +30,8 @@ config.setProperty("auto.offset.reset", "latest"); config.setProperty("msg.with.table.name", "true"); config.setProperty("enable.auto.commit", "true"); config.setProperty("auto.commit.interval.ms", "1000"); -config.setProperty("group.id", "group2"); -config.setProperty("client.id", "1"); +config.setProperty("group.id", "group1"); +config.setProperty("client.id", "client1"); config.setProperty("value.deserializer", "com.taosdata.example.AbsConsumerLoopWs$ResultDeserializer"); config.setProperty("value.deserializer.encoding", "UTF-8");