Metrics | USearch for Mojo

§ Dense Indexes

DenseOptions freezes an index’s geometry: its dimensions, metric, quantization, connectivity and values_per_key, angular over BF16 vectors unless told otherwise, with every zeroed optional field derived. DenseMetric names INNER, ANGULAR, EUCLIDEAN, HAMMING and JACCARD; the last two read vectors as ScalarKind.U1X8 bit sets and refuse any other quantization. Insertions and searches overlap freely on one handle: a search never writes to the graph, and an insertion publishes an entry only once it is reachable. multiply, maxsim and attend treat the index as a sparse operand, folding their arithmetic into the walk instead of materializing a match list, and need logits rather than distances, so they run on DenseMetric.INNER alone and refuse other metrics with Status.CONFIG_MISMATCH.

API

Types

DistanceA distance or similarity score in the metric of the index that produced it - usearch_distance_t.

comptime Distance = Float64

StructDenseMetricThe built-in dense metrics - usearch_dense_metric_t, each with its own SIMD kernel chain.

struct DenseMetric

The last two read their rows as ScalarKind.U1X8 bit sets and refuse any other quantization; the first four refuse that one. The three linear-algebra verbs run on INNER alone, since a product and a softmax both need logits rather than distances. Library.dense_metric_name spells each one as the engine does.

Fields

`code`	`c_int`	The raw `usearch_dense_metric_t` value the ABI exchanges.

Values

`UNKNOWN`	`DenseMetric(Int32(0))`	No kind named - an unset field, refused by every constructor.
`INNER`	`DenseMetric(Int32(1))`	Sum of elementwise products, unnormalized and scale-sensitive.
`ANGULAR`	`DenseMetric(Int32(2))`	Cosine distance in [0, 2], blind to magnitude.
`EUCLIDEAN`	`DenseMetric(Int32(3))`	L2 distance, zero only for identical vectors.
`HAMMING`	`DenseMetric(Int32(4))`	Count of differing bits, so its range is the dimensionality.
`JACCARD`	`DenseMetric(Int32(5))`	Differing bits over union bits in [0, 1], ignoring the zeros both vectors share.

Conforms to

Copyable, Deinitable, Equatable, ImplicitlyCopyable, Movable, RegisterPassable, TrivialRegisterPassable

StructDenseOptionsThe geometry an empty index freezes - what usearch_dense_init_ram_t and usearch_dense_init_vram_t share, without the placement each names its own way.1

struct DenseOptions

Zeroed optional fields derive from the geometry.

Fields

`metric`	`DenseMetric`	The metric kind used for distance calculations between vectors.
`quantization`	`ScalarKind`	The scalar type vectors are stored and quantized into.
`dimensions`	`c_size_t`	Dimensions in the indexed vectors.
`connectivity`	`c_size_t`	The connections-per-node bound; zero derives.
`values_per_key`	`c_size_t`	Upper bound on entries sharing one key; zero is unbounded.

Conforms to

Copyable, Deinitable, ImplicitlyCopyable, Movable

__init__Describes an index by its geometry, angular over BF16 vectors unless told otherwise.

def __init__(
    out self,
    dimensions: Int,
    metric: DenseMetric = DenseMetric.ANGULAR,
    quantization: ScalarKind = ScalarKind.BF16,
    connectivity: Int = Int(0),
    values_per_key: Int = Int(0)
)

Parameters

`dimensionsInt`		Dimensions per vector.
`metricDenseMetric`		The metric kind the graph is frozen under.
`quantizationScalarKind`		The scalar type vectors are stored as.
`connectivityInt`		The connections-per-node bound; zero derives.
`values_per_keyInt`		Upper bound on entries sharing one key; zero is unbounded.

StructDenseIndexA dense vector index, released when it goes out of scope.14

struct DenseIndex

Insertions and searches overlap freely on one handle: a search never writes to the graph, and an insertion publishes an entry only once it is reachable, so a concurrent walk sees a consistent graph at every instant. Calls on one executor run in submission order.

Verbs called on the index run on the calling thread; index.on(executor) runs the same verbs blocking on an executor, and index.deferred(executor) submits them there. The cursor and the stream's opening name no executor, and their pulls run on the receiver's.

Fields

`library`	`Library`	The loaded engine, held so its symbol table outlives every call made through the handle.
`address`	`Address`	The opaque `usearch_dense_index_t`, or zero once an absorb has consumed it.

Conforms to

Deinitable, DenseVerbs, Movable

__init__Adopts a handle the engine just created.

def __init__(out self, *, library: Library, address: Int)

Parameters

`libraryLibrary`		The loaded engine the handle was created through, and is freed through.
`addressInt`		A `usearch_dense_index_t` whose lifetime this index takes over.

__deinit__Releases the index and everything it owns, unless an absorb already took the handle. Calls usearch_dense_free.

def __deinit__(deinit self)

The loader reference is surrendered only after the call: reading the entry point is the last use of library, so without the trailing move Mojo drops the last reference - and dlcloses the engine - between the load and the branch to it.

