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.

Memory

MutableSegmentMaxItemCountcontrols when the active mutable segment is moved forward.

The default is1_000_000records. 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, circular key/value caches, sparse arrays, multipart sizing, and merge behavior.

Tune disk options with the actual read/write pattern.

Important options:

The default disk profile uses multipart disk segments,20_000_000as the disk segment max item count,1_500_000to3_000_000records per multipart part,4 MBdisk compression blocks, LZ4 fastest compression,1024sparse array step size, and1024key/value cache entries with10 secondlifetimes.

The decompressed block cache is not configured byDiskSegmentOptions. Disk compression block size is configured here, but inactive decompressed block cleanup is controlled by the maintainer.

WAL

WAL options control durability, compression, and backup behavior.

The default WAL mode isWriteAheadLogMode.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:

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

The default WAL profile uses async compressed WAL,256 KBcompression blocks, LZ4 fastest compression, and a100 msasync 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();

Live Backup

Live backup is configured withLiveBackupOptions.

Important options:

The local implementation is configured withLocalLiveBackupOptions:

Live backup is exposed for built-in non-transactional ZoneTree instances. Transactional trees need a transaction-aware backup design that captures transaction-log state together with storage-engine state.

Maintenance

The maintainer controls background merge work and inactive cache cleanup. Inactive cache cleanup releases decompressed disk blocks and expired circular key/value cache records.

The maintainer created byzoneTree.CreateMaintainer()uses these defaults:

The normalCreateMaintainer()path starts the cleanup job by default. LongerBlockCacheLifeTimecan improve repeated disk reads but retains more decompressed blocks in memory.

Deletion

Deletion behavior is configured with:

• SetIsDeletedDelegate,
• SetMarkValueDeletedDelegate,
• DisableDeletion.

TTL can be modeled through custom deletion logic.

Logging

UseSetLoggerto integrate ZoneTree with your application's logging stack, orSetLogLevelto adjust the default console logger.

using ZoneTree.Logger;

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

Storage Providers

SetRandomAccessDeviceManagercontrols disk segment storage.SetWriteAheadLogProvidercontrols 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.