未验证 提交 0d2fa6f1 编写于 作者: sangshuduo's avatar sangshuduo 提交者: GitHub

docs: refine python connector doc for req_id (#21526)

* docs: update csharp connector status

* docs: fix csharp ws bulk pulling

* docs: clarify database param is optional to websocket dsn

* docs: fix java connector mistake

* fix: a few typos

* fix: many typos

* docs: java connector support subscription over websocket

* fix: update 3.0 connector feature matrix

* docs: fix typos and use 3.1.0 in jdbc driver

* fix: update matrix for schemaless java status

* docs: use latest jdbc version in connect section

* docs: refine python connector doc for req_id
上级 d4bd1906
...@@ -362,7 +362,7 @@ By using the optional req_id parameter, you can specify a request ID that can be ...@@ -362,7 +362,7 @@ By using the optional req_id parameter, you can specify a request ID that can be
##### TaosConnection class ##### 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). As the way to connect introduced above but add `req_id` argument.
```python title="execute method" ```python title="execute method"
{{#include docs/examples/python/connection_usage_native_reference_with_req_id.py:insert}} {{#include docs/examples/python/connection_usage_native_reference_with_req_id.py:insert}}
...@@ -372,13 +372,9 @@ The `TaosConnection` class contains both an implementation of the PEP249 Connect ...@@ -372,13 +372,9 @@ The `TaosConnection` class contains both an implementation of the PEP249 Connect
{{#include docs/examples/python/connection_usage_native_reference_with_req_id.py:query}} {{#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 ##### 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. As the way to fetch data introduced above but add `req_id` argument.
```python title="blocks_iter method" ```python title="blocks_iter method"
{{#include docs/examples/python/result_set_with_req_id_examples.py}} {{#include docs/examples/python/result_set_with_req_id_examples.py}}
...@@ -391,17 +387,12 @@ The `TaosConnection` class and the `TaosResult` class already implement all the ...@@ -391,17 +387,12 @@ The `TaosConnection` class and the `TaosResult` class already implement all the
{{#include docs/examples/python/cursor_usage_native_reference_with_req_id.py}} {{#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>
<TabItem value="rest" label="REST connection"> <TabItem value="rest" label="REST connection">
##### Use of TaosRestCursor class ##### Use of TaosRestCursor class
The `TaosRestCursor` class is an implementation of the PEP249 Cursor interface. As the way to connect introduced above but add `req_id` argument.
```python title="Use of TaosRestCursor" ```python title="Use of TaosRestCursor"
{{#include docs/examples/python/connect_rest_with_req_id_examples.py:basic}} {{#include docs/examples/python/connect_rest_with_req_id_examples.py:basic}}
...@@ -421,8 +412,11 @@ The `RestClient` class is a direct wrapper for the [REST API](/reference/rest-ap ...@@ -421,8 +412,11 @@ The `RestClient` class is a direct wrapper for the [REST API](/reference/rest-ap
For a more detailed description of the `sql()` method, please refer to [RestClient](https://docs.taosdata.com/api/taospy/taosrest/restclient.html). For a more detailed description of the `sql()` method, please refer to [RestClient](https://docs.taosdata.com/api/taospy/taosrest/restclient.html).
</TabItem> </TabItem>
<TabItem value="websocket" label="WebSocket connection"> <TabItem value="websocket" label="WebSocket connection">
As the way to connect introduced above but add `req_id` argument.
```python ```python
{{#include docs/examples/python/connect_websocket_with_req_id_examples.py:basic}} {{#include docs/examples/python/connect_websocket_with_req_id_examples.py:basic}}
``` ```
......
...@@ -362,7 +362,7 @@ TaosCursor 类使用原生连接进行写入、查询操作。在客户端多线 ...@@ -362,7 +362,7 @@ TaosCursor 类使用原生连接进行写入、查询操作。在客户端多线
##### TaosConnection 类的使用 ##### TaosConnection 类的使用
`TaosConnection` 类既包含对 PEP249 Connection 接口的实现(如:`cursor`方法和 `close` 方法),也包含很多扩展功能(如: `execute`、 `query`、`schemaless_insert` 和 `subscribe` 方法 类似上文介绍的使用方法,增加 `req_id` 参数
```python title="execute 方法" ```python title="execute 方法"
{{#include docs/examples/python/connection_usage_native_reference_with_req_id.py:insert}} {{#include docs/examples/python/connection_usage_native_reference_with_req_id.py:insert}}
...@@ -372,13 +372,9 @@ TaosCursor 类使用原生连接进行写入、查询操作。在客户端多线 ...@@ -372,13 +372,9 @@ TaosCursor 类使用原生连接进行写入、查询操作。在客户端多线
{{#include docs/examples/python/connection_usage_native_reference_with_req_id.py:query}} {{#include docs/examples/python/connection_usage_native_reference_with_req_id.py:query}}
``` ```
:::tip
查询结果只能获取一次。比如上面的示例中 `fetch_all()` 和 `fetch_all_into_dict()` 只能用一个。重复获取得到的结果为空列表。
:::
##### TaosResult 类的使用 ##### TaosResult 类的使用
上面 `TaosConnection` 类的使用示例中,我们已经展示了两种获取查询结果的方法: `fetch_all()` 和 `fetch_all_into_dict()`。除此之外 `TaosResult` 还提供了按行迭代(`rows_iter`)或按数据块迭代(`blocks_iter`)结果集的方法。在查询数据量较大的场景,使用这两个方法会更高效 类似上文介绍的使用方法,增加 `req_id` 参数
```python title="blocks_iter 方法" ```python title="blocks_iter 方法"
{{#include docs/examples/python/result_set_with_req_id_examples.py}} {{#include docs/examples/python/result_set_with_req_id_examples.py}}
...@@ -391,14 +387,11 @@ TaosCursor 类使用原生连接进行写入、查询操作。在客户端多线 ...@@ -391,14 +387,11 @@ TaosCursor 类使用原生连接进行写入、查询操作。在客户端多线
{{#include docs/examples/python/cursor_usage_native_reference_with_req_id.py}} {{#include docs/examples/python/cursor_usage_native_reference_with_req_id.py}}
``` ```
:::note
TaosCursor 类使用原生连接进行写入、查询操作。在客户端多线程的场景下,这个游标实例必须保持线程独享,不能跨线程共享使用,否则会导致返回结果出现错误。
:::
</TabItem> </TabItem>
<TabItem value="rest" label="REST 连接"> <TabItem value="rest" label="REST 连接">
类似上文介绍的使用方法,增加 `req_id` 参数。
##### TaosRestCursor 类的使用 ##### TaosRestCursor 类的使用
`TaosRestCursor` 类是对 PEP249 Cursor 接口的实现。 `TaosRestCursor` 类是对 PEP249 Cursor 接口的实现。
...@@ -420,8 +413,11 @@ TaosCursor 类使用原生连接进行写入、查询操作。在客户端多线 ...@@ -420,8 +413,11 @@ TaosCursor 类使用原生连接进行写入、查询操作。在客户端多线
对于 `sql()` 方法更详细的介绍, 请参考 [RestClient](https://docs.taosdata.com/api/taospy/taosrest/restclient.html)。 对于 `sql()` 方法更详细的介绍, 请参考 [RestClient](https://docs.taosdata.com/api/taospy/taosrest/restclient.html)。
</TabItem> </TabItem>
<TabItem value="websocket" label="WebSocket 连接"> <TabItem value="websocket" label="WebSocket 连接">
类似上文介绍的使用方法,增加 `req_id` 参数。
```python ```python
{{#include docs/examples/python/connect_websocket_with_req_id_examples.py:basic}} {{#include docs/examples/python/connect_websocket_with_req_id_examples.py:basic}}
``` ```
......
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册