Core Essentials

An instance of the Ultipa graph database can host one or more graphs (or graphsets), each representing a dataset or domain of interconnected nodes and edges.

The data within a graph conforms to its graph type, which defines structural rules and constraints of a graph by outlining the allowed node schemas, edge schemas, their associated properties, and constraints.

GQL Conformance Note

The Node Schema and Edge Schema align with the Node Type and Edge Type defined in the ISO GQL standard.

Node Schema

A node schema defines a type of nodes allowed in the graph. It comprises a node schema name and a set of property types.

For example, a User node schema includes properties name (string type) and age (int32 type):

NODE User ({name string, age int32})

The schema name User also serves as its label. This schema can be referenced using the label expression :User.

Each graph comes with a built-in node schema named default. The default node schema is available for free use but cannot be be renamed or deleted.

Edge Schema

An edge schema defines a type of directed edges between nodes. It comprises an edge schema name and a set of property types.

For example, a Links edge schema connects any two nodes and includes a property description (string type):

EDGE Links ()-[{description string}]->()

The schema name Links also serves as its label. This schema can be referenced using the label expression :Links.

Each graph comes with a built-in edge schema named default. The default edge schema is available for free use but cannot be be renamed or deleted.

Property

Properties are associated with a node or edge schema to describe attributes of nodes and edges. A property is defined by a its name and value type. For example, a name property of type string. See All Property Value Types.

In addition, a property can:

• Be encrypted.
• Be enforced with constraints.
• Include a description.

Here is an example:

NODE User ({key string NOT NULL encrypt("AES128") COMMENT "The key used for authentication"})

This defines a node schema User with a property named key of type string. The property:

• Has a NOT NULL constraint, ensuring a value must be provided.
• Is encrypted using AES128.
• Includes a description: "The key used for authentication".

System Property

Each node has two built-in system properties serving as unique identifiers: _id and _uuid. The _id value can be manually assigned, ensuring distinct identification of nodes, while the _uuid value is always generated by the system.

Each edge has a built-in system property serving as unique identifier: _uuid. Its value is always generated by the system. Meanwhile, each edge connects a source node to a destination node, its _from/_to and _from_uuid/_to_uuid identify its two end nodes.

Constraint

Constraints enforce additional rules on the data within a graph, ensuring its accuracy, consistency, and integrity. Any data modification that violates a constraint will trigger an error and be rejected.

Naming Conventions

Graph

The names of all graphs in a database must be unique. Each graph name must:

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

Graph Type

The names of all graph types in a database must be unique. Each graph type name must:

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

Node/Edge Schema

Each node or edge schema name must:

• Contain 2 to 127 characters.
• Cannot start with a tilde (~).
• Cannot contain backticks (`).
• Cannot use system property names or reserved keywords.

Node schema names must be unique among node schemas, and edge schema names must be unique among edge schemas. However, a node schema and an edge schema are allowed to share the same name.

Property

Each property name must:

• Contain 2 to 127 characters.
• Cannot start with a tilde (~).
• Cannot contain backticks (`).
• Cannot use system property names or reserved keywords.

Property names must be unique among a node schema or an edge schema.

Constraint

Constraint name must:

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

Constraint names must be unique.