This is an automated email from the ASF dual-hosted git repository.
jiangtian pushed a commit to branch docs/dev
in repository https://gitbox.apache.org/repos/asf/tsfile.git
The following commit(s) were added to refs/heads/docs/dev by this push:
new eece1156 Update Tsfile multilingual version (#552)
eece1156 is described below
commit eece1156c5cc51ac1253249e733a086e873f4e03
Author: W1y1r <[email protected]>
AuthorDate: Tue Jul 22 09:42:23 2025 +0800
Update Tsfile multilingual version (#552)
---
src/.vuepress/sidebar/v2.x/en.ts | 16 +-
src/.vuepress/sidebar/v2.x/zh.ts | 16 +-
.../InterfaceDefinition/InterfaceDefinition-C.md | 473 +++++++++++++++++++++
.../InterfaceDefinition/InterfaceDefinition-CPP.md | 443 +++++++++++++++++++
.../InterfaceDefinition-Java.md} | 6 +-
.../InterfaceDefinition-Python.md | 282 ++++++++++++
src/UserGuide/latest/QuickStart/QuickStart-C.md | 243 +++++++++++
src/UserGuide/latest/QuickStart/QuickStart-CPP.md | 224 ++++++++++
.../{QuickStart.md => QuickStart-JAVA.md} | 11 +-
.../latest/QuickStart/QuickStart-PYTHON.md | 123 ++++++
.../InterfaceDefinition/InterfaceDefinition-C.md | 459 ++++++++++++++++++++
.../InterfaceDefinition/InterfaceDefinition-CPP.md | 446 +++++++++++++++++++
.../InterfaceDefinition-Java.md} | 113 +++--
.../InterfaceDefinition-Python.md | 264 ++++++++++++
src/zh/UserGuide/latest/QuickStart/QuickStart-C.md | 245 +++++++++++
.../UserGuide/latest/QuickStart/QuickStart-CPP.md | 223 ++++++++++
.../{QuickStart.md => QuickStart-JAVA.md} | 11 +-
.../latest/QuickStart/QuickStart-PYTHON.md | 131 ++++++
18 files changed, 3666 insertions(+), 63 deletions(-)
diff --git a/src/.vuepress/sidebar/v2.x/en.ts b/src/.vuepress/sidebar/v2.x/en.ts
index d8956f27..7fb59a6f 100644
--- a/src/.vuepress/sidebar/v2.x/en.ts
+++ b/src/.vuepress/sidebar/v2.x/en.ts
@@ -36,7 +36,13 @@ export const enSidebar = {
{
text: 'Quick Start',
collapsible: true,
- link: 'QuickStart/QuickStart',
+ prefix: 'QuickStart/',
+ children: [
+ { text: 'QuickStart-C', link: 'QuickStart-C' },
+ { text: 'QuickStart-CPP', link: 'QuickStart-CPP' },
+ { text: 'QuickStart-JAVA', link: 'QuickStart-JAVA' },
+ { text: 'QuickStart-PYTHON', link: 'QuickStart-PYTHON' },
+ ],
// prefix: 'QuickStart/',
// // children: 'structure',
// children: [
@@ -46,7 +52,13 @@ export const enSidebar = {
{
text: 'Interface Definitions',
collapsible: true,
- link: 'QuickStart/Interface-Definitions',
+ prefix: 'QuickStart/InterfaceDefinition',
+ children: [
+ { text: 'InterfaceDefinition-C', link: 'InterfaceDefinition-C' },
+ { text: 'InterfaceDefinition-CPP', link: 'InterfaceDefinition-CPP' },
+ { text: 'InterfaceDefinition-Java', link: 'InterfaceDefinition-Java' },
+ { text: 'InterfaceDefinition-Python', link:
'InterfaceDefinition-Python' },
+ ],
},
{
text: 'Ecosystem Integration',
diff --git a/src/.vuepress/sidebar/v2.x/zh.ts b/src/.vuepress/sidebar/v2.x/zh.ts
index c4d95cd7..95bca71a 100644
--- a/src/.vuepress/sidebar/v2.x/zh.ts
+++ b/src/.vuepress/sidebar/v2.x/zh.ts
@@ -36,7 +36,13 @@ export const zhSidebar = {
{
text: '快速上手',
collapsible: true,
- link: 'QuickStart/QuickStart',
+ prefix: 'QuickStart/',
+ children: [
+ { text: 'QuickStart-C', link: 'QuickStart-C' },
+ { text: 'QuickStart-CPP', link: 'QuickStart-CPP' },
+ { text: 'QuickStart-JAVA', link: 'QuickStart-JAVA' },
+ { text: 'QuickStart-PYTHON', link: 'QuickStart-PYTHON' },
+ ],
// prefix: 'QuickStart/',
// children: 'structure',
// children: [
@@ -46,7 +52,13 @@ export const zhSidebar = {
{
text: '接口定义',
collapsible: true,
- link: 'QuickStart/Interface-Definitions',
+ prefix: 'QuickStart/InterfaceDefinition',
+ children: [
+ { text: 'InterfaceDefinition-C', link: 'InterfaceDefinition-C' },
+ { text: 'InterfaceDefinition-CPP', link: 'InterfaceDefinition-CPP' },
+ { text: 'InterfaceDefinition-Java', link: 'InterfaceDefinition-Java' },
+ { text: 'InterfaceDefinition-Python', link:
'InterfaceDefinition-Python' },
+ ],
},
{
text: '生态集成',
diff --git
a/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md
b/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md
new file mode 100644
index 00000000..f5564398
--- /dev/null
+++
b/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md
@@ -0,0 +1,473 @@
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+# Interface definition - C
+
+
+
+## Schema
+
+```C
+typedef enum {
+ TS_DATATYPE_BOOLEAN = 0,
+ TS_DATATYPE_INT32 = 1,
+ TS_DATATYPE_INT64 = 2,
+ TS_DATATYPE_FLOAT = 3,
+ TS_DATATYPE_DOUBLE = 4,
+ TS_DATATYPE_TEXT = 5,
+ TS_DATATYPE_STRING = 11
+} TSDataType;
+
+typedef enum column_category { TAG = 0, FIELD = 1 } ColumnCategory;
+
+// ColumnSchema: Represents the schema of a single column,
+// including its name, data type, and category.
+typedef struct column_schema {
+ char* column_name;
+ TSDataType data_type;
+ ColumnCategory column_category;
+} ColumnSchema;
+
+// TableSchema: Defines the schema of a table,
+// including its name and a list of column schemas.
+typedef struct table_schema {
+ char* table_name;
+ ColumnSchema* column_schemas;
+ int column_num;
+} TableSchema;
+
+// ResultSetMetaData: Contains metadata for a result set,
+// such as column names and their data types.
+typedef struct result_set_meta_data {
+ char** column_names;
+ TSDataType* data_types;
+ int column_num;
+} ResultSetMetaData;
+```
+
+
+## Write Interface
+
+### TsFile WriteFile Create/Close
+
+```C
+/**
+ * @brief Creates a file for writing.
+ *
+ * @param pathname Target file 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.
+ */
+
+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.
+ *
+ * @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.
+ *
+ * @return TsFileWriter Valid handle on success, NULL on failure.
+ *
+ * @note Call tsfile_writer_close() to release resources.
+ */
+TsFileWriter tsfile_writer_new(WriteFile file, TableSchema* schema,
+ ERRNO* err_code);
+
+/**
+ * @brief Creates a TsFileWriter for writing a TsFile.
+ *
+ * @param file Target file where the table data will be written.
+ * @param schema Table schema definition.
+ * - Ownership: Should be 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.
+ */
+TsFileWriter tsfile_writer_new_with_memory_threshold(WriteFile file,
+ TableSchema* schema,
+ uint64_t memory_threshold,
+ ERRNO* err_code);
+
+/**
+ * @brief Releases resources associated with a TsFileWriter.
+ *
+ * @param writer [in] Writer handle obtained from tsfile_writer_new().
+ * After call: handle becomes invalid and must not be
reused.
+ * @return ERRNO - RET_OK(0) on success, or error code in errno_define_c.h.
+ */
+ERRNO tsfile_writer_close(TsFileWriter writer);
+```
+
+
+
+### Tablet Create/Close/Insert data
+
+You can use Tablet to insert data into TsFile in batches, and you need to
release the space occupied by the Tablet after use.
+
+```C
+/**
+ * @brief Creates a Tablet for batch data.
+ *
+ * @param column_name_list [in] Column names array. Size=column_num.
+ * @param data_types [in] Data types array. Size=column_num.
+ * @param column_num [in] Number of columns. Must be ≥1.
+ * @param max_rows [in] Pre-allocated row capacity. Must be ≥1.
+ * @return Tablet Valid handle.
+ * @note Call free_tablet() to release resources.
+ */
+Tablet tablet_new(char** column_name_list, TSDataType* data_types,
+ uint32_t column_num, uint32_t max_rows);
+/**
+ * @brief Gets current row count in the Tablet.
+ *
+ * @param tablet [in] Valid Tablet handle.
+ * @return uint32_t Row count (0 to max_rows-1).
+ */
+uint32_t tablet_get_cur_row_size(Tablet tablet);
+
+/**
+ * @brief Assigns timestamp to a row in the Tablet.
+ *
+ * @param tablet [in] Valid Tablet handle.
+ * @param row_index [in] Target row (0 ≤ index < max_rows).
+ * @param timestamp [in] Timestamp with int64_t type.
+ * @return ERRNO - RET_OK(0) or error code in errno_define_c.h.
+ */
+ERRNO tablet_add_timestamp(Tablet tablet, uint32_t row_index,
+ Timestamp timestamp);
+
+/**
+ * @brief Adds a string value to a Tablet row by column name.
+ *
+ * @param value [in] Null-terminated string. Ownership remains with caller.
+ * @return ERRNO.
+ */
+ERRNO tablet_add_value_by_name_string(Tablet tablet, uint32_t row_index,
+ const char* column_name,
+ const char* value);
+
+ // 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);
+
+
+/**
+ * @brief Adds a string value to a Tablet row by column index.
+ *
+ * @param value [in] Null-terminated string. Copied internally.
+ */
+ERRNO tablet_add_value_by_index_string(Tablet tablet, uint32_t row_index,
+ uint32_t column_index,
+ const char* value);
+
+
+// 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);
+
+
+void free_tablet(Tablet* tablet);
+```
+
+
+
+### Write Tablet into TsFile
+
+```C
+/**
+ * @brief Writes data from a Tablet to the TsFile.
+ *
+ * @param writer [in] Valid TsFileWriter handle.
+ * @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.
+ *
+ */
+
+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);
+
+/**
+ * @brief Releases resources associated with a TsFileReader.
+ *
+ * @param reader [in] Reader handle obtained from tsfile_reader_new().
+ * After call:
+ * Handle becomes invalid and must not be reused.
+ * Result_set obtained by this handle becomes invalid.
+ * @return ERRNO - RET_OK(0) on success, or error code in errno_define_c.h.
+ */
+ERRNO tsfile_reader_close(TsFileReader reader);
+```
+
+
+
+### Query table/get next
+
+```C
+
+/**
+ * @brief Query data from the specific table and columns within time range.
+ *
+ * @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().
+ */
+ResultSet tsfile_query_table(TsFileReader reader, const char* table_name,
+ char** columns, uint32_t column_num,
+ Timestamp start_time, Timestamp end_time,
+ ERRNO* err_code);
+
+/**
+ * @brief Check and fetch the next row in the ResultSet.
+ *
+ * @param result_set [in] Valid ResultSet handle.
+ * @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.
+ */
+bool tsfile_result_set_next(ResultSet result_set, ERRNO* error_code);
+
+/**
+ * @brief Free Result set
+ *
+ * @param result_set [in] Valid ResultSet handle ptr.
+ */
+void free_tsfile_result_set(ResultSet* result_set);
+```
+
+
+
+### Get Data from result set
+
+```c
+/**
+ * @brief Checks if the current row's column value is NULL by column name.
+ *
+ * @param result_set [in] Valid ResultSet with active row (after next()=true).
+ * @param column_name [in] Existing column name in result schema.
+ * @return bool - true: Value is NULL or column not found, false: Valid value.
+ */
+bool tsfile_result_set_is_null_by_name(ResultSet result_set,
+ const char* column_name);
+
+/**
+ * @brief Checks if the current row's column value is NULL by column index.
+ *
+ * @param column_index [in] Column position (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
+
+```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.
+ */
+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.
+ */
+TableSchema* tsfile_reader_get_all_table_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);
+```
+
+
+
+
+
+
+
+
diff --git
a/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md
b/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md
new file mode 100644
index 00000000..b165a024
--- /dev/null
+++
b/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md
@@ -0,0 +1,443 @@
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+# Interface Definitions - Cpp
+
+## Write Interface
+
+### TsFileTableWriter
+
+Used to write data to tsfile
+
+```cpp
+/**
+ * @brief Facilitates writing structured table data into a TsFile with a
specified schema.
+ *
+ * The TsFileTableWriter class is designed to write structured data,
particularly suitable for time-series data,
+ * into a file optimized for efficient storage and retrieval (referred to as
TsFile here). It allows users to define
+ * the schema of the tables they want to write, add rows of data according to
that schema, and serialize this data
+ * into a TsFile. Additionally, it provides options to limit memory usage
during the writing process.
+ */
+class TsFileTableWriter {
+ public:
+ /**
+ * TsFileTableWriter is used to write table data into a target file with
the given schema,
+ * optionally limiting the memory usage.
+ *
+ * @param writer_file Target file where the table data will be written.
Must not be null.
+ * @param table_schema Used to construct table structures. Defines the
schema of the table
+ * being written.
+ * @param memory_threshold Optional parameter. When the size of written
+ * data exceeds this value, the data will be automatically flushed to the
+ * disk. Default value is 128MB.
+ */
+ TsFileTableWriter(WriteFile* writer_file,
+ TableSchema* table_schema,
+ uint64_t memory_threshold = 128 * 1024 * 1024);
+ ~TsFileTableWriter();
+ /**
+ * Writes the given tablet data into the target file according to the
schema.
+ *
+ * @param tablet The tablet containing the data to be written. Must not be
null.
+ * @return Returns 0 on success, or a non-zero error code on failure.
+ */
+ int write_table(const Tablet& tablet);
+ /**
+ * Flushes any buffered data to the underlying storage medium, ensuring
all data is written out.
+ * This method ensures that all pending writes are persisted.
+ *
+ * @return Returns 0 on success, or a non-zero error code on failure.
+ */
+ int flush();
+ /**
+ * Closes the writer and releases any resources held by it.
+ * After calling this method, no further operations should be performed on
this instance.
+ *
+ * @return Returns 0 on success, or a non-zero error code on failure.
+ */
+ int close();
+};
+```
+
+### TableSchema
+
+Describe the data structure of the table schema
+
+```cpp
+/**
+* @brief Represents the schema information for an entire table.
+*
+* This class holds the metadata necessary to describe how a specific table is
structured,
+* including its name and the schemas of all its columns.
+*/
+class TableSchema {
+ public:
+ /**
+ * Constructs a TableSchema object with the given table name, column
schemas, and column categories.
+ *
+ * @param table_name The name of the table. Must be a non-empty string.
+ * This name is used to identify the table within the
system.
+ * @param column_schemas A vector containing ColumnSchema objects.
+ * Each ColumnSchema defines the schema for one
column in the table.
+ */
+ TableSchema(const std::string& table_name,
+ const std::vector<ColumnSchema>& column_schemas);
+};
+
+
+/**
+* @brief Represents the schema information for a single column.
+*
+* This structure holds the metadata necessary to describe how a specific
column is stored,
+* including its name, data type, category.
+*/
+struct ColumnSchema {
+ std::string column_name_;
+ common::TSDataType data_type_;
+ ColumnCategory column_category_;
+
+ /**
+ * @brief Constructs a ColumnSchema object with the given parameters.
+ *
+ * @param column_name The name of the column. Must be a non-empty string.
+ * This name is used to identify the column within the
table.
+ * @param data_type The data type of the measurement, such as INT32,
DOUBLE, TEXT, etc.
+ * This determines how the data will be stored and
interpreted.
+ * @param column_category The category of the column indicating its role
or type
+ * within the schema, e.g., FIELD, TAG.
+ * Defaults to ColumnCategory::FIELD if not
specified.
+ * @note It is the responsibility of the caller to ensure that
`column_name` is not empty.
+ */
+ ColumnSchema(std::string column_name, common::TSDataType data_type,
+ ColumnCategory column_category = ColumnCategory::FIELD) :
column_name_(std::move(column_name)),
+
data_type_(data_type),
+
column_category_(column_category) {
+ }
+};
+
+/**
+ * @brief Represents the data type of a measurement.
+ *
+ * This enumeration defines the supported data types for measurements in the
system.
+ */
+enum TSDataType : uint8_t {
+ BOOLEAN = 0,
+ INT32 = 1,
+ INT64 = 2,
+ FLOAT = 3,
+ DOUBLE = 4,
+ TEXT = 5,
+ STRING = 11
+};
+
+```
+
+### Tablet
+
+Write column memory structure
+
+```cpp
+/**
+ * @brief Represents a collection of data rows with associated metadata for
insertion into a table.
+ *
+ * This class is used to manage and organize data that will be inserted into a
specific target table.
+ * It handles the storage of timestamps and values, along with their
associated metadata such as column names and types.
+ */
+class Tablet {
+public:
+ /**
+ * @brief Constructs a Tablet object with the given parameters.
+ *
+ * @param column_names A vector containing the names of the columns in the
tablet.
+ * Each name corresponds to a column in the target
table.
+ * @param data_types A vector containing the data types of each column.
+ * These must match the schema of the target table.
+ * @param max_rows The maximum number of rows that this tablet can hold.
Defaults to DEFAULT_MAX_ROWS.
+ */
+ Tablet(const std::vector<std::string> &column_names,
+ const std::vector<common::TSDataType> &data_types,
+ int max_rows = DEFAULT_MAX_ROWS);
+
+ /**
+ * @brief Adds a timestamp to the specified row.
+ *
+ * @param row_index The index of the row to which the timestamp will be
added.
+ * Must be less than the maximum number of rows.
+ * @param timestamp The timestamp value to add.
+ * @return Returns 0 on success, or a non-zero error code on failure.
+ */
+ int add_timestamp(uint32_t row_index, int64_t timestamp);
+
+ /**
+ * @brief Template function to add a value of type T to the specified row
and column.
+ *
+ * @tparam T The type of the value to add.
+ * @param row_index The index of the row to which the value will be added.
+ * Must be less than the maximum number of rows.
+ * @param schema_index The index of the column schema corresponding to the
value being added.
+ * @param val The value to add.
+ * @return Returns 0 on success, or a non-zero error code on failure.
+ */
+ template <typename T>
+ int add_value(uint32_t row_index, uint32_t schema_index, T val);
+
+ /**
+ * @brief Template function to add a value of type T to the specified row
and column by name.
+ *
+ * @tparam T The type of the value to add.
+ * @param row_index The index of the row to which the value will be added.
+ * Must be less than the maximum number of rows.
+ * @param measurement_name The name of the column to which the value will
be added.
+ * Must match one of the column names provided
during construction.
+ * @param val The value to add.
+ * @return Returns 0 on success, or a non-zero error code on failure.
+ */
+ template <typename T>
+ int add_value(uint32_t row_index, const std::string &measurement_name, T
val);
+};
+```
+
+## Read Interface
+### Tsfile Reader
+use to execute query in tsfile and return value by ResultSet.
+```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.
+ */
+class TsFileReader {
+ public:
+ TsFileReader();
+ ~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 destroy the result set, this method should be called after the
+ * query is finished and result_set
+ *
+ * @param qds the result set
+ */
+ void destroy_query_data_set(ResultSet *qds);
+ ResultSet *read_timeseries(
+ const std::shared_ptr<IDeviceID> &device_id,
+ const std::vector<std::string> &measurement_name);
+ /**
+ * @brief get all devices in the tsfile
+ *
+ * @param table_name the table name
+ * @return std::vector<std::shared_ptr<IDeviceID>> the device id list
+ */
+ std::vector<std::shared_ptr<IDeviceID>> get_all_devices(
+ std::string table_name);
+ /**
+ * @brief get the timeseries schema by the device id and measurement name
+ *
+ * @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.
+ */
+ int get_timeseries_schema(std::shared_ptr<IDeviceID> device_id,
+ std::vector<MeasurementSchema> &result);
+ /**
+ * @brief get the table schema by the table name
+ *
+ * @param table_name the table name
+ * @return std::shared_ptr<TableSchema> the table schema
+ */
+ std::shared_ptr<TableSchema> get_table_schema(
+ const std::string &table_name);
+ /**
+ * @brief get all table schemas in the tsfile
+ *
+ * @return std::vector<std::shared_ptr<TableSchema>> the table schema list
+ */
+ std::vector<std::shared_ptr<TableSchema>> get_all_table_schemas();
+};
+```
+### ResultSet
+A collection of query.Support iterator to get data, and directly through the
column name or index to get specific data.
+```cpp
+/**
+ * @brief ResultSet is the query result of the TsfileReader. It provides access
+ * to the results.
+ *
+ * ResultSet is a virtual class. Convert it to the corresponding implementation
+ * class when used
+ * @note When using the tree model and the filter is a global time filter,
+ * it should be cast as QDSWithoutTimeGenerator.
+ * @note When using the tree model and the filter is not a global time filter,
+ * it should be QDSWithTimeGenerator.
+ * @note If the query uses the table model, the cast should be TableResultSet
+ */
+class ResultSet {
+ public:
+ ResultSet() {}
+ virtual ~ResultSet() {}
+ /**
+ * @brief Get the next row of the result set
+ *
+ * @param[out] has_next a boolean value indicating if there is a next row
+ * @return Returns 0 on success, or a non-zero error code on failure.
+ */
+ virtual int next(bool& has_next) = 0;
+ /**
+ * @brief Check if the value of the column is null by column name
+ *
+ * @param column_name the name of the column
+ * @return true if the value is null, false otherwise
+ */
+ virtual bool is_null(const std::string& column_name) = 0;
+ /**
+ * @brief Check if the value of the column is null by column index
+ *
+ * @param column_index the index of the column starting from 1
+ * @return true if the value is null, false otherwise
+ */
+ virtual bool is_null(uint32_t column_index) = 0;
+
+ /**
+ * @brief Get the value of the column by column name
+ *
+ * @param column_name the name of the column
+ * @return the value of the column
+ */
+ 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
+ * @return the value of the column
+ */
+ template <typename T>
+ T get_value(uint32_t column_index);
+ /**
+ * @brief Get the row record of the result set
+ *
+ * @return the row record
+ */
+ virtual RowRecord* get_row_record() = 0;
+ /**
+ * @brief Get the metadata of the result set
+ *
+ * @return std::shared_ptr<ResultSetMetadata> the metadata of the result
set
+ */
+ virtual std::shared_ptr<ResultSetMetadata> get_metadata() = 0;
+ /**
+ * @brief Close the result set
+ *
+ * @note this method should be called after the result set is no longer
+ * needed.
+ */
+ virtual void close() = 0;
+};
+```
+### ResultMeta
+user can obtain the metadata from ResultSetMetadata, including all columnnames
and data types. When a user uses a table model, the first columndefaults to the
time column.
+```cpp
+/**
+ * @brief metadata of result set
+ *
+ * user can obtain the metadata from ResultSetMetadata, including all column
+ * names and data types. When a user uses the table model, the first column
+ * defaults to the time column.
+ */
+class ResultSetMetadata {
+ public:
+ /**
+ * @brief constructor of ResultSetMetadata
+ *
+ * @param column_names the column names
+ * @param column_types the column types
+ */
+ ResultSetMetadata(const std::vector<std::string>& column_names,
+ const std::vector<common::TSDataType>& column_types);
+ /**
+ * @brief get the column type
+ *
+ * @param column_index the column index starting from 1
+ * @return the column type
+ */
+ common::TSDataType get_column_type(uint32_t column_index);
+ /**
+ * @brief get the column name
+ *
+ * @param column_index the column index starting from 1
+ * @return the column name
+ */
+ std::string get_column_name(uint32_t column_index);
+ /**
+ * @brief get the column count
+ *
+ * @return the column count by uint32_t
+ */
+ uint32_t get_column_count();
+};
+```
\ No newline at end of file
diff --git a/src/UserGuide/latest/QuickStart/Interface-Definitions.md
b/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-Java.md
similarity index 98%
rename from src/UserGuide/latest/QuickStart/Interface-Definitions.md
rename to
src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-Java.md
index 8c08262c..3ae53d09 100644
--- a/src/UserGuide/latest/QuickStart/Interface-Definitions.md
+++
b/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-Java.md
@@ -18,7 +18,7 @@
under the License.
-->
-# Interface Definitions
+# Interface Definitions - Java
## Write Interface
@@ -174,7 +174,7 @@ interface ITsFileReader extends AutoCloseable {
### TsFileReaderBuilder
-Used to construct ITsFileWriter
+Used to construct ITsFileReader
```Java
class TsFileReaderBuilder {
@@ -217,7 +217,7 @@ interface ResultSet extends AutoCloseable {
boolean isNull(String columnName);
boolean isNull(int columnIndex);
- // Close the current structure set
+ // Close the current result set
void close();
// Obtain the header of the result set
diff --git
a/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md
b/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md
new file mode 100644
index 00000000..ad6d4619
--- /dev/null
+++
b/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md
@@ -0,0 +1,282 @@
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+# Interface Definitions - Python
+
+## Schema
+
+```Python
+
+class TSDataType(IntEnum):
+ """
+ Enumeration of data types currently supported by TsFile.
+ """
+ BOOLEAN = 0
+ INT32 = 1
+ INT64 = 2
+ FLOAT = 3
+ DOUBLE = 4
+ TEXT = 5
+ STRING = 11
+
+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 = 0
+ FIELD = 1
+
+class ColumnSchema:
+ """Defines schema for a table column (name, datatype, category)."""
+
+ column_name = None
+ data_type = None
+ category = None
+
+ def __init__(self, column_name: str, data_type: TSDataType,
+ category: ColumnCategory = ColumnCategory.FIELD)
+
+class TableSchema:
+ """Schema definition for a table structure."""
+
+ table_name = None
+ columns = None
+
+ def __init__(self, table_name: str, columns: List[ColumnSchema])
+
+
+class ResultSetMetaData:
+ """Metadata container for query result sets (columns, types, table
name)."""
+
+ column_list = None
+ data_types = None
+ table_name = None
+
+ def __init__(self, column_list: List[str], data_types: List[TSDataType])
+
+```
+
+
+
+## Write interface
+
+### TsFileWriter
+
+```python
+class TsFileTableWriter:
+ """
+ Facilitates writing structured table data into a TsFile with a specified
schema.
+ """
+
+
+ """
+ :param path: The path of tsfile, will create if it doesn't exist.
+ :param table_schema: describes the schema of the tables want to write.
+ :return: no return value.
+ """
+ def __init__(self, path: str, table_schema: TableSchema)
+
+
+ """
+ Write a tablet into table in tsfile.
+ :param tablet: stored batch data of a table.
+ :return: no return value.
+ """
+ def write_table(self, tablet: Tablet)
+
+ """
+ Close TsFileTableWriter and flush data automatically.
+ :return: no return value.
+ """
+ def close(self)
+
+```
+
+
+
+### Tablet definition
+
+You can use Tablet to insert data into TsFile in batches.
+
+```Python
+class Tablet(object)
+ """
+ A pre-allocated columnar data container for batch data with type
constraints.
+ Creates timestamp buffer and typed data columns, with value range
validation ranges
+ for numeric types.
+
+ Initializes:
+ :param column_name_list: name list for data columns.
+ :param type_list: TSDataType values specifying allowed types per column.
+ :param max_row_num: Pre-allocated row capacity (default 1024)
+ :return: no return value.
+ """
+
+ def __init__(self, column_name_list: list[str], type_list:
list[TSDataType],
+ max_row_num: int = 1024)
+
+```
+
+## Read Interface
+
+### TsFileReader
+
+```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)
+
+
+ """
+ Executes a time range query on the specified table and columns.
+
+ :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.
+ """
+ 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
+
+ """
+ Retrieves the schema of the specified table.
+
+ :param table_name: The name of the table.
+ :return: The schema of the specified table.
+ """
+ def get_table_schema(self, table_name : str)-> TableSchema
+
+
+ """
+ Retrieves the schemas of all tables in the TsFile.
+
+ :return: A dictionary mapping table names to their schemas.
+ """
+ def get_all_table_schemas(self) ->dict[str, TableSchema]
+
+
+ """
+ Closes the TsFile reader. If the reader has active result sets, they will
be invalidated.
+ """
+ def close(self)
+
+```
+
+### ResultSet
+
+
+
+```python
+class ResultSet:
+ """
+ Retrieves data from a query result set. When a query is executed, a query
handler is returned.
+ If the reader is closed, the result set will become invalid.
+ """
+
+ """
+ Checks and moves to the next row in the query result set.
+
+ :return: True if the next row exists, False otherwise.
+ """
+ def next(self) -> bool
+
+
+ """
+ Retrieves the column information of the result set.
+
+ :return: A dictionary containing column names as keys and their data types
as values.
+ """
+ def get_result_column_info(self) -> dict[str, TsDataType]
+
+
+ """
+ Fetches the next DataFrame from the query result set.
+
+ :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_next_data_frame(self, max_row_num : int = 1024) -> DataFrame
+
+
+ """
+ Retrieves the value at the specified index from the query result set.
+
+ :param index: The index of the value to retrieve, 1 <= index <= column_num.
+ :return: The value at the specified index.
+ """
+ def get_value_by_index(self, index : int)
+
+
+ """
+ Retrieves the value for the specified column name from the query result
set.
+
+ :param column_name: The name of the column to retrieve the value from.
+ :return: The value of the specified column.
+ """
+ def get_value_by_name(self, column_name : str)
+
+
+
+ """
+ Retrieves the metadata of the result set.
+
+ :return: The metadata of the result set as a ResultSetMetadata object.
+ """
+ def get_metadata(self) -> ResultSetMetadata
+
+
+ """
+ Checks whether the field at the specified index in the result set is null.
+
+ :param index: The index of the field to check. 1 <= index <= column_num.
+ :return: True if the field is null, False otherwise.
+ """
+ def is_null_by_index(self, index : int)
+
+
+
+ """
+ Checks whether the field with the specified column name in the result set
is null.
+
+ :param name: The name of the column to check.
+ :return: True if the field is null, False otherwise.
+ """
+ def is_null_by_name(self, name : str)
+
+
+ """
+ Closes the result set and releases any associated resources.
+ """
+ def close(self)
+```
+
diff --git a/src/UserGuide/latest/QuickStart/QuickStart-C.md
b/src/UserGuide/latest/QuickStart/QuickStart-C.md
new file mode 100644
index 00000000..68a25802
--- /dev/null
+++ b/src/UserGuide/latest/QuickStart/QuickStart-C.md
@@ -0,0 +1,243 @@
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+# Quick Start - C
+
+## Dependencies
+
+- CMake >=3.11
+- Maven >=3.9.6
+- GCC >=4.8.5
+- Make >=4.3
+
+## Installation Method
+
+Clone the source code from git:
+
+```shell
+git clone https://github.com/apache/tsfile.git
+```
+Run Maven to compile in the TsFile root directory:
+
+```shell
+mvn clean install -P with-cpp -DskipTests
+```
+
+If Maven is not installed, you can compile tsfile using the following command:
+
+Linux or Macos:
+```shell
+mvnw clean install -P with-cpp -DskipTests
+```
+Windows:
+```shell
+mvnw.cmd clean install -P with-cpp -DskipTests
+```
+
+### Directory Structure
+
+• **Include Directory**: Located at
`tsfile/cpp/target/build/include/cwrapper`, it contains header files for
integration. Add this path to the compiler's include path (e.g., using `-I`
flag).
+
+• **Lib Directory**: At `tsfile/cpp/target/build/lib`, it holds compiled
library files. Specify this path and library name when linking (e.g., using
`-L` and `-l` flags).
+
+### CMake Integration
+Add to your CMakeLists.txt:
+```CMAKE
+find_library(TSFILE_LIB NAMES tsfile PATHS ${SDK_LIB} REQUIRED)
+target_link_libraries(your_target ${TSFILE_LIB})
+```
+Note: Set ${SDK_LIB} to your TsFile library directory.
+
+## Writing Process
+
+### Construct TsFileWriter
+
+```C
+ ERRNO code = 0;
+ char* table_name = "table1";
+
+ // Create table schema to describe a table in a tsfile.
+ TableSchema table_schema;
+ table_schema.table_name = strdup(table_name);
+ table_schema.column_num = 3;
+ table_schema.column_schemas =
+ (ColumnSchema*)malloc(sizeof(ColumnSchema) * 3);
+ table_schema.column_schemas[0] =
+ (ColumnSchema){.column_name = strdup("id1"),
+ .data_type = TS_DATATYPE_STRING,
+ .column_category = TAG};
+ table_schema.column_schemas[1] =
+ (ColumnSchema){.column_name = strdup("id2"),
+ .data_type = TS_DATATYPE_STRING,
+ .column_category = TAG};
+ table_schema.column_schemas[2] =
+ (ColumnSchema){.column_name = strdup("s1"),
+ .data_type = TS_DATATYPE_INT32,
+ .column_category = FIELD};
+
+ // Create a file with specify path to write tsfile.
+ WriteFile file = write_file_new("test_c.tsfile", &code);
+ HANDLE_ERROR(code);
+
+ // Create tsfile writer with specify table schema.
+ TsFileWriter writer = tsfile_writer_new(file, &table_schema, &code);
+ HANDLE_ERROR(code);
+```
+
+### Write Data
+
+```C
+ // Create tablet to insert data.
+ Tablet tablet =
+ tablet_new((char*[]){"id1", "id2", "s1"},
+ (TSDataType[]){TS_DATATYPE_STRING, TS_DATATYPE_STRING,
+ TS_DATATYPE_INT32},
+ 3, 5);
+
+ 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_int32_t(tablet, row, "s1", row);
+ }
+
+ // Write tablet data.
+ HANDLE_ERROR(tsfile_writer_write(writer, tablet));
+
+ // Free tablet.
+ free_tablet(&tablet);
+
+ // Free table schema we used before.
+ free_table_schema(table_schema);
+```
+### Close File
+
+```C
+ // Close writer.
+ HANDLE_ERROR(tsfile_writer_close(writer));
+
+ // Close write file after closing writer.
+ free_write_file(&file);
+```
+### Sample Code
+
+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
+
+### Construct TsFileReader
+
+```C
+ ERRNO code = 0;
+ char* table_name = "table1";
+
+ // Create tsfile reader with specify tsfile's path
+ TsFileReader reader = tsfile_reader_new("test_c.tsfile", &code);
+ HANDLE_ERROR(code);
+```
+
+### Construct Query
+```C
+ ResultSet ret = tsfile_query_table(
+ reader, table_name, (char*[]){"id1", "id2", "s1"}, 3, 0, 10, &code);
+ HANDLE_ERROR(code);
+
+ if (ret == NULL) {
+ HANDLE_ERROR(RET_INVALID_QUERY);
+ }
+```
+
+### Query Data
+
+```C
+ // Get query result metadata: column name and datatype
+ ResultSetMetaData metadata = tsfile_result_set_get_metadata(ret);
+ int column_num = tsfile_result_set_metadata_get_column_num(metadata);
+
+ for (int i = 1; i <= column_num; i++) {
+ printf("column:%s, datatype:%d\n",
tsfile_result_set_metadata_get_column_name(metadata, i),
+ tsfile_result_set_metadata_get_data_type(metadata, i));
+ }
+
+ // Get data by column name or index.
+ while (tsfile_result_set_next(ret, &code) && code == RET_OK) {
+ // Timestamp at column 1 and column index begin from 1.
+ Timestamp timestamp =
+ tsfile_result_set_get_value_by_index_int64_t(ret, 1);
+ printf("%ld\n", timestamp);
+ for (int i = 1; i <= column_num; i++) {
+ if (tsfile_result_set_is_null_by_index(ret, i)) {
+ printf(" null ");
+ } else {
+ switch (tsfile_result_set_metadata_get_data_type(metadata, i))
{
+ case TS_DATATYPE_BOOLEAN:
+ printf("%d\n",
tsfile_result_set_get_value_by_index_bool(
+ ret, i));
+ break;
+ case TS_DATATYPE_INT32:
+ printf("%d\n",
+
tsfile_result_set_get_value_by_index_int32_t(ret,
+
i));
+ break;
+ case TS_DATATYPE_INT64:
+ printf("%ld\n",
+
tsfile_result_set_get_value_by_index_int64_t(ret,
+
i));
+ break;
+ case TS_DATATYPE_FLOAT:
+ printf("%f\n",
tsfile_result_set_get_value_by_index_float(
+ ret, i));
+ break;
+ case TS_DATATYPE_DOUBLE:
+ printf("%lf\n",
+ tsfile_result_set_get_value_by_index_double(ret,
+ i));
+ break;
+ case TS_DATATYPE_STRING:
+ printf("%s\n",
+ tsfile_result_set_get_value_by_index_string(ret,
+ i));
+ break;
+ default:
+ printf("unknown_type");
+ break;
+ }
+ }
+ }
+ }
+
+ // Free query meta data
+ free_result_set_meta_data(metadata);
+
+ // Free query handler.
+ free_tsfile_result_set(&ret);
+```
+
+### Close File
+
+```C
+ // Close tsfile reader.
+ tsfile_reader_close(reader);
+```
+### Sample Code
+
+The sample code of using these interfaces is in
<https://github.com/apache/tsfile/blob/develop/cpp/examples/c_examples/demo_read.c>
+
diff --git a/src/UserGuide/latest/QuickStart/QuickStart-CPP.md
b/src/UserGuide/latest/QuickStart/QuickStart-CPP.md
new file mode 100644
index 00000000..0eb30716
--- /dev/null
+++ b/src/UserGuide/latest/QuickStart/QuickStart-CPP.md
@@ -0,0 +1,224 @@
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+# Quick Start - Cpp
+
+## Dependencies
+
+- CMake >=3.11
+- Maven >=3.9.6
+- GCC >=4.8.5
+- Make >=4.3
+
+## Installation Method
+
+Clone the source code from git:
+
+```shell
+git clone https://github.com/apache/tsfile.git
+```
+Run Maven to compile in the TsFile root directory:
+
+```shell
+mvn clean install -P with-cpp -DskipTests
+```
+
+Note: If Maven is not installed, you can use mvnw on Linux or mvnw.cmd on
Windows.
+
+### Directory Structure
+
+• **Include Directory**: Located at `tsfile/cpp/target/build/include`, it
contains header files for integration. Add this path to the compiler's include
path (e.g., using `-I` flag).
+
+• **Lib Directory**: At `tsfile/cpp/target/build/lib`, it holds compiled
library files. Specify this path and library name when linking (e.g., using
`-L` and `-l` flags).
+
+### CMake Integration
+Add to your CMakeLists.txt:
+```CMAKE
+find_library(TSFILE_LIB NAMES tsfile PATHS ${SDK_LIB} REQUIRED)
+target_link_libraries(your_target ${TSFILE_LIB})
+```
+Note: Set ${SDK_LIB} to your TSFile library directory.
+
+## Writing Process
+
+### Construct TsFileWriter
+
+```cpp
+ std::string file_name = "test.tsfile";
+ storage::libtsfile_init();
+
+ std::string table_name = "table1";
+
+ // Create a file with specify path to write tsfile.
+ storage::WriteFile file;
+ int flags = O_WRONLY | O_CREAT | O_TRUNC;
+#ifdef _WIN32
+ flags |= O_BINARY;
+#endif
+ mode_t mode = 0666;
+ file.create("test_cpp.tsfile", flags, mode);
+
+ // Create table schema to describe a table in a tsfile.
+ auto* schema = new storage::TableSchema(
+ table_name,
+ {
+ common::ColumnSchema("id1", common::STRING, common::UNCOMPRESSED,
+ common::PLAIN, common::ColumnCategory::TAG),
+ common::ColumnSchema("id2", common::STRING, common::UNCOMPRESSED,
+ common::PLAIN, common::ColumnCategory::TAG),
+ common::ColumnSchema("s1", common::INT64, common::UNCOMPRESSED,
+ common::PLAIN, common::ColumnCategory::FIELD),
+ });
+
+ // Create a file with specify path to write tsfile.
+ auto* writer = new storage::TsFileTableWriter(&file, schema);
+```
+
+### Write Data
+
+```cpp
+ // Create tablet to insert data.
+ storage::Tablet tablet(
+ table_name, {"id1", "id2", "s1"},
+ {common::STRING, common::STRING, common::INT64},
+ {common::ColumnCategory::TAG, common::ColumnCategory::TAG,
+ common::ColumnCategory::FIELD},
+ 10);
+
+
+ for (int row = 0; row < 5; row++) {
+ long timestamp = row;
+ tablet.add_timestamp(row, timestamp);
+ tablet.add_value(row, "id1", "id1_filed_1");
+ tablet.add_value(row, "id2", "id1_filed_2");
+ tablet.add_value(row, "s1", static_cast<int64_t>(row));
+ }
+
+ // Write tablet data.
+ writer->write_table(tablet);
+
+ // Flush data
+ writer->flush();
+```
+
+### Close File
+
+```cpp
+ 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
+
+### Construct TsFileReader
+
+```cpp
+ int code = 0;
+ storage::libtsfile_init();
+ std::string table_name = "table1";
+
+ // Create tsfile reader and open tsfile with specify path.
+ storage::TsFileReader reader;
+ reader.open("test_cpp.tsfile");
+```
+
+### Construct Query Request
+
+```cpp
+ // Query data with tsfile reader.
+ storage::ResultSet* temp_ret = nullptr;
+ std::vector<std::string> columns;
+ columns.emplace_back("id1");
+ columns.emplace_back("id2");
+ columns.emplace_back("s1");
+
+ // Column vector contains the columns you want to select.
+ reader.query(table_name, columns, 0, 100, temp_ret);
+```
+
+### Query Data
+
+```cpp
+ // Get query handler.
+ auto ret = dynamic_cast<storage::TableResultSet*>(temp_ret);
+
+ // Metadata in query handler.
+ auto metadata = ret->get_metadata();
+ int column_num = metadata->get_column_count();
+ for (int i = 1; i <= column_num; i++) {
+ std::cout << "column name: " << metadata->get_column_name(i)
+ << std::endl;
+ std::cout << "column type: "
+ << std::to_string(metadata->get_column_type(i)) << std::endl;
+ }
+
+ // Check and get next data.
+ bool has_next = false;
+ while ((code = ret->next(has_next)) == common::E_OK && has_next) {
+ // Timestamp at column 1 and column index begin from 1.
+ Timestamp timestamp = ret->get_value<Timestamp>(1);
+ for (int i = 1; i <= column_num; i++) {
+ if (ret->is_null(i)) {
+ std::cout << "null" << std::endl;
+ } else {
+ switch (metadata->get_column_type(i)) {
+ case common::BOOLEAN:
+ std::cout << ret->get_value<bool>(i) << std::endl;
+ break;
+ case common::INT32:
+ std::cout << ret->get_value<int32_t>(i) << std::endl;
+ break;
+ case common::INT64:
+ std::cout << ret->get_value<int64_t>(i) << std::endl;
+ break;
+ case common::FLOAT:
+ std::cout << ret->get_value<float>(i) << std::endl;
+ break;
+ case common::DOUBLE:
+ std::cout << ret->get_value<double>(i) << std::endl;
+ break;
+ case common::STRING:
+ std::cout << ret->get_value<common::String*>(i)
+ ->to_std_string()
+ << std::endl;
+ break;
+ default:;
+ }
+ }
+ }
+ }
+```
+
+### Close File
+
+```cpp
+ // Close query result set.
+ ret->close();
+ // Close reader.
+ reader.close();
+```
+
+### Sample Code
+
+The sample code of using these interfaces is in
<https://github.com/apache/tsfile/blob/develop/cpp/examples/cpp_examples/demo_read.cpp>
+
diff --git a/src/UserGuide/latest/QuickStart/QuickStart.md
b/src/UserGuide/latest/QuickStart/QuickStart-JAVA.md
similarity index 92%
rename from src/UserGuide/latest/QuickStart/QuickStart.md
rename to src/UserGuide/latest/QuickStart/QuickStart-JAVA.md
index 9dfb0998..5ac101ad 100644
--- a/src/UserGuide/latest/QuickStart/QuickStart.md
+++ b/src/UserGuide/latest/QuickStart/QuickStart-JAVA.md
@@ -18,7 +18,7 @@
under the License.
-->
-# Quick Start
+# Quick Start - Java
## Dependencies
@@ -78,9 +78,8 @@ TableSchema tableSchema =
.category(Tablet.ColumnCategory.FIELD)
.build(),
new ColumnSchemaBuilder()
- .name("s2")
- .dataType(TSDataType.BOOLEAN)
- .category(Tablet.ColumnCategory.FIELD)
+ .name("s2").
+ dataType(TSDataType.BOOLEAN)
.build()));
long memoryThreshold = 10 * 1024 * 1024;
@@ -122,7 +121,7 @@ writer.close();
### Sample Code
-The sample code of using these interfaces is in
<https://github.com/apache/tsfile/blob/rc/2.0.1/java/examples/src/main/java/org/apache/tsfile/v4/WriteTabletWithITsFileWriter.java>
+The sample code of using these interfaces is in
<https://github.com/apache/tsfile/blob/develop/java/examples/src/main/java/org/apache/tsfile/v4/WriteTabletWithITsFileWriter.java>
## Query Process
@@ -181,5 +180,5 @@ reader.close();
### Sample Code
-The sample code of using these interfaces is in
<https://github.com/apache/tsfile/blob/rc/2.0.1/java/examples/src/main/java/org/apache/tsfile/v4/ITsFileReaderAndITsFileWriter.java>
+The sample code of using these interfaces is in
<https://github.com/apache/tsfile/blob/develop/java/examples/src/main/java/org/apache/tsfile/v4/ITsFileReaderAndITsFileWriter.java>
diff --git a/src/UserGuide/latest/QuickStart/QuickStart-PYTHON.md
b/src/UserGuide/latest/QuickStart/QuickStart-PYTHON.md
new file mode 100644
index 00000000..2d855a9e
--- /dev/null
+++ b/src/UserGuide/latest/QuickStart/QuickStart-PYTHON.md
@@ -0,0 +1,123 @@
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+# Quick Start - Python
+
+## Dependencies
+
+If want to compile on your local envirment, the dependencies are below:
+
+- CMake >=3.11
+- Maven >=3.9.6
+- GCC >=4.8.5
+- Make >=4.3
+- cython >= 3.0.10
+- numpy >= 1.26.4
+- pandas >= 2.2.2
+- setuptools >= 70.0.0
+
+or use pip install, the dependencies are:
+
+numpy >= 1.26.4
+pandas >= 2.2.2
+
+## Installation Method
+
+### Compile on your local envirment
+Clone the source code from git:
+
+```shell
+git clone https://github.com/apache/tsfile.git
+```
+Run Maven to compile in the TsFile root directory:
+
+```shell
+mvn clean install -P with-python -DskipTests
+```
+
+If Maven is not installed, you can compile tsfile using the following command:
+
+Linux or Macos:
+```shell
+mvnw clean install -P with-python -DskipTests
+```
+Windows:
+```shell
+mvnw.cmd clean install -P with-python -DskipTests
+```
+
+### Directory Structure
+
+• **wheel**: Located at `tsfile/python/dist`, you can use pip to install this
wheel.
+
+### Install into your local envirment
+
+run `pip install` to install tsfile package you already compiled(Assuming the
compilation produces tsfile.wheel.).
+
+```bash
+pip install tsfile.wheel
+```
+
+
+
+## Writing Process
+
+```Python
+table_data_dir = os.path.join(os.path.dirname(__file__), "table_data.tsfile")
+if os.path.exists(table_data_dir):
+ os.remove(table_data_dir)
+
+column1 = ColumnSchema("id", TSDataType.STRING, ColumnCategory.TAG)
+column2 = ColumnSchema("id2", TSDataType.STRING, ColumnCategory.TAG)
+column3 = ColumnSchema("value", TSDataType.FLOAT, ColumnCategory.FIELD)
+table_schema = TableSchema("test_table", columns=[column1, column2, column3])
+
+
+### Free resource automatically
+with TsFileTableWriter(table_data_dir, table_schema) as writer:
+ tablet_row_num = 100
+ tablet = Tablet(
+ ["id", "id2", "value"],
+ [TSDataType.STRING, TSDataType.STRING, TSDataType.FLOAT],
+ tablet_row_num)
+
+ for i in range(tablet_row_num):
+ tablet.add_timestamp(i, i * 10)
+ tablet.add_value_by_name("id", i, "test1")
+ tablet.add_value_by_name("id2", i, "test" + str(i))
+ tablet.add_value_by_index(2, i, i * 100.2)
+
+ writer.write_table(tablet)
+```
+
+## Reading Process
+
+```Python
+table_data_dir = os.path.join(os.path.dirname(__file__), "table_data.tsfile")
+### Free resource automatically
+with TsFileReader(table_data_dir) as reader:
+ print(reader.get_all_table_schemas())
+ with reader.query_table("test_table", ["id2", "value"], 0, 50) as result:
+ print(result.get_metadata())
+ while result.next():
+ print(result.get_value_by_name("id2"))
+ print(result.get_value_by_name("value"))
+ print(result.read_data_frame())
+```
diff --git
a/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md
b/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md
new file mode 100644
index 00000000..45db6f3f
--- /dev/null
+++
b/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md
@@ -0,0 +1,459 @@
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+
+# 接口定义 - C
+
+
+## Schema（模式定义）
+
+```C++
+typedef enum {
+ TS_DATATYPE_BOOLEAN = 0,
+ TS_DATATYPE_INT32 = 1,
+ TS_DATATYPE_INT64 = 2,
+ TS_DATATYPE_FLOAT = 3,
+ TS_DATATYPE_DOUBLE = 4,
+ TS_DATATYPE_TEXT = 5,
+ TS_DATATYPE_STRING = 11
+} TSDataType;
+
+typedef enum column_category { TAG = 0, FIELD = 1 } ColumnCategory;
+
+// ColumnSchema：表示单个列的模式，包括列名、数据类型和分类。
+typedef struct column_schema {
+ char* column_name;
+ TSDataType data_type;
+ ColumnCategory column_category;
+} ColumnSchema;
+
+// TableSchema：定义一个表的模式，包括表名和列模式数组。
+typedef struct table_schema {
+ char* table_name;
+ ColumnSchema* column_schemas;
+ int column_num;
+} TableSchema;
+
+// ResultSetMetaData：结果集的元数据，包括列名和数据类型。
+typedef struct result_set_meta_data {
+ char** column_names;
+ TSDataType* data_types;
+ int column_num;
+} ResultSetMetaData;
+```
+
+## 写入接口
+
+### 创建/关闭 TsFile 写入文件
+
+```C++
+/**
+ * @brief 创建写入文件。
+ *
+ * @param pathname 目标文件路径。
+ * @param err_code [输出] RET_OK(0)，或 errno_define_c.h 中的错误码。
+ *
+ * @return WriteFile 成功返回有效句柄。
+ *
+ * @note 调用 free_write_file() 释放资源。
+ * @note 调用 free_write_file() 前，需确保 TsFileWriter 已关闭。
+ */
+
+WriteFile write_file_new(const char* pathname, ERRNO* err_code);
+
+void free_write_file(WriteFile* write_file);
+```
+
+
+### 创建/关闭 TsFile Writer
+
+在创建 TsFile Writer 时，需要指定 WriteFile 和 TableSchema。你可以使用
tsfile_writer_new_with_memory_threshold 设置内存阈值。
+
+```C++
+/**
+ * @brief 创建 TsFileWriter。
+ *
+ * @param file 写入目标文件。
+ * @param schema 表结构定义。
+ * - 由调用者负责释放。
+ * @param err_code [输出] RET_OK(0)，或 errno_define_c.h 中的错误码。
+ *
+ * @return TsFileWriter 成功返回有效句柄，失败返回 NULL。
+ *
+ * @note 使用完毕后需调用 tsfile_writer_close() 释放资源。
+ */
+TsFileWriter tsfile_writer_new(WriteFile file, TableSchema* schema,
+ ERRNO* err_code);
+
+/**
+ * @brief 创建 TsFileWriter，带内存阈值限制。
+ *
+ * @param file 写入目标文件。
+ * @param schema 表结构定义。
+ * - 由调用者负责释放。
+ * @param memory_threshold 超过该内存阈值时会自动刷盘。
+ * @param err_code [输出] RET_OK(0)，或 errno_define_c.h 中的错误码。
+ *
+ * @return TsFileWriter 成功返回有效句柄，失败返回 NULL。
+ *
+ * @note 使用完毕后需调用 tsfile_writer_close() 释放资源。
+ */
+TsFileWriter tsfile_writer_new_with_memory_threshold(WriteFile file,
+ TableSchema* schema,
+ uint64_t memory_threshold,
+ ERRNO* err_code);
+
+/**
+ * @brief 释放 TsFileWriter 相关资源。
+ *
+ * @param writer [输入] 来自 tsfile_writer_new() 的 Writer 句柄。
+ * 调用后该句柄失效，不可重复使用。
+ * @return ERRNO - 成功返回 RET_OK(0)，否则返回错误码。
+ */
+ERRNO tsfile_writer_close(TsFileWriter writer);
+```
+
+
+
+### 创建/关闭/插入数据 Tablet
+
+可以使用 Tablet 批量插入数据。数据写入后需释放对应内存资源。
+```C
+/**
+ * @brief 创建用于批量写入的 Tablet。
+ *
+ * @param column_name_list [输入] 列名数组，长度为 column_num。
+ * @param data_types [输入] 数据类型数组，长度为 column_num。
+ * @param column_num [输入] 列数量，必须 ≥ 1。
+ * @param max_rows [输入] 预分配的最大行数，必须 ≥ 1。
+ * @return Tablet 成功返回有效句柄。
+ * @note 使用完后需调用 free_tablet() 释放资源。
+ */
+Tablet tablet_new(char** column_name_list, TSDataType* data_types,
+ uint32_t column_num, uint32_t max_rows);
+/**
+ * @brief 获取当前 Tablet 中的行数。
+ *
+ * @param tablet [输入] 有效 Tablet 句柄。
+ * @return uint32_t 当前行数 (0 到 max_rows-1)。
+ */
+uint32_t tablet_get_cur_row_size(Tablet tablet);
+
+/**
+ * @brief 向指定行设置时间戳。
+ *
+ * @param tablet [输入] 有效 Tablet。
+ * @param row_index [输入] 目标行号 (0 ≤ index < max_rows)。
+ * @param timestamp [输入] 时间戳 (int64_t 类型)。
+ * @return ERRNO - 成功返回 RET_OK(0)，否则返回错误码。
+ */
+ERRNO tablet_add_timestamp(Tablet tablet, uint32_t row_index,
+ Timestamp timestamp);
+
+
+/**
+ * @brief 按列名为指定行添加字符串值。
+ *
+ * @param value [输入] 以 '\0' 结尾的字符串，调用者保留所有权。
+ */
+ERRNO tablet_add_value_by_name_string(Tablet tablet, uint32_t row_index,
+ const char* column_name,
+ const char* value);
+
+ // 支持多种数据类型插入
+ERRNO tablet_add_value_by_name_int32_t(Tablet tablet, uint32_t row_index,
+ const char* column_name,
+ int32_t value);
+ERRNO tablet_add_value_by_name_int64_t(Tablet tablet, uint32_t row_index,
+ const char* column_name,
+ int64_t value);
+
+ERRNO tablet_add_value_by_name_double(Tablet tablet, uint32_t row_index,
+ const char* column_name,
+ double value);
+
+ERRNO tablet_add_value_by_name_float(Tablet tablet, uint32_t row_index,
+ const char* column_name,
+ float value);
+
+ERRNO tablet_add_value_by_name_bool(Tablet tablet, uint32_t row_index,
+ const char* column_name,
+ bool value);
+
+/**
+ * @brief 按列索引为指定行添加值（支持多种数据类型）。
+ *
+ * @param value [输入] 字符串会被内部复制。
+ */
+ERRNO tablet_add_value_by_index_string(Tablet tablet, uint32_t row_index,
+ uint32_t column_index,
+ const char* value);
+
+
+ERRNO tablet_add_value_by_index_int32_t(Tablet tablet, uint32_t row_index,
+ uint32_t column_index,
+ int32_t value);
+ERRNO tablet_add_value_by_index_int64_t(Tablet tablet, uint32_t row_index,
+ uint32_t column_index,
+ int64_t value);
+
+ERRNO tablet_add_value_by_index_double(Tablet tablet, uint32_t row_index,
+ uint32_t column_index,
+ double value);
+
+ERRNO tablet_add_value_by_index_float(Tablet tablet, uint32_t row_index,
+ uint32_t column_index,
+ float value);
+
+ERRNO tablet_add_value_by_index_bool(Tablet tablet, uint32_t row_index,
+ uint32_t column_index,
+ bool value);
+
+
+void free_tablet(Tablet* tablet);
+```
+
+
+
+
+
+### 将 Tablet 写入 TsFile
+
+```C
+/**
+ * @brief 将 Tablet 中的数据写入 TsFile。
+ *
+ * @param writer [输入] 有效的 TsFileWriter 句柄。
+ * @param tablet [输入] 含数据的 Tablet，写入后可释放。
+ */
+
+ERRNO tsfile_writer_write(TsFileWriter writer, Tablet tablet);
+```
+
+
+
+
+## 读取接口
+
+### TsFile Reader 创建/关闭
+
+```C
+/**
+ * @brief 创建用于读取 TsFile 的 TsFileReader。
+ *
+ * @param pathname [输入] TsFile 路径。
+ * @param err_code [输出] RET_OK(0) 或错误码。
+ * @return 成功时返回有效句柄。
+ *
+ * @note 使用 tsfile_reader_close() 释放资源。
+ */
+
+TsFileReader tsfile_reader_new(const char* pathname, ERRNO* err_code);
+
+/**
+ * @brief 释放 TsFileReader 占用的资源。
+ *
+ * @note 调用后句柄失效，且由此句柄获得的结果集也失效。
+ */
+ERRNO tsfile_reader_close(TsFileReader reader);
+```
+
+
+
+### 查询表 / 获取下一行
+
+```C
+
+/**
+ * @brief 在指定时间范围内，从指定表和列中查询数据。
+ *
+ * @param reader [输入] 通过 tsfile_reader_new() 获取的有效 TsFileReader 句柄。
+ * @param table_name [输入] 目标表名，必须存在于 TsFile 中。
+ * @param columns [输入] 要查询的列名数组。
+ * @param column_num [输入] 列名数组中的列数。
+ * @param start_time [输入] 起始时间戳。
+ * @param end_time [输入] 结束时间戳，必须大于等于 start_time。
+ * @param err_code [输出] 成功返回 RET_OK(0)，否则返回 errno_define_c.h 中定义的错误码。
+ * @return ResultSet 查询结果集句柄。使用完成后必须通过 free_tsfile_result_set() 释放。
+ */
+ResultSet tsfile_query_table(TsFileReader reader, const char* table_name,
+ char** columns, uint32_t column_num,
+ Timestamp start_time, Timestamp end_time,
+ ERRNO* err_code);
+
+/**
+ * @brief 检查并获取结果集中的下一行数据。
+ *
+ * @param result_set [输入] 有效的 ResultSet 句柄。
+ * @param error_code [输出] 成功返回 RET_OK(0)，否则返回 errno_define_c.h 中的错误码。
+ * @return bool - true：存在下一行数据，false：已到达末尾或发生错误。
+ */
+bool tsfile_result_set_next(ResultSet result_set, ERRNO* error_code);
+
+/**
+ * @brief 释放结果集资源。
+ *
+ * @param result_set [输入] 有效的 ResultSet 句柄指针。
+ */
+void free_tsfile_result_set(ResultSet* result_set);
+```
+
+
+
+### 从结果集中获取数据
+
+```c
+/**
+ * @brief 判断当前行中指定列（按列名）对应的值是否为 NULL。
+ *
+ * @param result_set [输入] 当前处于有效行的 ResultSet（需在调用 next() 返回 true 之后）。
+ * @param column_name [输入] 结果集模式中存在的列名。
+ * @return bool - true：值为 NULL 或找不到该列，false：值有效。
+ */
+bool tsfile_result_set_is_null_by_name(ResultSet result_set,
+ const char* column_name);
+
+/**
+ * @brief 判断当前行中指定列（按列索引）对应的值是否为 NULL。
+ *
+ * @param column_index [输入] 列的位置（1 <= 索引 <= 结果集列数）。
+ * @return bool - true：值为 NULL 或索引超出范围，false：值有效。
+ */
+bool tsfile_result_set_is_null_by_index(ResultSet result_set,
+ uint32_t column_index);
+
+/**
+ * @brief 根据列名获取当前行中的字符串值。
+ *
+ * @param result_set [输入] 有效的结果集句柄。
+ * @param column_name [输入] 要获取的列名。
+ * @return char* - 字符串指针。调用者在使用完后必须手动释放该指针。
+ */
+char* tsfile_result_set_get_value_by_name_string(ResultSet result_set,
+ const char* column_name);
+
+bool tsfile_result_set_get_value_by_name_bool(ResultSet result_set, const
char*
+ column_name);
+int32_t tsfile_result_set_get_value_by_name_int32_t(ResultSet result_set,
const char*
+ column_name);
+int64_t tsfile_result_set_get_value_by_name_int64_t(ResultSet result_set,
const char*
+ column_name);
+float tsfile_result_set_get_value_by_name_float(ResultSet result_set, const
char*
+ column_name);
+double tsfile_result_set_get_value_by_name_double(ResultSet result_set, const
char*
+ column_name);
+
+/**
+ * @brief 根据列索引获取当前行中的字符串值。
+ *
+ * @param result_set [输入] 有效的结果集句柄。
+ * @param column_index [输入] 要获取的列索引（1 <= 索引 <= 列总数）。
+ * @return char* - 字符串指针。调用者在使用完后必须手动释放该指针。
+ */
+char* tsfile_result_set_get_value_by_index_string(ResultSet result_set,
+ uint32_t column_index);
+
+int32_t tsfile_result_set_get_value_by_index_int32_t(ResultSet result_set,
uint32_t
+ column_index);
+int64_t tsfile_result_set_get_value_by_index_int64_t(ResultSet result_set,
uint32_t
+ column_index);
+float tsfile_result_set_get_value_by_index_float(ResultSet result_set,
uint32_t
+ column_index);
+double tsfile_result_set_get_value_by_index_double(ResultSet result_set,
uint32_t
+ column_index);
+bool tsfile_result_set_get_value_by_index_bool(ResultSet result_set, uint32_t
+ column_index);
+
+/**
+ * @brief 获取描述结果集模式的元数据信息。
+ *
+ * @param result_set [输入] 有效的结果集句柄。
+ * @return ResultSetMetaData 元数据句柄。调用者在使用后应释放该元数据。
+ * @note 调用该函数前应检查 result_set 是否为 NULL，NULL 可能表示查询执行失败。
+ */
+ResultSetMetaData tsfile_result_set_get_metadata(ResultSet result_set);
+
+/**
+ * @brief 根据索引从元数据中获取列名。
+ *
+ * @param result_set_meta_data [输入] 有效的结果集元数据句柄。
+ * @param column_index [输入] 列的位置（1 <= 索引 <= 列总数）。
+ * @return const char* 只读字符串。如果索引无效则返回 NULL。
+ */
+
+char* tsfile_result_set_metadata_get_column_name(ResultSetMetaData
result_set_meta_data,
+ uint32_t column_index);
+
+/**
+ * @brief 根据索引从元数据中获取列的数据类型。
+ *
+ * @param result_set_meta_data [输入] 有效的结果集元数据句柄。
+ * @param column_index [输入] 列的位置（1 <= 索引 <= 列总数）。
+ * @return TSDataType 若索引无效则返回 TS_DATATYPE_INVALID（255）。
+ */
+TSDataType tsfile_result_set_metadata_get_data_type(
+ ResultSetMetaData result_set_meta_data, uint32_t column_index);
+
+/**
+ * @brief 获取结果集模式中的列总数。
+ *
+ * @param result_set_meta_data [输入] 有效的结果集元数据句柄。
+ * @return int 结果集中列的数量。
+ */
+int tsfile_result_set_metadata_get_column_num(ResultSetMetaData result_set);
+```
+
+
+
+### 从 TsFile Reader 中获取表定义
+
+```C
+/**
+ * @brief 获取 TsFile 中指定表的模式信息。
+ *
+ * @param reader [输入] 有效的读取器句柄。
+ * @param table_name [输入] 目标表名，必须存在于 TsFile 中。
+ * @return TableSchema 包含表及其列的信息。
+ * @note 调用者应调用 free_table_schema 释放返回的 TableSchema 资源。
+ */
+
+TableSchema tsfile_reader_get_table_schema(TsFileReader reader,
+ const char* table_name);
+/**
+ * @brief 获取 TsFile 中所有表的模式信息。
+ *
+ * @param size [输出] 返回的表模式数组中的元素数量。
+ * @return TableSchema* 表模式数组指针。
+ * @note 调用者必须对数组中的每个元素调用 free_table_schema()，
+ * 并对整个数组指针调用 free() 进行释放。
+ */
+
+TableSchema* tsfile_reader_get_all_table_schemas(TsFileReader reader,
+ uint32_t* size);
+
+/**
+ * @brief 释放 TableSchema 占用的内存空间。
+ *
+ * @param schema [输入] 需要释放的表模式结构。
+ */
+
+void free_table_schema(TableSchema schema);
+```
+
diff --git
a/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md
b/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md
new file mode 100644
index 00000000..11ba24bf
--- /dev/null
+++
b/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md
@@ -0,0 +1,446 @@
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+# 接口定义 - Cpp
+
+## 写入接口
+
+### TsFileTableWriter
+
+用于写入 TsFile.
+
+```cpp
+/**
+ * @brief 用于将结构化表格数据写入具有指定模式的 TsFile。
+ *
+ * TsFileTableWriter 类被设计用于写入结构化数据，特别适合时序数据，
+ * 数据将被写入一种为高效存储与检索优化的文件格式（即 TsFile）。该类允许用户定义
+ * 所需写入表的模式，按照该模式添加数据行，并将这些数据序列化写入 TsFile。
+ * 此外，还提供了在写入过程中限制内存使用的选项。
+ */
+class TsFileTableWriter {
+ public:
+ /**
+ * TsFileTableWriter 用于将表格数据写入具有指定模式的目标文件，
+ * 可选地限制内存使用。
+ *
+ * @param writer_file 要写入表数据的目标文件。不能为空。
+ * @param table_schema 用于构造表结构，定义正在写入表的模式。
+ * @param memory_threshold 可选参数。当写入数据的大小超过该值时，
+ * 数据将自动刷新到磁盘。默认值为 128MB。
+ */
+
+ TsFileTableWriter(WriteFile* writer_file,
+ TableSchema* table_schema,
+ uint64_t memory_threshold = 128 * 1024 * 1024);
+ ~TsFileTableWriter();
+ /**
+ * 将给定的 Tablet 数据按照表的模式写入目标文件。
+ *
+ * @param tablet 包含待写入数据的 Tablet。不能为空。
+ * @return 成功时返回 0，失败时返回 errno_define.h 中的非零错误码。
+ */
+
+ int write_table(const Tablet& tablet);
+ /**
+ * 将所有缓冲数据刷新到底层存储介质，确保所有数据都已写出。
+ * 此方法确保所有未完成的写入操作被持久化。
+ *
+ * @return 成功时返回 0，失败时返回 errno_define.h 中的非零错误码。
+ */
+
+ int flush();
+ /**
+ * 关闭写入器并释放其占用的所有资源。
+ * 调用此方法后，不应再对该实例执行任何操作。
+ *
+ * @return 成功时返回 0，失败时返回 errno_define.h 中的非零错误码。
+ */
+
+ int close();
+};
+```
+
+### 表模式
+
+描述表模式（schema）的数据结构。
+
+```cpp
+/**
+* @brief 表示整个表的模式信息。
+*
+* 此类包含描述特定表结构所需的元数据，
+* 包括表名以及所有列的模式信息。
+*/
+class TableSchema {
+ public:
+ /**
+ * 使用给定的表名和列模式构造一个 TableSchema 对象。
+ *
+ * @param table_name 表的名称，必须为非空字符串。
+ * 此名称用于在系统中标识该表。
+ * @param column_schemas 一个包含 ColumnSchema 对象的向量。
+ * 每个 ColumnSchema 定义表中一列的模式。
+ */
+ TableSchema(const std::string& table_name,
+ const std::vector<ColumnSchema>& column_schemas);
+};
+
+
+/**
+* @brief 表示单个列的模式信息。
+*
+* 此结构体包含描述特定列存储方式所需的元数据，
+* 包括列名、数据类型和列类别。
+*/
+struct ColumnSchema {
+ std::string column_name_;
+ common::TSDataType data_type_;
+ ColumnCategory column_category_;
+
+ /**
+ * @brief 使用给定参数构造一个 ColumnSchema 对象。
+ *
+ * @param column_name 列的名称，必须为非空字符串。
+ * 此名称用于在表中标识该列。
+ * @param data_type 该列的数据类型，例如 INT32、DOUBLE、TEXT 等。
+ * 数据类型决定了数据的存储与解释方式。
+ * @param column_category 列的类别，用于标识其在模式中的角色或类型，
+ * 例如 FIELD（字段）、TAG（标签）。
+ * 如果未指定，默认为 ColumnCategory::FIELD。
+ * @note 调用者有责任确保 `column_name` 非空。
+ */
+ ColumnSchema(std::string column_name, common::TSDataType data_type,
+ ColumnCategory column_category = ColumnCategory::FIELD) :
column_name_(std::move(column_name)),
+
data_type_(data_type),
+
column_category_(column_category) {
+ }
+};
+
+/**
+ * @brief Represents the data type of a measurement.
+ *
+ * This enumeration defines the supported data types for measurements in the
system.
+ */
+enum TSDataType : uint8_t {
+ BOOLEAN = 0,
+ INT32 = 1,
+ INT64 = 2,
+ FLOAT = 3,
+ DOUBLE = 4,
+ TEXT = 5,
+ STRING = 11
+};
+
+```
+
+### Tablet
+
+
+```cpp
+/**
+ * @brief 表示用于插入到表中的数据行集合及其相关元数据。
+ *
+ * 此类用于管理和组织将要插入特定目标表的数据。
+ * 它负责存储时间戳和值，以及相关的元数据，如列名和数据类型。
+ */
+class Tablet {
+public:
+ /**
+ * @brief 使用给定参数构造一个 Tablet 对象。
+ *
+ * @param column_names 一个包含该 Tablet 中列名的向量。
+ * 每个名称对应目标表中的一列。
+ * @param data_types 一个包含每列数据类型的向量。
+ * 这些类型必须与目标表的模式相匹配。
+ * @param max_rows 该 Tablet 可容纳的最大行数，默认为 DEFAULT_MAX_ROWS。
+ */
+ Tablet(const std::vector<std::string> &column_names,
+ const std::vector<common::TSDataType> &data_types,
+ int max_rows = DEFAULT_MAX_ROWS);
+
+ /**
+ * @brief 向指定行添加时间戳。
+ *
+ * @param row_index 要添加时间戳的行索引，
+ * 必须小于最大行数。
+ * @param timestamp 要添加的时间戳值。
+ * @return 成功时返回 0，失败时返回 errno_define.h 中的非零错误码。
+ */
+ int add_timestamp(uint32_t row_index, int64_t timestamp);
+
+ /**
+ * @brief 模板函数，用于向指定的行和列添加类型为 T 的值。
+ *
+ * @tparam T 要添加的值的类型, 如 int32_t, int64_t, double,
+ * float, bool, char*, std::tm.
+ * @param row_index 要添加值的行索引，
+ * 必须小于最大行数。
+ * @param schema_index 要添加的值对应的列模式索引。
+ * @param val 要添加的值。
+ * @return 成功时返回 0，失败时返回 errno_define.h 中的非零错误码。
+ */
+
+ template <typename T>
+ int add_value(uint32_t row_index, uint32_t schema_index, T val);
+
+ /**
+ * @brief 模板函数，用于通过列名向指定的行和列添加类型为 T 的值。
+ *
+ * @tparam T 要添加的值的类型, 如 int32_t, int64_t, double,
+ * float, bool, char*, std::tm.
+ * @param row_index 要添加值的行索引，
+ * 必须小于最大行数。
+ * @param measurement_name 要添加值的列名，
+ * 必须与构造时提供的列名之一匹配。
+ * @param val 要添加的值。
+ * @return 成功时返回 0，失败时返回 errno_define.h 中的非零错误码。
+ */
+ template <typename T>
+ int add_value(uint32_t row_index, const std::string &measurement_name, T
val);
+};
+```
+
+## 读接口
+### Tsfile Reader
+```cpp
+/**
+ * @brief TsFileReader 提供了查询所有以 .tsfile 为后缀的文件的能力。
+ *
+ * TsFileReader 旨在用于查询 .tsfile 文件，它支持树模型查询和表模型查询，
+ * 并支持查询元数据信息，如 TableSchema 和 TimeseriesSchema。
+ */
+
+class TsFileReader {
+ public:
+ TsFileReader();
+ ~TsFileReader();
+ /**
+ * @brief 打开 tsfile 文件。
+ *
+ * @param file_path 要打开的 tsfile 文件路径。
+ * @return 成功时返回 0，失败时返回 errno_define.h 中的非零错误码。
+ */
+
+ int open(const std::string &file_path);
+ /**
+ * @brief 关闭 tsfile，查询完成后应调用此方法。
+ *
+ * @return 成功时返回 0，失败时返回 errno_define.h 中的非零错误码。
+ */
+ int close();
+ /**
+ * @brief 通过查询表达式对 tsfile 进行查询，用户可以自行构造查询表达式来查询 tsfile。
+ *
+ * @param [in] qe 查询表达式。
+ * @param [out] ret_qds 查询结果集。
+ * @return 成功时返回 0，失败时返回 errno_define.h 中的非零错误码。
+ */
+ int query(storage::QueryExpression *qe, ResultSet *&ret_qds);
+ /**
+ * @brief 通过路径列表、起始时间和结束时间查询 tsfile，
+ * 本方法使用树模型进行查询。
+ *
+ * @param [in] path_list 路径列表。
+ * @param [in] start_time 起始时间。
+ * @param [in] end_time 结束时间。
+ * @param [out] result_set 查询结果集。
+ */
+ int query(std::vector<std::string> &path_list, int64_t start_time,
+ int64_t end_time, ResultSet *&result_set);
+ /**
+ * @brief 通过表名、列名、起始时间和结束时间查询 tsfile，
+ * 本方法使用表模型进行查询。
+ *
+ * @param [in] table_name 表名。
+ * @param [in] columns_names 列名列表。
+ * @param [in] start_time 起始时间。
+ * @param [in] end_time 结束时间。
+ * @param [out] result_set 查询结果集。
+ */
+ int query(const std::string &table_name,
+ const std::vector<std::string> &columns_names, int64_t
start_time,
+ int64_t end_time, ResultSet *&result_set);
+ /**
+ * @brief 销毁结果集，该方法应在查询完成并使用完 result_set 后调用。
+ *
+ * @param qds 查询结果集。
+ */
+ void destroy_query_data_set(ResultSet *qds);
+ ResultSet *read_timeseries(
+ const std::shared_ptr<IDeviceID> &device_id,
+ const std::vector<std::string> &measurement_name);
+ /**
+ * @brief 获取 tsfile 中的所有设备。
+ *
+ * @param table_name 表名。
+ * @return std::vector<std::shared_ptr<IDeviceID>> 设备 ID 列表。
+ */
+ std::vector<std::shared_ptr<IDeviceID>> get_all_devices(
+ std::string table_name);
+ /**
+ * @brief 根据设备 ID 和测量名称获取时间序列模式信息。
+ *
+ * @param [in] device_id 设备 ID。
+ * @param [out] result std::vector<MeasurementSchema> 测量模式列表。
+ * @return 成功时返回 0，失败时返回 errno_define.h 中的非零错误码。
+ */
+ int get_timeseries_schema(std::shared_ptr<IDeviceID> device_id,
+ std::vector<MeasurementSchema> &result);
+ /**
+ * @brief 根据表名获取表的模式信息。
+ *
+ * @param table_name 表名。
+ * @return std::shared_ptr<TableSchema> 表的模式信息。
+ */
+ std::shared_ptr<TableSchema> get_table_schema(
+ const std::string &table_name);
+ /**
+ * @brief 获取 tsfile 中所有表的模式信息。
+ *
+ * @return std::vector<std::shared_ptr<TableSchema>> 表模式信息列表。
+ */
+ std::vector<std::shared_ptr<TableSchema>> get_all_table_schemas();
+};
+```
+### ResultSet
+```cpp
+/**
+ * @brief ResultSet 是 TsFileReader 的查询结果集，用于访问查询结果。
+ *
+ * ResultSet 是一个虚类，使用时应转换为相应的实现类。
+ * @note 当使用树模型且过滤器是全局时间过滤器时，应转换为 QDSWithoutTimeGenerator。
+ * @note 当使用树模型但过滤器不是全局时间过滤器时，应转换为 QDSWithTimeGenerator。
+ * @note 如果查询使用的是表模型，则应转换为 TableResultSet。
+ */
+class ResultSet {
+ public:
+ ResultSet() {}
+ virtual ~ResultSet() {}
+
+ /**
+ * @brief 获取结果集的下一行。
+ *
+ * @param[out] has_next 布尔值，指示是否还有下一行。
+ * @return 成功时返回 0，失败时返回 errno_define.h 中的非零错误码。
+ */
+ virtual int next(bool& has_next) = 0;
+
+ /**
+ * @brief 根据列名检查该列的值是否为 null。
+ *
+ * @param column_name 列名。
+ * @return 如果值为 null 返回 true，否则返回 false。
+ */
+ virtual bool is_null(const std::string& column_name) = 0;
+
+ /**
+ * @brief 根据列索引检查该列的值是否为 null。
+ *
+ * @param column_index 从 1 开始的列索引。
+ * @return 如果值为 null 返回 true，否则返回 false。
+ */
+ virtual bool is_null(uint32_t column_index) = 0;
+
+ /**
+ * @brief 根据列名获取该列的值。
+ *
+ * @param column_name 列名。
+ * @return 该列的值。
+ */
+ template <typename T>
+ T get_value(const std::string& column_name);
+
+ /**
+ * @brief 根据列索引获取该列的值。
+ *
+ * @param column_index 从 1 开始的列索引。
+ * @return 该列的值。
+ */
+ template <typename T>
+ T get_value(uint32_t column_index);
+
+ /**
+ * @brief 获取当前行的 RowRecord。
+ *
+ * @return 当前行的 RowRecord。
+ */
+ virtual RowRecord* get_row_record() = 0;
+
+ /**
+ * @brief 获取结果集的元数据。
+ *
+ * @return std::shared_ptr<ResultSetMetadata> 结果集的元数据。
+ */
+ virtual std::shared_ptr<ResultSetMetadata> get_metadata() = 0;
+
+ /**
+ * @brief 关闭结果集。
+ *
+ * @note 当不再需要结果集时应调用此方法。
+ */
+ virtual void close() = 0;
+};
+
+```
+### ResultMeta
+```cpp
+/**
+ * @brief 结果集的元数据信息。
+ *
+ * 用户可以通过 ResultSetMetadata 获取结果集的元数据，
+ * 包括所有列名和数据类型。当用户使用表模型时，第一列默认是时间列。
+ */
+class ResultSetMetadata {
+ public:
+ /**
+ * @brief ResultSetMetadata 的构造函数。
+ *
+ * @param column_names 列名列表。
+ * @param column_types 列类型列表。
+ */
+ ResultSetMetadata(const std::vector<std::string>& column_names,
+ const std::vector<common::TSDataType>& column_types);
+
+ /**
+ * @brief 获取指定索引的列类型。
+ *
+ * @param column_index 从 1 开始的列索引。
+ * @return 对应的列类型。
+ */
+ common::TSDataType get_column_type(uint32_t column_index);
+
+ /**
+ * @brief 获取指定索引的列名。
+ *
+ * @param column_index 从 1 开始的列索引。
+ * @return 对应的列名。
+ */
+ std::string get_column_name(uint32_t column_index);
+
+ /**
+ * @brief 获取列的总数量。
+ *
+ * @return 列的数量（uint32_t 类型）。
+ */
+ uint32_t get_column_count();
+};
+
+```
\ No newline at end of file
diff --git a/src/zh/UserGuide/latest/QuickStart/Interface-Definitions.md
b/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-Java.md
similarity index 76%
rename from src/zh/UserGuide/latest/QuickStart/Interface-Definitions.md
rename to
src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-Java.md
index 09227a9d..109d2841 100644
--- a/src/zh/UserGuide/latest/QuickStart/Interface-Definitions.md
+++
b/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-Java.md
@@ -18,43 +18,49 @@
under the License.
-->
-# 接口定义
+# 接口定义 - Java
## 写入接口
### ITsFileWriter
-用于写入数据至 tsfile
+用于将数据写入 TsFile
```Java
interface ITsFileWriter extends AutoCloseable {
// 写入数据
void write(Tablet tablet);
- // 关闭写入
+
+ // 关闭写入器
void close();
}
+
```
### TsFileWriterBuilder
-用于构造 ITsFileWriter
+用于构建 ITsFileWriter
```Java
class TsFileWriterBuilder {
// 构建 ITsFileWriter 对象
public ITsFileWriter build();
+
// 目标文件
public TsFileWriterBuilder file(File file);
- // 用于构造表结构
+
+ // 用于构建表结构
public TsFileWriterBuilder tableSchema(TableSchema schema);
- // 用于限制对象的内存大小
+
+ // 用于限制写入时的内存使用大小
public TsFileWriterBuilder memoryThreshold(long memoryThreshold);
}
+
```
### TableSchema
-描述表 schema 的数据结构
+描述表结构的数据组织方式
```Java
class TableSchema {
@@ -65,10 +71,13 @@ class TableSchema {
class ColumnSchema {
// 构造函数
public ColumnSchema(String columnName, TSDataType dataType, ColumnCategory
columnCategory);
+
// 获取列名
public String getColumnName();
+
// 获取列的数据类型
public TSDataType getDataType();
+
// 获取列的类别
public Tablet.ColumnCategory getColumnCategory();
}
@@ -76,55 +85,62 @@ class ColumnSchema {
class ColumnSchemaBuilder {
// 构建 ColumnSchema 对象
public ColumnSchema build();
- // 列名
+
+ // 设置列名
public ColumnSchemaBuilder name(String columnName);
- // 列的数据类型
+
+ // 设置列的数据类型
public ColumnSchemaBuilder dataType(TSDataType columnType);
- // 列类别
+
+ // 设置列的类别
public ColumnSchemaBuilder category(ColumnCategory columnCategory);
+
// 支持的数据类型
enum TSDataType {
- BOOLEAN,
- INT32,
- INT64,
- FLOAT,
- DOUBLE,
- TIMESTAMP,
- TEXT,
- DATE,
- BLOB,
- STRING;
+ BOOLEAN, // 布尔型
+ INT32, // 32位整数
+ INT64, // 64位整数
+ FLOAT, // 单精度浮点数
+ DOUBLE, // 双精度浮点数
+ TIMESTAMP, // 时间戳
+ TEXT, // 文本
+ DATE, // 日期
+ BLOB, // 二进制大对象
+ STRING; // 字符串
}
+
// 支持的列类别
enum ColumnCategory {
- TAG,
- FIELD
+ TAG, // 标签列
+ FIELD // 测点列
}
}
+
```
### Tablet
-写入的列式内存结构
```Java
class Tablet {
// 构造函数
public Tablet(List<String> columnNameList, List<TSDataType> dataTypeList);
public Tablet(List<String> columnNameList, List<TSDataType> dataTypeList,
int maxRowNum);
- // 添加时间戳的接口
+
+ // 添加时间戳
void addTimestamp(int rowIndex, long timestamp);
- // 添加值的接口
- // 根据列名添加值
+
+ // 添加值
+ // 基于列名添加值
void addValue(int rowIndex, String columnName, int val);
void addValue(int rowIndex, String columnName, long val);
void addValue(int rowIndex, String columnName, float val);
void addValue(int rowIndex, String columnName, double val);
void addValue(int rowIndex, String columnName, boolean val);
void addValue(int rowIndex, String columnName, String val);
- void addValue(int rowIndex, String columnName, byte[] val);
+ void addValue(int rowIndex, String columnName, byte[] val);
void addValue(int rowIndex, String columnName, LocalDate val);
- // 根据索引位置添加值
+ // 基于索引添加值
void addValue(int rowIndex, int columnIndex, int val);
void addValue(int rowIndex, int columnIndex, long val);
void addValue(int rowIndex, int columnIndex, float val);
@@ -136,48 +152,54 @@ class Tablet {
}
```
-## 查询接口
+## Read Interface
### ITsFileReader
-用于查询 tsfile 中的数据
+用于在 TsFile 中查询数据。
```Java
interface ITsFileReader extends AutoCloseable {
// 用于执行查询并返回结果
ResultSet query(String tableName, List<String> columnNames, long startTime,
long endTime);
- // 返回tsfile中名为tableName的表的架构
+
+ // 返回 tsfile 中指定表名（tableName）的表结构信息
Optional<TableSchema> getTableSchemas(String tableName);
- // 检索ts文件中所有表的架构信息
+
+ // 获取 tsfile 中所有表的结构信息
List<TableSchema> getAllTableSchema();
+
// 关闭查询
void close();
}
+
```
### TsFileReaderBuilder
-用于构建 ITsFileWriter
+用于构建 ITsFileReader
```Java
class TsFileReaderBuilder {
// 构建 ITsFileReader 对象
public ITsFileReader build();
+
// 目标文件
public TsFileReaderBuilder file(File file);
}
+
```
### ResultSet
-用于构建 ITsFileWriter
+查询的结果集
```Java
interface ResultSet extends AutoCloseable {
- // 将光标移动到下一行并返回是否还有数据
- boolean next();
+ // 将游标移动到下一行，并返回是否还有数据
+ boolean next();
- // 获取当前行和某一列的值
+ // 获取当前行某一列的值
int getInt(String columnName);
int getInt(int columnIndex);
long getLong(String columnName);
@@ -195,27 +217,30 @@ interface ResultSet extends AutoCloseable {
byte[] getBinary(String columnName);
byte[] getBinary(int columnIndex);
- // 确定当前行中的列是否为NULL
+ // 判断当前行某一列是否为 NULL
boolean isNull(String columnName);
boolean isNull(int columnIndex);
- // 关闭当前结构集
+ // 关闭当前结果集
void close();
- // 获取结果集的表头
+ // 获取结果集的元数据信息
ResultSetMetadata getMetadata();
}
+
```
### ResultSetMetadata
-用于获取结果集的元数据
+用于获取结果集的元数据信息
```Java
-interface ResultSetMetadata {
- // 获取结果集第N列的列名
+interface ResultSetMetadata {
+ // 获取结果集中第 N 列的列名
String getColumnName(int columnIndex);
- // 获取结果集第N列的数据类型
+
+ // 获取结果集中第 N 列的数据类型
TSDataType getColumnType(int columnIndex);
}
+
```
diff --git
a/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md
b/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md
new file mode 100644
index 00000000..157d8cba
--- /dev/null
+++
b/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md
@@ -0,0 +1,264 @@
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+# 接口定义 - Python
+
+## 数据模式
+
+```Python
+class TSDataType(IntEnum):
+ """
+ TsFile 当前支持的数据类型枚举。
+ """
+ BOOLEAN = 0
+ INT32 = 1
+ INT64 = 2
+ FLOAT = 3
+ DOUBLE = 4
+ TEXT = 5
+ STRING = 11
+
+class ColumnCategory(IntEnum):
+ """
+ TsFile 中的列类别枚举。
+ TAG：表示标签列，用于存储元数据。
+ FIELD：表示测点列，用于存储实际数据值。
+ """
+ TAG = 0
+ FIELD = 1
+
+class ColumnSchema:
+ """定义表中某一列的模式（名称、数据类型、类别）。"""
+
+ column_name = None
+ data_type = None
+ category = None
+
+ def __init__(self, column_name: str, data_type: TSDataType,
+ category: ColumnCategory = ColumnCategory.FIELD)
+
+class TableSchema:
+ """表结构的模式定义。"""
+
+ table_name = None
+ columns = None
+
+ def __init__(self, table_name: str, columns: List[ColumnSchema])
+
+class ResultSetMetaData:
+ """查询结果集的元数据容器（列名、类型、表名）。"""
+
+ column_list = None
+ data_types = None
+ table_name = None
+
+ def __init__(self, column_list: List[str], data_types: List[TSDataType])
+
+
+```
+
+
+
+## 写入接口
+
+### TsFileWriter
+
+```python
+class TsFileTableWriter:
+ """
+ 用于将结构化表格数据写入具有指定模式的 TsFile。
+ """
+
+ """
+ :param path: tsfile 文件路径，如果不存在则会创建。
+ :param table_schema: 描述要写入表的结构信息。
+ :return: 无返回值。
+ """
+ def __init__(self, path: str, table_schema: TableSchema)
+
+ """
+ 将一个 Tablet 写入 TsFile 中的表中。
+ :param tablet: 存储表的批量数据。
+ :return: 无返回值。
+ """
+ def write_table(self, tablet: Tablet)
+
+ """
+ 关闭 TsFileTableWriter，并自动刷新数据。
+ :return: 无返回值。
+ """
+ def close(self)
+
+
+```
+
+
+### Tablet definition
+
+
+```Python
+class Tablet(object)
+ """
+ 一个为批量数据预分配的列式数据容器，具有类型约束。
+ 它会创建时间戳缓冲区和带类型的数据列，并对数值类型执行有效值范围校验。
+
+ 初始化参数:
+ :param column_name_list: 数据列的名称列表。
+ :param type_list: 每列允许的数据类型（TSDataType 枚举值）。
+ :param max_row_num: 预分配的最大行数（默认值为 1024）。
+ :return: 无返回值。
+ """
+
+ def __init__(self, column_name_list: list[str], type_list:
list[TSDataType],
+ max_row_num: int = 1024)
+
+```
+
+## 读取接口
+
+### TsFileReader
+
+```python
+class TsFileReader:
+ """
+ 从 TsFile 中查询表格数据。
+ """
+
+ """
+ 初始化指定路径的 TsFile 读取器。
+ :param pathname: TsFile 文件的路径。
+ :return: 无返回值。
+ """
+ def __init__(self, pathname)
+
+ """
+ 对指定的表和列执行时间范围查询。
+
+ :param table_name: 要查询的表名。
+ :param column_names: 要检索的列名列表。
+ :param start_time: 查询范围的起始时间（默认：int64 最小值）。
+ :param end_time: 查询范围的结束时间（默认：int64 最大值）。
+ :return: 查询结果集处理器。
+ """
+ def query_table(self, table_name : str, column_names : List[str],
+ start_time : int = np.iinfo(np.int64).min,
+ end_time: int = np.iinfo(np.int64).max) -> ResultSet
+
+ """
+ 获取指定表的模式信息。
+
+ :param table_name: 表名。
+ :return: 指定表的模式信息。
+ """
+ def get_table_schema(self, table_name : str) -> TableSchema
+
+ """
+ 获取 TsFile 中所有表的模式信息。
+
+ :return: 一个将表名映射到其模式的字典。
+ """
+ def get_all_table_schemas(self) -> dict[str, TableSchema]
+
+ """
+ 关闭 TsFile 读取器。如果读取器中有活动的结果集，它们将失效。
+ """
+ def close(self)
+
+
+```
+
+### ResultSet
+
+
+```python
+class ResultSet:
+ """
+ 用于从查询结果集中获取数据。当执行查询时，将返回一个结果集处理器。
+ 如果读取器被关闭，该结果集将失效。
+ """
+
+ """
+ 检查并移动到查询结果集中的下一行。
+
+ :return: 如果存在下一行则返回 True，否则返回 False。
+ """
+ def next(self) -> bool
+
+ """
+ 获取结果集的列信息。
+
+ :return: 一个字典，键为列名，值为对应的数据类型。
+ """
+ def get_result_column_info(self) -> dict[str, TsDataType]
+
+ """
+ 从查询结果集中读取下一个 DataFrame。
+
+ :param max_row_num: 要读取的最大行数，默认值为 1024。
+ :return: 包含查询结果数据的 DataFrame。
+ """
+ def read_next_data_frame(self, max_row_num : int = 1024) -> DataFrame
+
+ """
+ 从查询结果集中按索引获取值。
+
+ :param index: 要获取值的索引，1 <= index <= column_num。
+ :return: 指定索引处的值。
+ """
+ def get_value_by_index(self, index : int)
+
+ """
+ 从查询结果集中按列名获取值。
+
+ :param column_name: 要获取值的列名。
+ :return: 指定列的值。
+ """
+ def get_value_by_name(self, column_name : str)
+
+ """
+ 获取结果集的元数据信息。
+
+ :return: 结果集的元数据，类型为 ResultSetMetadata 对象。
+ """
+ def get_metadata(self) -> ResultSetMetadata
+
+ """
+ 检查结果集中指定索引位置的字段是否为 null。
+
+ :param index: 要检查的字段索引，1 <= index <= column_num。
+ :return: 若字段为 null 返回 True，否则返回 False。
+ """
+ def is_null_by_index(self, index : int)
+
+ """
+ 检查结果集中指定列名的字段是否为 null。
+
+ :param name: 要检查的列名。
+ :return: 若字段为 null 返回 True，否则返回 False。
+ """
+ def is_null_by_name(self, name : str)
+
+ """
+ 关闭结果集并释放相关资源。
+ """
+ def close(self)
+
+```
+
diff --git a/src/zh/UserGuide/latest/QuickStart/QuickStart-C.md
b/src/zh/UserGuide/latest/QuickStart/QuickStart-C.md
new file mode 100644
index 00000000..9574787b
--- /dev/null
+++ b/src/zh/UserGuide/latest/QuickStart/QuickStart-C.md
@@ -0,0 +1,245 @@
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+# 快速上手 - C
+
+## 依赖
+
+- CMake >=3.11
+- Maven >=3.9.6
+- GCC >=4.8.5
+- Make >=4.3
+
+## 安装
+
+从git克隆源代码:
+
+```shell
+git clone https://github.com/apache/tsfile.git
+```
+在 TsFile 根目录下执行 maven 编译:
+
+```shell
+mvn clean install -P with-cpp -DskipTests
+```
+
+如果没有安装 maven, 你可以执行下面的指令完成编译:
+
+在 Linux 或 Macos上：
+```shell
+mvnw clean install -P with-cpp -DskipTests
+```
+在 Windows 上:
+
+```shell
+mvnw.cmd clean install -P with-cpp -DskipTests
+```
+
+### 目录结构
+
+• **Include 目录**: 位于
`tsfile/cpp/target/build/include/cwrapper`，包含用于集成的头文件。将该路径添加到编译器的包含路径中（例如，使用 -I
标志）。
+
+• **Lib 目录**: 位于 `tsfile/cpp/target/build/lib`，存放编译后的库文件。链接时指定该路径和库名称（例如，使用
-L 和 -l 标志）。
+
+### 配置CMake
+
+在您的 CMakeLists.txt 中添加：
+```CMAKE
+find_library(TSFILE_LIB NAMES tsfile PATHS ${SDK_LIB} REQUIRED)
+target_link_libraries(your_target ${TSFILE_LIB})
+```
+注意：将 ${SDK_LIB} 设置为您的 TSFile 库目录。
+
+## 写入流程
+
+### 构造 TsFileWriter
+
+```C
+ERRNO code = 0;
+ char* table_name = "table1";
+
+ // Create table schema to describe a table in a tsfile.
+ TableSchema table_schema;
+ table_schema.table_name = strdup(table_name);
+ table_schema.column_num = 3;
+ table_schema.column_schemas =
+ (ColumnSchema*)malloc(sizeof(ColumnSchema) * 3);
+ table_schema.column_schemas[0] =
+ (ColumnSchema){.column_name = strdup("id1"),
+ .data_type = TS_DATATYPE_STRING,
+ .column_category = TAG};
+ table_schema.column_schemas[1] =
+ (ColumnSchema){.column_name = strdup("id2"),
+ .data_type = TS_DATATYPE_STRING,
+ .column_category = TAG};
+ table_schema.column_schemas[2] =
+ (ColumnSchema){.column_name = strdup("s1"),
+ .data_type = TS_DATATYPE_INT32,
+ .column_category = FIELD};
+
+ // Create a file with specify path to write tsfile.
+ WriteFile file = write_file_new("test_c.tsfile", &code);
+ HANDLE_ERROR(code);
+
+ // Create tsfile writer with specify table schema.
+ TsFileWriter writer = tsfile_writer_new(file, &table_schema, &code);
+ HANDLE_ERROR(code);
+```
+
+### 写入数据
+
+```C
+// Create tablet to insert data.
+ Tablet tablet =
+ tablet_new((char*[]){"id1", "id2", "s1"},
+ (TSDataType[]){TS_DATATYPE_STRING, TS_DATATYPE_STRING,
+ TS_DATATYPE_INT32},
+ 3, 5);
+
+ 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_int32_t(tablet, row, "s1", row);
+ }
+
+ // Write tablet data.
+ HANDLE_ERROR(tsfile_writer_write(writer, tablet));
+
+ // Free tablet.
+ free_tablet(&tablet);
+
+ // Free table schema we used before.
+ free_table_schema(table_schema);
+```
+### 关闭文件
+
+```C
+ // Close writer.
+ HANDLE_ERROR(tsfile_writer_close(writer));
+
+ // Close write file after closing writer.
+ free_write_file(&file);
+```
+### 示例代码
+
+The sample code of using these interfaces is in
<https://github.com/apache/tsfile/blob/develop/cpp/examples/c_examples/demo_write.c>
+
+## 读取流程
+
+### 构造 TsFileReader
+
+```C
+ ERRNO code = 0;
+ char* table_name = "table1";
+
+ // Create tsfile reader with specify tsfile's path
+ TsFileReader reader = tsfile_reader_new("test_c.tsfile", &code);
+ HANDLE_ERROR(code);
+```
+
+### 构造 Query Request
+```C
+ ResultSet ret = tsfile_query_table(
+ reader, table_name, (char*[]){"id1", "id2", "s1"}, 3, 0, 10, &code);
+ HANDLE_ERROR(code);
+
+ if (ret == NULL) {
+ HANDLE_ERROR(RET_INVALID_QUERY);
+ }
+```
+
+### 查询数据
+
+```C
+// Get query result metadata: column name and datatype
+ ResultSetMetaData metadata = tsfile_result_set_get_metadata(ret);
+ int column_num = tsfile_result_set_metadata_get_column_num(metadata);
+
+ for (int i = 1; i <= column_num; i++) {
+ printf("column:%s, datatype:%d\n",
tsfile_result_set_metadata_get_column_name(metadata, i),
+ tsfile_result_set_metadata_get_data_type(metadata, i));
+ }
+
+ // Get data by column name or index.
+ while (tsfile_result_set_next(ret, &code) && code == RET_OK) {
+ // Timestamp at column 1 and column index begin from 1.
+ Timestamp timestamp =
+ tsfile_result_set_get_value_by_index_int64_t(ret, 1);
+ printf("%ld\n", timestamp);
+ for (int i = 1; i <= column_num; i++) {
+ if (tsfile_result_set_is_null_by_index(ret, i)) {
+ printf(" null ");
+ } else {
+ switch (tsfile_result_set_metadata_get_data_type(metadata, i))
{
+ case TS_DATATYPE_BOOLEAN:
+ printf("%d\n",
tsfile_result_set_get_value_by_index_bool(
+ ret, i));
+ break;
+ case TS_DATATYPE_INT32:
+ printf("%d\n",
+
tsfile_result_set_get_value_by_index_int32_t(ret,
+
i));
+ break;
+ case TS_DATATYPE_INT64:
+ printf("%ld\n",
+
tsfile_result_set_get_value_by_index_int64_t(ret,
+
i));
+ break;
+ case TS_DATATYPE_FLOAT:
+ printf("%f\n",
tsfile_result_set_get_value_by_index_float(
+ ret, i));
+ break;
+ case TS_DATATYPE_DOUBLE:
+ printf("%lf\n",
+ tsfile_result_set_get_value_by_index_double(ret,
+ i));
+ break;
+ case TS_DATATYPE_STRING:
+ printf("%s\n",
+ tsfile_result_set_get_value_by_index_string(ret,
+ i));
+ break;
+ default:
+ printf("unknown_type");
+ break;
+ }
+ }
+ }
+ }
+
+ // Free query meta data
+ free_result_set_meta_data(metadata);
+
+ // Free query handler.
+ free_tsfile_result_set(&ret);
+```
+
+### 关闭文件
+
+```C
+ // Close tsfile reader.
+ tsfile_reader_close(reader);
+```
+### 示例代码
+
+The sample code of using these interfaces is in
<https://github.com/apache/tsfile/blob/develop/cpp/examples/c_examples/demo_read.c>
+
diff --git a/src/zh/UserGuide/latest/QuickStart/QuickStart-CPP.md
b/src/zh/UserGuide/latest/QuickStart/QuickStart-CPP.md
new file mode 100644
index 00000000..d91f3d82
--- /dev/null
+++ b/src/zh/UserGuide/latest/QuickStart/QuickStart-CPP.md
@@ -0,0 +1,223 @@
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+# 快速上手 - Cpp
+
+## 依赖
+
+- CMake >=3.11
+- Maven >=3.9.6
+- GCC >=4.8.5
+- Make >=4.3
+
+## 安装
+
+从git克隆源代码:
+
+```shell
+git clone https://github.com/apache/tsfile.git
+```
+在 TsFile 根目录下执行 maven 编译:
+
+```shell
+mvn clean install -P with-cpp -DskipTests
+```
+注意：如果 Maven 没有安装，您可以在 Linux 上使用 `mvnw`，或者在 Windows 上使用 `mvnw.cmd`。
+
+### 目录结构
+
+• **Include 目录**: 位于
`tsfile/cpp/target/build/include`，包含用于集成的头文件。将该路径添加到编译器的包含路径中（例如，使用 -I 标志）。
+
+• **Lib 目录**: 位于 `tsfile/cpp/target/build/lib`，存放编译后的库文件。链接时指定该路径和库名称（例如，使用
-L 和 -l 标志）。
+
+### CMake 集成
+在您的 CMakeLists.txt 中添加：
+```CMAKE
+find_library(TSFILE_LIB NAMES tsfile PATHS ${SDK_LIB} REQUIRED)
+target_link_libraries(your_target ${TSFILE_LIB})
+```
+注意：将 ${SDK_LIB} 设置为您的 TSFile 库目录。
+
+## 写入流程
+
+### 构造 TsFileWriter
+
+```cpp
+ std::string file_name = "test.tsfile";
+ storage::libtsfile_init();
+
+ std::string table_name = "table1";
+
+ // Create a file with specify path to write tsfile.
+ storage::WriteFile file;
+ int flags = O_WRONLY | O_CREAT | O_TRUNC;
+#ifdef _WIN32
+ flags |= O_BINARY;
+#endif
+ mode_t mode = 0666;
+ file.create("test_cpp.tsfile", flags, mode);
+
+ // Create table schema to describe a table in a tsfile.
+ auto* schema = new storage::TableSchema(
+ table_name,
+ {
+ common::ColumnSchema("id1", common::STRING, common::UNCOMPRESSED,
+ common::PLAIN, common::ColumnCategory::TAG),
+ common::ColumnSchema("id2", common::STRING, common::UNCOMPRESSED,
+ common::PLAIN, common::ColumnCategory::TAG),
+ common::ColumnSchema("s1", common::INT64, common::UNCOMPRESSED,
+ common::PLAIN, common::ColumnCategory::FIELD),
+ });
+
+ // Create a file with specify path to write tsfile.
+ auto* writer = new storage::TsFileTableWriter(&file, schema);
+```
+
+### 写入数据
+
+```cpp
+ // Create tablet to insert data.
+ storage::Tablet tablet(
+ table_name, {"id1", "id2", "s1"},
+ {common::STRING, common::STRING, common::INT64},
+ {common::ColumnCategory::TAG, common::ColumnCategory::TAG,
+ common::ColumnCategory::FIELD},
+ 10);
+
+
+ for (int row = 0; row < 5; row++) {
+ long timestamp = row;
+ tablet.add_timestamp(row, timestamp);
+ tablet.add_value(row, "id1", "id1_filed_1");
+ tablet.add_value(row, "id2", "id1_filed_2");
+ tablet.add_value(row, "s1", static_cast<int64_t>(row));
+ }
+
+ // Write tablet data.
+ writer->write_table(tablet);
+
+ // Flush data
+ writer->flush();
+```
+
+### 关闭文件
+
+```cpp
+ writer->close()
+```
+
+### 示例代码
+
+使用这些接口的示例代码可以在以下链接中找到
<https://github.com/apache/tsfile/blob/develop/cpp/examples/cpp_examples/demo_write.cpp>
+
+## 查询流程
+
+### 构造 TsFileReader
+
+```cpp
+ int code = 0;
+ storage::libtsfile_init();
+ std::string table_name = "table1";
+
+ // Create tsfile reader and open tsfile with specify path.
+ storage::TsFileReader reader;
+ reader.open("test_cpp.tsfile");
+```
+
+### 构造 Query Request
+
+```cpp
+ // Query data with tsfile reader.
+ storage::ResultSet* temp_ret = nullptr;
+ std::vector<std::string> columns;
+ columns.emplace_back("id1");
+ columns.emplace_back("id2");
+ columns.emplace_back("s1");
+
+ // Column vector contains the columns you want to select.
+ reader.query(table_name, columns, 0, 100, temp_ret);
+```
+
+### 查询数据
+
+```cpp
+ // Get query handler.
+ auto ret = dynamic_cast<storage::TableResultSet*>(temp_ret);
+
+ // Metadata in query handler.
+ auto metadata = ret->get_metadata();
+ int column_num = metadata->get_column_count();
+ for (int i = 1; i <= column_num; i++) {
+ std::cout << "column name: " << metadata->get_column_name(i)
+ << std::endl;
+ std::cout << "column type: "
+ << std::to_string(metadata->get_column_type(i)) << std::endl;
+ }
+
+ // Check and get next data.
+ bool has_next = false;
+ while ((code = ret->next(has_next)) == common::E_OK && has_next) {
+ // Timestamp at column 1 and column index begin from 1.
+ Timestamp timestamp = ret->get_value<Timestamp>(1);
+ for (int i = 1; i <= column_num; i++) {
+ if (ret->is_null(i)) {
+ std::cout << "null" << std::endl;
+ } else {
+ switch (metadata->get_column_type(i)) {
+ case common::BOOLEAN:
+ std::cout << ret->get_value<bool>(i) << std::endl;
+ break;
+ case common::INT32:
+ std::cout << ret->get_value<int32_t>(i) << std::endl;
+ break;
+ case common::INT64:
+ std::cout << ret->get_value<int64_t>(i) << std::endl;
+ break;
+ case common::FLOAT:
+ std::cout << ret->get_value<float>(i) << std::endl;
+ break;
+ case common::DOUBLE:
+ std::cout << ret->get_value<double>(i) << std::endl;
+ break;
+ case common::STRING:
+ std::cout << ret->get_value<common::String*>(i)
+ ->to_std_string()
+ << std::endl;
+ break;
+ default:;
+ }
+ }
+ }
+ }
+```
+
+### 关闭文件
+
+```cpp
+ // Close query result set.
+ ret->close();
+ // Close reader.
+ reader.close();
+```
+
+### Sample Code
+
+使用这些接口的示例代码可以在以下链接中找到
<https://github.com/apache/tsfile/blob/develop/cpp/examples/cpp_examples/demo_read.cpp>
+
diff --git a/src/zh/UserGuide/latest/QuickStart/QuickStart.md
b/src/zh/UserGuide/latest/QuickStart/QuickStart-JAVA.md
similarity index 92%
rename from src/zh/UserGuide/latest/QuickStart/QuickStart.md
rename to src/zh/UserGuide/latest/QuickStart/QuickStart-JAVA.md
index b750c458..b0c195f0 100644
--- a/src/zh/UserGuide/latest/QuickStart/QuickStart.md
+++ b/src/zh/UserGuide/latest/QuickStart/QuickStart-JAVA.md
@@ -18,7 +18,7 @@
under the License.
-->
-# 快速上手
+# 快速上手 - Java
## 依赖
@@ -78,9 +78,8 @@ TableSchema tableSchema =
.category(Tablet.ColumnCategory.FIELD)
.build(),
new ColumnSchemaBuilder()
- .name("s2")
- .dataType(TSDataType.BOOLEAN)
- .category(Tablet.ColumnCategory.FIELD)
+ .name("s2").
+ dataType(TSDataType.BOOLEAN)
.build()));
long memoryThreshold = 10 * 1024 * 1024;
@@ -122,7 +121,7 @@ writer.close();
### 示例代码
-使用这些接口的示例代码位于：<https://github.com/apache/tsfile/blob/rc/2.0.1/java/examples/src/main/java/org/apache/tsfile/v4/WriteTabletWithITsFileWriter.java>
+使用这些接口的示例代码位于：<https://github.com/apache/tsfile/blob/develop/java/examples/src/main/java/org/apache/tsfile/v4/WriteTabletWithITsFileWriter.java>
## 查询示例
@@ -181,5 +180,5 @@ reader.close();
### 示例代码
-使用这些接口的示例代码位于：<https://github.com/apache/tsfile/blob/rc/2.0.1/java/examples/src/main/java/org/apache/tsfile/v4/ITsFileReaderAndITsFileWriter.java>
+使用这些接口的示例代码位于：<https://github.com/apache/tsfile/blob/develop/java/examples/src/main/java/org/apache/tsfile/v4/ITsFileReaderAndITsFileWriter.java>
diff --git a/src/zh/UserGuide/latest/QuickStart/QuickStart-PYTHON.md
b/src/zh/UserGuide/latest/QuickStart/QuickStart-PYTHON.md
new file mode 100644
index 00000000..6d0b32cd
--- /dev/null
+++ b/src/zh/UserGuide/latest/QuickStart/QuickStart-PYTHON.md
@@ -0,0 +1,131 @@
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+# 快速上手 - Python
+
+## 依赖
+
+如果需要在在本地编译，依赖如下所示：
+
+- CMake >=3.11
+- Maven >=3.9.6
+- GCC >=4.8.5
+- Make >=4.3
+- cython >= 3.0.10
+- numpy >= 1.26.4
+- pandas >= 2.2.2
+- setuptools >= 70.0.0
+
+如果使用 Pip 在线安装 TsFile，依赖包如下：
+
+numpy >= 1.26.4
+pandas >= 2.2.2
+
+## 安装
+
+### 在本地进行编译
+
+从git克隆源代码:
+
+```shell
+git clone https://github.com/apache/tsfile.git
+```
+在 TsFile 根目录下执行 maven 编译:
+
+```shell
+mvn clean install -P with-python -DskipTests
+```
+
+如果没有安装 maven, 你可以执行下面的指令完成编译:
+
+在 Linux 或 Macos上：
+```shell
+mvnw clean install -P with-python -DskipTests
+```
+在 Windows 上:
+
+```shell
+mvnw.cmd clean install -P with-python -DskipTests
+```
+#### 目录结构
+
+• **wheel**: wheel文件位于 `tsfile/python/dist`, 你可以使用 pip install 命令来进行本地安装。
+
+### 安装到本地
+
+你可以执行 `pip install`命令来安装编译得到的 tsfile包（假设他的名字是 tsfile.wheel）
+
+```bash
+pip install tsfile.wheel
+```
+
+### 使用 PIP 进行在线安装
+
+使用pip 指令来在线安装 TsFile 包
+
+```bash
+pip install tsfile
+```
+
+
+## 写入示例
+
+```Python
+table_data_dir = os.path.join(os.path.dirname(__file__), "table_data.tsfile")
+if os.path.exists(table_data_dir):
+ os.remove(table_data_dir)
+
+column1 = ColumnSchema("id", TSDataType.STRING, ColumnCategory.TAG)
+column2 = ColumnSchema("id2", TSDataType.STRING, ColumnCategory.TAG)
+column3 = ColumnSchema("value", TSDataType.FLOAT, ColumnCategory.FIELD)
+table_schema = TableSchema("test_table", columns=[column1, column2, column3])
+
+
+### Free resource automatically
+with TsFileTableWriter(table_data_dir, table_schema) as writer:
+ tablet_row_num = 100
+ tablet = Tablet(
+ ["id", "id2", "value"],
+ [TSDataType.STRING, TSDataType.STRING, TSDataType.FLOAT],
+ tablet_row_num)
+
+ for i in range(tablet_row_num):
+ tablet.add_timestamp(i, i * 10)
+ tablet.add_value_by_name("id", i, "test1")
+ tablet.add_value_by_name("id2", i, "test" + str(i))
+ tablet.add_value_by_index(2, i, i * 100.2)
+
+ writer.write_table(tablet)
+```
+
+## 读取示例
+
+```Python
+table_data_dir = os.path.join(os.path.dirname(__file__), "table_data.tsfile")
+### Free resource automatically
+with TsFileReader(table_data_dir) as reader:
+ print(reader.get_all_table_schemas())
+ with reader.query_table("test_table", ["id2", "value"], 0, 50) as result:
+ print(result.get_metadata())
+ while result.next():
+ print(result.get_value_by_name("id2"))
+ print(result.get_value_by_name("value"))
+ print(result.read_data_frame())
+```
