GraphQL and General-Purpose Indexer
The GraphQL and sui-indexer-alt (Indexer) stack are part of the Sui data access infrastructure. The stack provides access to on-chain data through a high-performance GraphQL service backed by a scalable and general-purpose indexer. This stack is optimized for developers who need flexible queries, structured output, and historical access to data (with configurable retention) across the Sui network.
GraphQL is ideal for applications that require rich query patterns over structured data, such as fetching owned objects, transaction history, specific onchain attributes, and more. The GraphQL service runs on top of a Postgres-compatible database that is updated by different Indexer pipelines in parallel.
The General-purpose Indexer includes configurable checkpoint-based pipelines that extract data from the Sui remote checkpoint store and full nodes. The pipelines write processed data to a database optimized for GraphQL query access.
Together, the GraphQL service and Indexer offer a modular and production-ready data stack for builders, wallet developers, explorers, and indexer/data providers.
JSON-RPC is deprecated. Migrate to either gRPC or GraphQL RPC by April 2026.
Refer to the list of RPC or data providers that have enabled gRPC on their full nodes or offer GraphQL RPC. Contact a provider directly to request access. If your RPC or data provider doesn’t yet support these data access methods, ask them to enable support or contact the Sui Foundation team on Discord, Telegram, or Slack for help.
Refer to Access Sui Data for an overview of options to access Sui network data.
See GraphQL and General-Purpose Indexer for more information on the stack.
Indexer setup
The indexer consists of multiple pipelines that each read, transform, and write checkpoint data to a table. Multiple instances of the indexer can run in parallel, each configured by its own TOML file.
Hardware requirements
- CPU: 2 cores per instance
- Memory: 4GB per instance
Run sui-indexer-alt
Run an indexer instance using this command for each of the configuration files that follow:
$ sui-indexer-alt indexer \
--config <CONFIG_FILE> \
--database-url <DATABASE_URL> \
--remote-store-url <REMOTE_STORE_URL>
| CLI param | Description |
|---|---|
<CONFIG_FILE> | Path to indexer configuration file. |
<DATABASE_URL> | Postgres database connection string. |
<REMOTE_STORE_URL> | URL of a checkpoint bucket to index from, one of multiple possible data sources. |
Example:
$ sui-indexer-alt indexer \
--config misc.toml \
--database-url postgres://username:password@localhost:5432/database \
--remote-store-url https://checkpoints.mainnet.sui.io
Run config recommendations
We recommend using the TOML files below which are grouped by pipeline speed. All pipelines in an instance are limited by the slowest pipeline in that instance so these files each contain pipelines that run at approximately the same speed.
| Config TOML | Description | Pipelines | Backfill time | Data retention |
|---|---|---|---|---|
events.toml | Lightweight event tables. |
| 1-2 days | 90 days |
Click to open
| ||||
misc.toml | Lightweight miscellaneous tables. |
| 2-4 days | 90 days |
Click to open
| ||||
obj_versions.toml | Heavyweight object versions table containing data since genesis. | obj_versions | 10-14 days | unpruned |
Click to open
| ||||
tx_affected_addresses.toml | Midweight transaction table. | tx_affected_addresses | 1-2 days | 90 days |
Click to open
| ||||
tx_affected_objects.toml | Midweight transaction table. | tx_affected_objects | 1-2 days | 90 days |
Click to open
| ||||
tx_calls.toml | Midweight transaction table. | tx_calls | 1-2 days | 90 days |
Click to open
| ||||
tx_kinds.toml | Midweight transaction table. | tx_kinds | 1-2 days | 90 days |
Click to open
| ||||
Consistent store setup
All consistent store pipelines run in the same instance based on a single configuration file. Like the indexer, the pipelines run in parallel and throughput is limited by the slowest pipeline.
Hardware requirements
- CPU: 8 cores
- Memory: 32GB
Restore command
Restores one or more pipelines from checkpoint data in a GCS bucket.
$ sui-indexer-alt-consistent-store restore \
--azure <AZURE_BUCKET> \
--database-path <DATABASE_PATH> \
--gcs <GCS_BUCKET> \
--http <HTTP_ENDPOINT> \
--object-file-concurrency <OBJECT_FILE_CONCURRENCY> \
--pipeline <PIPELINE_NAME> \
--remote-store-url <REMOTE_STORE_URL> \
--s3 <S3_BUCKET>
| CLI parameter | Description |
|---|---|
<AZURE_BUCKET> * | Name or URL of Azure bucket containing managed snapshots. |
<DATABASE_PATH> | Path to RocksDB database. |
<GCS_ACCOUNT> * | Name or URL of GCS bucket containing managed snapshots. |
<HTTP_ENDPOINT> * | URL of formal snapshot API. |
<OBJECT_FILE_CONCURRENCY> | Path to indexer configuration file. |
<PIPELINE_NAME> | Name of pipeline to restore. Can be set multiple times; once per pipeline. |
<REMOTE_STORE_URL> | URL of a checkpoint bucket to index from, one of multiple possible data sources. |
<S3_BUCKET> * | Name or URL of AWS S3 bucket containing managed snapshots. |
* Must specify one of <AZURE_BUCKET>, <GCS_ACCOUNT>, <HTTP_ENDPOINT>, or <S3_BUCKET>.
Example:
$ sui-indexer-alt-consistent-store restore \
--database-path /path/to/rocksdb \
--http https://formal-snapshot.mainnet.sui.io \
--object-file-concurrency 5 \
--pipeline balances \
--pipeline object_by_owner \
--pipeline object_by_type \
--remote-store-url https://checkpoints.mainnet.sui.io
Run command
Run a consistent store instance using this command for the configuration file that follows:
$ sui-indexer-alt-consistent-store run \
--config <CONFIG_FILE> \
--database-path <DATABASE_PATH> \
--remote-store-url <REMOTE_STORE_URL>
| CLI param | Description |
|---|---|
<CONFIG_FILE> | Path to consistent store configuration file. |
<DATABASE_PATH> | Path to RocksDB database. |
<REMOTE_STORE_URL> | URL of a checkpoint bucket to index from, one of multiple possible data sources. |
Example:
$ sui-indexer-alt-consistent-store run \
--config consistent-store.toml \
--database-path /path/to/rocksdb \
--remote-store-url https://checkpoints.mainnet.sui.io
Run config recommendations
| Config TOML | Description | Pipelines | Backfill time | Data retention |
|---|---|---|---|---|
consistent-store.toml | Consistent store API configuration and event tables. |
| 1-2 hours | Unpruned |
consistent-store.toml
examples/prod-config/consistent-store.toml. You probably need to run `pnpm prebuild` and restart the site.GraphQL RPC server setup
GraphQL RPC server reads data from the general-purpose indexer's database (Postgres), the consistent store, and the archival service.
Hardware requirements
- CPU: 2 cores per instance
- Memory: 4GB per instance
Scale the number of nodes based on the desired read throughput requirements of your client applications.
GraphQL RPC server dependencies
The GraphQL RPC server relies on multiple backend services to fulfill different types of queries:
- Archival service (
--ledger-grpc-url) provides historical data for most queries involving checkpoints, objects, and transactions. - Consistent store (
--consistent-store-url) serves live data for queries related to current object and balance ownership. - Postgres database (
--database-url) is the primary store for most queries, except for direct object and transaction lookups handled by the Archival service. - Fullnode RPC (
--fullnode-rpc-url) powers transaction simulation and execution.
Set the appropriate service URLs in your run command based on the query types your GraphQL RPC server needs to support.
Run sui-indexer-alt-graphql
If you use the Sui Foundation–hosted public good archival service on Testnet or Mainnet, you may encounter performance issues. The team will address these before the GraphQL RPC and Archival Service reach general availability.
Use the following command to run a GraphQL RPC server node:
sui-indexer-alt-graphql rpc \
--config <PATH_TO_GRAPHQL_CONFIG_FILE> \
--indexer-config <PATH_TO_INDEXER_CONFIG_FILE_1> \
--indexer-config <PATH_TO_INDEXER_CONFIG_FILE_2> \
--indexer-config <PATH_TO_INDEXER_CONFIG_FILE_3> \
--ledger-grpc-url <LEDGER_GRPC_URL> \
--consistent-store-url <CONSISTENT_STORE_URL> \
--database-url <DATABASE_URL> \
--fullnode-rpc-url <FULLNODE_RPC_URL>
Multiple --indexer-config parameters can be provided, one for each general-purpose indexer instance.
| CLI parameter | Description |
|---|---|
CONFIG_FILE | Path to the optional GraphQL RPC server configuration file |
INDEXER_CONFIG_FILE | Path to general-purpose indexer configuration file; can be set multiple times for different pipelines |
LEDGER_GRPC_URL | URL to Archival service's LedgerService gRPC API |
CONSISTENT_STORE_URL | URL to Consistent store API |
DATABASE_URL | Postgres database connection string |
FULLNODE_RPC_URL | URL to full node RPC |
Example:
sui-indexer-alt-graphql rpc \
--config graphql.toml \
--indexer-config events.toml \
--indexer-config misc.toml \
--indexer-config obj_versions.toml \
--indexer-config tx_affected_addresses.toml \
--indexer-config tx_affected_objects.toml \
--indexer-config tx_calls.toml \
--indexer-config tx_kinds.toml \
--ledger-grpc-url https://archive.mainnet.sui.io:443 \
--consistent-store-url https://localhost:7001 \
--database-url postgres://username:password@localhost:5432/database \
--fullnode-rpc-url https://localhost:9000
Generating Configuration
You can run the GraphQL RPC server without a configuration file, which will use default values. To customize settings, generate a config file using the command below and edit it as needed:
sui-indexer-alt-graphql generate-config > <PATH_TO_GRAPHQL_CONFIG_FILE>
It will produce output similar to the following:
graphql.toml
[limits]
mutation-timeout-ms = 74000
query-timeout-ms = 40000
max-query-depth = 20
max-query-nodes = 300
max-output-nodes = 1000000
max-tx-payload-size = 174763
max-query-payload-size = 5000
default-page-size = 20
max-page-size = 50
max-multi-get-size = 200
page-size-override-fx-object-changes = 1024
page-size-override-packages = 200
max-type-argument-depth = 16
max-type-argument-width = 32
max-type-nodes = 256
max-move-value-depth = 128
max-move-value-bound = 1048576
max-display-field-depth = 10
max-display-output-size = 1048576
max-disassembled-module-size = 1048576
[health]
max-checkpoint-lag-ms = 300000
[name-service]
package-address = "0xd22b24490e0bae52676651b4f56660a5ff8022a2576e0089f79b3c88d44e08f0"
registry-id = "0xe64cd9db9f829c6cc405d9790bd71567ae07259855f4fba6f02c84f52298c106"
reverse-registry-id = "0x2fd099e17a292d2bc541df474f9fafa595653848cbabb2d7a4656ec786a1969f"
[watermark]
watermark-polling-interval-ms = 500
[zklogin]
env = "Prod"
max-epoch-upper-bound-delta = 30
Related links
The GraphQL RPC Beta service offers a structured way for your clients to interact with data on the Sui blockchain. It accesses data processed by a general-purpose indexer and can connect to an archival store for historical network state.
Use GraphQL to make Sui RPC calls. This feature is currently in Beta.
The sui-indexer-alt-framework is a powerful Rust framework for building high-performance, custom blockchain indexers on Sui. It provides customizable, production-ready components for data ingestion, processing, and storage.
The sui-indexer-alt-framework provides two distinct pipeline architectures. Understand the differences between the sequential and concurrent pipelines that the sui-indexer-alt-framework provides to decide which best suits your project needs.
Overview of the Archival Store and Service to access historical Sui network data.
Establishing a custom indexer helps improve latency, allows pruning the data of your Sui full node, and provides efficient assemblage of checkpoint data.
The sui-indexer-alt crate in the Sui repo.
The indexer that the Move Registry (MVR) implements.
The indexer that DeepBook implements.
Schema documentation for GraphQL Beta