Struct Rete 

pub struct Rete { /* private fields */ }

A read-only, in-memory view over a .rete file image.

Implementations

impl Rete

pub fn open(bytes: &[u8]) -> Result<Self, FileError>

Parse a full file image (v0 loads everything; a range-reading client will fetch only the sections it needs — same container format).

pub fn set_service_client(&mut self, client: Box<dyn ServiceClient>)

Attach the client that executes SERVICE <endpoint> { … } blocks (SPARQL 1.1 federated query) against remote SPARQL endpoints. Without one, a non-SILENT SERVICE fails the query with a clear error and a SERVICE SILENT degrades to one empty solution, per the spec.

pub fn header(&self) -> &Header

pub fn file_layout(&self) -> Vec<LayoutSegment>

The file’s byte layout, for visualization: header, metadata, dictionary, each index permutation’s tile directory and individual tiles, pyramid summary, and named graphs — sorted by offset. Bytes not covered by any segment are container framing (section directories and length fields).

pub fn metadata(&self) -> Option<&[u8]>

Raw bytes of the file’s metadata section, or None if it has none. The CLI stores a JSON Dataset Card here; rete-core treats it as opaque. Populated by Rete::open only — an Rete::open_ranged view returns None here (the card is not fetched on the minimal query path).

pub fn dictionary(&self) -> &Dictionary

pub fn pyramid(&self) -> Option<&PyramidMeta>

The pyramid metadata (summary graph + tiles), if the file has a pyramid.

pub fn pyramid_if_loaded(&self) -> Option<&PyramidMeta>

The pyramid metadata only if already resident or previously faulted — never triggers a lazy range read. The query planner uses this for cardinality estimation so it is free for an in-memory file and never adds a fetch on the lazy remote path (which defers the pyramid by design).

pub fn predicate_stats(&self) -> &[PredStat]

Per-predicate planner statistics from the query-stats block — empty when the file has none or the pyramid isn’t resident (the lazy path doesn’t fault it just for stats). See [crate::meta::PredStat].

pub fn char_sets(&self) -> &[CharSet]

The entity shapes (characteristic sets) from the pyramid — empty when the file has none or the pyramid isn’t resident. See [crate::meta::CharSet].

pub fn label_index(&self) -> &[LabelEntry]

The label index from the pyramid — empty when the file has none or the pyramid isn’t resident. See [crate::meta::LabelEntry].

pub fn prefix_search(&self, prefix: &str, limit: usize) -> Vec<(String, String)>

Prefix-search the label index: the subjects whose label starts with prefix (case-insensitive), as (label, subject_iri), capped at limit. Unlike the planner accessors, this faults the pyramid (where the index lives) on the lazy path — a prefix search is an explicit read, not a free estimate. Returns an empty vec when the file carries no label index.

pub fn has_text_index(&self) -> bool

Whether this file carries a full-text (TEXT_INDEX) section, i.e. it was built with --text-index. Cheap — reads the header, never faults.

pub fn text_search( &self, words: &[&str], prefix: Option<&str>, limit: usize, ) -> Vec<String>

Full-text search over the literals: subject IRIs that carry every word in words (whole-word, case-insensitive — AND semantics), optionally also requiring a word that starts with prefix (token-prefix). Results are ordered by subject id and capped at limit (0 = uncapped). Empty when the file has no text index or nothing matches.

Like prefix_search, this faults the index on the lazy remote path — a search is an explicit read, and only the queried posting lists are fetched, not the whole index.

pub fn default_index(&self) -> &GraphIndex

The default-graph permutation index.

pub fn dump(&self, graph: Option<&str>) -> Vec<TermTriple>

Resolve every triple of a graph (None = default graph) back to terms.

pub fn dump_each<F: FnMut(&str, &str, &str)>(&self, graph: Option<&str>, f: F)

Stream every triple of a graph (None = default) to f, resolving terms one at a time — no full Vec materialization, so it is safe on graphs far larger than RAM. rete export uses this to serialize 100M+ triple files that dump() (which collects every term into a Vec<String>) would OOM on.

pub fn named_graphs(&self) -> &[(String, GraphIndex)]

All named graphs as (iri, index).

pub fn graph_names(&self) -> Vec<&str>

IRIs of the named graphs in this dataset (the default graph is unnamed).

