Graph Store¶

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

🎯 Overview¶

⚙️ Algorithms Used¶

Query Execution¶

The module provides efficient query execution:

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

Graph Analytics¶

Built-in graph analytics algorithms include:

• 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¶

Efficient bulk loading capabilities:

• 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¶

Core Classes¶

GraphStore¶

The main facade for graph operations.

Methods:

Properties: - nodes - Access to NodeManager - relationships - Access to RelationshipManager - query_engine - Access to QueryEngine - analytics - Access to GraphAnalytics

Example:

from semantica.graph_store import GraphStore

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

GraphManager¶

Manager for graph store operations. Provides access to node, relationship, query, and analytics managers.

Methods: - get_stats() - Get graph statistics - create_index(label, property_name, index_type, **options) - Create an index

NodeManager¶

Manager for node CRUD operations.

Methods: - create(labels, properties, **options) - Create a node - create_batch(nodes, **options) - Create multiple nodes - get(node_id, labels, properties, limit, **options) - Get node(s) - update(node_id, properties, merge, **options) - Update a node - delete(node_id, detach, **options) - Delete a node

RelationshipManager¶

Manager for relationship CRUD operations.

Methods: - create(start_node_id, end_node_id, rel_type, properties, **options) - Create a relationship - get(node_id, rel_type, direction, limit, **options) - Get relationships - delete(rel_id, **options) - Delete a relationship

QueryEngine¶

Engine for query execution and optimization.

Methods: - execute(query, parameters, use_cache, **options) - Execute a Cypher/OpenCypher query - clear_cache() - Clear query cache - enable_cache() - Enable query caching - disable_cache() - Disable query caching

GraphAnalytics¶

Graph analytics and algorithms.

Methods: - shortest_path(start_node_id, end_node_id, rel_type, max_depth, **options) - Find shortest path - get_neighbors(node_id, rel_type, direction, depth, **options) - Get neighboring nodes - degree_centrality(labels, rel_type, direction, **options) - Calculate degree centrality - connected_components(labels, **options) - Find connected components

Store Backends¶

Neo4jStore¶

Enterprise-grade Neo4j backend store.

Features: - Bolt protocol support - Cluster awareness - APOC procedure integration - Multi-database support - Transaction support

Related Classes: - Neo4jDriver - Neo4j driver wrapper - Neo4jSession - Session management wrapper - Neo4jTransaction - Transaction wrapper

FalkorDBStore¶

High-performance Redis-based FalkorDB backend store.

Features: - Sparse matrix representation - Ultra-low latency - Redis protocol - Multi-graph support - Linear algebra based querying

Related Classes: - FalkorDBClient - Client wrapper - FalkorDBGraph - Graph wrapper with operations - FalkorDBQuery - Query execution wrapper

Special Methods: - select_graph(graph_name) - Select or create a graph - list_graphs() - List all available graphs - delete_graph(graph_name) - Delete a graph

Configuration and Registry Classes¶

GraphStoreConfig¶

Configuration manager for graph store module. Supports environment variables, config files (YAML, JSON, TOML), and programmatic configuration.

Methods: - get(key, default) - Get configuration value - set(key, value) - Set configuration value - update(config) - Update configuration with dictionary - get_method_config(method_name) - Get method-specific configuration - set_method_config(method_name, config) - Set method-specific configuration - get_all() - Get all configuration - get_neo4j_config() - Get Neo4j-specific configuration - get_falkordb_config() - Get FalkorDB-specific configuration - reset() - Reset configuration to defaults

Global Instance: - graph_store_config - Global configuration instance

MethodRegistry¶

Registry for custom graph store methods, enabling extensibility.

Methods: - register(task, method_name, method_func, **metadata) - Register a method - unregister(task, method_name) - Unregister a method - get(task, method_name) - Get a registered method - list_all(task) - List all registered methods - has(task, method_name) - Check if a method is registered - get_metadata(task, method_name) - Get metadata for a registered method

Supported Task Types: - node - Node CRUD methods - relationship - Relationship CRUD methods - query - Query execution methods - traversal - Graph traversal methods - analytics - Graph analytics methods - bulk - Bulk operation methods

Global Instance: - method_registry - Global method registry instance

Convenience Functions¶

The module provides convenience functions for common graph operations. These functions use a global GraphStore instance and support method registration for extensibility.

Node Operations¶

Relationship Operations¶

Query Operations¶

Analytics Operations¶

Utility Functions¶

Example:

from semantica.graph_store import (
    create_node,
    create_nodes,
    create_relationship,
    execute_query,
    shortest_path,
    get_neighbors,
    run_analytics
)

# Quick node creation
alice = create_node(["Person"], {"name": "Alice", "age": 30})
bob = create_node(["Person"], {"name": "Bob", "age": 25})

# Batch node creation
people = create_nodes([
    {"labels": ["Person"], "properties": {"name": "Charlie"}},
    {"labels": ["Person"], "properties": {"name": "Diana"}}
])

# Create relationship
rel = create_relationship(
    start_id=alice["id"],
    end_id=bob["id"],
    rel_type="KNOWS",
    properties={"since": 2020}
)

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

# Find shortest path
path = shortest_path(
    start_node_id=alice["id"],
    end_node_id=bob["id"],
    max_depth=5
)

# Get neighbors
neighbors = get_neighbors(node_id=alice["id"], depth=2)

# Run analytics
centrality = run_analytics(
    algorithm="degree_centrality",
    labels=["Person"]
)

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

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, parameters={"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
• Triplet Store Module - RDF-based alternative
• Visualization Module - Visualizing query results

Cookbook¶

Interactive tutorials to learn graph storage:

• Graph Store: Persist knowledge graphs in Neo4j or FalkorDB
• Topics: Neo4j, FalkorDB, Cypher, persistence, graph databases
• Difficulty: Intermediate
• Use Cases: Persistent storage, production deployments, graph database integration