# Retrieval and Streaming > USearch for C `usearch_dense_get` writes every vector stored under one key into an arena, shard by shard and in insertion order within each, as the [Arenas](https://www.unum.cloud/docs/usearch/c/inputs-and-outputs.md#arenas) example shows; an absent key leaves `vectors->data` `NULL`. A cursor walks the graph, every entry in storage order or breadth-first from `starts`, its keys and, when asked, each entry's `links` copied into an arena batch by batch: ```c usearch_dense_cursor_t cursor = NULL; usearch_dense_cursor_init(&(usearch_dense_cursor_init_t) {.index = index, .outcome = &outcome, .cursor = &cursor}); usearch_keys_view_t batch = {0}; for (size_t written = 1; written != 0 && outcome.status == usearch_status_success_k;) usearch_dense_cursor_next(&(usearch_dense_cursor_next_t) {.index = index, .executor = executor, .outcome = &outcome, .cursor = cursor, .keys = &batch, .written = &written, .arena = arena, .wanted = 1024}); usearch_dense_cursor_free(cursor); ``` Each shard's publication watermark is read as the walk enters it, so an entry once passed is never revisited, while a later shard may carry entries published after the walk began. Opened at `starts`, a cursor yields their own entries first, in the order given, then breadth-first the entries they link to, each entry once, so the first entries pulled carry the starts' immediate links. `links` is a `usearch_keys_tape_view_t`, entry `i` spanning `offsets[i]` up to `offsets[i+1]`, and the vectors themselves come from `usearch_dense_get`. When a predicate is selective enough that no `wanted` can be guessed upfront, a search stream keeps pulling matches in distance order: ```c usearch_dense_search_stream_t stream = NULL; usearch_dense_search_stream_init(&(usearch_dense_search_stream_init_t) { .stream = &stream, .index = index, .outcome = &outcome, .query = {query, 0, 128, usearch_scalar_f32_k}}); do { usearch_dense_search_stream_next(&(usearch_dense_search_stream_next_t) {.index = index, .executor = executor, .outcome = &outcome, .stream = stream, .matches = &matches, .arena = arena, .wanted = 10}); // ... keep the matches that pass, and stop once enough did ... } while (outcome.status == usearch_status_success_k && matches.counts[0] != 0); usearch_dense_search_stream_free(stream); ``` No residency implements streams yet, so `usearch_dense_search_stream_init` answers `usearch_status_unsupported_k` today. A stream keeps the walk's state between pulls, never a thread, so any number of them may stay open on one executor. Cursors and streams keep no hold on the index either: every pull passes the index it was opened on, any other is refused with `usearch_status_invalid_argument_k`, and an overlapping pull reports `usearch_status_contended_k`. `#include ` `#include ` `#include ` `#include ` ## usearch_dense_cursor_t A walk over the graph yielding each entry's key with the keys it links to, every entry as stored or breadth-first from start keys, which export, migration, and visualization read. ```c typedef struct usearch_dense_cursor_handle_t * usearch_dense_cursor_t; ``` Each shard's publication watermark is read as the walk enters that shard, so an entry once passed is never revisited, while a later shard may still carry entries published after the walk began. Each pull names the index again; an overlapping pull reports [`usearch_status_contended_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_contended_k). ## usearch_dense_search_stream_t A resumable search over one query: best-first traversal is naturally pausable, so the stream keeps the walk's frontier & visited set between pulls and yields matches lazily. ```c typedef struct usearch_dense_search_stream_handle_t * usearch_dense_search_stream_t; ``` Callers that post-filter aggressively pull until satisfied instead of guessing `wanted` upfront. The stream holds state, never a thread, so any number of them may stay open on one executor. Each pull names the index again; an overlapping pull reports [`usearch_status_contended_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_contended_k). ## usearch_geospatial_cursor_t A consistent snapshot cursor over the graph. ```c typedef struct usearch_geospatial_cursor_handle_t * usearch_geospatial_cursor_t; ``` Captures the publication watermark at creation, so concurrent inserts never appear mid-iteration, and yields each entry's key with the keys it links to - every entry as stored, or breadth-first from start keys - which export, migration, and visualization feed off. Each pull names the index again; an overlapping pull reports [`usearch_status_contended_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_contended_k). ## usearch_sequence_cursor_t A consistent snapshot cursor over the graph. ```c typedef struct usearch_sequence_cursor_handle_t * usearch_sequence_cursor_t; ``` Captures the publication watermark at creation, so concurrent inserts never appear mid-iteration, and yields each entry's key with the keys it links to - every entry as stored, or breadth-first from start keys - which export, migration, and visualization feed off. Each pull names the index again; an overlapping pull reports [`usearch_status_contended_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_contended_k). ## usearch_shapes_cursor_t A consistent snapshot cursor over the graph. ```c typedef struct usearch_shapes_cursor_handle_t * usearch_shapes_cursor_t; ``` Captures the publication watermark at creation, so concurrent inserts never appear mid-iteration, and yields each entry's key with the keys it links to - every entry as stored, or breadth-first from start keys - which export, migration, and visualization feed off. Each pull names the index again; an overlapping pull reports [`usearch_status_contended_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_contended_k). ## usearch_dense_get Retrieves every vector stored under one key into `arena`, one row per entry sharing the key, shard by shard and in insertion order within each - one call, however many there are. ```c void usearch_dense_get(usearch_dense_get_t *arguments); ``` The vectors span `written` entries; an absent key leaves `vectors->data` `NULL`. - `index`: The handle to be queried. - `executor`: The executor whose stream or thread copies the vectors; 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. - `key`: The key whose entries are exported. - `vectors`: Output for every vector, packed at their natural width, inside `arena`. - `written`: The __optional__ output for the vectors written; zero when the key is absent. - `arena`: Memory for `vectors`, rewound by the call. - `outputs_scalar`: The scalar type to export as, converted from storage where it differs. Statuses: - [`usearch_status_unknown_kind_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_unknown_kind_k) An unknown `outputs_scalar`. - [`usearch_status_shape_mismatch_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_shape_mismatch_k) Sub-byte vectors ending inside a byte. - [`usearch_status_invalid_argument_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_invalid_argument_k) A `NULL` `arena`. - [`usearch_status_device_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_device_k) An arena or an executor on another residency or device. - [`usearch_status_contended_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_contended_k) The arena serves another call, another call holds the executor or its pool, or a destructive window overlapped the read twice. - [`usearch_status_uninitialized_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_uninitialized_k) The executor holds no pool workers, or a VRAM index has no shards. - [`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 shard's device, or an NVMe medium the engines cannot read. ## usearch_dense_cursor_init Opens a walk over the current contents; see `[usearch_dense_cursor_t](#usearch_dense_cursor_t)`. ```c void usearch_dense_cursor_init(usearch_dense_cursor_init_t *arguments); ``` Without `starts` the cursor yields every entry as stored. With them it yields the start keys' own entries first, in the order given, then the entries those link to, breadth-first, each entry once, so a caller wanting only the starts' immediate links reads the links of the first pulled entries. A key the index lacks starts nothing, and a key several entries share starts from its first stored entry. - `index`: The handle to be scanned. - `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). - `starts_count`: The __optional__ count of `starts`; zero walks every entry as stored. - `starts`: The keys to walk from, in the order the walk begins with them. - `cursor`: Output for the new cursor; `NULL` on failure. Statuses: - [`usearch_status_invalid_argument_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_invalid_argument_k) `NULL` `starts` for a nonzero `starts_count`. - [`usearch_status_unsupported_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_unsupported_k) The handle lives on a GPU, which walks no links yet. ## usearch_dense_cursor_next Copies the next batch of entries out of the cursor into `arena`, each with the keys it links to, in the order [`usearch_dense_cursor_init`](#usearch_dense_cursor_init) describes; the vectors themselves come from [`usearch_dense_get`](#usearch_dense_get). ```c void usearch_dense_cursor_next(usearch_dense_cursor_next_t *arguments); ``` Links name only entries published when the pull ran, as the graph stored them then. The keys are copied rather than borrowed from the index, so the batch stays valid until the next call given the same arena, however the cursor moves meanwhile. - `index`: The handle the cursor was opened on. - `executor`: The executor the pull runs on. - `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. - `cursor`: The cursor to advance. - `keys`: Output for the identities, inside `arena`. - `links`: The __optional__ output for each entry's links, the keys of the entries it links to, entry `i` spanning `offsets`[i] up to `offsets`[i+1], inside `arena`; `NULL` skips them. - `written`: Output for the entries written; zero when the walk is exhausted. - `arena`: Memory for `keys` and `links`, rewound by the call. - `wanted`: The upper bound on entries this pull writes. Statuses: - [`usearch_status_io_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_io_k) A read from an NVMe view's drives failed. - [`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 cursor was opened on. ## usearch_*_cursor_free Releases the cursor; `NULL` is safe. ```c void usearch_dense_cursor_free(usearch_dense_cursor_t cursor); ``` - `usearch_dense_cursor_free`: cursor `usearch_dense_cursor_t` - `usearch_geospatial_cursor_free`: cursor `usearch_geospatial_cursor_t` - `usearch_sequence_cursor_free`: cursor `usearch_sequence_cursor_t` - `usearch_shapes_cursor_free`: cursor `usearch_shapes_cursor_t` Waits until every deferred call naming the handle is final. ## usearch_*_sample Draws keys around `focus`, or across the whole index, each hanging from a shown or earlier draw and placed in three dimensions beside the shown ones - so a view grows one connected sample as it zooms, never scanning the index. ```c void usearch_dense_sample(usearch_dense_sample_t *arguments); ``` - `usearch_dense_sample`: index `usearch_dense_index_t` - `usearch_geospatial_sample`: index `usearch_geospatial_index_t` - `usearch_sequence_sample`: index `usearch_sequence_index_t` - `usearch_shapes_sample`: index `usearch_shapes_index_t` The draws follow the graph: along paths joining the focus to each other and toward the nearest shown key, then around each focus key as far as its nearest neighbor on those paths, ranked by `seed` so a closer view draws a superset of a farther one. A key holding several entries draws each as its own, named by its entry ordinal. Each draw is placed by its distances to its nearest shown keys, the shown keys keeping their coordinates; with nothing shown, its row is projected through a seeded Gaussian matrix. The draws follow the graph: along paths joining the focus to each other and toward the nearest shown key, then around each focus key as far as its nearest neighbor on those paths, ranked by `seed` so a closer view draws a superset of a farther one. A key holding several entries draws each as its own, named by its entry ordinal. Each draw is placed at its Earth-fixed position, so `shown_coordinates` place nothing. The draws follow the graph: along paths joining the focus to each other and toward the nearest shown key, then around each focus key as far as its nearest neighbor on those paths, ranked by `seed` so a closer view draws a superset of a farther one. A key holding several entries draws each as its own, named by its entry ordinal. Each draw is placed by its distances to its nearest shown keys, the shown keys keeping their coordinates; with nothing shown, the draws are scaled against one another. - `index`: The handle to be sampled. - `executor`: The executor the draws run on; its kind must match the handle's 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. - `shown_count`: The __optional__ count of `shown`; zero shows nothing yet. - `shown`: The keys already shown: never drawn again, and the paths reach toward them. - `shown_coordinates`: Where the `shown` keys sit, `shown_count` rows of three [`usearch_scalar_f32_k`](https://www.unum.cloud/docs/usearch/c/inputs-and-outputs.md#usearch_scalar_f32_k) values, the points later draws are placed against. - `focus_count`: The __optional__ count of `focus`; zero looks around the whole index. - `focus`: The keys to look around, the roots the draws grow from. - `keys`: Output for the keys drawn, inside `arena`. - `entry_ordinals`: Output for which of its key's entries each draw is, in the order [`usearch_dense_get`](#usearch_dense_get) writes them, inside `arena`. - `parents`: Output for the one shown or earlier draw each draw hangs from and its distance, one column, a draw with none counting zero, inside `arena`. - `coordinates`: Output for where each draw is placed, `written` rows of three [`usearch_scalar_f32_k`](https://www.unum.cloud/docs/usearch/c/inputs-and-outputs.md#usearch_scalar_f32_k) values, inside `arena`. - `written`: Output for the draws written; fewer than `wanted` only once the region is exhausted. - `arena`: Memory for every output, rewound by the call. - `wanted`: The upper bound on draws this call writes. - `seed`: The draw: equal seeds, shown keys and focus over an unchanged index draw equally, and a larger `wanted` draws a superset. - `expansion_factor`: The __optional__ breadth of the candidates of the walks behind the draws; zero derives. - `progress`: The __optional__ handler, called with draws written and `wanted`. - `stats`: The __optional__ traversal telemetry; `NULL` skips reporting. Statuses: - [`usearch_status_invalid_argument_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_invalid_argument_k) `NULL` `shown` or `focus` for a nonzero count, or `shown_coordinates` not three [`usearch_scalar_f32_k`](https://www.unum.cloud/docs/usearch/c/inputs-and-outputs.md#usearch_scalar_f32_k) columns. - [`usearch_status_unsupported_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_unsupported_k) The handle lives on a GPU, which does not sample yet. - [`usearch_status_io_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_io_k) A read from an NVMe view's drives failed. ## usearch_dense_search_stream_init Opens a resumable search for one query; see `[usearch_dense_search_stream_t](#usearch_dense_search_stream_t)`. ```c void usearch_dense_search_stream_init( usearch_dense_search_stream_init_t *arguments); ``` - `stream`: Output for the new stream; `NULL` on failure. - `index`: The handle to be queried. - `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). - `query`: The single query row. - `expansion_factor`: The __optional__ breadth of the candidates the walk explores, as in `[usearch_dense_search_t](https://www.unum.cloud/docs/usearch/c/inputs-and-outputs.md#usearch_dense_search)`; zero derives. Statuses: - [`usearch_status_unsupported_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_unsupported_k) No residency implements the stream yet. ## usearch_dense_search_stream_next Pulls the next-nearest matches from the stream. ```c void usearch_dense_search_stream_next( usearch_dense_search_stream_next_t *arguments); ``` Ordering beyond the expansion horizon is best-effort nearest rather than globally exact, so a caller pulling far past the breadth it configured sees the ranking degrade rather than the stream end. - `index`: The handle the stream was opened on. - `executor`: The executor the pull runs on. - `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. - `stream`: The stream to advance. - `matches`: Output for the pull, as one row of a search inside `arena:` up to `wanted` more matches, their number in `matches->counts`[0], zero once the walk is drained. - `arena`: Memory for `matches`, rewound by the call. - `wanted`: The upper bound on matches this pull writes. 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 stream was opened on. ## usearch_dense_search_stream_free Releases the stream and the walk state it keeps; `NULL` is safe. ```c void usearch_dense_search_stream_free( usearch_dense_search_stream_t stream); ``` Waits until every deferred call naming the handle is final. ## usearch_geospatial_get Retrieves every observation stored under one key, in insertion order, within the rounding the index stores them at. ```c void usearch_geospatial_get(usearch_geospatial_get_t *arguments); ``` An absent key leaves `observations` `NULL`. - `index`: The handle to be queried. - `executor`: The executor whose stream or thread copies the observations; 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. - `key`: The key whose entries are exported. - `observations`: Output for the observations inside `arena`, `written` of them. - `written`: The __optional__ output for the entries written; zero when the key is absent. - `arena`: Memory for `observations`, rewound by the call. Statuses: - [`usearch_status_invalid_argument_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_invalid_argument_k) A `NULL` `arena`. - [`usearch_status_device_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_device_k) An arena or an executor on another residency or device. - [`usearch_status_contended_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_contended_k) The arena serves another call, or another call holds an NVMe view's executor or its pool. - [`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 exports nothing yet. - [`usearch_status_uninitialized_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_uninitialized_k) An NVMe view's executor holds no pool workers. - [`usearch_status_config_mismatch_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_config_mismatch_k) An NVMe medium the engines cannot read. ## usearch_geospatial_cursor_init Opens a snapshot cursor over the current contents; see `[usearch_geospatial_cursor_t](#usearch_geospatial_cursor_t)`. ```c void usearch_geospatial_cursor_init( usearch_geospatial_cursor_init_t *arguments); ``` Without `starts` the cursor yields every entry as stored. With them it yields the start keys' own entries first, in the order given, then the entries those link to, breadth-first, each entry once, so a caller wanting only the starts' immediate links reads the links of the first pulled entries. A key the index lacks starts nothing, and a key several entries share starts from the first stored. - `index`: The handle to be scanned. - `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). - `starts_count`: The __optional__ count of `starts`; zero walks every entry as stored. - `starts`: The keys to walk from, in the order the walk begins with them. - `cursor`: Output for the new cursor; `NULL` on failure. Statuses: - [`usearch_status_invalid_argument_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_invalid_argument_k) `NULL` `starts` for a nonzero `starts_count`. - [`usearch_status_unsupported_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_unsupported_k) The handle lives on a GPU, which walks no links yet. ## usearch_geospatial_cursor_next Copies the next batch of entries out of the cursor into `arena`, each with the keys it links to, in the order [`usearch_geospatial_cursor_init`](#usearch_geospatial_cursor_init) describes; the observations themselves come from [`usearch_geospatial_get`](#usearch_geospatial_get). ```c void usearch_geospatial_cursor_next( usearch_geospatial_cursor_next_t *arguments); ``` Links name only entries the snapshot holds, as the graph stored them when the pull ran. The keys are copied rather than borrowed from the index, so the batch stays valid until the next call given the same arena, however the cursor moves meanwhile. - `index`: The handle the cursor was opened on. - `executor`: The executor the pull runs on. - `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. - `cursor`: The cursor to advance. - `keys`: Output for the identities, inside `arena`. - `links`: The __optional__ output for each entry's links, the keys of the entries it links to in the graph, entry `i` spanning `offsets`[i] up to `offsets`[i+1], inside `arena`; `NULL` skips them. - `written`: Output for the entries written; zero when the snapshot is exhausted. - `arena`: Memory for `keys` and `links`, rewound by the call. - `wanted`: The upper bound on entries this pull writes. Statuses: - [`usearch_status_io_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_io_k) A read from an NVMe view's drives failed. - [`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 cursor was opened on. ## usearch_sequence_get Retrieves every sequence stored under one key as an Apache Arrow tape, in insertion order - one call, however many and however long they turn out to be. ```c void usearch_sequence_get(usearch_sequence_get_t *arguments); ``` An absent key leaves the tape's pointers `NULL`. - `index`: The handle to be queried. - `executor`: The executor whose thread copies the entries. - `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. - `key`: The key whose entries are exported. - `sequences`: Output for the tape inside `arena:` entries' bytes end to end, never terminated, around `written` + 1 offsets. - `written`: The __optional__ output for the entries written; zero when the key is absent. - `arena`: Memory for `sequences`, rewound by the call. Statuses: - [`usearch_status_invalid_argument_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_invalid_argument_k) A `NULL` `arena`. - [`usearch_status_device_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_device_k) An arena or an executor on another residency or device. - [`usearch_status_contended_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_contended_k) The arena serves another call, or another call holds an NVMe view's executor or its pool. - [`usearch_status_uninitialized_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_uninitialized_k) An NVMe view's executor holds no pool workers. - [`usearch_status_config_mismatch_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_config_mismatch_k) An NVMe medium the engines cannot read. ## usearch_sequence_cursor_init Opens a snapshot cursor over the current contents; see `[usearch_sequence_cursor_t](#usearch_sequence_cursor_t)`. ```c void usearch_sequence_cursor_init( usearch_sequence_cursor_init_t *arguments); ``` Without `starts` the cursor yields every entry as stored. With them it yields the start keys' own entries first, in the order given, then the entries those link to, breadth-first, each entry once, so a caller wanting only the starts' immediate links reads the links of the first pulled entries. A key the index lacks starts nothing, and a key several entries share starts from the first stored. - `index`: The handle to be scanned. - `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). - `starts_count`: The __optional__ count of `starts`; zero walks every entry as stored. - `starts`: The keys to walk from, in the order the walk begins with them. - `cursor`: Output for the new cursor; `NULL` on failure. Statuses: - [`usearch_status_invalid_argument_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_invalid_argument_k) `NULL` `starts` for a nonzero `starts_count`. - [`usearch_status_unsupported_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_unsupported_k) The handle lives on a GPU, which walks no links yet. ## usearch_sequence_cursor_next Copies the next batch of entries out of the cursor into `arena`, each with the keys it links to, in the order [`usearch_sequence_cursor_init`](#usearch_sequence_cursor_init) describes; the sequences themselves come from [`usearch_sequence_get`](#usearch_sequence_get). ```c void usearch_sequence_cursor_next( usearch_sequence_cursor_next_t *arguments); ``` Links name only entries the snapshot holds, as the graph stored them when the pull ran. The keys are copied rather than borrowed from the index, so the batch stays valid until the next call given the same arena, however the cursor moves meanwhile. - `index`: The handle the cursor was opened on. - `executor`: The executor the pull runs on. - `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. - `cursor`: The cursor to advance. - `keys`: Output for the identities, inside `arena`. - `links`: The __optional__ output for each entry's links, the keys of the entries it links to in the graph, entry `i` spanning `offsets`[i] up to `offsets`[i+1], inside `arena`; `NULL` skips them. - `written`: Output for the entries written; zero when the snapshot is exhausted. - `arena`: Memory for `keys` and `links`, rewound by the call. - `wanted`: The upper bound on entries this pull writes. Statuses: - [`usearch_status_io_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_io_k) A read from an NVMe view's drives failed. - [`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 cursor was opened on. ## usearch_shapes_get Retrieves every shape stored under one key as an Apache Arrow tape, in insertion order - one call, however many and however large they turn out to be. ```c void usearch_shapes_get(usearch_shapes_get_t *arguments); ``` Each shape comes back in the pose it was inserted in, to the precision of the stored scalar. An absent key leaves the tape's pointers `NULL`. - `index`: The handle to be queried. - `executor`: The executor whose stream or thread copies the points; 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. - `key`: The key whose entries are exported. - `shapes`: Output for the tape inside `arena:` every entry's points end to end, `x`, `y` and `z` interleaved in `outputs_scalar`, around `written` + 1 point offsets. - `written`: The __optional__ output for the entries written; zero when the key is absent. - `arena`: Memory for `shapes`, rewound by the call. - `outputs_scalar`: The scalar type to export as, converted from storage where it differs. Statuses: - [`usearch_status_invalid_argument_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_invalid_argument_k) A `NULL` `arena`. - [`usearch_status_device_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_device_k) An arena or an executor on another residency or device. - [`usearch_status_contended_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_contended_k) The arena serves another call, or another call holds an NVMe view's executor or its pool. - [`usearch_status_unsupported_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_unsupported_k) An `outputs_scalar` that is not a whole-byte scalar, or a handle living on a GPU, whose index exports nothing yet. - [`usearch_status_uninitialized_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_uninitialized_k) An NVMe view's executor holds no pool workers. - [`usearch_status_config_mismatch_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_config_mismatch_k) An NVMe medium the engines cannot read. ## usearch_shapes_cursor_init Opens a snapshot cursor over the current contents; see `[usearch_shapes_cursor_t](#usearch_shapes_cursor_t)`. ```c void usearch_shapes_cursor_init( usearch_shapes_cursor_init_t *arguments); ``` Without `starts` the cursor yields every entry as stored. With them it yields the start keys' own entries first, in the order given, then the entries those link to, breadth-first, each entry once, so a caller wanting only the starts' immediate links reads the links of the first pulled entries. A key the index lacks starts nothing, and a key several entries share starts from the first stored. - `index`: The handle to be scanned. - `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). - `starts_count`: The __optional__ count of `starts`; zero walks every entry as stored. - `starts`: The keys to walk from, in the order the walk begins with them. - `cursor`: Output for the new cursor; `NULL` on failure. Statuses: - [`usearch_status_invalid_argument_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_invalid_argument_k) `NULL` `starts` for a nonzero `starts_count`. - [`usearch_status_unsupported_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_unsupported_k) The handle lives on a GPU, which walks no links yet. ## usearch_shapes_cursor_next Copies the next batch of entries out of the cursor into `arena`, each with the keys it links to, in the order [`usearch_shapes_cursor_init`](#usearch_shapes_cursor_init) describes; the shapes themselves come from [`usearch_shapes_get`](#usearch_shapes_get). ```c void usearch_shapes_cursor_next( usearch_shapes_cursor_next_t *arguments); ``` Links name only entries the snapshot holds, as the graph stored them when the pull ran. The keys are copied rather than borrowed from the index, so the batch stays valid until the next call given the same arena, however the cursor moves meanwhile. - `index`: The handle the cursor was opened on. - `executor`: The executor the pull runs on. - `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. - `cursor`: The cursor to advance. - `keys`: Output for the identities, inside `arena`. - `links`: The __optional__ output for each entry's links, the keys of the entries it links to in the graph, entry `i` spanning `offsets`[i] up to `offsets`[i+1], inside `arena`; `NULL` skips them. - `written`: Output for the entries written; zero when the snapshot is exhausted. - `arena`: Memory for `keys` and `links`, rewound by the call. - `wanted`: The upper bound on entries this pull writes. Statuses: - [`usearch_status_io_k`](https://www.unum.cloud/docs/usearch/c/errors.md#usearch_status_io_k) A read from an NVMe view's drives failed. - [`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 cursor was opened on.