Serialization | USearch for Zig

The path extension picks the layout: a .safegraphs path is one monolith, and a .safegraphs.json path is a manifest cataloging many.

try index.on(executor).save("index.safegraphs", .{});
var copy = try usearch.DenseIndex.loadRam("index.safegraphs", .{ .executor = executor, .values_per_key = 1 });
var uploaded = try usearch.DenseIndex.loadVram("index.safegraphs", .{ .executor = gpu, .devices = &.{0} });
var mapped = try usearch.DenseIndex.viewRam("index.safegraphs"); // read-only, served in place

const metadata = try usearch.DenseIndex.metadataRead("index.safegraphs", .{}); // without loading a shard

The result carries only the four fields a checkpoint froze, so values_per_key and the placement stay yours to set in the load config.

Checkpoints are residency-portable: one file copies into RAM, uploads to a device, or is served in place on disk, decided by the constructor that reads it. In-memory buffers hold single monoliths only. saveBuffer lands one in an Arena, since only the call knows its length, and loadRamBuffer or loadVramBuffer reads it back.

const monolith = try index.saveBuffer(&arena, .{});
var restored = try usearch.DenseIndex.loadRamBuffer(try monolith.bytes(), .{});

API

Types

DenseMetadataThe geometry and metric a checkpoint froze - everything a reader learns without opening it, and nothing a reader must choose for itself.

pub const DenseMetadata = extern struct

Mirrors usearch_dense_metadata_t.

values_per_key is absent because it bounds a live handle's mutable state rather than anything the serialized form carries, and the placement is absent because a checkpoint records where it was written and never where a reader must keep it. Both stay the caller's to set when loading.

Fields

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

DenseLoadRamConfigOptional settings of DenseIndex.loadRam.

pub const DenseLoadRamConfig = struct

Fields

`executor`	`?Executor`	The executor the read fans out over; null reads on the calling thread.
`memory_domains`	`[]const i32`	The memory domains to place the parts on; empty derives every node the process may use.
`values_per_key`	`usize`	Upper bound on entries sharing one key, which no checkpoint records; zero is unbounded.
`progress`	`ProgressCallback`	Called with shards placed; a stopped load creates no index.
`progress_steps`	`usize`	Reports the call makes at most, the last at completion; zero derives to ten.
`diagnostics`	`?*Outcome`	Where the call's final outcome, its static message included, is copied; null copies nothing.

DenseLoadVramConfigOptional settings of DenseIndex.loadVram.

pub const DenseLoadVramConfig = struct

Fields

`executor`	`?Executor`	The executor the upload runs on; null runs on the calling thread and the default stream.
`devices`	`[]const i32`	The devices to place the parts on; empty derives one free device.
`values_per_key`	`usize`	Upper bound on entries sharing one key, which no checkpoint records; zero is unbounded.
`progress`	`ProgressCallback`	Called with shards placed; a stopped load creates no index.
`progress_steps`	`usize`	Reports the call makes at most, the last at completion; zero derives to ten.
`diagnostics`	`?*Outcome`	Where the call's final outcome, its static message included, is copied; null copies nothing.

DenseLoadRamBufferConfigOptional settings of DenseIndex.loadRamBuffer.

pub const DenseLoadRamBufferConfig = struct

Fields

`executor`	`?Executor`	The executor the copy fans out over; null copies on the calling thread.
`memory_domains`	`[]const i32`	The memory domains to place shards on; the monolith lands whole on the first.
`values_per_key`	`usize`	Upper bound on entries sharing one key, which no checkpoint records; zero is unbounded.
`progress`	`ProgressCallback`	Called with bytes placed; a stopped load creates no index.
`progress_steps`	`usize`	Reports the call makes at most, the last at completion; zero derives to ten.
`diagnostics`	`?*Outcome`	Where the call's final outcome, its static message included, is copied; null copies nothing.

DenseLoadVramBufferConfigOptional settings of DenseIndex.loadVramBuffer.

pub const DenseLoadVramBufferConfig = struct

Fields

