Constraints

Overview

Constraints enforce additional rules on the node and edge properties in the graph. Any attempt to insert or update data that violates these rules will result in an error.

Ultipa supports the following constraints in typed graphs:

• NOT NULL: Ensures that a property never contains null values.
• UNIQUE: Ensures that a property contains no duplicate values.
• NODE KEY: Ensures that key properties are non-null and the combination is unique within a specific node schema.
• EDGE KEY: Ensures that key properties are non-null and the combination is unique across all edge schemas in the graph.

Showing Constraints

To show node constraints in the current graph:

GQL
SHOW NODE CONSTRAINT

To show edge constraints in the current graph:

GQL
SHOW EDGE CONSTRAINT

The plural form SHOW NODE|EDGE CONSTRAINTS is also supported.

Each constraint provides the following essential metadata:

Creating Constraints

You can define constraints when creating a graph, creating a graph type, or within an existing graph. When creating constraints in an existing graph, it execute as a job, you may run SHOW JOB <id?> afterward to verify its success.

Note that creating a constraint in a large graph may take time, as the system must scan all existing data to ensure compliance. The creation will fail if any existing data violates the constraint, and the constraint status will be set to FAILED. To maintain data consistency, all other data modification operations are temporarily suspended during the constraint creation process.

NOT NULL

The NOT NULL constraint ensures that a property never contains null values.

To create a NOT NULL constraint on the property name of the User nodes:

GQL
ALTER NODE User ADD CONSTRAINT NOT NULL ON name

To create a NOT NULL constraint on the property weight of the link edges:

GQL
ALTER EDGE link ADD CONSTRAINT NOT NULL ON weight

The NOT NULL constraint can only be successfully created when there is no null values exist in the specified property.

You can apply the NOT NULL constraint to any property when creating a typed graph:

GQL
CREATE GRAPH g1 { 
  NODE User ({name STRING NOT NULL, age UINT32}),
  EDGE Follows ()-[{createdOn LOCAL DATETIME NOT NULL}]->()
}

You can also apply the NOT NULL constraint to any property when creating a graph type:

GQL
CREATE GRAPH TYPE gType { 
  NODE User ({name STRING NOT NULL, age UINT32}),
  EDGE Follows ()-[{createdOn LOCAL DATETIME NOT NULL}]->()
}

UNIQUE

The UNIQUE constraint ensures that a property contains no duplicate values. A UNIQUE constraint can be defined on either a single property or multiple properties.

Single-Property UNIQUE

To create a UNIQUE constraint on the property name of the User nodes:

GQL
ALTER NODE User ADD CONSTRAINT UNIQUE ON name

To create a UNIQUE constraint on the property weight of the link edges:

GQL
ALTER EDGE link ADD CONSTRAINT UNIQUE ON weight

The UNIQUE constraint can only be successfully created when there is no duplicated values exist in the specified property.

Composite UNIQUE

To create a composite UNIQUE constraint on the properties name and uid of the User nodes:

GQL
ALTER NODE User ADD CONSTRAINT UNIQUE ON name, uid

To create a composite UNIQUE constraint on the properties weight and eid of the link edges:

GQL
ALTER EDGE link ADD CONSTRAINT UNIQUE ON weight, eid

The UNIQUE constraint can be created successfully only when the combined values of all specified properties contain no duplicates.

UNIQUE with max_length

You can specify a max_length option for string properties when creating a UNIQUE constraint:

GQL
ALTER NODE User ADD CONSTRAINT UNIQUE ON email WITH {max_length: {email: 100}}

UNIQUE During Graph Creation

You can apply the UNIQUE constraint to any property when creating a typed graph:

GQL
CREATE GRAPH g1 { 
  NODE User ({name STRING UNIQUE, age UINT32}),
  EDGE Follows ()-[{createdOn LOCAL DATETIME UNIQUE}]->()
}

UNIQUE During Graph Type Creation

You can also apply the UNIQUE constraint to any property when creating a graph type:

GQL
CREATE GRAPH TYPE gType { 
  NODE User ({name STRING UNIQUE, age UINT32}),
  EDGE Follows ()-[{createdOn LOCAL DATETIME UNIQUE}]->()
}

NODE KEY

The NODE KEY constraint combines NOT NULL and UNIQUE — all key properties must be non-null, and the combination of key property values must be unique within a schema. A NODE KEY constraint can be defined on either a single property or multiple properties. It applies to nodes only.

Single-Property NODE KEY

To create a NODE KEY constraint on the property ssn of the User nodes:

GQL
ALTER NODE User ADD CONSTRAINT NODE KEY ON ssn

To successfully create the NODE KEY:

• The ssn property must not contain any null values.
• The ssn property must not contain any duplicate values.

Composite NODE KEY

To create a composite NODE KEY constraint on the properties first_name, last_name, and date_of_birth of the User nodes:

GQL
ALTER NODE User ADD CONSTRAINT NODE KEY ON first_name, last_name, date_of_birth

To successfully create the NODE KEY:

• None of the specified properties may contain null values.
• The combination of values across all specified properties must not contain any duplicates.

NODE KEY with max_length

You can specify a max_length option for string properties:

