apoc.export.json.query

Procedure APOC Core

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

Signature

apoc.export.json.query(query :: STRING?, file :: STRING?, config = {} :: MAP?) :: (file :: STRING?, source :: STRING?, format :: STRING?, nodes :: INTEGER?, relationships :: INTEGER?, properties :: INTEGER?, time :: INTEGER?, rows :: INTEGER?, batchSize :: INTEGER?, batches :: INTEGER?, done :: BOOLEAN?, data :: STRING?)

Input parameters

Name Type Default

query

STRING?

null

file

STRING?

null

config

MAP?

{}

Config parameters

The procedure support the following config parameters:

Table 1. Config parameters
name type default description

writeNodeProperties

boolean

false

if true export properties too.

stream

boolean

false

stream the json directly to the client into the data field

Output parameters

Name Type

file

STRING?

source

STRING?

format

STRING?

nodes

INTEGER?

relationships

INTEGER?

properties

INTEGER?

time

INTEGER?

rows

INTEGER?

batchSize

INTEGER?

batches

INTEGER?

done

BOOLEAN?

data

STRING?

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 neo4j.conf

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.

Usage Examples

The examples in this section are based on the following sample graph:

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 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 2. 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":33.46789,"longitude":13.1,"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 3. 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\":33.46789,\"longitude\":13.1,\"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 4. 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":56.7,"longitude":12.78,"height":null},{"crs":"wgs-84-3d","latitude":56.7,"longitude":12.78,"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 5. 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":33.46789,"longitude":13.1,"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 6. 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":33.46789,"longitude":13.1,"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 7. 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":33.46789,"longitude":13.1,"height":null},"age":42,"male":true,"kids":["Sam","Anna","Grace"]}},"end":{"id":"1","labels":["User"],"properties":{"name":"Jim","age":42}}}}