Skip to content

T
TDengine

taosdata / TDengine
接近 2 年 前同步成功

通知 1192
Star 22018
Fork 4786
T
TDengine
未验证 提交 430bad97 编写于 作者: B Bo Ding 提交者： GitHub
浏览文件
操作

docs: python connector part3 (#11958)

上级 48ae5daa
隐藏空白更改
内联 并排
Showing with 53 addition and 27 deletion
docs-cn/14-reference/03-connector/python.mdx
浏览文件 @ 430bad97
......@@ -101,7 +101,7 @@ import taosrest
</Tabs>
:::tip
如果系统上有多个版本的 Python，则可能有多个 `pip` 命令。要确保使用的 `pip` 命令路径是正确的。上面我们用 `pip3` 命令安装，排除了使用 Python 2.x 版本对应的 `pip` 的可能性。但是如果系统上有多个 Python 3.x 版本，仍需检查安装路径是否正确。最简单的验证方式是，在命令再次输入 `pip3 install taospy`, 就会打印出 `taospy` 的具体安装位置，比如在 Widnows 上：
如果系统上有多个版本的 Python，则可能有多个 `pip` 命令。要确保使用的 `pip` 命令路径是正确的。上面我们用 `pip3` 命令安装，排除了使用 Python 2.x 版本对应的 `pip` 的可能性。但是如果系统上有多个 Python 3.x 版本，仍需检查安装路径是否正确。最简单的验证方式是，在命令再次输入 `pip3 install taospy`, 就会打印出 `taospy` 的具体安装位置，比如在 Windows 上：
```
C:\> pip3 install taospy
......@@ -115,7 +115,7 @@ Requirement already satisfied: taospy in c:\users\username\appdata\local\program
### 连通性测试
在用连接器建立连接之前，建议先测试本地 TDengine CLI 到 TDengine 集群的连。
在用连接器建立连接之前，建议先测试本地 TDengine CLI 到 TDengine 集群的连通性。
<Tabs>
<TabItem value="native" label="原生连接">
......@@ -217,7 +217,7 @@ curl -u root:taosdata http://<FQDN>:<PORT>/rest/sql -d "select server_version()"
<Tabs default="native" groupId="connect">
<TabItem value="native" label="原生连接">
#### TaosConnection 类的使用
##### TaosConnection 类的使用
`TaosConnection` 类既包含对 PEP249 Connection 接口的实现(如：`cursor`方法和 `close` 方法)，也包含很多扩展功能（如： `execute`、 `query`、`schemaless_insert` 和 `subscribe` 方法。
......@@ -233,14 +233,14 @@ curl -u root:taosdata http://<FQDN>:<PORT>/rest/sql -d "select server_version()"
查询结果只能获取一次。比如上面的示例中 `featch_all` 和 `fetch_all_into_dict` 只能用一个。重复获取得到的结果为空列表。
:::
#### TaosResult 类的使用
##### TaosResult 类的使用
上面 `TaosConnection` 类的使用示例中，我们已经展示了两种获取查询结果的方法： `featch_all` 和 `fetch_all_into_dict`。除此之外 `TaosResult` 还提供了按行迭代(`rows_iter`)或按数据块迭代(`blocks_iter`)结果集的方法。在查询数据量较大的场景，使用这两个方法会更高效。
```python title="blocks_iter 方法"
{{#include docs-examples/python/result_set_examples.py}}
```
#### TaosCursor 类的使用
##### TaosCursor 类的使用
`TaosConnection` 类和 `TaosResult` 类已经实现了原生接口的所有功能。如果你对 PEP249 规范中的接口比较熟悉也可以使用 `TaosCursor` 类提供的方法。
......@@ -256,9 +256,28 @@ TaosCursor 类使用原生连接进行写入、查询操作。在客户端多线
</TabItem>
<TabItem value="rest" label="REST 连接">
```python
##### TaosRestCursor 类的使用
`TaosRestCursor` 类是对 PEP249 Cursor 接口的实现。
```python title="TaosRestCursor 的使用"
{{#include docs-examples/python/connect_rest_examples.py:basic}}
```
- `cursor.execute` ： 用来执行任意 SQL 语句。
- `cursor.rowcount`： 对于写入操作返回写入成功记录数。对于查询操作，返回结果集行数。
- `cursor.description` ： 返回字段的描述信息。关于描述信息的具体格式请参考[TaosRestCursor](https://docs.taosdata.com/api/taospy/taosrest/cursor.html)。
##### RestClient 类的使用
`RestClient` 类是对于 [REST API](/reference/rest-api) 的直接封装。它只包含一个 `sql()` 方法用于执行任意 SQL 语句， 并返回执行结果。
```python title="RestClient 的使用"
{{#include docs-examples/python/rest_client_example.py}}
```
对于 `sql()` 方法更详细的介绍， 请参考 [RestClient](https://docs.taosdata.com/api/taospy/taosrest/restclient.html)。
</TabItem>
</Tabs>
......@@ -293,7 +312,7 @@ TaosCursor 类使用原生连接进行写入、查询操作。在客户端多线
| [subscribe-async.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/subscribe-async.py) | 异步订阅 |
| [subscribe-sync.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/subscribe-sync.py) | 同步订阅 |
## 其它说明
## 其它说明
### 异常处理
......@@ -305,7 +324,7 @@ TaosCursor 类使用原生连接进行写入、查询操作。在客户端多线
### 关于纳秒 (nanosecond)
由于目前 Python 对 nanosecond 支持的不完善(参见下面的链接)，目前的实现方式是在 nanosecond 精度时返回整数，而不是 ms 和 us 返回的 datetime 类型，应用开发者需要自行处理，建议使用 pandas 的 to_datetime()。未来如果 Python 正式完整支持了纳秒，Python 连接器可能会修改相关接口。
由于目前 Python 对 nanosecond 支持的不完善(见下面的链接)，目前的实现方式是在 nanosecond 精度时返回整数，而不是 ms 和 us 返回的 datetime 类型，应用开发者需要自行处理，建议使用 pandas 的 to_datetime()。未来如果 Python 正式完整支持了纳秒，Python 连接器可能会修改相关接口。
1. https://stackoverflow.com/questions/10611328/parsing-datetime-strings-containing-nanoseconds
2. https://www.python.org/dev/peps/pep-0564/
......@@ -317,14 +336,14 @@ TaosCursor 类使用原生连接进行写入、查询操作。在客户端多线
## 重要更新
| 连接器版本 | 主要更新 | 发布日期 |
| ---------- | -------- | -------- |
| 2.3.0 | | |
| 2.2.5 | | |
| 2.2.4 | | |
| 2.2.3 | | |
| 连接器版本 | 重要更新 | 发布日期 |
| ---------- | --------------------------------------------------------------------------------- | ---------- |
| 2.3.0 | 1. support TDengine REST API <br/> 2. remove support for Python version below 3.6 | 2022-04-27 |
| 2.2.5 | support timezone option when connect | 2022-04-13 |
| 2.2.2 | support sqlalchemy dialect plugin | 2022-03-28 |
要了解更多，请参考：[Release Notes](https://github.com/taosdata/taos-connector-python/releases)
[**Release Notes**](https://github.com/taosdata/taos-connector-python/releases)
## API 参考
......
docs-examples/python/connect_rest_examples.py
浏览文件 @ 430bad97
......@@ -10,7 +10,7 @@ conn: TaosRestConnection = connect(host="localhost",
# ANCHOR_END: connect
# ANCHOR: basic
# create STable
cursor = conn.cursor()
cursor: TaosRestCursor = conn.cursor()
cursor.execute("DROP DATABASE IF EXISTS power")
cursor.execute("CREATE DATABASE power")
cursor.execute("CREATE STABLE power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)")
......@@ -20,10 +20,12 @@ cursor.execute("""INSERT INTO power.d1001 USING power.meters TAGS(Beijing.Chaoya
power.d1002 USING power.meters TAGS(Beijing.Chaoyang, 3) VALUES ('2018-10-03 14:38:16.650', 10.30000, 218, 0.25000)
power.d1003 USING power.meters TAGS(Beijing.Haidian, 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(Beijing.Haidian, 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)""")
print("affected rows", cursor.rowcount)
print("inserted row count:", cursor.rowcount)
# query data
cursor.execute("SELECT * FROM power.meters")
cursor.execute("SELECT * FROM power.meters LIMIT 3")
# 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
......@@ -33,15 +35,11 @@ for row in data:
print(row)
# output:
# affected rows 8
# inserted row count: 8
# queried row count: 3
# ['ts', 'current', 'voltage', 'phase', 'location', 'groupid']
# [datetime.datetime(2018, 10, 3, 14, 38, 5, tzinfo=tzinfo(480,'+08:00')), 10.3, 219, 0.31, 'beijing.chaoyang', 2]
# [datetime.datetime(2018, 10, 3, 14, 38, 15, tzinfo=tzinfo(480,'+08:00')), 12.6, 218, 0.33, 'beijing.chaoyang', 2]
# [datetime.datetime(2018, 10, 3, 14, 38, 16, 800000, tzinfo=tzinfo(480,'+08:00')), 12.3, 221, 0.31, 'beijing.chaoyang', 2]
# [datetime.datetime(2018, 10, 3, 14, 38, 16, 650000, tzinfo=tzinfo(480,'+08:00')), 10.3, 218, 0.25, 'beijing.chaoyang', 3]
# [datetime.datetime(2018, 10, 3, 14, 38, 5, 500000, tzinfo=tzinfo(480,'+08:00')), 11.8, 221, 0.28, 'beijing.haidian', 2]
# [datetime.datetime(2018, 10, 3, 14, 38, 16, 600000, tzinfo=tzinfo(480,'+08:00')), 13.4, 223, 0.29, 'beijing.haidian', 2]
# [datetime.datetime(2018, 10, 3, 14, 38, 5, tzinfo=tzinfo(480,'+08:00')), 10.8, 223, 0.29, 'beijing.haidian', 3]
# [datetime.datetime(2018, 10, 3, 14, 38, 6, 500000, tzinfo=tzinfo(480,'+08:00')), 11.5, 221, 0.35, 'beijing.haidian', 3]
# [datetime.datetime(2018, 10, 3, 14, 38, 5, tzinfo=datetime.timezone(datetime.timedelta(seconds=28800), '+08:00')), 10.3, 219, 0.31, 'beijing.chaoyang', 2]
# [datetime.datetime(2018, 10, 3, 14, 38, 15, tzinfo=datetime.timezone(datetime.timedelta(seconds=28800), '+08:00')), 12.6, 218, 0.33, 'beijing.chaoyang', 2]
# [datetime.datetime(2018, 10, 3, 14, 38, 16, 800000, tzinfo=datetime.timezone(datetime.timedelta(seconds=28800), '+08:00')), 12.3, 221, 0.31, 'beijing.chaoyang', 2]
# ANCHOR_END: basic
docs-examples/python/rest_client_example.py 0 → 100644
浏览文件 @ 430bad97
from taosrest import RestClient
client = RestClient("localhost", 6041, "root", "taosdata")
res: dict = client.sql("SELECT ts, current FROM power.meters LIMIT 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}
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或