IoTDB Python原生接口全攻略：从基础读写到高级实战

IoTDB Python原生接口全攻略：从基础读写到高级实战

做IoTDB时序数据开发的小伙伴，用Python对接肯定是高频需求，IoTDB官方的Python原生接口封装得特别友好，不管是基础的数据库连接、数据读写，还是高级的连接池管理、SSL加密、Pandas适配，全都能实现。今天就从环境搭建、基础使用，到DDL/DML操作、高级特性，再到测试和DBAPI适配，把IoTDB Python原生接口的用法一次性讲透，新手也能直接上手开发。

一、前期准备：安装依赖与包

用IoTDB Python原生接口前，得先装好两个核心依赖，一步到位不踩坑：

1. 安装thrift框架（要求版本≥0.13），是IoTDB底层的通信依赖
2. 安装IoTDB Python官方包（建议版本≥2.0），提供所有原生操作接口

直接用pip命令安装就行，执行以下两行：

pip3 install thrift>=0.13
pip3 install apache-iotdb>=2.0

二、快速入门：基础Session连接与使用

和Java接口类似，Python操作IoTDB的核心也是Session对象，所有数据库操作都基于它展开。先看一个最简的连接示例，几行代码就能完成建连、查时区、断连的全流程：

from iotdb.Session import Session

# 配置连接信息
ip = "127.0.0.1"
port_ = 6667  # 注意这里可以是int，也可以是str
username_ = "root"
password_ = "root"

# 初始化Session并建连
session = Session(ip, port_, username_, password_)
session.open(False)  # False表示不开启RPC压缩

# 简单操作：获取当前时区
zone = session.get_time_zone()
print(f"IoTDB当前时区：{zone}")

# 关闭连接，释放资源
session.close()

2.1 Session两种初始化方式

实际开发中，分单节点初始化 和多节点初始化两种场景，多节点模式能实现容灾重试，推荐生产环境使用：

（1）单节点初始化（基础版）

可配置拉取大小、时区、重定向等参数，按需调整：

session = Session(
    ip="127.0.0.1",
    port=6667,
    user="root",
    password="root",
    fetch_size=1024,  # 查询结果默认批量拉取大小
    zone_id="UTC+8",   # 会话时区
    enable_redirection=True  # 是否启用重定向
)

（2）多节点初始化（容灾版）

传入节点URL列表，当一个节点宕机时，会自动连接其他节点，提升可用性：

session = Session.init_from_node_urls(
    node_urls=["127.0.0.1:6667", "127.0.0.1:6668", "127.0.0.1:6669"],
    user="root",
    password="root",
    fetch_size=1024,
    zone_id="UTC+8",
    enable_redirection=True
)

2.2 Session核心基础操作

• 开启连接：session.open(enable_rpc_compression=False)，注意RPC压缩开关要和服务端保持一致，否则连接失败
• 关闭连接：session.close()，使用完必须调用，释放服务端连接资源

三、高效管理：SessionPool连接池使用

单Session在多线程场景下效率低，还容易出现连接复用问题，官方提供了SessionPool连接池来管理Session，自动实现连接复用，无需手动关注连接创建和销毁。

3.1 创建SessionPool

支持单节点和多节点两种配置方式，核心配置连接池最大大小、阻塞超时时间：

from iotdb.SessionPool import PoolConfig, SessionPool

# 方式1：单节点配置PoolConfig
pool_config = PoolConfig(
    host="127.0.0.1",
    port=6667,
    user_name="root",
    password="root",
    fetch_size=1024,
    time_zone="UTC+8",
    max_retry=3  # 连接失败重试次数
)

# 方式2：多节点配置PoolConfig
# pool_config = PoolConfig(
#     node_urls=["127.0.0.1:6667", "127.0.0.1:6668"],
#     user_name="root",
#     password="root",
#     fetch_size=1024,
#     time_zone="UTC+8",
#     max_retry=3
# )

