TSDB 存储引擎详解

• block：参见 确定索引键值部分的说明。
• Level File：参见 Level File 部分的说明。
• unsorted buffer / sorted buffer：参见写入流程部分的说明。
• sortColumns：sortColumns 的介绍。
• sortKey：参见 确定索引键值 部分的说明。

TSDB 引擎是 DolphinDB 基于 Log Structured Merge Tree (以下简称 LSM-Tree) 自研的存储引擎。

LSM-Tree 是一种分层、有序、面向磁盘的数据结构，主要用于处理写入密集型的工作负载，如日志系统、实时分析系统和数据库等。其实现的核心思想是利用磁盘批量顺序写入大幅提高写入性能。其工作流程图如下所示：

• LSM-Tree 的数据写入流程：

  1. 数据先写入 WAL Log（Write-Ahead Logging）用于故障恢复。
  2. 完成 WAL Log 写入后，数据会先存储在内存中的一个有序数据结构中（通常称为“内存表”），可以是一个红黑树结构或者 Skip List。当内存表缓存到一定大小后，会将其冻结（immutable）等待刷盘，然后生成一个新的内存表供之后的写事务写入。
  3. 将冻结的内存表写入磁盘的 SSTable（Sorted Strings Table）文件中，SSTable 是一种有序且不可变的数据文件，其内部的数据按照键值进行排序。（HINT：SSTable 即对应 DolphinDB 的 Level File 文件）。
  4. LSM-Tree 通常维护多个层级的 SSTable 文件，越旧的数据会存储在磁盘上越高的层级，且 SSTable 文件大小也会逐级递增。刚写入的 SSTable 文件存储在磁盘的 Level 0 层级，当单层的文件数过多或文件大小过大，系统会将多个 SSTable 文件合并成一个更大的文件，并在合并时进行去重操作，以保证数据的有序性。通过合并操作，可以提高查询性能，减少存储占用。但注意，合并操作会造成一定程度的写放大。

• LSM-Tree 的数据查询流程：

  1. 首先在内存表进行检索，由于内存表是有序的数据结构，因此可以利用算法快速检索并返回结果。
  2. 如果在内存表中找不到数据，则会按层级遍历磁盘上的 SSTable 进行检索，由于 SSTable 文件数据是按键值排序的，因此可以在单个 SSTable 内快速进行范围查询。为了提高 SSTable 遍历的效率，可以给 SSTable 增加 Bloom Filter，以减少不必要的磁盘扫描。
  3. 查询时，SSTable 可能会包含多个不同历史版本的数据，此时需要根据查询条件，找到符合版本的数据（例如最新一条数据）。

  注： 最坏的情况下，需要将所有层级的 SSTable 文件都遍历一遍，如果 SSTable 文件过多，查询是非常低效的，因此可以理解为什么 LSM-Tree 要引入合并机制，减小 SSTable 的文件数。

相较于传统的 B+ 树而言，LSM-Tree 的优势在于高吞吐写入与较低的随机写延迟，这非常契合 DolphinDB 海量数据高性能写入的设计诉求。虽然没有 B+ 树那样高效的随机读和范围查询性能，LSM-Tree 依靠键值排序使得单个 SSTable 文件的范围查询也十分高效。

参考资料： Principle of LSM Tree

DolphinDB 的 TSDB 引擎是基于 LSM-Tree 架构进行开发的，因此大部分内部的流程机制也和 LSM-Tree 类似，但在某些步骤进行了优化：

• 写入： 与 LSM-Tree 直接写入一个有序的数据结构不同，DolphinDB TSDB 引擎在写入数据到内存时，会先按写入顺序存储在一个写缓冲区域（unsorted write Buffer），当数据量累积到一定程度，再进行排序转化为一个 sorted buffer。

• 查询： DolphinDB TSDB 引擎会预先遍历 Level File（对应 LSM-Tree 的 SSTable 文件），读取查询涉及的分区下所有 Level File 尾部的索引信息到内存的索引区域（一次性读，常驻内存）。后续查询时，系统会先查询内存中的索引，若命中，则可以快速定位到对应 Level File 的数据块，无需再遍历磁盘上的文件。

  
  

本节将具体介绍 DolphinDB TSDB 引擎的增删改查（CRUD）流程。

sortColumns 参数在 TSDB 引擎中起到三个作用：确定索引键值、数据排序、数据去重。

TSDB 引擎存储的数据文件在 DolphinDB 中被称为 Level File（对应 LSM-Tree 的 SSTable 文件），即 LSMTree 架构各 Level 层级的文件。Level File 主要保存了数据和索引信息，其中索引信息保存在 Level File 的尾部。为了更好地理解 Level File 在整个系统中发挥的作用，本节将对 Level File 进行一个简单介绍。

