Python SDK

更新时间：2026-07-24

本文介绍如何使用 Python SDK 连接 TSDB 专享版，并完成数据写入和查询。

环境准备

使用 SDK 前，请准备一个 Python 项目，并完成 SDK 使用说明中的连接准备工作。建议使用独立的虚拟环境安装依赖。

安装 SDK

本文示例使用 influxdb3-python 0.20.0。

以下命令适用于 Linux / macOS；Windows 上使用 .venv\Scripts\activate 激活虚拟环境。

                Bash
                
                python -m venv .venv
source .venv/bin/activate
python -m pip install 'influxdb3-python==0.20.0'

配置连接信息

示例通过以下环境变量读取连接信息：

环境变量	说明
`TSDB_HOST_URL`	由集群详情页显示的访问地址和端口组成的完整 URL，例如 `http://<访问地址>:<端口>`
`TSDB_DATABASE_NAME`	目标 Database 名称
`TSDB_AUTH_TOKEN`	具有目标 Database 读写权限的业务访问令牌

写入和查询数据

以下示例初始化客户端，写入一条 Line Protocol 数据，然后使用 SQL 查询刚写入的数据：

                Python
                
            

                import os
import time

from influxdb_client_3 import InfluxDBClient3


client = InfluxDBClient3(
    host=os.environ["TSDB_HOST_URL"],
    token=os.environ["TSDB_AUTH_TOKEN"],
    database=os.environ["TSDB_DATABASE_NAME"],
    auth_scheme="Bearer",
    write_use_v2_api=False,
)

try:
    client.write(record="cpu,host=server01 usage=42.5")

    # 首次写入创建 Table 后，等待新表可查询。
    time.sleep(5)

    table = client.query(
        "SELECT time, host, usage FROM cpu "
        "WHERE host = 'server01' ORDER BY time DESC LIMIT 1"
    )
    for row in table.to_pylist():
        print(row)
finally:
    client.close()
            

配置说明

write_use_v2_api=False 用于启用 V3 写入接口，复制示例时请保留该配置。
写入和查询使用同一个 TSDB_HOST_URL，无需手动拼接 API 路径。
示例首次写入 cpu 时会自动创建 Table，因此在写入后等待 5 秒。新表通常在约 5 秒后可以查询，实际时间可能受集群运行状态影响。该等待只适用于首次建表；向已有 Table 写入不受影响。
查询结果以 Arrow 数据结构返回。示例使用 to_pylist() 转换结果；处理大量数据时，建议根据业务需要分批读取。
使用完成后调用 client.close() 释放 HTTP 和 Flight 连接。
SDK 只用于数据写入和查询。管理 Database、Table、Retention 或业务访问令牌时，请使用 CLI 工具或资源管理 API。

评价此篇文章

有帮助没帮助

百度智能云

时序时空数据库 TSDB