Prev |  | Next

## 20.5. Cypher queries via REST

The Neo4j REST API allows querying with Cypher, see Part III, “Cypher Query Language”. The results are returned as a list of string headers (`columns`), and a `data` part, consisting of a list of all rows, every row consisting of a list of REST representations of the field value —`Node`, `Relationship`, `Path` or any simple value like `String`.

| Tip
In order to speed up queries in repeated scenarios, try not to use literals but replace them with parameters wherever possible in order to let the server cache query plans, see Section 20.5.1, “Use parameters” for details. Also see Section 7.5, “Parameters” for where parameters can be used.

### 20.5.1. Use parameters

Cypher supports queries with parameters which are submitted as JSON.

    MATCH (x { name: { startName }})-[r]-(friend)
    WHERE friend.name = { name }
    RETURN TYPE(r)

Figure 20.3. Final Graph

Example request

- `POST` `http://localhost:7474/db/data/cypher`
- `Accept:` `application/json; charset=UTF-8`
- `Content-Type:` `application/json`

    {
      "query" : "MATCH (x {name: {startName}})-[r]-(friend) WHERE friend.name = {name} RETURN TYPE(r)",
      "params" : {
        "startName" : "I",
        "name" : "you"
      }
    }

Example response

- `200:` `OK`
- `Content-Type:` `application/json; charset=UTF-8`

    {
      "columns" : [ "TYPE(r)" ],
      "data" : [ [ "know" ] ]
    }

### 20.5.2. Create a node

Create a node with a label and a property using Cypher. See the request for the parameter sent with the query.

    CREATE (n:Person { name : { name }})
    RETURN n

Figure 20.4. Final Graph

Example request

- `POST` `http://localhost:7474/db/data/cypher`
- `Accept:` `application/json; charset=UTF-8`
- `Content-Type:` `application/json`

    {
      "query" : "CREATE (n:Person { name : {name} }) RETURN n",
      "params" : {
        "name" : "Andres"
      }
    }

Example response

- `200:` `OK`
- `Content-Type:` `application/json; charset=UTF-8`

    {
      "columns" : [ "n" ],
      "data" : [ [ {
        "labels" : "http://localhost:7474/db/data/node/47/labels",
        "outgoing_relationships" : "http://localhost:7474/db/data/node/47/relationships/out",
        "data" : {
          "name" : "Andres"
        },
        "traverse" : "http://localhost:7474/db/data/node/47/traverse/{returnType}",
        "all_typed_relationships" : "http://localhost:7474/db/data/node/47/relationships/all/{-list|&|types}",
        "self" : "http://localhost:7474/db/data/node/47",
        "property" : "http://localhost:7474/db/data/node/47/properties/{key}",
        "outgoing_typed_relationships" : "http://localhost:7474/db/data/node/47/relationships/out/{-list|&|types}",
        "properties" : "http://localhost:7474/db/data/node/47/properties",
        "incoming_relationships" : "http://localhost:7474/db/data/node/47/relationships/in",
        "extensions" : {
        },
        "create_relationship" : "http://localhost:7474/db/data/node/47/relationships",
        "paged_traverse" : "http://localhost:7474/db/data/node/47/paged/traverse/{returnType}{?pageSize,leaseTime}",
        "all_relationships" : "http://localhost:7474/db/data/node/47/relationships/all",
        "incoming_typed_relationships" : "http://localhost:7474/db/data/node/47/relationships/in/{-list|&|types}"
      } ] ]
    }

### 20.5.3. Create a node with multiple properties

Create a node with a label and multiple properties using Cypher. See the request for the parameter sent with the query.

    CREATE (n:Person { props })
    RETURN n

Figure 20.5. Final Graph

Example request

- `POST` `http://localhost:7474/db/data/cypher`
- `Accept:` `application/json; charset=UTF-8`
- `Content-Type:` `application/json`

    {
      "query" : "CREATE (n:Person { props } ) RETURN n",
      "params" : {
        "props" : {
          "position" : "Developer",
          "name" : "Michael",
          "awesome" : true,
          "children" : 3
        }
      }
    }

Example response

