apache · CritasWang · Feb 28, 2025 · Feb 25, 2025 · Feb 25, 2025
diff --git a/src/zh/UserGuide/Master/Tree/API/Programming-CSharp-Native-API.md b/src/zh/UserGuide/Master/Tree/API/Programming-CSharp-Native-API.md
@@ -21,13 +21,13 @@
 
 # C# 原生接口
 
-## 依赖
+## 1 依赖
 
 - .NET SDK >= 5.0 或 .NET Framework 4.x
 - Thrift >= 0.14.1
 - NLog >= 4.7.9
 
-## 安装
+## 2 安装
 
 您可以使用 NuGet Package Manager, .NET CLI等工具来安装，以 .NET CLI为例
 
@@ -50,7 +50,7 @@ dotnet add package Apache.IoTDB.framework
 dotnet add package Apache.IoTDB --version 0.12.1.2
 ```
 
-## 基本接口说明
+## 3 基本接口说明
 
 Session接口在语义上和其他语言客户端相同
 
@@ -88,7 +88,7 @@ await session_pool.InsertTabletAsync(tablet);
 await session_pool.Close();
 ```
 
-## **Row Record**
+## 4 **Row Record**
 
 - 对**IoTDB**中的`record`数据进行封装和抽象。
 - 示例：
