Result formats

1. Default

This format returns JSON with an embedded results element. To request this format, place application/json in the Accept header. This format is the default returned if no Accept header is provided.

{
    "results": [
        {
            "columns": [],
            "data": [
                {
                    "row": [ row-data ],
                    "meta": [ metadata ]
                },
                {

                }
            ]
        },
        {
             //another statement’s results
        }
    ]
}

For example, running the query UNWIND range(0,2,1) as number RETURN number will return the following results:

{
    "results": [
        {
            "columns": [
                "number"
            ],
            "data": [
                {
                    "row": [
                        0
                    ],
                    "meta": [
                        null
                    ]
                },
                {
                    "row": [
                        1
                    ],
                    "meta": [
                        null
                    ]
                },
                {
                    "row": [
                        2
                    ],
                    "meta": [
                        null
                    ]
                }
            ]
        }
    ],
    // other transactional data
}

2. Jolt

Jolt, short for JSON Bolt, is a JSON-based format which encloses the response value’s type together with the value inside a singleton object.

For example:

{ "Z": "2" }

This labels the value 2 as an integer type.

This format can be returned when adding application/vnd.neo4j.jolt+json-seq to the request’s Accept header.

2.1. Strict and sparse

There are two modes of Jolt that can be returned:

  • Strict mode, where all values are paired with their type.

  • Sparse mode, which omits typing pairing on values which can suitably be matched to JSON types.

By default, the sparse mode is returned. To enable strict mode, pass application/vnd.neo4j.jolt+json-seq;strict=true in the Accept header.

2.2. Jolt types

2.2.1. Base types

Type Label Type Example

(N/A)

null

null

?

Boolean

{ "?": "true" }

Z

Integer

{ "Z": "123" }

R

Float/Real

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

U

String

{ "U": "A string" }

T

Date/Time

{ "T": "2002-04-16T12:34:56"}

@

Geospatial

{"@": "POINT (30 10)"}

#

Base64

{ "#": "AaBb" }

[1]The type label R is used both to indicate floating point numbers and integers that are outside the range of 32-bit signed integers.

2.2.2. Composite types

Type Label Type Example

[]

List

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

{}

Dictionary

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

2.2.3. Entity types

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

For example:

{
 "()": [
   4711,
   [
     "A",
     "B"
   ],
   {
     "prop1": {
       "Z": "1"
     },
     "prop2": {
       "U": "Hello"
     }
   }
 ]
}
Relationships
{"->": [ rel_id, start_node_id, rel_type, end_node_id, {properties}]}
{"<-": [ rel_id, end_node_id, rel_type, start_node_id, {properties}]}

For example:

{
 "->": [
   4711,
   123,
   "KNOWS",
   124,
   {
     "since": {
       "Z": "1999"
     }
   }
 ]
}
Paths
{"..": [{node_1},{rel_1},{node_2},...,{node_n},{rel_n},{node_n+1}]}

For example:

{
 "..": [
   {
     "()": [
       111,
       [],
       {}
     ]
   },
   {
     "->": [
       9090,
       111,
       "KNOWS",
       222,
       {
         "since": {
           "Z": "1999"
         }
       }
     ]
   },
   {
     "()": [
       222,
       [],
       {}
     ]
   }
 ]
}

2.2.4. Container format

Jolt results will be returned in a new container format based on events. A typical response will contain:

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

Each event is a separate JSON document separated by a single new line character:

Event Function

header

Marks the start of a result set for a statement, and contains query fields.

data

For each record returned in the result set there will be a data json object. Depending on the query, each query can return multiple data objects.

The order of values in the array match the fields received in the header.

summary

Marks the end of a result set for a statement.

Can contain query plan information if requested.

info

Final event to appear after processing all statements (unless an error has occurred), and can contain transaction information (e.g. a commit URI).

error

Errors which occur during the processing of the transaction.

Multiple result sets in a request

When there are multiple queries in a single request there will be multiple header, data, and summary outputs for each query.

For example, posting the following request:

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

will yield the following result response:

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

Results sets will be returned in the same order as passed in the original request.