init_ramInitializes an empty, mutable index in host memory. Calls usearch_dense_init_ram.

def init_ram[ram_origin: ImmOrigin, //](
    library: Library,
    options: DenseOptions,
    ram: RamOptions[ram_origin] = RamOptions()
) -> Self

Parameters

`ram_originImmOrigin`	comptime	The options' borrowed node-id array, inferred from the argument.
`libraryLibrary`		The loaded engine, kept so the shared object stays mapped.
`optionsDenseOptions`		The geometry and metric; read only during this call.
`ramRamOptions[ram_origin]`		The memory domains to place one shard on apiece.

Returns

The new index.

Raises

Error if the geometry is refused, the placement cannot be resolved, or the allocation fails.

init_vramInitializes an empty, mutable index in device memory. Calls usearch_dense_init_vram.

def init_vram[vram_origin: ImmOrigin, //](
    library: Library,
    options: DenseOptions,
    vram: VramOptions[vram_origin] = VramOptions()
) -> Self

Parameters

`vram_originImmOrigin`	comptime	The options' borrowed ordinal array, inferred from the argument.
`libraryLibrary`		The loaded engine, kept so the shared object stays mapped.
`optionsDenseOptions`		The geometry and metric; read only during this call.
`vramVramOptions[vram_origin]`		The devices to place one shard on apiece.

Returns

The new index.

Raises

Error if the geometry is refused, or a device cannot be selected or claimed.

load_ramCopies a checkpoint into a new, mutable index in host memory, shard by shard. Calls usearch_dense_load_ram.

def load_ram[path_origin: ImmOrigin, ram_origin: ImmOrigin, //](
    executor: Executor,
    path: StringSpan[path_origin],
    ram: RamOptions[ram_origin] = RamOptions(),
    values_per_key: Int = Int(0)
) -> Self

Point the path at the manifest, never at one of the parts it enumerates - naming a part loads exactly that part, which is a fragment of the index rather than the index. Part p lands whole on shard p modulo the shard count, wherever it was written from.

Parameters

`path_originImmOrigin`	comptime	The path bytes' origin, inferred from the argument.
`ram_originImmOrigin`	comptime	The options' borrowed node-id array, inferred from the argument.
`executorExecutor`		The executor the read fans out over, one shard per thread; it also lends its engine.
`pathStringSpan[path_origin]`		The manifest of a sharded checkpoint, or a single `.safegraphs` monolith.
`ramRamOptions[ram_origin]`		The memory domains to place the parts on.
`values_per_keyInt`		Upper bound on entries sharing one key, which no checkpoint records.

Returns

The new index; a failed load creates none.

Raises

Error if the checkpoint cannot be read or decoded.

load_ram_bufferCopies a monolith from a memory buffer into a new, mutable index in host memory. Calls usearch_dense_load_ram_buffer.

def load_ram_buffer[buffer_origin: ImmOrigin, ram_origin: ImmOrigin, //](
    executor: Executor,
    buffer: Span[UInt8, buffer_origin],
    ram: RamOptions[ram_origin] = RamOptions(),
    values_per_key: Int = Int(0)
) -> Self

Parameters

`buffer_originImmOrigin`	comptime	The source bytes' origin, inferred from the argument.
`ram_originImmOrigin`	comptime	The options' borrowed node-id array, inferred from the argument.
`executorExecutor`		The executor the copy fans out over; it also lends its engine.
`bufferSpan[UInt8, buffer_origin]`		Source holding one serialized monolith.
`ramRamOptions[ram_origin]`		The memory domains to place shards on; the monolith lands whole on the first.
`values_per_keyInt`		Upper bound on entries sharing one key, which no checkpoint records.

Returns

The new index; a failed load creates none.

Raises

Error if the bytes cannot be decoded.

load_vramCopies a checkpoint into a new, mutable index in device memory, with the placement rules of load_ram. Calls usearch_dense_load_vram.

def load_vram[path_origin: ImmOrigin, vram_origin: ImmOrigin, //](
    executor: Executor,
    path: StringSpan[path_origin],
    vram: VramOptions[vram_origin] = VramOptions(),
    values_per_key: Int = Int(0)
) -> Self

Parameters

`path_originImmOrigin`	comptime	The path bytes' origin, inferred from the argument.
`vram_originImmOrigin`	comptime	The options' borrowed ordinal array, inferred from the argument.
`executorExecutor`		The executor the upload runs on, one stream per device; it also lends its engine.
`pathStringSpan[path_origin]`		The manifest of a sharded checkpoint, or a single `.safegraphs` monolith.
`vramVramOptions[vram_origin]`		The devices to place the parts on.
`values_per_keyInt`		Upper bound on entries sharing one key, which no checkpoint records.

Returns

The new index; a failed load creates none.

Raises

Error if the checkpoint cannot be read, or a device cannot hold it.

load_vram_bufferCopies a monolith from a host or device buffer into a new, mutable index in device memory. Calls usearch_dense_load_vram_buffer.

