Source: https://dev-docs.nebula-graph.io/v5.3.2/analytic/algorithms/graphsage/
Documentation version: v5.3.2

# 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](https://arxiv.org/abs/1706.02216).

## 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](https://dev-docs.nebula-graph.io/v5.3.2/analytic/algorithms/graphsage/#1_prepare_graph_data).

## Procedure implementation[]()

To compute GraphSAGE results, a [procedure](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/procedures/create/) is created.

For more information about the procedure, see [Procedure implementation](https://dev-docs.nebula-graph.io/v5.3.2/analytic/algorithms/graphsage/#procedure_implement). 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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/variable-definition/value-variable/) | Total number of neighborhood aggregation layers.
 | `feature_dim` | [Primitive value variable](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/variable-definition/value-variable/) | Dimensionality of node features / output embedding.
 | `layer` | [Primitive value variable](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/variable-definition/value-variable/) | Current aggregation layer index.
 | `degree` | Node-attached [SumAgg aggregator value variable](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/variable-definition/agg/sum_agg/) | Per-node neighbor count used for mean aggregation.
 | `curr_feat` | Node-attached [SumAgg aggregator value variable](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/variable-definition/agg/sum_agg/) | Per-node scalar feature value in the current layer.
 | `next_sum` | Node-attached [SumAgg aggregator value variable](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/variable-definition/agg/sum_agg/) | Per-node aggregated neighbor feature sum for the current layer.
 | `out_vec` | Node-attached [SumAgg aggregator value variable](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/variable-definition/agg/sum_agg/) | Per-node output embedding vector (map of {dim → value}).
 | `result_table` | [Table variable](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/variable-definition/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](https://dev-docs.nebula-graph.io/v5.3.2/analytic/algorithms/prepare-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](https://dev-docs.nebula-graph.io/v5.3.2/analytic/algorithms/files/graphsage/graphsage_node.csv): Node data.
  - [graphsage_edge.csv](https://dev-docs.nebula-graph.io/v5.3.2/analytic/algorithms/files/graphsage/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](https://dev-docs.nebula-graph.io/v5.3.2/analytic/algorithms/prepare-data/#troubleshooting) before continuing.

### 2. Create a procedure[]()

Create a procedure to implement the GraphSAGE algorithm. For more information about the procedure, see [Procedure implementation](https://dev-docs.nebula-graph.io/v5.3.2/analytic/algorithms/graphsage/#procedure_implement). 

````
'''
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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/in-out/export/). Match the exported fields to the returned columns and target properties.