UUIDs

The library supports manual and automation generation of UUIDs, which can be stored as properties on nodes.

UUIDs are generated using the java randomUUID utility method, which generates a v4UUID.

UUID may be encoded into String with well-known hexadecimal presentation (32 characters, e.g. 1051af4f-b81d-4a76-8605-ecfb8ef703d5) or Base64 (22 characters, e.g. vX8dM5XoSe2ldoc/QzMEyw)

Automatic UUIDs

There are also procedures that handle automatic adding of UUID properties, via the UUID Handler Lifecycle. The UUID handler is a transaction event handler that automatically adds the UUID property to a provided label and for the provided property name. Please check the following documentation to an in-depth description.

All these procedures (except the list and show ones) are intended to be executed in the system database, therefore they have to be used executed by opening a system database session. There are several ways of doing this: - when using cypher-shell or Neo4j Browser, one can prefix their Cypher query with :use system - when using fabric, one can prefix their Cypher query with USE system - when using the drivers, one can open a session directly against the system database

Moreover, they accept as first parameter the name of the database towards which we want to install/update/remove the automatic UUIDs. Through this implementation, we can use these procedures in a cluster environment, by leveraging the cluster routing mechanism.

Installing, updating or removing an automatic UUID is an eventually consistent operation. Therefore, they are not immediately added/updated/removed, but they have a refresh rate handled by the Apoc configuration apoc.uuid.refresh=<MILLISECONDS>

Enable apoc.uuid.enabled=true or apoc.uuid.enabled.[DATABASE_NAME]=true in $NEO4J_HOME/config/apoc.conf first.

Configuration value apoc.uuid.format let you choose between different UUID encoding methods: hex (default option) or base64.

Qualified Name Type Release

apoc.uuid.setup

CALL apoc.uuid.setup(databaseName, label, $config) | eventually adds the uuid transaction handler for the provided `label and uuidProperty, in case the UUID handler is already present it will be replaced by the new one`

Procedure

Apoc Extended

apoc.uuid.drop

CALL apoc.uuid.drop(databaseName, label) yield label, installed, properties | eventually removes previously added UUID handler and returns uuid information

Procedure

Apoc Extended

apoc.uuid.dropAll

CALL apoc.uuid.dropAll(databaseName) yield label, installed, properties | eventually removes all previously added UUID handlers and returns uuids' information

Procedure

Apoc Extended

apoc.uuid.list

CALL apoc.uuid.list() yield label, installed, properties | provides a list of all the uuid handlers installed with the related configuration

Procedure

Apoc Extended

apoc.uuid.show

CALL apoc.uuid.show(databaseName) | it lists all eventually installed UUID handler for a database

Procedure

Apoc Extended

UUID Examples

Create an Automatic UUID

This examples assume that we are on the neo4j database, and we want to create the automatic UUIDs in that database.

Add the uuid:

CALL apoc.uuid.setup('Person')
YIELD label, installed, properties
RETURN label, installed, properties

Note that the apoc.uuid.setup, as well as the apoc.uuid.drop, apoc.uuid.dropAll, have to be executed in the system database.

The result is:

label installed properties

"Person"

true

{uuidProperty → "uuid", addToExistingNodes → true}

When an apoc.uuid.setup procedure is executed, a query to create a constraint, if not exists, is automatically executed (also in this case, after a time defined by the apoc.uuid.refresh config): CREATE CONSTRAINT IF NOT EXISTS FOR (n:<label>) REQUIRE (n.<uuidProperty>) IS UNIQUE

It is then possible to execute the following query, after a time defined by the configuration apoc.uuid.refresh:

CREATE (n:Person {name: 'Daniel'})-[:Work]->(:Company {name: 'Neo4j'})

and the result will be a node :Person with 2 properties:

apoc.uuid.result

If the default configuration addToExistingNodes: true is chosen, in background (via the apoc.periodic.iterate procedure) all existing nodes will also be populated with a property with uuid values. and, when the execution is finished, a log with the query result like the following will be printed:

Result of batch computation obtained from existing nodes for UUID handler with label `MyLabel`:
{failedParams={}, committedOperations=1, batch={total=10, committed=10, failed=0, errors={}}, wasTerminated=false, batches=1, timeTaken=0, retries=0, errorMessages={}, total=1, operations={total=10, committed=10, failed=0, errors={}}, failedOperations=0, updateStatistics={nodesDeleted=0, labelsAdded=0, relationshipsCreated=0, nodesCreated=0, propertiesSet=1, relationshipsDeleted=0, labelsRemoved=0}, failedBatches=0}

List of Automatic UUIDs

It is possible to return the full list of automatic UUIDS in a database. For example, if the UUID in the following query is created:

CALL apoc.uuid.setup('TestShow')

It is then possible to run (also in this case, after a time defined by the configuration apoc.uuid.refresh):

CALL apoc.uuid.show()
Table 1. Results
label installed properties "Person"

Please note that, since the auto-UUID operations are eventually consistent (based on the apoc.uuid.refresh configuration), the apoc.uuid.show may return some UUIDs not yet added/updated/removed. To get the list of all of currently installed UUIDs, use the apoc.uuid.list

Remove Automatic UUIDs

CALL apoc.uuid.drop('Person')
YIELD label, installed, properties
RETURN label, installed, properties

The result is:

label installed properties

"Person"

false

{uuidProperty → "uuid", addToExistingNodes → true}

You can also remove all the uuid installed call the procedure as:

CALL apoc.uuid.dropAll()
YIELD label, installed, properties
RETURN label, installed, properties

The result is:

label installed properties

"Person"

false

{uuidProperty → "uuid", addToExistingNodes → true}

Export metadata

To import uuids in another database (for example after a ./neo4j-admin backup and /neo4j-admin restore), please see the apoc.systemdb.export.metadata procedure.