Chapter 1. Introduction

This chapter provides an introduction to the APOC library, and instructions for installation and use.

Neo4j 3.x introduced the concept of user-defined procedures and functions. Those are custom implementations of certain functionality, that can’t be (easily) expressed in Cypher itself. They are implemented in Java and can be easily deployed into your Neo4j instance, and then be called from Cypher directly.

The APOC library consists of many (about 450) procedures and functions to help with many different tasks in areas like data integration, graph algorithms or data conversion.

APOC Name History. Apoc was the technician and driver on board of the Nebuchadnezzar in the Matrix movie. He was killed by Cypher.

APOC was also the first bundled A Package Of Component for Neo4j in 2009.

APOC also stands for "Awesome Procedures On Cypher"

1.1. Installation

1.1.1. Installation: With Neo4j Desktop

APOC is easily installed with Neo4j Desktop, after creating your database just go to the "Manage" screen and the "Plugins" tab. Then click "Install" in the APOC box and you’re done.

desktop apoc

1.1.2. Manual Installation: Download latest release

Since APOC relies in some places on Neo4j’s internal APIs you need to use the matching APOC version for your Neo4j installation. Make sure that the first two version numbers match between Neo4j and APOC.

Go to the latest release for Neo4j version 4.0 and download the binary jar to place into your $NEO4J_HOME/plugins folder.

You can find all releases here.

Procedures that use internal APIs have to be allowed in $NEO4J_HOME/conf/neo4j.conf with, e.g. dbms.security.procedures.unrestricted=apoc.* for security reasons.

If you want to use this via docker, you need to amend -e NEO4J_dbms_security_procedures_unrestricted=apoc.\\\* to your docker run …​ command. The three backslashes are necessary to prevent wildcard expansions.

You can also whitelist procedures and functions in general to be loaded using: dbms.security.procedures.whitelist=apoc.coll.*,apoc.load.*

1.1.3. Using APOC with the Neo4j Docker image

APOC can be used with the Neo4j Docker image via the NEO4JLABS_PLUGINS environment variable. If we use this environment variable, the APOC plugin will be downloaded and configured at runtime.

This feature is intended to facilitate using APOC in development environments, but it is not recommended for use in production environments.

The following runs Neo4j 4.0 in a Docker container with the latest version of the APOC Library. 

docker run \
    -p 7474:7474 -p 7687:7687 \
    -v $PWD/data:/data -v $PWD/plugins:/plugins \
    --name neo4j-apoc \
    -e NEO4J_apoc_export_file_enabled=true \
    -e NEO4J_apoc_import_file_enabled=true \
    -e NEO4J_apoc_import_file_use__neo4j__config=true \
    -e NEO4JLABS_PLUGINS=\[\"apoc\"\] \
    neo4j:4.0

We should see the following two lines in the output after running this command:

Fetching versions.json for Plugin 'apoc' from https://neo4j-contrib.github.io/neo4j-apoc-procedures/versions.json
Installing Plugin 'apoc' from https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/download/4.0.0.15/4.0.0.15-all.jar to /plugins/apoc.jar

In a production environment we should download the APOC release matching our Neo4j version and, copy it to a local folder, and supply it as a data volume mounted at /plugins.

The following downloads the APOC Library into the plugins directory and then mounts that folder to the Neo4j Docker container. 

mkdir plugins
pushd plugins
wget https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/download/4.0.0.15/apoc-4.0.0.15-all.jar
popd
docker run --rm -e NEO4J_AUTH=none -p 7474:7474 -v $PWD/plugins:/plugins -p 7687:7687 neo4j:4.0

If you want to pass custom apoc config to your Docker instance, you can use environment variables, like here:

docker run \
    -p 7474:7474 -p 7687:7687 \
    -v $PWD/data:/data -v $PWD/plugins:/plugins \
    --name neo4j-apoc \
    -e NEO4J_apoc_export_file_enabled=true \
    -e NEO4J_apoc_import_file_enabled=true \
    -e NEO4J_apoc_import_file_use__neo4j__config=true \
    neo4j

If you want to allow APOC’s procedures that use internal APIs, you need to amend -e NEO4J_dbms_security_procedures_unrestricted=apoc.\\\* to your docker run …​ command. The three backslashes are necessary to prevent wildcard expansions.

1.2. Usage

User defined Functions can be used in any expression or predicate, just like built-in functions.

Procedures can be called stand-alone with CALL procedure.name();

But you can also integrate them into your Cypher statements which makes them so much more powerful.

Load JSON example. 

WITH 'https://raw.githubusercontent.com/neo4j-contrib/neo4j-apoc-procedures/4.0/src/test/resources/person.json' AS url

CALL apoc.load.json(url) YIELD value as person

MERGE (p:Person {name:person.name})
   ON CREATE SET p.age = person.age, p.children = size(person.children)

1.3. Feedback

Please provide feedback and report bugs as GitHub issues or join the Neo4j Community Forum and ask in the APOC & Procedures category.