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 ColumnCategory(IntEnum):
"""
TsFile 中的列类别枚举。
TAG：表示标签列，用于存储元数据。
FIELD：表示测点列，用于存储实际数据值。
"""
TAG = 0
FIELD = 1
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])
class TsFileTableWriter:
"""
用于将结构化表格数据写入具有指定模式的 TsFile。
"""
"""
:param path: tsfile 文件路径，如果不存在则会创建。
:param table_schema: 描述要写入表的结构信息。
:return: 无返回值。
"""
def __init__(self, path: str, table_schema: TableSchema)
"""
将一个 Tablet 写入 TsFile 中的表中。
:param tablet: 存储表的批量数据。
:return: 无返回值。
"""
def write_table(self, tablet: Tablet)
"""
关闭 TsFileTableWriter，并自动刷新数据。
:return: 无返回值。
"""
def close(self)
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)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
"""
获取指定表的模式信息。
: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)
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)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 迭代器。
该函数同时支持表模型（table-model）和树模型（tree-model）的 TsFile。
用户可以通过表名、列名、时间范围以及最大行数对数据进行过滤。
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
当指定的列在表结构中不存在时抛出。
"""TsFileDataFrame 围绕着三个核心类型：
- TsFileDataFrame: 入口对象，加载一至多个 TsFile 并提供统一视图。初始化时只扫描元数据，不读取实际数值。
- Timeseries: 单条时间序列的懒加载句柄。通过
df[...]的数组操作获得，包含序列元信息但不立即读取，仅在行号索引时才触发数据读取
- AlignedTimeseries: 多条序列的时间对齐结果。通过
df.loc[...]获取，一次性将指定时间范围内的多条序列对齐到同一时间轴并读入内存
| 示例 |
操作 |
返回类型 |
TsFileDataFrame(paths) |
加载文件/目录 |
TsFileDataFrame |
len(df) |
获取时间序列总数 |
int |
df.list_timeseries("weather") |
获取/按前缀筛选序列名 |
List[str] |
df["weather.beijing.humidity"]，df[0], df[-1] |
获取单条序列 |
Timeseries |
df[0:3], df[[0,2,5]] |
获取多条序列 |
List[Timeseries] |
df.loc[start:end, serlies_list] |
按时间戳对齐查询 |
AlignedTimeseries |
| 示例 |
操作 |
返回类型 |
ts.name |
序列名 |
str |
len(ts) |
序列点数 |
int |
ts.stats |
序列统计信息 |
dict |
ts[20] |
单值读取 |
float |
ts[20:100] |
行范围切片 |
np.ndarray |
ts.``timestamps |
时间戳数组 |
np.ndarray |
| 示例 |
操作 |
返回类型 |
data.timestamps |
时间戳数组 |
np.ndarray |
data.values |
值矩阵 |
np.ndarray, shape=(N, M) |
data.series_names |
序列名列表 |
List[str] |
data.shape |
形状 |
(N, M) |
len(data) |
行数 |
int |
data[0]、data[0:10]、data[0, 1] |
行 / 元素索引 |
np.ndarray/ scalar |
print(data)、data.show(50) |
格式化输出 |
自动截断的表格 |