GraphSAGE

Algorithm introduction

GraphSAGE generates node embeddings by aggregating neighborhood features layer by layer.

Compute a deterministic mean-aggregator GraphSAGE-style embedding on a directed graph whose node primary key is id and whose initial scalar feature comes from rating. The procedure uses each node's outgoing neighbors, iteratively averages the node state with its neighborhood state for num_layers rounds, and returns the hop-wise representation [h0, h1, ..., hk].

For more information, see GraphSAGE.

Data model

To implement the GraphSAGE algorithm in GQL, the following data model is used to create a graph type:

• Entities are represented by nodes of type Node, with properties id and rating.
• Relationships are represented by edges of type Link, with property weight.

For the complete definition of the graph type, see Prepare graph data.

Procedure implementation

To compute GraphSAGE results, a procedure is created.

For more information about the procedure, see Procedure implementation. The following section describes the key components of the procedure and how it works.

The procedure takes the following input parameters:

• num_layers: INT64 (default: 2). Number of neighborhood aggregation layers.

Additionally, the following variables are defined within the procedure:

Variable name	Variable type	Description
total_layers	Primitive value variable	Total number of neighborhood aggregation layers.
feature_dim	Primitive value variable	Dimensionality of node features / output embedding.
layer	Primitive value variable	Current aggregation layer index.
degree	Node-attached SumAgg aggregator value variable	Per-node neighbor count used for mean aggregation.
curr_feat	Node-attached SumAgg aggregator value variable	Per-node scalar feature value in the current layer.
next_sum	Node-attached SumAgg aggregator value variable	Per-node aggregated neighbor feature sum for the current layer.
out_vec	Node-attached SumAgg aggregator value variable	Per-node output embedding vector (map of {dim → value}).
result_table	Table variable	Output table storing (vertex_id, embedding) pairs.

The following steps outline the logic of the procedure:

1. Compute each node's degree; initialize curr_feat from each node's own feature.
2. For each layer, aggregate neighbor curr_feat values by summing into next_sum; divide by degree to obtain the mean.
3. Apply a non-linear activation (e.g., ReLU-style normalization) and update curr_feat from the aggregated result.
4. After all layers, store the final feature as the output embedding; return (vertex_id, embedding).

Steps

Run the following code blocks in order in the NebulaGraph Studio CONSOLE. For first-time setup, follow Prepare algorithm sample data to check where to run commands and how the directory is mounted.

1. Prepare graph data

1. Create a graph type that matches your data model.

   '''
   CREATE GRAPH TYPE IF NOT EXISTS graphsage_graph_type AS {
       NODE Node (LABEL Node {id INT PRIMARY KEY, rating INT}),
       EDGE Link (Node)-[LABEL Link {weight INT, MULTIEDGE KEY()}]->(Node)
   }
   '''
   

2. Download these CSV files and save them with their original names in examples/algorithms/graphsage/ under your deployment directory:

   • graphsage_node.csv: Node data.
   • graphsage_edge.csv: Edge data.
   Preview the CSV files

   graphsage_node.csv

   id,rating
   1,0
   2,2
   3,1
   4,0
   5,0
   6,2
   7,1
   8,2
   9,0
   10,1
   11,0
   12,2
   13,1
   14,1
   15,0
   16,2
   17,0
   18,1
   19,2
   20,0
   21,2
   22,1
   23,0
   24,1
   

   graphsage_edge.csv

   src_id,dst_id,weight
   1,2,4
   1,3,2
   1,4,7
   1,5,9
   2,3,1
   2,4,6
   2,5,5
   2,6,2
   3,4,3
   3,5,4
   3,6,8
   4,6,2
   4,7,6
   4,8,5
   5,6,4
   5,8,7
   5,9,6
   6,8,1
   6,9,5
   6,10,6
   7,9,2
   7,10,9
   8,9,3
   8,11,6
   8,12,4
   9,10,4
   9,12,7
   9,13,2
   10,12,1
   10,13,8
   10,14,4
   11,12,2
   11,14,5
   11,15,7
   12,14,3
   12,15,6
   12,16,5
   13,15,2
   13,16,7
   14,15,4
   14,17,8
   14,18,2
   15,16,1
   15,18,5
   15,19,3
   16,18,3
   16,19,6
   17,18,2
   17,20,7
   17,21,5
   18,19,4
   18,21,9
   18,22,6
   19,21,1
   19,22,5
   20,21,3
   20,23,6
   20,24,8
   21,22,2
   21,23,4
   21,24,7
   22,24,4
   23,24,1
   

3. Create a temporary graph based on the graph type and load the data files into the temporary graph.

   CREATE TEMPORARY GRAPH IF NOT EXISTS #graphsage_graph TYPED graphsage_graph_type
   

   '''
   USE #graphsage_graph IMPORT INTO GRAPH {
         NODE (v@Node {id: id, rating: rating}) FROM DATAFILE {
             PATH: "file:///examples/algorithms/graphsage/graphsage_node.csv",
             FORMAT: "CSV",
             DELIMITER: ','
         },
         EDGE (id: src_id)-[e@Link {weight: weight}]->(id: dst_id) FROM DATAFILE {
             PATH: "file:///examples/algorithms/graphsage/graphsage_edge.csv",
             FORMAT: "CSV",
             DELIMITER: ','
         }
     }
   '''
   

   After the import succeeds, run this query in the console to check the node count:

   '''
   USE #graphsage_graph
   MATCH (n)
   RETURN count(n) AS node_count
   '''
   

   The expected node_count is 24. If it differs, check the files and import results before continuing.

