# The Graph 查询没有数据？先检查子图、区块与分页

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

从官方 Explorer 定位子图，通过 schema 和 _meta 检查部署、索引状态及结果范围，避免把查询失败或索引滞后解释成链上没有活动。

## 使用工具
- [The Graph](https://lianxiaozhi.com/tools/the-graph) · [官方入口](https://thegraph.com/)

## 前置条件
- 明确要查询的协议、网络、实体和时间范围。只读查询不需要钱包签名。
- 能够查看目标子图的 schema 与查询入口；API key、配额和访问要求以当前官方页面为准，不把密钥放进公开截图。

## 1. 找到目标协议在目标网络上的子图

从官方 Graph Explorer 的 Subgraphs 页面搜索，核对名称、网络、发布者和版本。搜索排序或查询热度只帮助发现候选，不证明子图就是协议唯一官方数据源。

记录子图链接与 deployment 标识。存在多个部署时，回到协议自己的资料核对推荐入口，避免将旧测试部署的数据用于正式分析。

核对结果：查询记录中有网络、子图链接和部署标识，来源关系可说明。
依据：[The Graph：在 Explorer 中查找子图](https://thegraph.com/docs/en/subgraphs/existing-subgraphs/explorer/)
依据：[The Graph：GraphQL 字段、分页、历史区块与元数据](https://thegraph.com/docs/en/subgraphs/querying/graphql-api/)

## 2. 先读 schema 再拼查询

GraphQL 根字段来自该子图的实体定义。查看目标实体有哪些字段、类型与关系，不要把其他子图的 swaps 或 users 字段直接复制进来。

单实体通常按 id 查询，实体列表则读取复数根字段。子图查询是只读接口；需要 mutation 的任务不能靠修改查询字符串完成。

核对结果：每个查询字段都能在该部署的 schema 中找到。
依据：[The Graph：GraphQL 字段、分页、历史区块与元数据](https://thegraph.com/docs/en/subgraphs/querying/graphql-api/)

## 3. 用元数据核对索引进度

先运行简单元数据查询：{ _meta { block { number hash timestamp } deployment hasIndexingErrors } }。将返回的区块号与部署标识保留到分析记录。

block 描述子图已处理的区块信息；hasIndexingErrors 为 true 表示曾有索引错误，不能默认这些错误与当前研究无关。若元数据请求本身失败，先保留错误，不能写成区块为零。

核对结果：保存实际返回区块及错误标记；没有返回时标记读取失败。
依据：[The Graph：GraphQL 字段、分页、历史区块与元数据](https://thegraph.com/docs/en/subgraphs/querying/graphql-api/)

## 4. 让结果范围与问题一致

在实体列表上设置明确的过滤条件、排序方向和 first 数量。官方文档说明默认排序按 ID 字母数字顺序，不能默认第一页就是最近创建的记录。

需要历史区块时，确认该子图与查询入口支持对应 block 参数，并记录区块号或哈希。历史状态还有链重组与最终性约束，结果时间不能仅从查询执行时间推断。

核对结果：查询记录包含筛选条件、排序、数量上限及使用的区块范围。
依据：[The Graph：GraphQL 字段、分页、历史区块与元数据](https://thegraph.com/docs/en/subgraphs/querying/graphql-api/)

## 5. 分页后才能判断整体数量

返回 first 条记录只能说明当前页的结果。数据量较大时，官方建议使用属性游标，例如稳定排序下的 id_gt，避免大 skip 带来的性能问题。

保存最后一个游标并继续下一页，注意沿用相同过滤和排序。运行中部署或索引高度变化时，记录变化并重新评估可比性，不能把截断页数当成全量。

核对结果：总量结论能说明分页终点；没有分页完成时标注只是样本页。
依据：[The Graph：GraphQL 字段、分页、历史区块与元数据](https://thegraph.com/docs/en/subgraphs/querying/graphql-api/)

## 6. 按原因解释空结果

先查字段与过滤是否匹配，再查网络、部署和索引区块，最后才判断目标事件在该子图中确实无记录。某些链上活动根本不在子图设计的实体范围内。

将 schema 错误、访问错误、索引滞后和有效空数组分开保存。需证明链上没有发生时，还应回到交易或事件原始证据核对，子图空结果本身不是充分证据。

核对结果：空结果解释包含已检查的部署、范围、索引进度与仍存在的缺口。
依据：[The Graph：在 Explorer 中查找子图](https://thegraph.com/docs/en/subgraphs/existing-subgraphs/explorer/)
依据：[The Graph：GraphQL 字段、分页、历史区块与元数据](https://thegraph.com/docs/en/subgraphs/querying/graphql-api/)

## 常见错误
- 将名称相近的测试网子图当成主网数据。
- 默认结果按时间倒序，或把第一页当全量。
- 请求报错、索引滞后和有效空结果都记成零。
- 忽略子图 schema 并不覆盖协议的所有链上行为。

## 完成检查
- 能复现同一子图、同一范围和同一排序的查询。
- 结果附有索引区块、部署及分页范围。
- 空结果有明确状态与证据边界。

## 相关知识

## 官方依据
- [The Graph：在 Explorer 中查找子图](https://thegraph.com/docs/en/subgraphs/existing-subgraphs/explorer/)
- [The Graph：GraphQL 字段、分页、历史区块与元数据](https://thegraph.com/docs/en/subgraphs/querying/graphql-api/)