accessing-data

访问 Sui 数据

**MCP 工具：**如果你的环境支持，请同时查询 Sui 文档 MCP 服务（https://sui.mcp.kapa.ai），获取最新答案。用它来验证信息，以及查找这些参考文件未涵盖的细节。

“如何读取 Sui 数据？”是 Agent 编写的 Sui 代码中最常被误答的问题。默认做法已经改变。本技能将解决这个问题。

**关键事实：JSON-RPC 已弃用。**Sui Foundation 主网全节点将在 2026 年 7 月 27 日当周禁用 JSON-RPC，并于 2026 年 10 月中旬前彻底移除相关代码。新代码必须使用 gRPC 或 GraphQL RPC。SuiJsonRpcClient 仍然存在，可用于迁移，但已弃用，不应在新项目中使用。

四种规范的数据接口是：

1. gRPC（普遍可用）——延迟低、实时、便于代码生成。由全节点提供服务。支持流式传输和订阅。适用于交易提交、实时读取和数据摄取管道。
2. GraphQL RPC（普遍可用）——通过通用索引器的 Postgres + 全节点 + Archival Store，灵活地查询关系数据。支持读取、交易提交和试运行。最适合前端、仪表盘、钱包，以及任何能从可组合查询中受益的客户端。
3. Archival Store（普遍可用）——长期存储交易、检查点和对象状态，保留时间超出全节点的裁剪范围。如果运维方已配置归档存储支持，GraphQL RPC 可以透明地将受支持的历史查询路由到 Archival Store。对于 gRPC，客户端必须直接查询 Archival Service 端点，以获取超出全节点保留范围的历史数据。归档路由由运维方配置：如果运维方未设置归档存储支持，数据保留范围将受限于主存储中的数据。
4. 自定义索引器（sui-indexer-alt）——构建自己的数据管道，按应用所需的链上数据建立索引。可写入任意存储层（默认使用 Postgres，但也支持任何后端）。从 GCS 摄取检查点（回填），并通过全节点 gRPC 持续摄取。

链下 Blob 数据（图片、音频、模型、大型 JSON）应存储在 Walrus，而不是链上。Sui 存储 Blob 元数据；Blob 本身存放在 Walrus 存储节点上。

本技能中的所有模式均基于以下资料：

• https://docs.sui.io/concepts/data-access/data-serving（概述和弃用通知）
• https://docs.sui.io/concepts/data-access/graphql-rpc（GraphQL）
• https://docs.sui.io/concepts/data-access/archival-store（归档）
• https://docs.sui.io/guides/operator/indexer-stack-setup（通用索引器）
• https://docs.wal.app（Walrus）

如果不确定某个 API，请先从相关页面获取信息再作答。不要根据 Ethereum/Solana 类推猜测——Sui 的数据接口各不相同。

---

参考文件

grpc — gRPC API

路径： grpc.md **在以下情况加载：**编写后端服务、索引器、交易所、做市商、实时客户端或任何高吞吐量读取路径时。此外，在订阅效果流或进行试运行/交易模拟时也应加载。 **涵盖内容：**服务接口（ledger_service、transaction_execution_service、move_package_service、name_service、subscription_service）、各网络的端点 URL、TypeScript（SuiGrpcClient）和 Rust（sui-rpc crate）客户端、流式传输与请求-响应模式，以及任意语言的代码生成。

graphql — GraphQL RPC

路径： graphql.md **在以下情况加载：**应用需要灵活、可组合的查询时，例如前端需要在单个请求中关联对象数据、所有者元数据和事件历史，通过 GraphQL 提交交易或进行试运行，或使用筛选条件执行历史查询。 **涵盖内容：**GraphQL 端点 URL、与通用索引器及 Archival Store 的关系、SuiGraphQLClient 用法、常见查询结构、分页模式、速率限制、通过 GraphQL 执行和模拟交易，以及执行时附带读取所实现的写后读一致性。

indexers — 自定义索引（sui-indexer-alt）

路径： indexers.md 在以下情况下加载： 用户询问“如何追踪历史记录中的 X 事件？”、“如何构建浏览器 / 排行榜 / 分析管道？”，或者 GraphQL 或 gRPC 查询速度太慢 / 无法按所需方式筛选时。 涵盖内容： 检查点流式处理管道模型、回填（如 gs://mysten-mainnet-checkpoints-use4 这样的 GCS 存储桶）与稳态处理（全节点 gRPC）的区别、编写管道配置（events.toml、obj_versions.toml 模式）、并发调优，以及何时运行通用索引器而非自定义索引器。

archival — 归档存储

