GraphQL and General-Purpose Indexer

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

Storage requirements

The general-purpose indexer writes to a Postgres database. The storage footprint estimations outlined below are based on the network as of early 2026, and may fluctuate in relation to network growth. These numbers should be seen as directional rather than exact figures.

The bulk of the storage is consumed by obj_versions at 8.2 TB. A pruning strategy is in development.

A 30-day retention adds 1.8 TB on top, while a 90-day retention contributes up to an additional 3.1 TB.

30-day retention:

90-day retention:

Run sui-indexer-alt

Run an indexer instance using this command for each of the configuration files. The command varies based on whether the pipeline is prunable or unprunable:

For unprunable pipelines (must start from genesis)

$ sui-indexer-alt indexer \
    --config <CONFIG_FILE> \
    --database-url <DATABASE_URL> \
    --remote-store-url <REMOTE_STORE_URL>

For prunable pipelines with retention period

$ sui-indexer-alt indexer \
    --config <CONFIG_FILE> \
    --database-url <DATABASE_URL> \
    --remote-store-url <REMOTE_STORE_URL> \
    --first-checkpoint <CHECKPOINT_NUMBER>

For prunable pipelines, calculate the first-checkpoint based on your retention period:

• 30-day retention: Start from checkpoint current_checkpoint - 10368000
• 90-day retention: Start from checkpoint current_checkpoint - 31104000

Examples

Unprunable pipeline (from genesis):

$ sui-indexer-alt indexer \
    --config unpruned.toml \
    --database-url postgres://username:password@localhost:5432/database \
    --remote-store-url https://checkpoints.mainnet.sui.io

Prunable pipeline with 30-day retention (assuming current checkpoint is 100,000,000):

$ sui-indexer-alt indexer \
    --config events.toml \
    --database-url postgres://username:password@localhost:5432/database \
    --remote-store-url https://checkpoints.mainnet.sui.io \
    --first-checkpoint 89632000

Run config recommendations {#indexer-run-config}

Use the TOML files below; they 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.

:::info When backfilling, you should set the ingest-concurrency to a higher value, e.g. 200, then reduce it to 20 for normal operation at network tip. :::

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>

* 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>

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

GraphQL RPC server setup

GraphQL RPC server reads data from the general-purpose indexer's database (Postgres), the consistent store, and the archival service.

• Ensure that all unprunable indexer pipelines (obj_versions.toml and unpruned.toml) have fully caught up to the network tip before starting the GraphQL RPC server. The GraphQL service will only operate normally once these pipelines are complete.

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

:::info

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.

Example:

sui-indexer-alt-graphql rpc \
    --config graphql.toml \
    --indexer-config events.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 \
    --indexer-config unpruned.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:

Indexer/GraphQL Postgres-compatible Database Setup

Both the indexer and GraphQL server require a Postgres-compatible database shared between them.

These GraphQL request throughputs were tested against the following recommended specs:

• 500 requests per second when the indexer is backfilling from genesis or running a restore
• 1000 requests per second when the indexer is indexing from the network tip (~4.25 checkpoints per second)

AlloyDB Omni

AlloyDB Omni recommends 8GB RAM per vCPU link. Allocating less than this results in the database closing Indexer and GraphQL connections during load testing.

Hardware requirements

• CPU: 6 cores
• Memory: 48GB

Vanilla Postgres

Hardware requirements

• CPU: 6 cores
• Memory: 48GB

Adding a new pipeline

Adding a new pipeline to an existing indexer currently requires these steps:

1. We recommend starting a new pipeline in its own indexer instance, optionally with the --first-checkpoint <checkpoint> flag set if you want to start from a checkpoint after genesis.
   • Note: --first-checkpoint is only respected if no watermark record exists for the pipeline(s) (the pipeline has not been run before). The watermark record must be manually removed if you want to run the pipeline with a different value of --first-checkpoint or it will be ignored.
2. After the new pipeline has caught up to the tip of the network, you can optionally merge it into another indexer instance.

Reducing indexer pipeline table and index bloat

Bloat is the difference between the size of the data in the table or index and the amount of space it takes up on disk. Autovacuum prevents bloat if approximately the same number of rows is continually inserted and deleted like the case when pipeline pruning is enabled. However, autovacuum will not handle more rows being deleted than inserted. There are two cases where this can occur:

• Enabling pruning on an unpruned pipeline.
• Reducing the pruning retention period on a pruned table.

These tools can be used to reduce bloat: