Intro to PostGraphile V5 (Part 5): Polymorphism!
Tags: postgraphile, graphql, postgres, polymorphism
Published: 2023-07-21 10:56:04

> _Benjie is the community–funded maintainer of the Graphile suite — a collection of MIT–licensed Node.js developer tooling for GraphQL and/or PostgreSQL. A key project in this suite is PostGraphile, a high performance, customizable and extensible GraphQL schema generator for APIs backed primarily (but not exclusively!) by PostgreSQL._

> _This is part five in the "Intro to PostGraphile V5" series, which started with [Part 1: Replacing the Foundations](https://dev.to/graphile/intro-to-postgraphile-v5-part-1-replacing-the-foundations-3lh0). This week, Benjie takes a look at how_ Gra<em>fast</em> _enables PostGraphile to support polymorphism; you can get your hands on the pre–release now by becoming a sponsor — see [postgraphile.org](https://postgraphile.org/)_

Polymorphism in GraphQL is where a field can return different types of things. For example a field might state it will return a `Pet`, but at runtime that must actually be a `Cat` or a `Dog`:

```graphql
interface Pet {
  id: ID!
  name: String!
}

type Cat implements Pet {
  id: ID!
  name: String!
  color: String
}

type Dog implements Pet {
  id: ID!
  name: String!
  breed: String
}
```

In the above case, `Pet` is an interface type which means that every type it can be has to implement at least the shared fields.

However, there are also situations where there aren't shared fields — for example your morning alarm might be your phone, or it might be your hungry cat — for these, we use a union type:

```graphql
union MorningAlarm = Device | Cat

type Device {
  make: String!
  model: String!
}
```

Polymorphism can be very important in GraphQL APIs, and yet has been traditionally overlooked in PostGraphile due to the complexity of implementing it in the old look–ahead system, and concerns over runtime performance. In fact it's one of our longest running issue threads: [https://github.com/graphile/postgraphile/issues/387](https://github.com/graphile/postgraphile/issues/387) 

But no more!

Thanks to the magic that is Gra<em>fast</em>, we now support both interfaces and unions at the planning layer, and you can now use smart tags to indicate to PostGraphile that a given table (or set of tables) is polymorphic so that PostGraphile will automatically generate the interfaces/unions and types for you!

We support a number of patterns of polymorphism in your PostgreSQL database, the most common of which is probably the ["single table inheritance"](https://en.wikipedia.org/wiki/Single_Table_Inheritance) pattern, where you have a table containing a `type` column indicating the type of the row, and columns for all the different attributes that the different types may need. We also support "relational polymorphism" where a central table represents an interface and stores all the common attributes (plus the type), and then this table is one–to–one joined to another table (depending on the `type`) which has additional columns specific to that type.

Unions are much simpler, you can simply declare that any of your tables belongs to a particular union via the `@unionMember` smart tag, and that union will be created if it didn't already exist, and the table added to it.

We also support more exotic forms of polymorphism, including a many–join–tables polymorphism pattern that Netflix uses with PostGraphile V5, and Gra<em>fast</em> is flexible enough that we can add more patterns over time if the need arises! It's worth keeping in mind that Gra<em>fast</em> itself is completely independent of data source, so though we have built in a number of optimized polymorphic patterns for Postgres into PostGraphile, Gra<em>fast</em> users can leverage flexible polymorphism no matter what data sources they are using. 

If you have access to the V5 documentation, you can read more about it here: [https://postgraphile.org/postgraphile/next/polymorphism](https://postgraphile.org/postgraphile/next/polymorphism) 

This has been one of the most eagerly anticipated features of PostGraphile V5, and I'm extremely excited to announce that not only is it now, finally, possible; but it has been since late last year and the early adopters are getting on well with it!

<figure>

![Discord message from Mo Binni: "Finally was able to get around to modelling polymorphism in v5 and I just wanted to say Benjie this is amazing stuff and I'm super impressed"](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/grlr3jhu6g8n9yak2ap2.png)

<figcaption><p>A happy user of V5 polymorphism.</p></figcaption>
</figure>

Next up, another massive feature of V5 that'll be loved by serverless aficionados and people concerned about being locked into a PostGraphile schema alike!

> _~~Check back next week to find out what the next new feature is~~ Next, check out [Intro to PostGraphile V5 (Part 6): Excellent Executable Exports](https://dev.to/graphile/intro-to-postgraphile-v5-part-6-excellent-executable-exports-1150); and remember: to get your hands on a pre–release version of PostGraphile V5 including all its polymorphic goodness, all you need to do is sponsor Graphile at any tier and then drop us an email or DM! Find out more at [graphile.org/sponsor](http://graphile.org/sponsor)_