apoc.load.json

Procedure

apoc.load.json(urlOrKeyOrBinary ANY, path STRING, config MAP<STRING, ANY>) - imports JSON file as a stream of values if the given JSON file is a LIST<ANY>. If the given JSON file is a MAP, this procedure imports a single value instead.

Loading from local files requires setting apoc.import.file.enabled=true in apoc.conf. This is not supported on Aura. Aura instances are therefore limited to loading publicly hosted files.

Signature

apoc.load.json(urlOrKeyOrBinary :: ANY, path =  :: STRING, config = {} :: MAP) :: (value :: MAP)

Input parameters

Name	Type	Default
urlOrKeyOrBinary	ANY	null
path	STRING
config	MAP	{}

Name

Type

Default

urlOrKeyOrBinary

ANY

null

path

STRING

config

MAP

{}

Output parameters

Name	Type
value	MAP

Name

Type

value

MAP

Reading from a file

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

apoc.conf

apoc.import.file.enabled=true

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

Failed to invoke procedure: Caused by: java.lang.RuntimeException: Import from files not enabled, please set apoc.import.file.enabled=true in your apoc.conf

Import files are read from the import directory, which is defined by the server.directories.import property. This means that any file path that we provide is relative to this directory. If we try to read from 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.lang.RuntimeException: Can’t read url or key file:/path/to/neo4j/import/tmp/filename as json: /path/to/neo4j//import/tmp/filename (No such file or directory)

We can enable reading files from 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 read from anywhere on the file system, so be sure that this is your intention before setting this property.

Usage Examples

person.json contains a JSON document representing a person and their children.

person.json

{
 "name":"Michael",
 "age": 41,
 "children": ["Selina","Rana","Selma"]
}

We’ll place this file into the import directory of our Neo4j instance. Let’s now write a query using the apoc.load.json procedure to explore this file.

The following query processes person.json and returns the content as Cypher data structures

CALL apoc.load.json("file:///person.json")
YIELD value
RETURN value;

Table 1. Results
value
{name: "Michael", children: ["Selina", "Rana", "Selma"], age: 41}

We get back a map that looks almost the same as the JSON document. We can now extend that query to create a graph based on this JSON file. We’ll create a Person node for Michael and each of his children, and a CHILD_OF relationship from each child to the Michael node.

The following creates a graph based on person.json

CALL apoc.load.json("file:///person.json")
YIELD value
MERGE (p:Person {name: value.name})
SET p.age = value.age
WITH p, value
UNWIND value.children AS child
MERGE (c:Person {name: child})
MERGE (c)-[:CHILD_OF]->(p);

The Neo4j Browser visualization below shows the imported graph:

Binary file

You can also import a file from a binary byte[] (not compressed) or a compressed file (allowed compression algos are: GZIP, BZIP2, DEFLATE, BLOCK_LZ4, FRAMED_SNAPPY).

CALL apoc.load.json(`binaryGzipByteArray`, '', {compression: 'GZIP'})

or:

CALL apoc.load.json(`binaryFileNotCompressed`, '', {compression: 'NONE'})

For example, this one works well with apoc.util.compress function:

WITH apoc.util.compress('{"foo":[1,2,3]}', {compression: 'DEFLATE'}) as jsonCompressed
CALL apoc.load.json(jsonCompressed, '', {compression: 'DEFLATE'})
YIELD value
RETURN value

Table 2. Results
value
{"foo": [1, 2, 3] }