SubQuery

https://github.com/subquery/documentation
Admin
SubQuery is a decentralized data aggregation, indexing, and querying layer that transforms...
Tokens:328,519
Snippets:3,415
Trust Score:8.5
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install Docker on Linux

Source: https://github.com/subquery/documentation/blob/master/docs/subquery_network/node_operators/setup/install-linux.md

Installs Docker, enables it to start on boot, and starts the Docker service. This is a prerequisite for running containerized services.

```bash
sudo yum install docker
sudo systemctl enable docker
sudo systemctl start docker
```

--------------------------------

### Start SubQuery Project with npm

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/quickstart/snippets/run-locally.md

Use this command to start your SubQuery project locally using Docker with npm. Ensure Docker is installed and running.

```shell
npm run-script start:docker
```

--------------------------------

### Start Grafana Docker Compose

Source: https://github.com/subquery/documentation/blob/master/docs/subquery_network/node_operators/setup/becoming-a-node-operator.md

After configuring the Grafana setup files, run this command to start the Grafana dashboard services.

```bash
docker compose -f ./metrics/docker-compose-metrics.yml up -d
```

--------------------------------

### Initial Docker Compose Up Command

Source: https://github.com/subquery/documentation/blob/master/docs/subquery_network/node_operators/setup/troubleshooting.md

The command to start services defined in a docker-compose.yml file after ensuring Docker Compose is correctly installed and configured.

```bash
docker compose up
```

--------------------------------

### Install Docker Compose

Source: https://github.com/subquery/documentation/blob/master/docs/subquery_network/node_operators/setup/install-linux.md

Downloads and installs the latest version of Docker Compose, making it executable. Verify the installation afterward.

```bash
# get the latest version for docker-compose
sudo curl -L https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m) -o /usr/bin/docker-compose

# fix permissions after download:
sudo chmod +x /usr/bin/docker-compose

# verify the installation
sudo docker compose version
```

--------------------------------

### SubQuery Project Initialization Example

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/quickstart/quickstart.md

An example of the interactive prompts and user inputs during the SubQuery project initialization process.

```shell
$ npx @subql/cli init
Project name [subql-starter]: evm-hello-world
? Select a network family EVM
? Select a network Ethereum
? Select a template project ethereum-starter     This SubQuery project indexes all transfers and approval events for the wrapped Ether token on Ethereum Mainnet
? RPC endpoint: https://ethereum.rpc.subquery.network/public
? Author SubQuery Team
? Description This project can be use as a starting po...
evm-hello-world is ready
? Do you want to generate datasources and handlers from an existing contract ABI? no

```

--------------------------------

### Start SubQuery Project with Yarn

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/quickstart/snippets/run-locally.md

Use this command to start your SubQuery project locally using Docker with Yarn. Ensure Docker is installed and running.

```shell
yarn start:docker
```

--------------------------------

### Start Subql Node for Substrate/Polkadot

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/run_publish/run.md

Command to start the SubQuery indexer node for Substrate/Polkadot projects.

```shell
subql-node <command>
```

--------------------------------

### Install Dependencies and Build Project

Source: https://context7.com/subquery/documentation/llms.txt

Installs project dependencies, generates types from schema and ABIs, and builds the project. These are prerequisite steps before running the project.

```bash
# Install dependencies
npm install

# Generate types from schema and ABIs
npm run codegen

# Build the project
npm run build
```

--------------------------------

### Solana Datasource Configuration Example

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/build/manifest/chain-specific/solana.md

Example of a Solana datasource configuration within a SubQuery project manifest. Use this to specify the runtime, starting block, and mapping file for indexing Solana data.

```typescript
{ ...
  dataSources: [
    {
      kind: SolanaDataSourceKind.Runtime, // Indicates that this is default runtime
      startBlock: 1, // This changes your indexing start block, set this higher to skip initial blocks with less data
      mapping: {
        file: "./dist/index.js", // Entry path for this mapping
        handlers: [
          /* Enter handers here */
        ]
      }
    }
  ]
}
```

--------------------------------

### Install Project Dependencies with npm

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/quickstart/quickstart.md

Navigate to your project directory and install dependencies using npm. This command should be run after initializing the project.

```shell
cd PROJECT_NAME
npm install
```

--------------------------------

### Cosmos Data Source Configuration Example

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/build/manifest/chain-specific/cosmos.md

Example of a Cosmos data source configuration within a SubQuery project. Specifies the runtime kind, starting block, and mapping file.

```typescript
{
  ... 
  dataSources: [
    {
      kind: CosmosDataSourceKind.Runtime, // Indicates that this is default runtime
      startBlock: 1, // This changes your indexing start block, set this higher to skip initial blocks with less data
      mapping: {
        file: "./dist/index.js", // Entry path for this mapping
        handlers: [
          /* Enter handers here */
        ]
      }
    }
  ]
}
```

--------------------------------

### Expected Output of Dockerized SubQuery Project

Source: https://context7.com/subquery/documentation/llms.txt

Example output showing the SubQuery indexer node enqueuing blocks and the GraphQL engine starting. It also indicates the indexing speed and the GraphQL playground URL.

```text
# Expected output:
# subquery-node-1   | 2025-05-21T09:10:01.489Z <WorkerBlockDispatcherService> INFO Enqueuing blocks 4753408...4754452
# graphql-engine-1  | 2025-05-21T09:10:01.965Z <subql-query> INFO Started playground at http://localhost:3000
# subquery-node-1   | 2025-05-21T09:10:08.967Z <benchmark> INFO INDEXING: 7.13 blocks/s

# Access GraphQL playground at http://localhost:3000
```

--------------------------------

### Start Subql Node for Algorand

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/run_publish/run.md