路径： archival.md 在以下情况下加载： 所需数据已从全节点中裁剪——例如旧交易、旧对象版本、旧检查点。GraphQL RPC 可在运营方配置后，透明地将受支持的历史查询路由至归档；对于 gRPC，客户端需要单独的归档服务端点。 涵盖内容： 归档存储保留哪些数据、为何会进行裁剪、GraphQL RPC 如何透明地将请求路由至归档（需运营方配置），以及 gRPC 客户端为何需要单独的归档服务端点；还包括使用场景（合规、争议解决、长期分析）。

walrus — 链下 Blob 存储

路径： walrus.md 在以下情况下加载： 用户想要将文件（图像、音频、模型、文档、大型 JSON、视频）存储在“Sui 上”，或试图将数 MB 的数据放入 Move 对象中。请引导他们使用 Walrus。 涵盖内容： 为何不应将 Blob 放到链上（每个对象上限为 250 KB、存储基金的经济机制）、Walrus 模型（通过纠删码编码的 Blob 存储在链下，并由链上可用性证书提供证明）、Blob 生命周期，以及 @mysten/walrus 客户端扩展。

use-cases — 使用场景 → 方法映射

路径： use-cases.md 在以下情况下加载： 用户描述了他们想要做什么，而你需要选择合适的接口。对于不熟悉的数据访问请求，应首先加载此文件。 涵盖内容： 常见使用场景表（余额查询、查询拥有的对象列表、事件订阅、历史时点读取、分析仪表板、跨表联接、Blob 存储），并映射到合适的 API，同时说明理由。

路由指南

任务	加载
“如何从 Sui 读取 X？”（初步问题）	use-cases
编写后端 / 索引器读取路径	grpc + indexers
编写前端数据查询	graphql（钩子模式另需 frontend-apps skill）
构建自定义分析 / 浏览器管道	indexers
查询早于全节点保留期限的数据	archival + graphql
存储 / 检索大型文件	walrus
从 JSON-RPC 迁移	use-cases + grpc + graphql
从零开始设计新应用	use-cases（然后根据客户端类型选择 grpc 或 graphql）
全面审查数据密集型应用的代码	所有参考文件

技能内容

核心概念

• JSON-RPC 已弃用。 Sui Foundation 主网全节点将在 2026 年 7 月 27 日当周禁用 JSON-RPC；并于 2026 年 10 月中旬全面停用。新代码必须使用 gRPC 或 GraphQL RPC。SDK 中仍保留 SuiJsonRpcClient，作为弃用后的临时迁移方案。
• gRPC 是性能优先的默认选择（GA）。 提供类型化 protobuf、流式传输、低延迟，以及支持多种语言的客户端代码生成（TS、Rust、Go、Python 等）。由全节点直接提供服务。最适合后端、索引器，以及使用类型化系统语言构建的应用。
• GraphQL RPC 是灵活性优先的默认选择（GA）。 从通用索引器的 Postgres、全节点和归档存储读取数据。还支持提交交易和模拟执行。单个请求可以涵盖多种实体类型。最适合前端、工具，以及使用动态语言构建的应用。
• 归档路由由运营方配置。 如果运营方配置了归档存储支持，GraphQL RPC 可以透明地将受支持的历史定点查询路由到归档存储。gRPC 不会隐式回退到归档存储——对于超出全节点保留范围的历史数据，gRPC 客户端必须直接查询归档服务端点。如果未配置归档存储，数据保留范围仅限于主存储中保存的数据。
• 之所以需要自定义索引器，是因为没有任何托管 API 能满足所有查询需求。 如果你需要对数百万行数据进行筛选排序，并使用特定于应用的索引，请运行自己的 sui-indexer-alt 流水线。自定义索引器可以通过实现框架的 Store 和 Connection trait，将数据写入任何存储层——Postgres 是默认选项，而非硬性要求。
• 链上存储并非通用的 Blob 存储。 Move 对象大小上限为 250 KB。存储费用只需支付一次（存储基金会将收益重新分配给验证者）。大文件应存放在 Walrus 中。
• 存储基金不会“保存你的数据”。 它是一种经济机制：每笔写入费用的一部分会存入基金；验证者赚取的收益用于支付持续存储成本。它影响的是定价，而非数据的存储位置。

规则

