历史 SQL 改为滚动 15 天窗口：有哪些变化，如何调整查询

自 8 月以来，历史 SQL 有三项变化：付费订阅改为查询滚动 15 天窗口内的期权成交；接口返回的每一行都至少延迟 15 分钟；查询失败时会返回可据以处理的稳定错误代码。本文逐项说明这些变化，以及代码中需要更新的地方。每项变化的日期记录见 API 更新日志。

历史 SQL 速览

• 付费窗口: 过去 15 天（连续 360 小时）

• 数据新鲜度: 每行至少延迟 15 分钟

• 每次响应行数: 试用 10 行 · 付费约 10,000 行

• 窗口规模: 约 1 亿笔成交量级 - 近几周每个交易日约 1100 万笔

滚动 15 天窗口

自 2026 年 9 月 12 日起，付费（active）订阅仅能查询过去 15 天的成交。窗口为连续 360 小时，包含周末与节假日，通常覆盖约十个交易日。窗口持续滚动：一笔成交在执行满 360 小时后即移出窗口。

窗口在查询执行前生效。即使 SQL 中没有日期条件，更早的成交也会在连接、子查询与聚合之前被排除。由此带来两点影响：

• 跨越窗口边界的日期范围只返回窗口内的成交。
• 只查询更早日期的查询会不返回数据，而不是报错。如果原本正常的查询现在返回空结果，请先检查其中的日期。

付费成功响应包含 meta.lookback_days: 15，代码可据此确认所用的窗口。试用访问不变：试用响应最多返回 10 行。

每行至少延迟 15 分钟

自 2026 年 8 月 10 日起，历史 SQL 只返回执行时间戳至少已过去 15 分钟的成交。该规则作用于对成交表的每一次读取，包括嵌套查询与聚合，因此无法通过子查询读到更新的数据。

每次成功响应都会返回 meta.minimum_data_delay_minutes: 15 与响应头 X-OptionData-Historical-Sql-Minimum-Data-Delay-Minutes。需要实时成交，请使用实时 WebSocket。

更新你的查询

把固定日期改为相对日期

固定在较早日历日期上的查询，在付费套餐下现在不会返回数据。请改用近期的相对日期，并尽早加上标的筛选：

SELECT
  symbol,
  put_call,
  count() AS trades,
  sum(toFloat64(price) * size * 100) AS total_premium
FROM RawOptionTrades
WHERE symbol = 'AAPL'
  AND date >= today() - 7
GROUP BY symbol, put_call
ORDER BY total_premium DESC

低成本获取最新交易日

用体量很小的 RawOptionTradesMaxDateOnlyMV 视图获取最新交易日。直接对 RawOptionTrades 做不加限定的 max(date) 会扫描整张表，并以 QUERY_TOO_BROAD 失败。

SELECT max(date) AS latest_date
FROM RawOptionTradesMaxDateOnlyMV

读取响应中的 meta

在使用结果前，检查 meta.entitlement、meta.row_limit、meta.capped、meta.lookback_days 与 meta.minimum_data_delay_minutes。试用响应最多 10 行，付费响应最多约 10,000 行。

可据以处理的错误

查询失败时不再暴露数据库内部信息，也不再笼统返回 HTTP 500。每种失败都有稳定的 errorCode，查询本身的问题还会附带 reason：

INVALID_QUERY 的 reason 取值包括 UNKNOWN_IDENTIFIER、UNKNOWN_FUNCTION、TYPE_MISMATCH、NUMERIC_OVERFLOW、SYNTAX_ERROR、INVALID_AGGREGATION、INVALID_ARGUMENTS 与 INVALID_EXPRESSION：

{
  "status": "ERROR",
  "errorCode": "INVALID_QUERY",
  "reason": "UNKNOWN_IDENTIFIER",
  "errorMsg": "The query references a column, alias, or table identifier that is not available."
}

NUMERIC_OVERFLOW 通常来自定点精度列相乘。请在相乘或聚合前先转换类型，例如上文的 sum(toFloat64(price) * size * 100)。

没有变化的部分

RawOptionTrades 表结构、仅限 SELECT 的规则与接口地址都保持不变。推荐使用 Authorization: Bearer YOUR_API_KEY 认证，body 中的 api_key 字段仍然可用。标准 Pro 访问不包含窗口之外的更早成交；如需单独约定范围的导出，需要书面约定，请通过支持页面联系销售。

延伸阅读

• 历史期权成交 API 参考：表结构、限制与全部错误格式。
• 历史 SQL 快速入门：几分钟内跑通第一条查询。
• 期权链 API：可返回任意保留交易日的完整期权链，包括 15 天成交窗口之前的交易日。

用 OptionData API 运行。 注册，通过支持页面的二维码联系方式申请完成资格审核所需的邀请码，然后在准备好时主动激活 14 天免卡试用。符合条件的试用用户可从销售处获取优惠码，首年享受 50% 优惠；请联系销售获取优惠码，然后在试用结束前于账单页面输入。一个密钥覆盖实时 WebSocket、历史 SQL、期权链 REST 与市场结构。