Refine interface docs for public APIs
diff --git a/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md b/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md index 7ee9e74..e3fdf0b 100644 --- a/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md +++ b/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md
@@ -46,14 +46,9 @@ 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_SPRINTZ = 12, TS_ENCODING_INVALID = 255 } TSEncoding; @@ -64,9 +59,6 @@ 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; @@ -96,19 +88,6 @@ int column_num; } TableSchema; -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; - // ResultSetMetaData: Contains metadata for a result set, // such as column names and their data types. typedef struct result_set_meta_data { @@ -120,13 +99,6 @@ typedef struct arrow_schema ArrowSchema; typedef struct arrow_array ArrowArray; -typedef struct DeviceID { - char* path; - char* table_name; - uint32_t segment_count; - char** segments; -} DeviceID; - typedef struct TsFileStatisticBase { bool has_statistic; TSDataType type; @@ -154,35 +126,18 @@ } TimeseriesStatistic; #define tsfile_statistic_base(s) ((TsFileStatisticBase*)&(s)->u) - -typedef struct TimeseriesMetadata { - char* measurement_name; - TSDataType data_type; - int32_t chunk_meta_count; - TimeseriesStatistic statistic; - TimeseriesStatistic timeline_statistic; -} TimeseriesMetadata; - -typedef struct DeviceTimeseriesMetadataEntry { - DeviceID device; - TimeseriesMetadata* timeseries; - uint32_t timeseries_count; -} DeviceTimeseriesMetadataEntry; - -typedef struct DeviceTimeseriesMetadataMap { - DeviceTimeseriesMetadataEntry* entries; - uint32_t device_count; -} DeviceTimeseriesMetadataMap; ``` > `ColumnSchema` does not carry encoding/compression: on write, columns follow the > global defaults (see [Configuration](#configuration-encoding--compression)); on > read, each column is decoded with the file's actual settings. +> The encoding and compression constants listed above are the values accepted by +> the current writer/configuration path. > > `TimeseriesStatistic` is a tagged union in `tsfile_cwrapper.h`. Read common -> fields through `tsfile_statistic_base(&metadata.statistic)` and then use the -> active typed member (`int_s`, `float_s`, `bool_s`, `string_s`, or `text_s`) -> according to the statistic data type. +> fields through `tsfile_statistic_base(&statistic)` and then use the active +> typed member (`int_s`, `float_s`, `bool_s`, `string_s`, or `text_s`) according +> to the statistic data type. ## Write Interface @@ -811,57 +766,8 @@ uint32_t* size); /** - * @brief Gets all timeseries schema in the tsfile. - * @param size[out] number of DeviceSchema elements in the returned array. - * @return DeviceSchema*, an array of device schemas. - * @note The caller must call free_device_schema() on each element - * and free() the array pointer. - */ -DeviceSchema* tsfile_reader_get_all_timeseries_schemas(TsFileReader reader, - uint32_t* size); - -/** * @brief Free the tableschema's space. * @param schema [in] the table schema to be freed. */ void free_table_schema(TableSchema schema); - -void free_device_schema(DeviceSchema schema); ``` - -### Get Devices and Timeseries Metadata - -```C -/** - * @brief Lists all devices in the file. - * - * @param out_devices[out] allocated array; free with tsfile_free_device_id_array(). - * @param out_length[out] number of devices in the returned array. - */ -ERRNO tsfile_reader_get_all_devices(TsFileReader reader, DeviceID** out_devices, - uint32_t* out_length); - -void tsfile_free_device_id_array(DeviceID* devices, uint32_t length); -void tsfile_device_id_free_contents(DeviceID* d); - -/** - * @brief Timeseries metadata for all devices in the file. - */ -ERRNO tsfile_reader_get_timeseries_metadata_all( - TsFileReader reader, DeviceTimeseriesMetadataMap* out_map); - -/** - * @brief Timeseries metadata for the specified devices. - * - * length == 0 returns an empty map. For non-empty input, each DeviceID.path - * should contain the canonical device path. - */ -ERRNO tsfile_reader_get_timeseries_metadata_for_devices( - TsFileReader reader, const DeviceID* devices, uint32_t length, - DeviceTimeseriesMetadataMap* out_map); - -void tsfile_free_device_timeseries_metadata_map( - DeviceTimeseriesMetadataMap* map); -``` - -
diff --git a/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md b/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md index b95ccbc..559cb2b 100644 --- a/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md +++ b/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md
@@ -148,65 +148,6 @@ }; ``` -### TsFileWriter - -`TsFileWriter` is the lower-level writer interface from `tsfile_writer.h`. It -supports both tree-model and table-model writes. - -```cpp -extern int libtsfile_init(); -extern void libtsfile_destroy(); - -// Writer configuration. Invalid values return common::E_INVALID_ARG and leave -// the previous value unchanged. -extern int set_page_max_point_count(uint32_t page_max_point_count); -extern int set_max_degree_of_index_node(uint32_t max_degree_of_index_node); - -class TsFileWriter { - public: - TsFileWriter(); - ~TsFileWriter(); - void destroy(); - - int open(const std::string& file_path, int flags, mode_t mode); - int open(const std::string& file_path); - int init(storage::WriteFile* write_file); - int init(storage::RestorableTsFileIOWriter* rw); - - void set_generate_table_schema(bool generate_table_schema); - - int register_timeseries(const std::string& device_id, - const MeasurementSchema& measurement_schema); - int register_timeseries( - const std::string& device_path, - const std::vector<MeasurementSchema*>& measurement_schema_vec); - int register_aligned_timeseries( - const std::string& device_id, - const MeasurementSchema& measurement_schema); - int register_aligned_timeseries( - const std::string& device_id, - const std::vector<MeasurementSchema*>& measurement_schemas); - int register_table(const std::shared_ptr<TableSchema>& table_schema); - - int write_record(const TsRecord& record); - int write_tablet(const Tablet& tablet); - int write_record_aligned(const TsRecord& record); - int write_tablet_aligned(const Tablet& tablet); - int write_tree(const Tablet& tablet); - int write_tree(const TsRecord& record); - int write_table(Tablet& tablet); - - DeviceSchemasMap* get_schema_group_map(); - std::shared_ptr<TableSchema> get_table_schema( - const std::string& table_name) const; - int64_t calculate_mem_size_for_all_group(); - int64_t calculate_meta_mem_size() const; - int check_memory_size_and_may_flush_chunks(); - int flush(); - int close(); -}; -``` - ### TableSchema Describe the data structure of the table schema
diff --git a/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md b/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md index d0c0391..f44bbc3 100644 --- a/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md +++ b/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md
@@ -181,6 +181,14 @@ def write_dataframe(self, dataframe: pandas.DataFrame) """ + Write a pyarrow RecordBatch or Table into the table. The data must include a + time column and columns matching the table schema. + :param data: pyarrow.RecordBatch or pyarrow.Table. + :return: no return value. + """ + def write_arrow_batch(self, data) + + """ Flush buffered data to disk. :return: no return value. """ @@ -199,50 +207,6 @@ def __exit__(self, exc_type, exc_val, exc_tb) ``` -### TsFileWriter - -`TsFileWriter` is the lower-level writer exposed from `writer.pyx`. It can write -tree-model data (`register_timeseries`, `register_device`, `write_tablet`, -`write_row_record`) and table-model data (`register_table`, `write_table`, -`write_dataframe`, `write_arrow_batch`). - -```python -class TsFileWriter: - """ - :param pathname: Destination TsFile path. - :param memory_threshold: bytes buffered before an automatic flush (default 128MB). - """ - def __init__(self, pathname: str, memory_threshold: int = 128 * 1024 * 1024) - - def register_timeseries(self, device_name: str, - timeseries_schema: TimeseriesSchema) - - def register_device(self, device_schema: DeviceSchema) - - def register_table(self, table_schema: TableSchema) - - def write_tablet(self, tablet: Tablet) - - def write_dataframe(self, target_table: str, dataframe: pandas.DataFrame, - tableschema: TableSchema) - - def write_row_record(self, record: RowRecord) - - def write_table(self, tablet: Tablet) - - def write_arrow_batch(self, table_name: str, data, - time_col_index: int = -1) - - def flush(self) - - def close(self) - - def __enter__(self) - def __exit__(self, exc_type, exc_val, exc_tb) -``` - - - ### Tablet definition ```Python
diff --git a/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md b/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md index 7ee9e74..e3fdf0b 100644 --- a/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md +++ b/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md
@@ -46,14 +46,9 @@ 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_SPRINTZ = 12, TS_ENCODING_INVALID = 255 } TSEncoding; @@ -64,9 +59,6 @@ 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; @@ -96,19 +88,6 @@ int column_num; } TableSchema; -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; - // ResultSetMetaData: Contains metadata for a result set, // such as column names and their data types. typedef struct result_set_meta_data { @@ -120,13 +99,6 @@ typedef struct arrow_schema ArrowSchema; typedef struct arrow_array ArrowArray; -typedef struct DeviceID { - char* path; - char* table_name; - uint32_t segment_count; - char** segments; -} DeviceID; - typedef struct TsFileStatisticBase { bool has_statistic; TSDataType type; @@ -154,35 +126,18 @@ } TimeseriesStatistic; #define tsfile_statistic_base(s) ((TsFileStatisticBase*)&(s)->u) - -typedef struct TimeseriesMetadata { - char* measurement_name; - TSDataType data_type; - int32_t chunk_meta_count; - TimeseriesStatistic statistic; - TimeseriesStatistic timeline_statistic; -} TimeseriesMetadata; - -typedef struct DeviceTimeseriesMetadataEntry { - DeviceID device; - TimeseriesMetadata* timeseries; - uint32_t timeseries_count; -} DeviceTimeseriesMetadataEntry; - -typedef struct DeviceTimeseriesMetadataMap { - DeviceTimeseriesMetadataEntry* entries; - uint32_t device_count; -} DeviceTimeseriesMetadataMap; ``` > `ColumnSchema` does not carry encoding/compression: on write, columns follow the > global defaults (see [Configuration](#configuration-encoding--compression)); on > read, each column is decoded with the file's actual settings. +> The encoding and compression constants listed above are the values accepted by +> the current writer/configuration path. > > `TimeseriesStatistic` is a tagged union in `tsfile_cwrapper.h`. Read common -> fields through `tsfile_statistic_base(&metadata.statistic)` and then use the -> active typed member (`int_s`, `float_s`, `bool_s`, `string_s`, or `text_s`) -> according to the statistic data type. +> fields through `tsfile_statistic_base(&statistic)` and then use the active +> typed member (`int_s`, `float_s`, `bool_s`, `string_s`, or `text_s`) according +> to the statistic data type. ## Write Interface @@ -811,57 +766,8 @@ uint32_t* size); /** - * @brief Gets all timeseries schema in the tsfile. - * @param size[out] number of DeviceSchema elements in the returned array. - * @return DeviceSchema*, an array of device schemas. - * @note The caller must call free_device_schema() on each element - * and free() the array pointer. - */ -DeviceSchema* tsfile_reader_get_all_timeseries_schemas(TsFileReader reader, - uint32_t* size); - -/** * @brief Free the tableschema's space. * @param schema [in] the table schema to be freed. */ void free_table_schema(TableSchema schema); - -void free_device_schema(DeviceSchema schema); ``` - -### Get Devices and Timeseries Metadata - -```C -/** - * @brief Lists all devices in the file. - * - * @param out_devices[out] allocated array; free with tsfile_free_device_id_array(). - * @param out_length[out] number of devices in the returned array. - */ -ERRNO tsfile_reader_get_all_devices(TsFileReader reader, DeviceID** out_devices, - uint32_t* out_length); - -void tsfile_free_device_id_array(DeviceID* devices, uint32_t length); -void tsfile_device_id_free_contents(DeviceID* d); - -/** - * @brief Timeseries metadata for all devices in the file. - */ -ERRNO tsfile_reader_get_timeseries_metadata_all( - TsFileReader reader, DeviceTimeseriesMetadataMap* out_map); - -/** - * @brief Timeseries metadata for the specified devices. - * - * length == 0 returns an empty map. For non-empty input, each DeviceID.path - * should contain the canonical device path. - */ -ERRNO tsfile_reader_get_timeseries_metadata_for_devices( - TsFileReader reader, const DeviceID* devices, uint32_t length, - DeviceTimeseriesMetadataMap* out_map); - -void tsfile_free_device_timeseries_metadata_map( - DeviceTimeseriesMetadataMap* map); -``` - -
diff --git a/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md b/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md index b95ccbc..559cb2b 100644 --- a/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md +++ b/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md
@@ -148,65 +148,6 @@ }; ``` -### TsFileWriter - -`TsFileWriter` is the lower-level writer interface from `tsfile_writer.h`. It -supports both tree-model and table-model writes. - -```cpp -extern int libtsfile_init(); -extern void libtsfile_destroy(); - -// Writer configuration. Invalid values return common::E_INVALID_ARG and leave -// the previous value unchanged. -extern int set_page_max_point_count(uint32_t page_max_point_count); -extern int set_max_degree_of_index_node(uint32_t max_degree_of_index_node); - -class TsFileWriter { - public: - TsFileWriter(); - ~TsFileWriter(); - void destroy(); - - int open(const std::string& file_path, int flags, mode_t mode); - int open(const std::string& file_path); - int init(storage::WriteFile* write_file); - int init(storage::RestorableTsFileIOWriter* rw); - - void set_generate_table_schema(bool generate_table_schema); - - int register_timeseries(const std::string& device_id, - const MeasurementSchema& measurement_schema); - int register_timeseries( - const std::string& device_path, - const std::vector<MeasurementSchema*>& measurement_schema_vec); - int register_aligned_timeseries( - const std::string& device_id, - const MeasurementSchema& measurement_schema); - int register_aligned_timeseries( - const std::string& device_id, - const std::vector<MeasurementSchema*>& measurement_schemas); - int register_table(const std::shared_ptr<TableSchema>& table_schema); - - int write_record(const TsRecord& record); - int write_tablet(const Tablet& tablet); - int write_record_aligned(const TsRecord& record); - int write_tablet_aligned(const Tablet& tablet); - int write_tree(const Tablet& tablet); - int write_tree(const TsRecord& record); - int write_table(Tablet& tablet); - - DeviceSchemasMap* get_schema_group_map(); - std::shared_ptr<TableSchema> get_table_schema( - const std::string& table_name) const; - int64_t calculate_mem_size_for_all_group(); - int64_t calculate_meta_mem_size() const; - int check_memory_size_and_may_flush_chunks(); - int flush(); - int close(); -}; -``` - ### TableSchema Describe the data structure of the table schema
diff --git a/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md b/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md index d0c0391..f44bbc3 100644 --- a/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md +++ b/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md
@@ -181,6 +181,14 @@ def write_dataframe(self, dataframe: pandas.DataFrame) """ + Write a pyarrow RecordBatch or Table into the table. The data must include a + time column and columns matching the table schema. + :param data: pyarrow.RecordBatch or pyarrow.Table. + :return: no return value. + """ + def write_arrow_batch(self, data) + + """ Flush buffered data to disk. :return: no return value. """ @@ -199,50 +207,6 @@ def __exit__(self, exc_type, exc_val, exc_tb) ``` -### TsFileWriter - -`TsFileWriter` is the lower-level writer exposed from `writer.pyx`. It can write -tree-model data (`register_timeseries`, `register_device`, `write_tablet`, -`write_row_record`) and table-model data (`register_table`, `write_table`, -`write_dataframe`, `write_arrow_batch`). - -```python -class TsFileWriter: - """ - :param pathname: Destination TsFile path. - :param memory_threshold: bytes buffered before an automatic flush (default 128MB). - """ - def __init__(self, pathname: str, memory_threshold: int = 128 * 1024 * 1024) - - def register_timeseries(self, device_name: str, - timeseries_schema: TimeseriesSchema) - - def register_device(self, device_schema: DeviceSchema) - - def register_table(self, table_schema: TableSchema) - - def write_tablet(self, tablet: Tablet) - - def write_dataframe(self, target_table: str, dataframe: pandas.DataFrame, - tableschema: TableSchema) - - def write_row_record(self, record: RowRecord) - - def write_table(self, tablet: Tablet) - - def write_arrow_batch(self, table_name: str, data, - time_col_index: int = -1) - - def flush(self) - - def close(self) - - def __enter__(self) - def __exit__(self, exc_type, exc_val, exc_tb) -``` - - - ### Tablet definition ```Python
diff --git a/src/zh/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md b/src/zh/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md index 52eae53..9d3b5ea 100644 --- a/src/zh/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md +++ b/src/zh/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md
@@ -46,14 +46,9 @@ 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_SPRINTZ = 12, TS_ENCODING_INVALID = 255 } TSEncoding; @@ -64,9 +59,6 @@ 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; @@ -93,19 +85,6 @@ int column_num; } TableSchema; -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; - // ResultSetMetaData：结果集的元数据，包括列名和数据类型。 typedef struct result_set_meta_data { char** column_names; @@ -116,13 +95,6 @@ typedef struct arrow_schema ArrowSchema; typedef struct arrow_array ArrowArray; -typedef struct DeviceID { - char* path; - char* table_name; - uint32_t segment_count; - char** segments; -} DeviceID; - typedef struct TsFileStatisticBase { bool has_statistic; TSDataType type; @@ -150,31 +122,13 @@ } TimeseriesStatistic; #define tsfile_statistic_base(s) ((TsFileStatisticBase*)&(s)->u) - -typedef struct TimeseriesMetadata { - char* measurement_name; - TSDataType data_type; - int32_t chunk_meta_count; - TimeseriesStatistic statistic; - TimeseriesStatistic timeline_statistic; -} TimeseriesMetadata; - -typedef struct DeviceTimeseriesMetadataEntry { - DeviceID device; - TimeseriesMetadata* timeseries; - uint32_t timeseries_count; -} DeviceTimeseriesMetadataEntry; - -typedef struct DeviceTimeseriesMetadataMap { - DeviceTimeseriesMetadataEntry* entries; - uint32_t device_count; -} DeviceTimeseriesMetadataMap; ``` > `ColumnSchema` 不携带编码/压缩：写入时列遵循全局默认值（见[配置](#配置编码与压缩)），读取时按文件中的实际配置解码。 +> 上面列出的编码和压缩常量是当前 writer/configuration 路径实际接受的值。 > > `TimeseriesStatistic` 是 `tsfile_cwrapper.h` 中的带标签 union。可通过 -> `tsfile_statistic_base(&metadata.statistic)` 读取通用字段，再根据数据类型读取 +> `tsfile_statistic_base(&statistic)` 读取通用字段，再根据数据类型读取 > `int_s`、`float_s`、`bool_s`、`string_s` 或 `text_s`。 ## 写入接口 @@ -784,57 +738,10 @@ uint32_t* size); /** - * @brief 获取 TsFile 中所有 timeseries schema。 - * - * @param size [输出] 返回的 DeviceSchema 数组中的元素数量。 - * @return DeviceSchema* 设备 schema 数组指针。 - * @note 调用者必须对数组中的每个元素调用 free_device_schema()， - * 并对整个数组指针调用 free() 进行释放。 - */ -DeviceSchema* tsfile_reader_get_all_timeseries_schemas(TsFileReader reader, - uint32_t* size); - -/** * @brief 释放 TableSchema 占用的内存空间。 * * @param schema [输入] 需要释放的表模式结构。 */ void free_table_schema(TableSchema schema); - -void free_device_schema(DeviceSchema schema); -``` - -### 获取设备与 Timeseries Metadata - -```C -/** - * @brief 列出文件中的所有设备。 - * - * @param out_devices [输出] 分配出的设备数组；用 tsfile_free_device_id_array() 释放。 - * @param out_length [输出] 返回数组中的设备数量。 - */ -ERRNO tsfile_reader_get_all_devices(TsFileReader reader, DeviceID** out_devices, - uint32_t* out_length); - -void tsfile_free_device_id_array(DeviceID* devices, uint32_t length); -void tsfile_device_id_free_contents(DeviceID* d); - -/** - * @brief 获取文件中所有设备的 timeseries metadata。 - */ -ERRNO tsfile_reader_get_timeseries_metadata_all( - TsFileReader reader, DeviceTimeseriesMetadataMap* out_map); - -/** - * @brief 获取指定设备的 timeseries metadata。 - * - * length == 0 返回空 map。非空输入中每个 DeviceID.path 应包含规范设备路径。 - */ -ERRNO tsfile_reader_get_timeseries_metadata_for_devices( - TsFileReader reader, const DeviceID* devices, uint32_t length, - DeviceTimeseriesMetadataMap* out_map); - -void tsfile_free_device_timeseries_metadata_map( - DeviceTimeseriesMetadataMap* map); ```
diff --git a/src/zh/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md b/src/zh/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md index 43d5cfc..5e18d2d 100644 --- a/src/zh/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md +++ b/src/zh/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md
@@ -149,64 +149,6 @@ }; ``` -### TsFileWriter - -`TsFileWriter` 是 `tsfile_writer.h` 中的低层写入接口，支持 tree 模型和 table -模型写入。 - -```cpp -extern int libtsfile_init(); -extern void libtsfile_destroy(); - -// 写入器配置。非法值返回 common::E_INVALID_ARG，并保持原配置不变。 -extern int set_page_max_point_count(uint32_t page_max_point_count); -extern int set_max_degree_of_index_node(uint32_t max_degree_of_index_node); - -class TsFileWriter { - public: - TsFileWriter(); - ~TsFileWriter(); - void destroy(); - - int open(const std::string& file_path, int flags, mode_t mode); - int open(const std::string& file_path); - int init(storage::WriteFile* write_file); - int init(storage::RestorableTsFileIOWriter* rw); - - void set_generate_table_schema(bool generate_table_schema); - - int register_timeseries(const std::string& device_id, - const MeasurementSchema& measurement_schema); - int register_timeseries( - const std::string& device_path, - const std::vector<MeasurementSchema*>& measurement_schema_vec); - int register_aligned_timeseries( - const std::string& device_id, - const MeasurementSchema& measurement_schema); - int register_aligned_timeseries( - const std::string& device_id, - const std::vector<MeasurementSchema*>& measurement_schemas); - int register_table(const std::shared_ptr<TableSchema>& table_schema); - - int write_record(const TsRecord& record); - int write_tablet(const Tablet& tablet); - int write_record_aligned(const TsRecord& record); - int write_tablet_aligned(const Tablet& tablet); - int write_tree(const Tablet& tablet); - int write_tree(const TsRecord& record); - int write_table(Tablet& tablet); - - DeviceSchemasMap* get_schema_group_map(); - std::shared_ptr<TableSchema> get_table_schema( - const std::string& table_name) const; - int64_t calculate_mem_size_for_all_group(); - int64_t calculate_meta_mem_size() const; - int check_memory_size_and_may_flush_chunks(); - int flush(); - int close(); -}; -``` - ### TableSchema 描述表模式（schema）的数据结构。
diff --git a/src/zh/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md b/src/zh/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md index a2d6c14..6eb0d9f 100644 --- a/src/zh/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md +++ b/src/zh/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md
@@ -175,6 +175,14 @@ def write_dataframe(self, dataframe: pandas.DataFrame) """ + 将 pyarrow RecordBatch 或 Table 写入表中。数据必须包含时间列，并且列需要与表 + schema 匹配。 + :param data: pyarrow.RecordBatch 或 pyarrow.Table。 + :return: 无返回值。 + """ + def write_arrow_batch(self, data) + + """ 将缓冲数据刷新到磁盘。 :return: 无返回值。 """ @@ -194,49 +202,6 @@ ``` -### TsFileWriter - -`TsFileWriter` 是 `writer.pyx` 暴露的低层写入接口。它可以写入 tree 模型数据 -（`register_timeseries`、`register_device`、`write_tablet`、`write_row_record`）， -也可以写入 table 模型数据（`register_table`、`write_table`、`write_dataframe`、 -`write_arrow_batch`）。 - -```python -class TsFileWriter: - """ - :param pathname: 目标 TsFile 路径。 - :param memory_threshold: 触发自动刷盘前缓冲的字节数（默认 128MB）。 - """ - def __init__(self, pathname: str, memory_threshold: int = 128 * 1024 * 1024) - - def register_timeseries(self, device_name: str, - timeseries_schema: TimeseriesSchema) - - def register_device(self, device_schema: DeviceSchema) - - def register_table(self, table_schema: TableSchema) - - def write_tablet(self, tablet: Tablet) - - def write_dataframe(self, target_table: str, dataframe: pandas.DataFrame, - tableschema: TableSchema) - - def write_row_record(self, record: RowRecord) - - def write_table(self, tablet: Tablet) - - def write_arrow_batch(self, table_name: str, data, - time_col_index: int = -1) - - def flush(self) - - def close(self) - - def __enter__(self) - def __exit__(self, exc_type, exc_val, exc_tb) -``` - - ### Tablet definition
diff --git a/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md b/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md index 52eae53..9d3b5ea 100644 --- a/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md +++ b/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md
@@ -46,14 +46,9 @@ 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_SPRINTZ = 12, TS_ENCODING_INVALID = 255 } TSEncoding; @@ -64,9 +59,6 @@ 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; @@ -93,19 +85,6 @@ int column_num; } TableSchema; -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; - // ResultSetMetaData：结果集的元数据，包括列名和数据类型。 typedef struct result_set_meta_data { char** column_names; @@ -116,13 +95,6 @@ typedef struct arrow_schema ArrowSchema; typedef struct arrow_array ArrowArray; -typedef struct DeviceID { - char* path; - char* table_name; - uint32_t segment_count; - char** segments; -} DeviceID; - typedef struct TsFileStatisticBase { bool has_statistic; TSDataType type; @@ -150,31 +122,13 @@ } TimeseriesStatistic; #define tsfile_statistic_base(s) ((TsFileStatisticBase*)&(s)->u) - -typedef struct TimeseriesMetadata { - char* measurement_name; - TSDataType data_type; - int32_t chunk_meta_count; - TimeseriesStatistic statistic; - TimeseriesStatistic timeline_statistic; -} TimeseriesMetadata; - -typedef struct DeviceTimeseriesMetadataEntry { - DeviceID device; - TimeseriesMetadata* timeseries; - uint32_t timeseries_count; -} DeviceTimeseriesMetadataEntry; - -typedef struct DeviceTimeseriesMetadataMap { - DeviceTimeseriesMetadataEntry* entries; - uint32_t device_count; -} DeviceTimeseriesMetadataMap; ``` > `ColumnSchema` 不携带编码/压缩：写入时列遵循全局默认值（见[配置](#配置编码与压缩)），读取时按文件中的实际配置解码。 +> 上面列出的编码和压缩常量是当前 writer/configuration 路径实际接受的值。 > > `TimeseriesStatistic` 是 `tsfile_cwrapper.h` 中的带标签 union。可通过 -> `tsfile_statistic_base(&metadata.statistic)` 读取通用字段，再根据数据类型读取 +> `tsfile_statistic_base(&statistic)` 读取通用字段，再根据数据类型读取 > `int_s`、`float_s`、`bool_s`、`string_s` 或 `text_s`。 ## 写入接口 @@ -784,57 +738,10 @@ uint32_t* size); /** - * @brief 获取 TsFile 中所有 timeseries schema。 - * - * @param size [输出] 返回的 DeviceSchema 数组中的元素数量。 - * @return DeviceSchema* 设备 schema 数组指针。 - * @note 调用者必须对数组中的每个元素调用 free_device_schema()， - * 并对整个数组指针调用 free() 进行释放。 - */ -DeviceSchema* tsfile_reader_get_all_timeseries_schemas(TsFileReader reader, - uint32_t* size); - -/** * @brief 释放 TableSchema 占用的内存空间。 * * @param schema [输入] 需要释放的表模式结构。 */ void free_table_schema(TableSchema schema); - -void free_device_schema(DeviceSchema schema); -``` - -### 获取设备与 Timeseries Metadata - -```C -/** - * @brief 列出文件中的所有设备。 - * - * @param out_devices [输出] 分配出的设备数组；用 tsfile_free_device_id_array() 释放。 - * @param out_length [输出] 返回数组中的设备数量。 - */ -ERRNO tsfile_reader_get_all_devices(TsFileReader reader, DeviceID** out_devices, - uint32_t* out_length); - -void tsfile_free_device_id_array(DeviceID* devices, uint32_t length); -void tsfile_device_id_free_contents(DeviceID* d); - -/** - * @brief 获取文件中所有设备的 timeseries metadata。 - */ -ERRNO tsfile_reader_get_timeseries_metadata_all( - TsFileReader reader, DeviceTimeseriesMetadataMap* out_map); - -/** - * @brief 获取指定设备的 timeseries metadata。 - * - * length == 0 返回空 map。非空输入中每个 DeviceID.path 应包含规范设备路径。 - */ -ERRNO tsfile_reader_get_timeseries_metadata_for_devices( - TsFileReader reader, const DeviceID* devices, uint32_t length, - DeviceTimeseriesMetadataMap* out_map); - -void tsfile_free_device_timeseries_metadata_map( - DeviceTimeseriesMetadataMap* map); ```
diff --git a/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md b/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md index 43d5cfc..5e18d2d 100644 --- a/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md +++ b/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md
@@ -149,64 +149,6 @@ }; ``` -### TsFileWriter - -`TsFileWriter` 是 `tsfile_writer.h` 中的低层写入接口，支持 tree 模型和 table -模型写入。 - -```cpp -extern int libtsfile_init(); -extern void libtsfile_destroy(); - -// 写入器配置。非法值返回 common::E_INVALID_ARG，并保持原配置不变。 -extern int set_page_max_point_count(uint32_t page_max_point_count); -extern int set_max_degree_of_index_node(uint32_t max_degree_of_index_node); - -class TsFileWriter { - public: - TsFileWriter(); - ~TsFileWriter(); - void destroy(); - - int open(const std::string& file_path, int flags, mode_t mode); - int open(const std::string& file_path); - int init(storage::WriteFile* write_file); - int init(storage::RestorableTsFileIOWriter* rw); - - void set_generate_table_schema(bool generate_table_schema); - - int register_timeseries(const std::string& device_id, - const MeasurementSchema& measurement_schema); - int register_timeseries( - const std::string& device_path, - const std::vector<MeasurementSchema*>& measurement_schema_vec); - int register_aligned_timeseries( - const std::string& device_id, - const MeasurementSchema& measurement_schema); - int register_aligned_timeseries( - const std::string& device_id, - const std::vector<MeasurementSchema*>& measurement_schemas); - int register_table(const std::shared_ptr<TableSchema>& table_schema); - - int write_record(const TsRecord& record); - int write_tablet(const Tablet& tablet); - int write_record_aligned(const TsRecord& record); - int write_tablet_aligned(const Tablet& tablet); - int write_tree(const Tablet& tablet); - int write_tree(const TsRecord& record); - int write_table(Tablet& tablet); - - DeviceSchemasMap* get_schema_group_map(); - std::shared_ptr<TableSchema> get_table_schema( - const std::string& table_name) const; - int64_t calculate_mem_size_for_all_group(); - int64_t calculate_meta_mem_size() const; - int check_memory_size_and_may_flush_chunks(); - int flush(); - int close(); -}; -``` - ### TableSchema 描述表模式（schema）的数据结构。
diff --git a/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md b/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md index a2d6c14..6eb0d9f 100644 --- a/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md +++ b/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md
@@ -175,6 +175,14 @@ def write_dataframe(self, dataframe: pandas.DataFrame) """ + 将 pyarrow RecordBatch 或 Table 写入表中。数据必须包含时间列，并且列需要与表 + schema 匹配。 + :param data: pyarrow.RecordBatch 或 pyarrow.Table。 + :return: 无返回值。 + """ + def write_arrow_batch(self, data) + + """ 将缓冲数据刷新到磁盘。 :return: 无返回值。 """ @@ -194,49 +202,6 @@ ``` -### TsFileWriter - -`TsFileWriter` 是 `writer.pyx` 暴露的低层写入接口。它可以写入 tree 模型数据 -（`register_timeseries`、`register_device`、`write_tablet`、`write_row_record`）， -也可以写入 table 模型数据（`register_table`、`write_table`、`write_dataframe`、 -`write_arrow_batch`）。 - -```python -class TsFileWriter: - """ - :param pathname: 目标 TsFile 路径。 - :param memory_threshold: 触发自动刷盘前缓冲的字节数（默认 128MB）。 - """ - def __init__(self, pathname: str, memory_threshold: int = 128 * 1024 * 1024) - - def register_timeseries(self, device_name: str, - timeseries_schema: TimeseriesSchema) - - def register_device(self, device_schema: DeviceSchema) - - def register_table(self, table_schema: TableSchema) - - def write_tablet(self, tablet: Tablet) - - def write_dataframe(self, target_table: str, dataframe: pandas.DataFrame, - tableschema: TableSchema) - - def write_row_record(self, record: RowRecord) - - def write_table(self, tablet: Tablet) - - def write_arrow_batch(self, table_name: str, data, - time_col_index: int = -1) - - def flush(self) - - def close(self) - - def __enter__(self) - def __exit__(self, exc_type, exc_val, exc_tb) -``` - - ### Tablet definition