Source: https://dev-docs.yueshu.com.cn/v5.3.2/analytic/algorithms/graphsage/
Documentation version: v5.3.2

# GraphSAGE

本文介绍 GraphSAGE 算法，并演示如何用 GQL 实现该算法。

## 算法介绍

GraphSAGE 通过分层聚合邻域特征生成点嵌入。

该过程将算法逻辑封装为可复用过程，可直接在图数据上执行并输出结果。

更多信息，请参见 [GraphSAGE](https://arxiv.org/abs/1706.02216)。

## 数据模型

为了在 GQL 中实现 GraphSAGE 算法，使用以下数据模型创建图类型：

- 实体由类型为`Node`的点表示，点属性包括`id`和`rating`。
- 实体间关系由类型为`Link`的边表示，边属性包括`weight`。

该图类型的完整定义，请参见[准备图数据](https://dev-docs.yueshu.com.cn/v5.3.2/analytic/algorithms/graphsage/#1_prepare_graph_data)。

## 过程实现[]()

为了计算 GraphSAGE 结果，创建一个[过程](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/procedures/create/)。

关于该过程的更多信息，请参见[过程实现](https://dev-docs.yueshu.com.cn/v5.3.2/analytic/algorithms/graphsage/#procedure_implement)。下文将介绍该过程的关键组成部分及其工作原理。

该过程接受以下输入参数：

- `num_layers`：`INT64`类型，默认值`2`。 邻域聚合的层数。

此外，在过程内部定义了以下变量：

 | 变量名 | 变量类型 | 描述
 | `total_layers` | [原始值变量](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/variable-definition/value-variable/) | 邻域聚合的总层数。
 | `feature_dim` | [原始值变量](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/variable-definition/value-variable/) | 点特征和输出嵌入的维度。
 | `layer` | [原始值变量](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/variable-definition/value-variable/) | 当前聚合层索引。
 | `degree` | 点绑定 [SumAgg 聚合值变量](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/variable-definition/agg/sum_agg/) | 用于均值聚合的每点邻居数量。
 | `curr_feat` | 点绑定 [SumAgg 聚合值变量](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/variable-definition/agg/sum_agg/) | 每点在当前层的标量特征值。
 | `next_sum` | 点绑定 [SumAgg 聚合值变量](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/variable-definition/agg/sum_agg/) | 每点当前层邻居特征之和（用于均值聚合）。
 | `out_vec` | 点绑定 [SumAgg 聚合值变量](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/variable-definition/agg/sum_agg/) | 每点输出嵌入向量（{维度 → 值} 映射）。
 | `result_table` | [表变量](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/variable-definition/table-variable/) | 存储 (vertex_id, embedding) 结果对的输出表。

以下步骤概述了该过程的逻辑：

1. 计算每点的`degree`；用每点自身的特征初始化`curr_feat`。
2. 对每一层，将邻居的`curr_feat`累加到`next_sum`，除以`degree`得到均值聚合结果。
3. 应用非线性激活（如 ReLU 式归一化），用聚合结果更新`curr_feat`。
4. 所有层完成后，将最终特征作为输出嵌入；返回（`vertex_id`、`embedding`）。

## 操作步骤

在悦数图管理的控制台中，按顺序执行以下代码块。首次使用时，先按[准备算法示例数据](https://dev-docs.yueshu.com.cn/v5.3.2/analytic/algorithms/prepare-data/)确认操作位置和目录挂载。

### 1. 准备图数据[]()

1. 

创建一个与数据模型匹配的图类型。

````
'''
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. 

下载以下 CSV 文件，保留文件名，保存到部署目录下的`examples/algorithms/graphsage/`：

  - [graphsage_node.csv](https://dev-docs.yueshu.com.cn/v5.3.2/analytic/algorithms/files/graphsage/graphsage_node.csv)：点数据。
  - [graphsage_edge.csv](https://dev-docs.yueshu.com.cn/v5.3.2/analytic/algorithms/files/graphsage/graphsage_edge.csv)：边数据。

查看 CSV 内容

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 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: ','
      }
  }
'''

````

导入成功后，在控制台执行以下查询核对点数：

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

````

`node_count`应为`24`。点数不符时，先按[文件问题排查](https://dev-docs.yueshu.com.cn/v5.3.2/analytic/algorithms/prepare-data/#troubleshooting)检查文件和导入结果。

### 2. 创建过程[]()

创建实现 GraphSAGE 算法的过程。关于该过程的更多信息，请参见[过程实现](https://dev-docs.yueshu.com.cn/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. 调用过程[]()

执行`2`层邻域聚合，返回各点的嵌入向量。

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

````

返回：

展开查看返回

````
+-----------+-----------------------------------------------+
| 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]                               |
+-----------+-----------------------------------------------+

````

保存结果到文件或图中

如需将返回的结果保存为 CSV 文件或写入图，请参见 [EXPORT](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/in-out/export/)。导出字段应与返回列及目标属性对应。