# 初始化连接池：最大连接数5，获取连接阻塞超时3000毫秒
max_pool_size = 5
wait_timeout_in_ms = 3000
session_pool = SessionPool(pool_config, max_pool_size, wait_timeout_in_ms)

3.2 SessionPool核心操作

使用连接池的核心是获取连接-执行操作-归还连接，三步流程，用完必须归还，否则会造成连接泄漏：

# 1. 从连接池获取Session
session = session_pool.get_session()

# 2. 执行数据库操作（示例：创建存储组、创建时间序列）
STORAGE_GROUP_NAME = "root.sg1"
TIMESERIES_PATH = "root.sg1.d1.s1"
from iotdb.utils.DataType import TSDataType
from iotdb.utils.Encoding import TSEncoding
from iotdb.utils.Compressor import Compressor

session.set_storage_group(STORAGE_GROUP_NAME)
session.create_time_series(
    TIMESERIES_PATH, 
    TSDataType.BOOLEAN, 
    TSEncoding.PLAIN, 
    Compressor.SNAPPY
)

# 3. 使用完归还Session到连接池
session_pool.put_back(session)

# 4. 关闭连接池（程序结束时执行），自动关闭所有管理的Session
session_pool.close()

四、安全通信：SSL加密连接配置

生产环境中，为了保证数据传输安全，需要开启SSL加密连接，分为服务端证书配置 和Python客户端配置两步，缺一不可。

4.1 服务端配置

在IoTDB的conf/iotdb-system.properties配置文件中，添加/修改以下配置，指定证书路径和密码：

enable_thrift_ssl=true
key_store_path=/path/to/your/server_keystore.jks
key_store_pwd=your_keystore_password

4.2 Python客户端配置

初始化Session/SessionPool时，设置use_ssl=True，并指定服务端证书路径（crt/pem格式均可），提供两个实战示例：

示例1：SSL连接+单Session

from iotdb.Session import Session

ip = "127.0.0.1"
port_ = 6667
username_ = "root"
password_ = "root"
# 开启SSL并指定证书路径
use_ssl = True
ca_certs = "/path/to/your/server.crt"  # 或ca_certs = "/path/to/ca_cert.pem"

def get_data():
    session = Session(
        ip, port_, username_, password_, 
        use_ssl=use_ssl, ca_certs=ca_certs
    )
    session.open(False)
    # 执行查询并转换为Pandas DataFrame
    result = session.execute_query_statement("select * from root.eg.etth")
    df = result.todf()
    df.rename(columns={"Time": "date"}, inplace=True)
    session.close()
    return df

if __name__ == "__main__":
    df = get_data()
    print(df)

示例2：SSL连接+SessionPool

from iotdb.SessionPool import PoolConfig, SessionPool

ip = "127.0.0.1"
port_ = 6667
username_ = "root"
password_ = "root"
use_ssl = True
ca_certs = "/path/to/your/server.crt"

def get_data2():
    # 配置带SSL的PoolConfig
    pool_config = PoolConfig(
        host=ip,
        port=port_,
        user_name=username_,
        password=password_,
        fetch_size=1024,
        time_zone="UTC+8",
        max_retry=3,
        use_ssl=use_ssl,
        ca_certs=ca_certs,
    )
    session_pool = SessionPool(pool_config, 5, 3000)
    # 获取并使用Session
    session = session_pool.get_session()
    result = session.execute_query_statement("select * from root.eg.etth")
    df = result.todf()
    df.rename(columns={"Time": "date"}, inplace=True)
    # 归还并关闭
    session_pool.put_back(session)
    session_pool.close()
    return df

if __name__ == "__main__":
    df = get_data2()
    print(df)

五、核心操作：DDL数据定义接口

DDL操作主要是对存储组（Database）和时间序列的管理，包括创建、删除、检测存在性等，是操作IoTDB的基础，所有接口都通过Session对象调用。

5.1 存储组管理

存储组是IoTDB的一级数据组织单位，先创建存储组才能创建时间序列：

# 设置/创建存储组
session.set_storage_group("root.sg1")

# 删除单个存储组
session.delete_storage_group("root.sg1")

