运行事务

使用事务将相关的查询组合在一起，共同完成单个逻辑数据库操作。由于 Neo4j 符合 ACID 标准，事务内的查询要么作为一个整体执行，要么完全不执行：不可能出现事务部分成功而另一部分失败的情况。

显式事务仅在 Aura 和单实例自托管服务器上可用。如果您正在运行自托管集群，则需要实现自己的方法，以便属于同一事务的请求被路由到同一个集群成员。

包含 CALL {} IN TRANSACTIONS 的 Cypher 查询不能在显式事务中执行。请使用隐式事务提交这些查询。

创建事务

要打开一个新的（显式）事务，请向以下端点提交 POST 请求

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

<host> 是 Neo4j 实例所在的位置（例如：localhost, xxx.databases.neo4j.io），
<port> 是 Neo4j HTTP 服务器监听的端口（可选；默认 7474），
<databaseName> 是您要查询的数据库（例如：neo4j）。

每个请求必须包含一个 Authorization 请求头，有关详细信息，请参阅授权请求。

请求体可以

包含一个带有要执行的 Cypher 查询的 statement 对象
包含一个空的 statement 对象
完全为空。

后两种选择用于防止事务超时。
服务器将以新事务的位置进行响应。

请求示例

POST https://:7474/db/neo4j/query/v2/tx
Accept: application/json
Authorization: Basic bmVvNGo6dmVyeXNlY3JldA==
Content-Type: application/json

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

示例响应

202: Accepted  (1)
Content-Type: application/json
neo4j-cluster-affinity: MTAuOC41Ljc6MTc0NzQ=  (2)

{
  "data": {
    "fields": [  (3)
      "alice"
    ],
    "values": [  (4)
      [
        {
          "elementId": "4:ff04df25-ff2b-4b55-98f8-6888297b025e:0",  (5)
          "labels": [
            "Person"
          ],
          "properties": {
            "name": "Alice",
            "age": 42
          }
        }
      ]
    ]
  },
  "bookmarks": [  (6)
    "FB:kcwQ/wTfJf8rS1WY+GiIKXsCXgmQ"
  ],
  "transaction": {  (7)
    "id": "lyU",
    "expires": "2024-10-22T15:48:29Z"
  }
}

1	由于服务器在发送 HTTP 状态码时无法预知请求是否会成功，因此无论语句是否成功执行，所有 API 请求均返回 `202` 状态码。唯一的例外是认证错误，会返回 `401` 状态码。
2	`neo4j-cluster-affinity` 请求头仅由 Aura 实例返回，用于标识处理该事务的集群成员。它必须作为后续所有请求（包括提交/回滚请求）的请求头包含在内。
3	查询结果键。
4	查询返回的每个结果的值。每个单独的结果值顺序与 `fields` 相同。有关值格式的更多信息，请参阅纯 JSON 和类型化 JSON。
5	数据库内的实体 ID。请谨慎使用 `elementId`，因为不保证 ID 值与单个事务范围之外的元素之间的映射关系。例如，使用 `elementId` 在不同事务之间 `MATCH` 元素是有风险的。
6	书签 (Bookmarks) 用于强制执行事务的顺序。有关更多信息，请参阅协调事务并强制因果一致性。
7	事务元数据。请将该 ID 用于后续请求的 URI。

执行查询

事务打开后，您可以通过向以下端点发送更多 POST 请求来向其提交查询

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

您可以在首次请求结果的 transaction.id 键下找到事务 ID。

如果使用 Aura 实例，请求必须包含 neo4j-cluster-affinity 请求头，并重发服务器在打开事务时发送的值。

请求示例

POST https://:7474/db/neo4j/query/v2/tx/lyU
Accept: application/json
Authorization: Basic bmVvNGo6dmVyeXNlY3JldA==
Content-Type: application/json
neo4j-cluster-affinity: MTAuOC41Ljc6MTc0NzQ=

