Source: https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/variable-definition/agg/ Documentation version: v5.3.2 # 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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/variable-definition/value-variable/). 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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/ddl/graph-projection/create/), 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`](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/match-compute/#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`](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/match-compute/#per_block) clauses in match compute statements. | Declaration | `VALUE var AggType [= value_expression]` | `NODE VALUE var AggType [= value_expression]` | Reference | `@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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/variable-definition/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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/overview/keywords-identifiers/#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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/variable-definition/agg/sum_agg/). | AvgAgg | For all inputs `x`, maintains the average value `avg(x)`, which equals `sum(x)/count(x)`. For more information, see [AvgAgg](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/variable-definition/agg/avg_agg/). | MaxAgg | For all inputs `x`, maintains the maximum value `max(x)`. For more information, see [MaxAgg](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/variable-definition/agg/max_agg/). | MinAgg | For all inputs `x`, maintains the minimum value `min(x)`. For more information, see [MinAgg](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/variable-definition/agg/min_agg/). | AndAgg | For all inputs `x`, maintains the result of logical AND operation. For more information, see [AndAgg](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/variable-definition/agg/and_agg/). | OrAgg | For all inputs `x`, maintains the result of logical OR operation. For more information, see [OrAgg](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/variable-definition/agg/or_agg/). | ListAgg | Aggregates all inputs into a list in insertion order. For more information, see [ListAgg](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/variable-definition/agg/list_agg/). | SetAgg | Aggregates all inputs into a set that contains only unique values. For more information, see [SetAgg](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/variable-definition/agg/set_agg/). | 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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/variable-definition/agg/map_agg/). | TopKAgg | For all inputs, maintains the top K values based on specified sorting criteria. For more information, see [TopKAgg](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/variable-definition/agg/topk_agg/). ### `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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/#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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/overview/example-dataset/) and the temporary graph `#movie_temporary_graph` created in [CREATE TEMPORARY GRAPH](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/ddl/graph-projection/create/). ### Define global aggregator value variables ```` ''' USE movie { VALUE a SumAgg = 0 VALUE b MaxAgg = 0.0 VALUE c MinAgg = 100 VALUE d AvgAgg VALUE e OrAgg = false VALUE f AndAgg = true VALUE g ListAgg VALUE h ListAgg 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 MATCH (v@Actor) WHERE v.id > 271940 PER NODE (v) { SET v.@a = LIST[v.id] LOG_INFO("ID_List: ", v.@a) } } ''' ```` Return: ```` 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] ````