Native projection

Projected graphs reside in memory (in the graph catalog) until any of the following happens:

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.

A node projection can be specified using any of the following forms:

The projection map is specified as follows:

A Relationship projection can be specified using any of the following forms:

The projection map is specified as follows:

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.

You can use the wildcard operator * to select all the node labels for the projection. However, this does not retain the label information on the projected nodes.

Use the db.labels() instead to retrieve the list of all the labels, and use it as a value for the nodeProjection parameter as in the following example:

In a similar fashion, you can select all the relationship types for the projection by using db.relationshipTypes() as a value for the relationshipProjection parameter in place of ['KNOWS', 'READ'].