# Serialization

> USearch for Go

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.

```go
if err := index.On(executor).Save("index.safegraphs", nil); err != nil {
		log.Fatal(err)
}

restored, err := usearch.DenseLoadRam("index.safegraphs", &usearch.DenseLoadRamConfig{Executor: executor})
	if err != nil {
		log.Fatal(err)
}
defer restored.Close()

monolith, err := index.SaveBuffer(arena, nil) // sized by the call itself, see Arenas
serialized, err := monolith.Bytes()
copied, err := usearch.DenseLoadRamBuffer(serialized, nil)
```

Loading creates the index, freezing its geometry from the checkpoint's own headers.
`DenseMetadataRead` reads that geometry without opening a shard:

```go
metadata, err := usearch.DenseMetadataRead("index.safegraphs", nil) // a nil config reads on the calling goroutine
fmt.Println(metadata.Dimensions, metadata.Metric, metadata.Quantization)
```

The result carries only the four fields a checkpoint froze, so `ValuesPerKey` and the placement stay yours to set in the load config.
Serving a checkpoint in place, rather than copying it, yields a read-only handle whose mutating verbs fail with `StatusReadOnly`, through a memory mapping with `DenseViewRam`, or from drives with `DenseViewNvme`:

```go
mapped, err := usearch.DenseViewRam("index.safegraphs")
served, err := usearch.DenseViewNvme("index.safegraphs", &usearch.DenseViewNvmeConfig{
	Executor: drives,
	Paths:    []string{"/dev/nvme0n1"},
})
```

`import "github.com/unum-cloud/USearch/golang"`

## DenseLoadRamBufferConfig

DenseLoadRamBufferConfig carries the optional settings of DenseLoadRamBuffer.

```go
type DenseLoadRamBufferConfig struct {
    Executor *Executor
    MemoryDomains []int32
    CPUClass CPUClass
    ValuesPerKey uint
    Progress ProgressCallback
    ProgressSteps uint
}
```

- `Executor` `*Executor`: Executor is the one the copy fans out over; nil copies on the calling goroutine.
- `MemoryDomains` `[]int32`: MemoryDomains are the NUMA node IDs to place shards on, the monolith loading whole into the first; empty derives every node the process may use.
- `CPUClass` `CPUClass`: CPUClass is the class to dispatch as; the zero value derives the CPU's own.
- `ValuesPerKey` `uint`: ValuesPerKey bounds how many entries may share one key; zero is unbounded.
- `Progress` `ProgressCallback`: Progress reports the bytes placed and stops wherever it says to.
- `ProgressSteps` `uint`: ProgressSteps bounds the reports Progress hears, the last at completion; zero derives to ten.

## DenseLoadRamConfig

DenseLoadRamConfig carries the optional settings of DenseLoadRam.

```go
type DenseLoadRamConfig struct {
    Executor *Executor
    MemoryDomains []int32
    CPUClass CPUClass
    ValuesPerKey uint
    Progress ProgressCallback
    ProgressSteps uint
}
```

- `Executor` `*Executor`: Executor is the one the read fans out over; nil reads on the calling goroutine.
- `MemoryDomains` `[]int32`: MemoryDomains are the NUMA node IDs to place the parts on, part p loading whole into shard p modulo their count; empty derives every node the process may use.
- `CPUClass` `CPUClass`: CPUClass is the class to dispatch as; the zero value derives the CPU's own.
- `ValuesPerKey` `uint`: ValuesPerKey bounds how many entries may share one key, which no checkpoint records; zero is unbounded.
- `Progress` `ProgressCallback`: Progress reports the shards placed and stops wherever it says to; a stopped load creates no index.
- `ProgressSteps` `uint`: ProgressSteps bounds the reports Progress hears, the last at completion; zero derives to ten.

## DenseLoadVramBufferConfig

DenseLoadVramBufferConfig carries the optional settings of DenseLoadVramBuffer.

```go
type DenseLoadVramBufferConfig struct {
    Executor *Executor
    Devices []int32
    GPUClass GPUClass
    ValuesPerKey uint
    Progress ProgressCallback
    ProgressSteps uint
}
```

- `Executor` `*Executor`: Executor is the one the upload runs on; nil uploads on the default stream of each device.
- `Devices` `[]int32`: Devices are the CUDA ordinals to place shards on, the monolith loading whole onto the first; empty derives one free device.
- `GPUClass` `GPUClass`: GPUClass is the class to dispatch as; the zero value derives the devices' own.
- `ValuesPerKey` `uint`: ValuesPerKey bounds how many entries may share one key; zero is unbounded.
- `Progress` `ProgressCallback`: Progress reports the bytes placed and stops wherever it says to.
- `ProgressSteps` `uint`: ProgressSteps bounds the reports Progress hears, the last at completion; zero derives to ten.

