neo4j-contrib / Neo4j Apoc Procedures
Programming Languages
Projects that are alternatives of or similar to Neo4j Apoc Procedures
:readme: :branch: 4.2 :docs: https://neo4j.com/docs/labs/apoc/current :apoc-release: 4.2.0.2 :neo4j-version: 4.2.2 :img: https://raw.githubusercontent.com/neo4j-contrib/neo4j-apoc-procedures/{branch}/docs/images
= Awesome Procedures for Neo4j {branch}.x
// tag::readme[]
== Introduction
// tag::intro[] image::{img}/apoc.gif[float=right]
// tag::intro-text[] 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. // end::intro-text[]
=== License
Apache License 2.0
// tag::name-history[] === "APOC" Name history
// tag::name-history-text[] http://matrix.wikia.com/wiki/Apoc[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 http://neo4j.com/blog/convenient-package-neo4j-apoc-0-1-released/[A Package Of Component^] for Neo4j in 2009.
APOC also stands for "Awesome Procedures On Cypher" // end::name-history-text[] // end::name-history[]
== Installation: With Neo4j Desktop
// tag::install-desktop[]
APOC Full can be installed with http://neo4j.com/download[Neo4j Desktop], after creating your database, by going to the Manage
screen, and then the Plugins
tab.
Click Install
in the APOC box and wait until you see the "Installed" message.
// end::install-desktop[] image::{img}/desktop-apoc.jpg[width=800]
== Feedback
// tag::feedback[] Please provide feedback and report bugs as https://github.com/neo4j-contrib/neo4j-apoc-procedures/issues[GitHub issues] or join the https://community.neo4j.com/c/neo4j-graph-platform/procedures-apoc[Neo4j Community Forum and ask in the APOC & Procedures category^]. // end::feedback[]
// tag::calling-procedures[]
== Calling Procedures & Functions within Cypher
// tag::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 [source,cypher,subs=attributes]
WITH 'https://raw.githubusercontent.com/neo4j-contrib/neo4j-apoc-procedures/{branch}/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)
// end::usage[] // end::calling-procedures[]
// end::intro[]
== APOC Procedures & Functions Overview
All included procedures are listed in the link:{docs}/overview[overview in the documentation^] and detailed in subsequent sections.
=== Built in Help
// tag::help[] image::{img}/apoc-help-apoc.jpg[width=600]
[cols="1m,5"] |=== | call apoc.help('keyword') | lists name, description, signature, roles, based on keyword |===
// end::help[]
== Detailed Feature Documentation
See the link:{docs}[APOC User Guide^] for documentation of each of the major features of the library, including data import/export, graph refactoring, data conversion, and more.
// tag::signature[]
== Procedure & Function Signatures
To call procedures correctly, you need to know their parameter names, types and positions. And for YIELDing their results, you have to know the output column names and types.
INFO:The signatures are shown in error messages, if you use a procedure incorrectly.
You can see the procedures signature in the output of CALL apoc.help("name")
[source,cypher]
CALL apoc.help("dijkstra")
The signature is always name : : TYPE
, so in this case:
apoc.algo.dijkstra (startNode :: NODE?, endNode :: NODE?, relationshipTypesAndDirections :: STRING?, weightPropertyName :: STRING?) :: (path :: PATH?, weight :: FLOAT?)
.Parameter Explanation [opts=header,cols="m,m"] |=== | Name | Type h| Procedure Parameters | | startNode | Node | endNode | Node | relationshipTypesAndDirections | String | weightPropertyName | String h| Output Return Columns | | path | Path | weight | Float |===
// end::signature[]
== Manual Installation: Download latest release
// tag::install[]
Since APOC relies on Neo4j's internal APIs you need to use the matching APOC version for your Neo4j installaton. Make sure that the first two version numbers match between Neo4j and APOC.
Go to http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/{apoc-release}[the latest release] for Neo4j version {branch} and download the binary jar to place into your $NEO4J_HOME/plugins
folder.
You can find http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/[all releases here].
// end::install[]
== Manual Configuration
[WARNING]
// tag::warnings[]
For security reasons, procedures that use internal APIs are disabled by default.
They can be enabled by specifying config in $NEO4J_HOME/conf/neo4j.conf
e.g. +dbms.security.procedures.unrestricted=apoc.*+
If you want to do this when using the Neo4j Docker container, 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.
+dbms.security.procedures.whitelist=apoc.coll.*,apoc.load.*+
// end::warnings[]
You can also whitelist procedures and functions in general to be loaded using: // tag::version-matrix[] === Version Compatibility Matrix
Since APOC relies in some places on Neo4j's internal APIs you need to use the right APOC version for your Neo4j installaton.
APOC uses a consistent versioning scheme: <neo4j-version>.<apoc>
version.
The trailing <apoc>
part of the version number will be incremented with every apoc release.
[opts=header] |=== |apoc version | neo4j version | http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/4.2.0.2[4.2.0.2^] | 4.2.2 (4.2.x) | http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/4.1.0.4[4.1.0.4^] | 4.1.1 (4.1.x) | http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/4.0.0.16[4.0.0.16^] | 4.0.6 (4.0.x) | http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.5.0.11[3.5.0.11^] | 3.5.16 (3.5.x) | http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.4.0.4[3.4.0.6^] | 3.4.12 (3.4.x) | http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.3.0.4[3.3.0.4^] | 3.3.6 (3.3.x) | http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.2.3.6[3.2.3.6^] | 3.2.9 (3.2.x) | http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.1.3.9[3.1.3.9^] | 3.1.7 (3.1.x) | http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.0.8.6[3.0.8.6^] | 3.0.5-3.0.9 (3.0.x) | http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.5.0.0[3.5.0.0^] | 3.5.0-beta01 | http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.4.0.2[3.4.0.2^] | 3.4.5 | http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.3.0.3[3.3.0.3^] | 3.3.5 | http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.2.3.5[3.2.3.5^] | 3.2.3 | http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.1.3.8[3.1.3.8^] | 3.1.5 |===
// end::version-matrix[] === Get APOC Version
To know your current apoc
version you can use the function :
[source,cypher]
RETURN apoc.version();
=== Using APOC with the Neo4j Docker image
// tag::docker[]
APOC Full can be used with the https://hub.docker.com/_/neo4j/[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.
[NOTE]
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 [source,bash]
-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
docker run We should see the following two lines in the output after running this command:
[source,text,subs=attributes]
https://neo4j-contrib.github.io/neo4j-apoc-procedures/versions.json Installing Plugin 'apoc' from https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/download/{apoc-release}/{apoc-release}-all.jar to /plugins/apoc.jar
Fetching versions.json for Plugin 'apoc' fromIn 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
.
plugins
directory and then mounts that folder to the Neo4j Docker container
[source,bash,subs=attributes]
.The following downloads the APOC Library into the https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/download/{apoc-release}/apoc-{apoc-release}-all.jar popd docker run --rm -e NEO4J_AUTH=none -p 7474:7474 -v $PWD/plugins:/plugins -p 7687:7687 neo4j:{branch}
mkdir plugins pushd plugins wgetIf you want to pass custom apoc config to your Docker instance, you can use environment variables, like here:
[source,bash]
-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
docker run // end::docker[] // tag::build[]
=== Build & install the current development branch from source
http://github.com/neo4j-contrib/neo4j-apoc-procedures cd neo4j-apoc-procedures ./gradlew shadow cp build/libs/apoc--all.jar $NEO4J_HOME/plugins/ $NEO4J_HOME/bin/neo4j restart
git clone// If you want to run embedded or use neo4j-shell on a disk store, configure your plugins
directory in conf/neo4j.conf
with dbms.plugin.directory=path/to/plugins
.
A full build including running the tests can be run by ./gradlew build
.
// end::build[]