在使用 TSDB 引擎前，可以按需调整系统的配置项（TSDB 引擎相关的配置项一览表见TSDB 引擎配置项汇总），以充分发挥系统的性能。本节主要介绍其中几个重点参数：

• TSDBRedoLogDir：为了提高写入效率，建议将 TSDB redo log 配置在 SSD 盘。
• TSDBCacheEngineSize：默认是 1G，写入压力较大的场景可以适当调大该值。
  • 若设置过小，可能导致 cache engine 频繁刷盘，影响系统性能；
  • 若设置过大，由于 cache engine 内缓存的数据量很大，但由于未达到 cache engine 的大小（且未达到十分钟），因此数据尚未刷盘，此时若发生了机器断电或关机，重启后就需要回放大量事务，导致系统启动过慢。
• TSDBLevelFileIndexCacheSize：默认是 5% * maxMemSize，该配置项确定了索引数据（Level File indexes 和 zonemap）的上限，若配置过小，会造成索引频繁置换。在索引部分，较占内存空间的是 zonemap 部分，用户可以根据“分区数量 × sortKey 数量 × （4 × Σ各字段字节数）”进行估算（其中 4 表示 4 种预聚合指标 min，max，sum，notnullcount）。
• TSDBAsyncSortingWorkerNum：非负整数，默认值为 1，用于指定 TSDB cache engine 异步排序的工作线程数。在 CPU 资源充足的情况下，可以适当增大该值，以提高写入性能。
• TSDBCacheFlushWorkNum：TSDB cache engine 刷盘的工作线程数，默认值是 volumes 指定的磁盘卷数。若配置值小于磁盘卷数，则仍取默认值。通常无需修改此配置。

下述脚本以创建一个组合分区的数据库为例，和 OLAP 引擎创库时的区别仅在于 engine 设置不同：

db1 = database(, VALUE, 2020.01.01..2021.01.01)
db2 = database(, HASH, [SYMBOL, 100])
db = database(directory=dbName, partitionType=COMPO, partitionScheme=[db1, db2], engine="TSDB")

• 库表对应关系： 设计分布式数据库时，若存储的是分布式表，推荐一库一表，因为对于不同的表按照同一分区方案进行分区，可能造成每个分区的数据量不合理；若存储的是维度表，推荐一库多表，集中管理，因为维度表只有一个分区，且一次加载常驻内存。

• 分区设计：

  • TSDB 引擎单个分区推荐大小：400MB - 1GB（压缩前）

    分布式查询按照分区加载数据进行并行计算（包括查询、删除、修改等操作），若分区粒度过大，可能会造成内存不足、查询并行度降低、更新删除效率降低等问题；若分区粒度过小，可能会产生大量子任务增加节点负荷、大量小文件独写增加系统负荷、控制节点元数据爆炸等问题。

  • 分区设计步骤：

    1. 以推荐大小作为参照，先根据表中的记录数和每个字段的大小估算数据量，再根据分区方案计算的分区数（如天 + 股票 HASH10 的组合分区，可以按天数 * 10），通过数据量/分区数计算得到每个分区的大小。
    2. 若分区粒度不合理，调整分区粒度可以参考以下方案：
       • 粒度过小：若采用了值分区可以考虑改成范围分区，例如按天改成按月；若采用了 HASH 分区，可以考虑改小 HASH 分区数。
       • 粒度过大：若采用了范围分区可以考虑改成值分区，例如按年改成按月；若采用了 HASH 分区，可以考虑改大 HASH 分区数；若是一级分区，可以考虑用组合分区，此时新增一级通常是 HASH 分区，例按天单分区，粒度过大，考虑二级按股票代码 HASH 分区。

合理设置分区至关重要，如需了解详细的分区机制和如何设计合理的分区，可参见数据库分区

• 是否允许并发写入同一分区：

  此外，为了支持用户多线程能够并发写数据且不会因写入分区冲突而失败，DolphinDB 在创建数据库时支持了一个特殊的配置参数 atomic（该参数是 OLAP 和 TSDB 引擎共有参数）：

  • 默认为‘TRANS'，即不允许并发写入同一个 CHUNK 分区；
  • 设置为‘CHUNK'，则允许多线程并发写入同一分区。系统内部仍会串行执行写入任务，当一个线程正在写入某个分区时，其他写入该分区的线程检测到冲突会不断尝试重新写入。尝试 250 次（每次尝试间隔时间会随着尝试次数增加而增加，上限是 1s，整个尝试过程约持续 5 分钟）后仍然无法写入，则会写入失败。atomic='CHUNK' 配置可能会破坏事务的原子性，因为若某线程冲突重试达到上限后仍失败，则该部分数据将会丢失，需要谨慎设置。

