Skip to content

Add graph storage backend compatibility matrix #899

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
yulinlina wants to merge 1 commit into
base: main
Choose a base branch
from
+128 −0
Open

Add graph storage backend compatibility matrix #899

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
128 changes: 128 additions & 0 deletions docs/storage-backends.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,128 @@
# Graph storage backends and feature matrix

Semantica separates graph modeling from physical storage. LPG backends are accessed through `graph_store` adapters; RDF backends are accessed through `triplet_store` adapters.

This page is intentionally conservative: it distinguishes between an adapter existing, a feature being generally available with that model, and a backend needing user-supplied wiring.

## Status labels

- `built-in`: adapter implementation exists in Semantica core.
- `tested`: covered by automated integration fixtures or tests.
- `example-only`: usable example exists, but support is not asserted by integration tests.
- `interface/BYO`: interface or integration point exists; bring your own backend wiring.

## Adapter inventory

| Backend | Model | Adapter | Status | Reference |
| --- | --- | --- | --- | --- |
| Neo4j | LPG | `semantica.graph_store.Neo4jGraphStore` | built-in | `cookbook/introduction/09_Graph_Store.ipynb` |
| Amazon Neptune | LPG | `semantica.graph_store.NeptuneGraphStore` | built-in | `cookbook/introduction/21_Amazon_Neptune_Store.ipynb` |
| Apache AGE | LPG | `semantica.graph_store.AgeGraphStore` | built-in | `docs/graph_stores/apache_age.md` |
Comment on lines +18 to +20

@qodo-free-for-open-source-projects qodo-free-for-open-source-projects Bot Aug 10, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Action required

1. Nonexistent graph store adapters 🐞 Bug ≡ Correctness

docs/storage-backends.md lists and imports Neo4jGraphStore/NeptuneGraphStore/AgeGraphStore, but
these symbols are not defined/exported by semantica.graph_store, so the examples will raise
ImportError. The built-in LPG APIs are GraphStore (facade) and
Neo4jStore/AmazonNeptuneStore/ApacheAgeStore with different parameter names.
Agent Prompt 
### Issue description
`docs/storage-backends.md` references non-existent LPG adapter classes (`Neo4jGraphStore`, `NeptuneGraphStore`, `AgeGraphStore`) and shows constructor kwargs that do not match the actual Semantica APIs.

### Issue Context
Semantica’s LPG entry points are exported from `semantica.graph_store` as `GraphStore` (recommended facade) and the concrete backends `Neo4jStore`, `AmazonNeptuneStore`, and `ApacheAgeStore`.

### Fix Focus Areas
- docs/storage-backends.md[16-83]

### What to change
- Update the adapter inventory table to reference `semantica.graph_store.Neo4jStore`, `semantica.graph_store.AmazonNeptuneStore`, and `semantica.graph_store.ApacheAgeStore` **or** consistently document the facade usage (`GraphStore(backend="neo4j"|"neptune"|"age", ...)`).
- Update the “Minimal connection examples” accordingly:
  - Neo4j: use `GraphStore(... user=..., password=...)` or `Neo4jStore(uri=..., user=..., password=...)` (note `user`, not `username`).
  - Neptune: use `GraphStore(... endpoint=..., port=..., region=..., iam_auth=...)` or `AmazonNeptuneStore(endpoint=..., ...)` (note `endpoint`, not `host`).
  - AGE: use `GraphStore(backend="age", connection_string=..., graph_name=...)` or `ApacheAgeStore(connection_string=..., graph_name=...)` (note `connection_string/graph_name`, not `dsn/graph`).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

| RDF4J | RDF | `semantica.triplet_store.RDF4JStore` | built-in | `cookbook/introduction/20_Triplet_Store.ipynb` |
| Apache Jena | RDF | `semantica.triplet_store.JenaStore` | built-in | `cookbook/introduction/20_Triplet_Store.ipynb` |
| Blazegraph | RDF | `semantica.triplet_store.BlazegraphStore` | built-in | `cookbook/introduction/20_Triplet_Store.ipynb` |
| Anzo | RDF | `semantica.triplet_store.AnzoStore` | interface/BYO | `cookbook/introduction/20_Triplet_Store.ipynb` |

@qodo-free-for-open-source-projects qodo-free-for-open-source-projects Bot Aug 10, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remediation recommended

3. Anzo adapter misclassified 🐞 Bug ≡ Correctness

The adapter inventory marks Anzo as interface/BYO, but Semantica includes and exports a concrete
AnzoStore implementation, so users may incorrectly think no built-in adapter exists. This
contradicts the doc’s own definition of built-in (“adapter implementation exists in Semantica
core”).
Agent Prompt 
### Issue description
The Anzo row is labeled `interface/BYO`, but Semantica ships an `AnzoStore` backend in core.

### Issue Context
The doc defines `built-in` as “adapter implementation exists in Semantica core,” which matches `AnzoStore` being implemented and exported.

### Fix Focus Areas
- docs/storage-backends.md[14-25]

### What to change
- Change the Anzo adapter inventory status from `interface/BYO` to `built-in` (and optionally add a separate note in “Known limitations” if Anzo deployments require environment-specific validation).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Comment on lines +16 to +24

## Feature matrix

`Yes` means the capability is expected to work with the adapter and graph model. `Partial` means the capability works with model-specific constraints. `BYO` means the user must supply or validate wiring for the backend.

| Backend | Model | Ingestion | Context graph construction | Reasoning/analytics | Provenance | Known limitations |
| --- | --- | --- | --- | --- | --- | --- |
| Neo4j | LPG | Yes | Yes | Yes | Partial | Provenance and context metadata are stored as node and edge properties; relationship properties and stable node identifiers are required. |
| Amazon Neptune | LPG | Yes | Yes | Partial | Partial | Use the property-graph endpoint; AWS auth, VPC, and endpoint configuration can affect local tests. Provenance depends on node/edge properties. |
| Apache AGE | LPG | Yes | Yes | Partial | Partial | Runs through PostgreSQL/AGE; Cypher compatibility and property handling can differ from standalone LPG engines. |
| RDF4J | RDF | Yes | Partial | Partial | Partial | Context separation relies on named graphs; triple-level provenance may require reification or graph-level metadata. |
| Apache Jena | RDF | Yes | Partial | Partial | Partial | Named graphs are needed for context separation; backend configuration and transaction behavior matter. |
| Blazegraph | RDF | Yes | Partial | Partial | Partial | Use quads/named graphs for context; IRI stability and graph naming matter for provenance. |
| Anzo | RDF | BYO | BYO | BYO | BYO | Anzo deployments are environment-specific; validate repository/graph naming, named-graph support, and provenance mapping. |

## RDF and LPG differences

- LPG backends store context and provenance as graph elements and properties. If a backend does not support relationship properties, some provenance patterns may be degraded.
- RDF backends rely on IRIs, named graphs, and optional reification. Context graphs and provenance are easiest to preserve when the store supports named graphs/quads.
- Ingestion works across both models, but the physical representation differs: LPG stores nodes/edges directly, while RDF stores subject-predicate-object statements.
- Reasoning and analytics should be validated against the adapter's query capabilities, especially for path traversal, property filters, and named-graph queries.

## Minimal connection examples

Prefer the referenced notebook cells for a working setup. The examples below show the intended adapter entrypoints, not a universal connection DSL.

### Neo4j

