This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

HugeGraph (OLTP)

ToplingDB

ToplingDB Quick Start
ToplingDB YAML configuration file

ToplingDB

ToplingDB Quick Start

Thursday, October 09, 2025

前置条件

HugeGraph 版本: > 1.5.0
Java 版本: >= 11
确保已下载 ToplingDB 相关依赖
操作系统: Linux

启动和配置

ToplingDB是对 RocksDB 的可配置、可观测扩展，支持通过 YAML 文件进行动态调优，并通过内置 Web Server 实现实时监控

修改 hugegraph.properties

backend=rocksdb
serializer=binary
rocksdb.data_path=.
rocksdb.wal_path=.
# 配置文件路径
# 出于安全性考虑, HG中仅允许 yaml 文件位于conf/graphs目录下
rocksdb.option_path=./conf/graphs/rocksdb_plus.yaml
# 是否开启Web Server
rocksdb.open_http=true

初始化数据库（第一次启动时或在 conf/graphs/ 下手动添加了新配置时需要进行初始化）

cd *hugegraph-${version}
bin/init-store.sh

启动 server

bin/start-hugegraph.sh
Starting HugeGraphServer...
Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)....OK

提示的 url 与 rest-server.properties 中配置的 restserver.url 一致

Web Server 的监听端口在 YAML 文件中通过 http.listening_ports 字段进行配置

验证ToplingDB是否正常工作

前提: 确保核心参数配置正确

检查 hugegraph.properties 中包含:

# 配置文件路径
rocksdb.option_path=./conf/graphs/rocksdb_plus.yaml
# 是否开启Web Server
rocksdb.open_http=true

方式一: 访问Web监控界面

可视化访问Web监控页面，页面示例如下图所示:

通过终端验证:

# 访问 http://localhost:2011 (端口号取决于 YAML 配置中的 listening_ports)
curl http://localhost:2011 | grep topling

得到以下输出说明页面正常:

<p><a href="https://topling.cn">Topling Inc.</a>This is <strong>Engine Inspector</strong>, for metrics, see <a href='javascript:grafana()'>Grafana</a>!</p>

方式二: 检查日志中的 ToplingDB 初始化信息

tail -f logs/hugegraph-server.log | grep -i topling

类似输出说明存储引擎启动为ToplingDB:

2025-10-14 08:56:25 [db-open-1] [INFO] o.a.h.b.s.r.RocksDBStdSessions - SidePluginRepo found. Will attempt to open multi CFs RocksDB using Topling plugin.
2025-10-14 08:56:25 [db-open-1] [INFO] o.a.h.b.s.r.RocksDBStdSessions - Topling HTTP Server has been started according to the listening_ports specified in ./conf/graphs/rocksdb_plus.yaml

常见问题排查

问题 1: 启动失败，提示 YAML 格式错误

启动时有类似日志：

2025-10-15 01:55:50 [db-open-1] [INFO] o.a.h.b.s.r.RocksDBStdSessions - SidePluginRepo found. Will attempt to open multi CFs RocksDB using Topling plugin.
21:1: (891B):ERROR: 
sideplugin/rockside/3rdparty/rapidyaml/src/c4/yml/parse.cpp:3310: ERROR parsing yml: parse error: incorrect indentation?

解决方案:

检查 YAML 文件缩进是否正确（必须使用空格，不能使用 Tab）
验证 YAML 语法: python -c "import yaml; yaml.safe_load(open('conf/graphs/rocksdb_plus.yaml'))"
检查日志中的具体错误信息

问题 2: Web Server 端口冲突

启动时有类似日志：

2025-10-15 01:57:34 [db-open-1] [INFO] o.a.h.b.s.r.RocksDBStdSessions - SidePluginRepo found. Will attempt to open multi CFs RocksDB using Topling plugin.
2025-10-15 01:57:34 [db-open-1] [ERROR] o.a.h.b.s.r.RocksDBStore - Failed to open RocksDB 'rocksdb-data/data/g'
org.rocksdb.RocksDBException: rocksdb::Status rocksdb::SidePluginRepo::StartHttpServer(): null context when constructing CivetServer. Possible problem binding to port.
  at org.rocksdb.SidePluginRepo.startHttpServer(Native Method) ~[rocksdbjni-8.10.2-20250804.074027-4.jar:?]

解决方案:

检查端口是否被占用: lsof -i :2011
修改 YAML 文件中的 listening_ports 配置
重启 HugeGraph Server

问题 3: 初始化数据库失败

类似输出说明无法获取数据库锁，可能缺乏写权限，也可能是被数据库被另外一个进程锁定:

Caused by: org.rocksdb.RocksDBException: While lock file: rocksdb-data/data/m/LOCK: Resource temporarily unavailable
        at org.rocksdb.SidePluginRepo.nativeOpenDBMultiCF(Native Method)
        at org.rocksdb.SidePluginRepo.openDB(SidePluginRepo.java:22)

解决方案:

确认配置文件路径正确: rocksdb.option_path=./conf/graphs/rocksdb_plus.yaml
检查数据目录权限: 确保运行用户有读写权限
查看详细日志: bin/init-store.sh 2>&1 | tee init.log

ToplingDB YAML configuration file

Tuesday, September 30, 2025

RocksDB 提供了丰富的参数配置，但大多数情况下，这些配置需要通过硬编码完成。

ToplingDB 在此基础上引入了 SidePlugin + YAML 的方式，使得配置更加模块化和可组合。

本文重点介绍 ToplingDB 扩展参数 的部分，帮助读者理解这些配置的意义。

术语说明

MemTable: LSM-Tree 在内存中的可写数据结构，接收新写入的数据
SST (Sorted String Table): Memtable 持久化到磁盘后生成的有序键值对文件
Flush: 将 MemTable 数据写入磁盘生成 SST 的过程
Compaction: 合并多个 SST 文件以优化存储和查询性能的过程
L0, L1, … L6: LSM-Tree 的不同层级，数字越大层级越深

0. HugeGraph 中提供的rocksdb_plus.yaml

下文只包括HugeGraph中所使用的配置参数，ToplingDB支持的完整配置请参考：SidePlugin Wiki

http: # Web Server 相关配置
  # normally parent path of db path
  document_root: /dev/shm/rocksdb_resource # 静态资源目录, HugeGraph中通过`preload_topling.sh`进行静态资源提取
  listening_ports: '127.0.0.1:2011' # Web Server监听端口，用于管理/监控 如端口被占用，请改为其他端口，例如 2012 或 2013
setenv: # 环境变量设置
  StrSimpleEnvNameNotOverwrite: StringValue
  IntSimpleEnvNameNotOverwrite: 16384
  OverwriteThisEnv:
    #comment: overwrite is default to false
    overwrite: true
    value: force overwrite this env by overwrite true
Cache: # Cache 相关配置
  lru_cache: # 定义一个 LRU 缓存实例
    class: LRUCache
    params: 
      capacity: 8G # 缓存容量 8GB
      num_shard_bits: -1 # 分片数量，-1 表示自动
      strict_capacity_limit: false
      high_pri_pool_ratio: 0.5
      use_adaptive_mutex: false
      metadata_charge_policy: kFullChargeCacheMetadata # 元数据也计入缓存容量
Statistics: # 数据采样配置
  stat:
    class: default
    params:
      discard_tickers: # 丢弃的统计计数器，减少开销
        - rocksdb.block.cache
        - rocksdb.block.cachecompressed
        - rocksdb.block
        - rocksdb.memtable.payload.bytes.at.flush
        - rocksdb.memtable.garbage.bytes.at.flush
        - rocksdb.txn
        - rocksdb.blobdb
        - rocksdb.row.cache
        - rocksdb.number.block
        - rocksdb.bloom.filter
        - rocksdb.persistent
        - rocksdb.sim.block.cache
      discard_histograms: # 丢弃的直方图统计项
        # comment: ....
        - rocksdb.blobdb
        - rocksdb.bytes.compressed
        - rocksdb.bytes.decompressed
        - rocksdb.num.index.and.filter.blocks.read.per.level
        - rocksdb.num.data.blocks.read.per.level
        - rocksdb.compression.times.nanos
        - rocksdb.decompression.times.nanos
        - rocksdb.read.block.get.micros
        - rocksdb.write.raw.block.micros
      # comment end of array
      #stats_level: kAll
      stats_level: kDisableAll  # 禁用所有统计
MemTableRepFactory: # 内存中 memtable 的实现
  cspp: # ToplingDB 独有的高并发内存结构
    class: cspp
    params:
      mem_cap: 16G # 预分配足够的单块内存地址空间，这些内存可以只是保留地址空间，但并未实际分配 对物理内存并无要求，只是为CSPP保留虚拟内存空间
      use_vm: false
      token_use_idle: true
      chunk_size: 16K # 内部分配粒度
      convert_to_sst: kFileMmap # 直接将 MemTable 转化为 SST，省去 Flush，可选值：{kDontConvert, kDumpMem, kFileMmap}
      sync_sst_file: false # convert_to_sst 为 kFileMmap 时，SST 转化完成后是否执行 fsync
  skiplist: # RocksDB 默认的跳表结构
    class: SkipList
    params:
      lookahead: 0
