Skip to content

Graph-Native Infrastructure for Context and Accountable AI Systems

docs(triplet_store): align SPARQL and storage APIs with implementation

Sameer6305f7e8e87734b9
diff --git a/docs/reference/triplet_store.md b/docs/reference/triplet_store.md
index b232c1ca..a7d06a60 100644
--- a/docs/reference/triplet_store.md
+++ b/docs/reference/triplet_store.md
@@ -4,42 +4,77 @@ description: "RDF triple storage with SPARQL queries and bulk loading — Blazeg
icon: "table"
---
-`semantica.triplet_store` provides W3C-standard RDF storage with full SPARQL query support. Use it when you need semantic web compatibility, OWL reasoning, SPARQL-based queries, or standards-compliant RDF serialization.
+`semantica.triplet_store` provides W3C-standard RDF storage with SPARQL query support. Use it when you need semantic web compatibility, OWL-style reasoning, SPARQL-based queries, or standards-compliant RDF serialization.
## Exported Classes
| Class | Role |
| --- | --- |
-| `TripletStore` | Unified interface: `add_triplet`, `get_triplets`, `delete_triplet`, `execute_query`, `bulk_load` |
-| `QueryEngine` | SPARQL 1.1 execution with query optimization and result streaming |
-| `BulkLoader` | High-volume RDF loading with progress tracking and transaction batching |
-| `BlazegraphStore` | Blazegraph REST API — Named Graphs, SPARQL 1.1 Update, GeoSPARQL |
-| `JenaStore` | Apache Jena Fuseki — TDB2 backend, GeoSPARQL, SPARQL 1.1 |
-| `RDF4JStore` | Eclipse RDF4J — SailRepository, in-memory or native store |
+| `TripletStore` | Unified interface: `add_triplet`, `add_triplets`, `get_triplets`, `delete_triplet`, `execute_query` |
+| `QueryEngine` | SPARQL 1.1 execution with query optimization and result caching |
+| `BulkLoader` | High-volume RDF loading with batching, retries, and progress tracking |
+| `BlazegraphStore` | Blazegraph REST API — SPARQL 1.1 Update, namespace management |
+| `JenaStore` | Apache Jena — rdflib-backed, SPARQL read support via remote endpoint |
+| `RDF4JStore` | Eclipse RDF4J — REST API, transaction support |
## What You Get
<CardGroup cols={2}>
<Card title="TripletStore" icon="server">
- Unified interface across Blazegraph, Apache Jena (Fuseki), and RDF4J — swap backends with one parameter.
- </Card>
- <Card title="TripletStore (in-memory)" icon="bolt">
- Zero-setup in-memory mode via `backend="memory"` for unit tests and small datasets — no server required.
+ Unified interface across Blazegraph, Apache Jena, and RDF4J — swap backends with one parameter.
</Card>
<Card title="SPARQL" icon="magnifying-glass">
- Full SELECT, CONSTRUCT, ASK, and UPDATE query support with pagination for large result sets.
+ Full SPARQL SELECT, ASK, CONSTRUCT, and UPDATE query support via `execute_query()`.
+ </Card>
+ <Card title="Bulk Loading" icon="layer-group">
+ `add_triplets()` batches writes with configurable batch size, retry logic, and progress tracking.
</Card>
- <Card title="OWL Reasoning" icon="microchip">
- Apache Jena supports OWL and RDFS inference natively — subclass and property chain queries automatically resolved.
+ <Card title="SKOS Vocabulary" icon="diagram-project">
+ Built-in helpers: `add_skos_concept()` and `get_skos_concepts()` for controlled vocabulary management.
</Card>
- <Card title="Named Graphs" icon="diagram-project">
- Isolate triples by source, dataset, or time period using named graph management.
+ <Card title="Named Graphs" icon="folder-tree">
+ Blazegraph and RDF4J support named graph scoping via `graph=` on `execute_query()`.
</Card>
- <Card title="Import / Export" icon="file-export">
- Load and serialize to Turtle, JSON-LD, N-Triples, and RDF/XML with a single method call.
+ <Card title="Delta Computation" icon="code-compare">
+ `compute_delta(old_graph_uri, new_graph_uri)` returns added and removed triples between two named graph snapshots.
</Card>
</CardGroup>
+## Getting Started
+
+`TripletStore` wraps the backend of your choice. Construct a `Triplet` object (from `semantica.semantic_extract.types`) and call `add_triplet()`:
+
+```python
+from semantica.triplet_store import TripletStore
+from semantica.semantic_extract.types import Triplet
+
+store = TripletStore(
+ backend="blazegraph",
+ endpoint="http://localhost:9999/blazegraph/sparql"
+)
+
+# Create and store a single triplet
+t = Triplet(
+ subject="http://example.org/apple_inc",
+ predicate="http://example.org/founded_by",
+ object="http://example.org/steve_jobs",
+)
+store.add_triplet(t)
+
+# Query with SPARQL — returns a QueryResult with a .bindings list
+result = store.execute_query("""
+ PREFIX ex: <http://example.org/>
+ SELECT ?person ?company WHERE {
+ ?person ex:founded ?company .
+ }
+""")
+
+for row in result.bindings:
+ person = row.get("person", {}).get("value")
+ company = row.get("company", {}).get("value")
+ print(person, company)
+```
+
## Quick Start
<Steps>
@@ -55,20 +90,23 @@ icon: "table"
</Step>
<Step title="Add triplets">
```python
+ from semantica.semantic_extract.types import Triplet
+
# Add a single triplet
- store.add_triplet(
+ store.add_triplet(Triplet(
subject="http://example.org/apple_inc",
predicate="http://example.org/founded_by",
- obj="http://example.org/steve_jobs"
- )
+ object="http://example.org/steve_jobs",
+ ))
- # Bulk load a list of triplets
- store.add_triplets_bulk(triplets)
+ # Bulk-add a list of Triplet objects
+ store.add_triplets(triplets, batch_size=500)
```
</Step>
<Step title="Query with SPARQL">
```python
- results = store.sparql("""
+ # execute_query returns a QueryResult — iterate result.bindings
+ result = store.execute_query("""
PREFIX ex: <http://example.org/>
SELECT ?person ?company WHERE {
?person ex:founded ?company .
@@ -76,15 +114,16 @@ icon: "table"
}
""")
- for row in results:
- print(row["person"], row["company"])
+ for row in result.bindings:
+ print(row.get("person", {}).get("value"))
+ print(row.get("company", {}).get("value"))
```
</Step>
- <Step title="Export to file">
+ <Step title="Store an entire knowledge graph">
```python
- store.export("output.ttl", format="turtle")
- store.export("output.nt", format="nt")
- store.export("output.xml", format="xml")
+ # store(knowledge_graph, ontology) converts entities/relationships
+ # to RDF triples and bulk-loads them in one call
+ store.store(knowledge_graph=kg_dict, ontology=ontology_dict)
```
</Step>
</Steps>
@@ -93,146 +132,135 @@ icon: "table"
<Tabs>
<Tab title="Blazegraph">
+ ```bash
+ pip install requests
+ ```
+
```python
from semantica.triplet_store import TripletStore
store = TripletStore(
backend="blazegraph",
endpoint="http://localhost:9999/blazegraph/sparql",
- namespace="semantica"
+ namespace="kb", # default: "kb"
+ timeout=30, # request timeout in seconds
)
```
- Best for: Wikidata-style workloads, high triple counts, SPARQL 1.1 full support.
+ Best for: Wikidata-style workloads, high triple counts, named graph support, SPARQL 1.1 Update.
</Tab>
<Tab title="Apache Jena">
- ```python
- store = TripletStore(
- backend="jena",
- endpoint="http://localhost:3030/dataset/sparql",
- update_endpoint="http://localhost:3030/dataset/update"
- )
+ ```bash
+ pip install rdflib
```
- Best for: General RDF, standard SPARQL, production deployments needing OWL inference.
-
- **Enable OWL reasoning:**
-
```python
store = TripletStore(
backend="jena",
- endpoint="http://localhost:3030/dataset/sparql",
- update_endpoint="http://localhost:3030/dataset/update",
- reasoner="OWL", # "OWL" | "RDFS" | "OWL_MINI" | None
+ endpoint="http://localhost:3030/ds", # SPARQL read endpoint for rdflib SPARQLStore
)
+ ```
- # Load an OWL ontology — subclass/property chain inferences are automatic
- store.import_file("ontology.ttl", format="turtle")
- store.add_triplets_bulk(data_triplets)
+ Best for: local development with rdflib, SPARQL read queries against a Fuseki endpoint.
- # Query using inferred relationships
- results = store.sparql("""
- SELECT ?person WHERE {
- ?person a ex:Employee . # inferred via subClassOf chain
- }
- """)
- ```
+ **Note on inference:** `JenaStore` accepts `enable_inference=True` in config but OWL reasoning is a placeholder and does not produce inferred triples in the current implementation.
</Tab>
<Tab title="RDF4J">
+ ```bash
+ pip install requests
+ ```
+
```python
store = TripletStore(
backend="rdf4j",
- server_url="http://localhost:8080/rdf4j-server",
- repository_id="semantica"
+ endpoint="http://localhost:8080/rdf4j-server",
+ repository_id="semantica", # passed through **config
)
```
- Best for: Enterprise Java ecosystems, Eclipse Foundation deployments, plugin-based reasoning.
+ Best for: Eclipse Foundation deployments, transaction-based loading via REST API.
</Tab>
<Tab title="Backend Comparison">
- | Backend | License | OWL Reasoning | Hosted Option | Best For |
- | ------- | ------- | ------------- | ------------- | -------- |
- | Blazegraph | Open source | No | Self-hosted | Wikidata-style workloads, high triple count |
- | Apache Jena | Apache 2.0 | Yes (OWL/RDFS) | Self-hosted | General RDF, OWL reasoning, standard SPARQL |
- | RDF4J | Eclipse 1.0 | Via plugin | Self-hosted or cloud | Enterprise Java ecosystems |
- | InMemory | Built-in | No | N/A | Unit tests, small graphs, no server required |
+ | Backend | License | Named Graphs | Write via | Best For |
+ | ------- | ------- | ------------ | --------- | -------- |
+ | Blazegraph | Open source | Yes | SPARQL Update REST | High triple count, SPARQL 1.1 |
+ | Apache Jena | Apache 2.0 | No (rdflib backend) | rdflib in-process | Local dev, read queries |
+ | RDF4J | Eclipse 1.0 | Yes | REST API N-Triples | Enterprise Java, transactions |
</Tab>
</Tabs>
-## Namespace Prefix Management
+## Triplet Object
-Register custom prefixes to keep SPARQL queries readable:
+All store operations use the `Triplet` dataclass from `semantica.semantic_extract.types`:
```python
-from semantica.triplet_store import TripletStore
-from semantica.ontology import NamespaceManager
-
-ns = NamespaceManager(base_uri="http://example.org/")
-ns.register("ex", "http://example.org/")
-ns.register("schema", "https://schema.org/")
-ns.register("owl", "http://www.w3.org/2002/07/owl#")
-
-store = TripletStore(backend="jena", endpoint="...")
-
-# Registered prefixes are automatically prepended to every SPARQL query
-results = store.sparql("""
- SELECT ?company WHERE {
- ?person ex:works_for ?company ;
- schema:name "Alice" .
- }
-""")
+from semantica.semantic_extract.types import Triplet
+
+t = Triplet(
+ subject="http://example.org/apple_inc", # required: full URI string
+ predicate="http://example.org/founded_by", # required: full URI string
+ object="http://example.org/steve_jobs", # required: URI or literal string
+ confidence=0.95, # optional: float 0.0–1.0, default 1.0
+ metadata={"source": "wikipedia"}, # optional: dict
+)
```
+| Field | Type | Default | Description |
+| ----- | ---- | ------- | ----------- |
+| `subject` | `str` | required | Subject URI |
+| `predicate` | `str` | required | Predicate URI |
+| `object` | `str` | required | Object URI or literal |
+| `confidence` | `float` | `1.0` | Confidence score (0–1) |
+| `metadata` | `dict` | `{}` | Arbitrary metadata |
+
## TripletStore Methods
| Method | Returns | Description |
| ------ | ------- | ----------- |
-| `add_triplet(s, p, o, graph=None)` | `str` | Add a single triplet, returns triplet ID |
-| `add_triplets_bulk(triplets)` | `List[str]` | Batch add triplets with transaction support |
-| `get_triplets(graph=None)` | `List[dict]` | Retrieve all triplets or from a named graph |
-| `delete_triplet(triplet_id)` | `bool` | Delete a triplet by ID |
-| `sparql(query)` | `List[dict]` | Execute SPARQL SELECT query |
-| `sparql_construct(query)` | `Graph` | Execute SPARQL CONSTRUCT query |
-| `sparql_ask(query)` | `bool` | Execute SPARQL ASK query |
-| `sparql_update(query)` | `None` | Execute SPARQL UPDATE (INSERT/DELETE) |
-| `bulk_load(file, format)` | `None` | Load RDF file (turtle, nt, xml) |
-| `export(path, format)` | `None` | Export to turtle, nt, xml |
-| `list_graphs()` | `List[str]` | List all named graphs |
-| `clear_graph(graph_uri)` | `None` | Delete all triples from a named graph |
+| `add_triplet(triplet)` | `dict` | Add a single `Triplet` object |
+| `add_triplets(triplets, batch_size)` | `dict` | Bulk-add a list of `Triplet` objects; returns `{"success", "total", "processed", "failed", "batches"}` |
+| `get_triplets(subject, predicate, object)` | `List[Triplet]` | Retrieve triplets matching subject/predicate/object filters |
+| `delete_triplet(triplet)` | `dict` | Delete a `Triplet` from the store |
+| `update_triplet(old_triplet, new_triplet)` | `dict` | Atomic delete + add |
+| `execute_query(query, parameters, graph, graphs)` | `QueryResult` | Execute a SPARQL query — returns `QueryResult` with `.bindings`, `.variables`, `.execution_time` |
+| `store(knowledge_graph, ontology)` | `dict` | Convert a KG + ontology dict to RDF triples and bulk-load them |
+| `add_skos_concept(concept_uri, scheme_uri, pref_label, ...)` | `dict` | Add a SKOS concept with optional alt labels, broader/narrower/related |
+| `get_skos_concepts(scheme_uri)` | `List[dict]` | Retrieve all SKOS concepts, optionally filtered by scheme URI |
+| `compute_delta(old_graph_uri, new_graph_uri)` | `dict` | Return `{"added_triples", "removed_triples", "added_count", "removed_count"}` between two named graph snapshots |
+| `get_stats()` | `dict` | Get backend statistics |
## SPARQL Queries
+`execute_query()` is the single entry point for all SPARQL operations. It returns a `QueryResult` — access results via `.bindings`:
+
```python
-# SELECT — returns tabular results
-results = store.sparql("""
+from semantica.triplet_store import TripletStore
+
+store = TripletStore(backend="blazegraph", endpoint="http://localhost:9999/blazegraph/sparql")
+
+# SELECT — iterate result.bindings
+result = store.execute_query("""
PREFIX ex: <http://example.org/>
SELECT ?person ?company WHERE {
?person ex:founded ?company .
- ?company ex:located_in ex:SiliconValley .
}
""")
-# CONSTRUCT — returns a graph of matched triples
-graph = store.sparql_construct("""
- PREFIX ex: <http://example.org/>
- CONSTRUCT {
- ?s ex:connected_to ?o
- } WHERE {
- ?s ex:founded ?company .
- ?company ex:has_investor ?o .
- }
-""")
+for row in result.bindings:
+ print(row.get("person", {}).get("value"))
+ print(row.get("company", {}).get("value"))
-# ASK — returns True/False
-exists = store.sparql_ask("""
+# ASK, CONSTRUCT, UPDATE — same method, different SPARQL form
+result = store.execute_query("""
PREFIX ex: <http://example.org/>
ASK { ex:apple_inc ex:founded_by ex:steve_jobs . }
""")
+print(result.bindings) # ASK returns boolean result in bindings
-# UPDATE — insert or delete triples
-store.sparql_update("""
+# SPARQL UPDATE (INSERT/DELETE)
+store.execute_query("""
PREFIX ex: <http://example.org/>
INSERT DATA {
ex:apple_inc ex:listed_on ex:NASDAQ .
@@ -240,6 +268,15 @@ store.sparql_update("""
""")
```
+### QueryResult fields
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `bindings` | `List[dict]` | Each dict maps variable name → `{"value": ..., "type": ...}` |
+| `variables` | `List[str]` | SPARQL result variable names |
+| `execution_time` | `float` | Seconds elapsed |
+| `metadata` | `dict` | Query, graph scope, cache hit flag |
+
## SPARQL Result Pagination
For large result sets, paginate with LIMIT and OFFSET:
@@ -249,96 +286,220 @@ page_size = 1000
offset = 0
while True:
- results = store.sparql(f"""
+ result = store.execute_query(f"""
SELECT ?s ?p ?o WHERE {{
?s ?p ?o .
}}
ORDER BY ?s
LIMIT {page_size} OFFSET {offset}
""")
- if not results:
+ if not result.bindings:
break
- process_batch(results)
+ process_batch(result.bindings)
offset += page_size
```
-## Named Graph Management
+## Named Graph Scoping
+
+Blazegraph and RDF4J support named graphs. Scope `execute_query()` to a named graph with the `graph=` parameter:
```python
-# Named graphs — store triples in isolated contexts
-store.add_triplet(
+# Add a triplet — named graph stored in metadata or backend-specific API
+from semantica.semantic_extract.types import Triplet
+
+t = Triplet(
subject="http://example.org/a",
predicate="http://example.org/p",
- obj="http://example.org/b",
- graph="http://example.org/graph1"
+ object="http://example.org/b",
)
+store.add_triplet(t) # named graph targeting requires backend-specific API
-# Query a specific named graph
-results = store.sparql("""
+# Query a named graph via FROM clause in SPARQL
+result = store.execute_query("""
+ SELECT ?s ?p ?o WHERE {
+ ?s ?p ?o .
+ }
+""", graph="http://example.org/graph1") # injects FROM <graph> before WHERE
+
+# Or scope inline using FROM in the query string
+result = store.execute_query("""
SELECT ?s ?p ?o FROM <http://example.org/graph1> WHERE {
?s ?p ?o .
}
""")
+```
+
+<Note>
+ Named graph support is only available for Blazegraph and RDF4J backends. The `graph=` parameter is silently ignored for the Jena backend.
+</Note>
+
+## Bulk Loading
+
+`add_triplets()` batches writes via the internal `BulkLoader`. Access `store.bulk_loader` to configure it:
+
+```python
+from semantica.triplet_store import TripletStore
+from semantica.semantic_extract.types import Triplet
-# List all named graphs
-graphs = store.list_graphs()
+store = TripletStore(backend="blazegraph", endpoint="http://localhost:9999/blazegraph/sparql")
-# Clear a named graph
-store.clear_graph("http://example.org/graph1")
+# Default: batch_size=1000, max_retries=3
+result = store.add_triplets(triplets)
+# Returns: {"success": True, "total": N, "processed": N, "failed": 0, "batches": B}
+
+# Custom batch size for this call
+result = store.add_triplets(triplets, batch_size=500)
+
+# Validate before loading
+validation = store.bulk_loader.validate_before_load(triplets)
+if not validation["valid"]:
+ print(validation["errors"])
+```
+
+`BulkLoader` can also be used directly with a `progress_callback`:
+
+```python
+from semantica.triplet_store import BulkLoader
+
+loader = BulkLoader(batch_size=2000, max_retries=5, retry_delay=2.0)
+
+def on_progress(p):
+ print(f"{p.progress_percentage:.1f}% ({p.loaded_triplets}/{p.total_triplets})")
+
+progress = loader.load_triplets(triplets, store._store_backend, progress_callback=on_progress)
+print(f"Loaded {progress.loaded_triplets} in {progress.elapsed_time:.2f}s")
+```
+
+## Storing a Knowledge Graph
+
+`store(knowledge_graph, ontology)` converts a KG+ontology dict structure to RDF and bulk-loads everything in one call:
+
+```python
+kg = {
+ "entities": [
+ {"id": "apple_inc", "type": "Organization", "properties": {"name": "Apple Inc."}},
+ {"id": "steve_jobs", "type": "Person", "properties": {"name": "Steve Jobs"}},
+ ],
+ "relationships": [
+ {"source": "steve_jobs", "target": "apple_inc", "type": "founded"}
+ ],
+}
+ontology = {
+ "uri": "https://example.org/ontology/",
+ "classes": [
+ {"name": "Organization"},
+ {"name": "Person"},
+ ],
+ "properties": [
+ {"name": "founded", "type": "object", "domain": ["Person"], "range": ["Organization"]},
+ ],
+}
+
+result = store.store(knowledge_graph=kg, ontology=ontology)
+# Returns add_triplets result dict
+```
+
+## SKOS Vocabulary Management
+
+```python
+store.add_skos_concept(
+ concept_uri="http://example.org/skos/MachineLearning",
+ scheme_uri="http://example.org/skos/AIScheme",
+ pref_label="Machine Learning",
+ alt_labels=["ML", "Statistical Learning"],
+ broader=["http://example.org/skos/AI"],
+ definition="A field of artificial intelligence...",
+)
+
+# Retrieve all concepts in a scheme
+concepts = store.get_skos_concepts(scheme_uri="http://example.org/skos/AIScheme")
+for c in concepts:
+ print(c["uri"], c["pref_label"], c["alt_labels"])
+```
+
+## Delta Computation
+
+```python
+# Compare two named graph snapshots and return added/removed triples
+delta = store.compute_delta(
+ old_graph_uri="http://example.org/graph/v1",
+ new_graph_uri="http://example.org/graph/v2",
+)
+
+print(f"Added: {delta['added_count']} triples")
+print(f"Removed: {delta['removed_count']} triples")
+
+for t in delta["added_triples"]:
+ print(f"+ {t.subject} {t.predicate} {t.object}")
+for t in delta["removed_triples"]:
+ print(f"- {t.subject} {t.predicate} {t.object}")
```
## Integration with Export Module
-The Export module can write RDF that the triplet store then imports:
+The Export module writes RDF that the triplet store can then receive via `add_triplets()`:
```python
from semantica.export import RDFExporter
from semantica.triplet_store import TripletStore
+from semantica.semantic_extract.types import Triplet
# Export KG to Turtle
exporter = RDFExporter()
exporter.export_to_file(kg, "output.ttl", format="turtle")
-# Load into triplet store
-store = TripletStore(backend="jena", endpoint="http://localhost:3030/dataset/sparql")
-store.import_file("output.ttl", format="turtle")
-
-# Now query with SPARQL
-results = store.sparql("SELECT * WHERE { ?s ?p ?o } LIMIT 10")
+# Parse the file and load triplets into the store
+# (TripletStore does not have a built-in import_file() method —
+# parse with rdflib and convert to Triplet objects)
+import rdflib
+g = rdflib.Graph()
+g.parse("output.ttl", format="turtle")
+
+store = TripletStore(backend="jena", endpoint="http://localhost:3030/ds")
+triplets = [
+ Triplet(subject=str(s), predicate=str(p), object=str(o))
+ for s, p, o in g
+]
+store.add_triplets(triplets)
+
+# Query with SPARQL
+result = store.execute_query("SELECT * WHERE { ?s ?p ?o } LIMIT 10")
+for row in result.bindings:
+ print(row)
```
## Tips and Common Pitfalls
<Tip>
- **Use Apache Jena (Fuseki) for development and Blazegraph for production.** Jena runs with a single Docker command, supports OWL reasoning natively, and requires no licence. Switch to Blazegraph for high-throughput workloads by changing the `backend=` parameter — no other code changes needed.
+ **Use Apache Jena for development, Blazegraph for production.** Jena initializes with rdflib in-memory — no server required for local testing. Switch to Blazegraph for high-throughput persistent workloads by changing `backend=`.
</Tip>
<Warning>
- **Paginate large SPARQL result sets.** A `SELECT * WHERE { ?s ?p ?o }` against a million-triple store can return gigabytes of data. Always include `LIMIT` and `OFFSET` in exploratory queries, and iterate with `page_size` when you need full coverage. Unbounded queries against large stores will OOM or timeout.
+ **`execute_query()` returns `QueryResult`, not a list.** Iterate `result.bindings`, not `result` directly. Each binding is a dict mapping variable name → `{"value": ..., "type": ...}`.
</Warning>
-<Tip>
- **Use named graphs to isolate sources.** `store.add_triplet(..., graph="http://example.org/source_A")` puts triples into a named graph. You can then query just that source, merge selectively, or clear it without touching other data — far safer than mixing all triples into the default graph.
-</Tip>
-
-<Tip>
- **Register namespace prefixes before querying.** `NamespacePrefixManager` lets you write `?s ex:name ?o` instead of `?s <http://example.org/name> ?o`. Without prefixes, SPARQL queries against domain ontologies become unreadable and error-prone.
-</Tip>
+<Warning>
+ **`add_triplet()` takes a `Triplet` object, not keyword arguments.** Use `Triplet(subject=..., predicate=..., object=...)` from `semantica.semantic_extract.types` and pass the object — not `subject=`, `predicate=`, `obj=` to `add_triplet`.
+</Warning>
<Warning>
- **Enable OWL reasoning only when you need it.** `reasoner="OWL"` significantly increases query planning overhead. For simple triple lookups or SPARQL SELECT queries, leave reasoning off (`reasoner=None`) and enable it only for queries that depend on class hierarchies or property chains.
+ **Paginate large SPARQL result sets.** A `SELECT * WHERE { ?s ?p ?o }` against a large store returns all triples. Always include `LIMIT` and `OFFSET` in exploratory queries. `QueryEngine` adds `LIMIT 1000` automatically unless you specify one.
</Warning>
<Tip>
- **Export to Turtle before migrating backends.** If you need to move from Jena to Blazegraph (or any other store), `store.export("dump.ttl", format="turtle")` produces a portable file that any SPARQL store can import. Don't rely on backend-specific dump formats.
+ **Use named graphs to isolate sources.** Pass `graph="http://example.org/source_A"` to `execute_query()` to scope a query to a specific named graph. Blazegraph and RDF4J support named graphs; Jena (rdflib backend) does not.
</Tip>
+<Warning>
+ **`backend="jena"` OWL inference is a placeholder.** `enable_inference=True` is accepted but the inference call returns 0 inferred triples. For production OWL reasoning, use Jena Fuseki directly with its built-in reasoner configuration.
+</Warning>
+
<CardGroup cols={2}>
<Card title="Export" icon="file-export" href="export">
Export knowledge graphs to RDF formats.
</Card>
<Card title="Ontology" icon="sitemap" href="ontology">
- Load OWL ontologies into a triplet store.
+ Load OWL ontologies and store as RDF triples.
</Card>
<Card title="Reasoning" icon="microchip" href="reasoning">
SPARQL-based property chain inference.