Introspection | USearch for C

One call reports an index’s frozen geometry and its current counters:

usearch_dense_index_description_t description = {0};
usearch_dense_describe(&(usearch_dense_describe_t) {
    .index = index, .executor = executor, .outcome = &outcome, .description = &description});
printf("%zu of %zu entries, %zu bytes, %zu dimensions, class: %s\n", description.size, description.capacity,
       description.memory_usage, description.metadata.dimensions, usearch_cpu_class_name(description.cpu_class));

usearch_dense_count reports how many entries a key holds, as when a long document is split into chunks. usearch_dense_health audits how much of the graph a search reaches, sweeping forward from as many landmarks as one search draws:

usearch_reachability_t reachability = {0};
usearch_dense_health(&(usearch_dense_health_t) {
    .index = index, .executor = executor, .outcome = &outcome, .reachability = &reachability});
// `reachability.reachable` of `reachability.audited` entries are found by some search

usearch_capabilities_compiled and usearch_capabilities_available name the SIMD and GPU capabilities the library was built with and the machine offers, and description.cpu_class or description.gpu_class names the class an index dispatched to, which usearch_cpu_class_name and usearch_gpu_class_name spell. usearch_version reports the linked library’s version, which may differ from the USEARCH_VERSION_MAJOR family of macros the caller compiled against.

API

Types

usearch_dense_index_description_tA live index's state.

dense_index.h:1922 ↗

struct usearch_dense_index_description_t

Each counter is read once, so under concurrent insertions they may come from slightly different moments.

Fields

`metadata`	`usearch_dense_metadata_t`	The frozen metric, quantization, dimensions and connectivity, as a checkpoint reports them.
`size`	`size_t`	Stored entries.
`capacity`	`size_t`	Entries hosted without growing again.
`memory_usage`	`size_t`	Bytes the handle holds; traversal scratch is the executor's.
`cpu_class`	`usearch_cpu_class_t`	The CPU class whose kits the index dispatched to on RAM and NVMe; `usearch_cpu_class_unknown_k` on VRAM.
`gpu_class`	`usearch_gpu_class_t`	The GPU class whose kernels the index dispatched to on VRAM; `usearch_gpu_class_unknown_k` on RAM and NVMe.
`shards_count`	`size_t`	Live shards, each a graph of its own; a fresh index has one per memory domain or device it was placed on.

usearch_geospatial_key_stats_tWhat one key holds, enough to size a buffer before retrieving any of it.

geospatial_index.h:1018 ↗

struct usearch_geospatial_key_stats_t

Fields

`entries`	`size_t`	Entries sharing the key; keys need not be unique.

usearch_geospatial_index_description_tA live index's state.

geospatial_index.h:1738 ↗

struct usearch_geospatial_index_description_t

Each counter is read once, so under concurrent insertions they may come from slightly different moments.

Fields

`metadata`	`usearch_geospatial_metadata_t`	The frozen connectivity, as a checkpoint reports it.
`size`	`size_t`	Stored entries.
`capacity`	`size_t`	Entries hosted without growing again.
`memory_usage`	`size_t`	Bytes the handle holds, observations and the terrain pack included; traversal scratch is the executor's.
`cpu_class`	`usearch_cpu_class_t`	The CPU class whose kits the index dispatched to on RAM and NVMe; `usearch_cpu_class_unknown_k` on VRAM.
`gpu_class`	`usearch_gpu_class_t`	The GPU class whose kernels the index dispatched to on VRAM; `usearch_gpu_class_unknown_k` on RAM and NVMe.
`shards_count`	`size_t`	Live shards, each a graph of its own; a fresh index has one per memory domain or device it was placed on.

usearch_sequence_key_stats_tWhat one key holds, enough to size a buffer before retrieving any of it.

sequence_index.h:902 ↗

struct usearch_sequence_key_stats_t

Fields

`entries`	`size_t`	Entries sharing the key; keys need not be unique.
`total_bytes`	`size_t`	Bytes summed across those entries.
`largest_bytes`	`size_t`	Bytes of the longest single entry.

