Run transactions

Use transactions to group together related queries which work together to achieve a single logical database operation. As Neo4j is ACID compliant, queries within a transaction will either be executed as a whole or not at all: you cannot get a part of the transaction succeed and another fail.

Cypher queries with CALL {} IN TRANSACTIONS can not be executed in explicit transactions. Submit those queries with implicit transactions instead.

Create a transaction

To open a new (explicit) transaction, submit a POST request to the following endpoint:

http://<host>:<port>/db/<databaseName>/tx

The body of the request may either:

contain a statements object consisting of a list of statements to execute (example below)
contain a statements object consisting of an empty list
be entirely empty.

The server will respond with the location of the new transaction.

Example request

POST http://localhost:7474/db/neo4j/tx
Accept: application/json;charset=UTF-8
Content-Type: application/json
Authorization: Basic bmVvNGo6dmVyeXNlY3JldA==

{
  "statements": [
    {
      "statement": "MERGE (n:Person {name: $name, age: $age}) RETURN n",
      "parameters": {
        "name": "Patrick",
        "age": 24
      }
    }
  ]
}

Example response

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

{
  "results": [],
  "errors": [],
  "commit": "http://localhost:7474/db/neo4j/tx/50/commit",
  "transaction": {
    "expires": "Thu, 3 Aug 2023 11:45:10 GMT"
  }
}

Execute queries

Once a transaction is open, you can submit queries to it by sending more POST requests to the following endpoint:

http://<host>:<port>/db/<databaseName>/tx/<transactionID>

You can find the transaction ID under the commit key of your first request result.

Example request

POST http://localhost:7474/db/neo4j/tx/50
Accept: application/json;charset=UTF-8
Content-Type: application/json
Authorization: Basic bmVvNGo6dmVyeXNlY3JldA==

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

Example response

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

{
  "results": [ {
    "columns": ["n"],
    "data": [ {
      "row": [ {
        "name": "Alice",
        "age": 42
      } ],
      "meta": [ {
        "id": 36,
        "elementId": "4:0ea4a108-32c5-498c-99e7-95cc67ab5f7d:36",
        "type": "node",
        "deleted": false
      } ]
    } ]
  } ],
  "errors": [],
  "commit": "http://localhost:7474/db/neo4j/tx/50/commit",
  "transaction": {
    "expires": "Thu, 3 Aug 2023 11:45:20 GMT"
  }
}

Execute multiple queries

To reduce the number of requests and network overhead, you can include multiple statements within a single request. The server runs them in sequence, but separate from each other, so a statement cannot reference a variable defined in another statement. The response contains the result of each statement, in order.

Example request

POST http://localhost:7474/db/neo4j/tx/50
Accept: application/json;charset=UTF-8
Content-Type: application/json
Authorization: Basic bmVvNGo6dmVyeXNlY3JldA==

{
  "statements": [
    { "statement": "RETURN 1" },
    { "statement": "RETURN 2" }
  ]
}

Example response

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

{
  "results": [
    {
      "columns": ["1"],
      "data": [{ "row": [1], "meta": [null] }]
    },
    {
      "columns": ["2"],
      "data": [{ "row": [2], "meta": [null] }]
    }
  ],
  "errors": [],
  "commit": "http://localhost:7474/db/neo4j/tx/50/commit",
  "transaction": {
    "expires": "Thu, 3 Aug 2023 11:45:25 GMT"
  }
}

Transaction expiration and keep alive

Transactions expire automatically after a period of inactivity, after which they are rolled back. By default the timeout is 2 seconds, but you can set a different value in the server configuration (db.transaction.timeout).

The transaction expiration time is reported in each response, under the transaction key. To keep a transaction alive without submitting new queries, you can submit an empty statement list to the transaction URI.

Attempting to submit queries to an expired transaction results in an error:

{
  "results": [],
  "errors": [ {
    "code": "Neo.ClientError.Transaction.TransactionNotFound",
    "message": "Unrecognized transaction id. Transaction may have timed out and been rolled back."
  } ]
}

If a response does not contain the transaction key, the corresponding transaction has been closed. This usually happens after an error is raised.

Commit a transaction

To commit a transaction, send a POST request to the following endpoint:

http://<host>:<port>/db/<databaseName>/tx/<transactionID>/commit

Committing a transaction results in its changes becoming permanent on the database.

The request may optionally include a final bunch of queries, which will be executed before closing the transaction.

Rollback a transaction

To rollback a transaction, submit a DELETE request to the following endpoint:

http://localhost:7474/db/neo4j/tx/<transactionID>

When a transaction is rolled back, the status of the database gets restored to before the transaction was opened. All the changes your queries would make to the database are thus discarded.

Example request

DELETE http://localhost:7474/db/neo4j/tx/50
Accept: application/json;charset=UTF-8
Authorization: Basic bmVvNGo6dmVyeXNlY3JldA==

Example response

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

{
  "results": [],
  "errors": []
}

Authentication failure on open transactions

An authentication error (Neo.ClientError.Security.Unauthorized) in a request to an open transaction results in a rollback. The transaction remains open though.

Glossary

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.