GraphQL 및 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 July 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.

The GraphQL RPC release stage is currently in beta. Refer to the high-level timeline for releases.

스택에 대한 자세한 내용은 GraphQL 및 General-purpose Indexer를 참조하라.

Indexer setup

Indexer는 각 pipeline이 checkpoint 데이터를 읽고, 변환하고, 테이블에 기록하는 여러 pipeline으로 구성된다. 여러 Indexer instance를 병렬로 실행할 수 있으며, 각 instance는 자체 TOML 파일로 구성된다.

Hardware requirements

CPU: instance당 2 cores
Memory: instance당 4GB

Storage requirements

General-purpose Indexer는 Postgres database에 기록한다. 아래 storage footprint 추정치는 2026년 초 기준 네트워크를 바탕으로 하며, 네트워크 성장에 따라 달라질 수 있다. 이 수치는 정확한 값이라기보다 방향성을 보여 주는 참고치로 봐야 한다.

스토리지의 대부분은 obj_versions가 차지하며, 크기는 8.2 TB이다. pruning 전략은 현재 개발 중이다.

30일 retention은 여기에 1.8 TB를 추가하고, 90일 retention은 최대 3.1 TB를 더한다.

30일 retention:

테이블	Heap (GB)	Idx (GB)
tx_affected_objects	64–70	276–397
tx_calls	27–30	239–366
ev_struct_inst	15–19	174–267
tx_affected_addresses	17–18	63–92
ev_emit_mod	8–9	54–85
tx_balance_changes	18–20	5–6
tx_digests	8	21–25
tx_kinds	5	14–16
cp_sequence_numbers	10	5
TOTAL	444–450	1,827–1,842

90일 retention:

테이블	Heap (GB)	Idx (GB)
tx_affected_objects	188–202	580–752
tx_calls	82–87	560–715
ev_struct_inst	45–50	432–531
tx_affected_addresses	50–54	151–183
ev_emit_mod	22–24	129–167
tx_balance_changes	57–63	10–16
tx_digests	24–26	45–55
tx_kinds	15–16	30–36
cp_sequence_numbers	10	5
TOTAL	755–842	2,440–3,181

Run `sui-indexer-alt`

각 구성 파일마다 아래 명령으로 Indexer instance를 실행하라. 명령은 pipeline이 prunable인지 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>

Prunable pipeline의 경우 retention 기간을 기준으로 first-checkpoint를 계산하라:

30-day retention: checkpoint current_checkpoint - 10368000부터 시작
90-day retention: checkpoint current_checkpoint - 31104000부터 시작

CLI param	설명
`<CONFIG_FILE>`	Indexer 구성 파일 경로이다.
`<DATABASE_URL>`	Postgres database connection string이다.
`<REMOTE_STORE_URL>`	indexing에 사용할 checkpoint bucket URL이다. 가능한 여러 data sources 중 하나를 사용한다.
`<CHECKPOINT_NUMBER>`	(선택 사항) Prunable pipeline에서만 사용한다. retention 요구 사항에 따라 indexing을 시작할 checkpoint이다.

Examples

Unprunable pipeline(Genesis부터):

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

