结果格式
Aura 上不可用在 5.26 中已弃用

事务型 HTTP API 已弃用，已被 HTTP Query API 替代。请参阅查询 API → 纯 JSON 和查询 API → 类型化 JSON 了解如何使用查询 API 以不同格式获取查询结果的详细信息。

响应可以以三种格式返回查询数据：JSON、Jolt 或图形。

JSON

JSON 格式是默认格式，返回的 JSON 中包含一个嵌入的 results 元素。要请求此格式，请在请求头中设置 Accept: application/json（或者根本不指定，因为如果未提供 Accept 头，它会默认使用此格式）。

JSON 输出格式原型

{
  "results": [
    {
      "columns": [ columns-list ], (1)
      "data": [
        {
          "row": [ row-data ],  (2)
          "meta": [ entities-metadata ]  (3)
        },
      ]
    },
    {
     //another statement's results
    }
  ]
}

1	查询字段，即返回对象的键
2	查询结果（内部结构取决于对象类型）
3	每个返回实体（节点/关系）的元数据

请求示例

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 AS person",
      "parameters": {
          "name": "Phil"
      }
    }
  ]
}

示例响应

{
  "results": [ {
    "columns": [ "person" ],
    "data": [ {
      "row": [ {
        "name": "Phil"
      } ],
      "meta": [ {
        "id": 11,  (1)
        "elementId": "4:b7c0e943-1e73-474b-8ddc-e8ff3ae74cdd:11",  (2)
        "type": "node",  (3)
        "deleted": false  (4)
      } ]
    } ]
  } ],
  // other transactional data
}

1	（已弃用）数据库中的实体 ID
2	数据库中的实体 ID
3	实体类型
4	实体在查询中是否被删除（在对其执行 Cypher `DELETE` 后返回实体时为 `true`）

elementId 应谨慎使用，因为在单个事务范围之外，ID 值与元素之间的映射没有任何保证。换言之，在不同事务之间使用 elementId 来 MATCH 元素是有风险的。

Jolt

Jolt（全称 JSON Bolt）是一种基于 JSON 的格式，它在单例对象中将响应值的类型与值本身一起封装。

例如，{"Z": "2"} 将值 2 标记为整数类型。

要以此格式接收结果，请按如下方式设置 Accept 头

Accept: application/vnd.neo4j.jolt-v2

容器格式

Jolt 结果以基于事件的容器格式返回。典型的响应如下所示

{"header":{"fields":["name","age"]}}
{"data":[{"U":"Bob"},{"Z":"30"}]}
{"data":[{"U":"Alice"},{"Z":"40"}]}
{"data":[{"U":"Eve"},{"Z":"50"}]}
...
{"summary":{}}
{"info":{"commit":"commit/uri/1"}}

表 1. 容器格式对象
Event	函数
`header（标题行）`	标记语句的结果集开始，并包含查询字段。
`data`	每条返回记录对应的对象。每个查询可能返回多个 `data` 对象。数组中值的顺序与标题中接收到的字段顺序相匹配。
`summary`	标记语句的结果集结束。如果请求了查询计划信息，则包含该信息。
`info`	在处理完所有语句后出现的最终事件（除非发生错误）。包含事务信息（例如提交 URI、书签）。
`错误 (error)`	事务处理期间出现的错误。

换行符分隔模式和 JSON 序列模式

默认情况下，Jolt 以 换行符分隔模式 返回。在此模式下，每个事件都是一个独立的 JSON 文档，之间用单个 LF（换行符，UTF 编码：0x8A）分隔。

换行符分隔模式编码示例

{"header":{"fields":["result"]}}\n
{"data":[{"Z":"1"}]}\n
{"summary":{}}\n
{"info":{}}\n

API 也可以以 JSON 序列模式 返回（编码方式遵循 RFC 7464）。要实现该模式，请按如下方式设置 Accept 头

Accept: application/vnd.neo4j.jolt-v2+json-seq

