Resize

This page is part of the documentation for Orleans.Lattice 9.9.0 (release line 9.9), built 2026-10-04. It is also published as markdown, with every table and list, at README.md, and llms.txt lists every page.

What it shows

ILattice.ResizeAsync changes a tree's structural sizing (MaxLeafKeys / MaxInternalChildren) on a tree that already holds data. It runs online: reads and writes stay available while it drains the source into a freshly-sized destination tree (shadow-forwarding plain writes - typed CRDT deltas and streaming bulk appends are not forwarded) and atomically swaps the alias. The copy follows the tree's shard map, so every live entry is carried over, including one on a shard an adaptive split added - see the feature doc for the limits. This sample populates a tree with 500 entries (hashed across the default 64 shards, so each shard's root is still a single leaf), resizes its leaf capacity from the default 128 to 256 and its internal fan-out from the default 128 to 64, polls IsResizeCompleteAsync until the swap finishes, and confirms the data survived and the tree is still writable.

Run it

dotnet run --project samples/Resize

Expected output

(The resize duration varies run to run.)

== Resize sample ==

Populated 'catalog' with 500 entries (default MaxLeafKeys=128).

Calling ResizeAsync(newMaxLeafKeys: 256, newMaxInternalChildren: 64)...
Resize completed in 6.7s.

CountAsync after resize -> 500 (unchanged).
item:0250 = value-250
item:new  = post-resize (written after the resize)
-> same tree, wider leaves, data intact and still writable.

Done.

When to use

• The current fan-out no longer suits the workload (e.g. leaves are too small for the value sizes or access pattern) and you need to re-paginate an existing, populated tree without taking it offline.
• To start a brand-new tree with non-default sizing: call ResizeAsync on the empty tree, which hits the in-place empty-tree fast path.

When not to use

• Changing the shard count - that requires re-hashing keys and is done with ReshardAsync, not ResizeAsync.
• Casually or on the hot path. A resize on a populated tree copies the whole tree and adds a forward hop to every plain write until the swap. After the alias swap the resize soft-deletes the retired copy rather than purging it, so storage stays at roughly 2x until the soft-delete window (LatticeOptions.SoftDeleteDuration, 72 hours by default, during which UndoResizeAsync can still restore it) elapses; prefer an off-peak window for large trees.

Feature doc

docs/lattice/tree-sizing.md