A Graph Has a Home: Scopes, Cells, and Canonical Records

In HydraDB, a graph does not begin with a process or a cache; it begins with an addressable scope in durable storage. This chapter focuses on how a namespace, graph identity, and cell become the unit that HydraDB can read, mutate, index, and replace safely. Understanding that hierarchy lets a reader distinguish the records that define the graph from the structures that merely make those records faster to use.

That distinction matters because “the graph” is an overloaded phrase. It might mean the relationships an application created, the indexes used to find them, the local matrix used to traverse them, or the coordination data that helps a cluster decide who may write. HydraDB places all of these near one another in its storage model, but it gives them different authority. A process can lose its local matrix without losing a relationship. An index can lag without changing the answer that canonical records describe. The scope and cell structure make those differences concrete.

Scope is the first boundary

A HydraDB scope has three levels of meaning. A namespace path identifies the tenant context, possibly through bounded nested subnamespaces. A graph ID identifies one graph within that path. A cell identifies the independently stored portion selected by a request. Together, the namespace path and graph ID form a GraphScope; the cell is the storage target inside that scope.

For a reader, the useful analogy is not a directory tree but a chain of authority. The namespace says whose space is being addressed. The graph says which logical graph belongs there. The cell says which independent SlateDB database contains the records involved in this operation. A client request that names the wrong level is not merely incomplete: it can point at a different durable state or fail scope authorization altogether.

The physical layout follows this identity deterministically. HydraDB derives a storage path from the base location, the namespace path, and the graph ID, then stores each cell beneath that graph scope. Determinism is important for two reasons. First, a process that is replaced can derive the same location again instead of depending on a private catalog held by the old process. Second, coordination objects and index material can be placed beside the cell they describe while retaining a stable relationship to the graph.

The cell is where the abstract scope becomes operational. Each cell is opened as an independent SlateDB database. This lets HydraDB make decisions at a useful granularity: a writer is admitted for a particular scope and cell, a query pins a snapshot for that cell, and an index generation describes adjacency for that cell and edge type. The design does not require one process to own an entire tenant's graph forever. It can manage cells as separate durable units while compute nodes retain only the local state they need at the moment.

A hypothetical tenant might have a namespace for an organization, a graph representing its relationship data, and several cells selected by the deployment's request model. The important point is not the naming convention. It is that the same identity travels through storage, authorization, placement, leases, snapshots, and indexes. The cell is not just a shard label added for routing; it is the boundary at which those mechanisms meet.

The diagram separates location from content. A scope contains cells; a cell owns the durable graph records and can publish an immutable traversal generation. The generation is associated with the cell, but its relationship is “accelerates,” not “defines.” That difference will control how HydraDB handles index lag and cache loss.

A cell holds more than edges

A graph is often introduced as vertices joined by edges. That description is useful for intuition but incomplete for a durable database. HydraDB's canonical state must answer several related questions at once: which vertices exist, what labels and properties they carry, which relationships connect which endpoints, what type and direction each relationship has, and which metadata belongs to the relationship itself.

The storage model therefore keeps more than one representation of a connection. Outbound and inbound topology records make different traversal directions possible. High-degree adjacency can be represented in segments rather than as a single unbounded record. Tombstones record deletion state for segmented topology. Property indexes help locate vertices or relationships by values. Degree and count records summarize structural facts. Idempotency and import-fingerprint records let a retry or bulk operation be interpreted against durable history instead of only against the lifetime of one client session.

These structures should not be read as an arbitrary collection of implementation artifacts. Each exists because a different question has a different access shape. An outgoing-neighbor question needs a source-to-destination view. An incoming-neighbor question needs the reverse direction. A property selector needs a way to find candidate records without scanning every vertex. A deleted segment needs a durable marker so an older physical representation is not mistaken for a live edge. A relationship query needs identity and metadata even when traversal only needs to know that one endpoint can reach another.

That is why a structural edge and a relationship record are related but not identical. The topology layer can represent the fact that a source and destination are connected for a given type. The relationship layer can preserve a relationship identity and its properties, including the case where more than one relationship shares the same endpoints and type. HydraDB's native path behavior depends on this distinction: it can use compact structural adjacency to discover candidate paths, then return concrete relationship evidence from canonical records.

A mutation may touch several of these records together. Creating a relationship can update endpoint metadata, topology in the outbound direction, reverse topology when configured, degree counters, relationship identity records, relationship-property indexes, a topology changelog, and durable idempotency state. The exact set is operation-dependent, but the architectural requirement is stable: records that must describe one committed mutation cannot be treated as unrelated local cache entries. SlateDB's transaction and durability boundary is what ties them to one committed storage sequence.

