Coordinate transactions and enforce causal consistency

When working with a cluster, bookmarks allow you to chain transactions and enforce causal consistency. A bookmark is a token that represents some state of the database. By passing one or multiple bookmarks along with a query, the server will make sure that the query does not get executed before the represented state(s) have been established.

All responses include a bookmarks field containing a list of encoded bookmarks, which represent the state of the transaction’s committed changes.

Example response

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

You can provide a list of bookmarks to a subsequent transaction via the bookmarks key in the request body. The server waits until it has caught up with the changes encapsulated in the bookmarks before executing the submitted transaction.

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

Example request

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

{
  "statement": "MATCH (p1:Person {name: $source}) MATCH (p2:Person {name: $end}) MERGE p=(p1)-[:LIKES]->(p2) RETURN p",
  "parameters": {
    "source": "Alice",
    "end": "Lucy"
  },
  "bookmarks": ["FB:kcwQt8DpQx5zR0uN3Oj/OudM3QaQ", "FB:kcwQy9mp3ioyRom386bZDRRcuCiQ"]
}

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

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.