{
  "statement": "MERGE (n:Person {name: $name, age: $age}) RETURN n AS bob",
  "parameters": {
    "name": "Bob",
    "age": 43
  }
}

示例响应

202: Accepted
Content-Type: application/json

{
  "data": {
    "fields": [
      "bob"
    ],
    "values": [
      [
        {
          "elementId": "4:ff04df25-ff2b-4b55-98f8-6888297b034e:0",
          "labels": [
            "Person"
          ],
          "properties": {
            "name": "Bob",
            "age": 43
          }
        }
      ]
    ]
  },
  "bookmarks": [
    "FB:kcwQ/wTfJf8rS1WY+GiIKXsCXgmQ"
  ],
  "transaction": {
    "id": "lyU",
    "expires": "2024-10-22T15:48:29Z"
  }
}

事务过期与保持活跃

事务在一段不活动时间后会自动过期，随后将被回滚。默认超时时间为 60 秒，但您可以在服务器配置中设置不同的值（server.queryapi.transaction_idle_timeout）。

事务过期时间将在每次响应中报告，位于 transaction 键下。要保持事务活跃而不提交新查询，您可以向事务 URI 提交一个空语句。

尝试向已过期的事务提交查询会导致错误

{
  "errors": [ {
    "code": "Neo.ClientError.Request.Invalid",
    "message": "Transaction with Id: \"lyU\" was not found. It may have timed out and therefore rolled back or the routing header 'neo4j-cluster-affinity' was not provided."
  } ]
}

如果响应中不包含 transaction 键，则相应的事务已关闭。这通常在大多数错误发生后出现。

提交事务

要提交事务，请向以下端点发送 POST 请求

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

提交事务会使更改在数据库中永久生效。

该请求可以选择包含一个最终的 statement 对象，它会在关闭事务之前执行。

请求示例

POST https://:7474/db/neo4j/query/v2/tx/lyU/commit
Accept: application/json
Authorization: Basic bmVvNGo6dmVyeXNlY3JldA==
Content-Type: application/json
neo4j-cluster-affinity: MTAuOC41Ljc6MTc0NzQ=

示例响应

202: Accepted
Content-Type: application/json

{
    "bookmarks": [
        "FB:kcwQrwI41VhBRoiBLch+ikTikQKQ"
    ]
}

回滚事务

要回滚事务，请向以下端点提交 DELETE 请求

https://:7474/db/neo4j/tx/query/v2/<transactionID>

当事务回滚时，数据库的状态将恢复到事务打开之前的状态。因此，您的查询对数据库所做的所有更改都将被丢弃。

请求示例

DELETE https://:7474/db/neo4j/query/v2/tx/lyU
Accept: application/json
Authorization: Basic bmVvNGo6dmVyeXNlY3JldA==
neo4j-cluster-affinity: MTAuOC41Ljc6MTc0NzQ=

示例响应

202: Accepted
Content-Type: application/json

打开事务时的身份验证失败

对打开的事务的请求中出现身份验证错误 (Neo.ClientError.Security.Unauthorized) 会导致回滚。但事务本身仍然保持打开状态。

术语表

Aura: Aura 是 Neo4j 的全托管云服务。它提供免费和付费计划。
Cypher: Cypher 是 Neo4j 的图查询语言，允许您从数据库中检索数据。它类似于 SQL，但专门用于图数据。
ACID: 原子性 (Atomicity)、一致性 (Consistency)、隔离性 (Isolation)、持久性 (Durability) (ACID) 是保证数据库事务可靠处理的属性。符合 ACID 的 DBMS 确保即使发生故障，数据库中的数据也能保持准确和一致。
因果一致性: 如果集群的每个成员都以相同的顺序看到读写查询，则该数据库具有因果一致性。这比最终一致性更强。
事务: 事务是一个工作单元，要么被提交，要么在失败时被回滚。例如银行转账：它涉及多个步骤，但它们必须全部成功或全部撤销，以避免钱从一个账户扣除却未存入另一个账户的情况。