Graph

Overview

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

This page introduces how to manage graphs and graph types in a database.

Showing Graphs

Retrieves all graphs in the database:

SHOW GRAPH

It returns the following tables:

• The _graph table contains all graphs in the database.
• Each _graph_shard_<id> table contains the graphs that have data stored in shard <id>.

Ultipa Manager has been configured to display only the _graph table.

Each table includes the following fields:

Creating Graphs

Two types of graphs can be created in Ultipa:

1. Open Graph. An open graph is schema-free where no explicit schema definitions are required before inserting data. You can directly insert nodes and edges into the graph, and the corresponding schemas and properties will be automatically created on the fly. How to create an open graph

2. Typed Graph. A graph type defines all allowed node and edge schemas (types), and is composed of the following key components:

• Node schemas: A node schema consists of a schema name (which also acts as it label) and a set of properties. Each graph includes a built-in default node schema.
• Edge schemas: An edge schema consists of a schema name (which also acts as it label) and a set of properties. Each graph includes a built-in default edge schema.
• Properties: Attributes associated with node or edge schemas, defined by a name and a value type.
• Constraints: Additional rules applied to properties to ensure date accuracy, consistency, and integrity. How to define constraints during graph creation

Any data inserted into the graph must conform to its graph type - nodes or edges with undefined schemas or properties cannot be added. While the graph type is not immutable and can be adjusted, it sets a strict framework that governs data insertion. How to create a graph of a graph type

These two approaches to graph modeling offer a powerful blend of flexibility and control, supporting workflows that range from early-stage data exploration to production-grade applications demanding strict data integrity.

Graph data will be physically stored on the shard servers that make up the database deployment. You may run one or multiple shard servers, depending on your setup. For any graph, one or multiple shard servers can be designated to store nodes and edges in a distributed manner. How to configure graph sharding

Creating Open Graph

To create an open graph g1:

CREATE GRAPH g1 ANY

The ANY keyword identifies an open graph.

Creating Typed Graph

Empty Graph Type

To create a graph g2 with an empty graph type:

CREATE GRAPH g2

Although the graph type of g2 is empty, it is not an open graph. You must add node or edge schemas to the graph before inserting any data.

Customized Graph Type

To create a graph g3 with a graph type specification, which defines:

• Node schema User with properties name (STRING type) and age (UINT32 type).
• Node schema Club with no properties.
• Edge schema Follows with a property createdOn (LOCAL DATETIME type).
• Edge schema Joins with no properties.

CREATE GRAPH g3 { 
  NODE User ({name STRING, age UINT32}),
  NODE Club (),
  EDGE Follows ()-[{createdOn LOCAL DATETIME}]->(),
  EDGE Joins ()-[]->()
}

Pre-Defined Graph Type

To create a graph g4 from the pre-defined graph type gType (see How to create a graph type):

CREATE GRAPH g4 gType

or

CREATE GRAPH g4 :: gType

or

CREATE GRAPH g4 TYPED gType

You can use the TYPED keyword, the :: operator, or omit them altogether to specify the graph type to be used.

Graph Type of Another Graph

To create a graph g5 by copying the graph type of an existing graph trans:

CREATE GRAPH g5 LIKE trans

The LIKE keyword specifies the graph whose graph type is to be copied.

Configuring Graph Sharding

You can explicitly define how a graph is distributed across the shard servers in your database, including:

