Query the database

To run a query on a database, submit a POST request to the following endpoint:

http://<host>:<port>/db/<databaseName>/query/v2

<host> is where the Neo4j instance is located (example: localhost, xxx.databases.neo4j.io),
<port> is the port on which the Neo4j HTTP server is set to listen on (optional; default 7474),
<databaseName> is the database you want to query (example: neo4j).

The server wraps the submitted Cypher query in a (implicit) transaction for you. This means that in case any part of the query fails, the database will be reverted back to its status before any part of the query was executed.

It’s currently not possible to control the lifecycle of transactions through the Query API. If you need that flexibility, checkout the HTTP API and language libraries.

Each request must include an Authorization header, see Authorize requests for more information.

Example request

POST http://localhost:7474/db/neo4j/query/v2
Authorization: Basic bmVvNGo6dmVyeXNlY3JldA==
Content-Type: application/json

{
  "statement": "MERGE (n:Person {name: $name, age: $age}) RETURN n AS alice",
  "parameters": {
    "name": "Alice",
    "age": 42
  }
}

Example response

202: Accepted  (1)
Content-Type: application/json

{
  "data": {
    "fields": [  (2)
      "alice"
    ],
    "values": [  (3)
      {
        "elementId": "4:ff04df25-ff2b-4b55-98f8-6888297b025e:0",  (4)
        "labels": [
          "Person"
        ],
        "properties": {
          "name": "Alice",
          "age": 42
        }
      }
    ]
  },
  "bookmarks": [  (5)
    "FB:kcwQ/wTfJf8rS1WY+GiIKXsCXgmQ"
  ]
}

1	Because the server does not know whether the request will be successful or not when it sends the HTTP status code, all API requests return a `202` status code, regardless of whether the statements were successfully executed. The only exception is authentication errors, which result in a `401` status code.
2	Query result keys.
3	Query result values, in the same order as `fields`. For more information on what format the values may take, see Result formats.
4	Entity ID within the database. `elementId` should be used with care, as no guarantees are given about the mapping between ID values and elements outside the scope of a single transaction. For example, using an `elementId` to `MATCH` an element across different transactions is risky.
5	Bookmarks are used to enforce an ordering to transactions. For more information, see Coordinate transactions and enforce causal consistency.

Literal line breaks are not allowed inside Cypher statements submitted through the API (as per JSON specifications). This means that queries should fit on a single line. You can replace line breaks with spaces, as Cypher parses them equivalently.

Query parameters

Avoid hardcoding parameters directly into queries. Instead, always use placeholders and specify the Cypher parameters within a parameters object in the body of the request.

The benefits of using query parameters are twofold:

Performance: Neo4j compiles and caches query plans, but can only do so if the query structure is unchanged.
Security: if using user input in queries, parameters protect against Cypher injections.

Good practice — Use query parameters

{
  "statement": "MERGE (n:Person {name: $name, age: $age}) RETURN n",
  "parameters": {
    "name": "Alice",
    "age": 42
  }
}

Bad practice — Embed literals in query

{
  "statement": "MERGE (n:Person {name: 'Alice', age: 42}) RETURN n",
}

For general information on parameters, see Cypher Manual → Parameters.

Server notifications

If the server generates any notifications, they will be returned in the notifications key of the response object (as a list). Notifications include recommendations for performance improvements, warnings about the usage of deprecated features, and other hints about sub-optimal usage of Neo4j.

Example request

POST http://localhost:7474/db/neo4j/query/v2
Authorization: Basic bmVvNGo6dmVyeXNlY3JldA==
Content-Type: application/json

{
  "statement": "MATCH p=shortestPath((:Person {name: $from})-[*]->(:Person {name: $to})) RETURN p",
  "parameters": {
    "from": "Alice",
    "to": "Bob"
  }
}

Example response

202: Accepted
Content-Type: application/json

{
  "data": [
    ...
  ],
  "notifications": [
    {
      "code": "Neo.ClientNotification.Statement.UnboundedVariableLengthPattern",
      "description": "Using shortest path with an unbounded pattern will likely result in long execution times. It is recommended to use an upper limit to the number of node hops in your pattern.",
      "severity": "INFORMATION",
      "title": "The provided pattern is unbounded, consider adding an upper limit to the number of node hops.",
      "position": {
          "offset": 21,
          "line": 1,
          "column": 22
      },
      "category": "PERFORMANCE"
    }
  ],
  ...
}

Glossary

Aura: Aura is Neo4j’s fully managed cloud service. It comes with both free and paid plans.
Cypher: Cypher is Neo4j’s graph query language that lets you retrieve data from the database. It is like SQL, but for graphs.
ACID: Atomicity, Consistency, Isolation, Durability (ACID) are properties guaranteeing that database transactions are processed reliably. An ACID-compliant DBMS ensures that the data in the database remains accurate and consistent despite failures.
causal consistency: A database is causally consistent if read and write queries are seen by every member of the cluster in the same order. This is stronger than eventual consistency.
transaction: A transaction is a unit of work that is either committed in its entirety or rolled back on failure. An example is a bank transfer: it involves multiple steps, but they must all succeed or be reverted, to avoid money being subtracted from one account but not added to the other.