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

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, 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_000 as the disk segment max item count, 1_500_000 to 3_000_000 records per multipart part, 4 MB disk compression blocks, Zstd level 0 compression, 1024 sparse array step size, and 1024 key/value cache entries with 10 second lifetimes.

The decompressed block cache is not configured by DiskSegmentOptions. 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 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:

Use the default async compressed WAL as the starting point for most persistent data. Use Sync WAL when the application specifically needs the plain synchronous WAL path. Use sync-compressed WAL when the compressed WAL tradeoff is acceptable. Use No WAL only for cache, temporary, or intentionally rebuildable data.

The default WAL profile uses async compressed WAL, 256 KB compression blocks, Zstd level 0 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();

Live Backup

Live backup is configured with LiveBackupOptions.

Important options:

The local implementation is configured with LocalLiveBackupOptions:

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 by zoneTree.CreateMaintainer() uses these defaults:

The normal CreateMaintainer() path starts the cleanup job by default. Longer BlockCacheLifeTime can 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

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.