Skip to main content

NativeGraph

Struct NativeGraph 

Source
pub struct NativeGraph { /* private fields */ }
Expand description

The graph engine: an in-memory GraphEngine, optionally durable through a write-ahead log (open_durable). See the module docs for the guarantees.

Implementations§

Source§

impl NativeGraph

Source

pub fn new() -> Self

Create an empty in-memory engine. Ids start at 1.

Source

pub fn origin_id(&self) -> OriginId

This replica’s stable OriginId. Persisted next to the WAL for a durable store, ephemeral for an in-memory one.

Source

pub fn next_stamp(&self) -> Stamp

Issue the next causal Stamp (hlc, origin): advance the Hybrid Logical Clock and pair it with this replica’s origin. Strictly increasing — a sequence of local writes is totally ordered.

Source

pub fn stamp_of(&self, target: StampTarget) -> Option<Stamp>

The causal Stamp of target’s last autocommit write, or None if it is absent (never written, or deleted). Stamps live in memory only, so this starts empty after a restart.

Source

pub fn version_vector(&self) -> VersionVector

This replica’s VersionVector — the greatest causal Stamp seen per origin across every live entity . A peer hands this to delta_since to learn the minimal set of writes it is missing.

Built from the in-memory stamp table, so (like the table itself) it reflects only writes seen since the process started.

Source

pub fn delta_since(&self, remote: &VersionVector) -> Delta

The minimal Delta a holder of remote is missing: every live upsert and every tombstone whose stamp remote has not already observed . An empty remote (VersionVector::new) returns the entire state — a full bootstrap.

Deletes are carried as StampedChange::DeleteNode / StampedChange::DeleteEdge tombstones, so a delta converges removals as well as upserts (see the module docs). The returned records are deep clones, safe to serialise and send.

Source

pub fn apply_delta(&self, delta: &Delta) -> Result<ApplyStats>

Fold a received Delta into this replica by Last-Writer-Wins on the stamp, remapping the sender’s ids into our own id space by uuid . Each change is installed only if its stamp beats the local one for the same uuid, and the local HLC is advanced past every stamp seen. Idempotent — re-applying a delta changes nothing.

Because node/edge ids are per-replica, identity is the uuid each record carries: a uuid we already hold is merged at our local id, a new uuid is minted a fresh one, and an edge’s endpoints are resolved from their carried uuids (StampedEdge). This makes the exchange symmetric — independent concurrent writers converge — not just a fresh-replica bootstrap.

Changes apply in phase order (upsert nodes, upsert edges, delete edges, delete nodes) so endpoints exist before an edge references them and a cascading node delete runs last. Each winning change is persisted to the WAL (durable stores only; in-memory graphs skip the durable step), so a merge survives a restart. See the module docs for the remaining limitations.

Source

pub fn get_node_arc(&self, id: u64) -> Option<Arc<Node>>

Zero-copy node fetch: returns an Arc<Node> handle (a refcount bump) rather than deep-cloning the record the way GraphEngine::get_node must to honour its owned-return contract. Prefer this on read-hot paths where the caller only needs to read the node — a node with a large body/property map costs the same here as a tiny one.

Source

pub fn get_edge_arc(&self, id: u64) -> Option<Arc<Edge>>

Zero-copy edge fetch — the get_node_arc analogue for edges.

Source

pub fn node_id_of_uuid(&self, uuid: [u8; 16]) -> Option<u64>

The local id of the node with this globally-unique uuid, or None. A linear scan today (the uuid → id map is built per merge in apply_delta, not kept persistently); use it to address an entity across replicas by its stable uuid.

Source

pub fn edge_id_of_uuid(&self, uuid: [u8; 16]) -> Option<u64>

The local id of the edge with this globally-unique uuid, or None — the edge counterpart to node_id_of_uuid.

Source

pub fn get_node_by_uuid(&self, uuid: [u8; 16]) -> Option<Node>

Fetch a node by its globally-unique uuid.

Source

pub fn get_node_by_title(&self, title: &str) -> Option<Node>

Fetch a node by its unique title via the title index.

Source

pub fn list_recent(&self, limit: usize) -> Vec<Node>

Most-recently-updated nodes first, capped at limit (updated_at desc, then id desc).

