21.6. Legacy Cypher HTTP endpoint

[Note]Note

This endpoint is deprecated. Please transition to using the new transactional endpoint (see Section 21.1, “Transactional Cypher HTTP endpoint”). Among other things it allows you to run multiple Cypher statements in the same transaction.

The Neo4j REST API allows querying with Cypher, see 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]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 the section called “Use parameters” for details. Also see Section 7.5, “Parameters” for where parameters can be used.

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 21.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" ] ]
}

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 21.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/10082/labels",
    "outgoing_relationships" : "http://localhost:7474/db/data/node/10082/relationships/out",
    "data" : {
      "name" : "Andres"
    },
    "all_typed_relationships" : "http://localhost:7474/db/data/node/10082/relationships/all/{-list|&|types}",
    "traverse" : "http://localhost:7474/db/data/node/10082/traverse/{returnType}",
    "self" : "http://localhost:7474/db/data/node/10082",
    "property" : "http://localhost:7474/db/data/node/10082/properties/{key}",
    "properties" : "http://localhost:7474/db/data/node/10082/properties",
    "outgoing_typed_relationships" : "http://localhost:7474/db/data/node/10082/relationships/out/{-list|&|types}",
    "incoming_relationships" : "http://localhost:7474/db/data/node/10082/relationships/in",
    "extensions" : { },
    "create_relationship" : "http://localhost:7474/db/data/node/10082/relationships",
    "paged_traverse" : "http://localhost:7474/db/data/node/10082/paged/traverse/{returnType}{?pageSize,leaseTime}",
    "all_relationships" : "http://localhost:7474/db/data/node/10082/relationships/all",
    "incoming_typed_relationships" : "http://localhost:7474/db/data/node/10082/relationships/in/{-list|&|types}",
    "metadata" : {
      "id" : 10082,
      "labels" : [ "Person" ]
    }
  } ] ]
}

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 21.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/10079/labels",
    "outgoing_relationships" : "http://localhost:7474/db/data/node/10079/relationships/out",
    "data" : {
      "position" : "Developer",
      "awesome" : true,
      "name" : "Michael",
      "children" : 3
    },
    "all_typed_relationships" : "http://localhost:7474/db/data/node/10079/relationships/all/{-list|&|types}",
    "traverse" : "http://localhost:7474/db/data/node/10079/traverse/{returnType}",
    "self" : "http://localhost:7474/db/data/node/10079",
    "property" : "http://localhost:7474/db/data/node/10079/properties/{key}",
    "properties" : "http://localhost:7474/db/data/node/10079/properties",
    "outgoing_typed_relationships" : "http://localhost:7474/db/data/node/10079/relationships/out/{-list|&|types}",
    "incoming_relationships" : "http://localhost:7474/db/data/node/10079/relationships/in",
    "extensions" : { },
    "create_relationship" : "http://localhost:7474/db/data/node/10079/relationships",
    "paged_traverse" : "http://localhost:7474/db/data/node/10079/paged/traverse/{returnType}{?pageSize,leaseTime}",
    "all_relationships" : "http://localhost:7474/db/data/node/10079/relationships/all",
    "incoming_typed_relationships" : "http://localhost:7474/db/data/node/10079/relationships/in/{-list|&|types}",
    "metadata" : {
      "id" : 10079,
      "labels" : [ "Person" ]
    }
  } ] ]
}

