jt2594838 commented on code in PR #441: URL: https://github.com/apache/tsfile/pull/441#discussion_r1997820620
########## src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md: ########## @@ -0,0 +1,494 @@ +<!-- + + 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. + +--> +# Interface definition + + + +## 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_VECTOR = 6, + TS_DATATYPE_STRING = 11, + TS_DATATYPE_NULL_TYPE = 254, + TS_DATATYPE_INVALID = 255 +} TSDataType; + +typedef enum { + TS_ENCODING_PLAIN = 0, + TS_ENCODING_DICTIONARY = 1, + TS_ENCODING_RLE = 2, + TS_ENCODING_DIFF = 3, + TS_ENCODING_TS_2DIFF = 4, + TS_ENCODING_BITMAP = 5, + TS_ENCODING_GORILLA_V1 = 6, + TS_ENCODING_REGULAR = 7, + TS_ENCODING_GORILLA = 8, + TS_ENCODING_ZIGZAG = 9, + TS_ENCODING_FREQ = 10, + TS_ENCODING_INVALID = 255 +} TSEncoding; + +typedef enum { + TS_COMPRESSION_UNCOMPRESSED = 0, + TS_COMPRESSION_SNAPPY = 1, + TS_COMPRESSION_GZIP = 2, + TS_COMPRESSION_LZO = 3, + TS_COMPRESSION_SDT = 4, + TS_COMPRESSION_PAA = 5, + TS_COMPRESSION_PLA = 6, + TS_COMPRESSION_LZ4 = 7, + TS_COMPRESSION_INVALID = 255 +} CompressionType; + +typedef enum column_category { TAG = 0, FIELD = 1 } ColumnCategory; + +// ColumnSchema: Represents the schema of a single column, +// including its name, data type, and category. +typedef struct column_schema { + char* column_name; + TSDataType data_type; + ColumnCategory column_category; +} ColumnSchema; + +// TableSchema: Defines the schema of a table, +// including its name and a list of column schemas. +typedef struct table_schema { + char* table_name; + ColumnSchema* column_schemas; + int column_num; +} TableSchema; + +// ResultSetMetaData: Contains metadata for a result set, +// such as column names and their data types. +typedef struct result_set_meta_data { + char** column_names; + TSDataType* data_types; + int column_num; +} ResultSetMetaData; +``` + + + + + + + +## Write Interface + +### TsFile WriteFile Create/Close + +```C +/** + * @brief Creates a file for writing. + * + * @param pathname Target file path to create. + * @param err_code [out] RET_OK(0), or check error code in errno_define_c.h. + * + * @return WriteFile Valid handle on success. + * + * @note Call free_write_file() to release resources. + * @note Before call free_write_file(), make sure TsFileWriter has been closed. + */ + +WriteFile write_file_new(const char* pathname, ERRNO* err_code); + +void free_write_file(WriteFile* write_file); +``` + +### TsFile Writer Create/Close + +When creating a TsFile Writer, you need to specify WriteFile and TableSchema. You can use the memory_threshold parameter to limit the memory usage of the Writer during data writing, but in the current version, this parameter does not take effect. + +```C +/** + * @brief Creates a TsFileWriter for writing a TsFile. + * + * @param file Target file where the table data will be written. + * @param schema Table schema definition. + * - Ownership: Should be free it by Caller. + * @param err_code [out] RET_OK(0), or check error code in errno_define_c.h. Review Comment: remove "check". ########## src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md: ########## @@ -0,0 +1,494 @@ +<!-- + + 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. + +--> +# Interface definition + + + +## 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_VECTOR = 6, + TS_DATATYPE_STRING = 11, + TS_DATATYPE_NULL_TYPE = 254, + TS_DATATYPE_INVALID = 255 +} TSDataType; Review Comment: Data types (and encodings and compressions) that are not meant for API or are deprcated, like VECTOR, NULL_TYPE, should not appear in the user guide. ########## src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md: ########## @@ -0,0 +1,277 @@ +<!-- + + 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. + +--> +# Interface Definitions + + + +## Schema + +```Python + +class ColumnSchema: + """Defines schema for a table column (name, datatype, category).""" + + column_name = None + data_type = None + + def __init__(self, column_name: str, data_type: TSDataType, + category: ColumnCategory = ColumnCategory.FIELD) + def get_column_name(self) + def get_data_type(self) + def get_category(self) + +class TableSchema: + """Schema definition for a table structure.""" + + table_name = None + columns = None + + def __init__(self, table_name: str, columns: List[ColumnSchema]) + def get_table_name(self) + def get_columns(self) + + +class ResultSetMetaData: + """Metadata container for query result sets (columns, types, table name).""" + + column_list = None + data_types = None + table_name = None + + def __init__(self, column_list: List[str], data_types: List[TSDataType]) + def set_table_name(self, table_name: str) Review Comment: These methods are not for API, remove them from the doc. The same below. ########## src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md: ########## @@ -0,0 +1,494 @@ +<!-- + + 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. + +--> +# Interface definition + + + +## 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_VECTOR = 6, + TS_DATATYPE_STRING = 11, + TS_DATATYPE_NULL_TYPE = 254, + TS_DATATYPE_INVALID = 255 +} TSDataType; + +typedef enum { + TS_ENCODING_PLAIN = 0, + TS_ENCODING_DICTIONARY = 1, + TS_ENCODING_RLE = 2, + TS_ENCODING_DIFF = 3, + TS_ENCODING_TS_2DIFF = 4, + TS_ENCODING_BITMAP = 5, + TS_ENCODING_GORILLA_V1 = 6, + TS_ENCODING_REGULAR = 7, + TS_ENCODING_GORILLA = 8, + TS_ENCODING_ZIGZAG = 9, + TS_ENCODING_FREQ = 10, + TS_ENCODING_INVALID = 255 +} TSEncoding; + +typedef enum { + TS_COMPRESSION_UNCOMPRESSED = 0, + TS_COMPRESSION_SNAPPY = 1, + TS_COMPRESSION_GZIP = 2, + TS_COMPRESSION_LZO = 3, + TS_COMPRESSION_SDT = 4, + TS_COMPRESSION_PAA = 5, + TS_COMPRESSION_PLA = 6, + TS_COMPRESSION_LZ4 = 7, + TS_COMPRESSION_INVALID = 255 +} CompressionType; + +typedef enum column_category { TAG = 0, FIELD = 1 } ColumnCategory; + +// ColumnSchema: Represents the schema of a single column, +// including its name, data type, and category. +typedef struct column_schema { + char* column_name; + TSDataType data_type; + ColumnCategory column_category; +} ColumnSchema; + +// TableSchema: Defines the schema of a table, +// including its name and a list of column schemas. +typedef struct table_schema { + char* table_name; + ColumnSchema* column_schemas; + int column_num; +} TableSchema; + +// ResultSetMetaData: Contains metadata for a result set, +// such as column names and their data types. +typedef struct result_set_meta_data { + char** column_names; + TSDataType* data_types; + int column_num; +} ResultSetMetaData; +``` + + + + + + + +## Write Interface + +### TsFile WriteFile Create/Close + +```C +/** + * @brief Creates a file for writing. + * + * @param pathname Target file path to create. + * @param err_code [out] RET_OK(0), or check error code in errno_define_c.h. + * + * @return WriteFile Valid handle on success. + * + * @note Call free_write_file() to release resources. + * @note Before call free_write_file(), make sure TsFileWriter has been closed. + */ + +WriteFile write_file_new(const char* pathname, ERRNO* err_code); + +void free_write_file(WriteFile* write_file); +``` + +### TsFile Writer Create/Close + +When creating a TsFile Writer, you need to specify WriteFile and TableSchema. You can use the memory_threshold parameter to limit the memory usage of the Writer during data writing, but in the current version, this parameter does not take effect. + +```C +/** + * @brief Creates a TsFileWriter for writing a TsFile. + * + * @param file Target file where the table data will be written. + * @param schema Table schema definition. + * - Ownership: Should be free it by Caller. + * @param err_code [out] RET_OK(0), or check error code in errno_define_c.h. + * + * @return TsFileWriter Valid handle on success, NULL on failure. + * + * @note Call tsfile_writer_close() to release resources. + */ +TsFileWriter tsfile_writer_new(WriteFile file, TableSchema* schema, + ERRNO* err_code); + +/** + * @brief Creates a TsFileWriter for writing a TsFile. + * + * @param file Target file where the table data will be written. + * @param schema Table schema definition. + * - Ownership: Should be free it by Caller. + * @param memory_threshold used to limit the memory size + * of objects. If set to 0, no memory limit is enforced. + * @param err_code [out] RET_OK(0), or check error code in errno_define_c.h. + * + * @return TsFileWriter Valid handle on success, NULL on failure. + * + * @note Call tsfile_writer_close() to release resources. + */ +TsFileWriter tsfile_writer_new_with_memory_threshold(WriteFile file, + TableSchema* schema, + uint64_t memory_threshold, + ERRNO* err_code); + +/** + * @brief Releases resources associated with a TsFileWriter. + * + * @param writer [in] Writer handle obtained from tsfile_writer_new(). + * After call: handle becomes invalid and must not be reused. + * @return ERRNO - RET_OK(0) on success, check error code in errno_define_c.h. + */ +ERRNO tsfile_writer_close(TsFileWriter writer); +``` + + + +### Tablet Create/Close/Insert data + +You can use Tablet to insert data into TsFile in batches, and you need to release the space occupied by the Tablet after use. + +```C +/** + * @brief Creates a Tablet for batch data. + * + * @param column_name_list [in] Column names array. Size=column_num. + * @param data_types [in] Data types array. Size=column_num. + * @param column_num [in] Number of columns. Must be ≥1. + * @param max_rows [in] Pre-allocated row capacity. Must be ≥1. + * @return Tablet Valid handle. + * @note Call free_tablet() to release resources. + */ +Tablet tablet_new(char** column_name_list, TSDataType* data_types, + uint32_t column_num, uint32_t max_rows); +/** + * @brief Gets current row count in the Tablet. + * + * @param tablet [in] Valid Tablet handle. + * @return uint32_t Row count (0 to max_rows-1). + */ +uint32_t tablet_get_cur_row_size(Tablet tablet); + +/** + * @brief Assigns timestamp to a row in the Tablet. + * + * @param tablet [in] Valid Tablet handle. + * @param row_index [in] Target row (0 ≤ index < max_rows). + * @param timestamp [in] Timestamp with int64_t type. + * @return ERRNO - RET_OK(0)/RET_OUT_OF_RANGE(5) or check errno_define_c.h. + */ +ERRNO tablet_add_timestamp(Tablet tablet, uint32_t row_index, + Timestamp timestamp); + +/** + * @brief Adds a string value to a Tablet row by column name. + * + * @param value [in] Null-terminated string. Ownership remains with caller. + * @return ERRNO. + */ +ERRNO tablet_add_value_by_name_string(Tablet tablet, uint32_t row_index, + const char* column_name, + const char* value); + +// Multi type support: +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 Adds a string value to a Tablet row by column index. + * + * @param value [in] Null-terminated string. Copied internally. + */ +ERRNO tablet_add_value_by_index_string(Tablet tablet, uint32_t row_index, + uint32_t column_index, + const char* value); + + +// Multi type support: +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); +``` + + + +### Write Tablet into TsFile + +```C +/** + * @brief Writes data from a Tablet to the TsFile. + * + * @param writer [in] Valid TsFileWriter handle. Must be initialized. + * @param tablet [in] Tablet containing data. Should be freed after successful + * write. + * @return ERRNO - RET_OK(0), or check error code in errno_define_c.h. + * + */ + +ERRNO tsfile_writer_write(TsFileWriter writer, Tablet tablet); +``` + + + + + +## Read Interface + +### TsFile Reader Create/Close + +```C +/** + * @brief Creates a TsFileReader for reading a TsFile. + * + * @param pathname Source TsFiles path. Must be a valid path. + * @param err_code RET_OK(0), or check error code in errno_define_c.h. + * @return TsFileReader Valid handle on success, NULL on failure. + * + * @note Call tsfile_reader_close() to release resources. + */ + +TsFileReader tsfile_reader_new(const char* pathname, ERRNO* err_code); + +/** + * @brief Releases resources associated with a TsFileReader. + * + * @param reader [in] Reader handle obtained from tsfile_reader_new(). + * After call: + * Handle becomes invalid and must not be reused. + * Result_set obtained by this handle becomes invalid. + * @return ERRNO - RET_OK(0) on success, or check error code in errno_define_c.h. + */ +ERRNO tsfile_reader_close(TsFileReader reader); +``` + + + +### Query table/get next + +```C + +/** + * @brief Queries time series data from a specific table within time range. + * + * @param reader [in] Valid TsFileReader handle from tsfile_reader_new(). + * @param table_name [in] Target table name. Must exist in the TS file. + * @param columns [in] Array of column names to fetch. + * @param column_num [in] Number of columns in array. + * @param start_time [in] Start timestamp. + * @param end_time [in] End timestamp. Must ≥ start_time. + * @return ResultSet Query results handle. Must be freed with + * 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 Check and fetch the next row in the ResultSet. + * + * @param result_set [in] Valid ResultSet handle. + * @return bool - true: Row available, false: End of data or error. + */ +bool tsfile_result_set_next(ResultSet result_set, ERRNO* error_code); + +/** + * @brief Free Result set + * + * @param result_set [in] Valid ResultSet handle ptr. + */ +void free_tsfile_result_set(ResultSet* result_set); +``` + + + +### Get Data from result set + +```c +/** + * @brief Checks if the current row's column value is NULL by column name. + * + * @param result_set [in] Valid ResultSet with active row (after next()=true). + * @param column_name [in] Existing column name in result schema. + * @return bool - true: Value is NULL or column not found, false: Valid value. + */ +bool tsfile_result_set_is_null_by_name(ResultSet result_set, + const char* column_name); + +/** + * @brief Checks if the current row's column value is NULL by column index. + * + * @param column_index [in] Column position (0 ≤ index < result_column_count). Review Comment: 1 <= index <= result_column_count ########## src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md: ########## @@ -0,0 +1,277 @@ +<!-- + + 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. + +--> +# Interface Definitions + + + +## Schema + +```Python + +class ColumnSchema: + """Defines schema for a table column (name, datatype, category).""" + + column_name = None + data_type = None + + def __init__(self, column_name: str, data_type: TSDataType, + category: ColumnCategory = ColumnCategory.FIELD) + def get_column_name(self) + def get_data_type(self) + def get_category(self) + +class TableSchema: + """Schema definition for a table structure.""" + + table_name = None + columns = None + + def __init__(self, table_name: str, columns: List[ColumnSchema]) + def get_table_name(self) + def get_columns(self) + + +class ResultSetMetaData: + """Metadata container for query result sets (columns, types, table name).""" + + column_list = None + data_types = None + table_name = None + + def __init__(self, column_list: List[str], data_types: List[TSDataType]) + def set_table_name(self, table_name: str) + def get_data_type(self, column_index: int) -> TSDataType + def get_column_name(self, column_index: int) -> str + def get_column_name_index(self, column_name: str) -> int + def get_column_num(self) + def get_column_list(self) + def get_data_type_list(self) + +``` + + + +## Write interface + +### TsFileWriter + +```python +class TsFileTableWriter: + """ + Facilitates writing structured table data into a TsFile with a specified schema. + + The TsFileTableWriter class is designed to write structured data, + particularly suitable for time-series data, into a file optimized for + efficient storage and retrieval (referred to as TsFile here). It allows users + to define the schema of the tables they want to write, add rows of data + according to that schema, and serialize this data into a TsFile. + """ + + + """ + :param path: The path of tsfile, will create if it doesn't exist. + :param table_schema: describes the schema of the tables they want to write. + """ + def __init__(self, path: str, table_schema: TableSchema) + + + """ + Write a tablet into table in tsfile. + :param tablet: stored batch data of a table. + :return: no return value. + :raise: TableNotExistError if table does not exist or tablet's table_name does not match tableschema. + """ + def write_table(self, tablet: Tablet) + + + """ + Close TsFileTableWriter and will flush data automatically. + :return: no return value. + """ + def close(self) + +``` + + + +### Tablet definition + +You can use Tablet to insert data into TsFile in batches, and you need to release the space occupied by the Tablet after use. + +```Python +class Tablet(object) + """ + A pre-allocated columnar data container for batch data with type constraints. + + Initializes: + - column_name_list: Ordered names for data columns + - type_list: TSDataType values specifying allowed types per column + - max_row_num: Pre-allocated row capacity (default 1024) + + Creates timestamp buffer and typed data columns, with value range validation ranges + for numeric types. + """ + + def __init__(self, column_name_list: list[str], type_list: list[TSDataType], + max_row_num: int = 1024) + + + def set_table_name(self, table_name: str) + def get_column_name_list(self) + def get_data_type_list(self) + def get_timestamp_list(self) + def get_target_name(self) + def get_value_list(self) + def get_max_row_num(self) + def add_column(self, column_name: str, column_type: TSDataType) + def remove_column(self, column_name: str) + def set_timestamp_list(self, timestamp_list: list[int]) + def add_timestamp(self, row_index: int, timestamp: int) + def add_value_by_name(self, column_name: str, row_index: int, value: Union[int, float, bool, str, bytes]) + def add_value_by_index(self, col_index: int, row_index: int, value: Union[int, float, bool, str, bytes]) + def get_value_by_index(self, col_index: int, row_index: int) + def get_value_by_name(self, column_name: str, row_index: int) + def get_value_list_by_name(self, column_name: str) +``` + + + +## Read Interface + +### TsFileReader + +```python +class TsFileReader: + """ + Read and query table data from TsFiles. + """ + + + """ + Initialize a TsFile reader for the specified file path. + """ + def __init__(self, pathname) + + + """ + Execute a time range query on specified table and columns. + :return: query result handler. + """ + def query_table(self, table_name : str, column_names : List[str], + start_time : int = 0, end_time : int = 0) -> ResultSetPy Review Comment: Default start_time and end_time should be INT64.MIN and INT64.MAX. ########## src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md: ########## @@ -0,0 +1,494 @@ +<!-- + + 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. + +--> +# Interface definition + + + +## 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_VECTOR = 6, + TS_DATATYPE_STRING = 11, + TS_DATATYPE_NULL_TYPE = 254, + TS_DATATYPE_INVALID = 255 +} TSDataType; + +typedef enum { + TS_ENCODING_PLAIN = 0, + TS_ENCODING_DICTIONARY = 1, + TS_ENCODING_RLE = 2, + TS_ENCODING_DIFF = 3, + TS_ENCODING_TS_2DIFF = 4, + TS_ENCODING_BITMAP = 5, + TS_ENCODING_GORILLA_V1 = 6, + TS_ENCODING_REGULAR = 7, + TS_ENCODING_GORILLA = 8, + TS_ENCODING_ZIGZAG = 9, + TS_ENCODING_FREQ = 10, + TS_ENCODING_INVALID = 255 +} TSEncoding; + +typedef enum { + TS_COMPRESSION_UNCOMPRESSED = 0, + TS_COMPRESSION_SNAPPY = 1, + TS_COMPRESSION_GZIP = 2, + TS_COMPRESSION_LZO = 3, + TS_COMPRESSION_SDT = 4, + TS_COMPRESSION_PAA = 5, + TS_COMPRESSION_PLA = 6, + TS_COMPRESSION_LZ4 = 7, + TS_COMPRESSION_INVALID = 255 +} CompressionType; + +typedef enum column_category { TAG = 0, FIELD = 1 } ColumnCategory; + +// ColumnSchema: Represents the schema of a single column, +// including its name, data type, and category. +typedef struct column_schema { + char* column_name; + TSDataType data_type; + ColumnCategory column_category; +} ColumnSchema; + +// TableSchema: Defines the schema of a table, +// including its name and a list of column schemas. +typedef struct table_schema { + char* table_name; + ColumnSchema* column_schemas; + int column_num; +} TableSchema; + +// ResultSetMetaData: Contains metadata for a result set, +// such as column names and their data types. +typedef struct result_set_meta_data { + char** column_names; + TSDataType* data_types; + int column_num; +} ResultSetMetaData; +``` + + + + + + + +## Write Interface + +### TsFile WriteFile Create/Close + +```C +/** + * @brief Creates a file for writing. + * + * @param pathname Target file path to create. + * @param err_code [out] RET_OK(0), or check error code in errno_define_c.h. + * + * @return WriteFile Valid handle on success. + * + * @note Call free_write_file() to release resources. + * @note Before call free_write_file(), make sure TsFileWriter has been closed. + */ + +WriteFile write_file_new(const char* pathname, ERRNO* err_code); + +void free_write_file(WriteFile* write_file); +``` + +### TsFile Writer Create/Close + +When creating a TsFile Writer, you need to specify WriteFile and TableSchema. You can use the memory_threshold parameter to limit the memory usage of the Writer during data writing, but in the current version, this parameter does not take effect. Review Comment: "memory_threshold" is not in this method. ########## src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md: ########## @@ -0,0 +1,494 @@ +<!-- + + 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. + +--> +# Interface definition + + + +## 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_VECTOR = 6, + TS_DATATYPE_STRING = 11, + TS_DATATYPE_NULL_TYPE = 254, + TS_DATATYPE_INVALID = 255 +} TSDataType; + +typedef enum { + TS_ENCODING_PLAIN = 0, + TS_ENCODING_DICTIONARY = 1, + TS_ENCODING_RLE = 2, + TS_ENCODING_DIFF = 3, + TS_ENCODING_TS_2DIFF = 4, + TS_ENCODING_BITMAP = 5, + TS_ENCODING_GORILLA_V1 = 6, + TS_ENCODING_REGULAR = 7, + TS_ENCODING_GORILLA = 8, + TS_ENCODING_ZIGZAG = 9, + TS_ENCODING_FREQ = 10, + TS_ENCODING_INVALID = 255 +} TSEncoding; + +typedef enum { + TS_COMPRESSION_UNCOMPRESSED = 0, + TS_COMPRESSION_SNAPPY = 1, + TS_COMPRESSION_GZIP = 2, + TS_COMPRESSION_LZO = 3, + TS_COMPRESSION_SDT = 4, + TS_COMPRESSION_PAA = 5, + TS_COMPRESSION_PLA = 6, + TS_COMPRESSION_LZ4 = 7, + TS_COMPRESSION_INVALID = 255 +} CompressionType; + +typedef enum column_category { TAG = 0, FIELD = 1 } ColumnCategory; + +// ColumnSchema: Represents the schema of a single column, +// including its name, data type, and category. +typedef struct column_schema { + char* column_name; + TSDataType data_type; + ColumnCategory column_category; +} ColumnSchema; + +// TableSchema: Defines the schema of a table, +// including its name and a list of column schemas. +typedef struct table_schema { + char* table_name; + ColumnSchema* column_schemas; + int column_num; +} TableSchema; + +// ResultSetMetaData: Contains metadata for a result set, +// such as column names and their data types. +typedef struct result_set_meta_data { + char** column_names; + TSDataType* data_types; + int column_num; +} ResultSetMetaData; +``` + + + + + + + +## Write Interface + +### TsFile WriteFile Create/Close + +```C +/** + * @brief Creates a file for writing. + * + * @param pathname Target file path to create. + * @param err_code [out] RET_OK(0), or check error code in errno_define_c.h. + * + * @return WriteFile Valid handle on success. + * + * @note Call free_write_file() to release resources. + * @note Before call free_write_file(), make sure TsFileWriter has been closed. + */ + +WriteFile write_file_new(const char* pathname, ERRNO* err_code); + +void free_write_file(WriteFile* write_file); +``` + +### TsFile Writer Create/Close + +When creating a TsFile Writer, you need to specify WriteFile and TableSchema. You can use the memory_threshold parameter to limit the memory usage of the Writer during data writing, but in the current version, this parameter does not take effect. + +```C +/** + * @brief Creates a TsFileWriter for writing a TsFile. + * + * @param file Target file where the table data will be written. + * @param schema Table schema definition. + * - Ownership: Should be free it by Caller. + * @param err_code [out] RET_OK(0), or check error code in errno_define_c.h. + * + * @return TsFileWriter Valid handle on success, NULL on failure. + * + * @note Call tsfile_writer_close() to release resources. + */ +TsFileWriter tsfile_writer_new(WriteFile file, TableSchema* schema, + ERRNO* err_code); + +/** + * @brief Creates a TsFileWriter for writing a TsFile. + * + * @param file Target file where the table data will be written. + * @param schema Table schema definition. + * - Ownership: Should be free it by Caller. + * @param memory_threshold used to limit the memory size + * of objects. If set to 0, no memory limit is enforced. + * @param err_code [out] RET_OK(0), or check error code in errno_define_c.h. + * + * @return TsFileWriter Valid handle on success, NULL on failure. + * + * @note Call tsfile_writer_close() to release resources. + */ +TsFileWriter tsfile_writer_new_with_memory_threshold(WriteFile file, + TableSchema* schema, + uint64_t memory_threshold, + ERRNO* err_code); + +/** + * @brief Releases resources associated with a TsFileWriter. + * + * @param writer [in] Writer handle obtained from tsfile_writer_new(). + * After call: handle becomes invalid and must not be reused. + * @return ERRNO - RET_OK(0) on success, check error code in errno_define_c.h. + */ +ERRNO tsfile_writer_close(TsFileWriter writer); +``` + + + +### Tablet Create/Close/Insert data + +You can use Tablet to insert data into TsFile in batches, and you need to release the space occupied by the Tablet after use. + +```C +/** + * @brief Creates a Tablet for batch data. + * + * @param column_name_list [in] Column names array. Size=column_num. + * @param data_types [in] Data types array. Size=column_num. + * @param column_num [in] Number of columns. Must be ≥1. + * @param max_rows [in] Pre-allocated row capacity. Must be ≥1. + * @return Tablet Valid handle. + * @note Call free_tablet() to release resources. + */ +Tablet tablet_new(char** column_name_list, TSDataType* data_types, + uint32_t column_num, uint32_t max_rows); +/** + * @brief Gets current row count in the Tablet. + * + * @param tablet [in] Valid Tablet handle. + * @return uint32_t Row count (0 to max_rows-1). + */ +uint32_t tablet_get_cur_row_size(Tablet tablet); + +/** + * @brief Assigns timestamp to a row in the Tablet. + * + * @param tablet [in] Valid Tablet handle. + * @param row_index [in] Target row (0 ≤ index < max_rows). + * @param timestamp [in] Timestamp with int64_t type. + * @return ERRNO - RET_OK(0)/RET_OUT_OF_RANGE(5) or check errno_define_c.h. + */ +ERRNO tablet_add_timestamp(Tablet tablet, uint32_t row_index, + Timestamp timestamp); + +/** + * @brief Adds a string value to a Tablet row by column name. + * + * @param value [in] Null-terminated string. Ownership remains with caller. + * @return ERRNO. + */ +ERRNO tablet_add_value_by_name_string(Tablet tablet, uint32_t row_index, + const char* column_name, + const char* value); + +// Multi type support: +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 Adds a string value to a Tablet row by column index. + * + * @param value [in] Null-terminated string. Copied internally. + */ +ERRNO tablet_add_value_by_index_string(Tablet tablet, uint32_t row_index, + uint32_t column_index, + const char* value); + + +// Multi type support: +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); +``` + + + +### Write Tablet into TsFile + +```C +/** + * @brief Writes data from a Tablet to the TsFile. + * + * @param writer [in] Valid TsFileWriter handle. Must be initialized. + * @param tablet [in] Tablet containing data. Should be freed after successful + * write. + * @return ERRNO - RET_OK(0), or check error code in errno_define_c.h. + * + */ + +ERRNO tsfile_writer_write(TsFileWriter writer, Tablet tablet); +``` + + + + + +## Read Interface + +### TsFile Reader Create/Close + +```C +/** + * @brief Creates a TsFileReader for reading a TsFile. + * + * @param pathname Source TsFiles path. Must be a valid path. + * @param err_code RET_OK(0), or check error code in errno_define_c.h. + * @return TsFileReader Valid handle on success, NULL on failure. + * + * @note Call tsfile_reader_close() to release resources. + */ + +TsFileReader tsfile_reader_new(const char* pathname, ERRNO* err_code); + +/** + * @brief Releases resources associated with a TsFileReader. + * + * @param reader [in] Reader handle obtained from tsfile_reader_new(). + * After call: + * Handle becomes invalid and must not be reused. + * Result_set obtained by this handle becomes invalid. + * @return ERRNO - RET_OK(0) on success, or check error code in errno_define_c.h. + */ +ERRNO tsfile_reader_close(TsFileReader reader); +``` + + + +### Query table/get next + +```C + +/** + * @brief Queries time series data from a specific table within time range. + * + * @param reader [in] Valid TsFileReader handle from tsfile_reader_new(). + * @param table_name [in] Target table name. Must exist in the TS file. + * @param columns [in] Array of column names to fetch. + * @param column_num [in] Number of columns in array. + * @param start_time [in] Start timestamp. + * @param end_time [in] End timestamp. Must ≥ start_time. + * @return ResultSet Query results handle. Must be freed with + * 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 Check and fetch the next row in the ResultSet. + * + * @param result_set [in] Valid ResultSet handle. + * @return bool - true: Row available, false: End of data or error. + */ +bool tsfile_result_set_next(ResultSet result_set, ERRNO* error_code); + +/** + * @brief Free Result set + * + * @param result_set [in] Valid ResultSet handle ptr. + */ +void free_tsfile_result_set(ResultSet* result_set); +``` + + + +### Get Data from result set + +```c +/** + * @brief Checks if the current row's column value is NULL by column name. + * + * @param result_set [in] Valid ResultSet with active row (after next()=true). + * @param column_name [in] Existing column name in result schema. + * @return bool - true: Value is NULL or column not found, false: Valid value. + */ +bool tsfile_result_set_is_null_by_name(ResultSet result_set, + const char* column_name); + +/** + * @brief Checks if the current row's column value is NULL by column index. + * + * @param column_index [in] Column position (0 ≤ index < result_column_count). + * @return bool - true: Value is NULL or index out of range, false: Valid value. + */ +bool tsfile_result_set_is_null_by_index(ResultSet result_set, + uint32_t column_index); + +/** + * @brief Gets string value from current row by column name. + * + * @return char* - String pointer. Caller must free this ptr after usage. + */ +char* tsfile_result_set_get_value_by_name_string(ResultSet result_set, + const char* column_name); + +// Multi type support +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 Gets string value from current row by column index. + * + * @return char* - String pointer. Caller must free this ptr after usage. Review Comment: @param column_index ########## src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md: ########## @@ -0,0 +1,494 @@ +<!-- + + 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. + +--> +# Interface definition + + + +## 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_VECTOR = 6, + TS_DATATYPE_STRING = 11, + TS_DATATYPE_NULL_TYPE = 254, + TS_DATATYPE_INVALID = 255 +} TSDataType; + +typedef enum { + TS_ENCODING_PLAIN = 0, + TS_ENCODING_DICTIONARY = 1, + TS_ENCODING_RLE = 2, + TS_ENCODING_DIFF = 3, + TS_ENCODING_TS_2DIFF = 4, + TS_ENCODING_BITMAP = 5, + TS_ENCODING_GORILLA_V1 = 6, + TS_ENCODING_REGULAR = 7, + TS_ENCODING_GORILLA = 8, + TS_ENCODING_ZIGZAG = 9, + TS_ENCODING_FREQ = 10, + TS_ENCODING_INVALID = 255 +} TSEncoding; + +typedef enum { + TS_COMPRESSION_UNCOMPRESSED = 0, + TS_COMPRESSION_SNAPPY = 1, + TS_COMPRESSION_GZIP = 2, + TS_COMPRESSION_LZO = 3, + TS_COMPRESSION_SDT = 4, + TS_COMPRESSION_PAA = 5, + TS_COMPRESSION_PLA = 6, + TS_COMPRESSION_LZ4 = 7, + TS_COMPRESSION_INVALID = 255 +} CompressionType; + +typedef enum column_category { TAG = 0, FIELD = 1 } ColumnCategory; + +// ColumnSchema: Represents the schema of a single column, +// including its name, data type, and category. +typedef struct column_schema { + char* column_name; + TSDataType data_type; + ColumnCategory column_category; +} ColumnSchema; + +// TableSchema: Defines the schema of a table, +// including its name and a list of column schemas. +typedef struct table_schema { + char* table_name; + ColumnSchema* column_schemas; + int column_num; +} TableSchema; + +// ResultSetMetaData: Contains metadata for a result set, +// such as column names and their data types. +typedef struct result_set_meta_data { + char** column_names; + TSDataType* data_types; + int column_num; +} ResultSetMetaData; +``` + + + + + + + +## Write Interface + +### TsFile WriteFile Create/Close + +```C +/** + * @brief Creates a file for writing. + * + * @param pathname Target file path to create. + * @param err_code [out] RET_OK(0), or check error code in errno_define_c.h. + * + * @return WriteFile Valid handle on success. + * + * @note Call free_write_file() to release resources. + * @note Before call free_write_file(), make sure TsFileWriter has been closed. + */ + +WriteFile write_file_new(const char* pathname, ERRNO* err_code); + +void free_write_file(WriteFile* write_file); +``` + +### TsFile Writer Create/Close + +When creating a TsFile Writer, you need to specify WriteFile and TableSchema. You can use the memory_threshold parameter to limit the memory usage of the Writer during data writing, but in the current version, this parameter does not take effect. + +```C +/** + * @brief Creates a TsFileWriter for writing a TsFile. + * + * @param file Target file where the table data will be written. + * @param schema Table schema definition. + * - Ownership: Should be free it by Caller. Review Comment: Should be freed by the caller. ########## src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md: ########## @@ -0,0 +1,277 @@ +<!-- + + 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. + +--> +# Interface Definitions + + + +## Schema + +```Python + +class ColumnSchema: + """Defines schema for a table column (name, datatype, category).""" + + column_name = None + data_type = None + + def __init__(self, column_name: str, data_type: TSDataType, Review Comment: Where is category? ########## src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md: ########## @@ -0,0 +1,494 @@ +<!-- + + 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. + +--> +# Interface definition + + + +## 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_VECTOR = 6, + TS_DATATYPE_STRING = 11, + TS_DATATYPE_NULL_TYPE = 254, + TS_DATATYPE_INVALID = 255 +} TSDataType; + +typedef enum { + TS_ENCODING_PLAIN = 0, + TS_ENCODING_DICTIONARY = 1, + TS_ENCODING_RLE = 2, + TS_ENCODING_DIFF = 3, + TS_ENCODING_TS_2DIFF = 4, + TS_ENCODING_BITMAP = 5, + TS_ENCODING_GORILLA_V1 = 6, + TS_ENCODING_REGULAR = 7, + TS_ENCODING_GORILLA = 8, + TS_ENCODING_ZIGZAG = 9, + TS_ENCODING_FREQ = 10, + TS_ENCODING_INVALID = 255 +} TSEncoding; + +typedef enum { + TS_COMPRESSION_UNCOMPRESSED = 0, + TS_COMPRESSION_SNAPPY = 1, + TS_COMPRESSION_GZIP = 2, + TS_COMPRESSION_LZO = 3, + TS_COMPRESSION_SDT = 4, + TS_COMPRESSION_PAA = 5, + TS_COMPRESSION_PLA = 6, + TS_COMPRESSION_LZ4 = 7, + TS_COMPRESSION_INVALID = 255 +} CompressionType; + +typedef enum column_category { TAG = 0, FIELD = 1 } ColumnCategory; + +// ColumnSchema: Represents the schema of a single column, +// including its name, data type, and category. +typedef struct column_schema { + char* column_name; + TSDataType data_type; + ColumnCategory column_category; +} ColumnSchema; + +// TableSchema: Defines the schema of a table, +// including its name and a list of column schemas. +typedef struct table_schema { + char* table_name; + ColumnSchema* column_schemas; + int column_num; +} TableSchema; + +// ResultSetMetaData: Contains metadata for a result set, +// such as column names and their data types. +typedef struct result_set_meta_data { + char** column_names; + TSDataType* data_types; + int column_num; +} ResultSetMetaData; +``` + + + + + + + +## Write Interface + +### TsFile WriteFile Create/Close + +```C +/** + * @brief Creates a file for writing. + * + * @param pathname Target file path to create. + * @param err_code [out] RET_OK(0), or check error code in errno_define_c.h. + * + * @return WriteFile Valid handle on success. + * + * @note Call free_write_file() to release resources. + * @note Before call free_write_file(), make sure TsFileWriter has been closed. + */ + +WriteFile write_file_new(const char* pathname, ERRNO* err_code); + +void free_write_file(WriteFile* write_file); +``` + +### TsFile Writer Create/Close + +When creating a TsFile Writer, you need to specify WriteFile and TableSchema. You can use the memory_threshold parameter to limit the memory usage of the Writer during data writing, but in the current version, this parameter does not take effect. + +```C +/** + * @brief Creates a TsFileWriter for writing a TsFile. + * + * @param file Target file where the table data will be written. + * @param schema Table schema definition. + * - Ownership: Should be free it by Caller. + * @param err_code [out] RET_OK(0), or check error code in errno_define_c.h. + * + * @return TsFileWriter Valid handle on success, NULL on failure. + * + * @note Call tsfile_writer_close() to release resources. + */ +TsFileWriter tsfile_writer_new(WriteFile file, TableSchema* schema, + ERRNO* err_code); + +/** + * @brief Creates a TsFileWriter for writing a TsFile. + * + * @param file Target file where the table data will be written. + * @param schema Table schema definition. + * - Ownership: Should be free it by Caller. + * @param memory_threshold used to limit the memory size + * of objects. If set to 0, no memory limit is enforced. + * @param err_code [out] RET_OK(0), or check error code in errno_define_c.h. + * + * @return TsFileWriter Valid handle on success, NULL on failure. + * + * @note Call tsfile_writer_close() to release resources. + */ +TsFileWriter tsfile_writer_new_with_memory_threshold(WriteFile file, + TableSchema* schema, + uint64_t memory_threshold, + ERRNO* err_code); + +/** + * @brief Releases resources associated with a TsFileWriter. + * + * @param writer [in] Writer handle obtained from tsfile_writer_new(). + * After call: handle becomes invalid and must not be reused. + * @return ERRNO - RET_OK(0) on success, check error code in errno_define_c.h. + */ +ERRNO tsfile_writer_close(TsFileWriter writer); +``` + + + +### Tablet Create/Close/Insert data + +You can use Tablet to insert data into TsFile in batches, and you need to release the space occupied by the Tablet after use. + +```C +/** + * @brief Creates a Tablet for batch data. + * + * @param column_name_list [in] Column names array. Size=column_num. + * @param data_types [in] Data types array. Size=column_num. + * @param column_num [in] Number of columns. Must be ≥1. + * @param max_rows [in] Pre-allocated row capacity. Must be ≥1. + * @return Tablet Valid handle. + * @note Call free_tablet() to release resources. + */ +Tablet tablet_new(char** column_name_list, TSDataType* data_types, + uint32_t column_num, uint32_t max_rows); +/** + * @brief Gets current row count in the Tablet. + * + * @param tablet [in] Valid Tablet handle. + * @return uint32_t Row count (0 to max_rows-1). + */ +uint32_t tablet_get_cur_row_size(Tablet tablet); + +/** + * @brief Assigns timestamp to a row in the Tablet. + * + * @param tablet [in] Valid Tablet handle. + * @param row_index [in] Target row (0 ≤ index < max_rows). + * @param timestamp [in] Timestamp with int64_t type. + * @return ERRNO - RET_OK(0)/RET_OUT_OF_RANGE(5) or check errno_define_c.h. + */ +ERRNO tablet_add_timestamp(Tablet tablet, uint32_t row_index, + Timestamp timestamp); + +/** + * @brief Adds a string value to a Tablet row by column name. + * + * @param value [in] Null-terminated string. Ownership remains with caller. + * @return ERRNO. + */ +ERRNO tablet_add_value_by_name_string(Tablet tablet, uint32_t row_index, + const char* column_name, + const char* value); + +// Multi type support: +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 Adds a string value to a Tablet row by column index. + * + * @param value [in] Null-terminated string. Copied internally. + */ +ERRNO tablet_add_value_by_index_string(Tablet tablet, uint32_t row_index, + uint32_t column_index, + const char* value); + + +// Multi type support: +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); +``` + + + +### Write Tablet into TsFile + +```C +/** + * @brief Writes data from a Tablet to the TsFile. + * + * @param writer [in] Valid TsFileWriter handle. Must be initialized. + * @param tablet [in] Tablet containing data. Should be freed after successful + * write. + * @return ERRNO - RET_OK(0), or check error code in errno_define_c.h. + * + */ + +ERRNO tsfile_writer_write(TsFileWriter writer, Tablet tablet); +``` + + + + + +## Read Interface + +### TsFile Reader Create/Close + +```C +/** + * @brief Creates a TsFileReader for reading a TsFile. + * + * @param pathname Source TsFiles path. Must be a valid path. + * @param err_code RET_OK(0), or check error code in errno_define_c.h. + * @return TsFileReader Valid handle on success, NULL on failure. + * + * @note Call tsfile_reader_close() to release resources. + */ + +TsFileReader tsfile_reader_new(const char* pathname, ERRNO* err_code); + +/** + * @brief Releases resources associated with a TsFileReader. + * + * @param reader [in] Reader handle obtained from tsfile_reader_new(). + * After call: + * Handle becomes invalid and must not be reused. + * Result_set obtained by this handle becomes invalid. + * @return ERRNO - RET_OK(0) on success, or check error code in errno_define_c.h. + */ +ERRNO tsfile_reader_close(TsFileReader reader); +``` + + + +### Query table/get next + +```C + +/** + * @brief Queries time series data from a specific table within time range. + * + * @param reader [in] Valid TsFileReader handle from tsfile_reader_new(). + * @param table_name [in] Target table name. Must exist in the TS file. + * @param columns [in] Array of column names to fetch. + * @param column_num [in] Number of columns in array. + * @param start_time [in] Start timestamp. + * @param end_time [in] End timestamp. Must ≥ start_time. + * @return ResultSet Query results handle. Must be freed with + * 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 Check and fetch the next row in the ResultSet. + * + * @param result_set [in] Valid ResultSet handle. + * @return bool - true: Row available, false: End of data or error. + */ +bool tsfile_result_set_next(ResultSet result_set, ERRNO* error_code); + +/** + * @brief Free Result set + * + * @param result_set [in] Valid ResultSet handle ptr. + */ +void free_tsfile_result_set(ResultSet* result_set); +``` + + + +### Get Data from result set + +```c +/** + * @brief Checks if the current row's column value is NULL by column name. + * + * @param result_set [in] Valid ResultSet with active row (after next()=true). + * @param column_name [in] Existing column name in result schema. + * @return bool - true: Value is NULL or column not found, false: Valid value. + */ +bool tsfile_result_set_is_null_by_name(ResultSet result_set, + const char* column_name); + +/** + * @brief Checks if the current row's column value is NULL by column index. + * + * @param column_index [in] Column position (0 ≤ index < result_column_count). + * @return bool - true: Value is NULL or index out of range, false: Valid value. + */ +bool tsfile_result_set_is_null_by_index(ResultSet result_set, + uint32_t column_index); + +/** + * @brief Gets string value from current row by column name. + * + * @return char* - String pointer. Caller must free this ptr after usage. + */ +char* tsfile_result_set_get_value_by_name_string(ResultSet result_set, + const char* column_name); + +// Multi type support +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 Gets string value from current row by column index. + * + * @return char* - String pointer. Caller must free this ptr after usage. + */ +char* tsfile_result_set_get_value_by_index_string(ResultSet result_set, + uint32_t column_index); + +// Multi type support +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 Retrieves metadata describing the ResultSet's schema. + * + * @param result_set [in] Valid ResultSet handle. + * @return ResultSetMetaData Metadata handle. Caller should free the + * ResultSetMataData after usage. + * @note Before calling this func, check if result_set is NULL, which means + * the query may be not correct. + */ +ResultSetMetaData tsfile_result_set_get_metadata(ResultSet result_set); + +/** + * @brief Gets column name by index from metadata. + * + * @param column_index [in] Column position (0 ≤ index < column_num). + * @return const char* Read-only string. NULL if index invalid. + */ +char* tsfile_result_set_metadata_get_column_name(ResultSetMetaData result_set, + uint32_t column_index); + +/** + * @brief Gets column data type by index from metadata. + * + * @return TSDataType Returns TS_DATATYPE_INVALID(255) if index invalid. + */ +TSDataType tsfile_result_set_metadata_get_data_type( + ResultSetMetaData result_set, uint32_t column_index); + +/** + * @brief Gets total number of columns in the result schema. + * + * @return column num in result set metadata. + */ +int tsfile_result_set_metadata_get_column_num(ResultSetMetaData result_set); +``` + + + +### Get Table Schema from TsFile Reader + +```C +/** + * @brief Gets specific table's schema in the tsfile. + * + * @return TableSchema, contains table and column info. + * @note Caller should call free_table_schema to free the tableschema. + */ +TableSchema tsfile_reader_get_table_schema(TsFileReader reader, + const char* table_name); +/** + * @brief Gets all table schema in the tsfile. + * + * @return TableSchema, contains table and column info. + * @note Caller should call free_table_schema and free to free the ptr. Review Comment: Caller should first call free_table_schema to free each element in the array, and then free the array ptr. ########## src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md: ########## @@ -0,0 +1,494 @@ +<!-- + + 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. + +--> +# Interface definition + + + +## 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_VECTOR = 6, + TS_DATATYPE_STRING = 11, + TS_DATATYPE_NULL_TYPE = 254, + TS_DATATYPE_INVALID = 255 +} TSDataType; + +typedef enum { + TS_ENCODING_PLAIN = 0, + TS_ENCODING_DICTIONARY = 1, + TS_ENCODING_RLE = 2, + TS_ENCODING_DIFF = 3, + TS_ENCODING_TS_2DIFF = 4, + TS_ENCODING_BITMAP = 5, + TS_ENCODING_GORILLA_V1 = 6, + TS_ENCODING_REGULAR = 7, + TS_ENCODING_GORILLA = 8, + TS_ENCODING_ZIGZAG = 9, + TS_ENCODING_FREQ = 10, + TS_ENCODING_INVALID = 255 +} TSEncoding; + +typedef enum { + TS_COMPRESSION_UNCOMPRESSED = 0, + TS_COMPRESSION_SNAPPY = 1, + TS_COMPRESSION_GZIP = 2, + TS_COMPRESSION_LZO = 3, + TS_COMPRESSION_SDT = 4, + TS_COMPRESSION_PAA = 5, + TS_COMPRESSION_PLA = 6, + TS_COMPRESSION_LZ4 = 7, + TS_COMPRESSION_INVALID = 255 +} CompressionType; + +typedef enum column_category { TAG = 0, FIELD = 1 } ColumnCategory; + +// ColumnSchema: Represents the schema of a single column, +// including its name, data type, and category. +typedef struct column_schema { + char* column_name; + TSDataType data_type; + ColumnCategory column_category; +} ColumnSchema; + +// TableSchema: Defines the schema of a table, +// including its name and a list of column schemas. +typedef struct table_schema { + char* table_name; + ColumnSchema* column_schemas; + int column_num; +} TableSchema; + +// ResultSetMetaData: Contains metadata for a result set, +// such as column names and their data types. +typedef struct result_set_meta_data { + char** column_names; + TSDataType* data_types; + int column_num; +} ResultSetMetaData; +``` + + + + + + + +## Write Interface + +### TsFile WriteFile Create/Close + +```C +/** + * @brief Creates a file for writing. + * + * @param pathname Target file path to create. + * @param err_code [out] RET_OK(0), or check error code in errno_define_c.h. + * + * @return WriteFile Valid handle on success. + * + * @note Call free_write_file() to release resources. + * @note Before call free_write_file(), make sure TsFileWriter has been closed. + */ + +WriteFile write_file_new(const char* pathname, ERRNO* err_code); + +void free_write_file(WriteFile* write_file); +``` + +### TsFile Writer Create/Close + +When creating a TsFile Writer, you need to specify WriteFile and TableSchema. You can use the memory_threshold parameter to limit the memory usage of the Writer during data writing, but in the current version, this parameter does not take effect. + +```C +/** + * @brief Creates a TsFileWriter for writing a TsFile. + * + * @param file Target file where the table data will be written. + * @param schema Table schema definition. + * - Ownership: Should be free it by Caller. + * @param err_code [out] RET_OK(0), or check error code in errno_define_c.h. + * + * @return TsFileWriter Valid handle on success, NULL on failure. + * + * @note Call tsfile_writer_close() to release resources. + */ +TsFileWriter tsfile_writer_new(WriteFile file, TableSchema* schema, + ERRNO* err_code); + +/** + * @brief Creates a TsFileWriter for writing a TsFile. + * + * @param file Target file where the table data will be written. + * @param schema Table schema definition. + * - Ownership: Should be free it by Caller. + * @param memory_threshold used to limit the memory size + * of objects. If set to 0, no memory limit is enforced. + * @param err_code [out] RET_OK(0), or check error code in errno_define_c.h. + * + * @return TsFileWriter Valid handle on success, NULL on failure. + * + * @note Call tsfile_writer_close() to release resources. + */ +TsFileWriter tsfile_writer_new_with_memory_threshold(WriteFile file, + TableSchema* schema, + uint64_t memory_threshold, + ERRNO* err_code); + +/** + * @brief Releases resources associated with a TsFileWriter. + * + * @param writer [in] Writer handle obtained from tsfile_writer_new(). + * After call: handle becomes invalid and must not be reused. + * @return ERRNO - RET_OK(0) on success, check error code in errno_define_c.h. + */ +ERRNO tsfile_writer_close(TsFileWriter writer); +``` + + + +### Tablet Create/Close/Insert data + +You can use Tablet to insert data into TsFile in batches, and you need to release the space occupied by the Tablet after use. + +```C +/** + * @brief Creates a Tablet for batch data. + * + * @param column_name_list [in] Column names array. Size=column_num. + * @param data_types [in] Data types array. Size=column_num. + * @param column_num [in] Number of columns. Must be ≥1. + * @param max_rows [in] Pre-allocated row capacity. Must be ≥1. + * @return Tablet Valid handle. + * @note Call free_tablet() to release resources. + */ +Tablet tablet_new(char** column_name_list, TSDataType* data_types, + uint32_t column_num, uint32_t max_rows); +/** + * @brief Gets current row count in the Tablet. + * + * @param tablet [in] Valid Tablet handle. + * @return uint32_t Row count (0 to max_rows-1). + */ +uint32_t tablet_get_cur_row_size(Tablet tablet); + +/** + * @brief Assigns timestamp to a row in the Tablet. + * + * @param tablet [in] Valid Tablet handle. + * @param row_index [in] Target row (0 ≤ index < max_rows). + * @param timestamp [in] Timestamp with int64_t type. + * @return ERRNO - RET_OK(0)/RET_OUT_OF_RANGE(5) or check errno_define_c.h. + */ +ERRNO tablet_add_timestamp(Tablet tablet, uint32_t row_index, + Timestamp timestamp); + +/** + * @brief Adds a string value to a Tablet row by column name. + * + * @param value [in] Null-terminated string. Ownership remains with caller. + * @return ERRNO. + */ +ERRNO tablet_add_value_by_name_string(Tablet tablet, uint32_t row_index, + const char* column_name, + const char* value); + +// Multi type support: +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 Adds a string value to a Tablet row by column index. + * + * @param value [in] Null-terminated string. Copied internally. + */ +ERRNO tablet_add_value_by_index_string(Tablet tablet, uint32_t row_index, + uint32_t column_index, + const char* value); + + +// Multi type support: +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); +``` + + + +### Write Tablet into TsFile + +```C +/** + * @brief Writes data from a Tablet to the TsFile. + * + * @param writer [in] Valid TsFileWriter handle. Must be initialized. Review Comment: This statement is a bit confusing. There is no method for initializing a writer, only a method for instantiation (tsfile_writer_new). They are, in some contexts, different. ########## src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md: ########## @@ -0,0 +1,277 @@ +<!-- + + 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. + +--> +# Interface Definitions + + + +## Schema + +```Python + +class ColumnSchema: + """Defines schema for a table column (name, datatype, category).""" + + column_name = None + data_type = None + + def __init__(self, column_name: str, data_type: TSDataType, + category: ColumnCategory = ColumnCategory.FIELD) + def get_column_name(self) + def get_data_type(self) + def get_category(self) + +class TableSchema: + """Schema definition for a table structure.""" + + table_name = None + columns = None + + def __init__(self, table_name: str, columns: List[ColumnSchema]) + def get_table_name(self) + def get_columns(self) + + +class ResultSetMetaData: + """Metadata container for query result sets (columns, types, table name).""" + + column_list = None + data_types = None + table_name = None + + def __init__(self, column_list: List[str], data_types: List[TSDataType]) + def set_table_name(self, table_name: str) + def get_data_type(self, column_index: int) -> TSDataType + def get_column_name(self, column_index: int) -> str + def get_column_name_index(self, column_name: str) -> int + def get_column_num(self) + def get_column_list(self) + def get_data_type_list(self) + +``` + + + +## Write interface + +### TsFileWriter + +```python +class TsFileTableWriter: + """ + Facilitates writing structured table data into a TsFile with a specified schema. + + The TsFileTableWriter class is designed to write structured data, + particularly suitable for time-series data, into a file optimized for + efficient storage and retrieval (referred to as TsFile here). It allows users + to define the schema of the tables they want to write, add rows of data + according to that schema, and serialize this data into a TsFile. + """ + + + """ + :param path: The path of tsfile, will create if it doesn't exist. + :param table_schema: describes the schema of the tables they want to write. + """ + def __init__(self, path: str, table_schema: TableSchema) + + + """ + Write a tablet into table in tsfile. + :param tablet: stored batch data of a table. + :return: no return value. + :raise: TableNotExistError if table does not exist or tablet's table_name does not match tableschema. + """ + def write_table(self, tablet: Tablet) + + + """ + Close TsFileTableWriter and will flush data automatically. + :return: no return value. + """ + def close(self) + +``` + + + +### Tablet definition + +You can use Tablet to insert data into TsFile in batches, and you need to release the space occupied by the Tablet after use. + +```Python +class Tablet(object) + """ + A pre-allocated columnar data container for batch data with type constraints. + + Initializes: + - column_name_list: Ordered names for data columns + - type_list: TSDataType values specifying allowed types per column + - max_row_num: Pre-allocated row capacity (default 1024) + + Creates timestamp buffer and typed data columns, with value range validation ranges + for numeric types. + """ + + def __init__(self, column_name_list: list[str], type_list: list[TSDataType], + max_row_num: int = 1024) + + + def set_table_name(self, table_name: str) + def get_column_name_list(self) + def get_data_type_list(self) + def get_timestamp_list(self) + def get_target_name(self) + def get_value_list(self) + def get_max_row_num(self) + def add_column(self, column_name: str, column_type: TSDataType) + def remove_column(self, column_name: str) + def set_timestamp_list(self, timestamp_list: list[int]) + def add_timestamp(self, row_index: int, timestamp: int) + def add_value_by_name(self, column_name: str, row_index: int, value: Union[int, float, bool, str, bytes]) + def add_value_by_index(self, col_index: int, row_index: int, value: Union[int, float, bool, str, bytes]) + def get_value_by_index(self, col_index: int, row_index: int) + def get_value_by_name(self, column_name: str, row_index: int) + def get_value_list_by_name(self, column_name: str) +``` + + + +## Read Interface + +### TsFileReader + +```python +class TsFileReader: + """ + Read and query table data from TsFiles. Review Comment: Read and query -> Query TsFiles -> a TsFile ########## src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md: ########## @@ -0,0 +1,277 @@ +<!-- + + 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. + +--> +# Interface Definitions + + + +## Schema + +```Python + +class ColumnSchema: + """Defines schema for a table column (name, datatype, category).""" + + column_name = None + data_type = None + + def __init__(self, column_name: str, data_type: TSDataType, + category: ColumnCategory = ColumnCategory.FIELD) + def get_column_name(self) + def get_data_type(self) + def get_category(self) + +class TableSchema: + """Schema definition for a table structure.""" + + table_name = None + columns = None + + def __init__(self, table_name: str, columns: List[ColumnSchema]) + def get_table_name(self) + def get_columns(self) + + +class ResultSetMetaData: + """Metadata container for query result sets (columns, types, table name).""" + + column_list = None + data_types = None + table_name = None + + def __init__(self, column_list: List[str], data_types: List[TSDataType]) + def set_table_name(self, table_name: str) + def get_data_type(self, column_index: int) -> TSDataType + def get_column_name(self, column_index: int) -> str + def get_column_name_index(self, column_name: str) -> int + def get_column_num(self) + def get_column_list(self) + def get_data_type_list(self) + +``` + + + +## Write interface + +### TsFileWriter + +```python +class TsFileTableWriter: + """ + Facilitates writing structured table data into a TsFile with a specified schema. + + The TsFileTableWriter class is designed to write structured data, + particularly suitable for time-series data, into a file optimized for + efficient storage and retrieval (referred to as TsFile here). It allows users + to define the schema of the tables they want to write, add rows of data + according to that schema, and serialize this data into a TsFile. + """ + + + """ + :param path: The path of tsfile, will create if it doesn't exist. + :param table_schema: describes the schema of the tables they want to write. + """ + def __init__(self, path: str, table_schema: TableSchema) + + + """ + Write a tablet into table in tsfile. + :param tablet: stored batch data of a table. + :return: no return value. + :raise: TableNotExistError if table does not exist or tablet's table_name does not match tableschema. + """ + def write_table(self, tablet: Tablet) + + + """ + Close TsFileTableWriter and will flush data automatically. + :return: no return value. + """ + def close(self) + +``` + + + +### Tablet definition + +You can use Tablet to insert data into TsFile in batches, and you need to release the space occupied by the Tablet after use. + +```Python +class Tablet(object) + """ + A pre-allocated columnar data container for batch data with type constraints. + + Initializes: + - column_name_list: Ordered names for data columns + - type_list: TSDataType values specifying allowed types per column + - max_row_num: Pre-allocated row capacity (default 1024) + + Creates timestamp buffer and typed data columns, with value range validation ranges + for numeric types. + """ + + def __init__(self, column_name_list: list[str], type_list: list[TSDataType], + max_row_num: int = 1024) + + + def set_table_name(self, table_name: str) + def get_column_name_list(self) + def get_data_type_list(self) + def get_timestamp_list(self) + def get_target_name(self) + def get_value_list(self) + def get_max_row_num(self) + def add_column(self, column_name: str, column_type: TSDataType) + def remove_column(self, column_name: str) + def set_timestamp_list(self, timestamp_list: list[int]) + def add_timestamp(self, row_index: int, timestamp: int) + def add_value_by_name(self, column_name: str, row_index: int, value: Union[int, float, bool, str, bytes]) + def add_value_by_index(self, col_index: int, row_index: int, value: Union[int, float, bool, str, bytes]) + def get_value_by_index(self, col_index: int, row_index: int) + def get_value_by_name(self, column_name: str, row_index: int) + def get_value_list_by_name(self, column_name: str) +``` + + + +## Read Interface + +### TsFileReader + +```python +class TsFileReader: + """ + Read and query table data from TsFiles. + """ + + + """ + Initialize a TsFile reader for the specified file path. + """ + def __init__(self, pathname) + + + """ + Execute a time range query on specified table and columns. + :return: query result handler. + """ + def query_table(self, table_name : str, column_names : List[str], + start_time : int = 0, end_time : int = 0) -> ResultSetPy + + """ + Get table's schema with specify table name. + """ + def get_table_schema(self, table_name : str)-> TableSchema + + + """ + Get all tables schemas + """ + def get_all_table_schemas(self) ->dict[str, TableSchema] + + + """ + Close TsFile Reader, if reader has result sets, invalid them. + """ + def close(self) + + + +``` + +### ResultSet + + + +```python +class ResultSet: + """ + Get data from a query result. When reader run a query, a query handler will return. + If reader is closed, result set will not invalid anymore. + """ + + """ + Check and get next rows in query result. + :return: boolean, true means get next rows. Review Comment: next rows -> the next row in query result -> in the result set Mind the use of articles, the same below. ########## src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md: ########## @@ -0,0 +1,494 @@ +<!-- + + 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. + +--> +# Interface definition + + + +## 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_VECTOR = 6, + TS_DATATYPE_STRING = 11, + TS_DATATYPE_NULL_TYPE = 254, + TS_DATATYPE_INVALID = 255 +} TSDataType; + +typedef enum { + TS_ENCODING_PLAIN = 0, + TS_ENCODING_DICTIONARY = 1, + TS_ENCODING_RLE = 2, + TS_ENCODING_DIFF = 3, + TS_ENCODING_TS_2DIFF = 4, + TS_ENCODING_BITMAP = 5, + TS_ENCODING_GORILLA_V1 = 6, + TS_ENCODING_REGULAR = 7, + TS_ENCODING_GORILLA = 8, + TS_ENCODING_ZIGZAG = 9, + TS_ENCODING_FREQ = 10, + TS_ENCODING_INVALID = 255 +} TSEncoding; + +typedef enum { + TS_COMPRESSION_UNCOMPRESSED = 0, + TS_COMPRESSION_SNAPPY = 1, + TS_COMPRESSION_GZIP = 2, + TS_COMPRESSION_LZO = 3, + TS_COMPRESSION_SDT = 4, + TS_COMPRESSION_PAA = 5, + TS_COMPRESSION_PLA = 6, + TS_COMPRESSION_LZ4 = 7, + TS_COMPRESSION_INVALID = 255 +} CompressionType; + +typedef enum column_category { TAG = 0, FIELD = 1 } ColumnCategory; + +// ColumnSchema: Represents the schema of a single column, +// including its name, data type, and category. +typedef struct column_schema { + char* column_name; + TSDataType data_type; + ColumnCategory column_category; +} ColumnSchema; + +// TableSchema: Defines the schema of a table, +// including its name and a list of column schemas. +typedef struct table_schema { + char* table_name; + ColumnSchema* column_schemas; + int column_num; +} TableSchema; + +// ResultSetMetaData: Contains metadata for a result set, +// such as column names and their data types. +typedef struct result_set_meta_data { + char** column_names; + TSDataType* data_types; + int column_num; +} ResultSetMetaData; +``` + + + + + + + +## Write Interface + +### TsFile WriteFile Create/Close + +```C +/** + * @brief Creates a file for writing. + * + * @param pathname Target file path to create. + * @param err_code [out] RET_OK(0), or check error code in errno_define_c.h. + * + * @return WriteFile Valid handle on success. + * + * @note Call free_write_file() to release resources. + * @note Before call free_write_file(), make sure TsFileWriter has been closed. + */ + +WriteFile write_file_new(const char* pathname, ERRNO* err_code); + +void free_write_file(WriteFile* write_file); +``` + +### TsFile Writer Create/Close + +When creating a TsFile Writer, you need to specify WriteFile and TableSchema. You can use the memory_threshold parameter to limit the memory usage of the Writer during data writing, but in the current version, this parameter does not take effect. + +```C +/** + * @brief Creates a TsFileWriter for writing a TsFile. + * + * @param file Target file where the table data will be written. + * @param schema Table schema definition. + * - Ownership: Should be free it by Caller. + * @param err_code [out] RET_OK(0), or check error code in errno_define_c.h. + * + * @return TsFileWriter Valid handle on success, NULL on failure. + * + * @note Call tsfile_writer_close() to release resources. + */ +TsFileWriter tsfile_writer_new(WriteFile file, TableSchema* schema, + ERRNO* err_code); + +/** + * @brief Creates a TsFileWriter for writing a TsFile. + * + * @param file Target file where the table data will be written. + * @param schema Table schema definition. + * - Ownership: Should be free it by Caller. + * @param memory_threshold used to limit the memory size + * of objects. If set to 0, no memory limit is enforced. + * @param err_code [out] RET_OK(0), or check error code in errno_define_c.h. + * + * @return TsFileWriter Valid handle on success, NULL on failure. + * + * @note Call tsfile_writer_close() to release resources. + */ +TsFileWriter tsfile_writer_new_with_memory_threshold(WriteFile file, + TableSchema* schema, + uint64_t memory_threshold, + ERRNO* err_code); + +/** + * @brief Releases resources associated with a TsFileWriter. + * + * @param writer [in] Writer handle obtained from tsfile_writer_new(). + * After call: handle becomes invalid and must not be reused. + * @return ERRNO - RET_OK(0) on success, check error code in errno_define_c.h. + */ +ERRNO tsfile_writer_close(TsFileWriter writer); +``` + + + +### Tablet Create/Close/Insert data + +You can use Tablet to insert data into TsFile in batches, and you need to release the space occupied by the Tablet after use. + +```C +/** + * @brief Creates a Tablet for batch data. + * + * @param column_name_list [in] Column names array. Size=column_num. + * @param data_types [in] Data types array. Size=column_num. + * @param column_num [in] Number of columns. Must be ≥1. + * @param max_rows [in] Pre-allocated row capacity. Must be ≥1. + * @return Tablet Valid handle. + * @note Call free_tablet() to release resources. + */ +Tablet tablet_new(char** column_name_list, TSDataType* data_types, + uint32_t column_num, uint32_t max_rows); +/** + * @brief Gets current row count in the Tablet. + * + * @param tablet [in] Valid Tablet handle. + * @return uint32_t Row count (0 to max_rows-1). + */ +uint32_t tablet_get_cur_row_size(Tablet tablet); + +/** + * @brief Assigns timestamp to a row in the Tablet. + * + * @param tablet [in] Valid Tablet handle. + * @param row_index [in] Target row (0 ≤ index < max_rows). + * @param timestamp [in] Timestamp with int64_t type. + * @return ERRNO - RET_OK(0)/RET_OUT_OF_RANGE(5) or check errno_define_c.h. + */ +ERRNO tablet_add_timestamp(Tablet tablet, uint32_t row_index, + Timestamp timestamp); + +/** + * @brief Adds a string value to a Tablet row by column name. + * + * @param value [in] Null-terminated string. Ownership remains with caller. + * @return ERRNO. + */ +ERRNO tablet_add_value_by_name_string(Tablet tablet, uint32_t row_index, + const char* column_name, + const char* value); + +// Multi type support: +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 Adds a string value to a Tablet row by column index. + * + * @param value [in] Null-terminated string. Copied internally. + */ +ERRNO tablet_add_value_by_index_string(Tablet tablet, uint32_t row_index, + uint32_t column_index, + const char* value); + + +// Multi type support: +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); +``` + + + +### Write Tablet into TsFile + +```C +/** + * @brief Writes data from a Tablet to the TsFile. + * + * @param writer [in] Valid TsFileWriter handle. Must be initialized. + * @param tablet [in] Tablet containing data. Should be freed after successful + * write. + * @return ERRNO - RET_OK(0), or check error code in errno_define_c.h. + * + */ + +ERRNO tsfile_writer_write(TsFileWriter writer, Tablet tablet); +``` + + + + + +## Read Interface + +### TsFile Reader Create/Close + +```C +/** + * @brief Creates a TsFileReader for reading a TsFile. + * + * @param pathname Source TsFiles path. Must be a valid path. + * @param err_code RET_OK(0), or check error code in errno_define_c.h. + * @return TsFileReader Valid handle on success, NULL on failure. + * + * @note Call tsfile_reader_close() to release resources. + */ + +TsFileReader tsfile_reader_new(const char* pathname, ERRNO* err_code); + +/** + * @brief Releases resources associated with a TsFileReader. + * + * @param reader [in] Reader handle obtained from tsfile_reader_new(). + * After call: + * Handle becomes invalid and must not be reused. + * Result_set obtained by this handle becomes invalid. + * @return ERRNO - RET_OK(0) on success, or check error code in errno_define_c.h. + */ +ERRNO tsfile_reader_close(TsFileReader reader); +``` + + + +### Query table/get next + +```C + +/** + * @brief Queries time series data from a specific table within time range. + * + * @param reader [in] Valid TsFileReader handle from tsfile_reader_new(). + * @param table_name [in] Target table name. Must exist in the TS file. + * @param columns [in] Array of column names to fetch. + * @param column_num [in] Number of columns in array. + * @param start_time [in] Start timestamp. + * @param end_time [in] End timestamp. Must ≥ start_time. + * @return ResultSet Query results handle. Must be freed with + * 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 Check and fetch the next row in the ResultSet. + * + * @param result_set [in] Valid ResultSet handle. + * @return bool - true: Row available, false: End of data or error. + */ +bool tsfile_result_set_next(ResultSet result_set, ERRNO* error_code); + +/** + * @brief Free Result set + * + * @param result_set [in] Valid ResultSet handle ptr. + */ +void free_tsfile_result_set(ResultSet* result_set); +``` + + + +### Get Data from result set + +```c +/** + * @brief Checks if the current row's column value is NULL by column name. + * + * @param result_set [in] Valid ResultSet with active row (after next()=true). + * @param column_name [in] Existing column name in result schema. + * @return bool - true: Value is NULL or column not found, false: Valid value. + */ +bool tsfile_result_set_is_null_by_name(ResultSet result_set, + const char* column_name); + +/** + * @brief Checks if the current row's column value is NULL by column index. + * + * @param column_index [in] Column position (0 ≤ index < result_column_count). + * @return bool - true: Value is NULL or index out of range, false: Valid value. + */ +bool tsfile_result_set_is_null_by_index(ResultSet result_set, + uint32_t column_index); + +/** + * @brief Gets string value from current row by column name. + * + * @return char* - String pointer. Caller must free this ptr after usage. + */ +char* tsfile_result_set_get_value_by_name_string(ResultSet result_set, + const char* column_name); + +// Multi type support +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 Gets string value from current row by column index. + * + * @return char* - String pointer. Caller must free this ptr after usage. + */ +char* tsfile_result_set_get_value_by_index_string(ResultSet result_set, + uint32_t column_index); + +// Multi type support +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 Retrieves metadata describing the ResultSet's schema. + * + * @param result_set [in] Valid ResultSet handle. + * @return ResultSetMetaData Metadata handle. Caller should free the + * ResultSetMataData after usage. + * @note Before calling this func, check if result_set is NULL, which means + * the query may be not correct. + */ +ResultSetMetaData tsfile_result_set_get_metadata(ResultSet result_set); + +/** + * @brief Gets column name by index from metadata. + * + * @param column_index [in] Column position (0 ≤ index < column_num). + * @return const char* Read-only string. NULL if index invalid. + */ +char* tsfile_result_set_metadata_get_column_name(ResultSetMetaData result_set, + uint32_t column_index); + +/** + * @brief Gets column data type by index from metadata. + * + * @return TSDataType Returns TS_DATATYPE_INVALID(255) if index invalid. + */ +TSDataType tsfile_result_set_metadata_get_data_type( + ResultSetMetaData result_set, uint32_t column_index); + +/** + * @brief Gets total number of columns in the result schema. + * + * @return column num in result set metadata. + */ +int tsfile_result_set_metadata_get_column_num(ResultSetMetaData result_set); +``` + + + +### Get Table Schema from TsFile Reader + +```C +/** + * @brief Gets specific table's schema in the tsfile. + * + * @return TableSchema, contains table and column info. + * @note Caller should call free_table_schema to free the tableschema. Review Comment: Where is free_table_schema? ########## src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md: ########## @@ -0,0 +1,494 @@ +<!-- + + 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. + +--> +# Interface definition + + + +## 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_VECTOR = 6, + TS_DATATYPE_STRING = 11, + TS_DATATYPE_NULL_TYPE = 254, + TS_DATATYPE_INVALID = 255 +} TSDataType; + +typedef enum { + TS_ENCODING_PLAIN = 0, + TS_ENCODING_DICTIONARY = 1, + TS_ENCODING_RLE = 2, + TS_ENCODING_DIFF = 3, + TS_ENCODING_TS_2DIFF = 4, + TS_ENCODING_BITMAP = 5, + TS_ENCODING_GORILLA_V1 = 6, + TS_ENCODING_REGULAR = 7, + TS_ENCODING_GORILLA = 8, + TS_ENCODING_ZIGZAG = 9, + TS_ENCODING_FREQ = 10, + TS_ENCODING_INVALID = 255 +} TSEncoding; + +typedef enum { + TS_COMPRESSION_UNCOMPRESSED = 0, + TS_COMPRESSION_SNAPPY = 1, + TS_COMPRESSION_GZIP = 2, + TS_COMPRESSION_LZO = 3, + TS_COMPRESSION_SDT = 4, + TS_COMPRESSION_PAA = 5, + TS_COMPRESSION_PLA = 6, + TS_COMPRESSION_LZ4 = 7, + TS_COMPRESSION_INVALID = 255 +} CompressionType; + +typedef enum column_category { TAG = 0, FIELD = 1 } ColumnCategory; + +// ColumnSchema: Represents the schema of a single column, +// including its name, data type, and category. +typedef struct column_schema { + char* column_name; + TSDataType data_type; + ColumnCategory column_category; +} ColumnSchema; + +// TableSchema: Defines the schema of a table, +// including its name and a list of column schemas. +typedef struct table_schema { + char* table_name; + ColumnSchema* column_schemas; + int column_num; +} TableSchema; + +// ResultSetMetaData: Contains metadata for a result set, +// such as column names and their data types. +typedef struct result_set_meta_data { + char** column_names; + TSDataType* data_types; + int column_num; +} ResultSetMetaData; +``` + + + + + + + +## Write Interface + +### TsFile WriteFile Create/Close + +```C +/** + * @brief Creates a file for writing. + * + * @param pathname Target file path to create. + * @param err_code [out] RET_OK(0), or check error code in errno_define_c.h. + * + * @return WriteFile Valid handle on success. + * + * @note Call free_write_file() to release resources. + * @note Before call free_write_file(), make sure TsFileWriter has been closed. + */ + +WriteFile write_file_new(const char* pathname, ERRNO* err_code); + +void free_write_file(WriteFile* write_file); +``` + +### TsFile Writer Create/Close + +When creating a TsFile Writer, you need to specify WriteFile and TableSchema. You can use the memory_threshold parameter to limit the memory usage of the Writer during data writing, but in the current version, this parameter does not take effect. + +```C +/** + * @brief Creates a TsFileWriter for writing a TsFile. + * + * @param file Target file where the table data will be written. + * @param schema Table schema definition. + * - Ownership: Should be free it by Caller. + * @param err_code [out] RET_OK(0), or check error code in errno_define_c.h. + * + * @return TsFileWriter Valid handle on success, NULL on failure. + * + * @note Call tsfile_writer_close() to release resources. + */ +TsFileWriter tsfile_writer_new(WriteFile file, TableSchema* schema, + ERRNO* err_code); + +/** + * @brief Creates a TsFileWriter for writing a TsFile. + * + * @param file Target file where the table data will be written. + * @param schema Table schema definition. + * - Ownership: Should be free it by Caller. + * @param memory_threshold used to limit the memory size + * of objects. If set to 0, no memory limit is enforced. + * @param err_code [out] RET_OK(0), or check error code in errno_define_c.h. + * + * @return TsFileWriter Valid handle on success, NULL on failure. + * + * @note Call tsfile_writer_close() to release resources. + */ +TsFileWriter tsfile_writer_new_with_memory_threshold(WriteFile file, + TableSchema* schema, + uint64_t memory_threshold, + ERRNO* err_code); + +/** + * @brief Releases resources associated with a TsFileWriter. + * + * @param writer [in] Writer handle obtained from tsfile_writer_new(). + * After call: handle becomes invalid and must not be reused. + * @return ERRNO - RET_OK(0) on success, check error code in errno_define_c.h. + */ +ERRNO tsfile_writer_close(TsFileWriter writer); +``` + + + +### Tablet Create/Close/Insert data + +You can use Tablet to insert data into TsFile in batches, and you need to release the space occupied by the Tablet after use. + +```C +/** + * @brief Creates a Tablet for batch data. + * + * @param column_name_list [in] Column names array. Size=column_num. + * @param data_types [in] Data types array. Size=column_num. + * @param column_num [in] Number of columns. Must be ≥1. + * @param max_rows [in] Pre-allocated row capacity. Must be ≥1. + * @return Tablet Valid handle. + * @note Call free_tablet() to release resources. + */ +Tablet tablet_new(char** column_name_list, TSDataType* data_types, + uint32_t column_num, uint32_t max_rows); +/** + * @brief Gets current row count in the Tablet. + * + * @param tablet [in] Valid Tablet handle. + * @return uint32_t Row count (0 to max_rows-1). + */ +uint32_t tablet_get_cur_row_size(Tablet tablet); + +/** + * @brief Assigns timestamp to a row in the Tablet. + * + * @param tablet [in] Valid Tablet handle. + * @param row_index [in] Target row (0 ≤ index < max_rows). + * @param timestamp [in] Timestamp with int64_t type. + * @return ERRNO - RET_OK(0)/RET_OUT_OF_RANGE(5) or check errno_define_c.h. + */ +ERRNO tablet_add_timestamp(Tablet tablet, uint32_t row_index, + Timestamp timestamp); + +/** + * @brief Adds a string value to a Tablet row by column name. + * + * @param value [in] Null-terminated string. Ownership remains with caller. + * @return ERRNO. + */ +ERRNO tablet_add_value_by_name_string(Tablet tablet, uint32_t row_index, + const char* column_name, + const char* value); + +// Multi type support: +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 Adds a string value to a Tablet row by column index. + * + * @param value [in] Null-terminated string. Copied internally. + */ +ERRNO tablet_add_value_by_index_string(Tablet tablet, uint32_t row_index, + uint32_t column_index, + const char* value); + + +// Multi type support: +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); +``` + + + +### Write Tablet into TsFile + +```C +/** + * @brief Writes data from a Tablet to the TsFile. + * + * @param writer [in] Valid TsFileWriter handle. Must be initialized. + * @param tablet [in] Tablet containing data. Should be freed after successful + * write. + * @return ERRNO - RET_OK(0), or check error code in errno_define_c.h. + * + */ + +ERRNO tsfile_writer_write(TsFileWriter writer, Tablet tablet); +``` + + + + + +## Read Interface + +### TsFile Reader Create/Close + +```C +/** + * @brief Creates a TsFileReader for reading a TsFile. + * + * @param pathname Source TsFiles path. Must be a valid path. + * @param err_code RET_OK(0), or check error code in errno_define_c.h. + * @return TsFileReader Valid handle on success, NULL on failure. + * + * @note Call tsfile_reader_close() to release resources. + */ + +TsFileReader tsfile_reader_new(const char* pathname, ERRNO* err_code); + +/** + * @brief Releases resources associated with a TsFileReader. + * + * @param reader [in] Reader handle obtained from tsfile_reader_new(). + * After call: + * Handle becomes invalid and must not be reused. + * Result_set obtained by this handle becomes invalid. + * @return ERRNO - RET_OK(0) on success, or check error code in errno_define_c.h. + */ +ERRNO tsfile_reader_close(TsFileReader reader); +``` + + + +### Query table/get next + +```C + +/** + * @brief Queries time series data from a specific table within time range. + * + * @param reader [in] Valid TsFileReader handle from tsfile_reader_new(). + * @param table_name [in] Target table name. Must exist in the TS file. + * @param columns [in] Array of column names to fetch. + * @param column_num [in] Number of columns in array. + * @param start_time [in] Start timestamp. + * @param end_time [in] End timestamp. Must ≥ start_time. + * @return ResultSet Query results handle. Must be freed with + * 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 Check and fetch the next row in the ResultSet. + * + * @param result_set [in] Valid ResultSet handle. + * @return bool - true: Row available, false: End of data or error. + */ +bool tsfile_result_set_next(ResultSet result_set, ERRNO* error_code); + +/** + * @brief Free Result set + * + * @param result_set [in] Valid ResultSet handle ptr. + */ +void free_tsfile_result_set(ResultSet* result_set); +``` + + + +### Get Data from result set + +```c +/** + * @brief Checks if the current row's column value is NULL by column name. + * + * @param result_set [in] Valid ResultSet with active row (after next()=true). + * @param column_name [in] Existing column name in result schema. + * @return bool - true: Value is NULL or column not found, false: Valid value. + */ +bool tsfile_result_set_is_null_by_name(ResultSet result_set, + const char* column_name); + +/** + * @brief Checks if the current row's column value is NULL by column index. + * + * @param column_index [in] Column position (0 ≤ index < result_column_count). + * @return bool - true: Value is NULL or index out of range, false: Valid value. + */ +bool tsfile_result_set_is_null_by_index(ResultSet result_set, + uint32_t column_index); + +/** + * @brief Gets string value from current row by column name. + * + * @return char* - String pointer. Caller must free this ptr after usage. + */ +char* tsfile_result_set_get_value_by_name_string(ResultSet result_set, + const char* column_name); + +// Multi type support +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 Gets string value from current row by column index. + * + * @return char* - String pointer. Caller must free this ptr after usage. + */ +char* tsfile_result_set_get_value_by_index_string(ResultSet result_set, + uint32_t column_index); + +// Multi type support +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 Retrieves metadata describing the ResultSet's schema. + * + * @param result_set [in] Valid ResultSet handle. + * @return ResultSetMetaData Metadata handle. Caller should free the + * ResultSetMataData after usage. + * @note Before calling this func, check if result_set is NULL, which means + * the query may be not correct. + */ +ResultSetMetaData tsfile_result_set_get_metadata(ResultSet result_set); + +/** + * @brief Gets column name by index from metadata. + * + * @param column_index [in] Column position (0 ≤ index < column_num). + * @return const char* Read-only string. NULL if index invalid. + */ +char* tsfile_result_set_metadata_get_column_name(ResultSetMetaData result_set, + uint32_t column_index); + +/** + * @brief Gets column data type by index from metadata. + * + * @return TSDataType Returns TS_DATATYPE_INVALID(255) if index invalid. + */ +TSDataType tsfile_result_set_metadata_get_data_type( + ResultSetMetaData result_set, uint32_t column_index); + +/** + * @brief Gets total number of columns in the result schema. + * + * @return column num in result set metadata. + */ +int tsfile_result_set_metadata_get_column_num(ResultSetMetaData result_set); +``` + + + +### Get Table Schema from TsFile Reader + +```C +/** + * @brief Gets specific table's schema in the tsfile. + * + * @return TableSchema, contains table and column info. + * @note Caller should call free_table_schema to free the tableschema. + */ +TableSchema tsfile_reader_get_table_schema(TsFileReader reader, + const char* table_name); +/** + * @brief Gets all table schema in the tsfile. + * + * @return TableSchema, contains table and column info. Review Comment: @param size ... @return An array of TableSchema, ... ########## src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md: ########## @@ -0,0 +1,277 @@ +<!-- + + 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. + +--> +# Interface Definitions + + + +## Schema + +```Python + +class ColumnSchema: + """Defines schema for a table column (name, datatype, category).""" + + column_name = None + data_type = None + + def __init__(self, column_name: str, data_type: TSDataType, + category: ColumnCategory = ColumnCategory.FIELD) + def get_column_name(self) + def get_data_type(self) + def get_category(self) + +class TableSchema: + """Schema definition for a table structure.""" + + table_name = None + columns = None + + def __init__(self, table_name: str, columns: List[ColumnSchema]) + def get_table_name(self) + def get_columns(self) + + +class ResultSetMetaData: + """Metadata container for query result sets (columns, types, table name).""" + + column_list = None + data_types = None + table_name = None + + def __init__(self, column_list: List[str], data_types: List[TSDataType]) + def set_table_name(self, table_name: str) + def get_data_type(self, column_index: int) -> TSDataType + def get_column_name(self, column_index: int) -> str + def get_column_name_index(self, column_name: str) -> int + def get_column_num(self) + def get_column_list(self) + def get_data_type_list(self) + +``` + + + +## Write interface + +### TsFileWriter + +```python +class TsFileTableWriter: + """ + Facilitates writing structured table data into a TsFile with a specified schema. + + The TsFileTableWriter class is designed to write structured data, + particularly suitable for time-series data, into a file optimized for + efficient storage and retrieval (referred to as TsFile here). It allows users + to define the schema of the tables they want to write, add rows of data + according to that schema, and serialize this data into a TsFile. + """ + + + """ + :param path: The path of tsfile, will create if it doesn't exist. + :param table_schema: describes the schema of the tables they want to write. + """ + def __init__(self, path: str, table_schema: TableSchema) + + + """ + Write a tablet into table in tsfile. + :param tablet: stored batch data of a table. + :return: no return value. + :raise: TableNotExistError if table does not exist or tablet's table_name does not match tableschema. + """ + def write_table(self, tablet: Tablet) + + + """ + Close TsFileTableWriter and will flush data automatically. + :return: no return value. + """ + def close(self) + +``` + + + +### Tablet definition + +You can use Tablet to insert data into TsFile in batches, and you need to release the space occupied by the Tablet after use. + +```Python +class Tablet(object) + """ + A pre-allocated columnar data container for batch data with type constraints. + + Initializes: + - column_name_list: Ordered names for data columns + - type_list: TSDataType values specifying allowed types per column + - max_row_num: Pre-allocated row capacity (default 1024) + + Creates timestamp buffer and typed data columns, with value range validation ranges + for numeric types. + """ + + def __init__(self, column_name_list: list[str], type_list: list[TSDataType], + max_row_num: int = 1024) + + + def set_table_name(self, table_name: str) + def get_column_name_list(self) + def get_data_type_list(self) + def get_timestamp_list(self) + def get_target_name(self) + def get_value_list(self) + def get_max_row_num(self) + def add_column(self, column_name: str, column_type: TSDataType) + def remove_column(self, column_name: str) + def set_timestamp_list(self, timestamp_list: list[int]) + def add_timestamp(self, row_index: int, timestamp: int) + def add_value_by_name(self, column_name: str, row_index: int, value: Union[int, float, bool, str, bytes]) + def add_value_by_index(self, col_index: int, row_index: int, value: Union[int, float, bool, str, bytes]) + def get_value_by_index(self, col_index: int, row_index: int) + def get_value_by_name(self, column_name: str, row_index: int) + def get_value_list_by_name(self, column_name: str) +``` + + + +## Read Interface + +### TsFileReader + +```python +class TsFileReader: + """ + Read and query table data from TsFiles. + """ + + + """ + Initialize a TsFile reader for the specified file path. + """ + def __init__(self, pathname) + + + """ + Execute a time range query on specified table and columns. + :return: query result handler. + """ + def query_table(self, table_name : str, column_names : List[str], + start_time : int = 0, end_time : int = 0) -> ResultSetPy + + """ + Get table's schema with specify table name. + """ + def get_table_schema(self, table_name : str)-> TableSchema + + + """ + Get all tables schemas + """ + def get_all_table_schemas(self) ->dict[str, TableSchema] + + + """ + Close TsFile Reader, if reader has result sets, invalid them. + """ + def close(self) + + + +``` + +### ResultSet + + + +```python +class ResultSet: + """ + Get data from a query result. When reader run a query, a query handler will return. + If reader is closed, result set will not invalid anymore. + """ + + """ + Check and get next rows in query result. + :return: boolean, true means get next rows. + """ + def next(self) -> bool + + + """ + Get result set's columns info. + :return: a dict contains column's name and datatype. + """ + def get_result_column_info(self) -> dict[str, TsDataType] + + + """ + :param max_row_num: default row num: 1024 + :return: a dataframe contains data from query result. + """ + def read_next_data_frame(self, max_row_num : int = 1024) -> DataFrame + + + """ + Get value by index from query result set. + NOTE: index start from 1. + """ + def get_value_by_index(self, index : int) + + + """ + Get value by name from query result set. + """ + def get_value_by_name(self, column_name : str) + + + + """ + Get result set metadata in this result set. + """ + def get_metadata(self)->ResultSetMetadata + + + """ + Checks whether the field at the specified index in the result set is null. + + This method queries the underlying result set to determine if the value + at the given column index position represents a null value. Review Comment: This sentence is meaningless to the API user, remove it. ########## src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md: ########## @@ -0,0 +1,277 @@ +<!-- + + 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. + +--> +# Interface Definitions + + + +## Schema + +```Python + +class ColumnSchema: + """Defines schema for a table column (name, datatype, category).""" + + column_name = None + data_type = None + + def __init__(self, column_name: str, data_type: TSDataType, + category: ColumnCategory = ColumnCategory.FIELD) + def get_column_name(self) + def get_data_type(self) + def get_category(self) + +class TableSchema: + """Schema definition for a table structure.""" + + table_name = None + columns = None + + def __init__(self, table_name: str, columns: List[ColumnSchema]) + def get_table_name(self) + def get_columns(self) + + +class ResultSetMetaData: + """Metadata container for query result sets (columns, types, table name).""" + + column_list = None + data_types = None + table_name = None + + def __init__(self, column_list: List[str], data_types: List[TSDataType]) + def set_table_name(self, table_name: str) + def get_data_type(self, column_index: int) -> TSDataType + def get_column_name(self, column_index: int) -> str + def get_column_name_index(self, column_name: str) -> int + def get_column_num(self) + def get_column_list(self) + def get_data_type_list(self) + +``` + + + +## Write interface + +### TsFileWriter + +```python +class TsFileTableWriter: + """ + Facilitates writing structured table data into a TsFile with a specified schema. + + The TsFileTableWriter class is designed to write structured data, + particularly suitable for time-series data, into a file optimized for + efficient storage and retrieval (referred to as TsFile here). It allows users + to define the schema of the tables they want to write, add rows of data + according to that schema, and serialize this data into a TsFile. + """ + + + """ + :param path: The path of tsfile, will create if it doesn't exist. + :param table_schema: describes the schema of the tables they want to write. + """ + def __init__(self, path: str, table_schema: TableSchema) + + + """ + Write a tablet into table in tsfile. + :param tablet: stored batch data of a table. + :return: no return value. + :raise: TableNotExistError if table does not exist or tablet's table_name does not match tableschema. + """ + def write_table(self, tablet: Tablet) + + + """ + Close TsFileTableWriter and will flush data automatically. + :return: no return value. + """ + def close(self) + +``` + + + +### Tablet definition + +You can use Tablet to insert data into TsFile in batches, and you need to release the space occupied by the Tablet after use. + +```Python +class Tablet(object) + """ + A pre-allocated columnar data container for batch data with type constraints. + + Initializes: + - column_name_list: Ordered names for data columns + - type_list: TSDataType values specifying allowed types per column + - max_row_num: Pre-allocated row capacity (default 1024) + + Creates timestamp buffer and typed data columns, with value range validation ranges + for numeric types. + """ + + def __init__(self, column_name_list: list[str], type_list: list[TSDataType], + max_row_num: int = 1024) + + + def set_table_name(self, table_name: str) + def get_column_name_list(self) + def get_data_type_list(self) + def get_timestamp_list(self) + def get_target_name(self) + def get_value_list(self) + def get_max_row_num(self) + def add_column(self, column_name: str, column_type: TSDataType) + def remove_column(self, column_name: str) + def set_timestamp_list(self, timestamp_list: list[int]) + def add_timestamp(self, row_index: int, timestamp: int) + def add_value_by_name(self, column_name: str, row_index: int, value: Union[int, float, bool, str, bytes]) + def add_value_by_index(self, col_index: int, row_index: int, value: Union[int, float, bool, str, bytes]) + def get_value_by_index(self, col_index: int, row_index: int) + def get_value_by_name(self, column_name: str, row_index: int) + def get_value_list_by_name(self, column_name: str) +``` + + + +## Read Interface + +### TsFileReader + +```python +class TsFileReader: + """ + Read and query table data from TsFiles. + """ + + + """ + Initialize a TsFile reader for the specified file path. + """ + def __init__(self, pathname) + + + """ + Execute a time range query on specified table and columns. + :return: query result handler. + """ + def query_table(self, table_name : str, column_names : List[str], + start_time : int = 0, end_time : int = 0) -> ResultSetPy + + """ + Get table's schema with specify table name. + """ + def get_table_schema(self, table_name : str)-> TableSchema + + + """ + Get all tables schemas + """ + def get_all_table_schemas(self) ->dict[str, TableSchema] + + + """ + Close TsFile Reader, if reader has result sets, invalid them. + """ + def close(self) + + + +``` + +### ResultSet + + + +```python +class ResultSet: + """ + Get data from a query result. When reader run a query, a query handler will return. + If reader is closed, result set will not invalid anymore. Review Comment: a query result -> a query / a query result set run -> runs handler -> result set will return -> will be returned will not invalid -> will be invalid -- 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