Source

pub fn list_edges_by_kind( &self, kind: &str, limit: usize, offset: usize, ) -> Vec<Edge>

Edges of kind, id-ascending, paginated by limit/offset.

Source

pub fn set_embedding(&self, node_id: u64, vector: Vec<f32>) -> Result<()>

Store (or replace) node_id’s embedding, durably. Errors with CoreError::NodeNotFound if the node does not exist.

§Errors

CoreError::NodeNotFound if node_id is absent; propagates a WAL append/fsync failure.

Source

pub fn set_embeddings_batch(&self, embeddings: &[(u64, Vec<f32>)]) -> Result<()>

Store many embeddings in one durable batch (one fsync). Validates every node exists before applying any, so it is all-or-nothing.

§Errors

CoreError::NodeNotFound for the first absent node (nothing is written); propagates a WAL append/fsync failure.

Source

pub fn get_embedding(&self, node_id: u64) -> Option<Vec<f32>>

Fetch node_id’s embedding, or None.

Source

pub fn delete_embedding(&self, node_id: u64) -> Result<()>

Delete node_id’s embedding, durably. Idempotent (a missing embedding is not an error).

§Errors

Propagates a WAL append/fsync failure.

Source

pub fn embedding_count(&self) -> usize

The number of stored embeddings.

Source

pub fn all_embeddings(&self) -> Vec<(u64, Vec<f32>)>

Snapshot of all (node_id, embedding) pairs, id-ascending — e.g. to build a vector index. The order is deterministic.

Source

pub fn create_nodes(&self, new_nodes: Vec<NewNode>) -> Result<Vec<Node>>

Create many nodes in one durable batch.

§Errors

CoreError::DuplicateTitle if any title collides (within the batch or against an existing node) — the whole batch fails and nothing is written; propagates a WAL append/fsync failure.

Source

pub fn create_edges(&self, new_edges: Vec<NewEdge>) -> Result<Vec<Edge>>

Create many edges in one durable batch. Every edge’s endpoints must already exist.

§Errors

CoreError::NodeNotFound if an endpoint is missing (the whole batch fails, nothing written); propagates a WAL append/fsync failure.

Source

pub fn neighbors_arc( &self, node_id: u64, direction: Direction, kind: Option<&str>, ) -> Vec<Arc<Node>>

Distinct neighbours as zero-copy Arc<Node> handles — the fan-out counterpart to get_node_arc, so expanding a high-degree node never deep-clones every neighbour’s record.

Source

pub fn change_head(&self) -> u64

The current change-feed head — the sequence number of the most recent committed change. A caught-up subscriber holds this as its cursor; changes_since(change_head()) returns an empty batch.

Source

pub fn changes_since(&self, cursor: u64) -> ChangeBatch

Read every committed change after cursor, in commit order (the change feed). The returned ChangeBatch carries the resume cursor and, if the cursor had fallen behind the retained history, a lagged flag telling the subscriber to re-snapshot first.

Subscribers follow snapshot-then-tail: seed the index from a snapshot, remember change_head at that instant, then poll changes_since(cursor) and advance the cursor by each batch — so an FTS or vector index stays current without touching the write path.

Source

pub fn trim_before(&self, cursor: u64) -> u64

Drop change-feed history at or before cursor, bounding the feed’s memory.

The caller passes the minimum cursor across its live subscribers, so no subscriber that is still catching up loses a change it has not seen. After trimming, a subscriber whose cursor is below the new floor gets lagged = true from changes_since and must re-snapshot. cursor is clamped to the current head (the feed never trims a change that has not been produced). Returns the new retained floor — the sequence number before the oldest retained change.

Source

pub fn change_floor(&self) -> u64

The oldest sequence number still retained on the change-feed — the floor below which changes_since reports lagged. 0 until trim_before advances it.

Source

pub fn wal_fsync_count(&self) -> u64

Total fsyncs the durable WAL has performed since open — the group-commit coalescing metric: a batch of N writes flushed together counts as one, so under concurrency this stays far below the write count. 0 for an in-memory engine.

Source

pub fn snapshot(&self) -> GraphSnapshot

Take a consistent, read-only GraphSnapshot of the current state.

