TsFile Python 文档

简介

本目录包含 TsFile 的 Python 实现版本。Python 版本基于 C++ 版本构建，并通过 Cython 包将 TsFile 的读写能力集成到 Python 环境中。用户可以像在 Pandas 中使用 read_csv 和 write_csv 一样，方便地读取和写入 TsFile。

源代码位于 ./tsfile 目录。 以 .pyx 和 .pyd 结尾的文件为使用 Cython 编写的封装代码。 tsfile/tsfile.py 中定义了一些对用户开放的接口。

你可以在 ./examples/examples.py 中找到读写示例。

TsFileDataFrame 列角色描述

TsFileDataFrame 可以加载表和列的 JSON 描述文件。列值使用 C 表示协变量， 使用 T 表示目标变量：

{
  "multivariate": {
    "weather": {
      "columns": {
        "temperature": "C",
        "humidity": "T"
      }
    }
  }
}

未作为多变量训练数据使用的表可以不写入 multivariate。

创建 dataframe 时传入描述文件路径。get 和 set 提供对 JSON 顶层键的字典式 访问，其中 set 会将更新后的描述写回文件；另外还可以按表获取协变量列、目标 变量列及其数量：

df = TsFileDataFrame("weather.tsfile", description_path="description.json")
df.get("multivariate")
df.get_covariate_columns("weather")
df.get_target_columns("weather")
df.get_covariate_column_count("weather")
df.get_target_column_count("weather")
df.get_device_count("weather")
df.get_device_node_counts("weather")
df.get_device_point_counts("weather")
df.get_device_statistics("weather")
df.get_device_point_count("weather", "device_a")
df.get_device_stats("weather", {"device": "device_a"})
df.list_device_metadata("weather")
df.set(
    "multivariate",
    {"weather": {"columns": {"temperature": "T", "humidity": "T"}}},
)
df.close()

这里的节点数量指设备下实际存在的数值时间序列数量。get_device_node_counts 使用设备有序标签值元组作为 key。get_device_statistics 还会返回点数、非空值数量 和时间范围，list_device_metadata 则将标签展开为带名称的列。其中 point_count 遵循 DataFrame 的时间线数量（包含 NaN 行），value_count 只统计非空值。

---

如何贡献

建议使用 pylint 对 Python 代码进行检查。

目前尚无合适的 Cython 代码风格检查工具，因此 Cython 部分代码应遵循 pylint 所要求的 Python 代码风格。

功能列表

• [ ] 在 pywrapper 中调用 TsFile C++ 版本实现的批量读取接口。
• [ ] 支持将多个 DataFrame 写入同一个 TsFile 文件。

---

构建

在构建 TsFile 的 Python 版本之前，必须先构建 TsFile C++ 版本，因为 Python 版本依赖于 C++ 版本生成的共享库文件。

使用 Maven 在根目录构建

mvn -P with-cpp,with-python clean verify

使用 Python 命令构建

python setup.py build_ext --inplace

文件级 Properties

TsFileWriter 和 TsFileTableWriter 可以在打开期间写入二进制 property。 setter 仅接受 bytes。reader 返回 dict[str, bytes | None]，并区分 null 与 零长度 bytes。

with TsFileWriter("example.tsfile") as writer:
    writer.add_tsfile_property("binary-property", b"\x01\x00\xff")

with TsFileReader("example.tsfile") as reader:
    properties = reader.get_tsfile_properties()

Property value 不携带数据类型；保存数字或结构体时应使用明确、可跨语言的字节编码。