Create multiple 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 21.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/10083/labels",
    "outgoing_relationships" : "http://localhost:7474/db/data/node/10083/relationships/out",
    "data" : {
      "position" : "Developer",
      "name" : "Andres"
    },
    "all_typed_relationships" : "http://localhost:7474/db/data/node/10083/relationships/all/{-list|&|types}",
    "traverse" : "http://localhost:7474/db/data/node/10083/traverse/{returnType}",
    "self" : "http://localhost:7474/db/data/node/10083",
    "property" : "http://localhost:7474/db/data/node/10083/properties/{key}",
    "properties" : "http://localhost:7474/db/data/node/10083/properties",
    "outgoing_typed_relationships" : "http://localhost:7474/db/data/node/10083/relationships/out/{-list|&|types}",
    "incoming_relationships" : "http://localhost:7474/db/data/node/10083/relationships/in",
    "extensions" : { },
    "create_relationship" : "http://localhost:7474/db/data/node/10083/relationships",
    "paged_traverse" : "http://localhost:7474/db/data/node/10083/paged/traverse/{returnType}{?pageSize,leaseTime}",
    "all_relationships" : "http://localhost:7474/db/data/node/10083/relationships/all",
    "incoming_typed_relationships" : "http://localhost:7474/db/data/node/10083/relationships/in/{-list|&|types}",
    "metadata" : {
      "id" : 10083,
      "labels" : [ "Person" ]
    }
  } ], [ {
    "labels" : "http://localhost:7474/db/data/node/10084/labels",
    "outgoing_relationships" : "http://localhost:7474/db/data/node/10084/relationships/out",
    "data" : {
      "position" : "Developer",
      "name" : "Michael"
    },
    "all_typed_relationships" : "http://localhost:7474/db/data/node/10084/relationships/all/{-list|&|types}",
    "traverse" : "http://localhost:7474/db/data/node/10084/traverse/{returnType}",
    "self" : "http://localhost:7474/db/data/node/10084",
    "property" : "http://localhost:7474/db/data/node/10084/properties/{key}",
    "properties" : "http://localhost:7474/db/data/node/10084/properties",
    "outgoing_typed_relationships" : "http://localhost:7474/db/data/node/10084/relationships/out/{-list|&|types}",
    "incoming_relationships" : "http://localhost:7474/db/data/node/10084/relationships/in",
    "extensions" : { },
    "create_relationship" : "http://localhost:7474/db/data/node/10084/relationships",
    "paged_traverse" : "http://localhost:7474/db/data/node/10084/paged/traverse/{returnType}{?pageSize,leaseTime}",
    "all_relationships" : "http://localhost:7474/db/data/node/10084/relationships/all",
    "incoming_typed_relationships" : "http://localhost:7474/db/data/node/10084/relationships/in/{-list|&|types}",
    "metadata" : {
      "id" : 10084,
      "labels" : [ "Person" ]
    }
  } ] ]
}

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 21.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/10110/labels",
    "outgoing_relationships" : "http://localhost:7474/db/data/node/10110/relationships/out",
    "data" : {
      "position" : "Developer",
      "awesome" : true,
      "children" : 3,
      "firstName" : "Michael"
    },
    "all_typed_relationships" : "http://localhost:7474/db/data/node/10110/relationships/all/{-list|&|types}",
    "traverse" : "http://localhost:7474/db/data/node/10110/traverse/{returnType}",
    "self" : "http://localhost:7474/db/data/node/10110",
    "property" : "http://localhost:7474/db/data/node/10110/properties/{key}",
    "properties" : "http://localhost:7474/db/data/node/10110/properties",
    "outgoing_typed_relationships" : "http://localhost:7474/db/data/node/10110/relationships/out/{-list|&|types}",
    "incoming_relationships" : "http://localhost:7474/db/data/node/10110/relationships/in",
    "extensions" : { },
    "create_relationship" : "http://localhost:7474/db/data/node/10110/relationships",
    "paged_traverse" : "http://localhost:7474/db/data/node/10110/paged/traverse/{returnType}{?pageSize,leaseTime}",
    "all_relationships" : "http://localhost:7474/db/data/node/10110/relationships/all",
    "incoming_typed_relationships" : "http://localhost:7474/db/data/node/10110/relationships/in/{-list|&|types}",
    "metadata" : {
      "id" : 10110,
      "labels" : [ "Person" ]
    }
  } ] ]
}

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 21.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 ] ]
}

