semantica/docs/reference/graph_store.md

title, description, icon

title	description	icon
Graph Store Module	Unified interface for Neo4j, FalkorDB, Apache AGE, and Amazon Neptune graph databases.	server

semantica.graph_store provides a single API for persisting and querying knowledge graphs in production graph databases. Swap backends with a one-line change — no application code changes needed.

What You Get

• GraphStore — unified interface across all backends
• Backends — Neo4j, FalkorDB, Apache AGE (PostgreSQL), Amazon Neptune, NetworkX (in-memory)
• Cypher queries — full Cypher support for Neo4j and FalkorDB
• Bulk operations — batched node and edge loading with configurable batch sizes
• Schema management — create indexes and uniqueness constraints
• Path traversal — find paths between nodes with hop limits and relationship type filters

Basic Usage

from semantica.graph_store import GraphStore

store = GraphStore(
    backend="neo4j",
    uri="bolt://localhost:7687",
    user="neo4j",
    password="password"
)

store.add_nodes(entities)
store.add_edges(relationships)

results = store.query("MATCH (n)-[r]->(m) RETURN n, r, m LIMIT 10")

Backends

store = GraphStore(
    backend="neo4j",
    uri="bolt://localhost:7687",
    user="neo4j",
    password="password",
    database="neo4j"    # optional — targets default database
)

Best for: production workloads, complex Cypher queries, Bloom visualization.

store = GraphStore(
    backend="falkordb",
    host="localhost",
    port=6379,
    graph_name="semantica"
)

Best for: ultra-low latency queries over Redis protocol, edge deployments.

store = GraphStore(
    backend="apache_age",
    connection_string="postgresql://user:pass@localhost/graphdb",
    graph_name="semantica"
)

Best for: teams already running PostgreSQL who want graph queries without a separate service. See the Apache AGE Guide for setup.

store = GraphStore(
    backend="neptune",
    endpoint="your-cluster.cluster-xxxx.us-east-1.neptune.amazonaws.com",
    port=8182,
    region="us-east-1"
)

Best for: managed AWS deployments needing both SPARQL and Gremlin support.

store = GraphStore(backend="networkx")

Best for: development, testing, and graphs that fit in RAM. Data is not persisted.

Querying

# Cypher query with parameters (Neo4j, FalkorDB)
results = store.query(
    "MATCH (p:Person)-[:WORKS_FOR]->(o:Organization) WHERE o.name = $org RETURN p",
    parameters={"org": "Apple Inc."}
)

# Path traversal between two nodes
paths = store.find_paths(
    start_node="steve_jobs",
    end_node="apple_inc",
    max_hops=3,
    relationship_types=["FOUNDED", "WORKED_AT"]
)

Graph Operations

# Add a single node
store.add_node(
    "apple_inc",
    node_type="Organization",
    properties={"founded": 1976, "hq": "Cupertino"}
)

# Add a directed relationship
store.add_edge(
    "steve_jobs", "apple_inc",
    "FOUNDED",
    properties={"year": 1976}
)

# Bulk operations — use for large datasets
store.add_nodes_bulk(entities,       batch_size=1000)
store.add_edges_bulk(relationships,  batch_size=1000)

# Delete
store.delete_node("node_id")
store.delete_edge("edge_id")

# Get neighbors
neighbors = store.get_neighbors(
    "apple_inc",
    relationship_type="HAS_EMPLOYEE",
    direction="in"    # "in" | "out" | "both"
)

Schema Management

Create indexes and constraints to improve query performance:

# Index for fast label lookups
store.create_index(label="Person", property="name")

# Uniqueness constraint
store.create_constraint(
    label="Organization",
    property="id",
    constraint_type="unique"
)

# Inspect current schema
schema = store.get_schema()
print(schema["labels"])
print(schema["indexes"])
print(schema["constraints"])

Backend Comparison

Backend	Query Language	Deployment	Best For
Neo4j	Cypher	Self-hosted / Aura	Production, complex traversals
FalkorDB	Cypher	Redis-based	Ultra-low latency, edge
Apache AGE	OpenCypher	PostgreSQL	Teams already on Postgres
Amazon Neptune	SPARQL / Gremlin	AWS managed	Cloud-native AWS deployments
NetworkX	Python API	In-memory	Development and testing

Build the graph before persisting it. PostgreSQL-based graph storage setup. RDF triple store for semantic web and SPARQL queries. Visualize graphs stored in any backend.