O(1): it is an Arc::clone of the live state. The returned view is frozen — subsequent writes to this engine copy-on-write and leave the snapshot untouched — giving snapshot isolation for reads.

Source

pub fn begin(&self) -> NativeTx<'_>

Begin a NativeTx — a transaction that reads a consistent snapshot of the graph as of now, buffers its writes privately, and applies them all atomically on commit.

Isolation is snapshot: the transaction never sees another writer’s changes made after it began. Concurrency control is optimistic — the commit succeeds only if the graph has not changed since the transaction began, otherwise it returns CommitError::Conflict and the caller retries. Dropping the transaction without committing rolls it back.

Source

pub fn tx_begin(&self) -> NativeTxId

Begin a registered transaction — the executor-facing form of Self::begin for callers (a Bolt session) that keep only an id between statements: run each statement on Self::tx_engine(id), then Self::tx_commit / Self::tx_rollback. Same semantics as NativeTx: buffered writes, read-your-writes, snapshot isolation, first-committer-wins conflict detection, one fsynced WAL batch at commit.

Source

pub fn tx_engine(&self, id: NativeTxId) -> Option<NativeTxEngine<'_>>

The per-statement GraphEngine view of a registered transaction, or None once it has been committed / rolled back.

Source

pub fn tx_commit(&self, id: NativeTxId) -> Result<(), CommitError>

Commit a registered transaction: apply its buffered writes atomically (one fsynced WAL batch) if the graph has not changed since Self::tx_begin and the result satisfies every declared constraint. The slot is always closed — a failed commit discards the buffered writes, exactly like NativeTx::commit.

§Errors
Source

pub fn tx_rollback(&self, id: NativeTxId) -> bool

Discard a registered transaction’s buffered writes. Returns whether the slot was still open (a second call is a false no-op).

Source

pub fn tx_prepare(&self, id: NativeTxId, gid: &str) -> Result<(), PrepareError>

Two-phase commit, phase one: validate registered transaction id exactly as a commit would (no change since begin, constraints hold), durably log its write set as prepared under gid, and raise the write fence. The transaction is closed either way; on success it can only be finished by commit_prepared or rollback_prepared, from any handle and across restarts. While the fence is up every other write fails fast (CoreError::PreparedTransactionPending / CommitError::PreparedPending); reads are unaffected.

§Errors

PrepareError; nothing is prepared and no fence is raised.

Source

pub fn commit_prepared(&self, gid: &str) -> Result<(), ResolveError>

Two-phase commit, phase two: apply the write set prepared under gid and lower the fence once nothing else is prepared. Cannot conflict: the fence kept the graph unchanged since the prepare.

§Errors

ResolveError::UnknownGid if nothing is prepared under gid; ResolveError::Io if the commit record could not be written (the transaction stays prepared — retry).

Source

pub fn rollback_prepared(&self, gid: &str) -> Result<(), ResolveError>

Two-phase commit: discard the write set prepared under gid and lower the fence once nothing else is prepared.

§Errors

ResolveError::UnknownGid or ResolveError::Io, as for commit_prepared.

Source

pub fn heuristic_rollback_prepared(&self, gid: &str) -> Result<(), ResolveError>

Two-phase commit: roll back the transaction prepared under gid heuristically — a server decision after the opt-in prepared-transaction timeout, not the coordinator’s. The outcome is logged and remembered, so a later commit_prepared returns ResolveError::HeuristicRollback instead of pretending the transaction never existed (the XA heuristic-outcome model).

§Errors

As for rollback_prepared.

Source

pub fn list_prepared(&self) -> Vec<PreparedInfo>

Every prepared, unresolved transaction, by ascending gid — for a coordinator resolving in-doubt transactions, and for operators.

Source

pub fn add_constraint( &self, constraint: Constraint, ) -> Result<(), ConstraintViolation>

Declare a schema Constraint the engine enforces at transaction commit.

The constraint is validated against the current data first: if existing nodes already violate it, it is not stored and the ConstraintViolation is returned (matching Neo4j, which refuses to create a constraint the data does not already satisfy).

§Errors

ConstraintViolation if the current graph already violates the constraint.

Source

pub fn dump_wal(&self) -> Vec<WalOp>

