Struct ReadTransaction 

pub struct ReadTransaction { /* private fields */ }

Read transaction over a pinned snapshot.

A read transaction owns its own Arc<Snapshot> and never borrows the Database, so it stays valid across a later begin_write/checkpoint on the same handle (it cloned the snapshot before the write borrowed &mut). It is Send + Sync (asserted below).

Performance

Creating and cloning a read transaction is O(1): it shares the pinned snapshot through an Arc, not by copying.

Implementations

impl ReadTransaction

pub fn pin(&self) -> ReadPin

Returns this transaction’s reader pin.

Performance

This method is O(1).

pub fn catalog(&self) -> &Catalog

Returns catalog metadata.

Performance

This method is O(1).

pub fn element_count(&self) -> usize

Returns visible element count.

Performance

This method is O(base + overlay change).

pub fn relation_count(&self) -> usize

Returns visible relation count.

Performance

This method is O(base + overlay change).

pub fn incidence_count(&self) -> usize

Returns visible incidence count.

Performance

This method is O(base + overlay change).

pub fn element_ids(&self) -> Vec<ElementId>

Returns every visible element id in id order.

Performance

This method is O(element count).

pub fn relation_ids(&self) -> Vec<RelationId>

Returns every visible relation id in id order.

Performance

This method is O(relation count).

pub fn contains_element(&self, id: ElementId) -> bool

Returns whether an element exists.

Performance

This method is O(log change + log n).

pub fn contains_relation(&self, id: RelationId) -> bool

Returns whether a relation exists.

Performance

This method is O(log change + log n).

pub fn contains_incidence(&self, id: IncidenceId) -> bool

Returns whether an incidence exists.

Performance

This method is O(log change + log n).

pub fn element(&self, id: ElementId) -> Option<Cow<'_, ElementRecord>>

Returns an element record, borrowed from the base for a base-only id and owned for an overlay-supplied id.

Performance

This method is O(log change + log n).

pub fn relation(&self, id: RelationId) -> Option<Cow<'_, RelationRecord>>

Returns a relation record (see Self::element for the borrow contract).

Performance

This method is O(log change + log n).

pub fn incidence(&self, id: IncidenceId) -> Option<Cow<'_, IncidenceRecord>>

Returns an incidence record (see Self::element for the borrow contract).

Performance

This method is O(log change + log n).

pub fn element_incidences(&self, id: ElementId) -> Vec<IncidenceRecord>

Returns every visible incidence attached to an element, in ascending incidence-id order.

The merged set mixes overlay-owned and base-borrowed records, so this returns an owned Vec (IncidenceRecord is Copy, so the copy is cheap).

Performance

This method is O(base incidences + overlay incidence change).

pub fn property( &self, subject: PropertySubject, key: PropertyKeyId, ) -> Option<Cow<'_, PropertyValue>>

Returns one property value (see Self::element for the borrow contract).

Performance

This method is O(log subjects + log keys).

pub fn lookup_property_equal( &self, key: PropertyKeyId, value: &PropertyValue, ) -> Result<Vec<PropertySubject>, DbError>

Looks up subjects with a property value.

Errors

Returns DbError when the property key is unknown or value does not match the key schema.

Performance

This method is O(property subject count).

pub fn lookup_property_range( &self, key: PropertyKeyId, min: &PropertyValue, max: &PropertyValue, ) -> Result<Vec<PropertySubject>, DbError>

Looks up subjects with a property inside an inclusive range.

Errors

Returns DbError when the property key is unknown or either bound does not match the key schema.

Performance

This method is O(property subject count).

pub fn lookup_index( &self, index: IndexId, lookup: IndexLookup<'_>, ) -> Result<Vec<PropertySubject>, DbError>

Executes an index lookup.

Errors

Returns DbError when the index is unknown, the lookup shape does not match the index kind, or supplied property values do not match catalog schemas.

Performance

This method is O(indexed family size).

pub fn graph_projection( &self, id: ProjectionId, ) -> Result<GraphProjection, DbError>

Materializes a graph projection.

Errors

Returns DbError when the projection is unknown, is not a graph, or fails validation against current topology.

Performance

This method is O(relation count * incidence count).

pub fn graph_projection_by_name( &self, name: &str, ) -> Result<GraphProjection, DbError>

Materializes a graph projection by catalog name.

Errors

Returns DbError when the projection is unknown, is not a graph, or fails validation against current topology.

Performance

This method is O(log projection count + relation count * incidence count).

pub fn traverse_graph( &self, projection: ProjectionId, seeds: &[ElementId], options: TraversalOptions, ) -> Result<TraversalResult, DbError>

Traverses a cataloged graph projection from canonical seed elements.

Rows are unique canonical elements in BFS first-discovery order. Depth is the shortest discovered hop count from any seed.

Errors

Returns DbError when the projection is unknown, is not a graph, cannot be materialized, or a seed element is not part of the projection.

Performance

This method is O(relation count * incidence count + visited edges).

pub fn hypergraph_projection( &self, id: ProjectionId, ) -> Result<HypergraphProjection, DbError>

Materializes a hypergraph projection.

Errors

Returns DbError when the projection is unknown, is not a hypergraph, or fails validation against current topology.

Performance

This method is O(relation count * incidence count).

pub fn execute(&self, query: &PreparedQuery) -> Result<QueryResult, DbError>

Executes a prepared query.

Errors

Returns DbError when execution cannot materialize a referenced projection.

Performance

This method is O(plan output + projection build cost when used).

pub fn explain(&self, query: &PreparedQuery) -> String

Explains a prepared query.

Performance

This method is O(plan size).