Back to Details

accessing-data

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Accessing Data on Sui

在Sui上访问数据

MCP tool: When available in your environment, also query the Sui documentation MCP server (
https://sui.mcp.kapa.ai
) for up-to-date answers. Use it for verification and for details not covered by these reference files.
"How do I read data from Sui?" is the most frequently mis-answered question in agent-written Sui code. The defaults have changed. This skill fixes it.
Key fact: JSON-RPC is deprecated. From the official docs:
JSON-RPC is deprecated. Migrate to either gRPC or GraphQL RPC by July 2026.
Any code — or tutorial — that uses JSON-RPC for new reads is wrong for mainnet past mid-2026.
The four canonical data surfaces are:
  1. gRPC — low-latency, real-time, code-gen-friendly. Served by full nodes. Supports streaming/subscriptions. The default for transaction submission, live reads, and ingestion pipelines.
  2. GraphQL RPC — flexible relational queries over the General-Purpose Indexer's Postgres + full node + Archival Store. Supports reads, transaction submission, and dry-run. Best for frontends, dashboards, wallets, and any client that benefits from composable queries.
  3. Archival Store — long-term historical storage of transactions, checkpoints, and object states beyond full-node pruning. Accessed via GraphQL RPC (which routes to archival automatically for pruned data). Full nodes serving gRPC do not implicitly fall back to archival — if you need high-retention historical data over gRPC, you must query the archival service directly at its own URL.
  4. Custom indexer (
    sui-indexer-alt
    )     — build your own data pipeline keyed on exactly the on-chain data your app needs. Writes to any storage layer (Postgres by default, but any backend works). Ingests checkpoints from GCS (backfill) + full node gRPC (steady state).
Off-chain blob data (images, audio, models, large JSON) belongs on Walrus, not on-chain. Sui stores blob metadata; the blobs themselves sit on Walrus storage nodes.
All patterns in this skill are derived from:
If unsure about an API, fetch from the relevant page before answering. Do not guess from Ethereum/Solana analogs — Sui's data surfaces are distinct.
MCP工具： 如果你的环境中可用，也可以查询Sui文档MCP服务器（
https://sui.mcp.kapa.ai
）获取最新答案。用它来验证信息，以及获取这些参考文件未涵盖的细节。
“如何从Sui读取数据？”是Agent编写Sui代码时最常被错误回答的问题。默认方案已经变更，本技能将纠正这一问题。
关键事实：JSON-RPC已被弃用。 官方文档说明：
JSON-RPC已被弃用。请在2026年7月前迁移至gRPC或GraphQL RPC。
任何使用JSON-RPC进行新读取操作的代码或教程，对于2026年年中之后的主网来说都是错误的。
四种标准数据访问方式如下：
  1. gRPC —— 低延迟、实时、便于代码生成。由全节点提供服务。支持流式传输/订阅。是交易提交、实时读取和数据摄入管道的默认选择。
  2. GraphQL RPC —— 通过通用索引器的Postgres + 全节点 + 归档存储，支持灵活的关系型查询。支持读取、交易提交和试运行。最适合前端、仪表盘、钱包，以及任何可从组合式查询中获益的客户端。
  3. 归档存储（Archival Store） —— 长期存储全节点已清理的交易、检查点和对象状态。可通过GraphQL RPC访问（对于已清理的数据，GraphQL RPC会自动路由到归档存储）。提供gRPC服务的全节点不会自动回退到归档存储——如果需要通过gRPC访问高保留期的历史数据，你必须直接通过归档服务的专属URL进行查询。
  4. 自定义索引器（
    sui-indexer-alt
    ）     —— 构建完全符合你的应用所需链上数据的专属数据管道。可写入任何存储层（默认是Postgres，但支持任何后端）。从GCS（回填）和全节点gRPC（稳态）摄入检查点。
