开发者进阶中级666 次阅读
Subgraph 入门：怎么用 GraphQL 把链上数据查出来
用 GraphQL 查询链上数据的入门思路：manifest、schema 与 mappings 各负责什么，实体又该如何围绕查询来设计。
#The Graph#Subgraph#GraphQL#索引#链上数据
一句话结论
Subgraph 把"链上事件"翻译成"可查询的实体表"：你只声明数据的形状与处理逻辑，同步、存储与查询接口交给网络。
三个组成部分
- manifest：声明索引哪条链、哪些合约、从哪个区块开始，以及"哪个事件交给哪个函数处理"。
- schema：用 GraphQL 定义实体，也就是你希望在数据库里看到的数据表结构。
- mappings：用 AssemblyScript 写的处理函数，事件到达时被调用，由它读取事件参数、更新实体。
发布之后，索引器按 manifest 从指定高度同步，把每条事件喂给对应的映射函数，最终生成一个可以用 GraphQL 任意筛选、排序、分页的数据集。
实体设计的基本思路
关键在于围绕业务查询建表，而不是照抄合约的存储结构。合约里嵌套的 map 与 struct，在 GraphQL 里通常要拆成独立实体并用 ID 关联，例如用户、交易、池子、快照。同时要预留聚合字段（累计量、计数、最新值），因为查询端几乎一定需要排序。还要想清楚实体的粒度：一个实体代表一次事件，还是代表一个被反复更新的状态。
限制与取舍
GraphQL 查询很方便，但做不了复杂计算，也不能跨 subgraph 关联查询；映射函数是确定性执行的，不能发起外部网络请求。历史回填会消耗大量时间与索引资源，而 schema 改动通常意味着部署一个新版本、重新同步。
给你的教训
- 先定义查询，再设计 schema：从"前端要展示什么列表、按什么排序"倒推需要哪些字段。
- 映射函数必须容忍乱序与重复：重组、同块多事件、重复投递都会出现。
- 上线前确认清楚托管方式：托管服务与去中心化网络在可用性、费用与权限上完全不同。
- 别把它当通用数据库：需要写回、需要事务、需要权限控制的逻辑，都不该放在这里。