RDF / SPARQL stores
The RDF / SPARQL contributor package stores the lexical graph in an existing SPARQL 1.1 query/update endpoint. Generic standards-compatible endpoints are the default; Amazon Neptune IAM authentication is an optional transport.
The adapter executes native SPARQL. Builders and retrievers provide a backend-neutral operation identifier and structured parameters. Property-graph stores execute their native queries, while the RDF store selects the corresponding native SPARQL operation.
Install and register
Section titled “Install and register”Install the core and contributor packages from the same repository checkout. This contributor requires the source-ID guard operations added with it, which are not available in older core releases:
pip install ./lexical-graph ./lexical-graph-contrib/sparqlRegister its factory before creating the graph store:
from graphrag_toolkit.lexical_graph.storage import GraphStoreFactoryfrom graphrag_toolkit_contrib.lexical_graph.storage.graph.sparql import ( SPARQLGraphStoreFactory,)
GraphStoreFactory.register(SPARQLGraphStoreFactory)Connect the graph store to an existing repository or dataset.
Generic endpoint
Section titled “Generic endpoint”Provide the query URL and, if different, the update URL:
graph_store = GraphStoreFactory.for_graph_store( 'https://rdf.example.com/query', graph_store_type='sparql', update_endpoint='https://rdf.example.com/update',)Use the endpoint’s ordinary http:// or https:// URL without changing its
scheme. graph_store_type='sparql' selects the contributor. If
update_endpoint is omitted, the query URL is used for both operations.
HTTP Basic credentials can be passed in the URL, through username and
password, or through the SPARQL_USER and SPARQL_PASSWORD environment
variables. Custom headers support bearer tokens and endpoint-specific headers:
graph_store = GraphStoreFactory.for_graph_store( 'https://rdf.example.com/query', graph_store_type='sparql', headers={'Authorization': 'Bearer token'},)Amazon Neptune IAM
Section titled “Amazon Neptune IAM”Install the optional botocore dependency:
pip install ./lexical-graph './lexical-graph-contrib/sparql[neptune]'Then select IAM authentication explicitly and provide the AWS region:
graph_store = GraphStoreFactory.for_graph_store( 'https://my-cluster.cluster-abcdefghijkl.eu-central-1.neptune.amazonaws.com:8182/sparql', graph_store_type='sparql', auth_type='aws_iam', region_name='eu-central-1',)Each request is signed for the neptune-db service using credentials from
botocore’s standard provider chain. Credentials are resolved on every request,
allowing botocore to refresh temporary role, web-identity, IAM Identity Center,
ECS, and EC2 credentials. IAM transport requires HTTPS.
The same transport is available as a plain RDFLib graph:
from graphrag_toolkit_contrib.lexical_graph.storage.graph.sparql.neptune_iam import ( neptune_iam_graph,)
graph = neptune_iam_graph( 'https://my-cluster.cluster-abcdefghijkl.eu-central-1.neptune.amazonaws.com:8182', region_name='eu-central-1',)try: rows = graph.query('SELECT * WHERE { ?s ?p ?o } LIMIT 10')finally: graph.close()Namespaces and tenants
Section titled “Namespaces and tenants”The default schema namespace is
https://awslabs.github.io/graphrag-toolkit/lexical#; the default instance
namespace is https://awslabs.github.io/graphrag-toolkit/lexical/.
Customize them only when creating a new dataset:
graph_store = GraphStoreFactory.for_graph_store( 'https://rdf.example.com/query', graph_store_type='sparql', update_endpoint='https://rdf.example.com/update', lexical_prefix='gt', lexical_schema_namespace='https://example.com/graph/schema#', lexical_instance_namespace='https://example.com/graph/data/',)Every tenant, including the default tenant, uses a deterministic named graph.
Writes target that graph explicitly, and reads select it with the standard
SPARQL Protocol default-graph-uri parameter.
RDF model
Section titled “RDF model”Sources, chunks, topics, statements, facts, and entities retain their existing
lexical-graph identities. A node becomes a deterministic IRI with an RDF class
and lg:id; node properties become literal-valued predicates. Simple edges
become RDF predicates.
Extracted facts record their subject, predicate, and object directly:
<fact/f1> a lg:Fact ; lg:subject <entity/amazon> ; lg:predicate <relation/produces> ; lg:object <entity/ec2> ; lg:supports <statement/s1> ; lg:value "Amazon PRODUCES EC2" .
<relation/produces> a lg:Relation ; lg:value "PRODUCES" .This is the toolkit’s fact model, with the fact resource carrying its subject, predicate, object, and supporting statement.
Source and chunk metadata keys are percent-encoded in property IRIs and decoded
on retrieval. A metadata key named id uses lg:metadata/id, separate from
lg:id. Source hashes and tenant-scoped source-ID width records preserve the
core ingestion guards.
Indexing and retrieval
Section titled “Indexing and retrieval”The typed operations cover graph construction and the traversal-based
ChunkBasedSearch, EntityNetworkSearch, and EntityBasedSearch retrievers.
Use the RDF graph store together with a vector store and configured extraction,
embedding, and response models.
The standard retrieval metadata postprocessor can filter returned source metadata; vector-side filtering uses the configured vector backend.