跳到主要内容

分页与游标

查询结果按数据集的业务键稳定排序，用游标逐页取回。

请求与响应​

位置成员说明
请求体page.limit每页行数，1 至 1000，默认 1000。
请求体page.cursor首页省略或为 null；之后填上一页返回的 page.nextCursor。
响应page.nextCursor下一页的游标；已到最后一页时为 null。
响应page.complete为 true 表示本页是最后一页。

规则​

  • 翻页时 select、where 与 page.limit 必须与首页完全一致。游标绑定这次查询、所用凭据和首页的发布版本，改变其中任何一项都要从首页重新开始。
  • 游标固定首页所用的发布版本，翻页期间数据不会因新版本发布而错位。请求体同时携带 releaseId 时，它必须与游标的版本一致。
  • 游标有时效；过期或无效时从首页重新查询即可。

相关错误​

状态错误码含义
422invalid-cursor游标无效或已过期，属于其他查询或其他凭据，或与 releaseId 冲突。
409cursor-release-unavailable游标所属的发布版本已不可用。
409release-unavailable游标所属的版本不再是该数据集的当前版本。

遇到这三种错误时从首页重新查询。

示例​

import requests

BASE_URL = 'https://api.<环境域名>'  # 替换为实际服务地址，见快速开始
HEADERS = {'Authorization': 'Bearer <ACCESS_TOKEN>'}

body = {
    'select': ['security_code', 'trading_date', 'close_price'],
    'where': [{'field': 'trading_date', 'op': 'gte', 'value': '2026-01-05'},
              {'field': 'trading_date', 'op': 'lte', 'value': '2026-01-09'}],
    'page': {'limit': 1000},
}
rows = []
while True:
    response = requests.post(f'{BASE_URL}/v1/datasets/equity.daily_bars/query',
                             json=body, headers=HEADERS, timeout=60)
    response.raise_for_status()
    result = response.json()
    rows += result['data']
    if result['page']['complete']:
        break
    body['page']['cursor'] = result['page']['nextCursor']