This is the multi-page printable view of this section. Click here to print.
Welcome to HugeGraph Blog!
Here you will find technical articles, best practices, and community updates from the HugeGraph ecosystem:
Explore more content to enhance your graph database experience!
ToplingDB is a configurable and observable extension of RocksDB. It supports dynamic tuning via YAML files and enables real-time monitoring through a built-in Web Server.
Update hugegraph.properties
backend=rocksdb
serializer=binary
rocksdb.data_path=.
rocksdb.wal_path=.
# Path to YAML configuration file
# For security reasons, HG only allows YAML files to be located under the `conf/graphs` directory
rocksdb.option_path=./conf/graphs/rocksdb_plus.yaml
# Enable Web Server
rocksdb.open_http=true
Initialize the database (required on the first startup, or a new configuration was manually added under ‘conf/graphs/’)
cd *hugegraph-${version}
bin/init-store.sh
Start server
bin/start-hugegraph.sh
Starting HugeGraphServer...
Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)....OK
Check that hugegraph.properties includes:
# Configuration file path
rocksdb.option_path=./conf/graphs/rocksdb_plus.yaml
# Enable Web Server
rocksdb.open_http=true
Visualize the Web monitoring page. Example screenshot:
Verify via terminal:
# Access http://localhost:2011 (port depends on listening_ports in YAML config)
curl http://localhost:2011 | grep topling
The following output indicates the page is working:
<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>
tail -f logs/hugegraph-server.log | grep -i topling
Similar output indicates ToplingDB is the storage engine:
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
Sample log during startup:
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?
Solutions:
python -c "import yaml; yaml.safe_load(open('conf/graphs/rocksdb_plus.yaml'))"Sample log during startup:
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:?]
Solutions:
lsof -i :2011listening_ports in the YAML fileSample output indicating lock acquisition failure, possibly due to write permission issues or another process locking the DB:
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)
Solutions:
rocksdb.option_path=./conf/graphs/rocksdb_plus.yamlbin/init-store.sh 2>&1 | tee init.logRocksDB provides a rich set of configuration parameters, but most of them typically require hardcoded setup.
ToplingDB introduces a SidePlugin + YAML mechanism, making configuration more modular and composable.
This document focuses on the extended parameters of ToplingDB, helping readers understand their purpose and usage.
The following includes only the configuration parameters used in HugeGraph. For the full configuration supported by ToplingDB, refer to the SidePlugin Wiki:
http: # Web Server related configuration
# normally parent path of db path
document_root: /dev/shm/rocksdb_resource # Static resource directory, extracted by `preload_topling.sh` in HugeGraph
listening_ports: '127.0.0.1:2011' # Web Server listening port for management/monitoring
setenv: # Environment variable settings
StrSimpleEnvNameNotOverwrite: StringValue
IntSimpleEnvNameNotOverwrite: 16384
OverwriteThisEnv:
#comment: overwrite is default to false
overwrite: true
value: force overwrite this env by overwrite true
Cache: # Cache configuration
lru_cache: # Define an LRU cache instance
class: LRUCache
params:
capacity: 8G # Cache capacity: 8GB
num_shard_bits: -1 # Number of shards, -1 means auto
strict_capacity_limit: false
high_pri_pool_ratio: 0.5
use_adaptive_mutex: false
metadata_charge_policy: kFullChargeCacheMetadata # Metadata also counts toward cache capacity
Statistics: # Sampling configuration
stat:
class: default
params:
discard_tickers: # Discarded tickers to reduce overhead
- 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: # Discarded histogram metrics
# 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 # Disable all statistics
MemTableRepFactory: # MemTable implementation in memory
cspp: # ToplingDB-specific high-concurrency memory structure
class: cspp
params:
mem_cap: 16G # Preallocate sufficient virtual memory space; may reserve address space without actual allocation
use_vm: false
token_use_idle: true
chunk_size: 16K # Internal allocation granularity
convert_to_sst: kFileMmap # Convert MemTable directly to SST, skipping flush; options: {kDontConvert, kDumpMem, kFileMmap}
sync_sst_file: false # Whether to fsync after SST conversion when using kFileMmap
skiplist: # Default skiplist structure in RocksDB
class: SkipList
params:
lookahead: 0
TableFactory:
cspp_memtab_sst:
class: CSPPMemTabTable # TableFactory paired with cspp
params: # empty params
bb:
class: BlockBasedTable # Default block-based table in 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}" # Use the LRU cache defined above
block_cache_compressed:
persistent_cache:
filter_policy:
dispatch:
class: DispatcherTable
params:
default: bb # Default to BlockBasedTable
readers:
BlockBasedTable: bb
CSPPMemTabTable: cspp_memtab_sst
level_writers: [ bb, bb, bb, bb, bb, bb ] # Custom write strategy per level
CFOptions:
default:
max_write_buffer_number: 6
memtable_factory: "${cspp}" # Reference cspp defined above
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 # Reference dispatch defined above
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}" # Use the statistics config defined above
max_manifest_file_size: 100M
max_background_jobs: 8
compaction_readahead_size: 0
memtable_as_log_index: true # Combined with convert_to_sst: kFileMmap to enable [omit L0 Flush](https://github.com/topling/toplingdb/wiki/Omit-L0-Flush)
Key points:
listening_ports: '127.0.0.1:2011' sets the Web Server listening port to 2011 and restricts access to localhost.memtable_as_log_index: true combined with convert_to_sst: kFileMmap enables omit L0 Flush.memtable_factory: "${cspp}" specifies the memory structure as CSPP Memtable.table_factory: dispatch sets the TableFactory to the custom DispatcherTable defined in YAML.${lru_cache}, ${cspp}, etc.ToplingDB YAML Reference and Reuse Diagram:
This mechanism makes configuration more flexible and easier to compose in complex scenarios.
ToplingDB provides a MemTable type that RocksDB does not natively have, configured with the following parameters:
mem_cap is the size of the virtual address space reserved for CSPP. This may be just reserved address space without actual physical allocation.
The actual memory usage of mem_cap is approximately equal to write_buffer_size.
The underlying algorithm of CSPP adopts a pre-allocation strategy to support high-concurrency writes. Once the pre-allocated memory is filled, no further writes can proceed. However, RocksDB itself lacks a mechanism that allows a memtable to actively report “the pre-allocated memory is full, a new memtable is required”. Due to the complexity of its call chain, it is impractical to refactor RocksDB to add this capability. Therefore, CSPP adapts to RocksDB’s behavior through parameter design.
ToplingDB sets mem_cap to be much larger than write_buffer_size,
so that RocksDB will not prematurely trigger an “out of memory” error when writing to a memtable.
During CSPP initialization (New), the system rechecks the setting.
If mem_cap is found to be too small, it will be automatically adjusted to 2 * write_buffer_size to ensure stability during the write process.
The default value is 2G, and the effective maximum is 16G.
When allocating memory via malloc/posix_memalign, the address space may already be physically allocated (heap space with mapped pages), while CSPP only needs reserved virtual address space.
When use_vm is true, allocation is forced to use mmap, ensuring reserved address space without occupying physical pages.
The default is true. If physical memory is sufficient, it is recommended to disable this option—establishing mappings from mmap’s virtual memory to physical pages can trigger many minor page faults and may affect performance.
convert_to_sst supports three enum values:
kDontConvert: Disables the feature (default). Uses the traditional Flush process, offering the best compatibility for stability-focused scenarios.kDumpMem: During conversion, dumps the entire MemTable memory to an SST file, reducing CPU consumption but not memory usage.kFileMmap: mmaps MemTable content into a file—the key feature—reduces both CPU and memory usage. You can also set DBOptions.memtable_as_log_index = true to essentially eliminate MemTable Flush.These parameters offer more tunable options for the write path, allowing users to choose as needed.
For more design details, see: cspp-memtable, ToplingDB CSPP MemTable Design Essentials, CSPP Trie Design Analysis.
cspp MemTable.This level of flexibility is not available in native RocksDB configuration.
Compared to RocksDB’s coarse-grained controls, ToplingDB offers finer tuning.
Web Server security:
listening_ports: '127.0.0.1:2011' restricts access to local requests.rocksdb.open_http=false in hugegraph.properties.Shared memory safety:
document_root: /dev/shm/rocksdb_resource uses a shared memory directory.ToplingDB adds the following capabilities on top of RocksDB:
memtable_as_log_index)These extensions give users more tuning space, particularly suited for scenarios requiring high write performance and flexible operations.