Merge branch 'docs/wade-3.0-jdbc' into docs/wade-3.0-shibin
This commit is contained in:
menshibin
commit
7d0d105656
|
|
@ -20,13 +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
|
||||
System.out.println("SQLException: " + ex.getMessage());
|
||||
// handle any errors, please refer to the JDBC specifications for detailed exceptions info
|
||||
System.out.println("Failed to connect to " + jdbcUrl + "; ErrCode:" + ex.getErrorCode() + "; ErrMessage: " + ex.getMessage());
|
||||
}
|
||||
}
|
||||
// ANCHOR_END: main
|
||||
|
|
|
|||
|
|
@ -9,13 +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
|
||||
System.out.println("SQLException: " + ex.getMessage());
|
||||
// handle any errors, please refer to the JDBC specifications for detailed exceptions info
|
||||
System.out.println("Failed to connect to " + jdbcUrl + "; ErrCode:" + ex.getErrorCode() + "; ErrMessage: " + ex.getMessage());
|
||||
}
|
||||
}
|
||||
// ANCHOR_END: main
|
||||
|
|
|
|||
|
|
@ -16,14 +16,18 @@ 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");
|
||||
System.out.println("Connected to " + jdbcUrl + " successfully.");
|
||||
|
||||
// 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("Failed to connect to " + jdbcUrl + "; ErrCode:" + ex.getErrorCode() + "; ErrMessage: " + ex.getMessage());
|
||||
}
|
||||
}
|
||||
// ANCHOR_END: main
|
||||
|
|
|
|||
|
|
@ -312,66 +312,16 @@ phpize && ./configure --enable-swoole && make -j && make install
|
|||
|
||||
在执行这一步之前，请确保有一个正在运行的，且可以访问到的 TDengine，而且服务端的 FQDN 配置正确。以下示例代码，都假设 TDengine 安装在本机，且 FQDN（默认 localhost） 和 serverPort（默认 6030） 都使用默认配置。
|
||||
### 连接参数
|
||||
连接的配置项较多，因此在建立连接之前，我们能先介绍一下各语言连接器建立连接使用的参数。
|
||||
|
||||
<Tabs defaultValue="java" groupId="lang">
|
||||
<TabItem label="Java" value="java">
|
||||
|
||||
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：逐行拉取结果集。默认值为：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 连接中不生效。
|
||||
|
||||
|
||||
除了通过指定的 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` 语句切换数据库无效。
|
||||
|
||||
- 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。
|
||||
|
||||
**配置参数的优先级：**
|
||||
|
||||
通过前面三种方式获取连接，如果配置参数在 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-规范)
|
||||
|
||||
</TabItem>
|
||||
<TabItem label="Python" value="python">
|
||||
|
|
@ -392,6 +342,7 @@ properties 中的配置参数如下：
|
|||
</Tabs>
|
||||
|
||||
### Websocket 连接
|
||||
下面是各语言连接器建立 Websocket 连接代码样例。演示了如何使用 Websocket 连接方式连接到 TDengine 数据库，并对连接设定一些参数。整个过程主要涉及到数据库连接的建立和异常处理。
|
||||
|
||||
<Tabs defaultValue="java" groupId="lang">
|
||||
<TabItem label="Java" value="java">
|
||||
|
|
@ -431,6 +382,8 @@ properties 中的配置参数如下：
|
|||
</Tabs>
|
||||
|
||||
### 原生连接
|
||||
下面是各语言连接器建立原生连接代码样例。演示了如何使用原生连接方式连接到 TDengine 数据库，并对连接设定一些参数。整个过程主要涉及到数据库连接的建立和异常处理。
|
||||
|
||||
<Tabs defaultValue="java" groupId="lang">
|
||||
<TabItem label="Java" value="java">
|
||||
```java
|
||||
|
|
@ -462,6 +415,8 @@ properties 中的配置参数如下：
|
|||
</Tabs>
|
||||
|
||||
### REST 连接
|
||||
下面是各语言连接器建立 RESt 连接代码样例。演示了如何使用 REST 连接方式连接到 TDengine 数据库。整个过程主要涉及到数据库连接的建立和异常处理。
|
||||
|
||||
<Tabs defaultValue="java" groupId="lang">
|
||||
<TabItem label="Java" value="java">
|
||||
```java
|
||||
|
|
|
|||
|
|
@ -11,9 +11,9 @@ TDengine 对 SQL 语言提供了全面的支持，允许用户以熟悉的 SQL
|
|||
|
||||
下面介绍使用各语言连接器通过执行 SQL 完成建库、建表、写入数据和查询数据。
|
||||
|
||||
|
||||
## 建库和表
|
||||
以智能电表为例，展示如何使用连接器执行 SQL 来创建数据库和表。
|
||||
下面以智能电表为例，展示使用各语言连接器如何执行 SQL 命令创建一个名为 `power` 的数据库，然后使用 `power` 数据库为默认数据库。
|
||||
接着创建一个名为 `meters` 的超级表（STABLE），其表结构包含时间戳、电流、电压、相位等列，以及分组 ID 和位置作为标签。
|
||||
|
||||
<Tabs defaultValue="java" groupId="lang">
|
||||
<TabItem value="java" label="Java">
|
||||
|
|
@ -41,7 +41,7 @@ TDengine 对 SQL 语言提供了全面的支持，允许用户以熟悉的 SQL
|
|||
</Tabs>
|
||||
|
||||
## 插入数据
|
||||
以智能电表为例，展示如何使用连接器执行 SQL 来插入数据。
|
||||
下面以智能电表为例，展示如何使用连接器执行 SQL 来插入数据到 `power` 数据库的 `meters` 超级表。样例使用 TDengine 自动建表 SQL 语法，写入 d1001 子表中 3 条数据，写入 d1002 子表中 1 条数据，然后打印出实际插入数据条数。
|
||||
|
||||
<Tabs defaultValue="java" groupId="lang">
|
||||
<TabItem value="java" label="Java">
|
||||
|
|
@ -70,9 +70,8 @@ NOW 为系统内部函数，默认为客户端所在计算机当前时间。 NOW
|
|||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
|
||||
## 查询数据
|
||||
以智能电表为例，展示如何使用各语言连接器执行 SQL 来查询数据，并将获取到的结果打印出来。
|
||||
下面以智能电表为例，展示如何使用各语言连接器执行 SQL 来查询数据，从 `power` 数据库 `meters` 超级表中查询最多 100 行数据，并将获取到的结果按行打印出来。
|
||||
|
||||
<Tabs defaultValue="java" groupId="lang">
|
||||
<TabItem label="Java" value="java">
|
||||
|
|
@ -100,7 +99,6 @@ NOW 为系统内部函数，默认为客户端所在计算机当前时间。 NOW
|
|||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
|
||||
## 执行带有 reqId 的 SQL
|
||||
|
||||
reqId 可用于请求链路追踪，reqId 就像分布式系统中的 traceId 作用一样。一个请求可能需要经过多个服务或者模块才能完成。reqId 用于标识和关联这个请求的所有相关操作，以便于我们可以追踪和分析请求的完整路径。
|
||||
|
|
|
|||
|
|
@ -153,12 +153,17 @@ 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 连接
|
||||
|
||||
<Tabs defaultValue="java" groupId="schemaless">
|
||||
<TabItem value="java" label="Java">
|
||||
|
||||
|
||||
```java
|
||||
{{#include examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/SchemalessWsTest.java:schemaless}}
|
||||
```
|
||||
|
|
@ -190,9 +195,9 @@ writer.write(lineDemo, SchemalessProtocolType.LINE, SchemalessTimestampType.NANO
|
|||
### 原生连接
|
||||
<Tabs defaultValue="java" groupId="lang">
|
||||
<TabItem label="Java" value="java">
|
||||
```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 +224,29 @@ writer.write(lineDemo, SchemalessProtocolType.LINE, SchemalessTimestampType.NANO
|
|||
</Tabs>
|
||||
|
||||
|
||||
### REST 连接
|
||||
<Tabs defaultValue="java" groupId="lang">
|
||||
<TabItem label="Java" value="java">
|
||||
不支持
|
||||
</TabItem>
|
||||
<TabItem label="Python" value="python">
|
||||
</TabItem>
|
||||
<TabItem label="Go" value="go">
|
||||
</TabItem>
|
||||
<TabItem label="Rust" value="rust">
|
||||
</TabItem>
|
||||
<TabItem label="C#" value="csharp">
|
||||
</TabItem>
|
||||
<TabItem label="R" value="r">
|
||||
</TabItem>
|
||||
<TabItem label="C" value="c">
|
||||
</TabItem>
|
||||
<TabItem label="PHP" value="php">
|
||||
</TabItem>
|
||||
|
||||
</Tabs>
|
||||
|
||||
|
||||
## 查询写入的数据
|
||||
|
||||
运行上节的样例代码，会在 power 数据库中自动建表，我们可以通过 taos shell 或者应用程序来查询数据。下面给出用 taos shell 查询超级表和 meters 表数据的样例。
|
||||
|
|
|
|||
|
|
@ -13,7 +13,14 @@ import TabItem from "@theme/TabItem";
|
|||
- 预编译：当使用参数绑定时，SQL 语句可以被预编译并缓存，后续使用不同的参数值执行时，可以直接使用预编译的版本，提高执行效率。
|
||||
- 减少网络开销：参数绑定还可以减少发送到数据库的数据量，因为只需要发送参数值而不是完整的 SQL 语句，特别是在执行大量相似的插入或更新操作时，这种差异尤为明显。
|
||||
|
||||
下面我们继续以智能电表为例，展示各语言连接器使用参数绑定高效写入的功能。
|
||||
下面我们继续以智能电表为例，展示各语言连接器使用参数绑定高效写入的功能：
|
||||
1. 准备一个参数化的 SQL 插入语句，用于向超级表 `meters` 中插入数据。这个语句允许动态地指定子表名、标签和列值。
|
||||
2. 循环生成多个子表及其对应的数据行。对于每个子表：
|
||||
- 设置子表的名称和标签值（分组 ID 和位置）。
|
||||
- 生成多行数据，每行包括一个时间戳、随机生成的电流、电压和相位值。
|
||||
- 执行批量插入操作，将这些数据行插入到对应的子表中。
|
||||
3. 最后打印实际插入表中的行数。
|
||||
|
||||
## Websocket 连接
|
||||
<Tabs defaultValue="java" groupId="lang">
|
||||
<TabItem value="java" label="Java">
|
||||
|
|
|
|||
|
|
@ -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,30 +26,29 @@ TDengine 消费者的概念跟 Kafka 类似，消费者通过订阅主题来接
|
|||
|
||||
|
||||
### 创建参数
|
||||
创建消费者的参数较多，非常灵活的支持了各种连接类型、 Offset 提交方式、压缩、重连、反序列化等特性。各语言连接器都适用的通用基础配置项如下表所示：
|
||||
|
||||
| 参数名称 | 类型 | 参数说明 | 备注 |
|
||||
| :-----------------------: | :-----: | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `td.connect.ip` | string | 服务端的 IP 地址 | |
|
||||
| `td.connect.user` | string | 用户名 | |
|
||||
| `td.connect.pass` | string | 密码 | |
|
||||
| `td.connect.port` | integer | 服务端的端口号 | |
|
||||
| `group.id` | string | 消费组 ID，同一消费组共享消费进度 | <br />**必填项**。最大长度：192。<br />每个topic最多可建立100个 consumer group |
|
||||
| `client.id` | string | 客户端 ID | 最大长度：192。 |
|
||||
| `auto.offset.reset` | enum | 消费组订阅的初始位置 | <br />`earliest`: default(version < 3.2.0.0);从头开始订阅; <br/>`latest`: default(version >= 3.2.0.0);仅从最新数据开始订阅; <br/>`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 | 是否开启数据回放功能 | 默认关闭 |
|
||||
|
||||
|
||||
下面是各语言连接器创建参数：
|
||||
<Tabs defaultValue="java" groupId="lang">
|
||||
<TabItem value="java" label="Java">
|
||||
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 连接方式为例介绍数据订阅的其他功能。
|
||||
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
<TabItem label="Python" value="python">
|
||||
|
|
@ -79,6 +78,8 @@ Java 连接器创建消费者的参数为 Properties， 可以设置如下参数
|
|||
</Tabs>
|
||||
|
||||
### Websocket 连接
|
||||
介绍各语言连接器使用 Websocket 连接方式创建消费者。指定连接的服务器地址，设置自动提交，从最新消息开始消费，指定 `group.id` 和 `client.id` 等信息。有的语言的连接器还支持反序列化参数。
|
||||
|
||||
<Tabs defaultValue="java" groupId="lang">
|
||||
<TabItem value="java" label="Java">
|
||||
|
||||
|
|
@ -126,6 +127,9 @@ Java 连接器创建消费者的参数为 Properties， 可以设置如下参数
|
|||
|
||||
|
||||
### 原生连接
|
||||
介绍各语言连接器使用原生连接方式创建消费者。指定连接的服务器地址，设置自动提交，从最新消息开始消费，指定 `group.id` 和 `client.id` 等信息。有的语言的连接器还支持反序列化参数。
|
||||
|
||||
|
||||
<Tabs groupId="lang">
|
||||
<TabItem value="java" label="Java">
|
||||
|
||||
|
|
@ -269,20 +273,27 @@ Java 连接器创建消费者的参数为 Properties， 可以设置如下参数
|
|||
<TabItem value="java" label="Java">
|
||||
|
||||
```java
|
||||
// 获取订阅的 topicPartition
|
||||
Set<TopicPartition assignment() throws SQLException;
|
||||
|
||||
// 获取 offset
|
||||
long position(TopicPartition partition) throws SQLException;
|
||||
Map<TopicPartition, Long position(String topic) throws SQLException;
|
||||
Map<TopicPartition, Long beginningOffsets(String topic) throws SQLException;
|
||||
Map<TopicPartition, Long endOffsets(String topic) throws SQLException;
|
||||
Map<TopicPartition, OffsetAndMetadata committed(Set<TopicPartition partitions) throws SQLException;
|
||||
// 获取当前消费者分配的 TopicPartition 集合
|
||||
Set<TopicPartition> assignment() throws SQLException;
|
||||
|
||||
// 指定下一次 poll 中使用的 offset
|
||||
// 获取指定分区的当前偏移量
|
||||
long position(TopicPartition partition) throws SQLException;
|
||||
// 获取指定主题的所有分区的当前偏移量
|
||||
Map<TopicPartition, Long> position(String topic) throws SQLException;
|
||||
// 获取指定主题的所有分区的起始偏移量
|
||||
Map<TopicPartition, Long> beginningOffsets(String topic) throws SQLException;
|
||||
// 获取指定主题的所有分区的最新偏移量
|
||||
Map<TopicPartition, Long> endOffsets(String topic) throws SQLException;
|
||||
// 获取指定分区集合中的已提交偏移量
|
||||
Map<TopicPartition, OffsetAndMetadata> committed(Set<TopicPartition> partitions) throws SQLException;
|
||||
|
||||
// 设置指定分区的偏移量
|
||||
void seek(TopicPartition partition, long offset) throws SQLException;
|
||||
void seekToBeginning(Collection<TopicPartition partitions) throws SQLException;
|
||||
void seekToEnd(Collection<TopicPartition partitions) throws SQLException;
|
||||
// 将指定分区集合的偏移量设置为最开始
|
||||
void seekToBeginning(Collection<TopicPartition> partitions) throws SQLException;
|
||||
// 将指定分区集合的偏移量设置为最新
|
||||
void seekToEnd(Collection<TopicPartition> partitions) throws SQLException;
|
||||
```
|
||||
|
||||
示例代码：
|
||||
|
|
@ -379,11 +390,16 @@ void seekToEnd(Collection<TopicPartition partitions) throws SQLException;
|
|||
<TabItem value="java" label="Java">
|
||||
|
||||
```java
|
||||
void commitSync() throws SQLException;
|
||||
void commitSync(Map<TopicPartition, OffsetAndMetadata offsets) throws SQLException;
|
||||
// 同步提交当前消费者的偏移量
|
||||
void commitSync() throws SQLException;
|
||||
// 同步提交指定的偏移量
|
||||
void commitSync(Map<TopicPartition, OffsetAndMetadata> offsets) throws SQLException;
|
||||
|
||||
// 异步提交仅在 native 连接下有效
|
||||
void commitAsync(OffsetCommitCallback<V callback) throws SQLException;
|
||||
void commitAsync(Map<TopicPartition, OffsetAndMetadata offsets, OffsetCommitCallback<V callback) throws SQLException;
|
||||
// 异步提交当前消费者的偏移量，需要提供回调以处理可能的提交结果
|
||||
void commitAsync(OffsetCommitCallback<V> callback) throws SQLException;
|
||||
// 异步提交指定的偏移量，需要提供回调以处理可能的提交结果
|
||||
void commitAsync(Map<TopicPartition, OffsetAndMetadata> offsets, OffsetCommitCallback<V> callback) throws SQLException;
|
||||
```
|
||||
|
||||
|
||||
|
|
@ -581,7 +597,8 @@ void commitAsync(Map<TopicPartition, OffsetAndMetadata offsets, OffsetCommitCall
|
|||
{{#include examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/AbsWsConsumerLoop.java:consumer_demo}}
|
||||
```
|
||||
|
||||
**注意**：这里的 value.deserializer 配置参数值应该根据测试环境的包路径做相应的调整。
|
||||
**注意**：这里的 value.deserializer 配置参数值应该根据测试环境的包路径做相应的调整。
|
||||
其余代码请参考： [JDBC example](https://github.com/taosdata/TDengine/tree/3.0/examples/JDBC/JDBCDemo)
|
||||
|
||||
</TabItem>
|
||||
<TabItem label="Python" value="python">
|
||||
|
|
@ -628,6 +645,9 @@ void commitAsync(Map<TopicPartition, OffsetAndMetadata offsets, OffsetCommitCall
|
|||
{{#include examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/AbsConsumerLoopFull.java:consumer_demo}}
|
||||
```
|
||||
|
||||
**注意**：这里的 value.deserializer 配置参数值应该根据测试环境的包路径做相应的调整。
|
||||
其余代码请参考： [JDBC example](https://github.com/taosdata/TDengine/tree/3.0/examples/JDBC/JDBCDemo)
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem label="Python" value="python">
|
||||
|
|
|
|||
|
|
@ -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。
|
||||
|
||||
|
|
|
|||
|
|
@ -205,14 +205,13 @@ 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。
|
||||
|
||||
**注意**：使用 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`。
|
||||
|
|
@ -224,7 +223,7 @@ TDengine 的 JDBC URL 规范格式为：
|
|||
|
||||
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 +233,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”；
|
||||
|
|
@ -242,7 +241,6 @@ TDengine 中，只要保证 firstEp 和 secondEp 中一个节点有效，就可
|
|||
3. 使用 6041 作为连接端口。
|
||||
|
||||
对于 Websocket 和 REST 连接，url 中的配置参数如下：
|
||||
|
||||
- user：登录 TDengine 用户名，默认值 'root'。
|
||||
- password：用户登录密码，默认值 'taosdata'。
|
||||
- batchfetch: true：在执行查询时批量拉取结果集；false：逐行拉取结果集。默认值为：false。逐行拉取结果集使用 HTTP 方式进行数据传输。JDBC REST 连接支持批量拉取数据功能。taos-jdbcdriver 与 TDengine 之间通过 WebSocket 连接进行数据传输。相较于 HTTP，WebSocket 可以使 JDBC REST 连接支持大数据量查询，并提升查询性能。
|
||||
|
|
@ -270,7 +268,6 @@ TDengine 中，只要保证 firstEp 和 secondEp 中一个节点有效，就可
|
|||
> **注意**：应用中设置的 client parameter 为进程级别的，即如果要更新 client 的参数，需要重启应用。这是因为 client parameter 是全局参数，仅在应用程序的第一次设置生效。
|
||||
|
||||
properties 中的配置参数如下：
|
||||
|
||||
- TSDBDriver.PROPERTY_KEY_USER：登录 TDengine 用户名，默认值 'root'。
|
||||
- TSDBDriver.PROPERTY_KEY_PASSWORD：用户登录密码，默认值 'taosdata'。
|
||||
- TSDBDriver.PROPERTY_KEY_BATCH_LOAD: true：在执行查询时批量拉取结果集；false：逐行拉取结果集。默认值为：false。
|
||||
|
|
@ -292,10 +289,9 @@ properties 中的配置参数如下：
|
|||
- 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、客户端配置文件中有重复，则参数的`优先级由高到低`分别如下：
|
||||
|
||||
|
|
@ -308,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`
|
||||
- **接口说明**：获取数据库连接。
|
||||
|
|
@ -608,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`：待写入的数据行数组。
|
||||
|
|
@ -617,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<String> lines, SchemalessProtocolType protocolType, SchemalessTimestampType timestampType) throws SQLException`
|
||||
- `void write(List<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 int writeRaw(String line, SchemalessProtocolType protocolType, SchemalessTimestampType timestampType) throws SQLException`
|
||||
- `int writeRaw(String line, SchemalessProtocolType protocolType, SchemalessTimestampType timestampType) throws SQLException`
|
||||
- **接口说明**：以指定的协议类型和时间戳类型写入多行回车符分割的原始数据，回车符分割，并返回操作结果。
|
||||
- **参数说明**：
|
||||
- `line`：待写入的原始数据。
|
||||
|
|
@ -646,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`：待写入的原始数据。
|
||||
|
|
@ -1263,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<Integer> list) throws SQLException`
|
||||
- `void setInt(int columnIndex, ArrayList<Integer> list) throws SQLException`
|
||||
- **接口说明**：为指定列索引设置批量整型值。
|
||||
- **参数说明**：
|
||||
- `columnIndex`：列的索引位置。
|
||||
|
|
@ -1299,14 +1295,14 @@ ParameterMetaData 提供了参数元数据接口：
|
|||
- **异常**：
|
||||
- 如果操作过程中发生错误，将抛出 SQLException 异常。
|
||||
- 下面接口除了要设置的值类型不同外，其余同 setInt：
|
||||
- `public void setFloat(int columnIndex, ArrayList<Float> list) throws SQLException`
|
||||
- `public void setTimestamp(int columnIndex, ArrayList<Long> list) throws SQLException`
|
||||
- `public void setLong(int columnIndex, ArrayList<Long> list) throws SQLException`
|
||||
- `public void setDouble(int columnIndex, ArrayList<Double> list) throws SQLException`
|
||||
- `public void setBoolean(int columnIndex, ArrayList<Boolean> list) throws SQLException`
|
||||
- `public void setByte(int columnIndex, ArrayList<Byte> list) throws SQLException`
|
||||
- `public void setShort(int columnIndex, ArrayList<Short> list) throws SQLException`
|
||||
- `public void setString(int columnIndex, ArrayList<String> list, int size) throws SQLException`
|
||||
- `void setFloat(int columnIndex, ArrayList<Float> list) throws SQLException`
|
||||
- `void setTimestamp(int columnIndex, ArrayList<Long> list) throws SQLException`
|
||||
- `void setLong(int columnIndex, ArrayList<Long> list) throws SQLException`
|
||||
- `void setDouble(int columnIndex, ArrayList<Double> list) throws SQLException`
|
||||
- `void setBoolean(int columnIndex, ArrayList<Boolean> list) throws SQLException`
|
||||
- `void setByte(int columnIndex, ArrayList<Byte> list) throws SQLException`
|
||||
- `void setShort(int columnIndex, ArrayList<Short> list) throws SQLException`
|
||||
- `void setString(int columnIndex, ArrayList<String> list, int size) throws SQLException`
|
||||
- **接口说明**：为指定列索引设置字符串值列表。
|
||||
- **参数说明**：
|
||||
- `columnIndex`：列的索引位置。
|
||||
|
|
@ -1315,9 +1311,9 @@ ParameterMetaData 提供了参数元数据接口：
|
|||
- **异常**：
|
||||
- 如果操作过程中发生错误，将抛出 SQLException 异常。
|
||||
- 下面接口除了要设置的值类型不同外，其余同 setString：
|
||||
- `public void setVarbinary(int columnIndex, ArrayList<byte[]> list, int size) throws SQLException`
|
||||
- `public void setGeometry(int columnIndex, ArrayList<byte[]> list, int size) throws SQLException`
|
||||
- `public void setNString(int columnIndex, ArrayList<String> list, int size) throws SQLException`
|
||||
- `void setVarbinary(int columnIndex, ArrayList<byte[]> list, int size) throws SQLException`
|
||||
- `void setGeometry(int columnIndex, ArrayList<byte[]> list, int size) throws SQLException`
|
||||
- `void setNString(int columnIndex, ArrayList<String> list, int size) throws SQLException`
|
||||
- `void columnDataAddBatch() throws SQLException`
|
||||
- **接口说明**：将 `setInt（int columnIndex， ArrayList<Integer> list）` 等数组形式接口设置的数据添加到当前 PrepareStatement 对象的批处理中。
|
||||
- **异常**：
|
||||
|
|
@ -1352,81 +1348,82 @@ JDBC 标准不支持数据订阅，因此本章所有接口都是扩展接口。
|
|||
- 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 默认值发生变化。
|
||||
- TSDBDriver.PROPERTY_KEY_RECONNECT_RETRY_COUNT: 自动重连重试次数，默认值 3，仅在 PROPERTY_KEY_ENABLE_AUTO_RECONNECT 为 true 时生效。
|
||||
|
||||
- `public void subscribe(Collection<String> topics) throws SQLException`
|
||||
其他参数请参考：[Consumer 参数列表](../../../develop/tmq/#创建参数)， 注意TDengine服务端自 3.2.0.0 版本开始消息订阅中的 auto.offset.reset 默认值发生变化。
|
||||
|
||||
- `void subscribe(Collection<String> topics) throws SQLException`
|
||||
- **接口说明**：订阅一组主题。
|
||||
- **参数说明**：
|
||||
- `topics`：一个 `Collection<String>` 类型的参数，表示要订阅的主题列表。
|
||||
- **异常**：如果在订阅过程中发生错误，将抛出 SQLException 异常。
|
||||
- `public void unsubscribe() throws SQLException`
|
||||
- `void unsubscribe() throws SQLException`
|
||||
- **接口说明**：取消订阅所有主题。
|
||||
- **异常**：如果在取消订阅过程中发生错误，将抛出 SQLException 异常。
|
||||
- `public Set<String> subscription() throws SQLException`
|
||||
- `Set<String> subscription() throws SQLException`
|
||||
- **接口说明**：获取当前订阅的所有主题。
|
||||
- **返回值**：返回值类型为 `Set<String>`，即当前订阅的所有主题集合。
|
||||
- **异常**：如果在获取订阅信息过程中发生错误，将抛出 SQLException 异常。
|
||||
- `public ConsumerRecords<V> poll(Duration timeout) throws SQLException`
|
||||
- `ConsumerRecords<V> poll(Duration timeout) throws SQLException`
|
||||
- **接口说明**：轮询消息。
|
||||
- **参数说明**：
|
||||
- `timeout`：一个 `Duration` 类型的参数，表示轮询的超时时间。
|
||||
- **返回值**：返回值类型为 `ConsumerRecords<V>`，即轮询到的消息记录。
|
||||
- **异常**：如果在轮询过程中发生错误，将抛出 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<TopicPartition, Long> beginningOffsets(String topic) throws SQLException`
|
||||
- `Map<TopicPartition, Long> beginningOffsets(String topic) throws SQLException`
|
||||
- **接口说明**：获取指定主题的每个分区的最早偏移量。
|
||||
- **参数说明**：
|
||||
- `topic`：一个 `String` 类型的参数，表示要查询的主题。
|
||||
- **返回值**：返回值类型为 `Map<TopicPartition, Long>`，即指定主题的每个分区的最早偏移量。
|
||||
- **异常**：如果在获取最早偏移量过程中发生错误，将抛出 SQLException 异常。
|
||||
- `public Map<TopicPartition, Long> endOffsets(String topic) throws SQLException`
|
||||
- `Map<TopicPartition, Long> endOffsets(String topic) throws SQLException`
|
||||
- **接口说明**：获取指定主题的每个分区的最新偏移量。
|
||||
- **参数说明**：
|
||||
- `topic`：一个 `String` 类型的参数，表示要查询的主题。
|
||||
- **返回值**：返回值类型为 `Map<TopicPartition, Long>`，即指定主题的每个分区的最新偏移量。
|
||||
- **异常**：如果在获取最新偏移量过程中发生错误，将抛出 SQLException 异常。
|
||||
- `public void seekToBeginning(Collection<TopicPartition> partitions) throws SQLException`
|
||||
- `void seekToBeginning(Collection<TopicPartition> partitions) throws SQLException`
|
||||
- **接口说明**：将一组分区的偏移量设置到最早的偏移量。
|
||||
- **参数说明**：
|
||||
- `partitions`：一个 `Collection<TopicPartition>` 类型的参数，表示要操作的分区集合。
|
||||
- **异常**：如果在设置偏移量过程中发生错误，将抛出 SQLException 异常。
|
||||
- `public void seekToEnd(Collection<TopicPartition> partitions) throws SQLException`
|
||||
- `void seekToEnd(Collection<TopicPartition> partitions) throws SQLException`
|
||||
- **接口说明**：将一组分区的偏移量设置到最新的偏移量。
|
||||
- **参数说明**：
|
||||
- `partitions`：一个 `Collection<TopicPartition>` 类型的参数，表示要操作的分区集合。
|
||||
- **异常**：如果在设置偏移量过程中发生错误，将抛出 SQLException 异常。
|
||||
- `public Set<TopicPartition> assignment() throws SQLException`
|
||||
- `Set<TopicPartition> assignment() throws SQLException`
|
||||
- **接口说明**：获取消费者当前分配的所有分区。
|
||||
- **返回值**：返回值类型为 `Set<TopicPartition>`，即消费者当前分配的所有分区。
|
||||
- **异常**：如果在获取分配的分区过程中发生错误，将抛出 SQLException 异常。
|
||||
- `public OffsetAndMetadata committed(TopicPartition partition) throws SQLException`
|
||||
- `OffsetAndMetadata committed(TopicPartition partition) throws SQLException`
|
||||
- **接口说明**：获取指定分区最后提交的偏移量。
|
||||
- **参数说明**：
|
||||
- `partition`：一个 `TopicPartition` 类型的参数，表示要查询的分区。
|
||||
- **返回值**：返回值类型为 `OffsetAndMetadata`，即指定分区最后提交的偏移量。
|
||||
- **异常**：如果在获取提交的偏移量过程中发生错误，将抛出 SQLException 异常。
|
||||
- `public Map<TopicPartition, OffsetAndMetadata> committed(Set<TopicPartition> partitions) throws SQLException`
|
||||
- `Map<TopicPartition, OffsetAndMetadata> committed(Set<TopicPartition> partitions) throws SQLException`
|
||||
- **接口说明**：获取一组分区最后提交的偏移量。
|
||||
- **参数说明**：
|
||||
- `partitions`：一个 `Set<TopicPartition>` 类型的参数，表示要查询的分区集合。
|
||||
|
|
@ -1439,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`，即消息的偏移量。
|
||||
|
||||
|
|
@ -1459,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。
|
||||
|
||||
|
|
@ -1475,10 +1472,10 @@ TopicPartition 类提供了分区信息，包含消息主题和虚拟组 ID。
|
|||
|
||||
OffsetAndMetadata 类提供了偏移量元数据信息。
|
||||
|
||||
- `public long offset()`
|
||||
- `long offset()`
|
||||
- **接口说明**：获取此 OffsetAndMetadata 实例中的偏移量。
|
||||
- **返回值**：返回值类型为 `long`，即此 OffsetAndMetadata 实例中的偏移量。
|
||||
- `public String metadata()`
|
||||
- `String metadata()`
|
||||
- **接口说明**：获取此 OffsetAndMetadata 实例中的元数据。
|
||||
- **返回值**：返回值类型为 `String`，即此 OffsetAndMetadata 实例中的元数据。
|
||||
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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<KeyValuePair<string, string>> 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<TValue> Build()`
|
||||
- **接口说明**：构建消费者。
|
||||
- **返回值**：消费者对象。
|
||||
|
||||
`IConsumer` 接口提供了消费者相关 API：
|
||||
|
||||
- `ConsumeResult<TValue> Consume(int millisecondsTimeout)`
|
||||
- **接口说明**：消费消息。
|
||||
- **参数说明**：
|
||||
- `millisecondsTimeout`：毫秒超时时间。
|
||||
- **返回值**：消费结果。
|
||||
- **异常**：执行失败抛出 `TDengineError` 异常。
|
||||
|
||||
- `List<TopicPartition> Assignment { get; }`
|
||||
- **接口说明**：获取分配信息。
|
||||
- **返回值**：分配信息。
|
||||
- **异常**：执行失败抛出 `TDengineError` 异常。
|
||||
|
||||
- `List<string> Subscription()`
|
||||
- **接口说明**：获取订阅的主题。
|
||||
- **返回值**：主题列表。
|
||||
- **异常**：执行失败抛出 `TDengineError` 异常。
|
||||
|
||||
- `void Subscribe(IEnumerable<string> topic)`
|
||||
- **接口说明**：订阅主题列表。
|
||||
- **参数说明**：
|
||||
- `topic`：主题列表。
|
||||
- **异常**：执行失败抛出 `TDengineError` 异常。
|
||||
|
||||
- `void Subscribe(string topic)`
|
||||
- **接口说明**：订阅单个主题。
|
||||
- **参数说明**：
|
||||
- `topic`：主题。
|
||||
- **异常**：执行失败抛出 `TDengineError` 异常。
|
||||
|
||||
- `void Unsubscribe()`
|
||||
- **接口说明**：取消订阅。
|
||||
- **异常**：执行失败抛出 `TDengineError` 异常。
|
||||
|
||||
- `void Commit(ConsumeResult<TValue> consumerResult)`
|
||||
- **接口说明**：提交消费结果。
|
||||
- **参数说明**：
|
||||
- `consumerResult`：消费结果。
|
||||
- **异常**：执行失败抛出 `TDengineError` 异常。
|
||||
|
||||
- `List<TopicPartitionOffset> Commit()`
|
||||
- **接口说明**：提交全部消费结果。
|
||||
- **返回值**：分区偏移量。
|
||||
- **异常**：执行失败抛出 `TDengineError` 异常。
|
||||
|
||||
- `void Commit(IEnumerable<TopicPartitionOffset> offsets)`
|
||||
- **接口说明**：提交消费结果。
|
||||
- **参数说明**：
|
||||
- `offsets`：分区偏移量。
|
||||
- **异常**：执行失败抛出 `TDengineError` 异常。
|
||||
|
||||
- `void Seek(TopicPartitionOffset tpo)`
|
||||
- **接口说明**：跳转到分区偏移量。
|
||||
- **参数说明**：
|
||||
- `tpo`：分区偏移量。
|
||||
- **异常**：执行失败抛出 `TDengineError` 异常。
|
||||
|
||||
- `List<TopicPartitionOffset> Committed(TimeSpan timeout)`
|
||||
- **接口说明**：获取分区偏移量。
|
||||
- **参数说明**：
|
||||
- `timeout`：超时时间(未使用)。
|
||||
- **返回值**：分区偏移量。
|
||||
- **异常**：执行失败抛出 `TDengineError` 异常。
|
||||
|
||||
- `List<TopicPartitionOffset> Committed(IEnumerable<TopicPartition> partitions, TimeSpan timeout)`
|
||||
- **接口说明**：获取指定分区偏移量。
|
||||
- **参数说明**：
|
||||
- `partitions`：分区列表。
|
||||
- `timeout`：超时时间(未使用)。
|
||||
- **返回值**：分区偏移量。
|
||||
- **异常**：执行失败抛出 `TDengineError` 异常。
|
||||
|
||||
- `Offset Position(TopicPartition partition)`
|
||||
- **接口说明**：获取消费位置。
|
||||
- **参数说明**：
|
||||
- `partition`：分区。
|
||||
- **返回值**：偏移量。
|
||||
- **异常**：执行失败抛出 `TDengineError` 异常。
|
||||
|
||||
- `void Close()`
|
||||
- **接口说明**：关闭消费者。
|
||||
|
||||
#### 消费记录
|
||||
|
||||
`ConsumeResult` 类提供了消费结果相关接口：
|
||||
|
||||
- `public List<TmqMessage<TValue>> Message`
|
||||
- **接口说明**：获取消息列表。
|
||||
- **返回值**：消息列表。
|
||||
|
||||
`TmqMessage` 类提供了消息具体内容：
|
||||
|
||||
```csharp
|
||||
public class TmqMessage<TValue>
|
||||
{
|
||||
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<string, object>` 对象，其 key 为列名，值为对象。
|
||||
|
||||
ReferenceDeserializer 和 DictionaryDeserializer 的接口不会被用户直接调用，请参考使用样例。
|
||||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -38,8 +38,8 @@ 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("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
|
||||
|
|
@ -63,10 +63,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("Failed to poll data; ErrCode:" + ex.getErrorCode() + "; ErrMessage: " + ex.getMessage());
|
||||
throw new SQLException("Failed to poll data", ex);
|
||||
} finally {
|
||||
consumer.close();
|
||||
shutdownLatch.countDown();
|
||||
|
|
@ -90,10 +90,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("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();
|
||||
|
|
@ -105,9 +105,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("Failed to unsubscribe consumer. ErrCode:" + ex.getErrorCode() + "; ErrMessage: " + ex.getMessage());
|
||||
throw new SQLException("Failed to unsubscribe consumer", ex);
|
||||
} finally {
|
||||
consumer.close();
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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);
|
||||
}
|
||||
|
||||
|
|
@ -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<ResultBean> records = consumer.poll(Duration.ofMillis(100));
|
||||
for (ConsumerRecord<ResultBean> 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;
|
||||
|
|
|
|||
|
|
@ -30,21 +30,21 @@ 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");
|
||||
|
||||
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 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);
|
||||
}
|
||||
|
|
@ -53,17 +53,22 @@ try {
|
|||
|
||||
public void pollData() throws SQLException {
|
||||
try {
|
||||
// Subscribe to the topic
|
||||
consumer.subscribe(topics);
|
||||
|
||||
while (!shutdown.get()) {
|
||||
// poll data
|
||||
ConsumerRecords<ResultBean> records = consumer.poll(Duration.ofMillis(100));
|
||||
for (ConsumerRecord<ResultBean> 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;
|
||||
|
|
|
|||
|
|
@ -54,9 +54,9 @@ try (TaosConsumer<AbsConsumerLoop.ResultBean> 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
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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());
|
||||
}
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -43,8 +43,8 @@ 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("Failed to create db and table, url:" + jdbcUrl + "; ErrCode:" + ex.getErrorCode() + "; ErrMessage: " + ex.getMessage());
|
||||
}
|
||||
// ANCHOR_END: create_db_and_table
|
||||
|
||||
|
|
|
|||
|
|
@ -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,10 +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
|
||||
System.out.println("SQLException: " + ex.getMessage());
|
||||
// handle any errors, please refer to the JDBC specifications for detailed exceptions info
|
||||
System.out.println("Failed to insert data to power.meters, url:" + jdbcUrl + "; ErrCode:" + ex.getErrorCode() + "; ErrMessage: " + ex.getMessage());
|
||||
|
||||
}
|
||||
// ANCHOR_END: insert_data
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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,11 +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
|
||||
System.out.println("SQLException: " + ex.getMessage());
|
||||
// handle any errors, please refer to the JDBC specifications for detailed exceptions info
|
||||
System.out.println("Failed to query data from power.meters, url:" + jdbcUrl + "; ErrCode:" + ex.getErrorCode() + "; ErrMessage: " + ex.getMessage());
|
||||
}
|
||||
// ANCHOR_END: query_data
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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,25 +25,20 @@ 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);
|
||||
}
|
||||
}
|
||||
} 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("Failed to execute sql with reqId, url:" + jdbcUrl + "; ErrCode:" + ex.getErrorCode() + "; ErrMessage: " + ex.getMessage());
|
||||
|
||||
}
|
||||
// ANCHOR_END: with_reqid
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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,39 +32,23 @@ public class ParameterBindingBasicDemo {
|
|||
pstmt.setTagInt(0, i);
|
||||
pstmt.setTagString(1, "location_" + i);
|
||||
|
||||
// set column ts
|
||||
ArrayList<Long> 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<Float> f1List = new ArrayList<>();
|
||||
for (int j = 0; j < numOfRow; j++)
|
||||
f1List.add(random.nextFloat() * 30);
|
||||
pstmt.setFloat(1, f1List);
|
||||
|
||||
// set column voltage
|
||||
ArrayList<Integer> f2List = new ArrayList<>();
|
||||
for (int j = 0; j < numOfRow; j++)
|
||||
f2List.add(random.nextInt(300));
|
||||
pstmt.setInt(2, f2List);
|
||||
|
||||
// set column phase
|
||||
ArrayList<Float> 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
|
||||
System.out.println("SQLException: " + ex.getMessage());
|
||||
// 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());
|
||||
}
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -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<Long> 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<Float> f1List = new ArrayList<>();
|
||||
for (int j = 0; j < numOfRow; j++)
|
||||
f1List.add(random.nextFloat() * 30);
|
||||
pstmt.setFloat(1, f1List);
|
||||
|
||||
// set column voltage
|
||||
ArrayList<Integer> f2List = new ArrayList<>();
|
||||
for (int j = 0; j < numOfRow; j++)
|
||||
f2List.add(random.nextInt(300));
|
||||
pstmt.setInt(2, f2List);
|
||||
|
||||
// set column phase
|
||||
ArrayList<Float> 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
|
||||
|
|
@ -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);
|
||||
|
||||
|
|
@ -26,7 +26,8 @@ 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("Failed to insert data with schemaless, host:" + host + "; ErrCode:" + ex.getErrorCode() + "; ErrMessage: " + ex.getMessage());
|
||||
}
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -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";
|
||||
|
|
@ -26,7 +26,8 @@ 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("Failed to insert data with schemaless, host:" + host + "; ErrCode:" + ex.getErrorCode() + "; ErrMessage: " + ex.getMessage());
|
||||
}
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -48,8 +48,8 @@ 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("Failed to insert to table meters using stmt, url: " + jdbcUrl + "; ErrCode:" + ex.getErrorCode() + "; ErrMessage: " + ex.getMessage());
|
||||
}
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -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());
|
||||
}
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -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());
|
||||
}
|
||||
}
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue