Saltearse al contenido

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 name

Conecta 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 row
CREATE (: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 = 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}

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 = 1
ON MATCH SET r.times = r.times + 1
RETURN r.times AS times
// 1, then 2, …

Un lote de upserts:

// {"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

Las relaciones aceptan SET de propiedades de la misma forma:

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

SET 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.born
RETURN 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 a

Un 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 name

Leer 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 CREATE o MERGE (CREATE p = (…)).
  • LOAD CSV y CALL { … } IN TRANSACTIONS: agrupa en lotes con UNWIND $rows o con la API de carga masiva de Python.
  • BEGIN / COMMIT explí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).