usearch_sequence_index_description_tA live index's state.

sequence_index.h:1631 ↗

struct usearch_sequence_index_description_t

Each counter is read once, so under concurrent insertions they may come from slightly different moments.

Fields

`metadata`	`usearch_sequence_metadata_t`	The frozen metric and connectivity, as a checkpoint reports them.
`size`	`size_t`	Stored entries.
`capacity`	`size_t`	Entries hosted without growing again.
`memory_usage`	`size_t`	Bytes the handle holds, payload storage included; traversal scratch is the executor's.
`cpu_class`	`usearch_cpu_class_t`	The CPU class whose kits the index dispatched to on RAM and NVMe; `usearch_cpu_class_unknown_k` on VRAM.
`gpu_class`	`usearch_gpu_class_t`	The GPU class whose kernels the index dispatched to on VRAM; `usearch_gpu_class_unknown_k` on RAM and NVMe.
`shards_count`	`size_t`	Live shards, each a graph of its own; a fresh index has one per memory domain or device it was placed on.

usearch_shapes_key_stats_tWhat one key holds, enough to size a buffer before retrieving any of it.

shapes_index.h:898 ↗

struct usearch_shapes_key_stats_t

Fields

`entries`	`size_t`	Entries sharing the key; keys need not be unique.
`total_points`	`size_t`	Points summed across those entries.
`largest_points`	`size_t`	Points of the largest single entry.

usearch_shapes_index_description_tA live index's state.

shapes_index.h:1639 ↗

struct usearch_shapes_index_description_t

Each counter is read once, so under concurrent insertions they may come from slightly different moments.

Fields

`metadata`	`usearch_shapes_metadata_t`	The frozen metric, quantization, points and connectivity, as a checkpoint reports them.
`size`	`size_t`	Stored entries.
`capacity`	`size_t`	Entries hosted without growing again.
`total_points`	`size_t`	Points summed across every stored entry.
`memory_usage`	`size_t`	Bytes the handle holds, point storage included; traversal scratch is the executor's.
`cpu_class`	`usearch_cpu_class_t`	The CPU class whose kits the index dispatched to on RAM and NVMe; `usearch_cpu_class_unknown_k` on VRAM.
`gpu_class`	`usearch_gpu_class_t`	The GPU class whose kernels the index dispatched to on VRAM; `usearch_gpu_class_unknown_k` on RAM and NVMe.
`shards_count`	`size_t`	Live shards, each a graph of its own; a fresh index has one per memory domain or device it was placed on.

usearch_cpu_class_tThe CPU families USearch ships tuned variants for - dispatch reports its pick in this vocabulary, and callers may pin one.

types.h:509 ↗

enum usearch_cpu_class_t

Each class bundles the compute features, wait instruction, and atomics its silicon generation guarantees.

Values

`usearch_cpu_class_unknown_k`	`0`	No class detected.
`usearch_cpu_class_serial_k`		The portable floor: no SIMD assumptions, standard yields.
`usearch_cpu_class_intel_haswell_k`		Haswell-class x86: AVX2 & FMA, the 256-bit floor.
`usearch_cpu_class_intel_sierra_k`		Sierra Forest-class x86 - the E-core Xeons: AVX-VNNI and its successors without AVX-512, TPAUSE waits, CMPCCXADD conditional adds.
`usearch_cpu_class_intel_skylake_k`		Skylake-class x86: the AVX-512 foundation tier.
`usearch_cpu_class_intel_icelake_k`		Icelake-class x86: AVX-512 VNNI & VPOPCNT - the integer & bit workhorse.
`usearch_cpu_class_amd_genoa_k`		Genoa-class x86 - Zen 4 and newer: native bf16 dot products over AVX-512.
`usearch_cpu_class_intel_sapphire_k`		Sapphire Rapids-class x86: the Genoa bundle plus AVX-512 FP16 and the AMX-BF16 & AMX-INT8 tiles.
`usearch_cpu_class_intel_granite_k`		Granite Rapids-class x86: the Sapphire Rapids bundle plus the AMX-FP16 tiles.
`usearch_cpu_class_intel_diamond_k`		Diamond Rapids-class x86: the Granite Rapids bundle plus AVX10.2's FP8 conversions, TPAUSE waits, CMPCCXADD conditional adds.
`usearch_cpu_class_aws_g2_k`		Graviton2-class Arm - Neoverse N1, the bare NEON floor; phones predating Armv8.6 land here too.
`usearch_cpu_class_apple_m2_k`		Armv8.6+ NEON: dot products, bf16 & f16 fused multiplies - Apple M2, Cortex-A710 & X2 class silicon.
`usearch_cpu_class_apple_m4_k`		Apple M4-class Arm: the Armv8.6 NEON bundle plus the SME outer-product tiles.
`usearch_cpu_class_aws_g5_k`		Graviton5-class Arm - Neoverse V3, Armv9.2: monitored waits; no build compiles it yet.
`usearch_cpu_class_nvidia_vera_k`		Vera-class Arm - NVIDIA's Armv9.2-generation cores with FP8 dot products.
`usearch_cpu_class_alibaba_c930_k`		Alibaba C930-class RISC-V - T-Head's XuanTie core, RVA23: vectors with Zvbb, Zawrs monitored waits, Zacas single-instruction compare-and-swap.
`usearch_cpu_class_wasm32_v128_k`		WebAssembly every engine loads: 32-bit, single-threaded, the fixed-width simd128 tier.
`usearch_cpu_class_wasm64_extended_k`		WebAssembly with relaxed SIMD, shared memory for real thread pools, and the 64-bit addressing that alone lets one module's memory pass 4 GB.
`usearch_cpu_class_monoversioned_k`		The one class of a monoversioned build: every capability its floor implies or its preset vouches for, as the kernel libraries compiled them.

Spellings

char const * usearch_cpu_class_name(usearch_cpu_class_t cpu_class);

usearch_cpu_class_t usearch_cpu_class_from_name(
    usearch_bytes_view_t name);

usearch_gpu_class_tThe GPU families USearch ships tuned variants for, the device twin of usearch_cpu_class_t: one class per generation of kernel kits.

types.h:585 ↗

enum usearch_gpu_class_t

Values

`usearch_gpu_class_unknown_k`	`0`	No class detected.
`usearch_gpu_class_nvidia_ampere_k`		Ampere-class NVIDIA and every GPU without a class of its own - A100, A10 & RTX 30.
`usearch_gpu_class_nvidia_ada_k`		Ada-class NVIDIA - L4, L40S & RTX 40: the fp8 conversions.
`usearch_gpu_class_nvidia_hopper_k`		Hopper-class NVIDIA - H100 & H200: no TMA gather, DPX instructions.
`usearch_gpu_class_nvidia_blackwell_k`		Blackwell-class NVIDIA - B200, B300 & GB300: TMA gather4 scattered fetches.
`usearch_gpu_class_nvidia_blackwellrtx_k`		Consumer Blackwell NVIDIA - RTX 50, RTX PRO 6000 & DGX Spark.
`usearch_gpu_class_nvidia_rubin_k`		Rubin-class NVIDIA - the Vera-Rubin platform's device half.
`usearch_gpu_class_amd_cdna3_k`		CDNA3 AMD - MI300X & MI325X: gfx942, 64-wide waves, FNUZ fp8.
`usearch_gpu_class_amd_cdna4_k`		CDNA4 AMD - MI350X & MI355X: gfx950, OCP fp8.
`usearch_gpu_class_amd_cdna5_k`		CDNA5 AMD - MI400: gfx1250, 32-wide waves.
`usearch_gpu_class_apple_metal7_k`		Apple7-family GPUs and every Apple GPU without a class of its own - M1 & M2.
`usearch_gpu_class_apple_metal9_k`		Apple9-family GPUs - M3 & M4.
`usearch_gpu_class_apple_metal10_k`		Apple10-family GPUs - M5: the Neural Accelerator matrix units.

