Spring Boot+Hibernate+PostgreSQL中array_contains参数绑定报错求助

问题场景 #

在Spring Boot + Hibernate + PostgreSQL环境中，实体类MyEntity定义了如下数组字段：

@Column(name = "relations", columnDefinition = "text[]")
private Set<String> relations = new HashSet<>();

当需要查询包含指定关系值的实体时，硬编码值的查询可以正常运行：

@Query(value = """SELECT e.id FROM MyEntity e WHERE array_contains(e.relations, 'XXXXX')""")
List<String> findByRelation(String relation);

但使用参数绑定方式时，会抛出类型不匹配错误：

Caused by: org.postgresql.util.PSQLException: ERROR: operator does not exist: text[] @> character varying[]
  Hint: No operator matches the given name and argument types. You might need to add explicit type casts.
  Position: 195

原因是Hibernate默认将字符串参数解析为character varying类型，和数据库的text[]数组元素类型不兼容，导致运算符无法匹配。

修复方案 #

方案1：显式转换参数类型

在查询语句中直接将参数强制转换为text类型，匹配数组元素的类型：

@Query(value = """SELECT e.id FROM MyEntity e WHERE array_contains(e.relations, CAST(:relation AS text))""")
List<String> findByRelation(String relation);

方案2：使用PostgreSQL数组包含运算符

改用PostgreSQL原生的@>数组包含运算符，将参数包装为单元素数组并指定text[]类型：

@Query(value = """SELECT e.id FROM MyEntity e WHERE e.relations @> ARRAY[:relation]::text[]""")
List<String> findByRelation(String relation);

方案3：通过Hibernate注解指定参数类型

在方法参数上添加@Type注解，明确指定参数的Hibernate类型为text：

import org.hibernate.annotations.Type;
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.query.Param;

// ...

@Query(value = """SELECT e.id FROM MyEntity e WHERE array_contains(e.relations, :relation)""")
List<String> findByRelation(@Param("relation") @Type(type = "text") String relation);

内容的提问来源于stack exchange，提问作者Kucera.Jan.CZ