# 批量删除存储组
session.delete_storage_groups(["root.sg1", "root.sg2"])

5.2 时间序列管理

支持单/批量创建普通时间序列、对齐时间序列，以及删除、检测存在性，注意对齐时间序列目前暂不支持传感器别名。

from iotdb.utils.DataType import TSDataType
from iotdb.utils.Encoding import TSEncoding
from iotdb.utils.Compressor import Compressor

# 1. 创建单个普通时间序列
session.create_time_series(
    ts_path="root.sg1.d1.s1",
    data_type=TSDataType.INT64,
    encoding=TSEncoding.RLE,
    compressor=Compressor.SNAPPY,
    props=None,  # 扩展属性
    tags={"device": "d1"},  # 标签
    attributes={"unit": "℃"},  # 属性
    alias=None  # 别名
)

# 2. 批量创建普通时间序列
session.create_multi_time_series(
    ts_path_lst=["root.sg1.d1.s1", "root.sg1.d1.s2"],
    data_type_lst=[TSDataType.INT64, TSDataType.FLOAT],
    encoding_lst=[TSEncoding.RLE, TSEncoding.PLAIN],
    compressor_lst=[Compressor.SNAPPY, Compressor.LZ4]
)

# 3. 创建对齐时间序列
session.create_aligned_time_series(
    device_id="root.sg1.d1",
    measurements_lst=["s1", "s2", "s3"],
    data_type_lst=[TSDataType.INT64, TSDataType.FLOAT, TSDataType.BOOLEAN],
    encoding_lst=[TSEncoding.RLE, TSEncoding.PLAIN, TSEncoding.RLE],
    compressor_lst=[Compressor.SNAPPY, Compressor.LZ4, Compressor.SNAPPY]
)

# 4. 批量删除时间序列
session.delete_time_series(["root.sg1.d1.s1", "root.sg1.d1.s2"])

# 5. 检测时间序列是否存在
is_exist = session.check_time_series_exists("root.sg1.d1.s1")
print(f"时间序列是否存在：{is_exist}")

六、核心操作：DML数据操作接口

DML操作是IoTDB的核心，主要是数据写入 ，官方推荐使用insert_tablet方式写入，效率远高于单条插入，还支持空值写入。Python接口提供了普通Tablet 和Numpy Tablet两种实现，Numpy Tablet针对数值型数据做了优化，内存占用更低、写入速度更快。

6.1 推荐方式：Tablet写入

（1）普通Tablet写入（支持所有数据类型，兼容空值）

Tablet是一个设备的若干行数据块，每一行的测点列都相同，适合批量写入单设备多时间戳数据：

from iotdb.utils.Tablet import Tablet
from iotdb.utils.DataType import TSDataType

# 配置设备、测点、数据类型
device_id = "root.sg1.d1"
measurements_ = ["s1", "s2", "s3", "s4", "s5", "s6"]
data_types_ = [TSDataType.BOOLEAN, TSDataType.INT32, TSDataType.INT64, TSDataType.FLOAT, TSDataType.DOUBLE, TSDataType.TEXT]

# 示例1：写入非空数据
values_ = [
    [False, 10, 11, 1.1, 10011.1, "test01"],
    [True, 100, 11111, 1.25, 101.0, "test02"],
    [False, 100, 1, 188.1, 688.25, "test03"],
    [True, 0, 0, 0, 6.25, "test04"],
]
timestamps_ = [1, 2, 3, 4]
tablet_ = Tablet(device_id, measurements_, data_types_, values_, timestamps_)
session.insert_tablet(tablet_)

# 示例2：写入含空值数据（None表示空值）
values_ = [
    [None, 10, 11, 1.1, 10011.1, "test01"],
    [True, None, 11111, 1.25, 101.0, "test02"],
    [False, 100, None, 188.1, 688.25, "test03"],
    [True, 0, 0, 0, None, None],
]
timestamps_ = [16, 17, 18, 19]
tablet_ = Tablet(device_id, measurements_, data_types_, values_, timestamps_)
session.insert_tablet(tablet_)

