fix user docs
diff --git a/src/UserGuide/latest/QuickStart/Data-Model.md b/src/UserGuide/latest/QuickStart/Data-Model.md index f898b42..130652d 100644 --- a/src/UserGuide/latest/QuickStart/Data-Model.md +++ b/src/UserGuide/latest/QuickStart/Data-Model.md
@@ -49,6 +49,10 @@ null by default)</td> </tr> <tr> + <td rowspan="1">ATTRIBUTE</td> + <td>Additional column role in the file format and SDKs (with TAG, FIELD, TIME); see language API enums for when to use it.</td> + </tr> + <tr> <td rowspan="1">Time</td> <td>A table must have a time column, and data with the same identifier value is sorted by time by default.The values in the time column cannot be empty and must be in sequence.</td> </tr>
diff --git a/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md b/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md index f556439..b3c20a6 100644 --- a/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md +++ b/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md
@@ -20,9 +20,16 @@ --> # Interface definition - C +The C API is declared in `cwrapper/tsfile_cwrapper.h`. Success is `RET_OK` (0); other codes are defined in `cwrapper/errno_define_c.h`. +- **Table model**: one `TableSchema`, batch rows in a `Tablet`, queries by `table_name` and column names (time range, tag filter, row window, or batch TsBlock/Arrow). +- **Tree model**: queries by **device** id strings and **measurement** names; device listing and per-device timeseries metadata are documented under tree-oriented reads. -## Schema +**Column index convention**: `tsfile_result_set_get_value_by_index_*`, `tsfile_result_set_is_null_by_index`, and `tsfile_result_set_metadata_get_*` use **1-based** `column_index` (1 … column count), matching the underlying C++ `ResultSet` and the shipped C examples. + +## Schema and common types + +Excerpt; see the header for the full list and additional metadata structures (`DeviceID`, `TimeseriesMetadata`, `DeviceTimeseriesMetadataMap`, statistics unions, etc.). ```C typedef enum { @@ -32,29 +39,47 @@ TS_DATATYPE_FLOAT = 3, TS_DATATYPE_DOUBLE = 4, TS_DATATYPE_TEXT = 5, - TS_DATATYPE_STRING = 11 + TS_DATATYPE_VECTOR = 6, + TS_DATATYPE_TIMESTAMP = 8, + TS_DATATYPE_DATE = 9, + TS_DATATYPE_BLOB = 10, + TS_DATATYPE_STRING = 11, + TS_DATATYPE_NULL_TYPE = 254, + TS_DATATYPE_INVALID = 255 } TSDataType; -typedef enum column_category { TAG = 0, FIELD = 1 } ColumnCategory; +typedef enum column_category { + TAG = 0, + FIELD = 1, + ATTRIBUTE = 2, + TIME = 3 +} 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 timeseries_schema { + char* timeseries_name; + TSDataType data_type; + TSEncoding encoding; + CompressionType compression; +} TimeseriesSchema; + +typedef struct device_schema { + char* device_name; + TimeseriesSchema* timeseries_schema; + int timeseries_num; +} DeviceSchema; + typedef struct result_set_meta_data { char** column_names; TSDataType* data_types; @@ -62,412 +87,609 @@ } ResultSetMetaData; ``` +## Table model: write -## Write Interface - -### TsFile WriteFile Create/Close +### TsFile `WriteFile` and `TsFileWriter` ```C /** - * @brief Creates a file for writing. + * @brief Creates a file handle for TsFile writing. * - * @param pathname Target file to create. - * @param err_code [out] RET_OK(0), or 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. + * @param pathname Output file path. + * @param[out] err_code `RET_OK` on success. + * @return Valid `WriteFile` handle on success, otherwise NULL. */ - 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 in -tsfile_writer_new_with_memory_threshold 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. + * @brief Frees `WriteFile` resources. * - * @param file Target file where the table data will be written. - * @param schema Table schema definition. - * - Ownership: Should be freed by the caller. - * @param err_code [out] RET_OK(0), or error code in errno_define_c.h. + * @param[in,out] write_file Pointer to write-file handle. + */ +void free_write_file(WriteFile* write_file); + +/** + * @brief Creates a table-model TsFile writer. * - * @return TsFileWriter Valid handle on success, NULL on failure. - * - * @note Call tsfile_writer_close() to release resources. + * @param file Write file handle. + * @param schema Table schema definition. + * @param[out] err_code `RET_OK` on success. + * @return Valid `TsFileWriter` on success, otherwise NULL. */ TsFileWriter tsfile_writer_new(WriteFile file, TableSchema* schema, ERRNO* err_code); - /** - * @brief Creates a TsFileWriter for writing a TsFile. + * @brief Creates a writer with memory threshold. * - * @param file Target file where the table data will be written. - * @param schema Table schema definition. - * - Ownership: Should be freed by the caller. - * @param memory_threshold When the size of written data exceeds - * this value, the data will be automatically flushed to the disk. - * @param err_code [out] RET_OK(0), or error code in errno_define_c.h. - * - * @return TsFileWriter Valid handle on success, NULL on failure. - * - * @note Call tsfile_writer_close() to release resources. + * @param file Write file handle. + * @param schema Table schema definition. + * @param memory_threshold Threshold for buffered writes before flush. + * @param[out] err_code `RET_OK` on success. + * @return Valid `TsFileWriter` on success, otherwise NULL. */ -TsFileWriter tsfile_writer_new_with_memory_threshold(WriteFile file, - TableSchema* schema, - uint64_t memory_threshold, - ERRNO* err_code); +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. + * @brief Closes a TsFile writer. * - * @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, or error code in errno_define_c.h. + * @param writer Writer handle. + * @return `RET_OK` on success. */ ERRNO tsfile_writer_close(TsFileWriter writer); ``` +`memory_threshold` is passed through to the writer configuration (e.g. chunk group size threshold). Use a value appropriate for your write workload. - -### 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. +### `Tablet` (string columns use length) ```C /** - * @brief Creates a Tablet for batch data. + * @brief Creates a Tablet for batch writes. * - * @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. + * @param column_name_list Column names, length = `column_num`. + * @param data_types Data types, length = `column_num`. + * @param column_num Number of columns. + * @param max_rows Tablet capacity in rows. + * @return Valid `Tablet` handle. */ 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. + * @brief Gets current number of rows in tablet. * - * @param tablet [in] Valid Tablet handle. - * @return uint32_t Row count (0 to max_rows-1). + * @param tablet Tablet handle. + * @return Current row count. */ uint32_t tablet_get_cur_row_size(Tablet tablet); - /** - * @brief Assigns timestamp to a row in the Tablet. + * @brief Sets timestamp for a row. * - * @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) or error code in errno_define_c.h. + * @param tablet Tablet handle. + * @param row_index Target row index. + * @param timestamp Timestamp value. + * @return `RET_OK` on success. */ ERRNO tablet_add_timestamp(Tablet tablet, uint32_t row_index, Timestamp timestamp); - + +/* String: pass byte length (not necessarily null-terminated storage). */ /** - * @brief Adds a string value to a Tablet row by column name. + * @brief Sets string value by column name. * - * @param value [in] Null-terminated string. Ownership remains with caller. - * @return ERRNO. + * @param tablet Tablet handle. + * @param row_index Target row index. + * @param column_name Column name. + * @param value String bytes. + * @param value_len Byte length of `value`. + * @return `RET_OK` on success. */ -ERRNO tablet_add_value_by_name_string(Tablet tablet, uint32_t row_index, - const char* column_name, - const char* value); - - // Supports multiple data types -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); - - +ERRNO tablet_add_value_by_name_string_with_len( + Tablet tablet, uint32_t row_index, const char* column_name, + const char* value, int value_len); /** - * @brief Adds a string value to a Tablet row by column index. + * @brief Sets string value by column index. * - * @param value [in] Null-terminated string. Copied internally. + * @param tablet Tablet handle. + * @param row_index Target row index. + * @param column_index Target column index. + * @param value String bytes. + * @param value_len Byte length of `value`. + * @return `RET_OK` on success. */ -ERRNO tablet_add_value_by_index_string(Tablet tablet, uint32_t row_index, - uint32_t column_index, - const char* value); +ERRNO tablet_add_value_by_index_string_with_len( + Tablet tablet, uint32_t row_index, uint32_t column_index, + const char* value, int value_len); - -// Supports multiple data types -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); - - +/* Other types: generated names tablet_add_value_by_name_<type>, etc. */ +/** + * @brief Writes one tablet to TsFile. + * + * @param writer Writer handle. + * @param tablet Tablet handle. + * @return `RET_OK` on success. + */ +ERRNO tsfile_writer_write(TsFileWriter writer, Tablet tablet); +/** + * @brief Frees tablet resources. + * + * @param[in,out] tablet Tablet pointer. + */ void free_tablet(Tablet* tablet); ``` - - -### Write Tablet into TsFile +## Table model: read (time range and row window) ```C /** - * @brief Writes data from a Tablet to the TsFile. + * @brief Queries table-model data by time range. * - * @param writer [in] Valid TsFileWriter handle. - * @param tablet [in] Tablet containing data. Should be freed after successful - * writing. - * @return ERRNO - RET_OK(0), or error code in errno_define_c.h. - * + * @param reader Reader handle. + * @param table_name Table name. + * @param columns Selected columns. + * @param column_num Number of selected columns. + * @param start_time Start timestamp. + * @param end_time End timestamp. + * @param[out] err_code `RET_OK` on success. + * @return ResultSet handle on success. */ - -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 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); +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 Releases resources associated with a TsFileReader. + * @brief Queries table-model data with optional tag filter and batch mode. * - * @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 error code in errno_define_c.h. + * @param reader Reader handle. + * @param table_name Table name. + * @param columns Selected columns. + * @param column_num Number of selected columns. + * @param start_time Start timestamp. + * @param end_time End timestamp. + * @param tag_filter Optional tag filter. + * @param batch_size <=0 row mode, >0 batch TsBlock mode. + * @param[out] err_code `RET_OK` on success. + * @return ResultSet handle on success. */ -ERRNO tsfile_reader_close(TsFileReader reader); -``` - - - -### Query table/get next - -```C +ResultSet tsfile_query_table_batch( + TsFileReader reader, const char* table_name, char** columns, + uint32_t column_num, Timestamp start_time, Timestamp end_time, + TagFilterHandle tag_filter, int batch_size, ERRNO* err_code); /** - * @brief Query data from the specific table and columns within time range. + * @brief Queries table-model data by row window (offset/limit). * - * @param reader [in] Valid TsFileReader handle from tsfile_reader_new(). - * @param table_name [in] Target table name. Must exist in the TsFile. - * @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. - * @param err_code [out] RET_OK(0) on success, or error code in errno_define_c.h. - * @return ResultSet Query results handle. Must be freed with - * free_tsfile_result_set(). + * @param reader Reader handle. + * @param table_name Table name. + * @param column_names Selected columns. + * @param column_names_len Number of selected columns. + * @param offset Rows to skip. + * @param limit Max rows to return. <0 means unlimited. + * @param tag_filter Optional tag filter. + * @param batch_size <=0 row mode, >0 batch TsBlock mode. + * @param[out] err_code `RET_OK` on success. + * @return ResultSet handle on success. */ -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); +ResultSet tsfile_reader_query_table_by_row( + TsFileReader reader, const char* table_name, char** column_names, + int column_names_len, int offset, int limit, TagFilterHandle tag_filter, + int batch_size, ERRNO* err_code); /** - * @brief Check and fetch the next row in the ResultSet. + * @brief Moves to next row in result set. * - * @param result_set [in] Valid ResultSet handle. - * @param error_code RET_OK(0) on success, or error code in errno_define_c.h. - * @return bool - true: Row available, false: End of data or error. + * @param result_set ResultSet handle. + * @param[out] error_code `RET_OK` while iteration is valid. + * @return `true` if next row exists. */ bool tsfile_result_set_next(ResultSet result_set, ERRNO* error_code); - /** - * @brief Free Result set + * @brief Frees result set resources. * - * @param result_set [in] Valid ResultSet handle ptr. + * @param[in,out] result_set ResultSet pointer. */ 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 (1 <= 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. - * @param result_set [in] valid result set handle. - * @param column_name [in] the name of the column to be checked. - * @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); - -// Supports multiple data types -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. - * @param result_set [in] valid result set handle. - * @param column_index [in] the index of the column to be checked (1 <= index <= column_num). - * @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); - -// Supports multiple data types -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 result set handle. - * @return ResultSetMetaData Metadata handle. Caller should free the - * ResultSetMataData after usage. - * @note Before calling this func, check if the result_set is NULL, which - * may indicates a failed query execution. - */ -ResultSetMetaData tsfile_result_set_get_metadata(ResultSet result_set); - -/** - * @brief Gets column name by index from metadata. - * @param result_set_meta_data [in] Valid result set handle. - * @param column_index [in] Column position (1 <= index <= column_num). - * @return const char* Read-only string. NULL if index invalid. - */ -char* tsfile_result_set_metadata_get_column_name(ResultSetMetaData result_set_meta_data, - uint32_t column_index); - -/** - * @brief Gets column data type by index from metadata. - * @param result_set_meta_data [in] Valid result set meta data handle. - * @param column_index [in] Column position (1 <= index <= column_num). - * @return TSDataType Returns TS_DATATYPE_INVALID(255) if index invalid. - */ -TSDataType tsfile_result_set_metadata_get_data_type( - ResultSetMetaData result_set_meta_data, uint32_t column_index); - -/** - * @brief Gets total number of columns in the result schema. - * @param result_set_meta_data [in] Valid result set meta data handle. - * @return column num in result set metadata. - */ -int tsfile_result_set_metadata_get_column_num(ResultSetMetaData result_set); -``` - - - -### Get Table Schema from TsFile Reader +For batch / Arrow output from a batch `ResultSet` (`batch_size` > 0 in the query that produced it): ```C /** - * @brief Gets specific table's schema in the tsfile. - * @param reader [in], valid reader handle. - * @param table_name [in] Target table name. Must exist in the TsFile. - * @return TableSchema, contains table and column info. - * @note Caller should call free_table_schema to free the tableschema. + * @brief Gets next TsBlock from batch result and converts to Arrow. + * + * @param result_set Batch-mode ResultSet. + * @param[out] out_array Output ArrowArray. + * @param[out] out_schema Output ArrowSchema. + * @return `RET_OK` on success, no-more-data or error code otherwise. + */ +ERRNO tsfile_result_set_get_next_tsblock_as_arrow( + ResultSet result_set, ArrowArray* out_array, ArrowSchema* out_schema); +``` + +Row iteration and `get_value_by_index` / `is_null_by_index` / metadata accessors are shared with the tree model; see [Result set and metadata](#result-set-and-metadata) below. + +## Table model: tag filter + +```C +typedef enum { + TAG_FILTER_EQ = 0, TAG_FILTER_NEQ = 1, TAG_FILTER_LT = 2, + TAG_FILTER_LTEQ = 3, TAG_FILTER_GT = 4, TAG_FILTER_GTEQ = 5, + TAG_FILTER_REGEXP = 6, TAG_FILTER_NOT_REGEXP = 7, +} TagFilterOp; + +/** + * @brief Creates a simple comparison tag filter. + * + * @param reader Reader handle. + * @param table_name Table name. + * @param column_name TAG column name. + * @param value Comparison value. + * @param op Comparison operator. + * @param[out] err_code `RET_OK` on success. + * @return TagFilterHandle on success. + */ +TagFilterHandle tsfile_tag_filter_create( + TsFileReader reader, const char* table_name, const char* column_name, + const char* value, TagFilterOp op, ERRNO* err_code); +/** + * @brief Creates a BETWEEN / NOT BETWEEN tag filter. + * + * @param reader Reader handle. + * @param table_name Table name. + * @param column_name TAG column name. + * @param lower Lower bound. + * @param upper Upper bound. + * @param is_not `true` means NOT BETWEEN. + * @param[out] err_code `RET_OK` on success. + * @return TagFilterHandle on success. + */ +TagFilterHandle tsfile_tag_filter_between( + TsFileReader reader, const char* table_name, const char* column_name, + const char* lower, const char* upper, bool is_not, ERRNO* err_code); +/** + * @brief Combines filters with AND. + * + * @param left Left filter. + * @param right Right filter. + * @return Combined filter handle. + */ +TagFilterHandle tsfile_tag_filter_and(TagFilterHandle left, TagFilterHandle right); +/** + * @brief Combines filters with OR. + * + * @param left Left filter. + * @param right Right filter. + * @return Combined filter handle. + */ +TagFilterHandle tsfile_tag_filter_or(TagFilterHandle left, TagFilterHandle right); +/** + * @brief Negates a filter. + * + * @param filter Input filter. + * @return Negated filter handle. + */ +TagFilterHandle tsfile_tag_filter_not(TagFilterHandle filter); +/** + * @brief Frees a tag filter tree. + * + * @param filter Filter handle. + */ +void tsfile_tag_filter_free(TagFilterHandle filter); + +/** + * @brief Queries table with explicit tag filter. + * + * @param reader Reader handle. + * @param table_name Table name. + * @param columns Selected columns. + * @param column_num Number of selected columns. + * @param start_time Start timestamp. + * @param end_time End timestamp. + * @param tag_filter Tag filter. + * @param batch_size <=0 row mode, >0 batch TsBlock mode. + * @param[out] err_code `RET_OK` on success. + * @return ResultSet handle on success. + */ +ResultSet tsfile_query_table_with_tag_filter( + TsFileReader reader, const char* table_name, char** columns, + uint32_t column_num, Timestamp start_time, Timestamp end_time, + TagFilterHandle tag_filter, int batch_size, ERRNO* err_code); +``` + +## Tree model: read + +```C +/** + * @brief Queries tree-model data by full path list in time range. + * + * @param reader Reader handle. + * @param columns Full paths (`device.measurement`). + * @param column_num Number of paths. + * @param start_time Start timestamp. + * @param end_time End timestamp. + * @param[out] err_code `RET_OK` on success. + * @return ResultSet handle on success. + */ +ResultSet tsfile_query_table_on_tree( + TsFileReader reader, char** columns, uint32_t column_num, + Timestamp start_time, Timestamp end_time, ERRNO* err_code); + +/** + * @brief Queries tree-model data by row with offset/limit. + * + * @param reader Reader handle. + * @param device_ids Device id list. + * @param device_ids_len Device id count. + * @param measurement_names Measurement name list. + * @param measurement_names_len Measurement count. + * @param offset Rows to skip. + * @param limit Max rows to return. <0 means unlimited. + * @param[out] err_code `RET_OK` on success. + * @return ResultSet handle on success. + */ +ResultSet tsfile_reader_query_tree_by_row( + TsFileReader reader, char** device_ids, int device_ids_len, + char** measurement_names, int measurement_names_len, int offset, int limit, + ERRNO* err_code); +``` + +`tsfile_query_table_on_tree` uses full path strings in `columns` (e.g. `device.measurement`). `tsfile_reader_query_tree_by_row` passes parallel arrays of device ids and measurement names. + +## Metadata and devices (tree-oriented) + +```C +/** + * @brief Gets all devices from current file. + * + * @param reader Reader handle. + * @param[out] out_devices Output device array. + * @param[out] out_length Output array length. + * @return `RET_OK` on success. + */ +ERRNO tsfile_reader_get_all_devices(TsFileReader reader, DeviceID** out_devices, + uint32_t* out_length); +/** + * @brief Frees device array returned by `tsfile_reader_get_all_devices`. + * + * @param devices Device array. + * @param length Device count. + */ +void tsfile_free_device_id_array(DeviceID* devices, uint32_t length); + +/** + * @brief Gets timeseries metadata for all devices. + * + * @param reader Reader handle. + * @param[out] out_map Output metadata map. + * @return `RET_OK` on success. + */ +ERRNO tsfile_reader_get_timeseries_metadata_all( + TsFileReader reader, DeviceTimeseriesMetadataMap* out_map); +/** + * @brief Gets timeseries metadata for selected devices. + * + * @param reader Reader handle. + * @param devices Device array input. + * @param length Device count. + * @param[out] out_map Output metadata map. + * @return `RET_OK` on success. + */ +ERRNO tsfile_reader_get_timeseries_metadata_for_devices( + TsFileReader reader, const DeviceID* devices, uint32_t length, + DeviceTimeseriesMetadataMap* out_map); +/** + * @brief Frees metadata map allocated by metadata query APIs. + * + * @param[in,out] map Metadata map pointer. + */ +void tsfile_free_device_timeseries_metadata_map( + DeviceTimeseriesMetadataMap* map); +``` + +## `TsFileReader` open/close and table schema + +```C +/** + * @brief Creates a TsFile reader. + * + * @param pathname Input `.tsfile` path. + * @param[out] err_code `RET_OK` on success. + * @return Reader handle on success. + */ +TsFileReader tsfile_reader_new(const char* pathname, ERRNO* err_code); +/** + * @brief Closes reader and releases resources. + * + * @param reader Reader handle. + * @return `RET_OK` on success. + */ +ERRNO tsfile_reader_close(TsFileReader reader); + +/** + * @brief Gets one table schema by table name. + * + * @param reader Reader handle. + * @param table_name Table name. + * @return TableSchema value. */ TableSchema tsfile_reader_get_table_schema(TsFileReader reader, const char* table_name); /** - * @brief Gets all tables' schema in the tsfile. - * @param size[out] num of tableschema in return ptr. - * @return TableSchema*, an array of table schema. - * @note The caller must call free_table_schema() on each array element - * and free to deallocate the array pointer. + * @brief Gets all table schemas. + * + * @param reader Reader handle. + * @param[out] size Output schema count. + * @return Pointer to schema array. */ TableSchema* tsfile_reader_get_all_table_schemas(TsFileReader reader, - uint32_t* size); - + uint32_t* size); /** - * @brief Free the tableschema's space. - * @param schema [in] the table schema to be freed. + * @brief Gets all timeseries schemas grouped by device. + * + * @param reader Reader handle. + * @param[out] size Output device-schema count. + * @return Pointer to device schema array. + */ +DeviceSchema* tsfile_reader_get_all_timeseries_schemas(TsFileReader reader, + uint32_t* size); +/** + * @brief Frees one table schema. + * + * @param schema Table schema value. */ void free_table_schema(TableSchema schema); +/** + * @brief Frees one device schema. + * + * @param schema Device schema value. + */ +void free_device_schema(DeviceSchema schema); +/* plus free_column_schema, free_timeseries_schema as in the header */ ``` +## Result set and metadata +```C +/** + * @brief Gets result-set metadata descriptor. + * + * @param result_set ResultSet handle. + * @return Metadata descriptor. + */ +ResultSetMetaData tsfile_result_set_get_metadata(ResultSet result_set); +/** + * @brief Gets number of columns in metadata. + * + * @param result_set Metadata descriptor. + * @return Column count. + */ +int tsfile_result_set_metadata_get_column_num(ResultSetMetaData result_set); +/** + * @brief Gets column name by 1-based index. + * + * @param result_set Metadata descriptor. + * @param column_index 1-based column index. + * @return Column name pointer (read-only). + */ +char* tsfile_result_set_metadata_get_column_name( + ResultSetMetaData result_set, uint32_t column_index); +/** + * @brief Gets column type by 1-based index. + * + * @param result_set Metadata descriptor. + * @param column_index 1-based column index. + * @return TSDataType value. + */ +TSDataType tsfile_result_set_metadata_get_data_type( + ResultSetMetaData result_set, uint32_t column_index); +/** + * @brief Frees metadata resources. + * + * @param result_set_meta_data Metadata descriptor. + */ +void free_result_set_meta_data(ResultSetMetaData result_set_meta_data); +/* 1-based column_index for index-based getters */ +#define TSFILE_RESULT_SET_GET_VALUE_BY_NAME(type) /* bool, int32_t, ... */ +#define TSFILE_RESULT_SET_GET_VALUE_BY_INDEX(type) +/** + * @brief Gets current-row string value by column name. + * + * @param result_set ResultSet handle. + * @param column_name Column name. + * @return Newly allocated string (caller frees). + */ +char* tsfile_result_set_get_value_by_name_string(ResultSet result_set, + const char* column_name); +/** + * @brief Gets current-row string value by 1-based column index. + * + * @param result_set ResultSet handle. + * @param column_index 1-based column index. + * @return Newly allocated string (caller frees). + */ +char* tsfile_result_set_get_value_by_index_string(ResultSet result_set, + uint32_t column_index); +/** + * @brief Checks whether current-row value is NULL by column name. + * + * @param result_set ResultSet handle. + * @param column_name Column name. + * @return `true` if NULL. + */ +bool tsfile_result_set_is_null_by_name(ResultSet result_set, + const char* column_name); +/** + * @brief Checks whether current-row value is NULL by 1-based column index. + * + * @param result_set ResultSet handle. + * @param column_index 1-based column index. + * @return `true` if NULL. + */ +bool tsfile_result_set_is_null_by_index(ResultSet result_set, + uint32_t column_index); +``` +## Global time / datatype encoding and compression (optional) +```C +/** + * @brief Gets global time-column encoding. + * + * @return Encoding enum value. + */ +uint8_t get_global_time_encoding(); +/** + * @brief Gets global time-column compression. + * + * @return Compression enum value. + */ +uint8_t get_global_time_compression(); +/** + * @brief Gets default encoding for a data type. + * + * @param data_type Data type enum value. + * @return Encoding enum value. + */ +uint8_t get_datatype_encoding(uint8_t data_type); +/** + * @brief Gets global default compression. + * + * @return Compression enum value. + */ +uint8_t get_global_compression(); +/** + * @brief Sets global time-column encoding. + * + * @param encoding Encoding enum value. + * @return `RET_OK` on success. + */ +int set_global_time_encoding(uint8_t encoding); +/** + * @brief Sets global time-column compression. + * + * @param compression Compression enum value. + * @return `RET_OK` on success. + */ +int set_global_time_compression(uint8_t compression); +/** + * @brief Sets default encoding for one data type. + * + * @param data_type Data type enum value. + * @param encoding Encoding enum value. + * @return `RET_OK` on success. + */ +int set_datatype_encoding(uint8_t data_type, uint8_t encoding); +/** + * @brief Sets global default compression. + * + * @param compression Compression enum value. + * @return `RET_OK` on success. + */ +int set_global_compression(uint8_t compression); +``` +See `tsfile_cwrapper.h` for supported encodings and compressions per type.
diff --git a/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md b/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md index b1642f8..5906bcd 100644 --- a/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md +++ b/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md
@@ -20,7 +20,9 @@ --> # Interface Definitions - C++ -## Write Interface +Headers live under the C++ `src/reader` and `src/writer` directories in the source tree. This page splits APIs by **table model** (SQL-like table and columns) and **tree model** (device + measurement hierarchy). `storage::TsFileTreeReader` / `storage::TsFileTreeWriter` in `tsfile_tree_reader.h` / `tsfile_tree_writer.h` are the dedicated tree APIs; `storage::TsFileReader` is the main **table** query entry and also exposes some path/tree helpers on the same file. + +## Table model: write ### TsFileTableWriter @@ -214,130 +216,382 @@ }; ``` -## Read Interface -### Tsfile Reader -use to execute query in tsfile and return value by ResultSet. +## Table model: read — `TsFileReader` + +Table-oriented queries use `table_name`, column names, optional `Filter` (tag), and optional `batch_size` for TsBlock / batch mode. See `tsfile_reader.h` for full declarations. + ```cpp -/** - * @brief TsfileReader provides the ability to query all files with the suffix - * .tsfile - * - * TsfileReader is designed to query .tsfile files, it accepts tree model - * queries and table model queries, and supports querying metadata such as - * TableSchema and TimeseriesSchema. - */ +namespace storage { + class TsFileReader { public: + /** + * @brief Construct a TsFileReader instance. + */ TsFileReader(); + /** + * @brief Destroy TsFileReader and release held resources. + */ ~TsFileReader(); - /** - * @brief open the tsfile - * - * @param file_path the path of the tsfile which will be opened - * @return Returns 0 on success, or a non-zero error code on failure. - */ - int open(const std::string &file_path); - /** - * @brief close the tsfile, this method should be called after the - * query is finished - * - * @return Returns 0 on success, or a non-zero error code on failure. - */ - int close(); - /** - * @brief query the tsfile by the query expression,Users can construct - * their own query expressions to query tsfile - * - * @param [in] qe the query expression - * @param [out] ret_qds the result set - * @return Returns 0 on success, or a non-zero error code on failure. - */ - int query(storage::QueryExpression *qe, ResultSet *&ret_qds); - /** - * @brief query the tsfile by the path list, start time and end time - * this method is used to query the tsfile by the tree model. - * - * @param [in] path_list the path list - * @param [in] start_time the start time - * @param [in] end_time the end time - * @param [out] result_set the result set - */ - int query(std::vector<std::string> &path_list, int64_t start_time, - int64_t end_time, ResultSet *&result_set); - /** - * @brief query the tsfile by the table name, columns names, start time - * and end time. this method is used to query the tsfile by the table - * model. - * - * @param [in] table_name the table name - * @param [in] columns_names the columns names - * @param [in] start_time the start time - * @param [in] end_time the end time - * @param [out] result_set the result set - */ - int query(const std::string &table_name, - const std::vector<std::string> &columns_names, int64_t start_time, - int64_t end_time, ResultSet *&result_set); /** - * @brief query the tsfile by the table name, columns names, start time - * and end time, tag filter. this method is used to query the tsfile by the - * table model. + * @brief Open a TsFile. * - * @param [in] table_name the table name - * @param [in] columns_names the columns names - * @param [in] start_time the start time - * @param [in] end_time the end time - * @param [in] tag_filter the tag filter - * @param [out] result_set the result set + * @param file_path Path to the target `.tsfile`. + * @return Returns 0 on success, non-zero on failure. + */ + int open(const std::string& file_path); + /** + * @brief Close the currently opened TsFile. + * + * @return Returns 0 on success, non-zero on failure. + */ + int close(); + + /** + * @brief Query by expression tree. + * + * @param qe Input query expression. + * @param[out] ret_qds Output result set. + * @return Returns 0 on success, non-zero on failure. + */ + int query(storage::QueryExpression* qe, ResultSet*& ret_qds); + + /** + * @brief Query tree-style full paths in a time range. + * + * @param path_list Full path list, e.g. `device.measurement`. + * @param start_time Start timestamp (inclusive). + * @param end_time End timestamp (inclusive). + * @param[out] result_set Output result set. + * @return Returns 0 on success, non-zero on failure. + */ + int query(std::vector<std::string>& path_list, int64_t start_time, + int64_t end_time, ResultSet*& result_set); + + /** + * @brief Query table data in a time range. + * + * @param table_name Target table name. + * @param columns_names Requested columns. + * @param start_time Start timestamp (inclusive). + * @param end_time End timestamp (inclusive). + * @param[out] result_set Output result set. + * @param batch_size <= 0 means row-by-row mode, > 0 means TsBlock mode. + * @return Returns 0 on success, non-zero on failure. */ int query(const std::string& table_name, const std::vector<std::string>& columns_names, int64_t start_time, - int64_t end_time, ResultSet*& result_set, Filter* tag_filter); + int64_t end_time, ResultSet*& result_set, int batch_size = -1); /** - * @brief destroy the result set, this method should be called after the - * query is finished and result_set + * @brief Query table data in a time range with tag filter. * - * @param qds the result set + * @param table_name Target table name. + * @param columns_names Requested columns. + * @param start_time Start timestamp (inclusive). + * @param end_time End timestamp (inclusive). + * @param[out] result_set Output result set. + * @param tag_filter Optional filter on TAG columns. + * @param batch_size <= 0 means row-by-row mode, > 0 means TsBlock mode. + * @return Returns 0 on success, non-zero on failure. */ - void destroy_query_data_set(ResultSet *qds); - ResultSet *read_timeseries( - const std::shared_ptr<IDeviceID> &device_id, - const std::vector<std::string> &measurement_name); + int query(const std::string& table_name, + const std::vector<std::string>& columns_names, int64_t start_time, + int64_t end_time, ResultSet*& result_set, Filter* tag_filter, + int batch_size = 0); + /** - * @brief get all devices in the tsfile + * @brief Query tree full paths by row with offset/limit. * - * @param table_name the table name - * @return std::vector<std::shared_ptr<IDeviceID>> the device id list + * @param path_list Full path list. + * @param offset Number of leading rows to skip (>= 0). + * @param limit Maximum rows to return. < 0 means unlimited. + * @param[out] result_set Output result set. + * @return Returns 0 on success, non-zero on failure. */ - std::vector<std::shared_ptr<IDeviceID>> get_all_devices( - std::string table_name); + int queryByRow(std::vector<std::string>& path_list, int offset, int limit, + ResultSet*& result_set); + /** - * @brief get the timeseries schema by the device id and measurement name + * @brief Query table by row with offset/limit. * - * @param [in] device_id the device id - * @param [out] result std::vector<MeasurementSchema> the measurement schema - * list - * @return Returns 0 on success, or a non-zero error code on failure. + * @param table_name Target table name. + * @param column_names Requested columns. + * @param offset Number of leading rows to skip (>= 0). + * @param limit Maximum rows to return. < 0 means unlimited. + * @param[out] result_set Output result set. + * @param tag_filter Optional filter on TAG columns. + * @param batch_size <= 0 means row-by-row mode, > 0 means TsBlock mode. + * @return Returns 0 on success, non-zero on failure. + */ + int queryByRow(const std::string& table_name, + const std::vector<std::string>& column_names, int offset, + int limit, ResultSet*& result_set, + Filter* tag_filter = nullptr, int batch_size = 0); + + /** + * @brief Query table view over tree measurements. + * + * @param measurement_names Measurement names to select. + * @param start_time Start timestamp (inclusive). + * @param end_time End timestamp (inclusive). + * @param[out] result_set Output result set. + * @return Returns 0 on success, non-zero on failure. + */ + int query_table_on_tree(const std::vector<std::string>& measurement_names, + int64_t start_time, int64_t end_time, + ResultSet*& result_set); + + /** + * @brief Destroy a result set created by this reader. + * + * @param qds Result set pointer to destroy. + */ + void destroy_query_data_set(ResultSet* qds); + + /** + * @brief Read timeseries for one device with selected measurements. + * + * @param device_id Target device id. + * @param measurement_name Measurement names to read. + * @return ResultSet pointer on success. + */ + ResultSet* read_timeseries( + const std::shared_ptr<IDeviceID>& device_id, + const std::vector<std::string>& measurement_name); + + /** + * @brief Get all devices under a specified table. + * + * @param table_name Target table name. + * @return Device list. + */ + std::vector<std::shared_ptr<IDeviceID>> get_all_devices(std::string table_name); + /** + * @brief Get all device IDs in file. + * + * @return Device list. + */ + std::vector<std::shared_ptr<IDeviceID>> get_all_device_ids(); + /** + * @brief Get all devices in file (alias form). + * + * @return Device list. + */ + std::vector<std::shared_ptr<IDeviceID>> get_all_devices(); + + /** + * @brief Get timeseries schema for one device. + * + * @param device_id Target device. + * @param[out] result Output measurement schemas. + * @return Returns 0 on success, non-zero on failure. */ int get_timeseries_schema(std::shared_ptr<IDeviceID> device_id, - std::vector<MeasurementSchema> &result); + std::vector<MeasurementSchema>& result); + /** - * @brief get the table schema by the table name + * @brief Get timeseries metadata for specified devices. * - * @param table_name the table name - * @return std::shared_ptr<TableSchema> the table schema + * @param device_ids Devices to query. + * @return Map of device -> timeseries metadata. */ - std::shared_ptr<TableSchema> get_table_schema( - const std::string &table_name); + DeviceTimeseriesMetadataMap get_timeseries_metadata( + const std::vector<std::shared_ptr<IDeviceID>>& device_ids); /** - * @brief get all table schemas in the tsfile + * @brief Get timeseries metadata for all devices. * - * @return std::vector<std::shared_ptr<TableSchema>> the table schema list + * @return Map of device -> timeseries metadata. + */ + DeviceTimeseriesMetadataMap get_timeseries_metadata(); + + /** + * @brief Get one table schema by name. + * + * @param table_name Target table name. + * @return Table schema pointer. + */ + std::shared_ptr<TableSchema> get_table_schema(const std::string& table_name); + /** + * @brief Get all table schemas in file. + * + * @return List of table schemas. */ std::vector<std::shared_ptr<TableSchema>> get_all_table_schemas(); }; + +} // namespace storage +``` + +## Tree model: `TsFileTreeReader` and `TsFileTreeWriter` + +Use `tsfile_tree_reader.h` and `tsfile_tree_writer.h`. `TsFileTreeReader` holds a `std::shared_ptr<TsFileReader>` and exposes device + measurement queries; `TsFileTreeWriter` wraps a `std::shared_ptr<TsFileWriter>` for device/measurement registration and `Tablet` / `TsRecord` writes. + +```cpp +namespace storage { + +class TsFileTreeReader { + public: + /** + * @brief Construct a TsFileTreeReader instance. + */ + TsFileTreeReader(); + /** + * @brief Destroy TsFileTreeReader and release resources. + */ + ~TsFileTreeReader(); + + /** + * @brief Open a TsFile. + * + * @param file_path Path to the target `.tsfile`. + * @return Returns 0 on success, non-zero on failure. + */ + int open(const std::string& file_path); + /** + * @brief Close current TsFile. + * + * @return Returns 0 on success, non-zero on failure. + */ + int close(); + + /** + * @brief Query tree data by device list + measurement list in time range. + * + * @param device_ids Device identifiers. + * @param measurement_names Measurements to query. + * @param start_time Start timestamp (inclusive). + * @param end_time End timestamp (inclusive). + * @param[out] result_set Output result set. + * @return Returns 0 on success, non-zero on failure. + */ + int query(const std::vector<std::string>& device_ids, + const std::vector<std::string>& measurement_names, + int64_t start_time, int64_t end_time, ResultSet*& result_set); + + /** + * @brief Query tree data by row with offset/limit. + * + * @param device_ids Device identifiers. + * @param measurement_names Measurements to query. + * @param offset Number of leading rows to skip (>= 0). + * @param limit Maximum rows to return. < 0 means unlimited. + * @param[out] result_set Output result set. + * @return Returns 0 on success, non-zero on failure. + */ + int queryByRow(const std::vector<std::string>& device_ids, + const std::vector<std::string>& measurement_names, + int offset, int limit, ResultSet*& result_set); + + /** + * @brief Destroy query result set allocated by tree reader. + * + * @param result_set Result set pointer. + */ + void destroy_query_data_set(ResultSet* result_set); + + /** + * @brief Get measurement schema of one device. + * + * @param device_id Device identifier string. + * @return Measurement schema list. + */ + std::vector<MeasurementSchema> get_device_schema(const std::string& device_id); + /** + * @brief Get all device IDs in string form. + * + * @return Device ID string list. + */ + std::vector<std::string> get_all_device_ids(); + /** + * @brief Get all devices in IDeviceID form. + * + * @return Device list. + */ + std::vector<std::shared_ptr<IDeviceID>> get_all_devices(); + + /** + * @brief Get timeseries metadata for selected devices. + * + * @param device_ids Devices to query. + * @return Map of device -> timeseries metadata. + */ + DeviceTimeseriesMetadataMap get_timeseries_metadata( + const std::vector<std::shared_ptr<IDeviceID>>& device_ids); + /** + * @brief Get timeseries metadata for all devices. + * + * @return Map of device -> timeseries metadata. + */ + DeviceTimeseriesMetadataMap get_timeseries_metadata(); +}; + +class TsFileTreeWriter { + public: + /** + * @brief Construct tree writer from target file. + * + * @param writer_file Target write file handle. + * @param memory_threshold Buffered memory threshold before auto flush. + */ + explicit TsFileTreeWriter(WriteFile* writer_file, + uint64_t memory_threshold = 128 * 1024 * 1024); + /** + * @brief Construct tree writer from restorable writer. + * + * @param restorable_writer Restored writer handle. + * @param memory_threshold Buffered memory threshold before auto flush. + */ + explicit TsFileTreeWriter(RestorableTsFileIOWriter* restorable_writer, + uint64_t memory_threshold = 128 * 1024 * 1024); + + /** + * @brief Register one non-aligned timeseries for a device. + * + * @param device_id Device identifier. + * @param schema Measurement schema pointer. + * @return Returns 0 on success, non-zero on failure. + */ + int register_timeseries(std::string& device_id, MeasurementSchema* schema); + /** + * @brief Register aligned timeseries list for a device. + * + * @param device_id Device identifier. + * @param schemas Measurement schema pointer list. + * @return Returns 0 on success, non-zero on failure. + */ + int register_timeseries(std::string& device_id, + std::vector<MeasurementSchema*> schemas); + /** + * @brief Write one batch tablet. + * + * @param tablet Input tablet. + * @return Returns 0 on success, non-zero on failure. + */ + int write(const Tablet& tablet); + /** + * @brief Write one row record. + * + * @param record Input record. + * @return Returns 0 on success, non-zero on failure. + */ + int write(const TsRecord& record); + /** + * @brief Flush buffered data to storage. + * + * @return Returns 0 on success, non-zero on failure. + */ + int flush(); + /** + * @brief Close writer and release resources. + * + * @return Returns 0 on success, non-zero on failure. + */ + int close(); +}; + +} // namespace storage ``` ### ResultSet A collection of query.Support iterator to get data, and directly through the column name or index to get specific data. @@ -388,6 +642,7 @@ */ template <typename T> T get_value(const std::string& column_name); + /** * @brief Get the value of the column by column index * * @param column_index the index of the column starting from 1
diff --git a/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-Java.md b/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-Java.md index b71931d..0a09cc0 100644 --- a/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-Java.md +++ b/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-Java.md
@@ -28,10 +28,16 @@ ```Java interface ITsFileWriter extends AutoCloseable { - // Write data + /** + * Write one tablet into TsFile. + * + * @param tablet input tablet. + */ void write(Tablet tablet); - // Close Write + /** + * Close writer and flush buffered data. + */ void close(); } ``` @@ -42,16 +48,35 @@ ```Java class TsFileWriterBuilder { - // Build ITsFileWriter object + /** + * Build writer instance from configured options. + * + * @return ITsFileWriter instance. + */ public ITsFileWriter build(); - // target file + /** + * Set target file. + * + * @param file target file. + * @return builder itself. + */ public TsFileWriterBuilder file(File file); - // Used to construct table structures + /** + * Set table schema. + * + * @param schema table schema. + * @return builder itself. + */ public TsFileWriterBuilder tableSchema(TableSchema schema); - // Used to limit the memory size of objects + /** + * Set memory threshold for internal buffering. + * + * @param memoryThreshold threshold in bytes. + * @return builder itself. + */ public TsFileWriterBuilder memoryThreshold(long memoryThreshold); } ``` @@ -62,35 +87,77 @@ ```Java class TableSchema { - // Constructor function + /** + * Construct table schema. + * + * @param tableName table name. + * @param columnSchemaList column schema list. + */ public TableSchema(String tableName, List<ColumnSchema> columnSchemaList); } class ColumnSchema { - // Constructor function + /** + * Construct one column schema. + * + * @param columnName column name. + * @param dataType column data type. + * @param columnCategory column category. + */ public ColumnSchema(String columnName, TSDataType dataType, ColumnCategory columnCategory); - // Get column names + /** + * Get column name. + * + * @return column name. + */ public String getColumnName(); - // Get the data type of the column + /** + * Get column data type. + * + * @return TSDataType. + */ public TSDataType getDataType(); - // Get column category + /** + * Get column category. + * + * @return column category. + */ public Tablet.ColumnCategory getColumnCategory(); } class ColumnSchemaBuilder { - // Build ColumnSchema object + /** + * Build ColumnSchema object. + * + * @return ColumnSchema instance. + */ public ColumnSchema build(); - // Column Name + /** + * Set column name. + * + * @param columnName column name. + * @return builder itself. + */ public ColumnSchemaBuilder name(String columnName); - // The data type of the column + /** + * Set column data type. + * + * @param columnType data type. + * @return builder itself. + */ public ColumnSchemaBuilder dataType(TSDataType columnType); - // Column category + /** + * Set column category. + * + * @param columnCategory column category. + * @return builder itself. + */ public ColumnSchemaBuilder category(ColumnCategory columnCategory); // Supported types @@ -121,11 +188,28 @@ ```Java class Tablet { - // Constructor function + /** + * Construct tablet with default row capacity. + * + * @param columnNameList column names. + * @param dataTypeList column data types. + */ public Tablet(List<String> columnNameList, List<TSDataType> dataTypeList); + /** + * Construct tablet with explicit row capacity. + * + * @param columnNameList column names. + * @param dataTypeList column data types. + * @param maxRowNum max row count. + */ public Tablet(List<String> columnNameList, List<TSDataType> dataTypeList, int maxRowNum); - // Interface for adding timestamps + /** + * Set timestamp for one row. + * + * @param rowIndex target row index. + * @param timestamp timestamp value. + */ void addTimestamp(int rowIndex, long timestamp); // Interface for adding values @@ -158,19 +242,47 @@ ```Java interface ITsFileReader extends AutoCloseable { - // Used to execute queries and return results + /** + * Query table data in time range. + * + * @param tableName table name. + * @param columnNames selected columns. + * @param startTime start timestamp. + * @param endTime end timestamp. + * @return query result set. + */ ResultSet query(String tableName, List<String> columnNames, long startTime, long endTime); - // Used to execute queries and return results + /** + * Query table data in time range with tag filter. + * + * @param tableName table name. + * @param columnNames selected columns. + * @param startTime start timestamp. + * @param endTime end timestamp. + * @param tagFilter tag filter. + * @return query result set. + */ ResultSet query(String tableName, List<String> columnNames, long startTime, long endTime, Filter tagFilter); - // Return the schema of the table named tableName in tsfile + /** + * Get schema of one table. + * + * @param tableName table name. + * @return optional table schema. + */ Optional<TableSchema> getTableSchemas(String tableName); - // Retrieve schema information for all tables in the tsfile + /** + * Get schemas of all tables. + * + * @return list of table schemas. + */ List<TableSchema> getAllTableSchema(); - // Close query + /** + * Close reader. + */ void close(); } ``` @@ -181,10 +293,19 @@ ```Java class TsFileReaderBuilder { - // Build ITsFileReader object + /** + * Build reader instance. + * + * @return ITsFileReader instance. + */ public ITsFileReader build(); - // target file + /** + * Set target file. + * + * @param file target tsfile. + * @return builder itself. + */ public TsFileReaderBuilder file(File file); } ``` @@ -195,7 +316,11 @@ ```Java interface ResultSet extends AutoCloseable { - // Move the cursor to the next row and return whether there is still data + /** + * Move to next row. + * + * @return true if next row exists. + */ boolean next(); // Get the value of the current row and a certain column @@ -216,14 +341,31 @@ byte[] getBinary(String columnName); byte[] getBinary(int columnIndex); - // Determine whether a column is NULL in the current row + /** + * Check if current-row column is NULL. + * + * @param columnName column name. + * @return true if null. + */ boolean isNull(String columnName); + /** + * Check if current-row column is NULL. + * + * @param columnIndex 1-based column index. + * @return true if null. + */ boolean isNull(int columnIndex); - // Close the current result set + /** + * Close result set. + */ void close(); - // Obtain the header of the result set + /** + * Get result-set metadata. + * + * @return ResultSetMetadata. + */ ResultSetMetadata getMetadata(); } ``` @@ -234,10 +376,20 @@ ```Java interface ResultSetMetadata { - // Obtain the column name of the Nth column in the result set + /** + * Get column name by index. + * + * @param columnIndex 1-based column index. + * @return column name. + */ String getColumnName(int columnIndex); - // Obtain the data type of the Nth column in the result set + /** + * Get column type by index. + * + * @param columnIndex 1-based column index. + * @return TSDataType. + */ TSDataType getColumnType(int columnIndex); } ```
diff --git a/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md b/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md index 849f1c0..78b09f0 100644 --- a/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md +++ b/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md
@@ -20,6 +20,8 @@ --> # Interface Definitions - Python +The public package exports `TsFileReader` / `ResultSet` (Cython `TsFileReaderPy` / `ResultSetPy`), `TsFileTableWriter` for **table** writes, and `TsFileWriter` for lower-level / tree-style registration. **Table** queries: `query_table`, `query_table_by_row`. **Tree** paths: `query_table_on_tree`, `query_tree_by_row`, `query_timeseries` (device + sensors). Use `tsfile.tag_filter` with `query_table` / `query_table_by_row` for TAG columns. + ## Schema ```Python @@ -41,13 +43,12 @@ class ColumnCategory(IntEnum): """ - Enumeration of column categories in TsFile. - TAG: Represents a tag column, used for metadata. - FIELD: Represents a field column, used for storing actual data values. + TAG / FIELD / ATTRIBUTE / TIME (see `tsfile.constants`). """ - TAG = 0 FIELD = 1 + ATTRIBUTE = 2 + TIME = 3 class ColumnSchema: """Defines schema for a table column (name, datatype, category).""" @@ -140,59 +141,160 @@ ``` -## Read Interface +## Read interface -### TsFileReader +### `TsFileReader` (`TsFileReaderPy`) ```python class TsFileReader: """ - Query table data from a TsFile. - """ - - """ - Initialize a TsFile reader for the specified file path. - :param pathname: The path to the TsFile. - :return no return value. - """ - def __init__(self, pathname) + Open a TsFile reader. + :param pathname: Path to the TsFile. + :return: None. + """ + def __init__(self, pathname: str) -> None """ - Executes a time range query on the specified table and columns. + Query table-model data in a time range. - :param table_name: The name of the table to query. - :param column_names: A list of column names to retrieve. - :param start_time: The start time of the query range (default: minimum int64 value). - :param end_time: The end time of the query range (default: maximum int64 value). - :return: A query result set handler. + :param table_name: Target table name. + :param column_names: Requested columns. + :param start_time: Start timestamp (default INT64_MIN). + :param end_time: End timestamp (default INT64_MAX). + :param tag_filter: Optional `TagFilter` on TAG columns. + :param batch_size: <=0 row mode, >0 batch mode. + :return: ResultSet handle. """ - def query_table(self, table_name : str, column_names : List[str], - start_time : int = np.iinfo(np.int64).min, - end_time: int = np.iinfo(np.int64).max) -> ResultSet + def query_table( + self, + table_name: str, + column_names: List[str], + start_time: int = INT64_MIN, + end_time: int = INT64_MAX, + tag_filter: Optional[TagFilter] = None, + batch_size: int = 0, + ) -> ResultSet """ - Retrieves the schema of the specified table. + Query table-model data by row window. - :param table_name: The name of the table. - :return: The schema of the specified table. + :param table_name: Target table name. + :param column_names: Requested columns. + :param offset: Number of leading rows to skip. + :param limit: Max rows to return; <0 means unlimited. + :param tag_filter: Optional `TagFilter` on TAG columns. + :param batch_size: <=0 row mode, >0 batch mode. + :return: ResultSet handle. """ - def get_table_schema(self, table_name : str)-> TableSchema - + def query_table_by_row( + self, + table_name: str, + column_names: List[str], + offset: int = 0, + limit: int = -1, + tag_filter: Optional[TagFilter] = None, + batch_size: int = 0, + ) -> ResultSet """ - Retrieves the schemas of all tables in the TsFile. + Query tree-model full paths in a time range. - :return: A dictionary mapping table names to their schemas. + :param column_names: Full path list, e.g. `device.measurement`. + :param start_time: Start timestamp. + :param end_time: End timestamp. + :return: ResultSet handle. """ - def get_all_table_schemas(self) ->dict[str, TableSchema] - + def query_table_on_tree( + self, + column_names: List[str], + start_time: int = INT64_MIN, + end_time: int = INT64_MAX, + ) -> ResultSet """ - Closes the TsFile reader. If the reader has active result sets, they will be invalidated. - """ - def close(self) + Query tree-model data by row with offset/limit. + :param device_ids: Device id list. + :param measurement_names: Measurement name list. + :param offset: Number of leading rows to skip. + :param limit: Max rows to return; <0 means unlimited. + :return: ResultSet handle. + """ + def query_tree_by_row( + self, + device_ids: List[str], + measurement_names: List[str], + offset: int = 0, + limit: int = -1, + ) -> ResultSet + + """ + Query one device with selected sensors in time range. + + :param device_name: Device id. + :param sensor_list: Sensor/measurement names. + :param start_time: Start timestamp. + :param end_time: End timestamp. + :return: ResultSet handle. + """ + def query_timeseries( + self, + device_name: str, + sensor_list: List[str], + start_time: int = 0, + end_time: int = 0, + ) -> ResultSet + + """ + Get schema of one table. + + :param table_name: Table name. + :return: TableSchema object. + """ + def get_table_schema(self, table_name: str) -> TableSchema + """ + Get schemas of all tables. + + :return: Dict of table name -> TableSchema. + """ + def get_all_table_schemas(self) -> Dict[str, TableSchema] + """ + Get all timeseries schemas. + + :return: SDK-defined collection of device/timeseries schemas. + """ + def get_all_timeseries_schemas(self): + """All timeseries (device) schemas in the file; return type is SDK-defined.""" + + """ + Get all devices in the file. + + :return: List of DeviceID. + """ + def get_all_devices(self) -> List[DeviceID] + """ + Get timeseries metadata for all or selected devices. + + :param device_ids: None means all devices; [] means empty result. + :return: Dict keyed by device path. + """ + def get_timeseries_metadata( + self, device_ids: Optional[List] = None + ) -> Dict[str, DeviceTimeseriesMetadataGroup] + + """ + Close reader and invalidate active result sets. + """ + def close(self) -> None + """ + Context manager enter. + """ + def __enter__(self) -> "TsFileReader" + """ + Context manager exit. + """ + def __exit__(self, *args) -> None ``` ### ResultSet @@ -228,16 +330,23 @@ :param max_row_num: The maximum number of rows to retrieve. Default is 1024. :return: A DataFrame containing data from the query result set. """ - def read_data_frame(self, max_row_num : int = 1024) -> DataFrame + def read_data_frame(self, max_row_num: int = 1024) -> DataFrame - """ - Retrieves the value at the specified index from the query result set. + Fetch next Arrow batch in batch mode. - :param index: The index of the value to retrieve, 1 <= index <= column_num. - :return: The value at the specified index. + :return: `pyarrow.Table` for next batch, or None when exhausted. """ - def get_value_by_index(self, index : int) + def read_arrow_batch(self): + ... + + """ + Get value by 1-based column index. + + :param index: 1-based index. + :return: Typed field value from current row. + """ + def get_value_by_index(self, index: int) """
diff --git a/src/UserGuide/latest/QuickStart/QuickStart-C.md b/src/UserGuide/latest/QuickStart/QuickStart-C.md index 0d03e45..7a7f84f 100644 --- a/src/UserGuide/latest/QuickStart/QuickStart-C.md +++ b/src/UserGuide/latest/QuickStart/QuickStart-C.md
@@ -85,11 +85,14 @@ ``` Note: Set ${SDK_LIB} to your TsFile library directory. -## Writing Process +## Writing process (table model) + +The C API is **table-oriented** for this walkthrough: `TableSchema`, `Tablet`, and `tsfile_writer_write`. For **tree** reads/writes at the C level, see the tree query and metadata sections in [C interface definition](./InterfaceDefinition/InterfaceDefinition-C.md) (C++ has dedicated `TsFileTreeReader` / `TsFileTreeWriter` in the source tree). ### Construct TsFileWriter ```C +#include <string.h> ERRNO code = 0; char* table_name = "table1"; @@ -134,8 +137,10 @@ for (int row = 0; row < 5; row++) { Timestamp timestamp = row; tablet_add_timestamp(tablet, row, timestamp); - tablet_add_value_by_name_string(tablet, row, "id1", "id_field_1"); - tablet_add_value_by_name_string(tablet, row, "id2", "id_field_2"); + tablet_add_value_by_name_string_with_len( + tablet, row, "id1", "id_field_1", (int)strlen("id_field_1")); + tablet_add_value_by_name_string_with_len( + tablet, row, "id2", "id_field_2", (int)strlen("id_field_2")); tablet_add_value_by_name_int32_t(tablet, row, "s1", row); } @@ -161,7 +166,9 @@ The sample code of using these interfaces is in <https://github.com/apache/tsfile/blob/develop/cpp/examples/c_examples/demo_write.c> -## Reading Process +## Reading process (table model) + +Column access by index in the C wrapper is **1-based** (1 … N), matching `cpp/examples/c_examples/demo_read.c` and the underlying `ResultSet` API. ### Construct TsFileReader @@ -197,9 +204,9 @@ tsfile_result_set_metadata_get_data_type(metadata, i)); } - // Get data by column name or index. + // Get data by column name or index (1-based column_index). while (tsfile_result_set_next(ret, &code) && code == RET_OK) { - // Timestamp at column 1 and column index begin from 1. + // Time column is usually index 1 for this query layout. Timestamp timestamp = tsfile_result_set_get_value_by_index_int64_t(ret, 1); printf("%ld\n", timestamp); @@ -261,4 +268,4 @@ The sample code of using these interfaces is in <https://github.com/apache/tsfile/blob/develop/cpp/examples/c_examples/demo_read.c> -> Note: The above read/write examples are all based on the table model interface. For details about the interface definition, please refer to [C Interface Definition](./InterfaceDefinition/InterfaceDefinition-C.md). If you need information regarding the tree model, please contact us. +> The read/write examples above use the **table** C API. For **tree** queries (`tsfile_query_table_on_tree`, `tsfile_reader_query_tree_by_row`), device metadata, and tag filters, see [C interface definition](./InterfaceDefinition/InterfaceDefinition-C.md). In C++ the tree model is also exposed as `storage::TsFileTreeReader` / `storage::TsFileTreeWriter` in `tsfile_tree_reader.h` / `tsfile_tree_writer.h` in the source repository.
diff --git a/src/UserGuide/latest/QuickStart/QuickStart-CPP.md b/src/UserGuide/latest/QuickStart/QuickStart-CPP.md index 4f92b9d..588b451 100644 --- a/src/UserGuide/latest/QuickStart/QuickStart-CPP.md +++ b/src/UserGuide/latest/QuickStart/QuickStart-CPP.md
@@ -142,14 +142,16 @@ ### Close File ```cpp - writer->close() + writer->close(); ``` ### Sample Code The sample code of using these interfaces is in <https://github.com/apache/tsfile/blob/develop/cpp/examples/cpp_examples/demo_write.cpp> -## Query Process +## Query process (table model with `TsFileReader`) + +Tree-oriented C++ code should use `storage::TsFileTreeReader` (see the *Tree model* section in [C++ interface definition](./InterfaceDefinition/InterfaceDefinition-CPP.md)). The steps below use the **table** API on `TsFileReader`. ### Construct TsFileReader @@ -247,4 +249,4 @@ The sample code of using these interfaces is in <https://github.com/apache/tsfile/blob/develop/cpp/examples/cpp_examples/demo_read.cpp> -> Note: The above read/write examples are all based on the table model interface. For details about the interface definition, please refer to [C++ Interface Definition](./InterfaceDefinition/InterfaceDefinition-CPP.md). If you need information regarding the tree model, please contact us. +> The read/write steps above use the **table** API (`TsFileTableWriter` / `TsFileReader`). For the **tree** API, use `TsFileTreeWriter` and `TsFileTreeReader` in the source tree headers `tsfile_tree_writer.h` / `tsfile_tree_reader.h` and the [C++ interface definition](./InterfaceDefinition/InterfaceDefinition-CPP.md).
diff --git a/src/UserGuide/latest/QuickStart/QuickStart-PYTHON.md b/src/UserGuide/latest/QuickStart/QuickStart-PYTHON.md index c29dfba..29974c8 100644 --- a/src/UserGuide/latest/QuickStart/QuickStart-PYTHON.md +++ b/src/UserGuide/latest/QuickStart/QuickStart-PYTHON.md
@@ -127,7 +127,9 @@ writer.write_table(tablet) ``` -## Reading Process +## Reading process (table model) + +`TsFileReader` also supports **tree** queries: `query_table_on_tree`, `query_tree_by_row`, and `query_timeseries` — see [Python interface definition](./InterfaceDefinition/InterfaceDefinition-Python.md). ```Python import os @@ -158,5 +160,5 @@ The sample code of using these interfaces is in：https://github.com/apache/tsfile/blob/develop/python/examples/example.py -> Note: The above read/write examples are all based on the table model interface. For details about the interface definition, please refer to [Python Interface Definition](./InterfaceDefinition/InterfaceDefinition-Python.md). If you need information regarding the tree model, please contact us. +> The snippets above use the **table** writer/reader. Tree-style usage is documented in [Python interface definition](./InterfaceDefinition/InterfaceDefinition-Python.md) (`query_table_on_tree`, `query_tree_by_row`, etc.). C++ tree APIs are `TsFileTreeReader` / `TsFileTreeWriter` in the source headers `tsfile_tree_reader.h` / `tsfile_tree_writer.h`.
diff --git a/src/UserGuide/latest/QuickStart/QuickStart.md b/src/UserGuide/latest/QuickStart/QuickStart.md index fa7b25e..8216138 100644 --- a/src/UserGuide/latest/QuickStart/QuickStart.md +++ b/src/UserGuide/latest/QuickStart/QuickStart.md
@@ -20,6 +20,8 @@ --> # Quick Start - Java +The following steps use the **table**-model Java API (`ITsFileWriter`, `TableSchema`, `Tablet`). C/C++/Python tree-oriented APIs are described in the per-language quick starts and interface pages. + ## Dependencies - JDK >=1.8
diff --git a/src/zh/UserGuide/latest/QuickStart/Data-Model.md b/src/zh/UserGuide/latest/QuickStart/Data-Model.md index c4662bb..8daa77c 100644 --- a/src/zh/UserGuide/latest/QuickStart/Data-Model.md +++ b/src/zh/UserGuide/latest/QuickStart/Data-Model.md
@@ -30,6 +30,7 @@ | **时间列（TIME）** | 每个时序表必须有一个时间列，数据类型为 TIMESTAMP，名称可以自定义<br>时间列的值不能为空，必须顺序的。 | | **标签列（TAG）** | 设备的唯一标识（联合主键），可以为 0 至多个<br>标识列的数据类型目前仅支持String，不指定时默认为String<br>标签信息不可修改和删除，但允许增加<br>推荐按粒度由大到小进行排列<br>写入时必须指定所有标识列（未指定的标识列默认使用 null 填充）| | **测点列（FIELD）** | 一个设备采集的测点可以有1个至多个，值随时间变化<br>表的测点列没有数量限制，可以达到数十万以上<br>字段支持多种数据类型（与标签列固定为STRING类型不同）。 | +| **属性列（ATTRIBUTE）** | 接口层支持的附加列类别（与 TAG/FIELD/TIME 并列）<br>具体使用场景以各语言 SDK 与建模约定为准。 | ## 示例
diff --git a/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md b/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md index 45db6f3..f40cafa 100644 --- a/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md +++ b/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md
@@ -32,10 +32,16 @@ TS_DATATYPE_FLOAT = 3, TS_DATATYPE_DOUBLE = 4, TS_DATATYPE_TEXT = 5, - TS_DATATYPE_STRING = 11 + TS_DATATYPE_VECTOR = 6, + TS_DATATYPE_TIMESTAMP = 8, + TS_DATATYPE_DATE = 9, + TS_DATATYPE_BLOB = 10, + TS_DATATYPE_STRING = 11, + TS_DATATYPE_NULL_TYPE = 254, + TS_DATATYPE_INVALID = 255 } TSDataType; -typedef enum column_category { TAG = 0, FIELD = 1 } ColumnCategory; +typedef enum column_category { TAG = 0, FIELD = 1, ATTRIBUTE = 2, TIME = 3 } ColumnCategory; // ColumnSchema：表示单个列的模式，包括列名、数据类型和分类。 typedef struct column_schema { @@ -173,9 +179,10 @@ * * @param value [输入] 以 '\0' 结尾的字符串，调用者保留所有权。 */ -ERRNO tablet_add_value_by_name_string(Tablet tablet, uint32_t row_index, - const char* column_name, - const char* value); +ERRNO tablet_add_value_by_name_string_with_len(Tablet tablet, uint32_t row_index, + const char* column_name, + const char* value, + int value_len); // 支持多种数据类型插入 ERRNO tablet_add_value_by_name_int32_t(Tablet tablet, uint32_t row_index, @@ -202,9 +209,10 @@ * * @param value [输入] 字符串会被内部复制。 */ -ERRNO tablet_add_value_by_index_string(Tablet tablet, uint32_t row_index, - uint32_t column_index, - const char* value); +ERRNO tablet_add_value_by_index_string_with_len(Tablet tablet, uint32_t row_index, + uint32_t column_index, + const char* value, + int value_len); ERRNO tablet_add_value_by_index_int32_t(Tablet tablet, uint32_t row_index,
diff --git a/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md b/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md index a652c81..150e5eb 100644 --- a/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md +++ b/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md
@@ -336,6 +336,61 @@ std::vector<std::shared_ptr<TableSchema>> get_all_table_schemas(); }; ``` + +## 树模型接口（TsFileTreeReader / TsFileTreeWriter） + +树模型建议使用 `tsfile_tree_reader.h` 和 `tsfile_tree_writer.h` 中的专用接口： + +```cpp +namespace storage { + +class TsFileTreeReader { + public: + TsFileTreeReader(); + ~TsFileTreeReader(); + int open(const std::string& file_path); + int close(); + + // 按 device + measurement 列表进行时间范围查询 + int query(const std::vector<std::string>& device_ids, + const std::vector<std::string>& measurement_names, + int64_t start_time, int64_t end_time, ResultSet*& result_set); + + // 按行查询，支持 offset / limit + int queryByRow(const std::vector<std::string>& device_ids, + const std::vector<std::string>& measurement_names, + int offset, int limit, ResultSet*& result_set); + + void destroy_query_data_set(ResultSet* result_set); + std::vector<MeasurementSchema> get_device_schema(const std::string& device_id); + std::vector<std::string> get_all_device_ids(); + std::vector<std::shared_ptr<IDeviceID>> get_all_devices(); + DeviceTimeseriesMetadataMap get_timeseries_metadata( + const std::vector<std::shared_ptr<IDeviceID>>& device_ids); + DeviceTimeseriesMetadataMap get_timeseries_metadata(); +}; + +class TsFileTreeWriter { + public: + explicit TsFileTreeWriter(WriteFile* writer_file, + uint64_t memory_threshold = 128 * 1024 * 1024); + explicit TsFileTreeWriter(RestorableTsFileIOWriter* restorable_writer, + uint64_t memory_threshold = 128 * 1024 * 1024); + + int register_timeseries(std::string& device_id, MeasurementSchema* schema); + int register_timeseries(std::string& device_id, + std::vector<MeasurementSchema*> schemas); + int write(const Tablet& tablet); + int write(const TsRecord& record); + int flush(); + int close(); +}; + +} // namespace storage +``` + +该组接口与 `TsFileReader` / `TsFileTableWriter` 的表模型路径分离，便于在文档和业务代码中明确区分两种建模方式。 + ### ResultSet ```cpp /**
diff --git a/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-Java.md b/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-Java.md index fa3cad5..7e4bc0e 100644 --- a/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-Java.md +++ b/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-Java.md
@@ -20,6 +20,8 @@ --> # 接口定义 - Java +本页主要描述 **表模型** Java API。树模型原生读写可参考 C++ `TsFileTreeReader` / `TsFileTreeWriter` 头文件与对应快速上手文档。 + ## 写入接口 ### ITsFileWriter
diff --git a/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md b/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md index 08a4b2f..608548c 100644 --- a/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md +++ b/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md
@@ -46,6 +46,8 @@ """ TAG = 0 FIELD = 1 + ATTRIBUTE = 2 + TIME = 3 class ColumnSchema: """定义表中某一列的模式（名称、数据类型、类别）。""" @@ -164,6 +166,17 @@ start_time : int = np.iinfo(np.int64).min, end_time: int = np.iinfo(np.int64).max) -> ResultSet + def query_table_by_row(self, table_name: str, column_names: List[str], + offset: int = 0, limit: int = -1, + tag_filter = None, batch_size: int = 0) -> ResultSet + + def query_table_on_tree(self, column_names: List[str], + start_time: int = np.iinfo(np.int64).min, + end_time: int = np.iinfo(np.int64).max) -> ResultSet + + def query_tree_by_row(self, device_ids: List[str], measurement_names: List[str], + offset: int = 0, limit: int = -1) -> ResultSet + """ 获取指定表的模式信息。
diff --git a/src/zh/UserGuide/latest/QuickStart/QuickStart-C.md b/src/zh/UserGuide/latest/QuickStart/QuickStart-C.md index 3f8c944..c862491 100644 --- a/src/zh/UserGuide/latest/QuickStart/QuickStart-C.md +++ b/src/zh/UserGuide/latest/QuickStart/QuickStart-C.md
@@ -91,6 +91,7 @@ ### 构造 TsFileWriter ```C +#include <string.h> ERRNO code = 0; char* table_name = "table1"; @@ -135,8 +136,10 @@ for (int row = 0; row < 5; row++) { Timestamp timestamp = row; tablet_add_timestamp(tablet, row, timestamp); - tablet_add_value_by_name_string(tablet, row, "id1", "id_field_1"); - tablet_add_value_by_name_string(tablet, row, "id2", "id_field_2"); + tablet_add_value_by_name_string_with_len( + tablet, row, "id1", "id_field_1", (int)strlen("id_field_1")); + tablet_add_value_by_name_string_with_len( + tablet, row, "id2", "id_field_2", (int)strlen("id_field_2")); tablet_add_value_by_name_int32_t(tablet, row, "s1", row); } @@ -263,4 +266,4 @@ The sample code of using these interfaces is in <https://github.com/apache/tsfile/blob/develop/cpp/examples/c_examples/demo_read.c> -> 注意：以上读写示例均基于表模型接口，接口定义介绍可见[C 接口定义](./InterfaceDefinition/InterfaceDefinition-C.md)。若需了解树模型相关内容，请联系我们。 +> 注意：以上读写示例均基于**表模型**接口。树模型查询（如 `tsfile_query_table_on_tree`、`tsfile_reader_query_tree_by_row`）以及设备元数据相关接口请参考[C 接口定义](./InterfaceDefinition/InterfaceDefinition-C.md)。
diff --git a/src/zh/UserGuide/latest/QuickStart/QuickStart-CPP.md b/src/zh/UserGuide/latest/QuickStart/QuickStart-CPP.md index 6ff8228..c1a5754 100644 --- a/src/zh/UserGuide/latest/QuickStart/QuickStart-CPP.md +++ b/src/zh/UserGuide/latest/QuickStart/QuickStart-CPP.md
@@ -139,14 +139,17 @@ ### 关闭文件 ```cpp - writer->close() + writer->close(); ``` ### 示例代码 使用这些接口的示例代码可以在以下链接中找到 <https://github.com/apache/tsfile/blob/develop/cpp/examples/cpp_examples/demo_write.cpp> -## 查询流程 +## 查询流程（表模型） + +树模型 C++ 建议使用 `storage::TsFileTreeReader` / `storage::TsFileTreeWriter`（见 `tsfile_tree_reader.h` / `tsfile_tree_writer.h` 及接口定义）。 + ### 构造 TsFileReader @@ -244,4 +247,4 @@ 使用这些接口的示例代码可以在以下链接中找到 <https://github.com/apache/tsfile/blob/develop/cpp/examples/cpp_examples/demo_read.cpp> -> 注意：以上读写示例均基于表模型接口，接口定义介绍可见[C++ 接口定义](./InterfaceDefinition/InterfaceDefinition-CPP.md)。若需了解树模型相关内容，请联系我们。 +> 注意：以上示例使用 **TsFileTableWriter + TsFileReader** 的表模型路径。树模型请使用 **TsFileTreeWriter + TsFileTreeReader**，详见 [C++ 接口定义](./InterfaceDefinition/InterfaceDefinition-CPP.md)。
diff --git a/src/zh/UserGuide/latest/QuickStart/QuickStart-PYTHON.md b/src/zh/UserGuide/latest/QuickStart/QuickStart-PYTHON.md index 430a324..91756e1 100644 --- a/src/zh/UserGuide/latest/QuickStart/QuickStart-PYTHON.md +++ b/src/zh/UserGuide/latest/QuickStart/QuickStart-PYTHON.md
@@ -130,7 +130,9 @@ writer.write_table(tablet) ``` -## 读取示例 +## 读取示例（表模型） + +`TsFileReader` 同时支持树模型接口：`query_table_on_tree`、`query_tree_by_row`、`query_timeseries`（详见接口定义）。 ```Python import os @@ -163,5 +165,5 @@ 使用这些接口的示例代码可以在以下链接中找到：https://github.com/apache/tsfile/blob/develop/python/examples/example.py -> 注意：以上读写示例均基于表模型接口，接口定义介绍可见[Python 接口定义](./InterfaceDefinition/InterfaceDefinition-Python.md)。若需了解树模型相关内容，请联系我们。 +> 注意：以上示例基于表模型。树模型接口请参考 [Python 接口定义](./InterfaceDefinition/InterfaceDefinition-Python.md)。
diff --git a/src/zh/UserGuide/latest/QuickStart/QuickStart.md b/src/zh/UserGuide/latest/QuickStart/QuickStart.md index 3361051..427296d 100644 --- a/src/zh/UserGuide/latest/QuickStart/QuickStart.md +++ b/src/zh/UserGuide/latest/QuickStart/QuickStart.md
@@ -20,6 +20,8 @@ --> # 快速上手 - Java +以下示例使用 **表模型** Java API（`ITsFileWriter`、`TableSchema`、`Tablet`）。树模型读写请参考 C++ 的 `TsFileTreeReader` / `TsFileTreeWriter` 及其他语言接口。 + ## 依赖 - JDK >=1.8