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).
{
"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 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 | ||
---|---|---|---|---|
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
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:
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 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 | ||
---|---|---|---|---|
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|