类型化 JSON

普通 JSON 与带类型 JSON

普通 JSON 结果格式并不提供返回值的类型信息。例如，下列两个请求会得到完全相同的响应，尽管在第一个请求中返回值是 Cypher 的 STRING，而在第二个请求中返回值是 ZONED DATETIME。

{
  "statement": "RETURN '2024-01-01T21:40:32-01:00'"
}

{
  "statement": "RETURN datetime('2024-01-01T21:40:32-01:00')"
}

如果您需要知道每个返回值的具体类型，可以使用 Neo4j 的带类型信息的扩展 JSON 格式。

启用带类型的 JSON

要以带类型的 JSON 格式获取结果，请在请求头中设置 Accept: application/vnd.neo4j.query.v1.1。

在此格式中，每个返回值都是一个对象，类型信息和数值信息分别保存在不同的键中。

具有类型信息的 JSON 中的 OffsetDateTime 值示例

{
  "$type":"OffsetDateTime",
  "_value":"2024-01-01T21:40:32-01:00"
}

如果您还想使用该格式提交参数，请在请求头中设置 Content-Type: application/vnd.neo4j.query.v1.1。

示例

示例 1：参数和结果数据均采用扩展 JSON 格式

请求示例

POST https://:7474/db/neo4j/query/v2
Authorization: Basic bmVvNGo6dmVyeXNlY3JldA==
Accept: application/vnd.neo4j.query.v1.1
Content-Type: application/vnd.neo4j.query.v1.1

{
  "statement": "MERGE (p:Person {name: $name}) RETURN p AS person, p.name AS name",
  "parameters": {
    "name": {
      "$type": "String",
      "_value": "Phil"
    }
  }
}

示例响应

202: Accepted
Content-Type: application/vnd.neo4j.query.v1.1

{
  "data": {
    "fields": [
      "person",
      "name"
    ],
    "values": [
      [
        {
          "$type": "Node",
          "_value": {
            "_element_id": "4:ff04df25-ff2b-4b55-98f8-6888297b025e:2",
            "_labels": [
              "Person"
            ],
            "_properties": {
              "name": {
                "$type": "String",
                "_value": "Phil"
              }
            }
          }
        },
        {
          "$type": "String",
          "_value": "Phil"
        }
      ]
    ]
  },
  "bookmarks": [
    "FB:kcwQ/wTfJf8rS1WY+GiIKXsCXg6Q"
  ]
}

类型映射

本节详细说明了在查询 API 中 Cypher 类型的标签映射方式。

Cypher 类型查询 API 类型示例

NULL

null

{
  "$type": "Null",
  "_value": null
}

布尔值 (BOOLEAN)

布尔值

{
  "$type": "Boolean",
  "_value": true
}

INTEGER（整数）

整数

{
  "$type": "Integer",
  "_value": "123"
}

FLOAT

浮点数

{
  "$type": "Float",
  "_value": "4.56"
}

{
  "$type": "Float",
  "_value": "3.2E9"
}

浮点数值可以使用十进制表示（如 0.2）或科学计数法表示（如 2.0E-7、3.2E9）。超出范围的值会以 Nan、Infinity、-Infinity 表示。-NaN 在作为参数使用时会被当作 NaN 处理，但该值永远不会作为输出出现。

返回数值时，绝对值在 10⁻³（含）到 10⁷（不含）之间的使用十进制表示，其他数值使用科学计数法表示。

STRING

字符串

{
  "$type": "String",
  "_value": "Hello World"
}

字节数组

Base64 编码

{
  "$type": "Base64",
  "_value": "A2+/"
}

LIST

列表

{
  "$type": "List",
  "_value": [
    {
      "$type": "String",
      "_value": "A"
    },
    {
      "$type": "String",
      "_value": "B"
    }
  ]
}

MAP

Map

{
  "$type": "Map",
  "_value": {
    "fieldA": {
      "$type": "String",
      "_value": "A"
    },
    "fieldB": {
      "$type": "String",
      "_value": "B"
    }
  }
}

DATE

Date

{
  "$type": "Date",
  "_value": "2015-03-26"
}