（2）Numpy Tablet写入（数值型数据优选，效率更高）

使用numpy.ndarray存储数据，大幅降低内存占用和序列化耗时，推荐数值型数据使用，支持大端类型（建议显式指定，客户端也会自动做大小端转换）：

import numpy as np
from iotdb.utils.NumpyTablet import NumpyTablet
from iotdb.utils.BitMap import BitMap
from iotdb.utils.DataType import TSDataType

device_id = "root.sg1.d1"
measurements_ = ["s1", "s2", "s3", "s4", "s5", "s6"]
data_types_ = [TSDataType.BOOLEAN, TSDataType.INT32, TSDataType.INT64, TSDataType.FLOAT, TSDataType.DOUBLE, TSDataType.TEXT]

# 1. 写入非空Numpy Tablet
np_values_ = [
    np.array([False, True, False, True], TSDataType.BOOLEAN.np_dtype()),
    np.array([10, 100, 100, 0], TSDataType.INT32.np_dtype()),
    np.array([11, 11111, 1, 0], TSDataType.INT64.np_dtype()),
    np.array([1.1, 1.25, 188.1, 0], TSDataType.FLOAT.np_dtype()),
    np.array([10011.1, 101.0, 688.25, 6.25], TSDataType.DOUBLE.np_dtype()),
    np.array(["test01", "test02", "test03", "test04"], TSDataType.TEXT.np_dtype()),
]
np_timestamps_ = np.array([1, 2, 3, 4], TSDataType.INT64.np_dtype())
np_tablet_ = NumpyTablet(device_id, measurements_, data_types_, np_values_, np_timestamps_)
session.insert_tablet(np_tablet_)

# 2. 写入含空值的Numpy Tablet（用BitMap标记空值位置）
np_values_ = [
    np.array([False, True, False, True], TSDataType.BOOLEAN.np_dtype()),
    np.array([10, 100, 100, 0], TSDataType.INT32.np_dtype()),
    np.array([11, 11111, 1, 0], TSDataType.INT64.np_dtype()),
    np.array([1.1, 1.25, 188.1, 0], TSDataType.FLOAT.np_dtype()),
    np.array([10011.1, 101.0, 688.25, 6.25], TSDataType.DOUBLE.np_dtype()),
    np.array(["test01", "test02", "test03", "test04"], TSDataType.TEXT.np_dtype()),
]
np_timestamps_ = np.array([98, 99, 100, 101], TSDataType.INT64.np_dtype())
# 初始化BitMap，标记每个测点的空值位置
np_bitmaps_ = []
for i in range(len(measurements_)):
    np_bitmaps_.append(BitMap(len(np_timestamps_)))
np_bitmaps_[0].mark(0)  # s1的第0行是空值
np_bitmaps_[1].mark(1)  # s2的第1行是空值
np_bitmaps_[2].mark(2)  # s3的第2行是空值
np_bitmaps_[4].mark(3)  # s5的第3行是空值
np_bitmaps_[5].mark(3)  # s6的第3行是空值
# 插入含空值的Numpy Tablet
np_tablet_with_none = NumpyTablet(device_id, measurements_, data_types_, np_values_, np_timestamps_, np_bitmaps_)
session.insert_tablet(np_tablet_with_none)

（3）批量插入多个Tablet

适合同时写入多个设备的Tablet数据，一次调用完成批量操作：

# 构建多个Tablet对象，加入列表
tablet_lst = [tablet1, tablet2, np_tablet1]
# 批量插入
session.insert_tablets(tablet_lst)

6.2 基础方式：Record写入

Record是一个设备一个时间戳下的多个测点数据，适合单条/少量数据写入，效率低于Tablet，了解即可：

# 1. 插入单个Record
session.insert_record(
    device_id="root.sg1.d1",
    timestamp=100,
    measurements_=["s1", "s2"],
    data_types_=[TSDataType.INT64, TSDataType.FLOAT],
    values_=[100, 25.5]
)

