# Quick Start Guide

In this Quick Start guide, we're going to use the starter project as an example that you can use as a starting point for developing your SubQuery Project.

At the end of it, you'll have a working SubQuery project running on a SubQuery node with a GraphQL endpoint that you can query data from.

If you haven't already, we suggest that you familiarise yourself with the terminology used in SubQuery.

# Preparation

# Local Development Environment

# Install the SubQuery CLI

Install SubQuery CLI globally on your terminal by using Yarn or NPM:

# Yarn
yarn global add @subql/cli

# NPM
npm install -g @subql/cli
1
2
3
4
5

You can then run help to see available commands and usage provide by CLI

subql help
1

# Initialise the Starter SubQuery Project

Inside the directory in which you want to create a SubQuery project, simply replace PROJECT_NAME with your own and run the command:

subql init --starter PROJECT_NAME
1

You'll be asked certain questions as the SubQuery project is initalised:

  • Git repository (Optional): Provide a Git URL to a repo that this SubQuery project will be hosted in (when hosted in SubQuery Explorer)
  • RPC endpoint (Required): Provide a wss URL to a running RPC enpoint that will be used by default for this poject. You can quickly access public endpoints for different Polkadot networks or even create your own private dedicated node using OnFinalityopen in new window or just use the default Polkadot endpoint.
  • Authors: Enter the owner of this SubQuery project here
  • Description (Optional): You can provide a short paragraph about your project that describe what data it contains and what users can do with it
  • Version (Required): Enter a custom version number or use the default (1.0.0)
  • License (Required): Provide the software license for this project or accept the default (Apache-2.0)

After the initialisation process is complete, you should see a folder with your project name has been created inside the directory. The contents of this directoy should be identical to what's listed in the Directory Structure.

Last, under the project directory, run following command to install the new project's dependencies.

cd PROJECT_NAME

# Yarn
yarn install

# NPM
npm install
1
2
3
4
5
6
7

# Configure and Build the Starter Project

In the starter package that you just initialised, we have provided a standard set of configuration for your new project. You will mainly be working on the following files:

  • The Manifest in project.yaml
  • The GraphQL Schema in schema.graphql
  • The Mapping functions in src/mappings/ directory

For more information on how to write the SubQuery, check out our documentation under Create a project

# GraphQL Model Generation

In order to index your SubQuery project, you must first generate the required GraphQL models that you have defined in your GraphQL Schema file (schema.graphql). Run this command in the root of the project directory.

# Yarn
yarn codegen

# NPM 
npm run-script codegen
1
2
3
4
5

You'll find the generated models in the /src/types/models directory

# Build the Project

In order run your SubQuery Project on a locally hosted SubQuery Node, you need to build your work.

Run the build command from the project's root directory.

# Yarn
yarn build

# NPM
npm run-script build
1
2
3
4
5

# Running and Querying your Starter Project

Although you can quickly publish your new project to SubQuery Projectsopen in new window and query it using our Exploreropen in new window, the easiest way to run SubQuery nodes locally is in a Docker container, if you don't already have Docker you can install it from docker.comopen in new window.

Skip this and publish your new project to SubQuery Projects

# Run your SubQuery Project

All configuration that controls how a SubQuery node is run is defined in this docker-compose.yml file. For a new project that has been just initalised you won't need to change anything here, but you can read more about the file and the settings in our Run a Project section

Under the project directory run following command:

docker-compose pull && docker-compose up
1

It may take some time to download the required packages (@subql/nodeopen in new window, @subql/queryopen in new window, and Postgres) for the first time but soon you'll see a running SubQuery node.

# Query your Project

Open your browser and head to http://localhost:3000open in new window.

You should see a GraphQL playground is showing in the explorer and the schemas that ready to query.

For a new SubQuery starter project, you can try the following query to get a taste of how it works.

{
  query{
    starterEntities(first:10){
      nodes{
        field1,
        field2,
        field3
      }
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11

# Next Steps

Congratulations, you now have a locally running SubQuery project that accepts GraphQL API requests for sample data. In the next guide, we'll show you how to publish your new project to SubQuery Projectsopen in new window and query it using our Exploreropen in new window

Publish your new project to SubQuery Projects

Last Updated: 5/7/2021, 12:01:26 AM