- `200:` `OK`
- `Content-Type:` `application/json; charset=UTF-8`

    {
      "columns" : [ "n" ],
      "data" : [ [ {
        "labels" : "http://localhost:7474/db/data/node/44/labels",
        "outgoing_relationships" : "http://localhost:7474/db/data/node/44/relationships/out",
        "data" : {
          "position" : "Developer",
          "awesome" : true,
          "name" : "Michael",
          "children" : 3
        },
        "traverse" : "http://localhost:7474/db/data/node/44/traverse/{returnType}",
        "all_typed_relationships" : "http://localhost:7474/db/data/node/44/relationships/all/{-list|&|types}",
        "self" : "http://localhost:7474/db/data/node/44",
        "property" : "http://localhost:7474/db/data/node/44/properties/{key}",
        "outgoing_typed_relationships" : "http://localhost:7474/db/data/node/44/relationships/out/{-list|&|types}",
        "properties" : "http://localhost:7474/db/data/node/44/properties",
        "incoming_relationships" : "http://localhost:7474/db/data/node/44/relationships/in",
        "extensions" : {
        },
        "create_relationship" : "http://localhost:7474/db/data/node/44/relationships",
        "paged_traverse" : "http://localhost:7474/db/data/node/44/paged/traverse/{returnType}{?pageSize,leaseTime}",
        "all_relationships" : "http://localhost:7474/db/data/node/44/relationships/all",
        "incoming_typed_relationships" : "http://localhost:7474/db/data/node/44/relationships/in/{-list|&|types}"
      } ] ]
    }

### 20.5.4. Create mutiple nodes with properties

Create multiple nodes with properties using Cypher. See the request for the parameter sent with the query.

    CREATE (n:Person { props })
    RETURN n

Figure 20.6. Final Graph

Example request

- `POST` `http://localhost:7474/db/data/cypher`
- `Accept:` `application/json; charset=UTF-8`
- `Content-Type:` `application/json`

    {
      "query" : "CREATE (n:Person { props } ) RETURN n",
      "params" : {
        "props" : [ {
          "name" : "Andres",
          "position" : "Developer"
        }, {
          "name" : "Michael",
          "position" : "Developer"
        } ]
      }
    }

Example response

- `200:` `OK`
- `Content-Type:` `application/json; charset=UTF-8`

    {
      "columns" : [ "n" ],
      "data" : [ [ {
        "labels" : "http://localhost:7474/db/data/node/48/labels",
        "outgoing_relationships" : "http://localhost:7474/db/data/node/48/relationships/out",
        "data" : {
          "position" : "Developer",
          "name" : "Andres"
        },
        "traverse" : "http://localhost:7474/db/data/node/48/traverse/{returnType}",
        "all_typed_relationships" : "http://localhost:7474/db/data/node/48/relationships/all/{-list|&|types}",
        "self" : "http://localhost:7474/db/data/node/48",
        "property" : "http://localhost:7474/db/data/node/48/properties/{key}",
        "outgoing_typed_relationships" : "http://localhost:7474/db/data/node/48/relationships/out/{-list|&|types}",
        "properties" : "http://localhost:7474/db/data/node/48/properties",
        "incoming_relationships" : "http://localhost:7474/db/data/node/48/relationships/in",
        "extensions" : {
        },
        "create_relationship" : "http://localhost:7474/db/data/node/48/relationships",
        "paged_traverse" : "http://localhost:7474/db/data/node/48/paged/traverse/{returnType}{?pageSize,leaseTime}",
        "all_relationships" : "http://localhost:7474/db/data/node/48/relationships/all",
        "incoming_typed_relationships" : "http://localhost:7474/db/data/node/48/relationships/in/{-list|&|types}"
      } ], [ {
        "labels" : "http://localhost:7474/db/data/node/49/labels",
        "outgoing_relationships" : "http://localhost:7474/db/data/node/49/relationships/out",
        "data" : {
          "position" : "Developer",
          "name" : "Michael"
        },
        "traverse" : "http://localhost:7474/db/data/node/49/traverse/{returnType}",
        "all_typed_relationships" : "http://localhost:7474/db/data/node/49/relationships/all/{-list|&|types}",
        "self" : "http://localhost:7474/db/data/node/49",
        "property" : "http://localhost:7474/db/data/node/49/properties/{key}",
        "outgoing_typed_relationships" : "http://localhost:7474/db/data/node/49/relationships/out/{-list|&|types}",
        "properties" : "http://localhost:7474/db/data/node/49/properties",
        "incoming_relationships" : "http://localhost:7474/db/data/node/49/relationships/in",
        "extensions" : {
        },
        "create_relationship" : "http://localhost:7474/db/data/node/49/relationships",
        "paged_traverse" : "http://localhost:7474/db/data/node/49/paged/traverse/{returnType}{?pageSize,leaseTime}",
        "all_relationships" : "http://localhost:7474/db/data/node/49/relationships/all",
        "incoming_typed_relationships" : "http://localhost:7474/db/data/node/49/relationships/in/{-list|&|types}"
      } ] ]
    }