Spellings

char const * usearch_gpu_class_name(usearch_gpu_class_t gpu_class);

usearch_gpu_class_t usearch_gpu_class_from_name(
    usearch_bytes_view_t name);

usearch_reachability_tOne reachability audit: the population it judged, and how much of it a search reaches.

types.h:723 ↗

struct usearch_reachability_t

Fields

`audited`	`size_t`	Entries published when the audit started - the population it judges; entries inserted while it ran are not counted, so compare `reachable` against this, never a later size.
`reachable`	`size_t`	Of those, the entries a search reaches from the landmarks; the rest no search finds until a refinement re-links them.
`sweeps`	`size_t`	Levels the sweep took to converge; the deepest shard's on a sharded handle.
`back_sweeps`	`size_t`	Levels the sweep back toward the entry point took, where an audit sweeps both ways; the deepest shard's on a sharded handle.

usearch_nvme_class_tThe I/O engines USearch drives external memory through, newest first; an executor pinned to one tries it and degrades down the ladder the media admit.

types.h:1177 ↗

enum usearch_nvme_class_t

Values

`usearch_nvme_class_unknown_k`	`0`	Derives the newest engine the host and the media admit: io_uring, then Linux AIO, then blocking reads on kernel paths, and SPDK on transport identifiers.
`usearch_nvme_class_posix_k`		`pread` or `ReadFile` on the calling thread.
`usearch_nvme_class_linux_aio_k`		Linux AIO over `io_submit` and `io_getevents`, with `O_DIRECT`.
`usearch_nvme_class_linux_uring_k`		io_uring reads on files and block devices.
`usearch_nvme_class_linux_uring_passthrough_k`		io_uring NVMe passthrough on namespace character devices, such as `/dev/ng0n1`.
`usearch_nvme_class_linux_spdk_k`		The SPDK user-space driver, over namespaces named by transport identifiers.
`usearch_nvme_class_windows_ioring_k`		I/O Rings, on Windows 11 22H2 and newer.

Spellings

char const * usearch_nvme_class_name(usearch_nvme_class_t nvme_class);

usearch_nvme_class_t usearch_nvme_class_from_name(
    usearch_bytes_view_t name);

Functions

usearch_dense_healthAudits how much of the graph a search can reach: forward reachability from as many landmarks as one search draws, swept level by level.

dense_index.h:913 ↗

void usearch_dense_health(usearch_dense_health_t *arguments);

Read-only, so concurrent insertions merely leave fresh entries unaudited.

Parameters

`indexusearch_dense_index_t`		The handle to be audited.
`executorusearch_executor_t`		The executor to fan out over; its kind must match the residency.
`outcomeusearch_outcome_t *`		Output for the outcome, final once its status leaves `usearch_status_deferred_k`.
`completionusearch_completion_t`		Blocking, the default, or deferred.
`reachabilityusearch_reachability_t *`		Output for the audit; zeroed on failure.

Statuses

usearch_status_device_k The executor's kind does not match the residency.
usearch_status_uninitialized_k No shard is placed, the executor holds no pool workers or streams, or a VRAM handle keeps such an earlier failure.
usearch_status_contended_k Another call holds the executor or its pool, or a destructive window overlapped the audit twice.
usearch_status_config_mismatch_k The executor drives no stream on some VRAM shard's device, an NVMe medium the engines cannot read, or a VRAM handle keeps such an earlier failure.
usearch_status_overflow_k A VRAM handle keeps an earlier overflow.
usearch_status_unsupported_k or usearch_status_unsupported_layout_k A VRAM handle keeps such an earlier failure.

usearch_dense_countCounts the entries stored under one key.

dense_index.h:1070 ↗

void usearch_dense_count(usearch_dense_count_t *arguments);

