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)

Manual UUIDs

Qualified Name Type Release

apoc.create.uuid

apoc.create.uuid() - creates an UUID

Function

APOC Core

apoc.create.uuidBase64

- create an UUID encoded with Base64

Function

APOC Core

apoc.create.uuidBase64ToHex

- convert between an UUID encoded with Base64 to HEX format

Function

APOC Core

apoc.create.uuidHexToBase64

- convert an UUID in HEX format to encoded with Base64

Function

APOC Core

Usage Examples

The following generates a UUID

RETURN apoc.create.uuid() AS uuid;
Table 1. Results
uuid

"1051af4f-b81d-4a76-8605-ecfb8ef703d5"

The following creates a Person node, using a UUID as the merging key:

MERGE (p:Person {id: apoc.create.uuid()})
SET p.firstName = "Michael", p.surname = "Hunger"
RETURN p
Table 2. Results
p

{"firstName":"Michael","surname":"Hunger","id":"5530953d-b85e-4939-b37f-a79d54b770a3"}

The following generates a new UUID encoded with Base64:

RETURN apoc.create.uuidBase64() as output;
Table 3. Results
Output

"vX8dM5XoSe2ldoc/QzMEyw"

The following converts an UUID encoded with Base64 to HEX representation:

RETURN apoc.create.uuidHexToBase64("bd7f1d33-95e8-49ed-a576-873f433304cb") as output;
Table 4. Results
Output

"vX8dM5XoSe2ldoc/QzMEyw"

The following converts an UUID encoded with Base64 to HEX representation:

RETURN apoc.create.uuidBase64ToHex("vX8dM5XoSe2ldoc/QzMEyw") as output;
Table 5. Results
Output

"bd7f1d33-95e8-49ed-a576-873f433304cb"

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.

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

CALL apoc.uuid.install(label, {addToExistingNodes: true/false, uuidProperty: 'uuid'}) yield label, installed, properties, batchComputationResult | it will add 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 Full

apoc.uuid.remove

CALL apoc.uuid.remove(label) yield label, installed, properties | remove previously added uuid handler and returns uuid information. All the existing uuid properties are left as-is

Procedure

APOC Full

apoc.uuid.removeAll

CALL apoc.uuid.removeAll() yield label, installed, properties | it removes all previously added uuid handlers and returns uuids information. All the existing uuid properties are left as-is

Procedure

APOC Full

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 Full

Config

config

type

description

addToExistingNodes

Boolean (default: true)

when installed, for the label provided, adds the UUID to the nodes already existing in your graph

uuidProperty

String (default: uuid)

the name of the UUID field

UUID Examples

First create a Constraint for the Label and the Property, if you try to add a uuid an error occured.

CREATE CONSTRAINT ON (person:Person)
ASSERT person.uuid IS UNIQUE

Add the uuid:

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

The result is:

label installed properties batchComputationResult

"Person"

true

{uuidProperty → "uuid", addToExistingNodes → true}

{wasTerminated → false, count → 10, batches → 1, successes → 1, failedOps → 0, timeTaken → 0, operationErrors → {}, failedBatches → 0}

The result is Node Person that has 2 properties:

apoc.uuid.result

Get all the uuid installed, call the procedure as:

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

The result is:

label installed properties

"Person"

true

{uuidProperty → "uuid", addToExistingNodes → true}

Remove the uuid installed call the procedure as:

CALL apoc.uuid.remove('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.removeAll()
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.