neo4j-cypher

When to Use

• Writing, optimizing, or debugging Cypher queries
• Graph pattern matching, QPEs, variable-length paths
• Vector/fulltext search, subqueries, batch writes, LOAD CSV

When NOT to Use

• Driver migration/API changes → neo4j-migration-skill
• DB admin (users, config, backups) → neo4j-cli-tools-skill
• Hybrid search that combines vector with fulltext or other ranked sources → neo4j-vector-index-skill

GQL conformance note: LET, FINISH, FILTER, and INSERT are valid Cypher 25 clauses (introduced via GQL conformance, mostly in Neo4j 2025.06). On older versions, fall back to WITH / (omit RETURN) / WHERE / CREATE. INSERT requires &-separated multi-labels and does not support dynamic labels/types.

---

Pre-flight

?	Known	Unknown
<db-name>-schema.json found in project	Use it directly — skip live inspection	—
Schema (from context or live DB)	Use directly	Run Schema-First Protocol
Neo4j version	Use version features	Default to 2025.01 safe set
Executing (not generating)?	Use EXPLAIN + write gate	State query is unvalidated

Schema unknown + no tool → produce non-executable sketch outside a code block:

(<SOURCE_LABEL> {<KEY>: $value})-[:<REL_TYPE>]->(<TARGET_LABEL>)

Never fill guessed names — realistic guesses get copied blindly.

---

Defaults — apply every query

1. CYPHER 25 — first token; never repeat after UNION or inside subqueries
2. Schema first — inspect before writing; if schema in prompt, use it directly
3. MERGE on constrained key only; rel MERGE on already-bound endpoints only
4. Label-free MATCH (n) forbidden unless bound or followed by WHERE n:$($label)
5. LIMIT 25 default on all exploratory reads; push WITH n LIMIT before high-cardinality operations (variable-length traversals, fan-out MATCH, Cartesian products)
6. Comments: // only — -- is SQL, invalid
7. REPEATABLE ELEMENTS / DIFFERENT RELATIONSHIPS go after MATCH, not end of pattern
8. SHOW commands: YIELD before WHERE; combinable with general Cypher clauses incl. UNION/RETURN [2026.05] — SHOW DATABASES still requires system db (use USE system)
9. Inline node predicates (:Label WHERE p=x) — valid in MATCH only
10. WHERE cannot follow bare UNWIND — use WITH x WHERE
11. (a)-[:R]-(b) — undirected matches both directions, double-counts; use directed unless unknown
12. DETACH DELETE — plain DELETE throws if node has relationships