Configuration Reference

ZoneTreeFactory<TKey, TValue> owns the configuration used to create or open a tree. Configure components and options before calling an open method.

Factory Entry Points

Known key/value types receive default serializers and, where applicable, comparers and key hashers. Custom types require explicit compatible components.

Core Defaults

The public property identifiers BTreeLockMode, BTreeNodeSize, and BTreeLeafSize configure ZoneTree's mutable B+Tree.

Key Components

Metadata records all four component type names. On open, ZoneTree validates the comparer and serializer types, but it does not currently reject a changed key-hasher type. A comparer-order or serializer-format change is a storage migration even when the .NET type name stays the same. A replacement hasher does not change persisted data, but it must remain compatible with comparer equality.

Mutable-Segment Bloom Filter

The filter is sized from MutableSegmentMaxItemCount and MutableSegmentBloomFilterBitsPerItem. Allocation rounds up to a power of two and is capped at 2^30 bits.

using var zoneTree = new ZoneTreeFactory<long, string>()
    .SetMutableSegmentMaxItemCount(500_000)
    .SetMutableSegmentBloomFilterBitsPerItem(8)
    .OpenOrCreate();

Use 0 bits per item to disable the filter. A larger value is not free: it increases memory and does not eliminate comparer-based lookup after a possible match.

See mutable-segment Bloom filters for sizing, false-positive behavior, and hasher requirements.

WAL Defaults

WAL options apply when new WALs are created. Existing WALs retain their stored options. The modes have different caller acknowledgment and failure boundaries; read WAL modes before changing them.

Disk-Segment Defaults

Materialized chunks contain 16 aligned entries, so the default permits at most 65,536 cached materialized positions in one decompressed block. Actual memory depends on key/value shape and accessed positions.

using var zoneTree = new ZoneTreeFactory<long, string>()
    .ConfigureDiskSegmentOptions(options =>
    {
        options.DefaultSparseArrayStepSize = 512;
        options.MaterializedEntryCacheSize = 2048;
        options.SearchHintPrefetchSize = 16;
    })
    .OpenOrCreate();

The active disk-segment options are persisted in ZoneTree metadata. Individual segment files also retain the physical format information required to read their stored representation.

Iterator Defaults

Iterator options are per iterator and are not persisted.

Maintainer Defaults

The maintainer owns runtime jobs and cache cleanup rather than persisted tree options. Important defaults include a one-minute inactive block lifetime and a 30-second inactive-block cleanup interval.

using var maintainer = zoneTree.CreateMaintainer();

maintainer.BlockCacheLifeTime = TimeSpan.FromMinutes(1);
maintainer.InactiveBlockCacheCleanupInterval = TimeSpan.FromSeconds(30);

These settings apply to a created maintainer. The zoneTree.Maintenance API exposes state, events, and operations for custom maintenance policy.

Validation

The factory validates required components, enum values, compression compatibility, numeric ranges, multipart bounds, and a common case-insensitive string comparer/hasher mismatch.

AllowUnsafeOptionValues bypasses numeric range checks for advanced or test configurations. It does not make invalid component combinations safe and should not be a production tuning shortcut.

Complete Configuration Example

using ZoneTree;
using ZoneTree.Options;
using ZoneTree.WAL;

using var zoneTree = new ZoneTreeFactory<long, string>()
    .SetDataDirectory("data/app")
    .SetMutableSegmentMaxItemCount(500_000)
    .SetMutableSegmentBloomFilterBitsPerItem(8)
    .ConfigureWriteAheadLogOptions(options =>
    {
        options.WriteAheadLogMode = WriteAheadLogMode.AsyncCompressed;
    })
    .ConfigureDiskSegmentOptions(options =>
    {
        options.DiskSegmentMode = DiskSegmentMode.MultiPartDiskSegment;
        options.MaterializedEntryCacheSize = 4096;
        options.SearchHintPrefetchSize = 16;
    })
    .OpenOrCreate();

using var maintainer = zoneTree.CreateMaintainer();

See disk-segment tuning, read-path caching, and key components.