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 nameConnect 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 rowCREATE (: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 = trueON MATCH SET c.seen = trueRETURN 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 = 1ON MATCH SET r.times = r.times + 1RETURN r.times AS times// 1, then 2, …An upsert batch:
// {"rows": [{"name": "Lima", "pop": 11}, {"name": "Bogota", "pop": 8}]}UNWIND $rows AS rowMERGE (c:City {name: row.name})SET c.pop = row.popSET
MATCH (a:Person {name: 'Ada'})SET a.field = 'math', a.born = 1815 // assign propertiesRETURN properties(a) AS p// {born: 1815, field: 'math', name: 'Ada'}
MATCH (a:Person {name: 'Ada'}) SET a += {title: 'Countess'} // merge a mapMATCH (a:Person {name: 'Ada'}) SET a = {name: 'Ada', born: 1815} // replace all propertiesMATCH (a:Person {name: 'Ada'}) SET a:Mathematician // add a labelRelationships take property SET the same way:
MATCH (:Person {name: 'Alan'})-[k:KNOWS]->() SET k.since = 1937SET targets a property of a bound variable (a.prop = …); computed
targets are not supported.
REMOVE
MATCH (a:Person {name: 'Ada'})REMOVE a:Mathematician, a.bornRETURN 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 aA 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 nameRead 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
CREATEorMERGE(CREATE p = (…)). LOAD CSVandCALL { … } IN TRANSACTIONS: batch withUNWIND $rowsor the Python bulk API.- Explicit
BEGIN/COMMITin 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).