| <!-- |
| |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| |
| --> |
| # 接口定义 - Python |
| |
| ## 数据模式 |
| |
| ```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 |
| |
| ```python |
| 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 |
| |
| |
| ```Python |
| 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 |
| |
| ```python |
| 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 列处理的列名列表。 |
| """ |
| ``` |
| |
| ## 配置 |
| |
| 全局写入默认值——包括各类型的默认编码、默认压缩、时间列编码/压缩——以一个字典暴露。 |
| 请在创建写入器 **之前** 修改它们。 |
| |
| ```python |
| 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 |
| |
| ```python |
| 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 |
| |
| |
| ```python |
| 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 |
| |
| ```Python |
| |
| 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 |
| 当指定的列在表结构中不存在时抛出。 |
| """ |
| |
| ``` |
