接口定义 - Python

数据模式

class TSDataType(IntEnum):
    """
    TsFile 当前支持的数据类型枚举。
    """
    BOOLEAN = 0
    INT32 = 1
    INT64 = 2
    FLOAT = 3
    DOUBLE = 4
    TEXT = 5
    TIMESTAMP = 8
    DATE = 9
    BLOB = 10
    STRING = 11

class TSEncoding(IntEnum):
    """
    写入器支持的值编码。每个成员后的注释列出其可用于哪些数据类型。
    """
    PLAIN = 0         # 所有类型
    DICTIONARY = 1    # STRING、TEXT
    RLE = 2           # INT32、INT64、TIMESTAMP、DATE
    TS_2DIFF = 4      # INT32、INT64、TIMESTAMP、DATE、FLOAT、DOUBLE
    GORILLA = 8       # INT32、INT64、TIMESTAMP、DATE、FLOAT、DOUBLE
    ZIGZAG = 9        # INT32、INT64
    SPRINTZ = 12      # INT32、INT64、FLOAT、DOUBLE

class Compressor(IntEnum):
    """
    写入器支持的压缩，默认值为 LZ4。
    """
    UNCOMPRESSED = 0
    SNAPPY = 1
    GZIP = 2
    LZO = 3
    LZ4 = 7

class ColumnCategory(IntEnum):
    """
    TsFile 中的列类别枚举。
    TAG：标签列
    FIELD：测点列，存储测量值。
    ATTRIBUTE / TIME：保留的列角色。
    """
    TAG = 0
    FIELD = 1
    ATTRIBUTE = 2
    TIME = 3

class ColumnSchema:
    """定义表中某一列的模式（名称、数据类型、类别）。"""

    column_name = None
    data_type = None
    category = None

    def __init__(self, column_name: str, data_type: TSDataType,
                 category: ColumnCategory = ColumnCategory.FIELD)

class TableSchema:
    """表结构的模式定义。"""

    table_name = None
    columns = None

    def __init__(self, table_name: str, columns: List[ColumnSchema])

class ResultSetMetaData:
    """查询结果集的元数据容器（列名、类型、表名）。"""

    column_list = None
    data_types = None
    table_name = None

    def __init__(self, column_list: List[str], data_types: List[TSDataType])

写入接口

TsFileWriter

class TsFileTableWriter:
    """
    用于将结构化表格数据写入具有指定模式的 TsFile。
    """

    """
    :param path: tsfile 文件路径，如果不存在则会创建。
    :param table_schema: 描述要写入表的结构信息。
    :param memory_threshold: 触发自动刷盘前缓冲的字节数（默认 128MB）。
    :return: 无返回值。
    """
    def __init__(self, path: str, table_schema: TableSchema,
                 memory_threshold: int = 128 * 1024 * 1024)

    """
    将一个 Tablet 写入 TsFile 中的表中。
    :param tablet: 存储表的批量数据。
    :return: 无返回值。
    """
    def write_table(self, tablet: Tablet)

    """
    将一个 pandas DataFrame 写入表中。列的编码/压缩遵循表 schema（或引擎默认值）。
    :param dataframe: 要写入的数据。
    :return: 无返回值。
    """
    def write_dataframe(self, dataframe: pandas.DataFrame)

    """
    将缓冲数据刷新到磁盘。
    :return: 无返回值。
    """
    def flush(self)

    """
    关闭 TsFileTableWriter，并自动刷新数据。
    :return: 无返回值。
    """
    def close(self)

    # 可作为上下文管理器使用：
    #   with TsFileTableWriter(path, schema) as w:
    #       w.write_table(tablet)
    def __enter__(self)
    def __exit__(self, exc_type, exc_val, exc_tb)

Tablet definition

class Tablet(object)
    """
    一个为批量数据预分配的列式数据容器，具有类型约束。
    它会创建时间戳缓冲区和带类型的数据列，并对数值类型执行有效值范围校验。

    初始化参数:
    :param column_name_list: 数据列的名称列表。
    :param type_list: 每列允许的数据类型（TSDataType 枚举值）。
    :param max_row_num: 预分配的最大行数（默认值为 1024）。
    :return: 无返回值。
    """

    def __init__(self, column_name_list: list[str], type_list: list[TSDataType],
                 max_row_num: int = 1024)

dataframe_to_tsfile

def dataframe_to_tsfile(dataframe: pd.DataFrame,
                        file_path: str,
                        table_name: Optional[str] = None,
                        time_column: Optional[str] = None,
                        tag_column: Optional[list[str]] = None)
    """
    将 pandas DataFrame 写入 TsFile。

    :param dataframe:   要写入的数据。
    :param file_path:   目标 .tsfile 路径。
    :param table_name:  输出表名。
    :param time_column: 用作时间戳列的列名。
    :param tag_column:  作为 TAG 列处理的列名列表。
    """

配置

全局写入默认值——包括各类型的默认编码、默认压缩、时间列编码/压缩——以一个字典暴露。
请在创建写入器 之前 修改它们。

from tsfile import get_tsfile_config, set_tsfile_config
from tsfile import TSEncoding, Compressor

cfg = get_tsfile_config()          # -> 包含所有配置项的 dict
# 例如 cfg["default_compression_type_"]、cfg["int64_encoding_type_"]、
#      cfg["time_encoding_type_"]、cfg["time_compress_type_"] 等。

set_tsfile_config({
    "default_compression_type_": Compressor.LZ4,
    "int64_encoding_type_": TSEncoding.TS_2DIFF,
})

set_tsfile_config 会校验每个取值，且只更新你传入的键。编码/压缩取值为 TSEncoding / Compressor
成员。各数据类型允许的编码，以及不修改时使用的默认值：

数据类型	允许的编码	默认值
BOOLEAN	PLAIN	PLAIN
INT32、INT64、DATE	PLAIN、TS_2DIFF、GORILLA、ZIGZAG、RLE、SPRINTZ	TS_2DIFF
FLOAT、DOUBLE	PLAIN、TS_2DIFF、GORILLA、SPRINTZ	GORILLA
STRING、TEXT	PLAIN、DICTIONARY	PLAIN

压缩适用于所有数据类型：UNCOMPRESSED、SNAPPY、GZIP、LZO、LZ4（默认 LZ4）。

读取接口

TsFileReader

class TsFileReader:
    """
    从 TsFile 中查询表格数据。
    """

    """
    初始化指定路径的 TsFile 读取器。
    :param pathname: TsFile 文件的路径。
    :return: 无返回值。
    """
    def __init__(self, pathname)

    """
    对指定的表和列执行时间范围查询。

    :param table_name: 要查询的表名。
    :param column_names: 要检索的列名列表。
    :param start_time: 查询范围的起始时间（默认：int64 最小值）。
    :param end_time: 查询范围的结束时间（默认：int64 最大值）。
    :return: 查询结果集处理器。
    """
    def query_table(self, table_name : str, column_names : List[str],
                    start_time : int = np.iinfo(np.int64).min,
                    end_time: int = np.iinfo(np.int64).max) -> ResultSet

    """
    按行查询表，支持偏移量/行数限制下推与可选的标签过滤。标签谓词把查询限定到
    标签列取值满足条件的设备。用 tsfile.tag_filter 中的辅助函数构造过滤器
    （tag_eq、tag_neq、tag_lt、tag_lteq、tag_gt、tag_gteq、tag_between 等），
    并用 &、| 和 ~ 组合。

    :param table_name: 要查询的表名。
    :param column_names: 要检索的列名列表。
    :param offset: 需要跳过的起始行数（默认 0）。
    :param limit: 最多返回的行数；< 0 表示不限制。
    :param tag_filter: 可选的标签谓词（TagFilter），None 表示不过滤。
    :param batch_size: <= 0 逐行返回；> 0 按该大小返回数据块。
    :return: 查询结果集处理器。
    """
    def query_table_by_row(self, table_name : str, column_names : List[str],
                           offset : int = 0, limit : int = -1,
                           tag_filter = None, batch_size : int = 0) -> ResultSet

    """
    获取指定表的模式信息。

    :param table_name: 表名。
    :return: 指定表的模式信息。
    """
    def get_table_schema(self, table_name : str) -> TableSchema

    """
    获取 TsFile 中所有表的模式信息。

    :return: 一个将表名映射到其模式的字典。
    """
    def get_all_table_schemas(self) -> dict[str, TableSchema]

    """
    关闭 TsFile 读取器。如果读取器中有活动的结果集，它们将失效。
    """
    def close(self)

