update connector update history
This commit is contained in:
menshibin
sheyanjie-qq
parent
afb10cd075
commit
c61bf7a6c0
|
|
@ -35,9 +35,9 @@ Please refer to the [Supported Platforms List](../#supported-platforms)
|
|||
|
||||
### Version History
|
||||
|
||||
| TDengine Client Version | Main Changes | TDengine Version |
|
||||
| :------------------: | :---------------------------: | :----------------: |
|
||||
| 3.3.3.0 | First release, providing comprehensive support for SQL execution, parameter binding, schema-less writing, and data subscription. | 3.3.2.0 and higher versions |
|
||||
| TDengine Client Version | Major Changes | TDengine Version |
|
||||
| ------------------ | --------------------------- | ---------------- |
|
||||
| 3.3.3.0 | First release, providing comprehensive support for SQL execution, parameter binding, schema-less writing, and data subscription. | 3.3.2.0 and higher |
|
||||
|
||||
### Error Codes
|
||||
|
||||
|
|
|
|||
|
|
@ -18,45 +18,45 @@ The JDBC driver implementation for TDengine strives to be consistent with relati
|
|||
|
||||
:::
|
||||
|
||||
## JDBC and JRE Compatibility
|
||||
## JDBC and JRE Version Compatibility
|
||||
|
||||
- JDBC: Supports JDBC 4.2, with some features like schemaless writing and data subscription provided separately
|
||||
- JRE: Supports JRE 8 and above
|
||||
- JDBC: Supports JDBC 4.2 and above.
|
||||
- JRE: Supports JRE 8 and above.
|
||||
|
||||
## Supported Platforms
|
||||
|
||||
Native connection supports the same platforms as the TDengine client driver.
|
||||
REST connection supports all platforms that can run Java.
|
||||
- Native connection supports the same platforms as the TDengine client driver.
|
||||
- WebSocket/REST connection supports all platforms that can run Java.
|
||||
|
||||
## Version History
|
||||
|
||||
| taos-jdbcdriver Version | Main Changes | TDengine Version |
|
||||
| :------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------: | :----------------: |
|
||||
| 3.4.0 | 1. Replaced fastjson library with jackson; 2. WebSocket uses a separate protocol identifier; 3. Optimized background thread usage to avoid user misuse leading to timeouts. | - |
|
||||
| 3.3.4 | 1. Fixed getInt error when data type is float | - |
|
||||
| 3.3.3 | 1. Fixed memory leak caused by closing WebSocket statement | - |
|
||||
| 3.3.2 | 1. Optimized parameter binding performance under WebSocket connection; 2. Improved support for mybatis | - |
|
||||
| 3.3.0 | 1. Optimized data transmission performance under WebSocket connection; 2. Supports skipping SSL verification, off by default | 3.3.2.0 and higher |
|
||||
| 3.2.11 | Fixed a bug in closing result set in Native connection | - |
|
||||
| 3.2.10 | 1. REST/WebSocket connections support data compression during transmission; 2. WebSocket automatic reconnection mechanism, off by default; 3. Connection class provides methods for schemaless writing; 4. Optimized data fetching performance for native connections; 5. Fixed some known issues; 6. Metadata retrieval functions can return a list of supported functions. | - |
|
||||
| 3.2.9 | Fixed bug in closing WebSocket prepareStatement | - |
|
||||
| 3.2.8 | Optimized auto-commit, fixed manual commit bug in WebSocket, optimized WebSocket prepareStatement using a single connection, metadata supports views | - |
|
||||
| 3.2.7 | Supports VARBINARY and GEOMETRY types, added timezone setting support for native connections. Added WebSocket automatic reconnection feature. | 3.2.0.0 and higher |
|
||||
| 3.2.5 | Data subscription adds committed() and assignment() methods | 3.1.0.3 and higher |
|
||||
| 3.2.4 | Data subscription adds enable.auto.commit parameter under WebSocket connection, as well as unsubscribe() method. | - |
|
||||
| 3.2.3 | Fixed ResultSet data parsing failure in some cases | - |
|
||||
| 3.2.2 | New feature: Data subscription supports seek function. | 3.0.5.0 and higher |
|
||||
| 3.2.1 | New feature: WebSocket connection supports schemaless and prepareStatement writing. Change: consumer poll returns result set as ConsumerRecord, which can be accessed through value() method. | 3.0.3.0 and higher |
|
||||
| 3.2.0 | Connection issues, not recommended for use | - |
|
||||
| 3.1.0 | WebSocket connection supports subscription function | - |
|
||||
| 3.0.1 - 3.0.4 | Fixed data parsing errors in result sets under some conditions. 3.0.1 compiled in JDK 11 environment, other versions recommended for JDK 8 | - |
|
||||
| 3.0.0 | Supports TDengine 3.0 | 3.0.0.0 and higher |
|
||||
| 2.0.42 | Fixed wasNull interface return value in WebSocket connection | - |
|
||||
| 2.0.41 | Fixed username and password encoding method in REST connection | - |
|
||||
| 2.0.39 - 2.0.40 | Added REST connection/request timeout settings | - |
|
||||
| 2.0.38 | JDBC REST connection adds batch fetching function | - |
|
||||
| 2.0.37 | Added support for json tag | - |
|
||||
| 2.0.36 | Added support for schemaless writing | - |
|
||||
| taos-jdbcdriver Version | Major Changes | TDengine Version |
|
||||
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
|
||||
| 3.4.0 | 1. Replaced fastjson library with jackson. <br/> 2. WebSocket uses a separate protocol identifier. <br/> 3. Optimized background thread usage to avoid user misuse leading to timeouts. | - |
|
||||
| 3.3.4 | Fixed getInt error when data type is float. | - |
|
||||
| 3.3.3 | Fixed memory leak caused by closing WebSocket statement. | - |
|
||||
| 3.3.2 | 1. Optimized parameter binding performance under WebSocket connection. <br/> 2. Improved support for mybatis. | - |
|
||||
| 3.3.0 | 1. Optimized data transmission performance under WebSocket connection. <br/> 2. Supports skipping SSL verification, off by default. | 3.3.2.0 and higher |
|
||||
| 3.2.11 | Fixed a bug in closing result set in Native connection. | - |
|
||||
| 3.2.10 | 1. REST/WebSocket connections support data compression during transmission. <br/> 2. WebSocket automatic reconnection mechanism, off by default. <br/> 3. Connection class provides methods for schemaless writing. <br/> 4. Optimized data fetching performance for native connections. <br/> 5. Fixed some known issues. <br/> 6. Metadata retrieval functions can return a list of supported functions. | - |
|
||||
| 3.2.9 | Fixed bug in closing WebSocket prepareStatement. | - |
|
||||
| 3.2.8 | 1. Optimized auto-commit. <br/> 2. Fixed manual commit bug in WebSocket. <br/> 3. Optimized WebSocket prepareStatement using a single connection. <br/> 4. Metadata supports views. | - |
|
||||
| 3.2.7 | 1. Supports VARBINARY and GEOMETRY types. <br/> 2. Added timezone setting support for native connections. <br/> 3. Added WebSocket automatic reconnection feature. | 3.2.0.0 and higher |
|
||||
| 3.2.5 | Data subscription adds committed() and assignment() methods. | 3.1.0.3 and higher |
|
||||
| 3.2.4 | Data subscription adds enable.auto.commit parameter under WebSocket connection, as well as unsubscribe() method. | - |
|
||||
| 3.2.3 | Fixed ResultSet data parsing failure in some cases. | - |
|
||||
| 3.2.2 | New feature: Data subscription supports seek function. | 3.0.5.0 and higher |
|
||||
| 3.2.1 | 1. WebSocket connection supports schemaless and prepareStatement writing. <br/> 2. Consumer poll returns result set as ConsumerRecord, which can be accessed through value() method. | 3.0.3.0 and higher |
|
||||
| 3.2.0 | Connection issues, not recommended for use. | - |
|
||||
| 3.1.0 | WebSocket connection supports subscription function. | - |
|
||||
| 3.0.1 - 3.0.4 | Fixed data parsing errors in result sets under some conditions. 3.0.1 compiled in JDK 11 environment, other versions recommended for JDK 8. | - |
|
||||
| 3.0.0 | Supports TDengine 3.0 | 3.0.0.0 and higher |
|
||||
| 2.0.42 | Fixed wasNull interface return value in WebSocket connection. | - |
|
||||
| 2.0.41 | Fixed username and password encoding method in REST connection. | - |
|
||||
| 2.0.39 - 2.0.40 | Added REST connection/request timeout settings. | - |
|
||||
| 2.0.38 | JDBC REST connection adds batch fetching function. | - |
|
||||
| 2.0.37 | Added support for json tag. | - |
|
||||
| 2.0.36 | Added support for schemaless writing. | - |
|
||||
|
||||
## Exceptions and Error Codes
|
||||
|
||||
|
|
|
|||
|
|
@ -10,20 +10,38 @@ import RequestId from "./_request_id.mdx";
|
|||
|
||||
`driver-go` is the official Go language connector for TDengine, implementing the interface of the Go language [database/sql](https://golang.org/pkg/database/sql/) package. Go developers can use it to develop applications that access data in the TDengine cluster.
|
||||
|
||||
## Compatibility
|
||||
## Go Version Compatibility
|
||||
|
||||
Supports a minimum Go version of 1.14, but the latest version of Go is recommended.
|
||||
Supports Go 1.14 and above.
|
||||
|
||||
## Supported Platforms
|
||||
|
||||
Native connections support the same platforms as the TDengine client driver.
|
||||
REST connections support all platforms that can run Go.
|
||||
- Native connections support the same platforms as the TDengine client driver.
|
||||
- WebSocket/REST connections support all platforms that can run Go.
|
||||
|
||||
## Version Support
|
||||
## Version History
|
||||
|
||||
Please refer to the [version support list](https://github.com/taosdata/driver-go#remind).
|
||||
| driver-go Version | Major Changes | TDengine Version |
|
||||
|------------------|------------------------------------------------------------------|-------------------|
|
||||
| v3.5.8 | Fixed null pointer exception. | - |
|
||||
| v3.5.7 | taosWS and taosRestful support passing request id. | - |
|
||||
| v3.5.6 | Improved websocket query and insert performance. | 3.3.2.0 and higher |
|
||||
| v3.5.5 | Restful supports skipping SSL certificate check. | - |
|
||||
| v3.5.4 | Compatible with TDengine 3.3.0.0 tmq raw data. | - |
|
||||
| v3.5.3 | Refactored taosWS. | - |
|
||||
| v3.5.2 | Websocket compression and optimized tmq subscription performance. | 3.2.3.0 and higher |
|
||||
| v3.5.1 | Native stmt query and geometry type support. | 3.2.1.0 and higher |
|
||||
| v3.5.0 | Support tmq get assignment and seek offset. | 3.0.5.0 and higher |
|
||||
| v3.3.1 | Schemaless protocol insert based on websocket. | 3.0.4.1 and higher |
|
||||
| v3.1.0 | Provided Kafka-like subscription API. | - |
|
||||
| v3.0.4 | Added request id related interfaces. | 3.0.2.2 and higher |
|
||||
| v3.0.3 | Websocket-based statement insert. | - |
|
||||
| v3.0.2 | Websocket-based data query and insert. | 3.0.1.5 and higher |
|
||||
| v3.0.1 | Websocket-based message subscription. | - |
|
||||
| v3.0.0 | Adapted to TDengine 3.0 query and insert. | 3.0.0.0 and higher |
|
||||
|
||||
## Handling Exceptions
|
||||
|
||||
## Exceptions and Error Codes
|
||||
|
||||
If it is a TDengine error, you can obtain the error code and error message as follows.
|
||||
|
||||
|
|
|
|||
|
|
@ -4,10 +4,10 @@ title: Rust Client Library
|
|||
slug: /tdengine-reference/client-libraries/rust
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem";
|
||||
|
||||
import Preparation from "./_preparation.mdx"
|
||||
import Preparation from "./_preparation.mdx";
|
||||
import RequestId from "./_request_id.mdx";
|
||||
|
||||
[](https://crates.io/crates/taos)  [](https://docs.rs/taos)
|
||||
|
|
@ -16,37 +16,30 @@ import RequestId from "./_request_id.mdx";
|
|||
|
||||
The source code for this Rust connector is hosted on [GitHub](https://github.com/taosdata/taos-connector-rust).
|
||||
|
||||
## Connection Methods
|
||||
## Rust Version Compatibility
|
||||
|
||||
`taos` provides two ways to establish a connection. Generally, we recommend using **WebSocket Connection**.
|
||||
|
||||
- **Native Connection**, which connects to a TDengine instance via the TDengine client driver (taosc).
|
||||
- **WebSocket Connection**, which connects to a TDengine instance via the WebSocket interface of taosAdapter.
|
||||
|
||||
You can specify which connector to use through different "features (i.e., the Cargo keyword `features`)" (both are supported by default).
|
||||
|
||||
For a detailed introduction to connection methods, please refer to: [Connection Methods](../../../developer-guide/connecting-to-tdengine/)
|
||||
Supports Rust 1.70 and above.
|
||||
|
||||
## Supported Platforms
|
||||
|
||||
The platforms supported by the native connection are consistent with those supported by the TDengine client driver.
|
||||
WebSocket connection supports all platforms that can run Rust.
|
||||
- The platforms supported by the native connection are consistent with those supported by the TDengine client driver.
|
||||
- WebSocket connection supports all platforms that can run Rust.
|
||||
|
||||
## Version History
|
||||
|
||||
| Rust Connector Version | TDengine Version | Main Features |
|
||||
| :----------------: | :--------------: | :--------------------------------------------------: |
|
||||
| v0.12.3 | 3.3.0.0 or later | Optimized WebSocket query and insertion performance, support for VARBINARY and GEOMETRY types |
|
||||
| v0.12.0 | 3.2.3.0 or later | WS supports compression. |
|
||||
| v0.11.0 | 3.2.0.0 | TMQ feature optimization. |
|
||||
| v0.10.0 | 3.1.0.0 | WS endpoint change. |
|
||||
| v0.9.2 | 3.0.7.0 | STMT: ws to get tag_fields, col_fields. |
|
||||
| v0.8.12 | 3.0.5.0 | Message subscription: get consumption progress and start consuming at a specified progress. |
|
||||
| v0.8.0 | 3.0.4.0 | Supports schema-less writing. |
|
||||
| v0.7.6 | 3.0.3.0 | Supports using req_id in requests. |
|
||||
| v0.6.0 | 3.0.0.0 | Basic functionality. |
|
||||
| Rust Connector Version | Major Changes | TDengine Version |
|
||||
| -------------------- | --------------------------------------------------------------------------------------------------- | --------------- |
|
||||
| v0.12.3 | 1. Optimized WebSocket query and insert performance. <br/> 2. Supported VARBINARY and GEOMETRY types. | 3.3.0.0 and higher |
|
||||
| v0.12.0 | WebSocket supports compression. | 3.2.3.0 and higher |
|
||||
| v0.11.0 | TMQ feature optimization. | 3.2.0.0 and higher |
|
||||
| v0.10.0 | WebSocket endpoint change. | 3.1.0.0 and higher |
|
||||
| v0.9.2 | STMT: WebSocket to get tag_fields, col_fields. | 3.0.7.0 and higher |
|
||||
| v0.8.12 | Message subscription: get consumption progress and start consuming at a specified progress. | 3.0.5.0 and higher |
|
||||
| v0.8.0 | Supports schema-less writing. | 3.0.4.0 and higher |
|
||||
| v0.7.6 | Supports using req_id in requests. | 3.0.3.0 and higher |
|
||||
| v0.6.0 | Basic functionality. | 3.0.0.0 and higher |
|
||||
|
||||
## Error Handling
|
||||
## Exceptions and Error Codes
|
||||
|
||||
After an error occurs, you can obtain detailed information about the error:
|
||||
|
||||
|
|
@ -81,14 +74,14 @@ TDengine currently supports timestamp, numeric, character, and boolean types, wi
|
|||
| BINARY | Vec\<u8> |
|
||||
| NCHAR | String |
|
||||
| JSON | serde_json::Value |
|
||||
| VARBINARY | Bytes |
|
||||
| GEOMETRY | Bytes |
|
||||
| VARBINARY | Bytes |
|
||||
| GEOMETRY | Bytes |
|
||||
|
||||
**Note**: The JSON type is only supported in tags.
|
||||
|
||||
## Summary of Example Programs
|
||||
|
||||
For the source code of the example programs, please refer to: [rust example](https://github.com/taosdata/TDengine/tree/main/docs/examples/rust)
|
||||
Please refer to: [rust example](https://github.com/taosdata/TDengine/tree/main/docs/examples/rust)
|
||||
|
||||
## Frequently Asked Questions
|
||||
|
||||
|
|
@ -97,9 +90,9 @@ Please refer to [FAQ](../../../frequently-asked-questions/)
|
|||
## API Reference
|
||||
|
||||
The Rust connector interfaces are divided into synchronous and asynchronous interfaces, where the synchronous interfaces are generally implemented by the asynchronous ones, and the method signatures are basically the same except for the async keyword. For interfaces where the synchronous and asynchronous functionalities are the same, this document only provides explanations for the synchronous interfaces.
|
||||
For WebSocket connections and native connections, other than the different DSNs required to establish the connections, there is no difference in calling other interfaces.
|
||||
For WebSocket connections and native connections, other than the different DSNs required to establish the connections, there is no difference in calling other interfaces.
|
||||
|
||||
### Connection Features
|
||||
### Connection Features
|
||||
|
||||
#### DSN
|
||||
|
||||
|
|
@ -132,26 +125,31 @@ A complete DSN description string example is as follows: `taos+ws://localhost:60
|
|||
The TaosBuilder struct primarily provides methods for building Taos objects based on DSN, as well as features for checking connections and obtaining the client version number.
|
||||
|
||||
- `fn available_params() -> &'static [&'static str]`
|
||||
|
||||
- **Interface Description**: Retrieves a list of available parameters in the DSN.
|
||||
- **Return Value**: Returns a reference to a static slice of strings containing the names of available parameters.
|
||||
|
||||
- `fn from_dsn<D: IntoDsn>(dsn: D) -> RawResult<Self>`
|
||||
|
||||
- **Interface Description**: Creates a connection using a DSN string without checking the connection.
|
||||
- **Parameter Description**:
|
||||
- `dsn`: DSN string or a type that can be converted into a DSN.
|
||||
- **Return Value**: On success, returns a `RawResult` of its own type; on failure, returns an error.
|
||||
|
||||
- `fn client_version() -> &'static str`
|
||||
|
||||
- **Interface Description**: Gets the client version.
|
||||
- **Return Value**: Returns a static string of the client version.
|
||||
|
||||
- `fn ping(&self, _: &mut Self::Target) -> RawResult<()>`
|
||||
|
||||
- **Interface Description**: Checks if the connection is still alive.
|
||||
- **Parameter Description**:
|
||||
- `_`: Mutable reference to the target connection.
|
||||
- **Return Value**: On success, returns an empty `RawResult`; on failure, returns an error.
|
||||
|
||||
- `fn ready(&self) -> bool`
|
||||
|
||||
- **Interface Description**: Checks if it is ready to connect.
|
||||
- **Return Value**: Mostly returns `true`, indicating the address is ready for connection.
|
||||
|
||||
|
|
@ -168,20 +166,24 @@ Executing SQL primarily uses the Taos struct, and obtaining the result set and m
|
|||
The Taos struct provides multiple database operation APIs, including: executing SQL, schema-less writing, and some common database query encapsulations (such as creating databases, fetching)
|
||||
|
||||
- `pub fn is_native(&self) -> bool`
|
||||
|
||||
- **Interface Description**: Determines if the connection uses a native protocol.
|
||||
- **Return Value**: Returns `true` if using a native protocol, otherwise returns `false`.
|
||||
|
||||
- `pub fn is_ws(&self) -> bool`
|
||||
|
||||
- **Interface Description**: Determines if the connection uses the WebSocket protocol.
|
||||
- **Return Value**: Returns `true` if using the WebSocket protocol, otherwise returns `false`.
|
||||
|
||||
- `fn query<T: AsRef<str>>(&self, sql: T) -> RawResult<Self::ResultSet>`
|
||||
|
||||
- **Interface Description**: Executes an SQL query.
|
||||
- **Parameter Description**:
|
||||
- `sql`: The SQL statement to execute.
|
||||
- **Return Value**: On success, returns a `RawResult` of the `ResultSet`; on failure, returns an error.
|
||||
|
||||
- `fn query_with_req_id<T: AsRef<str>>(&self, sql: T, req_id: u64) -> RawResult<Self::ResultSet>`
|
||||
|
||||
- **Interface Description**: Executes an SQL query with a request ID.
|
||||
- **Parameter Description**:
|
||||
- `sql`: The SQL statement to execute.
|
||||
|
|
@ -189,28 +191,33 @@ The Taos struct provides multiple database operation APIs, including: executing
|
|||
- **Return Value**: On success, returns a `RawResult` of the `ResultSet`; on failure, returns an error.
|
||||
|
||||
- `fn exec<T: AsRef<str>>(&self, sql: T) -> RawResult<usize>`
|
||||
|
||||
- **Interface Description**: Executes an SQL statement.
|
||||
- **Parameter Description**:
|
||||
- `sql`: The SQL statement to execute.
|
||||
- **Return Value**: On success, returns the number of affected rows; on failure, returns an error.
|
||||
|
||||
- `fn exec_many<T: AsRef<str>, I: IntoIterator<Item = T>>(&self, input: I) -> RawResult<usize>`
|
||||
|
||||
- **Interface Description**: Executes multiple SQL statements in batch.
|
||||
- **Parameter Description**:
|
||||
- `input`: Collection of SQL statements to execute.
|
||||
- **Return Value**: On success, returns the total number of affected rows; on failure, returns an error.
|
||||
|
||||
- `fn query_one<T: AsRef<str>, O: DeserializeOwned>(&self, sql: T) -> RawResult<Option<O>>`
|
||||
|
||||
- **Interface Description**: Executes an SQL query and returns a single result.
|
||||
- **Parameter Description**:
|
||||
- `sql`: The SQL statement to execute.
|
||||
- **Return Value**: On success, returns an optional result object; on failure, returns an error.
|
||||
|
||||
- `fn server_version(&self) -> RawResult<Cow<str>>`
|
||||
|
||||
- **Interface Description**: Gets the server version.
|
||||
- **Return Value**: On success, returns the server version string as a `RawResult`; on failure, returns an error.
|
||||
|
||||
- `fn create_topic(&self, name: impl AsRef<str>, sql: impl AsRef<str>) -> RawResult<()>`
|
||||
|
||||
- **Interface Description**: Creates a topic.
|
||||
- **Parameter Description**:
|
||||
- `name`: The name of the topic.
|
||||
|
|
@ -218,20 +225,24 @@ The Taos struct provides multiple database operation APIs, including: executing
|
|||
- **Return Value**: On success, returns an empty `RawResult`; on failure, returns an error.
|
||||
|
||||
- `fn databases(&self) -> RawResult<Vec<ShowDatabase>>`
|
||||
|
||||
- **Interface Description**: Retrieves a list of databases.
|
||||
- **Return Value**: On success, returns a list of databases as a `RawResult`; on failure, returns an error.
|
||||
|
||||
- `fn topics(&self) -> RawResult<Vec<Topic>>`
|
||||
|
||||
- **Interface Description**: Retrieves topic information.
|
||||
- **Return Value**: On success, returns a list of topics as a `RawResult`; on failure, returns an error.
|
||||
|
||||
- `fn describe(&self, table: &str) -> RawResult<Describe>`
|
||||
|
||||
- **Interface Description**: Describes the table structure.
|
||||
- **Parameter Description**:
|
||||
- `table`: The name of the table.
|
||||
- **Return Value**: On success, returns a description of the table structure as a `RawResult`; on failure, returns an error.
|
||||
|
||||
- `fn database_exists(&self, name: &str) -> RawResult<bool>`
|
||||
|
||||
- **Interface Description**: Checks if a database exists.
|
||||
- **Parameter Description**:
|
||||
- `name`: The name of the database.
|
||||
|
|
@ -243,11 +254,12 @@ The Taos struct provides multiple database operation APIs, including: executing
|
|||
- `data`: Schema-less data.
|
||||
- **Return Value**: On success, returns an empty `RawResult`; on failure, returns an error.
|
||||
|
||||
### SmlData
|
||||
### SmlData
|
||||
|
||||
The SmlData structure provides a data structure for schema-less writing and methods for accessing properties.
|
||||
|
||||
- `pub struct SmlData`
|
||||
|
||||
- **Structure Description**: The `SmlData` structure is used to store schema-less data and related information.
|
||||
- **Field Description**:
|
||||
- `protocol`: Schema-less protocol, supports InfluxDB `Line`, OpenTSDB `Telnet`, OpenTSDB `Json`.
|
||||
|
|
@ -257,18 +269,22 @@ The SmlData structure provides a data structure for schema-less writing and meth
|
|||
- `req_id`: Request ID.
|
||||
|
||||
- `pub fn protocol(&self) -> SchemalessProtocol`
|
||||
|
||||
- **Interface Description**: Gets the schema-less protocol.
|
||||
- **Return Value**: Schema-less protocol type, supports InfluxDB `Line`, OpenTSDB `Telnet`, OpenTSDB `Json`.
|
||||
|
||||
- `pub fn precision(&self) -> SchemalessPrecision`
|
||||
|
||||
- **Interface Description**: Gets the timestamp precision.
|
||||
- **Return Value**: Timestamp precision type, supports `Hours`, `Minutes`, `Seconds`, `Millisecond` (default), `Microsecond`, `Nanosecond`.
|
||||
|
||||
- `pub fn data(&self) -> &Vec<String>`
|
||||
|
||||
- **Interface Description**: Retrieves the list of data.
|
||||
- **Return Value**: Reference to the list of data.
|
||||
|
||||
- `pub fn ttl(&self) -> Option<i32>`
|
||||
|
||||
- **Interface Description**: Get the data time-to-live.
|
||||
- **Return Value**: Time-to-live of the data (optional), in seconds.
|
||||
|
||||
|
|
@ -276,41 +292,49 @@ The SmlData structure provides a data structure for schema-less writing and meth
|
|||
- **Interface Description**: Get the request ID.
|
||||
- **Return Value**: Request ID (optional).
|
||||
|
||||
### Result Retrieval
|
||||
### Result Retrieval
|
||||
|
||||
#### ResultSet
|
||||
|
||||
The ResultSet structure provides methods for accessing the data and metadata of the result set.
|
||||
|
||||
- `fn affected_rows(&self) -> i32`
|
||||
|
||||
- **Interface Description**: Get the number of affected rows.
|
||||
- **Return Value**: Number of affected rows, type `i32`.
|
||||
|
||||
- `fn precision(&self) -> Precision`
|
||||
|
||||
- **Interface Description**: Get precision information.
|
||||
- **Return Value**: Precision information, type `Precision`.
|
||||
|
||||
- `fn fields(&self) -> &[Field]`
|
||||
|
||||
- **Interface Description**: Get field information. See the Field structure description below.
|
||||
- **Return Value**: Reference to an array of field information.
|
||||
|
||||
- `fn summary(&self) -> (usize, usize)`
|
||||
|
||||
- **Interface Description**: Get summary information.
|
||||
- **Return Value**: A tuple containing two `usize` types, representing some statistical information.
|
||||
|
||||
- `fn num_of_fields(&self) -> usize`
|
||||
|
||||
- **Interface Description**: Get the number of fields.
|
||||
- **Return Value**: Number of fields, type `usize`.
|
||||
|
||||
- `fn blocks(&mut self) -> IBlockIter<'_, Self>`
|
||||
|
||||
- **Interface Description**: Get an iterator for the raw data blocks.
|
||||
- **Return Value**: Iterator for the raw data blocks, type `IBlockIter<'_, Self>`.
|
||||
|
||||
- `fn rows(&mut self) -> IRowsIter<'_, Self>`
|
||||
|
||||
- **Interface Description**: Get an iterator for row-wise querying.
|
||||
- **Return Value**: Iterator for row-wise querying, type `IRowsIter<'_, Self>`.
|
||||
|
||||
- `fn deserialize<T>(&mut self) -> Map<IRowsIter<'_, Self>, fn(_: Result<RowView<'_>, Error>) -> Result<T, Error>>`
|
||||
|
||||
- **Interface Description**: Deserialize row data.
|
||||
- **Generic Parameters**:
|
||||
- `T`: Target type, must implement `DeserializeOwned`.
|
||||
|
|
@ -320,15 +344,17 @@ The ResultSet structure provides methods for accessing the data and metadata of
|
|||
- **Interface Description**: Convert the result set into a two-dimensional vector of values.
|
||||
- **Return Value**: On success, returns a two-dimensional vector of values, on failure returns an error, type `Result<Vec<Vec<Value>>, Error>`.
|
||||
|
||||
#### Field
|
||||
#### Field
|
||||
|
||||
The Field structure provides methods for accessing field information.
|
||||
|
||||
- `pub const fn empty() -> Field`
|
||||
|
||||
- **Interface Description**: Create an empty `Field` instance.
|
||||
- **Return Value**: Returns an empty `Field` instance.
|
||||
|
||||
- `pub fn new(name: impl Into<String>, ty: Ty, bytes: u32) -> Field`
|
||||
|
||||
- **Interface Description**: Create a new `Field` instance.
|
||||
- **Parameter Description**:
|
||||
- `name`: Field name.
|
||||
|
|
@ -337,22 +363,27 @@ The Field structure provides methods for accessing field information.
|
|||
- **Return Value**: Returns a new `Field` instance.
|
||||
|
||||
- `pub fn name(&self) -> &str`
|
||||
|
||||
- **Interface Description**: Get the field name.
|
||||
- **Return Value**: Returns the field name.
|
||||
|
||||
- `pub fn escaped_name(&self) -> String`
|
||||
|
||||
- **Interface Description**: Get the escaped field name.
|
||||
- **Return Value**: Returns the escaped field name.
|
||||
|
||||
- `pub const fn ty(&self) -> Ty`
|
||||
|
||||
- **Interface Description**: Get the field type.
|
||||
- **Return Value**: Returns the field type.
|
||||
|
||||
- `pub const fn bytes(&self) -> u32`
|
||||
|
||||
- **Interface Description**: Get the preset length of the field.
|
||||
- **Return Value**: For variable-length data types, returns the preset length; for other types, returns the byte width.
|
||||
|
||||
- `pub fn to_c_field(&self) -> c_field_t`
|
||||
|
||||
- **Interface Description**: Converts a `Field` instance into a C language structure.
|
||||
- **Return Value**: Returns the field represented by a C language structure.
|
||||
|
||||
|
|
@ -364,17 +395,19 @@ The Field structure provides methods for accessing field information.
|
|||
|
||||
Parameter binding functionality is mainly supported by the Stmt structure.
|
||||
|
||||
#### Stmt
|
||||
#### Stmt
|
||||
|
||||
The Stmt structure provides functionality related to parameter binding, used for efficient writing.
|
||||
|
||||
- `fn init(taos: &Q) -> RawResult<Self>`
|
||||
|
||||
- **Interface Description**: Initialize the parameter binding instance.
|
||||
- **Parameter Description**:
|
||||
- `taos`: Database connection instance.
|
||||
- **Return Value**: On success, returns the initialized instance; on failure, returns an error.
|
||||
|
||||
- `fn init_with_req_id(taos: &Q, req_id: u64) -> RawResult<Self>`
|
||||
|
||||
- **Interface Description**: Initialize the parameter binding instance using a request ID.
|
||||
- **Parameter Description**:
|
||||
- `taos`: Database connection instance.
|
||||
|
|
@ -382,24 +415,28 @@ The Stmt structure provides functionality related to parameter binding, used for
|
|||
- **Return Value**: On success, returns the initialized instance; on failure, returns an error.
|
||||
|
||||
- `fn prepare<S: AsRef<str>>(&mut self, sql: S) -> RawResult<&mut Self>`
|
||||
|
||||
- **Interface Description**: Prepare the SQL statement to be bound.
|
||||
- **Parameter Description**:
|
||||
- `sql`: SQL statement to prepare.
|
||||
- **Return Value**: On success, returns a mutable reference to itself; on failure, returns an error.
|
||||
|
||||
- `fn set_tbname<S: AsRef<str>>(&mut self, name: S) -> RawResult<&mut Self>`
|
||||
|
||||
- **Interface Description**: Set the table name.
|
||||
- **Parameter Description**:
|
||||
- `name`: Table name.
|
||||
- **Return Value**: On success, returns a mutable reference to itself; on failure, returns an error.
|
||||
|
||||
- `fn set_tags(&mut self, tags: &[Value]) -> RawResult<&mut Self>`
|
||||
|
||||
- **Interface Description**: Set tags.
|
||||
- **Parameter Description**:
|
||||
- `tags`: Array of tags.
|
||||
- **Return Value**: On success, returns a mutable reference to itself; on failure, returns an error.
|
||||
|
||||
- `fn set_tbname_tags<S: AsRef<str>>(&mut self, name: S, tags: &[Value]) -> RawResult<&mut Self>`
|
||||
|
||||
- **Interface Description**: Set the table name and tags.
|
||||
- **Parameter Description**:
|
||||
- `name`: Table name.
|
||||
|
|
@ -407,16 +444,19 @@ The Stmt structure provides functionality related to parameter binding, used for
|
|||
- **Return Value**: On success, returns a mutable reference to itself; on failure, returns an error.
|
||||
|
||||
- `fn bind(&mut self, params: &[ColumnView]) -> RawResult<&mut Self>`
|
||||
|
||||
- **Interface Description**: Bind parameters.
|
||||
- **Parameter Description**:
|
||||
- `params`: Array of parameters.
|
||||
- **Return Value**: On success, returns a mutable reference to itself; on failure, returns an error.
|
||||
|
||||
- `fn add_batch(&mut self) -> RawResult<&mut Self>`
|
||||
|
||||
- **Interface Description**: Add a batch.
|
||||
- **Return Value**: On success, returns a mutable reference to itself; on failure, returns an error.
|
||||
|
||||
- `fn execute(&mut self) -> RawResult<usize>`
|
||||
|
||||
- **Interface Description**: Execute the statement.
|
||||
- **Return Value**: On success, returns the number of affected rows; on failure, returns an error.
|
||||
|
||||
|
|
@ -433,26 +473,31 @@ Data subscription mainly involves three structures, providing connection establi
|
|||
Similar to TaosBuilder, TmqBuilder provides the functionality to create consumer objects.
|
||||
|
||||
- `fn available_params() -> &'static [&'static str]`
|
||||
|
||||
- **Interface Description**: Get the list of available parameters in the DSN.
|
||||
- **Return Value**: Returns a reference to a static slice of strings, containing the names of available parameters.
|
||||
|
||||
- `fn from_dsn<D: IntoDsn>(dsn: D) -> RawResult<Self>`
|
||||
|
||||
- **Interface Description**: Create a connection using a DSN string, without checking the connection.
|
||||
- **Parameter Description**:
|
||||
- `dsn`: DSN string or a type that can be converted into DSN.
|
||||
- **Return Value**: On success, returns `RawResult` of its own type, on failure returns an error.
|
||||
|
||||
- `fn client_version() -> &'static str`
|
||||
|
||||
- **Interface Description**: Get the client version.
|
||||
- **Return Value**: Returns a static string of the client version.
|
||||
|
||||
- `fn ping(&self, conn: &mut Self::Target) -> RawResult<()>`
|
||||
|
||||
- **Interface Description**: Check if the connection is still alive.
|
||||
- **Parameter Description**:
|
||||
- `conn`: Mutable reference to the target connection.
|
||||
- **Return Value**: On success, returns an empty `RawResult`, on failure returns an error.
|
||||
|
||||
- `fn ready(&self) -> bool`
|
||||
|
||||
- **Interface Description**: Check if it is ready to connect.
|
||||
- **Return Value**: Mostly returns `true`, indicating that the address is ready to connect.
|
||||
|
||||
|
|
@ -465,24 +510,28 @@ Similar to TaosBuilder, TmqBuilder provides the functionality to create consumer
|
|||
The Consumer structure provides subscription-related functionalities, including subscribing, fetching messages, committing offsets, setting offsets, etc.
|
||||
|
||||
- `fn subscribe<T: Into<String>, I: IntoIterator<Item = T> + Send>(&mut self, topics: I) -> RawResult<()>`
|
||||
|
||||
- **Interface Description**: Subscribe to a series of topics.
|
||||
- **Parameter Description**:
|
||||
- `topics`: List of topics to subscribe to.
|
||||
- **Return Value**: On success, returns an empty `RawResult`, on failure returns an error.
|
||||
|
||||
- `fn recv_timeout(&self, timeout: Timeout) -> RawResult<Option<(Self::Offset, MessageSet<Self::Meta, Self::Data>)>>`
|
||||
|
||||
- **Interface Description**: Receive messages within a specified timeout period.
|
||||
- **Parameter Description**:
|
||||
- `timeout`: Timeout period.
|
||||
- **Return Value**: On success, returns messages, on failure returns an error.
|
||||
|
||||
- `fn commit(&self, offset: Self::Offset) -> RawResult<()>`
|
||||
|
||||
- **Interface Description**: Commit the given offset.
|
||||
- **Parameter Description**:
|
||||
- `offset`: The offset to commit, see the Offset structure below.
|
||||
- **Return Value**: On success, returns an empty `RawResult`, on failure returns an error.
|
||||
|
||||
- `fn commit_offset(&self, topic_name: &str, vgroup_id: VGroupId, offset: i64) -> RawResult<()>`
|
||||
|
||||
- **Interface Description**: Commit offset for a specific topic and partition.
|
||||
- **Parameter Description**:
|
||||
- `topic_name`: Topic name.
|
||||
|
|
@ -491,14 +540,17 @@ The Consumer structure provides subscription-related functionalities, including
|
|||
- **Return Value**: On success, returns an empty `RawResult`, on failure returns an error.
|
||||
|
||||
- `fn list_topics(&self) -> RawResult<Vec<String>>`
|
||||
|
||||
- **Interface Description**: List all available topics.
|
||||
- **Return Value**: On success, returns a list of topics, on failure returns an error.
|
||||
|
||||
- `fn assignments(&self) -> Option<Vec<(String, Vec<Assignment>)>>`
|
||||
|
||||
- **Interface Description**: Get the current assignments of topics and partitions.
|
||||
- **Return Value**: On success, returns assignment information, on failure returns `None`.
|
||||
|
||||
- `fn offset_seek(&mut self, topic: &str, vg_id: VGroupId, offset: i64) -> RawResult<()>`
|
||||
|
||||
- **Interface Description**: Set the offset for a specific topic and partition.
|
||||
- **Parameter Description**:
|
||||
- `topic`: Topic name.
|
||||
|
|
@ -507,6 +559,7 @@ The Consumer structure provides subscription-related functionalities, including
|
|||
- **Return Value**: On success, returns an empty `RawResult`, on failure returns an error.
|
||||
|
||||
- `fn committed(&self, topic: &str, vgroup_id: VGroupId) -> RawResult<i64>`
|
||||
|
||||
- **Interface Description**: Get the committed offset for a specific topic and partition.
|
||||
- **Parameter Description**:
|
||||
- `topic`: Topic name.
|
||||
|
|
@ -525,10 +578,12 @@ The Consumer structure provides subscription-related functionalities, including
|
|||
The Offset structure provides information about the database, topic, and partition to which the current message belongs.
|
||||
|
||||
- `fn database(&self) -> &str`
|
||||
|
||||
- **Interface Description**: Get the database name of the current message.
|
||||
- **Return Value**: Reference to the database name.
|
||||
|
||||
- `fn topic(&self) -> &str`
|
||||
|
||||
- **Interface Description**: Get the topic name of the current message.
|
||||
- **Return Value**: Reference to the topic name.
|
||||
|
||||
|
|
@ -536,7 +591,7 @@ The Offset structure provides information about the database, topic, and partiti
|
|||
- **Interface Description**: Get the partition ID of the current message.
|
||||
- **Return Value**: Partition ID.
|
||||
|
||||
## Appendix
|
||||
## Appendix
|
||||
|
||||
- [Rust connector documentation](https://docs.rs/taos)
|
||||
- [Rust connector project URL](https://github.com/taosdata/taos-connector-rust)
|
||||
|
|
|
|||
|
|
@ -8,55 +8,70 @@ import Tabs from "@theme/Tabs";
|
|||
import TabItem from "@theme/TabItem";
|
||||
import RequestId from "./_request_id.mdx";
|
||||
|
||||
`taospy` is the official Python connector for TDengine. `taospy` provides a rich API, making it convenient for Python applications to use TDengine.
|
||||
`taopsy` is the official connector provided by TDengine database for Python language, which provides multiple access interfaces for database writing, querying, subscribing, etc.
|
||||
|
||||
The source code for the Python connector is hosted on [GitHub](https://github.com/taosdata/taos-connector-python).
|
||||
The installation command is as follows:
|
||||
``` bash
|
||||
# Native connection and REST connection
|
||||
pip3 install taospy
|
||||
|
||||
# WebSocket connection, optional installation
|
||||
pip3 install taos-ws-py
|
||||
```
|
||||
|
||||
The connector code is open sourced and hosted on Github [Taos Connector Python](https://github.com/taosdata/taos-connector-python).
|
||||
|
||||
## Connection Methods
|
||||
|
||||
`taospy` mainly provides three types of connectors. We generally recommend using **WebSocket Connection**.
|
||||
`taopsy` provides three connection methods, and we recommend using WebSocket connection.
|
||||
|
||||
- **Native Connection**, corresponding to the `taos` module of the `taospy` package. Connects to a TDengine instance natively through the TDengine client driver (taosc), supporting data writing, querying, data subscription, schemaless interface, and parameter binding interface.
|
||||
- **REST Connection**, corresponding to the `taosrest` module of the `taospy` package. Connects to a TDengine instance through the HTTP interface provided by taosAdapter, does not support schemaless and data subscription features.
|
||||
- **WebSocket Connection**, corresponding to the `taos-ws-py` package, which is optional. Connects to a TDengine instance through the WebSocket interface provided by taosAdapter, with a feature set slightly different from the native connection.
|
||||
- **Native Connection**, Python connector loads TDengine client driver (libtaos.so/taos.dll), directly connects to TDengine instance, with high performance and fast speed.
|
||||
Functionally, it supports functions such as data writing, querying, data subscription, schemaless interface, and parameter binding interface.
|
||||
- **REST Connection**, The Python connector connects to the TDengine instance through the HTTP interface provided by the taosAdapter, with minimal dependencies and no need to install the TDengine client driver.
|
||||
Functionality does not support features such as schemaless and data subscription.
|
||||
- **WebSocket Connection**, The Python connector connects to the TDengine instance through the WebSocket interface provided by the taosAdapter, which combines the advantages of the first two types of connections, namely high performance and low dependency.
|
||||
In terms of functionality, there are slight differences between the WebSocket connection implementation feature set and native connections.
|
||||
|
||||
For a detailed introduction to connection methods, please refer to: [Connection Methods](../../../developer-guide/connecting-to-tdengine/)
|
||||
For a detailed introduction of the connection method, please refer to: [Connection Method](../../../developer-guide/connecting-to-tdengine/)
|
||||
|
||||
In addition to encapsulating the native and REST interfaces, `taospy` also provides a programming interface compliant with [Python Data Access Standard (PEP 249)](https://peps.python.org/pep-0249/). This makes `taospy` easily integrated with many third-party tools, such as [SQLAlchemy](https://www.sqlalchemy.org/) and [pandas](https://pandas.pydata.org/).
|
||||
In addition to encapsulating Native and REST interfaces, `taopsy` also provides compliance with [the Python Data Access Specification (PEP 249)](https://peps.python.org/pep-0249/) The programming interface.
|
||||
This makes it easy to integrate `taopsy` with many third-party tools, such as [SQLAlchemy](https://www.sqlalchemy.org/) and [pandas](https://pandas.pydata.org/).
|
||||
|
||||
The method of establishing a connection directly with the server using the native interface provided by the client driver is referred to as "Native Connection"; the method of establishing a connection with the server using the REST interface or WebSocket interface provided by taosAdapter is referred to as "REST Connection" or "WebSocket Connection".
|
||||
The method of establishing a connection directly with the server using the native interface provided by the client driver is referred to as "Native Connection" in the following text;
|
||||
The method of establishing a connection with the server using the REST interface or WebSocket interface provided by the taosAdapter is referred to as a "REST Connection" or "WebSocket connection" in the following text.
|
||||
|
||||
## Python Version Compatibility
|
||||
|
||||
Supports Python 3.0 and above.
|
||||
|
||||
## Supported Platforms
|
||||
|
||||
- Native Connection [Supported Platforms](../../supported-platforms/) are consistent with the platforms supported by the TDengine client.
|
||||
- REST Connection supports all platforms that can run Python.
|
||||
-The platforms supported by native connections are consistent with those supported by the TDengine client driver.
|
||||
-WebSocket/REST connections support all platforms that can run Python.
|
||||
|
||||
### Supported Features
|
||||
## Versions History
|
||||
|
||||
- Native Connection supports all core features of TDengine, including: connection management, executing SQL, parameter binding, subscription, schemaless writing.
|
||||
- REST Connection supports features including: connection management, executing SQL. (Through executing SQL, you can: manage databases, manage tables and supertables, write data, query data, create continuous queries, etc.)
|
||||
Python Connector historical versions (it is recommended to use the latest version of 'taopsy'):
|
||||
|
||||
## Version History
|
||||
|Python Connector Version | Major Changes | TDengine Version|
|
||||
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
|
||||
|2.7.16 | Add subscription configuration (session. timeout. ms, Max. roll. interval. ms). | - |
|
||||
|2.7.15 | Added support for VARBINRY and GEOMETRY types. | - |
|
||||
|2.7.14 | Fix Known Issues. | - |
|
||||
|2.7.13 | Added tmq synchronous submission offset interface. | - |
|
||||
|2.7.12 | 1. Added support for varbinary type (STMT currently does not support varbinary). <br/> 2 Query performance improvement (thanks to contributor [hadrianl](https://github.com/taosdata/taos-connector-python/pull/209) ). | 3.1.1.2 and higher|
|
||||
|2.7.9 | Data subscription supports obtaining and resetting consumption progress. | 3.0.2.6 and higher|
|
||||
|2.7.8 | Added 'executioner_many'. | 3.0.0.0 and higher|
|
||||
|
||||
Regardless of the version of TDengine used, it is recommended to use the latest version of `taospy`.
|
||||
WebSocket Connector Historical Versions:
|
||||
|
||||
|Python Connector Version|Main Changes|
|
||||
|:-------------------:|:----:|
|
||||
|2.7.16|Added subscription configuration (session.timeout.ms, max.poll.interval.ms)|
|
||||
|2.7.15|Added support for VARBINARY and GEOMETRY types|
|
||||
|2.7.14|Fixed known issues|
|
||||
|2.7.13|Added tmq synchronous commit offset interface|
|
||||
|2.7.12|1. Added support for varbinary type (STMT does not support varbinary yet) <br/> 2. Improved query performance (thanks to contributor [hadrianl](https://github.com/taosdata/taos-connector-python/pull/209))|
|
||||
|2.7.9|Data subscription supports obtaining consumption progress and resetting consumption progress|
|
||||
|2.7.8|Added `execute_many`|
|
||||
|
||||
|Python WebSocket Connector Version|Major Changes|
|
||||
|:----------------------------:|:-----:|
|
||||
|0.3.5|Added support for VARBINARY and GEOMETRY types, fixed known issues|
|
||||
|0.3.2|Optimized WebSocket SQL query and insertion performance, updated readme and documentation, fixed known issues|
|
||||
|0.2.9|Fixed known issues|
|
||||
|0.2.5|1. Data subscription supports obtaining and resetting consumption progress <br/> 2. Supports schemaless <br/> 3. Supports STMT|
|
||||
|0.2.4|Data subscription adds unsubscribe method|
|
||||
|WebSocket Connector Version | Major Changes | TDengine Version|
|
||||
| ----------------------- | -------------------------------------------------------------------------------------------------- | ----------------- |
|
||||
|0.3.5 | Added support for VARBINARY and GEOMETRY types, fixed known issues. | 3.3.0.0 and higher|
|
||||
|0.3.2 | Optimize WebSocket SQL query and insertion performance, modify readme and documentation, fix known issues. | 3.2.3.0 and higher|
|
||||
|0.2.9 | Known issue fixes. | - |
|
||||
|0.2.5 | 1. Data subscription supports obtaining and resetting consumption progress. <br/>2 Support schemaless. <br/>3 Support STMT. | - |
|
||||
|0.2.4 | Data Subscription Addition/Unsubscribe Method. | 3.0.5.0 and higher|
|
||||
|
||||
## Exception Handling
|
||||
|
||||
|
|
@ -69,7 +84,7 @@ The Python connector may generate 4 types of exceptions:
|
|||
- For other TDengine module errors, please refer to [Error Codes](../../error-codes/)
|
||||
|
||||
|Error Type|Description|Suggested Actions|
|
||||
|:--------:|:---------:|:---------------:|
|
||||
|:---------|:----------|:----------------|
|
||||
|InterfaceError|taosc version too low, does not support the used interface|Please check the TDengine client version|
|
||||
|ConnectionError|Database connection error|Please check the TDengine server status and connection parameters|
|
||||
|DatabaseError|Database error|Please check the TDengine server version and upgrade the Python connector to the latest version|
|
||||
|
|
@ -94,7 +109,7 @@ All database operations in the Python Connector, if an exception occurs, will be
|
|||
TDengine currently supports timestamp, numeric, character, boolean types, and the corresponding Python type conversions are as follows:
|
||||
|
||||
|TDengine DataType|Python DataType|
|
||||
|:---------------:|:-------------:|
|
||||
|:---------------|:--------------|
|
||||
|TIMESTAMP|datetime|
|
||||
|INT|int|
|
||||
|BIGINT|int|
|
||||
|
|
|
|||
|
|
@ -12,23 +12,21 @@ import RequestId from "./_request_id.mdx";
|
|||
|
||||
The source code for the Node.js connector is hosted on [GitHub](https://github.com/taosdata/taos-connector-node/tree/main).
|
||||
|
||||
## Connection Method
|
||||
## Node.js Version Compatibility
|
||||
|
||||
The Node.js connector currently only supports WebSocket connections, which connect to a TDengine instance through the WebSocket interface provided by taosAdapter.
|
||||
|
||||
For a detailed introduction to the connection method, please refer to: [Connection Method](../../../developer-guide/connecting-to-tdengine/)
|
||||
- Supports Node.js 14 and above.
|
||||
|
||||
## Supported Platforms
|
||||
|
||||
Supports Node.js version 14 and above.
|
||||
- Support all platforms that can run Node.js.
|
||||
|
||||
## Version History
|
||||
|
||||
| Node.js Connector Version | Major Changes | TDengine Version |
|
||||
| :------------------: | :----------------------: | :----------------: |
|
||||
| 3.1.2 | Optimized data protocol and parsing, significantly improved performance| 3.3.2.0 and higher versions |
|
||||
| 3.1.1 | Optimized data transmission performance | 3.3.2.0 and higher versions |
|
||||
| 3.1.0 | New release, supports WebSocket connection | 3.2.0.0 and higher versions |
|
||||
| ------------------ | ---------------------- | ----------------|
|
||||
| 3.1.2 | Optimized data protocol and parsing, significantly improved performance.| - |
|
||||
| 3.1.1 | Optimized data transmission performance. | 3.3.2.0 and higher versions |
|
||||
| 3.1.0 | New release, supports WebSocket connection. | 3.2.0.0 and higher versions |
|
||||
|
||||
## Exception Handling
|
||||
|
||||
|
|
|
|||
|
|
@ -10,38 +10,27 @@ import RequestId from "./_request_id.mdx";
|
|||
|
||||
`TDengine.Connector` is the C# language connector provided by TDengine. C# developers can use it to develop C# applications that access data in the TDengine cluster.
|
||||
|
||||
## Connection Methods
|
||||
## .Net Version Compatibility
|
||||
|
||||
`TDengine.Connector` provides two types of connectors:
|
||||
|
||||
* **Native Connection**, which connects to a TDengine instance natively through the TDengine client driver (taosc), supporting data writing, querying, data subscription, schemaless interfaces, and parameter binding interfaces.
|
||||
* **WebSocket Connection**, which connects to a TDengine instance through the WebSocket interface provided by taosAdapter, with a slightly different set of features implemented compared to the native connection. (From v3.0.1 onwards)
|
||||
|
||||
For a detailed introduction to connection methods, please refer to: [Connection Methods](../../../developer-guide/connecting-to-tdengine/)
|
||||
|
||||
## Compatibility
|
||||
|
||||
* `TDengine.Connector` version 3.1.0 has been completely restructured and is no longer compatible with versions 3.0.2 and earlier. For documentation on version 3.0.2, please refer to [nuget](https://www.nuget.org/packages/TDengine.Connector/3.0.2)
|
||||
* `TDengine.Connector` 3.x is not compatible with TDengine 2.x. If you need to use the C# connector in an environment running TDengine 2.x, please use version 1.x of TDengine.Connector.
|
||||
- Supports .NET Framework 4.6 and above.
|
||||
- Supports .NET 5.0 and above.
|
||||
|
||||
## Supported Platforms
|
||||
|
||||
The supported platforms are consistent with those supported by the TDengine client driver.
|
||||
- Native connection supports the same platforms as the TDengine client driver.
|
||||
- WebSocket connection supports all platforms that can run the .NET runtime.
|
||||
|
||||
:::warning
|
||||
TDengine no longer supports the 32-bit Windows platform.
|
||||
:::
|
||||
## Version History
|
||||
|
||||
## Version Support
|
||||
| Connector Version | Major Changes | TDengine Version |
|
||||
|------------------|-------------------------------------------------|-------------------|
|
||||
| 3.1.4 | Improved WebSocket query and insert performance. | 3.3.2.0 and higher |
|
||||
| 3.1.3 | Supported WebSocket auto-reconnect. | - |
|
||||
| 3.1.2 | Fixed schemaless resource release. | - |
|
||||
| 3.1.1 | Supported varbinary and geometry types. | - |
|
||||
| 3.1.0 | WebSocket uses a native C# implementation. | 3.2.1.0 and higher |
|
||||
|
||||
| **Connector Version** | **TDengine Version** | **Main Features** |
|
||||
|------------------|------------------|----------------------------|
|
||||
| 3.1.3 | 3.2.1.0/3.1.1.18 | Supports WebSocket auto-reconnect |
|
||||
| 3.1.2 | 3.2.1.0/3.1.1.18 | Fixes schemaless resource release |
|
||||
| 3.1.1 | 3.2.1.0/3.1.1.18 | Supports varbinary and geometry types |
|
||||
| 3.1.0 | 3.2.1.0/3.1.1.18 | Native implementation of WebSocket |
|
||||
|
||||
## Exception Handling
|
||||
## Exceptions and Error Codes
|
||||
|
||||
`TDengine.Connector` will throw exceptions, and applications need to handle these exceptions. The taosc exception type `TDengineError` includes an error code and error message, which applications can use to handle the error.
|
||||
For error reporting in other TDengine modules, please refer to [Error Codes](../../error-codes/)
|
||||
|
|
|
|||
|
|
@ -20,7 +20,7 @@ TDengine ODBC provides both 64-bit and 32-bit drivers. However, the 32-bit versi
|
|||
|
||||
## ODBC Version Compatibility
|
||||
|
||||
- Supports ODBC 3.8 and all previous versions.
|
||||
- Supports all ODBC versions.
|
||||
|
||||
## Installation
|
||||
|
||||
|
|
@ -119,12 +119,12 @@ In addition to this, the WebSocket connection method also supports 32-bit applic
|
|||
|
||||
## Version History
|
||||
|
||||
| taos_odbc Version | Main Changes | TDengine Version |
|
||||
| :----------- | :-------------------------------------------------------------------------------------------------- | :---------------- |
|
||||
| v1.1.0 | 1. Supports view functionality;<br/>2. Supports VARBINARY/GEOMETRY data types;<br/>3. Supports ODBC 32-bit WebSocket connection method (Enterprise edition only);<br/>4. Supports ODBC data source configuration dialog settings for compatibility adaptation options for industrial software like KingSCADA, Kepware, etc. (Enterprise edition only); | 3.3.3.0 and higher |
|
||||
| v1.0.2 | Supports CP1252 character encoding; | 3.2.3.0 and higher |
|
||||
| v1.0.1 | 1. Supports DSN settings for BI mode, in BI mode TDengine database does not return system database and supertable subtable information;<br/>2. Refactored character set conversion module, improving read and write performance;<br/>3. Default connection method in ODBC data source configuration dialog changed to "WebSocket";<br/>4. Added "Test Connection" control in ODBC data source configuration dialog;<br/>5. ODBC data source configuration supports Chinese/English interface; | - |
|
||||
| v1.0.0.0 | Initial release, supports interacting with Tdengine database to read and write data, refer to the "API Reference" section for details | 3.2.2.0 and higher |
|
||||
| taos_odbc Version | Major Changes | TDengine Version |
|
||||
| ----------- | -------------------------------------------------------------------------------------------------- | ---------------- |
|
||||
| v1.1.0 | 1. Supports view functionality. <br/>2. Supports VARBINARY/GEOMETRY data types. <br/>3. Supports ODBC 32-bit WebSocket connection method (Enterprise edition only). <br/>4. Supports ODBC data source configuration dialog settings for compatibility adaptation options for industrial software like KingSCADA, Kepware, etc. (Enterprise edition only). | 3.3.3.0 and higher |
|
||||
| v1.0.2 | Supports CP1252 character encoding. | 3.2.3.0 and higher |
|
||||
| v1.0.1 | 1. Supports DSN settings for BI mode, in BI mode TDengine database does not return system database and supertable subtable information. <br/>2. Refactored character set conversion module, improving read and write performance. <br/> 3. Default connection method in ODBC data source configuration dialog changed to "WebSocket". <br/>4. Added "Test Connection" control in ODBC data source configuration dialog. <br/>5. ODBC data source configuration supports Chinese/English interface. | - |
|
||||
| v1.0.0.0 | Initial release, supports interacting with Tdengine database to read and write data, refer to the "API Reference" section for details. | 3.2.2.0 and higher |
|
||||
|
||||
## Data Type Mapping
|
||||
|
||||
|
|
|
|||
|
|
@ -26,7 +26,6 @@ async function createDbAndTable() {
|
|||
let conf = new taos.WSConfig(dsn);
|
||||
conf.setUser('root');
|
||||
conf.setPwd('taosdata');
|
||||
conf.setDb('power');
|
||||
wsSql = await taos.sqlConnect(conf);
|
||||
console.log("Connected to " + dsn + " successfully.");
|
||||
// create database
|
||||
|
|
|
|||
|
|
@ -37,8 +37,8 @@ TDengine 客户端驱动的动态库位于：
|
|||
### 版本历史
|
||||
|
||||
| TDengine 客户端版本 | 主要变化 | TDengine 版本 |
|
||||
| :------------------: | :---------------------------: | :----------------: |
|
||||
| 3.3.3.0 | 首次发布，提供了 SQL执行，参数绑定，无模式写入和数据订阅等全面功能支持。 | 3.3.2.0及更高版本 |
|
||||
| ------------------ | --------------------------- | ---------------- |
|
||||
| 3.3.3.0 | 首次发布，提供了 SQL执行，参数绑定，无模式写入和数据订阅等全面功能支持。 | 3.3.2.0 及更高版本 |
|
||||
|
||||
|
||||
### 错误码
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@ TDengine 的 JDBC 驱动实现尽可能与关系型数据库驱动保持一致
|
|||
|
||||
:::
|
||||
|
||||
## JDBC 和 JRE 兼容性
|
||||
## JDBC 和 JRE 版本兼容性
|
||||
|
||||
- JDBC: 支持 JDBC 4.2 及以上版本。
|
||||
- JRE: 支持 JRE 8 及以上版本。
|
||||
|
|
@ -32,7 +32,7 @@ TDengine 的 JDBC 驱动实现尽可能与关系型数据库驱动保持一致
|
|||
## 版本历史
|
||||
|
||||
| taos-jdbcdriver 版本 | 主要变化 | TDengine 版本 |
|
||||
| :------------------| :---------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------- |
|
||||
| ------------------| ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
|
||||
| 3.4.0 | 1. 使用 jackson 库替换 fastjson 库 <br/> 2. WebSocket 采用独立协议标识 <br/> 3. 优化后台拉取线程使用，避免用户误用导致超时 | - |
|
||||
| 3.3.4 | 解决了 getInt 在数据类型为 float 报错 | - |
|
||||
| 3.3.3 | 解决了 WebSocket statement 关闭导致的内存泄漏 | - |
|
||||
|
|
|
|||
|
|
@ -12,9 +12,9 @@ import RequestId from "./_request_id.mdx";
|
|||
|
||||
`driver-go` 是 TDengine 的官方 Go 语言连接器，实现了 Go 语言 [database/sql](https://golang.org/pkg/database/sql/) 包的接口。Go 开发人员可以通过它开发存取 TDengine 集群数据的应用软件。
|
||||
|
||||
## 兼容性
|
||||
## Go 版本兼容性
|
||||
|
||||
支持 Go 版本 1.14及以上版本。
|
||||
支持 Go 1.14 及以上版本。
|
||||
|
||||
## 支持的平台
|
||||
|
||||
|
|
@ -23,24 +23,24 @@ import RequestId from "./_request_id.mdx";
|
|||
|
||||
## 版本历史
|
||||
|
||||
| driver-go 版本 | 主要变化 | TDengine 版本 |
|
||||
|:-------------|:-------------------------------------|:------------|
|
||||
| v3.5.8 | 修复空指针异常 | 3.3.2.0 |
|
||||
| v3.5.7 | taosWS 和 taosRestful 支持传入 request id | 3.3.2.0 |
|
||||
| v3.5.6 | 提升 websocket 查询和写入性能 | 3.3.2.0 |
|
||||
| v3.5.5 | restful 支持跳过 ssl 证书检查 | 3.2.3.0 |
|
||||
| v3.5.4 | 兼容 TDengine 3.3.0.0 tmq raw data | 3.2.3.0 |
|
||||
| v3.5.3 | 重构 taosWS | 3.2.3.0 |
|
||||
| v3.5.2 | websocket 压缩和优化消息订阅性能 | 3.2.3.0 |
|
||||
| v3.5.1 | 原生 stmt 查询和 geometry 类型支持 | 3.2.1.0 |
|
||||
| v3.5.0 | 获取消费进度及按照指定进度开始消费 | 3.0.5.0 |
|
||||
| v3.3.1 | 基于 websocket 的 schemaless 协议写入 | 3.0.4.1 |
|
||||
| v3.1.0 | 提供贴近 kafka 的订阅 api | 3.0.2.2 |
|
||||
| v3.0.4 | 新增 request id 相关接口 | 3.0.2.2 |
|
||||
| v3.0.3 | 基于 websocket 的 statement 写入 | 3.0.1.5 |
|
||||
| v3.0.2 | 基于 websocket 的数据查询和写入 | 3.0.1.5 |
|
||||
| v3.0.1 | 基于 websocket 的消息订阅 | 3.0.0.0 |
|
||||
| v3.0.0 | 适配 TDengine 3.0 查询和写入 | 3.0.0.0 |
|
||||
| driver-go 版本 | 主要变化 | TDengine 版本 |
|
||||
|-------------|-------------------------------------|---------------|
|
||||
| v3.5.8 | 修复空指针异常 | - |
|
||||
| v3.5.7 | taosWS 和 taosRestful 支持传入 request id | - |
|
||||
| v3.5.6 | 提升 websocket 查询和写入性能 | 3.3.2.0 及更高版本 |
|
||||
| v3.5.5 | restful 支持跳过 ssl 证书检查 | - |
|
||||
| v3.5.4 | 兼容 TDengine 3.3.0.0 tmq raw data | - |
|
||||
| v3.5.3 | 重构 taosWS | - |
|
||||
| v3.5.2 | websocket 压缩和优化消息订阅性能 | 3.2.3.0 及更高版本 |
|
||||
| v3.5.1 | 原生 stmt 查询和 geometry 类型支持 | 3.2.1.0 及更高版本 |
|
||||
| v3.5.0 | 获取消费进度及按照指定进度开始消费 | 3.0.5.0 及更高版本 |
|
||||
| v3.3.1 | 基于 websocket 的 schemaless 协议写入 | 3.0.4.1 及更高版本 |
|
||||
| v3.1.0 | 提供贴近 kafka 的订阅 api | - |
|
||||
| v3.0.4 | 新增 request id 相关接口 | 3.0.2.2 及更高版本 |
|
||||
| v3.0.3 | 基于 websocket 的 statement 写入 | - |
|
||||
| v3.0.2 | 基于 websocket 的数据查询和写入 | 3.0.1.5 及更高版本 |
|
||||
| v3.0.1 | 基于 websocket 的消息订阅 | - |
|
||||
| v3.0.0 | 适配 TDengine 3.0 查询和写入 | 3.0.0.0 及更高版本 |
|
||||
|
||||
## 异常和错误码
|
||||
|
||||
|
|
|
|||
|
|
@ -16,9 +16,9 @@ import RequestId from "./_request_id.mdx";
|
|||
|
||||
该 Rust 连接器的源码托管在 [GitHub](https://github.com/taosdata/taos-connector-rust)。
|
||||
|
||||
## Rust 兼容性
|
||||
## Rust 版本兼容性
|
||||
|
||||
支持 1.70 及以上版本。
|
||||
支持 Rust 1.70 及以上版本。
|
||||
|
||||
## 支持的平台
|
||||
|
||||
|
|
@ -28,16 +28,16 @@ import RequestId from "./_request_id.mdx";
|
|||
## 版本历史
|
||||
|
||||
| Rust 连接器版本 | 主要变化 | TDengine 版本 |
|
||||
| :-------------- | :---------------------------------------------------------------------------- | :----------------- |
|
||||
| -------------- | ---------------------------------------------------------------------------- | ----------------- |
|
||||
| v0.12.3 | 1. 优化了 WebSocket 查询和插入性能 <br/> 2. 支持了 VARBINARY 和 GEOMETRY 类型 | 3.3.0.0 及更高版本 |
|
||||
| v0.12.0 | WS 支持压缩。 | 3.2.3.0 及更高版本 |
|
||||
| v0.11.0 | TMQ 功能优化。 | 3.2.0.0 |
|
||||
| v0.10.0 | WS endpoint 变更。 | 3.1.0.0 |
|
||||
| v0.9.2 | STMT：ws 下获取 tag_fields、col_fields。 | 3.0.7.0 |
|
||||
| v0.8.12 | 消息订阅：获取消费进度及按照指定进度开始消费。 | 3.0.5.0 |
|
||||
| v0.8.0 | 支持无模式写入。 | 3.0.4.0 |
|
||||
| v0.7.6 | 支持在请求中使用 req_id。 | 3.0.3.0 |
|
||||
| v0.6.0 | 基础功能。 | 3.0.0.0 |
|
||||
| v0.12.0 | WebSocket 支持压缩 | 3.2.3.0 及更高版本 |
|
||||
| v0.11.0 | TMQ 功能优化 | 3.2.0.0 及更高版本 |
|
||||
| v0.10.0 | WebSocket endpoint 变更 | 3.1.0.0 及更高版本 |
|
||||
| v0.9.2 | STMT：WebSocket 下获取 tag_fields、col_fields | 3.0.7.0 及更高版本 |
|
||||
| v0.8.12 | 消息订阅：获取消费进度及按照指定进度开始消费 | 3.0.5.0 及更高版本 |
|
||||
| v0.8.0 | 支持无模式写入 | 3.0.4.0 及更高版本 |
|
||||
| v0.7.6 | 支持在请求中使用 req_id | 3.0.3.0 及更高版本 |
|
||||
| v0.6.0 | 基础功能 | 3.0.0.0 及更高版本 |
|
||||
|
||||
## 异常和错误码
|
||||
|
||||
|
|
|
|||
|
|
@ -2,60 +2,74 @@
|
|||
toc_max_heading_level: 4
|
||||
sidebar_label: Python
|
||||
title: TDengine Python Connector
|
||||
description: "taospy 是 TDengine 的官方 Python 连接器。taospy 提供了丰富的 API， 使得 Python 应用可以很方便地使用 TDengine。tasopy 对 TDengine 的原生接口和 REST 接口都进行了封装， 分别对应 tasopy 的两个子模块：taos 和 taosrest。除了对原生接口和 REST 接口的封装，taospy 还提供了符合 Python 数据访问规范(PEP 249)的编程接口。这使得 taospy 和很多第三方工具集成变得简单，比如 SQLAlchemy 和 pandas"
|
||||
description: "TDengine 数据库面向 Python 语言提供的连接器"
|
||||
---
|
||||
|
||||
import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem";
|
||||
import RequestId from "./_request_id.mdx";
|
||||
|
||||
`taospy` 是 TDengine 的官方 Python 连接器。`taospy` 提供了丰富的 API， 使得 Python 应用可以很方便地使用 TDengine。
|
||||
`taospy` 是 TDengine 数据库面向 Python 语言提供的官方连接器，连接器对外提供对数据库写入、查询、订阅等多种访问接口。
|
||||
|
||||
Python 连接器的源码托管在 [GitHub](https://github.com/taosdata/taos-connector-python)。
|
||||
安装连接器命令如下：
|
||||
``` bash
|
||||
# 原生连接和 REST 连接
|
||||
pip3 install taospy
|
||||
|
||||
# WebSocket 连接，可选装
|
||||
pip3 install taos-ws-py
|
||||
```
|
||||
|
||||
连接器代码对外开源，源码托管在 Github [taos-connector-python](https://github.com/taosdata/taos-connector-python) 仓库。
|
||||
|
||||
## 连接方式
|
||||
`taospy`主要提供三种形式的连接器。一般我们推荐使用 **WebSocket 连接**。
|
||||
- **原生连接**，对应 `taospy` 包的 `taos` 模块。通过 TDengine 客户端驱动程序（taosc）原生连接 TDengine 实例，支持数据写入、查询、数据订阅、schemaless 接口和参数绑定接口等功能。
|
||||
- **REST 连接**，对应 `taospy` 包的 `taosrest` 模块。通过 taosAdapter 提供的 HTTP 接口连接 TDengine 实例，不支持 schemaless 和数据订阅等特性。
|
||||
- **WebSocket 连接**，对应 `taos-ws-py` 包，可以选装。通过 taosAdapter 提供的 WebSocket 接口连接 TDengine 实例，WebSocket 连接实现的功能集合和原生连接有少量不同。
|
||||
|
||||
`taospy`提供三种连接方式，我们推荐使用 **WebSocket 连接**。
|
||||
|
||||
- **原生连接**，Python 连接器加载 TDengine 客户端驱动程序(libtaos.so/taos.dll)，直接连接 TDengine 实例，特点性能高，速度快。功能上支持数据写入、查询、数据订阅、schemaless 接口和参数绑定接口等功能。对应 `taospy` 包的 `taos` 模块。
|
||||
- **REST 连接**，Python 连接器通过 `taosAdapter` 提供的 HTTP 接口连接 TDengine 实例，特点依赖小，不需要安装 TDengine 客户端驱动。功能上不支持 schemaless 和数据订阅等特性。对应 `taospy` 包的 `taosrest` 模块。
|
||||
- **WebSocket 连接**，Python 连接器通过 `taosAdapter` 提供的 WebSocket 接口连接 TDengine 实例，特点是兼具前两种连接的优势， 即性能高又依赖小。功能上 WebSocket 连接实现功能集合和原生连接有少量不同。对应 `taos-ws-py` 包，可以选装。
|
||||
|
||||
连接方式的详细介绍请参考：[连接方式](../../../develop/connect/#连接方式)
|
||||
|
||||
除了对原生接口和 REST 接口的封装，`taospy` 还提供了符合 [Python 数据访问规范(PEP 249)](https://peps.python.org/pep-0249/) 的编程接口。这使得 `taospy` 和很多第三方工具集成变得简单，比如 [SQLAlchemy](https://www.sqlalchemy.org/) 和 [pandas](https://pandas.pydata.org/)。
|
||||
|
||||
使用客户端驱动提供的原生接口直接与服务端建立的连接的方式下文中称为“原生连接”；使用 taosAdapter 提供的 REST 接口或 WebSocket 接口与服务端建立的连接的方式下文中称为“REST 连接”或“WebSocket 连接”。
|
||||
使用客户端驱动提供的原生接口直接与服务端建立的连接的方式下文中称为“原生连接”；使用 `taosAdapter` 提供的 REST 接口或 WebSocket 接口与服务端建立的连接的方式下文中称为“REST 连接”或“WebSocket 连接”。
|
||||
|
||||
## Python 版本兼容性
|
||||
|
||||
支持 Python 3.0 及以上版本。
|
||||
|
||||
## 支持的平台
|
||||
|
||||
- 原生连接[支持的平台](../#支持的平台)和 TDengine 客户端支持的平台一致。
|
||||
- REST 连接支持所有能运行 Python 的平台。
|
||||
|
||||
### 支持的功能
|
||||
|
||||
- 原生连接支持 TDengine 的所有核心功能， 包括： 连接管理、执行 SQL、参数绑定、订阅、无模式写入（schemaless）。
|
||||
- REST 连接支持的功能包括：连接管理、执行 SQL。 (通过执行 SQL 可以： 管理数据库、管理表和超级表、写入数据、查询数据、创建连续查询等)。
|
||||
- 原生连接支持的平台和 TDengine 客户端驱动支持的平台一致。
|
||||
- WebSocket/REST 连接支持所有能运行 Python 的平台。
|
||||
|
||||
## 历史版本
|
||||
|
||||
无论使用什么版本的 TDengine 都建议使用最新版本的 `taospy`。
|
||||
Python Connector 历史版本（建议使用最新版本的 `taospy`）：
|
||||
|
||||
|Python Connector 版本|主要变化|
|
||||
|:-------------------:|:----:|
|
||||
|2.7.16|新增订阅配置 (session.timeout.ms, max.poll.interval.ms)|
|
||||
|2.7.15|新增 VARBINARY 和 GEOMETRY 类型支持|
|
||||
|2.7.14|修复已知问题|
|
||||
|2.7.13|新增 tmq 同步提交 offset 接口|
|
||||
|2.7.12|1. 新增 varbinary 类型支持（STMT暂不支持 varbinary ）<br/> 2. query 性能提升（感谢贡献者[hadrianl](https://github.com/taosdata/taos-connector-python/pull/209)）|
|
||||
|2.7.9|数据订阅支持获取消费进度和重置消费进度|
|
||||
|2.7.8|新增 `execute_many`|
|
||||
|
||||
|Python WebSocket Connector 版本|主要变化|
|
||||
|:----------------------------:|:-----:|
|
||||
|0.3.5|新增 VARBINARY 和 GEOMETRY 类型支持，修复已知问题|
|
||||
|0.3.2|优化 WebSocket sql 查询和插入性能，修改 readme 和 文档，修复已知问题|
|
||||
|0.2.9|已知问题修复|
|
||||
|0.2.5|1. 数据订阅支持获取消费进度和重置消费进度 <br/> 2. 支持 schemaless <br/> 3. 支持 STMT|
|
||||
|0.2.4|数据订阅新增取消订阅方法|
|
||||
| Python Connector 版本 | 主要变化 | TDengine 版本 |
|
||||
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
|
||||
| 2.7.16 | 新增订阅配置 (session.timeout.ms, max.poll.interval.ms) | - |
|
||||
| 2.7.15 | 新增 VARBINARY 和 GEOMETRY 类型支持 | - |
|
||||
| 2.7.14 | 修复已知问题 | - |
|
||||
| 2.7.13 | 新增 tmq 同步提交 offset 接口 | - |
|
||||
| 2.7.12 | 1. 新增 varbinary 类型支持（STMT暂不支持 varbinary ）<br/> 2. query 性能提升（感谢贡献者[hadrianl](https://github.com/taosdata/taos-connector-python/pull/209)） | 3.1.1.2 及更高版本 |
|
||||
| 2.7.9 | 数据订阅支持获取消费进度和重置消费进度 | 3.0.2.6 及更高版本 |
|
||||
| 2.7.8 | 新增 `execute_many` | 3.0.0.0 及更高版本 |
|
||||
|
||||
WebSocket Connector 历史版本：
|
||||
|
||||
|
||||
| WebSocket Connector 版本 | 主要变化 | TDengine 版本 |
|
||||
| ----------------------- | ------------------------------------------------------------------------------------- | ----------------- |
|
||||
| 0.3.5 | 新增 VARBINARY 和 GEOMETRY 类型支持，修复已知问题 | 3.3.0.0 及更高版本 |
|
||||
| 0.3.2 | 优化 WebSocket sql 查询和插入性能，修改 readme 和 文档，修复已知问题 | 3.2.3.0 及更高版本 |
|
||||
| 0.2.9 | 已知问题修复 | - |
|
||||
| 0.2.5 | 1. 数据订阅支持获取消费进度和重置消费进度 <br/> 2. 支持 schemaless <br/> 3. 支持 STMT | - |
|
||||
| 0.2.4 | 数据订阅新增取消订阅方法 | 3.0.5.0 及更高版本 |
|
||||
|
||||
## 处理异常
|
||||
|
||||
|
|
@ -67,17 +81,17 @@ Python 连接器可能会产生 4 种异常：
|
|||
- 数据订阅异常
|
||||
- TDengine 其他功能模块的报错，请参考 [错误码](../../../reference/error-code)
|
||||
|
||||
|Error Type|Description|Suggested Actions|
|
||||
|:--------:|:---------:|:---------------:|
|
||||
|InterfaceError|taosc 版本太低，不支持所使用的接口|请检查 TDengine 客户端版本|
|
||||
|ConnectionError|数据库链接错误|请检查 TDengine 服务端状态和连接参数|
|
||||
|DatabaseError|数据库错误|请检查 TDengine 服务端版本，并将 Python 连接器升级到最新版|
|
||||
|OperationalError|操作错误|API 使用错误，请检查代码|
|
||||
|ProgrammingError|接口调用错误|请检查提交的数据是否正确|
|
||||
|StatementError|stmt 相关异常|请检查绑定参数与 sql 是否匹配|
|
||||
|ResultError|操作数据错误|请检查操作的数据与数据库中的数据类型是否匹配|
|
||||
|SchemalessError|schemaless 相关异常|请检查数据格式及对应的协议类型是否正确|
|
||||
|TmqError|tmq 相关异常|请检查 Topic 及 consumer 配置是否正确|
|
||||
| Error Type | Description | Suggested Actions |
|
||||
| :--------------- | :--------------------------------- | :--------------------------------------------------------- |
|
||||
| InterfaceError | taosc 版本太低，不支持所使用的接口 | 请检查 TDengine 客户端版本 |
|
||||
| ConnectionError | 数据库链接错误 | 请检查 TDengine 服务端状态和连接参数 |
|
||||
| DatabaseError | 数据库错误 | 请检查 TDengine 服务端版本，并将 Python 连接器升级到最新版 |
|
||||
| OperationalError | 操作错误 | API 使用错误，请检查代码 |
|
||||
| ProgrammingError | 接口调用错误 | 请检查提交的数据是否正确 |
|
||||
| StatementError | stmt 相关异常 | 请检查绑定参数与 sql 是否匹配 |
|
||||
| ResultError | 操作数据错误 | 请检查操作的数据与数据库中的数据类型是否匹配 |
|
||||
| SchemalessError | schemaless 相关异常 | 请检查数据格式及对应的协议类型是否正确 |
|
||||
| TmqError | tmq 相关异常 | 请检查 Topic 及 consumer 配置是否正确 |
|
||||
|
||||
Python 中通常通过 try-expect 处理异常，异常处理相关请参考 [Python 错误和异常文档](https://docs.python.org/3/tutorial/errors.html)。
|
||||
TDengine 其他功能模块的报错，请参考 [错误码](../../../reference/error-code)
|
||||
|
|
@ -92,32 +106,32 @@ Python Connector 的所有数据库操作如果出现异常，都会直接抛出
|
|||
|
||||
TDengine 目前支持时间戳、数字、字符、布尔类型，与 Python 对应类型转换如下：
|
||||
|
||||
|TDengine DataType|Python DataType|
|
||||
|:---------------:|:-------------:|
|
||||
|TIMESTAMP|datetime|
|
||||
|INT|int|
|
||||
|BIGINT|int|
|
||||
|FLOAT|float|
|
||||
|DOUBLE|int|
|
||||
|SMALLINT|int|
|
||||
|TINYINT|int|
|
||||
|BOOL|bool|
|
||||
|BINARY|str|
|
||||
|NCHAR|str|
|
||||
|JSON|str|
|
||||
|GEOMETRY|bytearray|
|
||||
|VARBINARY|bytearray|
|
||||
| TDengine DataType | Python DataType |
|
||||
| :---------------- | :-------------- |
|
||||
| TIMESTAMP | datetime |
|
||||
| INT | int |
|
||||
| BIGINT | int |
|
||||
| FLOAT | float |
|
||||
| DOUBLE | int |
|
||||
| SMALLINT | int |
|
||||
| TINYINT | int |
|
||||
| BOOL | bool |
|
||||
| BINARY | str |
|
||||
| NCHAR | str |
|
||||
| JSON | str |
|
||||
| GEOMETRY | bytearray |
|
||||
| VARBINARY | bytearray |
|
||||
## 示例程序汇总
|
||||
|
||||
| 示例程序链接 | 示例程序内容 |
|
||||
| ------------------------------------------------------------------------------------------------------------- | ----------------------- |
|
||||
| [bind_multi.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/bind-multi.py) | 参数绑定， 一次绑定多行 |
|
||||
| [bind_row.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/bind-row.py) | 参数绑定，一次绑定一行 |
|
||||
| [insert_lines.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/insert-lines.py) | InfluxDB 行协议写入 |
|
||||
| [json_tag.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/json-tag.py) | 使用 JSON 类型的标签 |
|
||||
| [tmq_consumer.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/tmq_consumer.py) | tmq 订阅 |
|
||||
| [native_all_type_query.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/native_all_type_query.py) | 支持全部类型示例 |
|
||||
| [native_all_type_stmt.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/native_all_type_stmt.py) | 参数绑定支持全部类型示例 |
|
||||
| 示例程序链接 | 示例程序内容 |
|
||||
| ------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
|
||||
| [bind_multi.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/bind-multi.py) | 参数绑定， 一次绑定多行 |
|
||||
| [bind_row.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/bind-row.py) | 参数绑定，一次绑定一行 |
|
||||
| [insert_lines.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/insert-lines.py) | InfluxDB 行协议写入 |
|
||||
| [json_tag.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/json-tag.py) | 使用 JSON 类型的标签 |
|
||||
| [tmq_consumer.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/tmq_consumer.py) | tmq 订阅 |
|
||||
| [native_all_type_query.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/native_all_type_query.py) | 支持全部类型示例 |
|
||||
| [native_all_type_stmt.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/native_all_type_stmt.py) | 参数绑定支持全部类型示例 |
|
||||
|
||||
示例程序源码请参考：
|
||||
|
||||
|
|
|
|||
|
|
@ -9,26 +9,24 @@ import TabItem from "@theme/TabItem";
|
|||
import RequestId from "./_request_id.mdx";
|
||||
|
||||
`@tdengine/websocket` 是 TDengine 的官方 Node.js 语言连接器。Node.js 开发人员可以通过它开发存取 TDengine 数据库的应用软件。
|
||||
|
||||
Node.js 连接器源码托管在 [GitHub](https://github.com/taosdata/taos-connector-node/tree/main)。
|
||||
|
||||
## 连接方式
|
||||
## Node.js 版本兼容性
|
||||
|
||||
Node.js 连接器目前仅支持 WebSocket 连接器， 其通过 taosAdapter 提供的 WebSocket 接口连接 TDengine 实例。
|
||||
|
||||
连接方式的详细介绍请参考：[连接方式](../../../develop/connect/#连接方式)
|
||||
- 支持 Node.js 14 及以上版本。
|
||||
|
||||
## 支持的平台
|
||||
|
||||
支持 Node.js 14及以上版本。
|
||||
- 支持所有能运行 Node.js 的平台。
|
||||
|
||||
|
||||
## 版本历史
|
||||
|
||||
| Node.js 连接器 版本 | 主要变化 | TDengine 版本 |
|
||||
| :------------------: | :----------------------: | :----------------: |
|
||||
| 3.1.2 | 对数据协议和解析进行了优化，性能得到大幅提升| 3.3.2.0 及更高版本 |
|
||||
| 3.1.1 | 优化了数据传输性能 | 3.3.2.0 及更高版本 |
|
||||
| 3.1.0 | 新版本发布，支持 WebSocket 连接 | 3.2.0.0 及更高版本 |
|
||||
| ------------------| ----------------------| ----------------|
|
||||
| 3.1.2 | 对数据协议和解析进行了优化，性能得到大幅提升| - |
|
||||
| 3.1.1 | 优化了数据传输性能 | 3.3.2.0 及更高版本 |
|
||||
| 3.1.0 | 新版本发布，支持 WebSocket 连接 | 3.2.0.0 及更高版本 |
|
||||
|
||||
## 处理异常
|
||||
|
||||
|
|
|
|||
|
|
@ -10,12 +10,10 @@ import RequestId from "./_request_id.mdx";
|
|||
|
||||
`TDengine.Connector` 是 TDengine 提供的 C# 语言连接器。C# 开发人员可以通过它开发存取 TDengine 集群数据的 C# 应用软件。
|
||||
|
||||
## 兼容性
|
||||
## .NET 版本兼容性
|
||||
|
||||
- .NET Framework 4.6 及以上版本。
|
||||
- .NET 5.0 及以上版本。
|
||||
- `TDengine.Connector` 3.1.0 版本进行了完整的重构，不再兼容 3.0.2 及以前版本。3.0.2 文档请参考 [nuget](https://www.nuget.org/packages/TDengine.Connector/3.0.2)
|
||||
- `TDengine.Connector` 3.x 不兼容 TDengine 2.x，如果在运行 TDengine 2.x 版本的环境下需要使用 C# 连接器请使用 TDengine.Connector 的 1.x 版本。
|
||||
|
||||
## 支持的平台
|
||||
|
||||
|
|
@ -24,13 +22,13 @@ import RequestId from "./_request_id.mdx";
|
|||
|
||||
## 版本历史
|
||||
|
||||
| Connector 版本 | 主要变化 | TDengine 版本 |
|
||||
|:-------------|:---------------------------|:------------|
|
||||
| 3.1.4 | 提升 websocket 查询和写入性能 | 3.3.2.0 |
|
||||
| 3.1.3 | 支持 WebSocket 自动重连 | 3.2.1.0 |
|
||||
| 3.1.2 | 修复 schemaless 资源释放 | 3.2.1.0 |
|
||||
| 3.1.1 | 支持 varbinary 和 geometry 类型 | 3.2.1.0 |
|
||||
| 3.1.0 | WebSocket 使用原生实现 | 3.2.1.0 |
|
||||
| Connector 版本 | 主要变化 | TDengine 版本 |
|
||||
|:-------------|:---------------------------|:--------------|
|
||||
| 3.1.4 | 提升 websocket 查询和写入性能 | 3.3.2.0 及更高版本 |
|
||||
| 3.1.3 | 支持 WebSocket 自动重连 | - |
|
||||
| 3.1.2 | 修复 schemaless 资源释放 | - |
|
||||
| 3.1.1 | 支持 varbinary 和 geometry 类型 | - |
|
||||
| 3.1.0 | WebSocket 使用原生实现 | 3.2.1.0 及更高版本 |
|
||||
|
||||
## 处理异常
|
||||
|
||||
|
|
|
|||
|
|
@ -113,11 +113,11 @@ TDengine ODBC 支持两种连接 TDengine 数据库方式：WebSocket 连接与
|
|||
## 版本历史
|
||||
|
||||
| taos_odbc 版本 | 主要变化 | TDengine 版本 |
|
||||
| :----------- | :-------------------------------------------------------------------------------------------------- | :---------------- |
|
||||
| v1.1.0 | 1. 支持视图功能；<br/>2. 支持 VARBINARY/GEOMETRY 数据类型；<br/>3. 支持 ODBC 32 位 WebSocket 连接方式（仅企业版支持）；<br/>4. 支持 ODBC 数据源配置对话框设置对工业软件 KingSCADA、Kepware 等的兼容性适配选项（仅企业版支持）； | 3.3.3.0及更高版本 |
|
||||
| v1.0.2 | 支持 CP1252 字符编码； | 3.2.3.0及更高版本 |
|
||||
| ----------- | -------------------------------------------------------------------------------------------------- | ---------------- |
|
||||
| v1.1.0 | 1. 支持视图功能；<br/>2. 支持 VARBINARY/GEOMETRY 数据类型；<br/>3. 支持 ODBC 32 位 WebSocket 连接方式（仅企业版支持）；<br/>4. 支持 ODBC 数据源配置对话框设置对工业软件 KingSCADA、Kepware 等的兼容性适配选项（仅企业版支持）； | 3.3.3.0 及更高版本 |
|
||||
| v1.0.2 | 支持 CP1252 字符编码； | 3.2.3.0 及更高版本 |
|
||||
| v1.0.1 | 1. 支持 DSN 设置 BI 模式，在 BI 模式下 TDengine 数据库不返回系统数据库和超级表子表信息；<br/>2. 重构字符集转换模块，提升读写性能；<br/>3. ODBC 数据源配置对话框中默认修改默认连接方式为“WebSocket”；<br/>4. ODBC 数据源配置对话框增加“测试连接”控件；<br/>5. ODBC 数据源配置支持中文/英文界面； | - |
|
||||
| v1.0.0.0 | 发布初始版本，支持与Tdengine数据库交互以读写数据，具体请参考“API 参考”一节 | 3.2.2.0及更高版本 |
|
||||
| v1.0.0.0 | 发布初始版本，支持与Tdengine数据库交互以读写数据，具体请参考“API 参考”一节 | 3.2.2.0 及更高版本 |
|
||||
|
||||
|
||||
## 数据类型映射
|
||||
|
|
|
|||
Loading…
Reference in New Issue