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 |
---|---|---|
- exports whole database as json to the provided file |
|
|
- exports given nodes and relationships as json to the provided file |
|
|
- exports given graph object as json to the provided file |
|
|
- exports results from the cypher statement as json to the provided file |
|
|
name | type | default | description |
---|---|---|---|
writeNodeProperties |
boolean |
true |
if true export properties too. |
stream |
boolean |
false |
stream the json directly to the client into the |
jsonFormat |
enum[JSON_LINES, ARRAY_JSON, JSON, JSON_ID_AS_KEYS] |
JSON_LINES |
the format of the exported json |
name | description |
---|---|
JSON_LINES |
the data will be exported as JSON lines |
ARRAY_JSON |
the data will be exported as array of json:
|
JSON |
the data will be exported as json with two (array) fields |
JSON_ID_AS_KEYS |
the data will be exported as json with two (map) fields |
The labels exported are ordered alphabetically.
The output of |
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.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 |
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.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 to S3
By default exporting to S3 is disabled.
We can enable it by setting the following property in 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, you can use the |
Using S3 protocol
When using the S3 protocol we need to download and copy the following jars into the plugins directory:
-
aws-java-sdk-core-1.12.136.jar (https://mvnrepository.com/artifact/com.amazonaws/aws-java-sdk-core/1.12.136)
-
aws-java-sdk-s3-1.12.136.jar (https://mvnrepository.com/artifact/com.amazonaws/aws-java-sdk-s3/1.12.136)
-
httpclient-4.5.13.jar (https://mvnrepository.com/artifact/org.apache.httpcomponents/httpclient/4.5.13)
-
httpcore-4.4.15.jar (https://mvnrepository.com/artifact/org.apache.httpcomponents/httpcore/4.4.15)
-
joda-time-2.10.13.jar (https://mvnrepository.com/artifact/joda-time/joda-time/2.10.13)
Once those files have been copied we’ll need to restart the database.
The S3 URL must be in the following format:
-
s3://accessKey:secretKey[:sessionToken]@endpoint:port/bucket/key
(where the sessionToken is optional) or -
s3://endpoint:port/bucket/key?accessKey=accessKey&secretKey=secretKey[&sessionToken=sessionToken]
(where the sessionToken is optional) or -
s3://endpoint:port/bucket/key
if the accessKey, secretKey, and the optional sessionToken are provided in the environment variables
Memory Requirements
To support large uploads, the S3 uploading utility may use up to 2.25 GB of memory at a time. The actual usage will depend on the size of the upload, but will use a maximum of 2.25 GB.
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.
all.json
CALL apoc.export.json.all("all.json",{useTypes:true})
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:
{"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}}}
data
columnCALL apoc.export.json.all(null,{useTypes:true, stream: true})
YIELD file, nodes, relationships, properties, data
RETURN file, nodes, relationships, properties, data
file | nodes | relationships | properties | data |
---|---|---|---|---|
|
|
|
|
"{\"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.
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
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:
{"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}}}
KNOWS
relationships and User
nodes in the data
columnMATCH (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
file | nodes | relationships | properties | data |
---|---|---|---|---|
|
|
|
|
"{\"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
value | g |
---|---|
|
{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: {}} |
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
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:
{"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}}}
data
columnCALL apoc.export.json.graph(apoc.static.get("knows.cached"), null, {stream: true})
YIELD file, nodes, relationships, properties, data
RETURN file, nodes, relationships, properties, data
file | nodes | relationships | properties | data |
---|---|---|---|---|
|
|
|
|
"{\"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.
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}}
)
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:
{"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}}}
User
nodes with an age
property greater than 10
to the data
columnCALL 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
file | nodes | relationships | properties | data |
---|---|---|---|---|
|
|
|
|
"{\"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}}}" |
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
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:
{"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}}
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}}
)
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:
{"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}}]}
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}}
)
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:
{"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.
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}
)
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:
{"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 |