Quick Start - Python

Dependencies

If want to compile on your local envirment, the dependencies are below:

• 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

or use pip install, the dependencies are:

numpy >= 1.26.4 pandas >= 2.2.2

Installation Method

Install From Pypi

Use pip to install the latest version from pypi:

pip install tsfile

Platform support:

Platform	python
Linux_x86_64	py39, py310, py311, py312, py313
Linux_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

To download wheel from pypi: https://pypi.org/project/tsfile/#files

Compile on your local envirment

Clone the source code from git:

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

Run Maven to compile in the TsFile root directory:

mvn clean install -P with-python -DskipTests

If Maven is not installed, you can compile tsfile using the following command:

Linux or Macos:

mvnw clean install -P with-python -DskipTests

Windows:

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

Directory Structure

• wheel: Located at tsfile/python/dist, you can use pip to install this wheel.

Install into your local envirment

run pip install to install tsfile package you already compiled(Assuming the compilation produces tsfile.wheel.).

pip install tsfile.wheel

Writing Process

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)

Reading Process

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())