ZONED TIME

Time

{
  "$type": "Time",
  "_value": "12:50:35.556+01:00"
}

LOCAL TIME

LocalTime

{
  "$type": "LocalTime",
  "_value": "12:50:35.556"
}

时区日期时间

ZonedDateTime

{
  "$type": "ZonedDateTime",
  "_value": "2015-11-21T21:40:32.142Z[Antarctica/Troll]"
}

偏移日期时间

OffsetDateTime

{
  "$type": "OffsetDateTime",
  "_value": "2015-11-21T21:40:32.142Z"
}

LOCAL DATETIME

LocalDateTime

{
  "$type": "LocalDateTime",
  "_value": "2015-07-04T19:32:24"
}

DURATION（持续时间）

Duration

{
  "$type": "Duration",
  "_value": "P14DT16H12M"
}

POINT

Point

{
  "$type": "Point",
  "_value": "SRID=7203;POINT (1.2 3.4)"
}

对于三维点，请使用 POINT Z 而不是 POINT。例如：

{
  "$type": "Point",
  "_value": "SRID=9157;POINT Z (1.0 2.0 3.0)"

}

NODE

节点

{
  "$type": "Node",
  "_value": {
    "_element_id": "4:ff04df25-ff2b-4b55-98f8-6888297b025e:2",
    "_labels": [
      "Person"
    ],
    "_properties": {
      "name": {
        "$type": "String",
        "_value": "Phil"
      }
    }
  }
}

RELATIONSHIP

关系

{
  "$type": "Relationship",
  "_value": {
    "_element_id": "5:ff04df25-ff2b-4b55-98f8-6888297b025e:2",
    "_start_node_element_id": "4:ff04df25-ff2b-4b55-98f8-6888297b025e:0",
    "_end_node_element_id": "4:ff04df25-ff2b-4b55-98f8-6888297b025e:2",
    "_type": "LIKES",
    "_properties": {
      "since": {
        "$type": "String",
        "_value": "forever!"
      }
    }
  }
}

PATH

路径

{
  "$type": "Path",
  "_value": [
    {
      "$type": "Node",
      "_value": {
        "_element_id": "4:ff04df25-ff2b-4b55-98f8-6888297b025e:0",
        "_labels": [
          "Person"
        ],
        "_properties": {
          "name": {
            "$type": "String",
            "_value": "Alice"
          },
          "age": {
            "$type": "Integer",
            "_value": "42"
          }
        }
      }
    },
    {
      "$type": "Relationship",
      "_value": {
        "_element_id": "5:ff04df25-ff2b-4b55-98f8-6888297b025e:2",
        "_start_node_element_id": "4:ff04df25-ff2b-4b55-98f8-6888297b025e:0",
        "_end_node_element_id": "4:ff04df25-ff2b-4b55-98f8-6888297b025e:2",
        "_type": "LIKES",
        "_properties": {
          "since": {
            "$type": "String",
            "_value": "forever!"
          }
        }
      }
    },
    {
      "$type": "Node",
      "_value": {
        "_element_id": "4:ff04df25-ff2b-4b55-98f8-6888297b025e:2",
        "_labels": [
          "Person"
        ],
        "_properties": {
          "name": {
            "$type": "String",
            "_value": "Phil"
          }
        }
      }
    }
  ]
}

路径中关系的方向仅在起始节点和结束节点的元素 ID 中编码。返回的节点和关系的顺序并不代表关系的实际方向。

VECTOR

向量

{
  "$type": "Vector",
  "_value": {
    "coordinatesType": "INT8",
    "coordinates": ["1", "-5", "10"]
  }
}

企业版 2025.11 引入

coordinatesType 支持的取值包括：FLOAT64、FLOAT32、INT64、INT32、INT16 和 INT8。coordinates 字段是一个数组，里面存放坐标值的字符串表示。向量的维度由 coordinates 数组的长度隐式决定。

UNSUPPORTED

不支持

{
  "$type": "Unsupported",
  "_value": "Type TheUnsupportedType is not supported."
}

引入于 2025.11