Result formats

The Query API can return queried data in two formats: plain JSON, or a Neo4j-extended JSON with type information.

Plain JSON

The JSON format is the default one. It returns plain JSON, with the query results embedded within the data object. To request this format, set Accept: application/json in the request headers (or omit it entirely, as it is the default if no Accept header is provided).

JSON output format prototype
{
  "data": {
    "fields": [ field1, field2, ... ],  (1)
    "values": [ entity1, entity2, ... ]  (2)
  }
}
1 Query fields, i.e. keys for the returned objects
2 Query result (the inner structure of each element depends on the object type)
Example 1. Return a node and a property

Example request

POST http://localhost:7474/db/neo4j/query/v2
Authorization: Basic bmVvNGo6dmVyeXNlY3JldA==
Content-Type: application/json
{
  "statement": "MERGE (p:Person {name: $name}) RETURN p AS person, p.name AS name",
  "parameters": {
    "name": "Phil"
  }
}

Example response

202: Accepted
Content-Type: application/json
{
  "data": {
    "fields": [
      "person",
      "name"
    ],
    "values": [
      {
        "elementId": "4:ff04df25-ff2b-4b55-98f8-6888297b025e:2",
        "labels": [
          "Person"
        ],
        "properties": {
          "name": "Phil"
        }
      },
      "Phil"
    ]
  },
  "bookmarks": [
    "FB:kcwQ/wTfJf8rS1WY+GiIKXsCXg6Q"
  ]
}

Type mapping

Cypher types are mapped to the closest JSON type, with the complex ones (temporal, spatial, binary) serialized to string.

Cypher type Query API type Example

NULL

null

 
null

BOOLEAN

boolean

 
true

INTEGER

number

 
123

FLOAT

number

 
4.56

STRING

string

 
"Hello World"

ByteArray

string (base64)

 
"A2+/"

LIST

array

 
[123, 456]

MAP

object

 
{
  "fieldA": "A value",
  "fieldB": "Another value"
}

Temporal
(DATE, ZONED TIME, LOCAL TIME, ZONED DATETIME, LOCAL DATETIME, DURATION)

string (ISO-8601)

 
"2015-03-26"
"12:50:35.556+01:00"
"12:50:35.556"
"2015-11-21T21:40:32.142Z[Antarctica/Troll]"
"2015-07-04T19:32:24"
"P14DT16H12M"

POINT

string (WKT)

 
"SRID=7203;POINT(1.2 3.4)"

NODE

object

 
{
  "elementId": "4:ff04df25-ff2b-4b55-98f8-6888297b025e:0",
  "labels": [
    "Person"
  ],
  "properties": {
    "name": "Alice",
    "age": 42
  }
}

RELATIONSHIP

object

 
{
  "elementId": "5:ff04df25-ff2b-4b55-98f8-6888297b025e:2",
  "startNodeElementId": "4:ff04df25-ff2b-4b55-98f8-6888297b025e:0",
  "endNodeElementId": "4:ff04df25-ff2b-4b55-98f8-6888297b025e:2",
  "type": "LIKES",
  "properties": {
    "since": "forever!"
  }
}

PATH

object

 
[
  {
    "elementId": "4:ff04df25-ff2b-4b55-98f8-6888297b025e:0",
    "labels": [
      "Person"
    ],
    "properties": {
      "name": "Alice",
      "age": 42
    }
  },
  {
    "elementId": "5:ff04df25-ff2b-4b55-98f8-6888297b025e:2",
    "startNodeElementId": "4:ff04df25-ff2b-4b55-98f8-6888297b025e:0",
    "endNodeElementId": "4:ff04df25-ff2b-4b55-98f8-6888297b025e:2",
    "type": "LIKES",
    "properties": {
      "since": "forever!"
    }
  },
  {
    "elementId": "4:ff04df25-ff2b-4b55-98f8-6888297b025e:2",
    "labels": [
      "Person"
    ],
    "properties": {
      "name": "Phil"
    }
  }
]
The direction of the relationship in a path is only encoded in the start and end node element IDs. The order of returned nodes and relationships is not representative of the direction of relationships.

JSON with type information

Plain JSON does not provide information about the type of a returned value. For example, the two following requests result in the exact same response, even if in the first case the return value is a Cypher STRING, while in the second case it is a ZONED DATETIME.

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

If you care about what type each returned value is, you can use Neo4j’s extended JSON format with type information. To receive the result in this format, set Accept: application/vnd.neo4j.query in the request headers.

In this format, each return value is an object where the type and value information are stored as separate keys:

An OffsetDateTime value with the JSON with type information
{
  "$type":"OffsetDateTime",
  "_value":"2024-01-01T21:40:32-01:00"
}

If you wish to also submit parameters with this format, set Content-Type: application/vnd.neo4j.query in the request headers.

Example 2. Both parameters and result data in extended JSON format

Example request

POST http://localhost:7474/db/neo4j/query/v2
Authorization: Basic bmVvNGo6dmVyeXNlY3JldA==
Accept: application/vnd.neo4j.query
Content-Type: application/vnd.neo4j.query
{
  "statement": "MERGE (p:Person {name: $name}) RETURN p AS person, p.name AS name",
  "parameters": {
    "name": {
      "$type": "String",
      "_value": "Phil"
    }
  }
}

Example response

202: Accepted
Content-Type: application/json
{
  "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"
  ]
}

Type mapping

This section details how Cypher types are labeled in the Query API.

Cypher type Query API type Example

NULL

null

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

BOOLEAN

Boolean

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

INTEGER

Integer

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

FLOAT

Float

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

STRING

String

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

ByteArray

Base64

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

LIST

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"
}

ZONED DATETIME

ZonedDateTime

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

LOCAL DATETIME

LocalDateTime

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

DURATION

Duration

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

POINT

Point

 
{
  "$type": "Point",
  "_value": {
    "coordinates": [
      2.3,
      4.5,
      2.0
    ],
    "crs": {
      "srid": 9157,
      "name": "cartesian-3d",
      "type": "link",
      "properties": {
        "href": "http://spatialreference.org/ref/sr-org/9157/ogcwkt/",
        "type": "ogcwkt"
      }
    }
  }
}

NODE

Node

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

RELATIONSHIP

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

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"
          }
        }
      }
    }
  ]
}
The direction of the relationship in a path is only encoded in the start and end node element IDs. The order of returned nodes and relationships is not representative of the direction of relationships.