Gebruik van geneste mutations

Geneste mutations maken het mogelijk om mutations uit te voeren op een ander type dan het roottype in GraphQL.

De onderstaande query voert een standaard mutation uit, waarbij het mutationveld updatePost van het roottype wordt gebruikt:

mutation {
  updatePost(input: {
    id: 5,
    title: "New title"
  }) {
    status
    errors {
      __typename
      ...on ErrorPayload {
        message
      }
    }
    post {
      title
    }
  }
}

De bovenstaande query kan ook worden uitgevoerd via een geneste mutation, waarbij het post-object eerst wordt opgehaald via het veld post, en vervolgens het mutationveld update, dat toebehoort aan het type Post, wordt toegepast op het post-object:

mutation {
  post(by: {id: 5}) {
    update(input: {
      title: "New title"
    }) {
      status
      post {
        title
      }
    }
  }
}

Mutations kunnen ook worden genest, waarbij gegevens worden gewijzigd op het resultaat van een andere mutation:

mutation {
  createPost(input: {
    title: "First title"
  }) {
    status
    postID
    post {
      update(input: {
        title: "Second title",
        contentAs: { html: "Some content" }
      }) {
        status
        post {
          title
          content
          addComment(input: {
            commentAs: { html: "My first comment" }
          }) {
            status
            commentID
            comment {
              content
              date
            }
          }
        }
      }
    }
  }
}

Vereenvoudigd roottype

Geneste mutations veranderen het roottype, van QueryRoot en MutationRoot naar één enkel Root-type dat zowel queries als mutations afhandelt:

Geneste mutations in de schemadocumentatie

Mutationvelden visualiseren

Gebruik de Voyager-client om te visualiseren welke de mutationvelden zijn.

Met geneste mutations kan elk type in het schema zowel query- als mutationvelden bevatten. Om ze te onderscheiden, wordt de beschrijving van het mutationveld voorafgegaan door het label "[Mutation] ".

Hier zijn bijvoorbeeld de velden voor het type Root:

Beschrijving van het type Root in de GraphiQL-documentatie

Geneste mutations gebruiken in de endpoints

Er zijn 2 niveaus waarop we kunnen bepalen of het schema geneste mutations gebruikt. In volgorde van prioriteit:

1. In de schemaconfiguratie

Of een custom endpoint of persisted query geneste mutations gebruikt, kan worden ingesteld via de bijbehorende schemaconfiguratie:

Mutationschema in de schemaconfiguratie

2. Standaardmodus, ingesteld in de Instellingen

Als de schemaconfiguratie de waarde "Default" heeft, wordt de modus gebruikt die is gedefinieerd in de Instellingen:

Geneste mutations configureren

Er zijn drie gedragingen die we kunnen kiezen voor het schema:

1. Geneste mutations niet inschakelen

Deze optie schakelt geneste mutations uit (en gebruikt in plaats daarvan het standaardgedrag) voor het schema.

2. Geneste mutations inschakelen, alle mutationvelden in het roottype behouden

Wanneer geneste mutations zijn ingeschakeld, kunnen mutationvelden twee keer aan het schema worden toegevoegd:

eenmaal onder het type Root
eenmaal onder het specifieke type

Bijvoorbeeld:

Root.updatePost
Post.update

Met deze optie worden de "gedupliceerde" mutationvelden van het roottype behouden.

3. Geneste mutations inschakelen, de overbodige mutationvelden uit het roottype verwijderen

Dezelfde optie als hierboven, maar waarbij de "gedupliceerde" mutationvelden uit het roottype worden verwijderd.

Bijvoorbeeld:

Root.updatePost wordt verwijderd
Post.update is beschikbaar

GraphQL-specificatie

Deze functionaliteit maakt momenteel geen deel uit van de GraphQL-specificatie, maar is wel aangevraagd:

Issue #252 - Proposal: Serial fields (nested mutations)