# Serialization

> USearch for Swift

Checkpoints ride the SafeGraphs interchange format, and the path extension picks the layout: a `.safegraphs` monolith, or a `.safegraphs.json` manifest beside its shards.

```swift
try index.on(executor).save(path: "index.safegraphs")
let copied = try DenseIndex.loadRam("index.safegraphs", config: DenseLoadRamConfig(executor: executor))
let mapped = try DenseIndex.viewRam("index.safegraphs")

let described = try DenseIndex.metadataRead("index.safegraphs")
print(described.dimensions, described.metric, described.quantization)
```

`loadRam` and `loadVram` copy the checkpoint into a new mutable index; `viewRam` serves it in place through a memory mapping, and every mutating verb on a viewed index reports `readOnly`.
Saving demands a mutation-free window, while concurrent readers keep searching throughout.

An in-memory checkpoint is the same bytes reached another way.
`saveBuffer` returns them as a `Monolith` read in place from an `Arena`, since only the call knows how many there are, and `loadRamBuffer` and `metadataReadBuffer` read them back through a span.

```swift
let monolith = try index.on(executor).saveBuffer(arena: arena)
let restored = try monolith.withUnsafeBytes { bytes in
    try DenseIndex.loadRamBuffer(bytes.bytes, config: DenseLoadRamBufferConfig(executor: executor))
}
```

`import USearch`

## DenseMetadata

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

```swift
struct DenseMetadata
```

A checkpoint records neither the placement nor the bound on entries sharing one key: the first
says where it was written rather than where a reader must keep it, and the second bounds a live
handle's mutable state rather than the serialized form. Both stay the caller's to choose when
loading.

Conforms to: `Sendable`

## dimensions

The scalars per stored vector.

```swift
var dimensions: Int
```

## metric

The distance kind the checkpoint scores with.

```swift
var metric: DenseMetric
```

## quantization

The scalar type its vectors are stored and quantized into.

```swift
var quantization: Scalar
```

## connectivity

The connections-per-node bound the graph was built with.

```swift
var connectivity: Int
```

## DenseSaveConfig

