docs: add content about req-id (#20650)

319ec95b · Adam Ji · GitHub · a5d4dfe2 · 319ec95b · 319ec95b
8 changed file
--- a/docs/en/14-reference/03-connector/07-python.mdx
+++ b/docs/en/14-reference/03-connector/07-python.mdx
@@ -353,6 +353,86 @@ For a more detailed description of the `sql()` method, please refer to [RestClie
 </TabItem>
 </Tabs>

+### Usage with req_id
+
+By using the optional req_id parameter, you can specify a request ID that can be used for tracing.
+
+<Tabs defaultValue="rest">
+<TabItem value="native" label="native connection">
+
+##### TaosConnection class
+
+The `TaosConnection` class contains both an implementation of the PEP249 Connection interface (e.g., the `cursor()` method and the `close()` method) and many extensions (e.g., the `execute()`, `query()`, `schemaless_insert()`, and `subscribe()` methods).
+
+```python title="execute method"
+{{#include docs/examples/python/connection_usage_native_reference_with_req_id.py:insert}}
+```
+
+```python title="query method"
+{{#include docs/examples/python/connection_usage_native_reference_with_req_id.py:query}}
+```
+
+:::tip
+The queried results can only be fetched once. For example, only one of `fetch_all()` and `fetch_all_into_dict()` can be used in the example above. Repeated fetches will result in an empty list.
+:::
+
+##### Use of TaosResult class
+
+In the above example of using the `TaosConnection` class, we have shown two ways to get the result of a query: `fetch_all()` and `fetch_all_into_dict()`. In addition, `TaosResult` also provides methods to iterate through the result set by rows (`rows_iter`) or by data blocks (`blocks_iter`). Using these two methods will be more efficient in scenarios where the query has a large amount of data.
+
+```python title="blocks_iter method"
+{{#include docs/examples/python/result_set_with_req_id_examples.py}}
+```
+##### Use of the TaosCursor class
+
+The `TaosConnection` class and the `TaosResult` class already implement all the functionality of the native interface. If you are familiar with the interfaces in the PEP249 specification, you can also use the methods provided by the `TaosCursor` class.
+
+```python title="Use of TaosCursor"
+{{#include docs/examples/python/cursor_usage_native_reference_with_req_id.py}}
+```
+
+:::note
+The TaosCursor class uses native connections for write and query operations. In a client-side multi-threaded scenario, this cursor instance must remain thread exclusive and cannot be shared across threads for use, otherwise, it will result in errors in the returned results.
+
+:::
+
+</TabItem>
+<TabItem value="rest" label="REST connection">
+
+##### Use of TaosRestCursor class
+
+The `TaosRestCursor` class is an implementation of the PEP249 Cursor interface.
+
+```python title="Use of TaosRestCursor"
+{{#include docs/examples/python/connect_rest_with_req_id_examples.py:basic}}
+```
+- `cursor.execute`: Used to execute arbitrary SQL statements.
+- `cursor.rowcount` : For write operations, returns the number of successful rows written. For query operations, returns the number of rows in the result set.
+- `cursor.description` : Returns the description of the field. Please refer to [TaosRestCursor](https://docs.taosdata.com/api/taospy/taosrest/cursor.html) for the specific format of the description information.
+
+##### Use of the RestClient class
+
+The `RestClient` class is a direct wrapper for the [REST API](/reference/rest-api). It contains only a `sql()` method for executing arbitrary SQL statements and returning the result.
+
+```python title="Use of RestClient"
+{{#include docs/examples/python/rest_client_with_req_id_example.py}}
+```
+
+For a more detailed description of the `sql()` method, please refer to [RestClient](https://docs.taosdata.com/api/taospy/taosrest/restclient.html).
+
+</TabItem>
+<TabItem value="websocket" label="WebSocket connection">
+
+```python
+{{#include docs/examples/python/connect_websocket_with_req_id_examples.py:basic}}
+```
+
+- `conn.execute`: can use to execute arbitrary SQL statements, and return the number of rows affected.
+- `conn.query`: can use to execute query SQL statements, and return the query results.
+
+</TabItem>
+</Tabs>
+
 ### Used with pandas

 <Tabs defaultValue="rest">

--- a/docs/examples/python/connect_rest_with_req_id_examples.py
+++ b/docs/examples/python/connect_rest_with_req_id_examples.py
+# ANCHOR: connect
+from taosrest import connect, TaosRestConnection, TaosRestCursor
+
+conn = connect(url="http://localhost:6041",
+               user="root",
+               password="taosdata",
+               timeout=30)
+
+# ANCHOR_END: connect
+# ANCHOR: basic
+# create STable
+cursor = conn.cursor()
+cursor.execute("DROP DATABASE IF EXISTS power", req_id=1)
+cursor.execute("CREATE DATABASE power", req_id=2)
+cursor.execute(
+    "CREATE STABLE power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)", req_id=3)
+
+# insert data
+cursor.execute("""INSERT INTO power.d1001 USING power.meters TAGS('California.SanFrancisco', 2) VALUES ('2018-10-03 14:38:05.000', 10.30000, 219, 0.31000) ('2018-10-03 14:38:15.000', 12.60000, 218, 0.33000) ('2018-10-03 14:38:16.800', 12.30000, 221, 0.31000)
+    power.d1002 USING power.meters TAGS('California.SanFrancisco', 3) VALUES ('2018-10-03 14:38:16.650', 10.30000, 218, 0.25000)
+    power.d1003 USING power.meters TAGS('California.LosAngeles', 2) VALUES ('2018-10-03 14:38:05.500', 11.80000, 221, 0.28000) ('2018-10-03 14:38:16.600', 13.40000, 223, 0.29000)
+    power.d1004 USING power.meters TAGS('California.LosAngeles', 3) VALUES ('2018-10-03 14:38:05.000', 10.80000, 223, 0.29000) ('2018-10-03 14:38:06.500', 11.50000, 221, 0.35000)""", req_id=4)
+print("inserted row count:", cursor.rowcount)
+
+# query data
+cursor.execute("SELECT * FROM power.meters LIMIT 3", req_id=5)
+# get total rows
+print("queried row count:", cursor.rowcount)
+# get column names from cursor
+column_names = [meta[0] for meta in cursor.description]
+# get rows
+data = cursor.fetchall()
+print(column_names)
+for row in data:
+    print(row)
+
+# output:
+# inserted row count: 8
+# queried row count: 3
+# ['ts', 'current', 'voltage', 'phase', 'location', 'groupid']
+# [datetime.datetime(2018, 10, 3, 14, 38, 5, 500000, tzinfo=datetime.timezone(datetime.timedelta(seconds=28800), '+08:00')), 11.8, 221, 0.28, 'california.losangeles', 2]
+# [datetime.datetime(2018, 10, 3, 14, 38, 16, 600000, tzinfo=datetime.timezone(datetime.timedelta(seconds=28800), '+08:00')), 13.4, 223, 0.29, 'california.losangeles', 2]
+# [datetime.datetime(2018, 10, 3, 14, 38, 5, tzinfo=datetime.timezone(datetime.timedelta(seconds=28800), '+08:00')), 10.8, 223, 0.29, 'california.losangeles', 3]
+# ANCHOR_END: basic
--- a/docs/examples/python/connect_websocket_with_req_id_examples.py
+++ b/docs/examples/python/connect_websocket_with_req_id_examples.py
+# ANCHOR: connect
+import taosws
+
+conn = taosws.connect("taosws://root:taosdata@localhost:6041")
+# ANCHOR_END: connect
+
+# ANCHOR: basic
+conn.execute("drop database if exists connwspy", req_id=1)
+conn.execute("create database if not exists connwspy", req_id=2)
+conn.execute("use connwspy", req_id=3)
+conn.execute("create table if not exists stb (ts timestamp, c1 int) tags (t1 int)", req_id=4)
+conn.execute("create table if not exists tb1 using stb tags (1)", req_id=5)
+conn.execute("insert into tb1 values (now, 1)", req_id=6)
+conn.execute("insert into tb1 values (now, 2)", req_id=7)
+conn.execute("insert into tb1 values (now, 3)", req_id=8)
+
+r = conn.execute("select * from stb", req_id=9)
+result = conn.query("select * from stb", req_id=10)
+num_of_fields = result.field_count
+print(num_of_fields)
+
+for row in result:
+    print(row)
+
+# output:
+# 3
+# ('2023-02-28 15:56:13.329 +08:00', 1, 1)
+# ('2023-02-28 15:56:13.333 +08:00', 2, 1)
+# ('2023-02-28 15:56:13.337 +08:00', 3, 1)
--- a/docs/examples/python/connection_usage_native_reference_with_req_id.py
+++ b/docs/examples/python/connection_usage_native_reference_with_req_id.py
+import taos
+
+# ANCHOR: insert
+conn = taos.connect()
+# Execute a sql, ignore the result set, just get affected rows. It's useful for DDL and DML statement.
+conn.execute("DROP DATABASE IF EXISTS test", req_id=1)
+conn.execute("CREATE DATABASE test", req_id=2)
+# change database. same as execute "USE db"
+conn.select_db("test")
+conn.execute("CREATE STABLE weather(ts TIMESTAMP, temperature FLOAT) TAGS (location INT)", req_id=3)
+affected_row = conn.execute("INSERT INTO t1 USING weather TAGS(1) VALUES (now, 23.5) (now+1m, 23.5) (now+2m, 24.4)", req_id=4)
+print("affected_row", affected_row)
+# output:
+# affected_row 3
+# ANCHOR_END: insert
+
+# ANCHOR: query
+# Execute a sql and get its result set. It's useful for SELECT statement
+result = conn.query("SELECT * from weather", req_id=5)
+
+# Get fields from result
+fields = result.fields
+for field in fields:
+    print(field)  # {name: ts, type: 9, bytes: 8}
+
+# output:
+# {name: ts, type: 9, bytes: 8}
+# {name: temperature, type: 6, bytes: 4}
+# {name: location, type: 4, bytes: 4}
+
+# Get data from result as list of tuple
+data = result.fetch_all()
+print(data)
+# output:
+# [(datetime.datetime(2022, 4, 27, 9, 4, 25, 367000), 23.5, 1), (datetime.datetime(2022, 4, 27, 9, 5, 25, 367000), 23.5, 1), (datetime.datetime(2022, 4, 27, 9, 6, 25, 367000), 24.399999618530273, 1)]
+
+# Or get data from result as a list of dict
+# map_data = result.fetch_all_into_dict()
+# print(map_data)
+# output:
+# [{'ts': datetime.datetime(2022, 4, 27, 9, 1, 15, 343000), 'temperature': 23.5, 'location': 1}, {'ts': datetime.datetime(2022, 4, 27, 9, 2, 15, 343000), 'temperature': 23.5, 'location': 1}, {'ts': datetime.datetime(2022, 4, 27, 9, 3, 15, 343000), 'temperature': 24.399999618530273, 'location': 1}]
+# ANCHOR_END: query
+
+
+conn.close()
\ No newline at end of file
--- a/docs/examples/python/cursor_usage_native_reference_with_req_id.py
+++ b/docs/examples/python/cursor_usage_native_reference_with_req_id.py
+import taos
+
+conn = taos.connect()
+cursor = conn.cursor()
+
+cursor.execute("DROP DATABASE IF EXISTS test", req_id=1)
+cursor.execute("CREATE DATABASE test", req_id=2)
+cursor.execute("USE test", req_id=3)
+cursor.execute("CREATE STABLE weather(ts TIMESTAMP, temperature FLOAT) TAGS (location INT)", req_id=4)
+
+for i in range(1000):
+    location = str(i % 10)
+    tb = "t" + location
+    cursor.execute(f"INSERT INTO {tb} USING weather TAGS({location}) VALUES (now+{i}a, 23.5) (now+{i + 1}a, 23.5)", req_id=5+i)
+
+cursor.execute("SELECT count(*) FROM weather", req_id=1005)
+data = cursor.fetchall()
+print("count:", data[0][0])
+cursor.execute("SELECT tbname, * FROM weather LIMIT 2", req_id=1006)
+col_names = [meta[0] for meta in cursor.description]
+print(col_names)
+rows = cursor.fetchall()
+print(rows)
+
+cursor.close()
+conn.close()
+
+# output:
+# count: 2000
+# ['tbname', 'ts', 'temperature', 'location']
+# row_count: -1
+# [('t0', datetime.datetime(2022, 4, 27, 14, 54, 24, 392000), 23.5, 0), ('t0', datetime.datetime(2022, 4, 27, 14, 54, 24, 393000), 23.5, 0)]
--- a/docs/examples/python/rest_client_with_req_id_example.py
+++ b/docs/examples/python/rest_client_with_req_id_example.py
+from taosrest import RestClient
+
+client = RestClient("http://localhost:6041", user="root", password="taosdata")
+res: dict = client.sql("SELECT ts, current FROM power.meters LIMIT 1", req_id=1)
+print(res)
+
+# output:
+# {'status': 'succ', 'head': ['ts', 'current'], 'column_meta': [['ts', 9, 8], ['current', 6, 4]], 'data': [[datetime.datetime(2018, 10, 3, 14, 38, 5, tzinfo=datetime.timezone(datetime.timedelta(seconds=28800), '+08:00')), 10.3]], 'rows': 1}
+
--- a/docs/examples/python/result_set_with_req_id_examples.py
+++ b/docs/examples/python/result_set_with_req_id_examples.py
+import taos
+
+conn = taos.connect()
+conn.execute("DROP DATABASE IF EXISTS test", req_id=1)
+conn.execute("CREATE DATABASE test", req_id=2)
+conn.select_db("test")
+conn.execute("CREATE STABLE weather(ts TIMESTAMP, temperature FLOAT) TAGS (location INT)", req_id=3)
+# prepare data
+for i in range(2000):
+    location = str(i % 10)
+    tb = "t" + location
+    conn.execute(f"INSERT INTO {tb} USING weather TAGS({location}) VALUES (now+{i}a, 23.5) (now+{i + 1}a, 23.5)", req_id=4+i)
+
+result: taos.TaosResult = conn.query("SELECT * FROM weather", req_id=2004)
+
+block_index = 0
+blocks: taos.TaosBlocks = result.blocks_iter()
+for rows, length in blocks:
+    print("block ", block_index, " length", length)
+    print("first row in this block:", rows[0])
+    block_index += 1
+
+conn.close()
+
+# possible output:
+# block  0  length 1200
+# first row in this block: (datetime.datetime(2022, 4, 27, 15, 14, 52, 46000), 23.5, 0)
+# block  1  length 1200
+# first row in this block: (datetime.datetime(2022, 4, 27, 15, 14, 52, 76000), 23.5, 3)
+# block  2  length 1200
+# first row in this block: (datetime.datetime(2022, 4, 27, 15, 14, 52, 99000), 23.5, 6)
+# block  3  length 400
+# first row in this block: (datetime.datetime(2022, 4, 27, 15, 14, 52, 122000), 23.5, 9)
--- a/docs/zh/08-connector/30-python.mdx
+++ b/docs/zh/08-connector/30-python.mdx
@@ -353,6 +353,85 @@ TaosCursor 类使用原生连接进行写入、查询操作。在客户端多线
 </TabItem>
 </Tabs>

+### 与 req_id 一起使用
+
+使用可选的 req_id 参数，指定请求 id，可以用于 tracing
+
+<Tabs defaultValue="rest">
+<TabItem value="native" label="原生连接">
+
+##### TaosConnection 类的使用
+
+`TaosConnection` 类既包含对 PEP249 Connection 接口的实现(如：`cursor`方法和 `close` 方法)，也包含很多扩展功能（如： `execute`、 `query`、`schemaless_insert` 和 `subscribe` 方法。
+
+```python title="execute 方法"
+{{#include docs/examples/python/connection_usage_native_reference_with_req_id.py:insert}}
+```
+
+```python title="query 方法"
+{{#include docs/examples/python/connection_usage_native_reference_with_req_id.py:query}}
+```
+
+:::tip
+查询结果只能获取一次。比如上面的示例中 `fetch_all()` 和 `fetch_all_into_dict()` 只能用一个。重复获取得到的结果为空列表。
+:::
+
+##### TaosResult 类的使用
+
+上面 `TaosConnection` 类的使用示例中，我们已经展示了两种获取查询结果的方法： `fetch_all()` 和 `fetch_all_into_dict()`。除此之外 `TaosResult` 还提供了按行迭代(`rows_iter`)或按数据块迭代(`blocks_iter`)结果集的方法。在查询数据量较大的场景，使用这两个方法会更高效。
+
+```python title="blocks_iter 方法"
+{{#include docs/examples/python/result_set_with_req_id_examples.py}}
+```
+##### TaosCursor 类的使用
+
+`TaosConnection` 类和 `TaosResult` 类已经实现了原生接口的所有功能。如果你对 PEP249 规范中的接口比较熟悉也可以使用 `TaosCursor` 类提供的方法。
+
+```python title="TaosCursor 的使用"
+{{#include docs/examples/python/cursor_usage_native_reference_with_req_id.py}}
+```
+
+:::note
+TaosCursor 类使用原生连接进行写入、查询操作。在客户端多线程的场景下，这个游标实例必须保持线程独享，不能跨线程共享使用，否则会导致返回结果出现错误。
+
+:::
+
+</TabItem>
+<TabItem value="rest" label="REST 连接">
+
+#####  TaosRestCursor 类的使用
+
+`TaosRestCursor` 类是对 PEP249 Cursor 接口的实现。
+
+```python title="TaosRestCursor 的使用"
+{{#include docs/examples/python/connect_rest_with_req_id_examples.py:basic}}
+```
+- `cursor.execute` ： 用来执行任意 SQL 语句。
+- `cursor.rowcount`： 对于写入操作返回写入成功记录数。对于查询操作，返回结果集行数。
+- `cursor.description` ： 返回字段的描述信息。关于描述信息的具体格式请参考[TaosRestCursor](https://docs.taosdata.com/api/taospy/taosrest/cursor.html)。
+
+##### RestClient 类的使用
+
+`RestClient` 类是对于 [REST API](../rest-api) 的直接封装。它只包含一个 `sql()` 方法用于执行任意 SQL 语句， 并返回执行结果。
+
+```python title="RestClient 的使用"
+{{#include docs/examples/python/rest_client_with_req_id_example.py}}
+```
+
+对于 `sql()` 方法更详细的介绍， 请参考 [RestClient](https://docs.taosdata.com/api/taospy/taosrest/restclient.html)。
+</TabItem>
+<TabItem value="websocket" label="WebSocket 连接">
+
+```python
+{{#include docs/examples/python/connect_websocket_with_req_id_examples.py:basic}}
+```
+
+- `conn.execute`: 用来执行任意 SQL 语句，返回影响的行数
+- `conn.query`: 用来执行查询 SQL 语句，返回查询结果
+
+</TabItem>
+</Tabs>
+
 ### 与 pandas 一起使用

 <Tabs defaultValue="rest">