离线blob数据（图片、音频、模型、大型JSON）应存储在Walrus上，而非链上。Sui存储blob元数据，blob本身存储在Walrus存储节点上。
本技能中的所有模式均源自：
如果对某个API不确定，请先从相关页面获取信息再作答。不要根据Ethereum/Solana的类似机制猜测——Sui的数据访问方式是独特的。

Reference files

参考文件

grpc — gRPC API

grpc —— gRPC API

Path: 
grpc.md
Load when: writing backend services, indexers, exchanges, market makers, real-time clients, or any high-throughput read path. Also when subscribing to effects streams or doing dry runs / transaction simulation. Covers: service surface (
ledger_service
, 
transaction_execution_service
, 
move_package_service
, 
name_service
, 
subscription_service
), endpoint URLs per network, the TypeScript (
SuiGrpcClient
) and Rust (
sui-rpc
crate) clients, streaming vs request-response, code-gen for arbitrary languages.
路径： 
grpc.md
加载时机： 编写后端服务、索引器、交易所、做市商、实时客户端，或任何高吞吐量读取路径时。也适用于订阅效果流、进行试运行/交易模拟的场景。 涵盖内容： 服务范围（
ledger_service
、
transaction_execution_service
、
move_package_service
、
name_service
、
subscription_service
）、各网络的端点URL、TypeScript（
SuiGrpcClient
）和Rust（
sui-rpc
crate）客户端、流式传输vs请求-响应、任意语言的代码生成。

graphql — GraphQL RPC

graphql —— GraphQL RPC

Path: 
graphql.md
Load when: the app needs flexible, composable queries — e.g., a frontend that joins object data with owner metadata and event history in a single request, transaction submission or dry-run via GraphQL, or historical queries with filters. Covers: GraphQL endpoint URLs, relationship to the General-Purpose Indexer + Archival Store, 
SuiGraphQLClient
usage, typical query shapes, pagination patterns, rate limits, transaction execution and simulation via GraphQL, execution-attached read-after-write consistency.
路径： 
graphql.md
加载时机： 应用需要灵活的组合式查询时——例如，前端在单个请求中关联对象数据、所有者元数据和事件历史；通过GraphQL提交交易或进行试运行；带过滤条件的历史查询。 涵盖内容： GraphQL端点URL、与通用索引器+归档存储的关系、
SuiGraphQLClient
的使用、典型查询结构、分页模式、速率限制、通过GraphQL执行和模拟交易、执行附加的写后读一致性。

indexers — Custom indexing (
sui-indexer-alt
)

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

Path: 
indexers.md
Load when: a user asks "how do I track X event across history?", "how do I build an explorer / leaderboard / analytics pipeline?", or when a GraphQL or gRPC query is too slow / not filterable the way they need. Covers: the checkpoint-streaming pipeline model, backfill (GCS buckets like 
gs://mysten-mainnet-checkpoints-use4
) vs steady-state (full node gRPC), writing a pipeline config (
events.toml
, 
obj_versions.toml
patterns), concurrency tuning, and when to run the General-Purpose Indexer vs a custom one.
路径： 
indexers.md
加载时机： 用户询问“如何跟踪历史中的X事件？”、“如何构建浏览器/排行榜/分析管道？”，或者GraphQL或gRPC查询太慢/无法按需求过滤时。 涵盖内容： 检查点流式管道模型、回填（如
gs://mysten-mainnet-checkpoints-use4
等GCS存储桶）vs稳态（全节点gRPC）、编写管道配置（
events.toml
、
obj_versions.toml
模式）、并发调优，以及何时运行通用索引器vs自定义索引器。

archival — Archival Store

archival —— 归档存储

Path: 
archival.md
Load when: the data you need has been pruned from full nodes — old transactions, old object versions, old checkpoints. GraphQL can route to archival when operator-configured; gRPC does not — you must query the Archival Service directly. Covers: what the Archival Store retains, why pruning exists, how GraphQL routes to archival (operator-configured), Archival Service gRPC endpoint URLs, direct archival access for gRPC users, use cases (compliance, dispute resolution, long-range analytics).
路径： 
archival.md
加载时机： 你需要的数据已被全节点清理——旧交易、旧对象版本、旧检查点。当运营商配置后，GraphQL可以路由到归档存储；gRPC则不行——你必须直接查询归档服务。 涵盖内容： 归档存储保留的内容、清理机制存在的原因、GraphQL如何路由到归档存储（运营商配置）、归档服务gRPC端点URL、gRPC用户的直接归档访问、用例（合规、争议解决、长期分析）。

