# 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.

```mojo
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.

`from usearch import DenseMetadata, BytesView, Monolith`

## DenseMetadata

The geometry and metric a checkpoint froze - `usearch_dense_metadata_t`, a pure output.

```mojo
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.

- `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.

```mojo
def __init__(out self)
```

## BytesView

A borrowed run of bytes and its length - `usearch_bytes_view_t`, never null-terminated.

```mojo
struct BytesView[origin: ImmOrigin = ImmUntrackedOrigin]
```

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

- `origin` (comptime): The borrowed storage, named so it outlives every call this view crosses.

- `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`

## of

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

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

```mojo
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`](https://www.unum.cloud/docs/usearch/mojo/executors.md#save_buffer) returns.

- `text_origin` (comptime): The string's origin, inferred from the argument.
- `text`: The characters to hand over.
- `bytes_origin` (comptime): The run's origin, inferred from the argument.
- `bytes`: The bytes to hand over.

## untracked

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

```mojo
def untracked(self) -> BytesView
```

## Monolith

The serialized index [`save_buffer`](https://www.unum.cloud/docs/usearch/mojo/executors.md#save_buffer) lands in its arena, read in place.

```mojo
struct Monolith[origin: MutOrigin]
```

- `origin` (comptime): The arena the bytes live in, which this result borrows.

- `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`

## bytes

The monolith, borrowed from the arena this result reads.

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

Raises: [`Error`](https://www.unum.cloud/docs/usearch/mojo/errors.md#Error) with [`UNINITIALIZED`](https://www.unum.cloud/docs/usearch/mojo/errors.md#UNINITIALIZED) once a later call rewound the arena, or [`DEVICE`](https://www.unum.cloud/docs/usearch/mojo/errors.md#DEVICE) over VRAM.

## dense_metadata_read

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

```mojo
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.

- `path_origin` (comptime): The path bytes' origin, inferred from the argument.
- `executor`: The executor the read runs on; it also lends its engine.
- `path`: The manifest of a sharded checkpoint, or a single monolith.

Raises: [`Error`](https://www.unum.cloud/docs/usearch/mojo/errors.md#Error) if the checkpoint cannot be opened or its header cannot be decoded.

## dense_metadata_read_buffer

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

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

- `buffer_origin` (comptime): The source bytes' origin, inferred from the argument.
- `executor`: The executor the read runs on; it also lends its engine.
- `buffer`: Source holding one serialized monolith.

Raises: [`Error`](https://www.unum.cloud/docs/usearch/mojo/errors.md#Error) if the bytes cannot be decoded.