Merge pull request #29409 from taosdata/docs/TD-33352-MAIN

Python Connector documents

docs/en/07-develop/05-stmt.md

@@ -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>

docs/en/14-reference/05-connector/10-cpp.md

@@ -1,4 +1,5 @@
 ---
+toc_max_heading_level: 4
 sidebar_label: C/C++
 title: C/C++ Client Library
 slug: /tdengine-reference/client-libraries/cpp

docs/en/14-reference/05-connector/14-java.md

@@ -1,4 +1,5 @@
 ---
+toc_max_heading_level: 4
 sidebar_label: Java
 title: Java Client Library
 slug: /tdengine-reference/client-libraries/java

docs/en/14-reference/05-connector/20-go.md

@@ -1,4 +1,5 @@
 ---
+toc_max_heading_level: 4
 sidebar_label: Go
 title: Go Client Library
 slug: /tdengine-reference/client-libraries/go

docs/en/14-reference/05-connector/26-rust.md

@@ -1,4 +1,5 @@
 ---
+toc_max_heading_level: 4
 sidebar_label: Rust
 title: Rust Client Library
 slug: /tdengine-reference/client-libraries/rust

docs/en/14-reference/05-connector/30-python.md

@@ -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 statement2(self, sql=None, option=None)`
-- `def statement(self, sql=None)`
+    - **Interface Description**：Creating an STMT2 object using a connection object
-  - **Interface Description**: Creates a stmt object using the connection object, if sql is not empty it will call prepare.
+    - **Parameter Description**
-  - `sql`: Precompiled SQL statement.
+        - `sql`: The bound SQL statement will call the `prepare` function if it is not empty
-  - **Return Value**: stmt object.
+        - `option` Pass in `TaoStmt2Option` class instance
-  - **Exception**: Throws `StatementError` exception on failure.
+    - **Return Value**：STMT2 object
+    - **Exception**：Throws `ConnectionError` on failure
 - `def prepare(self, sql)`
-  - **Interface Description**: Binds a precompiled sql statement.
+    - **Interface Description**：Bind a precompiled SQL statement
-  - **Parameter Description**:
+    - **Parameter Description**：
-    - `sql`: Precompiled SQL statement.
+        - `sql`: Precompiled SQL statement
-  - **Exception**: Throws `StatementError` exception on failure.
+    - **Exception**：Throws `StatementError` on failure
-- `def set_tbname(self, name)`
+- `def bind_param(self, tbnames, tags, datas)`
-  - **Interface Description**: Sets the table name for data to be written to.
+    - **Interface Description**：Binding Data as an Independent Array
-  - **Parameter Description**:
+    - **Parameter Description**：
-    - `name`: Table name, if you need to specify a database, for example: `db_name.table_name`.
+        - `tbnames`:Bind table name array, data type is list 
-  - **Exception**: Throws `StatementError` exception on failure.
+        - `tags`: Bind tag column value array, data type is list
-- `def set_tbname_tags(self, name, tags):`
+        - `datas`: Bind data column value array, data type of list
-  - **Interface Description**: Sets the table and Tags data, used for automatic table creation.
+    - **Exception**：Throws `StatementError` on failure
-  - **Parameter Description**:
+- `def bind_param_with_tables(self, tables)`
-    - `name`: Table name, if you need to specify a database, for example: `db_name.table_name`.
+    - **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
-    - `tags`: Tags data.
+    - **Parameter Description**：
-  - **Exception**: Throws `StatementError` exception on failure.
+        - `tables`: `BindTable` Independent table object array
-- `def bind_param(self, params, add_batch=True)`
+    - **Exception**：Throws `StatementError` on failure
-  - **Interface Description**: Binds a set of data and submits.
+- `def execute(self) -> int:`
-  - **Parameter Description**:
+    - **Interface Description**：Execute to write all bound data
-    - `params`: Data to bind.
+    - **Return Value**：Affects the number of rows
-    - `add_batch`: Whether to submit the bound data.
+    - **Exception**：Throws `QueryError` on failure
-  - **Exception**: Throws `StatementError` exception on failure.
+- `def result(self)`
-- `def bind_param_batch(self, binds, add_batch=True)`
+    - **Interface Description**：Get parameter binding query result set
-  - **Interface Description**: Binds multiple sets of data and submits.
+    - **Return Value**：Returns the TaosResult object
-  - **Parameter Description**:
+- `def close(self)`
-    - `binds`: Data to bind.
+    - **Interface Description**： close the STMT2 object
-    - `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.
 
 #### Data Subscription
 

