# <center>LevelDB设计文档 </center>
<center>王雪飞，马也驰 </center>

## 1.项目概述及目标
### 1.1 项目概述
本项目的背景是提升 LevelDB 在高写入负载场景下的性能。LevelDB 是一种轻量级的键值存储引擎，但在数据频繁更新或大值（Large Values）存储场景下，由于数据写入和合并（Compaction）过程的设计，其性能可能受到显著影响。为解决这一问题，项目目标是实现 KV（Key-Value）分离机制，以降低写放大现象并提高存储效率。

具体实现内容包括在 LevelDB 内部引入 KV 分离功能，即将键（Key）与值（Value）存储到不同的存储介质中。通过修改 SSTable 的结构设计，将键与指向值的指针存储在原有的文件中，而将实际值存储到单独的文件或存储介质中，从而减少 Compaction 操作对大值的处理负担。此外，项目还优化了数据访问逻辑，实现了值文件的高效读写支持。

该功能的应用场景主要包括：

1. 适用于大值写入频繁的场景，如日志存储、视频元数据管理等。
2. 提升 SSD 等固态存储设备的寿命，减少写入放大带来的磨损。
3. 在混合存储架构中，提高冷热数据分离的效率。

### 1.2 项目目标

本项目涵盖下面三个方面：
1. 实验一：在 LevelDB 的 value 中实现字段功能。
2. 实验二：实现 KV 分离。
3. 实验三：实现 Benchmark,测试并分析性能。

## 2. 实验内容
### 2.1 在 LevelDB 的 value 中实现字段功能
具体指：基于 levelDB扩展 value 的结构，使其可以包含多个字段，并通过这些字段实现类似数据库列查询的功能。

#### 2.1.1 实验要求：
字段存储：
1. 将 LevelDB 中的 value 组织成字段数组，每个数组元素对应一个字段（字段名：字段值）。
2. 字段会被序列化为字符串，然后插入LevelDB。
3. 这些字段可以通过解析字符串得到，字段名与字段值都是字符串类型。
4. 允许任意调整字段。

查询功能：
实现通过字段值查询对应的 key。

#### 2.1.2 实验内容
1. 数据存储与解析: 每个 value 存储为一个字符串数组，数组中的每个元素代表一个字段。
2. 通过字段查询 Key: 实现函数FindKeysByField，传入字段名和字段的值就可以找到对应的key

**设计思路：**
1. 使用 Field 存储属性和值，使用 FieldArray 存储多个 Field;
2. 函数 SerializeValue 把字段数组序列化为字符串;
3. 函数 ParseValue 把字符串反序列化为字段数组;
4. 函数 FindKeysByField 根据传入的字段名和字段的值找到对应的key。
### 2.1.3 实验进度以及实验结果
#### 实验进度
已初步实现上述四个函数，后续会对查询函数 FindKeysByField 进行优化和完善，并将上述函数添加到 LevelDB 的代码之中。
#### 实验结果
通过测试

#### 2.2 KV分离
**设计目标：**
将value的存储和key在lsm tree中的存储分离，降低lsm tree的GC开销

**设计思路：**
1. value的分离式存储
   我们使用若干个vlog文件，为每一个vlog文件设置容量上限（比如16MiB），并在内存中为每一个vlog维护一个discard计数器，表示这个vlog中当前有多少value已经在lsm tree中被标记为删除。
2. 存储value所在vlog和偏移量的元数据
   我们在key和vlog中添加一个slot_page的中间层，这一层存储每一个key对应的value所在的vlog文件和文件内偏移，而lsm tree中的key包含的实际上是这个中间层的slot下标，而每一个slot中存储的是key所对应的vlog文件号以及value在vlog中的偏移。这样，我们就可以在不修改lsm tree的基础上，完成对vlog的compaction，并将vlog的gc结果只反映在这个中间层slot_page中。这个slot_page实际上也是一个线性增长的log文件，作用类似于os中的页表，负责维护lsm tree中存储的slot下标到vlog和vlog内偏移量的一个映射。这样，通过slot_page我们就可以找到具体的vlog文件和其文件内偏移量。对于vlog的GC过程，我们不需要修改lsm tree中的内容，我们只需要修改slot_page中的映射即可。
