docs: add content about req-id (#20650)
This commit is contained in:
Adam Ji
GitHub
parent
a5d4dfe281
commit
319ec95b9d
|
|
@ -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">
|
||||
|
|
|
|||
|
|
@ -0,0 +1,44 @@
|
|||
# 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
|
||||
|
|
@ -0,0 +1,29 @@
|
|||
# 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)
|
||||
|
|
@ -0,0 +1,45 @@
|
|||
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()
|
||||
|
|
@ -0,0 +1,32 @@
|
|||
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)]
|
||||
|
|
@ -0,0 +1,9 @@
|
|||
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}
|
||||
|
||||
|
|
@ -0,0 +1,33 @@
|
|||
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)
|
||||
|
|
@ -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">
|
||||
|
|
|
|||
Loading…
Reference in New Issue