Aggregator value variables¶

Aggregator value variables are used to define aggregation operations on nested values. When referenced in subsequent statements, aggregator value variables must be prefixed with the symbol @, which distinguishes them from primitive value variables.

For numeric-related aggregator value variable declarations, explicit numeric type variants such as INT8, INT16, INT32, INT64, FLOAT, and DOUBLE are supported (depending on the specific aggregator value variable type).

Aggregator value variables are further categorized into two types:

Global aggregator value variables
Node-attached aggregator value variables

Caution

Node-attached aggregator value variables are only applicable to temporary graphs, while global aggregator value variables are applicable to both graphs and temporary graphs.

Global aggregator value variables¶

Global aggregator value variables must be declared at the global scope and are accessible from any part of the procedure after declaration.

Node-attached aggregator value variables¶

Node-attached aggregator value variables must be declared with the NODE keyword at the global scope and are accessible for aggregation only within per_block clauses in match compute statements.

Comparison¶

The following table summarizes the key differences between global and node-attached aggregator value variables:

	Global aggregator value variables	Node-attached aggregator value variables
Scope	Maintains a single shared state across the entire computation.	Each node in the graph maintains its own independent state.
Applicable graph type	Graphs and temporary graphs.	Temporary graphs only.
Accessible context	Any part of the procedure after declaration.	Only within `per_block` clauses in match compute statements.
Declaration	`VALUE var AggType<T> [= value_expression]`	`NODE VALUE var AggType<T> [= value_expression]`
Reference	`@var`	`<node_var>.@var` (within `PER NODE` / `PER PATH` blocks)
Memory footprint	Small. Only one copy of the aggregated state is maintained regardless of graph size.	Proportional to the number of nodes. Each node holds its own copy of the aggregated state.
Distributed mode considerations	Each round requires a global merge across all machines. Avoid storing large collections in global aggregator value variables (especially container-type aggregators such as `ListAgg`, `SetAgg`, and `MapAgg`), as both the memory footprint and the cross-machine transfer cost grow with the size of the collected data.	`PER NODE` operations are mostly local. `PER PATH` operations may incur more cross-machine communication, especially for high-degree nodes.

Caution

Global aggregator value variables are best suited for scalar values (e.g., SumAgg, MaxAgg, MinAgg, AvgAgg). Using container-type aggregators (ListAgg, SetAgg, MapAgg) as global aggregator value variables can lead to significant memory consumption and cross-machine transfer overhead in distributed mode, because the entire collection must be merged across all machines in each round. If you need to collect per-node data, consider using node-attached aggregator value variables or exporting results to a table variable instead.

Selection guidelines

To track a single summary value across the entire computation (e.g., a total count, a running sum, or a convergence flag), use a global aggregator value variable.
To maintain a separate value for each node (e.g., a distance, a score, or a component ID), use a node-attached aggregator value variable.
In iterative graph algorithms, the two types are often used together: node-attached aggregator value variables store the per-node results updated in each iteration, while global aggregator value variables track overall progress, such as whether any node's value changed in the current iteration and whether another iteration is needed.

Syntax¶

diagramsource

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

Parameters¶

`NODE`¶

The optional keyword NODE specifies that the variable is attached to the nodes in a temporary graph. Each node has its own instance of the variable, which holds the value specific to that node.

`aggregator_value_variable`¶

The name of the aggregator value variable to be defined. aggregator_value_variable can be a regular identifier or a delimited identifier enclosed with backticks (`). For more information about identifiers, see Rules for naming identifiers.

`aggr_type`¶

The type of aggregator applied to the nested values held by the variable.

The following table provides an overview of the supported aggregator types:

Aggregator type	Description
SumAgg	For all inputs `x`, maintains the value `sum(x)`. For more information, see SumAgg.
AvgAgg	For all inputs `x`, maintains the average value `avg(x)`, which equals `sum(x)/count(x)`. For more information, see AvgAgg.
MaxAgg	For all inputs `x`, maintains the maximum value `max(x)`. For more information, see MaxAgg.
MinAgg	For all inputs `x`, maintains the minimum value `min(x)`. For more information, see MinAgg.
AndAgg	For all inputs `x`, maintains the result of logical AND operation. For more information, see AndAgg.
OrAgg	For all inputs `x`, maintains the result of logical OR operation. For more information, see OrAgg.
ListAgg	Aggregates all inputs into a list in insertion order. For more information, see ListAgg.
SetAgg	Aggregates all inputs into a set that contains only unique values. For more information, see SetAgg.
MapAgg	For each input `TUPLE(key, value)`, maintains a map of key-value pairs where each key maps to an aggregated value. For more information, see MapAgg.
TopKAgg	For all inputs, maintains the top K values based on specified sorting criteria. For more information, see TopKAgg.

`value_expression`¶

An optional value expression that defines the initial value of the variable. It can be a constant, a function call, or a subquery that returns a single value. For more information about value expressions, see Value expressions.

= value_expression is supported only by SumAgg, MaxAgg, MinAgg, AndAgg, and OrAgg. For AvgAgg, ListAgg, TopKAgg, MapAgg, and SetAgg, specifying an initial value is invalid.

Examples¶

The following example is based on the graph movie created in the example dataset and the temporary graph #movie_temporary_graph created in CREATE TEMPORARY GRAPH.

Define global aggregator value variables¶

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

Return:

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

Define node-attached aggregator value variables¶

'''
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)  
  }  
}
'''