@@ -104,7 +104,7 @@ var rowRecord =
   new RowRecord(long timestamps, List<object> values, List<string> measurements);
 ```
 
-### **Tablet**
+### 4.1 **Tablet**
 
 - 一种类似于表格的数据结构，包含一个设备的若干行非空数据块。
 - 示例：
@@ -124,9 +124,9 @@ var tablet =
 
 
 
-## **API**
+## 5 **API**
 
-### **基础接口**
+### 5.1 **基础接口**
 
 | api name       | parameters                | notes                    | use example                   |
 | -------------- | ------------------------- | ------------------------ | ----------------------------- |
@@ -138,7 +138,7 @@ var tablet =
 | SetTimeZone    | string                    | set time zone            | session_pool.GetTimeZone()    |
 | GetTimeZone    | null                      | get time zone            | session_pool.GetTimeZone()    |
 
-### **Record相关接口**
+### 5.2 **Record相关接口**
 
 | api name                            | parameters                    | notes                               | use example                                                  |
 | ----------------------------------- | ----------------------------- | ----------------------------------- | ------------------------------------------------------------ |
@@ -149,7 +149,7 @@ var tablet =
 | TestInsertRecordAsync               | string, RowRecord             | test insert record                  | session_pool.TestInsertRecordAsync("root.97209_TEST_CSHARP_CLIENT_GROUP.TEST_CSHARP_CLIENT_DEVICE", rowRecord) |
 | TestInsertRecordsAsync              | List\<string\>, List\<RowRecord\> | test insert record                  | session_pool.TestInsertRecordsAsync(device_id, rowRecords)   |
 
-### **Tablet相关接口**
+### 5.3 **Tablet相关接口**
 
 | api name               | parameters   | notes                | use example                                  |
 | ---------------------- | ------------ | -------------------- | -------------------------------------------- |
@@ -158,14 +158,14 @@ var tablet =
 | TestInsertTabletAsync  | Tablet       | test insert tablet   | session_pool.TestInsertTabletAsync(tablet)   |
 | TestInsertTabletsAsync | List\<Tablet\> | test insert tablets  | session_pool.TestInsertTabletsAsync(tablets) |
 
-### **SQL语句接口**
+### 5.4 **SQL语句接口**
 
 | api name                      | parameters | notes                          | use example                                                  |
 | ----------------------------- | ---------- | ------------------------------ | ------------------------------------------------------------ |
 | ExecuteQueryStatementAsync    | string     | execute sql query statement    | session_pool.ExecuteQueryStatementAsync("select * from root.97209_TEST_CSHARP_CLIENT_GROUP.TEST_CSHARP_CLIENT_DEVICE where time<15"); |
 | ExecuteNonQueryStatementAsync | string     | execute sql nonquery statement | session_pool.ExecuteNonQueryStatementAsync( "create timeseries root.97209_TEST_CSHARP_CLIENT_GROUP.TEST_CSHARP_CLIENT_DEVICE.status with datatype=BOOLEAN,encoding=PLAIN") |
 
-### 数据表接口
+### 5.5 数据表接口
 
 | api name                   | parameters                                                   | notes                       | use example                                                  |
 | -------------------------- | ------------------------------------------------------------ | --------------------------- | ------------------------------------------------------------ |
@@ -178,7 +178,7 @@ var tablet =
 | DeleteTimeSeriesAsync      | string                                                       | delete time series          |                                                              |
 | DeleteDataAsync            | List\<string\>, long, long                                     | delete data                 | session_pool.DeleteDataAsync(ts_path_lst, 2, 3)              |
 
-### **辅助接口**
+### 5.6 **辅助接口**
 
 | api name                   | parameters | notes                       | use example                                          |
 | -------------------------- | ---------- | --------------------------- | ---------------------------------------------------- |
@@ -188,7 +188,7 @@ var tablet =
 
 用法可以参考[用户示例](https://github.com/apache/iotdb-client-csharp/tree/main/samples/Apache.IoTDB.Samples)
 
-## 连接池
+## 6 连接池
 
 为了实现并发客户端请求，我们提供了针对原生接口的连接池(`SessionPool`)，由于`SessionPool`本身为`Session`的超集，当`SessionPool`的`pool_size`参数设置为1时，退化为原来的`Session`
 
@@ -198,19 +198,19 @@ var tablet =
 
 当一个连接被用完后，他会自动返回池中等待下次被使用
 
-## ByteBuffer
+## 7 ByteBuffer
 
 在传入RPC接口参数时，需要对Record和Tablet两种数据结构进行序列化，我们主要通过封装的ByteBuffer类实现
 
 在封装字节序列的基础上，我们进行了内存预申请与内存倍增的优化，减少了序列化过程中内存的申请和释放，在一个拥有20000行的Tablet上进行序列化测试时，速度比起原生的数组动态增长具有**35倍的性能加速**
 
-### 实现介绍
+### 7.1 实现介绍
 在进行`RowRecords`以及`Tablet`的插入时，我们需要对多行RowRecord和Tablet进行序列化以进行发送。客户端中的序列化实现主要依赖于ByteBuffer完成。接下来我们介绍ByteBuffer的实现细节。本文包含如下几点内容:
  - 序列化的协议
  - C#与Java的大小端的差异
  - ByteBuffer内存倍增算法
 
-### 序列化协议
+### 7.2 序列化协议
 客户端向IoTDB服务器发送的序列化数据总体应该包含两个信息。
  -  数据类型
  -  数据本身
@@ -246,10 +246,10 @@ public enum TSDataType{BOOLEAN, INT32, INT64, FLOAT, DOUBLE, TEXT, NONE};
     限制：Tablet中数据不能有空值
 由于向 `IoTDB`服务器发送`Tablet`数据插入请求时会携带`行数`， `列数`, `列数据类型`，所以`Tabelt`序列化时我们不需要加入数据类型信息。`Tablet`是`按照列进行序列化`，这是因为后端可以通过行数得知出当前列的元素个数，同时根据列类型来对数据进行解析。
 
-### CSharp与Java序列化数据时的大小端差异
+### 7.3 CSharp与Java序列化数据时的大小端差异
 由于Java序列化默认大端协议，而CSharp序列化默认得到小端序列。所以我们在CSharp中序列化数据之后，需要对数据进行反转这样后端才可以正常解析。同时当我们从后端获取到序列化的结果时(如`SessionDataset`)，我们也需要对获得的数据进行反转以解析内容。这其中特例便是字符串的序列化，CSharp中对字符串的序列化结果为大端序，所以序列化字符串或者接收到字符串序列化结果时，不需要反转序列结果。
 
-### ByteBuffer内存倍增法
+### 7.4 ByteBuffer内存倍增法
 拥有数万行的Tablet的序列化结果可能有上百兆，为了能够高效的实现大`Tablet`的序列化，我们对ByteBuffer使用`内存倍增法`的策略来减少序列化过程中对于内存的申请和释放。即当当前的buffer的长度不足以放下序列化结果时，我们将当前buffer的内存`至少`扩增2倍。这极大的减少了内存的申请释放次数，加速了大Tablet的序列化速度。
 ```csharp
 private void extend_buffer(int space_need){
@@ -266,7 +266,7 @@ private void extend_buffer(int space_need){
 
 通过上述的策略，我们在一个有`20000`行的Tablet上进行测试时，序列化速度相比Naive数组长度动态生长实现算法具有约35倍的性能加速。
 
-## 异常重连
+## 8 异常重连
 
 当服务端发生异常或者宕机重启时，客户端中原来通过`Open()`产生的的session会失效，抛出`TException`异常
 

diff --git a/src/zh/UserGuide/Master/Tree/API/Programming-Cpp-Native-API.md b/src/zh/UserGuide/Master/Tree/API/Programming-Cpp-Native-API.md
@@ -21,7 +21,7 @@
 
 # C++ 原生接口
 
-## 依赖
+## 1 依赖
 
 - Java 8+
 - Flex
@@ -31,9 +31,9 @@
 - GCC 5.5.0+
 
 
-## 安装
+## 2 安装
 
-### 安装相关依赖
+### 2.1 安装相关依赖
 
 - **MAC**
  1. 安装 Bison ：
@@ -94,7 +94,7 @@
    - 添加 OpenSSL 下的 include 目录到 PATH 环境变量中
 
 
-### 执行编译
+### 2.2 执行编译
 
 从 git 克隆源代码:
 ```shell
@@ -136,7 +136,7 @@ git checkout rc/1.3.2
 
 编译成功后，打包好的库文件位于 `iotdb-client/client-cpp/target` 中，同时可以在 `example/client-cpp-example/target` 下找到编译好的示例程序。
 
-### 编译 Q&A
+### 2.3 编译 Q&A
 
 Q：Linux 上的环境有哪些要求呢？
 
@@ -163,11 +163,11 @@ A:
     - 执行 `.\mvnw.cmd clean install`
     - 回到 iotdb 代码目录执行 `.\mvnw.cmd clean package -pl example/client-cpp-example -am -DskipTests -P with-cpp -Dcmake.generator="Visual Studio 15 2017"`
 
-## 基本接口说明
+## 3 基本接口说明
 
 下面将给出 Session 接口的简要介绍和原型定义：
 
-### 初始化
+### 3.1 初始化
 
 - 开启 Session
 ```cpp
@@ -185,7 +185,7 @@ void open(bool enableRPCCompression);
 void close(); 
 ```
 
-### 数据定义接口（DDL）
+### 3.2 数据定义接口（DDL）
 
 #### Database 管理
 
@@ -309,7 +309,7 @@ std::vector<std::string> showMeasurementsInTemplate(const std::string &template_
 ```
 
 
-### 数据操作接口（DML）
+### 3.3 数据操作接口（DML）
 
 #### 数据写入
 
@@ -391,7 +391,7 @@ void deleteData(const std::vector<std::string> &paths, int64_t endTime);
 void deleteData(const std::vector<std::string> &paths, int64_t startTime, int64_t endTime);
 ```
 
-### IoTDB-SQL 接口
+### 3.4 IoTDB-SQL 接口
 
 - 执行查询语句
 ```cpp
@@ -404,7 +404,7 @@ void executeNonQueryStatement(const std::string &sql);
 ```
 
 
-## 示例代码
+## 4 示例代码
 
 示例工程源代码：
 
@@ -413,9 +413,9 @@ void executeNonQueryStatement(const std::string &sql);
 
 编译成功后，示例代码工程位于 `example/client-cpp-example/target`
 
-## FAQ
+## 5 FAQ
 
-### Thrift 编译相关问题
+### 5.1 Thrift 编译相关问题
 
 1. MAC：本地 Maven 编译 Thrift 时如出现以下链接的问题，可以尝试将 xcode-commandline 版本从 12 降低到 11.5
    https://stackoverflow.com/questions/63592445/ld-unsupported-tapi-file-type-tapi-tbd-in-yaml-file/65518087#65518087

diff --git a/src/zh/UserGuide/Master/Tree/API/Programming-Data-Subscription.md b/src/zh/UserGuide/Master/Tree/API/Programming-Data-Subscription.md
@@ -180,13 +180,13 @@ public class DataConsumerExample {
 
 
 
-## 2 全量接口说明
+## 3 全量接口说明
 
-### 2.1 参数列表
+### 3.1 参数列表
 
 可通过Properties参数对象设置消费者相关参数，具体参数如下。
 
-#### 2.1.1 SubscriptionConsumer
+#### 3.1.1 SubscriptionConsumer
 
 
 | 参数                    | 是否必填（默认值）                                           | 参数含义                                                     |
@@ -220,9 +220,9 @@ public class DataConsumerExample {
 | autoCommitInterval | optional: 5000 (min: 500) | Long: 自动提交消费进度的时间间隔，单位为**毫秒**仅当 autoCommit 参数为 true 的时候才会生效 |
 
 
-### 函数列表
+### 3.2 函数列表
 
-#### 数据订阅
+#### 3.2.1 数据订阅
 
 ##### SubscriptionPullConsumer
 

diff --git a/src/zh/UserGuide/Master/Tree/API/Programming-Go-Native-API.md b/src/zh/UserGuide/Master/Tree/API/Programming-Go-Native-API.md
@@ -21,7 +21,7 @@
 
 # Go 原生接口
 
-## 依赖
+## 1 依赖
 
  * golang >= 1.13
  * make   >= 3.0
@@ -30,7 +30,7 @@
  * Linux、Macos 或其他类 unix 系统
  * Windows+bash (下载 IoTDB Go client 需要 git ，通过 WSL、cygwin、Git Bash 任意一种方式均可)
 
-## 安装方法
+## 2 安装方法
 
  * 通过 go mod
 

diff --git a/src/zh/UserGuide/Master/Tree/API/Programming-JDBC.md b/src/zh/UserGuide/Master/Tree/API/Programming-JDBC.md
@@ -24,19 +24,19 @@
 *注意: 目前的JDBC实现仅是为与第三方工具连接使用的。使用JDBC（执行插入语句时）无法提供高性能写入。
 对于Java应用，我们推荐使用[Java 原生接口](./Programming-Java-Native-API.md)*
 
-## 依赖
+## 1 依赖
 
 * JDK >= 1.8
 * Maven >= 3.6
 
-## 安装方法
+## 2 安装方法
 
 在根目录下执行下面的命令：
 ```shell
 mvn clean install -pl iotdb-client/jdbc -am -DskipTests
 ```
 
-### 在 MAVEN 中使用 IoTDB JDBC
+### 2.1 在 MAVEN 中使用 IoTDB JDBC
 
 ```xml
 <dependencies>
@@ -48,7 +48,7 @@ mvn clean install -pl iotdb-client/jdbc -am -DskipTests
 </dependencies>
 ```
 
-### 示例代码
+### 2.2 示例代码
 
 本章提供了如何建立数据库连接、执行 SQL 和显示查询结果的示例。
 

diff --git a/src/zh/UserGuide/Master/Tree/API/Programming-Java-Native-API.md b/src/zh/UserGuide/Master/Tree/API/Programming-Java-Native-API.md
@@ -341,9 +341,9 @@ public class SessionPoolExample {
 }
 ```
 
-### 3 全量接口说明
+## 3 全量接口说明
 
-#### 3.1 参数列表
+### 3.1 参数列表
 
 Session具有如下的字段，可以通过构造函数或Session.Builder方式设置如下参数
 
@@ -379,9 +379,9 @@ Session具有如下的字段，可以通过构造函数或Session.Builder方式
 
 
 
-#### 3.2 接口列表
+### 3.2 接口列表
 
-##### 3.2.1 元数据管理
+#### 3.2.1 元数据管理
 
 | 方法名                                                       | 功能描述                 | 参数解释                                                     |
 | ------------------------------------------------------------ | ------------------------ | ------------------------------------------------------------ |
@@ -410,7 +410,7 @@ Session具有如下的字段，可以通过构造函数或Session.Builder方式
 | `unsetSchemaTemplate(String prefixPath, String templateName)` | 取消路径的模板设置       | `prefixPath`: 路径，`templateName`: 模板名称                 |
 
 
-##### 3.2.2 数据写入
+#### 3.2.2 数据写入
 
 | 方法名                                                       | 功能描述                           | 参数解释                                                     |
 | ------------------------------------------------------------ | ---------------------------------- | ------------------------------------------------------------ |
@@ -439,7 +439,7 @@ Session具有如下的字段，可以通过构造函数或Session.Builder方式
 | `insertAlignedTablets(Map<String, Tablet> tablets)`          | 批量插入多个对齐Tablet数据         | `tablets`: 设备ID到Tablet的映射表                            |
 | `insertAlignedTablets(Map<String, Tablet> tablets, boolean sorted)` | 批量插入排序的多个对齐Tablet数据   | 同上，增加 `sorted`: 数据是否已排序                          |
 
-##### 3.2.3 数据删除
+#### 3.2.3 数据删除
 
 | 方法名                                                       | 功能描述                     | 参数解释                                 |
 | ------------------------------------------------------------ | ---------------------------- | ---------------------------------------- |
@@ -450,7 +450,7 @@ Session具有如下的字段，可以通过构造函数或Session.Builder方式
 | `deleteData(List<String> paths, long startTime, long endTime)` | 删除路径时间范围内的历史数据 | 同上，增加 `startTime`: 起始时间戳       |
 
 
-##### 3.2.4 数据查询
+#### 3.2.4 数据查询
 
 | 方法名                                                       | 功能描述                         | 参数解释                                                     |
 | ------------------------------------------------------------ | -------------------------------- | ------------------------------------------------------------ |
@@ -468,7 +468,7 @@ Session具有如下的字段，可以通过构造函数或Session.Builder方式
 | `executeAggregationQuery(List<String> paths, List<TAggregationType> aggregations, long startTime, long endTime, long interval, long slidingStep)` | 执行滑动窗口聚合查询             | 同上，增加 `slidingStep`: 滑动步长                           |
 | `fetchAllConnections()`                                      | 获取所有活动连接信息             | 无参数                                                       |
 
-##### 3.2.5 系统状态与备份
+#### 3.2.5 系统状态与备份
 
 | 方法名                     | 功能描述               | 参数解释                               |
 | -------------------------- | ---------------------- | -------------------------------------- |