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?	{}

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?

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"})