查询数据库

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

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

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

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

目前无法通过查询 API 控制事务的生命周期。如果您需要这种灵活性，请查看 HTTP API 和语言库。

每个请求必须包含一个 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	书签用于对事务进行排序。有关更多信息，请参阅协调事务并强制因果一致性。

不允许在通过 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 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: 原子性、一致性、隔离性、持久性 (ACID) 是保证数据库事务可靠处理的属性。符合 ACID 的 DBMS 确保数据库中的数据即使在发生故障时也能保持准确一致。
因果一致性: 如果读取和写入查询在集群的每个成员上以相同的顺序出现，则数据库就是因果一致的。这比最终一致性更强。
事务: 事务是一项工作单元，该单元要么完全提交，要么在发生故障时回滚。例如，银行转账：它涉及多个步骤，但它们必须全部成功或被还原，以避免从一个帐户中扣除资金，而没有添加到另一个帐户中。