1. 新代码不要使用 JSON-RPC。 JSON-RPC 已弃用；Sui Foundation 主网全节点将在 2026 年 7 月 27 日当周禁用它。如果教程中使用 new SuiClient({ url: getFullnodeUrl(...) })，请改为 new SuiGrpcClient({ network, baseUrl })。如果现有代码使用 SuiJsonRpcClient，请迁移到 SuiGrpcClient 或 SuiGraphQLClient。仅将 SuiJsonRpcClient 作为短期迁移过渡方案提供——它仍存在于 SDK 中，但已弃用。
2. 推荐 API 时说明其 GA 状态。 gRPC、GraphQL RPC 和 Archival Store 均已正式发布（GA）。推荐其中任何一种时——尤其是在回答归档或历史数据相关问题时——请明确说明它们已正式发布。不要称其为 Beta 或实验性功能。
3. 根据构建目标选择初始 API。 前端、工具，以及使用动态语言开发的应用 → 从 GraphQL RPC 开始（功能涵盖 gRPC，支持可组合查询；在运营方配置后，可透明地路由归档请求）。后端、索引器，以及使用静态类型系统语言开发的应用 → 从 gRPC 开始（性能、流式传输、代码生成）。只有遇到限制时才切换。当前的临时限制（将在未来几个月内解决）：只有 gRPC 支持订阅；只有 GraphQL 支持对历史交易和事件进行筛选分页。
4. 不同 API 的归档路由方式不同。 在运营方配置了归档后端后，GraphQL RPC 会透明地将受支持的历史单点查询路由到 Archival Store。gRPC 不会隐式回退到归档服务——对于超出全节点保留范围的历史数据，gRPC 客户端必须直接查询 Archival Service 端点。如果未配置归档，数据保留范围仅限主存储中的内容。
5. 只有托管 API 不适用时，才构建自定义索引器。 运营索引器需要持续投入——包括 Postgres、检查点摄取和故障处理。请先评估 GraphQL RPC。
6. 大型文件应存储在 Walrus 上。 切勿建议将图像、音频或视频嵌入 Move 对象或交易输入中。如果用户正打算这样做，请引导他们查看 walrus 参考文件。
7. 正确匹配使用场景与方法。 参见 use-cases.md：
   • 实时余额 / 所有对象列表 / 币列表 → gRPC client.core.*。
   • 面向前端的灵活多实体查询 → GraphQL RPC。
   • 超过 N 天的历史交易 → GraphQL RPC（在运营方配置后透明地路由至归档）或 通过单独的 Archival Service 端点使用 gRPC。
   • 跨所有事件的自定义排行榜 / 分析 → 自定义索引器。
   • 交易订阅 / 实时效果流 → gRPC 流式传输。
   • 大型文件 → Walrus。
8. 不同 API 的写后读一致性有所不同。 对于 GraphQL RPC，executeTransaction 或 simulateTransaction 下的查询会在一个特殊作用域中执行，时间点紧接已执行或已模拟的交易之后，无需等待索引。这能为不依赖索引历史的字段（例如效果、Gas、对象变更）提供写后读一致性。请优先在同一个 GraphQL 请求中选择这些字段，而不是另发一个需要查询索引的后续请求。对于 gRPC，请在后续读取前调用 client.waitForTransaction({ digest })。在这两种情况下，写入后跨节点读取都不保证立即可见。
9. 不确定时请引用文档。 以上列出的所有来源。

常见错误

• 使用 client.getObject / client.getOwnedObjects / client.getCoins — 这些是已弃用 JSON-RPC 接口中的 v1 方法名。v2 中，所有 v2 客户端都使用 client.core.getObject / client.core.listOwnedObjects / client.core.listCoins。
• 只说“ Sui API”，却不说明是哪一种。“Sui API”混淆了用途各不相同的接口。务必注明 gRPC 或 GraphQL。
• **对于 gRPC 只需一个方法就能处理的简单查询，仍建议用户“使用索引器”。**只有在托管 API 无法满足需求时，才应考虑使用自定义索引器。
• **将图片或大型 JSON“存储在 Sui 上”。**Sui 的对象大小上限为 250 KB，定价模式也不适合这么做。请使用 Walrus。
• **假设 gRPC 和 GraphQL 返回相同的结构。**gRPC 使用 protobuf；GraphQL 使用类型化的 GraphQL。响应结构、字段名称和分页方式都不同。
• **轮询事件。**请改用 gRPC 流式传输／订阅。轮询成本高、延迟也高。
• **从一个 RPC 节点读取数据，却向另一个节点写入数据，并期待读后写一致性。**各完整节点在整个网络中最终会达到一致。对于 GraphQL，优先在同一个 executeTransaction mutation 中选择字段（执行附加范围可提供一致的结果，无需索引）。对于 gRPC，请从写入数据的同一节点读取，或在跨节点读取前调用 waitForTransaction。
• **混淆“存储基金”和“存储服务”。**存储基金是一种代币经济机制，不是可供调用的 API。
• **假设 gRPC 会透明地路由到归档服务。**只有 GraphQL RPC 会将受支持的历史查询透明地路由到 Archival Store（前提是运营方已配置）。对于 gRPC，客户端必须直接查询 Archival Service 端点，才能获取超出完整节点保留范围的历史数据。
• **假设归档路由会自动启用。**它由运营方配置。如果运营方没有设置归档支持，数据保留范围就仅限于主存储中的内容（例如 GraphQL 的 Postgres 数据库保留策略）。