TableFactory:
  cspp_memtab_sst:
    class: CSPPMemTabTable # 与 cspp 配套的 TableFactory
    params: # empty params
  bb:
    class: BlockBasedTable # RocksDB 默认的块表
    params:
      checksum: kCRC32c
      block_size: 4K
      block_restart_interval: 16
      index_block_restart_interval: 1
      metadata_block_size: 4K
      enable_index_compression: true
      block_cache: "${lru_cache}" # 使用上面定义的 LRU 缓存
      block_cache_compressed:
      persistent_cache:
      filter_policy:
  dispatch:
    class: DispatcherTable
    params:
      default: bb # 默认使用 BlockBasedTable
      readers:
        BlockBasedTable: bb
        CSPPMemTabTable: cspp_memtab_sst
      level_writers: [ bb, bb, bb, bb, bb, bb ] # 支持自定义各层写入策略
CFOptions:
  default:
    max_write_buffer_number: 6
    memtable_factory: "${cspp}" # 引用上方定义的cspp，使用 cspp 作为 MemTable
    write_buffer_size: 128M
    # set target_file_size_base as small as 512K is to make many SST files,
    # thus key prefix cache can present efficiency
    target_file_size_base: 64M
    target_file_size_multiplier: 1
    table_factory: dispatch # 引用上方定义的 dispatch, 使用 DispatcherTable Class
    max_bytes_for_level_base: 512M
    max_bytes_for_level_multiplier: 10
    level_compaction_dynamic_level_bytes: false
    level0_slowdown_writes_trigger: 20
    level0_stop_writes_trigger: 36
    level0_file_num_compaction_trigger: 2
    merge_operator: uint64add # support merge
    level_compaction_dynamic_file_size: true
    optimize_filters_for_hits: true
    allow_merge_memtables: true
    min_write_buffer_number_to_merge: 2
    compression_per_level:
      - kNoCompression
      - kNoCompression
      - kSnappyCompression
      - kSnappyCompression
      - kSnappyCompression
      - kSnappyCompression
      - kSnappyCompression
DBOptions:
  dbo:
    create_if_missing: true
    create_missing_column_families: false # this is important, must be false to hugegraph
    max_background_compactions: -1
    max_subcompactions: 4
    max_level1_subcompactions: 0
    inplace_update_support: false
    WAL_size_limit_MB: 0
    statistics: "${stat}"  # 使用上面定义的统计配置
    max_manifest_file_size: 100M
    max_background_jobs: 8 # 设置flush和compaction线程总数 建议设置为 (cpu核数 / 2)
    compaction_readahead_size: 0
    memtable_as_log_index: true # 此配置结合 convert_to_sst: kFileMmap 可实现[omit L0 Flush](https://github.com/topling/toplingdb/wiki/Omit-L0-Flush)

关键要点:

listening_ports: '127.0.0.1:2011' 指定Web Server监听端口为2011，并且仅允许本地访问
memtable_as_log_index: true 与 convert_to_sst: kFileMmap 结合实现omit L0 Flush
memtable_factory: "${cspp}" 指定了内存结构采用CSPP Memtable
table_factory: dispatch 指定了TableFactory使用YAML中自定义的DispatcherTable结构

1. 插件化配置与引用机制

YAML 插件化：配置文件以对象形式组织，每个对象可以单独定义并在其他地方引用。
引用语法：通过 ${lru_cache}、${cspp} 等方式在不同段落复用对象。
DispatcherTable：允许在不同层级或场景下选择不同的 TableFactory。RocksDB 原生只能指定单一 TableFactory。

ToplingDB YAML 引用与复用图示:

这种机制使得配置更灵活，便于在复杂场景下组合不同组件。

2. 新的 MemTable 实现：CSPP

ToplingDB 提供了一个 RocksDB 原生没有的 MemTable 类型，通过以下参数配置：

mem_cap

mem_cap 是指在内存地址空间中，为 CSPP 预留的空间大小，这些内存可以只是保留地址空间，并未实际分配的。 mem_cap 真正占用的内存大小约为 write_buffer_size 。

mem_cap 设计背景

CSPP 的底层算法为了支持高并发写入，采用了预分配内存的策略。当预分配的内存被写满时，新的写入操作将无法继续。然而，RocksDB 本身缺乏一种机制，使得 memtable 能够主动反馈 ‘预分配内存已满，需要切换到新的 memtable’ 。由于其函数调用链路复杂，难以通过重构来实现这一机制，因此 CSPP 只能通过参数设计来适配 RocksDB 的行为。

mem_cap 核心思路

