apoc.load.json

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.

Details
Syntax	`apoc.load.json(urlOrKeyOrBinary [, path, config ]) :: (value)`
Description	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.
Input arguments	Name	Type	Description
	`urlOrKeyOrBinary`	`ANY`	The name of the file or binary data to import the data from.
	`path`	`STRING`	A JSON path expression used to extract a certain part from the list. The default is: ``.
	`config`	`MAP`	`{ failOnError = true :: BOOLEAN, pathOptions :: LIST<STRING>, compression = "NONE" :: ["NONE", "BYTES", "GZIP", "BZIP2", "DEFLATE", "BLOCK_LZ4", "FRAMED_SNAPPY"] }`. The default is: `{}`.
Return arguments	Name	Type	Description
Return arguments	`value`	`MAP`	A map of data loaded from the given file.

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;

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

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