完整功能

English

使用 TerarkDB 的完整功能

现在您应该已经编译好了 Terark RocksDB 并且下载了 terark-zip-rocksdb, 如果还没有，请您回到这个页面

1. 简介

2. 目标用户

• 需要更细粒度的控制 TerarkDB 下的 SSTable (需要部分代码修改)
• 需要了解更多我们是如何实现 SSTable 的用户

NOTE: If you just want to experience TerarkDB without code changes of your application, please refer to 快速开始

3. RocksDB 工具

在我们的 RocksDB 克隆仓库, 我们为其增加了一部分配置以方便使用 TerarkDB, e.g.:

Utility	TerarkDB option
ldb	--use_terarkdb=1

4. TerarkDB 限制

• User comparator is not supported, you should encode your keys byte lexical order
• EnvOptions::use_mmap_reads must be true, can be set by DBOptions::allow_mmap_reads

5. RocksDB 注意事项

• table_factory 是 ColumnFamilyOptions 的成员, 并非 DBOptions 的!
• 如果通过 column families 调用 rocksdb::DB::Open(), 你必须为每个 table_factory 设置 ColumnFamilyDescriptor

// Caution: When calling this `Open` overload, you must 
// set column_families[i].options.table_factory
//
// You may pass an rocksdb::Option object as db_options, but this
// db_options.table_factory will NOT be used!!
//
static Status Open(const DBOptions& db_options, const std::string& name,
                   const std::vector<ColumnFamilyDescriptor>& column_families,
                   std::vector<ColumnFamilyHandle*>* handles, DB** dbptr);

6. 使用 TerarkZipTable

6.1. C++ 代码

• Compile flags

CXXFLAGS += -I/path/to/terark-zip-rocksdb/src

• Linker flags

LDFLAGS += -L/path/to/terark-zip-rocksdb-lib
LDFLAGS += -lterark-zip-rocksdb-r
LDFLAGS += -lterark-zbs-r -lterark-fsa-r -lterark-core-r

• C++ 代码示例

#include <table/terark_zip_table.h>
/// other includes...

  ///....
  TerarkZipTableOptions opt;

  /// TerarkZipTable 在压缩过程中需要临时文件夹
  opt.localTempDir = "/path/to/some/temp/dir"; // default is "/tmp"

  /// 0 : 不校验数据
  /// 1 : 校验元数据和索引, 在文件加载时进行
  /// 2 : 校验所有数据， 不在文件加载时进行。这个校验对每条记录都进行，同时这项操作会导致每条记录额外占用 4 字节
  /// 3 : 校验所有数据，不针对每条数据进行校验，而是只检查一个总体的校验值，校验失败会导致加载失败
  opt.checksumLevel = 3; // default 1

  ///    < 0 : 只有最后面的 Level 才使用 TerarkZip
  ///          等价于 `terarkZipMinLevel == num_levels-1`
  /// others : 当 `curlevel >= terarkZipMinLevel` 的时候使用 TerarkZip
  ///          包含两种特殊情况：
  ///                   == 0 : 所有的 Level 均使用 TerarkZip
  ///          >= num_levels : 所有的 Level 均回退到原始的 TableFactory
  /// 实践中 `terarkZipMinLevel = 0` 是比较好的选择
  /// 如果混合了原生的 RocksDB SST, 这些 SST 会占用过多的内存和 SSD，导致性能降低
  opt.terarkZipMinLevel = 0; // default

  /// optional
  opt.softZipWorkingMemLimit = 16ull << 30; // default
  opt.hardZipWorkingMemLimit = 32ull << 30; // default

  /// 让 RocksDB 压缩算法获知预估的 SST 尺寸
  opt.estimateCompressionRatio = 0.2;

  /// 字典尺寸和所有的 value 尺寸的比率
  opt.sampleRatio = 0.03;
 
  /// other opt are tricky, just use default

  /// rocksdb options when using terark-zip-rocksdb:

  /// fallback can be NULL
  auto fallback = NewBlockBasedTableFactory(); // or NewAdaptiveTableFactory();
  auto factory = NewTerarkZipTableFactory(opt, fallback);
  options.table_factory.reset(factory);

  /// terark-zip use mmap
  options.allow_mmap_reads = true;

  /// universal compaction reduce write amplification and is more friendly for
  /// large SST file, terark SST is better on larger SST file.
  /// although universal compaction needs 2x SSD space on worst case, but
  /// with terark-zip's high compression, the used SSD space is much smaller
  /// than rocksdb's block compression schema
  options.compaction_style = rocksdb::kCompactionStyleUniversal;

  /// larger MemTable yield larger level0 SST file
  /// larger SST file make terark-zip better
  options.write_buffer_size     =  1ull << 30; // 1G
  options.target_file_size_base =  1ull << 30; // 1G

  /// single sst file size on greater levels should be larger
  /// filesize(level[n+1]) = filesize(level[n]) * target_file_size_multiplier
  options.target_file_size_multiplier = 2; // can be larger, such as 3,5,10

  /// 关闭 RocksDB 写限速是可选的. 如果写限速打开并且写入速度过慢，用户可能会以为是 TerarkDB 导致的
  options.level0_slowdown_writes_trigger = INT_MAX;
  options.level0_stop_writes_trigger = INT_MAX;
  options.soft_pending_compaction_bytes_limit = 0;
  options.hard_pending_compaction_bytes_limit = 0;