docs: go and csharp api reference documentation
This commit is contained in:
t_max
parent
46591c88f3
commit
31bdddde57
|
|
@ -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 的接口不会被用户直接调用，请参考使用样例。
|
||||
Loading…
Reference in New Issue