Graphset

Overview

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

A graphset in Ultipa is either schema-free or schema-constrained.

Showing Graphsets

Retrieves graphsets in the database:

UQL
// Shows all graphsets
show().graph()

//Shows all graphsets with additional details (total_nodes, total_edges, etc.)
show().graph().more()

// Shows the specified graphset
show().graph("myGraph")

// Shows the specified graphset with additional details (total_nodes, total_edges, etc.)
show().graph("myGraph").more()

It returns the following tables:

The _graph table contains all graphsets in the database.
Each _graph_shard_<N> table contains the graphsets that have data stored in the shard with id <N>.

Each table includes fields that provide essential details about each graphset:

Field	Description
`id`	The unique id of the graphset.
`name`	The unique name assigned to the graphset.
`description`	The description given to the graphset.
`status`	The current state of the graphset, which can be `NORMAL`, `LOADING_SNAPSHOT`, `CREATING`, `DROPPING`, or `SCALING`.
`shards`	The ids of shards where the graph data is distributed.
`partition_by`	The function that computes the hash value for the sharding key, which is essential for sharding the graph data.
`meta_version`	The version number utilized by meta servers to synchronize DDL (Data Definition Language) operations on the graphset with shard servers.
`total_nodes`	The total count of nodes in the graphset. Only available in `_graph` when the `more()` method is used.
`total_edges`	The total count of edges in the graphset. Only available in `_graph` when the `more()` method is used.
`schema_free`	Whether the graph is schema-free.

Creating Graphsets

You can create a graphset using the create().graph() statement.

Syntax
create().graph("<name>", "<desc?>")
  .schemaFree()
  .shards(<shardList>)
  .partitionByHash(<hashFunc>, <shardKey?>)

Method	Param	Description
`graph()`	`<name>`	The unique name of the graphset. Naming conventions are: 2 to 127 characters. Begins with a letter. Allowed characters: letters (A-Z, a-z), numbers (0-9) and underscores (`_`).
`graph()`	`<desc?>`	Optional. Description of the graphset.
`schemaFree()`	/	Optional. Indicates whether the graph is schema-free. A schema-free graph doesn't require explicit schema definitions 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.
`shards()`	`<shardList>`	Optional. The list of ids of shards where the graph data will be stored. Defaults to all shards.
`partitionByHash()`	`<hashFunc>`	Optional. The function (`Crc32`, `Crc64WE`, `Crc64XZ`, or `CityHash64`) that computes the hash value for the sharding key, which is essential for sharding the graph data. Defaults to `Crc32`. For more information, refer to Crc and CityHash.
`partitionByHash()`	`<shardKey?>`	Optional. The node property used as the sharding key. Only `_id` is supported now.

To create a graphset named g1 and distribute its data to shards [1,2,3] using the CityHash64 function based on the _id of nodes:

UQL
create().graph("g1").shards([1,2,3]).partitionByHash(CityHash64, _id)

To create a graph g2:

UQL
create().graph("g2")

To create a schema-free graph g3:

UQL
create().graph("g3").schemaFree()

Altering Name and Description

You can modify name and description of a graphset using the alter().graph().set() statement.

To alter both name and description of the graphset myGraph

UQL
alter().graph("myGraph").set({name: "superGraph", description: "Graph used for transactions"})

To alter name of the graphset myGraph:

UQL
alter().graph("myGraph").set({name: "superGraph"})

To alter description of the graphset myGraph:

UQL
alter().graph("myGraph").set({description: "Graph used for transactions"})

To remove description of the graphset myGraph:

UQL
alter().graph("myGraph").set({description: ""})

Migrating Graphset Data

As data in a graphset 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. Use the alter().graph().shards().partitionConfig() statement to migrate data for a graph.

Syntax
alter().graph("<graphName>").shards(<shardList>).partitionConfig({strategy: "<rsStrat>"})

Method	Param	Description	Optional
`graph()`	`<graphName>`	Specifies the graphset.	No
`shards()`	`<shardList>`	Non-empty list of ids of shards where the graph data will be stored. This must differ from the current shard list and align with the `strategy` set in `partitionConfig()`.	No
`partitionConfig()`	Config map	Specifies the migration `strategy`, which can be set as follows: `balance`: Redistributes all graph data evenly across the new shards. `quickly_expand`: Quickly migrates some data from existing shards to newly added shards. The `<shardList>` must include all current shards. `quickly_shrink`: Quickly migrates data from removed shards to the remaining shards. The `<shardList>` can only be a subset of the current shards. When this method is omitted, `balance` is used by default.	Yes

Assuming the graphset myGraph is currently distributed across shards 1 and 2. To migrate myGraph from shards [1,2] to [1,4,5]:

UQL
alter().graph('myGraph').shards([1,4,5]).partitionConfig({strategy: "balance"})

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

UQL
alter().graph('myGraph').shards([3]).partitionConfig({strategy: "balance"})

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

UQL
alter().graph('myGraph').shards([1,2,4]).partitionConfig({strategy: "quickly_expand"})

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

UQL
alter().graph('myGraph').shards([1]).partitionConfig({strategy: "quickly_shrink"})

Dropping Graphsets

You can drop one or more graphsets using a single drop() statement. Each graphset is specified by chaining a graph() method. Dropping a graphset deleting the entire graphset from the database.

To drop the graphset myGraph:

UQL
drop().graph("myGraph")

To drop two graphsets:

UQL
drop().graph("myGraph_1").graph("myGraph_2")

By default, a graphset cannot be deleted if it still has existing HDC graphs. To bypass this restriction and force the deletion, use the force() method:

UQL
drop().graph("myGraph_1").graph("myGraph_2").force()

Truncating a Graphset

You can truncate a graph using the truncate().graph() 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.

UQL
// Truncates the graphset 'myGraph' (all nodes and edges will be deleted)
truncate().graph("myGraph")

// Truncates all @user nodes (edges attached to them will be deleted too)
truncate().graph("myGraph").nodes(@user)

// Truncates all nodes (all edges will be deleted too)
truncate().graph("myGraph").nodes("*")

// Truncates all @link edges
truncate().graph("myGraph").edges(@link)

// Truncates all edges
truncate().graph("myGraph").edges("*")

Compacting a Graphset

You can compact a graphset 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 the graphset myGraph:

UQL
compact().graph("myGraph")

NOTE

Data manipulation operations can generate redundant data, such as the old records retained after being updated or deleted. It's suggested to regularly compact graphsets to reclaim storage space and improve query efficiency.