Serialization | USearch for Mojo

Checkpoints ride the SafeGraphs interchange format, and the path extension picks the layout. A .safegraphs path is one self-describing monolith; a .safegraphs.json path is a manifest cataloging many, with every shard path resolved relative to it. In-memory buffers hold single monoliths only.

index.on(executor).save("index.safegraphs")
var restored = DenseIndex.load_ram(executor, "index.safegraphs")
var viewed = DenseIndex.view_ram(library, "index.safegraphs")  # read-only, served from the mapping
var metadata = dense_metadata_read(executor, "index.safegraphs")  # geometry without loading a shard

var monolith = index.save_buffer(arena)
var copied = DenseIndex.load_ram_buffer(executor, monolith.bytes())

Loading creates the index, freezing its geometry from the checkpoint’s own headers. The metadata carries only the four fields a checkpoint froze, so values_per_key and the placement stay yours to pass to the load.

API

StructDenseMetadataThe geometry and metric a checkpoint froze - usearch_dense_metadata_t, a pure output.1

struct DenseMetadata

Everything a reader learns without opening the checkpoint, and nothing a reader must choose for itself. Placement is absent because a checkpoint records where it was written rather than where a reader must keep it, and values_per_key is absent because it bounds a live handle's mutable state rather than anything the serialized form carries.

Never marked register-passable: its address crosses to C, and Mojo 1.1 mislays a struct once it is, so the probes would read back nothing.

Fields

`metric`	`DenseMetric`	The metric kind the checkpoint scores with.
`quantization`	`ScalarKind`	The scalar type its vectors are stored and quantized into.
`dimensions`	`c_size_t`	Scalars per stored vector.
`connectivity`	`c_size_t`	Connections per node the graph was built with.

Conforms to

Copyable, Defaultable, Deinitable, ImplicitlyCopyable, Movable

__init__Names no kind and no geometry, so an unwritten slot reads as an unanswered probe.

def __init__(out self)

StructBytesViewA borrowed run of bytes and its length - usearch_bytes_view_t, never null-terminated.2

struct BytesView[origin: ImmOrigin = ImmUntrackedOrigin]

Crosses by value, which the two-word argument class handles on both x86-64 and AArch64.

Parameters

`originImmOrigin`	comptime	The borrowed storage, named so it outlives every call this view crosses.

Fields

`data`	`CString`	The first byte, borrowed for the duration of the call.
`length`	`c_size_t`	How many bytes the run covers, since nothing terminates it.

Conforms to

Copyable, Deinitable, ImplicitlyCopyable, Movable, RegisterPassable, TrivialRegisterPassable

ofBorrows a Mojo string's bytes, which the caller keeps alive across the call.

def of[text_origin: ImmOrigin, //](text: StringSpan[text_origin]) -> BytesView[text_origin]

def of[bytes_origin: ImmOrigin, //](bytes: Span[UInt8, bytes_origin]) -> BytesView[bytes_origin]

Borrows a run of raw bytes, such as the monolith save_buffer returns.

Parameters

`text_originImmOrigin`	comptime	The string's origin, inferred from the argument.
`textStringSpan[text_origin]`		The characters to hand over.
`bytes_originImmOrigin`	comptime	The run's origin, inferred from the argument.
`bytesSpan[UInt8, bytes_origin]`		The bytes to hand over.

Returns

A view of exactly those bytes, with no terminator manufactured.

untrackedThe same run with its borrow erased - the one instantiation the ABI signatures name.

def untracked(self) -> BytesView

Returns

A view of the same bytes, whose type no longer keeps their storage alive.

StructMonolithThe serialized index save_buffer lands in its arena, read in place.1

struct Monolith[origin: MutOrigin]

Parameters

`originMutOrigin`	comptime	The arena the bytes live in, which this result borrows.

Fields

`arena`	`Pointer[Arena, origin]`	The arena holding the bytes.
`generation`	`Int`	The arena's call these bytes came from, so a read after a later call is refused.
`data`	`Address`	The first byte, inside the arena.
`length`	`Int`	Bytes the monolith spans.

Conforms to

Deinitable, Movable

bytesThe monolith, borrowed from the arena this result reads.

def bytes(ref self) -> Span[UInt8, origin_of(self)]

Returns

The bytes, valid until the arena's next call.

Raises

Error with UNINITIALIZED once a later call rewound the arena, or DEVICE over VRAM.

Functions

dense_metadata_readReads a checkpoint's geometry and metric without loading it. Calls usearch_dense_metadata_read.

def dense_metadata_read[path_origin: ImmOrigin, //](
    executor: Executor,
    path: StringSpan[path_origin]
) -> DenseMetadata

A manifest answers from its summary and its first part's header, so the cost does not grow with the index.

Parameters

`path_originImmOrigin`	comptime	The path bytes' origin, inferred from the argument.
`executorExecutor`		The executor the read runs on; it also lends its engine.
`pathStringSpan[path_origin]`		The manifest of a sharded checkpoint, or a single monolith.

Returns

The geometry and metric the checkpoint froze.

Raises

Error if the checkpoint cannot be opened or its header cannot be decoded.

dense_metadata_read_bufferReads a serialized monolith's geometry and metric without loading it. Calls usearch_dense_metadata_read_buffer.

def dense_metadata_read_buffer[buffer_origin: ImmOrigin, //](
    executor: Executor,
    buffer: Span[UInt8, buffer_origin]
) -> DenseMetadata

Parameters

`buffer_originImmOrigin`	comptime	The source bytes' origin, inferred from the argument.
`executorExecutor`		The executor the read runs on; it also lends its engine.
`bufferSpan[UInt8, buffer_origin]`		Source holding one serialized monolith.

Returns

The geometry and metric the monolith froze.

Raises

Error if the bytes cannot be decoded.