Skip to content

cloudthinker-ai/CloudSkills / skills/connections/analyzing-neo4j

analyzing-neo4j

Verified

Use when working with Neo4J — neo4j graph database analysis, index management, Cypher query optimization, APOC utilities, and cluster health monitoring.

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

ShortcutCounterWhy
"I'll skip discovery and check known resources"Always run Phase 1 discovery firstResource names change, new resources appear — assumed names cause errors
"The user only asked for a quick check"Follow the full discovery → analysis flowQuick checks miss critical issues; structured analysis catches silent failures
"Default configuration is probably fine"Audit configuration explicitlyDefaults often leave logging, security, and optimization features disabled
"Metrics aren't needed for this"Always check relevant metrics when availableAPI/CLI responses show current state; metrics reveal trends and intermittent issues
"I don't have access to that"Try the command and report the actual errorAssumed permission failures prevent useful investigation; actual errors are informative

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
deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall