array_agg必须配合group by使用，否则报错；正确用法包括按列分组、恒真分组group by ()、order by需置于函数内控制数组元素顺序，空组返回null需用coalesce兜底，不可与string_agg直接混用。

ARRAY_AGG必须配合GROUP BY使用，否则报错

直接写 SELECT ARRAY_AGG(name) 会触发错误：「ERROR: aggregate functions are not allowed in WHERE」或更常见的「ERROR: column "name" does not exist」——因为 ARRAY_AGG 是聚合函数，不能脱离分组上下文独立运行。它不像 COUNT(*) 那样允许无 GROUP BY 的全表聚合（除非你真想把整张表压成一个数组）。

正确姿势是明确分组维度：

• 按单列分组：SELECT dept, ARRAY_AGG(name) FROM employees GROUP BY dept
• 按多列分组：SELECT dept, role, ARRAY_AGG(id) FROM employees GROUP BY dept, role
• 不带 GROUP BY 但需全表聚合？加个恒真分组：SELECT ARRAY_AGG(name) FROM employees GROUP BY ()（返回一行一列，含完整数组）

ORDER BY必须写在ARRAY_AGG括号内，不能放外面

很多人写成 SELECT dept, ARRAY_AGG(name) ORDER BY name，结果发现排序无效——ORDER BY 在 ARRAY_AGG 外层只影响最终结果集顺序，不影响数组内部元素排列。

真正控制数组内顺序的写法，是把 ORDER BY 放进函数参数里：

• 升序（默认）：ARRAY_AGG(name ORDER BY name)
• 降序+处理 NULL：ARRAY_AGG(name ORDER BY name DESC NULLS LAST)
• 复合排序（如先按长度、再按字典）：ARRAY_AGG(name ORDER BY LENGTH(name), name)

注意：如果没加 ORDER BY，PostgreSQL 不保证数组元素顺序，不同执行计划可能导致结果波动——这点在做一致性校验或前端渲染时容易翻车。

空组和NULL值会让ARRAY_AGG返回NULL，不是空数组

当某组没有匹配行（比如 LEFT JOIN 后右表无数据），ARRAY_AGG 返回的是 NULL，不是 {}。这对应用层反序列化很危险：Java 的 ObjectMapper 或 Python 的 json.loads 可能直接抛异常，而不是给你一个空列表。

安全写法是用 COALESCE 显式兜底：

• COALESCE(ARRAY_AGG(name), ARRAY[]::text[]) → 强制转为空 text 数组
• COALESCE(ARRAY_AGG(id), ARRAY[]::int[]) → 对整数列同理
• 别写 COALESCE(ARRAY_AGG(name), '{}')，字符串字面量在类型推导时易出错

另外，源列本身含 NULL 时，ARRAY_AGG 默认保留它们；如需过滤，得提前用 WHERE name IS NOT NULL 或在表达式里套 COALESCE(name, 'N/A')。

和string_agg混用时，类型对齐比想象中更敏感

你可能想先用 ARRAY_AGG 拿明细，再用 string_agg 做展示，但这两者不兼容：前者输出数组类型（如 text[]），后者只接受标量表达式。直接传 string_agg(ARRAY_AGG(name), ',') 会报错「function string_agg(text[], unknown) does not exist」。

正确组合方式只有两种：

• 用 ARRAY_AGG + 应用层拼接（推荐）：保持结构化，方便去重、查长度、随机取样等后续操作
• 改用 string_agg 单独完成：string_agg(name, ', ' ORDER BY name)，省掉中间数组开销

特别提醒：如果字段是 jsonb 类型，ARRAY_AGG(jsonb_col) 返回的是 jsonb[]，但多数 ORM（如 SQLAlchemy、MyBatis）默认不识别该类型，需显式注册类型处理器或转成 TEXT 再解析。