• Hash function: A hash function (Crc32, Crc64WE, Crc64XZ, or CityHash64) computes the hash value for the sharding key (i.e., nodes' _id), which is essential for sharding the graph data. For more information, refer to Crc and CityHash.
• Shard ID list: A list of shard IDs indicating where the graph data will be stored.

By default, the graph data is to be distributed to all shards with Crc32.

To create a graph g6, setting the graph data to be distributed across shards [1,2,3] using the CityHash64 hash function:

CREATE GRAPH g6 { 
  NODE User ({name STRING, age UINT32}),
  NODE Club (),
  EDGE Follows ()-[{createdOn LOCAL DATETIME}]->(),
  EDGE Joins ()-[]->()
}
PARTITION BY HASH(CityHash64) SHARDS [1,2,3]

The PARTITION BY keyword specifies the hash function, the SHARDS keyword specifies the shard ID list. You can use either keyword independently.

After a graph is created, you may need to migrate its data to different shards. For details, see Migrating Graph Data.

Defining Constraints

You can include constraints in the graph type during graph creation to ensure the integrity and consistency of data that will be inserted into the graph.

To create a graph g7 with constraints:

• A NOT NULL constraint is applied to the name property of the User node schema, ensuring that every User node must have a non-NULL value for name.
• An EDGE KEY constraint is applied to all edge schemas. The specified property eID (INT64 type) will be automatically created for all edge schemas, and all values of eID will be both unique and non-NULL.

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

The NOT NULL constraint can be applied any individual properties, whereas the EDGE KEY constraint applies globally to all edges in the graph. You can also create a composite EDGE KEY constraint by specifying multiple properties:

CREATE GRAPH g7 { 
  NODE User ({name STRING NOT NULL, age UINT32}),
  NODE Club (),
  EDGE Follows ()-[{createdOn LOCAL DATETIME}]->(),
  EDGE Joins ()-[]->()
}
EDGE KEY eID INT64, weight FLOAT

In this example, the properties eID (INT64 type) and weight (FLOAT type) will be automatically created for all edge schemas; neither eID nor weight may contain NULL values, and the combination of eID and weight must not contain any duplicated values.

See this page for a detailed explanation of constraints and instructions on managing them after a graph is created.

Encrypting Properties

You can encrypt the values of a property using one of the supported encryption methods: AES128, AES256, RSA and ECC.

To create a graph g8, encrypting the name property of the User node schema:

CREATE GRAPH g8 { 
  NODE User ({name STRING encrypt("AES128"), age UINT32}),
  NODE Club (),
  EDGE Follows ()-[{createdOn LOCAL DATETIME}]->(),
  EDGE Joins ()-[]->()
}

Using IF NOT EXISTS

You can use the IF NOT EXISTS clause to prevent errors when attempting to create a graph that already exists. It allows the statement to be safely executed.

CREATE GRAPH IF NOT EXISTS g1

This creates the graph g1 only if a graph with that name does not exist. If g1 already exists, the statement is ignored without throwing an error.

Adding Comments

You can add comments to the graph and properties to improve clarity and understanding.

To create a graph g9, including comments for the graph and the createdOn property of the Follows edge schema:

CREATE GRAPH g9 { 
  NODE User ({name STRING, age UINT32}),
  NODE Club (),
  EDGE Follows ()-[{createdOn LOCAL DATETIME COMMENT "When the edge is established"}]->(),
  EDGE Joins ()-[]->()
}
COMMENT 'My social graph'

A Comprehensive Example

To create a graph g10 with its graph type specified:

CREATE GRAPH IF NOT EXIST g10 { 
  NODE User ({name STRING NOT NULL encrypt("AES128") COMMENT "Username, cannot be null", age UINT32}),
  NODE Club (),
  EDGE Follows ()-[{createdOn LOCAL DATETIME}]->(),
  EDGE Joins ()-[]->()
}
EDGE KEY eID INT64
PARTITION BY HASH(CityHash64) SHARDS [1,2,3]
COMMENT 'My social graph'

Altering Graph Name and Comment

The ALTER GRAPH statement can be used to alter the name and comment of a graph in the database.

To rename the graph amz to amazon:

ALTER GRAPH amz RENAME TO amazon

To update the comment of the graph amz:

ALTER GRAPH amz COMMENT 'Amazon dataset'

You can also perform both operations in a single ALTER GRAPH statement:

ALTER GRAPH amz RENAME TO amazon COMMENT 'Amazon dataset'

Migrating Graph Data

As data in a graph is distributed across shards, data migration may become necessary sometime — whether to more shards when existing ones become overloaded, or to distribute data across additional geographical locations. Conversely, migrating to fewer shards can free up underutilized resources, reduce costs, and simplify management. The ALTER GRAPH statement can be used to migrate data for a graph.

Assuming the graph myGraph is currently distributed across shards [1,2], to migrate it to [1,4,5]:

ALTER GRAPH myGraph ON SHARDS [1,4,5]

The default migration strategy is balance, which redistributes all graph data evenly across the new shards. In addition, you may specify one of the following strategies:

• quickly_expand: Quickly migrates some data from existing shards to newly added shards. The new shard list must include all current shards.
• quickly_shrink: Quickly migrates data from removed shards to the remaining shards. The new shard list must be a sub list of the current shards.

To quickly migrate myGraph from shards [1,2] to [1,2,4]:

ALTER GRAPH myGraph ON SHARDS [1,2,4] PARTITION CONFIG {strategy: "quickly_expand"}

To quickly migrate myGraph from shards [1,2] to [1]:

ALTER GRAPH myGraph ON SHARDS [1] PARTITION CONFIG {strategy: "quickly_shrink"}

Dropping Graphs

The DROP GRAPH statement drops a graph from the database.

To drop the graph g1:

DROP GRAPH g1

The IF EXISTS clause is used to prevent errors when attempting to delete a graph that does not exist. It allows the statement to be safely executed.

DROP GRAPH IF EXISTS g1

This deletes the graph g1 only if a graph with that name does exist. If g1 does not exist, the statement is ignored without throwing an error.

By default, a graph cannot be deleted if it still has existing HDC graphs. To bypass this restriction, use the FORCE keyword:

FORCE DROP GRAPH g1

Truncating Graphs

You can truncate a graph using the TRUNCATE statement. This operation deletes nodes and edges within the graph while preserving the graph itself and its defined graph type.

You may choose to truncate the entire graph, all nodes, all edges, or only the nodes or edges of a specific schema. Note that truncating nodes will also remove any edges connected to them.

To truncate myGraph:

TRUNCATE myGraph

To truncate all nodes in myGraph, note that all edges will be removed too:

TRUNCATE NODE * ON myGraph

To truncate all User nodes in myGraph, note that all edges connected to User nodes will be removed too:

TRUNCATE NODE User ON myGraph

To truncate all edges in myGraph:

TRUNCATE EDGE * ON myGraph

To truncate all Follows edges in myGraph:

TRUNCATE EDGE Follows ON myGraph

Compacting Graphs

You can compact a graph using the COMPACT GRAPH statement. This operation clears the invalid and redundant graph data from the server disk but does not make any changes to the valid data. The compact operation runs as a job, you may run SHOW JOB <id?> afterward to verify its completion.

To compact myGraph:

COMPACT GRAPH myGraph

Redundant data can be generated by some data manipulation operations, such as the old records retained after being updated or deleted. It's suggested to regularly compact graphs to reclaim storage space and improve query efficiency.

Managing Graph Types

The graph type defines structural rules for a graph by outlining the allowed node schemas, edge schemas, their associated properties and constraints. GQL allows you to define and store graph types in the database, making them reusable when creating new graphs.

Showing Graph Types

Retrieves all graph types in the database:

SHOW GRAPH TYPE

It returns a _graphType table with the following fields:

Creating Graph Types

The CREATE GRAPH TYPE statement creates a new graph type in the database.

To create a graph type gType:

CREATE GRAPH TYPE gType { 
  NODE User ({name STRING NOT NULL encrypt("AES128") COMMENT "Username, cannot be null", age UINT32}),
  NODE Club (),
  EDGE Follows ()-[{createdOn LOCAL DATETIME}]->(),
  EDGE Joins ()-[]->()
}
EDGE KEY eID INT64

Dropping Graph Types

The DROP GRAPH TYPE statement drops a graph type from the database.

To drop the graph type gType:

DROP GRAPH TYPE gType

The IF EXISTS clause is used to prevent errors when attempting to delete a graph type that does not exist. It allows the statement to be safely executed.

DROP GRAPH TYPE IF EXISTS gType

This deletes the graph type gType only if a graph type with that name does exist. If gType does not exist, the statement is ignored without throwing an error.

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 an underscore (_) or a tilde (~).
• Cannot contain backticks (`).
• Cannot use system property names or reserved words.

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 an underscore (_) or a tilde (~).
• Cannot contain backticks (`).
• Cannot use system property names or reserved words.

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.