[GitHub] [incubator-iotdb] liutaohua commented on a change in pull request #575: Add CN document of TsFile

[GitBox <gi...@apache.org>]

liutaohua commented on a change in pull request #575: Add CN document of TsFile
URL: https://github.com/apache/incubator-iotdb/pull/575#discussion_r349089613
 
 

 ##########
 File path: docs/Documentation-CHN/UserGuide/8-System Design (Developer)/1-Hierarchy.md
 ##########
 @@ -21,4 +21,401 @@
 
 # 第8章: 系统设计
 
-Coming Soon.
\ No newline at end of file
+## 1. TsFile 设计
+
+  本章是关于 TsFile 的设计细节.
+
+### 1.1 变量的存储
+
+- **大端存储**
+  - 比如： `int` `0x8` 将会被存储为 `00 00 00 08`, 而不是 `08 00 00 00`
+- **可变长的字符串类型**
+  - 存储的方式是以一个 `int` 类型的 `Size` + 字符串组成。`Size` 的值可以为 0。
+  - `Size` 指的是字符串所占的字节数，它并不一定等于字符串的长度. 
+  - 举例来说，"sensor_1" 这个字符串将被存储为 `00 00 00 08` + "sensor_1" (ASCII编码)。
+  - 另外需要注意的一点是 "Magic String"（文件签名）"TsFile000001", 因为他的 `Size(12)` 和 ASCII 编码值是固定的，所以没有必要在这个字符串前的写入 `Size` 值。
+- **数据类型的编码**
+  - 0: BOOLEAN
+  - 1: INT32 (`int`)
+  - 2: INT64 (`long`)
+  - 3: FLOAT
+  - 4: DOUBLE
+  - 5: TEXT (`String`)
+- **编码类型的编码**
+  - 0: PLAIN
+  - 1: PLAIN_DICTIONARY
+  - 2: RLE
+  - 3: DIFF
+  - 4: TS_2DIFF
+  - 5: BITMAP
+  - 6: GORILLA
+  - 7: REGULAR 
+- **压缩类型的编码**
+  - 0: UNCOMPRESSED
+  - 1: SNAPPY
+  - 2: GZIP
+  - 3: LZO
+  - 4: SDT
+  - 5: PAA
+  - 6: PLA
+- **TsDigest 统计类型的编码**
+  - 0: min_value
+  - 1: max_value
+  - 2: first_value
+  - 3: last_value
+  - 4: sum_value
+
+### 1.2 TsFile 概述
+
+下图是关于TsFile的结构图。
+
+![TsFile Breakdown](https://user-images.githubusercontent.com/40447846/61616997-6fad1300-ac9c-11e9-9c17-46785ebfbc88.png)
+
+#### 1.2.1 文件签名和版本号
+
+TsFile 是由 6 个字节的 "Magic String" (`TsFile`) 和 6 个字节的版本号 (`000001`)组成.
+
+
+#### 1.2.2 数据文件
+
+TsFile文件的内容可以划分为两个部分: 数据和元数据。数据和元数据之间是由一个字节的 `0x02` 做为分隔符。
+
+`ChunkGroup` 存储的是一个数组类型的数据，每一个 `ChunkGroup` 代表了一个 *设备(device)*.
+
+##### ChunkGroup
+
+`ChunkGroup` 包含一个数组(array)类型的 `Chunk` 和 `ChunkFooter`, 其中每个 `Chunk` 之间使用一个字节的 `0x00` 做为分隔符。
+
+##### Chunk
+
+一个 `Chunk` 代表了一个 *sensor* , 即传感器.在 `ChunkHeader` 和后面数组类型的 `Page` 之间使用一个字节的 `0x01` 做为分隔符。
+
+##### ChunkHeader
+
+|成员|类型|
+|:---:|:---:|
+|传感器名称(measurementID)|String|
+|chunk大小(dataSize)|int|
+|chunk的数据类型(dataType)|short|
+|包含的page数量(numOfPages)|int|
+|压缩类型(compressionType)|short|
+|编码类型(encodingType)|short|
+|Max Tombstone Time|long|
+
+##### Page
+
+一个 `Page` 页存储了 `Chunk` 的一些数据. 它包含一个 `PageHeader` 和实际的数据(time-value 编码的键值对)。
+
+PageHeader 结构
+
+|成员|类型|
+|:---:|:---:|
+|压缩前数据大小(uncompressedSize)|int|
+|SNAPPY压缩后数据大小(compressedSize)|int|
+|包含的values的数量(numOfValues)|int|
+|最大时间戳(maxTimestamp)|long|
+|最小时间戳(minTimestamp)|long|
+|该页最大值(max)|Type of the page|
+|该页最小值(min)|Type of the page|
+|该页第一个值(first)|Type of the page|
+|该页值的和(sum)|double|
+|该页最后一个值(last)|Type of the page|
+
+##### ChunkGroupFooter
+
+|成员|类型|
+|:---:|:---:|
+|设备Id(deviceID)|String|
+|ChunkGroup大小(dataSize)|long|
+|包含的chunks的数量(numberOfChunks)|int|
+
+#### 1.2.3  元数据
+
+##### 1.2.3.1 TsDeviceMetaData
+
+第一部分的元数据是 `TsDeviceMetaData` 
+
+|成员|类型|
+|:---:|:---:|
+|开始时间(startTime)|long|
+|结束时间(endTime)|long|
+|包含的ChunkGroup的数量|int|
+|所有的ChunkGroupMetaData(chunkGroupMetadataList)|list|
+
+###### ChunkGroupMetaData
+
+|成员|类型|
+|:---:|:---:|
+|设备Id(deviceID)|String|
+|在文件中ChunkGroup开始的偏移量(startOffsetOfChunkGroup)|long|
+|在文件中ChunkGroup结束的偏移量(endOffsetOfChunkGroup)|long|
+|版本(version)|long|
+|包含的ChunkMetaData的数量|int|
+|所有的ChunkMetaData(chunkMetaDataList)|list|
+
+###### ChunkMetaData
+
+|成员|类型|
+|:---:|:---:|
+|传感器名称(measurementUid)|String|
+|文件中ChunkHeader开始的偏移量(offsetOfChunkHeader)|long|
+|数据的总数(numOfPoints)|long|
+|开始时间(startTime)|long|
+|结束时间(endTime)|long|
+|数据类型(tsDataType)|short|
+|版本(version)|long|
 
 Review comment:
   that not serialize to disk

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services