631 lines
20 KiB
Plaintext
631 lines
20 KiB
Plaintext
---
|
||
toc_max_heading_level: 4
|
||
sidebar_label: Python
|
||
title: TDengine Python Connector
|
||
description: "taospy 是 TDengine 的官方 Python 连接器。taospy 提供了丰富的 API， 使得 Python 应用可以很方便地使用 TDengine。tasopy 对 TDengine 的原生接口和 REST 接口都进行了封装， 分别对应 tasopy 的两个子模块：taos 和 taosrest。除了对原生接口和 REST 接口的封装，taospy 还提供了符合 Python 数据访问规范(PEP 249)的编程接口。这使得 taospy 和很多第三方工具集成变得简单，比如 SQLAlchemy 和 pandas"
|
||
---
|
||
|
||
import Tabs from "@theme/Tabs";
|
||
import TabItem from "@theme/TabItem";
|
||
import RequestId from "./_request_id.mdx";
|
||
|
||
`taospy` 是 TDengine 的官方 Python 连接器。`taospy` 提供了丰富的 API， 使得 Python 应用可以很方便地使用 TDengine。
|
||
|
||
Python 连接器的源码托管在 [GitHub](https://github.com/taosdata/taos-connector-python)。
|
||
|
||
## 连接方式
|
||
`taospy`主要提供三种形式的连接器。一般我们推荐使用 **Websocket 连接**。
|
||
- **原生连接**，对应 `taospy` 包的 `taos` 模块。通过 TDengine 客户端驱动程序（taosc）原生连接 TDengine 实例，支持数据写入、查询、数据订阅、schemaless 接口和参数绑定接口等功能。
|
||
- **REST 连接**，对应 `taospy` 包的 `taosrest` 模块。通过 taosAdapter 提供的 HTTP 接口连接 TDengine 实例，不支持 schemaless 和数据订阅等特性。
|
||
- **Websocket 连接**，对应 `taos-ws-py` 包，可以选装。通过 taosAdapter 提供的 Websocket 接口连接 TDengine 实例，WebSocket 连接实现的功能集合和原生连接有少量不同。
|
||
|
||
连接方式的详细介绍请参考：[连接器建立连接的方式](../../develop/connect/#连接器建立连接的方式)
|
||
|
||
除了对原生接口和 REST 接口的封装，`taospy` 还提供了符合 [Python 数据访问规范(PEP 249)](https://peps.python.org/pep-0249/) 的编程接口。这使得 `taospy` 和很多第三方工具集成变得简单，比如 [SQLAlchemy](https://www.sqlalchemy.org/) 和 [pandas](https://pandas.pydata.org/)。
|
||
|
||
使用客户端驱动提供的原生接口直接与服务端建立的连接的方式下文中称为“原生连接”；使用 taosAdapter 提供的 REST 接口或 WebSocket 接口与服务端建立的连接的方式下文中称为“REST 连接”或“WebSocket 连接”。
|
||
|
||
## 支持的平台
|
||
|
||
- 原生连接[支持的平台](../#支持的平台)和 TDengine 客户端支持的平台一致。
|
||
- REST 连接支持所有能运行 Python 的平台。
|
||
|
||
### 支持的功能
|
||
|
||
- 原生连接支持 TDengine 的所有核心功能， 包括： 连接管理、执行 SQL、参数绑定、订阅、无模式写入（schemaless）。
|
||
- REST 连接支持的功能包括：连接管理、执行 SQL。 (通过执行 SQL 可以： 管理数据库、管理表和超级表、写入数据、查询数据、创建连续查询等)。
|
||
|
||
## 历史版本
|
||
|
||
无论使用什么版本的 TDengine 都建议使用最新版本的 `taospy`。
|
||
|
||
|Python Connector 版本|主要变化|
|
||
|:-------------------:|:----:|
|
||
|2.7.12|1. 新增 varbinary 类型支持（STMT暂不支持 varbinary ）<br/> 2. query 性能提升（感谢贡献者[hadrianl](https://github.com/taosdata/taos-connector-python/pull/209)）|
|
||
|2.7.9|数据订阅支持获取消费进度和重置消费进度|
|
||
|2.7.8|新增 `execute_many`|
|
||
|
||
|Python Websocket Connector 版本|主要变化|
|
||
|:----------------------------:|:-----:|
|
||
|0.2.9|已知问题修复|
|
||
|0.2.5|1. 数据订阅支持获取消费进度和重置消费进度 <br/> 2. 支持 schemaless <br/> 3. 支持 STMT|
|
||
|0.2.4|数据订阅新增取消订阅方法|
|
||
|
||
## 处理异常
|
||
|
||
Python 连接器可能会产生 4 种异常：
|
||
|
||
- Python 连接器本身的异常
|
||
- 原生连接方式的异常
|
||
- websocket 连接方式异常
|
||
- 数据订阅异常
|
||
- TDengine 其他功能模块的异常
|
||
|
||
|Error Type|Description|Suggested Actions|
|
||
|:--------:|:---------:|:---------------:|
|
||
|InterfaceError|taosc 版本太低，不支持所使用的接口|请检查 TDengine 客户端版本|
|
||
|ConnectionError|数据库链接错误|请检查 TDengine 服务端状态和连接参数|
|
||
|DatabaseError|数据库错误|请检查 TDengine 服务端版本，并将 Python 连接器升级到最新版|
|
||
|OperationalError|操作错误|API 使用错误，请检查代码|
|
||
|ProgrammingError|||
|
||
|StatementError|stmt 相关异常||
|
||
|ResultError|||
|
||
|SchemalessError|schemaless 相关异常||
|
||
|TmqError|tmq 相关异常||
|
||
|
||
Python 中通常通过 try-expect 处理异常，异常处理相关请参考 [Python 错误和异常文档](https://docs.python.org/3/tutorial/errors.html)。
|
||
|
||
Python Connector 的所有数据库操作如果出现异常，都会直接抛出来。由应用程序负责异常处理。比如：
|
||
|
||
```python
|
||
{{#include docs/examples/python/handle_exception.py}}
|
||
```
|
||
|
||
## TDengine DataType 和 Python DataType
|
||
|
||
TDengine 目前支持时间戳、数字、字符、布尔类型，与 Python 对应类型转换如下：
|
||
|
||
|TDengine DataType|Python DataType|
|
||
|:---------------:|:-------------:|
|
||
|TIMESTAMP|datetime|
|
||
|INT|int|
|
||
|BIGINT|int|
|
||
|FLOAT|float|
|
||
|DOUBLE|int|
|
||
|SMALLINT|int|
|
||
|TINYINT|int|
|
||
|BOOL|bool|
|
||
|BINARY|str|
|
||
|NCHAR|str|
|
||
|JSON|str|
|
||
|
||
## 安装步骤
|
||
|
||
### 安装前准备
|
||
|
||
1. 安装 Python。新近版本 taospy 包要求 Python 3.6.2+。早期版本 taospy 包要求 Python 3.7+。taos-ws-py 包要求 Python 3.7+。如果系统上还没有 Python 可参考 [Python BeginnersGuide](https://wiki.python.org/moin/BeginnersGuide/Download) 安装。
|
||
2. 安装 [pip](https://pypi.org/project/pip/)。大部分情况下 Python 的安装包都自带了 pip 工具， 如果没有请参考 [pip documentation](https://pip.pypa.io/en/stable/installation/) 安装。
|
||
3. 如果使用原生连接，还需[安装客户端驱动](../#安装客户端驱动)。客户端软件包含了 TDengine 客户端动态链接库(libtaos.so 或 taos.dll) 和 TDengine CLI。
|
||
|
||
### 使用 pip 安装
|
||
|
||
#### 卸载旧版本
|
||
|
||
如果以前安装过旧版本的 Python 连接器, 请提前卸载。
|
||
|
||
```
|
||
pip3 uninstall taos taospy
|
||
```
|
||
|
||
:::note
|
||
较早的 TDengine 客户端软件包含了 Python 连接器。如果从客户端软件的安装目录安装了 Python 连接器，那么对应的 Python 包名是 `taos`。 所以上述卸载命令包含了 `taos`， 不存在也没关系。
|
||
|
||
:::
|
||
|
||
#### 安装 `taospy`
|
||
|
||
<Tabs>
|
||
<TabItem label="从 PyPI 安装" value="pypi">
|
||
|
||
安装最新版本
|
||
|
||
```
|
||
pip3 install taospy
|
||
```
|
||
|
||
也可以指定某个特定版本安装。
|
||
|
||
```
|
||
pip3 install taospy==2.3.0
|
||
```
|
||
|
||
</TabItem>
|
||
<TabItem label="从 GitHub 安装" value="github">
|
||
|
||
```
|
||
pip3 install git+https://github.com/taosdata/taos-connector-python.git
|
||
```
|
||
|
||
</TabItem>
|
||
</Tabs>
|
||
|
||
#### 安装 `taos-ws-py`（可选）
|
||
|
||
taos-ws-py 包提供了通过 WebSocket 连接 TDengine 的能力，可选安装 taos-ws-py 以获得 WebSocket 连接 TDengine 的能力。
|
||
|
||
|
||
##### 和 taospy 同时安装
|
||
|
||
```bash
|
||
pip3 install taospy[ws]
|
||
```
|
||
|
||
##### 单独安装
|
||
|
||
```bash
|
||
pip3 install taos-ws-py
|
||
```
|
||
|
||
### 安装验证
|
||
|
||
<Tabs defaultValue="rest">
|
||
<TabItem value="native" label="原生连接">
|
||
|
||
对于原生连接，需要验证客户端驱动和 Python 连接器本身是否都正确安装。如果能成功导入 `taos` 模块，则说明已经正确安装了客户端驱动和 Python 连接器。可在 Python 交互式 Shell 中输入：
|
||
|
||
```python
|
||
import taos
|
||
```
|
||
|
||
</TabItem>
|
||
<TabItem value="rest" label="REST 连接">
|
||
|
||
对于 REST 连接，只需验证是否能成功导入 `taosrest` 模块。可在 Python 交互式 Shell 中输入：
|
||
|
||
```python
|
||
import taosrest
|
||
```
|
||
|
||
</TabItem>
|
||
<TabItem value="ws" label="WebSocket 连接">
|
||
|
||
对于 WebSocket 连接，只需验证是否能成功导入 `taosws` 模块。可在 Python 交互式 Shell 中输入：
|
||
|
||
```python
|
||
import taosws
|
||
```
|
||
|
||
</TabItem>
|
||
</Tabs>
|
||
|
||
:::tip
|
||
如果系统上有多个版本的 Python，则可能有多个 `pip` 命令。要确保使用的 `pip` 命令路径是正确的。上面我们用 `pip3` 命令安装，排除了使用 Python 2.x 版本对应的 `pip` 的可能性。但是如果系统上有多个 Python 3.x 版本，仍需检查安装路径是否正确。最简单的验证方式是，在命令再次输入 `pip3 install taospy`, 就会打印出 `taospy` 的具体安装位置，比如在 Windows 上：
|
||
|
||
```
|
||
C:\> pip3 install taospy
|
||
Looking in indexes: https://pypi.tuna.tsinghua.edu.cn/simple
|
||
Requirement already satisfied: taospy in c:\users\username\appdata\local\programs\python\python310\lib\site-packages (2.3.0)
|
||
```
|
||
|
||
:::
|
||
|
||
## 建立连接
|
||
|
||
### 连通性测试
|
||
|
||
在用连接器建立连接之前，建议先测试本地 TDengine CLI 到 TDengine 集群的连通性。
|
||
|
||
<Tabs defaultValue="rest">
|
||
<TabItem value="native" label="原生连接">
|
||
|
||
请确保 TDengine 集群已经启动， 且集群中机器的 FQDN （如果启动的是单机版，FQDN 默认为 hostname）在本机能够解析, 可用 `ping` 命令进行测试：
|
||
|
||
```
|
||
ping <FQDN>
|
||
```
|
||
|
||
然后测试用 TDengine CLI 能否正常连接集群：
|
||
|
||
```
|
||
taos -h <FQDN> -p <PORT>
|
||
```
|
||
|
||
上面的 FQDN 可以为集群中任意一个 dnode 的 FQDN， PORT 为这个 dnode 对应的 serverPort。
|
||
|
||
</TabItem>
|
||
<TabItem value="rest" label="REST 连接" groupId="connect">
|
||
|
||
对于 REST 连接， 除了确保集群已经启动，还要确保 taosAdapter 组件已经启动。可以使用如下 curl 命令测试：
|
||
|
||
```
|
||
curl -u root:taosdata http://<FQDN>:<PORT>/rest/sql -d "select server_version()"
|
||
```
|
||
|
||
上面的 FQDN 为运行 taosAdapter 的机器的 FQDN， PORT 为 taosAdapter 配置的监听端口， 默认为 6041。
|
||
如果测试成功，会输出服务器版本信息，比如：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"column_meta": [
|
||
[
|
||
"server_version()",
|
||
"VARCHAR",
|
||
7
|
||
]
|
||
],
|
||
"data": [
|
||
[
|
||
"3.0.0.0"
|
||
]
|
||
],
|
||
"rows": 1
|
||
}
|
||
```
|
||
|
||
</TabItem>
|
||
<TabItem value="ws" label="WebSocket 连接" groupId="connect">
|
||
|
||
对于 WebSocket 连接， 除了确保集群已经启动，还要确保 taosAdapter 组件已经启动。可以使用如下 curl 命令测试：
|
||
|
||
```
|
||
curl -i -N -d "show databases" -H "Authorization: Basic cm9vdDp0YW9zZGF0YQ==" -H "Connection: Upgrade" -H "Upgrade: websocket" -H "Host: <FQDN>:<PORT>" -H "Origin: http://<FQDN>:<PORT>" http://<FQDN>:<PORT>/rest/sql
|
||
```
|
||
|
||
上面的 FQDN 为运行 taosAdapter 的机器的 FQDN， PORT 为 taosAdapter 配置的监听端口， 默认为 6041。
|
||
如果测试成功，会输出服务器版本信息，比如：
|
||
|
||
```json
|
||
HTTP/1.1 200 OK
|
||
Content-Type: application/json; charset=utf-8
|
||
Date: Tue, 21 Mar 2023 09:29:17 GMT
|
||
Transfer-Encoding: chunked
|
||
|
||
{"status":"succ","head":["server_version()"],"column_meta":[["server_version()",8,8]],"data":[["2.6.0.27"]],"rows":1}
|
||
```
|
||
|
||
</TabItem>
|
||
</Tabs>
|
||
|
||
### 指定 Host 和 Properties 获取连接
|
||
|
||
以下示例代码假设 TDengine 安装在本机， 且 FQDN 和 serverPort 都使用了默认配置。
|
||
|
||
<Tabs defaultValue="rest">
|
||
<TabItem value="native" label="原生连接" groupId="connect">
|
||
|
||
```python
|
||
{{#include docs/examples/python/connect_native_reference.py}}
|
||
```
|
||
|
||
`connect` 函数的所有参数都是可选的关键字参数。下面是连接参数的具体说明：
|
||
|
||
- `host` ： 要连接的节点的 FQDN。 没有默认值。如果不同提供此参数，则会连接客户端配置文件中的 firstEP。
|
||
- `user` ：TDengine 用户名。 默认值是 root。
|
||
- `password` ： TDengine 用户密码。 默认值是 taosdata。
|
||
- `port` ： 要连接的数据节点的起始端口，即 serverPort 配置。默认值是 6030。只有在提供了 host 参数的时候，这个参数才生效。
|
||
- `config` ： 客户端配置文件路径。 在 Windows 系统上默认是 `C:\TDengine\cfg`。 在 Linux/macOS 系统上默认是 `/etc/taos/`。
|
||
- `timezone` ： 查询结果中 TIMESTAMP 类型的数据，转换为 python 的 datetime 对象时使用的时区。默认为本地时区。
|
||
|
||
:::warning
|
||
`config` 和 `timezone` 都是进程级别的配置。建议一个进程建立的所有连接都使用相同的参数值。否则可能产生无法预知的错误。
|
||
:::
|
||
|
||
:::tip
|
||
`connect` 函数返回 `taos.TaosConnection` 实例。 在客户端多线程的场景下，推荐每个线程申请一个独立的连接实例，而不建议多线程共享一个连接。
|
||
|
||
:::
|
||
|
||
</TabItem>
|
||
<TabItem value="rest" label="REST 连接">
|
||
|
||
```python
|
||
{{#include docs/examples/python/connect_rest_examples.py:connect}}
|
||
```
|
||
|
||
`connect()` 函数的所有参数都是可选的关键字参数。下面是连接参数的具体说明：
|
||
|
||
- `url`： taosAdapter REST 服务的 URL。默认是 \<http://localhost:6041>。
|
||
- `user`： TDengine 用户名。默认是 root。
|
||
- `password`： TDengine 用户密码。默认是 taosdata。
|
||
- `timeout`: HTTP 请求超时时间。单位为秒。默认为 `socket._GLOBAL_DEFAULT_TIMEOUT`。 一般无需配置。
|
||
|
||
</TabItem>
|
||
|
||
<TabItem value="websocket" label="WebSocket 连接">
|
||
|
||
```python
|
||
{{#include docs/examples/python/connect_websocket_examples.py:connect}}
|
||
```
|
||
|
||
`connect()` 函数参数为连接 url，协议为 `taosws` 或 `ws`
|
||
|
||
</TabItem>
|
||
</Tabs>
|
||
|
||
### 配置参数的优先级
|
||
|
||
如果配置参数在参数和客户端配置文件中有重复，则参数的优先级由高到低分别如下：
|
||
|
||
1. 连接参数
|
||
2. 使用原生连接时，TDengine 客户端驱动的配置文件 taos.cfg
|
||
|
||
## 使用示例
|
||
|
||
### 创建数据库和表
|
||
|
||
<Tabs defaultValue="rest">
|
||
<TabItem value="native" label="原生连接">
|
||
|
||
```python
|
||
{{#include docs/examples/python/create_db_native.py}}
|
||
```
|
||
|
||
</TabItem>
|
||
|
||
<TabItem value="rest" label="REST 连接">
|
||
|
||
```python
|
||
{{#include docs/examples/python/create_db_rest.py}}
|
||
```
|
||
|
||
</TabItem>
|
||
|
||
<TabItem value="websocket" label="WebSocket 连接">
|
||
|
||
```python
|
||
{{#include docs/examples/python/create_db_ws.py}}
|
||
```
|
||
|
||
</TabItem>
|
||
</Tabs>
|
||
|
||
### 插入数据
|
||
|
||
<Tabs defaultValue="rest">
|
||
<TabItem value="native" label="原生连接">
|
||
|
||
```python
|
||
{{#include docs/examples/python/insert_native.py:insert}}
|
||
```
|
||
|
||
</TabItem>
|
||
|
||
<TabItem value="rest" label="REST 连接">
|
||
|
||
```python
|
||
{{#include docs/examples/python/insert_rest.py:insert}}
|
||
```
|
||
|
||
</TabItem>
|
||
|
||
<TabItem value="websocket" label="WebSocket 连接">
|
||
|
||
```python
|
||
{{#include docs/examples/python/insert_ws.py:insert}}
|
||
```
|
||
|
||
</TabItem>
|
||
</Tabs>
|
||
|
||
> NOW 为系统内部函数，默认为客户端所在计算机当前时间。
|
||
> `NOW + 1s` 代表客户端当前时间往后加 1 秒，数字后面代表时间单位：a(毫秒)，s(秒)，m(分)，h(小时)，d(天)，w(周)，n(月)，y(年)。
|
||
|
||
### 查询数据
|
||
|
||
<Tabs defaultValue="rest">
|
||
<TabItem value="native" label="原生连接">
|
||
|
||
`TaosConnection` 类的 `query` 方法可以用来查询数据，返回 `TaosResult` 类型的结果数据。
|
||
|
||
```python
|
||
{{#include docs/examples/python/insert_native.py:query}}
|
||
```
|
||
|
||
:::tip
|
||
查询结果只能获取一次。比如上面的示例中 `fetch_all()` 和 `fetch_all_into_dict()` 只能用一个。重复获取得到的结果为空列表。
|
||
:::
|
||
|
||
</TabItem>
|
||
|
||
<TabItem value="rest" label="REST 连接">
|
||
|
||
RestClient 类是对于 REST API 的直接封装。它只包含一个 sql() 方法用于执行任意 SQL 语句， 并返回执行结果。
|
||
|
||
```python
|
||
{{#include docs/examples/python/insert_rest.py:query}}
|
||
```
|
||
|
||
对于 `sql()` 方法更详细的介绍， 请参考 [RestClient](https://docs.taosdata.com/api/taospy/taosrest/restclient.html)。
|
||
|
||
</TabItem>
|
||
|
||
<TabItem value="websocket" label="WebSocket 连接">
|
||
|
||
`TaosConnection` 类的 `query` 方法可以用来查询数据，返回 `TaosResult` 类型的结果数据。
|
||
|
||
```python
|
||
{{#include docs/examples/python/insert_ws.py:query}}
|
||
```
|
||
|
||
</TabItem>
|
||
</Tabs>
|
||
|
||
### 执行带有 reqId 的 SQL
|
||
|
||
<RequestId />
|
||
|
||
<Tabs defaultValue="rest">
|
||
<TabItem value="native" label="原生连接">
|
||
|
||
类似上文介绍的使用方法，增加 `req_id` 参数。
|
||
|
||
```python
|
||
{{#include docs/examples/python/insert_native.py:req_id}}
|
||
```
|
||
|
||
</TabItem>
|
||
<TabItem value="rest" label="REST 连接">
|
||
|
||
类似上文介绍的使用方法，增加 `req_id` 参数。
|
||
|
||
```python
|
||
{{#include docs/examples/python/insert_rest.py:req_id}}
|
||
```
|
||
|
||
</TabItem>
|
||
|
||
<TabItem value="websocket" label="WebSocket 连接">
|
||
|
||
类似上文介绍的使用方法，增加 `req_id` 参数。
|
||
|
||
```python
|
||
{{#include docs/examples/python/insert_ws.py:req_id}}
|
||
```
|
||
|
||
</TabItem>
|
||
</Tabs>
|
||
|
||
### 通过参数绑定写入数据
|
||
|
||
TDengine 的 Python 连接器支持参数绑定风格的 Prepare API 方式写入数据，和大多数数据库类似，目前仅支持用 `?` 来代表待绑定的参数。
|
||
|
||
<Tabs>
|
||
<TabItem value="native" label="原生连接">
|
||
|
||
```python
|
||
{{#include docs/examples/python/stmt_native.py:stmt}}
|
||
```
|
||
</TabItem>
|
||
|
||
<TabItem value="websocket" label="WebSocket 连接">
|
||
|
||
```python
|
||
{{#include docs/examples/python/stmt_ws.py:stmt}}
|
||
```
|
||
</TabItem>
|
||
</Tabs>
|
||
|
||
### 无模式写入
|
||
|
||
连接器支持无模式写入功能。
|
||
|
||
<Tabs defaultValue="list">
|
||
<TabItem value="list" label="原生连接">
|
||
|
||
```python
|
||
{{#include docs/examples/python/schemaless_native.py}}
|
||
```
|
||
|
||
</TabItem>
|
||
|
||
<TabItem value="raw" label="WebSocket 连接">
|
||
|
||
```python
|
||
{{#include docs/examples/python/schemaless_ws.py}}
|
||
```
|
||
|
||
</TabItem>
|
||
</Tabs>
|
||
|
||
### 执行带有 reqId 的无模式写入
|
||
|
||
连接器的 `schemaless_insert` 和 `schemaless_insert_raw` 方法支持 `req_id` 可选参数，此 `req_id` 可用于请求链路追踪。
|
||
|
||
```python
|
||
conn.schemaless_insert(
|
||
lines=lineDemo,
|
||
protocol=taos.SmlProtocol.LINE_PROTOCOL,
|
||
precision=taos.SmlPrecision.NANO_SECONDS,
|
||
req_id=1,
|
||
)
|
||
```
|
||
|
||
### 数据订阅
|
||
|
||
连接器支持数据订阅功能，数据订阅功能请参考 [数据订阅文档](../../develop/tmq/)。
|
||
|
||
#### 创建 Topic
|
||
|
||
```python
|
||
{{#include docs/examples/python/tmq_native.py:create_topic}}
|
||
```
|
||
|
||
#### 创建 Consumer
|
||
|
||
```python
|
||
{{#include docs/examples/python/tmq_native.py:create_consumer}}
|
||
```
|
||
|
||
#### 订阅 topics
|
||
|
||
```python
|
||
{{#include docs/examples/python/tmq_native.py:subscribe}}
|
||
```
|
||
|
||
#### 消费数据
|
||
|
||
```python
|
||
{{#include docs/examples/python/tmq_native.py:consume}}
|
||
```
|
||
|
||
#### 获取消费进度
|
||
|
||
Consumer API 的 `assignment` 方法用于获取 Consumer 订阅的所有 topic 的消费进度，返回结果类型为 TopicPartition 列表。
|
||
|
||
```python
|
||
{{#include docs/examples/python/tmq_native.py:assignment}}
|
||
```
|
||
|
||
Consumer API 的 `seek` 方法用于重置 Consumer 的消费进度到指定位置，方法参数类型为 TopicPartition。
|
||
|
||
```python
|
||
{{#include docs/examples/python/tmq_native.py:consume}}
|
||
```
|
||
|
||
#### 关闭订阅
|
||
|
||
消费结束后，应当取消订阅，并关闭 Consumer。
|
||
|
||
```python
|
||
{{#include docs/examples/python/tmq_native.py:unsubscribe}}
|
||
```
|
||
|
||
#### 完整示例
|
||
|
||
```python
|
||
{{#include docs/examples/python/tmq_native.py}}
|
||
```
|
||
|
||
### 更多示例程序
|
||
|
||
| 示例程序链接 | 示例程序内容 |
|
||
| ------------------------------------------------------------------------------------------------------------- | ----------------------- |
|
||
| [bind_multi.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/bind-multi.py) | 参数绑定， 一次绑定多行 |
|
||
| [bind_row.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/bind-row.py) | 参数绑定，一次绑定一行 |
|
||
| [insert_lines.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/insert-lines.py) | InfluxDB 行协议写入 |
|
||
| [json_tag.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/json-tag.py) | 使用 JSON 类型的标签 |
|
||
| [tmq_consumer.py](https://github.com/taosdata/taos-connector-python/blob/main/examples/tmq_consumer.py) | tmq 订阅 |
|
||
|
||
## 其它说明
|
||
|
||
### 关于纳秒 (nanosecond)
|
||
|
||
由于目前 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/
|
||
|
||
## 重要更新
|
||
|
||
[**Release Notes**](https://github.com/taosdata/taos-connector-python/releases)
|
||
|
||
## API 参考
|
||
|
||
- [taos](https://docs.taosdata.com/api/taospy/taos/)
|
||
- [taosrest](https://docs.taosdata.com/api/taospy/taosrest)
|
||
|
||
## 常见问题
|
||
|
||
欢迎[提问或报告问题](https://github.com/taosdata/taos-connector-python/issues)。
|