Graph

This page introduces statements for managing graphs and graph types in a database.

Showing Graphs

The SHOW GRAPH statement retrieves information about all graphs in the database.

SHOW GRAPH

The information about graphs is organized into different 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

Syntax

The CREATE GRAPH statement create a new graph in the database.

<create graph statement> ::= 
  "CREATE GRAPH" [ "IF NOT EXISTS" ] <graph name> [ <graph type> ] [ <graph sharding> ] [ <graph description> ]

<graph type> ::=
  <graph type specification> | <graph type reference> | <graph type like graph>

<graph type reference> ::=
  [ < "::" | "TYPED" > ] <graph type name>

<graph type like graph> ::=
  "LIKE" <existing graph name>
   
<graph sharding> ::= 
  "PARTITION BY" <hash function> "SHARDS" <shard id list> 
    
<graph description> ::=
  "COMMENT" <comment string>

When creating a graph, you can specify the following:

Without a Graph Type

To create a graph g1 with only its name specified, the graph data will be distributed to all shards using the Crc32 hash function by default:

CREATE GRAPH g1

Customizing Graph Type

To create a graph g1 which defines node schemas User and Club, edge schemas Follows and Joins, and a composite EDGE KEY constraint, the graph data will be distributed across shards 1, 2, and 3 using the CityHash64 hash function:

CREATE GRAPH g1 { 
  NODE User ({username string NOT NULL encrypt("AES128") COMMENT "Username, cannot be null", gender string}),
  NODE Club ({name string, since uint32}),
  EDGE Follows ()-[{createdOn datetime}]->(),
  EDGE Joins ()-[{memberNo uint64}]->()
} 
EDGE KEY time timestamp, eID int64
PARTITION BY HASH(CityHash64) SHARDS [1,2,3] 
COMMENT 'My first graph'

To create a graph g2, no property is associated with node and edge schemas, the graph data will be distributed to all shards using the Crc32 hash function by default:

CREATE GRAPH g2 { 
  NODE User (),
  NODE Club (),
  EDGE Follows ()-[]->(),
  EDGE Joins ()-[]->()
}

To create a graph g3 without any node or edge schemas, the graph data will be distributed only to shard 1 using the default Crc32 hash function:

CREATE GRAPH g3 {} SHARDS [1]

Reusing Graph Type

To create a graph g1 from the graph type gType, the graph data will be distributed to all shards using the Crc32 hash function by default:

CREATE GRAPH g1 gType

or

CREATE GRAPH g1 :: gType

or

CREATE GRAPH g1 TYPED gType

To create a graph g2 from the graph type gType, the graph data will be distributed across shards 1, 2, and 3 using the CityHash64 hash function:

CREATE GRAPH g2 gType
PARTITION BY HASH(CityHash64) SHARDS [1,2,3] 
COMMENT 'This is the description'

Reusing Graph Type of a Graph

To create a graph g1 from an existing graph named trans, the graph data will be distributed to all shards using the Crc32 hash function by default:

CREATE GRAPH g1 LIKE trans

To create a graph g2 from an existing graph named trans, the graph data will be distributed across shards 1, 2, and 3 using the CityHash64 hash function:

CREATE GRAPH g2 LIKE trans
PARTITION BY HASH(CityHash64) SHARDS [1,2,3] 
COMMENT 'This is the description'

Using IF NOT EXISTS

The IF NOT EXISTS clause is used 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.

Renaming Graphs

The ALTER GRAPH statement can be used to rename a graph in the database.

To rename the graph amz to amazon:

ALTER GRAPH amz RENAME TO amazon

Altering Graph Descriptions

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

To update the description of the graph amz:

ALTER GRAPH amz 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]

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.

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 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 property types, and constraints.

Showing Graph Types

The SHOW GRAPH TYPE statement retrieves information about all graph types in the database.

SHOW GRAPH TYPE

Graph type information is organized into the table _graphType with the following fields:

Creating Graph Types

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

<create graph type statement> ::= 
  "CREATE GRAPH TYPE" [ "IF NOT EXISTS" ] <graph type name> <graph type specification>

<graph type specification> ::= 
  "{" [ <element schema> [ { "," <element schema> }... ] ] "}" [ <edge key constarint> ]
  
<element schema> ::=
  <node schema> | <edge schema>
    
<node schema> ::=
  "NODE" <schema name> "(" [ <property types> ] ")"

<edge schema> ::=
  "EDGE" <schema name> "()-[" [ <property types> ] "]->()"
  
<property types> ::= 
  "{" <property type> [ { "," <property type> }... ] "}"

<property type> ::= 
  <property name> <property value type> [ <constraint name> ] [ <encryption> ] [ <property description> ]

<property description> ::=
  "COMMENT" <comment string>

<edge key constraint> ::=
  "EDEG KEY" <property name> <property value type> [ { "," <property name> <property value type> }... ]

When creating a graph type, you can specify the following:

Note: The label set of a node or edge schema <schema name> is inferred as :<schema name>.

To create a graph type gType which defines node schemas User and Club, edge schemas Follows and Joins, and a composite EDGE KEY constraint:

CREATE GRAPH TYPE gType { 
  NODE User ({username string NOT NULL encrypt("AES128") COMMENT "Username, cannot be null", gender string}),
  NODE Club ({name string, since uint32}),
  EDGE Follows ()-[{createdOn datetime}]->(),
  EDGE Joins ()-[{memberNo uint64}]->()
} EDGE KEY time timestamp, eID int64

The following graph type creation fails because the edge schema Follows contains an edge key property eID but with a different value type (string v.s. int64):

CREATE GRAPH TYPE gType { 
  NODE User ({username string NOT NULL encrypt("AES128") COMMENT "Username, cannot be null", gender string}),
  NODE Club ({name string, since uint32}),
  EDGE Follows ()-[{createdOn datetime, eID string}]->(),
  EDGE Joins ()-[{memberNo uint64}]->()
} EDGE KEY time timestamp, eID int64

To create a graph type gType_empty without any node or edge schemas:

CREATE GRAPH TYPE gType_empty {}

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.