Merge pull request #21778 from taosdata/docs/sunpeng/TD-23899-support-stmt-via-ws

docs: support stmt via ws

docs/en/14-reference/03-connector/07-python.mdx

@@ -667,6 +667,137 @@ Insert with req_id argument
 </TabItem>
 </Tabs>
 
+### Parameter Binding
+
+The Python connector provides a parameter binding api for inserting data. Similar to most databases, TDengine currently only supports the question mark `?` to indicate the parameters to be bound.
+
+<Tabs>
+<TabItem value="native" label="native connection">
+
+#### Create Stmt
+
+Call the `statement` method in `Connection` to create the `stmt` for parameter binding.
+
+```
+import taos
+
+conn = taos.connect()
+stmt = conn.statement("insert into log values(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)")
+```
+
+#### parameter binding
+
+Call the `new_multi_binds` function to create the parameter list for parameter bindings.
+
+```
+params = new_multi_binds(16)
+params[0].timestamp((1626861392589, 1626861392590, 1626861392591))
+params[1].bool((True, None, False))
+params[2].tinyint([-128, -128, None])  # -128 is tinyint null
+params[3].tinyint([0, 127, None])
+params[4].smallint([3, None, 2])
+params[5].int([3, 4, None])
+params[6].bigint([3, 4, None])
+params[7].tinyint_unsigned([3, 4, None])
+params[8].smallint_unsigned([3, 4, None])
+params[9].int_unsigned([3, 4, None])
+params[10].bigint_unsigned([3, 4, None])
+params[11].float([3, None, 1])
+params[12].double([3, None, 1.2])
+params[13].binary(["abc", "dddafadfadfadfadfa", None])
+params[14].nchar(["涛思数据", None, "a long string with 中文字符"])
+params[15].timestamp([None, None, 1626861392591])
+```
+
+Call the `bind_param` (for a single row) method or the `bind_param_batch` (for multiple rows) method to set the values.
+
+```
+stmt.bind_param_batch(params)
+```
+
+#### execute sql
+
+Call `execute` method to execute sql.
+
+```
+stmt.execute()
+```
+
+#### Close Stmt
+
+```
+stmt.close()
+```
+
+#### Example
+
+```python
+{{#include docs/examples/python/stmt_example.py}}
+```
+</TabItem>
+
+<TabItem value="websocket" label="WebSocket connection">
+
+#### Create Stmt
+
+Call the `statement` method in `Connection` to create the `stmt` for parameter binding.
+
+```
+import taosws
+
+conn = taosws.connect('taosws://localhost:6041/test')
+stmt = conn.statement()
+```
+
+#### Prepare sql
+
+Call `prepare` method in stmt to prepare sql.
+
+```
+stmt.prepare("insert into t1 values (?, ?, ?, ?)")
+```
+
+#### parameter binding
+
+Call the `bind_param` method to bind parameters.
+
+```
+stmt.bind_param([
+    taosws.millis_timestamps_to_column([1686844800000, 1686844801000, 1686844802000, 1686844803000]),
+    taosws.ints_to_column([1, 2, 3, 4]),
+    taosws.floats_to_column([1.1, 2.2, 3.3, 4.4]),
+    taosws.varchar_to_column(['a', 'b', 'c', 'd']),
+])
+```
+
+Call the `add_batch` method to add parameters to the batch.
+
+```
+stmt.add_batch()
+```
+
+#### execute sql
+
+Call `execute` method to execute sql.
+
+```
+stmt.execute()
+```
+
+#### Close Stmt
+
+```
+stmt.close()
+```
+
+#### Example
+
+```python
+{{#include docs/examples/python/stmt_websocket_example.py}}
+```
+</TabItem>
+</Tabs>
+
 ### Other sample programs
 
 | Example program links | Example program content |

docs/examples/python/stmt_example.py

