# 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. ```zig 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. ```zig const monolith = try index.saveBuffer(&arena, .{}); var restored = try usearch.DenseIndex.loadRamBuffer(try monolith.bytes(), .{}); ``` `const usearch = @import("usearch");` `const BytesView = @import("usearch").BytesView;` `const Monolith = @import("usearch").Monolith;` ## DenseMetadata The geometry and metric a checkpoint froze - everything a reader learns without opening it, and nothing a reader must choose for itself. ```zig 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. - `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. ## DenseLoadRamConfig Optional settings of [`DenseIndex.loadRam`](https://www.unum.cloud/docs/usearch/zig/metrics.md#loadRam). ```zig pub const DenseLoadRamConfig = struct ``` - `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. ## DenseLoadVramConfig Optional settings of [`DenseIndex.loadVram`](https://www.unum.cloud/docs/usearch/zig/metrics.md#loadVram). ```zig pub const DenseLoadVramConfig = struct ``` - `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. ## DenseLoadRamBufferConfig Optional settings of [`DenseIndex.loadRamBuffer`](https://www.unum.cloud/docs/usearch/zig/metrics.md#loadRamBuffer). ```zig pub const DenseLoadRamBufferConfig = struct ``` - `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. ## DenseLoadVramBufferConfig Optional settings of [`DenseIndex.loadVramBuffer`](https://www.unum.cloud/docs/usearch/zig/metrics.md#loadVramBuffer). ```zig pub const DenseLoadVramBufferConfig = struct ``` - `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. ## DenseViewNvmeConfig Optional settings of [`DenseIndex.viewNvme`](https://www.unum.cloud/docs/usearch/zig/metrics.md#viewNvme). ```zig pub const DenseViewNvmeConfig = struct ``` - `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. ## DenseMetadataReadConfig Optional settings of [`DenseIndex.metadataRead`](https://www.unum.cloud/docs/usearch/zig/metrics.md#metadataRead). ```zig pub const DenseMetadataReadConfig = struct ``` - `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. ## DenseMetadataReadBufferConfig Optional settings of [`DenseIndex.metadataReadBuffer`](https://www.unum.cloud/docs/usearch/zig/metrics.md#metadataReadBuffer). ```zig pub const DenseMetadataReadBufferConfig = struct ``` - `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. ## DenseSaveConfig Optional settings of [`DenseIndex.save`](https://www.unum.cloud/docs/usearch/zig/metrics.md#save). ```zig pub const DenseSaveConfig = struct ``` - `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. ## DenseSaveBufferConfig Optional settings of [`DenseIndex.saveBuffer`](https://www.unum.cloud/docs/usearch/zig/metrics.md#saveBuffer). ```zig pub const DenseSaveBufferConfig = struct ``` - `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. ## DenseSave One [`DenseIndex.save`](https://www.unum.cloud/docs/usearch/zig/metrics.md#save), as a [`Deferred`](https://www.unum.cloud/docs/usearch/zig/executors.md#Deferred) holds it. ```zig pub const DenseSave = struct ``` - `path` `[]const u8` - `config` `DenseSaveConfig` - `outcome` `Outcome` ## DenseSaveBuffer One [`DenseIndex.saveBuffer`](https://www.unum.cloud/docs/usearch/zig/metrics.md#saveBuffer), as a [`Deferred`](https://www.unum.cloud/docs/usearch/zig/executors.md#Deferred) holds it. ```zig pub const DenseSaveBuffer = struct ``` - `config` `DenseSaveBufferConfig` - `stamp` `Arena.Stamp`: The call the borrowed arena serves, which every view over the outputs carries. - `monolith` `BytesView` - `outcome` `Outcome` ## BytesView A borrowed run of bytes and its length, never null-terminated by contract - the shape every string argument arrives in. ```zig pub const BytesView = extern struct ``` Mirrors `usearch_bytes_view_t`. - `data` `?[*]const u8`: Base pointer of the run; null names an absent argument. - `length` `usize`: Bytes the run covers. ## of Borrows a slice as the view the C interface accepts - no terminator, no copy. ```zig pub fn of(bytes: []const u8) BytesView ``` ## Monolith The monolith [`DenseIndex.saveBuffer`](https://www.unum.cloud/docs/usearch/zig/metrics.md#saveBuffer) serialized into an arena. ```zig pub const Monolith = struct ``` It reads the arena, so every read is refused once that arena serves another call or is freed. - `stamp` `Arena.Stamp` - `view` `BytesView` ## bytes The serialized bytes, refusing a stale view with [`Error.Uninitialized`](https://www.unum.cloud/docs/usearch/zig/errors.md#Uninitialized) and device memory with [`Error.Device`](https://www.unum.cloud/docs/usearch/zig/errors.md#Device). ```zig pub fn bytes(self: Monolith) Error![]const u8 ``` ## residency Where the bytes live, which the host reads only as `.ram` or `.nvme`. ```zig pub fn residency(self: Monolith) Residency ```