ResultSet

class ResultSet:
    """
    用于从查询结果集中获取数据。当执行查询时，将返回一个结果集处理器。
    如果读取器被关闭，该结果集将失效。
    """

    """
    检查并移动到查询结果集中的下一行。

    :return: 如果存在下一行则返回 True，否则返回 False。
    """
    def next(self) -> bool

    """
    获取结果集的列信息。

    :return: 一个字典，键为列名，值为对应的数据类型。
    """
    def get_result_column_info(self) -> dict[str, TsDataType]

    """
    从查询结果集中读取下一个 DataFrame。

    :param max_row_num: 要读取的最大行数，默认值为 1024。
    :return: 包含查询结果数据的 DataFrame。
    """
    def read_data_frame(self, max_row_num : int = 1024) -> DataFrame

    """
    从查询结果集中按索引获取值。

    :param index: 要获取值的索引，1 <= index <= column_num。
    :return: 指定索引处的值。
    """
    def get_value_by_index(self, index : int)

    """
    从查询结果集中按列名获取值。

    :param column_name: 要获取值的列名。
    :return: 指定列的值。
    """
    def get_value_by_name(self, column_name : str)

    """
    获取结果集的元数据信息。

    :return: 结果集的元数据，类型为 ResultSetMetadata 对象。
    """
    def get_metadata(self) -> ResultSetMetadata

    """
    检查结果集中指定索引位置的字段是否为 null。

    :param index: 要检查的字段索引，1 <= index <= column_num。
    :return: 若字段为 null 返回 True，否则返回 False。
    """
    def is_null_by_index(self, index : int)

    """
    检查结果集中指定列名的字段是否为 null。

    :param name: 要检查的列名。
    :return: 若字段为 null 返回 True，否则返回 False。
    """
    def is_null_by_name(self, name : str)

    """
    关闭结果集并释放相关资源。
    """
    def close(self)

to_dataframe

def to_dataframe(file_path: str,
                 table_name: Optional[str] = None,
                 column_names: Optional[list[str]] = None,
                 start_time: Optional[int] = None,
                 end_time: Optional[int] = None,
                 max_row_num: Optional[int] = None,
                 as_iterator: bool = False) -> Union[pd.DataFrame, Iterator[pd.DataFrame]]:
        """
       从 TsFile 中读取数据，并将其转换为 Pandas DataFrame
       或 DataFrame 迭代器。

       用户可以通过表名、列名、时间范围以及最大行数对数据进行过滤。

       Parameters
       ----------
       file_path : str
           要读取的 TsFile 文件路径。

       table_name : Optional[str], default None
           表模型 TsFile 中要查询的表名。
           如果为 None 且文件为表模型，
           将使用 schema 中找到的第一个表。

       column_names : Optional[list[str]], default None
           要查询的列名/测点名列表。
           - 如果为 None，则返回所有列。
           - 在表模型 TsFile 中会校验列是否存在。

       start_time : Optional[int], default None
           查询的起始时间戳。
           如果为 None，则使用 int64 的最小值。

       end_time : Optional[int], default None
           查询的结束时间戳。
           如果为 None，则使用 int64 的最大值。

       max_row_num : Optional[int], default None
           读取的最大行数。
           - 如果为 None，则返回所有可用数据。
           - 当 `as_iterator` 为 False 时，
             若结果行数超过该值，DataFrame 将被截断。

       as_iterator : bool, default False
           是否返回 DataFrame 迭代器，而不是单个合并后的 DataFrame。
           - True：返回按批次生成 DataFrame 的迭代器
           - False：返回单个 Pandas DataFrame

       Returns
       -------
       Union[pandas.DataFrame, Iterator[pandas.DataFrame]]
           - 当 `as_iterator` 为 False 时，返回 Pandas DataFrame
           - 当 `as_iterator` 为 True 时，返回 Pandas DataFrame 迭代器

       Raises
       ------
       TableNotExistError
           当指定的表名在表模型 TsFile 中不存在时抛出。

       ColumnNotExistError
           当指定的列在表结构中不存在时抛出。
    """