# How to Configure Polyglot Graph Storage for RDF and LPG Databases in Semantica

> Configure polyglot graph storage for RDF and LPG databases in Semantica. Learn to set up your YAML config file and connect backends for flexible graph data management.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: how-to-guide
- Published: 2026-08-14

---

**To configure polyglot graph storage in Semantica, create a YAML configuration file at `~/.semantica/config.yaml` with `storage.rdf` and `storage.lpg` sections specifying your backends and connection options, then load it via `GraphStoreRegistry.from_config()`.**

Semantica's architecture treats graph storage as a *polyglot* component—you can plug in any **RDF triple store** (Oxigraph, Blazegraph, Apache Jena, Eclipse RDF4J) and any **Labeled Property Graph database** (Neo4j, FalkorDB, Apache AGE, AWS Neptune) without changing your application code. This guide walks through the complete configuration process based on the semantica-agi/semantica source code.

## How Polyglot Graph Storage Configuration Works

Semantica decouples storage backends from application logic through three core components: a YAML configuration file, a registry-based lookup system, and a unified `GraphStore` abstraction.

### The config.yaml File Structure

The configuration file contains a top-level `storage` section with two keys: `rdf` and `lpg`. Each declares a `backend` name and optional `options` for driver-specific settings.

```yaml

# ~/.semantica/config.yaml

storage:
  rdf:
    backend: oxigraph
    options:
      path: ./data/oxigraph.db
  lpg:
    backend: neo4j
    options:
      uri: bolt://localhost:7687
      auth:
        username: neo4j
        password: secret

```

The `storage` section supports these **RDF backends**: `oxigraph`, `blazegraph`, `jena`, `rdf4j`. For **LPG backends**: `neo4j`, `falkordb`, `age`, `neptune`.

*Source:* The README explains this polyglot design in the storage section【/cache/repos/github.com/semantica-agi/semantica/main/README.md#L78-L80】.

### The GraphStoreRegistry Lookup Mechanism

`GraphStoreRegistry` in [`semantica/graph_store/registry.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/graph_store/registry.py) maintains a mapping from backend identifiers to concrete store classes (`OxigraphStore`, `BlazegraphStore`, `Neo4jStore`, etc.). When `GraphStore.from_config()` is called, the registry:

1. Reads the `backend` value from the YAML
2. Loads the appropriate class
3. Passes the `options` dict to its constructor

*Key file:* [`semantica/graph_store/registry.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/graph_store/registry.py) implements this lookup logic【/cache/repos/github.com/semantica-agi/semantica/main/semantica/graph_store/registry.py】.

### The Unified GraphStore API

