| <!-- | |
| 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 | |
| 当指定的列在表结构中不存在时抛出。 | |
| """ | |
| ``` |