Transaction Configuration

For any transaction-initiating request (such as /tx or tx/commit), you can provide configuration options that apply for the duration of the whole transaction.

Access Mode

To ensure efficient load balancing across a cluster, it is important to label transactions that only contain READ statements with a READ access mode.

This can be done by adding an access-mode header to the request, with a value of READ.

If an access-mode configuration has not been provided, the default value is WRITE.

However, if you have clusters with Server-side routing disabled, the default value is READ.

Please note that access-mode is not required for a Neo4j single instance.

Example request

  • POST http://localhost:7474/db/neo4j/tx/commit

  • Accept: application/json;charset=UTF-8

  • Content-Type: application/json

  • Access-Mode: WRITE

{
  "statements": [
    {
      "statement": "CREATE (n) RETURN n"
    }
  ]
}

Example response

  • 200: OK

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

{
  "results" : [ {
    "columns" : [ "n" ],
    "data" : [ {
      "row" : [ { } ],
      "meta" : [ {
        "id" : 7,
        "type" : "node",
        "deleted" : false
      } ]
    } ]
  } ],
  "errors" : [ ]
}

Bookmarks

When working with a cluster, bookmarks allow you to chain transactions and enforce causal consistency.

You can add Bookmarks to the headers of a transaction initiating request. This header contains an array of strings with the encoded bookmarks. The server waits until it has caught up with the changes encapsulated in the bookmarks before executing the transaction.

In the example below, the server does not execute the transaction until it has registered the changes associated with the bookmarks FB:kcwQy9mp3ioyRom386bZDRRcuCeQ and FB:kcwQy9mp3ioyRom386bZDRRcuCiQ.

Example request

  • POST http://localhost:7474/db/neo4j/tx/commit

  • Accept: application/json;charset=UTF-8

  • Content-Type: application/json

  • Bookmarks: ["FB:kcwQy9mp3ioyRom386bZDRRcuCeQ", "FB:kcwQy9mp3ioyRom386bZDRRcuCiQ"]

{
  "statements": [
    {
      "statement": "RETURN 1 as n"
    }
  ]
}

On requests that commit a transaction (like the one above), the response includes a lastBookmarks property containing an array of encoded bookmarks, which represent the state of the transaction’s committed changes.

Example response

  • 200: OK

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

{
  "results" : [ {
    "columns" : [ "n" ],
    "data" : [ {
      "row" : [ 1 ],
      "meta" : [ null ]
    } ]
  } ],
  "errors" : [ ],
  "lastBookmarks":  ["FB:kcwQy9mp3ioyRom386bZDRRcuCSQ"]
}

You can use the bookmarks returned in the response in a subsequent transaction’s Bookmarks header, if you want to causally chain those transactions together.

Bookmarks returned by the server are not intended to be parsed or modified by the client and should simply be inserted as is into the Bookmarks header.