Spring Data JPA原生查询分页报错：limit附近存在语法错误

核心原因分析 #

Spring Data JPA对原生SQL分页的支持依赖于能正确识别主查询结构，当你的原生SQL包含子查询、联合查询等复杂逻辑时，框架自动拼接LIMIT/OFFSET的位置可能出错，直接破坏SQL语法。另外countQuery写法不规范、数据库方言配置错误也会引发这类问题。

具体解决方法 #

1. 调整主查询结构，适配框架分页拼接逻辑 #

如果主查询包含子查询或多表关联，需要将整个查询逻辑包裹在一个子查询中，确保框架能在最外层正确添加LIMIT/OFFSET。

比如原错误查询：

SELECT c.* FROM _chat c 
LEFT JOIN (SELECT chat_id, MAX(created_at) as last_msg_time FROM _message GROUP BY chat_id) m 
ON c.id = m.chat_id 
WHERE c.user_id = :userId 
ORDER BY COALESCE(m.last_msg_time, c.created_at) DESC

修改为：

SELECT t.* FROM (
    SELECT c.*, COALESCE(m.last_msg_time, c.created_at) as sort_time 
    FROM _chat c 
    LEFT JOIN (SELECT chat_id, MAX(created_at) as last_msg_time FROM _message GROUP BY chat_id) m 
    ON c.id = m.chat_id 
    WHERE c.user_id = :userId
) t 
ORDER BY t.sort_time DESC

2. 修正countQuery的写法 #

countQuery必须是独立的、能准确统计符合条件记录数的原生SQL，且筛选条件要和主查询完全一致，避免遗漏或逻辑偏差：

SELECT COUNT(DISTINCT c.id) FROM _chat c 
LEFT JOIN _message m ON c.id = m.chat_id 
WHERE c.user_id = :userId

3. 检查基础配置项 #

• 确认@Query注解已添加nativeQuery = true，这是原生查询支持分页的必要开关；
• 核对数据库方言配置是否匹配当前使用的数据库（比如PostgreSQL对应org.hibernate.dialect.PostgreSQLDialect），方言错误会导致框架生成不符合数据库语法的分页语句；
• 避免Pageable中的排序参数与SQL内的ORDER BY重复冲突，建议要么在SQL中固定排序逻辑，要么将排序完全交给Pageable（需确保排序字段是数据库存在的字段或子查询中的别名）。

完整代码示例 #

@Query(value = "SELECT t.* FROM (SELECT c.*, COALESCE(m.last_msg_time, c.created_at) as sort_time FROM _chat c LEFT JOIN (SELECT chat_id, MAX(created_at) as last_msg_time FROM _message GROUP BY chat_id) m ON c.id = m.chat_id WHERE c.user_id = :userId) t ORDER BY t.sort_time DESC",
       countQuery = "SELECT COUNT(DISTINCT c.id) FROM _chat c LEFT JOIN _message m ON c.id = m.chat_id WHERE c.user_id = :userId",
       nativeQuery = true)
Page<Chat> findChatsByUserId(@Param("userId") Long userId, Pageable pageable);

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