# Refinement > USearch for C `usearch_dense_refine` re-selects the neighbors of every stored entry against the finished graph, improving those chosen while the graph around them was incomplete. A cheap insertion pass followed by one refinement reaches a better graph in less total time than one expensive pass, so a wide `expansion_factor` belongs here rather than in `usearch_dense_insert`. Re-selection is idempotent and claims no identity, so a cancelled pass leaves the graph correct and merely less improved, still re-links any entry no search would reach, and answers `usearch_status_cancelled_k`. The index keeps nothing of a stopped pass, so a caller looping until the graph settles calls again: ```c size_t changed = 0; do { usearch_dense_refine(&(usearch_dense_refine_t) {.index = index, .executor = executor, .outcome = &outcome, .changed = &changed, .expansion_factor = 256}); } while (outcome.status == usearch_status_success_k && changed > 100); ``` Searches may run throughout on a RAM handle, while a VRAM handle rewrites neighbors in place and admits no overlapping search. Insertions never overlap a refinement: one running refuses it with `usearch_status_contended_k`, one arriving meanwhile is refused the same way and lands nothing, and so on VRAM is a save, which holds the handle the same way for its own duration. Nothing waits, so a service schedules refinements between its insertion bursts and retries a refused call. A refinement that must continue where a cancel stopped is a handle the caller holds instead. `usearch_dense_refinement_init` opens it, optionally absorbing donors first, and the index refuses insertions and saves until it is finished. Each `usearch_dense_refinement_next` continues it on the executor it was opened with, holding that executor only for the call, and answers `usearch_status_cancelled_k` while more is left. It reports the running totals, the nodes re-selected so far, those whose neighbors changed, and the telemetry, so a caller stops calling once the changed share stops paying for another call. `usearch_dense_refinement_finish` re-links what a stopped pass leaves, reports, reopens the index and frees the handle. ### Absorbing & Splitting `usearch_dense_absorb` moves an array of donor handles into one index, one donor after another, keeping their graphs rather than re-inserting their vectors. Donors are consumed and nulled as they go, so the array itself says which handles the caller still owns and must free, and a cancel stops only the closing refinement, answering `usearch_status_cancelled_k`. Each donor's shards append to the index's as appended parts with their edges rebased, then a refinement of every shard that took one walks each of its nodes across into the other part from landmarks drawn there and re-selects it, so a group costs one such refinement per donor, and its heal re-selects from the landmarks every node no earlier one links to. A donor must share the index's residency, scalar, class, metric and geometry, else the call answers `usearch_status_config_mismatch_k`, and an NVMe view answers `usearch_status_read_only_k`. An insertion running on the index or on the next donor refuses the call with `usearch_status_contended_k`, leaving that donor and the rest live, and an insertion into the index arriving meanwhile is refused the same way, while nothing may search a donor or start an insertion into it. A VRAM-built donor joins a RAM index through a save and a load. `usearch_dense_split` is the inverse, emptying one index into `count` receivers, empty handles of its residency, scalar, class, metric, geometry and shard count. It grows one graph-local part per receiver from roots drawn from `seed`, breadth-first over the links and capped at an equal share, lands part `p` of shard `s` in shard `s` of receiver `p` with edges rebased and edges across parts dropped, and refines the nodes that lost an edge. `usearch_dense_refinement_init` takes `receivers` in place of `donors` for the resumable form, never both, refusing the pair with `usearch_status_invalid_argument_k`. RAM and NVIDIA and AMD VRAM indexes split, Apple and NVMe ones answer `usearch_status_unsupported_k` and `usearch_status_read_only_k`, and the stand-in partitions by brute force. `#include ` `#include ` `#include ` `#include ` `#include ` ## usearch_dense_refinement_t One refinement in flight, optionally absorbing donors or splitting into receivers first. ```c typedef struct usearch_dense_refinement_handle_t * usearch_dense_refinement_t; ``` It holds everything the pass needs between calls, so a cancelled [`usearch_dense_refinement_next`](#usearch_dense_refinement_next) continues where it stopped, and nothing about it stays in the index once it finishes. The index admits no insertion and no save while the handle lives; searches proceed as during [`usearch_dense_refine`](#usearch_dense_refine). Each call names the index and the executor it was opened with. ## usearch_geospatial_refinement_t One refinement in flight, optionally absorbing donors or splitting into receivers first. ```c typedef struct usearch_geospatial_refinement_handle_t * usearch_geospatial_refinement_t; ``` It holds everything the pass needs between calls, so a cancelled [`usearch_geospatial_refinement_next`](#usearch_geospatial_refinement_next) continues where it stopped, and nothing about it stays in the index once it finishes. The index admits no insertion and no save while the handle lives; searches proceed as during [`usearch_geospatial_refine`](#usearch_geospatial_refine). Each call names the index and the executor it was opened with. ## usearch_sequence_refinement_t One refinement in flight, optionally absorbing donors or splitting into receivers first. ```c typedef struct usearch_sequence_refinement_handle_t * usearch_sequence_refinement_t; ``` It holds everything the pass needs between calls, so a cancelled [`usearch_sequence_refinement_next`](#usearch_sequence_refinement_next) continues where it stopped, and nothing about it stays in the index once it finishes. The index admits no insertion and no save while the handle lives; searches proceed as during [`usearch_sequence_refine`](#usearch_sequence_refine). Each call names the index and the executor it was opened with. ## usearch_shapes_refinement_t One refinement in flight, optionally absorbing donors or splitting into receivers first. ```c typedef struct usearch_shapes_refinement_handle_t * usearch_shapes_refinement_t; ``` It holds everything the pass needs between calls, so a cancelled [`usearch_shapes_refinement_next`](#usearch_shapes_refinement_next) continues where it stopped, and nothing about it stays in the index once it finishes. The index admits no insertion and no save while the handle lives; searches proceed as during [`usearch_shapes_refine`](#usearch_shapes_refine). Each call names the index and the executor it was opened with. ## usearch_refine_report_t What one refinement-family call did to the graph, counted alike in every modality and residency: `refine`, `absorb`, `compact`, `split` and `refinement_finish` land it. ```c struct usearch_refine_report_t ``` `changed` never exceeds `reselected`, and a pass over a settled graph changes nothing. A call that fails before its closing audit reports zeros; one its progress handler stopped still heals, so its report stands beside the [`usearch_status_cancelled_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_cancelled_k) it answers. - `reselected` `size_t`: Entries whose neighbors were selected again: the planned entries, then the fresh entries of every later round, then the islands of every heal round. - `changed` `size_t`: Of those, the entries whose neighbor set gained a member it lacked; order never counts, nor does a back-link re-selecting an entry the pass did not. - `islands_found` `size_t`: Entries the first audit found not reached both ways, counted once. - `islands_reconnected` `size_t`: Links written between an island and an entry the audit reached both ways, summed across the heal's audits. - `reachability` `usearch_reachability_t`: The audit closing the heal, as a fresh `health` call right after would take it. ## usearch_refine_options_t How a pass over the graph may spend, shared by every verb that refines. ```c struct usearch_refine_options_t ``` - `expansion_factor` `size_t`: The __optional__ breadth of the candidates a re-selection walk explores; zero derives. - `memory_limit` `size_t`: The __optional__ bytes the pass may hold beyond the index; its tiles of rows are sized from them, and zero takes one storage chunk per tile, or on VRAM half of the free device bytes. ## usearch_*_refine Re-selects the neighbors of every stored entry against the finished graph, improving neighbors chosen when the graph around them was still incomplete. ```c void usearch_dense_refine(usearch_dense_refine_t *arguments); ``` - `usearch_dense_refine`: index `usearch_dense_index_t` - `usearch_geospatial_refine`: index `usearch_geospatial_index_t` - `usearch_sequence_refine`: index `usearch_sequence_index_t` - `usearch_shapes_refine`: index `usearch_shapes_index_t` This is a build step rather than a repair. A cheap insertion pass followed by one refinement reaches a better graph, in less total time, than a single expensive insertion pass - so a wide `refine.expansion_factor` belongs here rather than in [`usearch_dense_insert`](https://www.unum.cloud/docs/usearch/c/inputs-and-outputs.md#usearch_dense_insert). Cancelling is safe, which is what makes a whole-graph sweep affordable. Re-selecting a node's neighbors is idempotent and claims no identity, so a stopped pass leaves the graph correct and merely less improved: nothing unwinds, and the call answers [`usearch_status_cancelled_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_cancelled_k). The index keeps nothing of a stopped pass, so the next call starts at the first entry again; a caller wanting to continue where a cancel stopped holds a `[usearch_dense_refinement_t](#usearch_dense_refinement_t)` instead. A caller loops until the report's `changed` falls below whatever change rate they consider settled. Re-selection alone can leave an island, an entry no search reaches, so every call closes by re-linking them: unreachable entries re-select from scratch, and whatever the diversity judgment still drops is reconnected to a reachable one. A cancelled call skips the rest of the re-selection but still re-links, so it never leaves entries unreachable. On a RAM handle searches may run throughout: re-selection publishes one node at a time and never removes a node, so a concurrent walk sees either the old neighbors or the new ones. On a VRAM handle the merge writes neighbors in place, so searches may not overlap. Insertions never overlap: one in flight refuses the call with [`usearch_status_contended_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_contended_k), and one arriving meanwhile is refused the same way, as is a VRAM save. A viewed handle refuses with [`usearch_status_read_only_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_read_only_k), like every other mutating verb. This is a build step rather than a repair. A cheap insertion pass followed by one refinement reaches a better graph, in less total time, than a single expensive insertion pass - so a wide `refine.expansion_factor` belongs here rather than in [`usearch_geospatial_insert`](https://www.unum.cloud/docs/usearch/c/inputs-and-outputs.md#usearch_geospatial_insert). A refined entry keeps its cone winners and the longest of its other candidates, then has its long links drawn again by the insertion's rule, so a refine never leaves an entry without them. Cancelling is safe, which is what makes a whole-graph sweep affordable. Re-selecting an entry's neighbors is idempotent and claims no identity, so a stopped pass leaves the graph correct and merely less improved: nothing unwinds, and the call answers [`usearch_status_cancelled_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_cancelled_k). The index keeps nothing of a stopped pass, so the next call starts at the first entry again; a caller wanting to continue where a cancel stopped holds a `[usearch_geospatial_refinement_t](#usearch_geospatial_refinement_t)` instead. Re-selection alone can leave an island, an entry no search reaches, so every call closes by re-linking them: unreachable entries re-select from scratch, and whatever the selection still drops is reconnected to a reachable one. A cancelled call skips the rest of the re-selection but still re-links, so it never leaves entries unreachable. Searches may run throughout: re-selection rewrites one entry at a time and never removes one, so a concurrent walk sees either the old neighbors or the new ones. Insertions never overlap: one in flight refuses the call with [`usearch_status_contended_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_contended_k), and one arriving meanwhile is refused the same way, as is a save. This is a build step rather than a repair. A cheap insertion pass followed by one refinement reaches a better graph, in less total time, than a single expensive insertion pass - so a wide `refine.expansion_factor` belongs here rather than in [`usearch_sequence_insert`](https://www.unum.cloud/docs/usearch/c/inputs-and-outputs.md#usearch_sequence_insert). It pays most in this modality, where a single alignment is quadratic and a stingy insertion pass is tempting. Cancelling is safe, which is what makes a whole-graph sweep affordable. Re-selecting an entry's neighbors is idempotent and claims no identity, so a stopped pass leaves the graph correct and merely less improved: nothing unwinds, and the call answers [`usearch_status_cancelled_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_cancelled_k). The index keeps nothing of a stopped pass, so the next call starts at the first entry again; a caller wanting to continue where a cancel stopped holds a `[usearch_sequence_refinement_t](#usearch_sequence_refinement_t)` instead. Re-selection alone can leave an island, an entry no search reaches, so every call closes by re-linking them: unreachable entries re-select from scratch, and whatever the selection still drops is reconnected to a reachable one. A cancelled call skips the rest of the re-selection but still re-links, so it never leaves entries unreachable. Searches may run throughout: re-selection rewrites one entry at a time and never removes one, so a concurrent walk sees either the old neighbors or the new ones. Insertions never overlap: one in flight refuses the call with [`usearch_status_contended_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_contended_k), and one arriving meanwhile is refused the same way, as is a save. This is a build step rather than a repair. A cheap insertion pass followed by one refinement reaches a better graph, in less total time, than a single expensive insertion pass - so a wide `refine.expansion_factor` belongs here rather than in [`usearch_shapes_insert`](https://www.unum.cloud/docs/usearch/c/inputs-and-outputs.md#usearch_shapes_insert). It pays most in this modality, where one comparison scores a whole shape against another. Cancelling is safe, which is what makes a whole-graph sweep affordable. Re-selecting an entry's neighbors is idempotent and claims no identity, so a stopped pass leaves the graph correct and merely less improved: nothing unwinds, and the call answers [`usearch_status_cancelled_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_cancelled_k). The index keeps nothing of a stopped pass, so the next call starts at the first entry again; a caller wanting to continue where a cancel stopped holds a `[usearch_shapes_refinement_t](#usearch_shapes_refinement_t)` instead. Re-selection alone can leave an island, an entry no search reaches, so every call closes by re-linking them: unreachable entries re-select from scratch, and whatever the selection still drops is reconnected to a reachable one. A cancelled call skips the rest of the re-selection but still re-links, so it never leaves entries unreachable. Searches may run throughout: re-selection rewrites one entry at a time and never removes one, so a concurrent walk sees either the old neighbors or the new ones. Insertions never overlap: one in flight refuses the call with [`usearch_status_contended_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_contended_k), and one arriving meanwhile is refused the same way, as is a save. - `index`: The handle to be refined. - `executor`: The executor to fan out over; its kind must match the residency. - `outcome`: Output for the outcome, final once its status leaves [`usearch_status_deferred_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_deferred_k). - `completion`: Blocking, the default, or deferred. - `report`: The __optional__ output for what the call did to the graph, as `[usearch_refine_report_t](#usearch_refine_report_t)` counts it; `NULL` skips reporting. - `refine`: The __optional__ breadth and bytes of the re-selection pass. - `progress`: The __optional__ handler, called with nodes re-selected; a cancel stops the re-selection, still heals, and answers [`usearch_status_cancelled_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_cancelled_k). - `stats`: The __optional__ traversal telemetry; `NULL` skips reporting. Statuses: - [`usearch_status_device_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_device_k) The executor's kind does not match the residency. - [`usearch_status_read_only_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_read_only_k) The handle is an NVMe view. - [`usearch_status_uninitialized_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_uninitialized_k) No shard is placed, the executor holds no threads, or a VRAM handle keeps such an earlier failure. - [`usearch_status_contended_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_contended_k) An insertion, load, save, refinement or absorption holds the handle, or another call holds the executor or its pool. - [`usearch_status_config_mismatch_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_config_mismatch_k) The executor drives no stream on some VRAM shard's device, or a VRAM handle keeps such an earlier failure. - [`usearch_status_overflow_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_overflow_k) A queue capacity wraps when rounded, or a VRAM handle keeps an earlier overflow. - [`usearch_status_unsupported_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_unsupported_k) or [`usearch_status_unsupported_layout_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_unsupported_layout_k) A VRAM handle keeps such an earlier failure. Statuses: - [`usearch_status_read_only_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_read_only_k) The handle is an NVMe view. - [`usearch_status_unsupported_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_unsupported_k) The handle lives on a GPU, whose index refines nothing yet. - [`usearch_status_contended_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_contended_k) An insertion or another refinement holds the handle. ## usearch_dense_absorb Absorbs every handle in `donors` into `index`, one after another, keeping their graphs rather than re-inserting their vectors and linking each in by walks across. ```c void usearch_dense_absorb(usearch_dense_absorb_t *arguments); ``` Donor handles are consumed and must not be used afterwards, not even for [`usearch_dense_free`](https://www.unum.cloud/docs/usearch/c/residency.md#usearch_dense_free). The donors land one after another, each all-or-nothing: its entries append to `index` shard by shard with their edges rebased, publish at once, and the donor is consumed, so at most one donor's entries are ever held twice. One refinement then walks every shard across the parts the donors appended, round by round, so a group of donors costs one refinement rather than one per donor. Readers of a RAM `index` may keep searching throughout, since unpublished entries hide behind the watermark, while a VRAM one rewrites neighbors in place and admits no overlapping search, as refinement does. Insertions into `index` or into a donor arriving meanwhile are refused with [`usearch_status_contended_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_contended_k), while searches of a donor run throughout. A failure leaves the donor it struck and every later one as live handles the caller still owns and must free, and `index` holding the donors before it; every consumed slot is nulled, so the array itself says which handles survived. The handler reports and cancels the closing refinement alone, exactly as in `usearch_dense_refine:` a cancel skips the rest of the walks across, still re-links, and answers [`usearch_status_cancelled_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_cancelled_k) with every donor consumed. A caller wanting to continue those walks later holds a `[usearch_dense_refinement_t](#usearch_dense_refinement_t)` instead. ``` usearch_dense_index_t shards[4] = {built_on_socket_0, built_on_socket_1, built_on_socket_2, built_on_socket_3}; usearch_outcome_t outcome = {0}; usearch_dense_absorb(&(usearch_dense_absorb_t){ .index = index, .executor = executor, .outcome = &outcome, .count = 4, .donors = shards, .progress = {report_to_terminal, &ui, 4}}); // Every entry of `shards` is consumed here; none of them may be freed afterwards. ``` - `index`: The handle absorbing the donors. - `executor`: The executor each donor's move and the closing refinement fan out over. - `outcome`: Output for the outcome, final once its status leaves [`usearch_status_deferred_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_deferred_k). - `completion`: Blocking, the default, or deferred. - `count`: Donor handles to absorb. - `donors`: Array of `count` handles, each consumed and nulled once its entries are published here. - `report`: The __optional__ output for what the call did to the graph, as `[usearch_refine_report_t](#usearch_refine_report_t)` counts it; `NULL` skips reporting. - `refine`: The __optional__ breadth and bytes of the closing refine. - `progress`: The __optional__ handler, called with the donor rows stitched so far out of every donor's; a cancel stops the stitching walks as it stops [`usearch_dense_refine`](#usearch_dense_refine), never a move. - `stats`: The __optional__ traversal telemetry; `NULL` skips reporting. Statuses: - [`usearch_status_read_only_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_read_only_k) `index` is an NVMe view. - [`usearch_status_invalid_argument_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_invalid_argument_k) A `NULL` slot in `donors`, or `NULL` `donors` for a nonzero `count`. - [`usearch_status_config_mismatch_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_config_mismatch_k) A donor of another residency, scalar, class, metric or geometry, a donor on a device the executor does not drive, or `index` itself. - [`usearch_status_contended_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_contended_k) An insertion in flight on `index` or on the next donor, or on VRAM a save of either; that donor and every later one stay live handles. ## usearch_dense_compact Compacts every shard of the handles in `sources` into `target` under `shard_capacity` entries per shard, largest first, each into the first shard with room, so it ends with as few shards as fit; in place when `target` is among `sources`. ```c void usearch_dense_compact(usearch_dense_compact_t *arguments); ``` The shard a bin keeps stays resident with its IDs, every other source shard follows it with its edges rebased and its keys beside it, and only the appended entries walk the target across the parts and link in, then each target shard re-links the islands that leaves, as [`usearch_dense_refine`](#usearch_dense_refine) does. In place, a moved entry's key moves with one atomic store, so lookups and searches of `target` run throughout and emptied shards stay as idle slots for its next generation. Once the call moved every source, each one but `target` is freed and nulled, as [`usearch_dense_absorb`](#usearch_dense_absorb) frees its donors; a failure frees none, those it consumed left empty and refusing insertions, so every handle in `sources` stays the caller's to free. - `target`: The handle the sources compact into, possibly one of them. - `executor`: The executor every move and the closing refinement fan out over. - `outcome`: Output for the outcome, final once its status leaves [`usearch_status_deferred_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_deferred_k). - `completion`: Blocking, the default, or deferred. - `count`: Source handles to compact. - `sources`: Array of `count` distinct handles; each but `target` is freed and nulled once every source moved. - `shard_capacity`: The __optional__ most entries one target shard holds; zero, or more than the target's own bound, means that bound. - `refine`: The __optional__ breadth and bytes of the closing refine. - `report`: The __optional__ output for what the call did to the graph, as `[usearch_refine_report_t](#usearch_refine_report_t)` counts it; `NULL` skips reporting. - `progress`: The __optional__ handler, called with nodes the closing refine re-selected; a cancel stops it as it stops [`usearch_dense_refine`](#usearch_dense_refine), never a move. - `stats`: The __optional__ traversal telemetry; `NULL` skips reporting. Statuses: - [`usearch_status_read_only_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_read_only_k) `target` is an NVMe view. - [`usearch_status_invalid_argument_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_invalid_argument_k) A `NULL` slot in `sources`, or `NULL` `sources` for a nonzero `count`. - [`usearch_status_config_mismatch_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_config_mismatch_k) A repeated source, or one of another residency, scalar, class, metric or geometry. - [`usearch_status_contended_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_contended_k) An insertion in flight on `target` or a source, or another call holding either; nothing moves. - [`usearch_status_unsupported_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_unsupported_k) A source shard past `shard_capacity`, which would have to be cut first, or a target outside RAM. ## usearch_dense_split Splits `index` into the handles in `receivers`, the inverse of `usearch_dense_absorb:` graph-local parts keeping their edges rather than re-inserting their vectors, one part per receiver, and `index` left empty but live. ```c void usearch_dense_split(usearch_dense_split_t *arguments); ``` Every receiver is checked and held before the first part moves, so a refusal moves nothing. The part roots are drawn from `seed` without a scan, and each part grows breadth-first over the links from its root, capped at an equal share of the entries, while entries no root reaches enter the smallest part. A sharded handle splits shard by shard, part `p` of shard `s` moving into shard `s` of receiver `p`. Each part then enters its receiver all-or-nothing, its edges rebased, its edges into other parts dropped, and the entries that lost one placed first; `index` clears once every part moved. Each receiver closes by re-selecting the entries that lost an edge and re-linking the islands that leaves, as [`usearch_dense_refine`](#usearch_dense_refine) does. Meanwhile, insertions into `index` or a receiver are refused with [`usearch_status_contended_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_contended_k), while searches of either run throughout. The handler reports and cancels the closing refinements alone, exactly as in `usearch_dense_refine:` a cancel skips the rest of the re-selection, still re-links, and answers [`usearch_status_cancelled_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_cancelled_k) with every part moved. A caller wanting to continue that re-selection later holds a `[usearch_dense_refinement_t](#usearch_dense_refinement_t)` opened with `receivers` instead. - `index`: The handle split into the receivers, left empty and live. - `executor`: The executor the partition, each part's move and the closing refinements fan out over. - `outcome`: Output for the outcome, final once its status leaves [`usearch_status_deferred_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_deferred_k). - `completion`: Blocking, the default, or deferred. - `count`: Receiver handles to split into, at least two. - `receivers`: Array of `count` empty handles of the source's residency, scalar, class, metric, geometry and shard count, each receiving one part. - `report`: The __optional__ output for what the call did to the graph, as `[usearch_refine_report_t](#usearch_refine_report_t)` counts it; `NULL` skips reporting. - `refine`: The __optional__ breadth and bytes of the closing refines. - `seed`: Picks the part roots: equal seeds over an unchanged index split equally. - `progress`: The __optional__ handler, called with nodes the closing refines re-selected; a cancel stops them as it stops [`usearch_dense_refine`](#usearch_dense_refine), never a move. - `stats`: The __optional__ traversal telemetry; `NULL` skips reporting. Statuses: - [`usearch_status_read_only_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_read_only_k) `index` is an NVMe view. - [`usearch_status_invalid_argument_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_invalid_argument_k) Fewer than two receivers, `NULL` `receivers`, or a `NULL` slot in them. - [`usearch_status_config_mismatch_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_config_mismatch_k) A receiver of another residency, scalar, class, metric, geometry or shard count, one holding entries, one on a device the executor does not drive, one named twice, or `index` itself. - [`usearch_status_contended_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_contended_k) An insertion in flight on `index` or on a receiver, or on VRAM a save of either; nothing moves. - [`usearch_status_overflow_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_overflow_k) A part passes a receiver's capacity or its node IDs. ## usearch_dense_refinement_init Opens a refinement of `index`, absorbing `donors` first when any are named, as [`usearch_dense_absorb`](#usearch_dense_absorb) moves them, or splitting it into `receivers`, as [`usearch_dense_split`](#usearch_dense_split) fills them. ```c void usearch_dense_refinement_init( usearch_dense_refinement_init_t *arguments); ``` Every allocation the refinement needs happens here or in a move, never in a step. - `index`: The handle to be refined. - `executor`: The executor every call on the refinement runs on; its kind must match the residency. - `outcome`: Output for the outcome, final once its status leaves [`usearch_status_deferred_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_deferred_k). - `completion`: Blocking, the default, or deferred. - `donors`: The __optional__ donors to absorb first, each consumed and nulled once its entries land; the array must outlive the refinement. - `count`: Donor handles in `donors`. - `receivers`: The __optional__ receivers to split `index` into first, as [`usearch_dense_split`](#usearch_dense_split) fills them, each refined in turn; the array must outlive the refinement. - `receivers_count`: Receiver handles in `receivers`, zero or at least two. - `refinement`: Output for the new handle; `NULL` on failure. - `refine`: The __optional__ breadth and bytes of every pass the refinement steps. - `seed`: Picks the part roots when `receivers` are named, as in [`usearch_dense_split`](#usearch_dense_split). Statuses: - [`usearch_status_read_only_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_read_only_k) `index` is an NVMe view. - [`usearch_status_invalid_argument_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_invalid_argument_k) A `NULL` slot in `donors` or `receivers`, `NULL` `donors` for a nonzero `count`, one receiver alone, or donors and receivers both named. - [`usearch_status_config_mismatch_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_config_mismatch_k) A donor or receiver of another residency, scalar, class, metric or geometry, a receiver holding entries, or `index` itself. - [`usearch_status_contended_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_contended_k) An insertion, save or another refinement in flight on `index`, or an insertion on a receiver. - [`usearch_status_unsupported_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_unsupported_k) `receivers` on an Apple GPU handle, whose index does not split anything yet. ## usearch_*_refinement_next Continues the refinement until it ends or `progress` cancels, moving any donors still pending first. ```c void usearch_dense_refinement_next( usearch_dense_refinement_next_t *arguments); ``` - `usearch_dense_refinement_next`: index `usearch_dense_index_t`, refinement `usearch_dense_refinement_t` - `usearch_geospatial_refinement_next`: index `usearch_geospatial_index_t`, refinement `usearch_geospatial_refinement_t` - `usearch_sequence_refinement_next`: index `usearch_sequence_index_t`, refinement `usearch_sequence_refinement_t` - `usearch_shapes_refinement_next`: index `usearch_shapes_index_t`, refinement `usearch_shapes_refinement_t` Answers [`usearch_status_cancelled_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_cancelled_k) when a later call has more to do; that call continues exactly where this one stopped. The executor is held only for the call. Every call reaching the refinement writes the running totals, a cancelled or failed one too, so they only grow from one call to the next and `changed` never exceeds `reselected`; all stay zero while donors are pending. - `index`: The handle the refinement was opened on. - `executor`: The executor the refinement was opened with. - `outcome`: Output for the outcome, final once its status leaves [`usearch_status_deferred_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_deferred_k). - `completion`: Blocking, the default, or deferred. - `refinement`: The refinement to continue. - `progress`: The __optional__ handler, called with nodes re-selected across every call so far. - `reselected`: The __optional__ outputs for the nodes re-selected so far and, of those, the ones whose neighbors changed; their ratio falling is what says another call buys little. - `stats`: The __optional__ traversal telemetry of every call on the refinement so far; `NULL` skips reporting. Statuses: - [`usearch_status_invalid_argument_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_invalid_argument_k) `index` is not the handle the refinement was opened on. - [`usearch_status_contended_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_contended_k) An insertion in flight on the next donor; that donor and every later one stay live handles, and a later call retries them. Statuses: - [`usearch_status_invalid_argument_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_invalid_argument_k) `index` or `executor` is not the one the refinement was opened with. ## usearch_dense_refinement_finish Skips whatever re-selection a stopped refinement left, re-links the islands it leaves as [`usearch_dense_refine`](#usearch_dense_refine) does, reports, reopens the index, and frees the handle. ```c void usearch_dense_refinement_finish( usearch_dense_refinement_finish_t *arguments); ``` A refinement whose donors have not all moved re-links nothing and reports zeros. - `index`: The handle the refinement was opened on. - `executor`: The executor the refinement was opened with. - `outcome`: Output for the outcome, final once its status leaves [`usearch_status_deferred_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_deferred_k). - `completion`: Blocking, the default, or deferred. - `refinement`: The refinement to finish; freed by the call, whatever it answers. - `report`: The __optional__ output for what the call did to the graph, as `[usearch_refine_report_t](#usearch_refine_report_t)` counts it; `NULL` skips reporting. - `stats`: The __optional__ traversal telemetry of every call on the refinement; `NULL` skips reporting. Statuses: - [`usearch_status_invalid_argument_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_invalid_argument_k) `index` is not the handle the refinement was opened on; the handle is still freed. ## usearch_geospatial_absorb Absorbs every handle in `donors` into `index`, one after another, keeping their graphs rather than re-inserting their observations, and links each in by walks across. ```c void usearch_geospatial_absorb(usearch_geospatial_absorb_t *arguments); ``` A consumed donor handle must not be used afterwards, not even for [`usearch_geospatial_free`](https://www.unum.cloud/docs/usearch/c/residency.md#usearch_geospatial_free). Every donor is checked and held before the first one enters, so a refusal consumes none. The donors then enter one after another, each all-or-nothing: its entries append to `index` with their edges rebased, publish at once, and the donor is consumed, so at most one donor's entries are ever held twice. One refinement then walks every entry across the parts the donors appended, round by round, so a group of donors costs one refinement rather than one per donor. Readers of `index` may keep searching throughout, since unpublished entries hide behind the watermark, while nothing may search a donor. Insertions into `index` arriving meanwhile are refused with [`usearch_status_contended_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_contended_k). A donor's terrain stays with it: the observations already carry the ground they were inserted over. The handler reports and cancels the closing refinement alone, exactly as in `usearch_geospatial_refine:` a cancel skips the rest of the walks across, still re-links, and answers [`usearch_status_cancelled_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_cancelled_k) with every donor consumed. A caller wanting to continue those walks later holds a `[usearch_geospatial_refinement_t](#usearch_geospatial_refinement_t)` instead. - `index`: The handle absorbing the donors. - `executor`: The executor each donor's move and the closing refinement fan out over. - `outcome`: Output for the outcome, final once its status leaves [`usearch_status_deferred_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_deferred_k). - `completion`: Blocking, the default, or deferred. - `count`: Donor handles to absorb. - `donors`: Array of `count` handles, each consumed and nulled once its entries are published here. - `report`: The __optional__ output for what the call did to the graph, as `[usearch_refine_report_t](#usearch_refine_report_t)` counts it; `NULL` skips reporting. - `refine`: The __optional__ breadth and bytes of the closing refine. - `progress`: The __optional__ handler, called with the donor rows stitched so far out of every donor's; a cancel stops the stitching walks as it stops [`usearch_geospatial_refine`](#usearch_geospatial_refine), never a move. - `stats`: The __optional__ traversal telemetry; `NULL` skips reporting. Statuses: - [`usearch_status_read_only_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_read_only_k) `index` is an NVMe view. - [`usearch_status_unsupported_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_unsupported_k) `index` lives on a GPU, whose index absorbs nothing yet. - [`usearch_status_invalid_argument_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_invalid_argument_k) A `NULL` slot in `donors`, or `NULL` `donors` for a nonzero `count`. - [`usearch_status_config_mismatch_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_config_mismatch_k) A donor of another residency, class or connectivity, or `index` itself. - [`usearch_status_contended_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_contended_k) An insertion or refinement in flight on `index` or on a donor; every donor stays a live handle. ## usearch_geospatial_split Splits `index` into the handles in `receivers`, the inverse of `usearch_geospatial_absorb:` graph-local parts keeping their edges rather than re-inserting their observations, one part per receiver, and `index` left empty but live. ```c void usearch_geospatial_split(usearch_geospatial_split_t *arguments); ``` Every receiver is checked and held before the first part moves, so a refusal moves nothing. The part roots are drawn from `seed` without a scan, and each part grows breadth-first over the links from its root, capped at an equal share of the entries, while entries no root reaches enter the smallest part. Each part then enters its receiver all-or-nothing, its edges rebased, its edges into other parts dropped, and the entries that lost one placed first; `index` clears once every part moved. Each receiver closes by re-selecting the entries that lost an edge and re-linking the islands that leaves, as [`usearch_geospatial_refine`](#usearch_geospatial_refine) does. Insertions into `index` or a receiver arriving meanwhile are refused with [`usearch_status_contended_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_contended_k), and nothing may search either until the call is final. A receiver keeps its own terrain: the observations already carry the ground they were inserted over. The handler reports and cancels the closing refinements alone, exactly as in `usearch_geospatial_refine:` a cancel skips the rest of the re-selection, still re-links, and answers [`usearch_status_cancelled_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_cancelled_k) with every part moved. A caller wanting to continue that re-selection later holds a `[usearch_geospatial_refinement_t](#usearch_geospatial_refinement_t)` opened with `receivers` instead. - `index`: The handle split into the receivers, left empty and live. - `executor`: The executor the partition, each part's move and the closing refinements fan out over. - `outcome`: Output for the outcome, final once its status leaves [`usearch_status_deferred_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_deferred_k). - `completion`: Blocking, the default, or deferred. - `count`: Receiver handles to split into, at least two. - `receivers`: Array of `count` empty handles of the source's residency, class and connectivity, each receiving one part. - `report`: The __optional__ output for what the call did to the graph, as `[usearch_refine_report_t](#usearch_refine_report_t)` counts it; `NULL` skips reporting. - `refine`: The __optional__ breadth and bytes of the closing refines. - `seed`: Picks the part roots: equal seeds over an unchanged index split equally. - `progress`: The __optional__ handler, called with entries the closing refines re-selected; a cancel stops them as it stops [`usearch_geospatial_refine`](#usearch_geospatial_refine), never a move. - `stats`: The __optional__ traversal telemetry; `NULL` skips reporting. Statuses: - [`usearch_status_read_only_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_read_only_k) `index` is a view. - [`usearch_status_invalid_argument_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_invalid_argument_k) Fewer than two receivers, `NULL` `receivers`, or a `NULL` slot in them. - [`usearch_status_config_mismatch_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_config_mismatch_k) A receiver of another residency, class or connectivity, one holding entries or another shard count, one named twice, or `index` itself. - [`usearch_status_contended_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_contended_k) An insertion or refinement in flight on `index` or on a receiver; nothing moves. - [`usearch_status_overflow_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_overflow_k) A part passes a receiver shard's ceiling. - [`usearch_status_unsupported_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_unsupported_k) `index` lives on a GPU, whose index splits nothing yet. ## usearch_geospatial_refinement_init Opens a refinement of `index`, absorbing `donors` first when any are named, as [`usearch_geospatial_absorb`](#usearch_geospatial_absorb) moves them, or splitting it into `receivers`, as [`usearch_geospatial_split`](#usearch_geospatial_split) fills them. ```c void usearch_geospatial_refinement_init( usearch_geospatial_refinement_init_t *arguments); ``` Every allocation the refinement needs in the index happens here, never in a step. - `index`: The handle to be refined. - `executor`: The executor every call on the refinement runs on; its kind must match the residency. - `outcome`: Output for the outcome, final once its status leaves [`usearch_status_deferred_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_deferred_k). - `completion`: Blocking, the default, or deferred. - `donors`: The __optional__ donors to absorb first, each consumed and nulled once its entries land; the array must outlive the refinement. - `count`: Donor handles in `donors`. - `receivers`: The __optional__ receivers to split `index` into first, as [`usearch_geospatial_split`](#usearch_geospatial_split) fills them, each refined in turn; the array must outlive the refinement. - `receivers_count`: Receiver handles in `receivers`, zero or at least two. - `refinement`: Output for the new handle; `NULL` on failure. - `refine`: The __optional__ breadth and bytes of every pass the refinement steps. - `seed`: Picks the part roots when `receivers` are named, as in [`usearch_geospatial_split`](#usearch_geospatial_split). Statuses: - [`usearch_status_read_only_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_read_only_k) `index` is an NVMe view. - [`usearch_status_unsupported_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_unsupported_k) `index` lives on a GPU, whose index refines nothing yet. - [`usearch_status_invalid_argument_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_invalid_argument_k) No executor, a `NULL` slot in `donors` or `receivers`, `NULL` `donors` for a nonzero `count`, one receiver alone, or donors and receivers both named. - [`usearch_status_config_mismatch_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_config_mismatch_k) A donor or receiver of another residency, class or connectivity, a receiver holding entries, or `index` itself. - [`usearch_status_contended_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_contended_k) An insertion or another refinement in flight on `index`, on a donor or on a receiver. ## usearch_geospatial_refinement_finish Skips whatever re-selection a stopped refinement left, re-links the islands it leaves as [`usearch_geospatial_refine`](#usearch_geospatial_refine) does, reports, reopens the index, and frees the handle. ```c void usearch_geospatial_refinement_finish( usearch_geospatial_refinement_finish_t *arguments); ``` A refinement whose donors have not all moved re-links nothing and reports zeros. - `index`: The handle the refinement was opened on. - `executor`: The executor the refinement was opened with. - `outcome`: Output for the outcome, final once its status leaves [`usearch_status_deferred_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_deferred_k). - `completion`: Blocking, the default, or deferred. - `refinement`: The refinement to finish; freed by the call, whatever it answers. - `report`: The __optional__ output for what the call did to the graph, as `[usearch_refine_report_t](#usearch_refine_report_t)` counts it; `NULL` skips reporting. - `stats`: The __optional__ traversal telemetry of every call on the refinement; `NULL` skips reporting. Statuses: - [`usearch_status_invalid_argument_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_invalid_argument_k) `index` or `executor` is not the one the refinement was opened with; the handle is still freed. ## usearch_sequence_absorb Absorbs every handle in `donors` into `index`, one after another, keeping their graphs rather than re-inserting their sequences, and links each in by walks across. ```c void usearch_sequence_absorb(usearch_sequence_absorb_t *arguments); ``` Donor handles are consumed and must not be used afterwards, not even for [`usearch_sequence_free`](https://www.unum.cloud/docs/usearch/c/residency.md#usearch_sequence_free). Every donor is checked and held before the first one enters, so a refusal consumes none. The donors then enter one after another, each all-or-nothing: its entries append to `index` with their edges rebased, publish at once, and the donor is consumed, so at most one donor's entries are ever held twice. One refinement then walks every entry across the parts the donors appended, round by round, so a group of donors costs one refinement rather than one per donor. Readers of `index` may keep searching throughout, since unpublished entries hide behind the watermark, while nothing may search a donor. Insertions into `index` arriving meanwhile are refused with [`usearch_status_contended_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_contended_k). The handler reports and cancels the closing refinement alone, exactly as in `usearch_sequence_refine:` a cancel skips the rest of the walks across, still re-links, and answers [`usearch_status_cancelled_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_cancelled_k) with every donor consumed. A caller wanting to continue those walks later holds a `[usearch_sequence_refinement_t](#usearch_sequence_refinement_t)` instead. - `index`: The handle absorbing the donors. - `executor`: The executor each donor's move and the closing refinement fan out over. - `outcome`: Output for the outcome, final once its status leaves [`usearch_status_deferred_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_deferred_k). - `completion`: Blocking, the default, or deferred. - `count`: Donor handles to absorb. - `donors`: Array of `count` handles, each consumed and nulled once its entries are published here. - `report`: The __optional__ output for what the call did to the graph, as `[usearch_refine_report_t](#usearch_refine_report_t)` counts it; `NULL` skips reporting. - `refine`: The __optional__ breadth and bytes of the closing refine. - `progress`: The __optional__ handler, called with the donor rows stitched so far out of every donor's; a cancel stops the stitching walks as it stops [`usearch_sequence_refine`](#usearch_sequence_refine), never a move. - `stats`: The __optional__ traversal telemetry; `NULL` skips reporting. Statuses: - [`usearch_status_read_only_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_read_only_k) `index` is an NVMe view. - [`usearch_status_unsupported_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_unsupported_k) `index` lives on a GPU, whose index absorbs nothing yet. - [`usearch_status_invalid_argument_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_invalid_argument_k) A `NULL` slot in `donors`, or `NULL` `donors` for a nonzero `count`. - [`usearch_status_config_mismatch_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_config_mismatch_k) A donor of another residency, class, kind or geometry, or `index` itself. - [`usearch_status_contended_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_contended_k) An insertion or refinement in flight on `index` or on a donor; every donor stays a live handle. ## usearch_sequence_split Splits `index` into the handles in `receivers`, the inverse of `usearch_sequence_absorb:` graph-local parts keeping their edges rather than re-inserting their sequences, one part per receiver, and `index` left empty but live. ```c void usearch_sequence_split(usearch_sequence_split_t *arguments); ``` Every receiver is checked and held before the first part moves, so a refusal moves nothing. The part roots are drawn from `seed` without a scan, and each part grows breadth-first over the links from its root, capped at an equal share of the entries, while entries no root reaches enter the smallest part. Each part then enters its receiver all-or-nothing, its edges rebased, its edges into other parts dropped, and the entries that lost one placed first; `index` clears once every part moved. Each receiver closes by re-selecting the entries that lost an edge and re-linking the islands that leaves, as [`usearch_sequence_refine`](#usearch_sequence_refine) does. Insertions into `index` or a receiver arriving meanwhile are refused with [`usearch_status_contended_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_contended_k), and nothing may search either until the call is final. The handler reports and cancels the closing refinements alone, exactly as in `usearch_sequence_refine:` a cancel skips the rest of the re-selection, still re-links, and answers [`usearch_status_cancelled_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_cancelled_k) with every part moved. A caller wanting to continue that re-selection later holds a `[usearch_sequence_refinement_t](#usearch_sequence_refinement_t)` opened with `receivers` instead. - `index`: The handle split into the receivers, left empty and live. - `executor`: The executor the partition, each part's move and the closing refinements fan out over. - `outcome`: Output for the outcome, final once its status leaves [`usearch_status_deferred_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_deferred_k). - `completion`: Blocking, the default, or deferred. - `count`: Receiver handles to split into, at least two. - `receivers`: Array of `count` empty handles of the source's residency, class, kind and geometry, each receiving one part. - `report`: The __optional__ output for what the call did to the graph, as `[usearch_refine_report_t](#usearch_refine_report_t)` counts it; `NULL` skips reporting. - `refine`: The __optional__ breadth and bytes of the closing refines. - `seed`: Picks the part roots: equal seeds over an unchanged index split equally. - `progress`: The __optional__ handler, called with entries the closing refines re-selected; a cancel stops them as it stops [`usearch_sequence_refine`](#usearch_sequence_refine), never a move. - `stats`: The __optional__ traversal telemetry; `NULL` skips reporting. Statuses: - [`usearch_status_read_only_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_read_only_k) `index` is a view. - [`usearch_status_invalid_argument_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_invalid_argument_k) Fewer than two receivers, `NULL` `receivers`, or a `NULL` slot in them. - [`usearch_status_config_mismatch_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_config_mismatch_k) A receiver of another residency, class, kind or geometry, one holding entries or another shard count, one named twice, or `index` itself. - [`usearch_status_contended_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_contended_k) An insertion or refinement in flight on `index` or on a receiver; nothing moves. - [`usearch_status_overflow_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_overflow_k) A part passes a receiver shard's ceiling. - [`usearch_status_unsupported_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_unsupported_k) `index` lives on a GPU, whose index splits nothing yet. ## usearch_sequence_refinement_init Opens a refinement of `index`, absorbing `donors` first when any are named, as [`usearch_sequence_absorb`](#usearch_sequence_absorb) moves them, or splitting it into `receivers`, as [`usearch_sequence_split`](#usearch_sequence_split) fills them. ```c void usearch_sequence_refinement_init( usearch_sequence_refinement_init_t *arguments); ``` Every allocation the refinement needs in the index happens here, never in a step. - `index`: The handle to be refined. - `executor`: The executor every call on the refinement runs on; its kind must match the residency. - `outcome`: Output for the outcome, final once its status leaves [`usearch_status_deferred_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_deferred_k). - `completion`: Blocking, the default, or deferred. - `donors`: The __optional__ donors to absorb first, each consumed and nulled once its entries land; the array must outlive the refinement. - `count`: Donor handles in `donors`. - `receivers`: The __optional__ receivers to split `index` into first, as [`usearch_sequence_split`](#usearch_sequence_split) fills them, each refined in turn; the array must outlive the refinement. - `receivers_count`: Receiver handles in `receivers`, zero or at least two. - `refinement`: Output for the new handle; `NULL` on failure. - `refine`: The __optional__ breadth and bytes of every pass the refinement steps. - `seed`: Picks the part roots when `receivers` are named, as in [`usearch_sequence_split`](#usearch_sequence_split). Statuses: - [`usearch_status_read_only_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_read_only_k) `index` is an NVMe view. - [`usearch_status_unsupported_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_unsupported_k) `index` lives on a GPU, whose index refines nothing yet. - [`usearch_status_invalid_argument_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_invalid_argument_k) No executor, a `NULL` slot in `donors` or `receivers`, `NULL` `donors` for a nonzero `count`, one receiver alone, or donors and receivers both named. - [`usearch_status_config_mismatch_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_config_mismatch_k) A donor or receiver of another residency, class, kind or geometry, a receiver holding entries, or `index` itself. - [`usearch_status_contended_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_contended_k) An insertion or another refinement in flight on `index`, on a donor or on a receiver. ## usearch_sequence_refinement_finish Skips whatever re-selection a stopped refinement left, re-links the islands it leaves as [`usearch_sequence_refine`](#usearch_sequence_refine) does, reports, reopens the index, and frees the handle. ```c void usearch_sequence_refinement_finish( usearch_sequence_refinement_finish_t *arguments); ``` A refinement whose donors have not all moved re-links nothing and reports zeros. - `index`: The handle the refinement was opened on. - `executor`: The executor the refinement was opened with. - `outcome`: Output for the outcome, final once its status leaves [`usearch_status_deferred_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_deferred_k). - `completion`: Blocking, the default, or deferred. - `refinement`: The refinement to finish; freed by the call, whatever it answers. - `report`: The __optional__ output for what the call did to the graph, as `[usearch_refine_report_t](#usearch_refine_report_t)` counts it; `NULL` skips reporting. - `stats`: The __optional__ traversal telemetry of every call on the refinement; `NULL` skips reporting. Statuses: - [`usearch_status_invalid_argument_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_invalid_argument_k) `index` or `executor` is not the one the refinement was opened with; the handle is still freed. ## usearch_shapes_absorb Absorbs every handle in `donors` into `index`, one after another, keeping their graphs rather than re-inserting their shapes, and links each in by walks across. ```c void usearch_shapes_absorb(usearch_shapes_absorb_t *arguments); ``` Donor handles are consumed and must not be used afterwards, not even for [`usearch_shapes_free`](https://www.unum.cloud/docs/usearch/c/residency.md#usearch_shapes_free). Every donor is checked and held before the first one enters, so a refusal consumes none. The donors then enter one after another, each all-or-nothing: its entries append to `index` with their edges rebased, publish at once, and the donor is consumed, so at most one donor's entries are ever held twice. One refinement then walks every entry across the parts the donors appended, round by round, so a group of donors costs one refinement rather than one per donor. Readers of `index` may keep searching throughout, since unpublished entries hide behind the watermark, while nothing may search a donor. Insertions into `index` arriving meanwhile are refused with [`usearch_status_contended_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_contended_k). The handler reports and cancels the closing refinement alone, exactly as in `usearch_shapes_refine:` a cancel skips the rest of the walks across, still re-links, and answers [`usearch_status_cancelled_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_cancelled_k) with every donor consumed. A caller wanting to continue those walks later holds a `[usearch_shapes_refinement_t](#usearch_shapes_refinement_t)` instead. - `index`: The handle absorbing the donors. - `executor`: The executor each donor's move and the closing refinement fan out over. - `outcome`: Output for the outcome, final once its status leaves [`usearch_status_deferred_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_deferred_k). - `completion`: Blocking, the default, or deferred. - `count`: Donor handles to absorb. - `donors`: Array of `count` handles, each consumed and nulled once its entries are published here. - `report`: The __optional__ output for what the call did to the graph, as `[usearch_refine_report_t](#usearch_refine_report_t)` counts it; `NULL` skips reporting. - `refine`: The __optional__ breadth and bytes of the closing refine. - `progress`: The __optional__ handler, called with the donor rows stitched so far out of every donor's; a cancel stops the stitching walks as it stops [`usearch_shapes_refine`](#usearch_shapes_refine), never a move. - `stats`: The __optional__ traversal telemetry; `NULL` skips reporting. Statuses: - [`usearch_status_read_only_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_read_only_k) `index` is an NVMe view. - [`usearch_status_unsupported_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_unsupported_k) `index` lives on a GPU, whose index absorbs nothing yet. - [`usearch_status_invalid_argument_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_invalid_argument_k) A `NULL` slot in `donors`, or `NULL` `donors` for a nonzero `count`. - [`usearch_status_config_mismatch_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_config_mismatch_k) A donor of another residency, class, scalar, kind or geometry, or `index` itself. - [`usearch_status_contended_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_contended_k) An insertion or refinement in flight on `index` or on a donor; every donor stays a live handle. ## usearch_shapes_split Splits `index` into the handles in `receivers`, the inverse of `usearch_shapes_absorb:` graph-local parts keeping their edges rather than re-inserting their shapes, one part per receiver, and `index` left empty but live. ```c void usearch_shapes_split(usearch_shapes_split_t *arguments); ``` Every receiver is checked and held before the first part moves, so a refusal moves nothing. The part roots are drawn from `seed` without a scan, and each part grows breadth-first over the links from its root, capped at an equal share of the entries, while entries no root reaches enter the smallest part. Each part then enters its receiver all-or-nothing, its edges rebased, its edges into other parts dropped, and the entries that lost one placed first; `index` clears once every part moved. Each receiver closes by re-selecting the entries that lost an edge and re-linking the islands that leaves, as [`usearch_shapes_refine`](#usearch_shapes_refine) does. Insertions into `index` or a receiver arriving meanwhile are refused with [`usearch_status_contended_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_contended_k), and nothing may search either until the call is final. The handler reports and cancels the closing refinements alone, exactly as in `usearch_shapes_refine:` a cancel skips the rest of the re-selection, still re-links, and answers [`usearch_status_cancelled_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_cancelled_k) with every part moved. A caller wanting to continue that re-selection later holds a `[usearch_shapes_refinement_t](#usearch_shapes_refinement_t)` opened with `receivers` instead. - `index`: The handle split into the receivers, left empty and live. - `executor`: The executor the partition, each part's move and the closing refinements fan out over. - `outcome`: Output for the outcome, final once its status leaves [`usearch_status_deferred_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_deferred_k). - `completion`: Blocking, the default, or deferred. - `count`: Receiver handles to split into, at least two. - `receivers`: Array of `count` empty handles of the source's residency, class, scalar, kind and geometry, each receiving one part. - `report`: The __optional__ output for what the call did to the graph, as `[usearch_refine_report_t](#usearch_refine_report_t)` counts it; `NULL` skips reporting. - `refine`: The __optional__ breadth and bytes of the closing refines. - `seed`: Picks the part roots: equal seeds over an unchanged index split equally. - `progress`: The __optional__ handler, called with entries the closing refines re-selected; a cancel stops them as it stops [`usearch_shapes_refine`](#usearch_shapes_refine), never a move. - `stats`: The __optional__ traversal telemetry; `NULL` skips reporting. Statuses: - [`usearch_status_read_only_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_read_only_k) `index` is a view. - [`usearch_status_invalid_argument_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_invalid_argument_k) Fewer than two receivers, `NULL` `receivers`, or a `NULL` slot in them. - [`usearch_status_config_mismatch_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_config_mismatch_k) A receiver of another residency, class, scalar, kind or geometry, one holding entries or another shard count, one named twice, or `index` itself. - [`usearch_status_contended_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_contended_k) An insertion or refinement in flight on `index` or on a receiver; nothing moves. - [`usearch_status_overflow_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_overflow_k) A part passes a receiver shard's ceiling. - [`usearch_status_unsupported_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_unsupported_k) `index` lives on a GPU, whose index splits nothing yet. ## usearch_shapes_refinement_init Opens a refinement of `index`, absorbing `donors` first when any are named, as [`usearch_shapes_absorb`](#usearch_shapes_absorb) moves them, or splitting it into `receivers`, as [`usearch_shapes_split`](#usearch_shapes_split) fills them. ```c void usearch_shapes_refinement_init( usearch_shapes_refinement_init_t *arguments); ``` Every allocation the refinement needs in the index happens here, never in a step. - `index`: The handle to be refined. - `executor`: The executor every call on the refinement runs on; its kind must match the residency. - `outcome`: Output for the outcome, final once its status leaves [`usearch_status_deferred_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_deferred_k). - `completion`: Blocking, the default, or deferred. - `donors`: The __optional__ donors to absorb first, each consumed and nulled once its entries land; the array must outlive the refinement. - `count`: Donor handles in `donors`. - `receivers`: The __optional__ receivers to split `index` into first, as [`usearch_shapes_split`](#usearch_shapes_split) fills them, each refined in turn; the array must outlive the refinement. - `receivers_count`: Receiver handles in `receivers`, zero or at least two. - `refinement`: Output for the new handle; `NULL` on failure. - `refine`: The __optional__ breadth and bytes of every pass the refinement steps. - `seed`: Picks the part roots when `receivers` are named, as in [`usearch_shapes_split`](#usearch_shapes_split). Statuses: - [`usearch_status_read_only_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_read_only_k) `index` is an NVMe view. - [`usearch_status_unsupported_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_unsupported_k) `index` lives on a GPU, whose index refines nothing yet. - [`usearch_status_invalid_argument_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_invalid_argument_k) No executor, a `NULL` slot in `donors` or `receivers`, `NULL` `donors` for a nonzero `count`, one receiver alone, or donors and receivers both named. - [`usearch_status_config_mismatch_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_config_mismatch_k) A donor or receiver of another residency, class, scalar, kind or geometry, a receiver holding entries, or `index` itself. - [`usearch_status_contended_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_contended_k) An insertion or another refinement in flight on `index`, on a donor or on a receiver. ## usearch_shapes_refinement_finish Skips whatever re-selection a stopped refinement left, re-links the islands it leaves as [`usearch_shapes_refine`](#usearch_shapes_refine) does, reports, reopens the index, and frees the handle. ```c void usearch_shapes_refinement_finish( usearch_shapes_refinement_finish_t *arguments); ``` A refinement whose donors have not all moved re-links nothing and reports zeros. - `index`: The handle the refinement was opened on. - `executor`: The executor the refinement was opened with. - `outcome`: Output for the outcome, final once its status leaves [`usearch_status_deferred_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_deferred_k). - `completion`: Blocking, the default, or deferred. - `refinement`: The refinement to finish; freed by the call, whatever it answers. - `report`: The __optional__ output for what the call did to the graph, as `[usearch_refine_report_t](#usearch_refine_report_t)` counts it; `NULL` skips reporting. - `stats`: The __optional__ traversal telemetry of every call on the refinement; `NULL` skips reporting. Statuses: - [`usearch_status_invalid_argument_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_invalid_argument_k) `index` or `executor` is not the one the refinement was opened with; the handle is still freed.