TDengine Python Connector
taospy
是 TDengine 的官方 Python 连接器。taospy
提供了丰富的 API, 使得 Python 应用可以很方便地使用 TDengine。
Python 连接器的源码托管在 GitHub。
连接方式
taospy
主要提供三种形式的连接器。一般我们推荐使用 Websocket 连接。
- 原生连接,对应
taospy
包的taos
模块。通过 TDengine 客户端驱动程序(taosc)原生连接 TDengine 实例,支持数据写入、查询、数据订阅、schemaless 接口和参数绑定接口等功能。 - REST 连接,对应
taospy
包的taosrest
模块。通过 taosAdapter 提供的 HTTP 接口连接 TDengine 实例,不支持 schemaless 和数据订阅等特性。 - Websocket 连接,对应
taos-ws-py
包,可以选装。通过 taosAdapter 提供的 Websocket 接口连接 TDengine 实例,WebSocket 连接实现的功能集合和原生连接有少量不同。
连接方式的详细介绍请参考:连接器建立连接的方式
除了对原生接口和 REST 接口的封装,taospy
还提供了符合 Python 数据访问规范(PEP 249) 的编程接口。这使得 taospy
和很多第三方工具集成变得简单,比如 SQLAlchemy 和 pandas。
使用客户端驱动提供的原生接口直接与服务端建立的连接的方式下文中称为“原生连接”;使用 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 ) 2. query 性能提升(感谢贡献者hadrianl) |
2.7.9 | 数据订阅支持获取消费进度和重置消费进度 |
2.7.8 | 新增 execute_many |
Python Websocket Connector 版本 | 主要变化 |
---|---|
0.2.9 | 已知问题修复 |
0.2.5 | 1. 数据订阅支持获取消费进度和重置消费进度 2. 支持 schemaless 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 错误和异常文档。
Python Connector 的所有数据库操作如果出现异常,都会直接抛出来。由应用程序负责异常处理。比如:
import taos
try:
conn = taos.connect()
conn.execute("CREATE TABLE 123") # wrong sql
except taos.Error as e:
print(e)
print("exception class: ", e.__class__.__name__)
print("error number:", e.errno)
print("error message:", e.msg)
except BaseException as other:
print("exception occur")
print(other)
# output:
# [0x0216]: syntax error near 'Incomplete SQL statement'
# exception class: ProgrammingError
# error number: -2147483114
# error message: syntax error near 'Incomplete SQL statement'
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 |
安装步骤
安装前准备
- 安装 Python。新近版本 taospy 包要求 Python 3.6.2+。早期版本 taospy 包要求 Python 3.7+。taos-ws-py 包要求 Python 3.7+。如果系统上还没有 Python 可参考 Python BeginnersGuide 安装。
- 安装 pip。大部分情况下 Python 的安装包都自带了 pip 工具, 如果没有请参考 pip documentation 安装。
- 如果使用原生连接,还需安装客户端驱动。客户端软件包含了 TDengine 客户端动态链接库(libtaos.so 或 taos.dll) 和 TDengine CLI。
使用 pip 安装
卸载旧版本
如果以前安装过旧版本的 Python 连接器, 请提前卸载。
pip3 uninstall taos taospy
较早的 TDengine 客户端软件包含了 Python 连接器。如果从客户端软件的安装目录安装了 Python 连接器,那么对应的 Python 包名是 taos
。 所以上述卸载命令包含了 taos
, 不存在也没关系。
安装 taospy
- 从 PyPI 安装
- 从 GitHub 安装
安装最新版本
pip3 install taospy
也可以指定某个特定版本安装。
pip3 install taospy==2.3.0
pip3 install git+https://github.com/taosdata/taos-connector-python.git
安装 taos-ws-py
(可选)
taos-ws-py 包提供了通过 WebSocket 连接 TDengine 的能力,可选安装 taos-ws-py 以获得 WebSocket 连接 TDengine 的能力。
和 taospy 同时安装
pip3 install taospy[ws]
单独安装
pip3 install taos-ws-py
安装验证
- 原生连接
- REST 连接
- WebSocket 连接
对于原生连接,需要验证客户端驱动和 Python 连接器本身是否都正确安装。如果能成功导入 taos
模块,则说明已经正确安装了客户端驱动和 Python 连接器。可在 Python 交互式 Shell 中输入:
import taos
对于 REST 连接,只需验证是否能成功导入 taosrest
模块。可在 Python 交互式 Shell 中输入:
import taosrest
对于 WebSocket 连接,只需验证是否能成功导入 taosws
模块。可在 Python 交互式 Shell 中输入:
import taosws
如果系统上有多个版本的 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 集群的连通性。
- 原生连接
- REST 连接
- WebSocket 连接
请确保 TDengine 集群已经启动, 且集群中机器的 FQDN (如果启动的是单机版,FQDN 默认为 hostname)在本机能够解析, 可用 ping
命令进行测试:
ping <FQDN>
然后测试用 TDengine CLI 能否正常连接集群:
taos -h <FQDN> -p <PORT>
上面的 FQDN 可以为集群中任意一个 dnode 的 FQDN, PORT 为这个 dnode 对应的 serverPort。
对于 REST 连接, 除了确保集群已经启动,还要确保 taosAdapter 组件已经启动。可以使用如下 curl 命令测试:
curl -u root:taosdata http://<FQDN>:<PORT>/rest/sql -d "select server_version()"
上面的 FQDN 为运行 taosAdapter 的机器的 FQDN, PORT 为 taosAdapter 配置的监听端口, 默认为 6041。 如果测试成功,会输出服务器版本信息,比如:
{
"code": 0,
"column_meta": [
[
"server_version()",
"VARCHAR",
7
]
],
"data": [
[
"3.0.0.0"
]
],
"rows": 1
}
对于 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。 如果测试成功,会输出服务器版本信息,比如:
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}
指定 Host 和 Properties 获取连接
以下示例代码假设 TDengine 安装在本机, 且 FQDN 和 serverPort 都使用了默认配置。
- 原生连接
- REST 连接
- WebSocket 连接
import taos
conn = taos.connect(
host="localhost",
user="root",
password="taosdata",
database="test",
port=6030,
config="/etc/taos", # for windows the default value is C:\TDengine\cfg
timezone="Asia/Shanghai",
) # default your host's timezone
server_version = conn.server_info
print("server_version", server_version)
client_version = conn.client_info
print("client_version", client_version) # 3.0.0.0
conn.close()
# possible output:
# 3.0.0.0
# 3.0.0.0
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 对象时使用的时区。默认为本地时区。
config
和 timezone
都是进程级别的配置。建议一个进程建立的所有连接都使用相同的参数值。否则可能产生无法预知的错误。
connect
函数返回 taos.TaosConnection
实例。 在客户端多线程的场景下,推荐每个线程申请一个独立的连接实例,而不建议多线程共享一个连接。
from taosrest import connect, TaosRestConnection, TaosRestCursor
conn = connect(url="http://localhost:6041",
user="root",
password="taosdata",
timeout=30)
connect()
函数的所有参数都是可选的关键字参数。下面是连接参数的具体说明:
url
: taosAdapter REST 服务的 URL。默认是 <http://localhost:6041>。user
: TDengine 用户名。默认是 root。password
: TDengine 用户密码。默认是 taosdata。timeout
: HTTP 请求超时时间。单位为秒。默认为socket._GLOBAL_DEFAULT_TIMEOUT
。 一般无需配置。
import taosws
conn = taosws.connect("taosws://root:taosdata@localhost:6041")
connect()
函数参数为连接 url,协议为 taosws
或 ws
配置参数的优先级
如果配置参数在参数和客户端配置文件中有重复,则参数的优先级由高到低分别如下:
- 连接参数
- 使用原生连接时,TDengine 客户端驱动的配置文件 taos.cfg
使用示例
创建数据库和表
- 原生连接
- REST 连接
- WebSocket 连接
import taos
conn = taos.connect(
host="localhost",
user="root",
password="taosdata",
port=6030,
)
db = "power"
conn.execute(f"DROP DATABASE IF EXISTS {db}")
conn.execute(f"CREATE DATABASE {db}")
# change database. same as execute "USE db"
conn.select_db(db)
# create super table
conn.execute(
"CREATE TABLE `meters` (`ts` TIMESTAMP, `current` FLOAT, `voltage` INT, `phase` FLOAT) TAGS (`groupid` INT, `location` BINARY(16))"
)
# create table
conn.execute("CREATE TABLE `d0` USING `meters` TAGS(0, 'Los Angles')")
conn.close()
import taosrest
conn = taosrest.connect(url="http://localhost:6041")
db = "power"
conn.execute(f"DROP DATABASE IF EXISTS {db}")
conn.execute(f"CREATE DATABASE {db}")
# create super table
conn.execute(
f"CREATE TABLE `{db}`.`meters` (`ts` TIMESTAMP, `current` FLOAT, `voltage` INT, `phase` FLOAT) TAGS (`groupid` INT, `location` BINARY(16))"
)
# create table
conn.execute(f"CREATE TABLE `{db}`.`d0` USING `{db}`.`meters` TAGS(0, 'Los Angles')")
conn.close()
import taosws
dsn = "taosws://root:taosdata@localhost:6041"
conn = taosws.connect(dsn)
db = "power"
conn.execute(f"DROP DATABASE IF EXISTS {db}")
conn.execute(f"CREATE DATABASE {db}")
# change database.
conn.execute(f"USE {db}")
# create super table
conn.execute(
"CREATE TABLE `meters` (`ts` TIMESTAMP, `current` FLOAT, `voltage` INT, `phase` FLOAT) TAGS (`groupid` INT, `location` BINARY(16))"
)
# create table
conn.execute("CREATE TABLE `d0` USING `meters` TAGS(0, 'Los Angles')")
conn.close()