This is an automated email from the ASF dual-hosted git repository. colinlee pushed a commit to branch add_doc in repository https://gitbox.apache.org/repos/asf/tsfile.git
commit 1998af5c2cd25d15c1f3d4423692f0f2646119a9 Author: colin <[email protected]> AuthorDate: Fri Jul 18 17:37:58 2025 +0800 add some doc. --- .../InterfaceDefinition/InterfaceDefinition-C.md | 2 +- .../InterfaceDefinition/InterfaceDefinition-CPP.md | 2 +- .../InterfaceDefinition-Java.md | 2 +- .../InterfaceDefinition-Python.md | 2 +- .../QuickStart/Navigating_Time_Series_Data.md | 64 +++ src/UserGuide/develop/QuickStart/QuickStart-C.md | 2 +- src/UserGuide/develop/QuickStart/QuickStart-CPP.md | 2 +- .../develop/QuickStart/QuickStart-JAVA.md | 2 +- .../develop/QuickStart/QuickStart-PYTHON.md | 2 +- .../InterfaceDefinition/InterfaceDefinition-C.md | 459 +++++++++++++++++++++ .../InterfaceDefinition/InterfaceDefinition-CPP.md | 444 ++++++++++++++++++++ .../InterfaceDefinition-Java.md | 119 +++--- .../InterfaceDefinition-Python.md | 264 ++++++++++++ .../QuickStart/Navigating_Time_Series_Data.md | 65 +++ .../UserGuide/develop/QuickStart/QuickStart-C.md | 2 +- .../UserGuide/develop/QuickStart/QuickStart-CPP.md | 2 +- .../develop/QuickStart/QuickStart-JAVA.md | 2 +- .../develop/QuickStart/QuickStart-PYTHON.md | 2 +- 18 files changed, 1371 insertions(+), 68 deletions(-) diff --git a/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md b/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md index 93630a53..f5564398 100644 --- a/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md +++ b/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md @@ -18,7 +18,7 @@ under the License. --> -# Interface definition +# Interface definition - C diff --git a/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md b/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md index cdae52a4..b165a024 100644 --- a/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md +++ b/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md @@ -18,7 +18,7 @@ under the License. --> -# Interface Definitions +# Interface Definitions - Cpp ## Write Interface diff --git a/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-Java.md b/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-Java.md index 62ecdce6..3ae53d09 100644 --- a/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-Java.md +++ b/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-Java.md @@ -18,7 +18,7 @@ under the License. --> -# Interface Definitions +# Interface Definitions - Java ## Write Interface diff --git a/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md b/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md index a3e4d9d2..ad6d4619 100644 --- a/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md +++ b/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md @@ -18,7 +18,7 @@ under the License. --> -# Interface Definitions +# Interface Definitions - Python ## Schema diff --git a/src/UserGuide/develop/QuickStart/Navigating_Time_Series_Data.md b/src/UserGuide/develop/QuickStart/Navigating_Time_Series_Data.md new file mode 100644 index 00000000..6ff81da3 --- /dev/null +++ b/src/UserGuide/develop/QuickStart/Navigating_Time_Series_Data.md @@ -0,0 +1,64 @@ +<!-- + + 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. + +--> +# Entering Time Series Data + +## What Is Time Series Data？ + +In today's era of the Internet of Things, various scenarios such as the Internet of Things and industrial scenarios are undergoing digital transformation. People collect various states of devices by installing sensors on them. If the motor collects voltage and current, the blade speed, angular velocity, and power generation of the fan; Vehicle collection of latitude and longitude, speed, and fuel consumption; The vibration frequency, deflection, displacement, etc. of the bridge. The data [...] + + + +Generally speaking, we refer to each collection point as a measurement point (also known as a physical quantity, time series, timeline, signal quantity, indicator, measurement value, etc.). Each measurement point continuously collects new data information over time, forming a time series. In the form of a table, each time series is a table formed by two columns: time and value; In a graphical way, each time series is a trend chart formed over time, which can also be vividly referred to a [...] + + + +The massive time series data generated by sensors is the foundation of digital transformation in various industries, so our modeling of time series data mainly focuses on equipment and sensors. + +## Key Concepts of Time Series Data +The main concepts involved in time-series data can be divided from bottom to top: data points, measurement points, and equipment. + + + +### Data Point + +- Definition: Consists of a timestamp and a value, where the timestamp is of type long and the value can be of various types such as BOOLEAN, FLOAT, INT32, etc. +- Example: A row of a time series in the form of a table in the above figure, or a point of a time series in the form of a graph, is a data point. + + + +### Measurement Points + +- Definition: It is a time series formed by multiple data points arranged in increments according to timestamps. Usually, a measuring point represents a collection point and can regularly collect physical quantities of the environment it is located in. +- Also known as: physical quantity, time series, timeline, semaphore, indicator, measurement value, etc +- Example： + - Electricity scenario: current, voltage + - Energy scenario: wind speed, rotational speed + - Vehicle networking scenarios: fuel consumption, vehicle speed, longitude, dimensions + - Factory scenario: temperature, humidity + +### Device + +- Definition: Corresponding to a physical device in an actual scene, usually a collection of measurement points, identified by one to multiple labels +- Example： + - Vehicle networking scenario: Vehicles identified by vehicle identification code (VIN) + - Factory scenario: robotic arm, unique ID identification generated by IoT platform + - Energy scenario: Wind turbines, identified by region, station, line, model, instance, etc + - Monitoring scenario: CPU, identified by machine room, rack, Hostname, device type, etc \ No newline at end of file diff --git a/src/UserGuide/develop/QuickStart/QuickStart-C.md b/src/UserGuide/develop/QuickStart/QuickStart-C.md index 035d139b..68a25802 100644 --- a/src/UserGuide/develop/QuickStart/QuickStart-C.md +++ b/src/UserGuide/develop/QuickStart/QuickStart-C.md @@ -18,7 +18,7 @@ under the License. --> -# Quick Start +# Quick Start - C ## Dependencies diff --git a/src/UserGuide/develop/QuickStart/QuickStart-CPP.md b/src/UserGuide/develop/QuickStart/QuickStart-CPP.md index cabdb372..0eb30716 100644 --- a/src/UserGuide/develop/QuickStart/QuickStart-CPP.md +++ b/src/UserGuide/develop/QuickStart/QuickStart-CPP.md @@ -18,7 +18,7 @@ under the License. --> -# Quick Start +# Quick Start - Cpp ## Dependencies diff --git a/src/UserGuide/develop/QuickStart/QuickStart-JAVA.md b/src/UserGuide/develop/QuickStart/QuickStart-JAVA.md index e0aca68b..5ac101ad 100644 --- a/src/UserGuide/develop/QuickStart/QuickStart-JAVA.md +++ b/src/UserGuide/develop/QuickStart/QuickStart-JAVA.md @@ -18,7 +18,7 @@ under the License. --> -# Quick Start +# Quick Start - Java ## Dependencies diff --git a/src/UserGuide/develop/QuickStart/QuickStart-PYTHON.md b/src/UserGuide/develop/QuickStart/QuickStart-PYTHON.md index 505f0342..2d855a9e 100644 --- a/src/UserGuide/develop/QuickStart/QuickStart-PYTHON.md +++ b/src/UserGuide/develop/QuickStart/QuickStart-PYTHON.md @@ -18,7 +18,7 @@ under the License. --> -# Quick Start +# Quick Start - Python ## Dependencies diff --git a/src/zh/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md b/src/zh/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md new file mode 100644 index 00000000..45db6f3f --- /dev/null +++ b/src/zh/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md @@ -0,0 +1,459 @@ +<!-- + + 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. + +--> + +# 接口定义 - C + + +## Schema（模式定义） + +```C++ +typedef enum { + TS_DATATYPE_BOOLEAN = 0, + TS_DATATYPE_INT32 = 1, + TS_DATATYPE_INT64 = 2, + TS_DATATYPE_FLOAT = 3, + TS_DATATYPE_DOUBLE = 4, + TS_DATATYPE_TEXT = 5, + TS_DATATYPE_STRING = 11 +} TSDataType; + +typedef enum column_category { TAG = 0, FIELD = 1 } ColumnCategory; + +// ColumnSchema：表示单个列的模式，包括列名、数据类型和分类。 +typedef struct column_schema { + char* column_name; + TSDataType data_type; + ColumnCategory column_category; +} ColumnSchema; + +// TableSchema：定义一个表的模式，包括表名和列模式数组。 +typedef struct table_schema { + char* table_name; + ColumnSchema* column_schemas; + int column_num; +} TableSchema; + +// ResultSetMetaData：结果集的元数据，包括列名和数据类型。 +typedef struct result_set_meta_data { + char** column_names; + TSDataType* data_types; + int column_num; +} ResultSetMetaData; +``` + +## 写入接口 + +### 创建/关闭 TsFile 写入文件 + +```C++ +/** + * @brief 创建写入文件。 + * + * @param pathname 目标文件路径。 + * @param err_code [输出] RET_OK(0)，或 errno_define_c.h 中的错误码。 + * + * @return WriteFile 成功返回有效句柄。 + * + * @note 调用 free_write_file() 释放资源。 + * @note 调用 free_write_file() 前，需确保 TsFileWriter 已关闭。 + */ + +WriteFile write_file_new(const char* pathname, ERRNO* err_code); + +void free_write_file(WriteFile* write_file); +``` + + +### 创建/关闭 TsFile Writer + +在创建 TsFile Writer 时，需要指定 WriteFile 和 TableSchema。你可以使用 tsfile_writer_new_with_memory_threshold 设置内存阈值。 + +```C++ +/** + * @brief 创建 TsFileWriter。 + * + * @param file 写入目标文件。 + * @param schema 表结构定义。 + * - 由调用者负责释放。 + * @param err_code [输出] RET_OK(0)，或 errno_define_c.h 中的错误码。 + * + * @return TsFileWriter 成功返回有效句柄，失败返回 NULL。 + * + * @note 使用完毕后需调用 tsfile_writer_close() 释放资源。 + */ +TsFileWriter tsfile_writer_new(WriteFile file, TableSchema* schema, + ERRNO* err_code); + +/** + * @brief 创建 TsFileWriter，带内存阈值限制。 + * + * @param file 写入目标文件。 + * @param schema 表结构定义。 + * - 由调用者负责释放。 + * @param memory_threshold 超过该内存阈值时会自动刷盘。 + * @param err_code [输出] RET_OK(0)，或 errno_define_c.h 中的错误码。 + * + * @return TsFileWriter 成功返回有效句柄，失败返回 NULL。 + * + * @note 使用完毕后需调用 tsfile_writer_close() 释放资源。 + */ +TsFileWriter tsfile_writer_new_with_memory_threshold(WriteFile file, + TableSchema* schema, + uint64_t memory_threshold, + ERRNO* err_code); + +/** + * @brief 释放 TsFileWriter 相关资源。 + * + * @param writer [输入] 来自 tsfile_writer_new() 的 Writer 句柄。 + * 调用后该句柄失效，不可重复使用。 + * @return ERRNO - 成功返回 RET_OK(0)，否则返回错误码。 + */ +ERRNO tsfile_writer_close(TsFileWriter writer); +``` + + + +### 创建/关闭/插入数据 Tablet + +可以使用 Tablet 批量插入数据。数据写入后需释放对应内存资源。 +```C +/** + * @brief 创建用于批量写入的 Tablet。 + * + * @param column_name_list [输入] 列名数组，长度为 column_num。 + * @param data_types [输入] 数据类型数组，长度为 column_num。 + * @param column_num [输入] 列数量，必须 ≥ 1。 + * @param max_rows [输入] 预分配的最大行数，必须 ≥ 1。 + * @return Tablet 成功返回有效句柄。 + * @note 使用完后需调用 free_tablet() 释放资源。 + */ +Tablet tablet_new(char** column_name_list, TSDataType* data_types, + uint32_t column_num, uint32_t max_rows); +/** + * @brief 获取当前 Tablet 中的行数。 + * + * @param tablet [输入] 有效 Tablet 句柄。 + * @return uint32_t 当前行数 (0 到 max_rows-1)。 + */ +uint32_t tablet_get_cur_row_size(Tablet tablet); + +/** + * @brief 向指定行设置时间戳。 + * + * @param tablet [输入] 有效 Tablet。 + * @param row_index [输入] 目标行号 (0 ≤ index < max_rows)。 + * @param timestamp [输入] 时间戳 (int64_t 类型)。 + * @return ERRNO - 成功返回 RET_OK(0)，否则返回错误码。 + */ +ERRNO tablet_add_timestamp(Tablet tablet, uint32_t row_index, + Timestamp timestamp); + + +/** + * @brief 按列名为指定行添加字符串值。 + * + * @param value [输入] 以 '\0' 结尾的字符串，调用者保留所有权。 + */ +ERRNO tablet_add_value_by_name_string(Tablet tablet, uint32_t row_index, + const char* column_name, + const char* value); + + // 支持多种数据类型插入 +ERRNO tablet_add_value_by_name_int32_t(Tablet tablet, uint32_t row_index, + const char* column_name, + int32_t value); +ERRNO tablet_add_value_by_name_int64_t(Tablet tablet, uint32_t row_index, + const char* column_name, + int64_t value); + +ERRNO tablet_add_value_by_name_double(Tablet tablet, uint32_t row_index, + const char* column_name, + double value); + +ERRNO tablet_add_value_by_name_float(Tablet tablet, uint32_t row_index, + const char* column_name, + float value); + +ERRNO tablet_add_value_by_name_bool(Tablet tablet, uint32_t row_index, + const char* column_name, + bool value); + +/** + * @brief 按列索引为指定行添加值（支持多种数据类型）。 + * + * @param value [输入] 字符串会被内部复制。 + */ +ERRNO tablet_add_value_by_index_string(Tablet tablet, uint32_t row_index, + uint32_t column_index, + const char* value); + + +ERRNO tablet_add_value_by_index_int32_t(Tablet tablet, uint32_t row_index, + uint32_t column_index, + int32_t value); +ERRNO tablet_add_value_by_index_int64_t(Tablet tablet, uint32_t row_index, + uint32_t column_index, + int64_t value); + +ERRNO tablet_add_value_by_index_double(Tablet tablet, uint32_t row_index, + uint32_t column_index, + double value); + +ERRNO tablet_add_value_by_index_float(Tablet tablet, uint32_t row_index, + uint32_t column_index, + float value); + +ERRNO tablet_add_value_by_index_bool(Tablet tablet, uint32_t row_index, + uint32_t column_index, + bool value); + + +void free_tablet(Tablet* tablet); +``` + + + + + +### 将 Tablet 写入 TsFile + +```C +/** + * @brief 将 Tablet 中的数据写入 TsFile。 + * + * @param writer [输入] 有效的 TsFileWriter 句柄。 + * @param tablet [输入] 含数据的 Tablet，写入后可释放。 + */ + +ERRNO tsfile_writer_write(TsFileWriter writer, Tablet tablet); +``` + + + + +## 读取接口 + +### TsFile Reader 创建/关闭 + +```C +/** + * @brief 创建用于读取 TsFile 的 TsFileReader。 + * + * @param pathname [输入] TsFile 路径。 + * @param err_code [输出] RET_OK(0) 或错误码。 + * @return 成功时返回有效句柄。 + * + * @note 使用 tsfile_reader_close() 释放资源。 + */ + +TsFileReader tsfile_reader_new(const char* pathname, ERRNO* err_code); + +/** + * @brief 释放 TsFileReader 占用的资源。 + * + * @note 调用后句柄失效，且由此句柄获得的结果集也失效。 + */ +ERRNO tsfile_reader_close(TsFileReader reader); +``` + + + +### 查询表 / 获取下一行 + +```C + +/** + * @brief 在指定时间范围内，从指定表和列中查询数据。 + * + * @param reader [输入] 通过 tsfile_reader_new() 获取的有效 TsFileReader 句柄。 + * @param table_name [输入] 目标表名，必须存在于 TsFile 中。 + * @param columns [输入] 要查询的列名数组。 + * @param column_num [输入] 列名数组中的列数。 + * @param start_time [输入] 起始时间戳。 + * @param end_time [输入] 结束时间戳，必须大于等于 start_time。 + * @param err_code [输出] 成功返回 RET_OK(0)，否则返回 errno_define_c.h 中定义的错误码。 + * @return ResultSet 查询结果集句柄。使用完成后必须通过 free_tsfile_result_set() 释放。 + */ +ResultSet tsfile_query_table(TsFileReader reader, const char* table_name, + char** columns, uint32_t column_num, + Timestamp start_time, Timestamp end_time, + ERRNO* err_code); + +/** + * @brief 检查并获取结果集中的下一行数据。 + * + * @param result_set [输入] 有效的 ResultSet 句柄。 + * @param error_code [输出] 成功返回 RET_OK(0)，否则返回 errno_define_c.h 中的错误码。 + * @return bool - true：存在下一行数据，false：已到达末尾或发生错误。 + */ +bool tsfile_result_set_next(ResultSet result_set, ERRNO* error_code); + +/** + * @brief 释放结果集资源。 + * + * @param result_set [输入] 有效的 ResultSet 句柄指针。 + */ +void free_tsfile_result_set(ResultSet* result_set); +``` + + + +### 从结果集中获取数据 + +```c +/** + * @brief 判断当前行中指定列（按列名）对应的值是否为 NULL。 + * + * @param result_set [输入] 当前处于有效行的 ResultSet（需在调用 next() 返回 true 之后）。 + * @param column_name [输入] 结果集模式中存在的列名。 + * @return bool - true：值为 NULL 或找不到该列，false：值有效。 + */ +bool tsfile_result_set_is_null_by_name(ResultSet result_set, + const char* column_name); + +/** + * @brief 判断当前行中指定列（按列索引）对应的值是否为 NULL。 + * + * @param column_index [输入] 列的位置（1 <= 索引 <= 结果集列数）。 + * @return bool - true：值为 NULL 或索引超出范围，false：值有效。 + */ +bool tsfile_result_set_is_null_by_index(ResultSet result_set, + uint32_t column_index); + +/** + * @brief 根据列名获取当前行中的字符串值。 + * + * @param result_set [输入] 有效的结果集句柄。 + * @param column_name [输入] 要获取的列名。 + * @return char* - 字符串指针。调用者在使用完后必须手动释放该指针。 + */ +char* tsfile_result_set_get_value_by_name_string(ResultSet result_set, + const char* column_name); + +bool tsfile_result_set_get_value_by_name_bool(ResultSet result_set, const char* + column_name); +int32_t tsfile_result_set_get_value_by_name_int32_t(ResultSet result_set, const char* + column_name); +int64_t tsfile_result_set_get_value_by_name_int64_t(ResultSet result_set, const char* + column_name); +float tsfile_result_set_get_value_by_name_float(ResultSet result_set, const char* + column_name); +double tsfile_result_set_get_value_by_name_double(ResultSet result_set, const char* + column_name); + +/** + * @brief 根据列索引获取当前行中的字符串值。 + * + * @param result_set [输入] 有效的结果集句柄。 + * @param column_index [输入] 要获取的列索引（1 <= 索引 <= 列总数）。 + * @return char* - 字符串指针。调用者在使用完后必须手动释放该指针。 + */ +char* tsfile_result_set_get_value_by_index_string(ResultSet result_set, + uint32_t column_index); + +int32_t tsfile_result_set_get_value_by_index_int32_t(ResultSet result_set, uint32_t + column_index); +int64_t tsfile_result_set_get_value_by_index_int64_t(ResultSet result_set, uint32_t + column_index); +float tsfile_result_set_get_value_by_index_float(ResultSet result_set, uint32_t + column_index); +double tsfile_result_set_get_value_by_index_double(ResultSet result_set, uint32_t + column_index); +bool tsfile_result_set_get_value_by_index_bool(ResultSet result_set, uint32_t + column_index); + +/** + * @brief 获取描述结果集模式的元数据信息。 + * + * @param result_set [输入] 有效的结果集句柄。 + * @return ResultSetMetaData 元数据句柄。调用者在使用后应释放该元数据。 + * @note 调用该函数前应检查 result_set 是否为 NULL，NULL 可能表示查询执行失败。 + */ +ResultSetMetaData tsfile_result_set_get_metadata(ResultSet result_set); + +/** + * @brief 根据索引从元数据中获取列名。 + * + * @param result_set_meta_data [输入] 有效的结果集元数据句柄。 + * @param column_index [输入] 列的位置（1 <= 索引 <= 列总数）。 + * @return const char* 只读字符串。如果索引无效则返回 NULL。 + */ + +char* tsfile_result_set_metadata_get_column_name(ResultSetMetaData result_set_meta_data, + uint32_t column_index); + +/** + * @brief 根据索引从元数据中获取列的数据类型。 + * + * @param result_set_meta_data [输入] 有效的结果集元数据句柄。 + * @param column_index [输入] 列的位置（1 <= 索引 <= 列总数）。 + * @return TSDataType 若索引无效则返回 TS_DATATYPE_INVALID（255）。 + */ +TSDataType tsfile_result_set_metadata_get_data_type( + ResultSetMetaData result_set_meta_data, uint32_t column_index); + +/** + * @brief 获取结果集模式中的列总数。 + * + * @param result_set_meta_data [输入] 有效的结果集元数据句柄。 + * @return int 结果集中列的数量。 + */ +int tsfile_result_set_metadata_get_column_num(ResultSetMetaData result_set); +``` + + + +### 从 TsFile Reader 中获取表定义 + +```C +/** + * @brief 获取 TsFile 中指定表的模式信息。 + * + * @param reader [输入] 有效的读取器句柄。 + * @param table_name [输入] 目标表名，必须存在于 TsFile 中。 + * @return TableSchema 包含表及其列的信息。 + * @note 调用者应调用 free_table_schema 释放返回的 TableSchema 资源。 + */ + +TableSchema tsfile_reader_get_table_schema(TsFileReader reader, + const char* table_name); +/** + * @brief 获取 TsFile 中所有表的模式信息。 + * + * @param size [输出] 返回的表模式数组中的元素数量。 + * @return TableSchema* 表模式数组指针。 + * @note 调用者必须对数组中的每个元素调用 free_table_schema()， + * 并对整个数组指针调用 free() 进行释放。 + */ + +TableSchema* tsfile_reader_get_all_table_schemas(TsFileReader reader, + uint32_t* size); + +/** + * @brief 释放 TableSchema 占用的内存空间。 + * + * @param schema [输入] 需要释放的表模式结构。 + */ + +void free_table_schema(TableSchema schema); +``` + diff --git a/src/zh/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md b/src/zh/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md new file mode 100644 index 00000000..f44b7f0c --- /dev/null +++ b/src/zh/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md @@ -0,0 +1,444 @@ +<!-- + + 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. + +--> +# 接口定义 - Cpp + +## 写入接口 + +### TsFileTableWriter + +用于写入 TsFile. + +```cpp +/** + * @brief 用于将结构化表格数据写入具有指定模式的 TsFile。 + * + * TsFileTableWriter 类被设计用于写入结构化数据，特别适合时序数据， + * 数据将被写入一种为高效存储与检索优化的文件格式（即 TsFile）。该类允许用户定义 + * 所需写入表的模式，按照该模式添加数据行，并将这些数据序列化写入 TsFile。 + * 此外，还提供了在写入过程中限制内存使用的选项。 + */ +class TsFileTableWriter { + public: + /** + * TsFileTableWriter 用于将表格数据写入具有指定模式的目标文件， + * 可选地限制内存使用。 + * + * @param writer_file 要写入表数据的目标文件。不能为空。 + * @param table_schema 用于构造表结构，定义正在写入表的模式。 + * @param memory_threshold 可选参数。当写入数据的大小超过该值时， + * 数据将自动刷新到磁盘。默认值为 128MB。 + */ + + TsFileTableWriter(WriteFile* writer_file, + TableSchema* table_schema, + uint64_t memory_threshold = 128 * 1024 * 1024); + ~TsFileTableWriter(); + /** + * 将给定的 Tablet 数据按照表的模式写入目标文件。 + * + * @param tablet 包含待写入数据的 Tablet。不能为空。 + * @return 成功时返回 0，失败时返回非零错误码。 + */ + + int write_table(const Tablet& tablet); + /** + * 将所有缓冲数据刷新到底层存储介质，确保所有数据都已写出。 + * 此方法确保所有未完成的写入操作被持久化。 + * + * @return 成功时返回 0，失败时返回非零错误码。 + */ + + int flush(); + /** + * 关闭写入器并释放其占用的所有资源。 + * 调用此方法后，不应再对该实例执行任何操作。 + * + * @return 成功时返回 0，失败时返回非零错误码。 + */ + + int close(); +}; +``` + +### 表模式 + +描述表模式（schema）的数据结构。 + +```cpp +/** +* @brief 表示整个表的模式信息。 +* +* 此类包含描述特定表结构所需的元数据， +* 包括表名以及所有列的模式信息。 +*/ +class TableSchema { + public: + /** + * 使用给定的表名和列模式构造一个 TableSchema 对象。 + * + * @param table_name 表的名称，必须为非空字符串。 + * 此名称用于在系统中标识该表。 + * @param column_schemas 一个包含 ColumnSchema 对象的向量。 + * 每个 ColumnSchema 定义表中一列的模式。 + */ + TableSchema(const std::string& table_name, + const std::vector<ColumnSchema>& column_schemas); +}; + + +/** +* @brief 表示单个列的模式信息。 +* +* 此结构体包含描述特定列存储方式所需的元数据， +* 包括列名、数据类型和列类别。 +*/ +struct ColumnSchema { + std::string column_name_; + common::TSDataType data_type_; + ColumnCategory column_category_; + + /** + * @brief 使用给定参数构造一个 ColumnSchema 对象。 + * + * @param column_name 列的名称，必须为非空字符串。 + * 此名称用于在表中标识该列。 + * @param data_type 该列的数据类型，例如 INT32、DOUBLE、TEXT 等。 + * 数据类型决定了数据的存储与解释方式。 + * @param column_category 列的类别，用于标识其在模式中的角色或类型， + * 例如 FIELD（字段）、TAG（标签）。 + * 如果未指定，默认为 ColumnCategory::FIELD。 + * @note 调用者有责任确保 `column_name` 非空。 + */ + ColumnSchema(std::string column_name, common::TSDataType data_type, + ColumnCategory column_category = ColumnCategory::FIELD) : column_name_(std::move(column_name)), + data_type_(data_type), + column_category_(column_category) { + } +}; + +/** + * @brief Represents the data type of a measurement. + * + * This enumeration defines the supported data types for measurements in the system. + */ +enum TSDataType : uint8_t { + BOOLEAN = 0, + INT32 = 1, + INT64 = 2, + FLOAT = 3, + DOUBLE = 4, + TEXT = 5, + STRING = 11 +}; + +``` + +### Tablet + + +```cpp +/** + * @brief 表示用于插入到表中的数据行集合及其相关元数据。 + * + * 此类用于管理和组织将要插入特定目标表的数据。 + * 它负责存储时间戳和值，以及相关的元数据，如列名和数据类型。 + */ +class Tablet { +public: + /** + * @brief 使用给定参数构造一个 Tablet 对象。 + * + * @param column_names 一个包含该 Tablet 中列名的向量。 + * 每个名称对应目标表中的一列。 + * @param data_types 一个包含每列数据类型的向量。 + * 这些类型必须与目标表的模式相匹配。 + * @param max_rows 该 Tablet 可容纳的最大行数，默认为 DEFAULT_MAX_ROWS。 + */ + Tablet(const std::vector<std::string> &column_names, + const std::vector<common::TSDataType> &data_types, + int max_rows = DEFAULT_MAX_ROWS); + + /** + * @brief 向指定行添加时间戳。 + * + * @param row_index 要添加时间戳的行索引， + * 必须小于最大行数。 + * @param timestamp 要添加的时间戳值。 + * @return 成功时返回 0，失败时返回非零错误码。 + */ + int add_timestamp(uint32_t row_index, int64_t timestamp); + + /** + * @brief 模板函数，用于向指定的行和列添加类型为 T 的值。 + * + * @tparam T 要添加的值的类型。 + * @param row_index 要添加值的行索引， + * 必须小于最大行数。 + * @param schema_index 要添加的值对应的列模式索引。 + * @param val 要添加的值。 + * @return 成功时返回 0，失败时返回非零错误码。 + */ + + template <typename T> + int add_value(uint32_t row_index, uint32_t schema_index, T val); + + /** + * @brief 模板函数，用于通过列名向指定的行和列添加类型为 T 的值。 + * + * @tparam T 要添加的值的类型。 + * @param row_index 要添加值的行索引， + * 必须小于最大行数。 + * @param measurement_name 要添加值的列名， + * 必须与构造时提供的列名之一匹配。 + * @param val 要添加的值。 + * @return 成功时返回 0，失败时返回非零错误码。 + */ + template <typename T> + int add_value(uint32_t row_index, const std::string &measurement_name, T val); +}; +``` + +## 读接口 +### Tsfile Reader +```cpp +/** + * @brief TsFileReader 提供了查询所有以 .tsfile 为后缀的文件的能力。 + * + * TsFileReader 旨在用于查询 .tsfile 文件，它支持树模型查询和表模型查询， + * 并支持查询元数据信息，如 TableSchema 和 TimeseriesSchema。 + */ + +class TsFileReader { + public: + TsFileReader(); + ~TsFileReader(); + /** + * @brief 打开 tsfile 文件。 + * + * @param file_path 要打开的 tsfile 文件路径。 + * @return 成功时返回 0，失败时返回非零错误码。 + */ + + int open(const std::string &file_path); + /** + * @brief 关闭 tsfile，查询完成后应调用此方法。 + * + * @return 成功时返回 0，失败时返回非零错误码。 + */ + int close(); + /** + * @brief 通过查询表达式对 tsfile 进行查询，用户可以自行构造查询表达式来查询 tsfile。 + * + * @param [in] qe 查询表达式。 + * @param [out] ret_qds 查询结果集。 + * @return 成功时返回 0，失败时返回非零错误码。 + */ + int query(storage::QueryExpression *qe, ResultSet *&ret_qds); + /** + * @brief 通过路径列表、起始时间和结束时间查询 tsfile， + * 本方法使用树模型进行查询。 + * + * @param [in] path_list 路径列表。 + * @param [in] start_time 起始时间。 + * @param [in] end_time 结束时间。 + * @param [out] result_set 查询结果集。 + */ + int query(std::vector<std::string> &path_list, int64_t start_time, + int64_t end_time, ResultSet *&result_set); + /** + * @brief 通过表名、列名、起始时间和结束时间查询 tsfile， + * 本方法使用表模型进行查询。 + * + * @param [in] table_name 表名。 + * @param [in] columns_names 列名列表。 + * @param [in] start_time 起始时间。 + * @param [in] end_time 结束时间。 + * @param [out] result_set 查询结果集。 + */ + int query(const std::string &table_name, + const std::vector<std::string> &columns_names, int64_t start_time, + int64_t end_time, ResultSet *&result_set); + /** + * @brief 销毁结果集，该方法应在查询完成并使用完 result_set 后调用。 + * + * @param qds 查询结果集。 + */ + void destroy_query_data_set(ResultSet *qds); + ResultSet *read_timeseries( + const std::shared_ptr<IDeviceID> &device_id, + const std::vector<std::string> &measurement_name); + /** + * @brief 获取 tsfile 中的所有设备。 + * + * @param table_name 表名。 + * @return std::vector<std::shared_ptr<IDeviceID>> 设备 ID 列表。 + */ + std::vector<std::shared_ptr<IDeviceID>> get_all_devices( + std::string table_name); + /** + * @brief 根据设备 ID 和测量名称获取时间序列模式信息。 + * + * @param [in] device_id 设备 ID。 + * @param [out] result std::vector<MeasurementSchema> 测量模式列表。 + * @return 成功时返回 0，失败时返回非零错误码。 + */ + int get_timeseries_schema(std::shared_ptr<IDeviceID> device_id, + std::vector<MeasurementSchema> &result); + /** + * @brief 根据表名获取表的模式信息。 + * + * @param table_name 表名。 + * @return std::shared_ptr<TableSchema> 表的模式信息。 + */ + std::shared_ptr<TableSchema> get_table_schema( + const std::string &table_name); + /** + * @brief 获取 tsfile 中所有表的模式信息。 + * + * @return std::vector<std::shared_ptr<TableSchema>> 表模式信息列表。 + */ + std::vector<std::shared_ptr<TableSchema>> get_all_table_schemas(); +}; +``` +### ResultSet +```cpp +/** + * @brief ResultSet 是 TsFileReader 的查询结果集，用于访问查询结果。 + * + * ResultSet 是一个虚类，使用时应转换为相应的实现类。 + * @note 当使用树模型且过滤器是全局时间过滤器时，应转换为 QDSWithoutTimeGenerator。 + * @note 当使用树模型但过滤器不是全局时间过滤器时，应转换为 QDSWithTimeGenerator。 + * @note 如果查询使用的是表模型，则应转换为 TableResultSet。 + */ +class ResultSet { + public: + ResultSet() {} + virtual ~ResultSet() {} + + /** + * @brief 获取结果集的下一行。 + * + * @param[out] has_next 布尔值，指示是否还有下一行。 + * @return 成功时返回 0，失败时返回非零错误码。 + */ + virtual int next(bool& has_next) = 0; + + /** + * @brief 根据列名检查该列的值是否为 null。 + * + * @param column_name 列名。 + * @return 如果值为 null 返回 true，否则返回 false。 + */ + virtual bool is_null(const std::string& column_name) = 0; + + /** + * @brief 根据列索引检查该列的值是否为 null。 + * + * @param column_index 从 1 开始的列索引。 + * @return 如果值为 null 返回 true，否则返回 false。 + */ + virtual bool is_null(uint32_t column_index) = 0; + + /** + * @brief 根据列名获取该列的值。 + * + * @param column_name 列名。 + * @return 该列的值。 + */ + template <typename T> + T get_value(const std::string& column_name); + + /** + * @brief 根据列索引获取该列的值。 + * + * @param column_index 从 1 开始的列索引。 + * @return 该列的值。 + */ + template <typename T> + T get_value(uint32_t column_index); + + /** + * @brief 获取当前行的 RowRecord。 + * + * @return 当前行的 RowRecord。 + */ + virtual RowRecord* get_row_record() = 0; + + /** + * @brief 获取结果集的元数据。 + * + * @return std::shared_ptr<ResultSetMetadata> 结果集的元数据。 + */ + virtual std::shared_ptr<ResultSetMetadata> get_metadata() = 0; + + /** + * @brief 关闭结果集。 + * + * @note 当不再需要结果集时应调用此方法。 + */ + virtual void close() = 0; +}; + +``` +### ResultMeta +```cpp +/** + * @brief 结果集的元数据信息。 + * + * 用户可以通过 ResultSetMetadata 获取结果集的元数据， + * 包括所有列名和数据类型。当用户使用表模型时，第一列默认是时间列。 + */ +class ResultSetMetadata { + public: + /** + * @brief ResultSetMetadata 的构造函数。 + * + * @param column_names 列名列表。 + * @param column_types 列类型列表。 + */ + ResultSetMetadata(const std::vector<std::string>& column_names, + const std::vector<common::TSDataType>& column_types); + + /** + * @brief 获取指定索引的列类型。 + * + * @param column_index 从 1 开始的列索引。 + * @return 对应的列类型。 + */ + common::TSDataType get_column_type(uint32_t column_index); + + /** + * @brief 获取指定索引的列名。 + * + * @param column_index 从 1 开始的列索引。 + * @return 对应的列名。 + */ + std::string get_column_name(uint32_t column_index); + + /** + * @brief 获取列的总数量。 + * + * @return 列的数量（uint32_t 类型）。 + */ + uint32_t get_column_count(); +}; + +``` \ No newline at end of file diff --git a/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-Java.md b/src/zh/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-Java.md similarity index 72% copy from src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-Java.md copy to src/zh/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-Java.md index 62ecdce6..0ca58670 100644 --- a/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-Java.md +++ b/src/zh/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-Java.md @@ -18,101 +18,104 @@ under the License. --> -# Interface Definitions +# 接口定义 - Java -## Write Interface +## 写入接口 ### ITsFileWriter -Used to write data to tsfile +用于将数据写入 TsFile ```Java interface ITsFileWriter extends AutoCloseable { - // Write data + // 写入数据 void write(Tablet tablet); - // Close Write + // 关闭写入器 void close(); } + ``` ### TsFileWriterBuilder -Used to construct ITsFileWriter +用于构建 ITsFileWriter ```Java class TsFileWriterBuilder { - // Build ITsFileWriter object + // 构建 ITsFileWriter 对象 public ITsFileWriter build(); - // target file + // 目标文件 public TsFileWriterBuilder file(File file); - // Used to construct table structures + // 用于构建表结构 public TsFileWriterBuilder tableSchema(TableSchema schema); - // Used to limit the memory size of objects + // 用于限制写入时的内存使用大小 public TsFileWriterBuilder memoryThreshold(long memoryThreshold); } + ``` ### TableSchema -Describe the data structure of the table schema +描述表结构的数据组织方式 ```Java class TableSchema { - // Constructor function + // 构造函数 public TableSchema(String tableName, List<ColumnSchema> columnSchemaList); } class ColumnSchema { - // Constructor function + // 构造函数 public ColumnSchema(String columnName, TSDataType dataType, ColumnCategory columnCategory); - // Get column names + // 获取列名 public String getColumnName(); - // Get the data type of the column + // 获取列的数据类型 public TSDataType getDataType(); - // Get column category + // 获取列的类别 public Tablet.ColumnCategory getColumnCategory(); } class ColumnSchemaBuilder { - // Build ColumnSchema object + // 构建 ColumnSchema 对象 public ColumnSchema build(); - // Column Name + // 设置列名 public ColumnSchemaBuilder name(String columnName); - // The data type of the column + // 设置列的数据类型 public ColumnSchemaBuilder dataType(TSDataType columnType); - // Column category + // 设置列的类别 public ColumnSchemaBuilder category(ColumnCategory columnCategory); - // Supported types + // 支持的数据类型 enum TSDataType { - BOOLEAN, - INT32, - INT64, - FLOAT, - DOUBLE, - TIMESTAMP, - TEXT, - DATE, - BLOB, - STRING; + BOOLEAN, // 布尔型 + INT32, // 32位整数 + INT64, // 64位整数 + FLOAT, // 单精度浮点数 + DOUBLE, // 双精度浮点数 + TIMESTAMP, // 时间戳 + TEXT, // 文本 + DATE, // 日期 + BLOB, // 二进制大对象 + STRING; // 字符串 } - // Supported column categories + // 支持的列类别 enum ColumnCategory { - TAG, - FIELD + TAG, // 标签列 + FIELD // 字段列 } } + ``` ### Tablet @@ -121,15 +124,15 @@ Write column memory structure ```Java class Tablet { - // Constructor function + // 构造函数 public Tablet(List<String> columnNameList, List<TSDataType> dataTypeList); public Tablet(List<String> columnNameList, List<TSDataType> dataTypeList, int maxRowNum); - // Interface for adding timestamps + // 添加时间戳 void addTimestamp(int rowIndex, long timestamp); - // Interface for adding values - // Add values based on column names + // 添加值 + // 基于列名添加值 void addValue(int rowIndex, String columnName, int val); void addValue(int rowIndex, String columnName, long val); void addValue(int rowIndex, String columnName, float val); @@ -138,7 +141,7 @@ class Tablet { void addValue(int rowIndex, String columnName, String val); void addValue(int rowIndex, String columnName, byte[] val); void addValue(int rowIndex, String columnName, LocalDate val); - // Add values based on index position + // 基于索引添加值 void addValue(int rowIndex, int columnIndex, int val); void addValue(int rowIndex, int columnIndex, long val); void addValue(int rowIndex, int columnIndex, float val); @@ -154,48 +157,50 @@ class Tablet { ### ITsFileReader -Used to query data in tsfile +用于在 TsFile 中查询数据。 ```Java interface ITsFileReader extends AutoCloseable { - // Used to execute queries and return results + // 用于执行查询并返回结果 ResultSet query(String tableName, List<String> columnNames, long startTime, long endTime); - // Return the schema of the table named tableName in tsfile + // 返回 tsfile 中指定表名（tableName）的表结构信息 Optional<TableSchema> getTableSchemas(String tableName); - // Retrieve schema information for all tables in the tsfile + // 获取 tsfile 中所有表的结构信息 List<TableSchema> getAllTableSchema(); - // Close query + // 关闭查询 void close(); } + ``` ### TsFileReaderBuilder -Used to construct ITsFileReader +用于构建 ITsFileReader ```Java class TsFileReaderBuilder { - // Build ITsFileReader object + // 构建 ITsFileReader 对象 public ITsFileReader build(); - // target file + // 目标文件 public TsFileReaderBuilder file(File file); } + ``` ### ResultSet -The result set of the query +查询的结果集 ```Java interface ResultSet extends AutoCloseable { - // Move the cursor to the next row and return whether there is still data + // 将游标移动到下一行，并返回是否还有数据 boolean next(); - // Get the value of the current row and a certain column + // 获取当前行某一列的值 int getInt(String columnName); int getInt(int columnIndex); long getLong(String columnName); @@ -213,28 +218,30 @@ interface ResultSet extends AutoCloseable { byte[] getBinary(String columnName); byte[] getBinary(int columnIndex); - // Determine whether a column is NULL in the current row + // 判断当前行某一列是否为 NULL boolean isNull(String columnName); boolean isNull(int columnIndex); - // Close the current result set + // 关闭当前结果集 void close(); - // Obtain the header of the result set + // 获取结果集的元数据信息 ResultSetMetadata getMetadata(); } + ``` ### ResultSetMetadata -Used to obtain metadata for the result set +用于获取结果集的元数据信息 ```Java interface ResultSetMetadata { - // Obtain the column name of the Nth column in the result set + // 获取结果集中第 N 列的列名 String getColumnName(int columnIndex); - // Obtain the data type of the Nth column in the result set + // 获取结果集中第 N 列的数据类型 TSDataType getColumnType(int columnIndex); } + ``` diff --git a/src/zh/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md b/src/zh/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md new file mode 100644 index 00000000..112d3c96 --- /dev/null +++ b/src/zh/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md @@ -0,0 +1,264 @@ +<!-- + + 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 + 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]) + + +``` + + + +## 写入接口 + +### TsFileWriter + +```python +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) + + +``` + + +### 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) + +``` + +## 读取接口 + +### 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 + + """ + 获取指定表的模式信息。 + + :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_next_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) + +``` + diff --git a/src/zh/UserGuide/develop/QuickStart/Navigating_Time_Series_Data.md b/src/zh/UserGuide/develop/QuickStart/Navigating_Time_Series_Data.md new file mode 100644 index 00000000..635b0583 --- /dev/null +++ b/src/zh/UserGuide/develop/QuickStart/Navigating_Time_Series_Data.md @@ -0,0 +1,65 @@ +<!-- + + 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. + +--> +# 走进时间序列数据 + +## 什么是时间序列数据？ + +在当今的物联网时代，物联网、工业等各种场景正在经历数字化转型。人们通过在设备上安装传感器来采集其各种状态数据。例如，电机采集电压和电流；风扇采集叶片转速、角速度和发电量；车辆采集经纬度、速度和油耗；桥梁采集振动频率、挠度、位移等。传感器的数据采集已经深入到各个行业。 + + + +通常，我们将每一个采集点称为测量点（也称为物理量、时间序列、时间线、信号量、指标、测量值等）。每个测量点会随着时间持续采集新的数据信息，形成一条时间序列。从表格的角度来看，每个时间序列是一张由“时间”和“数值”两列组成的表；从图形的角度来看，每条时间序列是一张随时间变化的趋势图，也可以形象地称作设备的“心电图”。 + + + +传感器产生的海量时间序列数据，是各行业数字化转型的基础，因此我们对时间序列数据的建模主要聚焦于设备和传感器。 + +## 时间序列数据的关键概念 + +时间序列数据中涉及的主要概念可以自底向上分为：数据点、测量点和设备。 + + + +### 数据点 + +- 定义：由一个时间戳和一个数值组成，其中时间戳为 long 类型，值可以是 BOOLEAN、FLOAT、INT32 等多种类型。 +- 示例：在上图中，表格形式中的一行时间序列，或图形形式中的一个时间序列上的点，都是一个数据点。 + + + +### 测量点 + +- 定义：由多个按照时间戳递增排列的数据点构成的时间序列。通常一个测量点表示一个采集点，并能定期采集其所处环境中的物理量。 +- 也称为：物理量、时间序列、时间线、信号量、指标、测量值等。 +- 示例： + - 电力场景：电流、电压 + - 能源场景：风速、转速 + - 车联网场景：油耗、车速、经度、纬度 + - 工厂场景：温度、湿度 + +### 设备 + +- 定义：对应实际场景中的一个物理设备，通常是多个测量点的集合，并通过一个或多个标签进行标识 +- 示例： + - 车联网场景：通过车辆识别码（VIN）标识的车辆 + - 工厂场景：机械臂，通过物联网平台生成的唯一 ID 进行标识 + - 能源场景：风电机组，通过区域、站点、线路、型号、实例等维度进行标识 +itoring scenario: CPU, identified by machine room, rack, Hostname, device type, etc \ No newline at end of file diff --git a/src/zh/UserGuide/develop/QuickStart/QuickStart-C.md b/src/zh/UserGuide/develop/QuickStart/QuickStart-C.md index be71a062..9574787b 100644 --- a/src/zh/UserGuide/develop/QuickStart/QuickStart-C.md +++ b/src/zh/UserGuide/develop/QuickStart/QuickStart-C.md @@ -18,7 +18,7 @@ under the License. --> -# 快速上手 +# 快速上手 - C ## 依赖 diff --git a/src/zh/UserGuide/develop/QuickStart/QuickStart-CPP.md b/src/zh/UserGuide/develop/QuickStart/QuickStart-CPP.md index bb8e9432..d91f3d82 100644 --- a/src/zh/UserGuide/develop/QuickStart/QuickStart-CPP.md +++ b/src/zh/UserGuide/develop/QuickStart/QuickStart-CPP.md @@ -18,7 +18,7 @@ under the License. --> -# 快速上手 +# 快速上手 - Cpp ## 依赖 diff --git a/src/zh/UserGuide/develop/QuickStart/QuickStart-JAVA.md b/src/zh/UserGuide/develop/QuickStart/QuickStart-JAVA.md index d249749b..b0c195f0 100644 --- a/src/zh/UserGuide/develop/QuickStart/QuickStart-JAVA.md +++ b/src/zh/UserGuide/develop/QuickStart/QuickStart-JAVA.md @@ -18,7 +18,7 @@ under the License. --> -# 快速上手 +# 快速上手 - Java ## 依赖 diff --git a/src/zh/UserGuide/develop/QuickStart/QuickStart-PYTHON.md b/src/zh/UserGuide/develop/QuickStart/QuickStart-PYTHON.md index b42cfed0..6d0b32cd 100644 --- a/src/zh/UserGuide/develop/QuickStart/QuickStart-PYTHON.md +++ b/src/zh/UserGuide/develop/QuickStart/QuickStart-PYTHON.md @@ -18,7 +18,7 @@ under the License. --> -# 快速上手 +# 快速上手 - Python ## 依赖
