Escribir datos
Cada sentencia de escritura es una transacción. Se agrega al write-ahead log y se confirma con una escritura condicional del manifest antes de que la llamada retorne; si cualquier parte falla (una restricción, un timeout, un error), no se confirma nada de la sentencia.
Por HTTP, una escritura retorna los contadores de write_outcome:
{"columns":["name"],"rows":[{"name":"Ada"}], "write_outcome":{"nodes_created":1,"edges_created":0,"nodes_deleted":0, "edges_deleted":0,"properties_set":0}}properties_set cuenta las propiedades escritas por SET,
ON CREATE SET, ON MATCH SET y REMOVE; las propiedades indicadas en un
patrón CREATE no se cuentan.
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 nameConecta nodos existentes haciendo match con ellos primero:
MATCH (a:Person {name: 'Ada'}), (b:Person {name: 'Grace'})CREATE (a)-[:INSPIRED]->(b)Una relación siempre tiene exactamente un tipo y una dirección. Al crear un
nodo se pueden indicar varios labels, (:Person:Admin {…}).
Lotes con UNWIND
Envía muchas filas en una sola sentencia con un parámetro de lista. Es mucho más rápido que una petición por fila:
// {"rows": [{"name": "Lima", "pop": 10}, {"name": "Quito", "pop": 3}]}UNWIND $rows AS rowCREATE (:City {name: row.name, pop: row.pop})Para cargas muy grandes desde Python, la API de carga masiva (put_nodes,
merge_nodes, merge_edges, load_parquet_nodes, load_parquet_edges)
omite por completo la planificación de Cypher; consulta la
referencia de Python.
MERGE
MERGE hace match con el patrón completo, o lo crea si no existe.
ON CREATE SET y ON MATCH SET se ejecutan en la rama correspondiente:
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}Fusiona una relación entre nodos vinculados, por ejemplo un contador de visitas:
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, …Un lote de upserts:
// {"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 labelLas relaciones aceptan SET de propiedades de la misma forma:
MATCH (:Person {name: 'Alan'})-[k:KNOWS]->() SET k.since = 1937SET apunta a una propiedad de una variable vinculada (a.prop = …); los
destinos calculados no están soportados.
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 y 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 aUn DELETE simple de un nodo que todavía tiene relaciones se rechaza, y la
sentencia no confirma nada:
{"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
Ejecuta cláusulas de actualización una vez por elemento de la lista, por cada fila:
MATCH (c:City)FOREACH (tag IN ['andes', 'capital'] | CREATE (c)-[:TAGGED]->(:Tag {name: tag}))El patrón de escritura condicional usa una lista de uno o cero elementos:
MATCH (c:City)FOREACH (_ IN CASE WHEN c.pop > 10 THEN [1] ELSE [] END | SET c.mega = true)El cuerpo puede contener CREATE, MERGE, SET, REMOVE, DELETE y
FOREACH anidados. Los valores retornados con RETURN más adelante en la
misma sentencia reflejan cada fila como estaba antes del FOREACH; lee el
resultado en una consulta posterior.
Subconsultas de escritura
Un CALL { … } correlacionado también puede escribir:
MATCH (p:Person {name: 'Alan'})CALL { WITH p CREATE (p)-[:WROTE]->(:Paper {title: 'On Computable Numbers'}) }RETURN p.name AS nameLeer tus propias escrituras
Las cláusulas posteriores de una sentencia ven lo que escribieron las cláusulas anteriores:
CREATE (t:Tmp) WITH t MATCH (x:Tmp) RETURN count(x) AS seen// {seen: 1}Restricciones y errores
Una escritura que viola una restricción de unicidad declarada falla, y se
hace rollback de la sentencia completa (HTTP 409, code: "constraint"):
constraint violation: User.email = Str("a@x") already exists (unique constraint)Cuando un índice vectorial cubre una propiedad, un vector de dimensión incorrecta se rechaza de la misma forma. Los demás fallos y sus códigos se listan en la taxonomía de errores.
No soportado
- Vincular una variable de camino en
CREATEoMERGE(CREATE p = (…)). LOAD CSVyCALL { … } IN TRANSACTIONS: agrupa en lotes conUNWIND $rowso con la API de carga masiva de Python.BEGIN/COMMITexplícitos en el texto Cypher. Los drivers Bolt pueden ejecutar varias sentencias en una transacción explícita; consulta Bolt.
Timeouts
Una sentencia de escritura tiene su propio presupuesto de tiempo real en el
servidor, --write-timeout (por defecto 60s). Una escritura que se queda
sin tiempo se descarta, no se confirma parcialmente. Para cargas masivas,
divide el trabajo en partes o sube el presupuesto
(NAMIDB_WRITE_TIMEOUT=0s lo elimina).