Chapter 5. Awesome Procedures on Cypher - APOC

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

That was for those among you who know how Neo4j is tinted with Matrix love. However, that does not explain what APOC of in our context. APOC stands for both of the following:

• A Package Of Components
• Awesome Procedures On Cypher

Both are right.

Started in 2009, APOC is a collection of functions and procedures that are available for use in Cypher. They cover the following subjects:

• Collection operations (sorting, min, max, and so on)
• Graph operations (indexes and refactoring)
• Text search
• Conversions
• Ranking
• Geospatial operations
• Data integration
• Reporting
• Getting a meta graph representing your graph

So, contrarily to the Matrix universe, Cypher does not kill APOC, not even the contrary.  APOC gives more procedures, more life to Cypher.

Installing APOC

The first step is to download the APOC version corresponding to your Neo4j version (same major and minor number), which can be seen in the Neo4j browser after clicking on the first tab in the upper-left corner of the screen. The next steps vary, depending on how you run Neo4j.

On a hardware server

If you have installed Neo4j on a hardware machine, whether it runs Windows, OS X, or Linux, stop your Neo4j server with the following command:

neo4j stop

Then copy the downloaded jar in the plugins subfolder and restart your server:

neo4j start

You can now jump to the paragraph Verifying APOC installation.

On a Docker container

First, you have to stop your container, as seen previously.

Then, providing you followed the instructions of the Chapter 2, Getting Started with Neo4j, cd into the neo4j folder you created and create a plugins directory:

cd ~/neo4j
mkdir plugins

In this new folder, copy the APOC JAR archive that you have downloaded.

Then, we will restart the container with a new file...

Verifying APOC installation

With your server started, you may now go to your Neo4j browser and input the following query:

CALL dbms.functions() YIELD name
WHERE name STARTS WITH 'apoc.'
RETURN count(name)
UNION 
CALL dbms.procedures() YIELD name
WHERE name STARTS WITH 'apoc.'
RETURN count(name)

This is a UNION query that will return two lines, fortunately with non-zero numbers. My result at the time of writing this is 98, then 201. Note that this is not using APOC, but built-in functions.

Note

A UNION query returns the concatenation of the results of two queries returning the same columns.

This means 98 functions and 201 procedures. I presume that soon, the formidable community and the uncomparable Michael Hunger (@mesirii) will reach 365 functions or procedures and we will have a new APOC calendar to go with the old wisdom that says:

One APOC a day keeps verbosity away.

I just made up this old wisdom, of course. Nevertheless, using APOC will keep the verbosity away from your queries because, in...

Functions and procedures

As I mentioned before, APOC contains functions and procedures; let's see how they differ. The keyword is complexity.

Functions are giving simpler services than procedures. Functions are designed to return a single value after a computation that only reads the database. Consequently, as you will have inferred, procedures can make changes to the database and return several results.

Procedures have to be CALL-ed. Functions can be referenced directly in a Cypher query (function is in bold).

CREATE (p:Person{GUID:apoc.create.UUID()})

We will see in a later chapter how to write our own functions and procedures.

My preferred usages 

Before we see the key usages of APOC, I would like to show you my preferred ones; you will notice that calling them looks a lot like one half of the UNION query previously seen, as the keyword to use APOC procedures goodness is CALL.

A little help from a friend

Considering there are almost 300 items in APOC, it is user-friendly to provide this function: an entry-point to APOC. Should we want to find all the procedures and functions that contain the word meta in their name or description, we should use this query:

CALL apoc.help('meta')

The result is as follows:

Meta-related APOC search result

The text field will give you a clear text description. The signature field details the parameters and the values returned. Don't get impressed with it.

This query is very useful; I added it as a favorite (by pressing the Star button at the right of the query input zone) for quicker access. 

Graph overview

This query will give you an overview of your database:

CALL apoc.meta.graph   // This...

Several key usages

Let's see some key usages; others will be seen in dedicated chapters, such as Chapter 8, Importing data into Neo4j.

Setup

First, we need to grant permissions to the APOC functions and procedures, so we need to add the following line to the end of the conf/neo4j.conf file; otherwise, we would get an error message like this one--apoc.algo.pagerank is not available due to having restricted access rights, check configuration:

dbms.security.procedures.unrestricted=apoc.*

Random graph generators

Well, not so random  graph generators, for there is an algorithm to choose and parameters to input. I call it random because it's meaningless:

CALL apoc.generate.ba(1000, 2, 'Person', 'FRIEND_OF')

This example uses the Barabasi-Albert (ba) model to generate a thousand nodes with the label Person that have two FRIEND_OF relations. As Person is a common label, each node will have a name property, which looks as follows, added automatically:

A lot of friends, connected

Be aware that this can create...

Test questions

Question 1: APOC is an awesome collection of procedures and functions

1. True.
2. False.

Question 2: APOC is a single man project

1. True.
2. False.

Question 3: There is a "dial 911" (US), "dial 112" (EU) command  in APOC, is it:

1. CALL apoc.help("me Micheal")
2. CALL apoc.112("me, Benoit")

Question 4: APOC allows to limitate resource usage:

1. True.
2. False.

Question 5: Which APOC innovation allows you to get a bird's eye view on your graph ?

1. CALL db.schema()
2. CALL apoc.meta.graph()
3. both, depending on context

Question 6: What is APOC made of ?

1. Pectin
2. Coffee
3. Bits
4. All of that

Question 7: What is TTL ?

1. Acronym of through the lens, a way to measure light for cameras
2. The time to live of nodes, for data that would be meaningful after a period

Summary

In this chapter, you have learned what is APOC, how to install and use it, what APOC is made of (not pectin), what are the differences between functions and procedures. We went through some key usages and listed others.

By knowing how to find information about the subjects that arouse your curiosity in APOC, you gained autonomy on this topic. You now know that APOC is good for you and probably already has the functions/procedures you are looking for.

Now, let's move on to the next chapter to learn how to extend the Cypher language.