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

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:

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:

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:

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:

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:

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 — Core data units
• Seams — Contradiction and supersession markers
• Coordinates — Hexagonal addressing system