# 2. 批量插入多个Record（多设备）
session.insert_records(
    device_ids_=["root.sg1.d1", "root.sg1.d2"],
    time_list_=[101, 102],
    measurements_list_=[["s1", "s2"], ["s1", "s2"]],
    data_type_list_=[[TSDataType.INT64, TSDataType.FLOAT], [TSDataType.INT64, TSDataType.FLOAT]],
    values_list_=[[200, 30.0], [300, 40.5]]
)

# 3. 插入单设备的多个Record
session.insert_records_of_one_device(
    device_id="root.sg1.d1",
    time_list=[103, 104],
    measurements_list=[["s1", "s2"], ["s1", "s2"]],
    data_types_list=[[TSDataType.INT64, TSDataType.FLOAT], [TSDataType.INT64, TSDataType.FLOAT]],
    values_list=[[400, 50.0], [500, 60.5]]
)

6.3 特殊方式：带类型推断的写入

如果数据都是字符串类型，可以使用insert_str_record接口，服务端会自动根据字符串值推断数据类型（如"true"→BOOLEAN，"3.2"→FLOAT），注意：类型推断会有额外耗时，效率低于普通写入：

# 字符串值自动推断类型
session.insert_str_record(
    device_id="root.sg1.d1",
    timestamp=200,
    measurements=["s1", "s2", "s3"],
    string_values=["true", "100", "3.14"]
)

6.4 对齐时间序列写入

对齐时间序列的写入接口都是insert_aligned_xxx格式，用法和普通时间序列一致，仅接口名不同，举例：

# 插入对齐Tablet
session.insert_aligned_tablet(aligned_tablet)
# 插入单个对齐Record
session.insert_aligned_record(device_id, timestamp, measurements_, data_types_, values_)

七、灵活查询：IoTDB-SQL接口

Python原生接口支持直接执行IoTDB-SQL语句，分为查询语句 和非查询语句，查询结果可直接转换为Pandas DataFrame，适配数据分析场景。

# 1. 执行查询语句（返回结果集）
result = session.execute_query_statement("SELECT ** FROM root.sg1.d1 LIMIT 10")
# 转换为Pandas DataFrame（数据分析优选）
df = result.todf()
print(df)

# 2. 执行非查询语句（DDL/DML，无返回结果）
session.execute_non_query_statement("SET STORAGE GROUP TO root.sg2")
session.execute_non_query_statement("CREATE TIMESERIES root.sg2.d1.s1 WITH DATATYPE=INT64, ENCODING=RLE")

# 3. 通用执行语句（自动适配查询/非查询）
session.execute_statement("DELETE TIMESERIES root.sg2.d1.s1")

八、高级特性：元数据模板接口

IoTDB的元数据模板可以快速批量创建相同结构的时间序列，避免重复配置，Python接口支持模板的创建、修改、挂载、卸载、查询、删除全流程操作。

8.1 构建并创建元数据模板

先创建Template对象，添加测点节点（MeasurementNode），再调用创建接口：

from iotdb.utils.Template import Template, MeasurementNode
from iotdb.utils.DataType import TSDataType
from iotdb.utils.Encoding import TSEncoding
from iotdb.utils.Compressor import Compressor

# 1. 构建模板（share_time=True表示共享时间戳，即对齐时间序列）
template_name = "device_template"
template = Template(name=template_name, share_time=True)

# 2. 添加测点节点
m_node_s1 = MeasurementNode("s1", TSDataType.INT64, TSEncoding.RLE, Compressor.SNAPPY)
m_node_s2 = MeasurementNode("s2", TSDataType.FLOAT, TSEncoding.PLAIN, Compressor.LZ4)
m_node_s3 = MeasurementNode("s3", TSDataType.BOOLEAN, TSEncoding.RLE, Compressor.SNAPPY)
template.add_template(m_node_s1)
template.add_template(m_node_s2)
template.add_template(m_node_s3)

# 3. 创建元数据模板
session.create_schema_template(template)

8.2 模板修改、挂载与卸载