The knobs of [`save`](https://www.unum.cloud/docs/usearch/swift/metrics.md#save).

```swift
struct DenseSaveConfig
```

## progress

Called with shards written.

```swift
var progress: Progress?
```

## progressSteps

Reports the call makes at most, the last at completion; zero derives to ten.

```swift
var progressSteps: Int
```

## init

```swift
init(progress: Progress? = nil, progressSteps: Int = 0)
```

## DenseSaveBufferConfig

The knobs of [`saveBuffer`](https://www.unum.cloud/docs/usearch/swift/metrics.md#saveBuffer).

```swift
struct DenseSaveBufferConfig
```

## progress

Called with bytes written.

```swift
var progress: Progress?
```

## progressSteps

Reports the call makes at most, the last at completion; zero derives to ten.

```swift
var progressSteps: Int
```

## init

```swift
init(progress: Progress? = nil, progressSteps: Int = 0)
```

## DenseLoadRamConfig

The knobs of [`loadRam`](https://www.unum.cloud/docs/usearch/swift/metrics.md#loadRam).

```swift
struct DenseLoadRamConfig
```

## executor

The executor the read fans out over, one shard per thread; nil reads on the calling thread.

```swift
var executor: Executor?
```

## memoryDomains

The memory domains to place the parts on, part `p` loading into shard `p` modulo their count; empty derives every node the process may allocate on.

```swift
var memoryDomains: [Int32]
```

## cpuClass

The class to dispatch as; nil derives the CPU's own.

```swift
var cpuClass: CPUClass?
```

## valuesPerKey

The bound on entries sharing one key, which no checkpoint records; zero is unbounded.

```swift
var valuesPerKey: Int
```

## progress

Called with shards placed.

```swift
var progress: Progress?
```

## progressSteps

Reports the call makes at most, the last at completion; zero derives to ten.

```swift
var progressSteps: Int
```

## init

```swift
init(executor: Executor? = nil, memoryDomains: [Int32] = [], cpuClass: CPUClass? = nil, valuesPerKey: Int = 0, progress: Progress? = nil, progressSteps: Int = 0)
```

## DenseLoadVramConfig

The knobs of [`loadVram`](https://www.unum.cloud/docs/usearch/swift/metrics.md#loadVram).

```swift
struct DenseLoadVramConfig
```

## executor

The executor the upload runs on, one stream per device; nil uploads from the calling thread.

```swift
var executor: Executor?
```

## devices

The devices to place the parts on, part `p` loading onto device `p` modulo their count; empty derives one free device.

```swift
var devices: [Int32]
```

## gpuClass

The class to dispatch as; nil derives the devices' own.

```swift
var gpuClass: GPUClass?
```

## valuesPerKey

The bound on entries sharing one key, which no checkpoint records; zero is unbounded.

```swift
var valuesPerKey: Int
```

## progress

Called with shards placed.

```swift
var progress: Progress?
```

## progressSteps

Reports the call makes at most, the last at completion; zero derives to ten.

```swift
var progressSteps: Int
```

## init

```swift
init(executor: Executor? = nil, devices: [Int32] = [], gpuClass: GPUClass? = nil, valuesPerKey: Int = 0, progress: Progress? = nil, progressSteps: Int = 0)
```

## DenseLoadRamBufferConfig

The knobs of [`loadRamBuffer`](https://www.unum.cloud/docs/usearch/swift/metrics.md#loadRamBuffer).

```swift
struct DenseLoadRamBufferConfig
```

## executor

The executor the copy fans out over; nil copies on the calling thread.

```swift
var executor: Executor?
```

## memoryDomains

The memory domains to place shards on; the monolith lands whole on the first.

```swift
var memoryDomains: [Int32]
```

## cpuClass

The class to dispatch as; nil derives the CPU's own.

```swift
var cpuClass: CPUClass?
```

## valuesPerKey

The bound on entries sharing one key, which no checkpoint records; zero is unbounded.

```swift
var valuesPerKey: Int
```

## progress

Called with bytes placed.

```swift
var progress: Progress?
```

## progressSteps

Reports the call makes at most, the last at completion; zero derives to ten.

```swift
var progressSteps: Int
```

## init

```swift
init(executor: Executor? = nil, memoryDomains: [Int32] = [], cpuClass: CPUClass? = nil, valuesPerKey: Int = 0, progress: Progress? = nil, progressSteps: Int = 0)
```

## DenseLoadVramBufferConfig

The knobs of [`loadVramBuffer`](https://www.unum.cloud/docs/usearch/swift/metrics.md#loadVramBuffer).

```swift
struct DenseLoadVramBufferConfig
```

## executor

The executor the upload runs on, one stream per device; nil uploads from the calling thread.

```swift
var executor: Executor?
```

## devices

The devices to place shards on; the monolith lands whole on the first.

```swift
var devices: [Int32]
```

## gpuClass

The class to dispatch as; nil derives the devices' own.

```swift
var gpuClass: GPUClass?
```

## valuesPerKey

The bound on entries sharing one key, which no checkpoint records; zero is unbounded.

```swift
var valuesPerKey: Int
```

## progress

Called with bytes placed.

```swift
var progress: Progress?
```

## progressSteps

Reports the call makes at most, the last at completion; zero derives to ten.

```swift
var progressSteps: Int
```

## init

```swift
init(executor: Executor? = nil, devices: [Int32] = [], gpuClass: GPUClass? = nil, valuesPerKey: Int = 0, progress: Progress? = nil, progressSteps: Int = 0)
```

## DenseViewNvmeConfig

The knobs of [`viewNvme`](https://www.unum.cloud/docs/usearch/swift/metrics.md#viewNvme).

```swift
struct DenseViewNvmeConfig
```

## executor

The NVMe executor whose rings read the checkpoint's headers; nil reads on the calling thread.

```swift
var executor: Executor?
```

## paths

The devices the parts are served from - a filesystem path, a transport identifier, or a FUSE mount over object storage; empty serves each part where its manifest points.

```swift
var paths: [String]
```

## cpuClass

The class to dispatch as; nil derives the CPU's own.

```swift
var cpuClass: CPUClass?
```

## init

```swift
init(executor: Executor? = nil, paths: [String] = [], cpuClass: CPUClass? = nil)
```

## Monolith

The monolith [`saveBuffer`](https://www.unum.cloud/docs/usearch/swift/metrics.md#saveBuffer) wrote into an arena, read in place.

```swift
struct Monolith
```

## count

The bytes in the monolith.

```swift
var count: Int { get }
```

## withUnsafeBytes

Lends the serialized checkpoint to `body`, which must not keep the buffer past its return.

```swift
func withUnsafeBytes<Result, Failure>(
    _ body: (UnsafeRawBufferPointer) throws(Failure) -> Result
) throws(Failure) -> Result where Failure : Error
```