Projecting graphs using native projections

Native projections can only project a limited set of node property types from the Neo4j database. The Node Properties page details which node property types are supported. Other types of node properties have to be transformed or encoded into one of the supported types in order to be projected using a native projection.

The node projection specifies which nodes from the database should be projected into the in-memory GDS graph. The projection is based around node labels, and offers three different syntaxes that can be used based on how detailed the projection needs to be.

All nodes with any of the specified node labels will be projected to the GDS graph. If a node has several labels, it will be projected several times. If the nodes have values for the specified properties, these will be projected as well. If a node does not have a value for a specified property, a default value will be used. Read more about default values below.

All specified node labels and properties must exist in the database. To project using a non-existing label, it is possible to create a label without any nodes using the db.createLabel() procedure. Similarly, to project a non-existing property, it is possible to create a node property without modifying the database, using the db.createProperty() procedure.

The relationship projection specifies which relationships from the database should be projected into the in-memory GDS graph. The projection is based around relationship types, and offers three different syntaxes that can be used based on how detailed the projection needs to be.

All relationships with any of the specified relationship types and with endpoint nodes projected in the node projection will be projected to the GDS graph. The validateRelationships configuration parameter controls whether to fail or silently discard relationships with endpoint nodes not projected by the node projection. If the relationships have values for the specified properties, these will be projected as well. If a relationship does not have a value for a specified property, a default value will be used. Read more about default values below.

All specified relationship types and properties must exist in the database. To project using a non-existing relationship type, it is possible to create a relationship without any relationships using the db.createRelationshipType() procedure. Similarly, to project a non-existing property, it is possible to create a relationship property without modifying the database, using the db.createProperty() procedure.

A simple graph is a graph with only one node label and relationship type, i.e., a monopartite graph. We are going to start with demonstrating how to load a simple graph by projecting only the Person node label and KNOWS relationship type.

In the example above, we used a short-hand syntax for the node and relationship projection. The used projections are internally expanded to the full Map syntax as shown in the Results table. In addition, we can see the projected in-memory graph contains three Person nodes, and the two KNOWS relationships.

A multi-graph is a graph with multiple node labels and relationship types.

To project multiple node labels and relationship types, we can adjust the projections as follows:

In the example above, we used a short-hand syntax for the node and relationship projection. The used projections are internally expanded to the full Map syntax as shown for the nodeProjection in the Results table. In addition, we can see the projected in-memory graph contains five nodes, and the two relationships.

By default, relationships are loaded in the same orientation as stored in the Neo4j db. In GDS, we call this the NATURAL orientation. Additionally, we provide the functionality to load the relationships in the REVERSE or even UNDIRECTED orientation.

To specify the orientation, we need to write the relationshipProjection with the extended Map-syntax. Projecting the KNOWS relationships UNDIRECTED, loads each relationship in both directions. Thus, the undirectedKnows graph contains four relationships, twice as many as the persons graph in Simple graph.

To project node properties, we can either use the nodeProperties configuration parameter for shared properties, or extend an individual nodeProjection for a specific label.

The projected graphWithProperties graph contains five nodes and six relationships. In the returned bookProjection we can observe, the node properties price and ratings are loaded for Books.

Further, the price property has a default value of 5.0. Not every book has a price specified in the example graph. In the following we check if the price was correctly projected:

We can see, that the price was projected with the Hobbit having the default price of 5.0.

Analogous to node properties, we can either use the relationshipProperties configuration parameter or extend an individual relationshipProjection for a specific type.

Next, we will verify that the relationship property numberOfPages were correctly loaded.

We can see, that the numberOfPages property is loaded. The default property value is Double.NaN and could be changed using the Map-Syntax the same as for node properties in Node properties.

Neo4j supports parallel relationships, i.e., multiple relationships between two nodes. By default, GDS preserves parallel relationships. For some algorithms, we want the projected graph to contain at most one relationship between two nodes.

We can specify how parallel relationships should be aggregated into a single relationship via the aggregation parameter in a relationship projection.

For graphs without relationship properties, we can use the COUNT aggregation. If we do not need the count, we could use the SINGLE aggregation.

Next, we will verify that the READ relationships were correctly aggregated.

We can see, that the two READ relationships between Florentin, and the Hobbit result in 2 numberOfReads.

For graphs with relationship properties we can also use other aggregations.

Next, we will verify that the relationship property numberOfPages was correctly aggregated.

We can see, that the two READ relationships between Florentin and the Hobbit sum up to 46 numberOfReads.

As mentioned in the syntax section, the validateRelationships flag controls whether an error will be raised when attempting to project a relationship where either the source or target node is not present in the node projection. Note that even if the flag is set to false such a relationship will still not be projected but the loading process will not be aborted.

We can simulate such a case with the graph present in the Neo4j database:

We can see that the above query resulted in an exception being thrown. The exception message will provide information about the specific node id that was missing, which will help debugging underlying problems.