:readme:
:branch: 3.3
:docs: https://neo4j-contrib.github.io/neo4j-apoc-procedures/index33.html
:apoc-release: 3.3.0.1
:neo4j-version: 3.3.0
:img: https://raw.githubusercontent.com/neo4j-contrib/neo4j-apoc-procedures/{branch}/docs/img

image:https://travis-ci.org/neo4j-contrib/neo4j-apoc-procedures.svg[alt="Travis CI Status", link="https://travis-ci.org/neo4j-contrib/neo4j-apoc-procedures"] image:https://img.shields.io/maven-central/v/org.neo4j.procedure/apoc.svg[alt="Maven status"] image:https://img.shields.io/github/release/neo4j-contrib/neo4j-apoc-procedures.svg[alt="Github release status"] image:https://img.shields.io/github/contributors/neo4j-contrib/neo4j-apoc-procedures.svg[alt="contributor stats"]

= Awesome Procedures for Neo4j {branch}.x

// tag::warnings[]

[WARNING]
====
Neo4j 3.2 has increased security for procedures and functions (aka sandboxing).
Procedures that use internal APIs have to be allowed in `$NEO4J_HOME/conf/neoj4.conf` with, e.g. `+dbms.security.procedures.unrestricted=apoc.trigger.*,apoc.meta.*+` for security reasons (or `+apoc.*+` for all).

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.
====

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

Neo4j 3.2 introduces user defined aggregation functions, we will use that feature in APOC in the future, e.g. for export, graph-algorithms and more, instead of passing in Cypher statements to procedures.

Please note that about 70 procedures have been turned from procedures into user defined functions.
This includes, `+apoc.date.* apoc.number.*, apoc.coll.*, apoc.map.*+` and some more packages.
See, this https://github.com/neo4j-contrib/neo4j-apoc-procedures/issues/144[issue] for a list. 
====

// end::warnings[]

== 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 algorithms, spatial, and more.

// tag::readme[]

== Introduction

// tag::intro[]
// tag::intro-text[]

image::{img}/apoc.gif[float=right]

Neo4j 3.0 introduced the concept of user defined procedures.
Those are custom implementations of certain functionality, that can't be (easily) expressed in Cypher itself.
Those procedures 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 300) procedures to help with many different tasks in areas like data integration, graph algorithms or data conversion.

=== License

Apache License 2.0

=== "APOC" Name history

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 Components] for Neo4j in 2009.

*APOC* also stands for "Awesome Procedures On Cypher"

== Installation

=== Download latest release

Go to http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/{apoc-release}
to find the latest release and download the binary jar to place into your `$NEO4J_HOME/plugins` folder.

NOTE: For *Neo4j Desktop* the `plugins` directory is in a different place, put the jar-file into these (make sure to replace all at upgrade).
See the https://neo4j.com/docs/operations-manual/current/configuration/file-locations/[Neo4j Manual] for more detail about the install locations.

* OSX: `/Applications/Neo4j\ Community\ Edition\ <version>.app/Contents/Resources/app/plugins` *AND* `/Users/<user>/Documents/Neo4j/default.graphdb/plugins`
* Windows: `C:\Program Files\Neo4j CE <version>\plugins`

// 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.

[options=headers]
|===
|apoc version | neo4j version
| http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.3.0.1[3.3.0.1] | 3.3.0 (3.3.x)
| http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.2.0.5[3.2.0.5] | 3.2.3 (3.2.x)
| http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.2.0.4[3.2.0.4] | 3.2.2
| http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.2.0.3[3.2.0.3] | 3.2.0
| http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.1.3.9[3.1.3.9] | 3.1.6 (3.1.x)
| http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.1.3.8[3.1.3.8] | 3.1.5
| http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.1.3.7[3.1.3.7] | 3.1.4
| http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.1.2.5[3.1.2.5] | 3.1.2
| http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.1.0.4[3.1.0.4] | 3.1.0-3.1.1 
| 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)
|3.0.4.3 | 3.0.4
|1.1.0 | 3.0.0 - 3.0.3
|1.0.0 | 3.0.0 - 3.0.3
|===

// 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 Neo4j Docker image

The https://hub.docker.com/_/neo4j/[Neo4j Docker image] allows to supply a volume for the `/plugins` folder. Download the APOC release fitting your Neo4j version to local folder `plugins` and provide it as a data volume:

[source,bash,subs=attributes]
----
mkdir plugins
pushd plugins
wget 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:{neo4j-version}
----

// end::intro-text[]
// tag::build[]

=== Build & install the current development branch from source

----
git clone http://github.com/neo4j-contrib/neo4j-apoc-procedures
./gradlew shadow
cp build/libs/apoc-<version>-SNAPSHOT-all.jar $NEO4J_HOME/plugins/
$NEO4J_HOME/bin/neo4j restart
----

// 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[]
// tag::calling-procedures[]

== Calling Procedures & Functions within Cypher

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]
----
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::calling-procedures[]

// end::intro[]


== APOC Procedures & Functions Overview

All included procedures are listed in the link:{docs}#_overview_of_apoc_procedures_functions[overview in the documentation] and detailed in subsequent sections.

== Feedback

Please provide feedback and report bugs as link:./issues[GitHub issues] or join the http://neo4j.com/slack[neo4j-users Slack] and ask on the #apoc channel.
You might also ask on http://stackoverflow.com/questions/tagged/neo4j+apoc[StackOverflow], please tag your question there with `neo4j` and `apoc`.

=== Built in Help

// tag::help[]

image::{img}/apoc-help-apoc.jpg[width=600]

[cols="1m,5"]
|===
| call apoc.help('search') | lists name, description, signature, roles, based on search-string
|===

// end::help[]

// 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")` (which itself uses `dbms.procedures()` and `dbms.functions()`)

[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[]
