Docs
La Recherche⌘ K
  • Accueil
  • À propos de The Graph
  • Réseaux pris en charge
  • Contrats du Protocole
  • Subgraphs
    • Substreams
      • Token API
        • AI Suite
          • Indexing
            • Resources
              Resources > Migration Guides

              9 minutes

              GraphQL Validations Migration Guide

              Bientôt, graph-node supportera 100% de la couverture de la [Spécification des validations GraphQL] (https://spec.graphql.org/June2018/#sec-Validation⁠).

              Les versions précédentes de graph-node ne prenaient pas en charge toutes les validations et fournissaient des réponses plus gracieuses - ainsi, en cas d’ambiguïté, graph-node ignorait les composants d’opérations GraphQL non valides.

              La prise en charge de GraphQL Validations est le pilier des nouvelles fonctionnalités à venir et des performances à grande échelle de The Graph Network.

              Il garantira également le déterminisme des réponses aux requêtes, une exigence clé sur The Graph Network.

              L’activation des validations GraphQL interrompra certaines requêtes existantes envoyées à l’API Graph.

              Pour être conforme à ces validations, veuillez suivre le guide de migration.

              ⚠️ Si vous ne migrez pas vos requêtes avant le déploiement des validations, elles renverront des erreurs et éventuellement casseront vos frontends/clients.

              Guide de migration

              Vous pouvez utiliser l’outil de migration CLI pour rechercher tous les problèmes dans vos opérations GraphQL et les résoudre. Vous pouvez également mettre à jour le point de terminaison de votre client GraphQL pour utiliser le point de terminaison « https://api-next.thegraph.com/subgraphs/name/$GITHUB_USER/$SUBGRAPH_NAME⁠ ». Tester vos requêtes sur ce point de terminaison vous aidera à trouver les problèmes dans vos requêtes.

              Not all Subgraphs will need to be migrated, if you are using GraphQL ESlint⁠ or GraphQL Code Generator⁠, they already ensure that your queries are valid.

              Outil CLI de migration

              La plupart des erreurs d’opérations GraphQL peuvent être trouvées à l’avance dans votre base de code.

              Pour cette raison, nous offrons une expérience fluide pour valider vos opérations GraphQL pendant le développement ou dans CI.

              @graphql-validate/cli⁠ est un outil CLI simple qui permet de valider les opérations GraphQL par rapport à un schéma donné.

              Commencer

              Vous pouvez exécuter l’outil comme suit :

              1npx @graphql-validate/cli -s https://api-next.thegraph.com/subgraphs/name/$GITHUB_USER/$SUBGRAPH_NAME -o *.graphql

              Notes:

              • Définissez ou remplacez $GITHUB_USER, $SUBGRAPH_NAME par les valeurs appropriées. Comme : artblocks/art-blocks⁠
              • L’URL du schéma d’aperçu (https://api-next.thegraph.com/⁠) fournie est fortement limitée en débit et sera supprimée une fois que tous les utilisateurs auront migré vers la nouvelle version. Ne l’utilisez pas en production.
              • Les opérations sont identifiées dans les fichiers avec les extensions suivantes .graphql,⁠.ts, .tsx , .js, jsx⁠ (option -o).

              Sortie CLI

              L’outil CLI [@graphql-validate/cli](https://github.com/saihaj/graphql-validate) affichera toutes les erreurs d’opérations GraphQL comme suit :

              Error output from CLI

              Pour chaque erreur, vous trouverez une description, le chemin et la position du fichier, ainsi qu’un lien vers un exemple de solution (voir la section suivante).

              Exécutez vos requêtes locales sur le schéma d’aperçu

              Nous fournissons un point de terminaison « https://api-next.thegraph.com/⁠ » qui exécute une version « graph-node » dont les validations sont activées.

              Vous pouvez tester des requêtes en les envoyant à :

              • https://api-next.thegraph.com/subgraphs/id/<Qm...>

              ou bien

              • https://api-next.thegraph.com/subgraphs/name/<GITHUB_USER>/<SUBGRAPH_NAME>

              Pour travailler sur des requêtes signalées comme comportant des erreurs de validation, vous pouvez utiliser votre outil de requête GraphQL préféré, comme Altair ou GraphiQL⁠, et essayer votre requête. Ces outils marqueront également ces erreurs dans leur interface utilisateur, avant même que vous ne l’exécutiez.

              Comment résoudre les problèmes

              Ci-dessous, vous trouverez toutes les erreurs de validation GraphQL qui pourraient survenir sur vos opérations GraphQL existantes.

              Les variables, opérations, fragments ou arguments GraphQL doivent être uniques

              Nous avons appliqué des règles pour garantir qu’une opération inclut un ensemble unique de variables, d’opérations, de fragments et d’arguments GraphQL.

              Une opération GraphQL n’est valide que si elle ne contient aucune ambiguïté.

              Pour y parvenir, nous devons nous assurer que certains composants de votre opération GraphQL doivent être uniques.

              Voici un exemple de quelques opérations non valides qui enfreignent ces règles :

              Nom de requête en double (#UniqueOperationNamesRule)

              1# L'opération suivante a violé UniqueOperationName2# règle, puisque nous avons une seule opération avec 2 requêtes3# avec le même nom4query myData {5  id6}78query myData {9  name10}

              Solution:

              1query myData {2  id3}45query myData2 {6  # renommer la deuxième requête7  name8}

              Nom de fragment en double (#UniqueFragmentNamesRule)

              1# L'opération suivante a violé la règle UniqueFragmentName2query myData {3  id4  ...MyFields5}67fragment MyFields {8  metadata9}1011fragment MyFields {12  name13}

              Solution:

              1query myData {2  id3  ...MyFieldsName4  ...MyFieldsMetadata5}67fragment MyFieldsMetadata { # assigner un nom unique au fragment8  metadata9}1011fragment MyFieldsName { # assigner un nom unique au fragment12  nom13}

              Variable en double (#UniqueVariableNamesRule)

              1# L'opération suivante viole le UniqueVariables2query myData($id: String, $id: Int) {3  id4  ...MyFields5}

              Solution:

              1query myData($id: String) {2  # conserver la variable pertinente (ici : `$id: String`)3  id4  ...MyFields5}

              Nom d’argument en double (#UniqueArgument)

              1# L'opération suivante a violé les UniqueArguments2query myData($id: ID!) {3  userById(id: $id, id: "1") {4    id5  }6}

              Solution:

              1query myData($id: ID!) {2  userById(id: $id) {3    id4  }5}

              Requête anonyme en double (#LoneAnonymousOperationRule)

              De plus, l’utilisation de deux opérations anonymes violera la règle « LoneAnonymousOperation » en raison d’un conflit dans la structure de réponse :

              1# Cela échouera s'il est exécuté ensemble dans2# une seule opération avec les deux requêtes suivantes :3query {4  someField5}67query {8  otherField9}

              Solution:

              1query {2  someField3  otherField4}

              Ou nommez les deux requêtes :

              1query FirstQuery {2  someField3}45query SecondQuery {6  otherField7}

              Chevauchement des domaines

              Un jeu de sélection GraphQL n’est considéré comme valide que s’il résout correctement l’éventuel jeu de résultats.

              Si un ensemble de sélection spécifique, ou un champ, crée une ambiguïté soit par le champ sélectionné, soit par les arguments utilisés, le service GraphQL ne parviendra pas à valider l’opération.

              Voici quelques exemples d’opérations non valides qui enfreignent cette règle :

              Conflit d’alias de champs (#OverlappingFieldsCanBeMergedRule)

              1# L'alias des champs peut provoquer des conflits, soit avec2# d'autres alias ou d'autres champs qui existent sur le3# Schéma GraphQL.4query {5  dogs {6    name: nickname7    name8  }9}

              Solution:

              1query {2  dogs {3    nickname: name4    originalName: name # alias du champ `name` original5  }6}

              *Champs en conflit avec des arguments (#OverlappingFieldsCanBeMergedRule)

              1# Différents arguments peuvent conduire à des données différentes,2# donc nous ne pouvons pas supposer que les champs seront les mêmes.3query {4  dogs {5    doesKnowCommand(dogCommand: SIT)6    doesKnowCommand(dogCommand: HEEL)7  }8}

              Solution:

              1query {2  dogs {3    knowsHowToSit: doesKnowCommand(dogCommand: SIT)4    knowsHowToHeel: doesKnowCommand(dogCommand: HEEL)5  }6}

              De plus, dans des cas d’utilisation plus complexes, vous pourriez enfreindre cette règle en utilisant deux fragments susceptibles de provoquer un conflit dans l’ensemble finalement attendu :

              1query {2  # Finalement, nous avons deux définitions de "x", pointant3  # vers des champs différents !4  ...A5  ...B6}78fragment A on Type {9  x: a10}1112fragment B on Type {13  x: b14}

              En plus de cela, les directives GraphQL côté client comme @skip et @include peuvent conduire à une ambiguïté, par exemple :

              1fragment mergeSameFieldsWithSameDirectives on Dog {2  name @include(if: true)3  name @include(if: false)

              Vous pouvez en savoir plus sur l’algorithme ici.⁠

              Variables ou fragments inutilisés

              Une opération GraphQL n’est également considérée comme valide que si tous les composants définis par l’opération (variables, fragments) sont utilisés.

              Voici quelques exemples d’opérations GraphQL qui enfreignent ces règles :

              Variable inutilisée (#NoUnusedVariablesRule)

              1# Invalide, car $someVar n'est jamais utilisé.2query something($someVar: String) {3  someData4}

              Solution:

              1query something {2  someData3}

              Fragment inutilisé (#NoUnusedFragmentsRule)

              1# Invalide, car le fragment AllFields n'est jamais utilisé.2query something {3  someData4}56fragment AllFields { # inutilisé :(7  name8  age9}

              Solution:

              1# Invalide, car le fragment AllFields n'est jamais utilisé.2query something {3  someData4}56# retirer le fragment `AllFields`

              Ensemble de sélection invalide ou manquant (#ScalarLeafsRule)

              De plus, une sélection de champ GraphQL n’est valide que si les éléments suivants sont validés :

              • Un champ d’objet doit avoir un ensemble de sélection spécifié.
              • Un champ de bord (scalaire, énumération) ne doit pas avoir de jeu de sélection spécifié.

              Voici quelques exemples de violations de ces règles avec le schéma suivant :

              1type Image {2  url: String!3}45type User {6  id: ID!7  avatar: Image!8}910type Query {11  user: User!12}

              Ensemble de sélection invalide

              1query {2  user {3    id { # Invalide, car "id" est de type ID et n'a pas de sous-champs45    }6  }7}

              Solution:

              1query {2  user {3    id4  }5}

              Ensemble de sélection manquant

              1query {2  user {3    id4    image # `image` nécessite un ensemble de sélection pour les sous-champs!5  }6}

              Solution:

              1query {2  user {3    id4    image {5      src6    }7  }8}

              Valeurs d’arguments incorrectes (#VariablesInAllowedPositionRule)

              Les opérations GraphQL qui transmettent des valeurs codées en dur aux arguments doivent être valides, en fonction de la valeur définie dans le schéma.

              Voici quelques exemples d’opérations non valides qui enfreignent ces règles :

              1query purposes {2  # Si "name" est défini comme "String" dans le schéma,3  # cette requête échouera lors de la validation.4  purpose(name: 1) {5    id6  }7}89# Cela pourrait également se produire lorsqu'une variable incorrecte est définie :1011query purposes($name: Int!) {12  # Si "name" est défini comme `String` dans le schéma,13  # cette requête échouera lors de la validation, car la14  # variable utilisée est de type `Int`15  purpose(name: $name) {16    id17  }18}

              Type, Variable, Fragment ou Directive connu (#UnknownX)

              L’API GraphQL générera une erreur si un type, une variable, un fragment ou une directive inconnu est utilisé.

              Ces références inconnues doivent être corrigées :

              • renommer si c’était une faute de frappe
              • sinon, supprimez

              Fragment : diffusion ou définition non valide

              Propagation de fragments non valide (#PossibleFragmentSpreadsRule)

              Un Fragment ne peut pas être réparti sur un type non applicable.

              Exemple, nous ne pouvons pas appliquer un fragment Cat au type Dog :

              1query {2	dog {3		...CatSimple4  }5}67fragment CatSimple on Cat {8  # ...9}

              Définition de fragment non valide (#FragmentsOnCompositeTypesRule)

              Tout Fragment doit être défini sur (en utilisant on ...) un type composite, en bref : objet, interface ou union.

              Les exemples suivants ne sont pas valides, car la définition de fragments sur des scalaires n’est pas valide.

              1fragment fragOnScalar on Int {2  # nous ne pouvons pas définir un fragment sur un scalaire (`Int`)3  something4}56fragment inlineFragOnScalar on Dog {7  ... on Boolean {8    # `Boolean` n'est pas un sous-type de `Dog`9    somethingElse10  }11}

              Utilisation des directives

              La directive ne peut pas être utilisée à cet emplacement (#KnownDirectivesRule)

              Seules les directives GraphQL (« @… ») prises en charge par l’API Graph peuvent être utilisées.

              Voici un exemple avec les directives prises en charge par GraphQL :

              1query {2  dog {3    name @include(true)4    age @skip(true)5  }6}

              Remarque : @stream, @live, @defer ne sont pas pris en charge.

              La directive ne peut être utilisée qu’une seule fois à cet emplacement (#UniqueDirectivesPerLocationRule)

              Les directives prises en charge par The Graph ne peuvent être utilisées qu’une seule fois par emplacement.

              Ce qui suit n’est pas valide (et redondant) :

              1query {2  dog {3    name @include(true) @include(true)4  }5}
              ⁠Edit on GitHub⁠

              Guide de migration de l'AssemblyScriptSubgraph Studio FAQ
              On this page
              • Guide de migration
              • Outil CLI de migration
              • Commencer
              • Sortie CLI
              • Exécutez vos requêtes locales sur le schéma d’aperçu
              • Comment résoudre les problèmes
              • Les variables, opérations, fragments ou arguments GraphQL doivent être uniques
              • Chevauchement des domaines
              • Variables ou fragments inutilisés
              • Ensemble de sélection invalide ou manquant (#ScalarLeafsRule)
              • Valeurs d’arguments incorrectes (#VariablesInAllowedPositionRule)
              • Type, Variable, Fragment ou Directive connu (#UnknownX)
              • Fragment : diffusion ou définition non valide
              • Utilisation des directives
              The GraphStatusTestnetActifs de la MarqueForumSécuritéPolitique de confidentialitéConditions d'utilisation