Spring Data JPA使用@Query查询列表字段报QuerySyntaxException如何解决

你出现该报错的根本原因是编写HQL查询时混淆了实体类/实体属性名和数据库表/列名：
HQL（Hibernate Query Language）是面向实体对象的查询语言，语法要求FROM后接实体类名，字段引用使用实体类的属性名，你当前写的HQL里FROM后用了数据库表名communication，字段引用用了数据库列名appointment_type_ids，不符合HQL语法规范，因此触发语法解析错误。

方案1：修正HQL写法（推荐） #

直接修正HQL里的实体类名和属性名即可，判断元素是否属于集合可以用HQL原生支持的MEMBER OF关键字，兼容性更好：

@Query("SELECT c FROM Communication c WHERE ?1 MEMBER OF c.appointmentTypeIds")
List<Communication> findAppointments(Integer targetTypeId);

如果需要保留ANY写法，修正后代码如下：

@Query("SELECT c FROM Communication c WHERE ?1 = ANY(c.appointmentTypeIds)")
List<Communication> findAppointments(Integer targetTypeId);

方案2：使用原生SQL查询 #

如果你希望直接使用数据库表名和列名写SQL，需要给@Query注解添加nativeQuery = true参数声明为原生查询：

@Query(value = "SELECT * FROM communication c WHERE ?1 = ANY(c.appointment_type_ids)", nativeQuery = true)
List<Communication> findAppointments(Integer targetTypeId);

额外注意事项 #

如果你的appointment_type_ids是数据库的数组类型（比如PostgreSQL的int4数组），需要确认实体类的List属性映射配置正确，否则即使查询语法正确也会出现序列化/反序列化异常，参考映射配置如下：

// 需要引入hypersistence-utils依赖支持数组类型映射
@Type(type = "io.hypersistence.utils.hibernate.type.array.ListArrayType")
@Column(name = "appointment_type_ids", columnDefinition = "integer[]")
private List<Integer> appointmentTypeIds;

内容的提问来源于stack exchange，提问作者jenny jenkins