+#!
+
+import taosws
+
+import taos
+
+db_name = 'test_ws_stmt'
+
+
+def before():
+    taos_conn = taos.connect()
+    taos_conn.execute("drop database if exists %s" % db_name)
+    taos_conn.execute("create database %s" % db_name)
+    taos_conn.select_db(db_name)
+    taos_conn.execute("create table t1 (ts timestamp, a int, b float, c varchar(10))")
+    taos_conn.execute(
+        "create table stb1 (ts timestamp, a int, b float, c varchar(10)) tags (t1 int, t2 binary(10))")
+    taos_conn.close()
+
+
+def stmt_insert():
+    before()
+
+    conn = taosws.connect('taosws://root:taosdata@localhost:6041/%s' % db_name)
+
+    while True:
+        try:
+            stmt = conn.statement()
+            stmt.prepare("insert into t1 values (?, ?, ?, ?)")
+
+            stmt.bind_param([
+                taosws.millis_timestamps_to_column([1686844800000, 1686844801000, 1686844802000, 1686844803000]),
+                taosws.ints_to_column([1, 2, 3, 4]),
+                taosws.floats_to_column([1.1, 2.2, 3.3, 4.4]),
+                taosws.varchar_to_column(['a', 'b', 'c', 'd']),
+            ])
+
+            stmt.add_batch()
+            rows = stmt.execute()
+            print(rows)
+            stmt.close()
+        except Exception as e:
+            if 'Retry needed' in e.args[0]:  # deal with [0x0125] Retry needed
+                continue
+            else:
+                raise e
+
+        break
+
+
+def stmt_insert_into_stable():
+    before()
+
+    conn = taosws.connect("taosws://root:taosdata@localhost:6041/%s" % db_name)
+
+    while True:
+        try:
+            stmt = conn.statement()
+            stmt.prepare("insert into ? using stb1 tags (?, ?) values (?, ?, ?, ?)")
+            stmt.set_tbname('stb1_1')
+            stmt.set_tags([
+                taosws.int_to_tag(1),
+                taosws.varchar_to_tag('aaa'),
+            ])
+            stmt.bind_param([
+                taosws.millis_timestamps_to_column([1686844800000, 1686844801000, 1686844802000, 1686844803000]),
+                taosws.ints_to_column([1, 2, 3, 4]),
+                taosws.floats_to_column([1.1, 2.2, 3.3, 4.4]),
+                taosws.varchar_to_column(['a', 'b', 'c', 'd']),
+            ])
+
+            stmt.add_batch()
+            rows = stmt.execute()
+            print(rows)
+            stmt.close()
+        except Exception as e:
+            if 'Retry needed' in e.args[0]:  # deal with [0x0125] Retry needed
+                continue
+            else:
+                raise e
+
+        break

docs/examples/python/stmt_websocket_example.py

+#!
+import time
+
+import taosws
+
+import taos
+
+
+def before_test(db_name):
+    taos_conn = taos.connect()
+    taos_conn.execute("drop database if exists %s" % db_name)
+    taos_conn.execute("create database %s" % db_name)
+    taos_conn.select_db(db_name)
+    taos_conn.execute("create table t1 (ts timestamp, a int, b float, c varchar(10))")
+    taos_conn.execute(
+        "create table stb1 (ts timestamp, a int, b float, c varchar(10)) tags (t1 int, t2 binary(10))")
+    taos_conn.close()
+
+
+def after_test(db_name):
+    taos_conn = taos.connect()
+    taos_conn.execute("drop database if exists %s" % db_name)
+    taos_conn.close()
+
+
+def stmt_insert():
+    db_name = 'test_ws_stmt_{}'.format(int(time.time()))
+    before_test(db_name)
+
+    conn = taosws.connect('taosws://root:taosdata@localhost:6041/%s' % db_name)
+
+    stmt = conn.statement()
+    stmt.prepare("insert into t1 values (?, ?, ?, ?)")
+
+    stmt.bind_param([
+        taosws.millis_timestamps_to_column([1686844800000, 1686844801000, 1686844802000, 1686844803000]),
+        taosws.ints_to_column([1, 2, 3, 4]),
+        taosws.floats_to_column([1.1, 2.2, 3.3, 4.4]),
+        taosws.varchar_to_column(['a', 'b', 'c', 'd']),
+    ])
+
+    stmt.add_batch()
+    rows = stmt.execute()
+    assert rows == 4
+    stmt.close()
+    after_test(db_name)
+
+
+def stmt_insert_into_stable():
+    db_name = 'test_ws_stmt_{}'.format(int(time.time()))
+    before_test(db_name)
+
+    conn = taosws.connect("taosws://root:taosdata@localhost:6041/%s" % db_name)
+
+    stmt = conn.statement()
+    stmt.prepare("insert into ? using stb1 tags (?, ?) values (?, ?, ?, ?)")
+    stmt.set_tbname('stb1_1')
+    stmt.set_tags([
+        taosws.int_to_tag(1),
+        taosws.varchar_to_tag('aaa'),
+    ])
+    stmt.bind_param([
+        taosws.millis_timestamps_to_column([1686844800000, 1686844801000, 1686844802000, 1686844803000]),
+        taosws.ints_to_column([1, 2, 3, 4]),
+        taosws.floats_to_column([1.1, 2.2, 3.3, 4.4]),
+        taosws.varchar_to_column(['a', 'b', 'c', 'd']),
+    ])
+
+    stmt.add_batch()
+    rows = stmt.execute()
+    assert rows == 4
+    stmt.close()
+    after_test(db_name)
+
+
+if __name__ == '__main__':
+    stmt_insert()
+    stmt_insert_into_stable()

