查询数据库

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

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

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

服务器会将您提交的 Cypher 查询包装在（隐式）事务中。这意味着，如果查询的任何部分失败，数据库将回滚到查询执行之前的状态。要运行显式事务，请参阅运行事务。

每个请求都必须包含 Authorization 请求头，有关更多信息，请参阅授权请求。

请求示例

POST http://localhost:7474/db/neo4j/query/v2
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

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

1	因为服务器在发送 HTTP 状态码时无法预知请求是否会成功，所以所有 API 请求都会返回 `202` 状态码，无论语句是否成功执行。唯一的例外是身份验证错误，它会导致 `401` 状态码。
2	查询结果键。
3	查询返回的每个结果的查询结果值。每个单独的结果值与 `fields` 的顺序相同。有关值可能采用的格式的更多信息，请参阅结果格式与数据类型。
4	数据库中的实体 ID。请谨慎使用 `elementId`，因为在单个事务范围之外，ID 值与元素之间的映射不作任何保证。例如，在不同事务中使用 `elementId` 来 `MATCH` 元素存在风险。
5	书签用于强制事务的排序。有关更多信息，请参阅协调事务并强制因果一致性。

根据 JSON 规范，通过 API 提交的 Cypher 语句中不允许使用字面换行符。这意味着查询应在一行内。您可以用空格替换换行符，因为 Cypher 对它们的解析效果相同。

查询参数

避免将参数直接硬编码到查询中。相反，请始终使用占位符，并在请求正文中的 parameters 对象内指定 Cypher 参数。

使用查询参数的好处有两方面

性能：Neo4j 会编译并缓存查询计划，但前提是查询结构保持不变。
安全性：如果在查询中使用用户输入，参数可以防止 Cypher 注入。

最佳实践 — 使用查询参数

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

不良实践 — 在查询中嵌入字面值

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

有关参数的更多一般信息，请参阅Cypher 手册 → 参数。

服务器通知

如果服务器生成任何通知，它们将作为列表在响应对象的 notifications 键中返回。通知包括性能改进建议、有关使用弃用功能的警告以及有关 Neo4j 次优使用的其他提示。

请求示例

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

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

响应示例

202: Accepted
Content-Type: application/json

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

术语表

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