DELETE

Generic Description

Remove matched entities.

Simple example:

MATCH (p:Person {name: 'Gus'}) DETACH DELETE p

Consumer-Level Explanation

Use DELETE when the query must remove matched entities and the planner needs to see that operation as part of the Cypher row pipeline. Keep the clause explicit because it controls row grain, variable scope, and what later clauses are allowed to reference.

More Detailed Explanation

DELETE is straightforward only when the surrounding query is straightforward. In real systems it is usually used after a carefully constrained MATCH or MERGE pipeline so that deletion is explicit and auditable.

What this clause is really for:

• it defines one concrete stage in the Cypher row pipeline, so variables available before and after DELETE must be clear
• it should make graph structure, temporal filters, document payload shaping, or procedure output explicit instead of relying on client-side interpretation
• planner tooling depends on this clause boundary to know row grain, variable scope, and whether later expressions are reads, writes, schema operations, or projections

Advanced Example

This example keeps DELETE inside a complete query pipeline so the clause boundary, visible variables, and returned row shape are clear to planner tooling.

UNWIND [{user_id: 'u-1', doc_id: 'd-1', ts: '2025-01-02T10:00:00Z', payload: {kind: 'view'}, doc_metadata: {kind: 'report'}, embedding: [0.22, 0.18, 0.44]}] AS evt
MERGE (u:User {user_id: evt.user_id})
MERGE (d:Document {doc_id: evt.doc_id})
CREATE (u)-[e:VIEWED]->(d)
SET e.ts = toDateTime(evt.ts),
    e.payload = evt.payload,
    d.metadata = evt.doc_metadata,
    d.embedding = vector(evt.embedding)
WITH u, d, e, date_trunc('day', e.ts) AS day_bucket
RETURN u.user_id, d.doc_id, day_bucket, keys(properties(d)) AS doc_keys

Real Use Cases

• removing invalid or expired graph artifacts
• data-cleanup jobs
• rolling back derived entities

Real Limitations And Tradeoffs

• dangerous when the preceding match is too broad
• entity lifecycle rules may require more than direct deletion
• clustered and transactional semantics still matter even for small deletes