alphaonedev/cypher

Purpose

This skill allows OpenClaw to execute Cypher queries for interacting with graph databases, specifically Neo4j, enabling operations like node matching, relationship creation, and graph traversals.

When to Use

Use this skill when working with graph-structured data, such as social networks or recommendation systems. For example, query relationships in a user graph or perform BFS on a knowledge base. Avoid it for relational data; opt for SQL-based skills instead.

Key Capabilities

• Execute core Cypher clauses: MATCH, CREATE, MERGE, DELETE.
• Handle path expressions for traversals (e.g., shortest paths).
• Support BFS/DFS traversals via algorithms like shortestPath().
• Perform aggregations (e.g., COUNT, SUM) on graph data.
• Run graph algorithms such as PageRank or community detection.
• Integrate with Neo4j for querying nodes and relationships.

Usage Patterns

To execute a Cypher query, use cypher-shell or the Python neo4j driver. Neo4j Community Edition runs on bolt://localhost:7687 with no authentication by default.

Example 1: Match all nodes and return their labels.

MATCH (n) RETURN labels(n), count(n) LIMIT 10;

Via CLI: cypher-shell -a bolt://localhost:7687 --format plain "MATCH (n) RETURN labels(n), count(n) LIMIT 10"

Example 2: Create a relationship between two nodes.

MATCH (a:Person {name: 'Alice'}), (b:Person {name: 'Bob'})
CREATE (a)-[:KNOWS]->(b);

Common Commands/API

Use cypher-shell for interactive queries or the Python neo4j driver for programmatic access:

# CLI query
cypher-shell -a bolt://localhost:7687 --format plain "MATCH (n:Skill) RETURN n.name LIMIT 10"

# Python neo4j driver
from neo4j import GraphDatabase

driver = GraphDatabase.driver("bolt://localhost:7687")
with driver.session() as session:
    result = session.run("MATCH (n:Skill) RETURN n.name LIMIT 10")
    for record in result:
        print(record["n.name"])
driver.close()

Config: Connection via bolt://localhost:7687, no auth. Use MERGE for upsert operations: MERGE (n:Person {name: 'Alice'}).

Integration Notes

Integrate this skill in OpenClaw by ensuring Neo4j is running (brew services start neo4j on macOS, systemctl start neo4j on Linux). Connection defaults to bolt://localhost:7687 with no authentication. Override via NEO4J_URI environment variable if needed.

Error Handling

Common errors include syntax issues (e.g., missing semicolons) or connection failures. Check for "Neo4jError: Invalid input" by validating queries first. If connection fails, verify Neo4j is running. In code, wrap queries in try-catch blocks:

from neo4j import GraphDatabase
from neo4j.exceptions import ServiceUnavailable, CypherSyntaxError

driver = GraphDatabase.driver("bolt://localhost:7687")
try:
    with driver.session() as session:
        result = session.run("MATCH (n) RETURN n LIMIT 5")
        records = list(result)
except ServiceUnavailable:
    print("Error: Neo4j is not running. Start with: brew services start neo4j")
except CypherSyntaxError as e:
    print(f"Cypher syntax error: {e}")
finally:
    driver.close()

For graph-specific errors like missing nodes, use OPTIONAL MATCH. Always log errors with details for debugging.

Graph Relationships

• Nodes: Person, Movie, Organization.
• Relationships: (:Person)-[:KNOWS]-(:Person), (:Person)-[:ACTED_IN]-(:Movie), (:Organization)-[:EMPLOYS]-(:Person).
• Path examples: Shortest path via shortestPath((:Person {name: 'Alice'})-[:KNOWS*]-(:Person {name: 'Bob'})).
• Aggregations: Use on relationships, e.g., RETURN COUNT((:Person)-[:KNOWS]-()) AS connections.