The resulting `GraphStore` object implements a single interface (`add_node`, `add_edge`, `execute_query`, etc.) defined in [`semantica/graph_store/graph_store.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/graph_store/graph_store.py). Internally, it delegates calls to the RDF or LPG driver, translating between **SPARQL** and **Cypher** as needed【/cache/repos/github.com/semantica-agi/semantica/main/semantica/graph_store/graph_store.py】.

## Complete Configuration Examples

### Minimal Configuration: Oxigraph + Neo4j

This configuration runs an embedded Oxigraph store for RDF data and connects to a local Neo4j instance for property graphs:

```yaml

# ~/.semantica/config.yaml

storage:
  rdf:
    backend: oxigraph
    options:
      path: ./oxigraph.db
  lpg:
    backend: neo4j
    options:
      uri: bolt://localhost:7687
      auth:
        username: neo4j
        password: ********

```

### Loading the Store in Python

```python
from semantica.context import ContextGraph
from semantica.graph_store.registry import GraphStoreRegistry

# Automatically reads ~/.semantica/config.yaml

graph_store = GraphStoreRegistry.from_config()

# Build a ContextGraph that uses the polyglot store

ctx = ContextGraph(storage=graph_store, advanced_analytics=True)

# Add an RDF triple

ctx.storage.rdf_store.add_triple(
    ("http://example.org/Alice", "http://xmlns.com/foaf/0.1/knows", "http://example.org/Bob")
)

# Add an LPG edge

ctx.storage.lpg_store.add_edge(
    source="Alice", target="Bob", edge_type="knows", since="2024-01-01"
)

```

*Source:* Example usage appears in the quick-start snippet of the README【/cache/repos/github.com/semantica-agi/semantica/main/README.md#L9-L13】.

### Swapping Backends Without Code Changes

To migrate from embedded Oxigraph to remote Blazegraph, and from Neo4j to AWS Neptune, only update the YAML:

```yaml
storage:
  rdf:
    backend: blazegraph
    options:
      endpoint: http://blazegraph.example.com/sparql
  lpg:
    backend: neptune
    options:
      endpoint: https://neptune.amazonaws.com:8182
      auth:
        aws_region: us-east-1
        iam_role: arn:aws:iam::123456789012:role/NeptuneAccess

```

The same Python code (`GraphStoreRegistry.from_config()`) now instantiates `BlazegraphStore` and `AmazonNeptune` classes.

## Programmatic Configuration (No Config File)

For dynamic environments, build stores directly and pass them to `GraphStore`:

```python
from semantica.graph_store.graph_store import GraphStore
from semantica.graph_store.neo4j_store import Neo4jStore
from semantica.graph_store.oxigraph_store import OxigraphStore

# Create individual store instances

rdf = OxigraphStore(path="./myoxigraph")
lpg = Neo4jStore(uri="bolt://localhost:7687", auth=("neo4j", "s3cr3t"))

# Compose into unified GraphStore

store = GraphStore(rdf_store=rdf, lpg_store=lpg)

# Use with ContextGraph

ctx = ContextGraph(storage=store, advanced_analytics=True)

```

## Implementation Files Reference

| File | Purpose | Location |
|------|---------|----------|
| [`config.py`](https://github.com/semantica-agi/semantica/blob/main/config.py) | Parses and validates YAML configuration | [`semantica/graph_store/config.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/graph_store/config.py) |
| [`registry.py`](https://github.com/semantica-agi/semantica/blob/main/registry.py) | Maps identifiers to store classes | [`semantica/graph_store/registry.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/graph_store/registry.py) |
| [`graph_store.py`](https://github.com/semantica-agi/semantica/blob/main/graph_store.py) | Unified `GraphStore` abstraction | [`semantica/graph_store/graph_store.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/graph_store/graph_store.py) |
| [`oxigraph_store.py`](https://github.com/semantica-agi/semantica/blob/main/oxigraph_store.py) | Embedded Oxigraph RDF implementation | [`semantica/graph_store/oxigraph_store.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/graph_store/oxigraph_store.py) |
| [`blazegraph_store.py`](https://github.com/semantica-agi/semantica/blob/main/blazegraph_store.py) | Remote Blazegraph SPARQL endpoint | [`semantica/graph_store/blazegraph_store.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/graph_store/blazegraph_store.py) |
| [`neo4j_store.py`](https://github.com/semantica-agi/semantica/blob/main/neo4j_store.py) | Neo4j Cypher driver | [`semantica/graph_store/neo4j_store.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/graph_store/neo4j_store.py) |
| [`falkordb_store.py`](https://github.com/semantica-agi/semantica/blob/main/falkordb_store.py) | FalkorDB RedisGraph driver | [`semantica/graph_store/falkordb_store.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/graph_store/falkordb_store.py) |
| [`age_store.py`](https://github.com/semantica-agi/semantica/blob/main/age_store.py) | Apache AGE PostgreSQL driver | [`semantica/graph_store/age_store.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/graph_store/age_store.py) |
| [`amazon_neptune.py`](https://github.com/semantica-agi/semantica/blob/main/amazon_neptune.py) | AWS Neptune Gremlin/Cypher driver | [`semantica/graph_store/amazon_neptune.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/graph_store/amazon_neptune.py) |

## Summary

- **Polyglot graph storage configuration** in Semantica uses a single YAML file to declare both RDF and LPG backends
- **`GraphStoreRegistry.from_config()`** reads `~/.semantica/config.yaml` and instantiates the correct drivers
- **Backend swaps require zero code changes**—only update the `backend` and `options` in your configuration
- **Unified API** through `GraphStore` abstracts SPARQL/Cypher differences
- **Eight supported backends** cover local embedded stores to managed cloud services

## Frequently Asked Questions

### What file format does Semantica use for storage configuration?

Semantica uses **YAML** for storage configuration. The default location is `~/.semantica/config.yaml`, though you can specify alternate paths when calling registry methods directly.

### Can I use different RDF and LPG backends in the same application?

Yes. Semantica's polyglot design intentionally supports mixing backends—you can pair any supported RDF store with any supported LPG database. The `GraphStore` abstraction maintains separate `rdf_store` and `lpg_store` attributes that operate independently.

### How do I migrate from local development to production storage?

Update only your [`config.yaml`](https://github.com/semantica-agi/semantica/blob/main/config.yaml) file. Change `backend: oxigraph` to `backend: blazegraph` or `backend: neptune`, then adjust the `options` section with production endpoints and credentials. Your Python code calling `GraphStoreRegistry.from_config()` remains unchanged.

### Is authentication supported for remote graph databases?

Yes. The `options` section accepts backend-specific authentication. For Neo4j, use `auth: {username: ..., password: ...}`. For AWS Neptune, use `auth: {aws_region: ..., iam_role: ...}`. Each driver implementation in `semantica/graph_store/` validates and applies these credentials appropriately.