Every entry is one row of dimensions, so the count is the whole extent and there is nothing further to report - the sibling modalities report stats here only because their entries vary in size.

Parameters

`indexusearch_dense_index_t`		The handle to be queried.
`executorusearch_executor_t`		The executor the lookup runs on.
`outcomeusearch_outcome_t *`		Output for the outcome, final once its status leaves `usearch_status_deferred_k`.
`completionusearch_completion_t`		Blocking, the default, or deferred.
`keyusearch_key_t`		The key whose entries are counted.
`entriessize_t *`		Output for the entries sharing `key`; zero means the index holds none.

Statuses

usearch_status_device_k The executor's kind does not match the residency.
usearch_status_uninitialized_k The executor holds no pool workers.
usearch_status_contended_k Another call holds the executor, or its pool runs another dispatch.
usearch_status_config_mismatch_k An NVMe medium the engines cannot read.

usearch_*_describe× 4Reports a live index's frozen metadata and current counters in one call.

dense_index.h:1969 ↗

void usearch_dense_describe(usearch_dense_describe_t *arguments);

Symbol	`index`	`description`
`usearch_dense_describe`	`usearch_dense_index_t`	`usearch_dense_index_description_t`
`usearch_geospatial_describe`	`usearch_geospatial_index_t`	`usearch_geospatial_index_description_t`
`usearch_sequence_describe`	`usearch_sequence_index_t`	`usearch_sequence_index_description_t`
`usearch_shapes_describe`	`usearch_shapes_index_t`	`usearch_shapes_index_description_t`

Parameters

`indexusearch_dense_index_t`		The handle to be described.
`executorusearch_executor_t`		The executor the report runs on.
`outcomeusearch_outcome_t *`		Output for the outcome, final once its status leaves `usearch_status_deferred_k`.
`completionusearch_completion_t`		Blocking, the default, or deferred.
`descriptionusearch_dense_index_description_t *`		Output, filled whole.

usearch_*_health× 3Audits how much of the graph a search can reach: every shard swept level by level from its first entry, forward and back.

geospatial_index.h:856 ↗

void usearch_geospatial_health(usearch_geospatial_health_t *arguments);

Symbol	`index`
`usearch_geospatial_health`	`usearch_geospatial_index_t`
`usearch_sequence_health`	`usearch_sequence_index_t`
`usearch_shapes_health`	`usearch_shapes_index_t`

Read-only, so concurrent insertions merely leave fresh entries out of the audit.

An NVMe view sweeps forward alone, from entries spaced through each part, so its back_sweeps stays zero.

Parameters

`indexusearch_geospatial_index_t`		The handle to be audited.
`executorusearch_executor_t`		The executor to fan out over; its kind must match the residency.
`outcomeusearch_outcome_t *`		Output for the outcome, final once its status leaves `usearch_status_deferred_k`.
`completionusearch_completion_t`		Blocking, the default, or deferred.
`reachabilityusearch_reachability_t *`		Output for the audit; zeroed on failure.

Statuses

usearch_status_device_k The executor's kind does not match the residency.
usearch_status_uninitialized_k No shard is placed, or the executor holds no pool workers or streams.
usearch_status_contended_k Another call holds the executor or its pool, or a destructive window overlapped the audit twice.
usearch_status_config_mismatch_k The executor drives no stream on some VRAM shard's device, or an NVMe medium the engines cannot read.
usearch_status_io_k A read from an NVMe view's drives failed.

usearch_geospatial_countCounts the entries stored under one key, on every residency.

geospatial_index.h:1056 ↗

void usearch_geospatial_count(usearch_geospatial_count_t *arguments);

Parameters

`indexusearch_geospatial_index_t`		The handle to be queried.
`executorusearch_executor_t`		The executor the lookup runs on.
`outcomeusearch_outcome_t *`		Output for the outcome, final once its status leaves `usearch_status_deferred_k`.
`completionusearch_completion_t`		Blocking, the default, or deferred.
`keyusearch_key_t`		The key whose entries are counted.
`key_statsusearch_geospatial_key_stats_t *`		Output for what `key` holds; zero `entries` means the index holds none.

