Skip to content

Writing data

Every write statement is one transaction. It is appended to the write-ahead log and committed with a conditional manifest write before the call returns; if any part fails (a constraint, a timeout, an error), nothing in the statement is committed.

Over HTTP a write returns write_outcome counters:

{"columns":["name"],"rows":[{"name":"Ada"}],
"write_outcome":{"nodes_created":1,"edges_created":0,"nodes_deleted":0,
"edges_deleted":0,"properties_set":0}}

properties_set counts properties written by SET, ON CREATE SET, ON MATCH SET and REMOVE; properties given in a CREATE pattern are not counted.

CREATE

CREATE (a:Person {name: 'Ada', born: 1815}) RETURN a.name AS name
// Nodes and the relationship between them in one pattern:
CREATE (a:Person {name: 'Alan'})-[:KNOWS {since: 1936}]->(b:Person {name: 'Alonzo'})
// Properties from a parameter map ({"props": {"name": "Grace", "born": 1906}}):
CREATE (p:Person $props) RETURN p.name AS name

Connect existing nodes by matching them first:

MATCH (a:Person {name: 'Ada'}), (b:Person {name: 'Grace'})
CREATE (a)-[:INSPIRED]->(b)

A relationship always has exactly one type and a direction. Several labels can be given at creation, (:Person:Admin {…}).

Batches with UNWIND

Send many rows in one statement with a list parameter. This is far faster than one request per row:

// {"rows": [{"name": "Lima", "pop": 10}, {"name": "Quito", "pop": 3}]}
UNWIND $rows AS row
CREATE (:City {name: row.name, pop: row.pop})

For very large loads from Python, the bulk API (put_nodes, merge_nodes, merge_edges, load_parquet_nodes, load_parquet_edges) skips Cypher planning entirely; see the Python reference.

MERGE

MERGE matches the whole pattern, or creates it if it does not exist. ON CREATE SET and ON MATCH SET run on the respective branch:

MERGE (c:City {name: 'Cusco'})
ON CREATE SET c.created = true
ON MATCH SET c.seen = true
RETURN c.created AS created, c.seen AS seen
// first run: {created: true, seen: null}; later runs: {created: true, seen: true}

Merge a relationship between bound nodes, for example a visit counter:

MATCH (a:Person {name: 'Ada'}), (c:City {name: 'Lima'})
MERGE (a)-[r:VISITED]->(c)
ON CREATE SET r.times = 1
ON MATCH SET r.times = r.times + 1
RETURN r.times AS times
// 1, then 2, …

An upsert batch:

// {"rows": [{"name": "Lima", "pop": 11}, {"name": "Bogota", "pop": 8}]}
UNWIND $rows AS row
MERGE (c:City {name: row.name})
SET c.pop = row.pop

SET

MATCH (a:Person {name: 'Ada'})
SET a.field = 'math', a.born = 1815 // assign properties
RETURN properties(a) AS p
// {born: 1815, field: 'math', name: 'Ada'}
MATCH (a:Person {name: 'Ada'}) SET a += {title: 'Countess'} // merge a map
MATCH (a:Person {name: 'Ada'}) SET a = {name: 'Ada', born: 1815} // replace all properties
MATCH (a:Person {name: 'Ada'}) SET a:Mathematician // add a label

Relationships take property SET the same way:

MATCH (:Person {name: 'Alan'})-[k:KNOWS]->() SET k.since = 1937

SET targets a property of a bound variable (a.prop = …); computed targets are not supported.

REMOVE

MATCH (a:Person {name: 'Ada'})
REMOVE a:Mathematician, a.born
RETURN labels(a) AS l, properties(a) AS p
// {l: ['Person'], p: {name: 'Ada'}}

DELETE and DETACH DELETE

// Delete a relationship:
MATCH (:Person {name: 'Alan'})-[k:KNOWS]->() DELETE k
// Delete a node and every relationship attached to it:
MATCH (a:Person {name: 'Ada'}) DETACH DELETE a

A plain DELETE of a node that still has relationships is refused, and the statement commits nothing:

{"code":"constraint","error":"write execution failed: constraint violation: cannot DELETE a node that still has relationships (found INSPIRED); use DETACH DELETE to remove the node and its relationships","gql_status":"23000","neo4j_code":"Neo.ClientError.Schema.ConstraintValidationFailed"}

(HTTP 409.)

FOREACH

Run update clauses once per list element, per row:

MATCH (c:City)
FOREACH (tag IN ['andes', 'capital'] | CREATE (c)-[:TAGGED]->(:Tag {name: tag}))

The conditional-write idiom uses a one- or zero-element list:

MATCH (c:City)
FOREACH (_ IN CASE WHEN c.pop > 10 THEN [1] ELSE [] END | SET c.mega = true)

The body may contain CREATE, MERGE, SET, REMOVE, DELETE and nested FOREACH. Values RETURNed later in the same statement reflect each row as it was before the FOREACH; read the result in a following query.

Write subqueries

A correlated CALL { … } can write too:

MATCH (p:Person {name: 'Alan'})
CALL { WITH p CREATE (p)-[:WROTE]->(:Paper {title: 'On Computable Numbers'}) }
RETURN p.name AS name

Read your own writes

Later clauses of a statement see what earlier clauses wrote:

CREATE (t:Tmp) WITH t MATCH (x:Tmp) RETURN count(x) AS seen
// {seen: 1}

Constraints and errors

A write that violates a declared unique constraint fails, and the whole statement is rolled back (HTTP 409, code: "constraint"):

constraint violation: User.email = Str("a@x") already exists (unique constraint)

When a vector index covers a property, a vector of the wrong dimension is rejected the same way. Other failures and their codes are listed in the error taxonomy.

Not supported

  • Binding a path variable in CREATE or MERGE (CREATE p = (…)).
  • LOAD CSV and CALL { … } IN TRANSACTIONS: batch with UNWIND $rows or the Python bulk API.
  • Explicit BEGIN / COMMIT in Cypher text. Bolt drivers can run several statements in one explicit transaction; see Bolt.

Timeouts

A write statement has its own wall-clock budget on the server, --write-timeout (default 60s). A write that runs out of time is discarded, not partially committed. For bulk loads, chunk the work or raise the budget (NAMIDB_WRITE_TIMEOUT=0s removes it).