Export to JSON

The export JSON procedures export data into a format that’s supported by JavaScript based visualisation tools. We may also want to export data into JSON format for importing into other tools or for general sharing of query results. The procedures described in this section support exporting to a file or as a stream.

The format used is jsonlines or JSONL, a streaming format that contains one JSON object per line, in our case a node or relationship.

Available Procedures

The table below describes the available procedures:

Qualified Name Type Release

Qualified Name	Type	Release
apoc.export.json.all `apoc.export.json.all(file,config)` - exports whole database as json to the provided file	`Procedure`	`APOC Core`
apoc.export.json.data `apoc.export.json.data(nodes,rels,file,config)` - exports given nodes and relationships as json to the provided file	`Procedure`	`APOC Core`
apoc.export.json.graph `apoc.export.json.graph(graph,file,config)` - exports given graph object as json to the provided file	`Procedure`	`APOC Core`
apoc.export.json.query `apoc.export.json.query(query,file,{config,…,params:{params}})` - exports results from the cypher statement as json to the provided file	`Procedure`	`APOC Core`

apoc.export.json.all

apoc.export.json.all(file,config) - exports whole database as json to the provided file

Procedure

APOC Core

apoc.export.json.data

apoc.export.json.data(nodes,rels,file,config) - exports given nodes and relationships as json to the provided file

Procedure

APOC Core

apoc.export.json.graph

apoc.export.json.graph(graph,file,config) - exports given graph object as json to the provided file

Procedure

APOC Core

apoc.export.json.query

apoc.export.json.query(query,file,{config,…,params:{params}}) - exports results from the cypher statement as json to the provided file

Procedure

APOC Core

Table 1. Config
name	type	default	description
writeNodeProperties	boolean	true	if true export properties too.
stream	boolean	false	stream the json directly to the client into the `data` field
jsonFormat	enum[JSON_LINES, ARRAY_JSON, JSON, JSON_ID_AS_KEYS]	JSON_LINES	the format of the exported json

Table 2. jsonFormat types
name	description
JSON_LINES	the data will be exported as JSON lines
ARRAY_JSON	the data will be exported as array of json: `[{"type":"node","id":"2","labels":["User"],"properties":{"age":12}},…]`
JSON	the data will be exported as json with two (array) fields `nodes` and `rels`: `{"nodes":[{"type":"node","id":"2","labels":["User"],"properties":{…}},…],"rels":[{"id":"0","type":"relationship","label":"KNOWS","properties":{"since":1993},"start":{"id":"0","labels":["User"]},"end":{"id":"1","labels":["User"]}},…]}`
JSON_ID_AS_KEYS	the data will be exported as json with two (map) fields `nodes` and `rels` where the key is the neo4j internal id and the value is the graph entity value: `{"nodes":{"0":{"type":"node","id":"0","labels":["User"],"properties":{…},"1":{…},"2":{…},"rels":{"0":{"id":"0","type":"relationship","label":"KNOWS","properties":{…},"start":{"id":"0","labels":["User"]},"end":{"id":"1","labels":["User"]}}}}`

The labels exported are ordered alphabetically. The output of labels() function is not sorted, use it in combination with apoc.coll.sort().

Exporting to a file

By default exporting to the file system is disabled. We can enable it by setting the following property in apoc.conf:

apoc.conf

apoc.export.file.enabled=true

If we try to use any of the export procedures without having first set this property, we’ll get the following error message:

Failed to invoke procedure: Caused by: java.lang.RuntimeException: Export to files not enabled, please set apoc.export.file.enabled=true in your apoc.conf. Otherwise, if you are running in a cloud environment without filesystem access, use the {stream:true} config and null as a 'file' parameter to stream the export back to your client. Note that the stream mode cannot be used with the apoc.export.xls.* procedures.

Export files are written to the import directory, which is defined by the dbms.directories.import property. This means that any file path that we provide is relative to this directory. If we try to write to an absolute path, such as /tmp/filename, we’ll get an error message similar to the following one:

Failed to invoke procedure: Caused by: java.io.FileNotFoundException: /path/to/neo4j/import/tmp/fileName (No such file or directory)

We can enable writing to anywhere on the file system by setting the following property in apoc.conf:

apoc.conf

apoc.import.file.use_neo4j_config=false

Neo4j will now be able to write anywhere on the file system, so be sure that this is your intention before setting this property.

Exporting a stream

If we don’t want to export to a file, we can stream results back in the data column instead by passing a file name of null and providing the stream:true config.

Examples

This section includes examples showing how to use the export to JSON procedures. These examples are based on a people dataset, which can be imported by running the following Cypher query:

CREATE (a:User {
    name:'Adam', age:42, male:true, kids:['Sam','Anna','Grace'],
    born:localdatetime('2015185T19:32:24'),
    place:point({latitude: 13.1, longitude: 33.46789})
})
CREATE (b:User {name:'Jim', age:42})
CREATE (c:User {age:12})

CREATE (a)-[:KNOWS {since: 1993}]->(b)

The Neo4j Browser visualization below shows the imported graph:

Note that, to perform a correct Point serialization, it is not recommended to export a point with coordinates x,y and crs: 'wgs-84', for example point({x: 56.7, y: 12.78, crs: 'wgs-84'}). Otherwise, the point will be exported with longitude and latitude (and heigth) instead of x and y (and z)

Export whole database to JSON

The apoc.export.json.all procedure exports the whole database to a JSON file or as a stream.

The following query exports the whole database to the file all.json

CALL apoc.export.json.all("all.json",{useTypes:true})

Table 3. Results
file	source	format	nodes	relationships	properties	time	rows	batchSize	batches	done	data
"all.json"	"database: nodes(3), rels(1)"	"json"	3	1	10	7	0	-1	0	TRUE	NULL

The contents of all.json are shown below:

all.json

{"type":"node","id":"0","labels":["User"],"properties":{"born":"2015-07-04T19:32:24","name":"Adam","place":{"crs":"wgs-84","latitude":13.1,"longitude":33.46789,"height":null},"age":42,"male":true,"kids":["Sam","Anna","Grace"]}}
{"type":"node","id":"1","labels":["User"],"properties":{"name":"Jim","age":42}}
{"type":"node","id":"2","labels":["User"],"properties":{"age":12}}
{"id":"0","type":"relationship","label":"KNOWS","properties":{"bffSince":"P5M1DT12H","since":1993},"start":{"id":"0","labels":["User"],"properties":{"born":"2015-07-04T19:32:24","name":"Adam","place":{"crs":"wgs-84","latitude":13.1,"longitude":33.46789,"height":null},"age":42,"male":true,"kids":["Sam","Anna","Grace"]}},"end":{"id":"1","labels":["User"],"properties":{"name":"Jim","age":42}}}

The following query returns a stream of the whole database in the data column

CALL apoc.export.json.all(null,{useTypes:true, stream: true})
YIELD file, nodes, relationships, properties, data
RETURN file, nodes, relationships, properties, data

Table 4. Results
file	nodes	relationships	properties	data
`NULL`	`3`	`1`	`10`	"{\"type\":\"node\",\"id\":\"0\",\"labels\":[\"User\"],\"properties\":{\"born\":\"2015-07-04T19:32:24\",\"name\":\"Adam\",\"place\":{\"crs\":\"wgs-84\",\"latitude\":13.1,\"longitude\":33.46789,\"height\":null},\"age\":42,\"male\":true,\"kids\":[\"Sam\",\"Anna\",\"Grace\"]}} {\"type\":\"node\",\"id\":\"1\",\"labels\":[\"User\"],\"properties\":{\"name\":\"Jim\",\"age\":42}} {\"type\":\"node\",\"id\":\"2\",\"labels\":[\"User\"],\"properties\":{\"age\":12}} {\"id\":\"50000\",\"type\":\"relationship\",\"label\":\"KNOWS\",\"properties\":{\"since\":1993},\"start\":{\"id\":\"0\",\"labels\":[\"User\"]},\"end\":{\"id\":\"1\",\"labels\":[\"User\"]}}"

Export specified nodes and relationships to JSON

The apoc.export.json.data procedure exports the specified nodes and relationships to a JSON file or as a stream.

The following query exports all KNOWS relationships and User nodes to the file knows.json

MATCH (nod:User)
MATCH ()-[rels:KNOWS]->()
WITH collect(nod) as a, collect(rels) as b
CALL apoc.export.json.data(a, b, "knows.json", null)
YIELD file, source, format, nodes, relationships, properties, time, rows, batchSize, batches, done, data
RETURN file, source, format, nodes, relationships, properties, time, rows, batchSize, batches, done, data

Table 5. Results
file	source	format	nodes	relationships	properties	time	rows	batchSize	batches	done	data
"knows.json"	"data: nodes(3), rels(3)"	"json"	3	1	10	1	0	-1	0	TRUE	NULL

The contents of knows.json are shown below:

knows.json

{"type":"node","id":"0","labels":["User"],"properties":{"born":"2015-07-04T19:32:24","name":"Adam","place":{"crs":"wgs-84","latitude":13.1,"longitude":33.46789,"height":null},"age":42,"male":true,"kids":["Sam","Anna","Grace"]}}
{"type":"node","id":"1","labels":["User"],"properties":{"name":"Jim","age":42}}
{"type":"node","id":"2","labels":["User"],"properties":{"age":12}}
{"id":"0","type":"relationship","label":"KNOWS","properties":{"bffSince":"P5M1DT12H","since":1993},"start":{"id":"0","labels":["User"],"properties":{"born":"2015-07-04T19:32:24","name":"Adam","place":{"crs":"wgs-84","latitude":13.1,"longitude":33.46789,"height":null},"age":42,"male":true,"kids":["Sam","Anna","Grace"]}},"end":{"id":"1","labels":["User"],"properties":{"name":"Jim","age":42}}}

The following query return a stream of all KNOWS relationships and User nodes in the data column

MATCH (nod:User)
MATCH ()-[rels:KNOWS]->()
WITH collect(nod) as a, collect(rels) as b
CALL apoc.export.json.data(a, b, null, {stream: true})
YIELD file, nodes, relationships, properties, data
RETURN file, nodes, relationships, properties, data

Table 6. Results
file	nodes	relationships	properties	data
`NULL`	`3`	`1`	`10`	"{\"type\":\"node\",\"id\":\"0\",\"labels\":[\"User\"],\"properties\":{\"born\":\"2015-07-04T19:32:24\",\"name\":\"Adam\",\"place\":{\"crs\":\"wgs-84\",\"latitude\":13.1,\"longitude\":33.46789 ,\"height\":null},\"age\":42,\"male\":true,\"kids\":[\"Sam\",\"Anna\",\"Grace\"]}} {\"type\":\"node\",\"id\":\"1\",\"labels\":[\"User\"],\"properties\":{\"name\":\"Jim\",\"age\":42}} {\"type\":\"node\",\"id\":\"2\",\"labels\":[\"User\"],\"properties\":{\"age\":12}} {\"id\":\"50000\",\"type\":\"rel

Export virtual graph to JSON

The apoc.export.json.graph procedure exports a virtual graph to a CSV file or as a stream.

The examples in this section are based on a virtual graph of the whole database. The query below creates a virtual graph and stores it in memory with the name db.cached using Static Value Storage.

CALL apoc.graph.fromDB('test',{})
YIELD graph AS g
CALL apoc.static.set("db.cached", g)
YIELD value
RETURN value, g

Table 7. Results
value	g
`NULL`	{name: "test", relationships: [[:KNOWS {since: 1993}]], nodes: [(:User {born: 2015-07-04T19:32:24, name: "Adam", place: point({srid:4326, x:33.46789, y:13.1}), age: 42, male: TRUE, kids: ["Sam", "Anna", "Grace"]}), (:User {name: "Jim", age: 42}), (:User {age: 12})], properties: {}}

The following query exports the virtual graph from static value storage to the file graph.json

CALL apoc.export.json.graph(apoc.static.get("db.cached"),"graph.json",{})
YIELD file, source, format, nodes, relationships, properties, time, rows, batchSize, batches, done, data
RETURN file, source, format, nodes, relationships, properties, time, rows, batchSize, batches, done, data

Table 8. Results
file	source	format	nodes	relationships	properties	time	rows	batchSize	batches	done	data
"graph.json"	"graph: nodes(3), rels(1)"	"json"	3	1	10	3	4	-1	0	TRUE	NULL

The contents of graph.json are shown below:

graph.json

{"type":"node","id":"0","labels":["User"],"properties":{"born":"2015-07-04T19:32:24","name":"Adam","place":{"crs":"wgs-84","latitude":13.1,"longitude":33.46789,"height":null},"age":42,"male":true,"kids":["Sam","Anna","Grace"]}}
{"type":"node","id":"1","labels":["User"],"properties":{"name":"Jim","age":42}}
{"type":"node","id":"2","labels":["User"],"properties":{"age":12}}
{"id":"0","type":"relationship","label":"KNOWS","properties":{"bffSince":"P5M1DT12H","since":1993},"start":{"id":"0","labels":["User"],"properties":{"born":"2015-07-04T19:32:24","name":"Adam","place":{"crs":"wgs-84","latitude":13.1,"longitude":33.46789,"height":null},"age":42,"male":true,"kids":["Sam","Anna","Grace"]}},"end":{"id":"1","labels":["User"],"properties":{"name":"Jim","age":42}}}

The following query returns a streams of the virtual graph from static value storage to the data column

CALL apoc.export.json.graph(apoc.static.get("knows.cached"), null, {stream: true})
YIELD file, nodes, relationships, properties, data
RETURN file, nodes, relationships, properties, data

Table 9. Results
file	nodes	relationships	properties	data
`NULL`	`2`	`1`	`9`	"{\"type\":\"node\",\"id\":\"0\",\"labels\":[\"User\"],\"properties\":{\"born\":\"2015-07-04T19:32:24\",\"name\":\"Adam\",\"place\":{\"crs\":\"wgs-84\",\"latitude\":13.1,\"longitude\":33.46789,\"height\":null},\"age\":42,\"male\":true,\"kids\":[\"Sam\",\"Anna\",\"Grace\"]}} {\"type\":\"node\",\"id\":\"1\",\"labels\":[\"User\"],\"properties\":{\"name\":\"Jim\",\"age\":42}} {\"id\":\"50000\",\"type\":\"relationship\",\"label\":\"KNOWS\",\"properties\":{\"since\":1993},\"start\":{\"id\":\"0\",\"labels\":[\"User\"]},\"end\":{\"id\":\"1\",\"labels\":[\"User\"]}}" "

Export results of Cypher query to JSON

The apoc.export.json.query procedure exports the results of a Cypher query to a JSON file or as a stream.

The following query exports all User nodes with an age property greater than 10 to the file users-age.json

CALL apoc.export.json.query(
    "MATCH (u:User) WHERE u.age > $age return u",
    "users-age.json",
    {params:{age:15}}
)

Table 10. Results
file	source	format	nodes	relationships	properties	time	rows	batchSize	batches	done	data
"users-age.json"	"statement: cols(1)"	"json"	2	0	8	3	2	-1	0	TRUE	NULL

The contents of users-age.json are shown below:

users-age.json

{"u":{"type":"node","id":"0","labels":["User"],"properties":{"born":"2015-07-04T19:32:24","name":"Adam","place":{"crs":"wgs-84","latitude":13.1,"longitude":33.46789,"height":null},"age":42,"male":true,"kids":["Sam","Anna","Grace"]}}}
{"u":{"type":"node","id":"1","labels":["User"],"properties":{"name":"Jim","age":42}}}
{"u":{"type":"node","id":"2","labels":["User"],"properties":{"age":12}}}

The following query returns a stream of User nodes with an age property greater than 10 to the data column

CALL apoc.export.json.query(
    "MATCH (u:User) WHERE u.age > $age return u",
    null,
    {params:{age:15}, stream: true}
)
YIELD file, nodes, relationships, properties, data
RETURN file, nodes, relationships, properties, data

Table 11. Results
file	nodes	relationships	properties	data
`NULL`	`2`	`0`	`8`	"{\"u\":{\"type\":\"node\",\"id\":\"0\",\"labels\":[\"User\"],\"properties\":{\"born\":\"2015-07-04T19:32:24\",\"name\":\"Adam\",\"place\":{\"crs\":\"wgs-84\",\"latitude\":13.1,\"longitude\":33.46789,\"height\":null},\"age\":42,\"male\":true,\"kids\":[\"Sam\",\"Anna\",\"Grace\"]}}} {\"u\":{\"type\":\"node\",\"id\":\"1\",\"labels\":[\"User\"],\"properties\":{\"name\":\"Jim\",\"age\":42}}}"

The following query exports a complex Cypher map structure to the file complex-cypher-structure.json

WITH "RETURN {
	value:1,
    data:[
    	10, 'car', null,
        point({ longitude: 56.7, latitude: 12.78 }),
        point({ longitude: 56.7, latitude: 12.78, height: 8 }),
        point({ x: 2.3, y: 4.5 }),
        point({ x: 2.3, y: 4.5, z: 2 }),
        date('2018-10-10'),
        datetime('2018-10-18T14:21:40.004Z'),
        localdatetime({ year:1984, week:10, dayOfWeek:3, hour:12, minute:31, second:14, millisecond: 645 }),
        {x:1, y:[1,2,3,{age:10}]}
    ]
} as key" AS query
CALL apoc.export.json.query(query, "complex-cypher-structure.json")
YIELD file, source, format, nodes, relationships, properties, time, rows, batchSize, batches, done, data
RETURN file, source, format, nodes, relationships, properties, time, rows, batchSize, batches, done, data

Table 12. Results
file	source	format	nodes	relationships	properties	time	rows	batchSize	batches	done	data
"complex-cypher-structure.json"	"statement: cols(1)"	"json"	0	0	16	2	1	-1	0	TRUE	NULL

The contents of complex-cypher-structure.json are shown below:

complex-cypher-structure.json

{"key":{"data":[10,"car",null,{"crs":"wgs-84","latitude":12.78,"longitude":56.7,"height":null},{"crs":"wgs-84-3d","latitude":12.78,"longitude":56.7,"height":8.0},{"crs":"cartesian","x":2.3,"y":4.5,"z":null},{"crs":"cartesian-3d","x":2.3,"y":4.5,"z":2.0},"2018-10-10","2018-10-18T14:21:40.004Z","1984-03-07T12:31:14.645",{"x":1,"y":[1,2,3,{"age":10}]}],"value":1}}

The following query exports a list of User nodes with an age property is greater than 10 to the file users-list.json

CALL apoc.export.json.query(
    "MATCH (u:User) RETURN COLLECT(u) as list",
    "users-list.json",
    {params:{age:10}}
)

Table 13. Results
file	source	format	nodes	relationships	properties	time	rows	batchSize	batches	done	data
"users-list.json"	"statement: cols(1)"	"json"	3	0	9	1	1	-1	0	TRUE	NULL

The contents of users-list.json are shown below:

users-list.json

{"list":[{"type":"node","id":"0","labels":["User"],"properties":{"born":"2015-07-04T19:32:24","name":"Adam","place":{"crs":"wgs-84","latitude":13.1,"longitude":33.46789,"height":null},"age":42,"male":true,"kids":["Sam","Anna","Grace"]}},{"type":"node","id":"1","labels":["User"],"properties":{"name":"Jim","age":42}},{"type":"node","id":"2","labels":["User"],"properties":{"age":12}}]}

The following query exports the map representation of User nodes connected by a KNOWS relationship to the file users-map.json

CALL apoc.export.json.query(
    "MATCH (u:User)-[r:KNOWS]->(d:User) RETURN u {.*}, d {.*}, r {.*}",
    "users-map.json",
    {params:{age:10}}
)

Table 14. Results
file	source	format	nodes	relationships	properties	time	rows	batchSize	batches	done	data
"users-map.json"	"statement: cols(3)"	"json"	0	0	11	8	1	-1	0	TRUE	NULL

The contents of users-map.json are shown below:

users-map.json

{"u":{"born":"2015-07-04T19:32:24","name":"Adam","place":{"crs":"wgs-84","latitude":13.1,"longitude":33.46789,"height":null},"age":42,"male":true,"kids":["Sam","Anna","Grace"]},"d":{"name":"Jim","age":42},"r":{"bffSince":"P5M1DT12H","since":1993}}

In this example we use the {.*} syntax when returning graph entities in the Cypher statement. This syntax returns a map representation of graph entities, meaning that only properties will be exported; labels and relationship types are excluded.

The following query exports all KNOWS relationship, including start and end nodes and their properties, to the file knows-with-node-properties.json

CALL apoc.export.json.query(
    "MATCH p = (u:User)-[rel:KNOWS]->(u2:User) RETURN rel",
    "knows-with-node-properties.json",
    {writeNodeProperties:true}
)

Table 15. Results
file	source	format	nodes	relationships	properties	time	rows	batchSize	batches	done	data
"knows-with-node-properties.json"	"statement: cols(1)"	"json"	0	1	1	20	2	-1	0	TRUE	NULL

The contents of knows-with-node-properties.json are shown below:

knows-with-node-properties.json

{"rel":{"id":"0","type":"relationship","label":"KNOWS","properties":{"bffSince":"P5M1DT12H","since":1993},"start":{"id":"0","labels":["User"],"properties":{"born":"2015-07-04T19:32:24","name":"Adam","place":{"crs":"wgs-84","latitude":13.1,"longitude":33.46789,"height":null},"age":42,"male":true,"kids":["Sam","Anna","Grace"]}},"end":{"id":"1","labels":["User"],"properties":{"name":"Jim","age":42}}}}

You can also compress the files to export. See here for more information