ZoneTree/docs/reference/configuration.md

Configuration

This page summarizes the most important configuration areas.

Factory

ZoneTreeFactory<TKey, TValue> configures and opens a tree.

Common methods:

• SetDataDirectory
• SetWriteAheadLogDirectory
• SetLogger
• SetLogLevel
• SetComparer
• SetKeySerializer
• SetValueSerializer
• SetMutableSegmentMaxItemCount
• SetDiskSegmentMaxItemCount
• SetDiskSegmentCompressionBlockSize
• SetRandomAccessDeviceManager
• SetWriteAheadLogProvider
• SetTransactionLog
• SetIsDeletedDelegate
• SetMarkValueDeletedDelegate
• DisableDeletion
• Configure
• ConfigureWriteAheadLogOptions
• ConfigureDiskSegmentOptions
• ConfigureTransactionLog
• OpenOrCreate
• Open
• Create
• OpenOrCreateTransactional

Set serializers, comparers, deletion delegates, and storage providers before opening the tree. Serializers cannot be changed after the WAL provider or transaction log has been initialized.

Comparer semantics are part of the persisted keyspace. ZoneTree stores the comparer type in metadata and validates it on open, but a custom comparer with the same type can still become incompatible if its comparison behavior changes. Create a new ZoneTree and rebuild/copy data when you need a different order.

Default Profile

ZoneTree defaults are designed as a practical general-purpose profile. Start with them, then tune after measuring the actual workload.

Area	Default
Mutable segment max item count	1_000_000 records
Disk segment max item count	20_000_000 records
BTree lock mode	NodeLevelMonitor
BTree node size	128
BTree leaf size	128
WAL mode	AsyncCompressed
WAL compression block size	256 KB
WAL compression	LZ4, fastest level
Async compressed WAL empty queue poll interval	100 ms
Sync compressed WAL tail writer	enabled
Sync compressed WAL tail writer interval	500 ms
Disk segment mode	MultiPartDiskSegment
Disk segment compression block size	4 MB
Disk segment compression	LZ4, fastest level
Multipart minimum record count	1_500_000 records
Multipart maximum record count	3_000_000 records
Key cache size	1024 records
Value cache size	1024 records
Key cache lifetime	10 seconds
Value cache lifetime	10 seconds
Default sparse array step size	1024
Maintainer maximum read-only segment count	64
Maintainer merge record threshold	0 records
Maintainer block cache lifetime	1 minute
Maintainer inactive cache cleanup interval	30 seconds
Maintainer inactive cache cleanup job from CreateMaintainer()	enabled
Console logger level	Warning

Memory

MutableSegmentMaxItemCount controls when the active mutable segment is moved forward.

The default is 1_000_000 records. This is a good starting point for small keys and values. Lower it for large values. Raise it only when memory budget and maintenance behavior are understood.

Disk

Disk segment options affect file layout, compression, caches, sparse arrays, multipart sizing, and merge behavior.

Tune disk options with the actual read/write pattern.

Important options:

Option	Purpose
DiskSegmentMode	single or multipart disk segment shape
CompressionBlockSize	block size for compressed random-access disk data
CompressionMethod	disk segment compression method
CompressionLevel	compression level for the selected method
MinimumRecordCount	lower target part size for multipart disk segments
MaximumRecordCount	upper target part size for multipart disk segments
DefaultSparseArrayStepSize	sparse index density for disk search
KeyCacheSize	circular cache size for recently read keys
ValueCacheSize	circular cache size for recently read values
KeyCacheRecordLifeTimeInMillisecond	key cache record lifetime
ValueCacheRecordLifeTimeInMillisecond	value cache record lifetime

The default disk profile uses multipart disk segments, 20_000_000 as the disk segment max item count, 1_500_000 to 3_000_000 records per multipart part, 4 MB disk compression blocks, LZ4 fastest compression, 1024 sparse array step size, and 1024 key/value cache entries with 10 second lifetimes.

WAL

WAL options control durability, compression, and backup behavior.

The default WAL mode is WriteAheadLogMode.AsyncCompressed. It is the recommended starting point for most persistent databases because it keeps WAL protection enabled while preserving high write throughput.

using ZoneTree.Options;

using var zoneTree = new ZoneTreeFactory<int, string>()
    .SetDataDirectory("data/app")
    .ConfigureWriteAheadLogOptions(options =>
    {
        options.WriteAheadLogMode = WriteAheadLogMode.AsyncCompressed;
    })
    .OpenOrCreate();

Important WAL options:

Option	Purpose
WriteAheadLogMode	chooses sync, sync-compressed, async-compressed, or no WAL
CompressionBlockSize	compressed WAL block size
CompressionMethod	compression method for compressed WAL modes
CompressionLevel	compression level for the selected method
SyncCompressedModeOptions	sync-compressed tail writer options
AsyncCompressedModeOptions	async writer polling behavior
EnableIncrementalBackup	preserves WAL content during WAL replacement/compaction

Use sync modes when the application specifically needs synchronous WAL acknowledgment. Use No WAL only for cache, temporary, or intentionally rebuildable data.

The default WAL profile uses async compressed WAL, 256 KB compression blocks, LZ4 fastest compression, and a 100 ms async empty-queue poll interval.

Incremental backup is disabled by default. Enable it only when you intentionally need WAL history preserved during WAL replacement or compaction.

using var zoneTree = new ZoneTreeFactory<int, string>()
    .SetDataDirectory("data/app")
    .ConfigureWriteAheadLogOptions(options =>
    {
        options.EnableIncrementalBackup = true;
    })
    .OpenOrCreate();

Maintenance

The maintainer controls background merge work and inactive cache cleanup.

The maintainer created by zoneTree.CreateMaintainer() uses these defaults:

Option	Default
MaximumReadOnlySegmentCount	64
ThresholdForMergeOperationStart	0 records
BlockCacheLifeTime	1 minute
InactiveBlockCacheCleanupInterval	30 seconds
inactive-cache cleanup job	enabled

EnableJobForCleaningInactiveCaches is false on a raw maintainer instance before the timer is started, but the normal CreateMaintainer() path starts the cleanup job by default.

Deletion

Deletion behavior is configured with:

• SetIsDeletedDelegate,
• SetMarkValueDeletedDelegate,
• DisableDeletion.

TTL can be modeled through custom deletion logic.

Logging

Use SetLogger to integrate ZoneTree with your application's logging stack, or SetLogLevel to adjust the default console logger.

using ZoneTree.Logger;

using var zoneTree = new ZoneTreeFactory<int, string>()
    .SetDataDirectory("data/app")
    .SetLogLevel(LogLevel.Warning)
    .OpenOrCreate();

Storage Providers

SetRandomAccessDeviceManager controls disk segment storage. SetWriteAheadLogProvider controls WAL storage. The default factory uses local file-system backed providers.

These extension points are advanced. Use them when embedding ZoneTree into a custom storage environment.