API Overview
ZoneTree's API surface is organized around one idea: an ordered durable storage engine that can be used directly or composed into larger systems.
Factory And Opening
ZoneTreeFactory<TKey, TValue>configures and opens a tree.
Common entry points:
OpenOrCreateCreateOpenOpenOrCreateTransactionalCreateTransactionalOpenTransactionalRestoreFromLatestLiveBackupRestoreFromLiveBackupGeneration
Common configuration methods:
SetDataDirectorySetWriteAheadLogDirectorySetComparerSetKeySerializerSetValueSerializerSetMutableSegmentMaxItemCountSetDiskSegmentMaxItemCountConfigureConfigureWriteAheadLogOptionsConfigureDiskSegmentOptionsSetRandomAccessDeviceManagerSetWriteAheadLogProviderSetTransactionLog
The factory fills known serializers and comparers for supported common types when they are not explicitly configured.
Core Tree
IZoneTree<TKey, TValue>is the main non-transactional interface.
Read methods:
TryGetContainsKeyCountCountFullScan
Write methods:
UpsertTryAddTryDeleteForceDelete
Successful mutating operations return an operation index. The operation index is useful for replay, audit, and replication pipelines as a per-key freshness token.
Atomic Methods
Atomic methods synchronize same-key read-modify-write operations across LSM-tree segments.
Important methods:
TryAtomicGetAndUpdateTryAtomicAddTryAtomicUpdateTryAtomicAddOrUpdateAtomicUpsert
Use atomic methods when the next value depends on the current value of the same key. Use regularUpsertfor simple inserts and replacements.
Transactions
Transactional trees coordinate multi-key changes.
Important areas:
BeginTransactionBeginFluentTransaction- read/write methods with transaction id
PreparePrepareAndCommitCommitRollbackReadCommittedTryGetUpsertAutoCommitDeleteAutoCommit- exceptionless transaction APIs
- fluent transaction APIs
Use transactions when several keys must change together. For one-key counters or compare-and-set behavior, atomic methods are usually the smaller tool.
Iterators
Iterators scan keys in comparer order or reverse comparer order.
Important methods:
CreateIteratorCreateReverseIteratorSeekNext
Iterator modes:
IteratorType.AutoRefreshIteratorType.NoRefreshIteratorType.SnapshotIteratorType.ReadOnlyRegion
Useful options:
includeDeletedRecordscontributeToTheBlockCache
Iterators are central to range scans, prefix layouts, exports, rebuilds, backup internals, and system-building workflows.
Maintenance
Maintenance APIs expose segment lifecycle operations, counters, and events.
UseCreateMaintainer()for standard background maintenance.
Important counters:
MutableSegmentRecordCountReadOnlySegmentsCountReadOnlySegmentsRecordCountInMemoryRecordCountTotalRecordCountIsMergingIsBottomSegmentsMerging
Important operations:
MoveMutableSegmentForwardStartMergeOperationStartBottomSegmentsMergeOperationSaveMetaDataReleaseReadBuffersReleaseCircularKeyCacheRecordsReleaseCircularValueCacheRecords
Important events:
OnMutableSegmentMovedForwardOnMergeOperationStartedOnMergeOperationEndedOnBottomSegmentsMergeOperationStartedOnBottomSegmentsMergeOperationEndedOnDiskSegmentCreatedOnDiskSegmentActivated- failed drop events.
These APIs are useful for services that want dashboards, custom maintenance windows, backup triggers, or storage-placement decisions.
Backup And Restore
Live backup APIs create complete backup generations while a built-in non-transactional ZoneTree remains open.
Important types:
LiveBackup<TKey, TValue>LiveBackupOptionsLiveBackupScheduleLocalLiveBackupProviderLocalLiveBackupOptionsILiveBackupStoreILiveBackupSource
Important methods:
CreateLiveBackupCreateGenerationAsyncStartStopWaitForLiveBackupAsyncRestoreFromLatestLiveBackupRestoreFromLiveBackupGeneration
ILiveBackupStoreis the write side.ILiveBackupSourceis the restore side. The local provider implements both.
Recovery And Low-Level Loading
ZoneTree also exposes public low-level recovery building blocks for tools and advanced systems:
ZoneTreeLoader<TKey, TValue>ZoneTreeMetaWAL<TKey, TValue>DiskSegmentFactoryMutableSegmentLoader<TKey, TValue>ReadOnlySegmentLoader<TKey, TValue>IWriteAheadLog<TKey, TValue>.ReadLogEntries
Use these APIs when building repair tools, migration tools, offline inspection, custom restore flows, or storage services. Load persisted metadata or provide equivalent factory configuration so the same comparer, serializers, providers, and options are used.
Storage Extension Points
ZoneTree can be embedded into custom storage environments.
Important extension points:
IFileStreamProviderIRandomAccessDeviceManagerIRandomAccessDeviceIWriteAheadLogProviderIWriteAheadLog<TKey, TValue>ITransactionLog<TKey, TValue>
The default factory path uses local file-system backed providers. Custom providers can redirect WALs, random-access disk segments, or backup generations into a different storage environment.
Replication Helper
Replicator<TKey, TValue>is a small helper for applying upserts by operation index. It keeps a companion ZoneTree of latest operation indexes per key and applies an incoming upsert only when the incoming operation index is fresh enough for that key.
It is a useful building block for replay pipelines, but the application still owns transport, ordering between unrelated keys, retries, conflict policy, and topology.