迁移至Hibernate 6时命名查询报错：无法解析'DATETIME'路径表达式

问题场景 #

原有基于SQL Server的JPA命名查询代码如下：

@NamedQuery(query="SELECT a FROM Employee a WHERE a.id = :id AND (a.dob > CONVERT(DATETIME, :dob, 102))")

迁移至Hibernate 6后，抛出如下错误：

org.hibernate.query.SemanticException: Could not interpret path expression 'DATETIME'

问题原因 #

Hibernate 6对JPQL的语法解析规则更严格，直接在JPQL中使用SQL Server原生的CONVERT(DATETIME, ...)写法时，解析器会将DATETIME误认为是实体的属性路径，从而触发语义错误。

解决办法 #

方法1：使用Hibernate FUNCTION函数调用原生转换 #

通过Hibernate提供的FUNCTION函数，将数据库原生函数的参数以字符串形式传递，避免解析错误：

@NamedQuery(query="SELECT a FROM Employee a WHERE a.id = :id AND (a.dob > FUNCTION('CONVERT', 'datetime', :dob, 102))")

这里将DATETIME作为字符串参数传入FUNCTION，Hibernate会正确识别为SQL Server函数的参数，而非实体属性。

方法2：Java端提前转换日期参数（推荐） #

如果:dob参数可以在业务代码中提前转换为LocalDate/Date类型，直接传递日期对象即可，无需在JPQL中做数据库端转换：

@NamedQuery(query="SELECT a FROM Employee a WHERE a.id = :id AND a.dob > :dob")

该方式符合JPQL的跨数据库设计原则，同时避免了数据库特定语法的依赖。

方法3：改用原生SQL查询 #

如果必须保留SQL Server特定的转换语法，可以将命名查询改为原生SQL查询：

@NamedNativeQuery(name="Employee.findByDob", 
    query="SELECT * FROM Employee a WHERE a.id = :id AND (a.dob > CONVERT(DATETIME, :dob, 102))", 
    resultClass=Employee.class)

原生SQL查询直接绕过JPQL解析器，使用数据库原生语法，但会失去JPQL的跨数据库兼容性。

内容的提问来源于stack exchange，提问作者DEBENDRA DHINDA