Neo4j Query Tuning Skill
Diagnose slow Cypher queries on production Neo4j with EXPLAIN/PROFILE and apply index, planner, and runtime fixes.
Overview
neo4j-query-tuning-skill is an agent skill for the Operate phase that diagnoses slow Neo4j Cypher queries from execution plans and prescribes targeted index, planner, and monitoring fixes.
Install
npx skills add https://github.com/neo4j-contrib/neo4j-skills --skill neo4j-query-tuning-skillWhat is this skill?
- EXPLAIN vs PROFILE with dbHits, rows, estimatedRows, and pageCacheHitRatio
- Full execution-plan operator reference with good/bad signals and fix strategies
- Cardinality estimation, stale stats, CartesianProduct, Eager, and over-traversal remedies
- Planner hints: USING INDEX, USING SCAN, USING JOIN ON; slotted, pipelined, parallel runtimes
- Query control via SHOW QUERIES, TERMINATE TRANSACTION; Aura and self-managed Neo4j 2025.x/2026.x
- Complete execution-plan operator reference table in bundled references
- Targets Neo4j 2025.x / 2026.x (self-managed or Aura)
Adoption & trust: 1 installs on skills.sh; 80 GitHub stars; 3/3 security scanners passed (skills.sh audits); trending (+100% hot-view momentum).
What problem does it solve?
Your graph queries are slow or costly in production and you cannot tell whether indexes, bad plans, or stale stats are to blame.
Who is it for?
Solo builders shipping features on Neo4j or Aura who need systematic Cypher tuning without a dedicated DBA.
Skip if: Teams with no running Neo4j instance or who only need one-off CRUD snippets without performance symptoms.
When should I use this skill?
Cypher latency, high dbHits, or bad plans appear on production or staging Neo4j workloads.
What do I get? / Deliverables
You get an interpreted execution plan, concrete remediation steps, and monitoring commands to validate improvements on Neo4j 2025.x/2026.x.
- Interpreted execution plan with operator-level diagnosis
- Targeted fix list (indexes, hints, replanning, runtime choice)
- Monitoring steps using SHOW QUERIES / stats APIs where available
Recommended Skills
Journey fit
Graph workloads stall in production; tuning and live query visibility are operate-time reliability work, not greenfield build. SHOW QUERIES, TRANSACTIONS, db.stats, and plan metrics are monitoring and observability workflows for running clusters.
How it compares
Use for plan-driven graph tuning instead of generic SQL-style query tips that ignore Cypher operators.
Common Questions / FAQ
Who is neo4j-query-tuning-skill for?
Indie developers and small teams running Neo4j-backed APIs or agents who own query latency and cluster health themselves.
When should I use neo4j-query-tuning-skill?
Use it in Operate when dashboards spike dbHits or p95 latency; in Ship perf passes before launch; and whenever PROFILE shows CartesianProduct, Eager, or full scans on hot paths.
Is neo4j-query-tuning-skill safe to install?
Review the Security Audits panel on this Prism page and limit agent permissions to the Neo4j endpoints and credentials you intend to expose.
SKILL.md
READMESKILL.md - Neo4j Query Tuning Skill
# neo4j-query-tuning-skill Diagnoses and fixes slow Neo4j Cypher queries by interpreting execution plans, identifying bad operators, and prescribing targeted fixes. ## What it covers - **EXPLAIN vs PROFILE** — when to use each; key metrics (dbHits, rows, estimatedRows, pageCacheHitRatio) - **Execution plan operators** — complete reference table with good/bad signals and fix strategies - **Cardinality estimation** — detecting stale stats, forcing replanning - **Common plan problems** — missing indexes, CartesianProduct, Eager, over-traversal - **Planner hints** — `USING INDEX`, `USING SCAN`, `USING JOIN ON` - **Runtime selection** — slotted, pipelined, parallel; when each is appropriate - **Query monitoring** — `SHOW QUERIES`, `SHOW TRANSACTIONS`, `TERMINATE TRANSACTION`, `db.stats.retrieve` ## Availability Works with any Neo4j 2025.x / 2026.x instance (self-managed or Aura). Some features require Enterprise edition: - `SHOW QUERIES` for other users' queries — Enterprise - `runtime=parallel` — Enterprise or Aura Pro 2025+ ## Install ```bash # Using Claude Code (agentskills.io): /skill install neo4j-query-tuning-skill ``` ## Reference Files - [`references/plan-operators.md`](references/plan-operators.md) — complete operator table with all variants - [`references/stats-and-monitoring.md`](references/stats-and-monitoring.md) — SHOW QUERIES, SHOW TRANSACTIONS, db.stats.*, index health, page cache # Cypher Execution Plan Operators — Full Reference Read plans bottom-up: leaf operators at bottom, `ProduceResults` at top. **Lazy vs Eager**: Most operators stream rows to parent as produced. Eager operators (marked ✗ below) must consume *all* input before emitting output — they materialise the full row set and can cause OOM on large inputs. --- ## Leaf Operators (data source) | Operator | Signal | Notes | |---|---|---| | `AllNodesScan` | ✗✗ Bad | Scans entire node store. No label → no label index. Add label + property index. | | `NodeByLabelScan` | ✗ Bad | Scans all nodes of a label. No property index. Add RANGE index. | | `NodeByIdSeek` | ✓ | Lookup by internal node ID. Fast but fragile — IDs are not stable. Use `elementId()`. | | `NodeIndexSeek` | ✓ | Equality/range predicate satisfied via RANGE or LOOKUP index. Optimal. | | `NodeUniqueIndexSeek` | ✓ | Unique constraint index hit. Optimal. | | `NodeIndexScan` | ~ | Full scan of an index (no predicate selectivity). Faster than label scan; still linear. | | `NodeIndexContainsScan` | ✓ | TEXT index CONTAINS/STARTS WITH. Requires TEXT index on property. | | `NodeIndexEndsWithScan` | ✓ | TEXT index ENDS WITH. Requires TEXT index on property. | | `RelationshipIndexSeek` | ✓ | Relationship property index hit. | | `RelationshipByIdSeek` | ✓ | Lookup by relationship ID. | | `DirectedRelationshipByIdSeek` | ✓ | Directed rel by ID. | | `UndirectedRelationshipByIdSeek` | ~ | Undirected rel scan — matches twice (both directions). | | `NodeByElementIdSeek` | ✓ | Lookup by `elementId()` string. Preferred over `id()`. | | `Argument` | — | Passes outer scope variables into subquery. | --- ## Traversal Operators | Operator | Signal | Notes | |---|---|---| | `Expand(All)` | ~ | Traverses all incoming/outgoing rels from a node. Normal. Limit fanout with WHERE/LIMIT. | | `Expand(Into)` | ~ | Finds rels between two already-matched nodes. Efficient for known endpoints. | | `OptionalExpand(All)` | ~ | OPTIONAL MATCH equivalent. Returns null row if no match. | | `OptionalExpand(Into)` | ~ | Optional expand between known endpoints. | | `VarLengthExpand(All)` | ✗ | Variable-length `(a)-[*1..5]->(b)` — can be expensive. Use QPE patterns or bound depth. | | `VarLengthExpand(Pruning)` | ~ | Pruned variable-length — avoids re-visiting nodes. Better than All. | | `BFSPruningVarLengthExpand` | ✓ | BFS-based; used for `SHORTEST` paths. Preferred. | | `ShortestPath` | ~ | Single shortest path. Replaced by QPE in Cypher 25. | --- ## Join Operators | Operator | Signal | Notes | |---|---|---| | `Carte