subgraphs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Goldsky Subgraphs

Subgraphs are hosted GraphQL APIs that index onchain events and expose them via a queryable endpoint. They are best for frontend applications and dApps that need flexible GraphQL queries over structured onchain data.

Could a Turbo pipeline solve this instead? If your goal is to stream raw onchain data into a database (PostgreSQL, ClickHouse, Kafka, S3) — not query via GraphQL — a Turbo pipeline is faster, cheaper, and requires no custom indexing code. Say "help me build a Turbo pipeline" and the turbo-builder skill will guide you.

Subgraph是托管式GraphQL API，可索引链上事件并通过可查询端点对外暴露。它们最适合需要对结构化链上数据进行灵活GraphQL查询的前端应用和dApp。

Turbo管道能否替代实现此需求？ 如果你的目标是将原始链上数据流式传输到数据库（PostgreSQL、ClickHouse、Kafka、S3）——而非通过GraphQL查询——那么Turbo管道速度更快、成本更低，且无需自定义索引代码。说出“帮我构建Turbo管道”，turbo-builder Skill将为你提供引导。

When to Use Subgraphs

何时使用Subgraph

Use case	Best tool
Frontend / dApp needs a GraphQL API	Subgraphs
Custom business logic in indexing handlers	Subgraphs
Migrate existing TheGraph subgraph	Subgraphs
Stream raw blockchain data to a database	Turbo pipelines
Real-time analytics in ClickHouse or Kafka	Turbo pipelines
Sync subgraph data into your own database	Mirror + subgraph source

使用场景	最佳工具
前端/dApp需要GraphQL API	Subgraphs
索引处理器中需自定义业务逻辑	Subgraphs
迁移现有TheGraph Subgraph	Subgraphs
将原始区块链数据流式传输到数据库	Turbo pipelines
在ClickHouse或Kafka中进行实时分析	Turbo pipelines
将Subgraph数据同步到自有数据库	Mirror + subgraph数据源

Initialize a Subgraph

初始化Subgraph

Scaffold a new subgraph project locally:

bash

goldsky subgraph init my-subgraph/1.0.0 --target-path ./my-subgraph

在本地搭建新的Subgraph项目：

bash

goldsky subgraph init my-subgraph/1.0.0 --target-path ./my-subgraph

Key init flags

核心初始化参数

Flag	Description
`--target-path <path>`	Directory to write subgraph files to
`--from-config <path>`	Path to instant subgraph JSON configuration file
`--abi <source>`	ABI source for contract(s)
`--contract <address>`	Contract address(es) to watch
`--contract-events <names>`	Event names to index
`--contract-calls <names>`	Call names to index
`--contract-name <name>`	Name of the contract(s)
`--network <network>`	Network for contract(s) — see docs for supported networks
`--start-block <block>`	Block to start indexing from
`--description <text>`	Subgraph description
`--call-handlers`	Enable call handlers
`--build`	Build the subgraph after writing files
`--deploy`	Deploy the subgraph after build
`--force`	Overwrite existing files at the target path

参数	描述
`--target-path <path>`	写入Subgraph文件的目录
`--from-config <path>`	快速Subgraph JSON配置文件路径
`--abi <source>`	合约ABI来源
`--contract <address>`	需监听的合约地址
`--contract-events <names>`	需索引的事件名称
`--contract-calls <names>`	需索引的调用名称
`--contract-name <name>`	合约名称
`--network <network>`	合约所在网络——查看文档了解支持的网络
`--start-block <block>`	开始索引的区块高度
`--description <text>`	Subgraph描述
`--call-handlers`	启用调用处理器
`--build`	写入文件后构建Subgraph
`--deploy`	构建完成后部署Subgraph
`--force`	覆盖目标路径下的现有文件

Deploy a Subgraph

部署Subgraph

Goldsky supports multiple deployment paths:

Goldsky支持多种部署方式：

From source (most common)

从源码部署（最常用）

Requires a compiled subgraph in a local directory.

bash

undefined

需要本地目录中有已编译的Subgraph。

bash

undefined

Install CLI and log in

安装CLI并登录

curl https://goldsky.com | sh goldsky login