# 1. 给模板添加测点
session.add_measurements_in_template(
    template_name="device_template",
    measurements_path=["s4"],
    data_types=[TSDataType.DOUBLE],
    encodings=[TSEncoding.PLAIN],
    compressors=[Compressor.LZ4],
    is_aligned=True  # 是否为对齐测点
)

# 2. 从模板删除测点
session.delete_node_in_template(template_name="device_template", path="s4")

# 3. 挂载模板到指定路径（路径下的设备将使用该模板）
session.set_schema_template(template_name="device_template", prefix_path="root.sg1")

# 4. 从指定路径卸载模板
session.unset_schema_template(template_name="device_template", prefix_path="root.sg1")

8.3 模板查询与删除

# 1. 查看所有模板
all_templates = session.show_all_templates()
print(all_templates)

# 2. 查看模板中的测点数量
count = session.count_measurements_in_template("device_template")
print(f"模板测点数量：{count}")

# 3. 查看模板下的所有测点
measurements = session.show_measurements_in_template("device_template")
print(measurements)

# 4. 删除模板（**注意：已挂载的模板无法删除**）
session.drop_schema_template("device_template")

九、数据分析友好：Pandas完美支持

IoTDB Python接口对Pandas做了深度适配，查询结果集SessionDataSet提供了todf()方法，可一键将查询结果转换为Pandas DataFrame，直接进行数据分析、可视化，这也是Python对接IoTDB的一大优势：

from iotdb.Session import Session
import pandas as pd

session = Session("127.0.0.1", 6667, "root", "root")
session.open(False)

# 执行查询
result = session.execute_query_statement("SELECT ** FROM root.sg1.d1")
# 一键转换为DataFrame
df = result.todf()

# 后续可直接进行Pandas操作
print(df.head())  # 查看前5行
print(df.describe())  # 统计分析
df.plot(x="Time", y="s1")  # 绘图

session.close()

十、测试便捷：IoTDB Testcontainer

Python客户端基于testcontainers库提供了容器化测试支持，无需手动部署IoTDB，可在Docker容器中快速启动/停止IoTDB实例，适合单元测试和集成测试。

10.1 安装依赖

pip3 install testcontainers

10.2 实战示例

通过IoTDBContainer快速启动IoTDB，支持指定版本：

import unittest
from iotdb.Session import Session
from testcontainers.iotdb import IoTDBContainer

class MyTestCase(unittest.TestCase):
    def test_something(self):
        # 启动IoTDB容器（默认最新版，指定版本：IoTDBContainer("apache/iotdb:0.12.0")）
        with IoTDBContainer() as c:
            # 连接容器中的IoTDB
            session = Session("localhost", c.get_exposed_port(6667), "root", "root")
            session.open(False)
            # 执行测试操作
            result = session.execute_query_statement("SHOW TIMESERIES")
            print(result)
            session.close()

if __name__ == '__main__':
    unittest.main()

十一、通用适配：IoTDB DBAPI（遵循Python DB API 2.0）

IoTDB提供了遵循Python DB API 2.0规范的通用接口，适配Python生态的通用数据库操作方式，支持普通SQL执行、带参数SQL、批量执行SQL，适合习惯通用DBAPI的开发者。

11.1 基础使用示例

from iotdb.dbapi import connect

# 1. 建立连接（参数与Session一致）
ip = "127.0.0.1"
port_ = 6667
username_ = "root"
password_ = "root"
conn = connect(
    ip, port_, username_, password_,
    fetch_size=1024,
    zone_id="UTC+8",
    sqlalchemy_mode=False
)
cursor = conn.cursor()

# 2. 执行简单SQL查询
cursor.execute("SELECT ** FROM root.sg1.d1 LIMIT 5")
# 获取所有结果
for row in cursor.fetchall():
    print(row)

# 3. 执行带参数的SQL（pyformat风格）
cursor.execute("SELECT ** FROM root.sg1.d1 WHERE time < %(time)s", {"time":"2024-01-01T00:08:00.000"})
for row in cursor.fetchall():
    print(row)

