Analyzing Neo4j

Neo4j Analysis Skill

Analyze and optimize Neo4j graph databases with safe, read-only operations.

MANDATORY: Two-Phase Execution

You MUST follow this two-phase pattern. Skipping Phase 1 causes hallucinated label/relationship names.

Phase 1: Discovery (ALWAYS run first)

#!/bin/bash

# 1. Database overview
cypher-shell -u "$NEO4J_USER" -p "$NEO4J_PASSWORD" -a "$NEO4J_URI" "CALL db.labels() YIELD label RETURN label;"

# 2. Relationship types
cypher-shell -u "$NEO4J_USER" -p "$NEO4J_PASSWORD" -a "$NEO4J_URI" "CALL db.relationshipTypes() YIELD relationshipType RETURN relationshipType;"

# 3. Property keys
cypher-shell -u "$NEO4J_USER" -p "$NEO4J_PASSWORD" -a "$NEO4J_URI" "CALL db.propertyKeys() YIELD propertyKey RETURN propertyKey;"

# 4. Schema overview
cypher-shell -u "$NEO4J_USER" -p "$NEO4J_PASSWORD" -a "$NEO4J_URI" "CALL db.schema.visualization();"

# 5. Sample nodes per label
cypher-shell -u "$NEO4J_USER" -p "$NEO4J_PASSWORD" -a "$NEO4J_URI" "MATCH (n:MyLabel) RETURN n LIMIT 3;"

Phase 1 outputs:

• Node labels and relationship types
• Property keys in use
• Sample nodes to understand actual properties

Phase 2: Analysis (only after Phase 1)

Only reference labels, relationship types, and properties confirmed in Phase 1.

Shell Script Patterns

Helper Function

#!/bin/bash

# Core Cypher runner — always use this
neo4j_query() {
    local query="$1"
    cypher-shell -u "${NEO4J_USER:-neo4j}" -p "${NEO4J_PASSWORD}" \
        -a "${NEO4J_URI:-bolt://localhost:7687}" \
        --format plain "$query"
}

# HTTP API alternative
neo4j_http() {
    local query="$1"
    curl -s -u "${NEO4J_USER:-neo4j}:${NEO4J_PASSWORD}" \
        -H "Content-Type: application/json" \
        -d "{\"statements\":[{\"statement\":\"$query\"}]}" \
        "http://${NEO4J_HOST:-localhost}:7474/db/neo4j/tx/commit"
}

Anti-Hallucination Rules

• NEVER reference a node label without confirming via db.labels()
• NEVER reference a relationship type without confirming via db.relationshipTypes()
• NEVER reference property names without seeing them in db.propertyKeys() or sample nodes
• NEVER assume index names — always check with SHOW INDEXES
• NEVER guess constraint names — always verify with SHOW CONSTRAINTS

Safety Rules

• READ-ONLY ONLY: Use only MATCH, RETURN, CALL (read procedures), EXPLAIN, PROFILE
• FORBIDDEN: CREATE, DELETE, DETACH DELETE, MERGE, SET, REMOVE, DROP without explicit user request
• ALWAYS add LIMIT to MATCH queries — graphs can have millions of nodes
• Use EXPLAIN before running expensive traversals
• Use PROFILE sparingly — it executes the query and captures runtime stats

Common Operations

Graph Overview

#!/bin/bash
echo "=== Neo4j Version ==="
neo4j_query "CALL dbms.components() YIELD name, versions RETURN name, versions;"

echo ""
echo "=== Node Counts by Label ==="
neo4j_query "CALL db.labels() YIELD label CALL { WITH label CALL db.stats.retrieve('GRAPH COUNTS') YIELD nodeCount RETURN nodeCount } RETURN label, nodeCount;" 2>/dev/null || \
neo4j_query "MATCH (n) RETURN labels(n)[0] AS label, count(*) AS count ORDER BY count DESC;"

echo ""
echo "=== Relationship Counts ==="
neo4j_query "MATCH ()-[r]->() RETURN type(r) AS type, count(*) AS count ORDER BY count DESC;"

echo ""
echo "=== Database Size ==="
neo4j_query "CALL dbms.queryJmx('org.neo4j:instance=kernel#0,name=Store sizes') YIELD attributes RETURN attributes;" 2>/dev/null || echo "JMX not available"

Index Management

#!/bin/bash
echo "=== Existing Indexes ==="
neo4j_query "SHOW INDEXES YIELD name, type, state, populationPercent, labelsOrTypes, properties RETURN name, type, state, populationPercent, labelsOrTypes, properties ORDER BY labelsOrTypes;"

echo ""
echo "=== Constraints ==="
neo4j_query "SHOW CONSTRAINTS YIELD name, type, labelsOrTypes, properties RETURN name, type, labelsOrTypes, properties;"

echo ""
echo "=== Index Usage (via query plan) ==="
neo4j_query "EXPLAIN MATCH (n:MyLabel {myProp: 'value'}) RETURN n;"

Query Performance Analysis

#!/bin/bash
echo "=== Active Queries ==="
neo4j_query "CALL dbms.listQueries() YIELD queryId, username, query, elapsedTimeMillis, status RETURN queryId, username, substring(query, 0, 80) AS query_preview, elapsedTimeMillis, status ORDER BY elapsedTimeMillis DESC;" 2>/dev/null || echo "listQueries not available in this edition"

echo ""
echo "=== Query Plan Analysis ==="
# Replace with actual query from Phase 1 discovery
neo4j_query "PROFILE MATCH (n:MyLabel)-[:MY_REL]->(m) RETURN n, m LIMIT 100;"

echo ""
echo "=== Transaction Status ==="
neo4j_query "CALL dbms.listTransactions() YIELD transactionId, username, currentQueryId, elapsedTimeMillis, status RETURN transactionId, username, currentQueryId, elapsedTimeMillis, status;" 2>/dev/null

APOC Utilities

#!/bin/bash
echo "=== APOC Version ==="
neo4j_query "RETURN apoc.version();" 2>/dev/null || echo "APOC not installed"

echo ""
echo "=== Graph Stats via APOC ==="
neo4j_query "CALL apoc.meta.stats() YIELD labelCount, relTypeCount, nodeCount, relCount, propertyKeyCount RETURN labelCount, relTypeCount, nodeCount, relCount, propertyKeyCount;" 2>/dev/null

echo ""
echo "=== Schema via APOC ==="
neo4j_query "CALL apoc.meta.schema() YIELD value RETURN value;" 2>/dev/null

Output Format

Present results as a structured report:

Analyzing Neo4J Report
══════════════════════
Resources discovered: [count]

Resource       Status    Key Metric    Issues
──────────────────────────────────────────────
[name]         [ok/warn] [value]       [findings]

Summary: [total] resources | [ok] healthy | [warn] warnings | [crit] critical
Action Items: [list of prioritized findings]

Target ≤50 lines of output. Use tables for multi-resource comparisons.

Counter-Rationalizations

Common Pitfalls

• Unbounded traversals: MATCH (a)-[*]->(b) can explode on large graphs — always bound depth with [*1..3]
• Cartesian products: Multiple disconnected MATCH patterns create cartesian products — always connect patterns
• Missing indexes: Label+property scans without indexes cause full scans — check SHOW INDEXES
• Eager operations: Some operations (e.g., COLLECT before DELETE) load everything into memory — use EXPLAIN to check for Eager operators
• PROFILE vs EXPLAIN: PROFILE executes the query; EXPLAIN only plans it — use EXPLAIN first on production
• Property existence: Properties are optional in Neo4j — always handle NULL/missing properties