3. slot_page文件和vlog文件的GC
   对于vlog文件，我们在内存中维护一个bitmap，用来表示每一个slot的使用情况，并在插入和GC删除kv时进行动态的分配和释放。对于vlog文件的GC，我们用一个后台线程来扫描所有vlog的discard计数器。当某些vlog的discard计数器超过某个阈值（比如1024），我们就对这些vlog文件进行GC过程，当GC完成之后将slot_page中的slot元数据进行更新，再将原来的vlog文件进行删除，GC过程就完成了。



### 3. 数据结构设计
`key的格式：| key | slot_num | `

`slot_page: | slot0:{vlog_no(定长), offset(定长)}, slot1:{vlog_no, offset}, ... | `

`value 的格式：| attr个数(定长) | attr1_name的长度(定长) | attr1_name(变长) | attr1_value的长度(定长) | attr1_value(变长) | ... |`

对于每一次读取，用户线程先读取lsm tree中key的slot_num下标，然后到slot_page中读取对应的slot内容(**每一个slot都是定长的**)，之后再在这个slot中读取value所在的vlog文件号和偏移量offset，之后到对应的vlog文件中读取value。

但是这又带来了一个问题，我们该如何管理slot_page这个文件？当插入新的kv时，我们需要在这个slot_page中分配新的slot，在GC删除某个kv时，我们需要将对应的slot进行释放。这里我们选择在内存中维护一个可线性扩展的bitmap。这个bitmap中每一个bit标识了当前slot_page文件中对应slot是否被使用，是为1，不是为0。这样一来，在插入新kv时，我们可以用bitmap来分配一个新的slot（将bitmap中第一个为0的bit设置为1），将内容进行写入；在GC删除某个kv时，我们将这个slot对应的bitmap中的bit重置为0即可。


### 4. 接口设计
#### 4.1 在 LevelDB 的 value 中实现字段功能
1. std::string SerializeValue(const FieldArray& fields)

**功能：** 将字段数组序列化为字符串

**输入：** 字段名和字段的值组成的字段数组

**输出：** 序列化后的字符串

2. FieldArray ParseValue(const std::string& value_str)

**功能：** 将字符串反序列化为字段数组

**输入：** 字符串

**输出：** 反序列化的字段数组

3. std::vector< std::string >FindKeysByField(leveldb::DB* db, Field &field)

**功能：** 根据字段名和字段的值找到对应的key

**输入：** 数据库名，字段名和字段的值

**输出：** 包含该字段和字段数组的 key,由于可能不只有一个，所以返回值为 vector

4. Put_Fields (待实现)

**功能：** 仿照Status DB::Put(const WriteOptions& opt, const Slice& key, const Slice& value)，通过调用序列化函数，实现以字段形式插入 value

**输入：** 数据库名，字段名和字段的值

**输出：** 包含该字段和字段数组的 key,由于可能不只有一个，所以返回值为 vector

5. Get_Fields (待实现) 
#### 4.2 实现KV分离
这里只展示和vlog以及GC无关的接口，vlog的创建，管理以及后台线程的GC设计到vlog等新数据结构的实现，较为复杂和庞大，这里不做展示。我们只列出与kv的插入有关的新接口：
1. 搜索slot_page文件: Status find_slot(const Slice& key, Slot *slot);
2. 搜索vlog文件: Status find_value(Slot *slot);
3. 分配新的slot: Status allocate_slot(Bitmap *map, uint64_t *s);
4. 释放slot: void deallocate_slot(Bitmap *map, uint64_t *s);



### 5. 功能测试
### 5.1 在 LevelDB 的 value 中实现字段功能
#### 5.1.1 功能测试
1. 能否以字段形式插入并读取数据
2. 能否以通过字段值查询对应的 key
````
Status OpenDB(std::string dbName, DB **db) {
  Options options;
  options.create_if_missing = true;
  return DB::Open(options, dbName, db);
}