# 4. 批量执行带参数的SQL（插入数据）
seq_of_parameters = [
    {"timestamp": 1, "temperature": 25.5},
    {"timestamp": 2, "temperature": 26.0},
    {"timestamp": 3, "temperature": 26.5},
]
sql = "insert into root.sg1.d1(timestamp,temperature) values(%(timestamp)s,%(temperature)s)"
cursor.executemany(sql, seq_of_parameters)

# 5. 关闭游标和连接
cursor.close()
conn.close()

十二、拓展适配：IoTDB SQLAlchemy Dialect（实验性）

IoTDB提供了SQLAlchemy方言适配，主要为了对接Apache Superset等可视化工具，注意：该特性仍为实验性，请勿在生产环境使用，仅支持简单的查询和ORM映射。

12.1 数据模型映射

IoTDB的层次数据模型与SQLAlchemy的关系数据模型做了如下映射，是适配的基础：

SQLAlchemy元数据	IoTDB元数据
Schema	Database（存储组）
Table	Path + Entity（设备）
Column	Measurement（测点）

12.2 数据类型映射

IoTDB数据类型	SQLAlchemy数据类型
BOOLEAN	Boolean
INT32	Integer
INT64	BigInteger
FLOAT	Float
DOUBLE	Float
TEXT	Text
LONG	BigInteger

12.3 基础使用示例

（1）直接执行SQL

from sqlalchemy import create_engine

# 创建引擎（连接格式：iotdb://用户名:密码@ip:端口）
engine = create_engine("iotdb://root:root@127.0.0.1:6667")
connect = engine.connect()

# 执行查询
result = connect.execute("SELECT ** FROM root.sg1.d1 LIMIT 5")
for row in result.fetchall():
    print(row)

connect.close()

（2）简单ORM查询

仅支持基础的查询和过滤，复杂操作暂不支持：

from sqlalchemy import create_engine, Column, Float, BigInteger, MetaData
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker

# 配置元数据（指定存储组）
metadata = MetaData(schema='root.sg1')
Base = declarative_base(metadata=metadata)

# 定义ORM模型（映射设备root.sg1.d1）
class Device(Base):
    __tablename__ = "d1"
    Time = Column(BigInteger, primary_key=True)  # 时间戳为主键
    s1 = Column(BigInteger)  # 测点s1
    s2 = Column(Float)       # 测点s2

# 创建引擎并建立会话
engine = create_engine("iotdb://root:root@127.0.0.1:6667")
DbSession = sessionmaker(bind=engine)
session = DbSession()

# 执行ORM查询（过滤s2>20的数据，查询s1）
res = session.query(Device.s1).filter(Device.s2 > 20)
for row in res:
    print(row)

session.close()

十三、开发与发版：给Python开发者的说明

如果需要对IoTDB Python客户端进行二次开发、调试或发版，需遵循以下步骤，核心基于Thrift编译和Maven构建：

13.1 开发环境准备

1. 首选Python3.7+版本
2. 安装thrift可执行文件（≥0.11.0），参考官方安装教程
3. 安装开发依赖：pip install -r requirements_dev.txt

13.2 编译Thrift库

在IoTDB源代码根目录执行以下Maven命令，自动生成Python的Thrift通信代码：

mvn clean generate-sources -pl iotdb-client/client-py -am

注意 ：生成的代码在iotdb/thrift目录，该目录会被Git忽略，切勿上传到代码仓库。

13.3 测试与格式化

1. 自定义测试用例添加到tests文件夹
2. 运行所有测试：pytest .（部分测试需要Docker环境）
3. 代码格式化：black .
4. 代码检查：flake8 .

13.4 发版流程

官方提供了release.sh脚本，一键完成发版全流程：删除临时目录→重新生成源码→代码检查→运行测试→构建包→发布到PyPI。

十四、总结

IoTDB Python原生接口是Python开发者对接IoTDB的最佳选择，封装友好、功能全面，从基础的Session连接 、DDL/DML操作 ，到高级的SessionPool连接池 、SSL加密 、元数据模板 ，再到数据分析友好的Pandas适配 、测试便捷的Testcontainer 、通用的DBAPI，几乎覆盖了所有开发场景。

