聚合值变量¶

聚合值变量用于定义对嵌套值的聚合操作。在引用聚合值变量时，必须在变量名前加上@符号，以区别于原始值变量。

对于数值相关的聚合值变量声明，支持显式的数值类型变体，包括INT8、INT16、INT32、INT64、FLOAT和DOUBLE（具体取决于聚合值变量类型）。

聚合值变量可细分为两种类型：

全局聚合值变量
点绑定聚合值变量

Caution

点绑定聚合值变量仅适用于临时图，而全局聚合值变量适用于持久图和临时图。

全局聚合值变量¶

全局聚合值变量必须在全局范围内声明，在声明后可以在过程的任何部分访问。

点绑定聚合值变量¶

点绑定聚合值变量必须在全局范围内使用NODE关键字声明，在声明后只能在匹配计算语句的per_block子句中进行聚合操作。

对比¶

下表总结了全局聚合值变量和点绑定聚合值变量之间的主要区别：

	全局聚合值变量	点绑定聚合值变量
作用域	在整个计算过程中维护一份共享状态。	图中每个点各自维护一份独立状态。
适用图类型	图和临时图均可使用。	仅适用于临时图。
可访问上下文	声明后，可在过程的任意位置访问。	仅可在匹配计算语句的`per_block`子句中访问。
声明方式	`VALUE var AggType<T> [= value_expression]`	`NODE VALUE var AggType<T> [= value_expression]`
引用方式	`@var`	`<node_var>.@var`（在`PER NODE` / `PER PATH`块中使用）
内存占用	较小。无论图的规模多大，始终只维护一份聚合状态。	与点数量成正比。每个点各持有一份聚合状态。
分布式模式注意事项	每轮计算需要在所有主机之间进行一次全局合并。应避免在全局聚合值变量中存放大型集合（尤其是容器类聚合器，如`ListAgg`、`SetAgg`、`MapAgg`），因为收集的数据量越大，内存占用和跨机传输开销也越大。	`PER NODE`操作以本地计算为主，跨机通信较少。`PER PATH`操作可能需要更多跨机通信，尤其是连接数较多的点。

Caution

全局聚合值变量适合存放标量值（如SumAgg、MaxAgg、MinAgg、AvgAgg）。如果将容器类聚合器（ListAgg、SetAgg、MapAgg）用作全局聚合值变量，在分布式模式下可能导致较高的内存占用和跨机传输开销，因为每轮计算都需要在所有机器之间合并整个集合。如需收集点数据，建议使用点绑定聚合值变量，或将结果导出到表变量中。

选择指引

如需在整个计算过程中追踪一个汇总值（如总计数、累计求和、收敛标志等），使用全局聚合值变量。
如需为每个点维护各自的值（如距离、得分、连通分量 ID 等），使用点绑定聚合值变量。
在迭代式图算法中，通常两者配合使用：点绑定聚合值变量存储每轮迭代中更新的点的结果，全局聚合值变量追踪整体进度（例如，判断当前迭代中是否有点的值发生了变化，从而决定是否需要继续迭代）。

语法¶

语法图源码

aggregator_value_variable_definition
aggr_type

aggregator_value_variable_definition ::=
    'NODE'? 'VALUE' aggregator_value_variable aggr_type ('=' value_expression)?

aggr_type ::=
    SumAgg 
    | AvgAgg
    | MaxAgg
    | MinAgg  
    | AndAgg  
    | OrAgg
    | ListAgg  
    | SetAgg   
    | MapAgg
    | TopKAgg

参数¶

`NODE`¶

可选关键字NODE用于指定该变量与临时图中的点的绑定关系。每个点都有一个该变量的实例，用于存储与该点绑定的值。

`aggregator_value_variable`¶

要定义的聚合值变量的名称。aggregator_value_variable可以是常规标识符或使用反引号(`)包围的分隔标识符。有关标识符的更多信息，请参见标识符命名规则。

`aggr_type`¶

对该变量持有的嵌套值执行的聚合类型。

下表简要介绍了支持的聚合类型：

聚合类型	描述
SumAgg	对所有输入`x`，保存值`sum(x)`。更多信息，请参见 SumAgg。
AvgAgg	对所有输入`x`，保存平均值`avg(x)`，也即`sum(x)/count(x)`。更多信息，请参见 AvgAgg。
MaxAgg	对所有输入`x`，保存最大值`max(x)`。更多信息，请参见 MaxAgg。
MinAgg	对所有输入`x`，保存最小值`min(x)`。更多信息，请参见 MinAgg。
AndAgg	对所有输入`x`，保存逻辑与操作的结果。更多信息，请参见 AndAgg。
OrAgg	对所有输入`x`，保存逻辑或操作的结果。更多信息，请参见 OrAgg。
ListAgg	将所有输入按照插入顺序聚合为一个列表。更多信息，请参见 ListAgg。
SetAgg	将所有输入聚合为不包含重复值的集合。更多信息，请参见 SetAgg。
MapAgg	对每个输入`TUPLE(key, value)`，维护一个键值对的映射，其中每个键映射到一个聚合值。更多信息，请参见 MapAgg。
TopKAgg	对所有输入，维护基于指定排序标准的前 K 个值。更多信息，请见 TopKAgg。

`value_expression`¶

用于指定该变量初始值的可选值表达式。值表达式可以是常量、函数调用或返回单个值的子查询。更多信息，请参见值表达式。

仅SumAgg、MaxAgg、MinAgg、AndAgg、OrAgg支持= value_expression。对于AvgAgg、ListAgg、TopKAgg、MapAgg、SetAgg，声明时指定初始值无效。

示例¶

以下示例基于示例数据集中创建的图movie和 CREATE TEMPORARY GRAPH 中创建的临时图#movie_temporary_graph。

定义全局聚合值变量¶

'''
USE movie { 
  VALUE a SumAgg<INT> = 0 
  VALUE b MaxAgg<DOUBLE> = 0.0 
  VALUE c MinAgg<INT> = 100 
  VALUE d AvgAgg<DOUBLE> 
  VALUE e OrAgg = false 
  VALUE f AndAgg = true 
  VALUE g ListAgg<INT> 
  VALUE h ListAgg<RECORD{x INT, y STRING}> 
  RETURN @a, @b, @c, @d, @e, @f, @g, @h 
    }
'''

返回：

+----+-----+-----+-----+-------+------+----+----+
| @a | @b  | @c  | @d  | @e    | @f   | @g | @h |
+----+-----+-----+-----+-------+------+----+----+
| 0  | 0.0 | 100 | 0.0 | false | true | [] | [] |
+----+-----+-----+-----+-------+------+----+----+

定义点绑定聚合值变量¶

'''
USE #movie_temporary_graph { 
  NODE VALUE a ListAgg<INT> 
  MATCH (v@Actor) WHERE v.id > 271940 
  PER NODE (v) { 
    SET v.@a = LIST[v.id] 
    LOG_INFO("ID_List: ", v.@a) 
  } 
}
'''

返回：

Log:
2025-07-14T07:30:37.718732 INFO  - ID_List: [271941]
2025-07-14T07:30:37.718732 INFO  - ID_List: [271947]
2025-07-14T07:30:37.718732 INFO  - ID_List: [271945]
2025-07-14T07:30:37.718978 INFO  - ID_List: [271943]
2025-07-14T07:30:37.718978 INFO  - ID_List: [271946]
2025-07-14T07:30:37.718978 INFO  - ID_List: [271944]
2025-07-14T07:30:37.718978 INFO  - ID_List: [282659]
2025-07-14T07:30:37.719037 INFO  - ID_List: [271942]