class dense_index_tAPI
Classdense_index_tOwns one dense index; destruction waits for its deferred calls.31
dense_index_t
dense_index_t() noexcept=default;dense_index_t(dense_index_t && other) noexcept;dense_index_t(dense_index_t const &)=delete;operator=
dense_index_t & operator=(dense_index_t && other) noexcept;dense_index_t & operator=(dense_index_t const &)=delete;~dense_index_t
~dense_index_t() noexcept;reserveGrows the shards ahead of a number of incoming vectors.
outcome reserve(
usearch_dense_reserve_t arguments,
executor_t const & executor = {}) noexcept;Statuses
usearch_status_read_only_kThe index is an NVMe view.usearch_status_uninitialized_kNo shard is placed.usearch_status_unknown_kind_kThe stored scalar's kits cannot finalize the metric.usearch_status_config_mismatch_kThe frozen geometry differs from a shard's, or on VRAM a shard's neighbors live on another device or no walk fits the device.usearch_status_overflow_kThe capacity passes a shard's ceiling, its ID space, its chunk directory or its key column.
clearErases all entries, keeping the reserved capacity and frozen geometry.
outcome clear(
usearch_dense_clear_t arguments = {},
executor_t const & executor = {}) noexcept;Statuses
usearch_status_read_only_kThe index is an NVMe view.usearch_status_contended_kA call in flight, a batch or load holding claims, or a plan holding the index closed.
insertAdds a run of vectors under their keys, all or nothing per call.
outcome insert(
usearch_dense_insert_t arguments,
executor_t const & executor = {}) noexcept;Statuses
usearch_status_read_only_kThe index is a view.usearch_status_contended_kA refinement, absorption or clear holds the index, or on VRAM a save or another insertion does; nothing written.
refineRefines the graph, answering its report: the nodes re-selected and changed, and the islands found and reconnected.
outcome<usearch_refine_report_t> refine(
usearch_dense_refine_t arguments = {},
executor_t const & executor = {}) noexcept;Statuses
usearch_status_device_kexecutor's kind does not match the residency.usearch_status_read_only_kThe index is an NVMe view.usearch_status_uninitialized_kNo shard is placed or froze its geometry,executorholds no threads, or a VRAM index keeps such an earlier failure.usearch_status_contended_kAn insertion, load, save, refinement or absorption holds the index, or another call holdsexecutoror its pool.usearch_status_config_mismatch_kexecutordrives no stream on some VRAM shard's device, or a VRAM index keeps such an earlier failure.usearch_status_overflow_kA queue capacity wraps when rounded, or a VRAM index keeps an earlier overflow.usearch_status_unsupported_korusearch_status_unsupported_layout_kA VRAM index keeps such an earlier failure.
healthAudits how much of the graph a search can reach.
outcome<usearch_reachability_t> health(
usearch_dense_health_t arguments = {},
executor_t const & executor = {}) noexcept;Statuses
usearch_status_device_kexecutor's kind does not match the residency.usearch_status_uninitialized_kNo shard is placed,executorholds no pool workers or streams, or a VRAM index keeps such an earlier failure.usearch_status_contended_kAnother call holdsexecutoror its pool, or a destructive window overlapped the audit twice.usearch_status_config_mismatch_kexecutordrives no stream on some VRAM shard's device, an NVMe medium the engines cannot read, or a VRAM index keeps such an earlier failure.usearch_status_overflow_kA VRAM index keeps an earlier overflow.usearch_status_unsupported_korusearch_status_unsupported_layout_kA VRAM index keeps such an earlier failure.
absorbAbsorbs the donor indexes arguments names into this one, consuming them.
outcome absorb(
usearch_dense_absorb_t arguments,
executor_t const & executor = {}) noexcept;Statuses
usearch_status_read_only_kThe index is an NVMe view.usearch_status_invalid_argument_kANULLdonor slot, orNULLdonors for a nonzero count.usearch_status_config_mismatch_kA donor of another residency, scalar, class, metric or geometry, a donor on a device the executor does not drive, or this index itself.usearch_status_contended_kAn insertion in flight on this index or on the next donor, or on VRAM a save of either; that donor and every later one stay live indexes.
searchFinds the nearest entries of every query arguments names, written into arena.
outcome<usearch_matches_view_t> search(
usearch_dense_search_t arguments,
arena_t const & arena,
executor_t const & executor = {}) noexcept;Statuses
usearch_status_unknown_kind_kA traversal other than a walk or a scan.usearch_status_unsupported_kA scan of an AMD or Apple VRAM index, or a predicate on any VRAM index.
countAnswers how many entries arguments.key holds.
outcome<std::size_t> count(
usearch_dense_count_t arguments,
executor_t const & executor = {}) noexcept;Statuses
usearch_status_device_kexecutor's kind does not match the residency.usearch_status_uninitialized_kexecutorholds no pool workers.usearch_status_contended_kAnother call holdsexecutor, or its pool runs another dispatch.usearch_status_config_mismatch_kAn NVMe medium the engines cannot read.
getAnswers the vectors arguments.key holds; arguments.written counts them when the caller sets it.
outcome<usearch_rows_view_t> get(
usearch_dense_get_t arguments,
arena_t const & arena,
executor_t const & executor = {}) noexcept;Statuses
usearch_status_unknown_kind_kAn unknown output scalar.usearch_status_shape_mismatch_kSub-byte rows ending inside a byte.usearch_status_invalid_argument_kAn emptyarena.usearch_status_device_kAn arena or an executor on another residency or device.usearch_status_contended_karenaserves another call, another call holdsexecutoror its pool, or a destructive window overlapped the read twice.usearch_status_uninitialized_kexecutorholds no pool workers, or a VRAM index has no shards.usearch_status_config_mismatch_kexecutordrives no stream on some shard's device, or an NVMe medium the engines cannot read.
cursor_initOpens a cursor over every entry of the index.
outcome<dense_cursor_t> cursor_init(
usearch_dense_cursor_init_t arguments = {}) noexcept;Statuses
usearch_status_invalid_argument_kNULLstarts for a nonzero count of them.
cursor_nextAnswers the next keys cursor walks to; the entries and their count land where the caller points.
outcome<usearch_keys_view_t> cursor_next(
dense_cursor_t const & cursor,
usearch_dense_cursor_next_t arguments,
arena_t const & arena,
executor_t const & executor = {}) noexcept;Statuses
usearch_status_invalid_argument_kcursorwas opened on another index.
search_stream_initOpens a stream of matches that later calls extend.
outcome<dense_search_stream_t> search_stream_init(
usearch_dense_search_stream_init_t arguments) noexcept;Statuses
usearch_status_unsupported_kNo residency implements the stream yet.
search_stream_nextAnswers the next matches of stream, writing them into arena.
outcome<usearch_matches_view_t> search_stream_next(
dense_search_stream_t const & stream,
usearch_dense_search_stream_next_t arguments,
arena_t const & arena,
executor_t const & executor = {}) noexcept;Statuses
usearch_status_invalid_argument_kstreamwas opened on another index.
saveWrites the index to the checkpoint path arguments names.
outcome save(
usearch_dense_save_t arguments,
executor_t const & executor = {}) noexcept;Statuses
usearch_status_contended_kA RAM save meeting an insertion in flight or one publishing under it, or a VRAM save meeting an insertion, refinement, absorption or another save in flight.
save_bufferWrites the index into one monolith in arena.
outcome<usearch_bytes_view_t> save_buffer(
usearch_dense_save_buffer_t arguments,
arena_t const & arena,
executor_t const & executor = {}) noexcept;Statuses
usearch_status_invalid_argument_kAn emptyarena.usearch_status_device_kAn arena or an executor on another residency or device.usearch_status_contended_karenaserves another call, another call holdsexecutoror its pool, a dispensed batch has yet to publish, or a call, batch, load or plan holds the index.usearch_status_unsupported_kThe index is an NVMe view, which already is its checkpoint.usearch_status_uninitialized_kNo shard is placed or froze its geometry, orexecutorholds no pool workers.usearch_status_unknown_kind_kThe stored scalar has no interchange dtype.usearch_status_config_mismatch_kexecutordrives no stream on some VRAM shard's device.
multiplyAnswers the products; their count and the width they needed land where the caller points.
outcome<usearch_matches_tape_view_t> multiply(
usearch_dense_multiply_t arguments,
arena_t const & arena,
executor_t const & executor = {}) noexcept;Statuses
usearch_status_unknown_kind_kA traversal other than a walk or a scan.usearch_status_unsupported_kA scan, or a predicate on a VRAM index.
attendAttends the query heads arguments names over the entries their walks score, writing the rows into arena.
outcome<usearch_rows_view_t> attend(
usearch_dense_attend_t arguments,
arena_t const & arena,
executor_t const & executor = {}) noexcept;Statuses
usearch_status_invalid_argument_kANULLvalue lookup.usearch_status_shape_mismatch_kThe head count does not divide the rows, or a lookup yields aNULLrow.usearch_status_unknown_kind_kA traversal other than a walk or a scan.usearch_status_unsupported_kA scan, or a predicate on a VRAM index.
maxsimScores query groups by late interaction against the index, writing the matches into arena.
outcome<usearch_matches_tape_view_t> maxsim(
usearch_dense_maxsim_t arguments,
arena_t const & arena,
executor_t const & executor = {}) noexcept;Statuses
usearch_status_unknown_kind_kA traversal other than a walk or a scan.usearch_status_shape_mismatch_kA query without rows, or decreasing query offsets.usearch_status_unsupported_kA scan, a predicate, ragged query offsets or a zerowantedon a VRAM index.
init_ramCreates an empty RAM index of the geometry options freezes.
outcome<dense_index_t> init_ram(
usearch_dense_init_ram_t options) noexcept;Statuses
usearch_status_config_mismatch_kZerooptions.dimensions, dimensions a packed quantization leaves a storage value partly filled by, or a connectivity that is not a power of two.
init_vramCreates an empty VRAM index of the geometry options freezes, on the devices it names.
outcome<dense_index_t> init_vram(
usearch_dense_init_vram_t options) noexcept;Statuses
usearch_status_config_mismatch_kZerooptions.dimensions, a connectivity that is not a power of two, or on NVIDIA and AMD a geometry whose walks cannot fit the device's shared memory.
load_ramCopies a checkpoint into a new, mutable index in host memory.
outcome<dense_index_t> load_ram(
usearch_dense_load_ram_t options,
executor_t const & executor = {}) noexcept;Statuses
usearch_status_invalid_argument_kAn empty path, or a checkpoint or part path that does not parse.usearch_status_malformed_kThe checkpoint lists no part, or a part, its header or its key column does not parse, or its connectivity or dimensions are unusable.usearch_status_unknown_kind_kAn unknown quantization, a metric its quantization does not score, or a kernel a shard cannot finalize.usearch_status_unsupported_kA quantization this build leaves out, or a pinned class the CPU does not admit.usearch_status_uninitialized_kNo memory domain to place a shard on, orexecutorholds no pool workers.usearch_status_config_mismatch_kA memory domain refusing a shard, or the checkpoint's geometry, dtypes or metric differ from the shards'.usearch_status_device_kexecutoris not a RAM executor.usearch_status_contended_kAnother call holdsexecutor, or its pool runs another dispatch.usearch_status_overflow_kA part passes a shard's bound, a key column or the locator map.
load_vramCopies a checkpoint into a new, mutable index in device memory.
outcome<dense_index_t> load_vram(
usearch_dense_load_vram_t options,
executor_t const & executor = {}) noexcept;Statuses
usearch_status_invalid_argument_kAn empty path, or a checkpoint or part path that does not parse.usearch_status_malformed_kThe checkpoint lists no part, or a part, its header or its key column does not parse, or its connectivity or dimensions are unusable.usearch_status_unknown_kind_kAn unknown quantization, a metric its quantization does not score, or a kernel a shard cannot finalize.usearch_status_unsupported_kA quantization this build leaves out, or devices that do not run the pinned class.usearch_status_config_mismatch_kDevices of more than one vendor or generation,executordriving no stream on some shard's device, or the checkpoint's geometry, dtypes or metric differing from the shards'.usearch_status_device_kAn ordinal past the listing, devices this build carries no kernels for, or an executor that is not a VRAM executor.usearch_status_contended_kAnother call holdsexecutor.usearch_status_overflow_kA part passes a shard's bound, a key column or the locator map.
load_ram_bufferCopies a checkpoint from a memory buffer into a new, mutable index in host memory.
outcome<dense_index_t> load_ram_buffer(
usearch_dense_load_ram_buffer_t options,
executor_t const & executor = {}) noexcept;Statuses
usearch_status_invalid_argument_kAn empty buffer.usearch_status_malformed_kThe manifest lists no part, or a part, its header or its key column does not parse, or its connectivity or dimensions are unusable.usearch_status_unknown_kind_kAn unknown quantization, a metric its quantization does not score, or a kernel a shard cannot finalize.usearch_status_unsupported_kA quantization this build leaves out, or a pinned class the CPU does not admit.usearch_status_uninitialized_kNo memory domain to place a shard on, orexecutorholds no pool workers.usearch_status_config_mismatch_kA memory domain refusing a shard, or the checkpoint's geometry, dtypes or metric differ from the shards'.usearch_status_device_kexecutoris not a RAM executor.usearch_status_contended_kAnother call holdsexecutor, or its pool runs another dispatch.usearch_status_overflow_kA part passes a shard's bound, a key column or the locator map.
load_vram_bufferCopies a checkpoint from a memory buffer into a new, mutable index in device memory.
outcome<dense_index_t> load_vram_buffer(
usearch_dense_load_vram_buffer_t options,
executor_t const & executor = {}) noexcept;Statuses
usearch_status_invalid_argument_kAn empty buffer.usearch_status_malformed_kThe manifest lists no part, or a part, its header or its key column does not parse, or its connectivity or dimensions are unusable.usearch_status_unknown_kind_kAn unknown quantization, a metric its quantization does not score, or a kernel a shard cannot finalize.usearch_status_unsupported_kA quantization this build leaves out, or devices that do not run the pinned class.usearch_status_config_mismatch_kDevices of more than one vendor or generation,executordriving no stream on some shard's device, or the checkpoint's geometry, dtypes or metric differing from the shards'.usearch_status_device_kAn ordinal past the listing, devices this build carries no kernels for, or an executor that is not a VRAM executor.usearch_status_contended_kAnother call holdsexecutor.usearch_status_overflow_kA part passes a shard's bound, a key column or the locator map.
view_ramServes a checkpoint in place through a memory mapping, as a read-only index.
outcome<dense_index_t> view_ram(
usearch_dense_view_ram_t options) noexcept;Statuses
usearch_status_unsupported_kAlways, as RAM shards cannot serve a mapping in place yet.
view_nvmeServes a checkpoint in place from NVMe drives as a read-only index, every later call reading it through executor 's engines.
outcome<dense_index_t> view_nvme(
usearch_dense_view_nvme_t options,
executor_t const & executor = {}) noexcept;Statuses
usearch_status_device_kexecutoris not an NVMe executor.usearch_status_invalid_argument_kAn empty path,NULLpaths for a nonzero count, or a path that does not parse or names a base off its medium's block.usearch_status_config_mismatch_kParts disagreeing with each other, with the scalar or with the devices named.usearch_status_unsupported_kA transport identifier in a build without SPDK, a quantization this build leaves out, or a pinned class the CPU does not admit.usearch_status_malformed_kThe manifest names no part, or a manifest or header does not parse.usearch_status_unknown_kind_kAn unknown quantization, a metric its quantization does not score, or a kernel the stored scalar's kits cannot finalize.
metadata_readReads a checkpoint's geometry & metric without loading it.
outcome<usearch_dense_metadata_t> metadata_read(
usearch_dense_metadata_read_t arguments,
executor_t const & executor = {}) noexcept;Statuses
usearch_status_invalid_argument_kAn empty path, or a path that does not parse.usearch_status_malformed_kThe file is empty, or its manifest or header does not parse.
metadata_read_bufferReads geometry & metric from a serialized checkpoint buffer.
outcome<usearch_dense_metadata_t> metadata_read_buffer(
usearch_dense_metadata_read_buffer_t arguments,
executor_t const & executor = {}) noexcept;Statuses
usearch_status_invalid_argument_kAn empty buffer.usearch_status_malformed_kThe manifest or the header does not parse.