在此模式下，每个事件在文档开头用 RS（记录分隔符/信息分隔符二，UTF-8 编码：0x1E）字符封装，并在文档结尾加上 LF 字符。

JSON 序列模式编码示例

\u001E{"header":{"fields":["result"]}}\n
\u001E{"data":[{"Z":"1"}]}\n
\u001E{"summary":{}}\n
\u001E{"info":{}}\n

稀疏模式与严格模式

默认情况下，Jolt 以 稀疏模式 返回数据，这种模式会省略可以匹配到 JSON 类型的值的类型配对。

在 严格模式 下，所有值都会与其类型配对。要启用 严格模式，在 Accept 头后追加 ;strict=true

Accept: application/vnd.neo4j.jolt-v2;strict=true

Accept: application/vnd.neo4j.jolt-v2+json-seq;strict=true

有关类型匹配的信息，请参阅 Jolt 类型。

请求中的多个结果集

当单个请求中包含多个查询时，每个查询都会产生多个 header、data 与 summary 输出。结果集按照请求中指定的顺序返回。

请求示例

POST https://:7474/db/neo4j/tx/commit
Accept: application/vnd.neo4j.jolt-v2
Content-Type: application/json
Authorization: Basic bmVvNGo6dmVyeXNlY3JldA==

{
  "statements": [
    { "statement": "RETURN 1 AS resultA" },
    { "statement": "UNWIND range(1,3,1) AS resultB RETURN resultB" }
  ]
}

示例响应

200: OK
Content-Type: application/vnd.neo4j.jolt-v2

{"header":{"fields":["resultA"]}}
{"data":[{"Z":"1"}]}
{"summary":{}}
{"header":{"fields":["resultB"]}}
{"data":[{"Z":"1"}]}
{"data":[{"Z":"2"}]}
{"data":[{"Z":"3"}]}
{"summary":{}}
{"info":{}}

Jolt 类型

本节详细说明了 Cypher 类型在 Jolt 中的标记方式。

基础类型

类型标签类型示例

类型标签	类型	示例
(N/A)	null	`null`
`?`	布尔值	`{"?": "true"}`
`Z`	整数	`{"Z": "123"}`
`R`	浮点数	`{"R": "9.87"}` ^[1]
`U`	字符串	`{"U": "Neo4j"}`
`T`	Temporal (时间类型)	`{"T": "2023-08-09T09:02:40.063Z"}` `{"T": "2023-08-09"}` `{"T": "09:02:40.063Z"}` `{"T": "P14DT16H12M"}`
`@`	Spatial (空间类型)	`{"@": "SRID=4326;POINT(1.2 3.4)"}` `{"@": "SRID=4979;POINT Z (3.4 5.6 7.8)"}`
`#`	十六进制	`{"#": "FA08"}`
1. 类型标签 `R` 同时用于指示浮点数以及超出 32 位有符号整数范围的整数。

(N/A)

null

null

?

布尔值

{"?": "true"}

Z

整数

{"Z": "123"}

R

浮点数

{"R": "9.87"} ^[1]

U

字符串

{"U": "Neo4j"}

T

Temporal (时间类型)

{"T": "2023-08-09T09:02:40.063Z"}
{"T": "2023-08-09"}
{"T": "09:02:40.063Z"}
{"T": "P14DT16H12M"}

@

Spatial (空间类型)

{"@": "SRID=4326;POINT(1.2 3.4)"}
{"@": "SRID=4979;POINT Z (3.4 5.6 7.8)"}

#

十六进制

{"#": "FA08"}

1. 类型标签 R 同时用于指示浮点数以及超出 32 位有符号整数范围的整数。

复合类型

类型标签类型示例

类型标签	类型	示例
`[]`	列表	`{"[]": [{"Z": "123"}, … ]}`
`{}`	Map	`{"{}": {"name": {"U": "Jeff"}, …}}`

[]

列表

{"[]": [{"Z": "123"}, … ]}

{}

Map

{"{}": {"name": {"U": "Jeff"}, …}}

实体类型

节点

{"()": [node_id, [ node_labels], {"prop1": "value1", "prop2": "value2"}]}

请求示例

POST https://:7474/db/neo4j/tx/commit
Accept: application/vnd.neo4j.jolt-v2
Content-Type: application/json
Authorization: Basic bmVvNGo6dmVyeXNlY3JldA==

{
  "statements": [
    {
      "statement": "MERGE (p:Person:Employee {name: 'Phil', age: 21}) RETURN p"
    }
  ]
}

示例响应

200: OK
Content-Type: application/vnd.neo4j.jolt-v2

{
  "header": {
    "fields": [
      "p"
    ]
  }
}
{
  "data": [
    {
      "()": [
        "4:b7c0e943-1e73-474b-8ddc-e8ff3ae74cdd:12",
        [
          "Person",
          "Employee"
        ],
        {
          "name": "Phil",
          "age": 21
        }
      ]
    }
  ]
}
{
  "summary": {}
}
{
  "info": {
    "lastBookmarks": [
      "FB:kcwQt8DpQx5zR0uN3Oj/OudM3ReQ"
    ]
  }
}

关系

{"->": [rel_id, start_node_id, rel_type, end_node_id, {properties}]}
{"<-": [rel_id, end_node_id, rel_type, start_node_id, {properties}]}

请求示例

POST https://:7474/db/neo4j/tx/commit
Accept: application/vnd.neo4j.jolt-v2
Content-Type: application/json
Authorization: Basic bmVvNGo6dmVyeXNlY3JldA==

{
  "statements": [
    {
      "statement": "MERGE (:Person:Employee {name: 'Phil', age: 21})-[rel:KNOWS {since: 1999}]->(:Person {name: 'Lucy', age: 20}) RETURN rel"
    }
  ]
}

示例响应

200: OK
Content-Type: application/vnd.neo4j.jolt-v2

{
  "header": {
    "fields": [
      "rel"
    ]
  }
}
{
  "data": [
    {
      "->": [
        "5:b7c0e943-1e73-474b-8ddc-e8ff3ae74cdd:7",
        "4:b7c0e943-1e73-474b-8ddc-e8ff3ae74cdd:12",
        "KNOWS",
        "4:b7c0e943-1e73-474b-8ddc-e8ff3ae74cdd:13",
        {
          "since": 1999
        }
      ]
    }
  ]
}
{
  "summary": {}
}
{
  "info": {
    "lastBookmarks": [
      "FB:kcwQt8DpQx5zR0uN3Oj/OudM3ReQ"
    ]
  }
}

路径

{"..": [{node_1}, {rel_1}, {node_2}, ..., {node_n}, {rel_n}, {node_n+1}]}

请求示例

POST https://:7474/db/neo4j/tx/commit
Accept: application/vnd.neo4j.jolt-v2
Content-Type: application/json
Authorization: Basic bmVvNGo6dmVyeXNlY3JldA==

{
  "statements": [
    {
      "statement": "MERGE path=(:Person:Employee {name: 'Phil', age: 21})-[:KNOWS {since: 1999}]->(:Person {name: 'Lucy', age: 20}) RETURN path"
    }
  ]
}

示例响应

200: OK
Content-Type: application/vnd.neo4j.jolt-v2

{
  "header": {
    "fields": [
      "path"
    ]
  }
}
{
  "data": [
    {
      "..": [
        {
          "()": [
            "4:b7c0e943-1e73-474b-8ddc-e8ff3ae74cdd:12",
            [
              "Person",
              "Employee"
            ],
            {
              "name": "Phil",
              "age": 21
            }
          ]
        },
        {
          "->": [
            "5:b7c0e943-1e73-474b-8ddc-e8ff3ae74cdd:7",
            "4:b7c0e943-1e73-474b-8ddc-e8ff3ae74cdd:12",
            "KNOWS",
            "4:b7c0e943-1e73-474b-8ddc-e8ff3ae74cdd:13",
            {
              "since": 1999
            }
          ]
        },
        {
          "()": [
            "4:b7c0e943-1e73-474b-8ddc-e8ff3ae74cdd:13",
            [
              "Person"
            ],
            {
              "name": "Lucy",
              "age": 20
            }
          ]
        }
      ]
    }
  ]
}
{
  "summary": {}
}
{
  "info": {
    "lastBookmarks": [
      "FB:kcwQt8DpQx5zR0uN3Oj/OudM3ReQ"
    ]
  }
}