Deploy from local build output

从本地构建产物部署

goldsky subgraph deploy my-subgraph/1.0.0 --path ./build

undefined

goldsky subgraph deploy my-subgraph/1.0.0 --path ./build

undefined

From ABI (instant subgraph)

从ABI部署（快速Subgraph）

Generate and deploy a subgraph directly from a contract ABI — no AssemblyScript needed:

bash

goldsky subgraph deploy my-subgraph/1.0.0 --from-abi ./MyContract.json

直接从合约ABI生成并部署Subgraph——无需编写AssemblyScript代码：

bash

goldsky subgraph deploy my-subgraph/1.0.0 --from-abi ./MyContract.json

From IPFS hash

从IPFS哈希部署

Deploy a subgraph already published to IPFS:

bash

goldsky subgraph deploy my-subgraph/1.0.0 --from-ipfs-hash QmXyz...

Use

--ipfs-gateway <url>

to specify a custom gateway (defaults to

https://ipfs.network.thegraph.com

部署已发布到IPFS的Subgraph：

bash

goldsky subgraph deploy my-subgraph/1.0.0 --from-ipfs-hash QmXyz...

使用

--ipfs-gateway <url>

指定自定义网关（默认值为

https://ipfs.network.thegraph.com

）。

No-code (dashboard wizard)

无代码部署（控制台向导）

Use the Goldsky dashboard to deploy pre-built subgraphs for common standards (ERC-20, ERC-721, etc.) without writing code. Navigate to app.goldsky.com → Subgraphs → Create.

使用Goldsky控制台部署针对通用标准（ERC-20、ERC-721等）的预构建Subgraph，无需编写代码。访问app.goldsky.com → Subgraphs → Create即可操作。

Migrate from The Graph

从The Graph迁移

One-step migration — no code changes needed:

bash

goldsky subgraph deploy my-subgraph/1.0.0 \
  --from-url <your-thegraph-deployment-url>

See docs.goldsky.com/subgraphs/deploying-subgraphs.

一键迁移——无需修改代码：

bash

goldsky subgraph deploy my-subgraph/1.0.0 \
  --from-url <your-thegraph-deployment-url>

查看文档：docs.goldsky.com/subgraphs/deploying-subgraphs。

Deploy flags reference

部署参数参考

Flag	Description
`--path <dir>`	Path to compiled subgraph directory
`--from-url <url>`	GraphQL endpoint of a publicly deployed subgraph (The Graph migration)
`--from-ipfs-hash <hash>`	IPFS hash of a publicly deployed subgraph
`--from-abi <path>`	Generate a subgraph from an ABI file
`--ipfs-gateway <url>`	Custom IPFS gateway (default: `https://ipfs.network.thegraph.com` )
`--tag <tags>`	Tag the subgraph after deployment (comma-separated for multiple)
`--start-block <number>`	Override start block
`--graft-from <name/version>`	Graft from the latest block of an existing subgraph
`--remove-graft`	Remove grafts from the subgraph prior to deployment
`--enable-call-handlers`	Enable call handlers (only with `--from-abi` )
`--description <text>`	Description/notes for the subgraph

Note:
--path
,
--from-url
,
--from-ipfs-hash
, and
--from-abi
are mutually exclusive — use only one.

参数	描述
`--path <dir>`	已编译Subgraph的目录路径
`--from-url <url>`	已公开部署的Subgraph的GraphQL端点（用于从The Graph迁移）
`--from-ipfs-hash <hash>`	已公开部署的Subgraph的IPFS哈希
`--from-abi <path>`	从ABI文件生成Subgraph
`--ipfs-gateway <url>`	自定义IPFS网关（默认值： `https://ipfs.network.thegraph.com` ）
`--tag <tags>`	部署后为Subgraph添加标签（多个标签用逗号分隔）
`--start-block <number>`	覆盖起始区块高度
`--graft-from <name/version>`	从现有Subgraph的最新区块进行嫁接
`--remove-graft`	部署前移除Subgraph的嫁接配置
`--enable-call-handlers`	启用调用处理器（仅与 `--from-abi` 配合使用）
`--description <text>`	Subgraph的描述/备注

注意：
--path
、
--from-url
、
--from-ipfs-hash
和
--from-abi
为互斥参数——仅能使用其中一个。

GraphQL Endpoints

GraphQL端点

Every deployed subgraph gets a public GraphQL endpoint:

https://api.goldsky.com/api/public/<project-id>/subgraphs/<name>/<version>/gn

To get your endpoint URL:

bash

goldsky subgraph list

每个已部署的Subgraph都会获得一个公开的GraphQL端点：

https://api.goldsky.com/api/public/<project-id>/subgraphs/<name>/<version>/gn

获取你的端点URL：

bash

goldsky subgraph list

Public vs. private endpoints

公开与私有端点

By default endpoints are public. To control endpoint visibility:

bash

undefined

默认端点为公开状态。如需控制端点可见性：

bash

undefined

Disable public endpoint

禁用公开端点

goldsky subgraph update my-subgraph/1.0.0 --public-endpoint disabled

Enable private endpoint (requires API key)

启用私有端点（需要API密钥）

goldsky subgraph update my-subgraph/1.0.0 --private-endpoint enabled


To require an API key for private endpoints:

1. Go to **app.goldsky.com → Settings → API Keys** and create a key.
2. Add the `Authorization` header to requests:

Authorization: Bearer <your-api-key>

---

goldsky subgraph update my-subgraph/1.0.0 --private-endpoint enabled


如需为私有端点设置API密钥验证：

1. 访问**app.goldsky.com → Settings → API Keys**创建密钥。
2. 在请求中添加`Authorization`请求头：

Authorization: Bearer <your-api-key>

---

Subgraph Tags

Subgraph标签

Tags pin a human-readable alias (like

prod

) to a specific subgraph version, so your frontend URL never changes when you redeploy.

bash

undefined

标签可将易读别名（如

prod

）绑定到特定Subgraph版本，这样即使重新部署，前端URL也无需更改。

bash

undefined

Create or update a tag

创建或更新标签

goldsky subgraph tag create my-subgraph/1.0.0 --tag prod

Tagged endpoint:

带标签的端点：

https://api.goldsky.com/api/public/<project-id>/subgraphs/my-subgraph/prod/gn

Delete a tag

删除标签

goldsky subgraph tag delete my-subgraph/1.0.0 --tag prod


You can also tag at deploy time:

```bash
goldsky subgraph deploy my-subgraph/2.0.0 --path ./build --tag prod

See docs.goldsky.com/subgraphs/tags.

goldsky subgraph tag delete my-subgraph/1.0.0 --tag prod


你也可以在部署时直接添加标签：

```bash
goldsky subgraph deploy my-subgraph/2.0.0 --path ./build --tag prod

查看文档：docs.goldsky.com/subgraphs/tags。

Webhooks

Webhook

Subgraph webhooks send a payload to an HTTP endpoint on every entity change (

INSERT

UPDATE

DELETE

). Useful for notifications and push-based flows.

bash

undefined

Subgraph Webhook会在每次实体变更（

INSERT

、

UPDATE

、

DELETE

）时向HTTP端点发送负载数据，适用于通知和推送式流程。

bash

undefined

Create a webhook

创建Webhook

goldsky subgraph webhook create my-subgraph/1.0.0
--name my-webhook
--url https://example.com/hook
--entity Transfer
--secret my-secret

List all webhooks

列出所有Webhook

goldsky subgraph webhook list

List available entities for a subgraph

列出Subgraph可用的实体

goldsky subgraph webhook list-entities my-subgraph/1.0.0

Delete a webhook

删除Webhook

goldsky subgraph webhook delete my-webhook


| Flag | Description |
| ---- | ----------- |
| `--name <name>` | Webhook name (must be unique) — required |
| `--url <url>` | URL to send events to — required |
| `--entity <entity>` | Subgraph entity to send events for — required |
| `--secret <secret>` | Secret included with each webhook request |

> **Tip:** If you need guaranteed delivery to a database, use Mirror to sync subgraph data instead of webhooks — it's more reliable.

See [docs.goldsky.com/subgraphs/webhooks](https://docs.goldsky.com/subgraphs/webhooks).

---

goldsky subgraph webhook delete my-webhook


| 参数 | 描述 |
| ---- | ----------- |
| `--name <name>` | Webhook名称（必须唯一）——必填 |
| `--url <url>` | 接收事件的URL——必填 |
| `--entity <entity>` | 需发送事件的Subgraph实体——必填 |
| `--secret <secret>` | 随每个Webhook请求发送的密钥 |

> **提示：** 如果需要确保数据可靠投递到数据库，请使用Mirror同步Subgraph数据，而非Webhook——Mirror的可靠性更高。

查看文档：[docs.goldsky.com/subgraphs/webhooks](https://docs.goldsky.com/subgraphs/webhooks)。

---

Managing Subgraphs

管理Subgraph

List subgraphs

列出Subgraph

bash

undefined

bash

undefined

List all subgraphs

列出所有Subgraph

goldsky subgraph list

List a specific subgraph

列出特定Subgraph

goldsky subgraph list my-subgraph/1.0.0

Show only tags or deployments

仅显示标签或部署记录

goldsky subgraph list --filter tags goldsky subgraph list --filter deployments

Summary view

摘要视图

goldsky subgraph list --summary

undefined

goldsky subgraph list --summary

undefined

Update a subgraph

更新Subgraph

bash

goldsky subgraph update my-subgraph/1.0.0 \
  --public-endpoint enabled \
  --private-endpoint disabled \
  --description "Production deployment"

Flag	Values	Description
`--public-endpoint`	`enabled` / `disabled`	Toggle public endpoint visibility
`--private-endpoint`	`enabled` / `disabled`	Toggle private endpoint (requires API key)
`--description`	text	Description/notes for the subgraph

bash

goldsky subgraph update my-subgraph/1.0.0 \
  --public-endpoint enabled \
  --private-endpoint disabled \
  --description "生产环境部署"

参数	可选值	描述
`--public-endpoint`	`enabled` / `disabled`	切换公开端点可见性
`--private-endpoint`	`enabled` / `disabled`	切换私有端点（需要API密钥）
`--description`	文本	Subgraph的描述/备注

Pause and resume

暂停与恢复

bash

undefined

bash

undefined

Pause a subgraph (stops indexing)

暂停Subgraph（停止索引）

goldsky subgraph pause my-subgraph/1.0.0

Resume a paused subgraph

恢复已暂停的Subgraph

goldsky subgraph start my-subgraph/1.0.0

undefined

goldsky subgraph start my-subgraph/1.0.0

undefined

Delete a subgraph

删除Subgraph

bash

goldsky subgraph delete my-subgraph/1.0.0

bash

goldsky subgraph delete my-subgraph/1.0.0

Skip confirmation prompt

跳过确认提示

goldsky subgraph delete my-subgraph/1.0.0 --force

---

goldsky subgraph delete my-subgraph/1.0.0 --force

---

Logs and Debugging

日志与调试

Tail a subgraph's logs to diagnose issues:

bash

undefined

查看Subgraph的日志以排查问题：

bash

undefined

View recent logs

查看近期日志

goldsky subgraph log my-subgraph/1.0.0

Logs from the last hour, errors only

查看过去1小时的错误日志

goldsky subgraph log my-subgraph/1.0.0 --since 1h --filter error

JSON format for parsing

以JSON格式输出以便解析

goldsky subgraph log my-subgraph/1.0.0 --format json


| Flag | Default | Description |
| ---- | ------- | ----------- |
| `--since <duration>` | `1m` | Show logs newer than duration (e.g. `5s`, `2m`, `3h`) |
| `--format <format>` | `text` | Output format: `pretty`, `json`, or `text` |
| `--filter <level>` | `info` | Minimum log level: `error`, `warn`, `info`, `debug` |
| `--levels <levels>` | — | Explicit comma-separated log levels to include |
| `--interval <seconds>` | `5` | Seconds between log checks |

goldsky subgraph log my-subgraph/1.0.0 --format json


| 参数 | 默认值 | 描述 |
| ---- | ------- | ----------- |
| `--since <duration>` | `1m` | 显示指定时长内的最新日志（如`5s`、`2m`、`3h`） |
| `--format <format>` | `text` | 输出格式：`pretty`、`json`或`text` |
| `--filter <level>` | `info` | 最低日志级别：`error`、`warn`、`info`、`debug` |
| `--levels <levels>` | — | 明确指定需包含的日志级别（用逗号分隔） |
| `--interval <seconds>` | `5` | 日志检查的间隔秒数 |

Stalled subgraphs

停滞的Subgraph

If a subgraph stops progressing, Goldsky auto-pauses it and sends an email notification. To diagnose:

Check logs:

goldsky subgraph log my-subgraph/1.0.0 --since 1h --filter error

Look for handler errors, RPC timeouts, or out-of-memory issues
Fix the issue and redeploy, or contact support@goldsky.com

如果Subgraph停止推进，Goldsky会自动暂停它并发送邮件通知。排查步骤：

查看日志：

goldsky subgraph log my-subgraph/1.0.0 --since 1h --filter error

检查处理器错误、RPC超时或内存不足问题
修复问题后重新部署，或联系support@goldsky.com

Cross-Chain Subgraphs

跨链Subgraph

To index the same contract across multiple chains, deploy separate subgraphs per chain, then use a Mirror pipeline to merge them into one database table.

See docs.goldsky.com/subgraphs/introduction.

如需跨多条链索引同一合约，请为每条链部署独立的Subgraph，然后使用Mirror管道将它们合并到同一个数据库表中。

查看文档：docs.goldsky.com/subgraphs/introduction。

CLI Command Reference

CLI命令参考

Action	Command
Initialize subgraph	`goldsky subgraph init <name/version>`
Deploy from source	`goldsky subgraph deploy <name/version> --path .`
Deploy from The Graph	`goldsky subgraph deploy <name/version> --from-url <url>`
Deploy from ABI	`goldsky subgraph deploy <name/version> --from-abi <path>`
Deploy from IPFS	`goldsky subgraph deploy <name/version> --from-ipfs-hash <hash>`
List subgraphs	`goldsky subgraph list`
Delete subgraph	`goldsky subgraph delete <name/version>`
Pause subgraph	`goldsky subgraph pause <name/version>`
Start subgraph	`goldsky subgraph start <name/version>`
Update subgraph	`goldsky subgraph update <name/version> --public-endpoint enabled`
Tail logs	`goldsky subgraph log <name/version>`
Create tag	`goldsky subgraph tag create <name/version> --tag <tag>`
Delete tag	`goldsky subgraph tag delete <name/version> --tag <tag>`
Create webhook	`goldsky subgraph webhook create <name/version> --name <n> --url <u> --entity <e>`
List webhooks	`goldsky subgraph webhook list`
Delete webhook	`goldsky subgraph webhook delete <webhook-name>`
List webhook entities	`goldsky subgraph webhook list-entities <name/version>`

操作	命令
初始化Subgraph	`goldsky subgraph init <name/version>`
从源码部署	`goldsky subgraph deploy <name/version> --path .`
从The Graph部署	`goldsky subgraph deploy <name/version> --from-url <url>`
从ABI部署	`goldsky subgraph deploy <name/version> --from-abi <path>`
从IPFS部署	`goldsky subgraph deploy <name/version> --from-ipfs-hash <hash>`
列出Subgraph	`goldsky subgraph list`
删除Subgraph	`goldsky subgraph delete <name/version>`
暂停Subgraph	`goldsky subgraph pause <name/version>`
启动Subgraph	`goldsky subgraph start <name/version>`
更新Subgraph	`goldsky subgraph update <name/version> --public-endpoint enabled`
查看日志	`goldsky subgraph log <name/version>`
创建标签	`goldsky subgraph tag create <name/version> --tag <tag>`
删除标签	`goldsky subgraph tag delete <name/version> --tag <tag>`
创建Webhook	`goldsky subgraph webhook create <name/version> --name <n> --url <u> --entity <e>`
列出Webhook	`goldsky subgraph webhook list`
删除Webhook	`goldsky subgraph webhook delete <webhook-name>`
列出Webhook实体	`goldsky subgraph webhook list-entities <name/version>`