apoc.load.json

Procedure APOC Core

apoc.load.json('urlOrKeyOrBinary',path, config) YIELD value - import JSON as stream of values if the JSON was an array or a single value if it was a map

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 dbms.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] }