30-day retention을 사용하는 Prunable pipeline(현재 checkpoint가 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

아래 TOML 파일을 사용하라. pipeline 속도별로 묶어 두었으며, 하나의 instance 안에서는 가장 느린 pipeline이 전체를 제한하므로 각 파일은 대략 비슷한 속도로 실행되는 pipeline만 담고 있다.

정보

백필 시에는 ingest-concurrency를 더 높은 값(예: 200)으로 설정하고, network tip에서 정상 운영할 때는 20으로 낮추는 것이 좋다.

Config TOML	유형	설명	Pipelines	Backfill 시간	데이터 retention	시작 checkpoint
`events.toml`	Prunable	경량 event 테이블.	`ev_emit_mod` `ev_struct_inst`	1-2일	구성 가능(예: 30일 또는 90일)	retention 기간 기준
Click to open `events.toml` examples/prod-config/indexer/events.toml `[pruner] retention = 31104000 [pipeline.ev_emit_mod.pruner] [pipeline.ev_struct_inst.pruner]`
`obj_versions.toml`	Unprunable	완전한 object version 대 checkpoint 매핑을 담는 object versions 테이블.	`obj_versions`	10-14일	모든 데이터를 유지해야 한다	제네시스(checkpoint 0)
Click to open `obj_versions.toml` examples/prod-config/indexer/obj_versions.toml `[ingestion] ingest-concurrency = 20 [committer] write-concurrency = 10 # obj_versions pipeline pruning not yet supported [pipeline.obj_versions]`
`tx_affected_addresses.toml`	Prunable	중간 규모 transaction 테이블.	`tx_affected_addresses`	1-2일	구성 가능(예: 30일 또는 90일)	retention 기간 기준
Click to open `tx_affected_addresses.toml` examples/prod-config/indexer/tx_affected_addresses.toml `[ingestion] ingest-concurrency = 20 [committer] write-concurrency = 10 [pruner] retention = 31104000 [pipeline.tx_affected_addresses.pruner]`
`tx_affected_objects.toml`	Prunable	중간 규모 transaction 테이블.	`tx_affected_objects`	1-2일	구성 가능(예: 30일 또는 90일)	retention 기간 기준
Click to open `tx_affected_objects.toml` examples/prod-config/indexer/tx_affected_objects.toml `[committer] write-concurrency = 20 [pruner] retention = 31104000 [pipeline.tx_affected_objects.pruner]`
`tx_calls.toml`	Prunable	중간 규모 transaction 테이블.	`tx_calls`	1-2일	구성 가능(예: 30일 또는 90일)	retention 기간 기준
Click to open `tx_calls.toml` examples/prod-config/indexer/tx_calls.toml `[committer] write-concurrency = 10 [pruner] retention = 31104000 [pipeline.tx_calls.pruner]`
`tx_kinds.toml`	Prunable	중간 규모 transaction 테이블.	`tx_kinds`	1-2일	구성 가능(예: 30일 또는 90일)	retention 기간 기준
Click to open `tx_kinds.toml` examples/prod-config/indexer/tx_kinds.toml `[pruner] retention = 31104000 [pipeline.tx_kinds.pruner]`
`unpruned.toml`	Unprunable	다른 query가 의존하는 기반 reference 데이터.	`cp_sequence_numbers` `kv_epoch_ends` `kv_epoch_starts` `kv_feature_flags` `kv_packages` `kv_protocol_configs` `sum_displays` `tx_balance_changes` `tx_digests`	2-4일	모든 데이터를 유지해야 한다	제네시스(checkpoint 0)
Click to open `unpruned.toml` examples/prod-config/indexer/unpruned.toml `[ingestion] ingest-concurrency = 20 [pipeline.cp_sequence_numbers] [pipeline.kv_epoch_ends] [pipeline.kv_epoch_starts] [pipeline.kv_feature_flags] [pipeline.kv_packages] [pipeline.kv_protocol_configs] [pipeline.sum_displays] [pipeline.tx_balance_changes] [pipeline.tx_digests]`

Consistent store setup

모든 Consistent Store pipeline은 하나의 구성 파일을 기반으로 동일한 instance에서 실행된다. Indexer와 마찬가지로 pipeline은 병렬로 실행되며, 처리량은 가장 느린 pipeline에 의해 제한된다.

Hardware requirements

CPU: 8 cores
Memory: 32GB

Restore command

GCS bucket의 checkpoint 데이터에서 하나 이상의 pipeline을 복원한다.

$ 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	설명
`<AZURE_BUCKET>` *	managed snapshots를 담고 있는 Azure bucket의 이름 또는 URL이다.
`<DATABASE_PATH>`	RocksDB database 경로이다.
`<GCS_ACCOUNT>` *	managed snapshots를 담고 있는 GCS bucket의 이름 또는 URL이다.
`<HTTP_ENDPOINT>` *	포멀 스냅샷 API URL이다.
`<OBJECT_FILE_CONCURRENCY>`	Indexer 구성 파일 경로이다.
`<PIPELINE_NAME>`	복원할 pipeline 이름이다. 여러 번 지정할 수 있으며, pipeline마다 한 번씩 사용한다.
`<REMOTE_STORE_URL>`	indexing에 사용할 checkpoint bucket URL이다. 가능한 여러 data sources 중 하나를 사용한다.
`<S3_BUCKET>` *	managed snapshots를 담고 있는 AWS S3 bucket의 이름 또는 URL이다.

* <AZURE_BUCKET>, <GCS_ACCOUNT>, <HTTP_ENDPOINT>, <S3_BUCKET> 중 하나는 반드시 지정해야 한다.

예시:

$ 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

다음 구성 파일을 사용해 Consistent Store instance를 실행하라.

$ sui-indexer-alt-consistent-store run \
    --config <CONFIG_FILE> \
    --database-path <DATABASE_PATH> \
    --remote-store-url <REMOTE_STORE_URL>

CLI param	설명
`<CONFIG_FILE>`	Consistent Store 구성 파일 경로이다.
`<DATABASE_PATH>`	RocksDB database 경로이다.
`<REMOTE_STORE_URL>`	indexing에 사용할 checkpoint bucket URL이다. 가능한 여러 data sources 중 하나를 사용한다.

예시:

$ 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	설명	Pipelines	Backfill 시간	데이터 retention
`consistent-store.toml`	Consistent Store API 구성과 event 테이블.	`balances` `object-by-owner` `object-by-type`	1-2시간	모든 데이터를 유지해야 한다

Click to open

consistent-store.toml

examples/prod-config/consistent_store.toml
[ingestion]
ingest-concurrency = 20

[pipeline.address-balances]

[pipeline.balances]

[pipeline.object-by-owner]

[pipeline.object-by-type]

GraphQL RPC server setup

GraphQL RPC server는 General-purpose Indexer의 database(Postgres), Consistent Store, 그리고 archival service에서 데이터를 읽는다.

Prerequisites

GraphQL RPC server를 시작하기 전에 모든 unprunable Indexer pipeline(obj_versions.toml과 unpruned.toml)이 network tip까지 완전히 따라잡았는지 확인하라. 이 pipeline들이 완료되어야만 GraphQL service가 정상적으로 동작한다.

Hardware requirements

CPU: instance당 2 cores
Memory: instance당 4GB

원하는 read throughput 요구 사항에 맞춰 node 수를 조정하라.

GraphQL RPC server dependencies

GraphQL RPC server는 서로 다른 유형의 query를 처리하기 위해 여러 백엔드 서비스에 의존한다.

아카이브 서비스(--ledger-grpc-url)는 checkpoint, object, transaction이 관련된 대부분의 query에 과거 데이터를 제공한다.
Consistent Store(--consistent-store-url)는 현재 object 및 balance ownership과 관련된 query에 live 데이터를 제공한다.
Postgres database(--database-url)는 대부분의 query에 대한 기본 저장소이며, direct object 및 transaction 조회만 아카이브 서비스가 처리한다.
풀 노드 RPC(--fullnode-rpc-url)는 transaction simulation과 execution을 담당한다.

GraphQL RPC server가 지원해야 하는 query 유형에 맞춰 실행 명령에 적절한 서비스 URL을 설정하라.

Run `sui-indexer-alt-graphql`

정보

Testnet 또는 Mainnet에서 Sui Foundation이 호스팅하는 public good 아카이브 서비스를 사용하는 경우 성능 문제가 발생할 수 있다. 팀은 GraphQL RPC와 아카이브 서비스가 general availability에 도달하기 전에 이를 해결할 예정이다.

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>

서로 다른 General-purpose Indexer instance마다 하나씩, 여러 --indexer-config parameter를 제공할 수 있다.

CLI parameter	설명
`CONFIG_FILE`	선택적인 GraphQL RPC server 구성 파일 경로
`INDEXER_CONFIG_FILE`	General-purpose Indexer 구성 파일 경로이다. 서로 다른 pipeline에 대해 여러 번 지정할 수 있다
`LEDGER_GRPC_URL`	아카이브 서비스의 `LedgerService` gRPC API URL
`CONSISTENT_STORE_URL`	Consistent store API URL
`DATABASE_URL`	Postgres database connection string
`FULLNODE_RPC_URL`	풀 노드 RPC URL

예시:

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

구성 파일 없이 GraphQL RPC server를 실행할 수도 있으며, 이 경우 기본값을 사용한다. 설정을 커스터마이즈하려면 아래 명령으로 구성 파일을 생성한 뒤 필요에 맞게 편집하라.


sui-indexer-alt-graphql generate-config > <PATH_TO_GRAPHQL_CONFIG_FILE>

다음과 비슷한 출력이 생성된다.

Click to open

graphql.toml

examples/prod-config/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

Indexer/GraphQL Postgres-compatible Database Setup

Indexer와 GraphQL server는 둘 다 공유하는 Postgres-compatible database가 필요하다.

다음 GraphQL 요청 처리량은 아래 권장 사양에서 테스트되었다.

Indexer가 제네시스부터 백필 중이거나 restore를 실행할 때 초당 500 requests
Indexer가 network tip에서 indexing 중일 때 초당 1000 requests(초당 약 4.25 checkpoints)

AlloyDB Omni

AlloyDB Omni는 vCPU당 8GB RAM을 권장한다 link. 이보다 적게 할당하면 부하 테스트 중 database가 Indexer와 GraphQL 연결을 종료한다.

Hardware requirements

CPU: 6 cores
Memory: 48GB

Vanilla Postgres

Hardware requirements

CPU: 6 cores
Memory: 48GB

Adding a new pipeline

기존 Indexer에 새 pipeline을 추가하려면 현재 다음 단계가 필요하다:

새 pipeline은 별도의 Indexer instance에서 시작하는 것을 권장한다. 필요하다면 Genesis 이후의 checkpoint에서 시작하도록 --first-checkpoint <checkpoint> 플래그를 설정할 수 있다.
- 참고: --first-checkpoint는 해당 pipeline의 watermark record가 없을 때만 적용된다(즉, pipeline이 이전에 실행된 적이 없어야 한다). 다른 --first-checkpoint 값을 사용하려면 watermark record를 수동으로 제거해야 하며, 그렇지 않으면 무시된다.
새 pipeline이 network tip까지 따라잡으면, 선택적으로 다른 Indexer instance에 병합할 수 있다.

Reducing indexer pipeline table and index bloat

bloat는 테이블 또는 인덱스 안의 데이터 크기와, 그것이 디스크에서 실제로 차지하는 공간 사이의 차이를 뜻한다. pipeline pruning이 활성화된 경우처럼 삽입과 삭제가 계속 비슷한 수로 일어나면 Autovacuum이 bloat를 방지한다. 하지만 삭제되는 row 수가 삽입되는 row 수보다 많아지면 Autovacuum만으로는 처리할 수 없다. 이런 상황은 두 가지 경우에 발생한다.

unpruned pipeline에서 pruning을 활성화할 때
pruned 테이블의 pruning retention 기간을 줄일 때

bloat를 줄이는 데 사용할 수 있는 도구는 다음과 같다:

Tool	Type	`ACCESS EXCLUSIVE` locking	스케줄 가능 여부	Link
`VACUUM FULL`	Built-in	전체 작업 동안 유지됨	아니오	https://www.postgresql.org/docs/current/sql-vacuum.html
pg_repack	Extension	초기 단계와 마지막 단계에서 잠시 발생	아니오	https://reorg.github.io/pg_repack/
pg_squeeze	Extension	마지막 단계에서 잠시 발생	예	https://github.com/cybertec-postgresql/pg_squeeze

Indexer setup​

Hardware requirements​

Storage requirements​

Run sui-indexer-alt​

For unprunable pipelines (must start from genesis)​

For prunable pipelines with retention period​

Examples​

Run config recommendations​

Consistent store setup​

Hardware requirements​

Restore command​

Run command​

Run config recommendations​

GraphQL RPC server setup​

Hardware requirements​

GraphQL RPC server dependencies​

Run sui-indexer-alt-graphql​

Generating Configuration​

Indexer/GraphQL Postgres-compatible Database Setup​

AlloyDB Omni​

Hardware requirements​

Vanilla Postgres​

Hardware requirements​

Adding a new pipeline​

Reducing indexer pipeline table and index bloat​

Indexer setup

Hardware requirements

Storage requirements

Run `sui-indexer-alt`

For unprunable pipelines (must start from genesis)

For prunable pipelines with retention period

Examples

Run config recommendations

Consistent store setup

Hardware requirements

Restore command

Run command

Run config recommendations

GraphQL RPC server setup

Hardware requirements

GraphQL RPC server dependencies

Run `sui-indexer-alt-graphql`

Generating Configuration

Indexer/GraphQL Postgres-compatible Database Setup

AlloyDB Omni

Hardware requirements

Vanilla Postgres

Hardware requirements

Adding a new pipeline

Reducing indexer pipeline table and index bloat