jt2594838 commented on code in PR #546: URL: https://github.com/apache/tsfile/pull/546#discussion_r2218063870
########## src/zh/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-Java.md: ########## @@ -0,0 +1,246 @@ +<!-- + + 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. + +--> +# 接口定义 - Java + +## 写入接口 + +### ITsFileWriter + +用于将数据写入 TsFile + +```Java +interface ITsFileWriter extends AutoCloseable { + // 写入数据 + void write(Tablet tablet); + + // 关闭写入器 + void close(); +} + +``` + +### TsFileWriterBuilder + +用于构建 ITsFileWriter + +```Java +class TsFileWriterBuilder { + // 构建 ITsFileWriter 对象 + public ITsFileWriter build(); + + // 目标文件 + public TsFileWriterBuilder file(File file); + + // 用于构建表结构 + public TsFileWriterBuilder tableSchema(TableSchema schema); + + // 用于限制写入时的内存使用大小 + public TsFileWriterBuilder memoryThreshold(long memoryThreshold); +} + +``` + +### TableSchema + +描述表结构的数据组织方式 + +```Java +class TableSchema { + // 构造函数 + public TableSchema(String tableName, List<ColumnSchema> columnSchemaList); +} + +class ColumnSchema { + // 构造函数 + public ColumnSchema(String columnName, TSDataType dataType, ColumnCategory columnCategory); + + // 获取列名 + public String getColumnName(); + + // 获取列的数据类型 + public TSDataType getDataType(); + + // 获取列的类别 + public Tablet.ColumnCategory getColumnCategory(); +} + +class ColumnSchemaBuilder { + // 构建 ColumnSchema 对象 + public ColumnSchema build(); + + // 设置列名 + public ColumnSchemaBuilder name(String columnName); + + // 设置列的数据类型 + public ColumnSchemaBuilder dataType(TSDataType columnType); + + // 设置列的类别 + public ColumnSchemaBuilder category(ColumnCategory columnCategory); + + // 支持的数据类型 + enum TSDataType { + BOOLEAN, // 布尔型 + INT32, // 32位整数 + INT64, // 64位整数 + FLOAT, // 单精度浮点数 + DOUBLE, // 双精度浮点数 + TIMESTAMP, // 时间戳 + TEXT, // 文本 + DATE, // 日期 + BLOB, // 二进制大对象 + STRING; // 字符串 + } + + // 支持的列类别 + enum ColumnCategory { + TAG, // 标签列 + FIELD // 字段列 Review Comment: 我们通常称之为测点列，最好使用统一的概念名。 ########## 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 要添加的值的类型。 Review Comment: 提示一下所支持的类型。 ########## 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，失败时返回非零错误码。 Review Comment: 提示一下错误码的定义放在哪个文件里。 -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: notifications-unsubscr...@tsfile.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