docs/en/14-reference/05-connector/35-node.md

@@ -1,4 +1,5 @@
 ---
+toc_max_heading_level: 4
 sidebar_label: Node.js
 title: Node.js Client Library
 slug: /tdengine-reference/client-libraries/node

docs/en/14-reference/05-connector/40-csharp.md

@@ -1,4 +1,5 @@
 ---
+toc_max_heading_level: 4
 sidebar_label: C#
 title: C# Client Library
 slug: /tdengine-reference/client-libraries/csharp

docs/examples/python/stmt2_native.py

@@ -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()

docs/zh/07-develop/05-stmt.md

@@ -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">

docs/zh/14-reference/05-connector/30-python.mdx

@@ -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)`
+- `def statement2(self, sql=None, option=None)`
-    - **接口说明**：使用连接对象创建 stmt 对象, 如果 sql 不空会进行调用 prepare。
+    - **接口说明**：使用连接对象创建 stmt2 对象
-    - `sql`: 预编译的 SQL 语句。
+    - **参数说明**
-    - **返回值**：stmt 对象。
+        - `sql`: 绑定的 SQL 语句，如果不为空会调用`prepare`函数
-    - **异常**：操作失败抛出 `StatementError` 异常。
+        - `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` 即可。
+        - `tbnames`: 绑定表名数组，数据类型为 list 
-    - **异常**：操作失败抛出 `StatementError` 异常。
+        - `tags`: 绑定 tag 列值数组，数据类型为 list 
-- `def set_tbname_tags(self, name, tags):`
+        - `tags`: 绑定普通列值数组，数据类型为 list 
-    - **接口说明**：设置表和 Tags 数据, 用于自动建表。
+    - **异常**：操作失败抛出 `StatementError` 异常
+- `def bind_param_with_tables(self, tables)`
+    - **接口说明**：以独立表方式绑定数据，独立表是以表为组织单位，每张表中有表名，TAG 值及普通列数值属性
     - **参数说明**：
-        - `name`: 表名，如果需要指定数据库, 例如： `db_name.table_name` 即可。
+        - `tables`: `BindTable` 独立表对象数组
-        - `tags`: Tags 数据。
     - **异常**：操作失败抛出 `StatementError` 异常。
-- `def bind_param(self, params, add_batch=True)`
+- `def execute(self) -> int:`
-    - **接口说明**：绑定一组数据并提交。
+    - **接口说明**：执行将绑定数据全部写入
-    - **参数说明**：
+    - **返回值**：影响行数
-        - `params`: 绑定数据。
+    - **异常**：操作失败抛出 `QueryError` 异常。
-        - `add_batch`: 是否提交绑定数据。
+- `def result(self)`
-    - **异常**：操作失败抛出 `StatementError` 异常。
+    - **接口说明**： 获取参数绑定查询结果集
-- `def bind_param_batch(self, binds, add_batch=True)`
+    - **返回值**：返回 TaosResult 对象
-    - **接口说明**：绑定多组数据并提交。
+- `def close(self)`
-    - **参数说明**：
+    - **接口说明**： 关闭 stmt2 对象
-        - `binds`: 绑定数据。
+
-        - `add_batch`: 是否提交绑定数据。
-    - **异常**：操作失败抛出 `StatementError` 异常。
-- `def add_batch(self)`
-    - **接口说明**：提交绑定数据。
-    - **异常**：操作失败抛出 `StatementError` 异常。
-- `def execute(self)`
-    - **接口说明**：执行将绑定的数据全部写入。
-    - **异常**：操作失败抛出 `StatementError` 异常。
-- `def affected_rows(self)`
-    - **接口说明**： 获取写入条数。
-    - **返回值**：写入条数。
-- `def close(&self)`
-    - **接口说明**： 关闭 stmt 对象。
 
 #### 数据订阅
 - **创建消费者支持属性列表**：

tests/docs-examples-test/python.sh

@@ -196,3 +196,4 @@ check_transactions || exit 1
 reset_cache || exit 1
 python3 tmq_websocket_example.py
 
+python3 stmt2_native.py

tests/parallel_test/cases.task

@@ -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

tests/parallel_test/run_case.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=$?