核心使用要点总结：

1. 生产环境优先使用多节点Session/SessionPool，实现容灾重试
2. 数据写入首选Tablet方式，Numpy Tablet对数值型数据效率更高
3. 数据分析直接使用todf()方法转换为Pandas DataFrame，高效便捷
4. 安全通信开启SSL加密，服务端和客户端证书配置缺一不可
5. 批量创建相同结构时间序列使用元数据模板，减少重复工作
6. 测试使用Testcontainer，容器化快速启动IoTDB，无需手动部署

不管是工业物联网的实时数据采集、时序数据存储，还是后续的数据分析、可视化，IoTDB Python原生接口都能完美适配，结合Python的生态优势，能大幅提升开发效率。

🌐 附：IoTDB的各大版本

📄 Apache IoTDB 是一款工业物联网时序数据库管理系统，采用端边云协同的轻量化架构，支持一体化的物联网时序数据收集、存储、管理与分析 ，具有多协议兼容、超高压缩比、高通量读写、工业级稳定、极简运维等特点。

版本	IoTDB 二进制包	IoTDB 源代码	发布说明
2.0.5	- All-in-one - AINode - SHA512 - ASC	- 源代码 - SHA512 - ASC	release notes
1.3.5	- All-in-one - AINode - SHA512 - ASC	- 源代码 - SHA512 - ASC	release notes
0.13.4	- All-in-one - Grafana 连接器 - Grafana 插件 - SHA512 - ASC	- 源代码 - SHA512 - ASC	release notes

✨ 目前最新版本为2.0.6，去获取：https://archive.apache.org/dist/iotdb/

联系博主

xcLeigh 博主，全栈领域优质创作者，博客专家，目前，活跃在CSDN、微信公众号、小红书、知乎、掘金、快手、思否、微博、51CTO、B站、腾讯云开发者社区、阿里云开发者社区等平台，全网拥有几十万的粉丝，全网统一IP为 xcLeigh。希望通过我的分享，让大家能在喜悦的情况下收获到有用的知识。主要分享编程、开发工具、算法、技术学习心得等内容。很多读者评价他的文章简洁易懂，尤其对于一些复杂的技术话题，他能通过通俗的语言来解释，帮助初学者更好地理解。博客通常也会涉及一些实践经验，项目分享以及解决实际开发中遇到的问题。如果你是开发领域的初学者，或者在学习一些新的编程语言或框架，关注他的文章对你有很大帮助。

亲爱的朋友，无论前路如何漫长与崎岖，都请怀揣梦想的火种，因为在生活的广袤星空中，总有一颗属于你的璀璨星辰在熠熠生辉，静候你抵达。

愿你在这纷繁世间，能时常收获微小而确定的幸福，如春日微风轻拂面庞，所有的疲惫与烦恼都能被温柔以待，内心永远充盈着安宁与慰藉。

至此，文章已至尾声，而您的故事仍在续写，不知您对文中所叙有何独特见解？期待您在心中与我对话，开启思想的新交流。

---

💞 关注博主 🌀 带你实现畅游前后端！

🏰 大屏可视化 🌀 带你体验酷炫大屏！

💯 神秘个人简介 🌀 带你体验不一样得介绍！

🥇 从零到一学习Python 🌀 带你玩转Python技术流！

🏆 前沿应用深度测评 🌀 前沿AI产品热门应用在线等你来发掘！

💦 注 ：本文撰写于CSDN平台 ,作者：xcLeigh （所有权归作者所有） ，https://xcleigh.blog.csdn.net/，如果相关下载没有跳转，请查看这个地址，相关链接没有跳转，皆是抄袭本文，转载请备注本文原地址。

---

📣 亲，码字不易，动动小手，欢迎 点赞 ➕ 收藏，如 🈶 问题请留言（或者关注下方公众号，看见后第一时间回复，还有海量编程资料等你来领！），博主看见后一定及时给您答复 💌💌💌