Command to start the SubQuery indexer node for Algorand.

```shell
subql-node-algorand <command>
```

--------------------------------

### Install Project Dependencies with yarn

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/quickstart/quickstart.md

Navigate to your project directory and install dependencies using yarn. This command should be run after initializing the project.

```shell
cd PROJECT_NAME
yarn install
```

--------------------------------

### Install @subql/node-ethereum with yarn

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/build/install.md

Install the SubQuery Ethereum node implementation globally using yarn. Yarn is not recommended for global installations.

```shell
yarn global add @subql/node-ethereum
```

--------------------------------

### Install @subql/query with yarn

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/build/install.md

Install the SubQuery query library globally using yarn. Yarn is not recommended for global installations.

```shell
yarn global add @subql/query
```

--------------------------------

### Start Subql Node for Stellar

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/run_publish/run.md

Command to start the SubQuery indexer node for Stellar.

```shell
subql-node-stellar <command>
```

--------------------------------

### Run Development Command for SubQuery Project

Source: https://context7.com/subquery/documentation/llms.txt

A convenience command that installs dependencies, generates types, builds the project, and starts all services with Docker Compose. Useful for local development.

```bash
# Or run the convenience command that does all of the above
npm run dev
```

--------------------------------

### React Client GraphQL Subscription Example

Source: https://context7.com/subquery/documentation/llms.txt

Example of using `@apollo/client` in a React application to subscribe to balance updates. Requires Apollo Client setup with WebSocket link.

```typescript
import { useSubscription, gql } from "@apollo/client";

const BALANCES_SUBSCRIPTION = gql`
  subscription BalancesSubscription($id: ID!, $mutation: String!) {
    balances(id: $id, mutation: $mutation) {
      id
      mutation_type
      _entity
      amount
    }
  }
`;

const BalanceUpdates = ({ accountId }) => {
  const { data, loading, error } = useSubscription(BALANCES_SUBSCRIPTION, {
    variables: { id: accountId, mutation: "UPDATE" },
  });

  if (loading) return <p>Loading...</p>;
  if (error) return <p>Error: {error.message}</p>;

  return (
    <div>
      <h4>Balance update for {accountId}</h4>
      {data && <p>New balance: {data.balances.amount}</p>}
    </div>
  );
};

```

--------------------------------

### Install Nginx

Source: https://github.com/subquery/documentation/blob/master/docs/subquery_network/node_operators/setup/security-guide.md

Installs the Nginx web server. This is required to act as a reverse proxy and handle SSL termination.

```shell
sudo apt install -y nginx
```

--------------------------------

### Install @subql/cli with yarn

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/build/install.md

Install the SubQuery CLI globally using yarn. Note that yarn is not recommended for global installations.

```shell
yarn global add @subql/cli
```

--------------------------------

### Start Subql Node for Cosmos

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/run_publish/run.md

Command to start the SubQuery indexer node for Cosmos-based chains.

```shell
subql-node-cosmos <command>
```

--------------------------------

### Download Docker Compose and IPFS Script

Source: https://github.com/subquery/documentation/blob/master/docs/subquery_network/node_operators/setup/install-local-docker.md

Download the docker-compose.yml file for the Node Operator services and an optional IPFS setup script. Ensure Docker is installed and running before executing.

```bash
mkdir subquery-indexer && cd subquery-indexer
curl https://raw.githubusercontent.com/subquery/network-indexer-services/main/deploy/docker-compose.yml -o docker-compose.yml

# extra steps to use local ipfs node
mkdir ipfs
curl https://raw.githubusercontent.com/subquery/network-indexer-services/main/deploy/ipfs/ipfs.sh -o ipfs/ipfs.sh
chmod +x ipfs/ipfs.sh
```

--------------------------------

### Install Subql Node for Stellar

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/run_publish/run.md

Install the SubQuery node package for Stellar using npm.

```shell
# NPM
npm install -g @subql/node-stellar
```

--------------------------------

### Start Subql Node for Near

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/run_publish/run.md

Command to start the SubQuery indexer node for Near Protocol.

```shell
subql-node-near <command>
```

--------------------------------

### Run SubQuery Indexer Node Manually

Source: https://context7.com/subquery/documentation/llms.txt

Starts the SubQuery indexer node manually for EVM chains using the installed package and specified project file. Requires database connection variables to be set.

```bash
# Run the indexer node
subql-node-ethereum -f ./project.ts
```

--------------------------------

### Run Docker Compose for SubQuery

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/quickstart/quickstart.md

This command pulls the necessary Docker images and starts the containers for the indexer, PostgreSQL database, and query service. Docker must be installed and running locally. Configuration is managed by docker-compose.yml.

```shell
docker compose pull && docker compose up
```

--------------------------------

### Install @subql/cli with npm

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/build/install.md

Install the SubQuery CLI globally using npm. This tool helps create and manage SubQuery projects.

```bash
npm install -g @subql/cli
```

--------------------------------

### Clone Example Project

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/academy/tutorials_examples/run-indexer.md

Clone a sample SubQuery project from GitHub to practice indexing. This provides a ready-to-use project for testing.

```shell
git clone https://github.com/subquery/subql-helloworld
```

--------------------------------

### Install Subql Node for Algorand

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/run_publish/run.md

Install the SubQuery node package for Algorand using npm.

```shell
# NPM
npm install -g @subql/node-algorand
```

--------------------------------

### Start Prometheus Server

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/run_publish/monitor.md

Command to start the Prometheus server, specifying the configuration file to use. Ensure the path to your prometheus.yml is correct.

```bash
prometheus --config.file=prometheus.yml
```

--------------------------------

### Install and Configure ufw-docker

Source: https://github.com/subquery/documentation/blob/master/docs/subquery_network/node_operators/setup/security-guide.md