### 20.5.5. Set all properties on a node using Cypher

Set all properties on a node.

    CREATE (n:Person { name: 'this property is to be deleted' })
    SET n = { props }
    RETURN n

Figure 20.7. Final Graph

Example request

- `POST` `http://localhost:7474/db/data/cypher`
- `Accept:` `application/json; charset=UTF-8`
- `Content-Type:` `application/json`

    {
      "query" : "CREATE (n:Person { name: 'this property is to be deleted' } ) SET n = { props } RETURN n",
      "params" : {
        "props" : {
          "position" : "Developer",
          "firstName" : "Michael",
          "awesome" : true,
          "children" : 3
        }
      }
    }

Example response

- `200:` `OK`
- `Content-Type:` `application/json; charset=UTF-8`

    {
      "columns" : [ "n" ],
      "data" : [ [ {
        "labels" : "http://localhost:7474/db/data/node/75/labels",
        "outgoing_relationships" : "http://localhost:7474/db/data/node/75/relationships/out",
        "data" : {
          "position" : "Developer",
          "awesome" : true,
          "children" : 3,
          "firstName" : "Michael"
        },
        "traverse" : "http://localhost:7474/db/data/node/75/traverse/{returnType}",
        "all_typed_relationships" : "http://localhost:7474/db/data/node/75/relationships/all/{-list|&|types}",
        "self" : "http://localhost:7474/db/data/node/75",
        "property" : "http://localhost:7474/db/data/node/75/properties/{key}",
        "outgoing_typed_relationships" : "http://localhost:7474/db/data/node/75/relationships/out/{-list|&|types}",
        "properties" : "http://localhost:7474/db/data/node/75/properties",
        "incoming_relationships" : "http://localhost:7474/db/data/node/75/relationships/in",
        "extensions" : {
        },
        "create_relationship" : "http://localhost:7474/db/data/node/75/relationships",
        "paged_traverse" : "http://localhost:7474/db/data/node/75/paged/traverse/{returnType}{?pageSize,leaseTime}",
        "all_relationships" : "http://localhost:7474/db/data/node/75/relationships/all",
        "incoming_typed_relationships" : "http://localhost:7474/db/data/node/75/relationships/in/{-list|&|types}"
      } ] ]
    }

### 20.5.6. Send a query

A simple query returning all nodes connected to some node, returning the node and the name property, if it exists, otherwise `NULL`:

    MATCH (x { name: 'I' })-[r]->(n)
    RETURN type(r), n.name, n.age

Figure 20.8. Final Graph

Example request

- `POST` `http://localhost:7474/db/data/cypher`
- `Accept:` `application/json; charset=UTF-8`
- `Content-Type:` `application/json`

    {
      "query" : "MATCH (x {name: 'I'})-[r]->(n) RETURN type(r), n.name, n.age",
      "params" : {
      }
    }

Example response

- `200:` `OK`
- `Content-Type:` `application/json; charset=UTF-8`

    {
      "columns" : [ "type(r)", "n.name", "n.age" ],
      "data" : [ [ "know", "him", 25 ], [ "know", "you", null ] ]
    }

### 20.5.7. Return paths

