ClickHouse 不支持 OFFSET 是因性能与设计冲突：它需全量扫描再丢弃前N行，违背列式存储跳过数据块的初衷；唯一高效分页是基于主键/排序字段的游标式下推查询。
ClickHouse 不支持 OFFSET 的根本原因
GORM 默认的 Offset() + Limit() 分页逻辑在 ClickHouse 上会直接报错或返回空结果，因为 ClickHouse 从 v21.8 起已明确禁用 OFFSET（错误信息：Unsupported syntax: OFFSET），且即使旧版本允许，性能也极差——它仍需扫描并丢弃前 N 行，违背列式存储“跳过无关数据块”的设计初衷。
真正可行的分页必须基于主键/排序字段的**游标式（cursor-based）下推**，让 ClickHouse 利用索引（如 ORDER BY 字段的跳数索引）直接定位数据块。
- ClickHouse 的
LIMIT n OFFSET m实际执行时不会跳过数据块，而是读全量再内存过滤，m 越大越慢 - GORM 的
Find(&results).Offset(10000).Limit(10)会被翻译成含OFFSET的 SQL，触发报错 - 唯一被 ClickHouse 高效支持的分页模式是：带
WHERE条件的连续范围查询，例如WHERE id > ? ORDER BY id LIMIT 10
GORM 中手动实现游标分页的关键写法
不能依赖 GORM 的 Offset，必须把分页逻辑下沉到 Where 和 Order 组合中。假设表有单调递增的 id（或时间戳 created_at），且已建好排序索引（ORDER BY (id)）：
// 第一页（无游标）
db.Order("id ASC").Limit(10).Find(&items)
// 后续页：传入上一页最后一条的 id 值（cursor）
lastID := items[len(items)-1].ID
db.Where("id > ?", lastID).Order("id ASC").Limit(10).Find(&items)
- 必须确保
ORDER BY字段与WHERE条件字段一致，否则 ClickHouse 可能无法利用跳数索引 - 若排序字段非唯一（如多个记录共用同一
created_at），需追加二级排序字段去重：ORDER BY created_at ASC, id ASC，且WHERE条件也要包含两者：WHERE (created_at, id) > (?, ?) - GORM 不原生支持复合游标比较，需手写 SQL 片段：
db.Where("(created_at, id) > (?, ?)", lastTime, lastID).Order("created_at ASC, id ASC")...
使用 GORM 的 Scopes 封装可复用的分页逻辑
把游标条件、排序、limit 抽成 Scope，避免每个查询重复写 Where 和 Order：
func CursorPage(cursor int64, limit int) func(db *gorm.DB) *gorm.DB {
return func(db *gorm.DB) *gorm.DB {
if cursor == 0 {
return db.Limit(limit)
}
return db.Where("id > ?", cursor).Limit(limit)
}
}
// 使用
db.Scopes(CursorPage(lastID, 10)).Order("id ASC").Find(&items)
- 注意：
Scope函数内不能调用db.Order()，因为 GORM 的Order是链式方法，需在Scopes外显式调用 - 如果业务需要支持“倒序分页”，游标逻辑要反转：
WHERE id < ? ORDER BY id DESC，且首次查询用ORDER BY id DESC LIMIT 10 - 不要在 Scope 中硬编码表名或字段名，应通过结构体标签（如
gorm:"primaryKey"）动态获取，提升可维护性
为什么 GORM 的 Count() 在 ClickHouse 里可能不准或超时
ClickHouse 的 COUNT(*) 虽快，但一旦加上复杂 WHERE 条件（尤其涉及多表 JOIN 或嵌套函数），就可能触发全表扫描或内存溢出。而 GORM 的 Count() 方法默认生成 SELECT COUNT(*) FROM (...) AS count 子查询，ClickHouse 对子查询优化较弱。
- 避免在分页接口中调用
db.Count(&total)—— 它可能比主查询还慢，且对列式数据库意义不大 - 真实场景中，用户并不需要精确总页数；可改用“是否有下一页”判断：
len(results) == limit，更轻量也更符合 ClickHouse 特性 - 如真需总数，应单独建物化视图或定时汇总表，而非每次请求实时算
游标分页本身不依赖总数，但开发者常因习惯强行加 Count，这是最容易被忽略的性能陷阱。ClickHouse 的优势在于快速取局部数据，不是强一致性全局统计。
