快速上手 - Python

依赖安装

使用 PIP 在线安装

1. 架构平台支持情况

Platform	python
Linux_x86_64	py39, py310, py311, py312, py313
Linus_aarch64	py39, py310, py311, py312, py313
MacOS_arm64	py39, py310, py311, py312, py313
MacOS_X86_64	py39, py310, py311, py312, py313
Win_amd64	py39, py310, py311, py312, py313

2. 安装依赖版本要求

   • numpy >= 1.26.4
   • pandas >= 2.2.2

3. 安装步骤

通过 pip 指令在线安装

pip install tsfile

下载 wheel 文件手动安装

1. 下载 wheel 文件：https://pypi.org/project/tsfile/#files
2. 通过 pip install 命令安装 wheel 文件

pip install tsfile.wheel

源码编译安装

1. 安装依赖版本要求

   • CMake >=3.11
   • Maven >=3.9.6
   • GCC >=4.8.5
   • Make >=4.3
   • cython >= 3.0.10
   • numpy >= 1.26.4
   • pandas >= 2.2.2
   • setuptools >= 70.0.0

2. 安装步骤

• 从git克隆源代码:

git clone https://github.com/apache/tsfile.git

• 在 TsFile 根目录下执行 maven 编译:

mvn clean install -P with-python -DskipTests

• 如果没有安装 maven, 你可以执行下面的指令完成编译:

  • 在 Linux 或 Macos上：

    mvnw clean install -P with-python -DskipTests
    

  • 在 Windows 上:

    mvnw.cmd clean install -P with-python -DskipTests
    

• 编译成功后，wheel 文件将位于 tsfile/python/dist 目录下, 可通过 pip install 命令进行本地安装（假设他的名字是 tsfile.wheel）

pip install tsfile.wheel

写入示例

import os
from tsfile import *

table_data_dir = os.path.join(os.path.dirname(__file__), "table_data.tsfile")
if os.path.exists(table_data_dir):
    os.remove(table_data_dir)

column1 = ColumnSchema("id", TSDataType.STRING, ColumnCategory.TAG)
column2 = ColumnSchema("id2", TSDataType.STRING, ColumnCategory.TAG)
column3 = ColumnSchema("value", TSDataType.DOUBLE, ColumnCategory.FIELD)
table_schema = TableSchema("test_table", columns=[column1, column2, column3])


### Free resource automatically
with TsFileTableWriter(table_data_dir, table_schema) as writer:
    tablet_row_num = 100
    tablet = Tablet(
                    ["id", "id2", "value"],
                    [TSDataType.STRING, TSDataType.STRING, TSDataType.DOUBLE],
                    tablet_row_num)

    for i in range(tablet_row_num):
        tablet.add_timestamp(i, i * 10)
        tablet.add_value_by_name("id", i, "test1")
        tablet.add_value_by_name("id2", i, "test" + str(i))
        tablet.add_value_by_index(2, i, i * 100.2)

    writer.write_table(tablet)

读取示例（表模型）

TsFileReader 同时支持树模型接口：query_table_on_tree、query_tree_by_row、query_timeseries（详见接口定义）。

import os
from tsfile import *

table_data_dir = os.path.join(os.path.dirname(__file__), "table_data.tsfile")
### Free resource automatically
with TsFileReader(table_data_dir) as reader:
    print(reader.get_all_table_schemas())
    with reader.query_table("test_table", ["id2", "value"], 0, 50) as result:
        print(result.get_metadata())
        while result.next():
            print(result.get_value_by_name("id2"))
            print(result.get_value_by_name("value"))
            print(result.read_data_frame())

使用 to_dataframe 读取 TsFile 为 Dataframe.

import os
import tsfile as ts
table_data_dir = os.path.join(os.path.dirname(__file__), "table_data.tsfile")
print(ts.to_dataframe(table_data_dir))

示例代码

使用这些接口的示例代码可以在以下链接中找到：https://github.com/apache/tsfile/blob/develop/python/examples/example.py

注意：以上示例基于表模型。树模型接口请参考 Python 接口定义。