> ## 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.

# Entity relations

> Define one-to-many and many-to-many entity relations schema files — @derivedFrom, @relation, and TypeORM-friendly conventions.

# Entity relations and inverse lookups

The term "entity relation" refers to the situation when an entity instance contains an instance of another entity within one of its fields. Type-wise this means that some entity (called the *owning entity*) has a field of a type that is some other, *non-owning* entity. Within the database, this is implemented as an (automatically indexed) foreign key column within the table mapped to the owning entity. A `fieldName` entity-typed field will map to a column named `field_name_id`.

[One-to-one](https://github.com/typeorm/typeorm/blob/master/docs/one-to-one-relations.md) and [one-to-many](https://github.com/typeorm/typeorm/blob/master/docs/many-to-one-one-to-many-relations.md) relations are supported by Typeorm. The "many" side of the one-to-many relations is always the owning side. Many-to-many relations are modeled as [two one-to-many relations with an explicit join table](#many-to-many-relations).

An entity relation is always unidirectional, but it is possible to request the data on the owning entity from the non-owning one. To do so, define a field decorated `@derivedFrom` in the schema. Doing so will cause the Typeorm code generated by [`squid-typeorm-codegen`](/en/sdk/squid-sdk/resources/persisting-data/typeorm) and the GraphQL API served by [`squid-graphql-server`](/en/sdk/squid-sdk/reference/openreader-server/overview) to show a virtual (that is, **not mapping to a database column**) field populated via inverse lookup queries.

The following examples illustrate the concepts.

## One-to-one relations

```graphql theme={"system"}
type Account @entity {
  id: ID!
  balance: BigInt!
  user: User @derivedFrom(field: "account")
}

type User @entity {
  id: ID!
  account: Account! @unique
  username: String!
  creation: DateTime!
}
```

The `User` entity references `Account` and owns the one-to-one relation. This is implemented as follows:

* On the database side: the `account` property of the `User` entity maps to the `account_id` foreign key column of the `user` table referencing the `account` table.
* On the TypeORM side: the `account` property of the `User` entity gets decorated with `@OneToOne` and `@JoinColumn`.
* On the GraphQL side: sub-selection of the `account` property is made available in `user`-related queries. Sub-selection of the `user` property is made available in `account`-related queries.

<Info>
  Unlike for the many-to-one case, the codegen will not add a virtual reverse lookup property to the TypeORM code for one-to-one relations. You can add it manually:

  ```typescript title="src/model/generated/account.model.ts" theme={"system"}
  import {OneToOne as OneToOne_} from "typeorm"

  @Entity_()
  export class Account {
    // ...
    @OneToOne_(() => User, e => e.account)
    user: User
  }
  ```

  If you are using this feature, please let us know at [the SquidDevs Telegram channel](https://t.me/HydraDevs).
</Info>

## Many-to-one/One-to-many relations

```graphql theme={"system"}
type Account @entity {
  "Account address"
  id: ID!
  transfersTo: [Transfer!] @derivedFrom(field: "to")
  transfersFrom: [Transfer!] @derivedFrom(field: "from")
}

type Transfer @entity {
  id: ID!
  to: Account!
  from: Account!
  amount: BigInt! 
}
```

Here `Transfer` defines owns the two relations and `Account` defines the corresponding inverse lookup properties. This is implemented as follows:

* On the database side: the `from` and `to` properties of the `Transfer` entity map to `from_id` and `to_id` foreign key columns of the `transfer` table referencing the `account` table.
* On the TypeORM side: properties `to` and `from` of the `Transfer` entity class get decorated with `@ManyToOne`. Properties `transfersTo` and `transfersFrom` decorated with `@OneToMany` get added to the `Account` entity class.
* On the GraphQL side: sub-selection of all relation-defined properties is made available in the schema.

## Many-to-many relations

Many-to-many entity relations should be modeled as two one-to-many relations with an explicitly defined join table.
Here is an example:

```graphql theme={"system"}
# an explicit join table 
type TradeToken @entity {
  id: ID! # This is required, even if useless
  trade: Trade!
  token: Token! 
}

type Token @entity {
  id: ID!
  symbol: String!
  trades: [TradeToken!]! @derivedFrom(field: "token")    
}

type Trade @entity {
  id: ID!
  tokens: [TradeToken!]! @derivedFrom(field: "trade")
}
```