Core concepts

This page defines the vocabulary the SDKs and API assume. To run something first, start with the Quickstart and come back here when a term is unfamiliar.

Graph scope: tenant / graph / branch

Every operation is scoped by three names that together form a GraphKey:

• tenant is the data plane’s internal isolation boundary. On the hosted product each stack is served as its own tenant, so a stack API key can only reach its own stack; self-hosted deployments name the tenant directly.
• graph is a named graph within the stack (default main). A graph’s ontology is set at creation and grows additively from there.
• branch is a copy-on-write snapshot of a graph (default main). A child branch reuses the parent’s log and index objects until it writes new commits.

In the SDKs you scope with client.graph("name"); over HTTP you pass ?graph=/?branch= query parameters.

Append-only log

little big brain does not destructively update facts by default. Ingest appends immutable events to a write-ahead log (WAL):

• entities, the named nodes an RDF subject or object resolves to
• edges, the statements between those nodes, carrying the source predicate IRI, the named-graph label, and literal term metadata
• observations, the evidence and source metadata behind a statement
• supersession links and provenance references

Current state is a reducer projection over that event history. Because history is retained, you can read how a statement changed over time and pin a query to a past snapshot. A retraction path exists for the cases that need deletion.

RDF projection

A whole knowledge-graph load introduces new predicates constantly. Storing one ontology relation per source predicate would mutate the schema on every one of them, so loaded RDF is stored on fixed-schema edges instead. The RDF projection expands those edges back into the original terms, so a SPARQL query matches the subjects, predicates, objects, named graphs, datatypes, and language tags of the document you loaded.

Snapshot & consistency

Each branch head owns one immutable F3 query base, a bounded sequence of immutable per-commit deltas, and retained checkpoints for time travel. The head is both durable truth and read authority; there is no second publication pointer. A request pins that exact head lineage for its lifetime.

Reads have two consistency modes:

• eventual is the default. It serves the pinned immutable F3 base. The response snapshot reports its served_at_seq with stale: true and stale_reason: "eventual_consistency" when deltas are waiting to be compacted.
• strong is an explicit opt-in. It applies the head’s bounded exact F3 delta suffix over the same base and therefore sees every accepted write immediately. It never falls back to graph assembly or returns stale success.

Read-your-writes

Because eventual is the default, use strong consistency and the min_indexed_seq floor to read back a fact you wrote a moment ago. Take the commit_seq a commit or import returned and pass it as min_indexed_seq (a body field, or ?min_indexed_seq= on the URL routes). The accepted commit already contains its queryable F3 delta, so the strong read succeeds without polling a publication job.

Published RDF and derived query indexes

Object storage holds leveled RDF truth, per-commit F3 deltas, and immutable F3 query bases. F3 range-reads object storage through disposable NVMe and RAM cache tiers. A commit becomes visible with its delta; background reconciliation later folds those deltas into a new verified base. Missing or invalid F3 state fails closed; a read never falls back to a slower corpus scan or runs an O(corpus) build inside the request.

Ontology

A graph’s ontology names its entity types, relation types, and properties, and gives them domains, ranges, and hierarchies. You can import a custom ontology at graph creation from JSON-LD, Turtle, RDF/XML, CSV/TSV, or a compact “spec” shape. OWL classes become entity types, owl:ObjectProperty declarations become relations, and owl:DatatypeProperty declarations become typed property fields (xsd:integer to integer, xsd:boolean to boolean, date and time datatypes to datetime, and so on). RDF loaded through import/rdf bootstraps a fixed generic schema instead, so no ontology design is required to start.

Query surfaces

Three read surfaces run over the same immutable branch-head RDF lineage:

• SPARQL 1.1 text runs on the conformant engine, and is also served at a native /sparql Protocol endpoint for tools like YASGUI and Protégé.
• Structured query is a SPARQL-subset SELECT/ASK over a basic graph pattern with typed filters, GROUP BY (including scalar and date-bucket keys), aggregates, HAVING, and ORDER BY, expressed as JSON rather than query text.
• SHACL covers Core, SHACL-SPARQL, and SHACL-AF for validation, shape selection, property paths, and rule-based inference.

See SPARQL, structured query & SHACL.

Reasoning & inference

Reads can return statements you never wrote, derived from the ones you did. The entailment control on every SPARQL read selects the regime, per query:

• subclass follows the asserted RDFS subClassOf hierarchy, so a query for a broad class also matches its subclasses.
• rdfs adds subproperty value propagation and domain/range type derivation.
• owl adds the OWL vocabulary on top: equivalence, inverse, symmetric, and transitive properties, property chains, class constructors, restriction rules, and owl:sameAs identity.

The default is none: a query returns the facts exactly as written. Every regime is resolved at query time from the published schema triples, with no rebuild and no republish, and the answer is deterministic for a pinned snapshot. See Reasoning & inference.

Storage

Every durable read and write goes through the ObjectBackend contract. Two backends exist: LocalFsObjectBackend for a filesystem and S3ObjectBackend for S3-compatible buckets, verified against MinIO and Hetzner Object Storage. Both provide immutable writes, conditional updates through compare-and-swap (If-None-Match / If-Match), range reads, content-hash ETags, checksum validation, and listing.

Metrics

An in-process metrics registry records graph-operation counters and latencies, object-backend counters, bytes, and latencies, and HTTP counters and latencies. The server exposes operator-only Prometheus text at /metrics, which Grafana consumes. Metric labels are deliberately low-cardinality.