Better Know APOC #0: Introduction

APOC

As all developers in good languages know – arrays and blog series start at 0, not 1 (sorry VB developers) so this is the introductory post to the upcoming series about APOC and it’s procedures etc.

What is APOC?

APOC stands for Awesome Procedures On Cypher – and is a large collection of community functions and procedures for use in Neo4j. You can read more about it on the page linked to above. Also – just so you know – I’m going to refer to them as procedures to save writing ‘functions and procedures’ all the time – because I’m lazy.

Setup for these posts

A lot of this stuff is listed on the APOC page, but use this as a quick get up to speed guide for when you’re reading the subsequent posts on here.

Setup – Configuration

You’ll need to setup your DB to be able to run the procs. We do this by adding a configuration property to your neo4j.conf file. The simplest (but most insecure) would be to add:

dbms.security.procedures.unrestricted=apoc.*

which will allow you to run all the APOC procedures. In the posts I’ll give a more specific version so you can execute just the ones we’re looking at, but if you have the above configuration property in your config – you can ignore that part of the posts.

Some of the procedures (export/import generally) require an additional configuration property, but that’ll be covered in the posts.

Setup – Data

90% of the time, if I can get away with it – I’m going to use the ‘Movies’ example database, it has many benefits – it’s a well-known type of data (most people know Movies have Actors etc) and it’s available to everyone who has Neo4j running.

To get the data you run:

:play movies

In the Neo4j Browser. Press the ‘next’ arrow and run the first query you see. You don’t need to do the rest.

Common stuff

The APOC procedures generally follow a common pattern, and there are some things you can do to help yourself

Get help

This is the first and most basic thing you can do – APOC has a built in help procedure, which you can run to get the signature of the procedure you’re interested in. In the posts the signatures will come from this method:

CALL apoc.help(‘NAME OF PROC’)

This will return a table with 5 columns:

  • Type: Whether it’s a procedure or function – this is important so you know how to call the thing
  • Name: If you’ve put in a non-complete name for help, this will tell you which proc you’re actually looking at
  • Text: Erm
  • Signature: This is the signature of the procedure (the most important bit from our POV)
  • Roles: If you have security setup – this is which roles can see/use this procedure
  • Writes: Ahhh

The signature is the main thing and that can be broken down into 2 parts, innies and outies, initially it can look a bit daunting as it’s one big lump of text, but break it down and it becomes easier:

image

Type wise – they’re all Java types, so easy to understand (Map = Dictionary .Netters).

Now you have the info – you have to pass all the parameters in – i.e. if there are 3 parameters, you can’t just pass in 2 and default the 3rd, you have to pass in all 3.

The Config Parameter

Pretty much all of the procedures will have this parameter:

config :: MAP?

This is a general config dictionary that allows the procedures to take in a large number of parameters without making the parameters list 1/2 a mile long (that’s 0.8KM my European friends).

It’s a Map<String, Object> and to set it when calling in Cypher you use the curly brace technique, so let’s say I want to set a parameter called ‘verbose’ to ‘true’ I would put:

{ verbose:true }

Easy – adding another parameter like (for example) ‘format’ and ‘json’ I would do:

{ verbose: true, format: ‘json’ }

One thing to bear in mind if you decide to look through the source code (and you should to see what these things are doing) is that the Config isn’t always just for the method you’re looking at.

For example ExportConfig is used by:

  • apoc.export.csv.*
  • apoc.export.cypher.*
  • apoc.export.graphml.*
  • etc

So whilst ExportConfig might well list 7 properties – the method you’re looking at may only actually use one of them – and setting the others will have no effect.

4 Replies to “Better Know APOC #0: Introduction”

Leave a Reply