walrus — Off-chain blob storage

walrus —— 离线blob存储

Path: 
walrus.md
Load when: the user wants to store a file (image, audio, model, document, large JSON, video) "on Sui" or is trying to put megabytes of data into a Move object. Route them to Walrus. Covers: why you don't put blobs on-chain (250 KB per-object cap, storage-fund economics), the Walrus model (erasure-coded blobs stored off-chain with on-chain availability certificates), blob lifecycle, and the 
@mysten/walrus
client extension.
路径： 
walrus.md
加载时机： 用户想要“在Sui上”存储文件（图片、音频、模型、文档、大型JSON、视频），或试图将数MB的数据放入Move对象时。引导他们使用Walrus。 涵盖内容： 为何不将blob存储在链上（每个对象250KB上限、存储基金经济模型）、Walrus模型（离线存储纠删码blob，链上存储可用性证书）、blob生命周期，以及
@mysten/walrus
客户端扩展。

use-cases — Use case → method mapping

use-cases —— 用例→方法映射

Path: 
use-cases.md
Load when: the user describes what they want to do and you need to pick the right surface. This is the first file to load for an unfamiliar data access request. Covers: table of common use cases (balance lookup, owned-object list, event subscription, historical point-in-time read, analytics dashboard, cross-table joins, blob storage) mapped to the right API with rationale.
路径： 
use-cases.md
加载时机： 用户描述他们想要实现的操作，而你需要选择合适的访问方式时。对于不熟悉的数据访问请求，这是首先要加载的文件。 涵盖内容： 常见用例表（余额查询、自有对象列表、事件订阅、历史时间点读取、分析仪表盘、跨表关联、blob存储），并映射到合适的API及理由。

Routing guide

路由指南

TaskLoad
"How do I read X from Sui?" (first-pass question)use-cases
Writing a backend/indexer read pathgrpc + indexers
Writing a frontend data querygraphql (+ frontend-apps skill for hook patterns)
Building a custom analytics / explorer pipelineindexers
Looking up data older than full-node retentionarchival + graphql
Storing / retrieving a large filewalrus
Migrating an existing JSON-RPC appuse-cases + grpc + graphql
Designing a new app from scratchuse-cases (then grpc or graphql based on client type)
Full code review of a data-heavy appall reference files
任务加载文件
“如何从Sui读取X数据？”（首次提问）use-cases
编写后端/索引器读取路径grpc + indexers
编写前端数据查询graphql（+ frontend-apps技能获取钩子模式）
构建自定义分析/浏览器管道indexers
查询早于全节点保留期的数据archival + graphql
存储/检索大文件walrus
迁移现有JSON-RPC应用use-cases + grpc + graphql
从零开始设计新应用use-cases（然后根据客户端类型选择grpc或graphql）
对数据密集型应用进行全面代码审查所有参考文件

Skill Content

技能内容

Key concepts

