apoc.uuid.install

Procedure APOC Full

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

Signature

apoc.uuid.install(label :: STRING?, config = {} :: MAP?) :: (batchComputationResult :: MAP?, label :: STRING?, installed :: BOOLEAN?, properties :: MAP?)

Input parameters

Name Type Default

label

STRING?

null

config

MAP?

{}

Config parameters

The procedure support the following config parameters:

Table 1. Config parameters
name type default description

addToExistingNodes

Boolean

true

adds UUID values to existing nodes. Will override an existing value.

addToSetLabels

Boolean

false

adds UUID values even when there is a set label. For example: MATCH (p:OtherLabel) SET p:LabelWithUuid.

uuidProperty

String

"uuid"

the property key for the UUID value

Output parameters

Name Type

batchComputationResult

MAP?

label

STRING?

installed

BOOLEAN?

properties

MAP?

Enable automatic UUIDs

This procedure is part of a set of 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.

By default automatic adding of UUIDs is disabled. We can enable it by setting the following property in apoc.conf:

apoc.conf
apoc.uuid.enabled=true

Usage Examples

We need to create a unique constraint for the label and property on which we want to add UUIDs.

If we try to setup UUID creation on nodes with the Person label without adding a constraint, we’ll get an exception as shown below:

CALL apoc.uuid.install("Person");
Table 2. Results

Failed to invoke procedure apoc.uuid.install: Caused by: java.lang.RuntimeException: No constraint found for label: Person, please add the constraint with the following : CREATE CONSTRAINT ON (person:Person) ASSERT person.uuid IS UNIQUE

We can create a constraint on the (Person, uuid) label/property pair by running the following query:

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

And now we can automatically add UUIDs to all new nodes, as well as existing nodes, by running the following query:

CALL apoc.uuid.install("Person");

By default, UUID values will be added to existing nodes and will override existing values. We can pass the config addToExistingNodes: false to only have UUIDs added to new nodes.

Table 3. Results

batchComputationResult

label

installed

properties

{failedParams: {}, committedOperations: 3, batch: {total: 1, committed: 1, failed: 0, errors: {}}, wasTerminated: FALSE, batches: 1, timeTaken: 0, retries: 0, errorMessages: {}, total: 3, operations: {total: 3, committed: 3, failed: 0, errors: {}}, failedOperations: 0, failedBatches: 0}

"Person"

TRUE

{uuidProperty: "uuid"}

Now let’s create a new Person node;

CREATE (:Person {name: "Tom Hanks"});

And if we look for all Person nodes, we’ll see it has a uuid property:

MATCH (p:Person {name: "Tom Hanks"})
RETURN p;
Table 4. Results
p

(:Person {name: "Tom Hanks", uuid: "cec34337-9709-46af-bbb7-9e0742d8aaa7"})

The uuid property will be created also with a label SET when the addToSetLabels configuration is set to true. For example:

CREATE (:AnotherLabel {name: "Tom Hanks"});
// ...
MATCH (n:AnotherLabel) SET n:Person;

If we want to use a different property key for our UUID value, we can pass in the uuidProperty key, not forgetting to first setup a constraint:

CREATE CONSTRAINT ON (person:Person)
ASSERT person.myUUID IS UNIQUE;
CALL apoc.uuid.install("Person", {uuidProperty: "myUUID"});
Table 5. Results

batchComputationResult

label

installed

properties

{failedParams: {}, committedOperations: 1, batch: {total: 1, committed: 1, failed: 0, errors: {}}, wasTerminated: FALSE, batches: 1, timeTaken: 0, retries: 0, errorMessages: {}, total: 1, operations: {total: 1, committed: 1, failed: 0, errors: {}}, failedOperations: 0, failedBatches: 0}

"Person"

TRUE

{uuidProperty: "myUUID"}

And now let’s find those Person nodes again:

MATCH (p:Person {name: "Tom Hanks"})
RETURN p;
Table 6. Results
p

(:Person {name: "Tom Hanks", uuid: "cec34337-9709-46af-bbb7-9e0742d8aaa7", myUUID: "d09f177b-ff91-4eb9-aac0-73e7a850c9ba"})