accessing-data

Sui のデータへのアクセス

MCP ツール： 環境で利用できる場合は、最新の回答を得るために Sui のドキュメント MCP サーバー（https://sui.mcp.kapa.ai）にも問い合わせてください。検証や、これらのリファレンスファイルに記載されていない詳細の確認に使用してください。

「Sui からデータを読み取るにはどうすればよいですか？」は、エージェントが作成した Sui コードで最も頻繁に誤答される質問です。デフォルトの設定は変更されています。このスキルで正しい方法を確認できます。

重要な事実：JSON-RPC は非推奨です。 Sui Foundation のメインネットフルノードでは、2026 年 7 月 27 日の週に JSON-RPC が無効化され、コード全体の廃止は 2026 年 10 月中旬までに完了する予定です。新しいコードでは gRPC または GraphQL RPC を使用する必要があります。SuiJsonRpcClient は移行用の非推奨 API として引き続き存在しますが、新しいプロジェクトでは使用しないでください。

標準的なデータアクセス手段は次の 4 つです。

1. gRPC（一般提供）— 低レイテンシでリアルタイム性があり、コード生成に適しています。フルノードから提供されます。ストリーミングとサブスクリプションに対応しています。トランザクションの送信、ライブデータの読み取り、取り込みパイプラインにおけるデフォルトの選択肢です。
2. GraphQL RPC（一般提供）— General-Purpose Indexer の 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 読み込むタイミング： 柔軟で構成可能なクエリが必要なアプリの場合。たとえば、オブジェクトデータ、所有者のメタデータ、イベント履歴を 1 回のリクエストで結合するフロントエンド、GraphQL 経由のトランザクション送信やドライラン、フィルターを使った履歴クエリなどです。 内容： GraphQL のエンドポイント URL、General-Purpose Indexer および 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 の場合、クライアントは別途 Archival Service のエンドポイントが必要です。 内容： アーカイブストアが保持するデータ、プルーニングが存在する理由、GraphQL RPC がアーカイブへ透過的にルーティングする方法（オペレーターによる設定）、gRPC クライアントに別途 Archival Service のエンドポイントが必要な理由、ユースケース（コンプライアンス、紛争解決、長期的な分析）について説明します。

walrus — オフチェーンの blob ストレージ

パス： walrus.md 次の場合に読み込みます： ユーザーがファイル（画像、音声、モデル、ドキュメント、大きな JSON、動画）を「Sui 上」に保存したい場合、または 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 スキルも参照）
カスタムの分析／エクスプローラーのパイプライン構築	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 を使用してください。SuiJsonRpcClient は、移行までの暫定手段として、非推奨ながら SDK に残っています。
• gRPC はパフォーマンスを重視する場合の標準です（GA）。 型付き protobuf、ストリーミング、低レイテンシー、複数言語に対応したクライアントコード生成（TS、Rust、Go、Python など）を利用できます。フルノードから直接提供されます。バックエンド、インデクサー、型付きシステム言語で構築されたアプリに最適です。
• GraphQL RPC は柔軟性を重視する場合の標準です（GA）。 General-Purpose Indexer の Postgres、フルノード、Archival Store からデータを読み取ります。トランザクションの送信とドライランにも対応しています。1 つのリクエストで複数のエンティティ型を扱えます。フロントエンド、ツール、動的言語で構築されたアプリに最適です。
• アーカイブへのルーティングは、オペレーターが設定します。 オペレーターがアーカイブバックエンドを設定している場合、GraphQL RPC は対応する過去データの個別検索を透過的に Archival Store へルーティングできます。gRPC はアーカイブへ暗黙的にフォールバックしません。フルノードの保持期間を超える過去データを取得するには、gRPC クライアントが Archival Service エンドポイントを直接クエリする必要があります。アーカイブが設定されていない場合、データ保持期間はプライマリストアが保持する範囲に限られます。
• ホスト型 API ではあらゆるクエリ形式に対応できないため、カスタムインデクサーが存在します。 アプリ固有のインデックスを使って、数百万行に対するフィルタリングとソートを行う必要がある場合は、独自の sui-indexer-alt パイプラインを実行してください。カスタムインデクサーは、フレームワークの Store および Connection トレイトを実装することで、任意のストレージレイヤーに書き込めます。Postgres はデフォルトですが、必須ではありません。
• オンチェーンストレージは汎用のバイナリデータストレージではありません。 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）**されています。これらのいずれかを推奨する場合、特にアーカイブや履歴に関する質問に答える場合は、一般提供されていることを明示してください。ベータ版や実験的なものと呼ばないでください。
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 の下にあるクエリは、インデックス処理を待たず、実行またはシミュレーションされたトランザクションの直後の特別なスコープで評価されます。これにより、インデックス化された履歴を必要としないフィールド（例：実行結果、ガス、オブジェクトの変更）について、書き込み後の読み取り整合性が得られます。別途インデックス化されたクエリを実行するのではなく、同じ 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を使います。
• どのAPIかを指定せずに「Sui API」を勧める。「Sui API」という表現は、用途の異なるインターフェースを混同させます。必ずgRPCかGraphQLかを明示してください。
• gRPCの1つのメソッドで済む単純なクエリに対して「インデクサーを使って」と勧める。ホステッドAPIでは対応できなくなった場合にのみ、カスタムインデクサーを検討してください。
• 画像や大きなJSONを「Sui上」に保存する。Suiのオブジェクトサイズ上限は250 KBであり、料金体系を考慮すると、これは適切ではありません。Walrusを使ってください。
• gRPCとGraphQLが同じ形式を返すと思い込む。gRPCはprotobuf、GraphQLは型付きGraphQLです。レスポンスの形式、フィールド名、ページネーションはそれぞれ異なります。
• イベントをポーリングする。代わりにgRPCのストリーミング／サブスクリプションを使ってください。ポーリングはコストとレイテンシーが高くなります。
• RPCノードから読み込み、別のRPCノードに書き込んで、読み取り後の一貫性が得られると期待する。フルノード間では、ネットワーク全体で結果整合性が保たれます。GraphQLの場合は、同じexecuteTransactionミューテーションでフィールドを選択する方法を優先してください（実行時に紐づいたスコープにより、インデックス作成なしで一貫した結果が得られます）。gRPCの場合は、書き込みに使用したのと同じノードから読み取るか、ノードをまたいで読み取る前にwaitForTransactionを実行してください。
• 「ストレージファンド」と「ストレージサービス」を混同する。ストレージファンドはトークノミクスの仕組みです。呼び出すAPIではありません。
• gRPCがアーカイブに透過的にルーティングすると考える。対応する過去データの検索をアーカイブストアに透過的にルーティングするのは、GraphQL RPCのみです（オペレーターが設定している場合）。gRPCの場合、フルノードの保持期間を超える過去データを取得するには、クライアントがアーカイブサービスのエンドポイントに直接クエリを送る必要があります。
• アーカイブへのルーティングが自動だと思い込む。これはオペレーターによる設定が必要です。オペレーターがアーカイブのバックエンドを設定していない場合、保持期間はプライマリストアが保持するデータに限られます（例：GraphQLにおけるPostgresデータベースの保持ポリシー）。