Installs the ufw-docker script and configures ufw to manage Docker-related firewall rules. This is useful for securing ports on bare metal installations.

```bash
sudo wget -O /usr/local/bin/ufw-docker https://github.com/chaifeng/ufw-docker/raw/master/ufw-docker
sudo chmod +x /usr/local/bin/ufw-docker
ufw-docker install
```

--------------------------------

### Start Subql Node for Concordium

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/run_publish/run.md

Command to start the SubQuery indexer node for Concordium.

```shell
subql-node-concordium <command>
```

--------------------------------

### Install Subql Node for EVM

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/run_publish/run.md

Install the SubQuery node package for EVM-compatible chains using npm.

```shell
# NPM
npm install -g @subql/node-ethereum
```

--------------------------------

### Start SubQuery node

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/build/install.md

Command to start the SubQuery Ethereum node. Replace `<command>` with the specific command to run.

```shell
subql-node-ethereum <command>
```

--------------------------------

### Install Subql Node for Substrate/Polkadot

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/run_publish/run.md

Install the SubQuery node package for Substrate/Polkadot projects using npm.

```shell
# NPM
npm install -g @subql/node
```

--------------------------------

### Install Subql Node for Near

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/run_publish/run.md

Install the SubQuery node package for Near Protocol using npm.

```shell
# NPM
npm install -g @subql/node-near
```

--------------------------------

### Install @subql/query with npm

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/build/install.md

Install the SubQuery query library globally using npm. This library provides a playground environment for querying your project data.

```bash
npm install -g @subql/query
```

--------------------------------

### Manage systemd Service

Source: https://github.com/subquery/documentation/blob/master/docs/subquery_network/node_operators/setup/install-linux.md

Enables the SubQuery service to start automatically on system boot, starts the service immediately, and checks its current status.

```bash
systemctl enable subquery.service
systemctl start subquery.service

systemctl status subquery.service
```

--------------------------------

### NEAR Project Configuration Example

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/build/manifest/chain-specific/near.md

Example configuration for a NEAR SubQuery project, including dictionary endpoint, bypassed blocks, and data source definitions with handlers and filters.

```yaml
dictionary: https://api.subquery.network/sq/subquery/near-dictionary
bypassBlocks: [81003306] # This is a missing block from the NEAR mainnet chain that we are skipping
dataSources:
  - kind: near/Runtime
    startBlock: 80980000 # You can set any start block you want here. This block was when the sweat_welcome.near address was created
    mapping:
      file: "./dist/index.js"
      handlers:
        # Using block handlers slows your project down as they can be executed with each and every block. Only use if you need to
        # - handler: handleBlock
        #   kind: near/BlockHandler
        #   filter:
        #     modulo: 10
        - handler: handleTransaction
          kind: near/TransactionHandler
          filter:
            sender: sweat_welcome.near
            receiver: token.sweat
        - handler: handleAction
          kind: near/ActionHandler
          filter:
            type: FunctionCall
            methodName: storage_deposit
            receiver: token.sweat
```

--------------------------------

### Start SubQuery Query Service with Playground

Source: https://context7.com/subquery/documentation/llms.txt

Starts the SubQuery query service with the GraphQL playground enabled for interactive querying.

```bash
subql-query --name project_name --playground
```

--------------------------------

### Install Subql Node for Cosmos

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/run_publish/run.md

Install the SubQuery node package for Cosmos-based chains using npm.

```shell
# NPM
npm install -g @subql/node-cosmos
```

--------------------------------

### Initialize SubQuery Project

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/build/introduction.md

Use this command to initialize a new SubQuery project. Ensure you have Node.js and npm installed.

```bash
npx @subql/cli init PROJECT_NAME
```

--------------------------------

### Install @subql/node-ethereum with npm

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/build/install.md

Install the SubQuery Ethereum node implementation globally using npm. This node extracts data from the Ethereum blockchain.

```bash
npm install -g @subql/node-ethereum
```

--------------------------------

### Install Subql Node for Concordium

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/run_publish/run.md

Install the SubQuery node package for Concordium using npm.

```shell
# NPM
npm install -g @subql/node-concordium
```

--------------------------------

### Install Apollo Client Dependencies

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/run_publish/query/subscription.md

Install the necessary Apollo Client and GraphQL packages for your React project.

```bash
npm install @apollo/client graphql
```

--------------------------------

### Install Subql Query Service

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/run_publish/run.md

Install the SubQuery query service globally using NPM. Avoid using `yarn global` due to potential dependency management issues.

```shell
# NPM
npm install -g @subql/query
```

--------------------------------

### Apollo Server Setup with PubSub

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/run_publish/query/subscription.md

Basic Apollo Server setup in Node.js using `graphql-subscriptions`' `PubSub` for managing publish/subscribe events. This includes type definitions and resolvers for subscriptions.

```javascript
const { ApolloServer, gql, PubSub } = require("apollo-server");
const pubsub = new PubSub();

// GraphQL type definitions
const typeDefs = gql`
  type Balances {
    id: ID!
    amount: Int!
  }

  type BalanceUpdate {
    id: ID!
    mutation_type: String!
    _entity: String!
    amount: Int!
  }

  type Subscription {
    balances(id: ID!, mutation: String!): BalanceUpdate
  }
`;

// Resolvers define the technique for fetching the types defined in the schema
const resolvers = {
  Subscription: {
    balances: {
      subscribe: (_, { id, mutation }) => {
        const channel = `${mutation}_${id}`;
        return pubsub.asyncIterator(channel);
      },
    },
  },
};

// Create the Apollo Server instance
const server = new ApolloServer({ typeDefs, resolvers });

// Start the server
server.listen().then(({ url }) => {
  console.log(`Server ready at ${url}`);
});
```

