Struct GraphIndex 

pub struct GraphIndex { /* private fields */ }

The six tiled permutation sections, queryable by triple pattern.

Implementations

impl GraphIndex

pub fn from_tiles(sections: [Vec<(u32, u32, Vec<u8>)>; 6]) -> GraphIndex

Rebuild from tiled sections: per permutation, (min_a, max_a, block bytes) per tile in ascending leading-id order — the v0.2 layout.

pub fn from_remote_directories( directories: [Vec<(u32, u32, Option<(u32, u32, u32, u32)>)>; 6], loader: Box<dyn Fn(usize, usize) -> Option<Vec<u8>> + Send + Sync>, ) -> GraphIndex

A remote index: only the tile directories (leading-id ranges per permutation, ascending) are known; tile payloads fault in through loader on first scan. Check load_incomplete after evaluating — a failed fetch must become an error, never a silently smaller result.

pub fn with_bulk_loader( self, bulk: Box<dyn Fn(usize, &[usize]) -> Option<Vec<Vec<u8>>> + Send + Sync>, ) -> GraphIndex

Attach a batched tile fetcher (see [TileBulkLoader]): multi-tile scans prefetch their span through it instead of faulting tile by tile.

pub fn load_incomplete(&self) -> bool

Did any tile fetch fail since this index was opened — or since the last reset_load_failure?

pub fn reset_load_failure(&self)

Forget recorded fetch failures — the start-of-evaluation reset for a RESIDENT session, making the incompleteness verdict per-query instead of per-open (one transient network blip used to fail every later query on the session). Safe because failed tiles are never cached: the next scan simply retries them.

pub fn is_remote(&self) -> bool

True for a remote/lazy index (tiles fault in over a RangeReader). The join planner uses this to pick read-aware strategies: here a per-row index probe is a network round-trip, not a memory lookup, so a left-deep scan + hash join often beats probing a moderately-sized prefix.

pub fn triple_count(&self) -> u32

Total triple count (sum of the SPO tiles’ zone counts). For a remote index this faults in the SPO tiles — prefer the header’s quad count.

pub fn tile_sections(&self) -> [&[Tile]; 6]

The tiles of each permutation section (in ALL_PERMS order), for the file writer.

pub fn best_permutation( pattern: (Option<u32>, Option<u32>, Option<u32>), ) -> IndexPermutation

The permutation selected for a pattern: the one with the longest bound prefix. Ties keep the canonical SPO order (then POS, then OSP), which makes provenance stable for unbound or equally selective shapes and routes a fully unbound pattern to the SPO block rather than fetching all three.

pub fn permutation_sorted_on( pattern: (Option<u32>, Option<u32>, Option<u32>), sort_col: usize, ) -> Option<IndexPermutation>

Choose a permutation that routes on pattern’s bound prefix and streams sorted on the canonical column sort_col (0=subject, 1=predicate, 2=object) — i.e. sort_col is the leading free component after the bound prefix. Returns None if sort_col is itself bound (then every row shares that value — any permutation is “sorted” on it) or no permutation qualifies. This is the precondition a merge join needs: both inputs sorted on the join key. Among qualifiers, the longest bound prefix (best routing) wins.

pub fn match_serialized_block( bytes: &[u8], permutation: IndexPermutation, pattern: (Option<u32>, Option<u32>, Option<u32>), ) -> Vec<(u32, u32, u32)>

Match one already-decoded serialized permutation block (a single v0.1 section or one v0.2 tile). This is the core primitive for range-routed readers: the caller fetches only the selected payload, then this scans it as if it came from a full GraphIndex.

pub fn match_pattern( &self, pattern: (Option<u32>, Option<u32>, Option<u32>), ) -> Vec<(u32, u32, u32)>

All triples matching pattern, returned in canonical (s, p, o) order.

Thin eager wrapper over scan_iter: collect the lazy stream and restore the canonical sort (the stream is sorted in the chosen permutation’s order, which differs from canonical once perm.back permutes the free components).

pub fn scan_iter( &self, pattern: (Option<u32>, Option<u32>, Option<u32>), ) -> impl Iterator<Item = (u32, u32, u32)>

Lazily stream the triples matching pattern in canonical (s, p, o) order within the chosen permutation — the streaming entry point for callers that can stop early (ASK, LIMIT, BGP probes) or that don’t need the canonical re-sort. Decodes only the matching groups (see TripleBlock::scan); a malformed/absent block yields nothing rather than panicking. The permutation is chosen for the longest bound prefix.