实际场景下，若设置为 'CHUNK' 发生数据丢失，用户可能难以定位到具体的分区，针对该场景有几个较推荐的方案：

1. 使用 tableInsert 写入，该函数会返回写入数据的记录数，根据记录数可以定位到写入失败的线程任务，若线程涉及的分区没有重叠，可以删除相关分区数据后重新写入。
2. 若使用 TSDB 引擎，且去重策略设置为了 FIRST 或者 LAST，则直接重复提交写入失败的线程任务，系统会进行去重，查询时不会读出重复数据。不适用于去重策略为 ALL 的场景，若为 ALL，则参照方案 1。

创建分布式表/维度表时，与 OLAP 引擎不同，TSDB 需要额外设置 sortColumns 这个必选参数，以及 keepDuplicates, sortKeyMappingFunction, softDelete 这几个可选参数。

// 函数
createPartitionedTable(dbHandle, table, tableName, [partitionColumns], [compressMethods], [sortColumns], [keepDuplicates=ALL], [sortKeyMappingFunction], [softDelete=false])

// 标准 SQL
create table dbPath.tableName (
    schema[columnDescription]
)
[partitioned by partitionColumns],
[sortColumns],
[keepDuplicates=ALL],
[sortKeyMappingFunction]

这里以通过函数创建一个 TSDB 下的分布式表为例：

