Merge pull request #29409 from taosdata/docs/TD-33352-MAIN
Python Connector documents
This commit is contained in:
Linhe Huo
GitHub
commit
d166d1b3d7
|
|
@ -98,7 +98,7 @@ This is a [more detailed parameter binding example](https://github.com/taosdata/
|
|||
<TabItem label="Python" value="python">
|
||||
|
||||
```python
|
||||
{{#include docs/examples/python/stmt_native.py}}
|
||||
{{#include docs/examples/python/stmt2_native.py}}
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
|
|
|||
|
|
@ -1,4 +1,5 @@
|
|||
---
|
||||
toc_max_heading_level: 4
|
||||
sidebar_label: C/C++
|
||||
title: C/C++ Client Library
|
||||
slug: /tdengine-reference/client-libraries/cpp
|
||||
|
|
|
|||
|
|
@ -1,4 +1,5 @@
|
|||
---
|
||||
toc_max_heading_level: 4
|
||||
sidebar_label: Java
|
||||
title: Java Client Library
|
||||
slug: /tdengine-reference/client-libraries/java
|
||||
|
|
|
|||
|
|
@ -1,4 +1,5 @@
|
|||
---
|
||||
toc_max_heading_level: 4
|
||||
sidebar_label: Go
|
||||
title: Go Client Library
|
||||
slug: /tdengine-reference/client-libraries/go
|
||||
|
|
|
|||
|
|
@ -1,4 +1,5 @@
|
|||
---
|
||||
toc_max_heading_level: 4
|
||||
sidebar_label: Rust
|
||||
title: Rust Client Library
|
||||
slug: /tdengine-reference/client-libraries/rust
|
||||
|
|
|
|||
|
|
@ -1,4 +1,5 @@
|
|||
---
|
||||
toc_max_heading_level: 4
|
||||
sidebar_label: Python
|
||||
title: Python Client Library
|
||||
slug: /tdengine-reference/client-libraries/python
|
||||
|
|
@ -55,6 +56,8 @@ Python Connector historical versions (it is recommended to use the latest versio
|
|||
|
||||
|Python Connector Version | Major Changes | TDengine Version|
|
||||
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
|
||||
|2.7.21 | Native supports STMT2 writing | - |
|
||||
|2.7.19 | Support Apache Superset connection to TDengine Cloud data source | - |
|
||||
|2.7.18 | Support Apache SuperSet BI Tools. | - |
|
||||
|2.7.16 | Add subscription configuration (session. timeout. ms, Max. roll. interval. ms). | - |
|
||||
|2.7.15 | Added support for VARBINRY and GEOMETRY types. | - |
|
||||
|
|
@ -136,7 +139,7 @@ TDengine currently supports timestamp, numeric, character, boolean types, and th
|
|||
| [tmq_consumer.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/tmq_consumer.py) | tmq subscription |
|
||||
| [native_all_type_query.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/native_all_type_query.py) | Example supporting all types |
|
||||
| [native_all_type_stmt.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/native_all_type_stmt.py) | Parameter binding example supporting all types |
|
||||
|
||||
| [test_stmt2.py](https://github.com/taosdata/taos-connector-python/blob/main/tests/test_stmt2.py) | Example of STMT2 writing |
|
||||
Example program source code can be found at:
|
||||
|
||||
1. [More native example programs](https://github.com/taosdata/taos-connector-python/tree/main/examples)
|
||||
|
|
@ -429,51 +432,40 @@ TaosResult object can be iterated over to retrieve queried data.
|
|||
- **Exceptions**: Throws `SchemalessError` if operation fails.
|
||||
|
||||
#### Parameter Binding
|
||||
|
||||
- `def statement(self, sql=None)`
|
||||
- **Interface Description**: Creates a stmt object using the connection object, if sql is not empty it will call prepare.
|
||||
- `sql`: Precompiled SQL statement.
|
||||
- **Return Value**: stmt object.
|
||||
- **Exception**: Throws `StatementError` exception on failure.
|
||||
- `def statement2(self, sql=None, option=None)`
|
||||
- **Interface Description**：Creating an STMT2 object using a connection object
|
||||
- **Parameter Description**
|
||||
- `sql`: The bound SQL statement will call the `prepare` function if it is not empty
|
||||
- `option` Pass in `TaoStmt2Option` class instance
|
||||
- **Return Value**：STMT2 object
|
||||
- **Exception**：Throws `ConnectionError` on failure
|
||||
- `def prepare(self, sql)`
|
||||
- **Interface Description**: Binds a precompiled sql statement.
|
||||
- **Parameter Description**:
|
||||
- `sql`: Precompiled SQL statement.
|
||||
- **Exception**: Throws `StatementError` exception on failure.
|
||||
- `def set_tbname(self, name)`
|
||||
- **Interface Description**: Sets the table name for data to be written to.
|
||||
- **Parameter Description**:
|
||||
- `name`: Table name, if you need to specify a database, for example: `db_name.table_name`.
|
||||
- **Exception**: Throws `StatementError` exception on failure.
|
||||
- `def set_tbname_tags(self, name, tags):`
|
||||
- **Interface Description**: Sets the table and Tags data, used for automatic table creation.
|
||||
- **Parameter Description**:
|
||||
- `name`: Table name, if you need to specify a database, for example: `db_name.table_name`.
|
||||
- `tags`: Tags data.
|
||||
- **Exception**: Throws `StatementError` exception on failure.
|
||||
- `def bind_param(self, params, add_batch=True)`
|
||||
- **Interface Description**: Binds a set of data and submits.
|
||||
- **Parameter Description**:
|
||||
- `params`: Data to bind.
|
||||
- `add_batch`: Whether to submit the bound data.
|
||||
- **Exception**: Throws `StatementError` exception on failure.
|
||||
- `def bind_param_batch(self, binds, add_batch=True)`
|
||||
- **Interface Description**: Binds multiple sets of data and submits.
|
||||
- **Parameter Description**:
|
||||
- `binds`: Data to bind.
|
||||
- `add_batch`: Whether to submit the bound data.
|
||||
- **Exception**: Throws `StatementError` exception on failure.
|
||||
- `def add_batch(self)`
|
||||
- **Interface Description**: Submits the bound data.
|
||||
- **Exception**: Throws `StatementError` exception on failure.
|
||||
- `def execute(self)`
|
||||
- **Interface Description**: Executes and writes all the bound data.
|
||||
- **Exception**: Throws `StatementError` exception on failure.
|
||||
- `def affected_rows(self)`
|
||||
- **Interface Description**: Gets the number of rows written.
|
||||
- **Return Value**: Number of rows written.
|
||||
- `def close(&self)`
|
||||
- **Interface Description**: Closes the stmt object.
|
||||
- **Interface Description**：Bind a precompiled SQL statement
|
||||
- **Parameter Description**：
|
||||
- `sql`: Precompiled SQL statement
|
||||
- **Exception**：Throws `StatementError` on failure
|
||||
- `def bind_param(self, tbnames, tags, datas)`
|
||||
- **Interface Description**：Binding Data as an Independent Array
|
||||
- **Parameter Description**：
|
||||
- `tbnames`:Bind table name array, data type is list
|
||||
- `tags`: Bind tag column value array, data type is list
|
||||
- `datas`: Bind data column value array, data type of list
|
||||
- **Exception**：Throws `StatementError` on failure
|
||||
- `def bind_param_with_tables(self, tables)`
|
||||
- **Interface Description**：Bind data in an independent table format. Independent tables are organized by table units, with table name, TAG value, and data column attributes in table object
|
||||
- **Parameter Description**：
|
||||
- `tables`: `BindTable` Independent table object array
|
||||
- **Exception**：Throws `StatementError` on failure
|
||||
- `def execute(self) -> int:`
|
||||
- **Interface Description**：Execute to write all bound data
|
||||
- **Return Value**：Affects the number of rows
|
||||
- **Exception**：Throws `QueryError` on failure
|
||||
- `def result(self)`
|
||||
- **Interface Description**：Get parameter binding query result set
|
||||
- **Return Value**：Returns the TaosResult object
|
||||
- `def close(self)`
|
||||
- **Interface Description**： close the STMT2 object
|
||||
|
||||
|
||||
#### Data Subscription
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,5 @@
|
|||
---
|
||||
toc_max_heading_level: 4
|
||||
sidebar_label: Node.js
|
||||
title: Node.js Client Library
|
||||
slug: /tdengine-reference/client-libraries/node
|
||||
|
|
|
|||
|
|
@ -1,4 +1,5 @@
|
|||
---
|
||||
toc_max_heading_level: 4
|
||||
sidebar_label: C#
|
||||
title: C# Client Library
|
||||
slug: /tdengine-reference/client-libraries/csharp
|
||||
|
|
|
|||
|
|
@ -0,0 +1,71 @@
|
|||
import taos
|
||||
from datetime import datetime
|
||||
import random
|
||||
|
||||
numOfSubTable = 10
|
||||
numOfRow = 10
|
||||
|
||||
conn = None
|
||||
stmt2 = None
|
||||
host="localhost"
|
||||
port=6030
|
||||
try:
|
||||
# 1 connect
|
||||
conn = taos.connect(
|
||||
user="root",
|
||||
password="taosdata",
|
||||
host=host,
|
||||
port=port,
|
||||
)
|
||||
|
||||
# 2 create db and table
|
||||
conn.execute("CREATE DATABASE IF NOT EXISTS power")
|
||||
conn.execute("USE power")
|
||||
conn.execute(
|
||||
"CREATE TABLE IF NOT EXISTS `meters` (`ts` TIMESTAMP, `current` FLOAT, `voltage` INT, `phase` FLOAT) TAGS (`groupid` INT, `location` BINARY(16))"
|
||||
)
|
||||
|
||||
# 3 prepare
|
||||
sql = "INSERT INTO ? USING meters (groupid, location) TAGS(?,?) VALUES (?,?,?,?)"
|
||||
stmt2 = conn.statement2(sql)
|
||||
|
||||
tbnames = []
|
||||
tags = []
|
||||
datas = []
|
||||
|
||||
for i in range(numOfSubTable):
|
||||
# tbnames
|
||||
tbnames.append(f"d_bind_{i}")
|
||||
# tags
|
||||
tags.append([i, f"location_{i}"])
|
||||
# datas
|
||||
current = int(datetime.now().timestamp() * 1000)
|
||||
timestamps = []
|
||||
currents = []
|
||||
voltages = []
|
||||
phases = []
|
||||
for j in range (numOfRow):
|
||||
timestamps.append(current + i*1000 + j)
|
||||
currents.append(float(random.random() * 30))
|
||||
voltages.append(random.randint(100, 300))
|
||||
phases.append(float(random.random()))
|
||||
data = [timestamps, currents, voltages, phases]
|
||||
datas.append(data)
|
||||
|
||||
# 4 bind param
|
||||
stmt2.bind_param(tbnames, tags, datas)
|
||||
|
||||
# 5 execute
|
||||
stmt2.execute()
|
||||
|
||||
# show
|
||||
print(f"Successfully inserted with stmt2 to power.meters. child={numOfSubTable} rows={numOfRow} \n")
|
||||
|
||||
except Exception as err:
|
||||
print(f"Failed to insert to table meters using stmt2, ErrMessage:{err}")
|
||||
raise err
|
||||
finally:
|
||||
if stmt2:
|
||||
stmt2.close()
|
||||
if conn:
|
||||
conn.close()
|
||||
|
|
@ -93,7 +93,7 @@ import TabItem from "@theme/TabItem";
|
|||
<TabItem label="Python" value="python">
|
||||
|
||||
```python
|
||||
{{#include docs/examples/python/stmt_native.py}}
|
||||
{{#include docs/examples/python/stmt2_native.py}}
|
||||
```
|
||||
</TabItem>
|
||||
<TabItem label="Go" value="go">
|
||||
|
|
|
|||
|
|
@ -52,7 +52,9 @@ Python Connector 历史版本（建议使用最新版本的 `taospy`）：
|
|||
|
||||
| Python Connector 版本 | 主要变化 | TDengine 版本 |
|
||||
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
|
||||
| 2.7.18 | 支持 Apache Superset BI 产品 | - |
|
||||
| 2.7.21 | Native 支持 STMT2 写入 | - |
|
||||
| 2.7.19 | 支持 Apache Superset 连接 TDengine Cloud 数据源 | - |
|
||||
| 2.7.18 | 支持 Apache Superset 产品连接本地 TDengine 数据源 | - |
|
||||
| 2.7.16 | 新增订阅配置 (session.timeout.ms, max.poll.interval.ms) | - |
|
||||
| 2.7.15 | 新增 VARBINARY 和 GEOMETRY 类型支持 | - |
|
||||
| 2.7.14 | 修复已知问题 | - |
|
||||
|
|
@ -131,7 +133,8 @@ TDengine 目前支持时间戳、数字、字符、布尔类型，与 Python 对
|
|||
| [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) | 参数绑定支持全部类型示例 |
|
||||
| [native_all_type_stmt.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/native_all_type_stmt.py) | 参数绑定 stmt 全部类型示例 |
|
||||
| [test_stmt2.py](https://github.com/taosdata/taos-connector-python/blob/main/tests/test_stmt2.py) | 参数绑定 stmt2 写入示例 |
|
||||
|
||||
示例程序源码请参考：
|
||||
|
||||
|
|
@ -284,6 +287,7 @@ TaosResult 对象可以通过循环遍历获取查询到的数据。
|
|||
- `fn close(&self) -> PyResult<()>`
|
||||
- **接口说明**： 关闭 stmt 对象。
|
||||
|
||||
|
||||
#### 数据订阅
|
||||
- **创建消费者支持属性列表**：
|
||||
- host：主机地址。
|
||||
|
|
@ -424,50 +428,40 @@ TaosResult 对象可以通过循环遍历获取查询到的数据。
|
|||
- **异常**：操作失败抛出 `SchemalessError` 异常。
|
||||
|
||||
#### 参数绑定
|
||||
- `def statement(self, sql=None)`
|
||||
- **接口说明**：使用连接对象创建 stmt 对象, 如果 sql 不空会进行调用 prepare。
|
||||
- `sql`: 预编译的 SQL 语句。
|
||||
- **返回值**：stmt 对象。
|
||||
- **异常**：操作失败抛出 `StatementError` 异常。
|
||||
- `def statement2(self, sql=None, option=None)`
|
||||
- **接口说明**：使用连接对象创建 stmt2 对象
|
||||
- **参数说明**
|
||||
- `sql`: 绑定的 SQL 语句，如果不为空会调用`prepare`函数
|
||||
- `option` 传入 TaosStmt2Option 类实例选项
|
||||
- **返回值**：stmt2 对象。
|
||||
- **异常**：操作失败抛出 `ConnectionError` 异常。
|
||||
- `def prepare(self, sql)`
|
||||
- **接口说明**：绑定预编译 sql 语句。
|
||||
- **接口说明**：绑定预编译 sql 语句
|
||||
- **参数说明**：
|
||||
- `sql`: 预编译的 SQL 语句。
|
||||
- `sql`: 绑定的 SQL 语句
|
||||
- **异常**：操作失败抛出 `StatementError` 异常。
|
||||
- `def set_tbname(self, name)`
|
||||
- **接口说明**：设置将要写入数据的表名。
|
||||
- `def bind_param(self, tbnames, tags, datas)`
|
||||
- **接口说明**：以独立数组方式绑定数据
|
||||
- **参数说明**：
|
||||
- `name`: 表名，如果需要指定数据库, 例如： `db_name.table_name` 即可。
|
||||
- **异常**：操作失败抛出 `StatementError` 异常。
|
||||
- `def set_tbname_tags(self, name, tags):`
|
||||
- **接口说明**：设置表和 Tags 数据, 用于自动建表。
|
||||
- `tbnames`: 绑定表名数组，数据类型为 list
|
||||
- `tags`: 绑定 tag 列值数组，数据类型为 list
|
||||
- `tags`: 绑定普通列值数组，数据类型为 list
|
||||
- **异常**：操作失败抛出 `StatementError` 异常
|
||||
- `def bind_param_with_tables(self, tables)`
|
||||
- **接口说明**：以独立表方式绑定数据，独立表是以表为组织单位，每张表中有表名，TAG 值及普通列数值属性
|
||||
- **参数说明**：
|
||||
- `name`: 表名，如果需要指定数据库, 例如： `db_name.table_name` 即可。
|
||||
- `tags`: Tags 数据。
|
||||
- `tables`: `BindTable` 独立表对象数组
|
||||
- **异常**：操作失败抛出 `StatementError` 异常。
|
||||
- `def bind_param(self, params, add_batch=True)`
|
||||
- **接口说明**：绑定一组数据并提交。
|
||||
- **参数说明**：
|
||||
- `params`: 绑定数据。
|
||||
- `add_batch`: 是否提交绑定数据。
|
||||
- **异常**：操作失败抛出 `StatementError` 异常。
|
||||
- `def bind_param_batch(self, binds, add_batch=True)`
|
||||
- **接口说明**：绑定多组数据并提交。
|
||||
- **参数说明**：
|
||||
- `binds`: 绑定数据。
|
||||
- `add_batch`: 是否提交绑定数据。
|
||||
- **异常**：操作失败抛出 `StatementError` 异常。
|
||||
- `def add_batch(self)`
|
||||
- **接口说明**：提交绑定数据。
|
||||
- **异常**：操作失败抛出 `StatementError` 异常。
|
||||
- `def execute(self)`
|
||||
- **接口说明**：执行将绑定的数据全部写入。
|
||||
- **异常**：操作失败抛出 `StatementError` 异常。
|
||||
- `def affected_rows(self)`
|
||||
- **接口说明**： 获取写入条数。
|
||||
- **返回值**：写入条数。
|
||||
- `def close(&self)`
|
||||
- **接口说明**： 关闭 stmt 对象。
|
||||
- `def execute(self) -> int:`
|
||||
- **接口说明**：执行将绑定数据全部写入
|
||||
- **返回值**：影响行数
|
||||
- **异常**：操作失败抛出 `QueryError` 异常。
|
||||
- `def result(self)`
|
||||
- **接口说明**： 获取参数绑定查询结果集
|
||||
- **返回值**：返回 TaosResult 对象
|
||||
- `def close(self)`
|
||||
- **接口说明**： 关闭 stmt2 对象
|
||||
|
||||
|
||||
#### 数据订阅
|
||||
- **创建消费者支持属性列表**：
|
||||
|
|
|
|||
|
|
@ -196,3 +196,4 @@ check_transactions || exit 1
|
|||
reset_cache || exit 1
|
||||
python3 tmq_websocket_example.py
|
||||
|
||||
python3 stmt2_native.py
|
||||
|
|
@ -6,6 +6,16 @@
|
|||
|
||||
,,n,unit-test,bash test.sh
|
||||
|
||||
#docs-examples test
|
||||
,,n,docs-examples-test,bash c.sh
|
||||
,,n,docs-examples-test,bash python.sh
|
||||
,,n,docs-examples-test,bash node.sh
|
||||
,,n,docs-examples-test,bash csharp.sh
|
||||
,,n,docs-examples-test,bash jdbc.sh
|
||||
,,n,docs-examples-test,bash rust.sh
|
||||
,,n,docs-examples-test,bash go.sh
|
||||
,,n,docs-examples-test,bash test_R.sh
|
||||
|
||||
#
|
||||
# army-test
|
||||
#
|
||||
|
|
@ -1661,13 +1671,3 @@
|
|||
,,n,develop-test,python3 ./test.py -f 5-taos-tools/taosbenchmark/sml_json_alltypes.py
|
||||
,,n,develop-test,python3 ./test.py -f 5-taos-tools/taosbenchmark/taosdemoTestQueryWithJson.py -R
|
||||
,,n,develop-test,python3 ./test.py -f 5-taos-tools/taosbenchmark/telnet_tcp.py -R
|
||||
|
||||
#docs-examples test
|
||||
,,n,docs-examples-test,bash c.sh
|
||||
,,n,docs-examples-test,bash python.sh
|
||||
,,n,docs-examples-test,bash node.sh
|
||||
,,n,docs-examples-test,bash csharp.sh
|
||||
,,n,docs-examples-test,bash jdbc.sh
|
||||
,,n,docs-examples-test,bash rust.sh
|
||||
,,n,docs-examples-test,bash go.sh
|
||||
,,n,docs-examples-test,bash test_R.sh
|
||||
|
|
|
|||
|
|
@ -77,7 +77,7 @@ md5sum /usr/lib/libtaos.so.1
|
|||
md5sum /home/TDinternal/debug/build/lib/libtaos.so
|
||||
|
||||
#get python connector and update: taospy 2.7.16 taos-ws-py 0.3.5
|
||||
pip3 install taospy==2.7.16
|
||||
pip3 install taospy==2.7.21
|
||||
pip3 install taos-ws-py==0.3.5
|
||||
$TIMEOUT_CMD $cmd
|
||||
RET=$?
|
||||
|
|
|
|||
Loading…
Reference in New Issue