Schema file and codegen

The schema file schema.graphql uses a GraphQL dialect to model the target entities and entity relations. The tooling around the schema file is then used to:

Generate TypeORM entities (with squid-typeorm-codegen(1), see below)
Generate the database schema from the TypeORM entities (see db migrations)
Optionally, the schema can be used to present the target data with a GraphQL API.

The schema file format is loosely compatible with the subgraph schema file, see Migrate from subgraph section for details.

TypeORM codegen

The squid-typeorm-codegen(1) tool is used to generate TypeORM entity classes from the schema defined in schema.graphql. Invoke it with

npx squid-typeorm-codegen

By default the entity classes are generated in src/model/generated. Codegen accepts either a single schema.graphql file or all .graphql files in a schema/ directory.

Example

A Foo entity defined in the schema file:

schema.graphql

type Foo @entity {
  id: ID!
  bar: String
  baz: BigInt!
}

The generated Foo entity with TypeORM decorators:

src/model/generated/foo.model.ts

import {
  Entity as Entity_,
  PrimaryColumn as PrimaryColumn_,
  StringColumn as StringColumn_,
  BigIntColumn as BigIntColumn_
} from "@subsquid/typeorm-store"

@Entity_()
export class Foo {
    constructor(props?: Partial<Foo>) {
        Object.assign(this, props)
    }

    @PrimaryColumn_()
    id!: string

    @StringColumn_({nullable: true})
    bar!: string | undefined | null

    @BigIntColumn_({nullable: false})
    baz!: bigint
}

The package also exports column decorators used by generated models, including StringColumn, BigIntColumn, BigDecimalColumn, BytesColumn, and DateTimeColumn. Import these from @subsquid/typeorm-store when writing model classes by hand.

Query and cost directives

Customize generated GraphQL root field names with arguments on @entity:

type Transfer @entity(queryName: "transferByHash", listQueryName: "transfers") {
  id: ID!
  memo: String @fulltext(query: "transferSearch")
}

@fulltext(query:) can be applied to one or more String fields. TypeORM codegen writes a migration that adds a generated PostgreSQL tsvector column and GIN index for each participating entity.

@subsquid/graphql-server 4.12.1 and OpenReader 5.5.1 do not expose the query value as a generated GraphQL root field. In the example above, transferSearch is not available through the generated API. Treat @fulltext as storage migration generation only and use a custom resolver, direct SQL, or another search service to expose the index.

OpenReader’s query-size estimator also understands @cardinality(value:) on entities and relation fields, and @byteWeight(value:) on fields. These annotations do not change the database schema. They provide expected result counts and field sizes for the GraphQL server’s response-size limits.

Overview

Pipes SDK

Squid SDK

Alternative clients

TypeORM codegen

Example

Query and cost directives

​TypeORM codegen

​Example

​Query and cost directives

TypeORM codegen

Example

Query and cost directives