--------------------------------

### EVM Quick Start Reference

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/quickstart/quickstart_chains/polygon.md

This snippet provides a reference for setting up an EVM-compatible SubQuery project. It includes essential configurations and handlers for indexing blockchain data.

```typescript
import { SubstrateEvent } from "@subql/types";
import { Account, Transfer } from "../types";
import { Balance } from "@polkadot/types/primitive";

export async function handleEvent(event: SubstrateEvent) {
    const { event: { data } } = event;

    // data - Investment
    const investment = Account.create({
        id: event.extrinsic.extrinsic.hash.toHex(),
        name: data[0].toString(),
        balance: (data[1] as Balance).toBigInt(),
    });
    await investment.save();
}

export async function handleCall(extrinsic: SubstrateExtrinsic) {
    const { extrinsic: { method: { method, section } } } = extrinsic;

    // method - Investment
    const investment = Account.create({
        id: extrinsic.extrinsic.hash.toHex(),
        name: method,
        balance: 1000n,
    });
    await investment.save();
}

```

--------------------------------

### Install SubQuery MCP Server

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/miscellaneous/ai.md

Run this command to install SubQuery MCP. It is used for integrating AI tools into SubQuery project development.

```bash
npx -y @subql/cli mcp
```

--------------------------------

### Start Dockerized SubQuery Tests

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/build/testing.md

Use this command to pull the Docker image and start the SubQuery node service, which will automatically run tests if `SUB_COMMAND` is set to 'test'.

```bash
SUB_COMMAND=test docker compose pull && docker compose up
```

--------------------------------

### Example Script Execution and Output

Source: https://github.com/subquery/documentation/blob/master/docs/subquery_network/node_operators/setup/becoming-a-node-operator.md

This demonstrates the typical output when running the auto-upgrade-tool.sh script, including backup creation, tag updates, and Docker service restarts.

```sh
./auto-upgrade-tool.sh
Latest coordinator tag: v2.10.0
Latest proxy tag: v2.9.0
📦 Backup created: docker-compose.yml.20250429_180911.bak
✅ Coordinator tag updated to v2.10.0.
🎉 docker-compose.yml has been updated to the latest tags.
Do you want to run 'docker compose up'? (yes/[no]): yes
🔄 Pulling latest images:
    Command    : docker compose pull
    Config file: docker-compose.yml
WARN[0000] /Users/a/company_info/network-indexer-services/deploy/docker-compose.yml: the attribute `version` is obsolete, it will be ignored, please remove it to avoid potential confusion
[+] Pulling 5/5
 ✔ redis Pulled                                                                     4.6s
 ✔ ipfs Pulled                                                                      2.9s
 ✔ proxy Pulled                                                                     2.9s
 ✔ coordinator Pulled                                                               4.3s
 ✔ postgres Pulled                                                                  4.2s
🔄 Starting services:
    Command    : docker compose up -d
    Config file: docker-compose.yml
WARN[0000] /Users/a/company_info/network-indexer-services/deploy/docker-compose.yml: the attribute `version` is obsolete, it will be ignored, please remove it to avoid potential confusion
WARN[0000] A network with the name `indexer_services` exists but was not created for project "deploy".
Set `external: true` to use an existing network.
[+] Running 5/5
 ✔ Container indexer_cache        Started                                           0.4s
 ✔ Container indexer_db           Healthy                                           5.9s
 ✔ Container indexer_ipfs         Healthy                                           5.9s
 ✔ Container indexer_coordinator  Healthy                                          11.5s
 ✔ Container indexer_proxy        Started                                          11.6s
```

--------------------------------

### Install gsutil in Dockerfile

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/run_publish/query/other_tools/bigquery.md

Installs the Google Cloud SDK, which includes the `gsutil` command-line tool, within a Docker container. This is necessary for uploading files to Google Cloud Storage.

```Dockerfile
RUN apt-get update && apt-get install -y \
    curl \
    gnupg \
    && curl https://sdk.cloud.google.com | bash
```

--------------------------------

### Run Project with npm

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/quickstart/quickstart.md

Use this command to start the development server for your SubQuery project. This command orchestrates multiple sub-commands for a streamlined development experience.

```shell
npm run-script dev
```

--------------------------------

### Install SubQuery Query Service

Source: https://context7.com/subquery/documentation/llms.txt

Installs the SubQuery query service globally. This service exposes indexed data through a GraphQL API.

```bash
# Install query service
npm install -g @subql/query
```

--------------------------------

### Start Indexing a Project

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/academy/tutorials_examples/run-indexer.md

Initiate the indexing process for a SubQuery project by running the `subql-node` command within the project directory. The `-f .` flag indicates the current directory.

```shell
subql-node -f .
```

--------------------------------

### Example Response for Shard Configuration

Source: https://github.com/subquery/documentation/blob/master/docs/subquery_network/data_node/sharding.md

This JSON object shows the current shard configuration, including the desired start and end block numbers for chain data.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "desiredChainDataStart": 20,
    "desiredChainDataEnd": 90
  }
}
```

--------------------------------

### Show Subql Query Help Information

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/run_publish/references.md

Use the `--help` flag to display all available command options for the subql-query CLI.

```shell
subql-query --help
```

--------------------------------

### Install SubQuery Node Globally

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/academy/tutorials_examples/run-indexer.md

Install the SubQuery node package globally using npm. This makes the `subql-node` command available system-wide.

```shell
npm install -g @subql/node
```

--------------------------------

### Create a New Subquery Project

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/quickstart/snippets/evm-quickstart-reference.md

Initialize a new Subquery project using the Subquery CLI. Choose a template to start with.

```bash
subql init <project-name>
```

--------------------------------

### Start SubQuery Query Service with GraphQL Playground

Source: https://context7.com/subquery/documentation/llms.txt

Starts the SubQuery query service, providing a GraphQL API for accessing indexed data. The '--playground' flag enables the interactive GraphQL playground interface.

```bash
# Start query service with GraphQL playground
subql-query --name my-project --playground
```

--------------------------------

### Query Solana Network Accounts

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/build/mapping-functions/sandbox/querying-chain-state.md

Query account and program state for Solana networks. This example shows how to get an account's balance and query its associated token accounts.

```typescript
import { SolanaTransaction } from "@subql/types-solana";