GQL
ALTER NODE User ADD CONSTRAINT NODE KEY ON first_name, last_name WITH {max_length: {first_name: 50, last_name: 50}}

NODE KEY During Graph Creation

You can apply the NODE KEY constraint when creating a typed graph:

GQL
CREATE GRAPH g1 {
  NODE User ({ssn STRING NODE KEY, name STRING, age UINT32}),
  EDGE Follows ()-[{createdOn LOCAL DATETIME}]->()
}

NODE KEY During Graph Type Creation

You can also apply the NODE KEY constraint when creating a graph type:

GQL
CREATE GRAPH TYPE gType {
  NODE User ({ssn STRING NODE KEY, name STRING, age UINT32}),
  EDGE Follows ()-[{createdOn LOCAL DATETIME}]->()
}

EDGE KEY

The EDGE KEY constraint specifies a property as the unique identifier for all edges in the graph, ensuring that its values are both non-null and unique. An EDGE KEY constraint can be defined on either a single property or multiple properties.

Details

• Only one EDGE KEY constraint can be defined per graph, either a single-property EDGE KEY or a composite EDGE KEY.
• EDGE KEY doesn't apply to properties of the type LIST.
• EDGE KEY properties are automatically cached to accelerate query performance.
• When the EDGE KEY is created, uniqueness is enforced within each shard. Duplicates may exist across shards at creation time, but all subsequent data modifications must comply with global uniqueness.

Single-Property EDGE KEY

To specify the edge property eID as EDGE KEY:

GQL
ALTER EDGE * ADD CONSTRAINT EDGE KEY ON eID INT32

To successfully create the EDGE KEY:

• All edges must possess an eID property of type INT32.
• The eID property doesn’t contain existing null or duplicated values.

When the property value type is not specified, it defaults to STRING:

GQL
ALTER EDGE * ADD CONSTRAINT EDGE KEY ON tag

In this case, all edges must have a tag property of type STRING.

Composite EDGE KEY

To specify the edge properties eID and tag as EDGE KEY:

GQL
ALTER EDGE * ADD CONSTRAINT EDGE KEY ON eID INT32, tag STRING

To successfully create the EDGE KEY:

• All edges must possess an eID property of type INT32 and a tag property of type STRING.
• Neither the property eID nor tag may contain existing null values.
• The combination of the values of eID and tag must not contain any duplicated values.

EDGE KEY During Graph Creation

You can apply the EDGE KEY constraint when creating a typed graph:

GQL
CREATE GRAPH g1 { 
  NODE User ({name STRING , age UINT32}),
  NODE Club ({name STRING}),
  EDGE Follows ()-[{createdOn LOCAL DATETIME}]->(),
  EDGE Joins ()-[]->()
}
EDGE KEY eID INT64, tag STRING

The specified EDGE KEY properties eID and tag will be automatically created for all edge schemas.

EDGE KEY During Graph Type Creation

You can apply the EDGE KEY constraint when creating a graph type:

GQL
CREATE GRAPH TYPE gType { 
  NODE User ({name STRING, age UINT32}),
  NODE Club ({name STRING}),
  EDGE Follows ()-[{createdOn LOCAL DATETIME}]->(),
  EDGE Joins ()-[]->()
}
EDGE KEY eID INT64

The specified EDGE KEY property eID will be automatically created for all edge schemas when this graph type is used.

Using IF NOT EXISTS

The IF NOT EXISTS clause prevents errors when attempting to create a constraint that already exists.

GQL
ALTER NODE User ADD CONSTRAINT IF NOT EXISTS NOT NULL ON name

This creates the constraint only if there is no existing NOT NULL constraint on the name property of User nodes. If such a constraint already exists, the statement is ignored without throwing an error.

Naming Conventions

Constraint names must be unique. Each constraint name must:

• Contain 2 to 64 characters.
• Begin with a letter.
• Allowed characters: letters (A-Z, a-z), numbers (0-9) and underscores (_).

Dropping Constraints

To drop the NOT NULL constraint on the name property of User nodes from the current graph:

GQL
ALTER NODE User DROP CONSTRAINT NOT NULL ON name

To drop the UNIQUE constraint on the name property of User nodes from the current graph:

GQL
ALTER NODE User DROP CONSTRAINT UNIQUE ON name

To drop the NODE KEY constraint on the ssn property of User nodes from the current graph:

GQL
ALTER NODE User DROP CONSTRAINT NODE KEY ON ssn

To drop the EDGE KEY constraint from the current graph:

GQL
ALTER EDGE * DROP EDGE KEY

You can also drop a constraint by its name:

GQL
ALTER NODE User DROP CONSTRAINT unique_email

Using IF EXISTS

The IF EXISTS clause prevents errors when attempting to drop a constraint that does not exist:

GQL
ALTER NODE User DROP CONSTRAINT IF EXISTS NOT NULL ON name
ALTER NODE User DROP CONSTRAINT IF EXISTS unique_email

Restrictions on Properties with Constraints

Renaming Properties

Properties with the NOT NULL or UNIQUE constraints can be renamed. However, renaming properties with an EDGE KEY constraint is not allowed.

Dropping Properties

A property with a constraint cannot be dropped until all the related constraints are deleted.