流式传输结果
引入于 2025.12

查询 API 可以通过 HTTP 将值以事件的形式进行流式传输。这使得客户端能够在数据到达时增量处理，提高内存效率，并使应用程序能够处理更大的数据集。

通过调整 Accept 请求头即可启用流式传输

对于 Plain JSON，使用 application/jsonl。
对于 Typed JSON，在后缀中添加 +jsonl。例如，application/vnd.neo4j.query.v1.1+jsonl。

为便于阅读，本页中的 JSON 对象使用换行进行格式化。实际上，每个事件都以单行表示。

对象结构

每个响应由一系列事件组成，每个事件表示为具有以下结构的 JSON 对象

{
    "$event": "Header | Record | Summary | Error",
    "_body": { /* event-specific payload */ }
}

$event — 事件类型。可能的取值有：Header、Record、Summary、Error。
_body — 特定于事件的主体。该字段的结构取决于事件类型。

客户端必须按接收的顺序消费事件。

在 HTTP/1.1 请求中，使用头部 Transfer-Encoding: chunked 以分块方式传输数据。HTTP/2 连接不需要此头部。

消息顺序

查询 API 的流式响应由按 JSON Lines 格式传输的一系列 JSON 事件组成。

事件按以下顺序发出

Header — 首先发送。定义结果结构和字段名称。
Record — 零个或多个事件，每个事件包含一行结果数据。
Summary — 在所有记录流式传输完毕后发送一次。包含执行元数据。
Error — 如果出现错误，可能在流中的任何位置出现。当发送 Error 事件时，后续将不再发送其他事件。

一旦收到 Summary 或 Error 事件，流即完成。

成功示例

Header
Record
Record
Record
Summary

{"$event":"Header","_body":{"fields":["name","age"]}}
{"$event":"Record","_body": ["Alice",32]}
{"$event":"Record","_body": ["Bob",29]}
{"$event":"Summary","_body":{"bookmarks":["FB:kcwQ/wTfJf8rS1WY+GiIKXsCXgmQ"]}}

失败示例

如果发生错误，流将在 Error 事件后立即终止。

Header
Error

{"$event":"Header","_body":{"fields":["name","age"]}}
{"$event":"Error","_body":[{"code":"Neo.ClientError.Statement.SyntaxError","message":"Invalid input 'RETURN'"}]}

事件类型

每种事件类型都有不同的负载格式。

`Header` 事件

Header 事件是流中的第一个事件。它提供关于查询结果的元数据，例如返回字段的名称和类型。还可能包含已创建事务的信息。

{
  "$event": "Header",
  "_body": {
    "fields": ["name", "age"]
  }
}

fields（可选） — 一个数组，包含后续每个 Record 事件中的列名。如果在创建事务时未运行查询，则不存在此字段。

`Record` 事件

Record 事件携带一行查询数据。每个结果行会发出一个 Record 事件。

{
  "$event": "Record",
  "_body": ["Antonio", 39]
}

{
  "$event": "Record",
  "_body": [{ "$type": "String", "_value": "Antonio" }, { "$type": "Integer",  "_value": "39" }]
}

_body — 一个数组，包含记录的字段值。顺序与 Header 事件中定义的 fields 数组相匹配。格式取决于使用的是 Plain JSON 还是 Typed JSON。

由于数据增量到达，客户端不应假设在处理之前所有的 Record 事件都已可用。

`Summary` 事件

Summary 事件标记流的结束并提供关于查询执行的元数据。

{
  "$event": "Summary",
  "_body": {
    "bookmarks": ["FB:kcwQ/wTfJf8rS1WY+GiIKXsCXgmQ"],
    "transaction": {
      "id": "lyU",
      "expires": "2024-10-22T15:48:29Z"
    },
    "notifications": [ /* notifications structure */ ],"counters": { /* counters structure */},
    "queryPlan": { /* query plan structure */ },
    "profiledQueryPlan": { /* profiled query plan structure */ }
  }
}

bookmarks（可选） — 数据库书签的列表。仅在响应表示已提交事务时出现。
transaction（可选） — 包含事务信息的对象。
notifications（可选） — 查询执行期间生成的警告或信息性消息。参见服务器通知。
counters（可选） — 关于查询所做更改的统计信息。参见检索查询计数器。
queryPlan（可选） — 逻辑查询计划。参见查询分析。
profiledQueryPlan（可选） — 详细的执行指标（若查询在启用分析时运行）。参见查询分析。

`Error` 事件

Error 事件表示在查询执行或流式传输期间发生了错误。

{
  "$event": "Error",
  "_body": [{
    "code": "Neo.ClientError.Statement.SyntaxError"
    "message": "Invalid input 'RETURN'"
  }]
}

code — Neo4j 错误码。
message — 可读的错误描述。

流式传输结果引入于 2025.12