查询数据库
Aura 上不可用在 5.26 中已弃用

事务性 HTTP API 已废弃，已被 HTTP 查询 API 取代。请参阅查询 API → 查询数据库了解如何使用查询 API 运行查询的详细信息。

要在数据库上运行查询，请向以下端点发送 POST 请求

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

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

服务器会自动为您将提交的 Cypher 查询包装在一个（隐式）事务中。这意味着如果查询的任何部分失败，数据库将回滚到执行查询前的状态。要控制事务的生命周期，请参阅运行事务。

每个请求必须包含 Authorization 头部，更多信息请参阅身份验证与授权。

请求示例

POST https://:7474/db/neo4j/tx/commit
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
      }
    }
  ]
}

示例响应

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": [],
  "lastBookmarks": [
    "FB:kcwQDqShCDLFSYyZ55XMZ6tffRuQ"
  ]
}

通过 API 提交的 Cypher 语句中不允许出现字面换行符（符合 JSON 规范）。这意味着查询应写在同一行。您可以将换行符替换为空格，因为 Cypher 对它们的解析是等价的。

查询参数

不要将参数硬编码或直接拼接到查询中。请始终使用占位符并指定 Cypher 参数。这是为了

性能优势：Neo4j 会编译并缓存查询，但前提是查询结构保持不变；
出于安全考虑：请参阅防止 Cypher 注入。

做 — 使用查询参数

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

不要 — 在查询中嵌入字面量

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

更多信息请参阅 Cypher 手册 → 参数。

执行多个查询

您可以在同一请求中发送多个 Cypher 语句。服务器会按顺序执行它们，但彼此相互独立，因而一个语句不能引用其他语句中定义的变量。响应按顺序包含每个语句的结果。

请求示例

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

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

示例响应

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": [],
  "lastBookmarks": [
    "FB:kcwQDqShCDLFSYyZ55XMZ6tffRuQ"
  ]
}

如果其中一个查询失败，所有语句 都会随请求一起回滚。 在下面的示例中，第二条语句因除以 0 而失败。结果是既没有创建 :Number 节点（甚至连 val: 1 那个也没有），也没有创建 :Person 节点。

请求示例

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

{
  "statements": [
    {
      "statement": "MERGE (p:Person {name: $name}) RETURN p",
      "parameters": {
        "name": "Bob"
      }
    },
    {
      "statement": "UNWIND [1, 0] AS i MERGE (n:Number {val: 1/i}) RETURN n"
    },
  ]
}

示例响应

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

{
  "results": [ {
    "columns": [ "p" ],
    "data": [ {
      "row": [ {
        "name": "Bob"
      } ],
      "meta": [ {
        "id": 8,
        "elementId": "4:0ea4a108-32c5-498c-99e7-95cc67ab5f7d:8",
        "type": "node",
        "deleted": false
      } ]
    ] }
  ] },
  {
    "columns": [ "n" ],
    "data": [ {
      "row": [ {
        "val": 1
      } ],
      "meta": [ {
        "id": 1,
        "elementId": "4:0ea4a108-32c5-498c-99e7-95cc67ab5f7d:1",
        "type": "node",
        "deleted": false
      } ]
    } ]
  } ],
  "errors": [ {
    "code": "Neo.ClientError.Statement.ArithmeticError",
    "message": "/ by zero"
  } ]
}

带有 `CALL {} IN TRANSACTIONS` 的查询

对使用 Cypher 子句 CALL {} IN TRANSACTIONS 的查询需格外小心。因为这些查询会自行生成额外的事务，可能会因与外围事务的交互而产生意外行为。

回滚行为

虽然任何语句的失败都会导致请求中所有语句回滚，但使用 CALL {} IN TRANSACTIONS 的语句除外。由于该子句创建的事务会独立提交，服务器无法在其他部分失败时将其回滚。

在下面的示例中，即使第二条语句因除零错误而执行失败，第一条语句仍不会被回滚。结果是创建了两个新的 :Person 节点。

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

{
  "statements": [
    {
      "statement": "UNWIND ['Sofia', 'Greg'] AS name CALL { WITH name CREATE (:Person {name: name}) } IN TRANSACTIONS OF 1 ROWS RETURN name"
    },
    {
      "statement": "UNWIND [1, 0] AS i MERGE (n:Number {val: 1/i}) RETURN n"
    },
  ]
}

查询顺序

包含 CALL {} In TRANSACTIONS 的查询必须在 statements JSON 列表中位列首位。未满足此要求将导致错误。

请求示例

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

{
  "statements": [
    {
      "statement": "MERGE (p:Person {name: $name}) RETURN p.name",
      "parameters": {
        "name": "Bob"
      }
    },
    {
      "statement": "UNWIND [1, 0] AS i CALL { WITH i MERGE (:Number {val: 1/i}) } IN TRANSACTIONS OF 1 ROWS RETURN i"
    },
  ]
}

示例响应

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

{
  "results": [ {
    "columns": [ "p.name" ],
    "data": [ {
      "row": [ "Bob" ],
      "meta": [ null ]
    }]
  },
  {
    "columns": [ "i" ],
    "data": []
  } ],
  "errors": [ {
    "code": "Neo.DatabaseError.Statement.ExecutionFailed",
    "message": "Expected transaction state to be empty when calling transactional subquery. (Transactions committed: 0)"
  } ]
}

服务器通知

如果服务器生成任何通知，它们将作为列表出现在响应对象的 notifications 键中。通知包括性能改进建议、对已弃用特性的使用警告以及其他关于 Neo4j 非最佳使用方式的提示。

请求示例

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

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

示例响应

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

{
  "results": [
    ...
  ],
  "notifications": [
    {
      "code": "Neo.ClientNotification.Statement.UnboundedVariableLengthPattern",
      "severity": "INFORMATION",
      "title": "The provided pattern is unbounded, consider adding an upper limit to the number of node hops.",
      "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.",
      "position": {
        "offset": 21,
        "line": 1,
        "column": 22
      }
    }
  ],
  ...
}

术语表

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

查询数据库Aura 上不可用在 5.26 中已弃用

请求示例

示例响应

查询参数

执行多个查询

请求示例

示例响应

请求示例

示例响应

带有 CALL {} IN TRANSACTIONS 的查询

回滚行为

查询顺序

请求示例

示例响应

服务器通知

请求示例

示例响应

术语表

查询数据库
Aura 上不可用在 5.26 中已弃用

带有 `CALL {} IN TRANSACTIONS` 的查询