export async function handleTransaction(tx: SolanaTransaction): Promise<void> {
  const connection = api; // Solana connection object
  
  // Query account balance
  const accountKey = tx.transaction.message.accountKeys[0];
  const balance = await connection.getBalance(accountKey.toBase58());
  
  logger.info(`Account ${accountKey.toBase58()} balance: ${balance} lamports`);
  
  // Query token account
  try {
    const tokenAccounts = await connection.getTokenAccountsByOwner(
      accountKey,
      { programId: TOKEN_PROGRAM_ID }
    );
    
    logger.info(`Token accounts: ${tokenAccounts.value.length}`);
    
  } catch (error) {
    logger.error(`Failed to query token accounts: ${error.message}`);
  }
}
```

--------------------------------

### Docker Compose File Changes Example

Source: https://github.com/subquery/documentation/blob/master/docs/subquery_network/node_operators/setup/becoming-a-node-operator.md

This diff shows an example of how the `docker-compose.yml` file is updated with new image tags after running the upgrade script.

```diff
# git diff docker-compose.yml

Δ deploy/docker-compose.yml
─────────────────────────────────────────────────────────────────────────────────────────
────────────────┐
• 18: services: │
────────────────┘
 18 ⋮ 18 │      retries: 5
 19 ⋮ 19 │
 20 ⋮ 20 │  coordinator:
-21 ⋮ 21 │    image: subquerynetwork/indexer-coordinator:v2.9.1
+21 ⋮ 21 │    image: subquerynetwork/indexer-coordinator:v2.10.0
 22 ⋮ 22 │    container_name: indexer_coordinator
 23 ⋮ 23 │    restart: always
 24 ⋮ 24 │    ports:
```

--------------------------------

### Get Current Shard Configuration via Admin RPC

Source: https://github.com/subquery/documentation/blob/master/docs/subquery_network/data_node/sharding.md

Retrieve the current shard configuration, including desired chain data start and end points, using the subql_dataInfo RPC method.

```json
{
    "jsonrpc": "2.0",
    "method": "subql_dataInfo",
    "params": [],
    "id": 0
}
```

--------------------------------

### Install SubQuery Node Package for EVM Chains

Source: https://context7.com/subquery/documentation/llms.txt

Installs the network-specific SubQuery node package for Ethereum Virtual Machine (EVM) chains. This is required for running the indexer node manually.

```bash
# Install network-specific node package
npm install -g @subql/node-ethereum  # For EVM chains
npm install -g @subql/node-cosmos    # For Cosmos chains
npm install -g @subql/node           # For Substrate/Polkadot
```

--------------------------------

### GraphQL Response for Dictionaries

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/quickstart/quickstart_multichain/safe.md

Example JSON response for the '_metadata' query, showing the 'dynamicDatasources' configuration. This includes template name, arguments (like proxy address), and start block for dynamic data sources.

```json
{
  "data": {
    "_metadata": {
      "dynamicDatasources": "[{\"templateName\":\"GnosisSafe\",\"args\":{\"proxyAddress\":\"0xF56F29E3fe941FDFb48859d46bB24425Fd648e55\"},\"startBlock\":110991101}]"
    }
  }
}
```

--------------------------------

### Example: EVM Contract Interaction

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/quickstart/snippets/evm-quickstart-reference.md

Demonstrates how to interact with an EVM smart contract using the generated ABI scaffold. This example shows calling a function on a contract.

```typescript
import { Transfer } from "../types";
import { Address } from "@polkadot/types/interfaces";
import erc20 from "../abi/erc20.json";

