Prisma1: Embedded types

[schickling]

UPDATE: We will implement the proposal given here

Motivation

In certain scenarios you want to compose types without using relations (via @relation). Here is a simple example:

type User @model {
  id: ID! @isUnique
  name: String!
  location: Location
  friends: [User!]! @relation(name: "Friends")
}

type Location {
  lat: Float!
  lng: Float!
  city: City
}

type City {
  name: String!
}

This means that...

• there is no allLocations query generated
• you can not traverse back from a Location to a User via GraphQL
• when a User is deleted, the Location node is deleted as well

Todo:

• [x] Spec out CUD mutation behaviour (including nested mutations)
• [x] Spec out query filter behaviour
• [x] Determine whether embedded types need to have an id field
• [x] Spec behaviour for nested embedded types
• [x] Determine whether createdAt / updatedAt fields should be supported
• [x] Determine what level of support should be provided for migrating between embedded and model type

Goals

Provide the ability to create a type A that is fully owned by another type B. This means that:

• A cannot be created alone
• if B is deleted, so is the corresponding A
• A does not require a globally unique id field
• A can only be accessed through B

With these goals in mind we can improve the developer experience in some key areas:

• simplify types.graphql definition
  
  
  
  • no id: ID! @isUnique
  
  
  • no backrelation
  
  
  • no @relation directive
  
  
  • cascading delete automatically configured
  
  
• simplify create and update mutations
  
  
  
  • as the type is fully owned by parent, there is no connect option
  
  
• don't include top-level allAs query
• don't allow relations to type

Spec

This is no longer valid

Storage

Each embedded type is stored in a separate table. The above schema results in these data tables:

User

| id | name |
|---|-------|

User_Location

| id | lat | lng |
|---|----|----|

User_Location_City

| id | name |
|---|-------|

and these relation tables:

UserLocationRelation

| id | A | B |
|---|---|--|

LocationCityRelation

| id | A | B |
|---|---|--|

Embedded types are stored the same way as normal model types with relations. This enables us to seamlessly migrate an embedded type to a model type and allows us to reuse the existing data fetching mechanism.

Note that embedded types have a table for each type they appear in. Above this is indicated by a prefix, but in practice we have to use an opaque identifier as some SQL engines have strict limits on column name length.

Different storage strategies

In the future we will likely add a configuration option to pick between different storage strategies optimised for specific use cases. Two obvious alternative strategies:

• inline json
• external document database (probably mongodb)

id, createdAt, updatedAt

The three fields id, createdAt, updatedAt are created and maintained internally. They can be exposed in the API by simply including them in the definition of the embedded type.

migrating between embedded and model type

In the future we will support easy non-destructive migration between model and embedded type.
The following before and after schema illustrates this:

before:

type User @model {
  id: ID! @isUnique
  name: String!
  location: Location
  friends: [User!]! @relation(name: "Friends")
}

type Location {
  lat: Float!
  lng: Float!
}

after:

type User @model {
  id: ID! @isUnique
  name: String!
  location: Location @relation(name: "UserLocation")
  friends: [User!]! @relation(name: "Friends")
}

type Location @model {
  id: ID! @isUnique
  user: User! @relation(name: "UserLocation")
  lat: Float!
  lng: Float!
}

The data structure will be the same before and after, so this migration can be done quickly and in a non-destructive way. The only change is the exposed API

Filter by embedded type values

The default storage strategy supports normal relation filters:

allUsers(
  filter: {
    location: {
      lat_gt: 30
      city: {
        name_not: "Copenhagen"
      }
    }
  }
) { ... }

note that embedded types does not get a top-level query. The only way to access a Location is by traversing from a User: { allUsers { location { lat } } }

Mutations

Create

embedded types can be created in a deeply nested fashion. Unlike model types, it is not possible to reference an existing embedded type by id.

If a required field in any embedded types is not provided, the entire create mutation fails

mutation {
  createUser(data: {
    name: "Karl"
    location: {
      lat: 1
      lng: 2
    }
  })
}

Update

When updating an embedded type, the entire existing object tree is kept, and only the provided keys are updated. In this example lng is updated, and lat retains its old value:

mutation {
  updateUser(id: "", data: {
    location: {
      lng: 3
    }
  })
}

If an update sets a key in a deeply nested embedded object structure, where the higher-level objects didn't exist before, Graphcool will attempt to create these objects. If any of these objects has required fields that are not being set, the entire update mutation will fail.

Delete

When deleting a model type, all its embedded types are deleted as well. This is a feature of the embedded type, and there is no way to change this behaviour.

mutation {
  deleteUser(id: "")
}

See the proposal given here

[kbrandwijk]

So basically, strongly typed JSON? If this is supported, then is there still a use case left for @relation? And for mandatory two-way relationships? I think this proposal should take that into account as well. Because I think everything could function exactly like it is doing now without that attribute.

Also related, I think types don't need to have a mandatory id field. I imagine every node having a unique id in the database, but whether or not you want to expose it in the schema should be up to the developer. There might be another field with @isUnique, and if there are none, then the User query (for example) would not be generated at all. This aligns with #257 for nested mutations.

In general, which queries/mutations to generate for a Type could be part of the service definition (graphcool.yml).

[kbrandwijk]

Also related, and probably closeable in favor of this one: https://github.com/graphcool/framework/issues/308

[pie6k]

Topic to consider is filtering by those fields. In your example @schickling - would I be able to filter Users by their location on query level like

allUsers(
  filter: {
    location: {
      lat_gt: 30
    }
  }
) {

}

I think it'd be very popular use case (at least in my case), while it'll propably not support any native database optimisations (unless you use postgress jsonp format etc)

[sorenbs]

Great input @pie6k and @kbrandwijk! I have documented all aspects of this proposal I am aware of. Would love for you to provide feedback on areas not yet covered or design decisions you disagree with or don't understand.

[marktani]

I have a couple of open questions:

• Is it possible to delete the embedded data while keeping the outer node?
• Can you add a field of any model type to an embedded type?
• Can you refer to a list of embedded types: locations: [Location!]!?
• What's the use case of id for embedded data?

[kbrandwijk]

Should I create a separate issue for my remark about deprecating the relation directive alltogether?

[sorenbs]

@kbrandwijk I don't really understand what/how/why it would mean to deprecate the @relation directive, so I think a separate issue is a good idea :-)

[kbrandwijk]

@sorenbs I was referring to my argumentation in a previous comment: https://github.com/graphcool/framework/issues/1160#issuecomment-341853424

[sorenbs]

@marktani:

• Is it possible to delete the embedded data while keeping the outer node?
  
  
  
  • yes - just set the field to null
  
  
• Can you add a field of any model type to an embedded type?
  
  
  
  • yes
  
  
• Can you refer to a list of embedded types: locations: [Location!]!?
  
  
  
  • in the first implementation not, later yes
  
  

[kbrandwijk]

Can you refer to a list of embedded types: locations: [Location!]!?
in the first implementation not, later yes

I think it's important to 'get this right' in one go, and try to minimize on the limitations. This reminds too much of the type restrictions in resolver functions.

[sorenbs]

UPDATE: This proposal will be part of Graphcool 1.0

With the stated goals for embedded types in mind, I'd like to explore an alternative way to achieve these goals without introducing embedded types as a new first-class concept.

@kbrandwijk I think this goes in the direction of what you were talking about in your comment above?

This alternative introduces some fundamental changes to the way Graphcool works, so brace yourself :-)

---

remove the @model directive

We can assume that all types are stored in database. If we introduce different kinds of types in the future, we can find a way to differentiate them, possibly with a new directive.

Make the id: ID! @unique field optional

When the id field is not present:

• we will still create it in the database and populate it with a normal cuid string.
• relations will use this id internally
• it will not be possible to query or connect a node of the type by id, but other unique fields can be used
  
  
  
  • If no unique fields exist on the type, we will not add the connect argument in nested mutations
  
  