关键概念

  • JSON-RPC is deprecated. Full deactivation targeted for July 2026. Any new code must default to gRPC or GraphQL RPC. Existing JSON-RPC code must be migrated.
  • gRPC is the performance default. Typed protobuf, streaming, low latency, polyglot client code gen (TS, Rust, Go, Python, etc.). Served directly by full nodes. Best for backends, indexers, and apps built in typed systems languages.
  • GraphQL RPC is the flexibility default. Generally available. Reads from the General-Purpose Indexer's Postgres + full node + Archival Store. Also supports transaction submission and dry-run. One request can span multiple entity types. Best for frontends, tools, and apps built in dynamic languages.
  • Archival routing is operator-configured. GraphQL RPC can route supported historical point lookups to Archival when the GraphQL operator configures it. Full nodes serving gRPC do not fall back to archival — if you need historical data over gRPC, query the Archival Service endpoint directly (e.g., 
    archive.mainnet.sui.io:443
    ).
  • Custom indexers exist because no hosted API fits every query shape. If you need filtered sorts over millions of rows with app-specific indexes, run your own 
    sui-indexer-alt
    pipeline. Custom indexers can write to any storage layer by implementing the framework's 
    Store
    and 
    Connection
    traits — Postgres is the default, not a requirement.
  • On-chain storage is not general-purpose blob storage. Max Move object size is 250 KB. Storage is paid once (storage fund redistributes returns to validators). Big files go to Walrus.
  • The storage fund does not "hold your data." It's an economic mechanism: a fraction of each write fee goes in; validators earn yield that pays for ongoing storage. It affects pricing, not where you store.
  • JSON-RPC已被弃用。 全面停用时间定为2026年7月。任何新代码必须默认使用gRPC或GraphQL RPC。现有JSON-RPC代码必须迁移。
  • gRPC是性能优先的默认选择。 类型化protobuf、流式传输、低延迟、多语言客户端代码生成（TS、Rust、Go、Python等）。由全节点直接提供服务。最适合后端、索引器，以及用类型化系统语言构建的应用。
  • GraphQL RPC是灵活性优先的默认选择。 全面可用。从通用索引器的Postgres + 全节点 + 归档存储读取数据。也支持交易提交和试运行。单个请求可覆盖多种实体类型。最适合前端、工具，以及用动态语言构建的应用。
  • 归档路由由运营商配置。 当GraphQL运营商配置后，GraphQL RPC可将支持的历史点查询路由到归档存储。提供gRPC服务的全节点不会回退到归档存储——如果需要通过gRPC访问历史数据，请直接查询归档服务端点（例如
    archive.mainnet.sui.io:443
    ）。
  • 自定义索引器的存在是因为没有托管API能适配所有查询结构。 如果你需要对数百万行数据进行带应用特定索引的过滤排序，请运行自己的
    sui-indexer-alt
    管道。自定义索引器可通过实现框架的
    Store
    和
    Connection
    trait写入任何存储层——Postgres是默认选择，但并非必须。
  • 链上存储不是通用blob存储。 Move对象最大大小为250KB。存储费用一次性支付（存储基金将收益重新分配给验证者）。大文件应存储在Walrus。
  • 存储基金并非“保存你的数据”。 它是一种经济机制：每笔写入费用的一部分存入基金；验证者获得收益以支付持续存储成本。它影响定价，而非存储位置。

Rules

