Skip to content

快速开始

Jump to bottom
rockeet edited this page Jan 7, 2019 · 42 revisions

English

快速开始

开始之前，您应该已经编译成功了 Terark RocksDB 且下载了 terark-zip-rocksdb, 如果还没有，请返回 首页 完成这项操作

1. 介绍

开始使用 TerarkDB 仅需要一些简单的环境变量设置.

由于 Terark RocksDB 和官方的 RocksDB 是二进制兼容的，您并不需要重新编译自己的应用层代码。 -- Note: 官方的 RocksDB 不同版本一般互不兼容，目前我们的最新稳定版兼容 rocksdb 5.9.2，尝鲜版兼容 rocksdb 5.17.0。

2. 目标用户

  • 想要快速体验 TerarkDB 的用户
  • 如果您现在已经在使用 RocksDB，并且不希望修改任何代码
  • 如果您现在已经在使用 RocksDB，并且不希望重新编译
  • 不需要细粒度的 TerarkDB 接口控制

3. 使用 TerarkDB

您需要首先设置一下的环境变量，以开启 TerarkDB 支持:

# If you have installed files in `terark-zip-rocksdb-XXX/lib` into
# system lib path(such as /usr/lib64), `LD_LIBRARY_PATH` is not needed.
export LD_LIBRARY_PATH=terark-zip-rocksdb-XXX/lib:$LD_LIBRARY_PATH

env LD_PRELOAD=libterark-zip-rocksdb-r.so \
    TerarkZipTable_localTempDir=/path/to/some/temp/dir \
    TerarkZipTable_indexNestLevel=2 \
    TerarkZipTable_indexCacheRatio=0.005 \
    TerarkZipTable_smallTaskMemory=1G \
    TerarkZipTable_softZipWorkingMemLimit=16G \
    TerarkZipTable_hardZipWorkingMemLimit=32G \
    app_exe_file app_args...

这些环境变量中，只有 LD_PRELOAD 和 TerarkZipTable_localTempDir 是必须的，其他的环境变量可以留空使用默认值即可.

更多的细节，可以参考 TerarkZipTableOptions.

3.3.1. 完整的选项

下表中省略了所有的环境变量均需要前缀 TerarkZipTable_，如对于 localTempDir 变量，您需要设置的环境变量是TerarkZipTable_localTempDir.

1) TerarkZipTableOptions 类中的参数

type env var suffix or
TerarkZipTableOptions::
member 		Default 解释说明
string localTempDir * 临时文件目录
enum
string		 entropyAlgo NoEntropy 熵编码对压缩率提高有限，
但对读性能影响巨大
string indexType IL_256 指定 rank-select 的实现方式
int checksumLevel 3 3 对整体数据做 checksum
int indexNestLevel 3 越大，压缩率越高，读性能越低
int indexNestScale 8 越大，压缩率越高，读性能越低
int indexTempLevel 0 越大，索引创建的内存用量约小，索引创建的速度越慢，
-1: 禁用临时文件
0: 智能判断，仅对大索引使用临时文件
int terarkZipMinLevel 0 仅在大于等于该 level 时，才使用 Terark 的 SSTable
int keyPrefixLen 0(禁用) For MongoRocks, MyRocks ...
一般上层数据库会用一个 BigEndianUint 作为下层 KeyValue 引擎中 Key 的前缀，用来区分不同的 table/index/...，相同的 table/index/... 一般具有相同的 schema，从而 KeyValue 引擎可以进行更好的优化
int offsetArrayBlockUnits 0(禁用) 合法值: {0,64,128}
int minPreadLen -1 < 0 : 总是不使用 pread
= 0 : 总是使用 pread
> 0 : 大于此长度时才使用 pread
---------
注意： 在内存受限时，pread 性能比 mmap 更稳定
bool disableSecondPassIter false false 对临时文件需求小，但压缩速度慢，true: 磁盘空间必须充足
bool useSuffixArrayLocalMatch false 可以提高压缩率，但会降低压缩速度
bool warmUpIndexOnOpen true 预热 index
bool warmUpValueOnOpen false 预热 value data
float estimateCompressionRatio 0.2 压缩率预估，SST Build 过程中，TerarkZipTable 并不会写 SST（Finish 时写才 SST），但 rocksdb 需要 SST Builder 报告 SST 文件尺寸，所以使用该预估值向 rocksdb 报告预估的 SST 文件尺寸，用来控制最终输出的 SST 文件尺寸
bool enableCompressionProbe true 自动检测数据冗余度（是否可压缩）。
该参数用来更准确地预估 SST 文件的尺寸，并提高压缩速度（当数据不可压缩时，就禁用压缩）
float sampleRatio 0.03 采样比率：对于单个 SST，全局字典的尺寸占 value 总尺寸的比例，全局字典的上限是 2G，如果超过 2G，也只保留 2G。
全局字典需要常驻内存，所以，如果数据的总尺寸比内存大很多，应该将该值适当调小，建议所有 SST 文件的全局字典的总尺寸不超过系统总内存的 30%
float indexCacheRatio 0 典型值 0 或者较小的值，如 0.003
在使用嵌套 Trie 树索引时，indexCache 可以提高点查(Point Query)的性能，0.003 大约可以将点查的性能提高 10%
int64 softZipWorkingMemLimit 系统总内存⁄8 软限制 compact 的内存用量
int64 hardZipWorkingMemLimit 系统总内存⁄4 硬限制 compact 的内存用量
int64 smallTaskMemory 系统总内存⁄32 小 compact(或 memtable flush) 的优先级更高

