> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sqd.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Schema file and codegen

> Define Squid SDK entities in schema.graphql and generate TypeORM models.

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](../../guides/writing-to-postgres))
* Optionally, the schema can be used to present the target data with a [GraphQL API](../../guides/serving-graphql).

The schema file format is loosely compatible with the [subgraph schema](https://thegraph.com/docs/en/developing/creating-a-subgraph/) file, see [Migrate from subgraph](../../guides/migration/migrate-from-thegraph) section for details.

## TypeORM codegen

The [`squid-typeorm-codegen(1)`](https://github.com/subsquid/squid-sdk/tree/master/typeorm/typeorm-codegen) tool is used to generate [TypeORM entity](https://typeorm.io/) classes from the schema defined in `schema.graphql`. Invoke it with

```bash theme={"system"}
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:

```graphql title="schema.graphql" theme={"system"}
type Foo @entity {
  id: ID!
  bar: String
  baz: BigInt!
}
```

The generated `Foo` entity with TypeORM decorators:

```ts title="src/model/generated/foo.model.ts" theme={"system"}
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`:

```graphql theme={"system"}
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.

<Warning>
  `@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](../openreader/configuration/custom-resolvers), direct SQL, or
  another search service to expose the index.
</Warning>

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](../openreader/configuration/dos-protection).