colName = `SecurityID`TradeDate`TradeTime`TradePrice`TradeQty`TradeAmount`BuyNo`SellNo
colType = `SYMBOL`DATE`TIME`DOUBLE`INT`DOUBLE`INT`INT
tbSchema = table(1:0, colName, colType)
db.createPartitionedTable(table=tbSchema, tableName=tbName, partitionColumns=`TradeDate`SecurityID, compressMethods={TradeTime:"delta"}, sortColumns=`SecurityID`TradeDate`TradeTime, keepDuplicates=ALL)

• 对字段应用合适的压缩算法（compressMethods）：

  • 对重复较高的字符串，使用 SYMBOL 类型存储。需要注意单个分区下 SYMBOL 字段的唯一值数不能超过 2^21(2097152) 个，否则会抛异常，见 S00003 。
  • 对时序数据或顺序数据（整型）可以使用 delta 算法存储，压缩性能测试可以参考 物联网应用范例 。
  • 其余默认 lz4 压缩算法。

• 合理设置排序字段（sortColumns）：

  • 确保一个分区的 sortKey 的组合数小于 1000。

    通常金融场景下会以 SecurityID+ 时间戳的组合、物联网场景下会以 deviceID+ 时间戳的组合来作为 sortColumns。 在 Level File 章节提及，Level File 的每个 sortKey 都对应存储了许多索引信息，因此在数据量固定的情况下，如果 sortKey 的数量过多，元数据也会变多。极端场景下，数据库可能会膨胀 50 倍！因此不推荐把主键或唯一约束设置为 sortColumns。

  • 建议把查询频率高的字段作为 sortColumns 中的前置列。

    索引键值是 sortKey 的组合值，查询时，如果过滤条件中包含 sortKey 字段，即可以快速定位索引，从而快速定位到数据块 block 加速查询。

    因为索引键在内存中是按照其组合值排序的，如果将频繁查询的字段前置，则若查询语句中包含前置的字段，则定位索引时可以通过二分查找进行加速，否则系统会对内存中的索引进行遍历。

  • 如果 sortColumns 只有一列，该列将作为 sortKey，块内数据是无序的。 因此，对于每个 sortKey 需要遍历内部的每一个 block；如果 sortColumns 有多列，则除最后一列外的作为索引列 sortKey，最后一列必须是时间列，block 内部按时间排序，如果查询条件指定了时间列，可以无需对每个 sortKey 下的 block 进行遍历。

  • 类型限制：sortColumns 只支持 integer, temporal, string 或 symbol 类型；sortKey 不能为为 TIME, TIMESTAMP, NANOTIME, NANOTIMESTAMP 类型。

• 索引降维（sortKeyMappingFunction）：

  如果单纯的依靠合理配置 sortColumns 仍然不能降低每个分区的 sortKey 数量，则可以通过指定该参数进行降维。

  例如： 5000 只股票，按照日期分区，设置股票代码和时间戳为 sortColumns，每个分区 sortKey 组合数约为 5000，不满足每个分区 sortKey 组合数不超过 1000 的原则，则可以通过指定 sortKeyMappingFunction=[hashBucket{, 500}] 进行降维，使每个分区的 sortKey 组合数降为 500。

  • 降维是对每个 sortKey 的字段进行的，因此有几个 sortKey 字段就需要指定几个降维函数。
  • 常用的降维函数是 hashBucket，即进行哈希映射。
  • 降维后可以通过 getTSDBSortKeyEntry 查询每个分区的 sortKey 信息。

• 数据去重（keepDuplicates）：

  • 对 同一个时间点产生多条数据，需要去重的场景， 可以根据业务需要设置 keepDuplicates=FIRST/LAST，分别对应每个 sortColumns 保留第一条还是最后一条数据。
  • 若对去重策略没有要求，则可以根据以下需求进行评估，以设置去重策略：
    • 高频更新：建议指定 keepDuplicates=LAST，因为 LAST 采用追加更新的方式效率更高（见更新流程）。
    • 查询性能：较推荐使用 keepDuplicates=ALL，因为其他去重策略查询时有额外的去重开销。
    • atomic=CHUNK：推荐使用 keepDuplicates=FIRST/LAST，若并发写入失败，直接重复写入即可，无需删除数据再写。

推荐每个分区的 sortKey 组合数不要超过 1000。

测试场景

本节以一个极端场景为例，只利用 sortColumns 去重的特性，将其作为主键或唯一约束使用，每个 sortKey 只对应很少的数据。

数据表结构

宽表存储，包含 100 个指标值。

分区方案

写入 5 日数据，每日 50 万条数据（约 400M），总数据量为 1.9 G。

• 分区方案：单分区，按天 VALUE 分区。
• 排序列 sortColumns：ID，tradeDate，TradeTime。其中 ID 和 tradeDate 的组合值将作为 sortKey。
• 去重规则 keepDuplicates：LAST，对于重复数据只保存最新的一条。

测试指标

实验分析

当每个 sortKey 对应很少的数据量的时候，会产生以下几个问题：

• 由于数据总量不变，导致 sortKey 非常多，索引信息占据大量内存。
• 数据碎片化存储，导致数据读写效率降低。
• 由于数据按照 block 进行压缩，而 block 是每个 sortKey 对应数据按照数据量进行划分的，若每个 block 数据量很少，压缩率也会降低。

若要对上述场景进行优化，可通过设置 sortKeyMappingFunction 对 sortKey 字段进行降维处理。该场景下，我们对 ID 字段进行降维，降维函数为 hashBucket{,500}，该函数用于将每个分区的 sortKey 数量降为 500：

db.createPartitionedTable(table=tbSchema,tableName=tbName,partitionColumns=`tradeDate,sortColumns=`ID`tradeDate`TradeTime,keepDuplicates=LAST, sortKeyMappingFunction=[hashBucket{,500},])

可以看到降维后，实际落盘大小和查询性能都有显著提升。

测试场景

不同去重策略下，Level File 合并前后对查询耗时的影响。

数据表结构

分区方案

每日写入 100,000,000 条数据（约 3800 M，包含 100000 个设备），通过脚本写入 10 天的数据量。

• 分区方案：组合分区，按 datetime（VALUE）+ machineId（HASH 100）分区。每个分区约 400 M 数据。
• 排序列 sortColumns：machineId，datetime。machineId 将作为 sortKey。
• 去重规则 keepDuplicates：建表时，通过 keepDuplicates 参数配置不同的去重策略，进行测试。

实际场景下，重复数据一般是由设备或通讯协议的机制产生的。一般数据重复率在 5% 左右。本实验模拟物联网场景下的数据产生，数据量也较贴合现实场景的数据重复率。

测试指标

• 进行点查（命中 sortKey）

  select * from loadTable(dbName, tbName_all) where machineId=999

  keepDuplicates	数据量	合并前耗时（ms）	合并后耗时（ms）
  ALL	9,812	32.2	28.5
  FIRST	9,541	27.7	26.7
  LAST	9,507	29.7	26.3

  select * from loadTable(dbName, tbName_all) where machineId=999 and datetime=2023.07.10

  keepDuplicates	数据量	合并前耗时（ms）	合并后耗时（ms）
  ALL	1,054	8.7	8.2
  FIRST	916	7.6	6.6
  LAST	968	8.1	6.8

  select * from loadTable(dbName, tbName_all) where machineId=999 and datetime=2023.07.10 and datetime between 2023.07.10 09:00:01.000 and 2023.07.10 09:00:03.000

  keepDuplicates	数据量	合并前耗时（ms）	合并后耗时（ms）
  ALL	202	6.2	6.1
  FIRST	201	5.8	5.8
  LAST	197	5.8	5.8

• 查询单个分区所有记录

  select * from loadTable(dbName, tbName_all) where datetime=2023.07.10

  keepDuplicates	数据量	合并前耗时（ms）	合并后耗时（ms）
  ALL	100,000,000	59,566.7	47,474.3
  FIRST	95,161,440	54,275.1	46,069.2
  LAST	95,161,940	57,954.2	44,443.1

• 查询全表的总记录数（命中元数据）

  select count(*) from loadTable(dbName, tbName)

  keepDuplicates	数据量	合并前耗时（ms）	合并后耗时（ms）
  ALL	1,000,000,000	218.9	216.8
  FIRST	951,623,687	6,324.1	1,180.9
  LAST	951,624,331	6,470.2	958.7

实验分析

（一） 对比 Level File 合并前后，每个查询语句性能的区别：

• 在不去重的场景下（keepDuplicates=ALL），整体提升不显著，但在遍历整个分区数据时，由于文件数据减少，查询性能提升约 20 %。
• 在去重的场景下（keepDuplicates=LAST / FIRST）：
  • 命中 sortKey 的查询语句：性能几乎不受 Level File 文件合并的影响。
  • 遍历分区的查询语句：性能在合并后会略所提升，约为 15 % 左右。
  • 命中元数据的查询语句：性能在合并前后提升较为显著，约提升 6 倍。

从内部机制分析，合并 Level File 对性能的影响主要在：

• 由于文件数减少，磁盘的寻道时间减少。但在查询数量大的场景下，磁盘的寻道时间可以忽略。
• 合并后重复数据减少，从而使数据去重的耗时也减少。
• 合并后文件数减少，从而使查询遍历的开销也减少。

Level File 的去重操作是在合并阶段完成的。若磁盘上存在较多的重复数据，查询时，会将这些数据全部读取到内存再进行去重。冗余的重复数据越多，这一步骤的耗时开销越显著。

（二） 对比使用三种不同的去重策略时，每个查询语句性能的区别：

• 命中 sortKey 的查询语句：三种去重策略性查询性能相差不大。
• 遍历分区的查询语句：ALL 策略的查询性能会略低于 FIRST 和 LAST 策略，主要是因为 ALL 策略无需去重，FIRST 和 LAST 都有一定的去重开销。
• 命中元数据的查询语句：ALL 的性能明显优于 FIRST 和 LAST（ALL 性能约为 FIRST/LAST 的 30 倍），这是因为 ALL 只需要读元数据即可，FIRST，ALL 需要对数据去重后进行统计，开销较大。

不同的查询策略对性能的影响主要在：

• ALL 策略文件数较 FIRST 和 LAST 策略多，理论上磁盘寻道时间应该更长，但在查询数量大的场景下，磁盘的寻道时间可以忽略。
• ALL 策略在查询时无需去重，而 FIRST 和 LAST 策略在查询时，需要读出所有满足查询条件的数据，然后在内存中进行去重操作，这一步较为耗时。

实验结论

在 Level File 文件数较多的场景下，若数据存在重复并设置了去重策略，则 Level File 文件合并后，遍历分区和命中元数据的查询语句性能会显著提升，点查性能提升不明显；若数据重复率低，或者未设置去重机制，则文件合并前后，查询性能提升较小。

参考 Level File 合并章节，DolphinDB TSDB 引擎内置了 Level File 的自动合并机制，依靠自动合并，大部分场景下 Level File 数量不会成为查询性能的瓶颈。

若自动合并后，Level File 数量仍比较多，且满足下述场景：

• 数据重复率较高
• 数据已经入库，不再变化（后续不再修改和写入）

用户也可以在线调用函数 triggerTSDBCompaction 手动触发合并，以减少文件数，提升查询性能。合并状态可以通过调用函数 getTSDBCompactionTaskStatus 进行查询。

触发集群中所有分区 Level File 合并脚本参考：

// dbName 需要替换成自己的数据库名
chunkIDs = exec * from pnodeRun(getChunksMeta{"/dbName/%"}) where type=1
for(chunkID in chunkIDs){
    pnodeRun(triggerTSDBCompaction{chunkID})
}
// 检查是否完成 Level File 合并
select * from pnodeRun(getTSDBCompactionTaskStatus) where endTime is null

• test_5_._1.dos
• test_5_._2.dos