This is an automated email from the ASF dual-hosted git repository.
hongzhigao 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 d1103359 Add QuickStart-CPP.md
d1103359 is described below
commit d1103359b06c554c14f72617069eb2ded86ffab7
Author: Hongzhi Gao <[email protected]>
AuthorDate: Wed Mar 19 13:45:19 2025 +0800
Add QuickStart-CPP.md
* Add a user guide document for TsFile-CPP
* fix some interfaces
* fix docs
* fix some interfaces
* remove unused data struct
* Add QuickStart-CPP.md
* Add additional content to the user manual
---
src/UserGuide/develop/QuickStart/QuickStart-CPP.md | 224 +++++++++++++++++++++
.../UserGuide/develop/QuickStart/QuickStart-CPP.md | 223 ++++++++++++++++++++
2 files changed, 447 insertions(+)
diff --git a/src/UserGuide/develop/QuickStart/QuickStart-CPP.md
b/src/UserGuide/develop/QuickStart/QuickStart-CPP.md
new file mode 100644
index 00000000..cabdb372
--- /dev/null
+++ b/src/UserGuide/develop/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
+
+## 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/zh/UserGuide/develop/QuickStart/QuickStart-CPP.md
b/src/zh/UserGuide/develop/QuickStart/QuickStart-CPP.md
new file mode 100644
index 00000000..bb8e9432
--- /dev/null
+++ b/src/zh/UserGuide/develop/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.
+
+-->
+# 快速上手
+
+## 依赖
+
+- 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>
+