图形

图形格式会汇总结果中所有列的节点和关系，并且会将节点、关系以及路径的集合进行扁平化。此格式有助于了解查询返回的节点和关系的图结构。

请求示例

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

{
  "statements": [
    {
      "statement": "CREATE (bike:Bike {weight: 10}) CREATE (frontWheel:Wheel {spokes: 3}) CREATE (backWheel:Wheel {spokes: 32}) CREATE p1 = (bike)-[:HAS {position: 1}]->(frontWheel) CREATE p2 = (bike)-[:HAS {position: 2} ]->(backWheel) RETURN bike, p1, p2",
      "resultDataContents": ["graph"]
    }
  ]
}

示例响应

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

{
  "results": [ {
    "columns": [
      "bike",
      "p1",
      "p2"
    ],
    "data": [ {
      "graph": {
        "nodes": [
          {
            "id": "17",
            "elementId": "4:b7c0e943-1e73-474b-8ddc-e8ff3ae74cdd:17",
            "labels": [ "Wheel" ],
            "properties": { "spokes": 3 }
          },
          {
            "id": "18",
            "elementId": "4:b7c0e943-1e73-474b-8ddc-e8ff3ae74cdd:18",
            "labels": [ "Wheel" ],
            "properties": { "spokes": 32 }
          },
          {
            "id": "16",
            "elementId": "4:b7c0e943-1e73-474b-8ddc-e8ff3ae74cdd:16",
            "labels": [ "Bike" ],
            "properties": { "weight": 10 }
          }
        ],
        "relationships": [
          {
            "id": "9",
            "elementId": "5:b7c0e943-1e73-474b-8ddc-e8ff3ae74cdd:9",
            "type": "HAS",
            "startNode": "16",
            "startNodeElementId": "4:b7c0e943-1e73-474b-8ddc-e8ff3ae74cdd:16",
            "endNode": "17",
            "endNodeElementId": "4:b7c0e943-1e73-474b-8ddc-e8ff3ae74cdd:17",
            "properties": { "position": 1 }
          },
          {
            "id": "10",
            "elementId": "5:b7c0e943-1e73-474b-8ddc-e8ff3ae74cdd:10",
            "type": "HAS",
            "startNode": "16",
            "startNodeElementId": "4:b7c0e943-1e73-474b-8ddc-e8ff3ae74cdd:16",
            "endNode": "18",
            "endNodeElementId": "4:b7c0e943-1e73-474b-8ddc-e8ff3ae74cdd:18",
            "properties": { "position": 2 }
          }
        ]
      }
    } ]
  } ],
  "errors": [],
  "commit": "https://:7474/db/neo4j/tx/14/commit",
  "transaction": {
      "expires": "Wed, 9 Aug 2023 08:08:35 GMT"
  }
}

您也可以将默认返回格式与图形格式组合使用。要实现此目的，请设置 "resultDataContents": ["row", "graph"] 。

由于图形格式与结果主体的编码方式无关，它可以与 JSON 或 Jolt 的 Accept 头一起使用。

结果格式Aura 上不可用在 5.26 中已弃用

JSON

请求示例

示例响应

Jolt

容器格式

换行符分隔模式和 JSON 序列模式

稀疏模式与严格模式

请求中的多个结果集

请求示例

示例响应

Jolt 类型

基础类型

复合类型

实体类型

请求示例

示例响应

请求示例

示例响应

请求示例

示例响应

图形

请求示例

示例响应

结果格式
Aura 上不可用在 5.26 中已弃用