Quick Start - Python

Dependencies and Installation

Install From Pypi

1. 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

2. Dependencies:

   • numpy >= 1.26.4
   • pandas >= 2.2.2

3. Use pip to install the latest version from pypi:

pip install tsfile

Install From Wheel File

1. Download wheel from pypi: https://pypi.org/project/tsfile/#files
2. Install the wheel file using the pip install command.

pip install tsfile.wheel

Install From Source Code Compilation

1. Dependencies

   • 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. Installation steps

• 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
    

• After successful compilation, the wheel file will be located in the tsfile/python/dist directory and can be installed locally using the pip install command (assuming its name is 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 (table model)

TsFileReader also supports tree queries: query_table_on_tree, query_tree_by_row, and query_timeseries — see Python interface definition.

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

Use to_dataframe to read tsfile as 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))

Sample Code

The sample code of using these interfaces is in：https://github.com/apache/tsfile/blob/develop/python/examples/example.py

The snippets above use the table writer/reader. Tree-style usage is documented in Python interface definition (query_table_on_tree, query_tree_by_row, etc.). C++ tree APIs are TsFileTreeReader / TsFileTreeWriter in the source headers tsfile_tree_reader.h / tsfile_tree_writer.h.