# SQD Solana只返回部分区间？核批次续读、409重组与最终块水位

整理：链小知（AI 辅助）
资料核对日期：2026-10-14
引用地址：https://lianxiaozhi.com/tools/guides/sqd-solana-stream-continuation-reorg-check
难度：进阶
核验方式：官方文档整理，未执行真实账户操作

按slot、字段选择和最后块续读规则核记录完整范围，不把空数据或暂时容量不足当链上零活动。

## 使用工具
- [SQD Portal](https://lianxiaozhi.com/tools/sqd) · [官方入口](https://sqd.dev/portal/)

## 前置条件
- 准备自己已有的脱敏配置、材料或响应记录，保留产品版本、网络、字段和采样时间；缺项保持未知。

## 1. 固定数据集、范围与访问层

从自己的记录固定solana-mainnet和type=solana，fromBlock为起始slot，toBlock为包含的截止slot；不要拿EVM块号套入Solana。Public是共享开发/评估容量，认证入口需Bearer或x-api-key；Public/Testing非商业，文档付费计划目前early access而非已开通保障。

核对结果：数据集、slot边界及访问用途各有依据；没有假定商业权限或SLA。
依据：[SQD：Solana stream请求字段与响应契约](https://docs.sqd.dev/en/api/solana/stream.md)
依据：[SQD：Portal计划、非商业开发与计费待上线](https://docs.sqd.dev/en/portal/pricing.md)
依据：[SQD：错误分类、重试与凭据权限](https://docs.sqd.dev/en/portal/introduction/error-handling.md)

## 2. 区分筛选器与返回字段

instructions数组的programId筛选程序；fields.instruction选择返回data、programId、accounts或transactionIndex，fields.block保留number和hash供续读。指令选择覆盖调用树内指令而非仅顶层；d1–d8按数据起始字节的0x十六进制匹配，a0–a15按accounts位置，不能把它们当任意文本搜索。

核对结果：过滤条件和输出字段分别登记；未只靠顶层指令推完整调用范围。
依据：[SQD：Solana stream请求字段与响应契约](https://docs.sqd.dev/en/api/solana/stream.md)

## 3. 以实际最后块续读同一条件

JSON Lines每行一个块。默认只含匹配数据的块，但总会包含本批实际覆盖区间首尾块；一批可在toBlock之前结束。设最后收到的header.number=N，下一批fromBlock=N+1，其他范围/过滤/字段保持；不能按返回条数推已读slot数。读取/解析中断或缺最后块时，完整截止范围仍未知。

核对结果：续读使用最后块号而非行数；请求截止与实际覆盖截止没有混同。
依据：[SQD Portal：Solana续读、最终性与重组](https://docs.sqd.dev/en/api/solana/introduction.md)
依据：[SQD：Solana stream请求字段与响应契约](https://docs.sqd.dev/en/api/solana/stream.md)

## 4. 未最终流遇409要回滚后续读

/stream续读带parentBlockHash，值为下一批首块预期父块hash；409 base_block_mismatch返回previousBlocks供定位新共识。撤回孤块造成的本地状态后，从较早位置重读，并继续带父hash；可能连续409，不能简单重试同一错误父hash。若任务只需最终数据，可选/finalized-stream，不能将其与含未最终块的/stream混为同一保障。

核对结果：父hash与续读位置一致；孤块回退、重复409及最终流选择有明确分支。
依据：[SQD Portal：Solana续读、最终性与重组](https://docs.sqd.dev/en/api/solana/introduction.md)
依据：[SQD：错误分类、重试与凭据权限](https://docs.sqd.dev/en/portal/introduction/error-handling.md)
依据：[SQD：Solana finalized-stream契约](https://docs.sqd.dev/en/api/solana/finalized-stream.md)

## 5. 最终水位和错误按契约判

/stream可带X-Sqd-Finalized-Head-Number/Hash，该块及更早块不会重组；负载均衡切换可能使后续头部数字降低，应保留已收到的最高最终水位。204表示请求范围尚无块且无错误body，不是零活动结论。overloaded按Retry-After等候，availability_error按提示退避；invalid_request/authentication/permission和api_error不靠同请求盲重试解决，message为不稳定说明而非程序匹配键。

核对结果：缺头部保持未知；最终水位不倒退；204、容量、请求和权限错误未填零。
依据：[SQD Portal：Solana续读、最终性与重组](https://docs.sqd.dev/en/api/solana/introduction.md)
依据：[SQD：错误分类、重试与凭据权限](https://docs.sqd.dev/en/portal/introduction/error-handling.md)

## 常见错误
- 一批没有匹配指令不代表整段范围已读完；返回200也不证明完整范围或最终性。
- 月度数据量按解压后字节衡量，包含链按生态口径计，不等数据集条数。

## 完成检查
- 保存输入、字段/单位、判定结果及待核差异；官方方法已核，实际客户端行为和本人服务权限未验证。

## 相关知识

## 官方依据
- [SQD Portal：Solana续读、最终性与重组](https://docs.sqd.dev/en/api/solana/introduction.md)
- [SQD：Solana stream请求字段与响应契约](https://docs.sqd.dev/en/api/solana/stream.md)
- [SQD：Solana finalized-stream契约](https://docs.sqd.dev/en/api/solana/finalized-stream.md)
- [SQD：错误分类、重试与凭据权限](https://docs.sqd.dev/en/portal/introduction/error-handling.md)
- [SQD：Portal计划、非商业开发与计费待上线](https://docs.sqd.dev/en/portal/pricing.md)