semantica/semantica/triplet_store/triplet_store_usage.md

Triplet Store Module Usage Guide

This comprehensive guide demonstrates how to use the triplet store module for RDF data storage and querying, supporting embedded Oxigraph and server-backed Blazegraph, Jena, RDF4J, and Anzo stores with unified interfaces, SPARQL query execution, bulk loading, and query optimization.

Table of Contents

1. Basic Usage
2. Store Registration
3. CRUD Operations
4. SPARQL Query Execution
5. Query Optimization
6. Bulk Loading
7. Store Backends
8. Configuration

Basic Usage

Using TripletStore Class

from semantica.triplet_store import TripletStore
from semantica.semantic_extract.triplet_extractor import Triplet

# Initialize store (Blazegraph default)
store = TripletStore(
    backend="blazegraph",
    endpoint="http://localhost:9999/blazegraph"
)

# Add a triplet
triplet = Triplet(
    subject="http://example.org/entity1",
    predicate="http://example.org/hasName",
    object="John Doe",
    confidence=0.9
)
result = store.add_triplet(triplet)

print(f"Triplet added: {result['success']}")

Using Convenience Functions

from semantica.triplet_store import register_store, add_triplet

# Register a store
store = register_store("main", "blazegraph", "http://localhost:9999/blazegraph")

# Add a triplet
result = add_triplet(
    Triplet("http://s", "http://p", "http://o"),
    store_id="main"
)

CRUD Operations

Adding Triplets

from semantica.triplet_store import TripletStore
from semantica.semantic_extract.triplet_extractor import Triplet

store = TripletStore(backend="blazegraph", endpoint="http://localhost:9999/blazegraph")

# Add single triplet
triplet = Triplet(
    subject="http://example.org/entity1",
    predicate="http://example.org/hasName",
    object="John Doe"
)
result = store.add_triplet(triplet)

# Add multiple triplets (Bulk)
triplets = [
    Triplet("http://example.org/entity1", "http://example.org/hasAge", "30"),
    Triplet("http://example.org/entity1", "http://example.org/hasCity", "New York")
]
result = store.add_triplets(triplets, batch_size=1000)
print(f"Added {result['total']} triplets")

Retrieving Triplets

# Get all triplets for a subject
triplets = store.get_triplets(subject="http://example.org/entity1")

# Get triplets matching predicate
triplets = store.get_triplets(predicate="http://example.org/hasName")

# Get specific triplet
triplets = store.get_triplets(
    subject="http://example.org/entity1",
    predicate="http://example.org/hasName",
    object="John Doe"
)

Deleting Triplets

# Delete triplet
triplet = Triplet(
    subject="http://example.org/entity1",
    predicate="http://example.org/hasName",
    object="John Doe"
)
result = store.delete_triplet(triplet)

SPARQL Query Execution

query = """
SELECT ?s ?p ?o
WHERE {
    ?s ?p ?o .
    ?s <http://example.org/hasName> ?o .
}
LIMIT 10
"""
result = store.execute_query(query)

print(f"Variables: {result.variables}")
print(f"Results: {len(result.bindings)}")
for binding in result.bindings:
    print(binding)

Bulk Loading

The module supports high-performance bulk loading with progress tracking.

from semantica.triplet_store import BulkLoader

loader = BulkLoader()
triplets = [...] # List of 10,000 triplets

# Load triplets
progress = loader.load_triplets(triplets, store._store_backend)

print(f"Loaded: {progress.loaded_triplets}/{progress.total_triplets}")
print(f"Failed: {progress.failed_triplets}")

Store Backends

Oxigraph (embedded)

Oxigraph runs in the Python process and does not require a separate server. Install the optional backend first:

pip install "semantica[tripletstore-oxigraph]"

Omit path for an in-memory store, which is useful for tests and temporary workloads:

store = TripletStore(backend="oxigraph")

Set path to persist the database in a local directory:

store = TripletStore(
    backend="oxigraph",
    path="./data/knowledge-graph",
)

The Oxigraph backend supports the same CRUD and SPARQL query methods as the other backends, including named graphs through the graph argument. For distributed production deployments, use one of the server-backed stores below.

Blazegraph

High-performance graph database supporting RDF/SPARQL.

store = TripletStore(backend="blazegraph", endpoint="http://localhost:9999/blazegraph")

Jena

Apache Jena Fuseki support.

store = TripletStore(backend="jena", endpoint="http://localhost:3030/ds")

RDF4J

Eclipse RDF4J support.

store = TripletStore(backend="rdf4j", endpoint="http://localhost:8080/rdf4j-server")

Anzo

Altair Anzo (Altair Graph Studio) support. Unlike Blazegraph's namespace or RDF4J's repository ID, Anzo addresses data by a dataset/graphmart URI rather than a short name, so dataset_uri is required and is percent-encoded into the endpoint path (<endpoint>/sparql/<store_type>/<url-encoded_dataset_uri>).

store = TripletStore(
    backend="anzo",
    endpoint="http://localhost:8080",
    dataset_uri="http://cambridgesemantics.com/Graphmart/abc123",
    store_type="graphmart",  # or "lds" (Anzo's Linked Data Set store type)
    username="user",
    password="pass",
)

Configuration

Configuration is managed via config.yaml or environment variables.

triplet_store:
  default_backend: blazegraph
  blazegraph_endpoint: http://localhost:9999/blazegraph
  jena_endpoint: http://localhost:3030/ds
  rdf4j_endpoint: http://localhost:8080/rdf4j-server
  anzo_endpoint: http://localhost:8080