export async function handleBlock(block: Context) {
  const contractAddress = "0x...";
  const contract = new Contract(block.timestamp, contractAddress, erc20);

  const balance = await contract.balanceOf(block.caller);
  const transfer: Transfer = {
    id: block.hash,
    balance: balance.toString(),
  };
  await transfer.save();
}
```

--------------------------------

### Download and Setup Indexer Services

Source: https://github.com/subquery/documentation/blob/master/docs/subquery_network/node_operators/setup/becoming-a-node-operator.md

Use this command to download and set up the necessary files for the Grafana dashboard. Ensure you back up your existing docker-compose.yaml before running.

```bash
cd indexer-services-folder
# Note the next step will overwrite your existing docker-compose.yml, make sure you have a backup
mkdir network-indexer-services-temp && curl -L https://api.github.com/repos/subquery/network-indexer-services/tarball/main | tar -xzf - --strip-components=1 -C ./network-indexer-services-temp && rm -rf ./ipfs ./metrics && mv ./network-indexer-services-temp/deploy/* . && rm -rf ./network-indexer-services-temp
```

--------------------------------

### View SubQuery CLI help

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/build/install.md

Run this command to see available commands and usage instructions for the SubQuery CLI.

```shell
subql --help
```

--------------------------------

### Show Help for Subql Node

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/run_publish/references.md

Use the --help flag to display all available command-line options for the current version of subql-node.

```shell
--help
```

--------------------------------

### Publish Project with Default Manifest

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/miscellaneous/ipfs.md

Run this command from your project's root directory to publish using the default `project.ts` manifest. Ensure `@subql/cli` is version 5.0.0 or above and the necessary `@subql/common-<network>` package is installed.

```bash
subql publish
```

--------------------------------

### Configure Gnosis Data Sources

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/quickstart/quickstart_chains/gnosis.md

Configure the project manifest to index POAP contract events and transactions. Specify the ABI, contract address, and start block. This setup triggers 'handleTokenMint' for mints and 'handleLog' for transfers.

```typescript
{
  dataSources: [
    {
      kind: EthereumDatasourceKind.Runtime,
      // When the POAP contract was deployed https://gnosisscan.io/tx/0x2e4873cb1390f5328d389276624d1ffa833e3934657d5a791ee145defff663a2
      startBlock: 12188423,
      options: {
        // Must be a key of assets
        abi: "poap",
        // this is the contract address for POAPs on Gnosis https://gnosisscan.io/token/0x22c1f6050e56d2876009903609a2cc3fef83b415
        address: "0x22c1f6050e56d2876009903609a2cc3fef83b415",
      },
      assets: new Map([["poap", { file: "./abis/poap.abi.json" }]]),
      mapping: {
        file: "./dist/index.js",
        handlers: [
          {
            kind: EthereumHandlerKind.Call,
            handler: "handleTokenMint",
            filter: {
              /**
               * The function can either be the function fragment or signature
               * function: '0xaf68b302'
               */
              function: "mintToken(uint256 eventId, address to)",
            },
          },
          {
            kind: EthereumHandlerKind.Event,
            handler: "handleLog",
            filter: {
              /**
               * Follows standard log filters https://docs.ethers.io/v5/concepts/events/
               * address: "0x60781C2586D68229fde47564546784ab3fACA982"
               */
              topics: [
                "Transfer(address indexed from, address indexed to, uint256 amount)",
              ],
            },
          },
        ],
      },
    },
  ],
}
```

--------------------------------

### Run SubQuery Project with Docker Compose

Source: https://context7.com/subquery/documentation/llms.txt

Starts the complete SubQuery stack, including the indexer node, PostgreSQL database, and GraphQL query service, using Docker Compose. This command pulls images and starts all services.

```bash
# Start all services with Docker
docker compose pull && docker compose up
```

--------------------------------

### Configure Solana Data Sources

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/quickstart/quickstart_chains/solana.md

Configure the `datasources` section in your `project.ts` file to specify the data source kind, start block, assets, and mapping handlers. This example sets up the handler for `transferChecked` instructions from the RNDR token program.

```typescript
{
  dataSources: [
    {
      kind: SolanaDatasourceKind.Runtime,
      startBlock: 336382792,

      assets: new Map([
        ["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA", { file: "./idls/tokenprogram.idl.json" }]
      ]),
      mapping: {
        file: "./dist/index.js",
        handlers: [
          {
            kind: SolanaHandlerKind.Instruction,
            handler: "handleCheckedTransfer",
            filter: {
              programId: "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
              discriminator: "transferChecked",
              accounts: [
                null,
                ['rndrizKT3MK1iimdxRdWabcF7Zg7AR5T4nud4EkHBof'],
              ]
            },
          },
        ],
      },
    },
  ],
}
```

--------------------------------

### Start Subquery Node

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/quickstart/snippets/evm-quickstart-reference.md

Run the Subquery node to index data for your project. Ensure you have configured your project's data source in the manifest file.

```bash
yarn start:dev
```

--------------------------------

### Query Native Token Balances (EVM)

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/build/mapping-functions/sandbox/querying-chain-state.md

Query native token balances for EVM-compatible networks like Ethereum, Polygon, and Binance Smart Chain. This example shows how to get the balance at a specific block number and the current balance.

```typescript
export async function handleTransaction(tx: EthereumTransaction): Promise<void> {
  // Query ETH balance
  const balance = await api.getBalance(tx.from, tx.blockNumber);
  
  // Query balance at current block
  const currentBalance = await api.getBalance(tx.from);
  
  logger.info(`Balance at block ${tx.blockNumber}: ${balance.toString()}`);
  logger.info(`Current balance: ${currentBalance.toString()}`);
  
  const account = Account.create({
    id: tx.from,
    balance: balance.toBigInt(),
    lastUpdatedBlock: BigInt(tx.blockNumber),
  });
  
  await account.save();
}
```

--------------------------------

### Initialize SubQuery Project with CLI

Source: https://context7.com/subquery/documentation/llms.txt

Use the SubQuery CLI to initialize a new indexing project. This command sets up the project structure, including manifest, schema, and mapping files. Follow the interactive prompts to configure your project.

```bash
npx @subql/cli init

# Interactive prompts:
# Project name: my-evm-project
# Network family: EVM
# Network: Ethereum
# Template: ethereum-starter
# RPC endpoint: https://ethereum.rpc.subquery.network/public
# Author: Your Name
# Description: My first SubQuery project

# Output: Creates project directory with all required files
# my-evm-project/
#   ├── project.ts          # Manifest file
#   ├── schema.graphql      # GraphQL schema
#   ├── src/
#   │   └── mappings/
#   │       └── mappingHandlers.ts
#   ├── docker-compose.yml
#   └── package.json
```

--------------------------------

### Multi-chain Manifest Example

Source: https://context7.com/subquery/documentation/llms.txt

Example TypeScript manifests for configuring multi-chain indexers, specifically for tracking cross-chain NFTs on Ethereum and Polygon. Each manifest defines network details, data sources, and event handlers.

```typescript
// Multi-chain manifest example for tracking cross-chain NFTs
// chain1-project.ts (Ethereum)
export default {
  network: { chainId: "1", endpoint: ["https://eth.rpc.example.com"] },
  dataSources: [{
    kind: EthereumDatasourceKind.Runtime,
    startBlock: 15000000,
    options: { abi: "nft", address: "0x..." },
    mapping: {
      handlers: [{
        kind: EthereumHandlerKind.Event,
        handler: "handleNFTMint",
        filter: { topics: ["Transfer(address,address,uint256)"] },
      }],
    },
  }],
};