规则

  1. Absolutely no JSON-RPC for new code. If a tutorial says 
    new SuiClient({ url: getFullnodeUrl(...) })
    , replace with 
    new SuiGrpcClient({ network, baseUrl })
    . If a user insists on JSON-RPC, name the deprecation + July 2026 sunset and offer 
    SuiJsonRpcClient
    only as a migration stopgap.
  2. Choose your initial API based on what you're building. Front-ends, tools, and apps in dynamic languages → start with GraphQL RPC (superset of gRPC functionality, composable queries, archival routing). Backends, indexers, and apps in typed systems languages → start with gRPC (performance, streaming, code-gen). Only switch if you hit a limitation. Current temporary caveats (will be resolved in the coming months): only gRPC supports subscriptions; only GraphQL supports filtered pagination over historical transactions and events.
  3. Archival routing differs by API. GraphQL RPC routes supported historical point lookups to archival when the operator configures it. gRPC does not — if you need high-retention historical access via gRPC, query the Archival Service directly at its own URL (e.g., 
    archive.mainnet.sui.io:443
    ).
  4. Build a custom indexer only when hosted APIs don't fit. Operating an indexer is ongoing work — Postgres, checkpoint ingestion, failure handling. Evaluate GraphQL RPC first.
  5. Put large files on Walrus. Never advise embedding images/audio/video in Move objects or in transaction inputs. If the user is trying to, route them to the 
    walrus
    reference file.
  6. Map use case → method correctly. See 
    use-cases.md
    :
    • Live balance / owned-object / coin list → gRPC 
      client.core.*
      .
    • Flexible multi-entity query for a frontend → GraphQL RPC.
    • Historical transaction > N days old → GraphQL RPC (routes through archival).
    • Custom leaderboard / analytics across all events → custom indexer.
    • Transaction subscription / real-time effects feed → gRPC streaming.
    • Large files → Walrus.
  7. Read-after-write consistency varies by API. For GraphQL RPC, queries nested under 
    executeTransaction
    or 
    simulateTransaction
    are evaluated in a special scope just after the executed/simulated transaction, without waiting for indexing. This provides consistent read-after-write for fields that don't require indexed history (e.g., effects, gas, object changes). Prefer selecting these fields in the same GraphQL request rather than making a separate indexed follow-up query. For gRPC, call 
    client.waitForTransaction({ digest })
    before the follow-up read. In both cases, cross-node reads after a write are not guaranteed immediately visible.
  8. Cite docs when unsure. All sources listed above.
  1. 新代码绝对禁止使用JSON-RPC。 如果教程中出现
    new SuiClient({ url: getFullnodeUrl(...) })
    ，请替换为
    new SuiGrpcClient({ network, baseUrl })
    。如果用户坚持使用JSON-RPC，请告知其弃用情况及2026年7月的停用时间，仅将
    SuiJsonRpcClient
    作为迁移过渡方案提供。
  2. 根据构建的应用选择初始API。 前端、工具和用动态语言构建的应用→从GraphQL RPC开始（gRPC功能的超集，组合式查询，归档路由）。后端、索引器和用类型化系统语言构建的应用→从gRPC开始（性能、流式传输、代码生成）。仅在遇到限制时才切换。当前临时限制（未来几个月内将解决）：只有gRPC支持订阅；只有GraphQL支持对历史交易和事件进行过滤分页。
  3. 不同API的归档路由方式不同。 当运营商配置后，GraphQL RPC可将支持的历史点查询路由到归档存储。gRPC则不行——如果需要通过gRPC访问高保留期的历史数据，请直接查询归档服务的专属URL（例如
    archive.mainnet.sui.io:443
    ）。
  4. 仅当托管API无法满足需求时才构建自定义索引器。 运行索引器是一项持续性工作——涉及Postgres、检查点摄入、故障处理。请先评估GraphQL RPC。
  5. 大文件存储在Walrus。 绝不建议将图片/音频/视频嵌入Move对象或交易输入中。如果用户尝试这样做，请引导他们查看
    walrus
    参考文件。
  6. 正确映射用例→方法。 参见
    use-cases.md
    ：
    • 实时余额/自有对象/代币列表→gRPC 
      client.core.*
      。
    • 前端的灵活多实体查询→GraphQL RPC。
    • 早于N天的历史交易→GraphQL RPC（通过归档路由）。
    • 跨所有事件的自定义排行榜/分析→自定义索引器。
    • 交易订阅/实时效果流→gRPC流式传输。
    • 大文件→Walrus。
  7. 不同API的写后读一致性不同。 对于GraphQL RPC，嵌套在
    executeTransaction
    或
    simulateTransaction
    下的查询会在执行/模拟交易后的特殊范围内进行评估，无需等待索引完成。这为不需要索引历史记录的字段（例如效果、gas、对象变更）提供一致的写后读。建议在同一个GraphQL请求中选择这些字段，而非单独发起索引后的后续查询。对于gRPC，在后续读取前调用
    client.waitForTransaction({ digest })
    。在两种情况下，写入后跨节点读取无法保证立即可见。
  8. 不确定时引用文档。 参考上述列出的所有来源。

Common mistakes