Dump the current state as a write-ahead-log op sequence: every node then every edge as an Upsert, in ascending id order. This is the “snapshot” form of the log — replaying it into a fresh engine via replay reproduces the graph exactly, which is what lets a periodic snapshot compact/truncate the incremental WAL. Constraints are schema, not data, and are not part of the dump.

Source

pub fn apply_wal_ops(&self, ops: &[WalOp]) -> Result<()>

Apply a batch of committed WalOps to this engine verbatim — ids/uuids/timestamps preserved, in order — and thread them through this engine’s own durability and change-feed (the read-replica apply path). Unlike apply_delta, which remaps ids for a peer-to-peer CRDT merge, this is faithful single-master replication: a follower applies its leader’s log and becomes an exact mirror. Each op extends the change-feed (so the follower’s own indexes can tail it) and, for a durable follower, is logged to its WAL.

Source

pub fn replay(ops: impl IntoIterator<Item = WalOp>) -> Self

Rebuild an engine by replaying a WalOp sequence in order — the recovery path: load a snapshot then replay the WAL tail, or replay a full WAL from empty. Ids/uuids/timestamps come from the logged records; the id counters advance past every replayed id so a post-recovery create never collides with a recovered node/edge.

Source

pub fn open_durable(path: impl AsRef<Path>) -> Result<Self>

Open a durable engine backed by a write-ahead log at path. If the file exists its records are replayed to reconstruct the graph; then the file is opened for append and every subsequent direct write is logged and fsynced before it returns, so a write that has returned survives a crash. Reopening the same path recovers the graph.

Both direct writes and transactions (begin) are durable, and a committed transaction is logged as one record (a JSON array of its ops), so it recovers all-or-nothing: a crash that tears the batch mid-write loses the whole transaction — which was never acknowledged — never half of it.

§Crash recovery

An acknowledged write returns only after fsync, so a crash can only tear the unacknowledged tail of the log. Recovery therefore truncates a torn final record (invalid bytes with nothing after them) and opens successfully — losing only what was never acknowledged — while an invalid record that is followed by valid data is genuine corruption of acknowledged history and refuses to open rather than silently dropping writes.

§Errors

CoreError::Io on a filesystem failure or on corruption before the tail; CoreError::Json on an encode failure.

Source

pub fn compact_wal(&self) -> Result<CompactWalStats>

Compact the write-ahead log: rewrite it as the current state’s snapshot form (every node/edge as one Upsert), discarding the superseded incremental history that has accumulated from overwrites and deletes . Bounds the log’s growth without changing the recovered graph.

Atomic and crash-safe: the snapshot is written to a temp file and fsynced, then renamed over the live log (an atomic replace on the same filesystem), then the append handle is reopened on the new file. A crash at any point leaves either the old or the new complete log — never a torn one. Writes are quiesced for the duration (the inner write lock is held). A no-op for an in-memory-only engine.

Returns the on-disk CompactWalStats (bytes before/after) so a caller — e.g. the storage-panel shrink endpoint — can report reclaimed bytes; an in-memory engine reports all-None.

§Errors

CoreError::Io / CoreError::Json on a filesystem or encode failure.

Source

pub fn wal_bytes(&self) -> Option<u64>

Physical on-disk size of the write-ahead log in bytes, or None for an in-memory engine (nothing on disk). The storage panel’s “file bytes”.

Source

pub fn wal_compacted_bytes(&self) -> u64

The byte size a freshly-compacted WAL would occupy — the serialized current state, one upsert per live node/edge (newline-terminated). The irreducible logical footprint; wal_bytes / this is the reclaimable-bloat ratio the append-only log accumulates from superseded upserts, tombstones and old versions.

Source

pub fn keyspace_stats(&self) -> Vec<(&'static str, u64, u64)>

Per-structure breakdown of the live index stack for the storage panel’s “Keyspaces” table. The durable WAL holds only records on disk (indexes are rebuilt on load), so this reports the in-memory structures: node/edge records plus the adjacency (out/in), title and kind indexes. Each tuple is (label, rows, content_bytes), where content_bytes is the structural in-memory footprint, not an on-disk size. Full-text and vector indexes live outside the engine and are not reported here.

Source

pub fn node_count(&self) -> u64

Number of node records currently stored.

Source

pub fn edge_count(&self) -> u64

Number of edge records currently stored.

Source

pub fn next_node_id(&self) -> u64

The next node id the allocator will hand out (monotonic; never reused).

Source

pub fn next_edge_id(&self) -> u64

The next edge id the allocator will hand out (monotonic; never reused).

Trait Implementations§

Source§

impl Default for NativeGraph

Source§

fn default() -> Self

Returns the “default value” for a type. Read more
Source§

impl GraphEngine for NativeGraph

Source§

fn create_node(&self, new_node: NewNode) -> Result<Node>

Create a node, allocating its id/uuid/timestamps. Read more
Source§

fn get_node(&self, id: u64) -> Result<Option<Arc<Node>>>

Fetch a node by id, or Ok(None) if absent. Read more
Source§

fn update_node(&self, id: u64, patch: NodePatch) -> Result<Node>

Apply a partial update to a node. Read more
Source§

fn delete_node(&self, id: u64) -> Result<()>

Delete a node (and its incident edges/indexes). Read more
Source§

fn delete_nodes(&self, ids: &[u64]) -> Result<usize>

Delete many nodes in one batch, returning how many were actually removed. Each node is dropped with its incident edges and index entries exactly as delete_node; ids that are already absent are skipped rather than erroring. Read more
Source§

fn create_edge(&self, new_edge: NewEdge) -> Result<Edge>

Create an edge between two existing nodes. Read more
Source§

fn get_edge(&self, id: u64) -> Result<Option<Edge>>

Fetch an edge by id, or Ok(None) if absent. Read more
Source§

fn update_edge(&self, id: u64, patch: EdgePatch) -> Result<Edge>

Apply a partial update to an edge (kind / weight / properties). Read more
Source§

fn delete_edge(&self, id: u64) -> Result<()>

Delete an edge (and its adjacency/index entries). Read more
Source§

fn neighbor_ids( &self, node_id: u64, direction: Direction, kind: Option<&str>, ) -> Result<Vec<u64>>

Return the distinct node ids adjacent to node_id in direction, optionally restricted to edges of kind — the id-only fan-out that reads straight from the adjacency index. Read more
Source§

fn neighbors( &self, node_id: u64, direction: Direction, kind: Option<&str>, ) -> Result<Vec<Arc<Node>>>

Return the adjacent nodes (loaded once each) in direction, optionally restricted to edges of kind. Read more
Source§

fn edges_of(&self, node_id: u64, direction: Direction) -> Result<Vec<Edge>>

Return the full Edge records incident to node_id in direction (the weighted/full-edge expansion, which loads each edge record — unlike neighbor_ids). Read more
Source§

fn all_nodes(&self) -> Result<Vec<Arc<Node>>>

Return every node in the store (a full scan — the label-less MATCH (n)). Read more
Source§

fn count_nodes(&self) -> Result<u64>

The number of nodes in the store — the MATCH (n) RETURN count(*) pushdown target: a bare count needs no record materialisation at all. Read more
Source§

fn count_nodes_by_kind(&self, kind: &str) -> Result<u64>

The number of nodes whose primary kind equals kind — the kind half of the labelled-count pushdown (secondary _labels matches are the label index’s business, not the engine’s). Read more
Source§

fn all_edges(&self) -> Result<Vec<Edge>>

Return every edge in the store (a full scan — the anonymous MATCH ()-[r]->()). Read more
Source§

fn nodes_by_kind( &self, kind: &str, limit: usize, offset: usize, ) -> Result<Vec<Arc<Node>>>

Return nodes of a given kind (label scan), paginated by limit / offset. Read more
Source§

fn export_dump(&self) -> Result<Dump>

Export the entire graph as a drevo-json-v1 Dump — every node and edge plus the id-allocation counters — the interchange format used for backup, JSON/GraphML round-trips, and cross-engine migration. Read more
Source§

fn apply_dump(&self, dump: Dump) -> Result<ImportReport>

Bulk-load a Dump into this engine verbatim, preserving every node/edge id (so edges stay connected) and clamping the id counters above every imported id. Nodes/edges already present byte-for-byte are skipped (idempotent re-import); an id that collides with different content, or an edge whose endpoint is missing, is an error. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.