`executor`	`?Executor`	The executor the upload runs on; null runs on the calling thread and the default stream.
`devices`	`[]const i32`	The devices to place shards on; the monolith lands whole on the first.
`values_per_key`	`usize`	Upper bound on entries sharing one key, which no checkpoint records; zero is unbounded.
`progress`	`ProgressCallback`	Called with bytes placed; a stopped load creates no index.
`progress_steps`	`usize`	Reports the call makes at most, the last at completion; zero derives to ten.
`diagnostics`	`?*Outcome`	Where the call's final outcome, its static message included, is copied; null copies nothing.

DenseViewNvmeConfigOptional settings of DenseIndex.viewNvme.

pub const DenseViewNvmeConfig = struct

Fields

`executor`	`?Executor`	The NVMe executor whose rings read the checkpoint's headers; null reads synchronously.
`paths`	`[]const BytesView`	The devices the parts are served from; empty serves each where its manifest points.
`diagnostics`	`?*Outcome`	Where the call's final outcome, its static message included, is copied; null copies nothing.

DenseMetadataReadConfigOptional settings of DenseIndex.metadataRead.

pub const DenseMetadataReadConfig = struct

Fields

`executor`	`?Executor`	The executor the read runs on; null reads on the calling thread.
`diagnostics`	`?*Outcome`	Where the call's final outcome, its static message included, is copied; null copies nothing.

DenseMetadataReadBufferConfigOptional settings of DenseIndex.metadataReadBuffer.

pub const DenseMetadataReadBufferConfig = struct

Fields

`executor`	`?Executor`	The executor the read runs on; null reads on the calling thread.
`diagnostics`	`?*Outcome`	Where the call's final outcome, its static message included, is copied; null copies nothing.

DenseSaveConfigOptional settings of DenseIndex.save.

pub const DenseSaveConfig = struct

Fields

`progress`	`ProgressCallback`	Called with shards written; a stopped save leaves leftovers every reader rejects.
`progress_steps`	`usize`	Reports the call makes at most, the last at completion; zero derives to ten.

DenseSaveBufferConfigOptional settings of DenseIndex.saveBuffer.

pub const DenseSaveBufferConfig = struct

Fields

`progress`	`ProgressCallback`	Called with bytes written; a stopped save leaves no bytes.
`progress_steps`	`usize`	Reports the call makes at most, the last at completion; zero derives to ten.

DenseSaveOne DenseIndex.save, as a Deferred holds it.

pub const DenseSave = struct

Fields

`path`	`[]const u8`
`config`	`DenseSaveConfig`
`outcome`	`Outcome`

DenseSaveBufferOne DenseIndex.saveBuffer, as a Deferred holds it.

pub const DenseSaveBuffer = struct

Fields

`config`	`DenseSaveBufferConfig`
`stamp`	`Arena.Stamp`	The call the borrowed arena serves, which every view over the outputs carries.
`monolith`	`BytesView`
`outcome`	`Outcome`

StructBytesViewA borrowed run of bytes and its length, never null-terminated by contract - the shape every string argument arrives in.1

types.zig:397 ↗

pub const BytesView = extern struct

Mirrors usearch_bytes_view_t.

Fields

`data`	`?[*]const u8`	Base pointer of the run; null names an absent argument.
`length`	`usize`	Bytes the run covers.

ofBorrows a slice as the view the C interface accepts - no terminator, no copy.

types.zig:404 ↗

pub fn of(bytes: []const u8) BytesView

StructMonolithThe monolith DenseIndex.saveBuffer serialized into an arena.2

dense.zig:2151 ↗

pub const Monolith = struct

It reads the arena, so every read is refused once that arena serves another call or is freed.

Fields

`stamp`	`Arena.Stamp`
`view`	`BytesView`

bytesThe serialized bytes, refusing a stale view with Error.Uninitialized and device memory with Error.Device.

dense.zig:2156 ↗

pub fn bytes(self: Monolith) Error![]const u8

residencyWhere the bytes live, which the host reads only as .ram or .nvme.

dense.zig:2162 ↗

pub fn residency(self: Monolith) Residency