> ## Documentation Index
> Fetch the complete documentation index at: https://hexxladb.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Edges

> Directed relationships between cells

An **Edge** is a directed relationship between two cells. Edges model connections like "see also", "follow-up", "derived from", or any custom relationship type you define.

## Edge structure

```go theme={null}
type Edge struct {
    From         PackedCoord
    To           PackedCoord
    RelationType string
    Weight       float64
    Provenance   ProvenanceWire
}
```

**Key components:**

* **From / To** — Packed coordinates of the source and target cells
* **RelationType** — String describing the relationship (e.g., "see-also", "follow-up")
* **Weight** — Optional float for ranking or importance
* **Provenance** — Source information and confidence

## Edge vs Seam

**Edges** model general-purpose relationships:

* "See also" references
* Conversation flow (follow-up)
* Derivation chains
* Custom application-specific links

**Seams** model contradiction and evolution:

* Conflicts between facts
* Preference supersession
* Audit trails for changes

Edges and seams are **distinct storage families**. The `Cell.Edges` and seam lists in the API are read aggregates, not denormalized primary storage.

## Creating edges

Use the helper `LinkCells` for common cases:

```go theme={null}
db.Update(func(tx *hexxladb.Tx) error {
    from := hexxladb.Coord{Q: 3, R: 1}
    to := hexxladb.Coord{Q: 4, R: 2}
    return tx.LinkCells(ctx, from, to, "see-also", 1.0, record.ProvenanceWire{
        SourceID:   "session-2",
        Confidence: 0.9,
    })
})
```

For full control, use `PutEdge`:

```go theme={null}
fromPk, _ := lattice.Pack(hexxladb.Coord{Q: 3, R: 1})
toPk, _ := lattice.Pack(hexxladb.Coord{Q: 4, R: 2})

err := tx.PutEdge(ctx, record.EdgeRecord{
    From:         fromPk,
    To:           toPk,
    RelationType: "derived-from",
    Weight:       0.8,
    Provenance:   record.ProvenanceWire{SourceID: "doc-456"},
})
```

## Retrieving edges

Get a specific edge:

```go theme={null}
fromPk, _ := lattice.Pack(hexxladb.Coord{Q: 3, R: 1})
toPk, _ := lattice.Pack(hexxladb.Coord{Q: 4, R: 2})

edge, ok, err := tx.GetEdge(ctx, fromPk, toPk, "see-also")
if err != nil {
    return err
}
if !ok {
    return errors.New("edge not found")
}
```

Iterate all outbound edges from a cell:

```go theme={null}
fromPk, _ := lattice.Pack(hexxladb.Coord{Q: 3, R: 1})

err := tx.AscendEdgesFrom(ctx, fromPk, func(edge record.EdgeRecord) bool {
    // Process edge
    fmt.Printf("Relation: %s, Weight: %f\n", edge.RelationType, edge.Weight)
    return true // continue iteration
})
```

## Common relation types

While you can define any relation type string, common patterns include:

| Relation type  | Use case                                 |
| -------------- | ---------------------------------------- |
| `see-also`     | Related content worth exploring          |
| `follow-up`    | Next item in a sequence or conversation  |
| `derived-from` | Source material or parent document       |
| `depends-on`   | Prerequisite relationship                |
| `related-to`   | General association                      |
| `refutes`      | Contradictory claim (use seams for this) |
| `supports`     | Evidentiary backing                      |

## Edge weights

Weights are optional floats that can represent:

* Relevance or importance
* Strength of relationship
* Ranking score for traversal

Use weights in your application logic to prioritize which edges to follow during graph traversal or context assembly.

## Deleting edges

To remove an edge, delete it directly:

```go theme={null}
fromPk, _ := lattice.Pack(hexxladb.Coord{Q: 3, R: 1})
toPk, _ := lattice.Pack(hexxladb.Coord{Q: 4, R: 2}

// Delete specific edge by relation type
// (Note: HexxlaDB doesn't have a dedicated DeleteEdge — use DeleteCell cascade or implement at application level)
```

When a cell is deleted via `DeleteCell`, all outbound edges are automatically removed.

## See also

* [Cells](/concepts/cells) — Core data units
* [Seams](/concepts/seams) — Contradiction and supersession markers
* [Coordinates](/concepts/coordinates) — Hexagonal addressing system