Statuses

usearch_status_device_k An NVMe view's executor is not an NVMe executor.
usearch_status_uninitialized_k An NVMe view's executor holds no pool workers.
usearch_status_contended_k Another call holds an NVMe view's executor, or its pool runs another dispatch.
usearch_status_config_mismatch_k An NVMe medium the engines cannot read.

usearch_sequence_countCounts the entries stored under one key, with their payload extent.

sequence_index.h:949 ↗

void usearch_sequence_count(usearch_sequence_count_t *arguments);

A GPU handle counts the entries alone and leaves the extents zero, because its payloads stay on the devices themselves.

Parameters

`indexusearch_sequence_index_t`		The handle to be queried.
`executorusearch_executor_t`		The executor the lookup runs on.
`outcomeusearch_outcome_t *`		Output for the outcome, final once its status leaves `usearch_status_deferred_k`.
`completionusearch_completion_t`		Blocking, the default, or deferred.
`keyusearch_key_t`		The key whose entries are counted.
`key_statsusearch_sequence_key_stats_t *`		Output for what `key` holds; zero `entries` means the index holds none.

Statuses

usearch_status_device_k An NVMe view's executor is not an NVMe executor.
usearch_status_uninitialized_k An NVMe view's executor holds no pool workers.
usearch_status_contended_k Another call holds an NVMe view's executor, or its pool runs another dispatch.
usearch_status_config_mismatch_k An NVMe medium the engines cannot read.

usearch_shapes_countCounts the entries stored under one key, with the extent of their points.

shapes_index.h:945 ↗

void usearch_shapes_count(usearch_shapes_count_t *arguments);

A GPU handle counts the entries alone and leaves the extents zero, because its payloads stay on the devices themselves.

Parameters

`indexusearch_shapes_index_t`		The handle to be queried.
`executorusearch_executor_t`		The executor the lookup runs on.
`outcomeusearch_outcome_t *`		Output for the outcome, final once its status leaves `usearch_status_deferred_k`.
`completionusearch_completion_t`		Blocking, the default, or deferred.
`keyusearch_key_t`		The key whose entries are counted.
`key_statsusearch_shapes_key_stats_t *`		Output for what `key` holds; zero `entries` means the index holds none.

Statuses

usearch_status_device_k An NVMe view's executor is not an NVMe executor.
usearch_status_uninitialized_k An NVMe view's executor holds no pool workers.
usearch_status_contended_k Another call holds an NVMe view's executor, or its pool runs another dispatch.
usearch_status_config_mismatch_k An NVMe medium the engines cannot read.

usearch_versionReports the version of the library this process linked, which may differ from the USEARCH_VERSION_MAJOR family of macros it was compiled against.

types.h:1428 ↗

void usearch_version(int *major, int *minor, int *patch);

Parameters

`major`	out	The major version, which changes whenever an argument structure does.
`minor`	out	The minor version.
`patch`	out	The patch version.

usearch_version_nameThe version of the library as a static null-terminated string, like "3.0.0".

types.h:1431 ↗

char const * usearch_version_name(void);

usearch_capabilities_compiledRetrieves the kernel families the CPU classes this binary compiled reach.

types.h:1437 ↗

char const * usearch_capabilities_compiled(void);

Returns

A comma-separated static string with capability names.

usearch_capabilities_availableRetrieves the kernel families of the newest CPU class the current machine runs.

types.h:1444 ↗

char const * usearch_capabilities_available(void);

Returns

A comma-separated static string with capability names, empty where the machine runs no class this build compiled, as a monoversioned build on an older CPU.

Macros

USEARCH_VERSION_MAJORMarks exported functions: exported while building the shared library, imported when consuming it on Windows, and of default visibility on ELF and Mach-O.

types.h:131 ↗

#define USEARCH_VERSION_MAJOR 3

Define it to override. The library's version, which the release tooling rewrites in place.