HQL使用USE INDEX报错：org.hibernate.hql.internal.ast.QuerySyntaxException

为什么会报错？ #

USE INDEX是MySQL原生SQL的索引提示语法，而你使用的HQL（Hibernate Query Language）是面向实体对象的查询语言，其语法解析器不识别这类数据库专属关键字，因此会抛出QuerySyntaxException提示意外的token USE。

解决方案 #

方案1：改用原生SQL查询

直接使用JPA的createNativeQuery方法编写MySQL原生SQL，就能正常解析USE INDEX：

String nativeSql = "SELECT d.* FROM " + getEntityName() + " d USE INDEX (PRIMARY) WHERE d.id IN :defectIds";
NativeQuery<Defect> query = getEntityManager().createNativeQuery(nativeSql, Defect.class);
query.setParameter("defectIds", ids);
List<Defect> defects = query.getResultList();

方案2：通过HQL查询提示实现（需Hibernate版本支持）

如果不想切换到原生SQL，可尝试使用Hibernate提供的查询hint添加索引提示，无需在HQL语句中直接写USE INDEX：

TypedQuery<Defect> query = getEntityManager().createQuery(
    "select d from " + getEntityName() + " d WHERE d.id in :defectIds", 
    Defect.class
);
// 添加MySQL索引提示的hint
query.setHint("hibernate.query.sql.hint", "USE INDEX (PRIMARY)");
query.setParameter("defectIds", ids);

注意：该hint的兼容性依赖Hibernate版本和MySQL方言，部分旧版本可能不支持，建议测试验证。

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