opsmill/infrahub / .agents/skills/neo4j-cypher-guide
neo4j-cypher-guide
VerifiedComprehensive guide for writing modern Neo4j Cypher queries. Essential for text2cypher MCP tools and LLMs generating Cypher queries. Covers removed/deprecated syntax, modern replacements, CALL subqueries for reads, COLLECT patterns, sorting best practices, set-based writes, Quantified Path Patterns (QPP) for efficient graph traversal, and how to choose the entry point of a query so the plan starts with an index seek instead of a label scan.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.6 KB |
| references/deprecated-syntax.md | markdown | 2.7 KB |
| references/entry-points.md | markdown | 3.6 KB |
| references/qpp.md | markdown | 6.5 KB |
| references/subqueries.md | markdown | 4.4 KB |
references/entry-points.md
View on GitHub# Branch-Scoped Query Entry Points Reference
## Why the Planner Prefers a Label Scan
Index statistics record how many distinct values the `branch` property has, not how many edges
carry each value. The planner therefore estimates a `{branch: $branch_name}` seek as the edges of
that type divided by the number of `branch` values, even when the branch holds a small fraction of
them. A label scan followed by an expand can then come out cheaper:
- A kind label with few vertices starts the plan on any instance.
- `:Root` on `IS_PART_OF` starts the plan on an instance with few branches, where each `branch`
value accounts for a large share of the edges. With more branches, the same pattern starts with
the seek.
- `:Node` starts the plan when the edge type has only two `branch` values, such as `main` and one
feature branch. With three or more values, `:Node` and `:Attribute` did not start the plan in
testing.
Every value of `$branch_name` gets the same plan. Neo4j caches one plan per length range of the
name, such as 2 to 10 or 11 to 100 characters, and the seek estimate above is the same for every
name. With a small kind label in the pattern, forcing the seek cut database hits by over 100x on a
branch with 25 changed edges, and multiplied them by about 70x on the default branch. Use the
label-free entry for a query that runs on a branch with few changes, and the `Node(uuid)` entry for
a query that can run on the default branch.
## Plan Operators to Check
Run `EXPLAIN`, or `PROFILE` on a realistic dataset, on each query text and read the first operator:
- Only the branch is known: `DirectedRelationshipIndexSeek` or `UndirectedRelationshipIndexSeek`.
A type union plans one seek per type under a `Union`, followed by a `Distinct`.
- The node uuids are known: `NodeIndexSeek` on `Node(uuid)`.
- `NodeByLabelScan`, or `UnionNodeByLabelsScan` for a label union such as `Attribute|Relationship`,
means a label replaced the index seek.
## Rules for the Label-Free Entry
- Leave every node in the first `MATCH` unlabelled, including nodes that are not endpoints of the
indexed edge: a small label on any node of a multi-hop pattern can start the plan.
- Check the labels in a step that the planner does not merge back into the first `MATCH`:
- `CALL () { ... }` when that step only checks labels. It holds no rows.
- `WITH DISTINCT` on the start node when a second `MATCH` expands from it, so each start node is
expanded once.
- A label check on the first `MATCH`, or after a plain `WITH`, is merged back and brings the
scan back.
- Put `DISTINCT` on the start node only. `DISTINCT` holds every row it has seen, and over every
matched edge it held about 13 times the memory of `DISTINCT` on the start node.
- Repeat the indexed edge in the second `MATCH`, so the query returns the same rows as the original
single `MATCH`.
- Leave out a label that the edge type already implies: `IS_PART_OF` always runs from a `Node` to
`Root` (`dev/knowledge/backend/database-schema.md`).
## Indexed Edge That Is Not the First Hop
```cypher
MATCH (n)-[:HAS_ATTRIBUTE]->(a)-[:HAS_VALUE {branch: $branch_name}]->()
WITH DISTINCT n
MATCH (root:Root)<-[r_root:IS_PART_OF]-(n)-[:HAS_ATTRIBUTE]->(a:Attribute)
-[r_value:HAS_VALUE {branch: $branch_name}]->(v:AttributeValue)
```
## Worked Example
The node, field and property path queries of the diff calculation in
`backend/infrahub/core/query/diff.py` build one entry clause per case and follow these rules.
## Adding a `branch` Index
Add a `branch` index for a new edge type to `rel_indexes` in `backend/infrahub/core/graph/index.py`.
New database indexes are on the "Ask First" list in `backend/AGENTS.md`.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |