Struct ReadTransaction 

pub struct ReadTransaction { /* private fields */ }

A read-only transaction

Read-only transactions may exist concurrently with writes

Implementations

impl ReadTransaction

pub fn open_table<K: Key + 'static, V: Value + 'static>( &self, definition: TableDefinition<'_, K, V>, ) -> Result<ReadOnlyTable<K, V>, TableError>

Open the given table

pub fn open_ttl_table<K: Key + 'static, V: Value + 'static>( &self, definition: TtlTableDefinition<K, V>, ) -> Result<ReadOnlyTtlTable<K, V>, TableError>

Open a TTL-enabled table for reading.

Returns an error if the table does not exist.

pub fn open_ivfpq_index( &self, definition: &IvfPqIndexDefinition, ) -> Result<ReadOnlyIvfPqIndex, TableError>

Open an IVF-PQ vector index for reading.

Returns an error if the index does not exist.

pub fn open_untyped_table( &self, handle: impl TableHandle, ) -> Result<ReadOnlyUntypedTable, TableError>

Open the given table without a type

pub fn open_multimap_table<K: Key + 'static, V: Key + 'static>( &self, definition: MultimapTableDefinition<'_, K, V>, ) -> Result<ReadOnlyMultimapTable<K, V>, TableError>

Open the given table

pub fn open_untyped_multimap_table( &self, handle: impl MultimapTableHandle, ) -> Result<ReadOnlyUntypedMultimapTable, TableError>

Open the given table without a type

pub fn list_tables(&self) -> Result<impl Iterator<Item = UntypedTableHandle>>

List all the tables

pub fn list_multimap_tables( &self, ) -> Result<impl Iterator<Item = UntypedMultimapTableHandle>>

List all the multimap tables

pub fn get_blob(&self, blob_id: &BlobId) -> Result<Option<(Vec<u8>, BlobMeta)>>

Retrieve a blob’s data and metadata by ID.

The returned data is verified against the stored xxh3-128 checksum.

pub fn get_blob_meta(&self, blob_id: &BlobId) -> Result<Option<BlobMeta>>

Retrieve only a blob’s metadata (no data read).

pub fn blob_by_sequence(&self, seq: u64) -> Result<Option<(BlobId, BlobMeta)>>

Look up a blob by its sequence number.

IVF-PQ indexes store vector IDs as u64 sequence numbers. This method resolves a sequence number back to the full (BlobId, BlobMeta) pair by performing a range scan on the blob table from BlobId::new(seq, 0) to BlobId::new(seq, u64::MAX).

Returns the first matching blob, or None if no blob has that sequence.

pub fn composite_query(&self) -> CompositeQuery<'_>

Start building a composite multi-signal query.

Fuses vector similarity, temporal recency, and causal proximity into a single ranked result set. See CompositeQuery for the full builder API.

pub fn read_blob_range( &self, blob_id: &BlobId, offset: u64, length: u64, ) -> Result<Option<Vec<u8>>>

Read a byte range from a blob without checksum verification.

Returns None if the blob does not exist. Returns StorageError::BlobRangeOutOfBounds if offset + length exceeds the blob’s total size.

pub fn blob_reader(&self, blob_id: &BlobId) -> Result<Option<BlobReader>>

Get a seekable reader for a blob’s data.

Returns None if the blob does not exist. The returned BlobReader implements std::io::Read and std::io::Seek for streaming access.

Range reads bypass checksum verification since the stored checksum covers the entire blob.

pub fn dedup_stats(&self) -> Result<DedupStats>

Query deduplication statistics.

Scans the dedup index and returns the number of unique content entries, total reference count across all entries, and estimated bytes saved by dedup. Returns zeroed stats if dedup has never been used.

pub fn blob_stats(&self) -> Result<BlobStats>

Returns statistics about blob region space usage (committed state).

Scans the primary blob table to compute live bytes, then compares with the committed region length to determine dead space and fragmentation.

pub fn blobs_in_time_range( &self, start_ns: u64, end_ns: u64, ) -> Result<Vec<(TemporalKey, BlobMeta)>>

Query blobs within a wall-clock time range (nanoseconds).

Returns (TemporalKey, BlobMeta) pairs ordered by timestamp. Complexity: O(log N + K) where K is the number of results. Returns an empty vec if start_ns > end_ns.

pub fn blobs_near( &self, reference: &BlobId, window_ns: u64, ) -> Result<Vec<(TemporalKey, BlobMeta)>>

Find blobs near a reference blob within a time window.

Looks up the reference blob’s timestamp, then scans +/-window_ns/2. Used for sensor fusion queries (“all inputs within 100ms of X”).

pub fn causal_chain( &self, blob_id: &BlobId, max_hops: usize, ) -> Result<Vec<(BlobId, BlobMeta, Option<CausalEdge>)>>

Traverse the causal chain backwards from a blob.

Follows causal_parent links up to max_hops steps. Returns blobs from newest to oldest (starting with the given blob). The Option<CausalEdge> is the edge from the blob’s parent to itself (None for the root of the chain or if no edge metadata exists).

pub fn causal_children(&self, blob_id: &BlobId) -> Result<Vec<CausalEdge>>

Get all direct causal children of a blob, with edge metadata.

The v2 causal edges index uses a composite (parent, child) key, supporting multiple children per parent (branching causal graphs).

pub fn causal_path( &self, from: &BlobId, to: &BlobId, max_depth: usize, ) -> Result<Option<CausalPath>>

Find a causal path between two blobs via backward traversal.

Walks from to toward from via causal_parent links. Returns the path including both endpoints with edge metadata, or None if no path exists within max_depth hops. The Option<CausalEdge> is the edge from parent to the node (None for the from endpoint which has no incoming edge).

pub fn blobs_by_tag(&self, tag: &str) -> Result<Vec<BlobId>>

Get all blobs with a given tag.

Uses a prefix range scan on the tag index for O(log N + K) performance where K is the number of matching blobs.

pub fn blobs_in_namespace( &self, namespace: &str, ) -> Result<Vec<(BlobId, BlobMeta)>>

Get all blobs in a namespace, with their metadata.

Uses the namespace index for efficient prefix scanning.

pub fn blobs_in_time_range_ns( &self, start_ns: u64, end_ns: u64, namespace: Option<&str>, ) -> Result<Vec<(TemporalKey, BlobMeta)>>

Query blobs within a time range, optionally filtered by namespace.

When namespace is Some, only blobs belonging to that namespace are included. When None, behaves identically to blobs_in_time_range.

pub fn blob_tags(&self, blob_id: &BlobId) -> Result<Vec<String>>

Get tags for a blob.

pub fn blob_namespace(&self, blob_id: &BlobId) -> Result<Option<String>>

Get namespace for a blob.

pub fn read_cdc_since(&self, after_txn_id: u64) -> Result<Vec<ChangeStream>>

Read CDC changes committed after the given transaction ID.

Returns all change records with transaction_id > after_txn_id, ordered by (transaction_id, sequence). Returns an empty vec if CDC has never been used or if there are no newer changes.

pub fn read_cdc_range( &self, start_txn: u64, end_txn: u64, ) -> Result<Vec<ChangeStream>>

Read CDC changes within a transaction ID range (inclusive on both ends).

Returns all change records where start_txn <= transaction_id <= end_txn, ordered by (transaction_id, sequence).

pub fn cdc_cursor(&self, name: &str) -> Result<Option<u64>>

Read the position of a named CDC cursor.

Returns the transaction ID that the named consumer has processed up to, or None if the cursor has never been set.

pub fn latest_cdc_transaction_id(&self) -> Result<Option<u64>>

Returns the transaction ID of the latest CDC log entry, or None if empty.

pub fn close(self) -> Result<(), TransactionError>

Close the transaction

Transactions are automatically closed when they and all objects referencing them have been dropped, so this method does not normally need to be called. This method can be used to ensure that there are no outstanding objects remaining.

Returns ReadTransactionStillInUse error if a table or other object retrieved from the transaction still references this transaction

Trait Implementations

impl BlobQueryProvider for ReadTransaction

type Error = StorageError

Error type returned by blob operations.

fn get_blob_meta( &self, blob_id: &BlobId, ) -> Result<Option<BlobMeta>, Self::Error>

Get blob metadata by ID.

fn blob_by_sequence( &self, seq: u64, ) -> Result<Option<(BlobId, BlobMeta)>, Self::Error>

Look up a blob by its sequence number.

fn blobs_in_time_range( &self, start_ns: u64, end_ns: u64, ) -> Result<Vec<(TemporalKey, BlobMeta)>, Self::Error>

Query blobs in a temporal range [start_ns, end_ns].

fn blobs_in_namespace( &self, namespace: &str, ) -> Result<Vec<(BlobId, BlobMeta)>, Self::Error>

Query blobs in a namespace, returning (BlobId, BlobMeta) pairs.

fn blobs_by_tag(&self, tag: &str) -> Result<Vec<BlobId>, Self::Error>

Query blobs that have the given tag.

fn causal_children( &self, blob_id: &BlobId, ) -> Result<Vec<CausalEdge>, Self::Error>

Get the causal children of a parent blob.

impl Debug for ReadTransaction

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for ReadTransaction

fn drop(&mut self)

Executes the destructor for this type.

impl StorageRead for ReadTransaction

type Table<'txn, K: Key + 'static, V: Value + 'static> = ReadOnlyTable<K, V> where Self: 'txn

The read-only table type returned by open_storage_table.

fn open_storage_table<K: Key + 'static, V: Value + 'static>( &self, definition: TableDefinition<'_, K, V>, ) -> Result<Self::Table<'_, K, V>>

Open a typed table for reading.