Make the @relation directive optional

When there is only one relation between two types, we don't need a relation name to match it up:

type Post {
  id: ID! @unique
  comments: [Comment!]! @relation(name: "Comments")
}

becomes:

type Post {
  id: ID! @unique
  comments: [Comment!]!
}

Make back-relations optional

Currently relations are required to have fields on both sides:

type Post {
  id: ID! @unique
  comments: [Comment!]! @relation(name: "Comments")
}

type Comment {
  id: ID! @unique
  post: Post! @relation(name: "Comments")
}

Allowing one-way relations would remove clutter in some cases:

type Post {
  id: ID! @unique
  comments: [Comment!]! @relation(name: "Comments")
}

type Comment {
  id: ID! @unique
}

Compromises compared to embedded types proposal

• must manually configure cascading delete
• top-level query will be there ( ie. allLocations)
• create and update mutations will contain the connect field if there are any unique fields

Adjusted proposal example

Proposal

type User @model {
  id: ID! @unique
  name: String!
  location: Location
  friends: [User!]! @relation(name: "Friends")
}

type Location {
  lat: Float!
  lng: Float!
  city: City
}

type City {
  name: String!
}

Alternate version

type User {
  id: ID! @unique
  name: String!
  location: Location @relation(onDelete: CASCADE)
  friends: [User!]!
}

type Location {
  lat: Float!
  lng: Float!
  city: City @relation(onDelete: CASCADE)
}

type City {
  name: String!
}

I'd love to get some opinions on this idea. Especially from @schickling and @mavilein who brought it up at our internal review and @kbrandwijk who brought up a similar idea in the comments above.

[mavilein]

Perfect ❤️

[pie6k]

Another thing to consider is migration from embedded data to @models and vice-versa.

Let's say you have embedded data already, but you want Location to become database entity. What would happen with existing data when @model will be added to Location?

[schickling]

@pie6k with @sorenbs' new proposal these would be the same, so migrations are trivial.

[sorenbs]

Our current understanding is that we should not implement special functionality for embedded types and instead implement the changes described in https://github.com/graphcool/framework/issues/1160#issuecomment-345373277 A few people have upvoted the proposal already, but I would like to hear from anyone who see any potential issues in the proposed changes.

[JensMadsen]

Personally I am not fund of:

Make the @relation directive optional
Make back-relations optional

I fear hard-to-resolve-bugs arising from this?

[kbrandwijk]

@JensMadsen Why would that result in bugs?

[jvbianchi]

In cases where the @relation is not used (because is optional) or is not given a name, what happens with relation permissions?

[sorenbs]

@jvbianchi In Graphcool 1.0 permissions are implemented in the GraphQL server, adding a lot of extra flexibility. You can already take a look at this approach in https://github.com/graphcool/graphql-server-example

[jvbianchi]

@sorenbs Where in this example you control user permission?

[pie6k]

Having this is the only thing that is preventing me from decision about using graph.cool as backend for my product and it's kind of urgent for me. Are you able to provide any information about progress and plans of implementing it?

[sorenbs]

@jvbianchi There is a very simple example in https://github.com/graphcool/graphql-server-example/blob/master/src/resolvers/Viewer.ts where the query is limited to the scope of the current user.

@nikolasburk is working on much more extensive documentation :-)

[sorenbs]

@pie6k This will be included in an early beta later this month. We expect to release 1.0 in January.

[marktani]

Embedded types, unidirection relations, and optional relation directives have been implemented in Prisma 1.0.

[sorenbs]

As we are starting to work on the MongoDB connector a new perspective is reviving the discussion on special handling for embedded types. I would appreciate any and all input on this proposal #2836 - especially from @schickling, @kbrandwijk, @mavilein who we instrumental in shaping the proposal outlined in https://github.com/prismagraphql/prisma/issues/1160#issuecomment-345373277 that is currently implemented in Prisma.