Source: https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/variable-definition/agg/list_agg/
Documentation version: v5.3.2

# ListAgg

A ListAgg aggregator value variable (`ListAgg<T>`) aggregates all inputs into a list in insertion order, where `T` represents the data type of the input values. To aggregate a set of unique input values, see [SetAgg](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/variable-definition/agg/set_agg/).

## Declaration syntax

diagramsource

 list_agg_declaration  

````
list_agg_declaration ::=
'NODE'? 'VALUE' aggregator_value_variable 'ListAgg' '<' ('INT8'|'INT16'|'INT32'|'INT64'|'FLOAT'|'DOUBLE'|'STRING'|'LIST' '<' data_type '>' |( 'RECORD' )? '{' ( (field_name data_type) ( ',' (field_name data_type) )* )? '}') '>'

````

## Parameters

The following are the specific parameters for ListAgg aggregator value variables. For information about other parameters in the declaration syntax, see [Parameters](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/variable-definition/agg/#parameters).

### `data_type`

The data type of the value that the field holds. Supported data types include numeric, string, boolean, temporal, vector, list, record, and spatial. For more information, see [Data types](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/data-types/).

### `field_name`

The name of a field in a record. `field_name` must be an identifier. 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).

## Initial value

As indicated in the declaration syntax, an initial value must not be specified during declaration.

## Input type and supported operations

The input type must be `T`, which is specified during declaration.

Both [assignment and aggregation](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/set/) operations are supported.

## Return type

````
ListAgg<T> -> LIST<T>

````

The return type is `LIST<T>`, with elements of the same type as the type `T` specified during declaration.

## Member functions

This section introduces the member functions supported by ListAgg aggregator value variables.

### size()

Returns the number of elements in the list held by a ListAgg aggregator value variable.

#### Function signature

````
size() -> UINT64

````

### clear()

Removes all elements from the list held by a ListAgg aggregator value variable.

#### Function signature

````
clear() -> VOID

````

## Examples

The following examples are based on 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/).

### Global ListAgg aggregator value variables

````
'''
USE #movie_temporary_graph {
  VALUE global_list_1 ListAgg<INT>
  VALUE global_list_2 ListAgg<INT>
  SET @global_list_1 += 3     // list: [3]
  SET @global_list_1 += 7     // list: [3, 7]  
  SET @global_list_1 += 5     // list: [3, 7, 5]
  LOG_INFO("@global_list_1: ", @global_list_1)

  // Assignment from empty LIST
  SET @global_list_1 = []   // Clear the list
  LOG_INFO("List from empty LIST:", @global_list_1)   // output: []

  // Assignment from a LIST 
  SET @global_list_1 = [1, 2, 2, 3, 1, 4]   // list: [1, 2, 2, 3, 1, 4]
  LOG_INFO("List from LIST assignment: ", @global_list_1)

  SET @global_list_2 += 3   // global_list_2: [3]
  SET @global_list_2 += 4   // global_list_2: [3, 4]
  LOG_INFO("@global_list_2: ", @global_list_2)

  // Assignment from another ListAgg
  SET @global_list_1 = @global_list_2         // global_list_1: [3, 4]
  LOG_INFO("After assignment from list_2: ", @global_list_1)

  // Aggregation from another ListAgg
  SET @global_list_1 += @global_list_2        // global_list_1: [3, 4, 3, 4]
  LOG_INFO("After aggregation from list_2: ", @global_list_1)

  // Member functions
  SET @global_list_2.clear()   // Clear the list 
  LOG_INFO("Clear the list: ", @global_list_2)       // Output: []
  LOG_INFO("Size: ", @global_list_1.size())       // Output: 4
}
'''

````

Return:

````
Log:
2025-08-21T02:18:53.175811 INFO  - @global_list_1: [3,7,5]
2025-08-21T02:18:53.176426 INFO  - List from empty LIST:[]
2025-08-21T02:18:53.176812 INFO  - List from LIST assignment: [1,2,2,3,1,4]
2025-08-21T02:18:53.177273 INFO  - @global_list_2: [3,4]
2025-08-21T02:18:53.177556 INFO  - After assignment from list_2: [3,4]
2025-08-21T02:18:53.177808 INFO  - After aggregation from list_2: [3,4,3,4]
2025-08-21T02:18:53.178056 INFO  - Clear the list: []
2025-08-21T02:18:53.178199 INFO  - Size: 4

````

### Node-attached ListAgg aggregator value variables

````
'''
USE #movie_temporary_graph {
  NODE VALUE node_list ListAgg<DOUBLE>
  MATCH (a@User WHERE a.id IN [1,3,4])-[w@Watch]->(b@Movie)
  PER PATH {
    // For each matched path, add the movie ID to the corresponding user's list
    SET a.@node_list += b.id
  }
  PER NODE (a) {
    LOG_INFO("a.id: ", a.id, " a.@node_list: ", a.@node_list)
  }
}
'''

````

In the preceding example, a node-attached ListAgg aggregator value variable `node_list` of type `ListAgg<DOUBLE>` is declared to hold a list of movie IDs for each user.

Return:

````
Log:
2025-08-21T06:25:50.230307 INFO  - a.id: 3 a.@node_list: [473,152]
2025-08-21T06:25:50.230307 INFO  - a.id: 1 a.@node_list: [11,651,10,104,601,100,497,252,473]
2025-08-21T06:25:50.230307 INFO  - a.id: 4 a.@node_list: [99,648,671,144,146,346,637,11,10,104,252,473]

````