2. Create a procedure

Create a procedure to implement the GraphSAGE algorithm. For more information about the procedure, see Procedure implementation.

'''
CREATE OR REPLACE PROCEDURE graphsage(
  num_layers INT64 DEFAULT 2
)
RETURNS (vertex_id INT64, embedding LIST<DOUBLE>)
COMMENT "Compute a deterministic mean-aggregator GraphSAGE-style embedding on a directed graph whose vertex primary key is id and whose initial scalar feature comes from rating. The procedure uses each node's outgoing neighbors, iteratively averages the node state with its neighborhood state for num_layers rounds, and returns the hop-wise representation [h0, h1, ..., hk]."
AS {
  VALUE total_layers INT64 = 0
  VALUE feature_dim INT64 = 0
  VALUE layer INT64 = 0

  NODE VALUE degree SumAgg<INT64> = 0
  NODE VALUE curr_feat SumAgg<DOUBLE> = 0.0
  NODE VALUE next_sum SumAgg<DOUBLE> = 0.0
  NODE VALUE out_vec MapAgg<INT64, SumAgg<DOUBLE>>

  TABLE result_table TYPED TABLE {
    vertex_id INT64,
    embedding LIST<DOUBLE>
  }

  SET total_layers = num_layers

  IF total_layers < 0 THEN {
    SET total_layers = 0
  }

  SET feature_dim = total_layers + 1

  MATCH (n)
  PER NODE (n) {
    SET n.@degree = 0
    SET n.@curr_feat = 0.0
    SET n.@next_sum = 0.0
    SET n.@out_vec.clear()
  }

  MATCH (s)-[e]->(t)
  PER PATH {
    SET s.@degree += 1
  }

  MATCH (n)
  PER NODE (n) {
    SET n.@curr_feat = CAST(n.rating AS DOUBLE)
    SET n.@out_vec += TUPLE(0, n.@curr_feat)
  }

  WHILE layer < total_layers THEN {
    MATCH (n)
    PER NODE (n) {
      SET n.@next_sum = 0.0
    }

    MATCH (s)-[e]->(t)
    PER PATH {
      SET s.@next_sum += t.@curr_feat
    }

    MATCH (n)
    PER NODE (n) {
      VALUE next_feat DOUBLE = 0.0

      IF n.@degree > 0 THEN {
        SET next_feat = (n.@curr_feat + n.@next_sum) / CAST(n.@degree + 1 AS DOUBLE)
      }
      ELSE {
        SET next_feat = n.@curr_feat
      }

      SET n.@curr_feat = next_feat
      SET n.@out_vec += TUPLE(layer + 1, next_feat)
      SET n.@next_sum = 0.0
    }

    SET layer = layer + 1
  }

  MATCH (n)
  PER NODE (n) {
    VALUE idx INT64 = 0
    VALUE embedding LIST<DOUBLE> = []

    WHILE idx < feature_dim THEN {
      SET embedding = embedding || [n.@out_vec.get(idx)]
      SET idx = idx + 1
    }

    EXPORT n.id, embedding INTO result_table
  }

  FOR r IN result_table
  RETURN
    r.vertex_id AS vertex_id,
    r.embedding AS embedding
  ORDER BY vertex_id ASC
}
'''

3. Call your procedure

Run 2 layers of neighborhood aggregation and return the embedding for each node.

USE #graphsage_graph CALL graphsage(2) RETURN vertex_id, embedding

Returns:

Expand to view results

+-----------+-----------------------------------------------+
| vertex_id | embedding                                     |
+-----------+-----------------------------------------------+
| 1         | [0.0, 0.6, 0.9199999999999999]                |
| 2         | [2.0, 1.0, 1.05]                              |
| 3         | [1.0, 0.75, 1.0625]                           |
| 4         | [0.0, 1.25, 1.0416666666666665]               |
| 5         | [0.0, 1.0, 1.0625]                            |
| 6         | [2.0, 1.25, 1.125]                            |
| 7         | [1.0, 0.6666666666666666, 0.9722222222222222] |
| 8         | [2.0, 1.0, 1.0]                               |
| 9         | [0.0, 1.0, 1.125]                             |
| 10        | [1.0, 1.25, 1.0]                              |
| 11        | [0.0, 0.75, 0.9375]                           |
| 12        | [2.0, 1.25, 1.1666666666666667]               |
| 13        | [1.0, 1.0, 1.3055555555555556]                |
| 14        | [1.0, 0.5, 1.0]                               |
| 15        | [0.0, 1.25, 1.5208333333333335]               |
| 16        | [2.0, 1.6666666666666667, 1.6111111111111114] |
| 17        | [0.0, 0.75, 1.0]                              |
| 18        | [1.0, 1.5, 1.2916666666666667]                |
| 19        | [2.0, 1.6666666666666667, 1.2222222222222223] |
| 20        | [0.0, 0.75, 0.8125]                           |
| 21        | [2.0, 1.0, 0.875]                             |
| 22        | [1.0, 1.0, 1.0]                               |
| 23        | [0.0, 0.5, 0.75]                              |
| 24        | [1.0, 1.0, 1.0]                               |
+-----------+-----------------------------------------------+

Save results to a file or graph

To save the returned results as CSV files or write them to a graph, see EXPORT. Match the exported fields to the returned columns and target properties.