def load_vram_buffer[buffer_origin: ImmOrigin, vram_origin: ImmOrigin, //](
    executor: Executor,
    buffer: Span[UInt8, buffer_origin],
    vram: VramOptions[vram_origin] = VramOptions(),
    values_per_key: Int = Int(0)
) -> Self

Parameters

`buffer_originImmOrigin`	comptime	The source bytes' origin, inferred from the argument.
`vram_originImmOrigin`	comptime	The options' borrowed ordinal array, inferred from the argument.
`executorExecutor`		The executor the upload runs on, one stream per device; it also lends its engine.
`bufferSpan[UInt8, buffer_origin]`		Source holding one serialized monolith.
`vramVramOptions[vram_origin]`		The devices to place shards on; the monolith lands whole on the first.
`values_per_keyInt`		Upper bound on entries sharing one key, which no checkpoint records.

Returns

The new index; a failed load creates none.

Raises

Error if the bytes cannot be decoded, or a device cannot hold them.

view_ramServes a checkpoint in place through a memory mapping, as a read-only index. Calls usearch_dense_view_ram.

def view_ram[path_origin: ImmOrigin, //](library: Library, path: StringSpan[path_origin]) -> Self

Nothing is copied, so opening costs the headers alone. Every mutating verb on the handle raises with READ_ONLY, and the files must stay unmodified until the handle is released.

Parameters

`path_originImmOrigin`	comptime	The path bytes' origin, inferred from the argument.
`libraryLibrary`		The loaded engine, kept so the shared object stays mapped.
`pathStringSpan[path_origin]`		The manifest of a sharded checkpoint, or a single `.safegraphs` monolith.

Returns

The read-only index.

Raises

Error if the checkpoint cannot be mapped or decoded.

view_nvmeServes a checkpoint in place from NVMe drives, read through the executor's rings. Calls usearch_dense_view_nvme.

def view_nvme[path_origin: ImmOrigin, nvme_origin: ImmOrigin, //](
    executor: Executor,
    path: StringSpan[path_origin],
    nvme: NvmeOptions[nvme_origin] = NvmeOptions()
) -> Self

Parameters

`path_originImmOrigin`	comptime	The path bytes' origin, inferred from the argument.
`nvme_originImmOrigin`	comptime	The options' borrowed path array, inferred from the argument.
`executorExecutor`		The NVMe executor whose rings read the checkpoint's headers; it also lends its engine.
`pathStringSpan[path_origin]`		The manifest of a sharded checkpoint, or a single `.safegraphs` monolith.
`nvmeNvmeOptions[nvme_origin]`		The devices the parts are served from; naming none serves each where it points.

Returns

The read-only index.

Raises

Error with UNSUPPORTED until NVMe checkpoints carry keys and a shard wrapper.

onThe same verbs, blocking on executor after every call submitted there before them. Binding-only.

def on(ref self, ref executor: Executor) -> DenseIndexOn[origin_of(executor, self)]

Parameters

`executorExecutor`		The executor every verb runs on; its kind must match the handle's residency.

Returns

A receiver borrowing both, which neither may outlive.

deferredThe same verbs, each submitted to executor and answering a Deferred at once. Binding-only.

def deferred(ref self, ref executor: Executor) -> DenseIndexDeferredOn[origin_of(executor, self)]

Parameters

`executorExecutor`		The executor every verb is submitted to; its kind must match the handle's residency.

Returns

A receiver borrowing both, which neither it nor any Deferred it answers may outlive.

cursorOpens a walk over every entry as stored, its pulls on the calling thread. Calls usearch_dense_cursor_init.

def cursor(ref self) -> DenseCursor[origin_of(self)]

def cursor[starts_origin: ImmOrigin, //](
    ref self,
    starts: Span[Key, starts_origin]
) -> DenseCursor[origin_of(self)]

Opens a walk from starts, its pulls on the calling thread. Calls usearch_dense_cursor_init.

Each shard's publication watermark is read as the walk enters that shard, so an entry once passed is never revisited.

Parameters

`starts_originImmOrigin`	comptime	The start keys' origin, inferred from the argument.
`startsSpan[Key, starts_origin]`		The keys to walk from.

Returns

The cursor, which borrows the index and cannot outlive it.

Raises

Error if the residency has no cursor, as VRAM does not.

search_streamOpens a resumable nearest-neighbor stream for one query, its pulls on the calling thread. Calls usearch_dense_search_stream_init.

def search_stream[query_origin: ImmOrigin, //](
    ref self,
    query: RowsView[query_origin],
    config: DenseSearchStreamInitConfig = DenseSearchStreamInitConfig(expansion_factor=Int(0))
) -> DenseSearchStream[origin_of(query_origin, self)]

The stream keeps walk state rather than a thread, so any number may stay open at once.

Parameters

`query_originImmOrigin`	comptime	The query row's origin, inferred from the argument.
`queryRowsView[query_origin]`		The single query row; a view of more rows has its first row read.
`configDenseSearchStreamInitConfig`		The breadth of the candidates the walk explores.

Returns

A stream yielding matches lazily, which borrows the index and the query.

Raises

Error with UNSUPPORTED while no residency implements the stream.