Skip to content

Commit 74f1c96

Browse files
leto-bleto-b
authored
add chapter number in part of tree doc-zh (#607)
* add chapter number in part of tree doc-zh * add chapter number in part of tree doc-zh
1 parent 8275a23 commit 74f1c96

112 files changed

Lines changed: 1544 additions & 1804 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎src/zh/UserGuide/Master/Tree/API/Programming-CSharp-Native-API.md‎

Lines changed: 19 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -21,13 +21,13 @@
2121

2222
# C# 原生接口
2323

24-
## 依赖
24+
## 1 依赖
2525

2626
- .NET SDK >= 5.0 或 .NET Framework 4.x
2727
- Thrift >= 0.14.1
2828
- NLog >= 4.7.9
2929

30-
## 安装
30+
## 2 安装
3131

3232
您可以使用 NuGet Package Manager, .NET CLI等工具来安装，以 .NET CLI为例
3333

@@ -50,7 +50,7 @@ dotnet add package Apache.IoTDB.framework
5050
dotnet add package Apache.IoTDB --version 0.12.1.2
5151
```
5252

53-
## 基本接口说明
53+
## 3 基本接口说明
5454

5555
Session接口在语义上和其他语言客户端相同
5656

@@ -88,7 +88,7 @@ await session_pool.InsertTabletAsync(tablet);
8888
await session_pool.Close();
8989
```
9090

91-
## **Row Record**
91+
## 4 **Row Record**
9292

9393
- 对**IoTDB**中的`record`数据进行封装和抽象。
9494
- 示例：
@@ -104,7 +104,7 @@ var rowRecord =
104104
new RowRecord(long timestamps, List<object> values, List<string> measurements);
105105
```
106106

107-
### **Tablet**
107+
### 4.1 **Tablet**
108108

109109
- 一种类似于表格的数据结构，包含一个设备的若干行非空数据块。
110110
- 示例：
@@ -124,9 +124,9 @@ var tablet =
124124

125125

126126

127-
## **API**
127+
## 5 **API**
128128

129-
### **基础接口**
129+
### 5.1 **基础接口**
130130

131131
| api name | parameters | notes | use example |
132132
| -------------- | ------------------------- | ------------------------ | ----------------------------- |
@@ -138,7 +138,7 @@ var tablet =
138138
| SetTimeZone | string | set time zone | session_pool.GetTimeZone() |
139139
| GetTimeZone | null | get time zone | session_pool.GetTimeZone() |
140140

141-
### **Record相关接口**
141+
### 5.2 **Record相关接口**
142142

143143
| api name | parameters | notes | use example |
144144
| ----------------------------------- | ----------------------------- | ----------------------------------- | ------------------------------------------------------------ |
@@ -149,7 +149,7 @@ var tablet =
149149
| TestInsertRecordAsync | string, RowRecord | test insert record | session_pool.TestInsertRecordAsync("root.97209_TEST_CSHARP_CLIENT_GROUP.TEST_CSHARP_CLIENT_DEVICE", rowRecord) |
150150
| TestInsertRecordsAsync | List\<string\>, List\<RowRecord\> | test insert record | session_pool.TestInsertRecordsAsync(device_id, rowRecords) |
151151

152-
### **Tablet相关接口**
152+
### 5.3 **Tablet相关接口**
153153

154154
| api name | parameters | notes | use example |
155155
| ---------------------- | ------------ | -------------------- | -------------------------------------------- |
@@ -158,14 +158,14 @@ var tablet =
158158
| TestInsertTabletAsync | Tablet | test insert tablet | session_pool.TestInsertTabletAsync(tablet) |
159159
| TestInsertTabletsAsync | List\<Tablet\> | test insert tablets | session_pool.TestInsertTabletsAsync(tablets) |
160160

161-
### **SQL语句接口**
161+
### 5.4 **SQL语句接口**
162162

163163
| api name | parameters | notes | use example |
164164
| ----------------------------- | ---------- | ------------------------------ | ------------------------------------------------------------ |
165165
| ExecuteQueryStatementAsync | string | execute sql query statement | session_pool.ExecuteQueryStatementAsync("select * from root.97209_TEST_CSHARP_CLIENT_GROUP.TEST_CSHARP_CLIENT_DEVICE where time<15"); |
166166
| 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") |
167167

168-
### 数据表接口
168+
### 5.5 数据表接口
169169

170170
| api name | parameters | notes | use example |
171171
| -------------------------- | ------------------------------------------------------------ | --------------------------- | ------------------------------------------------------------ |
@@ -178,7 +178,7 @@ var tablet =
178178
| DeleteTimeSeriesAsync | string | delete time series | |
179179
| DeleteDataAsync | List\<string\>, long, long | delete data | session_pool.DeleteDataAsync(ts_path_lst, 2, 3) |
180180

181-
### **辅助接口**
181+
### 5.6 **辅助接口**
182182

183183
| api name | parameters | notes | use example |
184184
| -------------------------- | ---------- | --------------------------- | ---------------------------------------------------- |
@@ -188,7 +188,7 @@ var tablet =
188188

189189
用法可以参考[用户示例](https://github.com/apache/iotdb-client-csharp/tree/main/samples/Apache.IoTDB.Samples)
190190

191-
## 连接池
191+
## 6 连接池
192192

193193
为了实现并发客户端请求，我们提供了针对原生接口的连接池(`SessionPool`)，由于`SessionPool`本身为`Session`的超集，当`SessionPool`的`pool_size`参数设置为1时，退化为原来的`Session`
194194

@@ -198,19 +198,19 @@ var tablet =
198198

199199
当一个连接被用完后，他会自动返回池中等待下次被使用
200200

201-
## ByteBuffer
201+
## 7 ByteBuffer
202202

203203
在传入RPC接口参数时，需要对Record和Tablet两种数据结构进行序列化，我们主要通过封装的ByteBuffer类实现
204204

205205
在封装字节序列的基础上，我们进行了内存预申请与内存倍增的优化，减少了序列化过程中内存的申请和释放，在一个拥有20000行的Tablet上进行序列化测试时，速度比起原生的数组动态增长具有**35倍的性能加速**
206206

207-
### 实现介绍
207+
### 7.1 实现介绍
208208
在进行`RowRecords`以及`Tablet`的插入时，我们需要对多行RowRecord和Tablet进行序列化以进行发送。客户端中的序列化实现主要依赖于ByteBuffer完成。接下来我们介绍ByteBuffer的实现细节。本文包含如下几点内容:
209209
- 序列化的协议
210210
- C#与Java的大小端的差异
211211
- ByteBuffer内存倍增算法
212212

213-
### 序列化协议
213+
### 7.2 序列化协议
214214
客户端向IoTDB服务器发送的序列化数据总体应该包含两个信息。
215215
- 数据类型
216216
- 数据本身
@@ -246,10 +246,10 @@ public enum TSDataType{BOOLEAN, INT32, INT64, FLOAT, DOUBLE, TEXT, NONE};
246246
限制：Tablet中数据不能有空值
247247
由于向 `IoTDB`服务器发送`Tablet`数据插入请求时会携带`行数`， `列数`, `列数据类型`，所以`Tabelt`序列化时我们不需要加入数据类型信息。`Tablet`是`按照列进行序列化`，这是因为后端可以通过行数得知出当前列的元素个数，同时根据列类型来对数据进行解析。
248248

249-
### CSharp与Java序列化数据时的大小端差异
249+
### 7.3 CSharp与Java序列化数据时的大小端差异
250250
由于Java序列化默认大端协议，而CSharp序列化默认得到小端序列。所以我们在CSharp中序列化数据之后，需要对数据进行反转这样后端才可以正常解析。同时当我们从后端获取到序列化的结果时(如`SessionDataset`)，我们也需要对获得的数据进行反转以解析内容。这其中特例便是字符串的序列化，CSharp中对字符串的序列化结果为大端序，所以序列化字符串或者接收到字符串序列化结果时，不需要反转序列结果。
251251

252-
### ByteBuffer内存倍增法
252+
### 7.4 ByteBuffer内存倍增法
253253
拥有数万行的Tablet的序列化结果可能有上百兆，为了能够高效的实现大`Tablet`的序列化，我们对ByteBuffer使用`内存倍增法`的策略来减少序列化过程中对于内存的申请和释放。即当当前的buffer的长度不足以放下序列化结果时，我们将当前buffer的内存`至少`扩增2倍。这极大的减少了内存的申请释放次数，加速了大Tablet的序列化速度。
254254
```csharp
255255
private void extend_buffer(int space_need){
@@ -266,7 +266,7 @@ private void extend_buffer(int space_need){
266266

267267
通过上述的策略，我们在一个有`20000`行的Tablet上进行测试时，序列化速度相比Naive数组长度动态生长实现算法具有约35倍的性能加速。
268268

269-
## 异常重连
269+
## 8 异常重连
270270

271271
当服务端发生异常或者宕机重启时，客户端中原来通过`Open()`产生的的session会失效，抛出`TException`异常
272272

‎src/zh/UserGuide/Master/Tree/API/Programming-Cpp-Native-API.md‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121

2222
# C++ 原生接口
2323

24-
## 依赖
24+
## 1 依赖
2525

2626
- Java 8+
2727
- Flex
@@ -31,9 +31,9 @@
3131
- GCC 5.5.0+
3232

3333

34-
## 安装
34+
## 2 安装
3535

36-
### 安装相关依赖
36+
### 2.1 安装相关依赖
3737

3838
- **MAC**
3939
1. 安装 Bison ：
@@ -94,7 +94,7 @@
9494
- 添加 OpenSSL 下的 include 目录到 PATH 环境变量中
9595

9696

97-
### 执行编译
97+
### 2.2 执行编译
9898

9999
从 git 克隆源代码:
100100
```shell
@@ -136,7 +136,7 @@ git checkout rc/1.3.2
136136

137137
编译成功后，打包好的库文件位于 `iotdb-client/client-cpp/target` 中，同时可以在 `example/client-cpp-example/target` 下找到编译好的示例程序。
138138

139-
### 编译 Q&A
139+
### 2.3 编译 Q&A
140140

141141
Q：Linux 上的环境有哪些要求呢？
142142

@@ -163,11 +163,11 @@ A:
163163
- 执行 `.\mvnw.cmd clean install`
164164
- 回到 iotdb 代码目录执行 `.\mvnw.cmd clean package -pl example/client-cpp-example -am -DskipTests -P with-cpp -Dcmake.generator="Visual Studio 15 2017"`
165165

166-
## 基本接口说明
166+
## 3 基本接口说明
167167

168168
下面将给出 Session 接口的简要介绍和原型定义：
169169

170-
### 初始化
170+
### 3.1 初始化
171171

172172
- 开启 Session
173173
```cpp
@@ -185,7 +185,7 @@ void open(bool enableRPCCompression);
185185
void close();
186186
```
187187

188-
### 数据定义接口（DDL）
188+
### 3.2 数据定义接口（DDL）
189189

190190
#### Database 管理
191191

@@ -309,7 +309,7 @@ std::vector<std::string> showMeasurementsInTemplate(const std::string &template_
309309
```
310310

311311

312-
### 数据操作接口（DML）
312+
### 3.3 数据操作接口（DML）
313313

314314
#### 数据写入
315315

@@ -391,7 +391,7 @@ void deleteData(const std::vector<std::string> &paths, int64_t endTime);
391391
void deleteData(const std::vector<std::string> &paths, int64_t startTime, int64_t endTime);
392392
```
393393

394-
### IoTDB-SQL 接口
394+
### 3.4 IoTDB-SQL 接口
395395

396396
- 执行查询语句
397397
```cpp
@@ -404,7 +404,7 @@ void executeNonQueryStatement(const std::string &sql);
404404
```
405405

406406

407-
## 示例代码
407+
## 4 示例代码
408408

409409
示例工程源代码：
410410

@@ -413,9 +413,9 @@ void executeNonQueryStatement(const std::string &sql);
413413

414414
编译成功后，示例代码工程位于 `example/client-cpp-example/target`
415415

416-
## FAQ
416+
## 5 FAQ
417417

418-
### Thrift 编译相关问题
418+
### 5.1 Thrift 编译相关问题
419419

420420
1. MAC：本地 Maven 编译 Thrift 时如出现以下链接的问题，可以尝试将 xcode-commandline 版本从 12 降低到 11.5
421421
https://stackoverflow.com/questions/63592445/ld-unsupported-tapi-file-type-tapi-tbd-in-yaml-file/65518087#65518087

‎src/zh/UserGuide/Master/Tree/API/Programming-Data-Subscription.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -181,13 +181,13 @@ public class DataConsumerExample {
181181

182182

183183

184-
## 2 全量接口说明
184+
## 3 全量接口说明
185185

186-
### 2.1 参数列表
186+
### 3.1 参数列表
187187

188188
可通过Properties参数对象设置消费者相关参数，具体参数如下。
189189

190-
#### 2.1.1 SubscriptionConsumer
190+
#### 3.1.1 SubscriptionConsumer
191191

192192

193193
| 参数 | 是否必填（默认值） | 参数含义 |
@@ -221,9 +221,9 @@ public class DataConsumerExample {
221221
| autoCommitInterval | optional: 5000 (min: 500) | Long: 自动提交消费进度的时间间隔，单位为**毫秒**仅当 autoCommit 参数为 true 的时候才会生效 |
222222

223223

224-
### 函数列表
224+
### 3.2 函数列表
225225

226-
#### 数据订阅
226+
#### 3.2.1 数据订阅
227227

228228
##### SubscriptionPullConsumer
229229

‎src/zh/UserGuide/Master/Tree/API/Programming-Go-Native-API.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121

2222
# Go 原生接口
2323

24-
## 依赖
24+
## 1 依赖
2525

2626
* golang >= 1.13
2727
* make >= 3.0
@@ -30,7 +30,7 @@
3030
* Linux、Macos 或其他类 unix 系统
3131
* Windows+bash (下载 IoTDB Go client 需要 git ，通过 WSL、cygwin、Git Bash 任意一种方式均可)
3232

33-
## 安装方法
33+
## 2 安装方法
3434

3535
* 通过 go mod
3636

‎src/zh/UserGuide/Master/Tree/API/Programming-JDBC.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -24,19 +24,19 @@
2424
*注意: 目前的JDBC实现仅是为与第三方工具连接使用的。使用JDBC（执行插入语句时）无法提供高性能写入。
2525
对于Java应用，我们推荐使用[Java 原生接口](./Programming-Java-Native-API.md)*
2626

27-
## 依赖
27+
## 1 依赖
2828

2929
* JDK >= 1.8
3030
* Maven >= 3.6
3131

32-
## 安装方法
32+
## 2 安装方法
3333

3434
在根目录下执行下面的命令：
3535
```shell
3636
mvn clean install -pl iotdb-client/jdbc -am -DskipTests
3737
```
3838

39-
### 在 MAVEN 中使用 IoTDB JDBC
39+
### 2.1 在 MAVEN 中使用 IoTDB JDBC
4040

4141
```xml
4242
<dependencies>
@@ -48,7 +48,7 @@ mvn clean install -pl iotdb-client/jdbc -am -DskipTests
4848
</dependencies>
4949
```
5050

51-
### 示例代码
51+
### 2.2 示例代码
5252

5353
本章提供了如何建立数据库连接、执行 SQL 和显示查询结果的示例。
5454

‎src/zh/UserGuide/Master/Tree/API/Programming-Java-Native-API.md‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -341,9 +341,9 @@ public class SessionPoolExample {
341341
}
342342
```
343343

344-
### 3 全量接口说明
344+
## 3 全量接口说明
345345

346-
#### 3.1 参数列表
346+
### 3.1 参数列表
347347

348348
Session具有如下的字段，可以通过构造函数或Session.Builder方式设置如下参数
349349

@@ -379,9 +379,9 @@ Session具有如下的字段，可以通过构造函数或Session.Builder方式
379379

380380

381381

382-
#### 3.2 接口列表
382+
### 3.2 接口列表
383383

384-
##### 3.2.1 元数据管理
384+
#### 3.2.1 元数据管理
385385

386386
| 方法名 | 功能描述 | 参数解释 |
387387
| ------------------------------------------------------------ | ------------------------ | ------------------------------------------------------------ |
@@ -410,7 +410,7 @@ Session具有如下的字段，可以通过构造函数或Session.Builder方式
410410
| `unsetSchemaTemplate(String prefixPath, String templateName)` | 取消路径的模板设置 | `prefixPath`: 路径，`templateName`: 模板名称 |
411411

412412

413-
##### 3.2.2 数据写入
413+
#### 3.2.2 数据写入
414414

415415
| 方法名 | 功能描述 | 参数解释 |
416416
| ------------------------------------------------------------ | ---------------------------------- | ------------------------------------------------------------ |
@@ -439,7 +439,7 @@ Session具有如下的字段，可以通过构造函数或Session.Builder方式
439439
| `insertAlignedTablets(Map<String, Tablet> tablets)` | 批量插入多个对齐Tablet数据 | `tablets`: 设备ID到Tablet的映射表 |
440440
| `insertAlignedTablets(Map<String, Tablet> tablets, boolean sorted)` | 批量插入排序的多个对齐Tablet数据 | 同上，增加 `sorted`: 数据是否已排序 |
441441

442-
##### 3.2.3 数据删除
442+
#### 3.2.3 数据删除
443443

444444
| 方法名 | 功能描述 | 参数解释 |
445445
| ------------------------------------------------------------ | ---------------------------- | ---------------------------------------- |
@@ -450,7 +450,7 @@ Session具有如下的字段，可以通过构造函数或Session.Builder方式
450450
| `deleteData(List<String> paths, long startTime, long endTime)` | 删除路径时间范围内的历史数据 | 同上，增加 `startTime`: 起始时间戳 |
451451

452452

453-
##### 3.2.4 数据查询
453+
#### 3.2.4 数据查询
454454

455455
| 方法名 | 功能描述 | 参数解释 |
456456
| ------------------------------------------------------------ | -------------------------------- | ------------------------------------------------------------ |
@@ -468,7 +468,7 @@ Session具有如下的字段，可以通过构造函数或Session.Builder方式
468468
| `executeAggregationQuery(List<String> paths, List<TAggregationType> aggregations, long startTime, long endTime, long interval, long slidingStep)` | 执行滑动窗口聚合查询 | 同上，增加 `slidingStep`: 滑动步长 |
469469
| `fetchAllConnections()` | 获取所有活动连接信息 | 无参数 |
470470

471-
##### 3.2.5 系统状态与备份
471+
#### 3.2.5 系统状态与备份
472472

473473
| 方法名 | 功能描述 | 参数解释 |
474474
| -------------------------- | ---------------------- | -------------------------------------- |

0 commit comments

Comments
 (0)