docs/zh/08-connector/30-python.mdx

@@ -672,6 +672,141 @@ consumer.close()
 </TabItem>
 </Tabs>
 
+### 通过参数绑定写入数据
+
+TDengine 的 Python 连接器支持参数绑定风格的 Prepare API 方式写入数据，和大多数数据库类似，目前仅支持用 `?` 来代表待绑定的参数。
+
+<Tabs>
+<TabItem value="native" label="原生连接">
+
+#### 创建 stmt
+
+Python 连接器的 `Connection` 提供了 `statement` 方法用于创建参数绑定对象 stmt，该方法接收 sql 字符串作为参数，sql 字符串目前仅支持用 `?` 来代表绑定的参数。
+
+```
+import taos
+
+conn = taos.connect()
+stmt = conn.statement("insert into log values(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)")
+```
+
+#### 参数绑定
+
+调用 `new_multi_binds` 函数创建 params 列表，用于参数绑定。
+
+```
+params = new_multi_binds(16)
+params[0].timestamp((1626861392589, 1626861392590, 1626861392591))
+params[1].bool((True, None, False))
+params[2].tinyint([-128, -128, None])  # -128 is tinyint null
+params[3].tinyint([0, 127, None])
+params[4].smallint([3, None, 2])
+params[5].int([3, 4, None])
+params[6].bigint([3, 4, None])
+params[7].tinyint_unsigned([3, 4, None])
+params[8].smallint_unsigned([3, 4, None])
+params[9].int_unsigned([3, 4, None])
+params[10].bigint_unsigned([3, 4, None])
+params[11].float([3, None, 1])
+params[12].double([3, None, 1.2])
+params[13].binary(["abc", "dddafadfadfadfadfa", None])
+params[14].nchar(["涛思数据", None, "a long string with 中文字符"])
+params[15].timestamp([None, None, 1626861392591])
+```
+
+调用 stmt 的 `bind_param` 以单行的方式设置 values 或 `bind_param_batch` 以多行的方式设置 values 方法绑定参数。
+
+```
+stmt.bind_param_batch(params)
+```
+
+#### 执行 sql
+
+调用 stmt 的 `execute` 方法执行 sql
+
+```
+stmt.execute()
+```
+
+#### 关闭 stmt
+
+最后需要关闭 stmt。
+
+```
+stmt.close()
+```
+
+#### 示例代码
+
+```python
+{{#include docs/examples/python/stmt_example.py}}
+```
+</TabItem>
+
+<TabItem value="websocket" label="WebSocket 连接">
+
+#### 创建 stmt
+
+Python WebSocket 连接器的 `Connection` 提供了 `statement` 方法用于创建参数绑定对象 stmt，该方法接收 sql 字符串作为参数，sql 字符串目前仅支持用 `?` 来代表绑定的参数。
+
+```
+import taosws
+
+conn = taosws.connect('taosws://localhost:6041/test')
+stmt = conn.statement()
+```
+
+#### 解析 sql
+
+调用 stmt 的 `prepare` 方法来解析 insert 语句。
+
+```
+stmt.prepare("insert into t1 values (?, ?, ?, ?)")
+```
+
+#### 参数绑定
+
+调用 stmt 的 `bind_param` 方法绑定参数。
+
+```
+stmt.bind_param([
+    taosws.millis_timestamps_to_column([1686844800000, 1686844801000, 1686844802000, 1686844803000]),
+    taosws.ints_to_column([1, 2, 3, 4]),
+    taosws.floats_to_column([1.1, 2.2, 3.3, 4.4]),
+    taosws.varchar_to_column(['a', 'b', 'c', 'd']),
+])
+```
+
+调用 stmt 的 `add_batch` 方法，将参数加入批处理。
+
+```
+stmt.add_batch()
+```
+
+#### 执行 sql
+
+调用 stmt 的 `execute` 方法执行 sql
+
+```
+stmt.execute()
+```
+
+#### 关闭 stmt
+
+最后需要关闭 stmt。
+
+```
+stmt.close()
+```
+
+#### 示例代码
+
+```python
+{{#include docs/examples/python/stmt_websocket_example.py}}
+```
+</TabItem>
+</Tabs>
+
 ### 其它示例程序
 
 | 示例程序链接                                                                                                  | 示例程序内容            |