ToplingDB 将 mem_cap 设置为远大于 write_buffer_size，从而避免 RocksDB 在向 Memtable 写入时过早触发“内存已满”的错误。在 CSPP 初始化（New）时，会再次检查，如果发现 mem_cap 设置过小，则会自动调整为 2 * write_buffer_size，以确保写入过程的稳定性。

mem_cap 默认值为 2G，有效最大值为 16G。

小型部署（< 16GB 内存）: 建议设置为系统内存的 20-30%
中型部署（16-64GB 内存）: 建议设置为 8-16G
大型部署（> 64GB 内存）: 建议设置为 16G

use_vm

在使用 malloc/posix_memalign 分配内存时，地址空间可能是已经实际分配的（位于堆空间中，已有对应的物理页面），而 CSPP 在分配时只需要获得保留的地址空间。 use_vm 选项为 true 时会强制使用 mmap 分配内存，从而保证分配的一定时是保留地址空间，但并不实际占用物理页面。 use_vm 默认值为 true。如果用户物理内存空间充足，建议关闭此选项，mmap 分配的虚拟内存空间在建立对物理地址的映射时会触发大量minor page fault，可能会影响性能。

convert_to_sst

convert_to_sst 支持以下三种枚举值:

kDontConvert: 禁用该功能，为默认值。使用传统的 Flush 流程，兼容性最好，适合对稳定性要求高的场景
kDumpMem: 转化时将 MemTable 的整块内存写入 SST 文件，避免 CPU 消耗，但未降低内存消耗
kFileMmap: 将 MemTable 内容 mmap 到文件，这是关键功能，同时降低 CPU 和内存消耗，可同时将 DBOptions.memtable_as_log_index 设为 true 从本质上消除 MemTable Flush

这些参数为数据写入路径提供了更多可调节空间，用户可按需选择。

更多设计细节请参考 ToplingDB 作者的撰写的相关博客：cspp-memtable, ToplingDB CSPP MemTable Design Essentials, CSPP Trie Design Analysis

3. TableFactory 扩展

CSPPMemTabTable：与 cspp MemTable 配套的 TableFactory。
DispatcherTable：支持为不同层级指定不同的 TableFactory，例如：
- 默认使用 BlockBasedTable。
- 特定层级可以使用 CSPPMemTabTable。

这类灵活性在 RocksDB 原生配置中并不存在。

4. 统计与观测控制

discard_tickers / discard_histograms：可以精确指定哪些统计项需要丢弃。
stats_level: kDisableAll：结合上述配置，可以灵活控制统计开销。

相比 RocksDB 的粗粒度控制，ToplingDB 提供了更细的调节方式。

5. DBOptions 新增参数

memtable_as_log_index: true：允许使用 MemTable 作为日志索引，加快恢复速度。

6. 安全注意事项

Web Server 安全配置:

Web Server 页面由ToplingDB提供，不包含权限认证功能
默认设置 listening_ports: '127.0.0.1:2011' 仅限本地访问
生产环境建议配置防火墙规则，仅允许内网访问
如需禁用 Web Server，在 hugegraph.properties 中设置 rocksdb.open_http=false

共享内存安全:

document_root: /dev/shm/rocksdb_resource 使用共享内存目录
多用户环境需要注意文件权限设置，避免未授权访问

7. 总结

ToplingDB 在 RocksDB 的基础上增加了以下能力：

插件化配置与对象复用
新的 MemTable 类型（cspp）及配套 TableFactory
DispatcherTable 支持多工厂调度
内置 Web Server
更灵活的统计与观测控制
特殊 DBOptions（如 memtable_as_log_index）

这些扩展为用户提供了更多的可调节空间，尤其适合需要高写入性能和灵活运维的场景。

HugeGraph (OLTP)

ToplingDB

ToplingDB Quick Start

前置条件

启动和配置

验证ToplingDB是否正常工作

前提: 确保核心参数配置正确

方式一: 访问Web监控界面

方式二: 检查日志中的 ToplingDB 初始化信息

常见问题排查

问题 1: 启动失败，提示 YAML 格式错误

问题 2: Web Server 端口冲突

问题 3: 初始化数据库失败

相关文档

ToplingDB YAML configuration file

术语说明

0. HugeGraph 中提供的rocksdb_plus.yaml

1. 插件化配置与引用机制

2. 新的 MemTable 实现：CSPP

mem_cap

mem_cap 设计背景

mem_cap 核心思路

use_vm

convert_to_sst

3. TableFactory 扩展

4. 统计与观测控制

5. DBOptions 新增参数

6. 安全注意事项

7. 总结

相关文档