TEST(TestSchema, Basic) {
  DB *db;
  WriteOptions writeOptions;
  ReadOptions readOptions;
  if(OpenDB("testdb", &db).ok() == false) {
    std::cerr << "open db failed" << std::endl;
    abort();
  }
  std::string key1 = "k_1";
  std::string key2 = "k_2";
  FieldArray fields1 = {
      {"name", "Customer1"},
      {"address", "IVhzIApeRb"},
      {"phone", "25-989-741-2988"}
  };

  FieldArray fields2 = {
      {"name", "Customer1"},
      {"address", "ecnu"},
      {"phone", "123456789"}
  };
  FieldArray fields3 = {
      {"name", "Customer2"},
      {"address", "ecnu"},
      {"phone", "111111111"}
  };
  // 序列化并插入
  std::string value1 = SerializeValue(fields1);
  std::string value2 = SerializeValue(fields2);
  std::string value3 = SerializeValue(fields3);
  db->Put(leveldb::WriteOptions(), key1, value1);
  db->Put(leveldb::WriteOptions(), key2, value2);
  db->Put(leveldb::WriteOptions(), key2, value3);

  // 读取并反序列化
  std::string value_ret;
  db->Get(leveldb::ReadOptions(), key1, &value_ret);
  auto fields_ret = ParseValue(value_ret);

  // 检查反序列化结果
  ASSERT_EQ(fields_ret.size(), fields1.size());
  for (size_t i = 0; i < fields_ret.size(); ++i) {
    ASSERT_EQ(fields_ret[i].first, fields1[i].first);
    ASSERT_EQ(fields_ret[i].second, fields1[i].second);
  }

  // 测试查找功能
  Field query_field = {"name", "Customer2"};
  std::vector<std::string> found_keys = FindKeysByField(db, query_field);
  std::cout << "找到的key有：" << found_keys.size() << "个" << std::endl;

  // 关闭数据库
  delete db;
}

int main(int argc, char **argv) {
  testing::InitGoogleTest(&argc, argv);
  return RUN_ALL_TESTS();
}
````
#### 5.1.2 测试结果
插入三条数据，name 字段分别为： Customer1, Customer1, Customer2

先根据 "name":"customer1"查找，结果为：
![图片](./pic/test_field_1.png)

在根据"name":"customer2"查找，结果为：
![图片](./pic/test_field_2.png)
### 5.2
单元测试:
1. 测试插入超过初始slot_page等slot数量之后，是否还能正常插入，检查slot_page文件等线性可扩展性
2. 测试插入后，进行删除，等待GC完成后再读取value和vlog的大小，看看GC过程是否正常进行。

性能测试:
1. 测试插入的吞吐
2. 测试在只有删除的情况下，GC的效率
3. 测试在插入和删除不同比重的负载下，系统的吞吐情况

#### 6. 可能遇到的挑战与解决方案
列出实现过程中可能遇到的技术难题及其解决思路，如如何处理GC开销、数据同步、索引原子更新等问题。
各种参数的设置，比如vlog的容量上限，以及slot_page的bitmap管理方式是否足够高效？以及在GC过程中如果对被GC中的vlog进行写入该让用户线程和后台线程以什么样的方式进行同步？slot_page的读写放大也是一个重要的问题。

#### 7. 分工和进度安排

| 功能                   | 完成日期  | 分工       |
|----------------------|-------|----------|
| Field相关接口实现          | 12.8  | 王雪飞      |
| value_log中value的存储格式 | 12.8  | 王雪飞      |
| slot_page 相关接口       | 12.8  | 马也驰      |
| slot_page实现          | 12.8  | 马也驰      |
| 修改leveldb的接口实现字段功能   | 12.17 | 王雪飞      |
| vlog的GC实现            | 12.29 | 马也驰      |
| 性能测试                 | 1.5   | 王雪飞, 马也驰 |
| 功能测试                 | 1.5   | 王雪飞， 马也驰 |