```python
from semantica.graph_store import Neo4jGraphStore

store = Neo4jGraphStore(
uri='bolt://localhost:7687',
username='neo4j',
password='password'
)
Comment on lines +56 to +60

@qodo-free-for-open-source-projects qodo-free-for-open-source-projects Bot Aug 10, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Informational

4. Password literal in example 🐞 Bug ⛨ Security

The Neo4j snippet uses a password-shaped literal (password='password'), which encourages
copy-pasting credentials into source even though the page later recommends env vars/secret storage.
Use an environment variable placeholder directly in the snippet to align with the guidance.
Agent Prompt 
### Issue description
The Neo4j example includes a literal password value.

### Issue Context
This page targets regulated/self-hosted deployments and already advises using environment variables or secret storage; the snippet should model that practice.

### Fix Focus Areas
- docs/storage-backends.md[51-61]

### What to change
- Replace the literal with an env-var based placeholder, e.g.:
  - `import os`
  - `password=os.environ.get("NEO4J_PASSWORD")`
  - (and optionally `username/user=os.environ.get("NEO4J_USER", "neo4j")`).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

```

### Amazon Neptune

```python
from semantica.graph_store import NeptuneGraphStore

store = NeptuneGraphStore(
host='your-neptune-endpoint',
port=8182
)
```
Comment on lines +51 to +72

### Apache AGE

```python
from semantica.graph_store import AgeGraphStore

store = AgeGraphStore(
dsn='postgresql://user:password@localhost:5432/semantica',
graph='semantica'
)
```

### RDF4J

```python
from semantica.triplet_store import RDF4JStore

store = RDF4JStore(
url='http://localhost:8080/rdf4j-server',
repository='semantica'
)
Comment on lines +90 to +93

@qodo-free-for-open-source-projects qodo-free-for-open-source-projects Bot Aug 10, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Action required

2. Broken triplet store examples 🐞 Bug ≡ Correctness

The RDF connection snippets use url=/repository= kwargs that don’t match the actual constructors
(e.g., BlazegraphStore requires endpoint, RDF4JStore uses endpoint + repository_id, and
AnzoStore requires dataset_uri), so the examples will error or not connect as shown. This makes
the “minimal connection examples” section unusable for RDF backends.
Agent Prompt 
### Issue description
`docs/storage-backends.md` shows RDF backend initialization with incorrect constructor keyword arguments (`url`, `repository`), which will raise `TypeError` (Blazegraph/Anzo) or fail to wire the connection settings (RDF4J/Jena).

### Issue Context
The backend classes in `semantica.triplet_store` use `endpoint` as the connection URL argument (and backend-specific config keys like `repository_id` or `dataset_uri`). The cookbook also demonstrates using the `TripletStore` facade with `backend=...` and `endpoint=...`.

### Fix Focus Areas
- docs/storage-backends.md[85-126]

### What to change (examples)
- RDF4J:
  - `RDF4JStore(endpoint="http://.../rdf4j-server", repository_id="semantica")`
- Jena:
  - `JenaStore(endpoint="http://localhost:3030/ds", dataset="semantica")` (or align with how Fuseki endpoints are represented in your docs)
- Blazegraph:
  - `BlazegraphStore(endpoint="http://localhost:9999/blazegraph", namespace="...")` (and omit `/sparql` if not required)
- Anzo:
  - `AnzoStore(endpoint="http://anzo-host:10000", dataset_uri="http://...Graphmart/..." )`
- Alternatively, show `TripletStore(backend="rdf4j"|"jena"|"blazegraph"|"anzo", endpoint=..., ...)` to keep docs consistent with the cookbook.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

```

### Apache Jena

```python
from semantica.triplet_store import JenaStore

store = JenaStore(
url='http://localhost:3030',
dataset='semantica'
)
```
Comment on lines +85 to +105

### Blazegraph

```python
from semantica.triplet_store import BlazegraphStore

store = BlazegraphStore(
url='http://localhost:9999/blazegraph/sparql'
)
```

### Anzo

```python
from semantica.triplet_store import AnzoStore

store = AnzoStore(
url='http://anzo-host:10000',
repository='semantica'
)
```

Replace hostnames, ports, repositories, graphs, and credentials with values from your environment. For regulated or self-hosted deployments, keep credentials in environment variables or secret storage rather than source code.
Loading