// chain2-project.ts (Polygon)
export default {
  network: { chainId: "137", endpoint: ["https://polygon.rpc.example.com"] },
  dataSources: [{
    kind: EthereumDatasourceKind.Runtime,
    startBlock: 30000000,
    options: { abi: "bridge", address: "0x..." },
    mapping: {
      handlers: [{
        kind: EthereumHandlerKind.Event,
        handler: "handleBridgeTransfer",
        filter: { topics: ["BridgeTransfer(address,uint256,uint256)"] },
      }],
    },
  }],
};
```

--------------------------------

### Start Node Operator Services with Docker Compose

Source: https://github.com/subquery/documentation/blob/master/docs/subquery_network/node_operators/setup/install-local-docker.md

Starts the Node Operator services using Docker Compose. This command pulls the necessary images and initiates the database, coordinator, proxy, cache, and optionally IPFS services.

```bash
docker compose up -d
```

--------------------------------

### Initialize New SubQuery Project

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/quickstart/quickstart.md

Use the SubQuery CLI to initialize a new project. You will be prompted for project name, network, template, RPC endpoint, author, and description.

```shell
npx @subql/cli init
```

--------------------------------

### Display Subql Node Version

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/run_publish/references.md

Use the `--version` flag to display the current installed version of the Subql Node.

```shell
subql-node --version
```

```text
0.19.1
```

--------------------------------

### Check Node and Docker Versions

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/quickstart/quickstart.md

Verify that Node.js and Docker are installed by checking their versions. Ensure you have LTS version of Node.js.

```shell
node -v
v22.15.0
```

```shell
docker -v
Docker version 27.4.0, build bde2b89
```

--------------------------------

### Type Generation Commands

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/build/mapping-functions/mapping/polkadot.md

Commands to install dependencies and run the type generation scripts.

```APIDOC
## Type Generation Commands

### Description
Execute commands to install dependencies and generate API types and metadata.

### Commands
1. **Install Dependencies**:
   ```shell
   yarn
   ```

2. **Generate Definitions**:
   ```shell
   yarn generate:defs
   ```
   This creates `types.ts` and `index.ts` in each module folder (e.g., `/kitties`).

3. **Generate Metadata**:
   ```shell
   yarn generate:meta
   ```
   This generates metadata and an `api-augment` file.
```

--------------------------------

### GraphQL Query Example

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/quickstart/quickstart_chains/monad.md

An example of a GraphQL query to retrieve data indexed by SubQuery.

```graphql
{
  query {
    approvals(first: 10, orderBy: amount_DESC) {
      nodes {
        id
        owner
        approved
        amount
      }
    }
  }
}
```

--------------------------------

### Configure `startBlock` in `project.yaml`

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/academy/tutorials_examples/block-height.md

Modify the `startBlock` key in your `project.yaml` file to specify the block height from which your SubQuery node should start synchronizing. This is useful for large blockchains to reduce initial sync time.

```yaml
specVersion: 0.0.1
description: ""
repository: ""
schema: ./schema.graphql
network:
  endpoint: wss://polkadot.api.onfinality.io/public-ws
  dictionary: https://api.subquery.network/sq/subquery/dictionary-polkadot
dataSources:
  - name: main
    kind: substrate/Runtime
    startBlock: 1000000
    mapping:
      handlers:
        - handler: handleBlock
          kind: substrate/BlockHandler

```

--------------------------------

### Example Query Result

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/quickstart/quickstart_chains/base.md

Sample JSON output from the GraphQL query, showing fetched claim and daily aggregation data.

```json
{
  "data": {
    "claims": {
      "nodes": [
        {
          "id": "0xd91db90047591afbe6ef1c85d2ad0505ee46be161a82fdb79f569194383ed51e",
          "blockHeight": "2155198",
          "timestamp": "2023-08-03T21:55:43",
          "claimer": "0x0bAE5E0BE6CEA98C61591354a5F43339fdD5b611",
          "receiver": "0x0bAE5E0BE6CEA98C61591354a5F43339fdD5b611",
          "tokenId": "2313836",
          "quantity": "1000"
        },
        {
          "id": "0x0114a68ebb4ee609409931a4c62abd2256a66f0fb91388ca00003765186c0e60",
          "blockHeight": "2155088",
          "timestamp": "2023-08-03T21:52:03",
          "claimer": "0x8A17AD3aB5588AE18B0f875dfb65f7AD61D95bDd",
          "receiver": "0x8A17AD3aB5588AE18B0f875dfb65f7AD61D95bDd",
          "tokenId": "2312064",
          "quantity": "1"
        },
        {
          "id": "0x3ccdc484d705776eba946e67e3577c0a629cc82027da6e866717412a158de9e9",
          "blockHeight": "2155088",
          "timestamp": "2023-08-03T21:52:03",
          "claimer": "0x7a2aaecf0c3bF01411f7AAe7DBB97535a7205498",
          "receiver": "0x7a2aaecf0c3bF01411f7AAe7DBB97535a7205498",
          "tokenId": "2312054",
          "quantity": "10"
        },
        {
          "id": "0x1ab0a99382c2ccbed4b64cf1407be214e5d23deff5028a1e4c751d65a1864c04",
          "blockHeight": "2155087",
          "timestamp": "2023-08-03T21:52:01",
          "claimer": "0x51A7b9AFb62dB473107e4a220CedDa67a8025630",
          "receiver": "0x51A7b9AFb62dB473107e4a220CedDa67a8025630",
          "tokenId": "2311934",
          "quantity": "100"
        },
        {
          "id": "0x7cb2474628b4ca6598c008b47dd3956632813b38c6ade08f64dbf59c7d5ad658",
          "blockHeight": "2155092",
          "timestamp": "2023-08-03T21:52:11",
          "claimer": "0x2B4FC7483C42312C3f62feE98671f7407770f16f",
          "receiver": "0x2B4FC7483C42312C3f62feE98671f7407770f16f",
          "tokenId": "2312138",
          "quantity": "1"
        }
      ]
    },
    "dailyAggregations": {
      "nodes": [
        {
          "id": "2023-08-03",
          "totalQuantity": "3184"
        }
      ]
    }
  }
}
```

--------------------------------

### Run SubQuery Project with Advanced Options

Source: https://context7.com/subquery/documentation/llms.txt

Use the `subql-query` command with various flags to configure project settings like name, playground, port, query limits, and security options.

```bash
subql-query \
  --name my-project \
  --playground \
  --port 3000 \
  --query-limit 500 \
  --query-depth 10 \
  --query-timeout 30000 \
  --max-connection 20 \
  --unsafe \
  --subscription
