Constraints

Overview

Constraints enforce additional rules on the property values given to nodes and edges in the graph. Any attempt to insert or update data that violates these rules will result in an error.

Ultipa supports the following constraints:

• NOT NULL: Enforces a property cannot have null values.
• EDGE KEY: Designates some properties as the unique identifier for all edges in the graph.

Showing Constraints

To show constraints created on node properties in the current graph:

SHOW NODE CONSTRAINT

To show constraints created on edge properties in the current graph:

SHOW EDGE CONSTRAINT

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. To maintain data consistency, all other data modification operations are temporarily suspended during the constraint creation process.

NOT NULL

The NOT NULL constraint enforces a property cannot have null values, ensuring that a value is always provided. The NOT NULL constraint can only be defined on a single property.

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

ALTER NODE User ADD CONSTRAINT NOT NULL ON name

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

ALTER EDGE link ADD CONSTRAINT NOT NULL ON weight

These constraints 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:

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:

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

EDGE KEY

The EDGE KEY constraint designates one or multiple properties as the unique identifier for all edges in the graph, ensuring that these properties are both non-null and unique. When multiple properties are specified, it is also referred to as a composite EDGE KEY.

Details

• Only one EDGE KEY 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

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.
• eID doesn’t contain existing null or duplicated values.

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

ALTER EDGE * ADD CONSTRAINT EDGE KEY ON tag

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

Composite EDGE KEY

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 eID nor tag may contain existing null values.
• The combination 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:

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:

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 is used to prevent errors when attempting to create a constraint that already exists. It allows the statement to be safely executed.

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.

Dropping Constraints

To drop the EDGE KEY constraint from the current graph:

ALTER EDGE * DROP EDGE KEY

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

ALTER NODE User DROP CONSTRAINT NOT NULL ON name

Restrictions on Properties with Constraints

Renaming Properties

Properties with the NOT NULL 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.