Overview
An HDC projection resides in the memory of an HDC (High-Density Computing) server, containing either full or partial data from a graphset loaded from the physcial storage of shard servers. HDC projections support all graph algorithms and data-retrieving graph queries.
HDC projections are managed by meta server. The latest HDC projection list is synchronized from meta server to name server during each heartbeat cycle. This list on name servers is referenced whenever HDC algorithms or queries are executed. Therefore, after creating or dropping an HDC projection, it is recommended to wait for two heartbeat intervals before performing further operations on the affected HDC projection. To adjust the heartbeat interval, update the heartbeat_interval_s
setting (defaults to 3 seconds) in the Server
section of the name server configuration.
Managing HDC Projections
Showing HDC Projections
Retrieves information about all HDC projections of the current graphset:
hdc.graph.show()
Or retrieves a specific projection, such as the one named hdcGraph_1
:
hdc.graph.show("hdcGraph_1")
It returns a table _projectList
with the following fields:
Field |
Description |
---|---|
project_name |
Name of the projection. |
project_type |
Type of the projection, which is hdc for all HDC projections. |
graph_name |
Name of the current graphset from which the data was loaded. |
status |
Current state of the projection, which can be DONE or CREATING , FAILED or UNKNOWN . |
stats |
Statistics about nodes and edges included in the projection, including their schemas, properties and total counts. |
is_default |
Indicates if it is the default HDC projection for the current graphset. |
hdc_server_name |
Name of the HDC server hosting the projection. |
hdc_server_status |
Current state of this HDC server, which can be ACTIVE or DEAD . |
config |
Configurations for the HDC projection. |
When retrieving a specific projection using hdc.graph.show("<projectName>")
, two supplementary tables are returned:
_graph_from_<hdcName>
: Shows all HDC projections created on<hdcName>
._algoList_from_<hdcName>
: Lists all algorithms installed on<hdcName>
.
Here, <hdcName>
is the name of the HDC server where the projection was created.
Creating an HDC Projection
The hdc.graph.create().to()
statement creates an in-memory projection of the current graphset to an HDC server. The project creation is executed as a job, you may run show().job(<id?>)
afterward to verify the success of the creation.
hdc.graph.create("<projectName>", {
nodes: {
"<schema1?>": ["<property1?>", "<property2?>", ...],
"<schema2?>": ["<property1?>", "<property2?>", ...],
...
},
edges: {
"<schema1?>": ["<property1?>", "<property2?>", ...],
"<schema2?>": ["<property1?>", "<property2?>", ...],
...
},
direction: "<edgeDirection?>",
load_id: <boolean?>,
update: "<dataSyncMode>",
query: "query",
default: <boolean?>
}).to("<hdcName>")
Method | Param | Description | Optional | |
---|---|---|---|---|
create() |
<projectName> |
Name of the projection. Each HDC projection name within an HDC server must be unique and cannot duplicate the name of any distributed projection of the same graphset. | No | |
Config Map | nodes |
Specifies nodes to project based on schemas and properties. The _uuid is loaded by default, while _id is configurable with load_id . Sets to "*": ["*"] to load all nodes. |
Yes | |
edges |
Specifies edges to project based on schemas and properties. All system properties are loaded by default. Sets to "*": ["*"] to load all edges. |
Yes | ||
direction |
Since each edge is physically stored twice - as an incoming edge along its destination node and an outgoing edge with its source node - you can choose to project only incoming edges with in , only outgoing edges with out , or both (the default setting) with undirected . Please note that in or out restricts graph traversal during computation to the specified direction. |
Yes | ||
load_id |
Sets to false to project nodes without _id values to save the memory space; it defaults to true . |
Yes | ||
update |
Sets the data sync mode. Only static (default) is supported now where any data change in the physical storage will not be synchronized to the projection. |
Yes | ||
query |
This is a reserved parameter to set a query to specify the data to project. Now it can be set to query only. |
No | ||
default |
Sets to true to specify this projection as the default HDC projection of the current graphset; it defaults to false . |
Yes | ||
to() |
<hdcName> |
Name of the HDC server to host the projection. | No |
To project the entire current graphset to hdc-server-1
as hdcGraph
:
hdc.graph.create("hdcGraph", {
nodes: {"*": ["*"]},
edges: {"*": ["*"]},
direction: "undirected",
load_id: true,
update: "static",
query: "query",
default: true
}).to("hdc-server-1")
To project @account
and @movie
nodes with selected properties and incoming @rate
edges in the current graphset to hdc-server-1
as hdcGraph_1
, while omitting nodes' _id
values:
hdc.graph.create("hdcGraph_1", {
nodes: {
"account": ["name", "gender"],
"movie": ["name", "year"]
},
edges: {"rate": ["*"]},
direction: "in",
load_id: false,
update: "static",
query: "query",
default: false
}).to("hdc-server-1")
Dropping an HDC Projection
You can drop any HDC projection of the current graphset from the HDC server using the hdc.graph.drop()
statement.
The following example deletes the HDC projection named hdcGraph_1
:
hdc.graph.drop("hdcGraph_1")
Example Graph and Projection
To create the graph, execute each of the following UQL queries sequentially in an empty graphset:
create().node_schema("entity").edge_schema("link")
create().edge_property(@link, "weight", float)
insert().into(@entity).nodes([{_id:"A"},{_id:"B"},{_id:"C"},{_id:"D"}])
insert().into(@link).edges([{_from:"A", _to:"B", weight:1},{_from:"A", _to:"C", weight:1.5},{_from:"A", _to:"D", weight:0.5},{_from:"B", _to:"C", weight:2},{_from:"C", _to:"D", weight:0.5}])
To create an HDC projection hdcGraph
of the entire graph:
hdc.graph.create("hdcGraph", {
nodes: {"*": ["*"]},
edges: {"*": ["*"]},
direction: "undirected",
load_id: true,
update: "static",
query: "query",
default: false
}).to("hdc-server-1")
Executing Queries
To execute a UQL query on an HDC projection, use the syntax exec{<query>} on <projectName>
. Note that HDC projections only support queries that retrieve data from the database.
To run the ab()
query on hdcGraph
:
exec{
ab().src({_id == "A"}).dest({_id == "C"}).depth(2) as p
return p
} on hdcGraph
Result:
p |
---|
A -> B -> C |
A -> D <- C |
To run the khop()
query on hdcGraph
:
exec{
khop().src({_id == "A"}).depth(1).direction(right) as n
return count(n)
} on hdcGraph
Result:
count(n) |
---|
3 |
Any query attempting to write data will fail in HDC projections. For instance, the following query results in an error indicating that node insertion is not supported.
exec{
insert().into(@entity).nodes([{_id: "E"}])
} on hdcGraph
Executing Algorithms
HDC projections run HDC algorithms. HDC algorithms run using one of the six execution modes: File Writeback, DB Writeback, Stats Writeback, Full Return, Stream Return, and Stats Return.
Writeback Modes
To execute an algorithm on an HDC projection using a writeback mode (File, DB, Stats), use the syntax algo().params().write()
. In the params()
method, you must include the parameter project
to specify the name of the projection.
File Writeback
Runs the Degree Centrality algorithm on hdcGraph
to compute the out-degree of all nodes and write the results back to a file degree.txt
:
algo(degree).params({
project: "hdcGraph",
return_id_uuid: "id",
direction: "out"
}).write({
file: {
filename: "degree.txt"
}
})
Result:
_id,degree_centrality
D,0
B,1
A,3
C,1
DB Writeback
Runs the Degree Centrality algorithm on hdcGraph
to compute the degree of all nodes and write the results back to the node property degree
:
algo(degree).params({
project: "hdcGraph"
}).write({
db: {
property: "degree"
}
})
Stats Writeback
Runs the Triangle Counting algorithm to count the number of triangles on the hdcGraph
and write the statistical summaries to the job:
algo(triangle_counting).params({
project: "hdcGraph",
result_type: 1
}).write({
stats: {}
})
Results:
triangle_count |
---|
2 |
Return Modes
To execute an algorithm on an HDC projection using a return mode (Full, Stream, Stats), use the syntax exec{<algo>} on <projectName>
.
Full Return
Runs the Degree Centrality algorithm on hdcGraph
to compute the out-degree of all nodes and return the results:
exec{
algo(degree).params({
return_id_uuid: "id",
direction: "out"
}) as r
return r
} on hdcGraph
Results:
_id | degree_centrality |
---|---|
D | 0 |
B | 1 |
A | 3 |
C | 1 |
Stream Return
Runs the Degree Centrality algorithm on hdcGraph
to compute the out-degree of all nodes and return the results:
exec{
algo(degree).params({
return_id_uuid: "id",
direction: "out"
}).stream() as r
return r
} on hdcGraph
Results:
_id | degree_centrality |
---|---|
D | 0 |
B | 1 |
A | 3 |
C | 1 |
Stats Return
Runs the Triangle Counting algorithm to count the number of triangles on hdcGraph
and return the statistical summaries:
exec{
algo(triangle_counting).params({
result_type: 1
}).stats() as s
return s
} on hdcGraph
Results:
triangle_count |
---|
2 |
Graph Traversal Direction
If an HDC projection is created with the direction
option set to in
or out
, graph traversal is restricted to incoming or outgoing edges, respectively. Queries or algorithms attempting to traverse in the missing direction throws errors or yields empty results.
To create an HDC projection hdcGraph_in_edges
of the graph with nodes and incoming edges:
hdc.graph.create("hdcGraph_in_edges", {
nodes: {"*": ["*"]},
edges: {"*": ["*"]},
direction: "in",
load_id: true,
update: "static",
query: "query",
default: false
}).to("hdc-server-1")
This khop()
query attempts to follow the outgoing (right) edges on hdcGraph_in_edges
, no result will be returned.
exec{
khop().src({_id == "A"}).depth(1).direction(right) as n
return count(n)
} on hdcGraph_in_edges
Result:
count(n) |
---|
0 |
This Degree Centrality algorithm computes the out-degree of all nodes on hdcGraph_in_edges
, they are all 0.
exec{
algo(degree).params({
return_id_uuid: "id",
direction: "out"
}) as r
return r
} on hdcGraph_in_edges
Results:
_id | degree_centrality |
---|---|
D | 0 |
B | 0 |
A | 0 |
C | 0 |
Exclusion of Node IDs
If an HDC projection is created with the load_id
option set to false
, it does not contain the _id
values for nodes. Queries or algorithms referencing _id
throws errors or yields empty results. In algorithm writeback files, _id
values are replaced with _uuid
values instead.
To create an HDC projection hdcGraph_no_id
of the graph without nodes' _id
values:
hdc.graph.create("hdcGraph_no_id", {
nodes: {"*": ["*"]},
edges: {"*": ["*"]},
direction: "undirected",
load_id: false,
update: "static",
query: "query",
default: false
}).to("hdc-server-1")
The ab()
query utilizes _id
to filter nodes on hdcGraph_no_id
, error occurs as the projection lacks nodes' _id
:
exec{
ab().src({_id == "A"}).dest({_id == "C"}).depth(2) as p
return p{*}
} on hdcGraph_no_id
The Degree Centrality algorithm computes the degree of all nodes on hdcGraph_no_id
, since the projection does not include node _id
values, the results will appear empty for that column:
exec{
algo(degree).params({
return_id_uuid: "id"
}) as r
return r
} on hdcGraph_no_id
Results:
_id | degree_centrality |
---|---|
2 | |
2 | |
3 | |
3 |
The Degree Centrality algorithm computes the degree of all nodes on hdcGraph_no_id
and writes the results back to a file degree.txt
, nodes' _id
are replaced with _uuid
:
algo(degree).params({
project: "hdcGraph_no_id",
return_id_uuid: "id"
}).write({
file: {
filename: "degree.txt"
}
})
Results:
_uuid,degree_centrality
288232575174967298,2
3530824306881724417,2
10016007770295238657,3
12033620403357220866,3
Exclusion of Properties
If an HDC projection is created without certain properties, queries or algorithms referencing those properties throws errors or yields empty results.
To create an HDC projection hdcGraph_no_weight
of the graph containing nodes and only system properties of @link
edges:
hdc.graph.create("hdcGraph_no_weight", {
nodes: {"*": ["*"]},
edges: {"link": []},
direction: "undirected",
load_id: true,
update: "static",
query: "query",
default: false
}).to("hdc-server-1")
The ab()
query finds shortest path between two nodes on hdcGraph_no_weight
, weighted by the edge property @link.weight
, error occurs as the weight
property is missing:
exec{
ab().src({_id == "A"}).dest({_id == "C"}).depth(2).shortest(@link.weight) as p
return p
} on hdcGraph_no_weight
The Degree Centrality algorithm computes the degree of all nodes weighted by the edge property @link.weight
on hdcGraph_no_weight
, error occurs as the weight
property is missing:
exec{
algo(degree).params({
edge_schema_property: "@link.weight"
}) as r
return r
} on hdcGraph_no_weight