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 to the request’s Accept header.

2.1. Line delimited and Sequenced

Jolt may be returned in either line feed delimited or JSON sequence[1] mode. The formats are made available via the application/vnd.neo4j.jolt and application/vnd.neo4j.jolt+json+seq types which may be passed to the request’s Accept header respectively.

2.2. 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;strict=true or application/vnd.neo4j.jolt+json-seq;strict=true in the Accept header.

2.3. Jolt types

2.3.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)"}

#

Hexadecimal

{ "#": "FA08" }

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.3.2. Composite types

Type Label Type Example

[]

List

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

{}

Dictionary

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

2.3.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.3.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 LF character (Line Feed, UTF encoding: 0x8A) or, if JSON sequences are requested, encapsulated within an RS character[2] (Information Separator Two, UTF-8 encoding: 0x1E) at the beginning of each document as well as a LF character at the end:

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.

For example, the default Jolt encoding will result in a stream encoded as follows:

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

While the JSON sequence based Jolt encoding will result in the following response:

\u001E{"header":{"fields":["result"]}}\n
\u001E{"data":[{"Z":"1"}]}\n
\u001E{"summary":{}}\n
\u001E{"info":{}}\n
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.


1. JSON Sequences are encoded as outlined in RFC 7464.
2. The common name is Record Separator, and the Unicode name is Information Separator Two