🗄️ Knowledge Graph Service

RDF triple store with SPARQL queries.

Overview

The Knowledge Graph (KG) provides an inferential projection of the Semantic Core, storing enterprise knowledge as interconnected entities and relationships using Oxigraph.

Feature Description
Storage RDF triple store (Turtle/JSON-LD)
Query SPARQL 1.1 (primary), Cypher (secondary)
Validation SHACL shapes
Inference OWL-RL (optional)

Technology Stack

Component Technology Purpose
Triple Store Oxigraph Production RDF storage
Python Bindings pyoxigraph Python integration
SPARQL Engine Comunica TypeScript queries
Validation pySHACL Shape checking
Inference OWL-RL Logical reasoning

Data Model

RDF Prefixes

1
2
3
4
5

PREFIX sea: <http://sea-forge.com/schema/core#>
PREFIX sea-debt: <http://sea-forge.com/schema/debt#>
PREFIX sea-inc: <http://sea-forge.com/schema/incident#>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>

Core Classes

DSL Concept RDF Class Description
Entity sea:Entity Business actors/objects
Resource sea:Resource Quantifiable assets
Flow sea:Flow Movements between entities
Policy sea:Rule Constraints and rules

API Endpoints

Endpoint Method Description
/graph/query POST Execute SPARQL query
/graph/shacl/validate POST Run SHACL validation
/graph/snapshots GET List snapshots
/graph/snapshots POST Create snapshot
/graph/snapshots/{id}/query POST Query specific snapshot
/graph/changesets POST Create change set
/graph/changesets/{id}/apply POST Apply changes

SPARQL Queries

Basic Select

1
2
3
4
5
6
7
8

PREFIX sea: <http://sea-forge.com/schema/core#>

SELECT ?entity ?name ?domain
WHERE {
  ?entity a sea:Entity ;
          rdfs:label ?name ;
          sea:inContext ?domain .
}

Find Flows

1
2
3
4
5
6
7
8
9
10

PREFIX sea: <http://sea-forge.com/schema/core#>

SELECT ?flow ?from ?to ?resource ?quantity
WHERE {
  ?flow a sea:Flow ;
        sea:from ?from ;
        sea:to ?to ;
        sea:resource ?resource ;
        sea:quantity ?quantity .
}

Aggregation

1
2
3
4
5
6
7
8
9
10

PREFIX sea: <http://sea-forge.com/schema/core#>

SELECT ?to (SUM(?quantity) as ?totalReceived)
WHERE {
  ?flow a sea:Flow ;
        sea:to ?to ;
        sea:quantity ?quantity .
}
GROUP BY ?to
ORDER BY DESC(?totalReceived)

Snapshot & Versioning

Design Principles

Principle Description
Isomorphism State derivable from inputs + change sets
Immutability Snapshot IDs are immutable
Idempotency Same change set = same result
Determinism Identical inputs → identical snapshot

Create Snapshot

1
2
3
4
5
6
7

curl -X POST http://localhost:8000/graph/snapshots \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.0.0",
    "description": "Initial production snapshot",
    "tags": ["production"]
  }'

Query Against Snapshot

1
2
3
4
5
6

curl -X POST http://localhost:8000/graph/snapshots/ifl:snap:abc123.../query \
  -H "Content-Type: application/json" \
  -d '{
    "language": "sparql",
    "query": "SELECT * WHERE { ?s ?p ?o } LIMIT 10"
  }'

Direct Oxigraph Access

SPARQL Query

1
2
3

curl -X POST http://localhost:7878/query \
  -H "Content-Type: application/sparql-query" \
  -d "SELECT * WHERE { ?s ?p ?o } LIMIT 10"

Load Triples

1
2
3

curl -X POST http://localhost:7878/store \
  -H "Content-Type: text/turtle" \
  --data-binary @model.ttl

Update (SPARQL Update)

1
2
3

curl -X POST http://localhost:7878/update \
  -H "Content-Type: application/sparql-update" \
  -d "DELETE WHERE { <http://example.org/entity1> ?p ?o }"

Performance Tuning

Strategy Implementation
Indexing Enable SPO, POS, OSP indexes
Caching Cache frequent query results
Batching Batch triple insertions
Pagination Use LIMIT/OFFSET for large results