Paths can be returned just like other return types.

    MATCH path =(x { name: 'I' })--(friend)
    RETURN path, friend.name

Figure 20.9. Final Graph

Example request

- `POST` `http://localhost:7474/db/data/cypher`
- `Accept:` `application/json; charset=UTF-8`
- `Content-Type:` `application/json`

    {
      "query" : "MATCH path = (x {name: 'I'})--(friend) RETURN path, friend.name",
      "params" : {
      }
    }

Example response

- `200:` `OK`
- `Content-Type:` `application/json; charset=UTF-8`

    {
      "columns" : [ "path", "friend.name" ],
      "data" : [ [ {
        "start" : "http://localhost:7474/db/data/node/74",
        "nodes" : [ "http://localhost:7474/db/data/node/74", "http://localhost:7474/db/data/node/73" ],
        "length" : 1,
        "relationships" : [ "http://localhost:7474/db/data/relationship/20" ],
        "end" : "http://localhost:7474/db/data/node/73"
      }, "you" ] ]
    }

### 20.5.8. Nested results

When sending queries that return nested results like list and maps, these will get serialized into nested JSON representations according to their types.

    MATCH (n)
    WHERE n.name IN ['I', 'you']
    RETURN collect(n.name)

Figure 20.10. Final Graph

Example request

- `POST` `http://localhost:7474/db/data/cypher`
- `Accept:` `application/json; charset=UTF-8`
- `Content-Type:` `application/json`

    {
      "query" : "MATCH (n) WHERE n.name in ['I', 'you'] RETURN collect(n.name)",
      "params" : {
      }
    }

Example response

- `200:` `OK`
- `Content-Type:` `application/json; charset=UTF-8`

    {
      "columns" : [ "collect(n.name)" ],
      "data" : [ [ [ "you", "I" ] ] ]
    }

### 20.5.9. Retrieve query metadata

By passing in an additional GET parameter when you execute Cypher queries, metadata about the query will be returned, such as how many labels were added or removed by the query.

    MATCH (n { name: 'I' })
    SET n:Actor
    REMOVE n:Director
    RETURN labels(n)

Figure 20.11. Final Graph

Example request

- `POST` `http://localhost:7474/db/data/cypher?includeStats=true`
- `Accept:` `application/json; charset=UTF-8`
- `Content-Type:` `application/json`

    {
      "query" : "MATCH (n {name: 'I'}) SET n:Actor REMOVE n:Director RETURN labels(n)",
      "params" : {
      }
    }

Example response

- `200:` `OK`
- `Content-Type:` `application/json; charset=UTF-8`

    {
      "columns" : [ "labels(n)" ],
      "data" : [ [ [ "Actor" ] ] ],
      "stats" : {
        "relationships_created" : 0,
        "nodes_deleted" : 0,
        "relationship_deleted" : 0,
        "indexes_added" : 0,
        "properties_set" : 0,
        "constraints_removed" : 0,
        "indexes_removed" : 0,
        "labels_removed" : 1,
        "constraints_added" : 0,
        "labels_added" : 1,
        "nodes_created" : 0,
        "contains_updates" : true
      }
    }

### 20.5.10. Errors

Errors on the server will be reported as a JSON-formatted message, exception name and stacktrace.

    MATCH (x { name: 'I' })
    RETURN x.dummy/0

Figure 20.12. Final Graph

Example request

- `POST` `http://localhost:7474/db/data/cypher`
- `Accept:` `application/json; charset=UTF-8`
- `Content-Type:` `application/json`

    {
      "query" : "MATCH (x {name: 'I'}) RETURN x.dummy/0",
      "params" : {
      }
    }

Example response

- `400:` `Bad Request`
- `Content-Type:` `application/json; charset=UTF-8`

    {
      "message": "/ by zero",
      "exception": "ArithmeticException",
      "fullname": "org.neo4j.cypher.ArithmeticException",
      "stacktrace": [
        "org.neo4j.cypher.internal.compiler.v2_1.commands.expressions.Divide.apply(Divide.scala:36)",
        "org.neo4j.cypher.internal.compiler.v2_1.pipes.ExtractPipe$$anonfun$3$$anonfun$apply$2.apply(ExtractPipe.scala:63)",
        "org.neo4j.cypher.internal.compiler.v2_1.pipes.ExtractPipe$$anonfun$3$$anonfun$apply$2.apply(ExtractPipe.scala:61)",
        "scala.collection.immutable.Map$Map1.foreach(Map.scala:109)",
        "org.neo4j.cypher.internal.compiler.v2_1.pipes.ExtractPipe$$anonfun$3.apply(ExtractPipe.scala:61)",
        "org.neo4j.cypher.internal.compiler.v2_1.pipes.ExtractPipe$$anonfun$3.apply(ExtractPipe.scala:60)",
        "org.neo4j.cypher.internal.compiler.v2_1.pipes.ExtractPipe$$anonfun$internalCreateResults$1.apply(ExtractPipe.scala:83)",
        "org.neo4j.cypher.internal.compiler.v2_1.pipes.ExtractPipe$$anonfun$internalCreateResults$1.apply(ExtractPipe.scala:83)",
        "scala.collection.Iterator$$anon$11.next(Iterator.scala:328)",
        "scala.collection.Iterator$$anon$11.next(Iterator.scala:328)",
        "org.neo4j.cypher.internal.compiler.v2_1.ClosingIterator$$anonfun$next$1.apply(ClosingIterator.scala:51)",
        "org.neo4j.cypher.internal.compiler.v2_1.ClosingIterator$$anonfun$next$1.apply(ClosingIterator.scala:48)",
        "org.neo4j.cypher.internal.compiler.v2_1.ClosingIterator.failIfThrows(ClosingIterator.scala:118)",
        "org.neo4j.cypher.internal.compiler.v2_1.ClosingIterator.next(ClosingIterator.scala:48)",
        "org.neo4j.cypher.internal.compiler.v2_1.PipeExecutionResult.next(PipeExecutionResult.scala:168)",
        "org.neo4j.cypher.internal.compiler.v2_1.PipeExecutionResult.next(PipeExecutionResult.scala:34)",
        "scala.collection.Iterator$$anon$11.next(Iterator.scala:328)",
        "scala.collection.convert.Wrappers$IteratorWrapper.next(Wrappers.scala:30)",
        "org.neo4j.cypher.internal.compiler.v2_1.PipeExecutionResult$$anon$1.next(PipeExecutionResult.scala:76)",
        "org.neo4j.helpers.collection.ExceptionHandlingIterable$1.next(ExceptionHandlingIterable.java:53)",
        "org.neo4j.helpers.collection.IteratorWrapper.next(IteratorWrapper.java:47)",
        "org.neo4j.server.rest.repr.ListRepresentation.serialize(ListRepresentation.java:64)",
        "org.neo4j.server.rest.repr.Serializer.serialize(Serializer.java:75)",
        "org.neo4j.server.rest.repr.MappingSerializer.putList(MappingSerializer.java:61)",
        "org.neo4j.server.rest.repr.CypherResultRepresentation.serialize(CypherResultRepresentation.java:83)",
        "org.neo4j.server.rest.repr.MappingRepresentation.serialize(MappingRepresentation.java:41)",
        "org.neo4j.server.rest.repr.OutputFormat.assemble(OutputFormat.java:219)",
        "org.neo4j.server.rest.repr.OutputFormat.formatRepresentation(OutputFormat.java:151)",
        "org.neo4j.server.rest.repr.OutputFormat.response(OutputFormat.java:134)",
        "org.neo4j.server.rest.repr.OutputFormat.ok(OutputFormat.java:71)",
        "org.neo4j.server.rest.web.CypherService.cypher(CypherService.java:122)",
        "java.lang.reflect.Method.invoke(Method.java:606)",
        "org.neo4j.server.rest.transactional.TransactionalRequestDispatcher.dispatch(TransactionalRequestDispatcher.java:139)",
        "org.neo4j.server.rest.security.SecurityFilter.doFilter(SecurityFilter.java:112)",
        "java.lang.Thread.run(Thread.java:724)"
      ]
    }

Copyright © 2014 Neo Technology

Prev | Up | Next
| Home |