cypher

目的

このスキルを使うと、OpenClaw で Cypher クエリを実行してグラフデータベース（特に Neo4j）を操作でき、ノードのマッチング、リレーションシップの作成、グラフのトラバーサルなどを行えます。

使用する場面

ソーシャルネットワークやレコメンデーションシステムなど、グラフ構造のデータを扱う際にこのスキルを使用してください。たとえば、ユーザーグラフのリレーションシップをクエリしたり、ナレッジベースに対して BFS を実行したりできます。リレーショナルデータには使用せず、代わりに SQL ベースのスキルを選択してください。

主な機能

• MATCH、CREATE、MERGE、DELETE などの Cypher の主要な句を実行します。
• トラバーサル用のパス式（最短パスなど）を扱います。
• shortestPath() などのアルゴリズムを使った BFS／DFS トラバーサルをサポートします。
• グラフデータに対して集計（COUNT、SUM など）を実行します。
• PageRank やコミュニティ検出などのグラフアルゴリズムを実行します。
• Neo4j と連携してノードやリレーションシップをクエリします。

使用パターン

Cypher クエリを実行するには、cypher-shell または Python の neo4j ドライバーを使用します。Neo4j Community Edition は、デフォルトでは認証なしで bolt://localhost:7687 で動作します。

例 1：すべてのノードをマッチさせ、ラベルを返します。

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

CLI から実行する場合：cypher-shell -a bolt://localhost:7687 --format plain "MATCH (n) RETURN labels(n), count(n) LIMIT 10"

例 2：2 つのノード間にリレーションシップを作成します。

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

主なコマンド／API

対話形式のクエリには cypher-shell を、プログラムからのアクセスには Python の neo4j ドライバーを使用します。

# 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()

設定：bolt://localhost:7687 で接続し、認証は不要です。アップサート操作には MERGE を使用します：MERGE (n:Person {name: 'Alice'})。

統合に関する注意

このスキルを OpenClaw に統合するには、Neo4j が実行中であることを確認してください（macOS では brew services start neo4j、Linux では systemctl start neo4j）。接続先はデフォルトで bolt://localhost:7687 で、認証は不要です。必要に応じて、NEO4J_URI 環境変数で上書きしてください。

エラー処理

よくあるエラーには、構文の問題（セミコロンの不足など）や接続失敗があります。クエリを事前に検証して、"Neo4jError: Invalid input" が発生しないようにしてください。接続に失敗する場合は、Neo4j が実行中であることを確認してください。コード内では、クエリを try-catch ブロックで囲みます。

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()

ノードが見つからないなど、グラフ固有のエラーには OPTIONAL MATCH を使用してください。デバッグできるよう、エラーの詳細を常にログに記録してください。

グラフのリレーションシップ

• ノード：Person、Movie、Organization。
• リレーションシップ：(:Person)-[:KNOWS]-(:Person)、(:Person)-[:ACTED_IN]-(:Movie)、(:Organization)-[:EMPLOYS]-(:Person)。
• パスの例：shortestPath((:Person {name: 'Alice'})-[:KNOWS*]-(:Person {name: 'Bob'})) で最短パスを取得します。
• 集計：リレーションシップに対して使用します。例：RETURN COUNT((:Person)-[:KNOWS]-()) AS connections。