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 19.5.1, “Use parameters” for details. Also see Section 7.5, “Parameters” for where parameters can be used. |
Cypher supports queries with parameters which are submitted as JSON.
MATCH (x { name: { startName }})-[r]-(friend) WHERE friend.name = { name } RETURN TYPE(r)
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" ] ] }
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
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}", "property" : "http://localhost:7474/db/data/node/47/properties/{key}", "self" : "http://localhost:7474/db/data/node/47", "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}" } ] ] }
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
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}", "property" : "http://localhost:7474/db/data/node/44/properties/{key}", "self" : "http://localhost:7474/db/data/node/44", "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}" } ] ] }
Create multiple nodes with properties using Cypher. See the request for the parameter sent with the query.
CREATE (n:Person { props }) RETURN n
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}", "property" : "http://localhost:7474/db/data/node/48/properties/{key}", "self" : "http://localhost:7474/db/data/node/48", "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}", "property" : "http://localhost:7474/db/data/node/49/properties/{key}", "self" : "http://localhost:7474/db/data/node/49", "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}" } ] ] }
Set all properties on a node.
CREATE (n:Person { name: 'this property is to be deleted' }) SET n = { props } RETURN n
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}", "property" : "http://localhost:7474/db/data/node/75/properties/{key}", "self" : "http://localhost:7474/db/data/node/75", "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}" } ] ] }
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
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 ] ] }
Paths can be returned just like other return types.
MATCH path =(x { name: 'I' })--(friend) RETURN path, friend.name
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" ] ] }
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)
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" ] ] ] }
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)
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 } }
Errors on the server will be reported as a JSON-formatted message, exception name and stacktrace.
MATCH (x { name: 'I' }) RETURN x.dummy/0
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_0.commands.expressions.Divide.apply(Divide.scala:36)", "org.neo4j.cypher.internal.compiler.v2_0.pipes.ExtractPipe$$anonfun$3$$anonfun$apply$2.apply(ExtractPipe.scala:63)", "org.neo4j.cypher.internal.compiler.v2_0.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_0.pipes.ExtractPipe$$anonfun$3.apply(ExtractPipe.scala:61)", "org.neo4j.cypher.internal.compiler.v2_0.pipes.ExtractPipe$$anonfun$3.apply(ExtractPipe.scala:60)", "org.neo4j.cypher.internal.compiler.v2_0.pipes.ExtractPipe$$anonfun$internalCreateResults$1.apply(ExtractPipe.scala:83)", "org.neo4j.cypher.internal.compiler.v2_0.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_0.ClosingIterator$$anonfun$next$1.apply(ClosingIterator.scala:46)", "org.neo4j.cypher.internal.compiler.v2_0.ClosingIterator$$anonfun$next$1.apply(ClosingIterator.scala:45)", "org.neo4j.cypher.internal.compiler.v2_0.ClosingIterator.failIfThrows(ClosingIterator.scala:91)", "org.neo4j.cypher.internal.compiler.v2_0.ClosingIterator.next(ClosingIterator.scala:45)", "org.neo4j.cypher.internal.compiler.v2_0.PipeExecutionResult.next(PipeExecutionResult.scala:168)", "org.neo4j.cypher.internal.compiler.v2_0.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_0.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:215)", "org.neo4j.server.rest.repr.OutputFormat.formatRepresentation(OutputFormat.java:147)", "org.neo4j.server.rest.repr.OutputFormat.response(OutputFormat.java:130)", "org.neo4j.server.rest.repr.OutputFormat.ok(OutputFormat.java:67)", "org.neo4j.server.rest.web.CypherService.cypher(CypherService.java:101)", "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