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 1df4a895 Docs For C and python interface. (#441)
1df4a895 is described below
commit 1df4a895e064fd6140ed3e6a240c9f2596619fe1
Author: Colin Lee <[email protected]>
AuthorDate: Fri Mar 21 11:09:45 2025 +0800
Docs For C and python interface. (#441)
* add c and py doc.
* add C interface.
* add python interface.
* fix doc
* fix some comment in docs.
* add quick start.
* add quick start.
* fix py user guide.
* add doc.
* add python example.
* add doc desc
* fix result set meta data.
* add some code.
* commands to command.
---
.../InterfaceDefinition/InterfaceDefinition-C.md | 473 +++++++++++++++++++++
.../InterfaceDefinition/InterfaceDefinition-CPP.md | 7 +-
.../InterfaceDefinition-Python.md | 282 ++++++++++++
src/UserGuide/develop/QuickStart/QuickStart-C.md | 243 +++++++++++
.../{QuickStart.md => QuickStart-JAVA.md} | 0
.../develop/QuickStart/QuickStart-PYTHON.md | 123 ++++++
.../UserGuide/develop/QuickStart/QuickStart-C.md | 245 +++++++++++
.../{QuickStart.md => QuickStart-JAVA.md} | 0
.../develop/QuickStart/QuickStart-PYTHON.md | 131 ++++++
9 files changed, 1501 insertions(+), 3 deletions(-)
diff --git
a/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md
b/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md
new file mode 100644
index 00000000..93630a53
--- /dev/null
+++
b/src/UserGuide/develop/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
+
+
+
+## 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/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md
b/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md
index 2344b3df..cdae52a4 100644
---
a/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md
+++
b/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md
@@ -44,12 +44,13 @@ class TsFileTableWriter {
* @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 used to limit the memory
size of objects.
- * If set to 0, no memory limit is enforced.
+ * @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 = 0);
+ uint64_t memory_threshold = 128 * 1024 * 1024);
~TsFileTableWriter();
/**
* Writes the given tablet data into the target file according to the
schema.
diff --git
a/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md
b/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md
new file mode 100644
index 00000000..a3e4d9d2
--- /dev/null
+++
b/src/UserGuide/develop/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
+
+## 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/develop/QuickStart/QuickStart-C.md
b/src/UserGuide/develop/QuickStart/QuickStart-C.md
new file mode 100644
index 00000000..035d139b
--- /dev/null
+++ b/src/UserGuide/develop/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
+
+## 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/develop/QuickStart/QuickStart.md
b/src/UserGuide/develop/QuickStart/QuickStart-JAVA.md
similarity index 100%
rename from src/UserGuide/develop/QuickStart/QuickStart.md
rename to src/UserGuide/develop/QuickStart/QuickStart-JAVA.md
diff --git a/src/UserGuide/develop/QuickStart/QuickStart-PYTHON.md
b/src/UserGuide/develop/QuickStart/QuickStart-PYTHON.md
new file mode 100644
index 00000000..505f0342
--- /dev/null
+++ b/src/UserGuide/develop/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
+
+## 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/develop/QuickStart/QuickStart-C.md
b/src/zh/UserGuide/develop/QuickStart/QuickStart-C.md
new file mode 100644
index 00000000..be71a062
--- /dev/null
+++ b/src/zh/UserGuide/develop/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.
+
+-->
+# 快速上手
+
+## 依赖
+
+- 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/develop/QuickStart/QuickStart.md
b/src/zh/UserGuide/develop/QuickStart/QuickStart-JAVA.md
similarity index 100%
rename from src/zh/UserGuide/develop/QuickStart/QuickStart.md
rename to src/zh/UserGuide/develop/QuickStart/QuickStart-JAVA.md
diff --git a/src/zh/UserGuide/develop/QuickStart/QuickStart-PYTHON.md
b/src/zh/UserGuide/develop/QuickStart/QuickStart-PYTHON.md
new file mode 100644
index 00000000..b42cfed0
--- /dev/null
+++ b/src/zh/UserGuide/develop/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.
+
+-->
+# 快速上手
+
+## 依赖
+
+如果需要在在本地编译，依赖如下所示：
+
+- 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())
+```
