Awesome Procedures for ONgDB 1.0.x

Introduction

ONgDB 1.0 introduces the concept of user-defined procedures and functions. Those are custom implementations of certain functionality, that can’t be (easily) expressed in Geequel itself. They are implemented in Java and can be easily deployed into your ONgDB instance, and then be called from Geequel 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.

License

Apache License 2.0

Feedback

Please provide feedback and report bugs as GitHub issues or join the Graph Foundation community Slack.

Calling Procedures & Functions within Geequel

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 Geequel statements which makes them so much more powerful.

Load JSON example

WITH 'https://raw.githubusercontent.com/graphfoundaiton/ongdb-apoc/{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)

APOC Procedures & Functions Overview

All included procedures are listed in the overview in the documentation and detailed in subsequent sections.

Built in Help

call apoc.help('keyword')

lists name, description, signature, roles, based on keyword

Detailed Feature Documentation

See the APOC User Guide for documentation of each of the major features of the library, including data import/export, graph refactoring, data conversion, and more.

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")

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?)

Table 1. Parameter Explanation

Name	Type
Procedure Parameters
startNode	Node
endNode	Node
relationshipTypesAndDirections	String
weightPropertyName	String
Output Return Columns
path	Path
weight	Float

Manual Installation: Download latest release

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

Go to the latest release for ONgDB version 1.0 and download the binary jar to place into your $ONGDB_HOME/plugins folder.

You can find all releases here.

Manual Configuration

Warning

Procedures that use internal APIs have to be allowed in $ONGDB_HOME/conf/ongdb.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 ONGDB_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.*

Version Compatibility Matrix

Since APOC relies in some places on ONgDB’s internal APIs you need to use the right APOC version for your ONgDB installation.

APOC uses a consistent versioning scheme: <ongdb-version>.<apoc> version. The trailing <apoc> part of the version number will be incremented with every apoc release.

apoc version	ongdb version
3.5.0.4	3.5.6 (3.5.x)
3.4.0.7	3.4.12 (3.4.x)
3.3.0.4	3.3.6 (3.3.x)
3.2.3.6	3.2.9 (3.2.x)
3.1.3.9	3.1.7 (3.1.x)
3.0.8.6	3.0.5-3.0.9 (3.0.x)
3.5.0.0	3.5.0-beta01
3.4.0.2	3.4.5
3.3.0.3	3.3.5
3.2.3.5	3.2.3
3.1.3.8	3.1.5

Get APOC Version

To know your current apoc version you can use the function :

RETURN apoc.version();

Using APOC with the ONgDB Docker image

The ONgDB Docker image allows to supply a volume for the /plugins folder. Download the APOC release matching your ONgDB version to local folder plugins and provide it as a data volume:

mkdir plugins
pushd plugins
wget https://github.com/graphfoundation/ongdb-apoc/releases/download/1.0.0.0/apoc-1.0.0.0-all.jar
popd
docker run --rm -e ONGDB_AUTH=none -p 7474:7474 -v $PWD/plugins:/plugins -p 7687:7687 graphfoundation/ongdb:1.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 ongdb-apoc \
    -e ONGDB_apoc_export_file_enabled=true \
    -e ONGDB_apoc_import_file_enabled=true \
    -e ONGDB_apoc_import_file_use__ongdb__config=true \
    graphfoundation/ongdb:1.0

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

Build & install the current development branch from source

git clone https://github.com/graphfoundation/ongdb-apoc
cd ongdb-apoc
./gradlew shadow
cp build/libs/apoc-<version>-all.jar $ONGDB_HOME/plugins/
$ONGDB_HOME/bin/ongdb restart

A full build including running the tests can be run by ./gradlew build.