2) ColumnFamilyOptions 类中的参数

type env var suffix or
ColumnFamilyOptions::member 		Default
enum by
string		 compaction_style universal
int num_levels 7
int64 write_buffer_size 系统总内存⁄32
int max_write_buffer_number 3
int64 target_file_size_base 系统总内存⁄2
int target_file_size_multiplier 1
int level0_file_num_compaction_trigger rocksdb
default

3) DBOptions 类中的参数

type env var suffix or
DBOptions::member 		Default
int base_background_compactions 3
int max_background_compactions 5
int max_background_flushes 3
int max_subcompactions 1

3) ColumnFamilyOptions::compaction_options_universal 中的参数

type env var suffix 或者
ColumnFamilyOptions::compaction_options_universal::member 		Default
int min_merge_width 4
int max_merge_width 50

5) 其他参数

type env var full name Default
string TerarkZipTable_blackListColumnFamily empty
int DictZipBlobStore_zipThreads min(8, physical_cpu_num)

  • TerarkZipTable_blackListColumnFamily

    • 只要定义了环境变量 TerarkZipTable_localTempDir，就会使用 TerarkZipTable，用户代码中设置的 option 参数就会全部失效
    • 用户可以把一些 column families 放在黑名单，他们将不会使用 TerarkZipTable
    • 多个 column families 需要通过 ',' 分割:
           TerarkZipTable_blackListColumnFamily=cf1,cf2,cf3
    • 可以考虑将 日志数据 或者短时间存在的数据放到黑名单

  • DictZipBlobStore_zipThreads

    • 如果这个变量不是 0, TerarkDB 的 SST Builder 会通过 read -> compress -> write 这个过程来压缩，这个过程由所有的 SST Builder 共享。这个变量代表上述过程的 compress 阶段的线程数.
    • 如果该变量比物理 CPU 数更大，将使用物理 CPU 数作为使用值.
    • 如果该变量是 0, TerarkDB 将不会使用 read -> compress -> write 这个过程，而是由调用线程来执行压缩.

3.4. 启动程序

完成设置后，直接启动程序即可

4. 背景知识

我们实际上实现了一个 RocksDB 的 SSTable 并且命名为 TerarkZipTable. 基于上面的环境变量，我们可以让 RocksDB 使用我们的 SSTable. 我们所有的算法均封装在 TerarkZipTable 并且不影响现有的 SSTable, 也就是说您可以不启动我们版本的 SSTable，继续使用默认版本。

5. 更多

TerarkZipTable 可以提供更细粒度功能： 使用 TerarkDB 的完整功能.

Terark.com

Table of Contents

Clone this wiki locally