semantica/docs/reference/graph_store.md

Graph Store

Unified interface for Property Graph Databases (Neo4j, KuzuDB, FalkorDB).

---

🎯 Overview

• :material-database-search:{ .lg .middle } Multi-Backend

  ---

  Support for Neo4j (Enterprise), KuzuDB (Embedded), and FalkorDB (Redis-based)

• :material-code-braces:{ .lg .middle } Cypher Support

  ---

  Execute standard Cypher queries across all supported backends

• :material-graph:{ .lg .middle } Graph Algorithms

  ---

  Built-in support for PageRank, Community Detection, and Path Finding

• :material-flash:{ .lg .middle } Bulk Loading

  ---

  Optimized batch processing for high-speed data ingestion

• :material-lock:{ .lg .middle } Transactions

  ---

  ACID transaction support with rollback capabilities

• :material-chart-bell-curve:{ .lg .middle } Analytics

  ---

  Centrality, Similarity, and Connectivity analysis

!!! tip "When to Use" - Persistent Storage: Storing the Knowledge Graph for long-term access - Complex Queries: Running multi-hop pattern matching queries - Graph Analytics: Performing global analysis on the graph structure - Production: Scaling to billions of nodes/edges (Neo4j/FalkorDB)

---

⚙️ Algorithms Used

Query Execution

• Cypher Translation: Adapting queries for specific backend nuances (though most support OpenCypher).
• Query Optimization: Index utilization and execution plan analysis.

Graph Analytics

• PageRank: Measuring node importance based on incoming links.
• Louvain Modularity: Detecting communities by optimizing modularity.
• Shortest Path: Dijkstra/A* for finding optimal routes.
• Jaccard Similarity: Measuring node similarity based on shared neighbors.

Bulk Operations

• Chunking: Splitting large datasets into optimal batch sizes (e.g., 5000 records) to prevent memory overflow.
• Parallel Loading: Concurrent batch insertion (backend dependent).

---

Main Classes

GraphStore

The main facade for graph operations.

Methods:

Method	Description
execute_query(query, params)	Run Cypher query
create_node(labels, props)	Add node
create_relationship(start, end, type)	Add edge

Example:

from semantica.graph_store import GraphStore

store = GraphStore(backend="neo4j")
store.execute_query(
    "MATCH (n:Person {name: $name}) RETURN n",
    params={"name": "Alice"}
)

Neo4jAdapter

Enterprise-grade backend.

Features:

• Bolt protocol support
• Cluster awareness
• APOC procedure integration

KuzuAdapter

Embedded, in-process backend.

Features:

• No external server required
• Columnar storage for speed
• Zero-copy integration with Arrow

FalkorDBAdapter

High-performance Redis module.

Features:

• Sparse matrix representation
• Ultra-low latency
• Redis protocol

---

Convenience Functions

from semantica.graph_store import execute_query, create_node

# Quick query
results = execute_query("MATCH (n) RETURN count(n) as count")

# Quick node creation
create_node(["Person"], {"name": "Bob"})

---

Configuration

Environment Variables

export GRAPH_STORE_BACKEND=neo4j
export NEO4J_URI=bolt://localhost:7687
export NEO4J_USER=neo4j
export NEO4J_PASSWORD=password

YAML Configuration

graph_store:
  backend: neo4j
  
  neo4j:
    uri: bolt://localhost:7687
    pool_size: 50
    
  kuzu:
    path: ./data/kuzu_db
    buffer_pool_size: 1024 # MB

---

Integration Examples

Hybrid Search (Vector + Graph)

from semantica.graph_store import GraphStore
from semantica.vector_store import VectorStore

# 1. Find relevant nodes via Vector Search
vector_store = VectorStore()
results = vector_store.search(query_vec, k=5)
node_ids = [r.metadata['node_id'] for r in results]

# 2. Expand context via Graph Traversal
graph_store = GraphStore()
query = """
MATCH (n)-[r]-(m)
WHERE elementId(n) IN $ids
RETURN n, r, m
"""
subgraph = graph_store.execute_query(query, params={"ids": node_ids})

---

Best Practices

1. Use Parameters: Always use parameters in Cypher queries ($name) instead of string concatenation to prevent injection and improve caching.
2. Batch Writes: Use create_nodes (plural) for bulk insertion instead of loop-inserting.
3. Create Indexes: Ensure you have indexes on frequently queried properties (id, name).
4. Close Connections: Use context managers (with GraphStore() as store:) or call close() to release resources.

---

See Also

• Knowledge Graph Module - Logical layer above Graph Store
• Triple Store Module - RDF-based alternative
• Visualization Module - Visualizing query results