## DenseLoadVramConfig

DenseLoadVramConfig carries the optional settings of DenseLoadVram.

```go
type DenseLoadVramConfig struct {
    Executor *Executor
    Devices []int32
    GPUClass GPUClass
    ValuesPerKey uint
    Progress ProgressCallback
    ProgressSteps uint
}
```

- `Executor` `*Executor`: Executor is the one the upload runs on; nil uploads on the default stream of each device.
- `Devices` `[]int32`: Devices are the CUDA ordinals to place the parts on, part p loading whole onto device p modulo their count; empty derives one free device.
- `GPUClass` `GPUClass`: GPUClass is the class to dispatch as; the zero value derives the devices' own.
- `ValuesPerKey` `uint`: ValuesPerKey bounds how many entries may share one key; zero is unbounded.
- `Progress` `ProgressCallback`: Progress reports the shards placed and stops wherever it says to.
- `ProgressSteps` `uint`: ProgressSteps bounds the reports Progress hears, the last at completion; zero derives to ten.

## DenseMetadataReadBufferConfig

DenseMetadataReadBufferConfig carries the optional settings of DenseMetadataReadBuffer.

```go
type DenseMetadataReadBufferConfig struct {
    Executor *Executor
}
```

- `Executor` `*Executor`: Executor is the one the read runs on; nil reads on the calling goroutine.

## DenseMetadataReadConfig

DenseMetadataReadConfig carries the optional settings of DenseMetadataRead.

```go
type DenseMetadataReadConfig struct {
    Executor *Executor
}
```

- `Executor` `*Executor`: Executor is the one the read runs on; nil reads on the calling goroutine.

## DenseSaveBufferConfig

DenseSaveBufferConfig carries the optional settings of SaveBuffer.

```go
type DenseSaveBufferConfig struct {
    Progress ProgressCallback
    ProgressSteps uint
}
```

- `Progress` `ProgressCallback`: Progress reports the bytes written and stops wherever it says to; a stopped save leaves no monolith.
- `ProgressSteps` `uint`: ProgressSteps bounds the reports Progress hears, the last at completion; zero derives to ten.

## DenseSaveConfig

DenseSaveConfig carries the optional settings of Save.

```go
type DenseSaveConfig struct {
    Progress ProgressCallback
    ProgressSteps uint
}
```

- `Progress` `ProgressCallback`: Progress reports the shards written and stops wherever it says to.
- `ProgressSteps` `uint`: ProgressSteps bounds the reports Progress hears, the last at completion; zero derives to ten.

## DenseViewNvmeConfig

DenseViewNvmeConfig carries the optional settings of DenseViewNvme.

```go
type DenseViewNvmeConfig struct {
    Executor *Executor
    Paths []string
    CPUClass CPUClass
}
```

- `Executor` `*Executor`: Executor is the NVMe executor whose rings read the checkpoint's headers; nil reads on the calling goroutine.
- `Paths` `[]string`: Paths are the devices or directories to serve the parts from; empty serves each where its manifest points.
- `CPUClass` `CPUClass`: CPUClass is the class to dispatch as; the zero value derives the CPU's own.

## DenseMetadata

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

```go
type DenseMetadata struct {
    Dimensions uint
    Metric DenseMetric
    Quantization Scalar
    Connectivity uint
}
```

ValuesPerKey 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, never where a reader must keep it. Both stay yours to set in the load config.

- `Dimensions` `uint`: Dimensions is the scalars per stored vector.
- `Metric` `DenseMetric`: Metric is the distance kind the checkpoint scores with.
- `Quantization` `Scalar`: Quantization is the scalar type its vectors are stored and quantized into.
- `Connectivity` `uint`: Connectivity is the connections per node the graph was built with.

## DenseMetadataRead

DenseMetadataRead reads a checkpoint's geometry and metric without loading it - from the manifest's summary when the path names one, so no shard is opened.

```go
func DenseMetadataRead(
    path string,
    config *DenseMetadataReadConfig,
) (DenseMetadata, error)
```

## DenseMetadataReadBuffer

DenseMetadataReadBuffer reads geometry and metric out of a serialized monolith buffer.

```go
func DenseMetadataReadBuffer(
    buffer []byte,
    config *DenseMetadataReadBufferConfig,
) (DenseMetadata, error)
```

## Monolith

Monolith is the serialized index SaveBuffer wrote into its arena.

```go
type Monolith struct {
    // contains filtered or unexported fields
}
```

## Bytes

Bytes borrows the monolith from its arena.

```go
func (monolith Monolith) Bytes() ([]byte, error)
```