Source: https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/variable-definition/agg/list_agg/
Documentation version: v5.3.2

# ListAgg

ListAgg 聚合值变量（`ListAgg<T>`）将所有类型为`T`的输入按照插入顺序聚合为一个列表。如需聚合不含重复值的集合，请参见 [SetAgg](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/variable-definition/agg/set_agg/)。

## 声明语法

语法图源码

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

````

## 参数

以下为 ListAgg 聚合值变量的特有参数。关于声明语法中其他参数的详细信息，请参见[参数](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/variable-definition/agg/#_6)。

### `data_type`

字段所持有值的数据类型。支持的数据类型包括数值、字符串、布尔值、时间和日期、向量、列表、记录、地理空间。更多信息，请参见[数据类型](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/data-types/)。

### `field_name`

记录中的字段名称。`field_name`必须是标识符。有关标识符的更多信息，请参见[标识符命名规则](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/overview/keywords-identifiers/#_3)。

## 初始值

从声明语法中可见，声明时不能指定初始值。

## 输入类型与支持的操作

输入类型必须为声明时指定的类型`T`。

支持[赋值与聚合](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/set/)操作。

## 返回类型

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

````

返回类型为列表`LIST<T>`，其中每个元素的类型与声明时指定的类型`T`相同。

## 成员函数

本节介绍 ListAgg 聚合值变量支持的成员函数。

### size()

返回 ListAgg 聚合值变量中列表的元素数量。

#### 函数签名

````
size() -> UINT64

````

### clear()

移除 ListAgg 聚合值变量中列表的所有元素。

#### 函数签名

````
clear() -> VOID

````

## 示例

以下示例基于 [CREATE TEMPORARY GRAPH](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/ddl/graph-projection/create/) 中创建的临时图`#movie_temporary_graph`。

### 全局 ListAgg 聚合值变量

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

  // 用空列表进行赋值
  SET @global_list_1 = []   // 清空列表
  LOG_INFO("List from empty LIST:", @global_list_1)   // 输出： []

  // 用列表进行赋值
  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)

  // 用另一个 ListAgg 进行赋值
  SET @global_list_1 = @global_list_2         // global_list_1: [3, 4]
  LOG_INFO("After assignment from list_2: ", @global_list_1)

  // 用另一个 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)

  // 成员函数
  SET @global_list_2.clear()   // 清空列表
  LOG_INFO("Clear the list: ", @global_list_2)       // 输出：[]
  LOG_INFO("Size: ", @global_list_1.size())       // 输出：4
}
'''

````

返回：

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

````

### 点绑定 ListAgg 聚合值变量

````
'''
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 {
    // 对于每条匹配的路径，将电影 ID 作为值添加到用户的列表中
    SET a.@node_list += b.id
  }
  PER NODE (a) {
    LOG_INFO("a.id: ", a.id, " a.@node_list: ", a.@node_list)
  }
}
'''

````

上述示例声明了一个类型为`ListAgg<DOUBLE>`的点绑定聚合值变量`node_list`。该变量用于存储每个用户观看的电影的 ID 列表。

返回：

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

````