常见错误

  • Using 
    client.getObject
    / 
    client.getOwnedObjects
    / 
    client.getCoins
     — these are v1 JSON-RPC method names. v2 is 
    client.core.getObject
    / 
    client.core.listOwnedObjects
    / 
    client.core.listCoins
    on any of the v2 clients.
  • Recommending "the Sui API" without specifying which. "The Sui API" conflates three different interfaces with different use cases. Always name gRPC / GraphQL / JSON-RPC.
  • Telling users to "use the indexer" for a simple query that gRPC covers in one method. Only reach for a custom indexer when you've outgrown the hosted APIs.
  • Storing images or large JSON "on Sui." Sui's 250 KB object size limit and pricing model make this wrong. Use Walrus.
  • Assuming all three APIs return the same shape. gRPC is protobuf; GraphQL is typed GraphQL; JSON-RPC is JSON with v1-specific nesting. Response shapes differ; field names differ; pagination differs.
  • Polling for events via JSON-RPC. Use gRPC streaming / subscriptions instead. Polling is high-cost and high-latency.
  • Reading from an RPC node and writing to a different one expecting read-after-write consistency. Fullnodes are eventually consistent across the network. For GraphQL, prefer selecting fields in the same 
    executeTransaction
    mutation (execution-attached scope gives consistent results without indexing). For gRPC, read from the same node you wrote to, or 
    waitForTransaction
    before cross-node reads.
  • Conflating "storage fund" with "storage service." The storage fund is a tokenomics mechanism. It is not an API you call.
  • Assuming gRPC falls back to archival for pruned data. It does not. GraphQL can route to archival when the operator configures it. For gRPC clients needing historical data, query the Archival Service directly (e.g., 
    archive.mainnet.sui.io:443
    ).
  • Assuming GraphQL archival routing is automatic. It's operator-configured. If the GraphQL operator hasn't paired the service with an Archival Service backend, retention is limited to the Postgres database's retention policy.
  • 使用
    client.getObject
    / 
    client.getOwnedObjects
    / 
    client.getCoins
    ——这些是v1 JSON-RPC方法名。v2版本在任何v2客户端上对应的是
    client.core.getObject
    / 
    client.core.listOwnedObjects
    / 
    client.core.listCoins
    。
  • 推荐“the Sui API”而不指定具体类型。“Sui API”混淆了三个具有不同用例的不同接口。务必明确说明是gRPC / GraphQL / JSON-RPC。
  • 告诉用户“使用索引器”来处理gRPC可通过单个方法完成的简单查询。 只有在托管API无法满足需求时才使用自定义索引器。
  • 将图片或大型JSON“存储在Sui上”。 Sui的250KB对象大小限制和定价模型决定了这种做法是错误的。请使用Walrus。
  • 假设三个API返回相同的数据结构。 gRPC是protobuf格式；GraphQL是类型化GraphQL格式；JSON-RPC是带有v1特定嵌套的JSON格式。响应结构、字段名称、分页方式均不同。
  • 通过JSON-RPC轮询事件。 请改用gRPC流式传输/订阅。轮询成本高且延迟大。
  • 从一个RPC节点读取并写入另一个节点，期望实现写后读一致性。 全节点在网络中最终一致。对于GraphQL，建议在同一个
    executeTransaction
    变更请求中选择字段（执行附加范围无需索引即可提供一致结果）。对于gRPC，从写入的同一节点读取，或在跨节点读取前调用
    waitForTransaction
    。
  • 混淆“存储基金”和“存储服务”。 存储基金是一种通证经济机制，并非可调用的API。
  • 假设gRPC会为已清理的数据回退到归档存储。 事实并非如此。当运营商配置后，GraphQL可路由到归档存储。对于需要历史数据的gRPC客户端，请直接查询归档服务（例如
    archive.mainnet.sui.io:443
    ）。
  • 假设GraphQL归档路由是自动的。 它由运营商配置。如果GraphQL运营商未将服务与归档服务后端配对，保留期将受限于Postgres数据库的保留策略。