apoc.import.json

Details
Syntax	`apoc.import.json(urlOrBinaryFile [, config ]) :: (file, source, format, nodes, relationships, properties, time, rows, batchSize, batches, done, data)`
Description	Imports a graph from the provided JSON file.
Input arguments	Name	Type	Description
	`urlOrBinaryFile`	`ANY`	The name of the file or binary data to import the data from.
	`config`	`MAP`	`{ unwindBatchSize = 5000 :: INTEGER, txBatchSize = 5000 :: INTEGER, importIdName = "neo4jImportId" :: STRING, nodePropertyMappings = {} :: MAP, relPropertyMappings = {} :: MAP, compression = "NONE" :: ["NONE", "BYTES", "GZIP", "BZIP2", "DEFLATE", "BLOCK_LZ4", "FRAMED_SNAPPY”], cleanup = false :: BOOLEAN, nodePropFilter = {} :: MAP, relPropFilter = {} :: MAP }`. The default is: `{}`.
Return arguments	Name	Type	Description
	`file`	`STRING`	The name of the file from which the data was imported.
	`source`	`STRING`	The source of the imported data: "file", "binary" or "file/binary".
	`format`	`STRING`	The format of the file: ["csv", "graphml", "json"].
	`nodes`	`INTEGER`	The number of imported nodes.
	`relationships`	`INTEGER`	The number of imported relationships.
	`properties`	`INTEGER`	The number of imported properties.
	`time`	`INTEGER`	The duration of the import.
	`rows`	`INTEGER`	The number of rows returned.
	`batchSize`	`INTEGER`	The size of the batches the import was run in.
	`batches`	`INTEGER`	The number of batches the import was run in.
	`done`	`BOOLEAN`	Whether the import ran successfully.
	`data`	`ANY`	The data returned by the import.

Config parameters

This procedure supports the following config parameters:

Config parameters
Name	Type	Default	Description
`unwindBatchSize`	`INTEGER`	`5000`	The batch size of the unwind.
`txBatchSize`	`INTEGER`	`5000`	The batch size of the transaction.
`importIdName`	`STRING`	`neo4jImportId`	The name of the property to be populated with the "id" field present into the json. For example a row `{"type":"node", "labels":["Language"], "id":"10"}`, with importIdName:`foo`, will create a node `(:User {foo: "10"})`
`nodePropertyMappings`	`MAP`	`{}`	The mapping label/property name/property type for Custom Neo4j types (point date). I.e. { User: { born: 'Point', dateOfBirth: 'Datetime' } }
`relPropertyMappings`	`MAP`	`{}`	The mapping rel type/property name/property type for Custom Neo4j types (point date). I.e. { KNOWS: { since: 'Datetime' } }
`compression`	`Enum[NONE, BYTES, GZIP, BZIP2, DEFLATE, BLOCK_LZ4, FRAMED_SNAPPY]`	`null`	Allow taking binary data, either not compressed (value: `NONE`) or compressed (other values)
`cleanup`	`BOOLEAN`	false	To remove the "id" field present into the json, if present. Note that in this way we cannot import relationship, because we leverage on "id" field to connect the nodes.
`nodePropFilter`	`MAP<STRING, LIST<STRING>>`	`{}`	A map with the labels as keys, and the list of property keys to filter during the import as values. For example `{ User: ['name', 'surname'], Another: ['foo']}` will skip the properties 'name' and 'surname' of nodes with label 'User' and the property 'foo' of (:Another) nodes. Note that if a node has multiple labels, in this example `(:User:Another {})`, all properties of both labels will be filtered, that is 'name', 'surname', and 'foo'. We can also pass a key `_all` to filter properties of all nodes, for example `{_all: ['myProp']}`
`relPropFilter`	`MAP<STRING, LIST<STRING>>`	`{}`	A map with the relationship types as keys, and the list of property keys to filter during the import as values. For example `{ MY_REL: ['foo', 'baz'] }` will skip the properties 'foo' and 'baz' of '[:MY_REL]' relationship. We can also pass a key `_all` to filter properties of all relationships, for example `{_all: ['myProp']}`

nodePropertyMappings and relPropertyMappings support the following Neo4j types:

POINT
DATE
LOCAL TIME
LOCAL DATETIME
DURATION
ZONED TIME
ZONED DATETIME

Usage Examples

The apoc.import.json procedure can be used to import JSON files created by the apoc.export.json.* procedures, exported using the config parameter jsonFormat: 'JSON_LINES' (default config).

all.json contains a subset of Neo4j’s movies graph, and was generated by apoc.export.json.all.

all.json

{"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}}}

We can import this file using apoc.import.json.

CALL apoc.import.json("file:///all.json")

Results

| file               | source | format | nodes | relationships | properties | time | rows | batchSize | batches | done | data
| "file:///all.json" | "file" | "json" | 3     | 1             | 15         | 105  | 4    | -1        | 0       | TRUE | NULL

Uniqueness Constraints

In order to avoid duplicate imported values, a uniqueness constraint is required on all imported node labels and relationship types. If this constraint is missing, the procedure will return an error message providing both information about the missing constraint and the command that will create it. (Because this procedure uses WRITE mode it cannot itself add constraints.)

Example 1. Importing a JSON file before and after creating a uniqueness constraint

The file missingConstraint.json contains the following:

{"type":"node","id":"1","labels":["Test"],"properties":{"name":"A test name"}}

Executing the following query on a database with no constraints will throw an error:

CALL apoc.import.json("file:///missingConstraint.json")

Error message

Failed to invoke procedure `apoc.import.json`: Caused by: java.lang.RuntimeException: Missing constraint required for import. Execute this query:
CREATE CONSTRAINT FOR (n:Test) REQUIRE n.neo4jImportId IS UNIQUE;

The last line of the error message provides the necessary statement to create the constraint:

CREATE CONSTRAINT FOR (n:Test) REQUIRE n.neo4jImportId IS UNIQUE;

After adding the constraint, the import will run successfully:

CALL apoc.import.json("file:///missingConstraint.json")

Results

| file                             | source | format | nodes | relationships | properties | time | rows | batchSize | batches | done | data
| "file:///missingConstraint.json" | "file" | "json" | 1     | 0             | 2          | 24   | 1    | -1        | 0       | TRUE | NULL

Binary file

You can also import a file from a binary byte[] not compressed (default value, with config {compression: NONE}) or a compressed file (allowed compression algos are: GZIP, BZIP2, DEFLATE, BLOCK_LZ4, FRAMED_SNAPPY). That is:

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

or:

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

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

WITH apoc.util.compress('{"type":"node","id":"2","labels":["User"],"properties":{"age":12}}', {compression: 'DEFLATE'}) AS jsonCompressed
CALL apoc.import.json(jsonCompressed, {compression: 'DEFLATE'})
YIELD source, format, nodes, relationships, properties
RETURN source, format, nodes, relationships, properties

Results

| source | format | nodes | relationships | properties
| "binary" | "json" | 1     | 0             | 2