pub fn graph_index(&self, iri: &str) -> Option<&GraphIndex>

The permutation index of a named graph, or None if absent.

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

Match a triple pattern in dictionary-ID space (subject/predicate/object IDs), returning integer triples — the fast path used by the BGP engine.

pub fn predicate_pairs(&self, predicate: &str) -> Vec<(u32, u32)>

All (subject_node, object_node) pairs for a predicate, as unified node IDs — no term resolution. The fast path for graph traversal.

pub fn open_ranged<R: RangeReader>(reader: &R) -> Result<Self, FileError>

Open via a RangeReader, fetching only the header and the named section ranges — never a linear scan of the whole resource. A full query open touches at most 4 ranges (header, dictionary, index, pyramid-meta).

pub fn open_ranged_lazy<R: RangeReader + Send + Sync + 'static>( reader: R, ) -> Result<Self, FileError>

Open via an owned RangeReader with lazy tile faulting (tiled v0.2 files): fetches the header, dictionary, pyramid meta, named graphs, and each permutation’s tile directory — but no default-graph tile payloads. Tiles fault in (one range request each) the first time a scan touches them, so a selective SPARQL query fetches O(touched tiles) bytes instead of the whole index.

Failure contract: scans are infallible by design, so a failed tile fetch yields an empty tile and sets a sticky flag — after evaluating, callers MUST check index_incomplete and surface an error instead of the (possibly partial) results.

pub fn index_incomplete(&self) -> bool

Did any lazy fetch (index tile or dictionary chunk) fail since this Rete was opened? When true, query results may be silently incomplete — callers using Rete::open_ranged_lazy must check this after evaluating and turn it into an error.

pub fn reset_load_failures(&self)

Forget recorded lazy-fetch failures — the start-of-evaluation reset for a RESIDENT session (a browser worker holding one Rete across many queries): it makes index_incomplete a per-query verdict instead of a per-open one, so a single transient network failure no longer fails every subsequent query on the session. Sound because failed tiles/chunks are never cached — the next evaluation simply retries the fetch.

pub fn query_with_provenance( &self, s: Option<&str>, p: Option<&str>, o: Option<&str>, ) -> Vec<TripleProvenance>

Evaluate a triple pattern and include the file/index provenance for every matched result. A bound term that is unknown to the dictionary yields no matches.

pub fn query( &self, s: Option<&str>, p: Option<&str>, o: Option<&str>, ) -> Vec<TermTriple>

Evaluate a triple pattern given as optional term strings, returning matching triples resolved back to terms. A bound term that is unknown to the dictionary yields no matches.

pub fn query_in_graph( &self, graph: Option<&str>, s: Option<&str>, p: Option<&str>, o: Option<&str>, ) -> Vec<TermTriple>

Match a triple pattern within a single graph — None is the default graph, Some(iri) a named graph — resolving matches to canonical terms. This is Rete::query (default-graph only) generalized to any graph: the graph-scoped primitive a quad-aware consumer (e.g. an RDF4J Sail’s getStatements) needs. An unknown graph IRI, or a bound term absent from the shared dictionary, yields an empty result. All graphs share one dictionary, so the pattern resolves once against that ID space.

pub fn query_quads( &self, s: Option<&str>, p: Option<&str>, o: Option<&str>, ) -> Vec<(TermTriple, Option<String>)>

Match a triple pattern across the default graph and every named graph, tagging each match with its graph (None = default). The quad-level companion to Rete::query; default-graph matches come first, then each named graph in stored order.

pub fn query_ranged<R: RangeReader>( reader: &R, s: Option<&str>, p: Option<&str>, o: Option<&str>, ) -> Result<Vec<TermTriple>, FileError>

Evaluate one triple pattern through a RangeReader by fetching only the header, the dictionary, and — for a tiled (v0.2) file — the selected permutation section’s tile directory plus the tile(s) the bound leading id routes to; an unbound leading id fetches the section’s tile body in one request. v0.1 files fetch the whole selected section. Unknown bound terms return an empty result before touching the index.

pub fn route_pattern_ranged<R: RangeReader>( reader: &R, s: Option<&str>, p: Option<&str>, o: Option<&str>, ) -> Result<bool, FileError>

Route one triple pattern to its permutation section without fetching any payload bytes. Returns false when a bound term is unknown and the index was skipped.