Canonical truth, acceleration, and coordination

The easiest way to lose the storage model is to classify state by physical location alone. An immutable traversal generation lives in object storage, but that does not make it canonical graph truth. A local cache lives on an SSD, but its disposability does not make it irrelevant to performance. A lease or scope marker is durable, but it has a coordination or discovery role rather than the authority to redefine a relationship.

A more reliable classification is by the question each record is allowed to answer:

The first row is the authority boundary. The second row is a performance boundary. The third is a control-plane boundary. The fourth is a disposable execution boundary. Their proximity in an object-store prefix does not erase those roles.

Scope markers illustrate the difference between discovery and truth. HydraDB can place immutable markers that allow indexers to discover graph scopes without a writable catalog service in the graph data path. The marker says that a scope is registered and discoverable; it is not a replacement for the cell's canonical records. If an indexer finds a scope marker but no usable traversal generation, the correct response is to inspect durable graph state or leave the index absent—not to invent graph content from the marker.

The same reasoning applies to property and degree indexes. They may be essential for an efficient plan, but their purpose is to accelerate a lookup or summarize a fact already grounded in canonical records. When a query uses them, HydraDB still has to respect the pinned storage view. When a rebuilt index is absent, the query path can fall back to a canonical scan or adjacency operation within its configured bounds. A materialized structure is valuable because it can be recreated from truth, not because it has become a second truth.

Why object storage does not mean one object per vertex

“Object-store-native” can suggest a naive design in which every vertex and relationship is an independent object. That would make a graph operation depend on a large number of object requests and would move database concerns such as transactions, snapshots, compaction, and write ordering into application code. HydraDB takes a different route. Graph records are SlateDB keys, and SlateDB organizes durable changes through write-ahead logs, manifests, sorted-string tables, compaction, and snapshots on the object store.

This arrangement preserves the operational property HydraDB wants—durable state outside the compute process—without discarding database structure. The object store supplies the shared durable medium. SlateDB supplies the storage engine behavior that makes a cell readable at a sequence and writable under a writer epoch. The graph layer defines how vertex, relationship, topology, metadata, tombstone, and index records fit into that engine.

The distinction also clarifies why a local cache can be rebuilt. A cache is not asked to reconstruct the graph from an informal collection of files. It reopens the same cell and lets the durable storage model provide the records and snapshots from which local blocks, adjacency, or compiled matrices can be hydrated. The cost of replacement is real—remote reads, replay, compilation, and warm-up—but the replacement process has a stable source to work from.

There is a trade-off here. Remote durable storage can increase cold latency and make index or reader refresh sensitive to object-store round trips. A process with a warm local cache may respond differently from a freshly replaced process. Those are performance differences, not proof that the graph has changed. The repository's design evidence supports this distinction, but it does not by itself provide a universal latency or availability guarantee across object-store providers.

Scope isolation as a replacement test

A useful test for the model is to imagine replacing one compute process while the graph is active. The new process must know which namespace and graph it is serving, derive the same scope and cell location, open a reader or writer according to the current authority rules, and rebuild only the local state it needs. It should not need the old process's private memory to learn what relationships were committed.

Cell isolation helps contain the work. A query node does not need to hydrate every graph in every namespace before serving a request. A scoped runtime can open the targeted cell, use its own cache, and close or reopen warm scopes under a configured limit. An indexer can retain read-only handles for recently used scopes while treating those handles as a bounded scheduling cache. Closing a handle releases compute state; it does not delete the graph.

The same boundary supports tenancy and coordination. A request's scope is a concrete object that can be authorized. A writer lease can be named for a specific scope and cell rather than for an entire cluster. An index generation can be checked against the cell and edge type it describes. These checks reduce the danger of using a valid record in the wrong graph simply because the record's shape looks familiar.

The storage model therefore does more than organize data. It carries the central promise from the opening discussion into a form that other mechanisms can use. Durable graph content has an address, a cell, and a SlateDB lifecycle. Derived structures can be placed beside it and rebuilt against it. Coordination records can guide compute without becoming content. Local state can disappear without taking committed relationships with it.

The remaining question is temporal rather than spatial. Once a query has found the right cell, which version of that cell should it see when a writer has advanced the durable sequence and an index still describes an older one? That is where HydraDB's snapshot boundary, causal and strong freshness choices, and safe overlay behavior become necessary.

References

• HydraDB repository