查询数据库

要对数据库运行查询，请向以下端点提交一个 POST 请求

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

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

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

每个请求必须包含一个 Authorization 头部，详见授权请求获取更多信息。

请求示例

POST https://: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` 相同。有关值可能采用的格式的更多信息，请参见普通 JSON 与类型化 JSON。
4	数据库中的实体 ID。请谨慎使用 `elementId`，因为对 ID 值与单个事务范围之外的元素之间的映射没有任何保证。例如，在不同事务之间使用 `elementId` 来 `MATCH` 一个元素是有风险的。
5	书签用于强制事务的顺序。有关更多信息，请参阅协调事务并强制因果一致性。

通过 API 提交的 Cypher 语句中不允许出现文字换行（依据 JSON 规范）。这意味着查询应该写在单行中。你可以将换行符替换为空格，因为 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 https://: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 确保即使发生故障，数据库中的数据也能保持准确和一致。
因果一致性: 如果集群的每个成员都以相同的顺序看到读写查询，则该数据库具有因果一致性。这比最终一致性更强。
事务: 事务是一个工作单元，要么被提交，要么在失败时被回滚。例如银行转账：它涉及多个步骤，但它们必须全部成功或全部撤销，以避免钱从一个账户扣除却未存入另一个账户的情况。