```

--------------------------------

### Cache `get()` Method

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/build/mapping-functions/sandbox/cache.md

Demonstrates how to use the `get()` method to retrieve data from the in-memory cache.

```APIDOC
## GET /cache/get

### Description
Retrieves the value associated with a specified key from the cache. This method is asynchronous and returns a Promise that resolves to the value. If the key does not exist, it resolves to `undefined`.

### Method
GET

### Endpoint
`/cache/get`

### Parameters
#### Query Parameters
- **key** (string) - Required - The key of the value to retrieve.

### Response
#### Success Response (200)
- **value** (any | undefined) - The value associated with the key, or `undefined` if the key is not found.

#### Response Example
```json
{
  "value": "2023-10-23"
}
```
```

--------------------------------

### Example .env File Configuration

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/miscellaneous/env-support.md

Define environment variables for your SubQuery project. Variables like ENDPOINT and CHAIN_ID can be set here to match your blockchain network. Sensitive information can also be stored securely.

```shell
# Example .env
ENDPOINT=https://polygon-rpc.com
CHAIN_ID=204
```

--------------------------------

### Check SubQuery Node Version

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/academy/tutorials_examples/run-indexer.md

Verify the installed version of the SubQuery node. This command is useful after installation or updates.

```shell
subql-node --version
```

--------------------------------

### Example Query Result

Source: https://github.com/subquery/documentation/blob/master/docs/indexer/quickstart/quickstart_chains/solana.md

An example JSON response from a GraphQL query, showing a list of transfer nodes with their details.

```json
{
  "data": {
    "transfers": {
      "nodes": [
        {
          "id": "5kA8Hsch2tsCEBduKdi9LmLF1Jpdx93eaXzXcxkdexGMUdjSzRz994oNQQAb9vX4ZRQEmFdgupVPs9RiTsi5SWtP-3.1",
          "from": "AyzyikXL9kKs2cwyHsWLEe22aRYAvhbWwFn9TKrgmMx",
          "to": "7nAXsw5ZSGBmC3xECDL26FeVfaWKccQHCDfqoCNAnR9B",
          "amount": "200000000000000",
          "blockNumber": "314765468"
        },
        {
          "id": "BiiEoNiHmPgWZGZHAq8Qs6zRfnv7AjCd75e66RrVNpxzFz7XdydyrJXfcNoxHzqUUCLu6njGso4HUdjydGEBzZ4-2",
          "from": "GvpfztSKEi1xa5b48W7xvnZCNTZDSP4A4rS1HfiBs7RB",
          "to": "7JJ17zbcUfgrCyZK77aax2YYx9CyqdBW2kou1euNyhec",
          "amount": "178136424747427",
          "blockNumber": "315018963"
        },
        {
          "id": "5m8dqwmBGgWGUa57k99FtHo3qJu9GYCFFtDBE82zdgSx4Yhd6vdgZFuBcPcuD9ZkZjyrNMkwSrq3pVinUHdCd2aU-4",
          "from": "Azq8XAqwJj2nedMMtiH4fgmtoPpy3XR7HZRB32MnpE1E",
          "to": "BCLkJ8As4jb6iRzhTdxLaVRj8cjUxrDPfPXzZXZ5TjU5",
          "amount": "70859502000000",
          "blockNumber": "314982009"
        },
        {
          "id": "4Tc7FmDP3qyw9KnxebQVT8kTf6z8mxQRKGTA7gUXvcz3oCVUCCsQCFAyCa3eqK582qnqEiGV9ynMBCswTxNDM2vW-2",
          "from": "DHK6wAbfKTmnQ878GDmPnfjLfQLFPXVURKfDgUAsKZbz",
          "to": "GkrdqdHMNvb9mpL51UmGKX3bUAtcbjtoTAvwFGHiCyb6",
          "amount": "49997500000004",
          "blockNumber": "316298108"
        },
        {
          "id": "4SugdVF6j4WVsCjxLxAnZRNdPtU3sttx1oHy19KjuWhtf5LarWPEBoZsUHteUJad5sijY8r5LdxTzxhJayXuZLXG-2",
          "from": "ECKa34RVAo5Fvwkp1uEedh6jkM5o4CThvJeShysqJgQs",
          "to": "4PcC3r3yfAJHJJ4WFjhuBcZDX38RNTvDCFLTJZF2cWxY",
          "amount": "48944100000000",
          "blockNumber": "314859767"
        }
      ]
    }
  }
}
```
Tokens:
Raw