Return paths

Paths can be returned just like other return types.

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

Figure 21.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" : [ [ {
    "directions" : [ "->" ],
    "start" : "http://localhost:7474/db/data/node/10109",
    "nodes" : [ "http://localhost:7474/db/data/node/10109", "http://localhost:7474/db/data/node/10108" ],
    "length" : 1,
    "relationships" : [ "http://localhost:7474/db/data/relationship/55" ],
    "end" : "http://localhost:7474/db/data/node/10108"
  }, "you" ] ]
}

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 21.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" ] ] ]
}

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 21.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
  }
}

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 21.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": "BadInputException",
  "fullname": "org.neo4j.server.rest.repr.BadInputException",
  "stacktrace": [
    "org.neo4j.server.rest.repr.RepresentationExceptionHandlingIterable.exceptionOnNext(RepresentationExceptionHandlingIterable.java:39)",
    "org.neo4j.helpers.collection.ExceptionHandlingIterable$1.next(ExceptionHandlingIterable.java:55)",
    "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:58)",
    "org.neo4j.server.rest.repr.MappingRepresentation.serialize(MappingRepresentation.java:41)",
    "org.neo4j.server.rest.repr.OutputFormat.assemble(OutputFormat.java:242)",
    "org.neo4j.server.rest.repr.OutputFormat.formatRepresentation(OutputFormat.java:174)",
    "org.neo4j.server.rest.repr.OutputFormat.response(OutputFormat.java:157)",
    "org.neo4j.server.rest.repr.OutputFormat.ok(OutputFormat.java:73)",
    "org.neo4j.server.rest.web.CypherService.cypher(CypherService.java:123)",
    "java.lang.reflect.Method.invoke(Method.java:606)",
    "org.neo4j.server.rest.transactional.TransactionalRequestDispatcher.dispatch(TransactionalRequestDispatcher.java:139)",
    "java.lang.Thread.run(Thread.java:745)"
  ],
  "cause": {
    "message": "/ by zero",
    "errors": [
      {
        "message": "/ by zero",
        "code": "Neo.ClientError.Statement.ArithmeticError"
      }
    ],
    "cause": {
      "message": "/ by zero",
      "errors": [
        {
          "message": "/ by zero",
          "code": "Neo.ClientError.Statement.ArithmeticError"
        }
      ],
      "cause": {
        "message": "/ by zero",
        "errors": [
          {
            "message": "/ by zero",
            "code": "Neo.ClientError.Statement.ArithmeticError"
          }
        ],
        "exception": "ArithmeticException",
        "stacktrace": [
          "org.neo4j.cypher.internal.compatibility.exceptionHandlerFor2_2$.arithmeticException(CompatibilityFor2_2.scala:48)",
          "org.neo4j.cypher.internal.compatibility.exceptionHandlerFor2_2$.arithmeticException(CompatibilityFor2_2.scala:45)",
          "org.neo4j.cypher.internal.compiler.v2_2.ArithmeticException.mapToPublic(CypherException.scala:98)",
          "org.neo4j.cypher.internal.compatibility.exceptionHandlerFor2_2$.runSafely(CompatibilityFor2_2.scala:99)",
          "org.neo4j.cypher.internal.compatibility.ExecutionResultWrapperFor2_2$$anon$1.next(CompatibilityFor2_2.scala:158)",
          "org.neo4j.cypher.internal.compatibility.ExecutionResultWrapperFor2_2$$anon$1.next(CompatibilityFor2_2.scala:156)",
          "org.neo4j.cypher.javacompat.ExecutionResult.next(ExecutionResult.java:214)",
          "org.neo4j.cypher.javacompat.ExecutionResult.next(ExecutionResult.java:50)",
          "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:58)",
          "org.neo4j.server.rest.repr.MappingRepresentation.serialize(MappingRepresentation.java:41)",
          "org.neo4j.server.rest.repr.OutputFormat.assemble(OutputFormat.java:242)",
          "org.neo4j.server.rest.repr.OutputFormat.formatRepresentation(OutputFormat.java:174)",
          "org.neo4j.server.rest.repr.OutputFormat.response(OutputFormat.java:157)",
          "org.neo4j.server.rest.repr.OutputFormat.ok(OutputFormat.java:73)",
          "org.neo4j.server.rest.web.CypherService.cypher(CypherService.java:123)",
          "java.lang.reflect.Method.invoke(Method.java:606)",
          "org.neo4j.server.rest.transactional.TransactionalRequestDispatcher.dispatch(TransactionalRequestDispatcher.java:139)",
          "java.lang.Thread.run(Thread.java:745)"
        ],
        "fullname": "org.neo4j.cypher.ArithmeticException"
      },
      "exception": "QueryExecutionKernelException",
      "stacktrace": [
        "org.neo4j.cypher.javacompat.ExecutionResult.converted(ExecutionResult.java:344)",
        "org.neo4j.cypher.javacompat.ExecutionResult.next(ExecutionResult.java:218)",
        "org.neo4j.cypher.javacompat.ExecutionResult.next(ExecutionResult.java:50)",
        "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:58)",
        "org.neo4j.server.rest.repr.MappingRepresentation.serialize(MappingRepresentation.java:41)",
        "org.neo4j.server.rest.repr.OutputFormat.assemble(OutputFormat.java:242)",
        "org.neo4j.server.rest.repr.OutputFormat.formatRepresentation(OutputFormat.java:174)",
        "org.neo4j.server.rest.repr.OutputFormat.response(OutputFormat.java:157)",
        "org.neo4j.server.rest.repr.OutputFormat.ok(OutputFormat.java:73)",
        "org.neo4j.server.rest.web.CypherService.cypher(CypherService.java:123)",
        "java.lang.reflect.Method.invoke(Method.java:606)",
        "org.neo4j.server.rest.transactional.TransactionalRequestDispatcher.dispatch(TransactionalRequestDispatcher.java:139)",
        "java.lang.Thread.run(Thread.java:745)"
      ],
      "fullname": "org.neo4j.kernel.impl.query.QueryExecutionKernelException"
    },
    "exception": "QueryExecutionException",
    "stacktrace": [
      "org.neo4j.kernel.impl.query.QueryExecutionKernelException.asUserException(QueryExecutionKernelException.java:35)",
      "org.neo4j.cypher.javacompat.ExecutionResult.converted(ExecutionResult.java:344)",
      "org.neo4j.cypher.javacompat.ExecutionResult.next(ExecutionResult.java:218)",
      "org.neo4j.cypher.javacompat.ExecutionResult.next(ExecutionResult.java:50)",
      "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:58)",
      "org.neo4j.server.rest.repr.MappingRepresentation.serialize(MappingRepresentation.java:41)",
      "org.neo4j.server.rest.repr.OutputFormat.assemble(OutputFormat.java:242)",
      "org.neo4j.server.rest.repr.OutputFormat.formatRepresentation(OutputFormat.java:174)",
      "org.neo4j.server.rest.repr.OutputFormat.response(OutputFormat.java:157)",
      "org.neo4j.server.rest.repr.OutputFormat.ok(OutputFormat.java:73)",
      "org.neo4j.server.rest.web.CypherService.cypher(CypherService.java:123)",
      "java.lang.reflect.Method.invoke(Method.java:606)",
      "org.neo4j.server.rest.transactional.TransactionalRequestDispatcher.dispatch(TransactionalRequestDispatcher.java:139)",
      "java.lang.Thread.run(Thread.java:745)"
    ],
    "fullname": "org.neo4j.graphdb.QueryExecutionException"
  },
  "errors": [
    {
      "message": "/ by zero",
      "code": "Neo.ClientError.Statement.ArithmeticError"
    }
  ]
}