Redis Search偏移量上限问题及Cursor API适用性咨询

为避免客户端内存溢出，我采用LIMIT分页（累加offset）从Redis Search（ft.search）批量获取4-5万条数据，但offset达到10000时出现异常：执行ft.search idx:cits "*" LIMIT 10000 10仅返回总数，offset=10001时报错“OFFSET exceeds maximum of 10000”。现咨询：

1. 能否通过JavaScript代码或Redis配置修改该偏移量上限？
2. 若不能，有何替代方案？
3. Cursor API是否存在相同限制？它可处理多少条目？

附问题复现代码：

const { createClient, SchemaFieldTypes } = require('redis')

const client = createClient()

async function start(client) {
    await client.connect()
    try {
        // 仅按这3个字段排序
        await client.ft.create(
            'idx:cits',
            {
                mid: {
                    type: SchemaFieldTypes.TAG
                },
                timestamp: {
                    type: SchemaFieldTypes.NUMERIC,
                    sortable: true
                },
                position: {
                    type: SchemaFieldTypes.GEO
                }
            },
            {
                ON: 'HASH',
                PREFIX: 'CITS'
            }
        )
    } catch (e) {
        if (e.message === 'Index already exists') {
            console.log('索引已存在，跳过创建。')
        } else {
            console.error(e)
            process.exit(1)
        }
    }

    for (let index = 0; index < 45000; index++) {
        await client.hSet(`CITS:${index}:0:0:00:00:5e:00:53:af`, {
            timestamp: index,
            position: '0,0',
            mid: '00:00:5e:00:53:af',
            message: 'payload'
        })
    }

    try {
        let results = await client.ft.search(
            'idx:cits',
            '@mid:{00\:00\:5e\:00\:53\:af}',
            { LIMIT: { from: 10000, size: 10 } }
        )
        console.log(results)
        results = await client.ft.search(
            'idx:cits',
            '@mid:{00\:00\:5e\:00\:53\:af}',
            { LIMIT: { from: 10001, size: 10 } }
        )
    } catch (e) {
        console.log(e)
    }

    await client.quit()
}
start(client)

1. 能否修改偏移量上限？ #

不能通过JavaScript代码或常规Redis配置修改10000的offset上限。这是Redis Search内置的性能保护机制——过大的offset会迫使Redis扫描并跳过大量结果，占用极高的内存和CPU资源，严重影响服务稳定性，因此官方固定了这个限制。

2. 替代方案 #

方案一：基于排序字段的键集分页 #

利用你已设置为sortable的timestamp字段，每次分页时记录最后一条数据的timestamp值，下一次查询通过范围条件过滤掉之前的数据，彻底替代offset。示例代码：

async function fetchBatch(client, lastTimestamp = -Infinity, batchSize = 1000) {
    const results = await client.ft.search(
        'idx:cits',
        `@mid:{00\:00\:5e\:00\:53\:af} @timestamp:[${lastTimestamp}+inf]`,
        { 
            LIMIT: { from: 0, size: batchSize },
            SORTBY: { BY: 'timestamp', DIRECTION: 'ASC' }
        }
    )
    if (results.total === 0) return null;
    // 获取当前批次最后一条数据的timestamp
    const lastItem = results.documents.at(-1);
    const newLastTimestamp = lastItem.value.timestamp;
    return { data: results.documents, nextTimestamp: newLastTimestamp };
}

// 批量获取所有数据的调用示例
async function fetchAllData(client) {
    let allData = [];
    let lastTimestamp = -Infinity;
    while (true) {
        const batch = await fetchBatch(client, lastTimestamp);
        if (!batch) break;
        allData.push(...batch.data);
        lastTimestamp = batch.nextTimestamp;
        // 可选：添加小延迟避免压垮Redis服务
        await new Promise(resolve => setTimeout(resolve, 100));
    }
    return allData;
}

这种方式性能远优于offset分页，没有10000的上限限制，适合大规模数据批量获取。

方案二：使用Redis Search Cursor API（下文详细说明） #

3. Cursor API的限制与能力 #

Cursor API不存在10000的offset限制，它是Redis官方专为大规模结果集遍历设计的方案，通过服务器端维护游标状态，每次返回一批结果，直到游标耗尽。

使用Cursor API的示例代码：

async function fetchWithCursor(client, batchSize = 1000) {
    let allData = [];
    // 初始化游标，获取第一个批次和游标ID
    let cursorResult = await client.ft.search(
        'idx:cits',
        '@mid:{00\:00\:5e\:00\:53\:af}',
        { 
            CURSOR: 0,
            LIMIT: { size: batchSize }
        }
    );
    allData.push(...cursorResult.documents);
    
    // 循环获取后续批次，直到游标ID为0（表示遍历完成）
    while (cursorResult.cursor !== 0) {
        cursorResult = await client.ft.search(
            'idx:cits',
            '@mid:{00\:00\:5e\:00\:53\:af}',
            { 
                CURSOR: cursorResult.cursor,
                LIMIT: { size: batchSize }
            }
        );
        allData.push(...cursorResult.documents);
        await new Promise(resolve => setTimeout(resolve, 100));
    }
    return allData;
}

Cursor API可以处理百万级甚至更大的结果集，只要服务器资源足够。需要注意两点：

• 游标默认10分钟后过期，若遍历时间较长，可在创建索引或查询时通过CURSOR_TIMEOUT参数（单位毫秒）调整过期时间；
• 每次调用必须传递上一次返回的游标ID，直到游标ID为0时停止遍历。

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